first commit

docs/foundation/flow/cbor/src/cwt/claims.md

@@ -0,0 +1,53 @@
+# `claims`
+
+## Purpose
+
+Encode and decode RFC 8392 CBOR Web Token claim sets. The seven IANA-
+registered claims (`iss`, `sub`, `aud`, `exp`, `nbf`, `iat`, `cti`) are
+typed; private claims keyed by IANA-numeric label survive the round-trip
+unchanged.
+
+## Features
+
+- `encodeCwt(claims)` — deterministic claim-set encoding so token bytes are
+  byte-stable across runs.
+- `decodeCwt(bytes)` — typed `CwtClaims` output with full validation at the
+  field boundaries.
+- Time fields (`exp`, `nbf`, `iat`) accept `Date` on the input side; the
+  decoder produces `Date` from raw integers, bigints, or values wrapped in
+  CBOR tag 1 (epoch).
+- `aud` accepts both `string` and `string[]` per RFC 8392 §3.1.
+- Private claims threaded through `claims.private` keyed by integer label
+  number — opaque to the typed claims but preserved on round-trip.
+
+## Usage
+
+```ts
+import { decodeCwt, encodeCwt } from "@suaveplan/cbor/cwt";
+
+const wire = encodeCwt({
+  iss: "https://issuer.example",
+  exp: new Date("2030-01-01"),
+  cti: new Uint8Array([0x01, 0x02]),
+  private: { 100: "tenant-a" },
+});
+
+const claims = decodeCwt(wire);
+```
+
+## API
+
+- `encodeCwt(claims: CwtClaims): Uint8Array`
+- `decodeCwt(bytes: Uint8Array): CwtClaims`
+
+Throws `CborError(UNEXPECTED_TYPE)` for malformed claim labels, wrong inner
+types, non-string `iss`/`sub`, malformed `aud`, etc.
+
+## Notes
+
+`exp`/`nbf`/`iat` always serialise as integer epoch seconds rather than
+`Tagged(1, …)` — both forms are valid on the wire per RFC 8392, but the
+integer form is shorter and the deterministic profile prefers shortest-form.
+Private claims must use integer labels per the CWT registry; non-integer
+keys are silently dropped on encode (the `Object.entries` walk filters
+them) — the typed `private` shape is keyed by `number`.