@gradial/aci 0.1.41 → 0.1.42

package/dist/next/personalization-host.d.ts

@@ -0,0 +1,118 @@
+import { type PersonalizationExperiment } from '../edge/personalization-core.js';
+export declare const CONTENT_PATH_HEADER = "x-aci-content-path";
+export declare const CONTENT_PATH_CACHE_PARAM = "__aci_content_path";
+export interface EdgeDispatch {
+    kind: 'static-direct' | 'compose-origin' | 'framework-origin' | string;
+    artifactPath?: string;
+    contentPath?: string;
+}
+export interface EdgeRuleCondition {
+    field: string;
+    operator: 'exists' | 'equals' | 'contains' | 'startsWith' | string;
+    value?: unknown;
+}
+export interface EdgeRuleExpression {
+    all?: EdgeRuleCondition[];
+    any?: EdgeRuleCondition[];
+}
+export interface EdgeRouteVariant {
+    variantKey: string;
+    variantValues?: Record<string, string>;
+    priority?: number;
+    rule?: EdgeRuleExpression;
+    dispatch: EdgeDispatch;
+}
+export interface EdgeRouteEntry {
+    pattern: string;
+    priority: number;
+    dispatch: EdgeDispatch;
+    variants?: Record<string, EdgeRouteVariant>;
+}
+export interface EdgeRouteManifest {
+    manifestVersion: string;
+    releaseId: string;
+    siteId: string;
+    routes: Record<string, EdgeRouteEntry>;
+    experiments?: Record<string, PersonalizationExperiment>;
+    notFoundPage?: string;
+    errorPage?: string;
+}
+/** Immutable release routing state read by an EdgeRouter. */
+export interface PersonalizationRouteStore {
+    readEdgeManifest(releaseId: string): Promise<EdgeRouteManifest | null>;
+}
+/** Customer-owned collection state. This is deliberately not an EdgeRouter dependency. */
+export interface PersonalizationCollectionStore {
+    readClaims(siteId: string, namespace: string, identityHash: string): Promise<string | null>;
+    appendEvent(key: string, record: unknown): Promise<void>;
+    putSuppression(key: string, record: unknown): Promise<void>;
+}
+/** @deprecated Use the narrower router or collection store at each boundary. */
+export interface PersonalizationBlobStore extends PersonalizationRouteStore, PersonalizationCollectionStore {
+}
+export interface SigningKey {
+    kid: string;
+    secret: string;
+}
+export interface IdentitySigningKeys {
+    current: SigningKey;
+    previous?: SigningKey;
+}
+export interface PersonalizationHostConfig {
+    siteId: string;
+    store: PersonalizationRouteStore;
+    identityKeys: IdentitySigningKeys;
+    claimsKeys?: Record<string, string>;
+    identityCookieTTLSeconds?: number;
+    secureCookies?: boolean;
+    now?: () => Date;
+    randomBytes?: (length: number) => Uint8Array;
+}
+export interface CookieMutation {
+    name: string;
+    value: string;
+    options: {
+        path: '/';
+        httpOnly?: boolean;
+        secure?: boolean;
+        sameSite: 'lax';
+        maxAge: number;
+        expires?: Date;
+    };
+}
+export interface PersonalizationResolution {
+    requestHeaders: Headers;
+    contentPath: string;
+    variantKey: string;
+    experiment?: {
+        id: string;
+        arm: string;
+        allocationVersion: string;
+    };
+    cookies: CookieMutation[];
+}
+export interface ConsentSnapshot {
+    version: number;
+    purposes: string[];
+    grantedAt: string;
+    source?: string;
+}
+interface ClaimsPayload {
+    aud?: string[];
+    seg?: string[];
+    iat: number;
+    exp: number;
+}
+export declare function resolvePersonalizationRequest(request: Request, releaseId: string, config: PersonalizationHostConfig): Promise<PersonalizationResolution>;
+export declare function consentSignals(request: Request, cookies: Map<string, string>): {
+    hasConsent: boolean;
+    snapshot: ConsentSnapshot | null;
+    allowsIdentityTier: boolean;
+    privacyDenied: boolean;
+};
+export declare function parseCookieHeader(value: string | null): Map<string, string>;
+export declare function verifyIdentityCookie(value: string, keys: IdentitySigningKeys): Promise<string | null>;
+export declare function sha256Hex(value: string): Promise<string>;
+export declare function identityHashHex(namespace: string, value: string): Promise<string>;
+export declare function verifyClaims(value: string, keys: Record<string, string>, now: Date): Promise<ClaimsPayload | null>;
+export {};

