lambder 6.0.2 → 7.0.2

package/dist/session/LambderSessionManager.js

@@ -1,16 +1,6 @@
-import crypto from "crypto";
-import { loadDynamoClientSdk, loadDynamoDocumentSdk } from "../stores/LambderDdbSdk.js";
-import { compressText, restoreText } from "../shared/LambderCompressionCodec.js";
-import { resolveCompressionOption, } from "../shared/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
- * LambderDdbIdempotency use; below minBytes, or with compression off, the
- * record keeps a plain `data` attribute.
- */
-const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
+import { LambderWebCrypto } from "./LambderSessionCrypto.js";
+import { coerceToError } from "../shared/wire/LambderCrashDetail.js";
+import { assertPositiveInteger } from "../shared/util/LambderOptionChecks.js";
 /**
  * Wraps errors thrown by the dataRefresh callback so they stay
  * distinguishable from "no session": fetchSessionIfExists() swallows missing
@@ -19,157 +9,162 @@ const SESSION_COMPRESSION_DEFAULTS = { minBytes: 0, quality: 5 };
  */
 export class LambderSessionDataRefreshError extends Error {
     constructor(cause) {
-        super(`Session dataRefresh failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        super(`Session dataRefresh failed: ${coerceToError(cause).message}`, { cause });
         this.name = "LambderSessionDataRefreshError";
     }
 }
 /**
- * Wraps DynamoDB failures during a session read so they stay distinguishable
+ * Wraps store failures during a session read so they stay distinguishable
  * from "no session": fetchSessionIfExists() swallows missing or invalid
- * sessions but rethrows this. Without the distinction a transient DynamoDB
+ * sessions but rethrows this. Without the distinction a transient store
  * error would answer sessionExpired, and the caller would then clear the
  * client's session cookies: an infra blip forcing a real logout.
  */
 export class LambderSessionReadError extends Error {
     constructor(cause) {
-        super(`Session read failed: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+        super(`Session read failed: ${coerceToError(cause).message}`, { cause });
         this.name = "LambderSessionReadError";
     }
 }
+/**
+ * The longest either half of a session token may be. A minted token is two
+ * 64-character hex halves, so this is sixteen times the room the default
+ * crypto needs, which leaves a custom LambderSessionCrypto free to mint
+ * longer hashes or secrets without this file knowing its lengths, and leaves
+ * LambderPlainSessionCrypto, which hex-encodes its input rather than hashing
+ * it, room for a session key and salt of several hundred characters.
+ * Deriving the exact length from the crypto instead would tie the check to
+ * whichever crypto is configured today and reject every session minted by
+ * the previous one, and LambderSessionCrypto exposes no length to read.
+ *
+ * The number that matters is the one this is comfortably under: DynamoDB
+ * refuses a partition key over 2048 bytes, and a cookie may carry 4000, so
+ * without a bound a planted oversized cookie reaches the store as a key it
+ * cannot take, the read throws, and a live session beside it answers 500 on
+ * every request.
+ */
+const MAX_SESSION_TOKEN_HALF_CHARS = 1024;
+/** Hex in either case: what every LambderSessionCrypto's sha256Hex and randomHex produce, whichever case a custom one picks. */
+const SESSION_TOKEN_HALF_PATTERN = /^[0-9a-fA-F]+$/;
+/**
+ * Whether a string has the shape a minted session token has:
+ * `sessionKeyHash:secret`, both hex, neither longer than 1024 characters.
+ *
+ * It lives beside the code that mints and splits that format rather than
+ * beside the cookie reader, so the ceiling is a property of the model and
+ * anyone handing lookupSession a token they did not mint can ask the same
+ * question. The session controller asks it of every candidate cookie before
+ * any store read, so a malformed candidate is "no session" and never a read
+ * error. Nothing a browser legitimately holds fails it, because the only
+ * writer of these cookies is the code that mints them.
+ */
+export const isMintedSessionToken = (token) => {
+    const halves = token.split(":");
+    if (halves.length !== 2)
+        return false;
+    return halves.every((half) => half.length > 0 && half.length <= MAX_SESSION_TOKEN_HALF_CHARS && SESSION_TOKEN_HALF_PATTERN.test(half));
+};
+/**
+ * The session model: how a session is minted, what its tokens look like,
+ * how it is found from a presented token, when it expires, when its data is
+ * renewed, and how it is rotated or ended. Storage and cryptography are
+ * injected, so the same class runs on Lambda over DynamoDB, in a test over
+ * a Map, and in a browser under the mock runtime.
+ *
+ * Token format: the session cookie carries `sessionKeyHash:secret`, where
+ * the hash locates the partition and only the secret's hash is stored as
+ * the sort key, so the lookup itself proves possession of the raw secret
+ * and a store read yields no usable token. The CSRF token is a second
+ * random value the client sends back in the request body; its hash is
+ * stored too.
+ */
 export default class LambderSessionManager {
-    tableName;
+    store;
     sessionSalt;
-    partitionKey;
-    sortKey;
-    tableRegion;
-    /** The document client and the SDK it came from, created the first time the table is touched. */
-    readyPromise;
     enableSlidingExpiration;
     slidingWriteIntervalSeconds;
     dataRefresh;
-    compression;
-    constructor({ tableName, tableRegion, partitionKey, sortKey, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, compression, }) {
-        this.tableName = tableName;
+    crypto;
+    constructor({ store, sessionSalt, enableSlidingExpiration = true, slidingWriteIntervalSeconds, dataRefresh, crypto, }) {
+        this.store = store;
         this.sessionSalt = sessionSalt;
-        this.partitionKey = partitionKey;
-        this.sortKey = sortKey;
         this.enableSlidingExpiration = enableSlidingExpiration;
-        this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds ?? null;
+        this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds === undefined
+            ? null
+            : assertPositiveInteger(slidingWriteIntervalSeconds, "session.slidingWriteIntervalSeconds");
+        if (dataRefresh)
+            assertPositiveInteger(dataRefresh.ttlSeconds, "session.dataRefresh.ttlSeconds");
         this.dataRefresh = dataRefresh ?? null;
-        this.compression = resolveCompressionOption(compression, SESSION_COMPRESSION_DEFAULTS);
-        this.tableRegion = tableRegion;
-    }
-    /** The SDK and the client, loaded and created the first time the table is touched (see LambderDdbSdk). */
-    ready() {
-        this.readyPromise ??= Promise.all([loadDynamoClientSdk("LambderSessionManager"), loadDynamoDocumentSdk("LambderSessionManager")])
-            .then(([clientSdk, sdk]) => ({ sdk, client: sdk.DynamoDBDocumentClient.from(new clientSdk.DynamoDBClient({ region: this.tableRegion })) }))
-            .catch((error) => { this.readyPromise = undefined; throw error; });
-        return this.readyPromise;
+        this.crypto = crypto ?? new LambderWebCrypto();
+        if (!this.crypto.isCryptographic && !store.isMemoryOnly) {
+            throw new Error("Lambder: this session crypto does not hash and does not draw cryptographically random bytes, " +
+                "so it may only sit in front of a store that dies with the process. Over a persistent store every " +
+                "record would be a usable credential and the sessionSalt would be readable from it.");
+        }
+        if (typeof sessionSalt !== "string" || sessionSalt.length === 0) {
+            throw new Error("Lambder: session sessionSalt is empty. It salts the hash that partitions the store, so it has to be a real, stable secret.");
+        }
     }
-    sessionUserKeyHasher(password) {
-        return crypto.createHash("sha256")
-            .update(`${password}${this.sessionSalt}`)
-            .digest("hex");
+    /**
+     * The salted partition hash of a sessionKey: sha256 of the key followed
+     * by the salt, with NO separator between them.
+     *
+     * The missing separator is frozen by the wire guarantee, not chosen
+     * again here: every live session in every deployed table was partitioned
+     * under this exact string, so inserting a separator would relocate every
+     * partition key at once and read to everyone signed in as being logged
+     * out. What it costs is worth naming so nobody reintroduces it by
+     * accident: without a separator the split between key and salt is not
+     * recoverable from the string, so two deployments SHARING one table
+     * collide when the difference between their salts can be absorbed into a
+     * sessionKey ("ab" + "cd" and "a" + "bcd" hash alike). Two deployments
+     * over one table must therefore not stand in a prefix relationship over
+     * their salts. Separate tables, or salts that are independent random
+     * strings, both rule it out.
+     */
+    sessionKeyHashOf(sessionKey) {
+        return this.crypto.sha256Hex(`${sessionKey}${this.sessionSalt}`);
     }
     /**
      * At-rest hash for the bearer secrets (session sort-key secret, CSRF
      * token). Fast unsalted sha256 is the right construction here: the
      * inputs are 256-bit random values, so there is nothing to brute-force;
-     * hashing just ensures a leaked table read yields no usable cookies.
+     * hashing just ensures a leaked store read yields no usable cookies.
      */
     hashToken(value) {
-        return crypto.createHash("sha256").update(value).digest("hex");
-    }
-    constantTimeCompare(a, b) {
-        if (a.length !== b.length)
-            return false;
-        const bufferA = Buffer.from(a, 'utf8');
-        const bufferB = Buffer.from(b, 'utf8');
-        return crypto.timingSafeEqual(new Uint8Array(bufferA), new Uint8Array(bufferB));
-    }
-    async ddbGetItem(key) {
-        const { client, sdk } = await this.ready();
-        const response = await client.send(new sdk.GetCommand({ TableName: this.tableName, Key: key, ConsistentRead: true }));
-        if (response.Item)
-            return response.Item;
-        return null;
-    }
-    ;
-    /**
-     * Persists a session record. With compression on, `data` is stored as
-     * Brotli bytes (`dataBr`) beside its JSON byte length (`dataBytes`)
-     * once the JSON reaches minBytes; otherwise it stays a plain attribute.
-     */
-    async ddbPutItem(session) {
-        const { data, ...item } = session;
-        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;
-        }
-        const { client, sdk } = await this.ready();
-        return await client.send(new sdk.PutCommand({ TableName: this.tableName, Item: item, }));
-    }
-    ;
-    async ddbDeleteItem(key) {
-        const { client, sdk } = await this.ready();
-        return await client.send(new sdk.DeleteCommand({ TableName: this.tableName, Key: key, }));
-    }
-    ;
-    /** Sort keys of every session under a partition (the callers only need the keys). */
-    async ddbQueryAllByPartitionKey(partitionValue) {
-        const params = {
-            TableName: this.tableName,
-            KeyConditionExpression: "#pk = :pv",
-            ProjectionExpression: "#sk",
-            ExpressionAttributeNames: { "#pk": this.partitionKey, "#sk": this.sortKey },
-            ExpressionAttributeValues: { ":pv": partitionValue },
-        };
-        const queryResults = [];
-        do {
-            const { client, sdk } = await this.ready();
-            const { Items, LastEvaluatedKey } = await client.send(new sdk.QueryCommand(params));
-            if (Items)
-                queryResults.push(...Items);
-            params.ExclusiveStartKey = LastEvaluatedKey;
-            if (typeof LastEvaluatedKey == "undefined")
-                return queryResults;
-            // eslint-disable-next-line no-constant-condition
-        } while (true);
-    }
-    ;
-    async ddbDeleteAllByPartitionKey(partitionValue) {
-        const queryResults = await this.ddbQueryAllByPartitionKey(partitionValue);
-        for (const item of queryResults) {
-            const { client, sdk } = await this.ready();
-            await client.send(new sdk.DeleteCommand({
-                TableName: this.tableName,
-                Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] }
-            }));
-        }
+        return this.crypto.sha256Hex(value);
     }
     async createSession(sessionKey, data = {}, ttlInSeconds = 30 * 24 * 60 * 60, options) {
-        const sessionKeyHash = this.sessionUserKeyHasher(sessionKey);
+        // Checked rather than trusted: the TTL becomes the record's expiresAt
+        // and the store's own expiry attribute, so a NaN or a fraction from an
+        // unparsed environment variable would write a record nothing ever
+        // retires and no read ever accepts.
+        assertPositiveInteger(ttlInSeconds, "createSession ttlInSeconds");
+        // Refused for the same reason as a NaN TTL: an empty sessionKey
+        // writes a record that lookupSession rejects on every read (a session
+        // has to name its subject), so the caller would be handed a
+        // valid-looking cookie pair for a session nobody can ever sign in
+        // with, and every request after it would read as a silent logout.
+        if (!sessionKey)
+            throw new Error("Lambder: createSession sessionKey is empty. It names the subject the session belongs to and partitions the store, so an empty one writes a record no read accepts.");
+        const sessionKeyHash = await this.sessionKeyHashOf(sessionKey);
         // The sort-key SECRET goes to the client; only its hash becomes the
-        // DynamoDB range key, so the table never contains a usable token.
-        const sessionSortKeySecret = crypto.randomBytes(32).toString("hex");
-        const sessionToken = `${sessionKeyHash}:${sessionSortKeySecret}`;
-        const csrfToken = crypto.randomBytes(32).toString("hex");
+        // store's range key, so the store never contains a usable token.
+        const secret = await this.crypto.randomHex(32);
+        const sessionToken = `${sessionKeyHash}:${secret}`;
+        const csrfToken = await this.crypto.randomHex(32);
         const createdAt = Math.floor(Date.now() / 1000);
         const lastAccessedAt = createdAt;
         const expiresAt = Number(createdAt) + Number(ttlInSeconds);
         const session = {
-            [this.partitionKey]: sessionKeyHash,
-            [this.sortKey]: this.hashToken(sessionSortKeySecret),
-            csrfTokenHash: this.hashToken(csrfToken),
+            sessionKeyHash,
+            secretHash: await this.hashToken(secret),
+            csrfTokenHash: await this.hashToken(csrfToken),
             sessionKey, data,
             createdAt, lastAccessedAt, expiresAt, ttlInSeconds,
             ...(this.dataRefresh ? { dataExpiresAt: options?.dataExpiresAt ?? (createdAt + this.dataRefresh.ttlSeconds) } : {}),
         };
-        await this.ddbPutItem(session);
+        await this.store.put(session);
         return { session, sessionToken, csrfToken };
     }
     async updateSessionData(session, newData) {
@@ -185,14 +180,23 @@ export default class LambderSessionManager {
         if (this.enableSlidingExpiration) {
             session.expiresAt = session.lastAccessedAt + session.ttlInSeconds;
         }
-        await this.ddbPutItem(session);
+        await this.store.put(session);
         return session;
     }
-    async getSession(sessionToken) {
-        const [sessionKeyHash, sessionSortKeySecret] = sessionToken.split(":");
-        if (!sessionKeyHash || !sessionSortKeySecret)
+    /**
+     * The record a token names, read and structurally checked, with nothing
+     * renewed. Split out of getSession so a caller weighing several candidate
+     * cookies can decide which one is this visitor's BEFORE anything is
+     * written on their behalf: renewing slides an expiry and may run the
+     * app's dataRefresh callback, and a cookie a sibling host planted must
+     * not get either from the victim's traffic.
+     */
+    async lookupSession(sessionToken) {
+        const [sessionKeyHash, secret] = sessionToken.split(":");
+        if (!sessionKeyHash || !secret)
             return null;
-        // A DynamoDB read failure propagates typed: null means "no such
+        const secretHash = await this.hashToken(secret);
+        // A store read failure propagates typed: null means "no such
         // session", which callers translate to sessionExpired, and the caller
         // then clears the client's session cookies. A transient infra error
         // must surface as a 500, not force a logout.
@@ -200,32 +204,45 @@ export default class LambderSessionManager {
         try {
             // The lookup itself proves possession of the raw secret: the
             // range key is its hash, so only the true secret finds the item.
-            session = await this.ddbGetItem({
-                [this.partitionKey]: sessionKeyHash,
-                [this.sortKey]: this.hashToken(sessionSortKeySecret)
-            });
+            session = await this.store.get(sessionKeyHash, secretHash);
         }
         catch (err) {
             throw new LambderSessionReadError(err);
         }
         if (!session)
             return null;
-        // A compressed record (see ddbPutItem) decodes back into `data`. One
-        // that fails to decode throws, which the controller treats like any
-        // malformed record: no session.
-        if (session.dataBr) {
-            session.data = JSON.parse(await restoreText(session.dataBr, "br", { declaredBytes: session.dataBytes }));
-            delete session.dataBr;
-            delete session.dataBytes;
-        }
+        // The record has to be the one that was asked for. A correct store
+        // answers with the item under the two keys it was given, and this is
+        // what a store that does not (a cache keyed loosely, a query that
+        // forgot its partition) runs into instead of handing back somebody
+        // else's session. The hashes are already in hand, so it costs a
+        // comparison and no hashing.
+        if (!this.crypto.constantTimeEqual(session.sessionKeyHash ?? "", sessionKeyHash))
+            return null;
+        if (!this.crypto.constantTimeEqual(session.secretHash ?? "", secretHash))
+            return null;
         if (!session.csrfTokenHash)
             return null;
         if (!session.sessionKey)
             return null;
         if (!session.createdAt)
             return null;
+        // Expiry is enforced here, on every read, because the store contract
+        // allows a record past its expiresAt: a DynamoDB TTL deletes within
+        // days rather than at the second, and a store over a plain table
+        // sweeps nothing at all.
         if (!session.expiresAt || session.expiresAt < Date.now() / 1000)
             return null;
+        return session;
+    }
+    ;
+    /**
+     * The renewal half of a session read: the dataRefresh callback once its
+     * shelf life has passed, and the sliding-expiration write. Returns null
+     * when a refresh says the session is over (a deleted or disabled login),
+     * which ends it the same way a missing record does.
+     */
+    async renewSession(session) {
         const now = Math.floor(Date.now() / 1000);
         let needsWrite = false;
         // Renew session.data once its shelf life has passed (opt-in
@@ -250,7 +267,7 @@ export default class LambderSessionManager {
             needsWrite = true;
         }
         // Update last accessed time if sliding expiration is enabled.
-        // Throttled: skip the DynamoDB write when the session was refreshed
+        // Throttled: skip the store write when the session was refreshed
         // recently, to avoid a write on every request. A due data renewal
         // above forces the write anyway, so both updates share one put.
         if (this.enableSlidingExpiration) {
@@ -265,8 +282,16 @@ export default class LambderSessionManager {
         if (needsWrite) {
             // Wait for the update to ensure it persists before Lambda freezes.
             // A failed put is not fatal: the data served is fresh, and an
-            // unpersisted renewal simply runs again on the next read.
-            await this.ddbPutItem(session).catch(() => { });
+            // unpersisted renewal simply runs again on the next read. It is
+            // still logged, because a store that fails every renewal write
+            // means sliding expiration has quietly stopped working and every
+            // session now ends at its creation TTL, which otherwise shows up
+            // only as users being signed out sooner than the app promises.
+            // The reason only, never the record or the token: a log line is
+            // not the place for anything that identifies a session.
+            await this.store.put(session).catch((err) => {
+                console.error(`Lambder session: the renewal write failed, so this session keeps its stored expiry. ${coerceToError(err).message}`);
+            });
         }
         return session;
     }
@@ -300,22 +325,29 @@ export default class LambderSessionManager {
         if (this.enableSlidingExpiration) {
             session.expiresAt = now + session.ttlInSeconds;
         }
-        await this.ddbPutItem(session);
+        await this.store.put(session);
         return session;
     }
     ;
-    isSessionValid(session, sessionToken, csrfToken, skipCsrfTokenCheck = false) {
+    /**
+     * Checks a record against the session token presented with it: the
+     * partition hash and the bearer secret the cookie carries, plus the
+     * structural checks and the expiry. This is the half a route needs, and
+     * the half lookupSession has already proved for a record it just found by
+     * that token's own hash, so the read path does not ask it again.
+     */
+    async isSessionTokenValid(session, sessionToken) {
         if (!session)
             return false;
-        if (!sessionToken || typeof sessionToken !== "string")
+        if (!sessionToken)
             return false;
         // Presented raw secrets are checked against the stored hashes.
-        const [sessionKeyHash, sessionSortKeySecret] = sessionToken.split(":");
-        if (!sessionKeyHash || !sessionSortKeySecret)
+        const [sessionKeyHash, secret] = sessionToken.split(":");
+        if (!sessionKeyHash || !secret)
             return false;
-        if (!this.constantTimeCompare(String(session[this.partitionKey] ?? ""), sessionKeyHash))
+        if (!this.crypto.constantTimeEqual(session.sessionKeyHash, sessionKeyHash))
             return false;
-        if (!this.constantTimeCompare(String(session[this.sortKey] ?? ""), this.hashToken(sessionSortKeySecret)))
+        if (!this.crypto.constantTimeEqual(session.secretHash, await this.hashToken(secret)))
             return false;
         if (!session.csrfTokenHash)
             return false;
@@ -325,24 +357,30 @@ export default class LambderSessionManager {
             return false;
         if (!session.expiresAt || session.expiresAt < Date.now() / 1000)
             return false;
-        if (!skipCsrfTokenCheck) {
-            if (!csrfToken || typeof csrfToken !== "string")
-                return false;
-            if (!this.constantTimeCompare(session.csrfTokenHash, this.hashToken(csrfToken)))
-                return false;
-        }
         return true;
     }
+    /**
+     * Checks a record against the CSRF token the request posted: the other
+     * half, asked of an API call and not of a route. Separate methods rather
+     * than one with a skip flag, because a boolean at the call site says
+     * nothing about which half it turns off, and the two are asked in
+     * different places for different reasons.
+     */
+    async isSessionCsrfTokenValid(session, csrfToken) {
+        if (!session?.csrfTokenHash)
+            return false;
+        if (!csrfToken)
+            return false;
+        return this.crypto.constantTimeEqual(session.csrfTokenHash, await this.hashToken(csrfToken));
+    }
     async deleteSession(session) {
-        await this.ddbDeleteItem({
-            [this.partitionKey]: session[this.partitionKey],
-            [this.sortKey]: session[this.sortKey],
-        });
+        await this.store.delete(session.sessionKeyHash, session.secretHash);
         return true;
     }
     ;
+    /** Deletes every session that shares the record's subject: "log this subject out everywhere". */
     async deleteSessionAll(session) {
-        await this.ddbDeleteAllByPartitionKey(session[this.partitionKey]);
+        await this.deleteAllUnder(session.sessionKeyHash);
         return true;
     }
     ;
@@ -352,41 +390,31 @@ export default class LambderSessionManager {
      * session record.
      */
     async deleteSessionAllByKey(sessionKey) {
-        await this.ddbDeleteAllByPartitionKey(this.sessionUserKeyHasher(sessionKey));
+        await this.deleteAllUnder(await this.sessionKeyHashOf(sessionKey));
         return true;
     }
     ;
+    async deleteAllUnder(sessionKeyHash) {
+        for (const secretHash of await this.store.listSecretHashes(sessionKeyHash)) {
+            await this.store.delete(sessionKeyHash, secretHash);
+        }
+    }
     /**
      * Marks the data of every session of the given sessionKey stale, so each
      * renews via dataRefresh on its next read: "this subject's roles or
      * permissions changed, apply it now", without logging the subject out
      * (deleteSessionAllByKey) and without waiting for the data TTL. Stamps
-     * dataExpiresAt only, conditionally on the record still existing, so it
-     * neither resurrects a session deleted in between nor overwrites a
-     * concurrent write. Requires dataRefresh to be configured.
+     * dataExpiresAt only, on records that still exist, so it neither
+     * resurrects a session deleted in between nor overwrites a concurrent
+     * write. Requires dataRefresh to be configured.
      */
     async expireSessionDataAllByKey(sessionKey) {
         if (!this.dataRefresh)
             throw new Error("dataRefresh is not configured. Pass session.dataRefresh at creation to enable.");
-        const partitionValue = this.sessionUserKeyHasher(sessionKey);
+        const sessionKeyHash = await this.sessionKeyHashOf(sessionKey);
         const now = Math.floor(Date.now() / 1000);
-        for (const item of await this.ddbQueryAllByPartitionKey(partitionValue)) {
-            try {
-                const { client, sdk } = await this.ready();
-                await client.send(new sdk.UpdateCommand({
-                    TableName: this.tableName,
-                    Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] },
-                    UpdateExpression: "SET #dataExpiresAt = :now",
-                    ConditionExpression: "attribute_exists(#sk)",
-                    ExpressionAttributeNames: { "#dataExpiresAt": "dataExpiresAt", "#sk": this.sortKey },
-                    ExpressionAttributeValues: { ":now": now },
-                }));
-            }
-            catch (err) {
-                // Deleted between the query and the update: nothing left to expire.
-                if (err.name !== "ConditionalCheckFailedException")
-                    throw err;
-            }
+        for (const secretHash of await this.store.listSecretHashes(sessionKeyHash)) {
+            await this.store.markDataExpired(sessionKeyHash, secretHash, now);
         }
         return true;
     }

package/dist/shared/LambderI18n.d.ts

@@ -1,5 +1,5 @@
 /**
- * LambderI18n — standalone, framework-free, isomorphic typed translation module.
+ * LambderI18n: standalone, framework-free, isomorphic typed translation module.
  *
  * Zero dependencies, no Node/DOM requirements (browser detection is feature-gated),
  * safe to import in both lambda backends and frontend bundles.
@@ -21,7 +21,7 @@ export interface LambderLanguageMeta {
 /** Extracts `{param}` placeholder names from a string literal type. */
 export type LambderI18nExtractParams<S extends string> = S extends `${string}{${infer P}}${infer Rest}` ? P | LambderI18nExtractParams<Rest> : never;
 /**
- * Typed translator: `t(key)` — and when the key's contract value contains
+ * Typed translator: `t(key)`, and when the key's contract value contains
  * `{tokens}`, a params object with exactly those tokens is required.
  */
 export type LambderI18nTranslator<TContract extends Record<string, string>> = <K extends keyof TContract & string>(...args: LambderI18nExtractParams<TContract[K]> extends never ? [key: K] : [key: K, params: Record<LambderI18nExtractParams<TContract[K]>, string | number>]) => string;
@@ -60,7 +60,7 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     forLanguage(code: keyof TLanguages & string): LambderI18nTranslator<TContract>;
     /**
      * Strict extension: every language must provide every new key. Keys must
-     * be new — redeclaring a parent key is a compile-time and runtime error.
+     * be new: redeclaring a parent key is a compile-time and runtime error.
      * Returns a new instance whose key space = parent keys + new keys.
      */
     extend<const TExt extends {
@@ -72,8 +72,8 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     } & TExt): LambderI18nInstance<TLanguages, TDefault, TEnforced, TContract & TExt[TDefault]>;
     /**
      * Partial extension: only the `enforced` languages are required; all other
-     * languages are optional (and may provide a subset of keys) — missing
-     * translations fall back to the default language. Keys must be new —
+     * languages are optional (and may provide a subset of keys), and missing
+     * translations fall back to the default language. Keys must be new:
      * redeclaring a parent key is a compile-time and runtime error.
      */
     extendPartial<const TExt extends {
@@ -116,7 +116,7 @@ export interface LambderI18nInstance<TLanguages extends Record<string, LambderLa
     isLanguageCode(value: string): value is keyof TLanguages & string;
     readonly languages: TLanguages;
     readonly languageList: (keyof TLanguages & string)[];
-    /** Ordered language metadata (declaration order), with `code` injected — ready for switcher menus. */
+    /** Ordered language metadata (declaration order), with `code` injected, ready for switcher menus. */
     readonly languageMetaList: (TLanguages[keyof TLanguages] & {
         code: keyof TLanguages & string;
     })[];

package/dist/shared/LambderI18n.js

@@ -1,5 +1,5 @@
 /**
- * LambderI18n — standalone, framework-free, isomorphic typed translation module.
+ * LambderI18n: standalone, framework-free, isomorphic typed translation module.
  *
  * Zero dependencies, no Node/DOM requirements (browser detection is feature-gated),
  * safe to import in both lambda backends and frontend bundles.

package/dist/shared/contracts/LambderFileSource.d.ts

@@ -0,0 +1,33 @@
+/** A file a source serves: its bytes, and its mime type when the source knows it (otherwise resolved from the extension). */
+export type LambderFile = {
+    body: Buffer;
+    mimeType?: string;
+};
+/**
+ * Where an app's files come from: the `files` option at creation, read by
+ * servePublicFiles, serveIndexHtml, res.file and res.templateFile alike,
+ * through the instance's one reader (LambderFiles). Implement `read` over
+ * any backing store: LambderLocalFileSource (a folder), LambderS3FileSource
+ * (S3, or R2 and other S3-compatible stores), LambderHttpFileSource (any
+ * origin serving files by path), or your own. The reader does the rest for
+ * every source: path rule, memory cache, mime fallback from the extension.
+ */
+export interface LambderFileSource {
+    /**
+     * The file at a relative path, or null when there is no such file, which
+     * lets a request fall through to the route fallback.
+     *
+     * The reader has already refused everything that is not a plain relative
+     * path: no leading slash, no empty, "." or ".." segment, no backslash.
+     * A source that resolves the value against a base an attacker must not
+     * leave (a URL, a filesystem root) still re-checks the result, because a
+     * contract is not a boundary.
+     */
+    read(relativePath: string): Promise<LambderFile | null>;
+}
+/**
+ * A file a remote store returned: the store's Content-Type unless it is a
+ * generic octet-stream, in which case the extension decides, as for local
+ * files.
+ */
+export declare const remoteStoreFile: (body: Buffer, contentType: string | null | undefined) => LambderFile;

package/dist/shared/contracts/LambderFileSource.js

@@ -0,0 +1,19 @@
+/*
+ * Where an app's files come from: the interface, and the one helper its
+ * remote implementations share.
+ *
+ * Declared in shared/ beside LambderSessionStore, LambderRateLimiter and
+ * LambderIdempotencyStore, so all four store families read the same way: the
+ * interface here, the implementations in stores/ (LambderLocalFileSource,
+ * LambderS3FileSource, LambderHttpFileSource). core/ names the interface and
+ * nothing else of the family.
+ *
+ * What reads through a source is the instance's reader, LambderFiles: it owns
+ * the path rule, the memory cache and the mime fallback.
+ */
+/**
+ * A file a remote store returned: the store's Content-Type unless it is a
+ * generic octet-stream, in which case the extension decides, as for local
+ * files.
+ */
+export const remoteStoreFile = (body, contentType) => contentType && !contentType.endsWith("octet-stream") ? { body, mimeType: contentType } : { body };