@gradial/aci 0.1.52-rc.1 → 0.1.52-rc.13

package/dist/content/resolve-slots.d.ts

@@ -1,9 +1,16 @@
 import type { LayoutEntry } from './provider.js';
 import type { KernelPageBlock } from './types.js';
-export interface FragmentData {
-    id: string;
+export interface FragmentBlock {
+    $type: 'component';
     component: string;
     props?: Record<string, unknown>;
 }
+export interface FragmentData {
+    fragmentId?: string;
+    id?: string;
+    block?: FragmentBlock;
+    component?: string;
+    props?: Record<string, unknown>;
+}
 export type FragmentLoader = (id: string) => Promise<FragmentData>;
 export declare function resolveSlots(layout: LayoutEntry, pageRegions: Record<string, KernelPageBlock[]>, getFragment: FragmentLoader): Promise<Record<string, KernelPageBlock[]>>;

package/dist/content/resolve-slots.js

@@ -11,10 +11,12 @@ export async function resolveSlots(layout, pageRegions, getFragment) {
             const blocks = [];
             for (const ref of defaults) {
                 const fragment = await getFragment(ref.fragmentId);
+                const block = fragment.block ?? { component: fragment.component ?? '', props: fragment.props };
                 blocks.push({
-                    id: fragment.id,
-                    component: fragment.component,
-                    props: fragment.props || {},
+                    $type: 'component',
+                    id: fragment.id ?? fragment.fragmentId ?? ref.fragmentId,
+                    component: block.component,
+                    props: block.props || {},
                 });
             }
             resolved[slot.name] = blocks;

package/dist/content/types.d.ts

@@ -42,11 +42,13 @@ export interface KernelPageSeo {
     canonical?: string;
 }
 export interface KernelPageBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;
 }
 export interface KernelAtomicBlock {
+    $type: 'component';
     id: string;
     component: string;
     props: Record<string, unknown>;

package/dist/edge/personalization-core.js

@@ -13,6 +13,7 @@ export function resolvePersonalizationDecision(request, route, claims, experimen
         const candidates = Object.values(experiments)
             .filter((item) => (item.kind === 'ab' || item.kind === 'abn') && item.status === 'running')
             .filter((item) => routeHasExperiment(route, item.id))
+            .filter((item) => experimentEligible(item, claims))
             .sort((left, right) => (right.priority || 0) - (left.priority || 0)
             || String(left.id || '').localeCompare(String(right.id || '')));
         for (let index = 0; index < candidates.length; index++) {
@@ -39,7 +40,8 @@ function selectRuleVariant(request, route, claims, experiments) {
         const values = variant.variantValues || variantValuesFromKey(key);
         const experimentID = String(values.experiment || '').trim();
         if (experimentID && (!experiments || !experiments[experimentID]
-            || experiments[experimentID].status !== 'running'))
+            || experiments[experimentID].status !== 'running'
+            || !experimentEligible(experiments[experimentID], claims)))
             continue;
         if (!requestDimensionsMatch(request, values))
             continue;
@@ -66,6 +68,16 @@ function variantValuesFromKey(key) {
     }
     return values;
 }
+// The eligibility gate (audience-scoped-experiments ASE-F4/F5), mirrored
+// from internal/domain/edge/personalization-core.ts: an experiment declaring
+// eligibilityAudienceId is skipped unless the verified claims carry the ID.
+// Ungated experiments return true, preserving byte-identical behavior.
+function experimentEligible(item, claims) {
+    const audienceID = String(item.eligibilityAudienceId || '').trim();
+    if (!audienceID)
+        return true;
+    return !!claims && (claims.aud || []).includes(audienceID);
+}
 function routeHasExperiment(route, experimentID) {
     for (const key in route.variants || {}) {
         const values = route.variants[key].variantValues || variantValuesFromKey(key);

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

@@ -0,0 +1,24 @@
+export interface ObjectReader {
+    readObject(path: string): Promise<Uint8Array>;
+}
+export interface ComposeObjectRef {
+    path: string;
+    digest: string;
+}
+export interface ComposeSlot {
+    name: string;
+    required: boolean;
+    placeholder: string;
+    parts: ComposeObjectRef[];
+}
+export interface ComposeEnvelope {
+    schema: 'gradial.compose-envelope.v1';
+    algorithm: 'aci-html-compose-v1';
+    shell: ComposeObjectRef;
+    slots: ComposeSlot[];
+}
+export declare function composeEnvelope(reader: ObjectReader, envelopePath: string, envelopeDigest: string): Promise<{
+    html: string;
+    contentType: string;
+}>;
+export declare function validateEnvelope(envelope: unknown): ComposeEnvelope;

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

@@ -0,0 +1,89 @@
+const decoder = new TextDecoder('utf-8', { fatal: true });
+export async function composeEnvelope(reader, envelopePath, envelopeDigest) {
+    const envelopeBytes = await reader.readObject(envelopePath);
+    await requireDigest(envelopeBytes, envelopeDigest, 'compose envelope');
+    let parsed;
+    try {
+        parsed = JSON.parse(decoder.decode(envelopeBytes));
+    }
+    catch {
+        throw new Error('compose envelope is malformed');
+    }
+    const envelope = validateEnvelope(parsed);
+    const shellBytes = await reader.readObject(envelope.shell.path);
+    await requireDigest(shellBytes, envelope.shell.digest, 'compose shell');
+    let html = decoder.decode(shellBytes);
+    for (const slot of envelope.slots) {
+        if (occurrences(html, slot.placeholder) !== 1) {
+            throw new Error(`compose slot ${JSON.stringify(slot.name)} placeholder must occur exactly once`);
+        }
+        if (slot.required && slot.parts.length === 0) {
+            throw new Error(`compose slot ${JSON.stringify(slot.name)} is required`);
+        }
+        const parts = [];
+        for (const part of slot.parts) {
+            const bytes = await reader.readObject(part.path);
+            await requireDigest(bytes, part.digest, `compose slot ${slot.name}`);
+            parts.push(decoder.decode(bytes));
+        }
+        html = html.replace(slot.placeholder, parts.join(''));
+    }
+    if (html.includes('<!--ACI_SLOT:')) {
+        throw new Error('compose shell has unresolved slots');
+    }
+    return { html, contentType: 'text/html; charset=utf-8' };
+}
+export function validateEnvelope(envelope) {
+    if (!envelope || typeof envelope !== 'object') {
+        throw new Error('compose envelope is malformed');
+    }
+    const obj = envelope;
+    if (obj.schema !== 'gradial.compose-envelope.v1'
+        || obj.algorithm !== 'aci-html-compose-v1'
+        || !Array.isArray(obj.slots)) {
+        throw new Error('compose envelope is malformed');
+    }
+    const env = envelope;
+    validateRef(env.shell);
+    const names = new Set();
+    for (const slot of env.slots) {
+        if (!slot || !/^[A-Za-z][A-Za-z0-9_-]*$/.test(slot.name) || names.has(slot.name)) {
+            throw new Error('compose slot is malformed');
+        }
+        names.add(slot.name);
+        if (slot.placeholder !== `<!--ACI_SLOT:${slot.name}-->` || !Array.isArray(slot.parts)) {
+            throw new Error(`compose slot ${JSON.stringify(slot.name)} is malformed`);
+        }
+        for (const part of slot.parts)
+            validateRef(part);
+    }
+    return env;
+}
+function validateRef(ref) {
+    const path = String(ref?.path || '');
+    if (!path || path.includes('\\') || path.split('/').some((part) => !part || part === '.' || part === '..')) {
+        throw new Error('compose object path is invalid');
+    }
+    if (!/^[0-9a-f]{64}$/.test(String(ref.digest || '').toLowerCase())) {
+        throw new Error('compose object digest is invalid');
+    }
+}
+async function requireDigest(bytes, want, label) {
+    const ab = new ArrayBuffer(bytes.byteLength);
+    new Uint8Array(ab).set(bytes);
+    const actual = Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', ab)), (byte) => byte.toString(16).padStart(2, '0')).join('');
+    if (actual !== want.toLowerCase())
+        throw new Error(`${label} digest mismatch`);
+}
+function occurrences(value, needle) {
+    let count = 0;
+    let offset = 0;
+    while (true) {
+        offset = value.indexOf(needle, offset);
+        if (offset < 0)
+            break;
+        count += 1;
+        offset += needle.length;
+    }
+    return count;
+}

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

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

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

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

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

@@ -0,0 +1,13 @@
+export interface MimicClaims {
+    scope: string;
+    siteId: string;
+    aud?: string[];
+    seg?: 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,59 @@
+// 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); the SDK
+// mirror for framework hosts is packages/sdk/src/mimic/core.ts.
+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;
+    }
+    if (claims.scope !== 'mimic')
+        return null;
+    if (typeof claims.siteId !== 'string' || claims.siteId !== siteId)
+        return null;
+    const aud = Array.isArray(claims.aud) ? claims.aud : [];
+    const seg = Array.isArray(claims.seg) ? claims.seg : [];
+    if (aud.length + seg.length === 0)
+        return null;
+    if (aud.length > MIMIC_MAX_MEMBERSHIPS || seg.length > MIMIC_MAX_MEMBERSHIPS)
+        return null;
+    const expiresAt = new Date(claims.expiresAt);
+    if (Number.isNaN(expiresAt.getTime()) || expiresAt.getTime() <= Date.now())
+        return null;
+    return { ...claims, aud, seg };
+}
+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

@@ -8,9 +8,12 @@ export declare function resolvePersonalizationDecision(request: PersonalizationR
  * @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): Classification;
+export declare function classify(ctx: PersonalizationRequestContext, data: ClassificationData, identity?: PersonalizationIdentity, claims?: PersonalizationClaims | null): Classification;
 /**
  * Phase 2: Decide the winning variant for a specific route.
  *

package/dist/internal/domain/edge/personalization-core.js

@@ -20,6 +20,7 @@ export function resolvePersonalizationDecision(request, route, claims, experimen
         const candidates = Object.values(experiments)
             .filter((item) => (item.kind === 'ab' || item.kind === 'abn') && item.status === 'running')
             .filter((item) => routeHasExperiment(route, item.id))
+            .filter((item) => experimentEligible(item, claims))
             .sort((left, right) => (right.priority || 0) - (left.priority || 0)
             || String(left.id || '').localeCompare(String(right.id || '')));
         for (let index = 0; index < candidates.length; index++) {
@@ -50,7 +51,8 @@ function selectRuleVariant(request, route, claims, experiments) {
         const values = variant.variantValues || variantValuesFromKey(key);
         const experimentID = String(values.experiment || '').trim();
         if (experimentID && (!experiments || !experiments[experimentID]
-            || experiments[experimentID].status !== 'running'))
+            || experiments[experimentID].status !== 'running'
+            || !experimentEligible(experiments[experimentID], claims)))
             continue;
         if (!requestDimensionsMatch(request, values))
             continue;
@@ -64,6 +66,16 @@ function selectRuleVariant(request, route, claims, experiments) {
         || String(left.variantKey || '').localeCompare(String(right.variantKey || '')));
     return matches[0] || null;
 }
+// The eligibility gate (audience-scoped-experiments ASE-F4/F5): an
+// experiment declaring eligibilityAudienceId is skipped entirely — before
+// bucketing or arm candidacy — unless the verified claims carry the ID.
+// Ungated experiments return true, preserving byte-identical behavior.
+function experimentEligible(item, claims) {
+    const audienceID = String(item.eligibilityAudienceId || '').trim();
+    if (!audienceID)
+        return true;
+    return !!claims && (claims.aud || []).includes(audienceID);
+}
 function routeHasExperiment(route, experimentID) {
     for (const key in route.variants || {}) {
         const values = route.variants[key].variantValues || variantValuesFromKey(key);
@@ -279,9 +291,12 @@ function utf8(value) {
  * @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 function classify(ctx, data, identity) {
+export function classify(ctx, data, identity, claims) {
     // Evaluate audience rules
     const matchedAudiences = [];
     for (const key in data.audiences) {
@@ -307,6 +322,8 @@ export function classify(ctx, data, identity) {
                 continue;
             if (exp.kind !== 'ab' && exp.kind !== 'abn')
                 continue;
+            if (!experimentEligible(exp, claims))
+                continue;
             const assignment = assignExperiment(exp, identity);
             if (assignment) {
                 experimentArms[expId] = assignment;
@@ -348,21 +365,21 @@ export function decide(record, classification, ctx) {
         if (!matched && values.segment && classification.matchedSegments.includes(values.segment)) {
             matched = true;
         }
-        // Experiment arm assignment
+        // Experiment arm assignment. The arm is a candidate only — committing it
+        // inside the win block prevents a losing arm variant from leaving a
+        // stale experiment decision behind when another variant wins.
+        let armMatch = null;
         if (!matched && experimentID) {
             const arm = classification.experimentArms[experimentID];
             if (arm && arm.variantKey === variant.variantKey) {
                 matched = true;
-                bestExperiment = arm;
+                armMatch = arm;
             }
         }
         if (matched) {
             if (!bestVariant || betterVariant(variant.priority || 0, variant.variantKey, bestVariant.priority || 0, bestVariant.variantKey)) {
                 bestVariant = variant;
-                // Only set experiment if this variant's experiment arm won
-                if (!experimentID || !classification.experimentArms[experimentID]) {
-                    bestExperiment = null;
-                }
+                bestExperiment = armMatch;
             }
         }
     }

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

@@ -10,20 +10,28 @@ export async function resolvePersonalizationRequest(request, config) {
     const cookies = parseCookieHeader(request.headers.get('cookie'));
     const consent = consentSignals(request, cookies);
     const now = (config.now ?? (() => new Date()))();
-    // Consent-gated identity model (R25): static artifact selection NEVER mints
+    // Consent-gated identity model (R25): artifact selection NEVER mints
     // identity. It reads cookies for classification but never writes them.
-    // Identity (aci_id) is minted by the collect/consent endpoint after
-    // explicit consent. This keeps all content responses cacheable and is
-    // GDPR-compliant (no non-essential cookie before consent).
+    // Identity (aci_id) is minted only after explicit consent — by the
+    // collect/consent endpoint, and by the hosting edge router / framework
+    // host on consented 200 HTML page responses (which then bypass shared
+    // caches). Unconsented content responses stay cookie-free and cacheable
+    // (no non-essential cookie before consent).
     //
     // GPC/DNT deny fully: no read, no identity, no experiment bucketing.
-    const rawIdentity = consent.privacyDenied
+    //
+    // Mimic (specs/features/audience-mimic): a validated mimicClaims input
+    // bypasses identity resolution entirely — the session reads no aci_id and
+    // no aci_claims (D-2/D-7), so identityHash stays empty and the experiment
+    // tier is structurally skipped (D-5).
+    const mimic = config.mimicClaims;
+    const rawIdentity = mimic || consent.privacyDenied
         ? null
         : await verifyIdentityCookie(cookies.get('aci_id') || '', config.identityKeys);
     // The identity hash feeds experiment bucketing for identified visitors.
     // Claims are a signed cookie written by /collect; the EdgeRouter
     // never reads the customer object store to refresh or revoke them.
-    let signedClaims = cookies.get('aci_claims') || '';
+    let signedClaims = mimic ? '' : cookies.get('aci_claims') || '';
     let identityHash = '';
     if (rawIdentity) {
         identityHash = await identityHashHex('aci_id', rawIdentity);
@@ -36,9 +44,11 @@ export async function resolvePersonalizationRequest(request, config) {
     const matchedRoute = config.route;
     let variantKey = '';
     if (matchedRoute) {
-        const claims = consent.allowsIdentityTier
-            ? await verifyClaims(signedClaims, config.claimsKeys || {}, now)
-            : null;
+        const claims = mimic
+            ? { aud: mimic.aud, seg: mimic.seg, iat: 0, exp: 0 }
+            : consent.allowsIdentityTier
+                ? await verifyClaims(signedClaims, config.claimsKeys || {}, now)
+                : null;
         const decision = resolvePersonalizationDecision(toPersonalizationRequestContext(request), matchedRoute, claims, config.experiments, identityHash
             ? { usable: true, siteId: config.siteId, namespace: 'aci_id', identityHash }
             : undefined);

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

@@ -75,6 +75,7 @@ export interface PersonalizationExperiment {
     priority?: number;
     allocationVersion?: string;
     salt?: string;
+    eligibilityAudienceId?: string;
     arms: Array<{
         id: string;
         allocationBasisPoints?: number;
@@ -169,6 +170,10 @@ export interface PersonalizationHostConfig {
     secureCookies?: boolean;
     now?: () => Date;
     randomBytes?: (length: number) => Uint8Array;
+    mimicClaims?: {
+        aud?: string[];
+        seg?: string[];
+    };
 }
 export interface PersonalizationResolution {
     variantKey: string;
@@ -178,4 +183,15 @@ export interface PersonalizationResolution {
         allocationVersion: string;
     };
 }
+export interface CompositionDescriptor {
+    layoutArtifact: string;
+    fragments?: Record<string, string>;
+}
+export type SelectedTargetKind = 'direct' | 'compose' | 'render';
+export interface SelectedTarget {
+    kind: SelectedTargetKind;
+    path: string;
+    digest: string;
+    composition?: CompositionDescriptor;
+}
 export { IdentityErasureFencedError } from '../../platform/collectionstore/errors.js';

package/dist/mimic/core.d.ts

@@ -0,0 +1,34 @@
+export interface MimicClaims {
+    scope: string;
+    siteId: string;
+    aud?: string[];
+    seg?: string[];
+    sub?: string;
+    jti?: string;
+    iat: string;
+    expiresAt: string;
+}
+export declare const MIMIC_PARAM = "aci_mimic";
+export declare const MIMIC_COOKIE = "aci_mimic";
+export declare const MIMIC_EXIT = "exit";
+export declare const MIMIC_MAX_MEMBERSHIPS = 32;
+export declare const MIMIC_MAX_TOKEN_BYTES = 2048;
+export declare function validateMimicToken(token: string, signKey: string, siteId: string): Promise<MimicClaims | null>;
+export interface MimicCookie {
+    name: string;
+    value: string;
+    options: {
+        httpOnly: boolean;
+        sameSite: 'lax';
+        maxAge: number;
+        path: string;
+        secure?: boolean;
+    };
+}
+export declare function createMimicEntryCookie(token: string, expiresAt: string, secure?: boolean): MimicCookie;
+export declare function createMimicClearCookie(secure?: boolean): MimicCookie;
+export declare function createMimicBannerHTML(claims: Pick<MimicClaims, 'aud' | 'seg'>, expiresAt: string): string;
+export declare function injectMimicBannerIntoHTML(html: string, banner: string): string;
+export declare const MIMIC_BANNER_HEADER = "x-aci-mimic-banner";
+export declare function encodeMimicBanner(claims: MimicClaims): string;
+export declare function decodeMimicBanner(encoded: string): string;

package/dist/mimic/core.js

@@ -0,0 +1,127 @@
+// View-as-audience mimic session helpers (specs/features/audience-mimic).
+// Mirror of internal/domain/hosting/runtime/mimic.ts for SDK-hosted paths
+// (Next middleware); the token validator is the twin of
+// validateMimicToken in internal/domain/hosting/runtime/edge_router.ts and
+// internal/domain/edge/routing/mimic.go, pinned by the shared vector file
+// (internal/domain/edge/routing/testdata/mimic_token_vectors.json).
+export const MIMIC_PARAM = 'aci_mimic';
+export const MIMIC_COOKIE = 'aci_mimic';
+export const MIMIC_EXIT = 'exit';
+export const MIMIC_MAX_MEMBERSHIPS = 32;
+export const MIMIC_MAX_TOKEN_BYTES = 2048;
+export async function validateMimicToken(token, signKey, siteId) {
+    try {
+        if (!token || token.length > MIMIC_MAX_TOKEN_BYTES || !signKey || !siteId)
+            return null;
+        const parts = token.split('.');
+        if (parts.length !== 3)
+            return null;
+        const signingInput = `${parts[0]}.${parts[1]}`;
+        const signature = base64URLToBytes(parts[2]);
+        const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(signKey), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const expected = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(signingInput)));
+        if (!constantTimeEqual(signature, expected))
+            return null;
+        const claims = JSON.parse(new TextDecoder().decode(base64URLToBytes(parts[1])));
+        if (claims.scope !== 'mimic')
+            return null;
+        if (typeof claims.siteId !== 'string' || claims.siteId !== siteId)
+            return null;
+        const aud = Array.isArray(claims.aud) ? claims.aud : [];
+        const seg = Array.isArray(claims.seg) ? claims.seg : [];
+        if (aud.length + seg.length === 0)
+            return null;
+        if (aud.length > MIMIC_MAX_MEMBERSHIPS || seg.length > MIMIC_MAX_MEMBERSHIPS)
+            return null;
+        const expiresAt = Date.parse(claims.expiresAt);
+        if (Number.isNaN(expiresAt) || expiresAt <= Date.now())
+            return null;
+        return { ...claims, aud, seg };
+    }
+    catch {
+        return null;
+    }
+}
+// The session cookie dies with the token so an expired session self-clears
+// back to the genuine experience (D-12).
+export function createMimicEntryCookie(token, expiresAt, secure = true) {
+    const maxAge = Math.max(1, Math.ceil((Date.parse(expiresAt) - Date.now()) / 1000));
+    return {
+        name: MIMIC_COOKIE,
+        value: token,
+        options: { httpOnly: true, sameSite: 'lax', maxAge, path: '/', secure },
+    };
+}
+export function createMimicClearCookie(secure = true) {
+    return {
+        name: MIMIC_COOKIE,
+        value: '',
+        options: { httpOnly: true, sameSite: 'lax', maxAge: 0, path: '/', secure },
+    };
+}
+// The banner is the truth signal (REQ-4): present on every mimic render,
+// absent otherwise. v1 lists raw IDs — the documented fallback (spec 04).
+export function createMimicBannerHTML(claims, expiresAt) {
+    const names = [...(claims.aud ?? []), ...(claims.seg ?? [])]
+        .map(escapeHTML)
+        .join(', ');
+    const remainingMinutes = Math.max(1, Math.ceil((Date.parse(expiresAt) - Date.now()) / 60000));
+    return `<div role="alert" style="position:fixed;top:0;left:0;right:0;z-index:9999;display:flex;align-items:center;justify-content:center;gap:12px;padding:8px 16px;background-color:#0f2e1d;color:#fff;font-size:13px;font-family:system-ui,-apple-system,sans-serif;box-shadow:0 2px 8px rgba(0,0,0,0.3);">
+  <span aria-hidden="true" style="display:inline-flex;align-items:center;justify-content:center;width:18px;height:18px;border-radius:50%;background-color:#10b981;color:#0f2e1d;font-weight:700;font-size:11px;flex-shrink:0;">M</span>
+  <span style="font-weight:500;">Viewing as audience</span>
+  <span style="font-family:monospace;opacity:0.85;font-size:12px;">${names}</span>
+  <span style="opacity:0.7;font-size:12px;">expires in ${remainingMinutes} min</span>
+  <a href="?${MIMIC_PARAM}=${MIMIC_EXIT}" style="margin-left:auto;padding:4px 12px;border-radius:6px;background-color:#dc2626;color:#fff;text-decoration:none;font-size:12px;font-weight:600;white-space:nowrap;">Exit</a>
+</div>`;
+}
+export function injectMimicBannerIntoHTML(html, banner) {
+    return html.includes('</body>') ? html.replace('</body>', `${banner}</body>`) : html + banner;
+}
+// MIMIC_BANNER_HEADER carries the base64url-encoded banner HTML from the
+// middleware to the framework render (the MimicBanner component in
+// next/page.tsx). It is a reserved header: the middleware strips any inbound
+// copy and sets it only for a validated session.
+export const MIMIC_BANNER_HEADER = 'x-aci-mimic-banner';
+export function encodeMimicBanner(claims) {
+    return bytesToBase64URL(new TextEncoder().encode(createMimicBannerHTML(claims, claims.expiresAt)));
+}
+export function decodeMimicBanner(encoded) {
+    try {
+        return new TextDecoder().decode(base64URLToBytes(encoded));
+    }
+    catch {
+        return '';
+    }
+}
+function bytesToBase64URL(bytes) {
+    let binary = '';
+    for (const byte of bytes)
+        binary += String.fromCharCode(byte);
+    return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+function base64URLToBytes(value) {
+    const base64 = value.replace(/-/g, '+').replace(/_/g, '/');
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, '=');
+    const binary = atob(padded);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+function constantTimeEqual(left, right) {
+    if (left.length !== right.length)
+        return false;
+    let diff = 0;
+    for (let i = 0; i < left.length; i++) {
+        diff |= left[i] ^ right[i];
+    }
+    return diff === 0;
+}
+function escapeHTML(value) {
+    return value
+        .replace(/&/g, '&amp;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;');
+}

package/dist/next/collect-route.d.ts

@@ -12,6 +12,12 @@ export interface PersonalizationCollectRouteConfig {
      * suppression disabled (fails safe).
      */
     claimsKeys?: Record<string, string>;
+    /**
+     * Mimic sign key (audience-mimic design/05): a validly signed, unexpired
+     * aci_mimic cookie gets the uniform 202 with nothing stored and no claims
+     * rotation. An invalid cookie is ignored. Absent = no suppression.
+     */
+    mimicSignKey?: string;
     retentionSeconds?: number;
     secureCookies?: boolean;
     now?: () => Date;