lambder 5.1.3 → 6.0.2

package/dist/session/LambderSessionManager.js

@@ -1,7 +1,6 @@
 import crypto from "crypto";
-import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
-import { DynamoDBDocumentClient, QueryCommand, DeleteCommand, PutCommand, GetCommand, UpdateCommand } from "@aws-sdk/lib-dynamodb";
-import { compressText, restoreBoundedText } from "../shared/LambderCompressionCodec.js";
+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
@@ -42,7 +41,9 @@ export default class LambderSessionManager {
     sessionSalt;
     partitionKey;
     sortKey;
-    ddbDocumentClient;
+    tableRegion;
+    /** The document client and the SDK it came from, created the first time the table is touched. */
+    readyPromise;
     enableSlidingExpiration;
     slidingWriteIntervalSeconds;
     dataRefresh;
@@ -56,8 +57,14 @@ export default class LambderSessionManager {
         this.slidingWriteIntervalSeconds = slidingWriteIntervalSeconds ?? null;
         this.dataRefresh = dataRefresh ?? null;
         this.compression = resolveCompressionOption(compression, SESSION_COMPRESSION_DEFAULTS);
-        const ddbClient = new DynamoDBClient({ region: tableRegion });
-        this.ddbDocumentClient = DynamoDBDocumentClient.from(ddbClient);
+        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;
     }
     sessionUserKeyHasher(password) {
         return crypto.createHash("sha256")
@@ -81,7 +88,8 @@ export default class LambderSessionManager {
         return crypto.timingSafeEqual(new Uint8Array(bufferA), new Uint8Array(bufferB));
     }
     async ddbGetItem(key) {
-        const response = await this.ddbDocumentClient.send(new GetCommand({ TableName: this.tableName, Key: key, ConsistentRead: true }));
+        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;
@@ -102,11 +110,13 @@ export default class LambderSessionManager {
         else {
             item.data = data;
         }
-        return await this.ddbDocumentClient.send(new PutCommand({ TableName: this.tableName, Item: item, }));
+        const { client, sdk } = await this.ready();
+        return await client.send(new sdk.PutCommand({ TableName: this.tableName, Item: item, }));
     }
     ;
     async ddbDeleteItem(key) {
-        return await this.ddbDocumentClient.send(new DeleteCommand({ TableName: this.tableName, Key: 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). */
@@ -120,7 +130,8 @@ export default class LambderSessionManager {
         };
         const queryResults = [];
         do {
-            const { Items, LastEvaluatedKey } = await this.ddbDocumentClient.send(new QueryCommand(params));
+            const { client, sdk } = await this.ready();
+            const { Items, LastEvaluatedKey } = await client.send(new sdk.QueryCommand(params));
             if (Items)
                 queryResults.push(...Items);
             params.ExclusiveStartKey = LastEvaluatedKey;
@@ -133,7 +144,8 @@ export default class LambderSessionManager {
     async ddbDeleteAllByPartitionKey(partitionValue) {
         const queryResults = await this.ddbQueryAllByPartitionKey(partitionValue);
         for (const item of queryResults) {
-            await this.ddbDocumentClient.send(new DeleteCommand({
+            const { client, sdk } = await this.ready();
+            await client.send(new sdk.DeleteCommand({
                 TableName: this.tableName,
                 Key: { [this.partitionKey]: partitionValue, [this.sortKey]: item[this.sortKey] }
             }));
@@ -202,7 +214,7 @@ export default class LambderSessionManager {
         // that fails to decode throws, which the controller treats like any
         // malformed record: no session.
         if (session.dataBr) {
-            session.data = JSON.parse(await restoreBoundedText(session.dataBr, session.dataBytes, "br"));
+            session.data = JSON.parse(await restoreText(session.dataBr, "br", { declaredBytes: session.dataBytes }));
             delete session.dataBr;
             delete session.dataBytes;
         }
@@ -360,7 +372,8 @@ export default class LambderSessionManager {
         const now = Math.floor(Date.now() / 1000);
         for (const item of await this.ddbQueryAllByPartitionKey(partitionValue)) {
             try {
-                await this.ddbDocumentClient.send(new UpdateCommand({
+                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",

package/dist/shared/LambderApiContract.d.ts

@@ -19,6 +19,7 @@ export type ApiContractShape = Record<string, {
      */
     guards?: any;
 }>;
+import type { LambderCrashDetail } from "./LambderCrashDetail.js";
 /** Envelope flags/channels the server may set beside (or instead of) the payload. */
 export type LambderApiResponseConfig = {
     versionExpired?: boolean;
@@ -27,6 +28,14 @@ export type LambderApiResponseConfig = {
     message?: any;
     errorMessage?: any;
     logList?: any[];
+    /**
+     * A crash described in full (name, message, stack, cause chain, where it
+     * happened), for a caller that is allowed to see it: a global error
+     * handler answering a trusted invoker sets it with describeCrash().
+     * LambderInvokeCaller reads it back as the cause of the error it throws;
+     * the browser caller ignores it.
+     */
+    crash?: LambderCrashDetail;
 };
 /** The API wire envelope both sides speak: res.api() emits it, LambderCaller parses it. */
 export type LambderApiResponse<T> = LambderApiResponseConfig & {

package/dist/shared/LambderApiOutcome.d.ts

@@ -0,0 +1,69 @@
+/**
+ * The one mapping from an HTTP answer to an API outcome.
+ *
+ * LambderCaller (a browser, over fetch) and LambderInvokeCaller (a server,
+ * over a direct Lambda invoke) receive the same envelope and must read it
+ * the same way: which status is a crash, which is a rejected input, in what
+ * order the envelope flags are honoured, what a non-envelope body means.
+ * Both hand their answer to resolveApiOutcome and act on the result; the
+ * side effects each has (handlers, cookie clearing, error reporting) stay
+ * with the caller that owns them. Pure and dependency-free, so the browser
+ * entry resolves it.
+ */
+import type { z } from "zod";
+import type { LambderApiResponse } from "./LambderApiContract.js";
+/**
+ * The 422 body's `zodError` as it survives JSON: a ZodError's name and
+ * message, and its issues spelled out. Not a ZodError instance (it has no
+ * methods on this side of the wire), which is why it is not typed as one.
+ */
+export type LambderValidationError = {
+    name: string;
+    message: string;
+    issues: z.core.$ZodIssue[];
+};
+export type LambderApiFailureReason = 'network' | 'timeout' | 'server' | 'validation' | 'versionExpired' | 'sessionExpired' | 'notAuthorized' | 'errorMessage' | 'unknown';
+/**
+ * Discriminated result of an API call: `ok: true` carries the payload, every
+ * failure carries a machine-readable reason, so "the server returned null"
+ * and "the request failed" are never conflated.
+ */
+export type LambderApiOutcome<T> = {
+    ok: true;
+    payload: T | null | undefined;
+    response: LambderApiResponse<T>;
+} | {
+    ok: false;
+    reason: LambderApiFailureReason;
+    /** HTTP status, when a response was received. */
+    status?: number;
+    /** Envelope errorMessage, when the server provided one. */
+    errorMessage?: any;
+    /** Seconds to wait before retrying, from the response's Retry-After header (rate-limit refusals send it). */
+    retryAfterSeconds?: number;
+    /** Underlying Error for network/timeout/server/unknown failures. */
+    error?: Error;
+    /** The issues for 'validation'. */
+    zodError?: LambderValidationError;
+    /** The parsed envelope, when one was received (protocol-level failures, and a 5xx that answered with Lambder's own envelope). */
+    response?: LambderApiResponse<T>;
+};
+/** What the mapping needs from an HTTP answer, whichever transport produced it. */
+export type LambderApiHttpAnswer = {
+    status: number;
+    statusText?: string;
+    /** Case-insensitive header lookup; null or undefined when absent. */
+    header: (name: string) => string | null | undefined;
+    /** The body parsed as JSON; rejects when it is not JSON. */
+    json: () => Promise<unknown>;
+    /** The body as text. */
+    text: () => Promise<string>;
+};
+/**
+ * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
+ * the envelope when the server sent one (Lambder's own 500 body carries
+ * errorMessage, and a global error handler may add crash and logList); a
+ * 422 is a validation failure only with Lambder's validation body; anything
+ * else must be a JSON envelope, whose flags are honoured in a fixed order.
+ */
+export declare const resolveApiOutcome: <T>(answer: LambderApiHttpAnswer) => Promise<LambderApiOutcome<T>>;

package/dist/shared/LambderApiOutcome.js

@@ -0,0 +1,79 @@
+/**
+ * The one mapping from an HTTP answer to an API outcome.
+ *
+ * LambderCaller (a browser, over fetch) and LambderInvokeCaller (a server,
+ * over a direct Lambda invoke) receive the same envelope and must read it
+ * the same way: which status is a crash, which is a rejected input, in what
+ * order the envelope flags are honoured, what a non-envelope body means.
+ * Both hand their answer to resolveApiOutcome and act on the result; the
+ * side effects each has (handlers, cookie clearing, error reporting) stay
+ * with the caller that owns them. Pure and dependency-free, so the browser
+ * entry resolves it.
+ */
+/**
+ * Reads one HTTP answer into an outcome. A 5xx is a server failure that keeps
+ * the envelope when the server sent one (Lambder's own 500 body carries
+ * errorMessage, and a global error handler may add crash and logList); a
+ * 422 is a validation failure only with Lambder's validation body; anything
+ * else must be a JSON envelope, whose flags are honoured in a fixed order.
+ */
+export const resolveApiOutcome = async (answer) => {
+    const status = answer.status;
+    if (status >= 500) {
+        // Lambder's own 500 fallback is a JSON envelope, but custom error
+        // handlers may answer text/HTML: parse defensively.
+        let envelope;
+        try {
+            const bodyText = await answer.text();
+            try {
+                const parsed = JSON.parse(bodyText);
+                if (parsed !== null && typeof parsed === "object")
+                    envelope = parsed;
+            }
+            catch { /* not an envelope */ }
+        }
+        catch { /* body unavailable */ }
+        return {
+            ok: false, reason: 'server', status,
+            errorMessage: envelope?.errorMessage,
+            ...(envelope ? { response: envelope } : {}),
+            error: new Error("Request failed: " + status + " - " + (answer.statusText ?? "")),
+        };
+    }
+    if (status === 422) {
+        // A 422 without Lambder's validation body (e.g. a proxy's error page)
+        // is a server failure, not a validation result.
+        let zodError;
+        try {
+            zodError = (await answer.json())?.zodError;
+        }
+        catch { /* not JSON */ }
+        if (zodError === undefined) {
+            return { ok: false, reason: 'server', status, error: new Error("Request failed: 422 without a validation body") };
+        }
+        return { ok: false, reason: 'validation', status, zodError };
+    }
+    // Retry-After (delta-seconds) rides every refusal that knows its reset
+    // time, e.g. a rate limit; absent or unreadable is undefined.
+    const retryAfterValue = Number(answer.header("retry-after") ?? NaN);
+    const retryAfter = Number.isFinite(retryAfterValue) && retryAfterValue >= 0 ? { retryAfterSeconds: retryAfterValue } : {};
+    let data;
+    try {
+        data = await answer.json();
+        if (data === null || typeof data !== "object")
+            throw new Error("Response is not an object");
+    }
+    catch (err) {
+        // A non-envelope body (e.g. an HTML error page) is a server failure.
+        return { ok: false, reason: 'server', status, error: new Error("Request failed: response is not a valid API envelope (status " + status + ")", { cause: err }) };
+    }
+    if (data.versionExpired)
+        return { ok: false, reason: 'versionExpired', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    if (data.sessionExpired)
+        return { ok: false, reason: 'sessionExpired', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    if (data.notAuthorized)
+        return { ok: false, reason: 'notAuthorized', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    if (data.errorMessage)
+        return { ok: false, reason: 'errorMessage', status, errorMessage: data.errorMessage, response: data, ...retryAfter };
+    return { ok: true, payload: data.payload, response: data };
+};

package/dist/shared/LambderCallOptions.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The contract-driven typing of a call's options argument, and the runtime
+ * merge of guard inputs, shared by the browser caller (LambderCaller) and the
+ * server-side invoke caller (LambderInvokeCaller). Both speak the same
+ * envelope to the same kind of contract, so what an API demands of its caller
+ * (a guardInput-mode guard's value, say) is decided here once and the two
+ * callers cannot drift on it. Pure types and one dependency-free function,
+ * so the browser entry resolves it.
+ */
+export type IsAny<T> = 0 extends (1 & T) ? true : false;
+export type GuardInputsOf<TEntry> = TEntry extends {
+    guardInputs: infer G;
+} ? G : never;
+/** Input type of guard G on one contract entry; never when that API does not declare it. */
+type GuardInputOf<TEntry, G extends string> = GuardInputsOf<TEntry> extends infer I ? (G extends keyof I ? I[G] : never) : never;
+/**
+ * What guardInputsProvider returns: for every provided guard name, the value
+ * the contract's APIs expect for it (a union across APIs when they differ).
+ * Naming a guard no API declares in guardInput mode resolves to never, so a
+ * typo fails the provider's return type instead of going missing at runtime.
+ */
+export type LambderProvidedGuardInputs<TContract, TProvided extends string> = IsAny<TContract> extends true ? Record<TProvided, unknown> : {
+    [G in TProvided]: {
+        [K in keyof TContract]: GuardInputOf<TContract[K], G>;
+    }[keyof TContract];
+};
+/**
+ * Supplies guardInputs for every call from one place (the organization the
+ * UI is on, a device token), keyed by guard name; per-call guardInputs
+ * merge on top. Name the guards it covers in the caller's second type
+ * parameter, `new LambderCaller<Contract, "orgPermission">`, and calls to
+ * APIs whose guardInput guards are all covered no longer require the
+ * options argument. May be async; a throw fails the call as an unknown
+ * error before anything is sent.
+ */
+export type LambderGuardInputsProvider<TContract, TProvided extends string> = (apiName: keyof TContract & string) => LambderProvidedGuardInputs<TContract, TProvided> | Promise<LambderProvidedGuardInputs<TContract, TProvided>>;
+/** Optional until the caller names provided guards: naming them without a provider would send nothing. */
+export type LambderGuardInputsProviderOption<TContract, TProvided extends string> = [
+    TProvided
+] extends [never] ? {
+    guardInputsProvider?: LambderGuardInputsProvider<TContract, TProvided>;
+} : {
+    guardInputsProvider: LambderGuardInputsProvider<TContract, TProvided>;
+};
+/** An API's guardInput guards the provider does not cover: those the call must still pass. */
+type RemainingGuardInputs<TEntry, TProvided extends string> = Omit<GuardInputsOf<TEntry>, TProvided>;
+/**
+ * The options argument of one call: optional normally, REQUIRED (with
+ * guardInputs) when the API's contract declares guardInput-mode guards the
+ * provider does not cover, so forgetting to send a guard's value is a
+ * compile error at the call site. Provided guards may still be overridden
+ * per call. TOptions is the caller's own per-call options type; the
+ * guardInputs requirement is layered on top of it.
+ */
+export type LambderCallOptionsArg<TContract, TApiName, TProvided extends string, TOptions extends {
+    guardInputs?: Record<string, unknown>;
+}> = IsAny<TContract> extends true ? [options?: TOptions] : TApiName extends keyof TContract ? [GuardInputsOf<TContract[TApiName]>] extends [never] ? [options?: TOptions] : [keyof RemainingGuardInputs<TContract[TApiName], TProvided>] extends [never] ? [options?: TOptions & {
+    guardInputs?: Partial<GuardInputsOf<TContract[TApiName]>>;
+}] : [
+    options: TOptions & {
+        guardInputs: RemainingGuardInputs<TContract[TApiName], TProvided> & Partial<GuardInputsOf<TContract[TApiName]>>;
+    }
+] : [options?: TOptions];
+/**
+ * Provider values underneath, per-call values on top; undefined when neither
+ * side supplied any. Synchronous on purpose: a caller awaits its provider
+ * only when it has one, so a call without a provider still issues its
+ * request in the same tick it was made.
+ */
+export declare const mergeGuardInputs: (provided: Record<string, unknown> | undefined, perCall: Record<string, unknown> | undefined) => Record<string, unknown> | undefined;
+export {};

package/dist/shared/LambderCallOptions.js

@@ -0,0 +1,16 @@
+/**
+ * The contract-driven typing of a call's options argument, and the runtime
+ * merge of guard inputs, shared by the browser caller (LambderCaller) and the
+ * server-side invoke caller (LambderInvokeCaller). Both speak the same
+ * envelope to the same kind of contract, so what an API demands of its caller
+ * (a guardInput-mode guard's value, say) is decided here once and the two
+ * callers cannot drift on it. Pure types and one dependency-free function,
+ * so the browser entry resolves it.
+ */
+/**
+ * Provider values underneath, per-call values on top; undefined when neither
+ * side supplied any. Synchronous on purpose: a caller awaits its provider
+ * only when it has one, so a call without a provider still issues its
+ * request in the same tick it was made.
+ */
+export const mergeGuardInputs = (provided, perCall) => provided !== undefined || perCall !== undefined ? { ...provided, ...perCall } : undefined;

package/dist/shared/LambderCompressionCodec.d.ts

@@ -3,10 +3,15 @@
  *
  * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
  * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
- * and request payloads (gzip, because the browser's CompressionStream
- * offers nothing else). They all compress text, so TEXT mode throughout,
- * and they all restore it the same way: the compressed bytes beside the
- * text's original UTF-8 byte length.
+ * and request payloads (gzip from a browser, whose CompressionStream offers
+ * nothing else; Brotli from a Node caller). They all compress text, so TEXT
+ * mode throughout, and they all restore it the same way: the compressed
+ * bytes beside the text's original UTF-8 byte length. The one restore
+ * without a declared length is a compressed HTTP answer read by
+ * LambderInvokeCaller, which passes a ceiling instead; both restores take
+ * either bound. That answer is also the one restore whose bytes may not be
+ * text at all, so the restore comes in two: restoreBytes returns the buffer
+ * and restoreText decodes it.
  *
  * That length is the safety mechanism, not bookkeeping. It bounds the
  * decompression, so a body that would expand without limit is cut off
@@ -48,8 +53,40 @@ export declare class LambderCompressionError extends Error {
  */
 export declare const compressText: (input: Buffer, encoding: LambderEncoding, quality: number) => Promise<Buffer>;
 /**
- * Restores text from compressed bytes beside the declared UTF-8 byte length
- * of the original, bounded and verified by that length. Throws
- * LambderCompressionError on anything it cannot vouch for.
+ * What bounds a restore: the text's declared UTF-8 byte length, stored
+ * beside the bytes (the decompression stops there and the result must match
+ * it exactly), or a ceiling alone, for bytes whose sender recorded no length
+ * (a compressed HTTP answer): the decompression stops there and nothing is
+ * verified.
  */
-export declare const restoreBoundedText: (compressed: Uint8Array, declaredBytes: number, encoding: LambderEncoding) => Promise<string>;
+export type LambderRestoreBound = {
+    declaredBytes: number;
+} | {
+    maxBytes: number;
+};
+/**
+ * Restores the original bytes from compressed bytes under a bound. With
+ * `declaredBytes` (records at rest, request payloads) the length both bounds
+ * the decompression and verifies it, so a body that would expand without
+ * limit is cut off rather than allocated, and a truncated or tampered input
+ * fails instead of decoding to something merely plausible. With `maxBytes`
+ * only the ceiling holds; truncation and corruption are what zlib's
+ * stream-end check and gzip's CRC catch. Throws LambderCompressionError on
+ * anything it cannot vouch for. A nonsense ceiling is the caller's
+ * configuration error and throws a plain Error.
+ *
+ * This is the restore for bytes that are not text: a compressed binary
+ * answer (a wasm module, an image a route forced compression on) read by
+ * LambderInvokeCaller. Text callers use restoreText, which is this plus the
+ * UTF-8 decode; going through a string would replace every byte that is not
+ * valid UTF-8 and hand back a body that is silently not what was sent.
+ */
+export declare const restoreBytes: (compressed: Uint8Array, encoding: LambderEncoding, bound: LambderRestoreBound) => Promise<Buffer>;
+/**
+ * Restores text: restoreBytes plus the UTF-8 decode. What every text caller
+ * uses (sessions, the DynamoDB stores, request payloads). The declared byte
+ * length a `declaredBytes` bound carries is the text's UTF-8 byte length,
+ * which is the restored buffer's length, so the verification is the same one
+ * either way.
+ */
+export declare const restoreText: (compressed: Uint8Array, encoding: LambderEncoding, bound: LambderRestoreBound) => Promise<string>;

package/dist/shared/LambderCompressionCodec.js

@@ -3,10 +3,15 @@
  *
  * Five things compress: sessions, LambderDdbCache and LambderDdbIdempotency
  * (Brotli at rest in DynamoDB), HTTP responses (Brotli or gzip, negotiated)
- * and request payloads (gzip, because the browser's CompressionStream
- * offers nothing else). They all compress text, so TEXT mode throughout,
- * and they all restore it the same way: the compressed bytes beside the
- * text's original UTF-8 byte length.
+ * and request payloads (gzip from a browser, whose CompressionStream offers
+ * nothing else; Brotli from a Node caller). They all compress text, so TEXT
+ * mode throughout, and they all restore it the same way: the compressed
+ * bytes beside the text's original UTF-8 byte length. The one restore
+ * without a declared length is a compressed HTTP answer read by
+ * LambderInvokeCaller, which passes a ceiling instead; both restores take
+ * either bound. That answer is also the one restore whose bytes may not be
+ * text at all, so the restore comes in two: restoreBytes returns the buffer
+ * and restoreText decodes it.
  *
  * That length is the safety mechanism, not bookkeeping. It bounds the
  * decompression, so a body that would expand without limit is cut off
@@ -79,13 +84,30 @@ export const compressText = async (input, encoding, quality) => {
     });
 };
 /**
- * Restores text from compressed bytes beside the declared UTF-8 byte length
- * of the original, bounded and verified by that length. Throws
- * LambderCompressionError on anything it cannot vouch for.
+ * Restores the original bytes from compressed bytes under a bound. With
+ * `declaredBytes` (records at rest, request payloads) the length both bounds
+ * the decompression and verifies it, so a body that would expand without
+ * limit is cut off rather than allocated, and a truncated or tampered input
+ * fails instead of decoding to something merely plausible. With `maxBytes`
+ * only the ceiling holds; truncation and corruption are what zlib's
+ * stream-end check and gzip's CRC catch. Throws LambderCompressionError on
+ * anything it cannot vouch for. A nonsense ceiling is the caller's
+ * configuration error and throws a plain Error.
+ *
+ * This is the restore for bytes that are not text: a compressed binary
+ * answer (a wasm module, an image a route forced compression on) read by
+ * LambderInvokeCaller. Text callers use restoreText, which is this plus the
+ * UTF-8 decode; going through a string would replace every byte that is not
+ * valid UTF-8 and hand back a body that is silently not what was sent.
  */
-export const restoreBoundedText = async (compressed, declaredBytes, encoding) => {
-    if (!Number.isSafeInteger(declaredBytes) || declaredBytes <= 0) {
-        throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.missingLength, "compressed value is missing its byte length");
+export const restoreBytes = async (compressed, encoding, bound) => {
+    const verified = "declaredBytes" in bound;
+    const limit = verified ? bound.declaredBytes : bound.maxBytes;
+    if (!Number.isSafeInteger(limit) || limit <= 0) {
+        if (verified) {
+            throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.missingLength, "compressed value is missing its byte length");
+        }
+        throw new Error("restoreBytes: maxBytes must be a positive integer");
     }
     const zlib = await requireZlib();
     let output;
@@ -98,16 +120,24 @@ export const restoreBoundedText = async (compressed, declaredBytes, encoding) =>
                 resolve(result); };
             // maxOutputLength is the bound: zlib stops rather than allocating past it.
             if (encoding === "br")
-                zlib.brotliDecompress(compressed, { maxOutputLength: declaredBytes }, done);
+                zlib.brotliDecompress(compressed, { maxOutputLength: limit }, done);
             else
-                zlib.gunzip(compressed, { maxOutputLength: declaredBytes }, done);
+                zlib.gunzip(compressed, { maxOutputLength: limit }, done);
         });
     }
     catch (err) {
         throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.undecodable, "compressed value could not be decompressed", { cause: err });
     }
-    if (output.length !== declaredBytes) {
+    if (verified && output.length !== limit) {
         throw new LambderCompressionError(LAMBDER_RESTORE_FAILURES.lengthMismatch, "decompressed length does not match the declared length");
     }
-    return output.toString("utf8");
+    return output;
 };
+/**
+ * Restores text: restoreBytes plus the UTF-8 decode. What every text caller
+ * uses (sessions, the DynamoDB stores, request payloads). The declared byte
+ * length a `declaredBytes` bound carries is the text's UTF-8 byte length,
+ * which is the restored buffer's length, so the verification is the same one
+ * either way.
+ */
+export const restoreText = async (compressed, encoding, bound) => (await restoreBytes(compressed, encoding, bound)).toString("utf8");

package/dist/shared/LambderCrashDetail.d.ts

@@ -0,0 +1,48 @@
+/**
+ * A crash, described for a caller that is allowed to see it.
+ *
+ * A global error handler decides what a failed request learns about the
+ * failure. A browser gets a generic message; a trusted caller (another
+ * lambda invoking this one, a developer holding a debug cookie) can be
+ * handed the whole thing: the error's name, message and stack, its cause
+ * chain, and where it happened, so the caller can store it in its own
+ * error log and point at the right CloudWatch stream. The envelope carries
+ * it in the `crash` field beside errorMessage; LambderInvokeCaller reads it
+ * back and rebuilds an Error from it as the `cause` of the error it throws,
+ * so an error reporter that walks causes sees the callee's stack without
+ * being taught anything.
+ *
+ * Dependency-free and isomorphic: the type is part of the envelope both
+ * entries export, and describeCrash needs nothing from Node.
+ */
+export type LambderCrashCause = {
+    name: string;
+    message: string;
+    stack?: string | null;
+};
+export type LambderCrashDetail = LambderCrashCause & {
+    /** The Error `cause` chain, outermost first, a few levels deep. */
+    causeList?: LambderCrashCause[];
+    /** The failed invocation's own awsRequestId, from the render context's lambdaContext. */
+    requestId?: string | null;
+    /** The function it happened in, from the same place. */
+    functionName?: string | null;
+};
+/**
+ * Describes whatever was thrown. Pass the render context (the global error
+ * handler's second argument) so the detail names the invocation it came
+ * from; it is optional because the handler receives null when the context
+ * itself could not be built.
+ */
+export declare const describeCrash: (error: unknown, ctx?: {
+    lambdaContext?: {
+        awsRequestId?: string;
+        functionName?: string;
+    } | null;
+} | null) => LambderCrashDetail;
+/**
+ * Rebuilds an Error (with its cause chain) from a crash detail, so a caller
+ * can chain it as the `cause` of its own error and reporters that walk
+ * causes see the callee's stack as it was.
+ */
+export declare const errorFromCrashDetail: (crash: LambderCrashDetail) => Error;

package/dist/shared/LambderCrashDetail.js

@@ -0,0 +1,78 @@
+/**
+ * A crash, described for a caller that is allowed to see it.
+ *
+ * A global error handler decides what a failed request learns about the
+ * failure. A browser gets a generic message; a trusted caller (another
+ * lambda invoking this one, a developer holding a debug cookie) can be
+ * handed the whole thing: the error's name, message and stack, its cause
+ * chain, and where it happened, so the caller can store it in its own
+ * error log and point at the right CloudWatch stream. The envelope carries
+ * it in the `crash` field beside errorMessage; LambderInvokeCaller reads it
+ * back and rebuilds an Error from it as the `cause` of the error it throws,
+ * so an error reporter that walks causes sees the callee's stack without
+ * being taught anything.
+ *
+ * Dependency-free and isomorphic: the type is part of the envelope both
+ * entries export, and describeCrash needs nothing from Node.
+ */
+const MAX_NAME_CHARS = 200;
+const MAX_MESSAGE_CHARS = 2000;
+const MAX_STACK_CHARS = 8000;
+const MAX_CAUSE_DEPTH = 3;
+const clamp = (value, max) => (value.length > max ? value.slice(0, max) : value);
+const describeCause = (error) => ({
+    name: clamp(error.name || "Error", MAX_NAME_CHARS),
+    message: clamp(error.message || String(error), MAX_MESSAGE_CHARS),
+    stack: error.stack ? clamp(error.stack, MAX_STACK_CHARS) : null,
+});
+/**
+ * Describes whatever was thrown. Pass the render context (the global error
+ * handler's second argument) so the detail names the invocation it came
+ * from; it is optional because the handler receives null when the context
+ * itself could not be built.
+ */
+export const describeCrash = (error, ctx) => {
+    const where = {
+        requestId: ctx?.lambdaContext?.awsRequestId ?? null,
+        functionName: ctx?.lambdaContext?.functionName ?? null,
+    };
+    if (error instanceof Error) {
+        const causeList = [];
+        let cause = error.cause;
+        let depth = 0;
+        while (cause instanceof Error && depth < MAX_CAUSE_DEPTH) {
+            causeList.push(describeCause(cause));
+            cause = cause.cause;
+            depth += 1;
+        }
+        return { ...describeCause(error), ...(causeList.length ? { causeList } : {}), ...where };
+    }
+    if (typeof error === "string") {
+        return { name: "Error", message: clamp(error, MAX_MESSAGE_CHARS), stack: null, ...where };
+    }
+    let message;
+    try {
+        message = JSON.stringify(error) ?? String(error);
+    }
+    catch {
+        message = String(error);
+    }
+    return { name: "UnknownError", message: clamp(message, MAX_MESSAGE_CHARS), stack: null, ...where };
+};
+/**
+ * Rebuilds an Error (with its cause chain) from a crash detail, so a caller
+ * can chain it as the `cause` of its own error and reporters that walk
+ * causes see the callee's stack as it was.
+ */
+export const errorFromCrashDetail = (crash) => {
+    const build = (entry, cause) => {
+        const error = new Error(entry.message, cause ? { cause } : undefined);
+        error.name = entry.name;
+        error.stack = entry.stack ?? `${entry.name}: ${entry.message}`;
+        return error;
+    };
+    let cause;
+    for (const entry of [...(crash.causeList ?? [])].reverse())
+        cause = build(entry, cause);
+    return build(crash, cause);
+};