@cookiemunch/sdk 0.5.1 → 0.7.0

package/CHANGELOG.md

@@ -2,6 +2,28 @@
 
 Every published release, newest first. Dates are the day the version was cut.
 
+## 0.7.0 (2026-10-24)
+
+- Added: `sandbox.get` / `create` / `delete` — a sandbox organisation made from yours: the same people and plan, never billed, test keys only, every rights request a test.
+- Added: dated API versions — the `apiVersion` client option (sends `CookieMunch-Version`), `versions()`, and `keys.updateSelf({ apiVersion })`. Keys minted from 2026-10-24 are strict about unknown body fields by default; older keys behave as before.
+- Added: `exchangeOperatorToken()` — swap an identity provider's token for a key that lasts at most an hour (RFC 8693 token exchange).
+- Added: `sandbox` and `sandboxOf` on `me()`.
+
+## 0.6.0 (2026-10-24)
+
+- Added: `dsar.openCase` / `getCase` / `cancelCase` / `caseReceipt` / `caseReceiptPdf` / `listByTrace` — rights cases fanned out to every connected system, with one `executeAfter`, a trace and a signed receipt.
+- Added: `dsarSettings.get` / `set` (a site's `graceDays`). **Opt-in for existing sites:** a site that existed before grace periods shipped reads `graceDays: 0` (`source: 'legacy'`) and its erasures run exactly as before until you set one; new sites start at 7.
+- Added: `fulfillment.executorConformance` / `rollExecutorCompletionSecret`, `integrations.subjectCard`, and `runExecutorConformance()` — the cm-standard-v2 conformance kit as a function, no Cookie Munch key needed.
+- Added: `closure` and `restriction` types, the `erasure`/`erase`/`export` aliases, and the `cancelled` status.
+- Added: `fulfillment.executor(id)` — one connection with its full profile. Read it before changing `profile`: `updateExecutor` replaces the whole profile.
+- Added: keys — `keys.self()`, `keys.rollSelf()`, `keys.vend({ scopes, ttlSeconds })` (short-lived, at most 12 h), `keys.listStandard()`, `keys.revokeLeaked(report)`; keys can be minted with `scopes`, `cbids` and `expiresInDays`.
+- Added: `partnerLinks.list` / `create` / `revoke` (any partner, scoped), and `metadata.get` / `update` with `metadata` and `externalRef` on sites, webhooks, connections, rights requests and orgs; `?metadata[key]=` list filters; `deleteSandbox` on sandbox sites and orgs.
+- Added: `sites.cookieSuggestions` / `declareCookieSuggestions`, `importCookieManifest` (any vendor's embed manifest) and `removeCookiePreset` for custom presets; `embedManifest(cbid)`; first-class cookie presets for `referalli`, `firstpromoter`, `partnerstack`, `tapfiliate` and `impact` (`referally` is a deprecated alias).
+- Added: `sites.getBrand` / `setBrand` (DTCG brand.json import with a read-back), `consent.insights`, `categoryRegistry()`, `entitlements()`, `provisionEnv(ref)`, and `provision(input, { fromStep })` with the forgedeck (v2) body.
+- Added: `healthWaivers.list` / `set` / `remove`, `auditSink.get` / `set` / `remove` (CloudEvents), `webhooks.replay(id, since)`, `audit(limit, { actor: 'self' })`, `fulfillment.recheckExecutor` and `executorHealthHistory`.
+- Added: `readConsent(source, { requireSigned })`, `verifyDecisionSignature`, `verifyToken` (consent tokens, against the partner JWKS) and `consentSignaturePayload`.
+- Added: the `X-Secret-Recipient` option seals every once-shown secret; `Idempotency-Key` on creates.
+
 ## 0.5.1 (2026-10-23)
 
 - Fixed: `sites.waitForScan` no longer sends one extra poll in the last few milliseconds before its deadline when the server answers at once.

package/dist/chunk-OSVTQPQG.js

@@ -0,0 +1,187 @@
+// src/consent.ts
+var CONSENT_COOKIE_NAME = "CookieMunch";
+function cookieHeaderOf(src) {
+  if (typeof src === "string") return src;
+  if (!src || typeof src !== "object") return "";
+  const h = src.headers;
+  if (!h) return "";
+  if (typeof h.get === "function") {
+    return h.get("cookie") ?? "";
+  }
+  const c = h.cookie;
+  return typeof c === "string" ? c : "";
+}
+function cookieValue(header, name) {
+  for (const part of header.split(";")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) continue;
+    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();
+  }
+  return null;
+}
+function bool(v) {
+  return typeof v === "boolean";
+}
+function decode(raw) {
+  try {
+    return decodeURIComponent(raw);
+  } catch {
+    return raw;
+  }
+}
+function normalize(o) {
+  if (!o || typeof o !== "object") return null;
+  const r = o;
+  if (!bool(r.preferences) || !bool(r.statistics) || !bool(r.marketing)) return null;
+  if (r.method !== "explicit" && r.method !== "implied") return null;
+  if (typeof r.ver !== "number" || typeof r.utc !== "number") return null;
+  if (typeof r.stamp !== "string" && typeof r.stamp !== "number") return null;
+  if (typeof r.region !== "string") return null;
+  const out = {
+    necessary: true,
+    // never trust a cookie that claims necessary:false
+    preferences: r.preferences,
+    statistics: r.statistics,
+    marketing: r.marketing,
+    method: r.method,
+    ver: r.ver,
+    utc: r.utc,
+    region: r.region,
+    stamp: String(r.stamp)
+  };
+  if (r.custom && typeof r.custom === "object" && !Array.isArray(r.custom)) {
+    const custom = {};
+    for (const [k, v] of Object.entries(r.custom)) if (bool(v)) custom[k] = v;
+    if (Object.keys(custom).length > 0) out.custom = custom;
+  }
+  if (typeof r.sig === "string") out.sig = r.sig;
+  return out;
+}
+function parseConsentValue(raw) {
+  if (!raw) return null;
+  const decoded = decode(raw);
+  try {
+    return normalize(JSON.parse(decoded));
+  } catch {
+  }
+  if (!decoded.includes("necessary")) return null;
+  const json = decoded.replace(/'/g, '"').replace(/([{,]\s*)([A-Za-z_][\w]*)\s*:/g, '$1"$2":');
+  try {
+    return normalize(JSON.parse(json));
+  } catch {
+    return null;
+  }
+}
+var DAY_MS = 24 * 60 * 60 * 1e3;
+function readConsent(source, opts = {}) {
+  const consent = readUnsigned(source, opts);
+  if (opts.requireSigned !== true) return consent;
+  if (!consent?.sig) return Promise.resolve(null);
+  return verifyDecisionSignature(consent, opts).then((ok) => ok ? consent : null);
+}
+function readUnsigned(source, opts) {
+  const raw = cookieValue(cookieHeaderOf(source), opts.cookieName ?? CONSENT_COOKIE_NAME);
+  const consent = raw ? parseConsentValue(raw) : null;
+  if (!consent) return null;
+  if (typeof opts.minVersion === "number" && consent.ver < opts.minVersion) return null;
+  if (typeof opts.expiryDays === "number" && opts.expiryDays > 0) {
+    if ((opts.now ?? Date.now()) - consent.utc > opts.expiryDays * DAY_MS) return null;
+  }
+  return consent;
+}
+function getConsent(source, cookieName = CONSENT_COOKIE_NAME) {
+  return readConsent(source, { cookieName });
+}
+function isAllowed(consent, category) {
+  if (category === "necessary") return true;
+  if (!consent) return false;
+  if (category === "preferences") return consent.preferences === true;
+  if (category === "statistics") return consent.statistics === true;
+  if (category === "marketing") return consent.marketing === true;
+  return consent.custom?.[category] === true;
+}
+var DEFAULT_JWKS_URL = "https://api.cookiemunch.net/v1/partner/jwks.json";
+function consentSignaturePayload(d) {
+  const b = (v) => v ? "1" : "0";
+  const custom = d.custom ?? {};
+  const named = Object.keys(custom).sort().map((k) => `${k}=${b(custom[k])}`).join(",");
+  return `cmc1|${d.stamp}|${d.ver}|${d.utc}|${b(d.preferences)}${b(d.statistics)}${b(d.marketing)}|${named}`;
+}
+var jwksCache = /* @__PURE__ */ new Map();
+var JWKS_TTL_MS = 60 * 60 * 1e3;
+async function keySet(opts, kid) {
+  if (opts.jwks) return opts.jwks;
+  const url = opts.jwksUrl ?? DEFAULT_JWKS_URL;
+  const hit = jwksCache.get(url);
+  if (hit && Date.now() - hit.at < JWKS_TTL_MS && hit.set.keys.some((k) => k.kid === kid)) return hit.set;
+  const f = opts.fetch ?? globalThis.fetch;
+  if (!f) throw new Error("no fetch available to load the key set; pass `jwks`");
+  const res = await f(url);
+  if (!res.ok) throw new Error(`key set ${url} answered ${res.status}`);
+  const set = await res.json();
+  if (!set || !Array.isArray(set.keys)) throw new Error(`key set ${url} is not a JWKS`);
+  jwksCache.set(url, { at: Date.now(), set });
+  return set;
+}
+function b64urlBytes(s) {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+async function edVerify(jwk, data, signature) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("WebCrypto is unavailable in this runtime");
+  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x) return false;
+  const key = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+  return subtle.verify({ name: "Ed25519" }, key, b64urlBytes(signature), new TextEncoder().encode(data));
+}
+async function verifyDecisionSignature(consent, opts = {}) {
+  const dot = consent.sig?.lastIndexOf(".") ?? -1;
+  if (!consent.sig || dot <= 0) return false;
+  const kid = consent.sig.slice(0, dot);
+  try {
+    const jwk = (await keySet(opts, kid)).keys.find((k) => k.kid === kid);
+    if (!jwk) return false;
+    return await edVerify(jwk, consentSignaturePayload(consent), consent.sig.slice(dot + 1));
+  } catch {
+    return false;
+  }
+}
+async function verifyToken(token, opts = {}) {
+  const parts = typeof token === "string" ? token.split(".") : [];
+  if (parts.length !== 3) throw new Error("not a JWT");
+  const [h, p, s] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(new TextDecoder().decode(b64urlBytes(h)));
+    claims = JSON.parse(new TextDecoder().decode(b64urlBytes(p)));
+  } catch {
+    throw new Error("malformed token");
+  }
+  if (header.alg !== "EdDSA" || !header.kid) throw new Error("unexpected token algorithm");
+  const jwk = (await keySet(opts, header.kid)).keys.find((k) => k.kid === header.kid);
+  if (!jwk || !await edVerify(jwk, `${h}.${p}`, s)) throw new Error("bad signature");
+  if (claims.token_use !== "consent") throw new Error("not a consent token");
+  const now = (opts.now ?? Date.now()) / 1e3;
+  const leeway = opts.leewaySeconds ?? 30;
+  if (typeof claims.exp !== "number" || now > claims.exp + leeway) throw new Error("expired");
+  if (typeof claims.iat === "number" && claims.iat > now + leeway) throw new Error("issued in the future");
+  if (opts.cbid !== void 0 && (claims.cbid !== opts.cbid || claims.aud !== `cookiemunch:${opts.cbid}`)) throw new Error("token is for another site");
+  return claims;
+}
+
+export {
+  CONSENT_COOKIE_NAME,
+  parseConsentValue,
+  readConsent,
+  getConsent,
+  isAllowed,
+  DEFAULT_JWKS_URL,
+  consentSignaturePayload,
+  verifyDecisionSignature,
+  verifyToken
+};
+//# sourceMappingURL=chunk-OSVTQPQG.js.map

