@gradial/aci 0.1.52-rc.21 → 0.1.52-rc.24

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

@@ -59,6 +59,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,11 +141,17 @@ 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('');
+    return bytesToHex(new Uint8Array(digest));
+}
+function bytesToHex(bytes) {
+    let value = '';
+    for (const byte of bytes)
+        value += byte.toString(16).padStart(2, '0');
+    return value;
 }
 // ── Claims cookie (aci_claims) ──
 export async function verifyClaims(value, keys, now) {
@@ -139,7 +159,9 @@ export async function verifyClaims(value, keys, now) {
     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 {
@@ -164,26 +186,40 @@ export function expireCookie(name, secure) {
     return { name, value: '', options: { path: '/', httpOnly: true, secure, sameSite: 'lax', maxAge: 0, expires: new Date(0) } };
 }
 // ── 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));
-    }
-    catch {
+// 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/mimic_token.d.ts

@@ -3,6 +3,7 @@ export interface MimicClaims {
     siteId: string;
     aud?: string[];
     seg?: string[];
+    arms?: Record<string, string>;
     sub?: string;
     jti?: string;
     iat: string;

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

@@ -31,20 +31,87 @@ export async function validateMimicToken(token, signingKey, siteId) {
     catch {
         return null;
     }
-    if (claims.scope !== 'mimic')
+    // 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;
-    if (typeof claims.siteId !== 'string' || claims.siteId !== siteId)
+    const raw = claims;
+    if (raw.scope !== 'mimic')
         return null;
-    const aud = Array.isArray(claims.aud) ? claims.aud : [];
-    const seg = Array.isArray(claims.seg) ? claims.seg : [];
-    if (aud.length + seg.length === 0)
+    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(claims.expiresAt);
+    const expiresAt = new Date(raw.expiresAt);
     if (Number.isNaN(expiresAt.getTime()) || expiresAt.getTime() <= Date.now())
         return null;
-    return { ...claims, aud, seg };
+    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, '/')

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

@@ -1,5 +1,11 @@
-import type { PersonalizationRequestContext, PersonalizationClaims, PersonalizationRoute, PersonalizationExperiment, PersonalizationIdentity, PersonalizationDecision, ClassificationData, Classification, EdgeRouteEntry } from './types.js';
-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;
@@ -46,37 +52,6 @@ export declare function evaluateRequestExpression(rule: {
 export declare const EXPRESSION_OPERATORS: string[];
 export declare const EXPRESSION_NUMBER_GRAMMAR: RegExp;
 export declare const EXPRESSION_TIMESTAMP_GRAMMAR: RegExp;
-/**
- * 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.
- * @param claims  The verified claims the caller already holds (eligibility
- *                gate input, ASE-F4). Undefined/null means "no claims" —
- *                gated experiments are skipped.
- * @returns Classification — matched audiences, segments, and experiment arm assignments
- */
-export declare function classify(ctx: PersonalizationRequestContext, data: ClassificationData, identity?: PersonalizationIdentity, claims?: PersonalizationClaims | null): Classification;
-/**
- * Phase 2: Decide the winning variant for a specific route.
- *
- * Uses the classification from Phase 1 for cheap set-membership lookups.
- * Audience/segment rules were already evaluated in Phase 1; the one rule
- * evaluated here is an experiment arm variant's own rule, because the arm
- * assignment is candidacy, not entitlement (ADR 0040).
- *
- * @param record        The route entry (path, dispatch, variants)
- * @param classification The visitor's classification from Phase 1
- * @param ctx           The request context (signal facts + rejection sink)
- * @param claims        The verified claims the caller already holds — the
- *                      same object passed to classify() — so an arm variant's
- *                      audience.memberships rule resolves identically to the
- *                      resolver path and fails closed without it (ADR 0039).
- * @returns The decision — winning variant + experiment assignment, or nulls
- */
-export declare function decide(record: EdgeRouteEntry, classification: Classification, ctx: PersonalizationRequestContext, claims?: PersonalizationClaims | null): PersonalizationDecision;
 export declare const DEVICE_CLASSES: string[];
 /**
  * Classifies the request's device class from its own headers. Returns '' when