lambder 6.0.1 → 7.0.1

package/dist/stores/LambderDdbRateLimiter.js

@@ -1,17 +1,6 @@
-import { loadDynamoClientSdk } from "./LambderDdbSdk.js";
-/**
- * The fixed windows a policy may cap, smallest first (the evaluation order),
- * with their length. The policy type derives from this table, so the two can
- * never drift.
- */
-export const RATE_LIMIT_WINDOWS = [
-    { key: "perMin", seconds: 60 },
-    { key: "per10Min", seconds: 10 * 60 },
-    { key: "perHour", seconds: 60 * 60 },
-    { key: "perDay", seconds: 24 * 60 * 60 },
-    { key: "perWeek", seconds: 7 * 24 * 60 * 60 },
-    { key: "perMonth", seconds: 30 * 24 * 60 * 60 },
-];
+import { assertPartitionKeyFits, createDynamoClientLoader, isConditionalCheckFailure, } from "./LambderDdbSdk.js";
+import { assertNumberAtLeast } from "../shared/util/LambderOptionChecks.js";
+import { RATE_LIMIT_WINDOWS, } from "../shared/contracts/LambderRateLimiter.js";
 /**
  * Fixed-window rate limiter backed by DynamoDB.
  *
@@ -24,39 +13,41 @@ export const RATE_LIMIT_WINDOWS = [
  * would give up the conditional-ADD atomicity). Items carry an `expiresAt`
  * attribute for DynamoDB TTL.
  *
+ * The tracker key is caller data (an address, a session key, whatever a
+ * policy handler returned), so a key whose partition key would pass
+ * DynamoDB's 2048-byte limit is refused here, before any window is counted,
+ * rather than reaching the table and coming back as a ValidationException:
+ * that is not a conditional-check failure, so it escapes as a store error and
+ * a caller failing open on it counts nothing at all, which is the limit
+ * silently off. Lambder's own engine folds an over-long key into a digest
+ * long before this, so a key that gets here came from a direct caller.
+ *
+ * A DynamoDB error propagates: a limiter says whether the caller is over its
+ * limit, and it cannot answer that question when it cannot reach the table.
+ * Whether an unanswerable limit lets the request through is the application's
+ * call, not the storage's, so it is made once for every limiter at
+ * `rateLimits.failOpen` and the engine there handles the throw.
+ *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on `expiresAt`.
  * Items are prefixed `RL#` by default, so the table can be shared with
- * LambderDdbCache (`CACHE#`) and LambderDdbIdempotency (`IDEM#`) without key
+ * LambderDdbCache (`CACHE#`) and LambderDdbIdempotencyStore (`IDEM#`) without key
  * collisions.
  */
 export class LambderDdbRateLimiter {
     tableName;
     keyPrefix;
-    /** The client given at creation, or one created from `region` on first use; the SDK arrives with it. */
-    providedClient;
-    region;
-    readyPromise;
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    ready;
     ttlWindowMultiplier;
-    failOpen;
+    now;
     constructor(options) {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
         this.tableName = options.tableName;
         this.keyPrefix = options.keyPrefix ?? "RL";
-        this.ttlWindowMultiplier = options.ttlWindowMultiplier ?? 2;
-        if (!Number.isFinite(this.ttlWindowMultiplier) || this.ttlWindowMultiplier < 1) {
-            throw new Error("ttlWindowMultiplier must be a number greater than or equal to 1");
-        }
-        this.failOpen = options.failOpen ?? false;
-        this.providedClient = options.client;
-        this.region = options.region;
-    }
-    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
-    ready() {
-        this.readyPromise ??= loadDynamoClientSdk("LambderDdbRateLimiter")
-            .then((sdk) => ({ sdk, client: this.providedClient ?? new sdk.DynamoDBClient(this.region ? { region: this.region } : {}) }))
-            .catch((error) => { this.readyPromise = undefined; throw error; });
-        return this.readyPromise;
+        this.ttlWindowMultiplier = assertNumberAtLeast(options.ttlWindowMultiplier ?? 2, 1, "ttlWindowMultiplier");
+        this.now = options.now ?? (() => Date.now());
+        this.ready = createDynamoClientLoader({ user: "LambderDdbRateLimiter", region: options.region, client: options.client });
     }
     /**
      * Increment every configured window for `trackerKey` (IP, session, user id, ...)
@@ -64,25 +55,39 @@ export class LambderDdbRateLimiter {
      * reset time when so.
      */
     async isRateLimited(trackerKey, policy) {
-        const nowSeconds = Math.floor(Date.now() / 1000);
+        const nowSeconds = Math.floor(this.now() / 1000);
+        // Once for the whole call, and before the first window is counted: a
+        // key the table will not take fails every window the same way, so
+        // refusing it here is the difference between one clear error and a
+        // policy that counts nothing while reporting nothing.
+        const partitionKey = this.partitionKeyFor(trackerKey);
         for (const { key, seconds } of RATE_LIMIT_WINDOWS) {
             const limit = policy[key];
             if (!limit)
                 continue;
             const windowStart = Math.floor(nowSeconds / seconds) * seconds;
-            const exceeded = await this.incrementWindow(trackerKey, key, windowStart, seconds, limit, nowSeconds);
+            const exceeded = await this.incrementWindow(partitionKey, key, windowStart, seconds, limit, nowSeconds);
             if (exceeded)
                 return { window: key, limit, resetAt: windowStart + seconds };
         }
         return false;
     }
+    /** The item's partition key, refused when the tracker key makes it one DynamoDB will not take. */
+    partitionKeyFor(trackerKey) {
+        return assertPartitionKeyFits({
+            user: "LambderDdbRateLimiter",
+            what: "tracker key",
+            partitionKey: `${this.keyPrefix}#${trackerKey}`,
+            remedy: "Shorten the key the policy hands the limiter.",
+        });
+    }
     /** Increments one window counter. Returns true when the limit was already reached. */
-    async incrementWindow(trackerKey, sortKeyPrefix, windowStart, windowSeconds, limit, nowSeconds) {
+    async incrementWindow(partitionKey, sortKeyPrefix, windowStart, windowSeconds, limit, nowSeconds) {
         const expiresAt = nowSeconds + Math.ceil(windowSeconds * this.ttlWindowMultiplier);
         const input = {
             TableName: this.tableName,
             Key: {
-                pk: { S: `${this.keyPrefix}#${trackerKey}` },
+                pk: { S: partitionKey },
                 sk: { S: `${sortKeyPrefix}#${windowStart}` },
             },
             UpdateExpression: "ADD #count :one SET #expiresAt = if_not_exists(#expiresAt, :expiresAt)",
@@ -100,14 +105,11 @@ export class LambderDdbRateLimiter {
             return false;
         }
         catch (error) {
-            if (error.name === "ConditionalCheckFailedException")
+            // The refused condition is the limiter's own answer; anything else
+            // is the table being unreachable, which only the caller can decide
+            // what to do about.
+            if (isConditionalCheckFailure(error))
                 return true;
-            if (this.failOpen) {
-                // Failing open swallows the error from the caller's view, so
-                // keep the infra failure visible in the logs.
-                console.error(`LambderDdbRateLimiter: DynamoDB error while counting "${trackerKey}", allowing the request (failOpen).`, error);
-                return false;
-            }
             throw error;
         }
     }

package/dist/stores/LambderDdbSdk.d.ts

@@ -11,10 +11,87 @@
  * LambderInvokeCaller load theirs. One loader per package, memoized for the
  * container's life; a missing package fails that first call with the
  * install hint rather than failing the import of lambder itself.
+ *
+ * The two facts about DynamoDB itself that every one of those stores has to
+ * agree on live here as well, for the same reason: a conditional write's
+ * refusal is an answer rather than a failure, and a partition key has a
+ * limit that the caller data these stores build keys from can pass.
+ */
+import type { DynamoDBClient } from "@aws-sdk/client-dynamodb";
+import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+type LambderDynamoClientSdk = typeof import("@aws-sdk/client-dynamodb");
+type LambderDynamoDocumentSdk = typeof import("@aws-sdk/lib-dynamodb");
+/** What every DynamoDB-backed store needs before it can touch its table: the SDK, and a client made with it. */
+export type LambderDynamoClientReady = {
+    client: DynamoDBClient;
+    sdk: LambderDynamoClientSdk;
+};
+/**
+ * The "ready" step each DynamoDB-backed store runs before its first table
+ * call: load the SDK, then take the client the app supplied or build one.
+ * Memoized for the store's life, and a FAILED load is deliberately not, so a
+ * store that ran before the package was installed asks again rather than
+ * caching the install hint for ever.
+ *
+ * Written once because four stores had written it for themselves and had
+ * already drifted apart on the region: three passed the SDK's default chain
+ * through and the cache pinned `us-east-1`, so one store out of four ignored
+ * the deployment's own region.
+ *
+ * `region` absent means the SDK's default chain (`AWS_REGION`, the Lambda
+ * environment, the shared config file), which is what a store should leave
+ * alone unless the caller names one.
+ */
+export declare const createDynamoClientLoader: (options: {
+    user: string;
+    region?: string;
+    client?: DynamoDBClient;
+}) => (() => Promise<LambderDynamoClientReady>);
+/** What the session store needs before its first table call: the document SDK, and a document client made with it. */
+export type LambderDynamoDocumentClientReady = {
+    client: DynamoDBDocumentClient;
+    sdk: LambderDynamoDocumentSdk;
+};
+/**
+ * The document-client twin of createDynamoClientLoader, for the one store
+ * that speaks the document API. A supplied client is taken as is, and then
+ * only `@aws-sdk/lib-dynamodb` is loaded: the item-level package is needed
+ * only to construct a client of our own.
+ */
+export declare const createDynamoDocumentClientLoader: (options: {
+    user: string;
+    region?: string;
+    client?: DynamoDBDocumentClient;
+}) => (() => Promise<LambderDynamoDocumentClientReady>);
+/**
+ * Whether DynamoDB refused a write because its condition did not hold, which
+ * is how every conditional write here reports the thing it was testing for: a
+ * claim already taken, a counter at its limit, a lease somebody else holds.
+ * An answer, not a failure, so it is the one error class these stores catch
+ * and the reason they must not catch any other.
+ */
+export declare const isConditionalCheckFailure: (error: unknown) => boolean;
+/**
+ * DynamoDB's own limit on a partition key, which every store's
+ * `<keyPrefix>#<caller data>` key has to fit inside.
+ */
+export declare const MAX_PARTITION_KEY_BYTES = 2048;
+/**
+ * The partition key, or a refusal naming the byte count. Every store here
+ * builds its key out of caller data (an idempotency key and the identity it
+ * is scoped by, a rate-limit key a policy handler returned), so the length is
+ * the caller's to reach and this is the one place that measures it.
+ *
+ * Checked rather than left to DynamoDB, which answers an over-long key with a
+ * ValidationException: that is not a ConditionalCheckFailedException, so it
+ * escapes as a store error that reads as "the table is broken" and, under a
+ * fail-open setting, is swallowed into no protection at all. The message
+ * carries the count and never the key, because it reaches a log.
  */
-export type LambderDynamoClientSdk = typeof import("@aws-sdk/client-dynamodb");
-export type LambderDynamoDocumentSdk = typeof import("@aws-sdk/lib-dynamodb");
-/** `@aws-sdk/client-dynamodb`, for the item-level API the stores speak and the client the session manager wraps. */
-export declare const loadDynamoClientSdk: (user: string) => Promise<LambderDynamoClientSdk>;
-/** `@aws-sdk/lib-dynamodb`, the document client the session manager reads and writes through. */
-export declare const loadDynamoDocumentSdk: (user: string) => Promise<LambderDynamoDocumentSdk>;
+export declare const assertPartitionKeyFits: (options: {
+    user: string;
+    what: string;
+    partitionKey: string;
+    remedy: string;
+}) => string;
+export {};

package/dist/stores/LambderDdbSdk.js

@@ -11,6 +11,11 @@
  * LambderInvokeCaller load theirs. One loader per package, memoized for the
  * container's life; a missing package fails that first call with the
  * install hint rather than failing the import of lambder itself.
+ *
+ * The two facts about DynamoDB itself that every one of those stores has to
+ * agree on live here as well, for the same reason: a conditional write's
+ * refusal is an answer rather than a failure, and a partition key has a
+ * limit that the caller data these stores build keys from can pass.
  */
 let clientSdk;
 let documentSdk;
@@ -20,12 +25,88 @@ const withInstallHint = (loading, packageName, user, reset) => loading.catch((ca
     throw new Error(`${user} requires ${packageName}: npm install ${packageName}`, { cause });
 });
 /** `@aws-sdk/client-dynamodb`, for the item-level API the stores speak and the client the session manager wraps. */
-export const loadDynamoClientSdk = (user) => {
+const loadDynamoClientSdk = (user) => {
     clientSdk ??= withInstallHint(import("@aws-sdk/client-dynamodb"), "@aws-sdk/client-dynamodb", user, () => { clientSdk = undefined; });
     return clientSdk;
 };
 /** `@aws-sdk/lib-dynamodb`, the document client the session manager reads and writes through. */
-export const loadDynamoDocumentSdk = (user) => {
+const loadDynamoDocumentSdk = (user) => {
     documentSdk ??= withInstallHint(import("@aws-sdk/lib-dynamodb"), "@aws-sdk/lib-dynamodb", user, () => { documentSdk = undefined; });
     return documentSdk;
 };
+/**
+ * The "ready" step each DynamoDB-backed store runs before its first table
+ * call: load the SDK, then take the client the app supplied or build one.
+ * Memoized for the store's life, and a FAILED load is deliberately not, so a
+ * store that ran before the package was installed asks again rather than
+ * caching the install hint for ever.
+ *
+ * Written once because four stores had written it for themselves and had
+ * already drifted apart on the region: three passed the SDK's default chain
+ * through and the cache pinned `us-east-1`, so one store out of four ignored
+ * the deployment's own region.
+ *
+ * `region` absent means the SDK's default chain (`AWS_REGION`, the Lambda
+ * environment, the shared config file), which is what a store should leave
+ * alone unless the caller names one.
+ */
+export const createDynamoClientLoader = (options) => {
+    let readyPromise;
+    return () => {
+        readyPromise ??= loadDynamoClientSdk(options.user)
+            .then((sdk) => ({ sdk, client: options.client ?? new sdk.DynamoDBClient(options.region ? { region: options.region } : {}) }))
+            .catch((error) => { readyPromise = undefined; throw error; });
+        return readyPromise;
+    };
+};
+/**
+ * The document-client twin of createDynamoClientLoader, for the one store
+ * that speaks the document API. A supplied client is taken as is, and then
+ * only `@aws-sdk/lib-dynamodb` is loaded: the item-level package is needed
+ * only to construct a client of our own.
+ */
+export const createDynamoDocumentClientLoader = (options) => {
+    let readyPromise;
+    const build = async () => {
+        if (options.client)
+            return { sdk: await loadDynamoDocumentSdk(options.user), client: options.client };
+        const [clientSdk, sdk] = await Promise.all([loadDynamoClientSdk(options.user), loadDynamoDocumentSdk(options.user)]);
+        return { sdk, client: sdk.DynamoDBDocumentClient.from(new clientSdk.DynamoDBClient(options.region ? { region: options.region } : {})) };
+    };
+    return () => {
+        readyPromise ??= build().catch((error) => { readyPromise = undefined; throw error; });
+        return readyPromise;
+    };
+};
+/**
+ * Whether DynamoDB refused a write because its condition did not hold, which
+ * is how every conditional write here reports the thing it was testing for: a
+ * claim already taken, a counter at its limit, a lease somebody else holds.
+ * An answer, not a failure, so it is the one error class these stores catch
+ * and the reason they must not catch any other.
+ */
+export const isConditionalCheckFailure = (error) => !!error && typeof error === "object" && "name" in error && error.name === "ConditionalCheckFailedException";
+/**
+ * DynamoDB's own limit on a partition key, which every store's
+ * `<keyPrefix>#<caller data>` key has to fit inside.
+ */
+export const MAX_PARTITION_KEY_BYTES = 2048;
+/**
+ * The partition key, or a refusal naming the byte count. Every store here
+ * builds its key out of caller data (an idempotency key and the identity it
+ * is scoped by, a rate-limit key a policy handler returned), so the length is
+ * the caller's to reach and this is the one place that measures it.
+ *
+ * Checked rather than left to DynamoDB, which answers an over-long key with a
+ * ValidationException: that is not a ConditionalCheckFailedException, so it
+ * escapes as a store error that reads as "the table is broken" and, under a
+ * fail-open setting, is swallowed into no protection at all. The message
+ * carries the count and never the key, because it reaches a log.
+ */
+export const assertPartitionKeyFits = (options) => {
+    const partitionKeyBytes = Buffer.byteLength(options.partitionKey, "utf8");
+    if (partitionKeyBytes > MAX_PARTITION_KEY_BYTES) {
+        throw new Error(`${options.user}: the ${options.what} is ${partitionKeyBytes} bytes with its prefix, over DynamoDB's ${MAX_PARTITION_KEY_BYTES}-byte partition key limit. ${options.remedy}`);
+    }
+    return options.partitionKey;
+};

package/dist/stores/LambderDdbSessionStore.d.ts

@@ -0,0 +1,65 @@
+import type { DynamoDBDocumentClient } from "@aws-sdk/lib-dynamodb";
+import { type LambderCompressionOption } from "../shared/wire/LambderCompressionOption.js";
+import type { LambderSessionRecord, LambderSessionStore } from "../shared/contracts/LambderSessionStore.js";
+export type LambderDdbSessionStoreOptions = {
+    tableName: string;
+    /** Region the client is created for on first use; the SDK's default chain otherwise. */
+    region?: string;
+    /** Attribute names of the table's hash and range keys. Defaults: "pk" and "sk". */
+    partitionKey?: string;
+    sortKey?: string;
+    /**
+     * Brotli compression of session.data at rest. `true` (the default)
+     * compresses every record, the same as `{ minBytes: 0 }`; `false` turns
+     * it off; `{ minBytes }` compresses only records whose JSON is at least
+     * that many bytes. Records written under either setting read back, so
+     * it can be switched on or off on a live table.
+     */
+    compression?: LambderCompressionOption;
+    /** A ready document client, e.g. one shared with the rest of the app. */
+    client?: DynamoDBDocumentClient;
+};
+/**
+ * Sessions at rest in DynamoDB: one item per session under the two hashes,
+ * with session.data Brotli-compressed by default. The store maps the
+ * manager's record onto the table's own key attribute names and back, and
+ * owns nothing of the session model itself.
+ *
+ * Table shape: a string hash key (the salted sessionKey hash, every session
+ * of one subject shares it) and a string range key (the bearer secret's
+ * hash), plus a TTL on `expiresAt` to let DynamoDB sweep expired sessions.
+ */
+export declare class LambderDdbSessionStore<SessionData = unknown> implements LambderSessionStore<SessionData> {
+    /** DynamoDB keeps records after this process is gone. */
+    readonly isMemoryOnly = false;
+    readonly tableName: string;
+    private readonly partitionKey;
+    private readonly sortKey;
+    private readonly compression;
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    private readonly ready;
+    constructor(options: LambderDdbSessionStoreOptions);
+    private keyOf;
+    /** The item for a record: the two hashes under the table's key names, the data plain or compressed. */
+    private toItem;
+    /**
+     * The record for an item. A compressed record decodes back into `data`;
+     * one whose data cannot be decoded is a malformed record and reads as no
+     * session, the same as a record missing its csrfTokenHash.
+     *
+     * Read failures and malformed records have to stay apart, and this is the
+     * seam where they separate. A read failure is infrastructure and must
+     * surface as a 500, because signing somebody out over a transient
+     * DynamoDB error is a worse answer than an error page. A record that will
+     * not decode is not transient: it will not decode on the next request
+     * either, so a 500 there is a session the visitor can neither use nor
+     * clear, on every request, until the TTL retires it. Ending it lets them
+     * log in again.
+     */
+    private fromItem;
+    get(sessionKeyHash: string, secretHash: string): Promise<LambderSessionRecord<SessionData> | null>;
+    put(record: LambderSessionRecord<SessionData>): Promise<void>;
+    delete(sessionKeyHash: string, secretHash: string): Promise<void>;
+    listSecretHashes(sessionKeyHash: string): Promise<string[]>;
+    markDataExpired(sessionKeyHash: string, secretHash: string, at: number): Promise<void>;
+}

package/dist/stores/LambderDdbSessionStore.js

@@ -0,0 +1,161 @@
+import { createDynamoDocumentClientLoader, isConditionalCheckFailure } from "./LambderDdbSdk.js";
+import { compressText, restoreText } from "../shared/wire/LambderCompressionCodec.js";
+import { resolveCompressionOption, } from "../shared/wire/LambderCompressionOption.js";
+/**
+ * Session compression defaults: every record compressed (see
+ * LambderCompressionOption for the option's shape and toggle semantics).
+ * A compressed record carries the data's JSON as Brotli bytes (`dataBr`)
+ * beside its byte length (`dataBytes`), the scheme LambderDdbCache and
+ * LambderDdbIdempotencyStore use; below minBytes, or with compression off, the
+ * record keeps a plain `data` attribute.
+ */
+const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
+/**
+ * Sessions at rest in DynamoDB: one item per session under the two hashes,
+ * with session.data Brotli-compressed by default. The store maps the
+ * manager's record onto the table's own key attribute names and back, and
+ * owns nothing of the session model itself.
+ *
+ * Table shape: a string hash key (the salted sessionKey hash, every session
+ * of one subject shares it) and a string range key (the bearer secret's
+ * hash), plus a TTL on `expiresAt` to let DynamoDB sweep expired sessions.
+ */
+export class LambderDdbSessionStore {
+    /** DynamoDB keeps records after this process is gone. */
+    isMemoryOnly = false;
+    tableName;
+    partitionKey;
+    sortKey;
+    compression;
+    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
+    ready;
+    constructor(options) {
+        if (!options.tableName.trim())
+            throw new Error("tableName is required");
+        this.tableName = options.tableName;
+        this.partitionKey = options.partitionKey ?? "pk";
+        this.sortKey = options.sortKey ?? "sk";
+        this.compression = resolveCompressionOption(options.compression, SESSION_COMPRESSION_DEFAULTS);
+        this.ready = createDynamoDocumentClientLoader({
+            user: "LambderDdbSessionStore",
+            ...(options.region !== undefined ? { region: options.region } : {}),
+            ...(options.client ? { client: options.client } : {}),
+        });
+    }
+    keyOf(sessionKeyHash, secretHash) {
+        return { [this.partitionKey]: sessionKeyHash, [this.sortKey]: secretHash };
+    }
+    /** The item for a record: the two hashes under the table's key names, the data plain or compressed. */
+    async toItem(record) {
+        const { sessionKeyHash, secretHash, data, ...rest } = record;
+        const item = { ...this.keyOf(sessionKeyHash, secretHash), ...rest };
+        const raw = this.compression && Buffer.from(JSON.stringify(data), "utf8");
+        if (this.compression && raw && raw.byteLength >= this.compression.minBytes) {
+            item.dataBr = await compressText(raw, "br", this.compression.quality);
+            item.dataBytes = raw.byteLength;
+        }
+        else {
+            item.data = data;
+        }
+        return item;
+    }
+    /**
+     * The record for an item. A compressed record decodes back into `data`;
+     * one whose data cannot be decoded is a malformed record and reads as no
+     * session, the same as a record missing its csrfTokenHash.
+     *
+     * Read failures and malformed records have to stay apart, and this is the
+     * seam where they separate. A read failure is infrastructure and must
+     * surface as a 500, because signing somebody out over a transient
+     * DynamoDB error is a worse answer than an error page. A record that will
+     * not decode is not transient: it will not decode on the next request
+     * either, so a 500 there is a session the visitor can neither use nor
+     * clear, on every request, until the TTL retires it. Ending it lets them
+     * log in again.
+     */
+    async fromItem(item) {
+        const { [this.partitionKey]: sessionKeyHash, [this.sortKey]: secretHash, dataBr, dataBytes, data, ...rest } = item;
+        let restored = data;
+        if (dataBr) {
+            try {
+                restored = JSON.parse(await restoreText(dataBr, "br", { declaredBytes: dataBytes }));
+            }
+            catch (err) {
+                console.warn(`LambderDdbSessionStore: a session record in "${this.tableName}" could not be decoded, so it reads as no session.`, err);
+                return null;
+            }
+        }
+        // The load-bearing fields are checked before the cast, because
+        // everything past this line trusts them: the manager compares the two
+        // hashes in constant time (a non-string would throw there rather than
+        // answer false) and reads expiresAt as a number to decide whether the
+        // session is over. An item missing them is not this store's record,
+        // whether it was written by hand, by an older schema, or by another
+        // app sharing the table, and it reads as no session for the same
+        // reason an undecodable one does: it will not become valid later.
+        if (typeof sessionKeyHash !== "string" || typeof secretHash !== "string"
+            || typeof rest.csrfTokenHash !== "string" || typeof rest.sessionKey !== "string"
+            || typeof rest.createdAt !== "number" || typeof rest.expiresAt !== "number"
+            || typeof rest.ttlInSeconds !== "number") {
+            console.warn(`LambderDdbSessionStore: an item in "${this.tableName}" is missing the fields a session record has, so it reads as no session.`);
+            return null;
+        }
+        // The one cast: session.data is whatever the app put there, and JSON
+        // (or the plain attribute) hands it back as any. Nothing in the store
+        // can check it, because the shape is the app's, not this layer's.
+        return { sessionKeyHash, secretHash, data: restored, ...rest };
+    }
+    async get(sessionKeyHash, secretHash) {
+        const { client, sdk } = await this.ready();
+        const response = await client.send(new sdk.GetCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash), ConsistentRead: true }));
+        if (!response.Item)
+            return null;
+        return await this.fromItem(response.Item);
+    }
+    async put(record) {
+        const item = await this.toItem(record);
+        const { client, sdk } = await this.ready();
+        await client.send(new sdk.PutCommand({ TableName: this.tableName, Item: item }));
+    }
+    async delete(sessionKeyHash, secretHash) {
+        const { client, sdk } = await this.ready();
+        await client.send(new sdk.DeleteCommand({ TableName: this.tableName, Key: this.keyOf(sessionKeyHash, secretHash) }));
+    }
+    async listSecretHashes(sessionKeyHash) {
+        const params = {
+            TableName: this.tableName,
+            KeyConditionExpression: "#pk = :pv",
+            ProjectionExpression: "#sk",
+            ExpressionAttributeNames: { "#pk": this.partitionKey, "#sk": this.sortKey },
+            ExpressionAttributeValues: { ":pv": sessionKeyHash },
+        };
+        const hashes = [];
+        for (;;) {
+            const { client, sdk } = await this.ready();
+            const { Items, LastEvaluatedKey } = await client.send(new sdk.QueryCommand(params));
+            for (const item of Items ?? [])
+                hashes.push(item[this.sortKey]);
+            if (LastEvaluatedKey === undefined)
+                return hashes;
+            params.ExclusiveStartKey = LastEvaluatedKey;
+        }
+    }
+    async markDataExpired(sessionKeyHash, secretHash, at) {
+        try {
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.UpdateCommand({
+                TableName: this.tableName,
+                Key: this.keyOf(sessionKeyHash, secretHash),
+                UpdateExpression: "SET #dataExpiresAt = :at",
+                ConditionExpression: "attribute_exists(#sk)",
+                ExpressionAttributeNames: { "#dataExpiresAt": "dataExpiresAt", "#sk": this.sortKey },
+                ExpressionAttributeValues: { ":at": at },
+            }));
+        }
+        catch (err) {
+            // Deleted between the query and the update: nothing left to expire.
+            if (!isConditionalCheckFailure(err))
+                throw err;
+        }
+    }
+}

package/dist/stores/LambderHttpFileSource.d.ts

@@ -1,4 +1,4 @@
-import { type LambderFile, type LambderFileSource } from "../core/LambderFiles.js";
+import { type LambderFile, type LambderFileSource } from "../shared/contracts/LambderFileSource.js";
 export type LambderHttpFileSourceOptions = {
     /**
      * The folder URL relative paths resolve under: "https://assets.example.com/v42/".

package/dist/stores/LambderHttpFileSource.js

@@ -1,4 +1,4 @@
-import { remoteStoreFile } from "../core/LambderFiles.js";
+import { remoteStoreFile } from "../shared/contracts/LambderFileSource.js";
 const DEFAULT_TIMEOUT_MS = 10_000;
 /**
  * Files over HTTP(S) from any origin that serves them by path: a CDN, a
@@ -34,6 +34,15 @@ export class LambderHttpFileSource {
     }
     async read(relativePath) {
         const url = new URL(relativePath.split("/").map(encodeURIComponent).join("/"), this.baseUrl);
+        // The reader's path rule already refuses everything that could make
+        // this reference leave the configured folder (a leading slash makes it
+        // root-relative, two make it protocol-relative and pick the host).
+        // Checked again here rather than trusted, because the value being
+        // resolved is the request path and what leaving costs is a
+        // credentialed fetch of an attacker-named origin, served back from
+        // this app's own domain.
+        if (!url.href.startsWith(this.baseUrl.href))
+            return null;
         const response = await fetch(url, { headers: this.headers, signal: AbortSignal.timeout(this.timeoutMs) });
         if (!response.ok) {
             await response.body?.cancel();

package/dist/stores/LambderLocalFileSource.d.ts

@@ -0,0 +1,15 @@
+import type { LambderFile, LambderFileSource } from "../shared/contracts/LambderFileSource.js";
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root: the reader's
+ * path rule already refuses anything that could leave it, and the resolved
+ * path is checked against the root again here, because a contract is not a
+ * boundary.
+ */
+export declare class LambderLocalFileSource implements LambderFileSource {
+    private root;
+    constructor({ root }: {
+        root: string;
+    });
+    read(relativePath: string): Promise<LambderFile | null>;
+}

package/dist/stores/LambderLocalFileSource.js

@@ -0,0 +1,28 @@
+import { getFS, getPath } from "../shared/util/LambderNodeModules.js";
+/**
+ * Files from a folder on the Lambda's filesystem, typically the build output
+ * bundled into the deployment package. Reads stay under root: the reader's
+ * path rule already refuses anything that could leave it, and the resolved
+ * path is checked against the root again here, because a contract is not a
+ * boundary.
+ */
+export class LambderLocalFileSource {
+    root;
+    constructor({ root }) {
+        this.root = root;
+    }
+    async read(relativePath) {
+        const fs = await getFS();
+        const path = await getPath();
+        if (!fs || !path)
+            throw new Error("Lambder: LambderLocalFileSource requires a Node.js environment.");
+        const base = path.resolve(this.root);
+        const absolute = path.resolve(base, relativePath);
+        if (absolute !== base && !absolute.startsWith(base + path.sep))
+            return null;
+        const stat = await fs.promises.stat(absolute).catch(() => null);
+        if (!stat?.isFile())
+            return null;
+        return { body: await fs.promises.readFile(absolute) };
+    }
+}