@blamejs/core 0.8.43 → 0.8.49

package/lib/content-credentials.js

@@ -1,56 +1,31 @@
 "use strict";
 /**
- * b.contentCredentials — California SB-942 / AB-853 + C2PA 2.1
- * content-provenance manifest builder for AI-generated assets.
- *
- * California SB-942 (Cal. Bus. & Prof. Code §22757) + AB-853, both
- * effective 2026-08-02, require providers of generative AI systems
- * to embed a latent (machine-readable) provenance disclosure in
- * every AI-generated image / video / audio asset distributed in
- * California. The disclosure MUST carry:
- *
- *   - Provider name
- *   - System (model) identifier + version
- *   - Content timestamp (when generated)
- *   - Unique content ID
- *
- * SB-942 specifically cites C2PA (Coalition for Content Provenance
- * and Authenticity) as an acceptable disclosure format. C2PA 2.1+
- * manifests carry signed assertions with the same fields.
- *
- * The framework can't embed the manifest into image/video/audio
- * bytes directly (that requires format-specific muxers — JPEG XMP /
- * PNG iTXt / MP4 ContentBoxes / etc. that vary per codec). What it
- * CAN do:
- *
- *   - Build a C2PA-shaped manifest carrying the required fields.
- *   - Sign the manifest with the framework's audit-sign keypair
- *     (ML-DSA-87 — or operator-supplied SigStore key).
- *   - Emit a tamper-evident audit row recording the disclosure.
- *   - Validate inbound manifests presented by upstream content
- *     pipelines (the receiver side of the same chain).
- *
- * Operator workflow:
+ * @module b.contentCredentials
+ * @featured true
+ * @nav    AI
+ * @title  Content Credentials
  *
- *   var manifest = b.contentCredentials.build({
- *     provider:        "Acme AI Inc.",
- *     system:          "acme-image-v3",
- *     systemVersion:   "3.2.1",
- *     contentId:       "img-2026-05-08-abc123",
- *     contentType:     "image/png",
- *     contentSha3:     hashHex,
- *     // operator's display attribution + machine-readable fields
- *   });
- *   var signed = b.contentCredentials.sign(manifest, { signWith: ... });
- *   // operator hands `signed.manifest` to their muxer for embedding
+ * @intro
+ *   C2PA 2.1 content provenance — sign assets with a manifest
+ *   declaring origin, edits, AI involvement.
+ *
+ *   California SB-942 (Cal. Bus. & Prof. Code §22757) + AB-853,
+ *   effective 2026-08-02, require generative-AI providers to embed a
+ *   latent disclosure carrying provider name, system identifier,
+ *   system version, content timestamp, and a unique content ID in
+ *   every AI-generated image / video / audio asset distributed in
+ *   California. SB-942 names C2PA as an acceptable format.
  *
- * Public API:
+ *   The framework can't push bytes into format-specific muxers (JPEG
+ *   XMP / PNG iTXt / MP4 boxes vary per codec). What it does ship:
+ *   build a C2PA-shaped manifest with the SB-942 required fields,
+ *   sign it with the audit-sign keypair (ML-DSA-87 by default),
+ *   record a tamper-evident audit row, and verify inbound manifests
+ *   on the receive side. Operators hand the signed manifest to their
+ *   format-specific embedder.
  *
- *   contentCredentials.build(opts) -> manifest (unsigned)
- *   contentCredentials.sign(manifest, opts) -> { manifest, signature }
- *   contentCredentials.verify(envelope, publicKeyPem) -> { valid, claims }
- *   contentCredentials.required(opts) -> array of missing-field errors
- *     (returns [] when the operator's input satisfies SB-942 minimums)
+ * @card
+ *   C2PA 2.1 content provenance — sign assets with a manifest declaring origin, edits, AI involvement.
  */
 
 var crypto = require("./crypto");
@@ -112,6 +87,44 @@ function _validateBuildOpts(opts) {
   }
 }
 
