`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

import { resolveB64 } from "@suaveplan/jws";

resolveB64({ alg: "HS256" }); // true (default)
resolveB64({ alg: "HS256", b64: true }); // true

Usage: Advanced Example

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.

2.6 KiB Raw Permalink Blame History

b64 (RFC 7797) header