@farukada/aws-langgraph-dynamodb-ts 0.8.0 → 1.0.0-rc.1

package/dist/shared/codec/s3/bounded-body.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oversizedObjectError = oversizedObjectError;
+exports.readBodyBounded = readBodyBounded;
+const base_error_1 = require("../../errors/base-error");
+const error_code_1 = require("../../errors/error-code");
+/** The typed error for an object over the download cap. */
+function oversizedObjectError(key, bytes, maxBytes) {
+    return new base_error_1.DynamoDBLangGraphError(`S3 object ${key} exceeds the ${maxBytes}-byte maxDownloadBytes cap ` +
+        `(${bytes} bytes declared or read)`, error_code_1.ErrorCode.S3_OFFLOAD_FAILED, { operation: 'download', key });
+}
+function concat(chunks, total) {
+    const out = new Uint8Array(total);
+    let offset = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return out;
+}
+/**
+ * Buffer an S3 body without ever holding more than `maxBytes` of it. A
+ * streaming body is consumed chunk by chunk and abandoned the moment the
+ * running total passes the cap; a body that only offers
+ * `transformToByteArray()` is read whole and then checked.
+ */
+async function readBodyBounded(body, key, maxBytes) {
+    const streaming = body;
+    const iterate = streaming[Symbol.asyncIterator];
+    if (typeof iterate !== 'function') {
+        const whole = new Uint8Array(await body.transformToByteArray());
+        if (whole.length > maxBytes)
+            throw oversizedObjectError(key, whole.length, maxBytes);
+        return whole;
+    }
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of { [Symbol.asyncIterator]: iterate.bind(streaming) }) {
+        total += chunk.length;
+        if (total > maxBytes) {
+            streaming.destroy?.();
+            throw oversizedObjectError(key, total, maxBytes);
+        }
+        chunks.push(chunk);
+    }
+    return concat(chunks, total);
+}

package/dist/shared/codec/s3/client-types.d.ts

@@ -0,0 +1,34 @@
+/** A region as the SDK accepts it: a string or a provider resolving to one. */
+export type S3RegionLike = string | (() => Promise<string>);
+/** A value an S3 client option can hold. */
+export type S3ClientOption = string | number | boolean | object | null | undefined;
+/**
+ * The S3 client options this library reads (`region`) or sets (`maxAttempts`),
+ * open to every other `S3ClientConfig` key.
+ */
+export interface S3ClientOptions {
+    region?: S3RegionLike;
+    maxAttempts?: number;
+    [option: string]: S3ClientOption;
+}
+/**
+ * Structural stand-in for `S3ClientConfig`, so the shipped declarations compile
+ * without the optional `@aws-sdk/client-s3` peer installed. A literal gets
+ * completion for the options the library uses; a typed `S3ClientConfig`
+ * variable is accepted as it is.
+ */
+export type S3ClientConfigLike = S3ClientOptions | object;
+/** The options of a config, read through the structural type. */
+export declare function s3ClientOptions(config: S3ClientConfigLike | undefined): S3ClientOptions;
+/** What every SDK command object carries: its `input`. */
+export interface S3CommandLike {
+    input: object;
+}
+/**
+ * The S3 client surface this library calls, typed structurally for the same
+ * reason. `S3Client` from `@aws-sdk/client-s3` satisfies it.
+ */
+export interface S3ClientLike {
+    send(command: S3CommandLike, options?: object): Promise<object>;
+    destroy(): void;
+}

package/dist/shared/codec/s3/client-types.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.s3ClientOptions = s3ClientOptions;
+/** The options of a config, read through the structural type. */
+function s3ClientOptions(config) {
+    return (config ?? {});
+}

package/dist/shared/codec/s3/client.d.ts