package/dist/chunk-OSVTQPQG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/consent.ts"],"sourcesContent":["/**\n * Server-side consent reading. The Cookie Munch embed stores the visitor's decision in a\n * first-party `CookieMunch` cookie (URL-encoded JSON). This lets a server / edge worker read\n * that decision from the incoming request — to gate server-rendered tags or SSR'd third-party\n * scripts BEFORE they hit the browser — without shipping the whole embed. Zero-dependency and\n * runtime-agnostic: accepts a raw Cookie header, a Node `req` (`req.headers.cookie`), or a\n * Fetch `Request` (`request.headers.get('cookie')`).\n *\n *   import { readConsent, isAllowed } from '@cookiemunch/sdk/consent';\n *   const consent = readConsent(req.headers.cookie);   // ServerConsent | null\n *   if (isAllowed(consent, 'statistics')) { …render analytics tag… }\n *\n * The contract is documented at https://cookiemunch.net/docs/consent-cookie. It accepts\n * exactly what the embed accepts, so a server never grants what the browser would refuse:\n * strict JSON (URL-encoded or not) and the relaxed object literal Cookiebot writes.\n *\n * This module imports nothing — `@cookiemunch/sdk/consent` pulls in no API client.\n */\n\n/** The first-party cookie the embed writes (mirrors @cookiemunch/core COOKIE_NAME). */\nexport const CONSENT_COOKIE_NAME = 'CookieMunch';\n\n/** A visitor's consent decision, read from the request cookie. `necessary` is always true. */\nexport interface ServerConsent {\n  necessary: true;\n  preferences: boolean;\n  statistics: boolean;\n  marketing: boolean;\n  /** How consent was given. `implied` = not yet an explicit choice. */\n  method: 'explicit' | 'implied';\n  /** Custom (non-standard) categories, when the site defines any. */\n  custom?: Record<string, boolean>;\n  /** Consent-policy version the decision was made under (see `minVersion`). */\n  ver: number;\n  /** When the decision was made, epoch milliseconds (see `expiryDays`). */\n  utc: number;\n  /** Region code the decision was made in (`unknown` when undetected). */\n  region: string;\n  /** The anonymous consent-receipt id tying this browser to the consent log. */\n  stamp: string;\n  /**\n   * `<kid>.<base64url>`: the API's Ed25519 signature over this decision, issued when the\n   * ledger recorded it. Absent on a decision no ledger holds (a hand-written cookie).\n   */\n  sig?: string;\n}\n\n/** The site's consent policy, so the server applies the same rules the embed does. */\nexport interface ReadConsentOptions {\n  /** Cookie name. Default `CookieMunch`. */\n  cookieName?: string;\n  /**\n   * The site's current consent version (`consent.version`, or the config `ver` when that is\n   * higher). A decision made under an older version is not honoured by the embed — the\n   * visitor is asked again — so it reads as `null` here too.\n   */\n  minVersion?: number;\n  /** The site's `consent.expiryDays`: a decision older than this reads as `null`. */\n  expiryDays?: number;\n  /** Clock for `expiryDays`, epoch ms. Default `Date.now()`. */\n  now?: number;\n}\n\n/** Where the platform's public signing keys come from, for signatures and consent tokens. */\nexport interface KeySetOptions {\n  /** A key set you already hold (`{ keys: [...] }`). Skips the fetch. */\n  jwks?: JsonWebKeySet;\n  /** Default `https://api.cookiemunch.net/v1/partner/jwks.json`. */\n  jwksUrl?: string;\n  /** Injectable fetch. Default: the global one. */\n  fetch?: typeof fetch;\n}\n\n/** `readConsent` with `requireSigned: true`: only a decision the API signed counts. */\nexport interface ReadSignedConsentOptions extends ReadConsentOptions, KeySetOptions {\n  requireSigned: true;\n}\n\n/** Anything we can pull a Cookie header off of. */\nexport type ConsentSource =\n  | string\n  | null\n  | undefined\n  | { headers?: { cookie?: string | null; get?(name: string): string | null } | Record<string, unknown> };\n\nfunction cookieHeaderOf(src: ConsentSource): string {\n  if (typeof src === 'string') return src;\n  if (!src || typeof src !== 'object') return '';\n  const h = src.headers;\n  if (!h) return '';\n  // Fetch Request: headers.get('cookie'); Node: headers.cookie.\n  if (typeof (h as { get?(n: string): string | null }).get === 'function') {\n    return (h as { get(n: string): string | null }).get('cookie') ?? '';\n  }\n  const c = (h as Record<string, unknown>).cookie;\n  return typeof c === 'string' ? c : '';\n}\n\n/** Extract one cookie's raw value from a Cookie header (no decoding). */\nfunction cookieValue(header: string, name: string): string | null {\n  for (const part of header.split(';')) {\n    const eq = part.indexOf('=');\n    if (eq === -1) continue;\n    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();\n  }\n  return null;\n}\n\nfunction bool(v: unknown): v is boolean {\n  return typeof v === 'boolean';\n}\n\nfunction decode(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw; // not URL-encoded; use as-is\n  }\n}\n\n/** The embed's own validation (core cookie.ts `normalize`), field for field. */\nfunction normalize(o: unknown): ServerConsent | null {\n  if (!o || typeof o !== 'object') return null;\n  const r = o as Record<string, unknown>;\n  if (!bool(r.preferences) || !bool(r.statistics) || !bool(r.marketing)) return null;\n  if (r.method !== 'explicit' && r.method !== 'implied') return null;\n  if (typeof r.ver !== 'number' || typeof r.utc !== 'number') return null;\n  if (typeof r.stamp !== 'string' && typeof r.stamp !== 'number') return null;\n  if (typeof r.region !== 'string') return null;\n  const out: ServerConsent = {\n    necessary: true, // never trust a cookie that claims necessary:false\n    preferences: r.preferences,\n    statistics: r.statistics,\n    marketing: r.marketing,\n    method: r.method,\n    ver: r.ver,\n    utc: r.utc,\n    region: r.region,\n    stamp: String(r.stamp),\n  };\n  if (r.custom && typeof r.custom === 'object' && !Array.isArray(r.custom)) {\n    const custom: Record<string, boolean> = {};\n    for (const [k, v] of Object.entries(r.custom as Record<string, unknown>)) if (bool(v)) custom[k] = v;\n    if (Object.keys(custom).length > 0) out.custom = custom;\n  }\n  if (typeof r.sig === 'string') out.sig = r.sig;\n  return out;\n}\n\n/**\n * Parse a raw cookie value into a validated ServerConsent, or null. Accepts the two formats\n * the embed reads: URL-encoded (or plain) strict JSON, and Cookiebot's relaxed object\n * literal — `{stamp:'…',necessary:true,…}` — left behind by a site migrating from Cookiebot.\n */\nexport function parseConsentValue(raw: string): ServerConsent | null {\n  if (!raw) return null;\n  const decoded = decode(raw);\n  try {\n    return normalize(JSON.parse(decoded));\n  } catch {\n    /* not strict JSON — try the Cookiebot literal */\n  }\n  if (!decoded.includes('necessary')) return null;\n  const json = decoded.replace(/'/g, '\"').replace(/([{,]\\s*)([A-Za-z_][\\w]*)\\s*:/g, '$1\"$2\":');\n  try {\n    return normalize(JSON.parse(json));\n  } catch {\n    return null;\n  }\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\n/**\n * Read the visitor's consent from a request: a raw `Cookie` header, a Node `req`, or a Fetch\n * `Request`. Returns null when there is no decision the embed would honour — no cookie, an\n * unparseable one, or (with the options) one made under an older version or past expiry.\n */\nexport function readConsent(source: ConsentSource, opts: ReadSignedConsentOptions): Promise<ServerConsent | null>;\nexport function readConsent(source: ConsentSource, opts?: ReadConsentOptions & { requireSigned?: false }): ServerConsent | null;\nexport function readConsent(\n  source: ConsentSource,\n  opts: ReadConsentOptions & { requireSigned?: boolean } & KeySetOptions = {},\n): ServerConsent | null | Promise<ServerConsent | null> {\n  const consent = readUnsigned(source, opts);\n  if (opts.requireSigned !== true) return consent;\n  // CMU-S04: a decision counts only when the API's signature over it verifies against the\n  // published key set. A hand-written cookie (no sig) or a forged one reads as no decision.\n  if (!consent?.sig) return Promise.resolve(null);\n  return verifyDecisionSignature(consent, opts).then((ok) => (ok ? consent : null));\n}\n\nfunction readUnsigned(source: ConsentSource, opts: ReadConsentOptions): ServerConsent | null {\n  const raw = cookieValue(cookieHeaderOf(source), opts.cookieName ?? CONSENT_COOKIE_NAME);\n  const consent = raw ? parseConsentValue(raw) : null;\n  if (!consent) return null;\n  if (typeof opts.minVersion === 'number' && consent.ver < opts.minVersion) return null;\n  if (typeof opts.expiryDays === 'number' && opts.expiryDays > 0) {\n    if ((opts.now ?? Date.now()) - consent.utc > opts.expiryDays * DAY_MS) return null;\n  }\n  return consent;\n}\n\n/**\n * Read the visitor's consent from a request. The original spelling of {@link readConsent},\n * kept for existing callers; the second argument is the cookie name.\n */\nexport function getConsent(source: ConsentSource, cookieName: string = CONSENT_COOKIE_NAME): ServerConsent | null {\n  return readConsent(source, { cookieName });\n}\n\n/** Standard + custom consent categories. */\nexport type ConsentCategory = 'necessary' | 'preferences' | 'statistics' | 'marketing' | (string & {});\n\n/**\n * Whether a category is allowed for this visitor. `necessary` is always allowed. A missing\n * consent (`null` — visitor hasn't decided) is treated as NOT allowed for non-necessary\n * categories (fail-closed / prior-blocking posture), matching the embed.\n */\nexport function isAllowed(consent: ServerConsent | null, category: ConsentCategory): boolean {\n  if (category === 'necessary') return true;\n  if (!consent) return false;\n  // Explicit per-literal access rather than `consent[category]`: the `(string & {})` arm of\n  // ConsentCategory defeats control-flow narrowing, so a dynamic index is typed as an\n  // implicit-any index into ServerConsent (TS7053, which fails the tsup DTS build).\n  if (category === 'preferences') return consent.preferences === true;\n  if (category === 'statistics') return consent.statistics === true;\n  if (category === 'marketing') return consent.marketing === true;\n  return consent.custom?.[category] === true;\n}\n\n// ---- signatures (CMU-S04) and consent tokens (CMU-F06) ----\n\nexport const DEFAULT_JWKS_URL = 'https://api.cookiemunch.net/v1/partner/jwks.json';\n\n/** The fields of a decision its signature covers. */\nexport interface SignableDecision {\n  stamp: string;\n  ver: number;\n  utc: number;\n  preferences: boolean;\n  statistics: boolean;\n  marketing: boolean;\n  custom?: Record<string, boolean> | undefined;\n}\n\n/**\n * The exact line the API signs for a recorded decision. Identical to @cookiemunch/core's\n * `consentSignaturePayload` (a server test pins the two together).\n */\nexport function consentSignaturePayload(d: SignableDecision): string {\n  const b = (v: boolean | undefined): string => (v ? '1' : '0');\n  const custom = d.custom ?? {};\n  const named = Object.keys(custom)\n    .sort()\n    .map((k) => `${k}=${b(custom[k])}`)\n    .join(',');\n  return `cmc1|${d.stamp}|${d.ver}|${d.utc}|${b(d.preferences)}${b(d.statistics)}${b(d.marketing)}|${named}`;\n}\n\ninterface Jwk {\n  kty?: string;\n  crv?: string;\n  x?: string;\n  kid?: string;\n  alg?: string;\n}\nexport interface JsonWebKeySet {\n  keys: Jwk[];\n}\n\nconst jwksCache = new Map<string, { at: number; set: JsonWebKeySet }>();\nconst JWKS_TTL_MS = 60 * 60 * 1000;\n\nasync function keySet(opts: KeySetOptions, kid: string): Promise<JsonWebKeySet> {\n  if (opts.jwks) return opts.jwks;\n  const url = opts.jwksUrl ?? DEFAULT_JWKS_URL;\n  const hit = jwksCache.get(url);\n  // An unknown kid refetches: the key may have rotated since the cached copy.\n  if (hit && Date.now() - hit.at < JWKS_TTL_MS && hit.set.keys.some((k) => k.kid === kid)) return hit.set;\n  const f = opts.fetch ?? (globalThis as { fetch?: typeof fetch }).fetch;\n  if (!f) throw new Error('no fetch available to load the key set; pass `jwks`');\n  const res = await f(url);\n  if (!res.ok) throw new Error(`key set ${url} answered ${res.status}`);\n  const set = (await res.json()) as JsonWebKeySet;\n  if (!set || !Array.isArray(set.keys)) throw new Error(`key set ${url} is not a JWKS`);\n  jwksCache.set(url, { at: Date.now(), set });\n  return set;\n}\n\nfunction b64urlBytes(s: string): Uint8Array {\n  const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4);\n  const bin = atob(b64);\n  const out = new Uint8Array(bin.length);\n  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);\n  return out;\n}\n\n/** Ed25519 verify with WebCrypto (Node 20+, Deno, Bun, workers, browsers). */\nasync function edVerify(jwk: Jwk, data: string, signature: string): Promise<boolean> {\n  const subtle = (globalThis as { crypto?: Crypto }).crypto?.subtle;\n  if (!subtle) throw new Error('WebCrypto is unavailable in this runtime');\n  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || !jwk.x) return false;\n  const key = await subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, { name: 'Ed25519' }, false, ['verify']);\n  return subtle.verify({ name: 'Ed25519' }, key, b64urlBytes(signature) as BufferSource, new TextEncoder().encode(data) as BufferSource);\n}\n\n/** Does the cookie's `sig` verify for this decision? False on anything malformed. */\nexport async function verifyDecisionSignature(consent: ServerConsent, opts: KeySetOptions = {}): Promise<boolean> {\n  const dot = consent.sig?.lastIndexOf('.') ?? -1;\n  if (!consent.sig || dot <= 0) return false;\n  const kid = consent.sig.slice(0, dot);\n  try {\n    const jwk = (await keySet(opts, kid)).keys.find((k) => k.kid === kid);\n    if (!jwk) return false;\n    return await edVerify(jwk, consentSignaturePayload(consent), consent.sig.slice(dot + 1));\n  } catch {\n    return false;\n  }\n}\n\n/** What a consent token (`CookieMunch.getConsentToken()`) asserts. */\nexport interface ConsentTokenClaims {\n  iss: string;\n  /** The decision's stamp. */\n  sub: string;\n  /** `cookiemunch:<cbid>`. */\n  aud: string;\n  token_use: 'consent';\n  cbid: string;\n  stamp: string;\n  /** Every category the decision answered, `necessary` included. */\n  choices: Record<string, boolean>;\n  ver: number;\n  /** When the decision was made, epoch ms. */\n  decidedAt: number;\n  cause?: string;\n  iat: number;\n  exp: number;\n}\n\nexport interface VerifyTokenOptions extends KeySetOptions {\n  /** Require the token to be for this site. */\n  cbid?: string;\n  /** Clock, epoch ms. Default `Date.now()`. */\n  now?: number;\n  /** Allowed clock skew, seconds. Default 30. */\n  leewaySeconds?: number;\n}\n\n/**\n * Verify a consent token from `CookieMunch.getConsentToken()` (CMU-F06) against the published\n * key set and return its claims. Throws on a bad signature, a wrong site, or an expired token.\n */\nexport async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<ConsentTokenClaims> {\n  const parts = typeof token === 'string' ? token.split('.') : [];\n  if (parts.length !== 3) throw new Error('not a JWT');\n  const [h, p, s] = parts as [string, string, string];\n  let header: { alg?: string; kid?: string };\n  let claims: ConsentTokenClaims;\n  try {\n    header = JSON.parse(new TextDecoder().decode(b64urlBytes(h)));\n    claims = JSON.parse(new TextDecoder().decode(b64urlBytes(p)));\n  } catch {\n    throw new Error('malformed token');\n  }\n  if (header.alg !== 'EdDSA' || !header.kid) throw new Error('unexpected token algorithm');\n  const jwk = (await keySet(opts, header.kid)).keys.find((k) => k.kid === header.kid);\n  if (!jwk || !(await edVerify(jwk, `${h}.${p}`, s))) throw new Error('bad signature');\n  if (claims.token_use !== 'consent') throw new Error('not a consent token');\n  const now = (opts.now ?? Date.now()) / 1000;\n  const leeway = opts.leewaySeconds ?? 30;\n  if (typeof claims.exp !== 'number' || now > claims.exp + leeway) throw new Error('expired');\n  if (typeof claims.iat === 'number' && claims.iat > now + leeway) throw new Error('issued in the future');\n  if (opts.cbid !== undefined && (claims.cbid !== opts.cbid || claims.aud !== `cookiemunch:${opts.cbid}`)) throw new Error('token is for another site');\n  return claims;\n}\n"],"mappings":"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","names":[]}

package/dist/consent.cjs

@@ -21,10 +21,14 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var consent_exports = {};
 __export(consent_exports, {
   CONSENT_COOKIE_NAME: () => CONSENT_COOKIE_NAME,
+  DEFAULT_JWKS_URL: () => DEFAULT_JWKS_URL,
+  consentSignaturePayload: () => consentSignaturePayload,
   getConsent: () => getConsent,
   isAllowed: () => isAllowed,
   parseConsentValue: () => parseConsentValue,
-  readConsent: () => readConsent
+  readConsent: () => readConsent,
+  verifyDecisionSignature: () => verifyDecisionSignature,
+  verifyToken: () => verifyToken
 });
 module.exports = __toCommonJS(consent_exports);
 var CONSENT_COOKIE_NAME = "CookieMunch";
@@ -82,6 +86,7 @@ function normalize(o) {
     for (const [k, v] of Object.entries(r.custom)) if (bool(v)) custom[k] = v;
     if (Object.keys(custom).length > 0) out.custom = custom;
   }
+  if (typeof r.sig === "string") out.sig = r.sig;
   return out;
 }
 function parseConsentValue(raw) {
@@ -101,6 +106,12 @@ function parseConsentValue(raw) {
 }
 var DAY_MS = 24 * 60 * 60 * 1e3;
 function readConsent(source, opts = {}) {
+  const consent = readUnsigned(source, opts);
+  if (opts.requireSigned !== true) return consent;
+  if (!consent?.sig) return Promise.resolve(null);
+  return verifyDecisionSignature(consent, opts).then((ok) => ok ? consent : null);
+}
+function readUnsigned(source, opts) {
   const raw = cookieValue(cookieHeaderOf(source), opts.cookieName ?? CONSENT_COOKIE_NAME);
   const consent = raw ? parseConsentValue(raw) : null;
   if (!consent) return null;
@@ -121,12 +132,88 @@ function isAllowed(consent, category) {
   if (category === "marketing") return consent.marketing === true;
   return consent.custom?.[category] === true;
 }
+var DEFAULT_JWKS_URL = "https://api.cookiemunch.net/v1/partner/jwks.json";
+function consentSignaturePayload(d) {
+  const b = (v) => v ? "1" : "0";
+  const custom = d.custom ?? {};
+  const named = Object.keys(custom).sort().map((k) => `${k}=${b(custom[k])}`).join(",");
+  return `cmc1|${d.stamp}|${d.ver}|${d.utc}|${b(d.preferences)}${b(d.statistics)}${b(d.marketing)}|${named}`;
+}
+var jwksCache = /* @__PURE__ */ new Map();
+var JWKS_TTL_MS = 60 * 60 * 1e3;
+async function keySet(opts, kid) {
+  if (opts.jwks) return opts.jwks;
+  const url = opts.jwksUrl ?? DEFAULT_JWKS_URL;
+  const hit = jwksCache.get(url);
+  if (hit && Date.now() - hit.at < JWKS_TTL_MS && hit.set.keys.some((k) => k.kid === kid)) return hit.set;
+  const f = opts.fetch ?? globalThis.fetch;
+  if (!f) throw new Error("no fetch available to load the key set; pass `jwks`");
+  const res = await f(url);
+  if (!res.ok) throw new Error(`key set ${url} answered ${res.status}`);
+  const set = await res.json();
+  if (!set || !Array.isArray(set.keys)) throw new Error(`key set ${url} is not a JWKS`);
+  jwksCache.set(url, { at: Date.now(), set });
+  return set;
+}
+function b64urlBytes(s) {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+async function edVerify(jwk, data, signature) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("WebCrypto is unavailable in this runtime");
+  if (jwk.kty !== "OKP" || jwk.crv !== "Ed25519" || !jwk.x) return false;
+  const key = await subtle.importKey("jwk", { kty: "OKP", crv: "Ed25519", x: jwk.x }, { name: "Ed25519" }, false, ["verify"]);
+  return subtle.verify({ name: "Ed25519" }, key, b64urlBytes(signature), new TextEncoder().encode(data));
+}
+async function verifyDecisionSignature(consent, opts = {}) {
+  const dot = consent.sig?.lastIndexOf(".") ?? -1;
+  if (!consent.sig || dot <= 0) return false;
+  const kid = consent.sig.slice(0, dot);
+  try {
+    const jwk = (await keySet(opts, kid)).keys.find((k) => k.kid === kid);
+    if (!jwk) return false;
+    return await edVerify(jwk, consentSignaturePayload(consent), consent.sig.slice(dot + 1));
+  } catch {
+    return false;
+  }
+}
+async function verifyToken(token, opts = {}) {
+  const parts = typeof token === "string" ? token.split(".") : [];
+  if (parts.length !== 3) throw new Error("not a JWT");
+  const [h, p, s] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(new TextDecoder().decode(b64urlBytes(h)));
+    claims = JSON.parse(new TextDecoder().decode(b64urlBytes(p)));
+  } catch {
+    throw new Error("malformed token");
+  }
+  if (header.alg !== "EdDSA" || !header.kid) throw new Error("unexpected token algorithm");
+  const jwk = (await keySet(opts, header.kid)).keys.find((k) => k.kid === header.kid);
+  if (!jwk || !await edVerify(jwk, `${h}.${p}`, s)) throw new Error("bad signature");
+  if (claims.token_use !== "consent") throw new Error("not a consent token");
+  const now = (opts.now ?? Date.now()) / 1e3;
+  const leeway = opts.leewaySeconds ?? 30;
+  if (typeof claims.exp !== "number" || now > claims.exp + leeway) throw new Error("expired");
+  if (typeof claims.iat === "number" && claims.iat > now + leeway) throw new Error("issued in the future");
+  if (opts.cbid !== void 0 && (claims.cbid !== opts.cbid || claims.aud !== `cookiemunch:${opts.cbid}`)) throw new Error("token is for another site");
+  return claims;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   CONSENT_COOKIE_NAME,
+  DEFAULT_JWKS_URL,
+  consentSignaturePayload,
   getConsent,
   isAllowed,
   parseConsentValue,
-  readConsent
+  readConsent,
+  verifyDecisionSignature,
+  verifyToken
 });
 //# sourceMappingURL=consent.cjs.map