package/dist/next/personalization-host.js

@@ -0,0 +1,276 @@
+import { resolvePersonalizationDecision, } from '../edge/personalization-core.js';
+const DEFAULT_IDENTITY_TTL_SECONDS = 90 * 24 * 60 * 60;
+const DEFAULT_CLAIMS_TTL_SECONDS = 24 * 60 * 60;
+const textEncoder = new TextEncoder();
+export const CONTENT_PATH_HEADER = 'x-aci-content-path';
+export const CONTENT_PATH_CACHE_PARAM = '__aci_content_path';
+export async function resolvePersonalizationRequest(request, releaseId, config) {
+    const requestHeaders = new Headers(request.headers);
+    const cookies = parseCookieHeader(request.headers.get('cookie'));
+    const consent = consentSignals(request, cookies);
+    const mutations = [];
+    const now = (config.now ?? (() => new Date()))();
+    const secure = config.secureCookies ?? new URL(request.url).protocol === 'https:';
+    // Universal minting (spec anonymous-experiments REQ-1 / ADR 0016):
+    // identity existence is privacy-signal gated, never consent gated.
+    // GPC/DNT deny FULLY — no mint, no resolve, even with a valid cookie or a
+    // stored granting envelope (D-2). An unverifiable cookie self-heals by
+    // re-minting (REQ-4). aci_m is issue-only (D-11): a resolve-path refresh
+    // would put a Set-Cookie on every returning visitor's response, defeating
+    // the any-Set-Cookie => private, no-store cache rule.
+    let rawIdentity = consent.privacyDenied
+        ? null
+        : await verifyIdentityCookie(cookies.get('aci_id') || '', config.identityKeys);
+    if (!consent.privacyDenied && !rawIdentity) {
+        rawIdentity = randomIdentity(config.randomBytes);
+        const signed = await signIdentity(rawIdentity, config.identityKeys.current);
+        const maxAge = config.identityCookieTTLSeconds ?? DEFAULT_IDENTITY_TTL_SECONDS;
+        mutations.push(cookieMutation('aci_id', signed, maxAge, now, secure, true));
+        mutations.push(cookieMutation('aci_m', '1', maxAge, now, secure, false));
+    }
+    // The identity hash feeds experiment bucketing for EVERY identified
+    // visitor. 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 identityHash = '';
+    if (rawIdentity) {
+        identityHash = await identityHashHex('aci_id', rawIdentity);
+    }
+    if (rawIdentity && consent.allowsIdentityTier && signedClaims) {
+        if (!await verifyClaims(signedClaims, config.claimsKeys || {}, now)) {
+            signedClaims = '';
+        }
+    }
+    if ((!consent.allowsIdentityTier || !rawIdentity || !signedClaims) && cookies.has('aci_claims')) {
+        mutations.push(expireCookie('aci_claims', secure));
+    }
+    const manifest = await config.store.readEdgeManifest(releaseId);
+    const route = manifest ? matchRoute(new URL(request.url).pathname, manifest) : null;
+    let contentPath = route?.dispatch.contentPath || '';
+    let variantKey = '';
+    if (route) {
+        const claims = consent.allowsIdentityTier
+            ? await verifyClaims(signedClaims, config.claimsKeys || {}, now)
+            : null;
+        const decision = resolvePersonalizationDecision(toPersonalizationRequestContext(request), route, claims, manifest?.experiments, identityHash
+            ? { usable: true, siteId: config.siteId, namespace: 'aci_id', identityHash }
+            : undefined);
+        if (decision.variant) {
+            variantKey = decision.variant.variantKey;
+            contentPath = decision.variant.dispatch.contentPath || contentPath;
+        }
+        if (decision.experiment) {
+            requestHeaders.set('X-ACI-Experiment-ID', decision.experiment.experimentId);
+            requestHeaders.set('X-ACI-Experiment-Arm', decision.experiment.armId);
+            requestHeaders.set('X-ACI-Experiment-Allocation-Version', decision.experiment.allocationVersion);
+        }
+        const experiment = decision.experiment
+            ? { id: decision.experiment.experimentId, arm: decision.experiment.armId, allocationVersion: decision.experiment.allocationVersion }
+            : undefined;
+        if (contentPath)
+            requestHeaders.set(CONTENT_PATH_HEADER, contentPath);
+        if (variantKey)
+            requestHeaders.set('x-aci-variant-key', variantKey);
+        return { requestHeaders, contentPath, variantKey, experiment, cookies: mutations };
+    }
+    if (contentPath) {
+        requestHeaders.set(CONTENT_PATH_HEADER, contentPath);
+    }
+    if (variantKey) {
+        requestHeaders.set('x-aci-variant-key', variantKey);
+    }
+    return { requestHeaders, contentPath, variantKey, cookies: mutations };
+}
+export function consentSignals(request, cookies) {
+    const privacyDenied = request.headers.get('sec-gpc')?.trim() === '1'
+        || request.headers.get('dnt')?.trim() === '1'
+        || ['deny', 'opt-out', 'off'].includes((request.headers.get('x-gradial-privacy-override') || '').trim().toLowerCase());
+    const raw = request.headers.get('x-aci-consent') || cookies.get('aci_consent') || '';
+    const snapshot = parseConsent(raw);
+    const allows = snapshot?.purposes.some((purpose) => purpose.toLowerCase() === 'personalization') || false;
+    return {
+        hasConsent: snapshot !== null,
+        snapshot,
+        allowsIdentityTier: !privacyDenied && allows,
+        privacyDenied,
+    };
+}
+export function parseCookieHeader(value) {
+    const cookies = new Map();
+    for (const part of (value || '').split(';')) {
+        const separator = part.indexOf('=');
+        if (separator < 0)
+            continue;
+        const name = part.slice(0, separator).trim();
+        if (name)
+            cookies.set(name, part.slice(separator + 1).trim());
+    }
+    return cookies;
+}
+export async function verifyIdentityCookie(value, keys) {
+    const parts = value.trim().split('.');
+    if (parts.length !== 3 || parts.some((part) => part === ''))
+        return null;
+    const [rawID, kid, signature] = parts;
+    const key = [keys.current, keys.previous].find((candidate) => candidate?.kid === kid);
+    if (!key)
+        return null;
+    return await verifyHMAC(`${rawID}.${kid}`, signature, key.secret) ? rawID : null;
+}
+export async function sha256Hex(value) {
+    const digest = await crypto.subtle.digest('SHA-256', textEncoder.encode(value));
+    return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, '0')).join('');
+}
+export async function identityHashHex(namespace, value) {
+    return sha256Hex(`${namespace.trim().toLowerCase()}\x00${value.trim()}`);
+}
+function parseConsent(raw) {
+    let decoded = raw.trim();
+    if (!decoded)
+        return null;
+    try {
+        decoded = decodeURIComponent(decoded);
+    }
+    catch {
+        // Evaluate the original value.
+    }
+    const legacy = new Set(['true', 'all', 'granted', 'yes', 'personalization', 'personalized']);
+    if (legacy.has(decoded.toLowerCase())) {
+        return { version: 0, purposes: ['personalization'], grantedAt: '' };
+    }
+    try {
+        const parsed = JSON.parse(decoded);
+        if (!Number.isInteger(parsed.v) || !Array.isArray(parsed.p) || !parsed.p.every((item) => typeof item === 'string') || typeof parsed.t !== 'string') {
+            return null;
+        }
+        return {
+            version: parsed.v,
+            purposes: parsed.p,
+            grantedAt: parsed.t,
+            source: typeof parsed.src === 'string' ? parsed.src : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function matchRoute(pathname, manifest) {
+    const normalized = normalizePath(pathname);
+    if (manifest.routes[normalized])
+        return manifest.routes[normalized];
+    const candidates = Object.values(manifest.routes)
+        .filter((route) => routePatternMatches(route.pattern, normalized))
+        .sort((left, right) => right.priority - left.priority || left.pattern.localeCompare(right.pattern));
+    return candidates[0] || null;
+}
+function normalizePath(value) {
+    let path = value.trim() || '/';
+    if (!path.startsWith('/'))
+        path = `/${path}`;
+    if (path.length > 1)
+        path = path.replace(/\/+$/, '');
+    return path;
+}
+function routePatternMatches(pattern, pathname) {
+    pattern = normalizePath(pattern);
+    if (pattern === pathname)
+        return true;
+    const expression = pattern
+        .replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+        .replace(/\\\[\\\[\\\.\\\.\\\.[^\]]+\\\]\\\]/g, '.*')
+        .replace(/\\\[\\\.\\\.\\\.[^\]]+\\\]/g, '.+')
+        .replace(/\\\[[^\]]+\\\]/g, '[^/]+')
+        .replace(/:[^/]+/g, '[^/]+')
+        .replace(/\\\*/g, '.*');
+    try {
+        return new RegExp(`^${expression}$`).test(pathname);
+    }
+    catch {
+        return false;
+    }
+}
+function toPersonalizationRequestContext(request) {
+    const url = new URL(request.url);
+    const cookies = parseCookieHeader(request.headers.get('cookie'));
+    const query = {};
+    url.searchParams.forEach((value, key) => {
+        (query[key] ||= []).push(value);
+    });
+    const headers = Object.fromEntries(request.headers.entries());
+    return {
+        path: url.pathname,
+        query,
+        headers,
+        cookies: Object.fromEntries(cookies.entries()),
+        signals: {
+            geo: {
+                country: headers['x-vercel-ip-country'] || '',
+                region: headers['x-vercel-ip-country-region'] || '',
+                city: headers['x-vercel-ip-city'] || '',
+            },
+        },
+    };
+}
+export async function verifyClaims(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];
+    if (!secret || !await verifyHMAC(`v1.${kid}.${body}`, signature, secret))
+        return null;
+    try {
+        const payload = JSON.parse(new TextDecoder().decode(base64URLDecode(body)));
+        if (!Number.isFinite(payload.exp) || payload.exp <= Math.floor(now.getTime() / 1000))
+            return null;
+        return payload;
+    }
+    catch {
+        return null;
+    }
+}
+async function signIdentity(rawID, key) {
+    const signature = await hmac(`${rawID}.${key.kid}`, key.secret);
+    return `${rawID}.${key.kid}.${signature}`;
+}
+function randomIdentity(random) {
+    const bytes = random ? random(16) : crypto.getRandomValues(new Uint8Array(16));
+    return base64URLEncode(bytes);
+}
+async function verifyHMAC(value, signature, secret) {
+    try {
+        const key = await crypto.subtle.importKey('raw', textEncoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['verify']);
+        return await crypto.subtle.verify('HMAC', key, base64URLDecode(signature), textEncoder.encode(value));
+    }
+    catch {
+        return false;
+    }
+}
+async function hmac(value, secret) {
+    const key = await crypto.subtle.importKey('raw', textEncoder.encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+    return base64URLEncode(new Uint8Array(await crypto.subtle.sign('HMAC', key, textEncoder.encode(value))));
+}
+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) {
+    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;
+}
+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) },
+    };
+}
+function expireCookie(name, secure) {
+    return { name, value: '', options: { path: '/', httpOnly: true, secure, sameSite: 'lax', maxAge: 0, expires: new Date(0) } };
+}