@@ -1,6 +1,12 @@
-import type { S3Client, S3ClientConfig } from '@aws-sdk/client-s3';
-/** Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. */
-export declare function loadS3Sdk(): Promise<typeof import('@aws-sdk/client-s3')>;
+import type { S3Client } from '@aws-sdk/client-s3';
+import type { S3ClientConfigLike } from './client-types';
+type S3Sdk = typeof import('@aws-sdk/client-s3');
+/**
+ * Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. A
+ * failed import is not cached, so an install or a fixed bundle can succeed on
+ * a later call.
+ */
+export declare function loadS3Sdk(): Promise<S3Sdk>;
 /**
  * Construct an `S3Client` from `config` using the lazily-loaded SDK. Defaults
  * `maxAttempts: 1` so the SDK's own internal retries are disabled and this
@@ -8,5 +14,5 @@ export declare function loadS3Sdk(): Promise<typeof import('@aws-sdk/client-s3')
  * matching {@link resolveDynamoDBClient}'s equivalent default; an explicit
  * `maxAttempts` in `config` still wins.
  */
-export declare function createDefaultS3Client(config: S3ClientConfig): Promise<S3Client>;
-//# sourceMappingURL=client.d.ts.map
+export declare function createDefaultS3Client(config: S3ClientConfigLike): Promise<S3Client>;
+export {};

package/dist/shared/codec/s3/client.js

@@ -2,11 +2,34 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadS3Sdk = loadS3Sdk;
 exports.createDefaultS3Client = createDefaultS3Client;
+const errors_1 = require("../../errors/errors");
+/** Codes Node and bundlers use for an import that cannot be resolved. */
+const MISSING_MODULE_CODES = ['ERR_MODULE_NOT_FOUND', 'MODULE_NOT_FOUND'];
 let sdkPromise;
-/** Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. */
+/**
+ * Convert a failed import of the optional peer into a typed error that names
+ * the remedy. Any other failure (a broken build, a syntax error inside the
+ * package) passes through unchanged.
+ */
+function wrapMissingPeer(error) {
+    const code = error.code;
+    if (code !== undefined && MISSING_MODULE_CODES.includes(code)) {
+        throw new errors_1.ValidationError('S3 offload requires the optional peer @aws-sdk/client-s3 (npm install @aws-sdk/client-s3); ' +
+            'bundlers must keep it installed or external', 's3', error);
+    }
+    throw error;
+}
+/**
+ * Lazily import the optional `@aws-sdk/client-s3` peer, caching the module. A
+ * failed import is not cached, so an install or a fixed bundle can succeed on
+ * a later call.
+ */
 async function loadS3Sdk() {
     if (!sdkPromise) {
-        sdkPromise = import('@aws-sdk/client-s3');
+        sdkPromise = import('@aws-sdk/client-s3').catch((error) => {
+            sdkPromise = undefined;
+            return wrapMissingPeer(error);
+        });
     }
     return sdkPromise;
 }
@@ -21,4 +44,3 @@ async function createDefaultS3Client(config) {
     const { S3Client: S3ClientCtor } = await loadS3Sdk();
     return new S3ClientCtor({ maxAttempts: 1, ...config });
 }
-//# sourceMappingURL=client.js.map

package/dist/shared/codec/s3/config.d.ts

