@gradial/aci 0.1.41 → 0.1.43

package/dist/next/middleware.js

@@ -1,18 +1,40 @@
 import { NextResponse } from 'next/server.js';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
 import { PREVIEW_TOKEN_COOKIE, PREVIEW_RELEASE_COOKIE, extractPreviewToken, resolvePreviewContext, createPreviewCookies, previewSignKey, } from '../preview/core.js';
+import { CONTENT_PATH_HEADER, CONTENT_PATH_CACHE_PARAM, resolvePersonalizationRequest, } from './personalization-host.js';
 const RELEASE_SCOPED_PREFIX = '/__r';
-// CMS document paths (robots.txt, sitemap.xml) pass through the middleware
-// and are served by Next.js rewrites configured in withAci().
-const CMS_DOCUMENT_PATHS = new Set(['/robots.txt', '/sitemap.xml']);
+const FRAMEWORK_ORIGIN_AUTH_HEADER = 'x-gradial-framework-origin-auth';
+const FRAMEWORK_SITE_ID_HEADER = 'x-baremetal-site-id';
+const FRAMEWORK_RELEASE_ID_HEADER = 'x-baremetal-release-id';
+const FRAMEWORK_CONTENT_REF_HEADER = 'x-aci-content-ref';
+const FRAMEWORK_CONTENT_BASE_URL_HEADER = 'x-baremetal-content-base-url';
+const textEncoder = new TextEncoder();
+const CMS_ASSET_PATHS = new Set(['/robots.txt', '/sitemap.xml']);
+const FRAMEWORK_RUNTIME_PATHS = new Set(['/favicon.ico', '/_health']);
+const FRAMEWORK_RUNTIME_PREFIXES = [
+    '/_next',
+    '/api',
+    '/collect',
+    '/gradial/assets',
+    '/.gradial-dam',
+];
 const PUBLIC_PATHS = new Set(typeof __ACI_PUBLIC_PATHS__ !== 'undefined' ? __ACI_PUBLIC_PATHS__ : []);
 const PASSTHROUGH_ROUTES = (typeof __ACI_PASSTHROUGH_ROUTES__ !== 'undefined' ? __ACI_PASSTHROUGH_ROUTES__ : []);
