# `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.