package/dist/consent.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/consent.ts"],"sourcesContent":["/**\n * Server-side consent reading. The Cookie Munch embed stores the visitor's decision in a\n * first-party `CookieMunch` cookie (URL-encoded JSON). This lets a server / edge worker read\n * that decision from the incoming request — to gate server-rendered tags or SSR'd third-party\n * scripts BEFORE they hit the browser — without shipping the whole embed. Zero-dependency and\n * runtime-agnostic: accepts a raw Cookie header, a Node `req` (`req.headers.cookie`), or a\n * Fetch `Request` (`request.headers.get('cookie')`).\n *\n *   import { readConsent, isAllowed } from '@cookiemunch/sdk/consent';\n *   const consent = readConsent(req.headers.cookie);   // ServerConsent | null\n *   if (isAllowed(consent, 'statistics')) { …render analytics tag… }\n *\n * The contract is documented at https://cookiemunch.net/docs/consent-cookie. It accepts\n * exactly what the embed accepts, so a server never grants what the browser would refuse:\n * strict JSON (URL-encoded or not) and the relaxed object literal Cookiebot writes.\n *\n * This module imports nothing — `@cookiemunch/sdk/consent` pulls in no API client.\n */\n\n/** The first-party cookie the embed writes (mirrors @cookiemunch/core COOKIE_NAME). */\nexport const CONSENT_COOKIE_NAME = 'CookieMunch';\n\n/** A visitor's consent decision, read from the request cookie. `necessary` is always true. */\nexport interface ServerConsent {\n  necessary: true;\n  preferences: boolean;\n  statistics: boolean;\n  marketing: boolean;\n  /** How consent was given. `implied` = not yet an explicit choice. */\n  method: 'explicit' | 'implied';\n  /** Custom (non-standard) categories, when the site defines any. */\n  custom?: Record<string, boolean>;\n  /** Consent-policy version the decision was made under (see `minVersion`). */\n  ver: number;\n  /** When the decision was made, epoch milliseconds (see `expiryDays`). */\n  utc: number;\n  /** Region code the decision was made in (`unknown` when undetected). */\n  region: string;\n  /** The anonymous consent-receipt id tying this browser to the consent log. */\n  stamp: string;\n}\n\n/** The site's consent policy, so the server applies the same rules the embed does. */\nexport interface ReadConsentOptions {\n  /** Cookie name. Default `CookieMunch`. */\n  cookieName?: string;\n  /**\n   * The site's current consent version (`consent.version`, or the config `ver` when that is\n   * higher). A decision made under an older version is not honoured by the embed — the\n   * visitor is asked again — so it reads as `null` here too.\n   */\n  minVersion?: number;\n  /** The site's `consent.expiryDays`: a decision older than this reads as `null`. */\n  expiryDays?: number;\n  /** Clock for `expiryDays`, epoch ms. Default `Date.now()`. */\n  now?: number;\n}\n\n/** Anything we can pull a Cookie header off of. */\nexport type ConsentSource =\n  | string\n  | null\n  | undefined\n  | { headers?: { cookie?: string | null; get?(name: string): string | null } | Record<string, unknown> };\n\nfunction cookieHeaderOf(src: ConsentSource): string {\n  if (typeof src === 'string') return src;\n  if (!src || typeof src !== 'object') return '';\n  const h = src.headers;\n  if (!h) return '';\n  // Fetch Request: headers.get('cookie'); Node: headers.cookie.\n  if (typeof (h as { get?(n: string): string | null }).get === 'function') {\n    return (h as { get(n: string): string | null }).get('cookie') ?? '';\n  }\n  const c = (h as Record<string, unknown>).cookie;\n  return typeof c === 'string' ? c : '';\n}\n\n/** Extract one cookie's raw value from a Cookie header (no decoding). */\nfunction cookieValue(header: string, name: string): string | null {\n  for (const part of header.split(';')) {\n    const eq = part.indexOf('=');\n    if (eq === -1) continue;\n    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();\n  }\n  return null;\n}\n\nfunction bool(v: unknown): v is boolean {\n  return typeof v === 'boolean';\n}\n\nfunction decode(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw; // not URL-encoded; use as-is\n  }\n}\n\n/** The embed's own validation (core cookie.ts `normalize`), field for field. */\nfunction normalize(o: unknown): ServerConsent | null {\n  if (!o || typeof o !== 'object') return null;\n  const r = o as Record<string, unknown>;\n  if (!bool(r.preferences) || !bool(r.statistics) || !bool(r.marketing)) return null;\n  if (r.method !== 'explicit' && r.method !== 'implied') return null;\n  if (typeof r.ver !== 'number' || typeof r.utc !== 'number') return null;\n  if (typeof r.stamp !== 'string' && typeof r.stamp !== 'number') return null;\n  if (typeof r.region !== 'string') return null;\n  const out: ServerConsent = {\n    necessary: true, // never trust a cookie that claims necessary:false\n    preferences: r.preferences,\n    statistics: r.statistics,\n    marketing: r.marketing,\n    method: r.method,\n    ver: r.ver,\n    utc: r.utc,\n    region: r.region,\n    stamp: String(r.stamp),\n  };\n  if (r.custom && typeof r.custom === 'object' && !Array.isArray(r.custom)) {\n    const custom: Record<string, boolean> = {};\n    for (const [k, v] of Object.entries(r.custom as Record<string, unknown>)) if (bool(v)) custom[k] = v;\n    if (Object.keys(custom).length > 0) out.custom = custom;\n  }\n  return out;\n}\n\n/**\n * Parse a raw cookie value into a validated ServerConsent, or null. Accepts the two formats\n * the embed reads: URL-encoded (or plain) strict JSON, and Cookiebot's relaxed object\n * literal — `{stamp:'…',necessary:true,…}` — left behind by a site migrating from Cookiebot.\n */\nexport function parseConsentValue(raw: string): ServerConsent | null {\n  if (!raw) return null;\n  const decoded = decode(raw);\n  try {\n    return normalize(JSON.parse(decoded));\n  } catch {\n    /* not strict JSON — try the Cookiebot literal */\n  }\n  if (!decoded.includes('necessary')) return null;\n  const json = decoded.replace(/'/g, '\"').replace(/([{,]\\s*)([A-Za-z_][\\w]*)\\s*:/g, '$1\"$2\":');\n  try {\n    return normalize(JSON.parse(json));\n  } catch {\n    return null;\n  }\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\n/**\n * Read the visitor's consent from a request: a raw `Cookie` header, a Node `req`, or a Fetch\n * `Request`. Returns null when there is no decision the embed would honour — no cookie, an\n * unparseable one, or (with the options) one made under an older version or past expiry.\n */\nexport function readConsent(source: ConsentSource, opts: ReadConsentOptions = {}): ServerConsent | null {\n  const raw = cookieValue(cookieHeaderOf(source), opts.cookieName ?? CONSENT_COOKIE_NAME);\n  const consent = raw ? parseConsentValue(raw) : null;\n  if (!consent) return null;\n  if (typeof opts.minVersion === 'number' && consent.ver < opts.minVersion) return null;\n  if (typeof opts.expiryDays === 'number' && opts.expiryDays > 0) {\n    if ((opts.now ?? Date.now()) - consent.utc > opts.expiryDays * DAY_MS) return null;\n  }\n  return consent;\n}\n\n/**\n * Read the visitor's consent from a request. The original spelling of {@link readConsent},\n * kept for existing callers; the second argument is the cookie name.\n */\nexport function getConsent(source: ConsentSource, cookieName: string = CONSENT_COOKIE_NAME): ServerConsent | null {\n  return readConsent(source, { cookieName });\n}\n\n/** Standard + custom consent categories. */\nexport type ConsentCategory = 'necessary' | 'preferences' | 'statistics' | 'marketing' | (string & {});\n\n/**\n * Whether a category is allowed for this visitor. `necessary` is always allowed. A missing\n * consent (`null` — visitor hasn't decided) is treated as NOT allowed for non-necessary\n * categories (fail-closed / prior-blocking posture), matching the embed.\n */\nexport function isAllowed(consent: ServerConsent | null, category: ConsentCategory): boolean {\n  if (category === 'necessary') return true;\n  if (!consent) return false;\n  // Explicit per-literal access rather than `consent[category]`: the `(string & {})` arm of\n  // ConsentCategory defeats control-flow narrowing, so a dynamic index is typed as an\n  // implicit-any index into ServerConsent (TS7053, which fails the tsup DTS build).\n  if (category === 'preferences') return consent.preferences === true;\n  if (category === 'statistics') return consent.statistics === true;\n  if (category === 'marketing') return consent.marketing === true;\n  return consent.custom?.[category] === true;\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/consent.ts"],"sourcesContent":["/**\n * Server-side consent reading. The Cookie Munch embed stores the visitor's decision in a\n * first-party `CookieMunch` cookie (URL-encoded JSON). This lets a server / edge worker read\n * that decision from the incoming request — to gate server-rendered tags or SSR'd third-party\n * scripts BEFORE they hit the browser — without shipping the whole embed. Zero-dependency and\n * runtime-agnostic: accepts a raw Cookie header, a Node `req` (`req.headers.cookie`), or a\n * Fetch `Request` (`request.headers.get('cookie')`).\n *\n *   import { readConsent, isAllowed } from '@cookiemunch/sdk/consent';\n *   const consent = readConsent(req.headers.cookie);   // ServerConsent | null\n *   if (isAllowed(consent, 'statistics')) { …render analytics tag… }\n *\n * The contract is documented at https://cookiemunch.net/docs/consent-cookie. It accepts\n * exactly what the embed accepts, so a server never grants what the browser would refuse:\n * strict JSON (URL-encoded or not) and the relaxed object literal Cookiebot writes.\n *\n * This module imports nothing — `@cookiemunch/sdk/consent` pulls in no API client.\n */\n\n/** The first-party cookie the embed writes (mirrors @cookiemunch/core COOKIE_NAME). */\nexport const CONSENT_COOKIE_NAME = 'CookieMunch';\n\n/** A visitor's consent decision, read from the request cookie. `necessary` is always true. */\nexport interface ServerConsent {\n  necessary: true;\n  preferences: boolean;\n  statistics: boolean;\n  marketing: boolean;\n  /** How consent was given. `implied` = not yet an explicit choice. */\n  method: 'explicit' | 'implied';\n  /** Custom (non-standard) categories, when the site defines any. */\n  custom?: Record<string, boolean>;\n  /** Consent-policy version the decision was made under (see `minVersion`). */\n  ver: number;\n  /** When the decision was made, epoch milliseconds (see `expiryDays`). */\n  utc: number;\n  /** Region code the decision was made in (`unknown` when undetected). */\n  region: string;\n  /** The anonymous consent-receipt id tying this browser to the consent log. */\n  stamp: string;\n  /**\n   * `<kid>.<base64url>`: the API's Ed25519 signature over this decision, issued when the\n   * ledger recorded it. Absent on a decision no ledger holds (a hand-written cookie).\n   */\n  sig?: string;\n}\n\n/** The site's consent policy, so the server applies the same rules the embed does. */\nexport interface ReadConsentOptions {\n  /** Cookie name. Default `CookieMunch`. */\n  cookieName?: string;\n  /**\n   * The site's current consent version (`consent.version`, or the config `ver` when that is\n   * higher). A decision made under an older version is not honoured by the embed — the\n   * visitor is asked again — so it reads as `null` here too.\n   */\n  minVersion?: number;\n  /** The site's `consent.expiryDays`: a decision older than this reads as `null`. */\n  expiryDays?: number;\n  /** Clock for `expiryDays`, epoch ms. Default `Date.now()`. */\n  now?: number;\n}\n\n/** Where the platform's public signing keys come from, for signatures and consent tokens. */\nexport interface KeySetOptions {\n  /** A key set you already hold (`{ keys: [...] }`). Skips the fetch. */\n  jwks?: JsonWebKeySet;\n  /** Default `https://api.cookiemunch.net/v1/partner/jwks.json`. */\n  jwksUrl?: string;\n  /** Injectable fetch. Default: the global one. */\n  fetch?: typeof fetch;\n}\n\n/** `readConsent` with `requireSigned: true`: only a decision the API signed counts. */\nexport interface ReadSignedConsentOptions extends ReadConsentOptions, KeySetOptions {\n  requireSigned: true;\n}\n\n/** Anything we can pull a Cookie header off of. */\nexport type ConsentSource =\n  | string\n  | null\n  | undefined\n  | { headers?: { cookie?: string | null; get?(name: string): string | null } | Record<string, unknown> };\n\nfunction cookieHeaderOf(src: ConsentSource): string {\n  if (typeof src === 'string') return src;\n  if (!src || typeof src !== 'object') return '';\n  const h = src.headers;\n  if (!h) return '';\n  // Fetch Request: headers.get('cookie'); Node: headers.cookie.\n  if (typeof (h as { get?(n: string): string | null }).get === 'function') {\n    return (h as { get(n: string): string | null }).get('cookie') ?? '';\n  }\n  const c = (h as Record<string, unknown>).cookie;\n  return typeof c === 'string' ? c : '';\n}\n\n/** Extract one cookie's raw value from a Cookie header (no decoding). */\nfunction cookieValue(header: string, name: string): string | null {\n  for (const part of header.split(';')) {\n    const eq = part.indexOf('=');\n    if (eq === -1) continue;\n    if (part.slice(0, eq).trim() === name) return part.slice(eq + 1).trim();\n  }\n  return null;\n}\n\nfunction bool(v: unknown): v is boolean {\n  return typeof v === 'boolean';\n}\n\nfunction decode(raw: string): string {\n  try {\n    return decodeURIComponent(raw);\n  } catch {\n    return raw; // not URL-encoded; use as-is\n  }\n}\n\n/** The embed's own validation (core cookie.ts `normalize`), field for field. */\nfunction normalize(o: unknown): ServerConsent | null {\n  if (!o || typeof o !== 'object') return null;\n  const r = o as Record<string, unknown>;\n  if (!bool(r.preferences) || !bool(r.statistics) || !bool(r.marketing)) return null;\n  if (r.method !== 'explicit' && r.method !== 'implied') return null;\n  if (typeof r.ver !== 'number' || typeof r.utc !== 'number') return null;\n  if (typeof r.stamp !== 'string' && typeof r.stamp !== 'number') return null;\n  if (typeof r.region !== 'string') return null;\n  const out: ServerConsent = {\n    necessary: true, // never trust a cookie that claims necessary:false\n    preferences: r.preferences,\n    statistics: r.statistics,\n    marketing: r.marketing,\n    method: r.method,\n    ver: r.ver,\n    utc: r.utc,\n    region: r.region,\n    stamp: String(r.stamp),\n  };\n  if (r.custom && typeof r.custom === 'object' && !Array.isArray(r.custom)) {\n    const custom: Record<string, boolean> = {};\n    for (const [k, v] of Object.entries(r.custom as Record<string, unknown>)) if (bool(v)) custom[k] = v;\n    if (Object.keys(custom).length > 0) out.custom = custom;\n  }\n  if (typeof r.sig === 'string') out.sig = r.sig;\n  return out;\n}\n\n/**\n * Parse a raw cookie value into a validated ServerConsent, or null. Accepts the two formats\n * the embed reads: URL-encoded (or plain) strict JSON, and Cookiebot's relaxed object\n * literal — `{stamp:'…',necessary:true,…}` — left behind by a site migrating from Cookiebot.\n */\nexport function parseConsentValue(raw: string): ServerConsent | null {\n  if (!raw) return null;\n  const decoded = decode(raw);\n  try {\n    return normalize(JSON.parse(decoded));\n  } catch {\n    /* not strict JSON — try the Cookiebot literal */\n  }\n  if (!decoded.includes('necessary')) return null;\n  const json = decoded.replace(/'/g, '\"').replace(/([{,]\\s*)([A-Za-z_][\\w]*)\\s*:/g, '$1\"$2\":');\n  try {\n    return normalize(JSON.parse(json));\n  } catch {\n    return null;\n  }\n}\n\nconst DAY_MS = 24 * 60 * 60 * 1000;\n\n/**\n * Read the visitor's consent from a request: a raw `Cookie` header, a Node `req`, or a Fetch\n * `Request`. Returns null when there is no decision the embed would honour — no cookie, an\n * unparseable one, or (with the options) one made under an older version or past expiry.\n */\nexport function readConsent(source: ConsentSource, opts: ReadSignedConsentOptions): Promise<ServerConsent | null>;\nexport function readConsent(source: ConsentSource, opts?: ReadConsentOptions & { requireSigned?: false }): ServerConsent | null;\nexport function readConsent(\n  source: ConsentSource,\n  opts: ReadConsentOptions & { requireSigned?: boolean } & KeySetOptions = {},\n): ServerConsent | null | Promise<ServerConsent | null> {\n  const consent = readUnsigned(source, opts);\n  if (opts.requireSigned !== true) return consent;\n  // CMU-S04: a decision counts only when the API's signature over it verifies against the\n  // published key set. A hand-written cookie (no sig) or a forged one reads as no decision.\n  if (!consent?.sig) return Promise.resolve(null);\n  return verifyDecisionSignature(consent, opts).then((ok) => (ok ? consent : null));\n}\n\nfunction readUnsigned(source: ConsentSource, opts: ReadConsentOptions): ServerConsent | null {\n  const raw = cookieValue(cookieHeaderOf(source), opts.cookieName ?? CONSENT_COOKIE_NAME);\n  const consent = raw ? parseConsentValue(raw) : null;\n  if (!consent) return null;\n  if (typeof opts.minVersion === 'number' && consent.ver < opts.minVersion) return null;\n  if (typeof opts.expiryDays === 'number' && opts.expiryDays > 0) {\n    if ((opts.now ?? Date.now()) - consent.utc > opts.expiryDays * DAY_MS) return null;\n  }\n  return consent;\n}\n\n/**\n * Read the visitor's consent from a request. The original spelling of {@link readConsent},\n * kept for existing callers; the second argument is the cookie name.\n */\nexport function getConsent(source: ConsentSource, cookieName: string = CONSENT_COOKIE_NAME): ServerConsent | null {\n  return readConsent(source, { cookieName });\n}\n\n/** Standard + custom consent categories. */\nexport type ConsentCategory = 'necessary' | 'preferences' | 'statistics' | 'marketing' | (string & {});\n\n/**\n * Whether a category is allowed for this visitor. `necessary` is always allowed. A missing\n * consent (`null` — visitor hasn't decided) is treated as NOT allowed for non-necessary\n * categories (fail-closed / prior-blocking posture), matching the embed.\n */\nexport function isAllowed(consent: ServerConsent | null, category: ConsentCategory): boolean {\n  if (category === 'necessary') return true;\n  if (!consent) return false;\n  // Explicit per-literal access rather than `consent[category]`: the `(string & {})` arm of\n  // ConsentCategory defeats control-flow narrowing, so a dynamic index is typed as an\n  // implicit-any index into ServerConsent (TS7053, which fails the tsup DTS build).\n  if (category === 'preferences') return consent.preferences === true;\n  if (category === 'statistics') return consent.statistics === true;\n  if (category === 'marketing') return consent.marketing === true;\n  return consent.custom?.[category] === true;\n}\n\n// ---- signatures (CMU-S04) and consent tokens (CMU-F06) ----\n\nexport const DEFAULT_JWKS_URL = 'https://api.cookiemunch.net/v1/partner/jwks.json';\n\n/** The fields of a decision its signature covers. */\nexport interface SignableDecision {\n  stamp: string;\n  ver: number;\n  utc: number;\n  preferences: boolean;\n  statistics: boolean;\n  marketing: boolean;\n  custom?: Record<string, boolean> | undefined;\n}\n\n/**\n * The exact line the API signs for a recorded decision. Identical to @cookiemunch/core's\n * `consentSignaturePayload` (a server test pins the two together).\n */\nexport function consentSignaturePayload(d: SignableDecision): string {\n  const b = (v: boolean | undefined): string => (v ? '1' : '0');\n  const custom = d.custom ?? {};\n  const named = Object.keys(custom)\n    .sort()\n    .map((k) => `${k}=${b(custom[k])}`)\n    .join(',');\n  return `cmc1|${d.stamp}|${d.ver}|${d.utc}|${b(d.preferences)}${b(d.statistics)}${b(d.marketing)}|${named}`;\n}\n\ninterface Jwk {\n  kty?: string;\n  crv?: string;\n  x?: string;\n  kid?: string;\n  alg?: string;\n}\nexport interface JsonWebKeySet {\n  keys: Jwk[];\n}\n\nconst jwksCache = new Map<string, { at: number; set: JsonWebKeySet }>();\nconst JWKS_TTL_MS = 60 * 60 * 1000;\n\nasync function keySet(opts: KeySetOptions, kid: string): Promise<JsonWebKeySet> {\n  if (opts.jwks) return opts.jwks;\n  const url = opts.jwksUrl ?? DEFAULT_JWKS_URL;\n  const hit = jwksCache.get(url);\n  // An unknown kid refetches: the key may have rotated since the cached copy.\n  if (hit && Date.now() - hit.at < JWKS_TTL_MS && hit.set.keys.some((k) => k.kid === kid)) return hit.set;\n  const f = opts.fetch ?? (globalThis as { fetch?: typeof fetch }).fetch;\n  if (!f) throw new Error('no fetch available to load the key set; pass `jwks`');\n  const res = await f(url);\n  if (!res.ok) throw new Error(`key set ${url} answered ${res.status}`);\n  const set = (await res.json()) as JsonWebKeySet;\n  if (!set || !Array.isArray(set.keys)) throw new Error(`key set ${url} is not a JWKS`);\n  jwksCache.set(url, { at: Date.now(), set });\n  return set;\n}\n\nfunction b64urlBytes(s: string): Uint8Array {\n  const b64 = s.replace(/-/g, '+').replace(/_/g, '/') + '==='.slice((s.length + 3) % 4);\n  const bin = atob(b64);\n  const out = new Uint8Array(bin.length);\n  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);\n  return out;\n}\n\n/** Ed25519 verify with WebCrypto (Node 20+, Deno, Bun, workers, browsers). */\nasync function edVerify(jwk: Jwk, data: string, signature: string): Promise<boolean> {\n  const subtle = (globalThis as { crypto?: Crypto }).crypto?.subtle;\n  if (!subtle) throw new Error('WebCrypto is unavailable in this runtime');\n  if (jwk.kty !== 'OKP' || jwk.crv !== 'Ed25519' || !jwk.x) return false;\n  const key = await subtle.importKey('jwk', { kty: 'OKP', crv: 'Ed25519', x: jwk.x }, { name: 'Ed25519' }, false, ['verify']);\n  return subtle.verify({ name: 'Ed25519' }, key, b64urlBytes(signature) as BufferSource, new TextEncoder().encode(data) as BufferSource);\n}\n\n/** Does the cookie's `sig` verify for this decision? False on anything malformed. */\nexport async function verifyDecisionSignature(consent: ServerConsent, opts: KeySetOptions = {}): Promise<boolean> {\n  const dot = consent.sig?.lastIndexOf('.') ?? -1;\n  if (!consent.sig || dot <= 0) return false;\n  const kid = consent.sig.slice(0, dot);\n  try {\n    const jwk = (await keySet(opts, kid)).keys.find((k) => k.kid === kid);\n    if (!jwk) return false;\n    return await edVerify(jwk, consentSignaturePayload(consent), consent.sig.slice(dot + 1));\n  } catch {\n    return false;\n  }\n}\n\n/** What a consent token (`CookieMunch.getConsentToken()`) asserts. */\nexport interface ConsentTokenClaims {\n  iss: string;\n  /** The decision's stamp. */\n  sub: string;\n  /** `cookiemunch:<cbid>`. */\n  aud: string;\n  token_use: 'consent';\n  cbid: string;\n  stamp: string;\n  /** Every category the decision answered, `necessary` included. */\n  choices: Record<string, boolean>;\n  ver: number;\n  /** When the decision was made, epoch ms. */\n  decidedAt: number;\n  cause?: string;\n  iat: number;\n  exp: number;\n}\n\nexport interface VerifyTokenOptions extends KeySetOptions {\n  /** Require the token to be for this site. */\n  cbid?: string;\n  /** Clock, epoch ms. Default `Date.now()`. */\n  now?: number;\n  /** Allowed clock skew, seconds. Default 30. */\n  leewaySeconds?: number;\n}\n\n/**\n * Verify a consent token from `CookieMunch.getConsentToken()` (CMU-F06) against the published\n * key set and return its claims. Throws on a bad signature, a wrong site, or an expired token.\n */\nexport async function verifyToken(token: string, opts: VerifyTokenOptions = {}): Promise<ConsentTokenClaims> {\n  const parts = typeof token === 'string' ? token.split('.') : [];\n  if (parts.length !== 3) throw new Error('not a JWT');\n  const [h, p, s] = parts as [string, string, string];\n  let header: { alg?: string; kid?: string };\n  let claims: ConsentTokenClaims;\n  try {\n    header = JSON.parse(new TextDecoder().decode(b64urlBytes(h)));\n    claims = JSON.parse(new TextDecoder().decode(b64urlBytes(p)));\n  } catch {\n    throw new Error('malformed token');\n  }\n  if (header.alg !== 'EdDSA' || !header.kid) throw new Error('unexpected token algorithm');\n  const jwk = (await keySet(opts, header.kid)).keys.find((k) => k.kid === header.kid);\n  if (!jwk || !(await edVerify(jwk, `${h}.${p}`, s))) throw new Error('bad signature');\n  if (claims.token_use !== 'consent') throw new Error('not a consent token');\n  const now = (opts.now ?? Date.now()) / 1000;\n  const leeway = opts.leewaySeconds ?? 30;\n  if (typeof claims.exp !== 'number' || now > claims.exp + leeway) throw new Error('expired');\n  if (typeof claims.iat === 'number' && claims.iat > now + leeway) throw new Error('issued in the future');\n  if (opts.cbid !== undefined && (claims.cbid !== opts.cbid || claims.aud !== `cookiemunch:${opts.cbid}`)) throw new Error('token is for another site');\n  return claims;\n}\n"],"mappings":"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","names":[]}

package/dist/consent.d.cts

@@ -36,6 +36,11 @@ interface ServerConsent {
     region: string;
     /** The anonymous consent-receipt id tying this browser to the consent log. */
     stamp: string;
+    /**
+     * `<kid>.<base64url>`: the API's Ed25519 signature over this decision, issued when the
+     * ledger recorded it. Absent on a decision no ledger holds (a hand-written cookie).
+     */
+    sig?: string;
 }
 /** The site's consent policy, so the server applies the same rules the embed does. */
 interface ReadConsentOptions {
@@ -52,6 +57,19 @@ interface ReadConsentOptions {
     /** Clock for `expiryDays`, epoch ms. Default `Date.now()`. */
     now?: number;
 }
+/** Where the platform's public signing keys come from, for signatures and consent tokens. */
+interface KeySetOptions {
+    /** A key set you already hold (`{ keys: [...] }`). Skips the fetch. */
+    jwks?: JsonWebKeySet;
+    /** Default `https://api.cookiemunch.net/v1/partner/jwks.json`. */
+    jwksUrl?: string;
+    /** Injectable fetch. Default: the global one. */
+    fetch?: typeof fetch;
+}
+/** `readConsent` with `requireSigned: true`: only a decision the API signed counts. */
+interface ReadSignedConsentOptions extends ReadConsentOptions, KeySetOptions {
+    requireSigned: true;
+}
 /** Anything we can pull a Cookie header off of. */
 type ConsentSource = string | null | undefined | {
     headers?: {
@@ -70,7 +88,10 @@ declare function parseConsentValue(raw: string): ServerConsent | null;
  * `Request`. Returns null when there is no decision the embed would honour — no cookie, an
  * unparseable one, or (with the options) one made under an older version or past expiry.
  */
-declare function readConsent(source: ConsentSource, opts?: ReadConsentOptions): ServerConsent | null;
+declare function readConsent(source: ConsentSource, opts: ReadSignedConsentOptions): Promise<ServerConsent | null>;
+declare function readConsent(source: ConsentSource, opts?: ReadConsentOptions & {
+    requireSigned?: false;
+}): ServerConsent | null;
 /**
  * Read the visitor's consent from a request. The original spelling of {@link readConsent},
  * kept for existing callers; the second argument is the cookie name.
@@ -84,5 +105,65 @@ type ConsentCategory = 'necessary' | 'preferences' | 'statistics' | 'marketing'
  * categories (fail-closed / prior-blocking posture), matching the embed.
  */
 declare function isAllowed(consent: ServerConsent | null, category: ConsentCategory): boolean;
+declare const DEFAULT_JWKS_URL = "https://api.cookiemunch.net/v1/partner/jwks.json";
+/** The fields of a decision its signature covers. */
+interface SignableDecision {
+    stamp: string;
+    ver: number;
+    utc: number;
+    preferences: boolean;
+    statistics: boolean;
+    marketing: boolean;
+    custom?: Record<string, boolean> | undefined;
+}
+/**
+ * The exact line the API signs for a recorded decision. Identical to @cookiemunch/core's
+ * `consentSignaturePayload` (a server test pins the two together).
+ */
+declare function consentSignaturePayload(d: SignableDecision): string;
+interface Jwk {
+    kty?: string;
+    crv?: string;
+    x?: string;
+    kid?: string;
+    alg?: string;
+}
+interface JsonWebKeySet {
+    keys: Jwk[];
+}
+/** Does the cookie's `sig` verify for this decision? False on anything malformed. */
+declare function verifyDecisionSignature(consent: ServerConsent, opts?: KeySetOptions): Promise<boolean>;
+/** What a consent token (`CookieMunch.getConsentToken()`) asserts. */
+interface ConsentTokenClaims {
+    iss: string;
+    /** The decision's stamp. */
+    sub: string;
+    /** `cookiemunch:<cbid>`. */
+    aud: string;
+    token_use: 'consent';
+    cbid: string;
+    stamp: string;
+    /** Every category the decision answered, `necessary` included. */
+    choices: Record<string, boolean>;
+    ver: number;
+    /** When the decision was made, epoch ms. */
+    decidedAt: number;
+    cause?: string;
+    iat: number;
+    exp: number;
+}
+interface VerifyTokenOptions extends KeySetOptions {
+    /** Require the token to be for this site. */
+    cbid?: string;
+    /** Clock, epoch ms. Default `Date.now()`. */
+    now?: number;
+    /** Allowed clock skew, seconds. Default 30. */
+    leewaySeconds?: number;
+}
+/**
+ * Verify a consent token from `CookieMunch.getConsentToken()` (CMU-F06) against the published
+ * key set and return its claims. Throws on a bad signature, a wrong site, or an expired token.
+ */
+declare function verifyToken(token: string, opts?: VerifyTokenOptions): Promise<ConsentTokenClaims>;
 
-export { CONSENT_COOKIE_NAME, type ConsentCategory, type ConsentSource, type ReadConsentOptions, type ServerConsent, getConsent, isAllowed, parseConsentValue, readConsent };
+export { CONSENT_COOKIE_NAME, type ConsentCategory, type ConsentSource, type ConsentTokenClaims, DEFAULT_JWKS_URL, type JsonWebKeySet, type KeySetOptions, type ReadConsentOptions, type ReadSignedConsentOptions, type ServerConsent, type SignableDecision, type VerifyTokenOptions, consentSignaturePayload, getConsent, isAllowed, parseConsentValue, readConsent, verifyDecisionSignature, verifyToken };