@gradial/aci 0.1.41 → 0.1.43

package/dist/next/personalization-host.js

@@ -0,0 +1,257 @@
+import { resolvePersonalizationDecision, } from '../edge/personalization-core.js';
+import { parsePortableConsentEnvelope, portableConsentAllowsPersonalization, trimPortableConsentWhitespace, } from '../consent/portable-envelope.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 class IdentityErasureFencedError extends Error {
+    name = 'IdentityErasureFencedError';
+    constructor() {
+        super('identity collection is fenced by erasure');
+    }
+}
+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 headerConsent = request.headers.get('x-aci-consent');
+    const hasHeaderConsent = trimPortableConsentWhitespace(headerConsent || '') !== '';
+    const raw = hasHeaderConsent
+        ? headerConsent
+        : cookies.get('aci_consent') || '';
+    const snapshot = parsePortableConsentEnvelope(raw, !hasHeaderConsent);
+    const allows = portableConsentAllowsPersonalization(snapshot);
+    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 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.d.ts

@@ -9,6 +9,7 @@ export interface FetchConfig {
     accessKeyId?: string;
     secretAccessKey?: string;
     sessionToken?: string;
+    roleArn?: string;
     endpoint?: string;
     releaseId?: string;
     edgeConfig?: string;

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;
@@ -135,6 +135,7 @@ export async function getReleaseAssetResponse(releaseId, assetPath, config = {})
         accessKeyId: config.accessKeyId,
         secretAccessKey: config.secretAccessKey,
         sessionToken: config.sessionToken,
+        roleArn: config.roleArn,
         endpoint: config.endpoint,
     });
     const key = joinKey(provider.config.keyPrefix, 'assets', clean);
@@ -179,6 +180,7 @@ export async function getDamAssetResponse(assetPath, config = {}) {
         accessKeyId: config.accessKeyId,
         secretAccessKey: config.secretAccessKey,
         sessionToken: config.sessionToken,
+        roleArn: config.roleArn,
         endpoint: config.endpoint,
     });
     const key = joinKey(provider.config.keyPrefix, clean);
@@ -235,6 +237,7 @@ async function resolveS3Provider(config) {
         accessKeyId: config.accessKeyId,
         secretAccessKey: config.secretAccessKey,
         sessionToken: config.sessionToken,
+        roleArn: config.roleArn,
         endpoint: config.endpoint,
     });
     // Pre-warm the manifest with cached version

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

@@ -0,0 +1,27 @@
+export interface VercelCollectSDKRouteConfig {
+    siteId: string;
+    edgeConfig: string;
+    region: string;
+    roleArn: string;
+    hostingBucket: string;
+    hostingKeyPrefix?: string;
+}
+export interface VercelCollectSDKRouteDependencies {
+    s3Client?: VercelCollectSDKS3Client;
+    readEdgeConfig?: (connection: string, key: string) => Promise<unknown>;
+    onError?: (error: unknown) => void;
+}
+export interface VercelCollectSDKS3Client {
+    send(command: {
+        input: unknown;
+    }): Promise<unknown>;
+}
+export type VercelCollectSDKRoute = (request: Request) => Promise<Response>;
+/**
+ * Creates the Node-only stable collect-SDK route used by ACI's injected
+ * Vercel Function. The provider pointer selects the immutable release on every
+ * uncached invocation, so an old code deployment remains correct while a
+ * canonical activation converges through Edge Config and deployment promotion.
+ */
+export declare function createVercelCollectSDKRoute(input: VercelCollectSDKRouteConfig, dependencies?: VercelCollectSDKRouteDependencies): VercelCollectSDKRoute;
+export declare function createVercelCollectSDKRouteFromEnv(env?: Record<string, string | undefined>, dependencies?: VercelCollectSDKRouteDependencies): VercelCollectSDKRoute;

package/dist/next/vercel-collect-sdk-route.js