+/**
+ * @primitive b.contentCredentials.build
+ * @signature b.contentCredentials.build(opts)
+ * @since     0.8.44
+ * @related   b.contentCredentials.sign, b.contentCredentials.verify, b.contentCredentials.required
+ *
+ * Build an unsigned C2PA 2.1-shaped manifest carrying the SB-942
+ * §22757(a) required fields (provider, system, system version,
+ * content ID) plus optional content type, SHA3-512 digest, and a
+ * visible-disclosure string. Returns a frozen object so downstream
+ * code can't mutate the claims before signing. `generatedAt`
+ * defaults to `Date.now()` so the manifest carries a real timestamp
+ * unless the operator pins one for testing.
+ *
+ * @opts
+ *   provider:          string,             // e.g. "Acme AI Inc."
+ *   providerContact:   string,             // optional contact URL
+ *   system:            string,             // model id, e.g. "acme-image-v3"
+ *   systemVersion:     string,             // semver
+ *   contentId:         string,             // unique per asset
+ *   contentType:       string,             // IANA media type (optional)
+ *   contentSha3:       string,             // SHA3-512 hex (optional)
+ *   generatedAt:       number,             // ms epoch (optional)
+ *   visibleDisclosure: string,             // operator display text (optional)
+ *
+ * @example
+ *   var manifest = b.contentCredentials.build({
+ *     provider:      "Acme AI Inc.",
+ *     system:        "acme-image-v3",
+ *     systemVersion: "3.2.1",
+ *     contentId:     "img-2026-05-08-abc123",
+ *     contentType:   "image/png",
+ *     generatedAt:   Date.UTC(2026, 4, 8),
+ *   });
+ *   manifest.aiGenerated;        // → true
+ *   manifest.system.id;          // → "acme-image-v3"
+ *   manifest.content.id;         // → "img-2026-05-08-abc123"
+ */
 function build(opts) {
   _validateBuildOpts(opts);
   var generatedAt = typeof opts.generatedAt === "number" ? opts.generatedAt : Date.now();
@@ -141,6 +154,36 @@ function build(opts) {
   return Object.freeze(manifest);
 }
 
+/**
+ * @primitive b.contentCredentials.required
+ * @signature b.contentCredentials.required(opts)
+ * @since     0.8.44
+ * @related   b.contentCredentials.build, b.contentCredentials.verify
+ *
+ * Pre-flight check that returns the list of SB-942 §22757(a) fields
+ * missing from a candidate input — useful for operator UIs that
+ * surface "what's needed before we can disclose" without round-
+ * tripping through `build` and catching the throw. Returns `[]`
+ * when every required field is present and non-empty.
+ *
+ * @opts
+ *   provider:      string,                 // required
+ *   system:        string,                 // required
+ *   systemVersion: string,                 // required
+ *   contentId:     string,                 // required
+ *
+ * @example
+ *   b.contentCredentials.required({
+ *     provider:      "Acme AI Inc.",
+ *     system:        "acme-image-v3",
+ *     systemVersion: "3.2.1",
+ *     contentId:     "img-001",
+ *   });
+ *   // → []
+ *
+ *   b.contentCredentials.required({ provider: "Acme AI Inc." });
+ *   // → ["missing-system", "missing-systemVersion", "missing-contentId"]
+ */
 function required(opts) {
   var errors = [];
   if (!opts || typeof opts !== "object") return ["opts-required"];
@@ -152,6 +195,36 @@ function required(opts) {
   return errors;
 }
 
+/**
+ * @primitive b.contentCredentials.sign
+ * @signature b.contentCredentials.sign(manifest, opts)
+ * @since     0.8.44
+ * @related   b.contentCredentials.build, b.contentCredentials.verify, b.crypto.sign
+ *
+ * Canonicalize the manifest (RFC 8785 JCS via `b.canonicalJson`) and
+ * sign it with `b.crypto.sign` using the operator's private-key PEM
+ * — typically the ML-DSA-87 audit-sign keypair. Returns an envelope
+ * with the original manifest plus the base64-encoded signature.
+ * Audits the disclosure under `contentcredentials.signed` unless the
+ * caller passes `audit:false`.
+ *
+ * @opts
+ *   privateKeyPem: string,                 // PEM-encoded signing key
+ *   audit:         boolean,                // default true
+ *
+ * @example
+ *   var pair = b.crypto.generateSigningKeyPair("ml-dsa-87");
+ *   var manifest = b.contentCredentials.build({
+ *     provider:      "Acme AI Inc.",
+ *     system:        "acme-image-v3",
+ *     systemVersion: "3.2.1",
+ *     contentId:     "img-2026-05-08-abc123",
+ *   });
+ *   var envelope = b.contentCredentials.sign(manifest, {
+ *     privateKeyPem: pair.privateKey,
+ *   });
+ *   typeof envelope.signature;   // → "string"
+ */
 function sign(manifest, opts) {
   opts = opts || {};
   if (!manifest || typeof manifest !== "object") {
@@ -180,6 +253,38 @@ function sign(manifest, opts) {
   };
 }
 
+/**
+ * @primitive b.contentCredentials.verify
+ * @signature b.contentCredentials.verify(envelope, publicKeyPem, opts)
+ * @since     0.8.44
+ * @related   b.contentCredentials.sign, b.contentCredentials.build, b.crypto.verify
+ *
+ * Verify a signed envelope produced by `sign`. Re-canonicalizes the
+ * manifest, checks the signature with `b.crypto.verify` against the
+ * operator-supplied public-key PEM, and re-runs the SB-942 required-
+ * field presence check on the verified claims so a manifest with a
+ * valid signature but missing fields fails closed. Never throws —
+ * returns `{ valid, claims, reason }`. Audits successful
+ * verifications under `contentcredentials.verified` unless
+ * `audit:false`.
+ *
+ * @opts
+ *   audit: boolean,                        // default true
+ *
+ * @example
+ *   var pair = b.crypto.generateSigningKeyPair("ml-dsa-87");
+ *   var manifest = b.contentCredentials.build({
+ *     provider:      "Acme AI Inc.",
+ *     system:        "acme-image-v3",
+ *     systemVersion: "3.2.1",
+ *     contentId:     "img-001",
+ *   });
+ *   var envelope = b.contentCredentials.sign(manifest, {
+ *     privateKeyPem: pair.privateKey,
+ *   });
+ *   var result = b.contentCredentials.verify(envelope, pair.publicKey);
+ *   result.valid;   // → true
+ */
 function verify(envelope, publicKeyPem, opts) {
   opts = opts || {};
   if (!envelope || typeof envelope !== "object" || !envelope.manifest || !envelope.signature) {

package/lib/cookies.js

@@ -1,55 +1,50 @@
 "use strict";
 /**
- * cookies — cookie parse/serialize + access-gated sealed cookies.
+ * @module b.cookies
+ * @nav    HTTP
+ * @title  Cookies
  *
- * RFC 6265 cookie plumbing the framework was duplicating across
- * middleware: a parser in attach-user, ad-hoc Set-Cookie strings in
- * route handlers, no shared place for attribute defaults. This is the
- * single primitive.
+ * @intro
+ *   RFC 6265 cookie plumbing — parse, serialize, and sealed (vault-
+ *   gated) cookies in one primitive. Replaces the ad-hoc Set-Cookie
+ *   strings that used to live in middleware and route handlers.
  *
- * Two surfaces:
+ *   Two surfaces:
  *
- *   1. Module-level (stateless): cookies.parse / cookies.serialize.
- *      Useful in test fixtures and code that doesn't have a vault.
+ *     1. Module-level (stateless): `b.cookies.parse` /
+ *        `b.cookies.serialize` / `b.cookies.parseSafe`. Useful in test
+ *        fixtures and code paths that don't have a vault wired.
  *
- *   2. Instance (cookies.create): bound defaults for cookie attributes,
- *      a wired vault for sealed reads/writes, and req/res helpers.
+ *     2. Instance (`b.cookies.create`): bound defaults for cookie
+ *        attributes, a wired vault for sealed reads/writes, and
+ *        request/response helpers (`read` / `write` / `clear` /
+ *        `writeSealed` / `readSealed`).
  *
- *   var cookies = b.cookies.create({
- *     vault: b.vault,                  // required for sealed* methods
- *     defaults: {
- *       httpOnly: true,
- *       secure:   true,                // default true; HTTPS expected
- *       sameSite: "Lax",
- *       path:     "/",
- *       maxAge:   7 * 86400,           // seconds
- *     },
- *   });
+ *   Defaults mirror modern browser expectations: HttpOnly on,
+ *   Secure on, SameSite=Lax, Path=/. Operators developing locally
+ *   over plain http opt out of Secure explicitly so the production
+ *   posture isn't silently weakened.
  *
- *   cookies.parse("a=1; b=2")           → { a: "1", b: "2" }
- *   cookies.serialize("name", "v",
- *     { maxAge: 3600 })                 → "name=v; Max-Age=3600; Path=/; HttpOnly; SameSite=Lax; Secure"
+ *   Cookie-prefix invariants from RFC 6265bis §4.1.3 are enforced at
+ *   serialize time: `__Secure-*` requires Secure; `__Host-*` requires
+ *   Secure + Path=/ + no Domain. Operator typos (`__Host-` cookie
+ *   without Path=/) throw at the source instead of silently failing
+ *   on the browser side.
  *
- *   cookies.read(req, "name")           → "v" or null
- *   cookies.write(res, "name", "v", {}) // appends to existing Set-Cookie
- *   cookies.clear(res, "name", {})      // expire by Max-Age=0
+ *   Header-injection defense: cookie names are RFC 6265 tokens; values
+ *   reject CRLF / NUL / semicolon / comma pre-encoding, then percent-
+ *   encode on write and percent-decode on read. Domain / Path
+ *   attributes are CRLF/NUL-scrubbed before they reach Set-Cookie.
  *
- *   cookies.writeSealed(res, "session", sid)  // vault.seal then write
- *   cookies.readSealed(req, "session")        // read then vault.unseal
+ *   Sealed cookies wrap the value in a `vault.seal` envelope: without
+ *   the framework's vault key no client can hand-craft a valid value,
+ *   so curl-with-arbitrary-cookies (or any tool that hasn't been
+ *   through the framework's crypto flow) can't reach a sealed-cookie-
+ *   gated endpoint. The vault prefix is stripped on write and re-added
+ *   on read so the cookie carries only the compact base64 envelope.
  *
- * Sealed-cookie purpose: the cookie value is a vault.seal of the real
- * value. Without the framework's vault key, no client can hand-craft a
- * valid cookie value, so the API is unreachable via curl-with-arbitrary-
- * cookies or any tool that hasn't been through the framework's crypto
- * flow. The vault prefix is stripped on write and re-added on read so
- * the cookie carries only the base64 envelope.
- *
- * Defense in serialize/parse:
- *   - Cookie name must be a valid token (no CTLs, no separator chars).
- *   - Cookie value must not contain CRLF, semicolon, or comma.
- *   - Value is percent-encoded on write, percent-decoded on read.
- *   - Domain / Path are CRLF-stripped to defeat header injection
- *     attempts via operator-controlled but improperly-escaped inputs.
+ * @card
+ *   RFC 6265 cookie plumbing — parse, serialize, and sealed (vault- gated) cookies in one primitive.
  */
 
 var C = require("./constants");
@@ -116,6 +111,25 @@ function _scrubAttr(s) {
 
 }
 
+/**
+ * @primitive b.cookies.parse
+ * @signature b.cookies.parse(cookieHeader)
+ * @since     0.1.72
+ * @status    stable
+ * @related   b.cookies.parseSafe, b.cookies.serialize, b.cookies.create
+ *
+ * Lenient RFC 6265 Cookie-header parser. Returns a plain object
+ * `{ name: value }` with last-write-wins semantics (matching every
+ * browser). Surrounding double-quotes are stripped per §5.2 and
+ * values are percent-decoded; malformed pairs are silently dropped
+ * because that's how browsers behave. For the threat-detecting
+ * variant that surfaces issues instead of dropping silently, use
+ * `parseSafe`.
+ *
+ * @example
+ *   var jar = b.cookies.parse("session=abc; theme=%22dark%22");
+ *   // → { session: "abc", theme: "dark" }
+ */
 function parse(cookieHeader) {
   var out = {};
   if (typeof cookieHeader !== "string" || cookieHeader.length === 0) return out;
@@ -140,6 +154,43 @@ function parse(cookieHeader) {
   return out;
 }
 
+/**
+ * @primitive b.cookies.serialize
+ * @signature b.cookies.serialize(name, value, attrs)
+ * @since     0.1.72
+ * @status    stable
+ * @related   b.cookies.parse, b.cookies.create
+ *
+ * Build a single Set-Cookie header value from a name, value, and
+ * attributes object. Validates the name as an RFC 6265 token, the
+ * value against CRLF / NUL / `;` / `,`, and enforces the `__Secure-`
+ * / `__Host-` prefix invariants from RFC 6265bis §4.1.3. SameSite
+ * is normalized to `Strict` / `Lax` / `None`, and SameSite=None
+ * implicitly turns Secure on so browsers don't silently drop the
+ * cookie. Throws `CookieError` on any invariant break — the operator
+ * sees the typo at the call site, not as a silently-missing cookie.
+ *
+ * @opts
+ *   maxAge:      3600,        // integer seconds; emits `Max-Age=`
+ *   expires:     new Date(),  // Date or parseable date string
+ *   domain:      "example.com",
+ *   path:        "/",
+ *   httpOnly:    true,
+ *   secure:      true,
+ *   sameSite:    "Lax",       // "Strict" / "Lax" / "None"
+ *   partitioned: false,       // CHIPS partitioning
+ *   priority:    "Medium",    // "Low" / "Medium" / "High"
+ *
+ * @example
+ *   var header = b.cookies.serialize("__Host-sid", "abc", {
+ *     httpOnly: true,
+ *     secure:   true,
+ *     sameSite: "Lax",
+ *     path:     "/",
+ *     maxAge:   3600,
+ *   });
+ *   // → "__Host-sid=abc; Max-Age=3600; Path=/; HttpOnly; SameSite=Lax; Secure"
+ */
 function serialize(name, value, attrs) {
   _validateName(name);
   _validateValue(value);
@@ -269,6 +320,40 @@ function _readCookieFromReq(req, name) {
   return Object.prototype.hasOwnProperty.call(jar, name) ? jar[name] : null;
 }
 
+/**
+ * @primitive b.cookies.create
+ * @signature b.cookies.create(opts)
+ * @since     0.1.72
+ * @status    stable
+ * @related   b.cookies.parse, b.cookies.serialize, b.vault.seal
+ *
+ * Build a cookie helper bound to a default attribute set and an
+ * optional vault. Returned object exposes `read(req, name)`,
+ * `write(res, name, value, attrs)`, `clear(res, name, attrs)`, and
+ * (when a vault is wired) `writeSealed` / `readSealed` for vault-
+ * gated cookie values. Per-call attrs merge over the bound defaults
+ * so callers override piecewise.
+ *
+ * @opts
+ *   vault:    b.vault,                 // required for sealed* methods
+ *   defaults: {
+ *     httpOnly: true,
+ *     secure:   true,
+ *     sameSite: "Lax",
+ *     path:     "/",
+ *     maxAge:   604800,                // seconds (7 days)
+ *   },
+ *
+ * @example
+ *   var cookies = b.cookies.create({
+ *     vault:    b.vault,
+ *     defaults: { httpOnly: true, secure: true, sameSite: "Lax", path: "/" },
+ *   });
+ *   cookies.write(res, "theme", "dark", { maxAge: 86400 });
+ *   cookies.writeSealed(res, "session", "u-1");
+ *   var sid = cookies.readSealed(req, "session");
+ *   // → "u-1" or null
+ */
 function create(opts) {
   opts = opts || {};
   validateOpts(opts, ["vault", "defaults"], "b.cookies");
@@ -343,27 +428,34 @@ function create(opts) {
   };
 }
 
-// parseSafe — threat-detecting inbound-cookie parser. Returns
-// { jar, issues } where every detected anomaly surfaces as an issue
-// instead of being silently dropped (as the lenient parse() does).
-//
-// Threat catalog applied to the inbound Cookie header:
-//   - Oversized header — total bytes exceed maxHeaderBytes (default 8 KiB).
-//   - Oversized pair — name + value exceeds NAME_LENGTH + VALUE_LENGTH cap.
-//   - Duplicate cookie name — RFC 6265 last-write-wins is the browser
-//     behavior, but two pairs with the same name in one Cookie header
-//     usually indicates cookie-tossing (attacker-set parent-domain
-//     cookie shadowing the legitimate one).
-//   - Malformed pair — missing `=` or empty name.
-//   - Forbidden chars in raw header — CR / LF / NUL injected through
-//     a downstream proxy.
-//   - Empty / non-string input — operator-misuse signal.
-//
-// Issue shape: { kind, severity: "high"|"warn", snippet, name? }.
-//
-// Operators wire it through `b.middleware.cookies` (the convenience
-// middleware below) or call directly when they want the issues list
-// without imposing a request lifecycle.
+/**
+ * @primitive b.cookies.parseSafe
+ * @signature b.cookies.parseSafe(cookieHeader, opts)
+ * @since     0.7.20
+ * @status    stable
+ * @related   b.cookies.parse, b.middleware.cookies
+ *
+ * Threat-detecting inbound-cookie parser. Returns
+ * `{ jar, issues }` where every detected anomaly surfaces as an
+ * issue instead of being silently dropped (as the lenient `parse`
+ * does). Detected issues: oversized header / pair, duplicate cookie
+ * name (cookie-tossing class), malformed pair, CR / LF / NUL in the
+ * raw header (proxy-side injection vector), and non-string input.
+ * Issue shape: `{ kind, severity: "high" | "warn", snippet, name? }`.
+ *
+ * @opts
+ *   maxHeaderBytes: 8192,    // total Cookie-header byte cap
+ *   maxNameBytes:   256,     // per-name byte cap
+ *   maxValueBytes:  4096,    // per-value byte cap
+ *
+ * @example
+ *   var result = b.cookies.parseSafe("session=abc; session=evil", {
+ *     maxHeaderBytes: 8192,
+ *   });
+ *   // → { jar: { session: "evil" },
+ *   //     issues: [{ kind: "duplicate-name", severity: "high",
+ *   //                name: "session", snippet: "..." }] }
+ */
 function parseSafe(cookieHeader, opts) {
   opts = opts || {};
   var maxHeaderBytes = opts.maxHeaderBytes || C.BYTES.kib(8);