@@ -1,13 +1,26 @@
-import type { S3Client, S3ClientConfig } from '@aws-sdk/client-s3';
+import type { S3ClientConfigLike } from './client-types';
 /** Configuration for offloading large payloads to S3. */
 export interface S3OffloadConfig {
     bucketName: string;
     keyPrefix?: string;
+    /**
+     * Serialized payloads at or above this size are offloaded (default 350 KB).
+     * Only the payload counts: the store's inline embedding (about 10 bytes per
+     * dimension, so ~10 KB at 1024 dims and ~45 KB at 4096) lives on the same
+     * item and is not part of it, so keep `thresholdBytes` plus the embedding
+     * under DynamoDB's 400 KB item limit or the put fails with a raw
+     * `ValidationException`.
+     */
     thresholdBytes?: number;
     serverSideEncryption?: string;
     sseKmsKeyId?: string;
-    clientConfig?: S3ClientConfig;
-    createS3Client?: (config: S3ClientConfig) => S3Client;
+    /** Largest object this adapter will buffer from S3 (default 50 MiB). */
+    maxDownloadBytes?: number;
+    /**
+     * S3 client configuration (an `S3ClientConfig`). `region` defaults to the
+     * adapter's DynamoDB region.
+     */
+    clientConfig?: S3ClientConfigLike;
 }
 /**
  * Build a fully-qualified S3 key: `${prefix}${parts, each base64url-encoded,
@@ -15,10 +28,24 @@ export interface S3OffloadConfig {
  * `parts` arrays never collide, since a namespace element or key is allowed
  * to contain '/' (only the DynamoDB '#' separator is forbidden at the
  * validation layer) and base64url's output alphabet never contains '/'.
+ *
+ * The produced key is checked against S3's 1024-byte object-key cap: the
+ * encoding grows every part by a third, so identifiers that each pass their
+ * own length rule can still compose a key S3 would reject with a raw error.
  */
 export declare function buildS3Key(prefix: string, parts: readonly string[]): string;
-/** Build a deterministic, TTL-independent lifecycle rule id from the prefix. */
+/**
+ * The key prefix doubles as the S3 lifecycle rule's `Filter.Prefix`. An empty
+ * or root prefix would make that rule expire the whole bucket, and a prefix
+ * without a trailing `/` (`app/langgraph`) would also match every sibling
+ * object that merely starts with the same characters (`app/langgraph-other/`).
+ */
+export declare function assertScopedKeyPrefix(keyPrefix: string): void;
+/**
+ * Build a deterministic, TTL-independent lifecycle rule id from the prefix.
+ * Trailing slashes are trimmed with a loop rather than `/\/+$/`, whose
+ * backtracking is quadratic in the number of slashes.
+ */
 export declare function buildLifecycleRuleId(prefix: string): string;
 /** An adapter's default S3 key prefix: the shared base plus its own segment. */
 export declare function defaultAdapterKeyPrefix(base: string, adapter: string): string;
-//# sourceMappingURL=config.d.ts.map

package/dist/shared/codec/s3/config.js

@@ -1,26 +1,58 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.buildS3Key = buildS3Key;
+exports.assertScopedKeyPrefix = assertScopedKeyPrefix;
 exports.buildLifecycleRuleId = buildLifecycleRuleId;
 exports.defaultAdapterKeyPrefix = defaultAdapterKeyPrefix;
+const constants_1 = require("../../constants");
+const errors_1 = require("../../errors/errors");
+const key_scope_1 = require("./key-scope");
 /**
  * Build a fully-qualified S3 key: `${prefix}${parts, each base64url-encoded,
  * joined with '/'}.bin`. Encoding (not rejecting) is what makes two distinct
  * `parts` arrays never collide, since a namespace element or key is allowed
  * to contain '/' (only the DynamoDB '#' separator is forbidden at the
  * validation layer) and base64url's output alphabet never contains '/'.
+ *
+ * The produced key is checked against S3's 1024-byte object-key cap: the
+ * encoding grows every part by a third, so identifiers that each pass their
+ * own length rule can still compose a key S3 would reject with a raw error.
  */
 function buildS3Key(prefix, parts) {
-    const encoded = parts.map((part) => Buffer.from(part, 'utf8').toString('base64url'));
-    return `${prefix}${encoded.join('/')}.bin`;
+    const encoded = parts.map(key_scope_1.encodeKeyPart);
+    const key = `${prefix}${encoded.join('/')}.bin`;
+    const bytes = Buffer.byteLength(key, 'utf8');
+    if (bytes > constants_1.MAX_S3_KEY_BYTES) {
+        throw new errors_1.ValidationError(`the offloaded S3 object key would be ${bytes} bytes; S3 caps keys at ` +
+            `${constants_1.MAX_S3_KEY_BYTES} — shorten the identifiers or the keyPrefix`, 's3Key');
+    }
+    return key;
 }