package/dist/next/server.js

@@ -10,7 +10,7 @@ export async function getPage(route = '', config = {}) {
     if (runtimeInput)
         return runtimeInput.page;
     const provider = await resolveProviderWithFallback(config);
-    const variantPage = await pageFromFunctionRef(provider);
+    const variantPage = await pageFromContentPath(provider);
     if (variantPage !== null)
         return variantPage;
     return await provider.getPage(route);
@@ -56,7 +56,7 @@ export async function getRenderInput(route = '/', config = {}) {
     // Cache shared resources (manifest, siteConfig) but not per-page content
     // Page-level caching is handled by CDN
     const [page, siteConfig] = await Promise.all([
-        pageFromFunctionRef(provider).then((variantPage) => variantPage ?? provider.getPage(route)),
+        pageFromContentPath(provider).then((variantPage) => variantPage ?? provider.getPage(route)),
         getCachedSiteConfig(provider),
     ]);
     return {
@@ -77,19 +77,19 @@ export async function getPageRuntimeRenderInput() {
     }
 }
 // The personalization edge proxies framework-origin requests with
-// X-Baremetal-Function-Ref naming the exact page payload its decision
+// X-Aci-Content-Ref naming the exact page payload its decision
 // selected (base or variant). When present, the SSR render must use that
 // payload — otherwise every visitor gets the base page and edge decisioning
 // is cosmetic. The S3 provider only serves refs the release manifest
 // declares.
-const BAREMETAL_FUNCTION_REF_HEADER = 'x-baremetal-function-ref';
-async function pageFromFunctionRef(provider) {
+const ACI_CONTENT_PATH_HEADER = 'x-aci-content-path';
+async function pageFromContentPath(provider) {
     if (!(provider instanceof S3ContentProvider))
         return null;
     let ref = '';
     try {
         const current = await headers();
-        ref = (current.get(BAREMETAL_FUNCTION_REF_HEADER) || '').trim();
+        ref = (current.get(ACI_CONTENT_PATH_HEADER) || '').trim();
     }
     catch {
         return null;

package/dist/next/vercel-personalization.d.ts

@@ -0,0 +1,3 @@
+export { CONTENT_PATH_CACHE_PARAM, CONTENT_PATH_HEADER, resolvePersonalizationRequest, type EdgeRouteManifest, type PersonalizationBlobStore, type PersonalizationCollectionStore, type PersonalizationHostConfig, type PersonalizationRouteStore, type PersonalizationResolution, } from './personalization-host.js';
+export { createPersonalizationCollectRoute, type PersonalizationCollectRouteConfig, } from './collect-route.js';
+export { createVercelPersonalizationFromEnv, createVercelCollectionFromEnv, VercelEdgeConfigRouteStore, createVercelS3PersonalizationStore, VercelS3PersonalizationStore, type VercelS3PersonalizationConfig, } from './vercel-s3-personalization.js';

package/dist/next/vercel-personalization.js

@@ -0,0 +1,3 @@
+export { CONTENT_PATH_CACHE_PARAM, CONTENT_PATH_HEADER, resolvePersonalizationRequest, } from './personalization-host.js';
+export { createPersonalizationCollectRoute, } from './collect-route.js';
+export { createVercelPersonalizationFromEnv, createVercelCollectionFromEnv, VercelEdgeConfigRouteStore, createVercelS3PersonalizationStore, VercelS3PersonalizationStore, } from './vercel-s3-personalization.js';

package/dist/next/vercel-s3-personalization.d.ts

@@ -0,0 +1,58 @@
+import type { EdgeRouteManifest, PersonalizationCollectionStore, PersonalizationHostConfig, PersonalizationRouteStore } from './personalization-host.js';
+export interface VercelS3PersonalizationConfig {
+    region: string;
+    roleArn?: string;
+    hostingBucket: string;
+    eventsBucket: string;
+    hostingKeyPrefix?: string;
+    claimsKeyPrefix?: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+}
+export interface S3CommandClient {
+    send(command: {
+        input: unknown;
+    }): Promise<any>;
+}
+/**
+ * Node-only Vercel collection adapter for audience lake objects and signed
+ * claims. The EdgeRouter never receives this adapter or AWS credentials.
+ * Production construction exchanges the Vercel workload OIDC token for
+ * scoped AWS credentials; no long-lived AWS keys are read.
+ */
+export declare class VercelS3PersonalizationStore implements PersonalizationCollectionStore {
+    private readonly config;
+    private readonly client;
+    constructor(config: VercelS3PersonalizationConfig, client?: S3CommandClient);
+    readClaims(siteId: string, namespace: string, identityHash: string): Promise<string | null>;
+    appendEvent(key: string, record: unknown): Promise<void>;
+    putSuppression(key: string, record: unknown): Promise<void>;
+    private readObject;
+}
+/**
+ * Edge Config is the provider projection for immutable release routing state.
+ * This tiny store is safe in Next middleware: it only fetches the route
+ * projection and never reads S3, claims, or event data.
+ */
+export declare class VercelEdgeConfigRouteStore implements PersonalizationRouteStore {
+    private readonly edgeConfig;
+    private readonly siteId;
+    constructor(edgeConfig: string, siteId: string);
+    readEdgeManifest(releaseId: string): Promise<EdgeRouteManifest | null>;
+}
+export declare function createVercelS3PersonalizationStore(config: VercelS3PersonalizationConfig): VercelS3PersonalizationStore;
+/**
+ * Builds the EdgeRouter configuration used by Next middleware. It deliberately
+ * has no AWS/S3 configuration: its only remote dependency is the provider's
+ * Edge Config projection.
+ */
+export declare function createVercelPersonalizationFromEnv(env?: Record<string, string | undefined>): PersonalizationHostConfig | undefined;
+/** Builds the Node.js `/collect` configuration. This is the only Vercel
+ * application runtime that receives data-plane storage configuration. */
+export declare function createVercelCollectionFromEnv(env?: Record<string, string | undefined>): {
+    siteId: string;
+    store: PersonalizationCollectionStore;
+    identityKeys: PersonalizationHostConfig['identityKeys'];
+    claimsKeys: Record<string, string>;
+    secureCookies: boolean;
+} | undefined;