first commit

docs/security-stack/security/jws/src/header/b64.md

@@ -0,0 +1,59 @@
+# `b64` (RFC 7797) header
+
+## Purpose
+
+RFC 7797 §3 implements the `b64` header parameter, allowing JWS producers to embed unencoded payloads directly into the signing input. When `b64: false`, the second compact-form segment is the raw payload bytes themselves (not base64url-encoded) and the signing input becomes `BASE64URL(protected) || "." || rawPayloadBytes`. The RFC's MUST clauses require that any `b64: false` header also list `"b64"` in `crit` so verifiers ignorant of RFC 7797 refuse the token rather than misinterpret it.
+
+## Features
+
+- `resolveB64(header)` — returns the effective boolean (`true` when absent).
+- `b64: false` without `"b64"` in `crit` → `JWS.B64_INVALID`.
+- Non-boolean `b64` value → `JWS.B64_INVALID`.
+- Absent `b64` defaults to base64url encoding (RFC 7515 §3.1 default).
+
+## Usage: Basic Example
+
+```ts
+import { resolveB64 } from "@suaveplan/jws";
+
+resolveB64({ alg: "HS256" }); // true (default)
+resolveB64({ alg: "HS256", b64: true }); // true
+```
+
+## Usage: Advanced Example
+
+```ts
+import { compactSign, compactVerify, resolveB64, JwsError } from "@suaveplan/jws";
+
+// Produce a b64: false token (raw-payload signing input).
+const token = await compactSign("hello", key, "HS256", {
+    protectedHeader: { b64: false, crit: ["b64"] },
+    b64: false,
+});
+
+const result = await compactVerify(token, key, {
+    algorithms: ["HS256"],
+    acceptableCriticalHeaders: ["b64"],
+});
+// result.payloadString === "hello" — raw, not base64url-decoded
+
+// Missing crit listing — verifier rejects.
+try {
+    resolveB64({ alg: "HS256", b64: false });
+} catch (err) {
+    if (err instanceof JwsError && err.code === "JWS.B64_INVALID") {
+        // RFC 7797 §3 MUST violation.
+    }
+}
+```
+
+## API Reference
+
+- `resolveB64(header: JoseHeader): boolean`
+  - Returns `true` when `b64` is absent or `b64: true`.
+  - Returns `false` only when `b64: false` AND `crit` includes `"b64"`.
+  - Throws `JwsError(JWS.B64_INVALID)` for non-boolean values or `false` without `crit`.
+
+## Implementation Notes
+
+The RFC 7797 contract is asymmetric: producers may emit `b64: true` without `crit` (default behaviour), but `b64: false` MUST be marked critical. This module enforces only the verifier side; the sign pipeline emits the `crit: ["b64"]` companion automatically when callers pass `b64: false` so producers do not have to remember the dual-write. Raw-payload signing input requires special handling — the payload bytes cannot pass through `TextEncoder` when the producer's payload contains the `.` byte (0x2e), since that's also the segment separator; the compact-form parser handles this by treating the segment as bytes once `b64: false` is resolved, not as a UTF-8 string.