@gradial/aci 0.1.42 → 0.1.43

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

@@ -1,3 +1,4 @@
-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';
+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

@@ -1,3 +1,4 @@
-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';
+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

@@ -1,4 +1,4 @@
-import type { EdgeRouteManifest, PersonalizationCollectionStore, PersonalizationHostConfig, PersonalizationRouteStore } from './personalization-host.js';
+import type { EdgeRouteManifest, PersonalizationCollectionStore, PersonalizationHostConfig, PersonalizationEnvelopeWrite, PersonalizationRouteStore } from './personalization-host.js';
 export interface VercelS3PersonalizationConfig {
     region: string;
     roleArn?: string;
@@ -8,12 +8,22 @@ export interface VercelS3PersonalizationConfig {
     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.
@@ -25,8 +35,16 @@ export declare class VercelS3PersonalizationStore implements PersonalizationColl
     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>;
+    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;
 }
 /**
@@ -40,7 +58,9 @@ export declare class VercelEdgeConfigRouteStore implements PersonalizationRouteS
     constructor(edgeConfig: string, siteId: string);
     readEdgeManifest(releaseId: string): Promise<EdgeRouteManifest | null>;
 }
-export declare function createVercelS3PersonalizationStore(config: VercelS3PersonalizationConfig): VercelS3PersonalizationStore;
+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
@@ -48,7 +68,8 @@ export declare function createVercelS3PersonalizationStore(config: VercelS3Perso
  */
 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. */
+ * 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;