@cookiemunch/sdk 0.5.1 → 0.7.0

package/dist/consent.d.ts

@@ -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 };

package/dist/consent.js

@@ -1,15 +1,23 @@
 import {
   CONSENT_COOKIE_NAME,
+  DEFAULT_JWKS_URL,
+  consentSignaturePayload,
   getConsent,
   isAllowed,
   parseConsentValue,
-  readConsent
-} from "./chunk-G7ORTXTK.js";
+  readConsent,
+  verifyDecisionSignature,
+  verifyToken
+} from "./chunk-OSVTQPQG.js";
 export {
   CONSENT_COOKIE_NAME,
+  DEFAULT_JWKS_URL,
+  consentSignaturePayload,
   getConsent,
   isAllowed,
   parseConsentValue,
-  readConsent
+  readConsent,
+  verifyDecisionSignature,
+  verifyToken
 };
 //# sourceMappingURL=consent.js.map