lambder 3.8.1 → 4.0.1

package/dist/{LambderSessionManager.js → session/LambderSessionManager.js}

@@ -13,6 +13,19 @@ export class LambderSessionDataRefreshError extends Error {
         this.name = "LambderSessionDataRefreshError";
     }
 }
+/**
+ * Wraps DynamoDB 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
+ * 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 });
+        this.name = "LambderSessionReadError";
+    }
+}
 export default class LambderSessionManager {
     tableName;
     sessionSalt;
@@ -38,6 +51,15 @@ export default class LambderSessionManager {
             .update(`${password}${this.sessionSalt}`)
             .digest("hex");
     }
+    /**
+     * 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.
+     */
+    hashToken(value) {
+        return crypto.createHash("sha256").update(value).digest("hex");
+    }
     constantTimeCompare(a, b) {
         if (a.length !== b.length)
             return false;
@@ -90,22 +112,24 @@ export default class LambderSessionManager {
     }
     async createSession(sessionKey, data = {}, ttlInSeconds = 30 * 24 * 60 * 60, options) {
         const sessionKeyHash = this.sessionUserKeyHasher(sessionKey);
-        const sessionSortKey = crypto.randomBytes(32).toString("hex");
-        const sessionToken = `${sessionKeyHash}:${sessionSortKey}`;
+        // 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");
         const createdAt = Math.floor(Date.now() / 1000);
         const lastAccessedAt = createdAt;
         const expiresAt = Number(createdAt) + Number(ttlInSeconds);
         const session = {
             [this.partitionKey]: sessionKeyHash,
-            [this.sortKey]: sessionSortKey,
-            sessionToken, csrfToken,
+            [this.sortKey]: this.hashToken(sessionSortKeySecret),
+            csrfTokenHash: this.hashToken(csrfToken),
             sessionKey, data,
             createdAt, lastAccessedAt, expiresAt, ttlInSeconds,
             ...(this.dataRefresh ? { dataExpiresAt: options?.dataExpiresAt ?? (createdAt + this.dataRefresh.ttlSeconds) } : {}),
         };
         await this.ddbPutItem(session);
-        return session;
+        return { session, sessionToken, csrfToken };
     }
     async updateSessionData(session, newData) {
         if (!session)
@@ -124,25 +148,28 @@ export default class LambderSessionManager {
         return session;
     }
     async getSession(sessionToken) {
-        const [sessionKeyHash, sessionSortKey] = sessionToken.split(":");
-        if (!sessionKeyHash || !sessionSortKey)
+        const [sessionKeyHash, sessionSortKeySecret] = sessionToken.split(":");
+        if (!sessionKeyHash || !sessionSortKeySecret)
             return null;
+        // A DynamoDB 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.
         let session;
         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]: sessionSortKey
+                [this.sortKey]: this.hashToken(sessionSortKeySecret)
             });
         }
         catch (err) {
-            return null;
+            throw new LambderSessionReadError(err);
         }
-        // Use constant error response to prevent timing attacks
         if (!session)
             return null;
-        if (!session.sessionToken || !this.constantTimeCompare(session.sessionToken, sessionToken))
-            return null;
-        if (!session.csrfToken)
+        if (!session.csrfTokenHash)
             return null;
         if (!session.sessionKey)
             return null;
