Initial Commit

packages/security-stack/crypto/crypto-utils/src/encoding/base64/base64.md

@@ -0,0 +1,56 @@
+# Base64 encoding
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Standard Base64 (RFC 4648 §4) and URL-safe Base64 (§5) encoding and decoding for byte buffers. Standard Base64 is the default for JSON, JWT headers, and binary payloads in MIME. URL-safe Base64 substitutes `-` and `_` for `+` and `/` so the result can appear in URLs and file paths without percent-escaping. Standard Base64 (`toBase64` / `fromBase64`) is delegated entirely to `@suaveplan/bytes`; the URL-safe variants are implemented here because they use a crypto-specific `+→- / →_` substitution pattern not present in the bytes package.
+
+## Features
+
+- `toBase64` / `fromBase64`: RFC 4648 §4 with `=` padding — delegated to `@suaveplan/bytes`.
+- `toBase64Url` / `fromBase64Url`: RFC 4648 §5 without padding — implemented natively by post-processing the standard base64 output.
+- URL-safe decoder tolerates optional trailing `=` padding.
+- Throws `BytesError` (from `@suaveplan/bytes`) on malformed standard base64; same error type propagates through the URL-safe decoder.
+
+## Usage: Basic Example
+
+```ts
+import { fromBase64, toBase64 } from "@suaveplan/crypto-utils/encoding";
+
+const s = toBase64(new TextEncoder().encode("foobar")); // "Zm9vYmFy"
+const bytes = fromBase64(s);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { fromBase64Url, toBase64Url } from "@suaveplan/crypto-utils/encoding";
+import { BytesError } from "@suaveplan/bytes";
+
+function parseJwtSegment(segment: string): Uint8Array {
+    try {
+        return fromBase64Url(segment);
+    } catch (err) {
+        if (err instanceof BytesError) {
+            throw new Error(`JWT segment not valid base64url: ${segment.slice(0, 8)}…`);
+        }
+        throw err;
+    }
+}
+
+const encoded = toBase64Url(new Uint8Array([0xfb, 0xff, 0xbf]));
+parseJwtSegment(encoded);
+```
+
+## API Reference
+
+- `toBase64(bytes: Uint8Array): string` — RFC 4648 §4 with `=` padding. Never throws. Alias for `bytesToBase64` from `@suaveplan/bytes`.
+- `fromBase64(s: string): Uint8Array` — RFC 4648 §4. Throws `BytesError(BYTES.ENCODE.INVALID_BASE64)` on invalid characters or bad length.
+- `toBase64Url(bytes: Uint8Array): string` — RFC 4648 §5 without padding. Calls `toBase64` then substitutes `+→-`, `/→_`, strips `=`.
+- `fromBase64Url(s: string): Uint8Array` — RFC 4648 §5. Restores `+` and `/`, adds padding, then delegates to `fromBase64`. Tolerates optional trailing `=` padding. Throws `BytesError` on malformed input.
+
+## Implementation Notes
+
+Standard base64 (`toBase64` / `fromBase64`) are direct `const` aliases for `bytesToBase64` / `base64ToBytes` from `@suaveplan/bytes`, eliminating duplicate encoding logic. URL-safe base64 is implemented as a post-processing step: `toBase64Url` calls `toBase64` then performs three `String.replace` calls to swap characters and strip padding. `fromBase64Url` reverses the substitution, computes missing padding (aligning to a multiple of 4), then delegates to `fromBase64`. This approach ensures the URL-safe round-trip shares exactly the same underlying byte semantics as the standard variant. Error type for invalid input is `BytesError` (from `@suaveplan/bytes`) rather than the legacy `CryptoUtilsError`.