@gradial/aci 0.1.52-rc.9 → 0.1.52

package/dist/internal/domain/edge/identity.js

@@ -5,10 +5,9 @@
 // - Consent signal extraction (GPC/DNT + portable consent envelope)
 // - Identity cookie verification and minting (aci_id)
 // - Claims cookie verification (aci_claims)
-// - Cookie mutation helpers
 //
 // Shared by every static edge adapter; this logic has no SDK host wrapper.
-// internal/domain/audience/runtime/identity.ts imports from here as well.
+// internal/domain/audience/runtime/collect.ts imports from here as well.
 const encoder = new TextEncoder();
 const decoder = new TextDecoder();
 // ── Constants ──
@@ -59,6 +58,20 @@ export function consentSignals(request, cookies) {
         privacyDenied,
     };
 }
+// identityIssuancePermitted is the one rule for issuing a first-party identity
+// on a request that carries none (ADR 0048). Privacy signals deny outright. A
+// recorded consent choice — any envelope, even a malformed one — decides by
+// itself, so an explicit denial holds in an opt-out country. Only a visitor
+// with no recorded choice falls back to the release's opt-out countries, and
+// an unknown country is never one of them. Personalization uses of the
+// identity (claims, memberships, provider bootstrap) stay gated on the grant.
+export function identityIssuancePermitted(consent, country, optOutCountries) {
+    if (consent.privacyDenied)
+        return false;
+    if (consent.hasConsent || consent.consentInvalid)
+        return consent.allowsIdentityTier;
+    return country !== '' && optOutCountries.includes(country);
+}
 export function parseConsent(raw, decodeCookieValue = true) {
     let decoded = trimConsentWhitespace(raw);
     if (!decoded)
@@ -127,19 +140,46 @@ export function randomIdentity(random) {
 }
 export async function identityHashHex(namespace, value) {
     const digest = await crypto.subtle.digest('SHA-256', encoder.encode(`${namespace.trim().toLowerCase()}\x00${value.trim()}`));
-    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    return bytesToHex(new Uint8Array(digest));
 }
-export async function sha256Hex(value) {
-    const digest = await crypto.subtle.digest('SHA-256', encoder.encode(value));
-    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+function bytesToHex(bytes) {
+    let value = '';
+    for (const byte of bytes)
+        value += byte.toString(16).padStart(2, '0');
+    return value;
 }
 // ── Claims cookie (aci_claims) ──
+// verifyClaims is the PERSONALIZATION grade: signature, expiry, and the
+// ADR 0059 §6 issuer-marker gate — a claim without a fresh marker is never
+// trusted for membership selection. Existing signed cookies expire by their
+// own TTL; their old contents are not read during the transition.
 export async function verifyClaims(value, keys, now) {
+    const payload = await verifyClaimsAuthenticity(value, keys, now);
+    if (payload === null || claimsIssuer(payload) === undefined)
+        return null;
+    return payload;
+}
+// verifyClaimsEvidence is the EVIDENCE grade (anonymous-experiments REQ-6):
+// signature and expiry WITHOUT the issuer gate. The collector's
+// withdrawal/suppression trigger only needs proof that identity-tier state
+// existed — an authentically signed, unexpired pre-cutover (unmarked) cookie
+// is exactly that proof, and the Go collector accepts it the same way (Go
+// ClaimsVerifier.VerifyClaims has no marker gate). Evidence never feeds
+// membership selection, so the §6 gate does not apply here.
+export async function verifyClaimsEvidence(value, keys, now) {
+    return verifyClaimsAuthenticity(value, keys, now);
+}
+// verifyClaimsAuthenticity is the shared core: envelope, keyed signature,
+// and expiry — no policy gate. Every structural failure degrades to null
+// (never an error), matching Go's no-oracle posture.
+async function verifyClaimsAuthenticity(value, keys, now) {
     const parts = value.trim().split('.');
     if (parts.length !== 4 || parts[0] !== 'v1')
         return null;
     const [, kid, body, signature] = parts;
-    const secret = keys[kid];
+    // The kid is viewer-controlled: select only an owned key, never an inherited
+    // Object.prototype member such as `__proto__` or `constructor`.
+    const secret = Object.hasOwn(keys, kid) ? keys[kid] : undefined;
     if (!secret || !await verifyHMAC(`v1.${kid}.${body}`, signature, secret))
         return null;
     try {
@@ -152,38 +192,102 @@ export async function verifyClaims(value, keys, now) {
         return null;
     }
 }
-// ── Cookie mutation helpers ──
-export function cookieMutation(name, value, maxAge, now, secure, httpOnly) {
-    return {
-        name,
-        value,
-        options: { path: '/', httpOnly, secure, sameSite: 'lax', maxAge, expires: new Date(now.getTime() + maxAge * 1000) },
-    };
+/**
+ * Exposes the payload's `iss` marker. Malformed/unknown markers — and
+ * pre-0059 unmarked payloads — yield undefined; since the §6 cutover,
+ * verifyClaims rejects those payloads outright, so a verified payload always
+ * carries a marker. The marker identifies the minting path; it does not
+ * grant membership by itself.
+ */
+export function claimsIssuer(payload) {
+    const iss = payload?.iss;
+    return iss === 'aci' || iss === 'edge' ? iss : undefined;
 }
-export function expireCookie(name, secure) {
-    return { name, value: '', options: { path: '/', httpOnly: true, secure, sameSite: 'lax', maxAge: 0, expires: new Date(0) } };
+/** audience.MaxClaimsCookieBytes — the hard 1 KiB aci_claims budget. */
+export const MAX_CLAIMS_COOKIE_BYTES = 1024;
+/** audience.DefaultClaimsTTL — the 24-hour signed-lifetime ceiling. */
+export const DEFAULT_CLAIMS_TTL_SECONDS = 24 * 60 * 60;
+/**
+ * Mint rejection: oversize, a malformed key, or a missing issuer marker.
+ * Callers fail closed on it — the edge never truncates or subsets
+ * memberships to fit (ADR 0059 §2/§3).
+ */
+export class ClaimsMintError extends Error {
+    name = 'ClaimsMintError';
 }
-// ── Internal crypto helpers ──
-async function verifyHMAC(value, signature, secret) {
-    try {
-        const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
-        return await crypto.subtle.verify('HMAC', key, base64URLDecode(signature), encoder.encode(value));
+/**
+ * Mints one signed aci_claims value: v1.{kid}.{base64url(payload)}.{hmac},
+ * byte-identical to Go's ClaimsIssuer.IssueClaims — payload field order is
+ * aud (omitted when empty), seg (omitted when empty), iat, exp, iss, and the
+ * TTL clamps to the 24-hour ceiling. The exact bytes are pinned against the
+ * Go golden in claims_contract.test.ts. Issuance requires an explicit issuer
+ * marker; the marker identifies the minting path, it does not grant
+ * membership by itself.
+ */
+export async function issueClaims(memberships, issuer, key, now, ttlSeconds) {
+    const kid = key.kid.trim();
+    if (!key.secret)
+        throw new ClaimsMintError('claims issuer requires a secret');
+    if (!kid)
+        throw new ClaimsMintError('claims issuer requires a kid');
+    if (kid.includes('.'))
+        throw new ClaimsMintError("claims kid must not contain '.'");
+    if (issuer !== 'aci' && issuer !== 'edge') {
+        throw new ClaimsMintError('claims issuer requires an explicit issuer marker');
     }
-    catch {
-        return false;
+    const ttl = ttlSeconds === undefined || ttlSeconds <= 0 || ttlSeconds > DEFAULT_CLAIMS_TTL_SECONDS
+        ? DEFAULT_CLAIMS_TTL_SECONDS
+        : Math.floor(ttlSeconds);
+    const iat = Math.floor(now.getTime() / 1000);
+    const body = JSON.stringify({
+        ...(memberships.aud?.length ? { aud: memberships.aud } : {}),
+        ...(memberships.seg?.length ? { seg: memberships.seg } : {}),
+        iat,
+        exp: iat + ttl,
+        iss: issuer,
+    });
+    const encoded = base64URLEncode(encoder.encode(body));
+    const value = `v1.${kid}.${encoded}.${await hmacSHA256(`v1.${kid}.${encoded}`, key.secret)}`;
+    if (encoder.encode(value).byteLength > MAX_CLAIMS_COOKIE_BYTES) {
+        throw new ClaimsMintError(`claims cookie exceeds the ${MAX_CLAIMS_COOKIE_BYTES}-byte budget (aud=${memberships.aud?.length ?? 0} seg=${memberships.seg?.length ?? 0})`);
     }
+    return value;
+}
+// ── Internal crypto helpers ──
+// verifyHMAC returns a verdict about the signature, which is the only visitor
+// input here: a malformed or wrong signature is `false`. A fault importing the
+// key or computing the MAC — an empty or misconfigured secret, a WebCrypto
+// failure — is not a verdict and propagates to the caller's documented failure
+// boundary (hosting D-14's logged private 503, the collect handler's observed
+// 500). Folding it into `false` would silently read every visitor as
+// unidentified.
+export async function verifyHMAC(value, signature, secret) {
+    const signatureBytes = decodeSignature(signature);
+    if (!signatureBytes)
+        return false;
+    const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    return await crypto.subtle.verify('HMAC', key, signatureBytes, encoder.encode(value));
+}
+// Signatures are unpadded base64url, the only encoding the Go signers emit. A
+// value outside that grammar (or of a length no base64 string can have) is
+// malformed input; within it, decoding cannot fail.
+const BASE64URL_SIGNATURE = /^[A-Za-z0-9_-]+$/;
+function decodeSignature(signature) {
+    if (!BASE64URL_SIGNATURE.test(signature) || signature.length % 4 === 1)
+        return null;
+    return base64URLDecode(signature);
 }
-async function hmacSHA256(value, secret) {
+export async function hmacSHA256(value, secret) {
     const key = await crypto.subtle.importKey('raw', encoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
     return base64URLEncode(new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(value))));
 }
-function base64URLEncode(bytes) {
+export function base64URLEncode(bytes) {
     let binary = '';
     for (const byte of bytes)
         binary += String.fromCharCode(byte);
     return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-function base64URLDecode(value) {
+export function base64URLDecode(value) {
     const padded = value.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - value.length % 4) % 4);
     const binary = atob(padded);
     const bytes = new Uint8Array(binary.length);

package/dist/internal/domain/edge/index.d.ts

@@ -1,5 +1,5 @@
 export * from './types.js';
 export * from './personalization-core.js';
 export * from './identity.js';
-export * from './compose.js';
+export * from './mimic_token.js';
 export { resolvePersonalizationRequest, } from './resolve.js';

package/dist/internal/domain/edge/index.js

@@ -3,5 +3,5 @@
 export * from './types.js';
 export * from './personalization-core.js';
 export * from './identity.js';
-export * from './compose.js';
+export * from './mimic_token.js';
 export { resolvePersonalizationRequest, } from './resolve.js';

package/dist/internal/domain/edge/mimic_token.d.ts

@@ -0,0 +1,14 @@
+export interface MimicClaims {
+    scope: string;
+    siteId: string;
+    aud?: string[];
+    seg?: string[];
+    arms?: Record<string, string>;
+    sub?: string;
+    jti?: string;
+    iat: string;
+    expiresAt: string;
+}
+export declare const MIMIC_MAX_MEMBERSHIPS = 32;
+export declare const MIMIC_MAX_TOKEN_BYTES = 2048;
+export declare function validateMimicToken(token: string, signingKey: string, siteId: string): Promise<MimicClaims | null>;

package/dist/internal/domain/edge/mimic_token.js

@@ -0,0 +1,125 @@
+// Mimic token validation for the edge runtime (specs/features/audience-mimic).
+//
+// Same HS256 envelope and signing key as preview; the scope claim makes the
+// tokens non-interchangeable (D-6). This validator is the twin of
+// internal/domain/edge/routing/mimic.go, pinned by the shared vector file
+// (internal/domain/edge/routing/testdata/mimic_token_vectors.json).
+export const MIMIC_MAX_MEMBERSHIPS = 32;
+export const MIMIC_MAX_TOKEN_BYTES = 2048;
+export async function validateMimicToken(token, signingKey, siteId) {
+    if (!token || token.length > MIMIC_MAX_TOKEN_BYTES || !signingKey || !siteId)
+        return null;
+    const parts = token.split('.');
+    if (parts.length !== 3)
+        return null;
+    const signingInput = parts[0] + '.' + parts[1];
+    let signatureBytes;
+    try {
+        signatureBytes = base64URLDecode(parts[2]);
+    }
+    catch {
+        return null;
+    }
+    const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(signingKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+    const valid = await crypto.subtle.verify('HMAC', key, signatureBytes, new TextEncoder().encode(signingInput));
+    if (!valid)
+        return null;
+    let claims;
+    try {
+        claims = JSON.parse(new TextDecoder().decode(base64URLDecode(parts[1])));
+    }
+    catch {
+        return null;
+    }
+    // Explicit shape validation (edge-functions I-17): the Go twin rejects a
+    // wrong-typed present field at json.Unmarshal, so this validator must
+    // reject the same tokens rather than tolerating-and-defaulting them.
+    // Absent optional fields stay absent — addition stays compatible,
+    // corruption does not (design/09 claims delta).
+    if (typeof claims !== 'object' || claims === null || Array.isArray(claims))
+        return null;
+    const raw = claims;
+    if (raw.scope !== 'mimic')
+        return null;
+    if (typeof raw.siteId !== 'string' || raw.siteId !== siteId)
+        return null;
+    const aud = shapeStringList(raw.aud);
+    const seg = shapeStringList(raw.seg);
+    const arms = shapeStringMap(raw.arms);
+    if (aud === null || seg === null || arms === null)
+        return null;
+    if (raw.sub !== undefined && typeof raw.sub !== 'string')
+        return null;
+    if (raw.jti !== undefined && typeof raw.jti !== 'string')
+        return null;
+    if (typeof raw.iat !== 'string' || Number.isNaN(new Date(raw.iat).getTime()))
+        return null;
+    if (typeof raw.expiresAt !== 'string')
+        return null;
+    // Amended validity rule (03, design/09): at least one entry across aud,
+    // seg, and arms — an arms-only token is valid; empty memberships are a
+    // real visitor state.
+    if (aud.length + seg.length + Object.keys(arms).length === 0)
+        return null;
+    if (aud.length > MIMIC_MAX_MEMBERSHIPS || seg.length > MIMIC_MAX_MEMBERSHIPS)
+        return null;
+    const expiresAt = new Date(raw.expiresAt);
+    if (Number.isNaN(expiresAt.getTime()) || expiresAt.getTime() <= Date.now())
+        return null;
+    const validated = {
+        scope: 'mimic',
+        siteId: raw.siteId,
+        iat: raw.iat,
+        expiresAt: raw.expiresAt,
+    };
+    if (aud.length > 0)
+        validated.aud = aud;
+    if (seg.length > 0)
+        validated.seg = seg;
+    if (Object.keys(arms).length > 0)
+        validated.arms = arms;
+    if (raw.sub !== undefined)
+        validated.sub = raw.sub;
+    if (raw.jti !== undefined)
+        validated.jti = raw.jti;
+    return validated;
+}
+// shapeStringList admits an absent field or a list of strings; anything else
+// (a scalar, a list with non-string members) is the malformed shape Go's
+// json.Unmarshal rejects.
+function shapeStringList(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return null;
+    for (const member of value) {
+        if (typeof member !== 'string')
+            return null;
+    }
+    return value;
+}
+// shapeStringMap is the arms-field twin of shapeStringList: an absent field
+// or a string→string map; a scalar, array, or non-string value is malformed.
+function shapeStringMap(value) {
+    if (value === undefined)
+        return {};
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return null;
+    const out = {};
+    for (const [key, member] of Object.entries(value)) {
+        if (typeof member !== 'string')
+            return null;
+        out[key] = member;
+    }
+    return out;
+}
+function base64URLDecode(value) {
+    const padded = value.replace(/-/g, '+').replace(/_/g, '/')
+        + '='.repeat((4 - value.length % 4) % 4);
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let index = 0; index < binary.length; index += 1) {
+        bytes[index] = binary.charCodeAt(index);
+    }
+    return bytes;
+}

package/dist/internal/domain/edge/personalization-core.d.ts

@@ -1,24 +1,63 @@
-import type { PersonalizationRequestContext, PersonalizationClaims, PersonalizationVariant, PersonalizationRoute, PersonalizationExperiment, PersonalizationIdentity, PersonalizationDecision, ClassificationData, Classification, EdgeRouteEntry } from './types.js';
-export declare function selectPersonalizationVariant(request: PersonalizationRequestContext, route: PersonalizationRoute | null, claims: PersonalizationClaims | null, experiments?: Record<string, PersonalizationExperiment>, identity?: PersonalizationIdentity): PersonalizationVariant | null;
-export declare function resolvePersonalizationDecision(request: PersonalizationRequestContext, route: PersonalizationRoute | null, claims: PersonalizationClaims | null, experiments?: Record<string, PersonalizationExperiment>, identity?: PersonalizationIdentity): PersonalizationDecision;
+import type { PersonalizationRequestContext, PersonalizationClaims, PersonalizationRoute, PersonalizationExperiment, PersonalizationIdentity, PersonalizationDecision } from './types.js';
+export { preparePersonalizationRoute } from './personalization_index.js';
+export declare class PersonalizationResolutionError extends Error {
+    readonly variantKey: string;
+    readonly code = "personalization.tuple_missing";
+    constructor(variantKey: string);
+}
+export declare function resolvePersonalizationDecision(request: PersonalizationRequestContext, route: PersonalizationRoute | null, claims: PersonalizationClaims | null, experiments?: Record<string, PersonalizationExperiment>, identity?: PersonalizationIdentity, forcedArms?: Record<string, string>): PersonalizationDecision;
+export type ExpressionFactStatus = 'present' | 'absent' | 'unavailable';
+export interface ExpressionFact {
+    status: ExpressionFactStatus;
+    values?: string[];
+}
+export interface ExpressionDiagnostic {
+    code: string;
+    path: string;
+    scope: 'request';
+    message: string;
+}
+export interface ExpressionLeafTrace {
+    path: string;
+    group: 'all' | 'any';
+    index: number;
+    field: string;
+    operator: string;
+    status: ExpressionFactStatus;
+    matched: boolean;
+    reason: 'matched' | 'not_matched' | 'absent' | 'unavailable';
+}
+export interface ExpressionGroupTrace {
+    path: string;
+    group: 'all' | 'any';
+    total: number;
+    matched: number;
+    passed: boolean;
+}
+export interface RequestExpressionResult {
+    qualified: boolean;
+    diagnostics: ExpressionDiagnostic[];
+    trace: {
+        scope: 'request';
+        empty: boolean;
+        groups: ExpressionGroupTrace[];
+        leaves: ExpressionLeafTrace[];
+    };
+}
+/** Evaluate one request expression and produce the same redacted trace used for qualification. */
+export declare function evaluateRequestExpression(rule: {
+    all?: unknown[];
+    any?: unknown[];
+}, resolve: (field: string) => ExpressionFact): RequestExpressionResult;
+export declare const EXPRESSION_OPERATORS: string[];
+export declare const EXPRESSION_NUMBER_GRAMMAR: RegExp;
+export declare const EXPRESSION_TIMESTAMP_GRAMMAR: RegExp;
+export declare const DEVICE_CLASSES: string[];
 /**
- * Phase 1: Classify the visitor against all release-level rules.
- *
- * @param ctx     The request context (cookies, headers, geo, query)
- * @param data    Release-level classification data (audiences, segments, experiments)
- * @param identity Visitor identity (for experiment bucketing). Pass undefined
- *                 if no identity or privacy denied.
- * @returns Classification — matched audiences, segments, and experiment arm assignments
+ * Classifies the request's device class from its own headers. Returns '' when
+ * the request carried neither User-Agent nor Sec-CH-UA-Mobile, which the fact
+ * resolver reports as ABSENT — the same status the missing header itself
+ * resolves to, and deliberately distinct from the 'unknown' class, which means
+ * classified and unrecognized.
  */
-export declare function classify(ctx: PersonalizationRequestContext, data: ClassificationData, identity?: PersonalizationIdentity): Classification;
-/**
- * Phase 2: Decide the winning variant for a specific route.
- *
- * Uses the classification from Phase 1 for cheap set-membership lookups.
- * No rule evaluation — just set membership and priority comparison.
- *
- * @param record        The route entry (path, dispatch, variants)
- * @param classification The visitor's classification from Phase 1
- * @returns The decision — winning variant + experiment assignment, or nulls
- */
-export declare function decide(record: EdgeRouteEntry, classification: Classification, ctx: PersonalizationRequestContext): PersonalizationDecision;
+export declare function deviceClassFromHeaders(headers: Record<string, string>): string;