-/** Build a deterministic, TTL-independent lifecycle rule id from the prefix. */
+/**
+ * The key prefix doubles as the S3 lifecycle rule's `Filter.Prefix`. An empty
+ * or root prefix would make that rule expire the whole bucket, and a prefix
+ * without a trailing `/` (`app/langgraph`) would also match every sibling
+ * object that merely starts with the same characters (`app/langgraph-other/`).
+ */
+function assertScopedKeyPrefix(keyPrefix) {
+    if (keyPrefix === '' || keyPrefix === '/' || !keyPrefix.endsWith('/')) {
+        throw new errors_1.ValidationError('s3.keyPrefix must be a non-empty path that ends with "/" (for example "langgraph/"): ' +
+            'it scopes both the offloaded objects and the S3 lifecycle rule', 's3.keyPrefix');
+    }
+}
+/**
+ * Build a deterministic, TTL-independent lifecycle rule id from the prefix.
+ * Trailing slashes are trimmed with a loop rather than `/\/+$/`, whose
+ * backtracking is quadratic in the number of slashes.
+ */
 function buildLifecycleRuleId(prefix) {
-    const slug = prefix.replace(/\/+$/, '').replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
+    let trimmed = prefix;
+    while (trimmed.endsWith('/'))
+        trimmed = trimmed.slice(0, -1);
+    const slug = trimmed.replace(/[^a-zA-Z0-9-]/g, '-') || 'default';
     return `langgraph-ttl-${slug}`;
 }
 /** An adapter's default S3 key prefix: the shared base plus its own segment. */
 function defaultAdapterKeyPrefix(base, adapter) {
     return `${base}${adapter}/`;
 }
-//# sourceMappingURL=config.js.map

package/dist/shared/codec/s3/delete.d.ts

@@ -5,4 +5,3 @@ import type { S3Client } from '@aws-sdk/client-s3';
  * callers (orphan cleanup) can decide how loudly to react.
  */
 export declare function deleteObjects(client: S3Client, bucket: string, keys: string[]): Promise<string[]>;
-//# sourceMappingURL=delete.d.ts.map

package/dist/shared/codec/s3/delete.js

@@ -26,4 +26,3 @@ async function deleteObjects(client, bucket, keys) {
     }
     return failed;
 }
-//# sourceMappingURL=delete.js.map

package/dist/shared/codec/s3/key-scope.d.ts

@@ -0,0 +1,23 @@
+/** base64url-encode one key part; the output alphabet never contains `/` or `.`. */
+export declare function encodeKeyPart(part: string): string;
+/**
+ * The path every key `buildS3Key(prefix, [...parts, ...more])` shares: the
+ * prefix plus the encoded `parts` joined by `/`, with neither `.bin` nor a
+ * trailing `/`.
+ */
+export declare function s3KeyScope(prefix: string, parts: readonly string[]): string;
+/**
+ * True when `key` was produced by `buildS3Key` from exactly `parts`
+ * (`<scope>.bin`) or from `parts` plus further parts (`<scope>/…`). An empty
+ * `parts` degrades to a prefix-only check. Because parts are base64url-encoded
+ * and joined by `/`, an identifier sharing a leading substring with another
+ * (`t` and `t1`) never matches its scope.
+ */
+export declare function isKeyInScope(key: string, prefix: string, parts: readonly string[]): boolean;
+/**
+ * Refuse a row-sourced `s3Key` that lies outside the path the row's own
+ * identifiers produce. A row is trusted for its shape, not for the object it
+ * points at: a writer able to place one row in a partition must not be able
+ * to make this library download or delete another tenant's object.
+ */
+export declare function assertKeyInScope(key: string, prefix: string, parts: readonly string[]): void;