@@ -233,9 +260,15 @@ export default class LambderSessionManager {
             return false;
         if (!sessionToken || typeof sessionToken !== "string")
             return false;
-        if (!this.constantTimeCompare(session.sessionToken, sessionToken))
+        // Presented raw secrets are checked against the stored hashes.
+        const [sessionKeyHash, sessionSortKeySecret] = sessionToken.split(":");
+        if (!sessionKeyHash || !sessionSortKeySecret)
+            return false;
+        if (!this.constantTimeCompare(String(session[this.partitionKey] ?? ""), sessionKeyHash))
+            return false;
+        if (!this.constantTimeCompare(String(session[this.sortKey] ?? ""), this.hashToken(sessionSortKeySecret)))
             return false;
-        if (!session.csrfToken)
+        if (!session.csrfTokenHash)
             return false;
         if (!session.sessionKey)
             return false;
@@ -246,7 +279,7 @@ export default class LambderSessionManager {
         if (!skipCsrfTokenCheck) {
             if (!csrfToken || typeof csrfToken !== "string")
                 return false;
-            if (!this.constantTimeCompare(session.csrfToken, csrfToken))
+            if (!this.constantTimeCompare(session.csrfTokenHash, this.hashToken(csrfToken)))
                 return false;
         }
         return true;

package/dist/{LambderApiContract.d.ts → shared/LambderApiContract.d.ts}

@@ -12,6 +12,20 @@ export type ApiContractShape = Record<string, {
     /** Present when the API declares guardInput-mode guards: guard name -> value the client must send via options.guardInputs. */
     guardInputs?: any;
 }>;
+/** Envelope flags/channels the server may set beside (or instead of) the payload. */
+export type LambderApiResponseConfig = {
+    versionExpired?: boolean;
+    sessionExpired?: boolean;
+    notAuthorized?: boolean;
+    message?: any;
+    errorMessage?: any;
+    logList?: any[];
+};
+/** The API wire envelope both sides speak: res.api() emits it, LambderCaller parses it. */
+export type LambderApiResponse<T> = LambderApiResponseConfig & {
+    apiVersion?: string | null;
+    payload?: T | null;
+};
 /**
  * Helper type for merging new API into existing contract during chaining
  */

package/dist/{LambderApiError.d.ts → shared/LambderApiError.d.ts}

@@ -1,4 +1,4 @@
-import type { HttpStatusCode } from "./LambderResponse.js";
+import type { HttpStatusCode } from "../core/LambderResponse.js";
 export type LambderApiErrorOptions = {
     /**
      * Structured, user-facing failure detail placed on the API envelope's

package/dist/{LambderDdbCache.js → stores/LambderDdbCache.js}

@@ -1,5 +1,6 @@
 import { BatchWriteItemCommand, DeleteItemCommand, DynamoDBClient, GetItemCommand, PutItemCommand, QueryCommand, } from "@aws-sdk/client-dynamodb";
-import { getCrypto, getZlib } from "./node-polyfills.js";
+import { getCrypto } from "../shared/node-polyfills.js";
+import { brotliCompressText, brotliDecompressText } from "./LambderDdbCompression.js";
 import { LRUCache } from "lru-cache";
 const DEFAULT_TTL_SECONDS = 365 * 24 * 60 * 60;
 const DEFAULT_CHUNK_BYTES = 350 * 1024;
@@ -12,46 +13,14 @@ const BATCH_WRITE_LIMIT = 25;
 const MAX_BATCH_RETRIES = 8;
 // Node builtins are loaded lazily through node-polyfills so this module can
 // sit in a frontend bundle's import graph (via the package root) without
-// breaking; using the cache at runtime still requires Node.
-const requireZlib = async () => {
-    const zlib = await getZlib();
-    if (!zlib)
-        throw new Error("LambderDdbCache requires a Node.js environment.");
-    return zlib;
-};
+// breaking; using the cache at runtime still requires Node. Brotli helpers
+// are shared with LambderDdbIdempotency via ./LambderDdbCompression.js.
 const requireCrypto = async () => {
     const crypto = await getCrypto();
     if (!crypto)
         throw new Error("LambderDdbCache requires a Node.js environment.");
     return crypto;
 };
-const compress = async (input, quality) => {
-    const zlib = await requireZlib();
-    return new Promise((resolve, reject) => {
-        zlib.brotliCompress(input, {
-            params: {
-                [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
-                [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
-            },
-        }, (error, output) => {
-            if (error)
-                reject(error);
-            else
-                resolve(output);
-        });
-    });
-};
-const decompress = async (input, maxOutputLength) => {
-    const zlib = await requireZlib();
-    return new Promise((resolve, reject) => {
-        zlib.brotliDecompress(input, { maxOutputLength }, (error, output) => {
-            if (error)
-                reject(error);
-            else
-                resolve(output);
-        });
-    });
-};
 const sha256 = async (value) => {
     const crypto = await requireCrypto();
     return crypto.createHash("sha256").update(value).digest("hex");
@@ -127,7 +96,7 @@ export class LambderDdbCache {
         const nowSeconds = this.nowSeconds();
         if (cached && cached.expiresAt > nowSeconds) {
             try {
-                const output = await decompress(cached.compressed, this.maxValueBytes);
+                const output = await brotliDecompressText(cached.compressed, this.maxValueBytes);
                 if (output.length === cached.uncompressedBytes) {
                     return JSON.parse(output.toString("utf8"));
                 }
@@ -150,7 +119,7 @@ export class LambderDdbCache {
             if (await sha256(compressed) !== manifest.checksum) {
                 throw new Error("compressed checksum does not match manifest");
             }
-            const output = await decompress(compressed, this.maxValueBytes);
+            const output = await brotliDecompressText(compressed, this.maxValueBytes);
             if (output.length !== manifest.uncompressedBytes) {
                 throw new Error("uncompressed byte length does not match manifest");
             }
@@ -186,7 +155,7 @@ export class LambderDdbCache {
         if (input.length > this.maxValueBytes) {
             throw new Error(`Cache value exceeds maxValueBytes (${input.length} > ${this.maxValueBytes})`);
         }
-        const compressed = await compress(input, this.compressionQuality);
+        const compressed = await brotliCompressText(input, this.compressionQuality);
         if (compressed.length > this.maxValueBytes) {
             throw new Error(`Compressed cache value exceeds maxValueBytes (${compressed.length} > ${this.maxValueBytes})`);
         }

package/dist/stores/LambderDdbCompression.d.ts

@@ -0,0 +1,3 @@
+export declare const brotliCompressText: (input: Buffer, quality: number) => Promise<Buffer>;
+/** maxOutputLength bounds decompression so a corrupt record cannot balloon memory. */
+export declare const brotliDecompressText: (input: Buffer, maxOutputLength: number) => Promise<Buffer>;

package/dist/stores/LambderDdbCompression.js

@@ -0,0 +1,39 @@
+import { getZlib } from "../shared/node-polyfills.js";
+// Brotli compression shared by the DynamoDB-backed stores (LambderDdbCache,
+// LambderDdbIdempotency). Values they persist are text (JSON), so TEXT mode;
+// zlib is loaded lazily through node-polyfills so these modules can sit in a
+// frontend bundle's import graph (via the package root) without breaking.
+const requireZlib = async () => {
+    const zlib = await getZlib();
+    if (!zlib)
+        throw new Error("Lambder DDB stores require a Node.js environment.");
+    return zlib;
+};
+export const brotliCompressText = async (input, quality) => {
+    const zlib = await requireZlib();
+    return new Promise((resolve, reject) => {
+        zlib.brotliCompress(input, {
+            params: {
+                [zlib.constants.BROTLI_PARAM_QUALITY]: quality,
+                [zlib.constants.BROTLI_PARAM_MODE]: zlib.constants.BROTLI_MODE_TEXT,
+            },
+        }, (error, output) => {
+            if (error)
+                reject(error);
+            else
+                resolve(output);
+        });
+    });
+};
+/** maxOutputLength bounds decompression so a corrupt record cannot balloon memory. */
+export const brotliDecompressText = async (input, maxOutputLength) => {
+    const zlib = await requireZlib();
+    return new Promise((resolve, reject) => {
+        zlib.brotliDecompress(input, { maxOutputLength }, (error, output) => {
+            if (error)
+                reject(error);
+            else
+                resolve(output);
+        });
+    });
+};

package/dist/{LambderDdbIdempotency.d.ts → stores/LambderDdbIdempotency.d.ts}

@@ -4,19 +4,24 @@ export interface LambderDdbIdempotencyOptions {
     region?: string;
     /** Partition key prefix, keeps records separated from other systems in a shared table. Default: "IDEM". */
     keyPrefix?: string;
+    /** Brotli quality (0-11) for stored bodies, like LambderDdbCache. Default: 5. */
+    compressionQuality?: number;
     client?: DynamoDBClient;
 }
+export type LambderIdempotencyDoneRecord = {
+    statusCode: number;
+    /** Response headers stored with the record (normalized multi-value map). */
+    headers: Record<string, string[]>;
+    body: string;
+};
 export type LambderIdempotencyBeginResult = {
     state: "new";
     ownerToken: string;
 } | {
     state: "pending";
-} | {
+} | ({
     state: "done";
-    statusCode: number;
-    contentType: string | null;
-    body: string;
-};
+} & LambderIdempotencyDoneRecord);
 /**
  * DynamoDB-backed idempotency records: one item per (identity, api, key)
  * scope, claimed atomically with a conditional put. The first request claims
@@ -30,6 +35,11 @@ export type LambderIdempotencyBeginResult = {
  * and loses the scope to a retry can no longer overwrite or delete the
  * retry's claim (both settle calls become silent no-ops instead).
  *
+ * Stored bodies of 1KB or more are Brotli-compressed (same scheme as
+ * LambderDdbCache): the bodies are JSON envelopes that typically shrink
+ * 5-10x, which cuts DynamoDB write units and lets large responses fit the
+ * item budget instead of skipping replay storage.
+ *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on
  * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
  * shared with LambderDdbRateLimiter (`RL#`) and LambderDdbCache (`CACHE#`)
@@ -38,9 +48,21 @@ export type LambderIdempotencyBeginResult = {
 export declare class LambderDdbIdempotency {
     readonly tableName: string;
     readonly keyPrefix: string;
+    private readonly compressionQuality;
     private readonly client;
     constructor(options: LambderDdbIdempotencyOptions);
     private itemKey;
+    /** Parse a stored item's response headers. */
+    private static readItemHeaders;
+    /** A stored item's response body: plain (`body`) or Brotli (`bodyBr` + `bodyBytes`). */
+    private static readItemBody;
+    /**
+     * Read the scope without claiming it: the stored response when a
+     * completed, unexpired record exists, null otherwise (absent, pending, or
+     * expired). Eventually-consistent read: a miss here only means the caller
+     * proceeds to begin(), whose read is authoritative.
+     */
+    peek(scopeKey: string): Promise<LambderIdempotencyDoneRecord | null>;
     /**
      * Claim the scope. "new" means this request now owns it (proven by the
      * returned ownerToken) and must call complete() or abandon(); "pending"
@@ -51,17 +73,24 @@ export declare class LambderDdbIdempotency {
         pendingTtlSeconds: number;
     }): Promise<LambderIdempotencyBeginResult>;
     /**
-     * Store the response for replays, overwriting the pending claim. Requires
-     * still holding the claim: returns false (storing nothing) when the
-     * ownerToken no longer matches, i.e. the claim expired and a retry took
-     * the scope over.
+     * Store the response for replays, overwriting the pending claim. Bodies
+     * of COMPRESS_MIN_BYTES or more are stored Brotli-compressed (they are
+     * JSON envelopes, which typically shrink 5-10x), cutting DynamoDB write
+     * units and letting large responses fit the item budget; smaller bodies
+     * stay plain. Returns:
+     *
+     * - "stored": the record is in place and will replay.
+     * - "too-large": even compressed, the body exceeds the item budget;
+     *   nothing was written and the caller should release the claim.
+     * - "lost": the ownerToken no longer matches, i.e. the claim expired and
+     *   a retry took the scope over; nothing was written.
      */
-    complete(scopeKey: string, ownerToken: string, { statusCode, contentType, body, ttlSeconds }: {
+    complete(scopeKey: string, ownerToken: string, { statusCode, headers, body, ttlSeconds }: {
         statusCode: number;
-        contentType: string | null;
+        headers: Record<string, string[]>;
         body: string;
         ttlSeconds: number;
-    }): Promise<boolean>;
+    }): Promise<"stored" | "too-large" | "lost">;
     /**
      * Release the claim without storing a response (crash, uncacheable
      * response), so a retry can execute. Conditional on still holding the

package/dist/{LambderDdbIdempotency.js → stores/LambderDdbIdempotency.js}

@@ -1,5 +1,14 @@
 import crypto from "crypto";
 import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } from "@aws-sdk/client-dynamodb";
+import { brotliCompressText, brotliDecompressText } from "./LambderDdbCompression.js";
+/** Bodies at or above this size are stored Brotli-compressed; smaller ones stay plain. */
+const COMPRESS_MIN_BYTES = 1024;
+/**
+ * Stored-body budget inside DynamoDB's 400KB item limit (headers, keys and
+ * attributes need headroom). Applies to the bytes actually stored, so a
+ * large compressible response (JSON usually shrinks 5-10x) still replays.
+ */
+const MAX_STORED_BODY_BYTES = 350_000;
 /**
  * DynamoDB-backed idempotency records: one item per (identity, api, key)
  * scope, claimed atomically with a conditional put. The first request claims
@@ -13,6 +22,11 @@ import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } fr
  * and loses the scope to a retry can no longer overwrite or delete the
  * retry's claim (both settle calls become silent no-ops instead).
  *
+ * Stored bodies of 1KB or more are Brotli-compressed (same scheme as
+ * LambderDdbCache): the bodies are JSON envelopes that typically shrink
+ * 5-10x, which cuts DynamoDB write units and lets large responses fit the
+ * item budget instead of skipping replay storage.
+ *
  * Table shape: string hash key `pk`, string range key `sk`, TTL on
  * `expiresAt`. Items are prefixed `IDEM#` by default, so the table can be
  * shared with LambderDdbRateLimiter (`RL#`) and LambderDdbCache (`CACHE#`)
@@ -21,17 +35,73 @@ import { DynamoDBClient, PutItemCommand, GetItemCommand, DeleteItemCommand, } fr
 export class LambderDdbIdempotency {
     tableName;
     keyPrefix;
+    compressionQuality;
     client;
     constructor(options) {
         if (!options.tableName.trim())
             throw new Error("tableName is required");
         this.tableName = options.tableName;
         this.keyPrefix = options.keyPrefix ?? "IDEM";
+        this.compressionQuality = options.compressionQuality ?? 5;
+        if (!Number.isInteger(this.compressionQuality) || this.compressionQuality < 0 || this.compressionQuality > 11) {
+            throw new Error("compressionQuality must be an integer from 0 to 11");
+        }
         this.client = options.client ?? new DynamoDBClient(options.region ? { region: options.region } : {});
     }
     itemKey(scopeKey) {
         return { pk: { S: `${this.keyPrefix}#${scopeKey}` }, sk: { S: "idem" } };
     }
+    /** Parse a stored item's response headers. */
+    static readItemHeaders(item) {
+        const raw = item.headersJson?.S;
+        if (!raw)
+            return {};
+        try {
+            const parsed = JSON.parse(raw);
+            if (parsed && typeof parsed === "object")
+                return parsed;
+        }
+        catch { /* corrupt record: replay with no headers rather than fail */ }
+        return {};
+    }
+    /** A stored item's response body: plain (`body`) or Brotli (`bodyBr` + `bodyBytes`). */
+    static async readItemBody(item) {
+        const compressed = item.bodyBr?.B;
+        if (compressed) {
+            const declaredBytes = Number(item.bodyBytes?.N ?? 0);
+            if (!declaredBytes)
+                throw new Error("LambderDdbIdempotency: compressed record is missing bodyBytes.");
+            const output = await brotliDecompressText(Buffer.from(compressed), declaredBytes);
+            if (output.length !== declaredBytes) {
+                throw new Error("LambderDdbIdempotency: stored body length does not match its record.");
+            }
+            return output.toString("utf8");
+        }
+        return item.body?.S ?? "";
+    }
+    /**
+     * Read the scope without claiming it: the stored response when a
+     * completed, unexpired record exists, null otherwise (absent, pending, or
+     * expired). Eventually-consistent read: a miss here only means the caller
+     * proceeds to begin(), whose read is authoritative.
+     */
+    async peek(scopeKey) {
+        const existing = await this.client.send(new GetItemCommand({
+            TableName: this.tableName,
+            Key: this.itemKey(scopeKey),
+        }));
+        const item = existing.Item;
+        if (!item || item.state?.S !== "done")
+            return null;
+        const nowSeconds = Math.floor(Date.now() / 1000);
+        if (Number(item.expiresAt?.N ?? 0) <= nowSeconds)
+            return null;
+        return {
+            statusCode: Number(item.statusCode?.N ?? 200),
+            headers: LambderDdbIdempotency.readItemHeaders(item),
+            body: await LambderDdbIdempotency.readItemBody(item),
+        };
+    }
     /**
      * Claim the scope. "new" means this request now owns it (proven by the
      * returned ownerToken) and must call complete() or abandon(); "pending"
@@ -72,20 +142,39 @@ export class LambderDdbIdempotency {
             return {
                 state: "done",
                 statusCode: Number(item.statusCode?.N ?? 200),
-                contentType: item.contentType?.S ?? null,
-                body: item.body?.S ?? "",
+                headers: LambderDdbIdempotency.readItemHeaders(item),
+                body: await LambderDdbIdempotency.readItemBody(item),
             };
         }
         return { state: "pending" };
     }
     /**
-     * Store the response for replays, overwriting the pending claim. Requires
-     * still holding the claim: returns false (storing nothing) when the
-     * ownerToken no longer matches, i.e. the claim expired and a retry took
-     * the scope over.
+     * Store the response for replays, overwriting the pending claim. Bodies
+     * of COMPRESS_MIN_BYTES or more are stored Brotli-compressed (they are
+     * JSON envelopes, which typically shrink 5-10x), cutting DynamoDB write
+     * units and letting large responses fit the item budget; smaller bodies
+     * stay plain. Returns:
+     *
+     * - "stored": the record is in place and will replay.
+     * - "too-large": even compressed, the body exceeds the item budget;
+     *   nothing was written and the caller should release the claim.
+     * - "lost": the ownerToken no longer matches, i.e. the claim expired and
+     *   a retry took the scope over; nothing was written.
      */
-    async complete(scopeKey, ownerToken, { statusCode, contentType, body, ttlSeconds }) {
+    async complete(scopeKey, ownerToken, { statusCode, headers, body, ttlSeconds }) {
         const nowSeconds = Math.floor(Date.now() / 1000);
+        const rawBody = Buffer.from(body, "utf8");
+        let bodyAttributes;
+        if (rawBody.byteLength >= COMPRESS_MIN_BYTES) {
+            const compressed = await brotliCompressText(rawBody, this.compressionQuality);
+            if (compressed.byteLength > MAX_STORED_BODY_BYTES)
+                return "too-large";
+            // bodyBytes bounds and verifies decompression on read.
+            bodyAttributes = { bodyBr: { B: compressed }, bodyBytes: { N: String(rawBody.byteLength) } };
+        }
+        else {
+            bodyAttributes = { body: { S: body } };
+        }
         try {
             await this.client.send(new PutItemCommand({
                 TableName: this.tableName,
@@ -94,19 +183,19 @@ export class LambderDdbIdempotency {
                     state: { S: "done" },
                     ownerToken: { S: ownerToken },
                     statusCode: { N: String(statusCode) },
-                    ...(contentType ? { contentType: { S: contentType } } : {}),
-                    body: { S: body },
+                    headersJson: { S: JSON.stringify(headers) },
+                    ...bodyAttributes,
                     expiresAt: { N: String(nowSeconds + ttlSeconds) },
                 },
                 ConditionExpression: "ownerToken = :owner",
                 ExpressionAttributeValues: { ":owner": { S: ownerToken } },
             }));
-            return true;
+            return "stored";
         }
         catch (error) {
             if (error.name !== "ConditionalCheckFailedException")
                 throw error;
-            return false;
+            return "lost";
         }
     }
     /**

package/dist/{LambderDdbRateLimiter.js → stores/LambderDdbRateLimiter.js}

@@ -81,8 +81,12 @@ export class LambderDdbRateLimiter {
         catch (error) {
             if (error.name === "ConditionalCheckFailedException")
                 return true;
-            if (this.failOpen)
+            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/testing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Testing entry point (`import ... from "lambder/testing"`).
+ *
+ * Mock tooling that neither the server nor the production client bundle
+ * should carry: the MSW adapter that serves an app's typed API contract
+ * from in-browser mock handlers during development and tests.
+ */
+export { default as LambderMSW } from "./client/LambderMSW.js";
+export type { LambderMswModule } from "./client/LambderMSW.js";

package/dist/testing.js

@@ -0,0 +1,8 @@
+/**
+ * Testing entry point (`import ... from "lambder/testing"`).
+ *
+ * Mock tooling that neither the server nor the production client bundle
+ * should carry: the MSW adapter that serves an app's typed API contract
+ * from in-browser mock handlers during development and tests.
+ */
+export { default as LambderMSW } from "./client/LambderMSW.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "3.8.1",
+  "version": "4.0.1",
   "description": "",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -9,6 +9,24 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "client": [
+        "./dist/client.d.ts"
+      ],
+      "testing": [
+        "./dist/testing.d.ts"
+      ]
     }
   },
   "browser": {