-const ASSET_PREFIX = typeof __ACI_ASSET_PREFIX__ !== 'undefined'
-    ? __ACI_ASSET_PREFIX__
-    : '/.gradial-dam';
 export function createGradialMiddleware(config = {}) {
     return async function middleware(request) {
         const url = request.nextUrl;
+        const frameworkDispatch = await resolveFrameworkDispatch(request, config);
+        if (frameworkDispatch.kind === 'rejected') {
+            return frameworkDispatch.response;
+        }
+        // The outer framework proxy authenticates every request with reserved
+        // dispatch headers, including Next/API/static runtime paths. Match those
+        // paths so the handoff is validated and reserved headers are stripped.
+        // Document rewrites retain only the validated, canonical content-path
+        // query because Vercel uses it as the selected payload's cache identity.
+        if (isFrameworkRuntimePath(url.pathname)) {
+            return passThroughResponse(request, frameworkDispatch);
+        }
         // ?leave_preview=1 → clear cookies, redirect to clean URL
         if (url.searchParams.get('leave_preview') === '1') {
             const cleanUrl = new URL(url.pathname, url.origin);
@@ -22,18 +44,13 @@ export function createGradialMiddleware(config = {}) {
             return response;
         }
         if (PUBLIC_PATHS.has(url.pathname)) {
-            return NextResponse.next();
-        }
-        if (CMS_DOCUMENT_PATHS.has(url.pathname)) {
-            return NextResponse.next();
+            return passThroughResponse(request, frameworkDispatch);
         }
-        // DAM asset requests are NOT release-scoped; they rewrite to S3 via
-        // withAci() rewrites. Pass them through so the rewrite fires.
-        if (isAssetPath(url.pathname)) {
-            return NextResponse.next();
+        if (CMS_ASSET_PATHS.has(url.pathname)) {
+            return passThroughResponse(request, frameworkDispatch);
         }
         if (isPassthroughRoute(url.pathname)) {
-            return NextResponse.next();
+            return passThroughResponse(request, frameworkDispatch);
         }
         // Block direct access to /__r/... — only middleware rewrites may use it.
         if (isReleaseScopedPath(url.pathname, RELEASE_SCOPED_PREFIX)) {
@@ -42,12 +59,20 @@ export function createGradialMiddleware(config = {}) {
                 headers: { 'Cache-Control': 'private, no-store' },
             });
         }
+        if (frameworkDispatch.kind === 'trusted') {
+            const response = rewriteToReleaseScopedPath(request, frameworkDispatch.releaseId, false, {
+                contentPath: frameworkDispatch.contentPath,
+                requestHeaders: frameworkRequestHeaders(request, frameworkDispatch.contentPath),
+            });
+            enforceCookieCacheRule(response);
+            return response;
+        }
         // Try preview token first; if valid, use that release.
         // If no token or invalid, fall through to active release from edge config.
         const preview = await resolvePreviewFromRequest(request, config);
         // Local file-backed development has no release-indexed artifact tree. A
         // valid preview token is still useful there—it proves signing, expiry, and
-        // cookie propagation—but rewriting to /__r/{releaseId}/{path} would create
+        // cookie propagation—but rewriting to /__r/{release}/routes would create
         // a path the file provider cannot serve. Keep the public route and mark
         // the response private, matching preview's cache semantics.
         if (process.env.ACI_CONTENT_PROVIDER === 'file') {
@@ -59,6 +84,7 @@ export function createGradialMiddleware(config = {}) {
                     response.cookies.set(cookie.name, cookie.value, cookie.options);
                 }
             }
+            enforceCookieCacheRule(response);
             return response;
         }
         const releaseId = preview?.releaseId || await activeReleaseFromEdgeConfig(config);
@@ -85,25 +111,88 @@ export function createGradialMiddleware(config = {}) {
                     response.cookies.set(cookie.name, cookie.value, cookie.options);
                 }
             }
+            enforceCookieCacheRule(response);
             return response;
         }
         // Rewrite public URL to release-scoped internal path for CDN cache isolation.
-        // Each release gets a unique URL (/__r/{releaseId}/...) so the CDN
+        // Each release gets a unique URL (/__r/{releaseId}/routes/...) so the CDN
         // cache key is per-release. New release = new URL = cache miss = fresh content.
-        const response = rewriteToReleaseScopedPath(request, releaseId, Boolean(preview?.isPreview));
+        let personalization;
+        if (config.personalization) {
+            const siteId = config.personalization.siteId || siteIdForConfig(config);
+            if (!siteId) {
+                return new Response('ACI site id is not configured', {
+                    status: 500,
+                    headers: { 'Cache-Control': 'private, no-store' },
+                });
+            }
+            try {
+                personalization = await resolvePersonalizationRequest(request, releaseId, {
+                    ...config.personalization,
+                    siteId,
+                });
+            }
+            catch {
+                return new Response('personalization artifacts unavailable', {
+                    status: 503,
+                    headers: { 'Cache-Control': 'private, no-store' },
+                });
+            }
+        }
+        const response = rewriteToReleaseScopedPath(request, releaseId, Boolean(preview?.isPreview), personalization
+            ? {
+                contentPath: personalization.contentPath,
+                requestHeaders: personalization.requestHeaders,
+            }
+            : undefined);
         // Persist preview token as cookie so navigation stays in preview
         if (preview?.token && preview.isPreview) {
             for (const cookie of createPreviewCookies(preview.token, releaseId)) {
                 response.cookies.set(cookie.name, cookie.value, cookie.options);
             }
         }
+        if (personalization) {
+            for (const cookie of personalization.cookies) {
+                response.cookies.set(cookie.name, cookie.value, cookie.options);
+            }
+            if (personalization.variantKey) {
+                response.headers.set('X-ACI-Variant-Key', personalization.variantKey);
+            }
+            if (personalization.experiment) {
+                response.headers.set('X-ACI-Experiment-ID', personalization.experiment.id);
+                response.headers.set('X-ACI-Experiment-Arm', personalization.experiment.arm);
+                response.headers.set('X-ACI-Experiment-Allocation-Version', personalization.experiment.allocationVersion);
+            }
+        }
+        enforceCookieCacheRule(response);
         return response;
     };
 }