@@ -0,0 +1,205 @@
+import { createHash } from 'node:crypto';
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
+import { getUncachedEdgeConfigValue } from './edge-config.js';
+const SHA256_HEX = /^[0-9a-f]{64}$/;
+/**
+ * Creates the Node-only stable collect-SDK route used by ACI's injected
+ * Vercel Function. The provider pointer selects the immutable release on every
+ * uncached invocation, so an old code deployment remains correct while a
+ * canonical activation converges through Edge Config and deployment promotion.
+ */
+export function createVercelCollectSDKRoute(input, dependencies = {}) {
+    const config = validateConfig(input);
+    const readEdgeConfig = dependencies.readEdgeConfig || getUncachedEdgeConfigValue;
+    const client = dependencies.s3Client || new S3Client({
+        region: config.region,
+        credentials: awsCredentialsProvider({
+            roleArn: config.roleArn,
+            clientConfig: { region: config.region },
+        }),
+    });
+    const onError = dependencies.onError || ((error) => {
+        console.error('[ACI collect SDK] route failed', error);
+    });
+    return async (request) => {
+        const method = request.method.toUpperCase();
+        if (method !== 'GET' && method !== 'HEAD') {
+            return new Response('method not allowed', {
+                status: 405,
+                headers: {
+                    Allow: 'GET, HEAD',
+                    'Cache-Control': 'private, no-store',
+                },
+            });
+        }
+        try {
+            const active = parseActiveReleasePointer(await readEdgeConfig(config.edgeConfig, activeReleaseKey(config.siteId)));
+            const projection = parseProjection(await readEdgeConfig(config.edgeConfig, edgeRoutesKey(config.siteId, active.releaseId)));
+            if (projection.siteId !== config.siteId || projection.releaseId !== active.releaseId) {
+                throw new Error(`collect SDK projection identity mismatch: got ${projection.siteId}/${projection.releaseId}, `
+                    + `want ${config.siteId}/${active.releaseId}`);
+            }
+            if (!Object.prototype.hasOwnProperty.call(projection, 'collectSdk')) {
+                return new Response(method === 'HEAD' ? null : 'collect SDK is not enabled for this release', {
+                    status: 404,
+                    headers: { 'Cache-Control': 'no-store' },
+                });
+            }
+            const entry = validateCollectSDKEntry(projection.collectSdk);
+            const body = await readSDKObject(client, config.hostingBucket, joinKey(config.hostingKeyPrefix, 'releases', active.releaseId, entry.path));
+            const actualHash = createHash('sha256').update(body).digest('hex');
+            if (actualHash !== entry.hash) {
+                throw new Error(`collect SDK digest mismatch: got ${actualHash}, want ${entry.hash}`);
+            }
+            const etag = `"${entry.hash}"`;
+            const headers = new Headers({
+                'Content-Type': 'text/javascript; charset=utf-8',
+                'Cache-Control': 'public, max-age=300, must-revalidate',
+                ETag: etag,
+            });
+            if (ifNoneMatchSatisfied(request.headers.get('if-none-match'), etag)) {
+                return new Response(null, { status: 304, headers });
+            }
+            headers.set('Content-Length', String(body.byteLength));
+            const responseBody = body.buffer.slice(body.byteOffset, body.byteOffset + body.byteLength);
+            return new Response(method === 'HEAD' ? null : responseBody, { status: 200, headers });
+        }
+        catch (error) {
+            onError(error);
+            return new Response(method === 'HEAD' ? null : 'collect SDK is temporarily unavailable', {
+                status: 503,
+                headers: { 'Cache-Control': 'private, no-store' },
+            });
+        }
+    };
+}
+export function createVercelCollectSDKRouteFromEnv(env = process.env, dependencies = {}) {
+    try {
+        return createVercelCollectSDKRoute({
+            siteId: requiredEnv(env, 'ACI_SITE_ID'),
+            edgeConfig: requiredEnv(env, 'EDGE_CONFIG'),
+            region: env.AWS_REGION || env.AWS_DEFAULT_REGION || '',
+            roleArn: requiredEnv(env, 'AWS_ROLE_ARN'),
+            hostingBucket: requiredEnv(env, 'HOSTING_BUCKET'),
+            hostingKeyPrefix: env.HOSTING_KEY_PREFIX || env.GRADIAL_S3_KEY_PREFIX,
+        }, dependencies);
+    }
+    catch (error) {
+        (dependencies.onError || ((value) => {
+            console.error('[ACI collect SDK] configuration failed', value);
+        }))(error);
+        return async (request) => new Response(request.method.toUpperCase() === 'HEAD' ? null : 'collect SDK is temporarily unavailable', { status: 503, headers: { 'Cache-Control': 'private, no-store' } });
+    }
+}
+function validateConfig(input) {
+    const siteId = requiredPathSegment(input.siteId, 'ACI site ID');
+    const edgeConfig = input.edgeConfig.trim();
+    const region = input.region.trim();
+    const roleArn = input.roleArn.trim();
+    const hostingBucket = input.hostingBucket.trim();
+    if (!edgeConfig)
+        throw new Error('Edge Config connection is required');
+    if (!region)
+        throw new Error('AWS region is required');
+    if (!roleArn)
+        throw new Error('AWS role ARN is required');
+    if (!hostingBucket)
+        throw new Error('hosting bucket is required');
+    return {
+        siteId,
+        edgeConfig,
+        region,
+        roleArn,
+        hostingBucket,
+        hostingKeyPrefix: cleanKey(input.hostingKeyPrefix || ''),
+    };
+}
+function parseActiveReleasePointer(value) {
+    const parsed = parseRecord(value, 'active release pointer');
+    return { releaseId: requiredPathSegment(parsed.releaseId || '', 'active release ID') };
+}
+function parseProjection(value) {
+    const parsed = parseRecord(value, 'collect SDK route projection');
+    const projection = {
+        releaseId: requiredPathSegment(parsed.releaseId || '', 'projection release ID'),
+        siteId: requiredPathSegment(parsed.siteId || '', 'projection site ID'),
+    };
+    if (Object.prototype.hasOwnProperty.call(parsed, 'collectSdk')) {
+        projection.collectSdk = parsed.collectSdk;
+    }
+    return projection;
+}
+function parseRecord(value, label) {
+    const parsed = typeof value === 'string' ? JSON.parse(value) : value;
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error(`${label} is unavailable or malformed`);
+    }
+    return parsed;
+}
+function validateCollectSDKEntry(value) {
+    const entry = parseRecord(value, 'collect SDK metadata');
+    if (typeof entry.hash !== 'string' || typeof entry.path !== 'string') {
+        throw new Error('collect SDK metadata must contain string hash and path fields');
+    }
+    const hash = entry.hash.trim().toLowerCase();
+    const path = cleanKey(entry.path);
+    if (!SHA256_HEX.test(hash))
+        throw new Error('collect SDK hash must be lowercase SHA-256');
+    const expectedPath = `_aci/aci.${hash}.js`;
+    if (path !== expectedPath || path !== entry.path) {
+        throw new Error(`collect SDK path ${JSON.stringify(entry.path)} must equal ${JSON.stringify(expectedPath)}`);
+    }
+    return { hash, path };
+}
+async function readSDKObject(client, bucket, key) {
+    const output = await client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
+    if (output.Body?.transformToByteArray)
+        return await output.Body.transformToByteArray();
+    if (output.Body?.transformToString) {
+        return new TextEncoder().encode(await output.Body.transformToString());
+    }
+    throw new Error(`collect SDK object ${key} returned an unsupported body`);
+}
+function ifNoneMatchSatisfied(value, etag) {
+    const header = (value || '').trim();
+    if (!header)
+        return false;
+    if (header === '*')
+        return true;
+    return header.split(',').some((candidate) => {
+        const normalized = candidate.trim().replace(/^W\//, '');
+        return normalized === etag;
+    });
+}
+function activeReleaseKey(siteId) {
+    return `activeRelease_${edgeKeySegment(siteId)}`;
+}
+function edgeRoutesKey(siteId, releaseId) {
+    return `edgeRoutes_${edgeKeySegment(siteId)}_${edgeKeySegment(releaseId)}`;
+}
+function edgeKeySegment(value) {
+    return value.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+function requiredPathSegment(value, label) {
+    const clean = value.trim();
+    if (!clean || clean === '.' || clean === '..' || clean.includes('/') || clean.includes('\\')) {
+        throw new Error(`${label} is required and must be one path segment`);
+    }
+    return clean;
+}
+function cleanKey(value) {
+    const segments = value.replaceAll('\\', '/').split('/').filter((segment) => segment && segment !== '.');
+    if (segments.some((segment) => segment === '..'))
+        throw new Error('S3 key traversal is not allowed');
+    return segments.join('/');
+}
+function joinKey(...parts) {
+    return parts.map((part) => cleanKey(part || '')).filter(Boolean).join('/');
+}
+function requiredEnv(env, key) {
+    const value = env[key]?.trim() || '';
+    if (!value)
+        throw new Error(`${key} is required for the Vercel collect SDK route`);
+    return value;
+}

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

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

package/dist/next/vercel-personalization.js

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

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

@@ -0,0 +1,79 @@
+import type { EdgeRouteManifest, PersonalizationCollectionStore, PersonalizationHostConfig, PersonalizationEnvelopeWrite, PersonalizationRouteStore } from './personalization-host.js';
+export interface VercelS3PersonalizationConfig {
+    region: string;
+    roleArn?: string;
+    hostingBucket: string;
+    eventsBucket: string;
+    hostingKeyPrefix?: string;
+    claimsKeyPrefix?: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    collectionWriteTimeoutMs?: number;
+}
+export interface S3CommandClient {
+    send(command: {
+        input: unknown;
+    }, options?: {
+        abortSignal?: AbortSignal;
+    }): Promise<any>;
+}
+export declare class EnvelopeIDCollisionError extends Error {
+    readonly key: string;
+    readonly existingDigest: string;
+    readonly incomingDigest: string;
+    readonly name = "EnvelopeIDCollisionError";
+    constructor(key: string, existingDigest: string, incomingDigest: string);
+}
+/**
+ * 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>;
+    appendEnvelope(write: PersonalizationEnvelopeWrite): Promise<void>;
+    putSuppression(key: string, record: unknown): Promise<void>;
+    private acquireCollectionGate;
+    private releaseCollectionGate;
+    private settleResumedEnvelope;
+    private collectionGenerationSettled;
+    private putCollectionGate;
+    private readCollectionGate;
+    private sendWithWriteDeadline;
+    private writeTimeoutMs;
+    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 & {
+    roleArn: string;
+}): 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, and it
+ * fails closed unless the exact-project AWS workload role is configured. */
+export declare function createVercelCollectionFromEnv(env?: Record<string, string | undefined>): {
+    siteId: string;
+    store: PersonalizationCollectionStore;
+    identityKeys: PersonalizationHostConfig['identityKeys'];
+    claimsKeys: Record<string, string>;
+    secureCookies: boolean;
+} | undefined;