@gradial/aci 0.1.42 → 0.1.43

package/dist/next/vercel-s3-personalization.js

@@ -1,6 +1,32 @@
 import { GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client, } from '@aws-sdk/client-s3';
 import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
 import { getUncachedEdgeConfigValue } from './edge-config.js';
+import { IdentityErasureFencedError } from './personalization-host.js';
+const ENVELOPE_DIGEST_METADATA_KEY = 'aci-envelope-sha256';
+const COLLECTION_GATE_ETAG_METADATA_KEY = 'aci-collection-gate-etag';
+const COLLECTION_GATE_STATE_METADATA_KEY = 'aci-collection-gate-state';
+const COLLECTION_GATE_OWNER_METADATA_KEY = 'aci-collection-gate-owner';
+const COLLECTION_GATE_DIGEST_METADATA_KEY = 'aci-collection-gate-envelope-sha256';
+const COLLECTION_GATE_PREFIX = 'audience/collection-gate';
+const COLLECTION_WRITE_TIMEOUT_MS = 2 * 60 * 1000;
+const COLLECTION_GATE_RETRY_MS = 25;
+const COLLECTION_GATE_ATTEMPTS = 80;
+const MAX_LAKE_OBJECT_RECORDS = 100;
+const MAX_LAKE_OBJECT_WRITE_BYTES = 1024 * 1024;
+const SHA256_HEX = /^[0-9a-f]{64}$/i;
+const textEncoder = new TextEncoder();
+export class EnvelopeIDCollisionError extends Error {
+    key;
+    existingDigest;
+    incomingDigest;
+    name = 'EnvelopeIDCollisionError';
+    constructor(key, existingDigest, incomingDigest) {
+        super(`envelope ID collision at ${key}`);
+        this.key = key;
+        this.existingDigest = existingDigest;
+        this.incomingDigest = incomingDigest;
+    }
+}
 /**
  * Node-only Vercel collection adapter for audience lake objects and signed
  * claims. The EdgeRouter never receives this adapter or AWS credentials.
@@ -12,16 +38,24 @@ export class VercelS3PersonalizationStore {
     client;
     constructor(config, client) {
         this.config = config;
+        if (client) {
+            this.client = client;
+            return;
+        }
+        const roleArn = config.roleArn?.trim() || '';
+        if (!roleArn) {
+            throw new Error('AWS role ARN is required for the Vercel S3 personalization store');
+        }
         const s3Config = {
             region: config.region,
             endpoint: config.endpoint,
             forcePathStyle: config.forcePathStyle,
-            ...(config.roleArn ? { credentials: awsCredentialsProvider({
-                    roleArn: config.roleArn,
-                    clientConfig: { region: config.region },
-                }) } : {}),
+            credentials: awsCredentialsProvider({
+                roleArn,
+                clientConfig: { region: config.region },
+            }),
         };
-        this.client = client || new S3Client(s3Config);
+        this.client = new S3Client(s3Config);
     }
     async readClaims(siteId, namespace, identityHash) {
         const key = joinKey(this.config.claimsKeyPrefix || 'audience/claims/v1', requiredSegment(identityHash, 'identity hash').slice(0, 2).toLowerCase(), requiredSegment(siteId, 'site id'), requiredSegment(namespace, 'identity namespace').toLowerCase(), `${requiredSegment(identityHash, 'identity hash').toLowerCase()}.json`);
@@ -36,30 +70,96 @@ export class VercelS3PersonalizationStore {
             return null;
         return envelope.signedValue;
     }
-    async appendEvent(key, record) {
+    async appendEnvelope(write) {
+        const digest = write.digest.trim().toLowerCase();
+        if (!SHA256_HEX.test(digest)) {
+            throw new Error('envelope digest must be a SHA-256 hex value');
+        }
+        if (!Array.isArray(write.records) ||
+            write.records.length === 0 ||
+            write.records.length > MAX_LAKE_OBJECT_RECORDS ||
+            write.records.some((record) => !record ||
+                typeof record !== 'object' ||
+                Array.isArray(record) ||
+                record.schemaVersion !== 2)) {
+            throw new Error(`envelope records must be a schemaVersion-2 array with 1-${MAX_LAKE_OBJECT_RECORDS} entries`);
+        }
+        const body = JSON.stringify(write.records);
+        const bodyBytes = textEncoder.encode(body).byteLength;
+        if (bodyBytes > MAX_LAKE_OBJECT_WRITE_BYTES) {
+            throw new Error(`serialized envelope is ${bodyBytes} bytes, maximum ${MAX_LAKE_OBJECT_WRITE_BYTES}`);
+        }
+        const key = cleanKey(write.key);
+        const gate = await this.acquireCollectionGate(write, digest);
         const input = {
             Bucket: this.config.eventsBucket,
-            Key: cleanKey(key),
-            Body: JSON.stringify(record),
+            Key: key,
+            Body: body,
             ContentType: 'application/json',
             IfNoneMatch: '*',
+            Metadata: {
+                [ENVELOPE_DIGEST_METADATA_KEY]: digest,
+                [COLLECTION_GATE_ETAG_METADATA_KEY]: gate.etag,
+            },
         };
+        if (gate.resumedUncertain) {
+            return this.settleResumedEnvelope(input.Key, digest, gate);
+        }
+        let operationError;
+        let settled = false;
         try {
-            await this.client.send(new PutObjectCommand(input));
+            await this.sendWithWriteDeadline(new PutObjectCommand(input));
+            settled = true;
         }
         catch (error) {
-            if (!isConditionalConflict(error))
+            if (!isConditionalConflict(error)) {
+                // Unknown write outcome: retain state=collecting without expiry.
+                // A retry is HEAD-only and cannot release until this exact write is
+                // visible with the authorizing generation metadata.
                 throw error;
+            }
             // S3 can report 409 for two concurrent conditional writes even when
             // neither write has committed yet. Confirm the object before treating
             // the conflict as the idempotent duplicate case.
+            let head;
             try {
-                await this.client.send(new HeadObjectCommand({ Bucket: input.Bucket, Key: input.Key }));
+                head = await this.client.send(new HeadObjectCommand({ Bucket: input.Bucket, Key: input.Key }));
             }
             catch (headError) {
-                throw new Error(`conditional event write conflicted before ${input.Key} was stored`, { cause: headError });
+                // The conditional outcome remains unknown; retain the collecting
+                // generation exactly like an unclassified PUT failure.
+                throw new Error(`conditional envelope write conflicted before ${input.Key} was stored`, { cause: headError });
             }
+            const existingDigest = envelopeDigestMetadata(head.Metadata);
+            const existingGateETag = metadataValue(head.Metadata, COLLECTION_GATE_ETAG_METADATA_KEY);
+            settled = true;
+            if (existingDigest === digest && (existingGateETag === gate.etag || gate.claimedFromOpen)) {
+                // Identical retry. A resumed uncertain generation must match the
+                // exact authorizing gate ETag; a gate claimed from open may observe
+                // an object already settled by the prior open generation.
+            }
+            else if (existingDigest !== digest) {
+                operationError = new EnvelopeIDCollisionError(input.Key, existingDigest, digest);
+            }
+            else {
+                // Keep the resumed generation collecting: the object cannot prove
+                // it was authorized by this uncertain writer.
+                throw new Error(`envelope at ${input.Key} does not match resumed collection-gate generation ${gate.etag}`);
+            }
+        }
+        if (!settled)
+            throw new Error(`envelope write did not settle at ${input.Key}`);
+        try {
+            await this.releaseCollectionGate(gate);
         }
+        catch (releaseError) {
+            if (operationError) {
+                throw new AggregateError([operationError, releaseError], 'envelope operation and collection-gate release both failed');
+            }
+            throw releaseError;
+        }
+        if (operationError)
+            throw operationError;
     }
     async putSuppression(key, record) {
         await this.client.send(new PutObjectCommand({
@@ -69,6 +169,214 @@ export class VercelS3PersonalizationStore {
             ContentType: 'application/json',
         }));
     }
+    async acquireCollectionGate(write, requestedDigest) {
+        const siteId = requiredSegment(write.siteId, 'site id');
+        const namespace = requiredSegment(write.identityNamespace, 'identity namespace').toLowerCase();
+        const identityHash = requiredIdentityHash(write.identityHash);
+        const owner = requiredEnvelopeId(write.envelopeId);
+        const digest = requiredDigest(requestedDigest);
+        const key = joinKey(COLLECTION_GATE_PREFIX, identityHash.slice(0, 2), siteId, namespace, `${identityHash}.json`);
+        for (let attempt = 0; attempt < COLLECTION_GATE_ATTEMPTS; attempt += 1) {
+            const collecting = {
+                schemaVersion: 1,
+                state: 'collecting',
+                owner,
+                digest,
+            };
+            try {
+                const etag = await this.putCollectionGate(key, collecting);
+                return {
+                    key,
+                    etag,
+                    owner,
+                    digest,
+                    claimedFromOpen: false,
+                    resumedUncertain: false,
+                };
+            }
+            catch (error) {
+                if (!isConditionalConflict(error))
+                    throw new Error(`create collection gate ${key}`, { cause: error });
+            }
+            const current = await this.readCollectionGate(key);
+            if (current.record.state === 'erased')
+                throw new IdentityErasureFencedError();
+            if (current.record.state === 'collecting') {
+                const currentOwner = requiredEnvelopeId(current.record.owner || '');
+                const currentDigest = requiredDigest(current.record.digest || '');
+                if (currentOwner === owner) {
+                    if (currentDigest !== digest) {
+                        throw new EnvelopeIDCollisionError(key, currentDigest, digest);
+                    }
+                    return {
+                        key,
+                        etag: current.etag,
+                        owner,
+                        digest,
+                        claimedFromOpen: false,
+                        resumedUncertain: true,
+                    };
+                }
+                const settled = await this.collectionGenerationSettled(siteId, namespace, identityHash, currentOwner, currentDigest, current.etag);
+                if (settled) {
+                    await this.releaseCollectionGate({
+                        key,
+                        etag: current.etag,
+                        owner: currentOwner,
+                        digest: currentDigest,
+                        claimedFromOpen: false,
+                        resumedUncertain: true,
+                    });
+                    continue;
+                }
+                await delay(COLLECTION_GATE_RETRY_MS);
+                continue;
+            }
+            else if (current.record.state !== 'open') {
+                throw new Error(`collection gate ${key} has unknown state ${String(current.record.state)}`);
+            }
+            try {
+                const etag = await this.putCollectionGate(key, collecting, current.etag);
+                return {
+                    key,
+                    etag,
+                    owner,
+                    digest,
+                    claimedFromOpen: true,
+                    resumedUncertain: false,
+                };
+            }
+            catch (error) {
+                if (!isConditionalConflict(error))
+                    throw new Error(`claim collection gate ${key}`, { cause: error });
+            }
+            await delay(COLLECTION_GATE_RETRY_MS);
+        }
+        throw new Error(`collection gate is busy at ${key}`);
+    }
+    async releaseCollectionGate(lease) {
+        try {
+            await this.putCollectionGate(lease.key, { schemaVersion: 1, state: 'open' }, lease.etag);
+            return;
+        }
+        catch (error) {
+            let current;
+            try {
+                current = await this.readCollectionGate(lease.key);
+            }
+            catch (readError) {
+                throw new AggregateError([error, readError], `release collection gate and reconcile state failed at ${lease.key}`);
+            }
+            if (current.record.state === 'open')
+                return;
+            if (current.record.state === 'erased')
+                throw new IdentityErasureFencedError();
+            if (current.record.state === 'collecting' && current.etag !== lease.etag) {
+                return;
+            }
+            throw error;
+        }
+    }
+    async settleResumedEnvelope(key, digest, gate) {
+        for (let attempt = 0; attempt < COLLECTION_GATE_ATTEMPTS; attempt += 1) {
+            let head;
+            try {
+                head = await this.client.send(new HeadObjectCommand({ Bucket: this.config.eventsBucket, Key: key }));
+            }
+            catch (error) {
+                if (isNotFound(error)) {
+                    await delay(COLLECTION_GATE_RETRY_MS);
+                    continue;
+                }
+                throw new Error(`verify uncertain envelope ${key}; collection gate remains busy`, { cause: error });
+            }
+            const existingDigest = envelopeDigestMetadata(head.Metadata);
+            const existingGateETag = metadataValue(head.Metadata, COLLECTION_GATE_ETAG_METADATA_KEY);
+            if (existingDigest !== digest) {
+                throw new EnvelopeIDCollisionError(key, existingDigest, digest);
+            }
+            if (existingGateETag !== gate.etag) {
+                throw new Error(`envelope at ${key} does not match resumed collection-gate generation ${gate.etag}`);
+            }
+            await this.releaseCollectionGate(gate);
+            return;
+        }
+        throw new Error(`uncertain envelope ${key} is not yet visible; collection gate remains busy`);
+    }
+    async collectionGenerationSettled(siteId, namespace, identityHash, owner, digest, gateETag) {
+        const key = joinKey('audience/first-party', identityHash.slice(0, 2), siteId, namespace, identityHash, `${owner}.json`);
+        let head;
+        try {
+            head = await this.client.send(new HeadObjectCommand({ Bucket: this.config.eventsBucket, Key: key }));
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return false;
+            throw new Error(`verify collecting generation object ${key}`, { cause: error });
+        }
+        const existingDigest = envelopeDigestMetadata(head.Metadata);
+        const existingGateETag = metadataValue(head.Metadata, COLLECTION_GATE_ETAG_METADATA_KEY);
+        if (existingDigest !== digest || existingGateETag !== gateETag) {
+            throw new Error(`collecting generation object ${key} has mismatched proof metadata`);
+        }
+        return true;
+    }
+    async putCollectionGate(key, record, ifMatch) {
+        const metadata = {
+            [COLLECTION_GATE_STATE_METADATA_KEY]: record.state,
+        };
+        if (record.owner)
+            metadata[COLLECTION_GATE_OWNER_METADATA_KEY] = record.owner;
+        if (record.digest)
+            metadata[COLLECTION_GATE_DIGEST_METADATA_KEY] = record.digest;
+        const output = await this.client.send(new PutObjectCommand({
+            Bucket: this.config.eventsBucket,
+            Key: cleanKey(key),
+            Body: JSON.stringify(record),
+            ContentType: 'application/json',
+            Metadata: metadata,
+            ...(ifMatch ? { IfMatch: ifMatch } : { IfNoneMatch: '*' }),
+        }));
+        const etag = output.ETag?.trim() || '';
+        if (!etag)
+            throw new Error(`collection gate PUT returned no ETag at ${key}`);
+        return etag;
+    }
+    async readCollectionGate(key) {
+        let output;
+        try {
+            output = await this.client.send(new HeadObjectCommand({ Bucket: this.config.eventsBucket, Key: cleanKey(key) }));
+        }
+        catch (error) {
+            throw new Error(`head collection gate ${key}`, { cause: error });
+        }
+        const etag = output.ETag?.trim() || '';
+        if (!etag)
+            throw new Error(`collection gate ${key} has no ETag`);
+        const metadata = lowerCaseMetadata(output.Metadata);
+        return {
+            etag,
+            record: {
+                schemaVersion: 1,
+                state: metadata[COLLECTION_GATE_STATE_METADATA_KEY],
+                owner: metadata[COLLECTION_GATE_OWNER_METADATA_KEY],
+                digest: metadata[COLLECTION_GATE_DIGEST_METADATA_KEY],
+            },
+        };
+    }
+    async sendWithWriteDeadline(command) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.writeTimeoutMs());
+        try {
+            return await this.client.send(command, { abortSignal: controller.signal });
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    writeTimeoutMs() {
+        return positiveDuration(this.config.collectionWriteTimeoutMs, COLLECTION_WRITE_TIMEOUT_MS);
+    }
     async readObject(bucket, key) {
         try {
             const output = await this.client.send(new GetObjectCommand({ Bucket: bucket, Key: key }));
@@ -144,7 +452,8 @@ export function createVercelPersonalizationFromEnv(env = process.env) {
     };
 }
 /** 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 function createVercelCollectionFromEnv(env = process.env) {
     if (env.ACI_PERSONALIZATION_HOST_ENABLED !== 'true')
         return undefined;
@@ -152,6 +461,7 @@ export function createVercelCollectionFromEnv(env = process.env) {
     const region = env.AWS_REGION || env.AWS_DEFAULT_REGION || '';
     if (!region)
         throw new Error('AWS_REGION is required for the Vercel /collect route');
+    const roleArn = requiredEnv(env, 'AWS_ROLE_ARN');
     const currentKID = env.ACI_IDENTITY_KID || env.AUDIENCE_IDENTITY_COOKIE_KID || 'v1';
     const currentSecret = env.ACI_IDENTITY_SECRET || env.AUDIENCE_IDENTITY_COOKIE_SECRET || '';
     if (!currentSecret)
@@ -169,7 +479,7 @@ export function createVercelCollectionFromEnv(env = process.env) {
         siteId,
         store: createVercelS3PersonalizationStore({
             region,
-            roleArn: env.AWS_ROLE_ARN?.trim() || undefined,
+            roleArn,
             hostingBucket: requiredEnv(env, 'HOSTING_BUCKET'),
             eventsBucket: requiredEnv(env, 'EVENTS_BUCKET'),
             hostingKeyPrefix: env.HOSTING_KEY_PREFIX,
@@ -189,6 +499,26 @@ function requiredSegment(value, label) {
         throw new Error(`${label} is required and must be one path segment`);
     return clean;
 }
+function requiredIdentityHash(value) {
+    const hash = requiredSegment(value, 'identity hash').toLowerCase();
+    if (!/^[0-9a-f]{2,}$/.test(hash))
+        throw new Error('identity hash must be lowercase hexadecimal');
+    return hash;
+}
+function requiredEnvelopeId(value) {
+    const envelopeId = requiredSegment(value, 'envelope id').toUpperCase();
+    if (!/^[0-7][0-9A-HJKMNP-TV-Z]{25}$/.test(envelopeId)) {
+        throw new Error('envelope id must be a normalized ULID');
+    }
+    return envelopeId;
+}
+function requiredDigest(value) {
+    const digest = value.trim().toLowerCase();
+    if (!SHA256_HEX.test(digest)) {
+        throw new Error('envelope digest must be a SHA-256 hex value');
+    }
+    return digest;
+}
 function requiredEnv(env, name) {
     const value = env[name]?.trim() || '';
     if (!value)
@@ -218,3 +548,27 @@ function isConditionalConflict(error) {
         || value?.name === 'ConditionalRequestConflict'
         || value?.name === 'PreconditionFailed';
 }
+function envelopeDigestMetadata(metadata) {
+    return metadataValue(metadata, ENVELOPE_DIGEST_METADATA_KEY).toLowerCase();
+}
+function metadataValue(metadata, want) {
+    for (const [key, value] of Object.entries(metadata || {})) {
+        if (key.toLowerCase() === want) {
+            return value.trim();
+        }
+    }
+    return '';
+}
+function lowerCaseMetadata(metadata) {
+    return Object.fromEntries(Object.entries(metadata || {}).map(([key, value]) => [key.toLowerCase(), value.trim()]));
+}
+function positiveDuration(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error('collection gate durations must be positive');
+    return value;
+}
+async function delay(milliseconds) {
+    await new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/dist/providers/s3.d.ts

@@ -6,13 +6,28 @@ export interface S3ContentProviderConfig {
     accessKeyId?: string;
     secretAccessKey?: string;
     sessionToken?: string;
+    roleArn?: string;
     endpoint?: string;
 }
-type ResolvedS3Config = Required<S3ContentProviderConfig>;
+type ResolvedS3Config = {
+    bucket: string;
+    keyPrefix: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken: string;
+    roleArn: string;
+    endpoint: string;
+};
+export interface S3CommandClient {
+    send(command: {
+        input: unknown;
+    }): Promise<any>;
+}
 export declare class S3ContentProvider implements ContentProvider {
     #private;
     readonly config: ResolvedS3Config;
-    constructor(config?: S3ContentProviderConfig);
+    constructor(config?: S3ContentProviderConfig, client?: S3CommandClient);
     listRoutes(): Promise<RouteEntry[]>;
     getSiteConfig<T = unknown>(): Promise<T>;
     getPage<T = unknown>(route: string): Promise<T>;
@@ -29,6 +44,6 @@ export declare class S3ContentProvider implements ContentProvider {
     fetchRaw(key: string): Promise<Response>;
     private getJSON;
 }
-export declare function getS3JSON<T>(key: string, config: ResolvedS3Config): Promise<T>;
-export declare function getS3Raw(key: string, config: ResolvedS3Config): Promise<Response>;
+export declare function getS3JSON<T>(key: string, config: ResolvedS3Config, client?: S3CommandClient): Promise<T>;
+export declare function getS3Raw(key: string, config: ResolvedS3Config, client?: S3CommandClient): Promise<Response>;
 export {};

package/dist/providers/s3.js

@@ -1,4 +1,6 @@
 import crypto from 'node:crypto';
+import { GetObjectCommand, S3Client } from '@aws-sdk/client-s3';
+import { awsCredentialsProvider } from '@vercel/oidc-aws-credentials-provider';
 import { FragmentNotFoundError, LayoutNotFoundError, PageNotFoundError } from '../content/provider.js';
 import { normalizeRoute } from '../content/routes.js';
 // ---------------------------------------------------------------------------
@@ -7,8 +9,10 @@ import { normalizeRoute } from '../content/routes.js';
 export class S3ContentProvider {
     config;
     #manifest;
-    constructor(config = {}) {
+    #client;
+    constructor(config = {}, client) {
         this.config = resolveS3Config(config);
+        this.#client = client || oidcS3Client(this.config);
     }
     async listRoutes() {
         const manifest = await this.manifest();
@@ -83,24 +87,18 @@ export class S3ContentProvider {
         return await this.#manifest;
     }
     async fetchRaw(key) {
-        return await getS3Raw(key, this.config);
+        return await getS3Raw(key, this.config, this.#client);
     }
     async getJSON(key) {
-        return await getS3JSON(joinKey(this.config.keyPrefix, key), this.config);
+        return await getS3JSON(joinKey(this.config.keyPrefix, key), this.config, this.#client);
     }
 }
 // ---------------------------------------------------------------------------
 // S3 fetch with AWS SigV4 signing
 // ---------------------------------------------------------------------------
-export async function getS3JSON(key, config) {
+export async function getS3JSON(key, config, client) {
     const startTime = Date.now();
-    const url = s3ObjectURL(config, key);
-    const signedHeaders = signedS3Headers('GET', url, config);
-    const res = await fetch(url, {
-        method: 'GET',
-        headers: signedHeaders,
-        cache: 'no-store'
-    });
+    const res = await getS3Raw(key, config, client);
     const duration = Date.now() - startTime;
     console.log(`[ACI S3] GET ${key} - ${res.status} in ${duration}ms`);
     if (!res.ok) {
@@ -108,7 +106,9 @@ export async function getS3JSON(key, config) {
     }
     return (await res.json());
 }
-export async function getS3Raw(key, config) {
+export async function getS3Raw(key, config, client) {
+    if (client)
+        return await getS3RawWithClient(key, config, client);
     const url = s3ObjectURL(config, key);
     const signedHeaders = signedS3Headers('GET', url, config);
     return await fetch(url, {
@@ -122,20 +122,90 @@ export async function getS3Raw(key, config) {
 // ---------------------------------------------------------------------------
 function resolveS3Config(config) {
     const resolved = {
-        bucket: config.bucket || process.env.ACI_S3_BUCKET || '',
-        keyPrefix: config.keyPrefix || process.env.ACI_S3_KEY_PREFIX || '',
-        region: config.region || process.env.AWS_REGION || 'us-east-1',
-        accessKeyId: config.accessKeyId || process.env.AWS_ACCESS_KEY_ID || '',
-        secretAccessKey: config.secretAccessKey || process.env.AWS_SECRET_ACCESS_KEY || '',
-        sessionToken: config.sessionToken || process.env.AWS_SESSION_TOKEN || '',
-        endpoint: trimSlash(config.endpoint || process.env.ACI_S3_ENDPOINT || '')
+        bucket: configuredValue(config.bucket, process.env.ACI_S3_BUCKET),
+        keyPrefix: configuredValue(config.keyPrefix, process.env.ACI_S3_KEY_PREFIX),
+        region: configuredValue(config.region, process.env.AWS_REGION) || 'us-east-1',
+        accessKeyId: configuredValue(config.accessKeyId, process.env.AWS_ACCESS_KEY_ID),
+        secretAccessKey: configuredValue(config.secretAccessKey, process.env.AWS_SECRET_ACCESS_KEY),
+        sessionToken: configuredValue(config.sessionToken, process.env.AWS_SESSION_TOKEN),
+        roleArn: configuredValue(config.roleArn, process.env.AWS_ROLE_ARN),
+        endpoint: trimSlash(configuredValue(config.endpoint, process.env.ACI_S3_ENDPOINT))
     };
-    for (const key of ['bucket', 'accessKeyId', 'secretAccessKey']) {
-        if (!resolved[key])
-            throw new Error(`S3 config missing ${key}`);
+    if (!resolved.bucket)
+        throw new Error('S3 config missing bucket');
+    if (!resolved.roleArn) {
+        if (resolved.accessKeyId && !resolved.secretAccessKey) {
+            throw new Error('S3 config missing secretAccessKey');
+        }
+        if (!resolved.accessKeyId && resolved.secretAccessKey) {
+            throw new Error('S3 config missing accessKeyId');
+        }
+        if (!resolved.accessKeyId) {
+            throw new Error('S3 config missing credential mode: set AWS_ROLE_ARN or both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY');
+        }
     }
     return resolved;
 }
+function oidcS3Client(config) {
+    if (!config.roleArn)
+        return undefined;
+    return new S3Client({
+        region: config.region,
+        ...(config.endpoint ? {
+            endpoint: config.endpoint,
+            forcePathStyle: true,
+        } : {}),
+        credentials: awsCredentialsProvider({
+            roleArn: config.roleArn,
+            clientConfig: { region: config.region },
+        }),
+    });
+}
+async function getS3RawWithClient(key, config, client) {
+    try {
+        const output = await client.send(new GetObjectCommand({
+            Bucket: config.bucket,
+            Key: key,
+        }));
+        if (!output.Body?.transformToWebStream) {
+            throw new Error(`S3 GET ${key} returned an unsupported object body`);
+        }
+        const headers = new Headers();
+        if (output.ContentType)
+            headers.set('content-type', output.ContentType);
+        if (output.ContentLength !== undefined) {
+            headers.set('content-length', String(output.ContentLength));
+        }
+        if (output.ETag)
+            headers.set('etag', output.ETag);
+        if (output.LastModified) {
+            headers.set('last-modified', output.LastModified.toUTCString());
+        }
+        return new Response(output.Body.transformToWebStream(), {
+            status: 200,
+            headers,
+        });
+    }
+    catch (error) {
+        const status = s3ErrorStatus(error);
+        if (status) {
+            return new Response(error instanceof Error ? error.message : String(error), { status });
+        }
+        throw new Error(`S3 GET ${key} failed`, { cause: error });
+    }
+}
+function s3ErrorStatus(error) {
+    if (!error || typeof error !== 'object')
+        return undefined;
+    const status = error
+        .$metadata?.httpStatusCode;
+    return typeof status === 'number' && status >= 400 && status <= 599
+        ? status
+        : undefined;
+}
+function configuredValue(configured, environment) {
+    return (configured === undefined ? environment : configured)?.trim() || '';
+}
 function s3ObjectURL(config, key) {
     const encodedKey = encodeKey(key);
     if (config.endpoint) {