-function rewriteToReleaseScopedPath(request, releaseId, isPreview) {
+/**
+ * Any response that writes a cookie is per-visitor and must never enter a
+ * shared cache (anonymous-experiments REQ-3(a)): a CDN-cached Set-Cookie
+ * replays one visitor's identity/claims to everyone under that cache key.
+ * Per-variant CACHING itself stays legitimate — the variant travels in the
+ * cache-keyed query parameter, not in cookies.
+ */
+export function enforceCookieCacheRule(response) {
+    if (response.cookies.getAll().length === 0) {
+        return;
+    }
+    response.headers.set('Cache-Control', 'private, no-store');
+    response.headers.delete('CDN-Cache-Control');
+    response.headers.delete('Vercel-CDN-Cache-Control');
+}
+function rewriteToReleaseScopedPath(request, releaseId, isPreview, options) {
     const rewriteURL = new URL(request.url);
     rewriteURL.pathname = releaseScopedPath(RELEASE_SCOPED_PREFIX, releaseId, request.nextUrl.pathname);
-    const response = NextResponse.rewrite(rewriteURL);
+    rewriteURL.searchParams.delete(CONTENT_PATH_CACHE_PARAM);
+    if (options?.contentPath) {
+        rewriteURL.searchParams.set(CONTENT_PATH_CACHE_PARAM, options.contentPath);
+    }
+    const response = options?.requestHeaders
+        ? NextResponse.rewrite(rewriteURL, { request: { headers: options.requestHeaders } })
+        : NextResponse.rewrite(rewriteURL);
     if (isPreview) {
         response.headers.set('Cache-Control', 'private, no-store');
     }
@@ -114,6 +203,113 @@ function rewriteToReleaseScopedPath(request, releaseId, isPreview) {
     }
     return response;
 }
+async function resolveFrameworkDispatch(request, config) {
+    // The outer edge has already minted identity and selected a release/payload.
+    // A trusted handoff must use that exact decision; falling through would mint
+    // a second identity and may select a different experiment arm.
+    const originAuth = request.headers.get(FRAMEWORK_ORIGIN_AUTH_HEADER);
+    const forwardedSiteId = request.headers.get(FRAMEWORK_SITE_ID_HEADER);
+    const forwardedReleaseId = request.headers.get(FRAMEWORK_RELEASE_ID_HEADER);
+    const forwardedContentRef = request.headers.get(FRAMEWORK_CONTENT_REF_HEADER);
+    const contentPathValues = request.nextUrl.searchParams.getAll(CONTENT_PATH_CACHE_PARAM);
+    const hasReservedDispatch = originAuth !== null
+        || forwardedSiteId !== null
+        || forwardedReleaseId !== null
+        || forwardedContentRef !== null
+        || request.headers.has(FRAMEWORK_CONTENT_BASE_URL_HEADER)
+        || request.headers.has(CONTENT_PATH_HEADER)
+        || contentPathValues.length > 0;
+    if (!hasReservedDispatch) {
+        return { kind: 'direct' };
+    }
+    const expectedOriginAuth = config.frameworkOriginAuthToken
+        || process.env.ACI_FRAMEWORK_ORIGIN_AUTH_TOKEN
+        || '';
+    if (!expectedOriginAuth
+        || originAuth === null
+        || !(await secureStringEqual(expectedOriginAuth, originAuth))) {
+        return rejectedFrameworkDispatch(403, 'framework dispatch forbidden');
+    }
+    if (!forwardedSiteId || !forwardedReleaseId) {
+        return rejectedFrameworkDispatch(400, 'invalid framework dispatch');
+    }
+    const expectedSiteId = siteIdForConfig(config);
+    if (!expectedSiteId || forwardedSiteId !== expectedSiteId) {
+        return rejectedFrameworkDispatch(403, 'framework dispatch forbidden');
+    }
+    if (forwardedContentRef === null && contentPathValues.length === 0) {
+        return {
+            kind: 'trusted',
+            releaseId: forwardedReleaseId,
+            contentPath: '',
+        };
+    }
+    if (!forwardedContentRef
+        || contentPathValues.length !== 1
+        || contentPathValues[0] !== forwardedContentRef) {
+        return rejectedFrameworkDispatch(400, 'invalid framework dispatch');
+    }
+    return {
+        kind: 'trusted',
+        releaseId: forwardedReleaseId,
+        contentPath: forwardedContentRef,
+    };
+}
+function passThroughResponse(request, frameworkDispatch) {
+    if (frameworkDispatch.kind !== 'trusted') {
+        return NextResponse.next();
+    }
+    if (frameworkDispatch.contentPath) {
+        return new Response('invalid framework dispatch', {
+            status: 400,
+            headers: { 'Cache-Control': 'private, no-store' },
+        });
+    }
+    return NextResponse.next({
+        request: {
+            headers: sanitizedFrameworkRequestHeaders(request),
+        },
+    });
+}
+function frameworkRequestHeaders(request, contentPath) {
+    const requestHeaders = sanitizedFrameworkRequestHeaders(request);
+    if (contentPath) {
+        requestHeaders.set(CONTENT_PATH_HEADER, contentPath);
+    }
+    return requestHeaders;
+}
+function sanitizedFrameworkRequestHeaders(request) {
+    const requestHeaders = new Headers(request.headers);
+    requestHeaders.delete(FRAMEWORK_ORIGIN_AUTH_HEADER);
+    requestHeaders.delete(FRAMEWORK_SITE_ID_HEADER);
+    requestHeaders.delete(FRAMEWORK_RELEASE_ID_HEADER);
+    requestHeaders.delete(FRAMEWORK_CONTENT_REF_HEADER);
+    requestHeaders.delete(FRAMEWORK_CONTENT_BASE_URL_HEADER);
+    requestHeaders.delete(CONTENT_PATH_HEADER);
+    return requestHeaders;
+}
+function rejectedFrameworkDispatch(status, message) {
+    return {
+        kind: 'rejected',
+        response: new Response(message, {
+            status,
+            headers: { 'Cache-Control': 'private, no-store' },
+        }),
+    };
+}
+async function secureStringEqual(expected, actual) {
+    const [expectedDigest, actualDigest] = await Promise.all([
+        crypto.subtle.digest('SHA-256', textEncoder.encode(expected)),
+        crypto.subtle.digest('SHA-256', textEncoder.encode(actual)),
+    ]);
+    const expectedBytes = new Uint8Array(expectedDigest);
+    const actualBytes = new Uint8Array(actualDigest);
+    let different = 0;
+    for (let index = 0; index < expectedBytes.length; index += 1) {
+        different |= expectedBytes[index] ^ actualBytes[index];
+    }
+    return different === 0;
+}
 function isReleaseScopedPath(pathname, prefix) {
     return pathname === prefix || pathname.startsWith(`${prefix}/`);
 }
@@ -185,8 +381,8 @@ async function activeReleaseFromEdgeConfig(config) {
         return active.releaseId;
     return clampRelease(active.releaseId, active.sequence || 0, compatibility);
 }
-function siteIdForConfig(_config) {
-    return process.env.ACI_SITE_ID || '';
+function siteIdForConfig(config) {
+    return config.siteId || process.env.ACI_SITE_ID || '';
 }
 async function getEdgeConfigJSON(edgeConfig, key) {
     const value = await getEdgeConfigValue(edgeConfig, key);
@@ -243,16 +439,15 @@ function clampRelease(activeReleaseId, activeSequence, compatibility) {
 function edgeKeySegment(value) {
     return value.replace(/[^A-Za-z0-9_-]/g, '_');
 }
-function isAssetPath(pathname) {
-    if (pathname === ASSET_PREFIX || pathname.startsWith(`${ASSET_PREFIX}/`))
-        return true;
-    if (pathname.startsWith('/gradial/assets/'))
-        return true;
-    return false;
-}
 function isPassthroughRoute(pathname) {
     return PASSTHROUGH_ROUTES.some((route) => routeMatches(pathname, route));
 }
+function isFrameworkRuntimePath(pathname) {
+    if (FRAMEWORK_RUNTIME_PATHS.has(pathname)) {
+        return true;
+    }
+    return FRAMEWORK_RUNTIME_PREFIXES.some((prefix) => pathname === prefix || pathname.startsWith(`${prefix}/`));
+}
 function routeMatches(pathname, route) {
     const cleanPath = normalizeRoutePath(pathname);
     const cleanRoute = normalizeRoutePath(route);
@@ -276,8 +471,37 @@ function normalizeRoutePath(value) {
     return pathname.replace(/\/{2,}/g, '/').replace(/\/$/, '') || '/';
 }
 export const aciMiddlewareMatcher = [
-    '/((?!_next(?:/|$)|api(?:/|$)|favicon\\.ico$|\\.gradial-dam(?:/|$)).*)',
+    '/((?!_next(?:/|$)|api(?:/|$)|collect(?:/|$)|gradial/assets(?:/|$)|favicon\\.ico$).*)',
+    {
+        source: '/:path*',
+        has: [{ type: 'header', key: 'x-gradial-framework-origin-auth' }],
+    },
+    {
+        source: '/:path*',
+        has: [{ type: 'header', key: 'x-baremetal-site-id' }],
+    },
+    {
+        source: '/:path*',
+        has: [{ type: 'header', key: 'x-baremetal-release-id' }],
+    },
+    {
+        source: '/:path*',
+        has: [{ type: 'header', key: 'x-aci-content-ref' }],
+    },
+    {
+        source: '/:path*',
+        has: [{ type: 'header', key: 'x-baremetal-content-base-url' }],
+    },
+    {
+        source: '/:path*',
+        has: [{ type: 'header', key: 'x-aci-content-path' }],
+    },
+    {
+        source: '/:path*',
+        has: [{ type: 'query', key: '__aci_content_path' }],
+    },
 ];
 export const config = {
+    runtime: 'nodejs',
     matcher: aciMiddlewareMatcher,
 };

package/dist/next/page.js

@@ -4,6 +4,7 @@ import { Fragment } from 'react';
 import { PageNotFoundError, getRenderInput, getLayout, getFragment, } from './server.js';
 import { routeMetadataForContent, resolveSlots, } from '../content/index.js';
 import { renderBlocks } from './render.js';
+import { AssignmentsScript } from './assignments-script.js';
 import { CollectScript } from './collect-script.js';
 /**
  * Creates the catch-all route handler for a Next.js ACI site.
@@ -80,7 +81,7 @@ export function createPage(registry, options) {
                 }
                 return (_jsx(Fragment, { children: renderedBlocks }, slot.name));
             }));
-            return (_jsxs(_Fragment, { children: [renderedSlots.filter(Boolean), _jsx(CollectScript, { siteConfig: input.siteConfig })] }));
+            return (_jsxs(_Fragment, { children: [renderedSlots.filter(Boolean), _jsx(AssignmentsScript, { page: input.page }), _jsx(CollectScript, { siteConfig: input.siteConfig })] }));
         }
         catch (error) {
             if (error instanceof PageNotFoundError)

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

@@ -0,0 +1,127 @@
+import { type PersonalizationExperiment } from '../edge/personalization-core.js';
+import { type PortableConsentSnapshot } from '../consent/portable-envelope.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;
+}
+export interface PersonalizationEnvelopeWrite {
+    key: string;
+    envelopeId: string;
+    siteId: string;
+    identityNamespace: string;
+    identityHash: string;
+    records: readonly unknown[];
+    digest: string;
+}
+export declare class IdentityErasureFencedError extends Error {
+    readonly name = "IdentityErasureFencedError";
+    constructor();
+}
+/** 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>;
+    appendEnvelope(write: PersonalizationEnvelopeWrite): 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 type ConsentSnapshot = PortableConsentSnapshot;
+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 {};