package/dist/shared/codec/s3/key-scope.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeKeyPart = encodeKeyPart;
+exports.s3KeyScope = s3KeyScope;
+exports.isKeyInScope = isKeyInScope;
+exports.assertKeyInScope = assertKeyInScope;
+const errors_1 = require("../../errors/errors");
+/** base64url-encode one key part; the output alphabet never contains `/` or `.`. */
+function encodeKeyPart(part) {
+    return Buffer.from(part, 'utf8').toString('base64url');
+}
+/**
+ * The path every key `buildS3Key(prefix, [...parts, ...more])` shares: the
+ * prefix plus the encoded `parts` joined by `/`, with neither `.bin` nor a
+ * trailing `/`.
+ */
+function s3KeyScope(prefix, parts) {
+    return `${prefix}${parts.map(encodeKeyPart).join('/')}`;
+}
+/**
+ * True when `key` was produced by `buildS3Key` from exactly `parts`
+ * (`<scope>.bin`) or from `parts` plus further parts (`<scope>/…`). An empty
+ * `parts` degrades to a prefix-only check. Because parts are base64url-encoded
+ * and joined by `/`, an identifier sharing a leading substring with another
+ * (`t` and `t1`) never matches its scope.
+ */
+function isKeyInScope(key, prefix, parts) {
+    const scope = s3KeyScope(prefix, parts);
+    if (parts.length === 0)
+        return key.startsWith(scope);
+    return key === `${scope}.bin` || key.startsWith(`${scope}/`);
+}
+/**
+ * Refuse a row-sourced `s3Key` that lies outside the path the row's own
+ * identifiers produce. A row is trusted for its shape, not for the object it
+ * points at: a writer able to place one row in a partition must not be able
+ * to make this library download or delete another tenant's object.
+ */
+function assertKeyInScope(key, prefix, parts) {
+    if (isKeyInScope(key, prefix, parts))
+        return;
+    throw new errors_1.ValidationError(`s3Key "${key}" lies outside the S3 path this row may reference ` +
+        `("${s3KeyScope(prefix, parts)}"); refusing to touch an object the row does not own`, 's3Key');
+}

package/dist/shared/codec/s3/lifecycle.d.ts

@@ -1,8 +1,14 @@
 import type { S3Client } from '@aws-sdk/client-s3';
 /**
- * Idempotently ensure a `${ttlDays}`-day expiration lifecycle rule exists for
- * `prefix`. Reads existing rules, preserves user-defined ones, and only
- * adds/updates the library's prefix-scoped rule.
+ * Idempotently ensure a `days`-day expiration lifecycle rule exists for
+ * `prefix`. Reads existing rules, preserves user-defined ones and the
+ * bucket-level `TransitionDefaultMinimumObjectSize` (a Put replaces the whole
+ * configuration, so dropping it would reset the bucket to the default), and
+ * only adds/updates the library's prefix-scoped rule.
+ *
+ * Noncurrent versions expire after the same number of days, so a versioned
+ * bucket does not retain every superseded payload forever; the field is inert
+ * on an unversioned bucket. The prefix is re-checked here because this rule is
+ * the one place an unscoped prefix would destroy data outside this library's.
  */
-export declare function ensureLifecycleRule(client: S3Client, bucket: string, prefix: string, ttlDays: number): Promise<void>;
-//# sourceMappingURL=lifecycle.d.ts.map
+export declare function ensureLifecycleRule(client: S3Client, bucket: string, prefix: string, days: number): Promise<void>;

package/dist/shared/codec/s3/lifecycle.js

@@ -3,45 +3,61 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ensureLifecycleRule = ensureLifecycleRule;
 const client_1 = require("./client");
 const config_1 = require("./config");
-async function readRules(client, bucket) {
+async function readState(client, bucket) {
     const { GetBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
     try {
         const existing = await client.send(new GetBucketLifecycleConfigurationCommand({ Bucket: bucket }));
-        return existing.Rules ?? [];
+        return {
+            rules: existing.Rules ?? [],
+            transitionDefaultMinimumObjectSize: existing.TransitionDefaultMinimumObjectSize,
+        };
     }
     catch (error) {
         if (error.name === 'NoSuchLifecycleConfiguration')
-            return [];
+            return { rules: [] };
         throw error;
     }
 }
-function alreadyCorrect(rule, ttlDays) {
-    return rule?.Status === 'Enabled' && rule.Expiration?.Days === ttlDays;
+function alreadyCorrect(rule, days) {
+    return (rule?.Status === 'Enabled' &&
+        rule.Expiration?.Days === days &&
+        rule.NoncurrentVersionExpiration?.NoncurrentDays === days);
 }
 /**
- * Idempotently ensure a `${ttlDays}`-day expiration lifecycle rule exists for
- * `prefix`. Reads existing rules, preserves user-defined ones, and only
- * adds/updates the library's prefix-scoped rule.
+ * Idempotently ensure a `days`-day expiration lifecycle rule exists for
+ * `prefix`. Reads existing rules, preserves user-defined ones and the
+ * bucket-level `TransitionDefaultMinimumObjectSize` (a Put replaces the whole
+ * configuration, so dropping it would reset the bucket to the default), and
+ * only adds/updates the library's prefix-scoped rule.
+ *
+ * Noncurrent versions expire after the same number of days, so a versioned
+ * bucket does not retain every superseded payload forever; the field is inert
+ * on an unversioned bucket. The prefix is re-checked here because this rule is
+ * the one place an unscoped prefix would destroy data outside this library's.
  */
-async function ensureLifecycleRule(client, bucket, prefix, ttlDays) {
+async function ensureLifecycleRule(client, bucket, prefix, days) {
+    (0, config_1.assertScopedKeyPrefix)(prefix);
     const ruleId = (0, config_1.buildLifecycleRuleId)(prefix);
-    const rules = await readRules(client, bucket);
-    const existing = rules.find((rule) => rule.ID === ruleId);
-    if (alreadyCorrect(existing, ttlDays))
+    const state = await readState(client, bucket);
+    const existing = state.rules.find((rule) => rule.ID === ruleId);
+    if (alreadyCorrect(existing, days))
         return;
     const newRule = {
         ID: ruleId,
         Filter: { Prefix: prefix },
         Status: 'Enabled',
-        Expiration: { Days: ttlDays },
+        Expiration: { Days: days },
+        NoncurrentVersionExpiration: { NoncurrentDays: days },
     };
     const merged = existing
-        ? rules.map((rule) => (rule.ID === ruleId ? newRule : rule))
-        : [...rules, newRule];
+        ? state.rules.map((rule) => (rule.ID === ruleId ? newRule : rule))
+        : [...state.rules, newRule];
     const { PutBucketLifecycleConfigurationCommand } = await (0, client_1.loadS3Sdk)();
     await client.send(new PutBucketLifecycleConfigurationCommand({
         Bucket: bucket,
         LifecycleConfiguration: { Rules: merged },
+        ...(state.transitionDefaultMinimumObjectSize === undefined
+            ? {}
+            : { TransitionDefaultMinimumObjectSize: state.transitionDefaultMinimumObjectSize }),
     }));
 }
-//# sourceMappingURL=lifecycle.js.map

package/dist/shared/codec/s3/offloader.d.ts

@@ -12,6 +12,7 @@ export declare class S3Offloader {
     private readonly thresholdBytes;
     private readonly sse;
     private readonly sseKmsKeyId?;
+    private readonly maxDownloadBytes;
     private readonly config;
     constructor(config: S3OffloadConfig);
     private getClient;
@@ -21,9 +22,13 @@ export declare class S3Offloader {
     buildKey(parts: readonly string[]): string;
     /** The configured key prefix. */
     getKeyPrefix(): string;
+    /** True when `key` lies under this offloader's prefix and the `scope` parts' path. */
+    ownsKey(key: string, scope: readonly string[]): boolean;
+    /** Refuse a row-sourced key outside the row's own path (see {@link assertKeyInScope}). */
+    assertOwnedKey(key: string, scope: readonly string[]): void;
     /** Upload `data` under `key`, returning the key. */
     upload(key: string, data: Uint8Array): Promise<string>;
-    /** Download the bytes stored under `key`. */
+    /** Download the bytes stored under `key`, refusing objects over `maxDownloadBytes`. */
     download(key: string): Promise<Uint8Array>;
     /** Delete `keys`, returning the keys S3 reported as failed. */
     deleteBatch(keys: string[]): Promise<string[]>;
@@ -37,4 +42,3 @@ export declare class S3Offloader {
      */
     destroy(): void;
 }
-//# sourceMappingURL=offloader.d.ts.map

package/dist/shared/codec/s3/offloader.js

@@ -5,6 +5,7 @@ const constants_1 = require("../../constants");
 const client_1 = require("./client");
 const config_1 = require("./config");
 const delete_1 = require("./delete");
+const key_scope_1 = require("./key-scope");
 const lifecycle_1 = require("./lifecycle");
 const read_write_1 = require("./read-write");
 /**
@@ -20,6 +21,7 @@ class S3Offloader {
     thresholdBytes;
     sse;
     sseKmsKeyId;
+    maxDownloadBytes;
     config;
     constructor(config) {
         this.config = config;
@@ -28,10 +30,19 @@ class S3Offloader {
         this.thresholdBytes = config.thresholdBytes ?? constants_1.DEFAULT_S3_THRESHOLD_BYTES;
         this.sse = config.serverSideEncryption ?? constants_1.DEFAULT_S3_SSE;
         this.sseKmsKeyId = config.sseKmsKeyId;
+        this.maxDownloadBytes = config.maxDownloadBytes ?? constants_1.DEFAULT_MAX_S3_DOWNLOAD_BYTES;
+        /**
+         * Warm the optional peer's import so a missing `@aws-sdk/client-s3`
+         * surfaces on the very first S3 operation, typed, rather than on the first
+         * oversize payload days later. The rejection is handled here; whichever
+         * operation runs first re-raises it through its own `loadS3Sdk()` call.
+         */
+        void (0, client_1.loadS3Sdk)().catch(() => undefined);
     }
     getClient() {
         if (!this.clientPromise) {
             const cfg = this.config.clientConfig ?? {};
+            /** The hook is typed structurally for consumers; the runtime modules use the real SDK client. */
             this.clientPromise = (this.config.createS3Client
                 ? Promise.resolve(this.config.createS3Client({ maxAttempts: 1, ...cfg }))
                 : (0, client_1.createDefaultS3Client)(cfg)).then((client) => {
@@ -62,6 +73,14 @@ class S3Offloader {
     getKeyPrefix() {
         return this.keyPrefix;
     }
+    /** True when `key` lies under this offloader's prefix and the `scope` parts' path. */
+    ownsKey(key, scope) {
+        return (0, key_scope_1.isKeyInScope)(key, this.keyPrefix, scope);
+    }
+    /** Refuse a row-sourced key outside the row's own path (see {@link assertKeyInScope}). */
+    assertOwnedKey(key, scope) {
+        (0, key_scope_1.assertKeyInScope)(key, this.keyPrefix, scope);
+    }
     /** Upload `data` under `key`, returning the key. */
     async upload(key, data) {
         await (0, read_write_1.uploadObject)(await this.getClient(), {
@@ -73,9 +92,9 @@ class S3Offloader {
         });
         return key;
     }
-    /** Download the bytes stored under `key`. */
+    /** Download the bytes stored under `key`, refusing objects over `maxDownloadBytes`. */
     async download(key) {
-        return (0, read_write_1.downloadObject)(await this.getClient(), this.bucketName, key);
+        return (0, read_write_1.downloadObject)(await this.getClient(), this.bucketName, key, this.maxDownloadBytes);
     }
     /** Delete `keys`, returning the keys S3 reported as failed. */
     async deleteBatch(keys) {
@@ -97,4 +116,3 @@ class S3Offloader {
     }
 }
 exports.S3Offloader = S3Offloader;
-//# sourceMappingURL=offloader.js.map

package/dist/shared/codec/s3/orphans.d.ts

@@ -5,6 +5,12 @@ export interface OrphanCleanupOptions {
     rng?: () => number;
     maxAttempts?: number;
     signal?: AbortSignal;
+    /**
+     * The row's own leading key parts when `keys` were read back from a row.
+     * A key outside the path they produce is never deleted, only reported; own
+     * uploads (built by this call) pass no scope.
+     */
+    scope?: readonly string[];
 }
 /**
  * Best-effort delete of S3 objects orphaned by a failed DynamoDB write. Retries
@@ -15,4 +21,3 @@ export interface OrphanCleanupOptions {
  * `ensureS3LifecycleRule()`, which is opt-in.
  */
 export declare function cleanUpS3Orphans(offloader: S3Offloader, keys: ReadonlyArray<string | undefined>, context: string, logger: Logger, options?: OrphanCleanupOptions): Promise<void>;
-//# sourceMappingURL=orphans.d.ts.map

package/dist/shared/codec/s3/orphans.js

@@ -19,6 +19,20 @@ async function backoffSleep(delayMs, options) {
         return true;
     }
 }
+/** Drop every key outside the row's scope, reporting each one. */
+function ownedOnly(offloader, keys, scope, context, logger) {
+    return keys.filter((key) => {
+        if (offloader.ownsKey(key, scope))
+            return true;
+        logger.warn(`${context}: refusing to delete an S3 object outside this row's scope`, { key });
+        return false;
+    });
+}
+/** The non-empty keys, restricted to the row's scope when one is given. */
+function selectOrphans(offloader, keys, context, logger, options) {
+    const present = keys.filter((key) => typeof key === 'string' && key.length > 0);
+    return options.scope ? ownedOnly(offloader, present, options.scope, context, logger) : present;
+}
 /**
  * Best-effort delete of S3 objects orphaned by a failed DynamoDB write. Retries
  * transient errors with full-jitter backoff; on persistent failure or when S3
@@ -28,7 +42,7 @@ async function backoffSleep(delayMs, options) {
  * `ensureS3LifecycleRule()`, which is opt-in.
  */
 async function cleanUpS3Orphans(offloader, keys, context, logger, options = {}) {
-    const orphans = keys.filter((key) => typeof key === 'string' && key.length > 0);
+    const orphans = selectOrphans(offloader, keys, context, logger, options);
     if (orphans.length === 0)
         return;
     const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
@@ -55,4 +69,3 @@ async function cleanUpS3Orphans(offloader, keys, context, logger, options = {})
         message: lastError.message,
     });
 }
-//# sourceMappingURL=orphans.js.map

package/dist/shared/codec/s3/read-write.d.ts

@@ -9,6 +9,10 @@ export interface UploadParams {
 }
 /** Upload `data` to S3, wrapping failures as `S3_OFFLOAD_FAILED`. */
 export declare function uploadObject(client: S3Client, params: UploadParams): Promise<void>;
-/** Download an object's bytes, wrapping failures/empty bodies as `S3_OFFLOAD_FAILED`. */
-export declare function downloadObject(client: S3Client, bucket: string, key: string): Promise<Uint8Array>;
-//# sourceMappingURL=read-write.d.ts.map
+/**
+ * Download an object's bytes, wrapping failures/empty bodies as
+ * `S3_OFFLOAD_FAILED`. An object over `maxBytes` is refused from its declared
+ * `ContentLength` before the body is touched, or while streaming when the
+ * length is unknown, so a replaced or hostile object can never exhaust memory.
+ */
+export declare function downloadObject(client: S3Client, bucket: string, key: string, maxBytes: number): Promise<Uint8Array>;