lambder 7.3.1 → 8.0.2

package/dist/core/LambderTemplatingEngine.js

@@ -1,27 +1,169 @@
 import { getFS } from "../shared/util/LambderNodeModules.js";
 import { renderHtmlValue } from "../shared/LambderHtml.js";
+import { HtmlPositionReader, URL_ATTRIBUTE_NAMES, safeUrlValue, valueLanguageOf } from "../shared/LambderHtmlPositions.js";
 const TOKEN_PATTERN = /<!--\s*(?:(slot:([\w-]+)\s*\/)|(slot:([\w-]+))|(\/slot:([\w-]+))|(if:(!?)([\w-]+))|(else)|(\/if:(!?)([\w-]+)))\s*-->/g;
 /**
  * Fail loudly on slot positions where HTML escaping cannot protect against
- * injection: unquoted attribute values (`class=<!--slot:x/-->`) and inside
- * <script>/<style> elements (HTML escaping is the wrong grammar there; embed
- * data with jsonScript() into a normal slot instead).
+ * injection:
+ * - an unquoted attribute value (`class=<!--slot:x/-->`, with or without a
+ *   prefix before the slot), where a space in the value starts a new
+ *   attribute;
+ * - inside a tag where an attribute name goes (`<input <!--slot:x/-->>`),
+ *   where any value is a new attribute;
+ * - inside the quoted value of an event handler, `style` or `srcdoc`, which
+ *   the browser reads as another language (see valueLanguageOf);
+ * - inside <script>/<style> elements (HTML escaping is the wrong grammar
+ *   there; embed data with jsonScript() into a normal slot instead).
+ * Attribute values vary through if/else around whole-tag variants, or a
+ * slot inside a quoted value.
  */
-const assertSafeSlotPosition = (source, slotIndex, slotName) => {
-    const before = source.slice(0, slotIndex);
-    if (/=\s*$/.test(before)) {
+const assertSafeSlotPosition = (point, slotName) => {
+    if (point.position === "afterEquals" || point.position === "unquoted") {
         throw new Error(`LambderTemplatingEngine: slot "${slotName}" is in an unquoted attribute position. ` +
             `Escaping cannot prevent injection there; quote the attribute: attr="<!--slot:${slotName}/-->".`);
     }
-    for (const tag of ["script", "style"]) {
-        const lastOpen = before.toLowerCase().lastIndexOf(`<${tag}`);
-        if (lastOpen !== -1 && before.toLowerCase().indexOf(`</${tag}`, lastOpen) === -1) {
-            throw new Error(`LambderTemplatingEngine: slot "${slotName}" is inside a <${tag}> element where HTML ` +
-                `escaping does not apply. Pass data with the jsonScript() helper in a regular slot instead.`);
-        }
+    if (point.position === "tag") {
+        throw new Error(`LambderTemplatingEngine: slot "${slotName}" is inside a tag where an attribute name goes. ` +
+            `Escaping cannot prevent injection there; put the slot inside a quoted value, or vary the whole tag with <!--if:...-->.`);
+    }
+    const valueLanguage = point.position === "quoted" ? valueLanguageOf(point.attributeName) : null;
+    if (valueLanguage) {
+        throw new Error(`LambderTemplatingEngine: slot "${slotName}" is inside the ${point.attributeName} attribute, whose value the browser ` +
+            `reads as ${valueLanguage} once it has decoded the HTML escapes, so escaping cannot prevent injection there. ` +
+            `Pass the value in a data- attribute a script reads, or vary the whole tag with <!--if:...-->.`);
+    }
+    if (point.position === "rawText") {
+        throw new Error(`LambderTemplatingEngine: slot "${slotName}" is inside a <${point.tagName}> element where HTML ` +
+            `escaping does not apply. Pass data with the jsonScript() helper in a regular slot instead.`);
+    }
+};
+/** Where a point sits, in the words of a refusal. */
+const describePoint = (point) => {
+    switch (point.position) {
+        case "text": return "in text";
+        case "comment": return "in a comment";
+        case "tag": return "inside a tag where an attribute name goes";
+        case "afterEquals":
+        case "unquoted": return `in the unquoted ${point.attributeName} value`;
+        case "quoted": return `in the quoted ${point.attributeName} value`;
+        case "rawText": return `inside a <${point.tagName}> element`;
     }
 };
+/** What a refusal of branches that leave the template in different positions tells the author to do. */
+const BRANCH_ADVICE = "Vary the whole tag or element inside the branches instead, so every branch ends where the others do.";
 const parseTemplate = (source) => {
+    const tokens = [...source.matchAll(TOKEN_PATTERN)];
+    // Every slot's position is checked before the tree is built, which also
+    // finds the URL values holding one: the tree wraps each such value in a
+    // node of its own, so a render can check the value whole.
+    //
+    // The HTML is read in one pass along the template's own structure, with
+    // the tokens left out: they are not HTML, and inside a tag the ">" that
+    // ends <!--if:x--> would otherwise read as the tag's end. Each branch of
+    // an if is read from where the block starts, a missing else being an
+    // empty branch, and a slot with default content is a block whose
+    // branches are the default and the value. After a block, the text that
+    // follows is read in both resulting readings until they sit at the same
+    // position and join, and they have to before the next block, or which
+    // position the next block's branches start from would depend on the
+    // data. A slot met while they are still apart passes only when it lands
+    // alike in both. Each character is read at most twice, whatever the
+    // nesting. Malformed nesting stops the walk, and the build below refuses
+    // it by name.
+    const urlValues = new Map();
+    let readings = [new HtmlPositionReader()];
+    let apartSince = "";
+    const blocks = [];
+    const readOn = (text) => {
+        for (const reading of readings) {
+            reading.read(text);
+            const undecidable = reading.undecidable;
+            if (undecidable?.reason === "commentValue") {
+                throw new Error(`LambderTemplatingEngine: slot "${undecidable.label}" is inside a comment, right before text that ends the comment ` +
+                    `or not depending on how the value ends ("-", "--" or "--!" before a ">"). Put a space after the slot.`);
+            }
+            if (undecidable) {
+                throw new Error(`LambderTemplatingEngine: the branches of ${undecidable.label} end after different attribute names, and the "=" ` +
+                    `after them would give its value to a different attribute in each. ${BRANCH_ADVICE}`);
+            }
+        }
+        if (readings.length === 2 && readings[0].joinWith(readings[1], apartSince))
+            readings = [readings[0]];
+    };
+    const requireOneReading = (token) => {
+        if (readings.length === 1)
+            return readings[0];
+        const [first, second] = readings.map((reading) => describePoint(reading.point()));
+        throw new Error(`LambderTemplatingEngine: the branches of ${apartSince} leave the template in different positions` +
+            `${first === second ? "" : ` (${first} after one, ${second} after the other)`}, and ${token} comes before they meet again. ` +
+            BRANCH_ADVICE);
+    };
+    let readCursor = 0;
+    let walkedToEnd = true;
+    for (const token of tokens) {
+        readOn(source.slice(readCursor, token.index));
+        readCursor = token.index + token[0].length;
+        const [, , selfClosingName, openSlot, openSlotName, closeSlot, closeSlotName, openIf, openIfNegation, openIfName, elseTag, , closeIfNegation, closeIfName] = token;
+        const slotName = selfClosingName ?? openSlotName;
+        if (slotName !== undefined) {
+            const [point, otherPoint] = readings.map((reading) => reading.point());
+            if (otherPoint && (otherPoint.position !== point.position || otherPoint.attributeName !== point.attributeName
+                || otherPoint.quote !== point.quote || otherPoint.tagName !== point.tagName)) {
+                throw new Error(`LambderTemplatingEngine: slot "${slotName}" comes after ${apartSince}, whose branches leave the template in different ` +
+                    `positions: the slot is ${describePoint(point)} after one, ${describePoint(otherPoint)} after the other. ${BRANCH_ADVICE}`);
+            }
+            assertSafeSlotPosition(point, slotName);
+            if (point.position === "quoted" && URL_ATTRIBUTE_NAMES.has(point.attributeName)) {
+                // No token holds a quote character, so the nearest quotes
+                // around the slot are its value's own. A quote only one
+                // branch holds leaves that block crossing the value's edge,
+                // which the build below refuses.
+                const start = source.lastIndexOf(point.quote, token.index) + 1;
+                const end = source.indexOf(point.quote, token.index);
+                if (end === -1) {
+                    throw new Error(`LambderTemplatingEngine: slot "${slotName}" is inside a quoted ${point.attributeName} value that never closes.`);
+                }
+                urlValues.set(start, { start, end, attributeName: point.attributeName });
+            }
+            if (openSlot) {
+                const valueReading = requireOneReading(token[0]).copy();
+                valueReading.skipValue(slotName);
+                blocks.push({ opening: token[0], key: `slot:${slotName}`, secondStart: valueReading, firstEnd: null });
+            }
+            else {
+                for (const reading of readings)
+                    reading.skipValue(slotName);
+            }
+            continue;
+        }
+        if (openIf) {
+            blocks.push({ opening: token[0], key: `if:${openIfNegation}${openIfName}`, secondStart: requireOneReading(token[0]).copy(), firstEnd: null });
+            continue;
+        }
+        const block = blocks.pop();
+        const closingKey = closeSlot ? `slot:${closeSlotName}` : `if:${closeIfNegation}${closeIfName}`;
+        if (!block || (elseTag ? !block.key.startsWith("if:") || block.firstEnd !== null : block.key !== closingKey)) {
+            walkedToEnd = false;
+            break;
+        }
+        const reading = requireOneReading(token[0]);
+        if (elseTag) {
+            block.firstEnd = reading;
+            readings = [block.secondStart];
+            blocks.push(block);
+            continue;
+        }
+        readings = block.firstEnd ? [block.firstEnd, reading] : [reading, block.secondStart];
+        apartSince = block.opening;
+    }
+    if (walkedToEnd)
+        readOn(source.slice(readCursor));
+    // In source order already: the values were met in token order, and two
+    // never overlap.
+    const boundaries = [...urlValues.values()].flatMap((range) => [
+        { index: range.start, range, opens: true },
+        { index: range.end, range, opens: false },
+    ]);
     const root = { kind: "root", name: "", negated: false, nodes: [], elseNodes: [], inElse: false };
     const stack = [root];
     const top = () => stack[stack.length - 1];
@@ -29,21 +171,42 @@ const parseTemplate = (source) => {
         const frame = top();
         (frame.inElse ? frame.elseNodes : frame.nodes).push(node);
     };
-    TOKEN_PATTERN.lastIndex = 0;
     let cursor = 0;
-    let match;
-    while ((match = TOKEN_PATTERN.exec(source)) !== null) {
-        if (match.index > cursor) {
-            emit({ type: "text", value: source.slice(cursor, match.index) });
+    const emitTextUpTo = (index) => {
+        if (index > cursor)
+            emit({ type: "text", value: source.slice(cursor, index) });
+        cursor = index;
+    };
+    let nextBoundary = 0;
+    const passBoundariesUpTo = (index) => {
+        for (; nextBoundary < boundaries.length && boundaries[nextBoundary].index <= index; nextBoundary += 1) {
+            const { index: boundaryIndex, range, opens } = boundaries[nextBoundary];
+            emitTextUpTo(boundaryIndex);
+            if (opens) {
+                stack.push({ kind: "urlValue", name: range.attributeName, negated: false, nodes: [], elseNodes: [], inElse: false });
+                continue;
+            }
+            const frame = stack.pop();
+            if (frame.kind !== "urlValue") {
+                throw new Error(`LambderTemplatingEngine: <!--${frame.kind}:${frame.name}--> opens inside a quoted ${range.attributeName} value holding a slot ` +
+                    `and closes outside it. Keep the block wholly inside the value, or the value wholly inside the block.`);
+            }
+            emit({ type: "urlValue", nodes: frame.nodes });
         }
-        cursor = TOKEN_PATTERN.lastIndex;
+    };
+    for (const match of tokens) {
+        passBoundariesUpTo(match.index);
+        emitTextUpTo(match.index);
+        cursor = match.index + match[0].length;
         const [, selfClosingSlot, selfClosingName, openSlot, openSlotName, closeSlot, closeSlotName, openIf, openIfNegation, openIfName, elseTag, closeIf, closeIfNegation, closeIfName] = match;
+        if ((closeSlot || elseTag || closeIf) && top().kind === "urlValue") {
+            throw new Error(`LambderTemplatingEngine: ${match[0]} belongs to a block opened outside the quoted ${top().name} value holding a slot it sits in. ` +
+                `Keep the block wholly inside the value, or the value wholly inside the block.`);
+        }
         if (selfClosingSlot) {
-            assertSafeSlotPosition(source, match.index, selfClosingName);
             emit({ type: "slot", name: selfClosingName, defaultNodes: [] });
         }
         else if (openSlot) {
-            assertSafeSlotPosition(source, match.index, openSlotName);
             stack.push({ kind: "slot", name: openSlotName, negated: false, nodes: [], elseNodes: [], inElse: false });
         }
         else if (closeSlot) {
@@ -72,35 +235,46 @@ const parseTemplate = (source) => {
             emit({ type: "if", name: frame.name, negated: frame.negated, thenNodes: frame.nodes, elseNodes: frame.elseNodes });
         }
     }
-    if (cursor < source.length) {
-        emit({ type: "text", value: source.slice(cursor) });
-    }
+    passBoundariesUpTo(source.length);
+    emitTextUpTo(source.length);
     if (stack.length !== 1) {
         const frame = top();
         throw new Error(`LambderTemplatingEngine: unclosed <!--${frame.kind}:${frame.name}--> block.`);
     }
     return root.nodes;
 };
-const renderNodes = (nodes, data) => {
-    let out = "";
+const renderNodes = (nodes, data, output) => {
     for (const node of nodes) {
         if (node.type === "text") {
-            out += node.value;
+            output.html += node.value;
         }
         else if (node.type === "slot") {
             const value = Object.prototype.hasOwnProperty.call(data, node.name) ? data[node.name] : undefined;
-            out += value === undefined ? renderNodes(node.defaultNodes, data) : renderHtmlValue(value);
+            if (value === undefined) {
+                renderNodes(node.defaultNodes, data, output);
+            }
+            else {
+                if (output.firstDataIndex === -1)
+                    output.firstDataIndex = output.html.length;
+                output.html += renderHtmlValue(value);
+            }
+        }
+        else if (node.type === "urlValue") {
+            // Rendered on its own, so the check reads the value whole and
+            // knows which part of it the template wrote.
+            const value = { html: "", firstDataIndex: -1 };
+            renderNodes(node.nodes, data, value);
+            output.html += safeUrlValue(value.html, value.firstDataIndex);
         }
         else {
             // Own properties only, the same lookup the slot branch uses:
-            // through the prototype, <!--if:toString--> was unconditionally
-            // true on every render.
+            // through the prototype, <!--if:toString--> would be true on
+            // every render.
             const value = Object.prototype.hasOwnProperty.call(data, node.name) ? data[node.name] : undefined;
             const condition = !!value !== node.negated;
-            out += renderNodes(condition ? node.thenNodes : node.elseNodes, data);
+            renderNodes(condition ? node.thenNodes : node.elseNodes, data, output);
         }
     }
-    return out;
 };
 const collectNames = (nodes, slots, conditions) => {
     for (const node of nodes) {
@@ -113,6 +287,9 @@ const collectNames = (nodes, slots, conditions) => {
             collectNames(node.thenNodes, slots, conditions);
             collectNames(node.elseNodes, slots, conditions);
         }
+        else if (node.type === "urlValue") {
+            collectNames(node.nodes, slots, conditions);
+        }
     }
 };
 export class LambderTemplatingEngine {
@@ -144,7 +321,9 @@ export class LambderTemplatingEngine {
     }
     /** Render with escaped-by-default data; unknown keys ignored, omitted slots keep defaults. */
     render(data = {}) {
-        return renderNodes(this.nodes, data);
+        const output = { html: "", firstDataIndex: -1 };
+        renderNodes(this.nodes, data, output);
+        return output.html;
     }
 }
 /** Wrap the <title> content and the pre-</head> position in virtual slot markers. */

package/dist/index.d.ts

@@ -3,7 +3,9 @@ export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export type { LambderCreatedHook } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
-export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderIdempotencyKeyScope, LambderLogListHandler } from "./client/LambderCaller.js";
+export type { LambderApiOutcome, LambderApiFailureReason, LambderValidationError, LambderCallOptions, LambderCallerOptions, LambderGuardInputsProvider, LambderProvidedGuardInputs, LambderLogListHandler } from "./client/LambderCaller.js";
+export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
+export type { LambderIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 export { lambderFetchTransport } from "./client/lambderFetchTransport.js";
 export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFailure } from "./shared/transport/LambderApiTransport.js";
 export { lambderCookieJarTransport } from "./shared/transport/lambderCookieJarTransport.js";
@@ -34,13 +36,14 @@ export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVer
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export type { LambderApiEnvelopeConfig, LambderValidationAnswerBody } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";
+export { LambderApiOutputValidationError } from "./api/LambderApiOutputValidationError.js";
 export { LambderInvokeError, isLambderInvokeError } from "./invoke/LambderInvokeOutcome.js";
 export type { LambderInvokeOutcome, LambderInvokeFailure, LambderInvokeValidationFailure, LambderInvokeCrashFailure, LambderInvokePayloadTooLargeFailure, LambderInvokeEnvelopeFailure, LambderInvokeDeliveryFailure, LambderInvokeFailureReason, LambderInvokeFunctionError, } from "./invoke/LambderInvokeOutcome.js";
 export { default as LambderInvokeCaller, LAMBDER_INVOKE_MAX_EVENT_BYTES, } from "./invoke/LambderInvokeCaller.js";
 export type { LambderInvokeCallerOptions, LambderInvokeCallOptions, LambderInvokeFailureHandler, LambderInvokeLogListHandler, LambderInvokeTransport, LambderInvokeTransportResult, LambderInvokeRequestInit, LambderInvokeEventInit, } from "./invoke/LambderInvokeCaller.js";
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 export type { LambderCrashDetail, LambderCrashCause } from "./shared/wire/LambderCrashDetail.js";
-export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export type { LambderApiRefusalOptions, LambderRefusalMessage, LambderAppRefusalMessage, LambderRefusalCode, LambderRefuseOptions } from "./shared/wire/LambderApiRefusal.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
 export { default as LambderResolver } from "./core/LambderResolver.js";
@@ -49,7 +52,7 @@ export type { LambderSessionManagerOptions } from "./session/LambderSessionManag
 export { default as LambderSessionController } from "./session/LambderSessionController.js";
 export { DEFAULT_SESSION_TOKEN_COOKIE_KEY, DEFAULT_SESSION_CSRF_COOKIE_KEY } from "./shared/wire/LambderSessionCookieNames.js";
 export type { LambderSessionControllerOptions, LambderSessionRequestInfo } from "./session/LambderSessionController.js";
-export type { LambderSessionStore, LambderSessionRecord } from "./shared/contracts/LambderSessionStore.js";
+export type { LambderSessionStore, LambderSessionRecord, LambderSessionChanges, LambderSessionUpdateResult } from "./shared/contracts/LambderSessionStore.js";
 export { LambderMemorySessionStore } from "./stores/LambderMemorySessionStore.js";
 export { LambderWebCrypto, LambderPlainSessionCrypto, isWebCryptoAvailable } from "./session/LambderSessionCrypto.js";
 export type { LambderSessionCrypto } from "./session/LambderSessionCrypto.js";
@@ -65,7 +68,7 @@ export type { LambderRouteMatcher, LambderRouteConditionFn, LambderRouteConditio
 export type { LambderCorsConfig } from "./core/LambderCors.js";
 export type { LambderCreateOptions, LambderSessionOptions, LambderActionTools, LambderHandler, } from "./core/LambderCreateOptions.js";
 export type { LambderIndexHtmlOptions } from "./core/LambderIndexHtml.js";
-export type { LambderRouteHandler, LambderSessionRouteHandler, LambderActionHandler, LambderActionFilter, LambderHookEvent, LambderBeforeRenderHook, LambderAfterRenderHook, LambderFallbackHook, LambderGlobalErrorHandler, LambderFallbackHandler, LambderInputValidationHandler, } from "./core/LambderCreateOptions.js";
+export type { LambderRouteHandler, LambderSessionRouteHandler, LambderActionHandler, LambderActionFilter, LambderHookEvent, LambderBeforeRenderHook, LambderAfterRenderHook, LambderFallbackHook, LambderGlobalErrorHandler, LambderFallbackHandler, LambderInputValidationHandler, LambderCrashOptions, LambderCrashReporter, LambderCrashSite, } from "./core/LambderCreateOptions.js";
 export type { LambderPublicFilesOptions } from "./core/LambderPublicFiles.js";
 export { LambderFiles } from "./core/LambderFiles.js";
 export type { LambderFilesOption, LambderFileMemoryCacheOption, LambderReadFile } from "./core/LambderFiles.js";
@@ -83,8 +86,11 @@ export { compressText, restoreBytes, restoreText, LambderCompressionError, LAMBD
 export type { LambderRestoreFailure, LambderRestoreBound } from "./shared/wire/LambderCompressionCodec.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 export { LambderSessionNotFoundError, LambderSessionAmbiguousError } from "./session/LambderSessionController.js";
+export type { LambderCache, LambderCacheKey, LambderCacheSetOptions, LambderCacheListOptions } from "./shared/contracts/LambderCache.js";
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
-export type { LambderCacheKey, LambderDdbCacheOptions, LambderDdbCacheSetOptions, LambderDdbCacheGetOrSetOptions, LambderDdbCacheListOptions, } from "./stores/LambderDdbCache.js";
+export type { LambderDdbCacheOptions, LambderDdbCacheGetOrSetOptions, } from "./stores/LambderDdbCache.js";
+export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
+export type { LambderMemoryCacheOptions } from "./stores/LambderMemoryCache.js";
 export { RATE_LIMIT_WINDOWS } from "./shared/contracts/LambderRateLimiter.js";
 export type { LambderRateLimiter, LambderRateLimitWindow, LambderRateLimitPolicy, LambderRateLimitExceeded, LambderRateLimitResult, } from "./shared/contracts/LambderRateLimiter.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
@@ -96,19 +102,20 @@ export type { LambderDdbIdempotencyStoreOptions } from "./stores/LambderDdbIdemp
 export { LambderMemoryIdempotencyStore } from "./stores/LambderMemoryIdempotencyStore.js";
 export { lambderGuard, lambderRateLimitKey } from "./core/LambderPolicyBuilders.js";
 export { lambderGuardBuilder } from "./api/LambderApiGuards.js";
-export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, } from "./api/LambderApiGuards.js";
+export type { LambderGuardBuilder, LambderApiGuard, LambderGuardMeta, LambderGuardMetaMap, LambderGuardRunAt, LambderAllowedGuardNames, LambderParamlessGuardNames, LambderGuardsOption, LambderGuardDataOf, LambderGuardInputsOf, } from "./api/LambderApiGuards.js";
 export { lambderRateLimitKeyBuilder, rateLimitRefusal, DEFAULT_RATE_LIMIT_REFUSAL } from "./api/LambderApiRateLimits.js";
 export type { LambderRateLimitKeyBuilder } from "./api/LambderApiRateLimits.js";
-export type { LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
+export type { LambderContextRateLimit, LambderContextRateLimitCheck, LambderRateLimitCheckResult, LambderChargeablePolicyNames, LambderChargeKeyArgs, LambderRateLimitKeyFn, LambderRateLimitPer, LambderRateLimitBudget, LambderRateLimitChargeAt, LambderApiRateLimitPolicyConfig, LambderApiRateLimitsConfig, LambderAllowedPolicyNames, LambderRateLimitOption, } from "./api/LambderApiRateLimits.js";
 export type { LambderApiIdempotencyConfig } from "./api/LambderApiIdempotency.js";
 export type { LambderGuardsOptionValue, LambderRateLimitOverride, LambderRateLimitOptionValue, LambderApiIdempotencyOption, } from "./shared/wire/LambderApiOptionValues.js";
 export { createLambderI18n } from "./shared/LambderI18n.js";
 export type { LambderLanguageMeta, LambderI18nConfig, LambderI18nInstance, LambderI18nTranslator, LambderI18nExtractParams, LambderI18nDictionaryLoader, LambderI18nCodes, LambderI18nKeys, LambderI18nTranslatorFor, } from "./shared/LambderI18n.js";
-export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderFlattenContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
+export type { LambderApiContractShape, LambderApiMode, LambderApiEnvelopeBody, LambderApiResponseConfig, LambderApiNullAnswerConfig, LambderContractEntry, LambderMergeContract, LambderFlattenContract, LambderGuardNamesIn, LambderContractMode, LambderContractKeysWithMode, LambderContractKeysWithGuard, LambderJsonOf, LambderJsonOutputOf, LambderContractGuardsOf, LambderContractGuardNames, LambderContractGuardInputsOf, LambderContractGuardInput, LambderContractGuardInputNames, LambderContractRateLimitOf, LambderContractRateLimitNames, LambderContractIdempotencyOf, } from "./shared/wire/LambderApiContract.js";
 export type { LambderRenderContext, LambderSessionRenderContext, LambderHttpEvent, LambderHttpEventFormat } from "./core/LambderContext.js";
 export type { LambderApiAnswerOutcome, LambderApiSuccessOutcome, LambderApiCallFailure, LambderApiValidationFailure, LambderApiEnvelopeFailure, LambderApiHttpAnswer, } from "./shared/wire/LambderApiOutcome.js";
 export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
+export type { LambderContextOptions } from "./core/LambderContext.js";
 export { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, compressPayloadBrotli, } from "./shared/wire/LambderRequestPayload.js";
 export type { LambderCompressedGzipPayload, LambderCompressedBrotliPayload, LambderRequestCompressionOption, LambderRequestCompressionSettings, } from "./shared/wire/LambderRequestPayload.js";
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./shared/wire/LambderCookie.js";

package/dist/index.js

@@ -2,6 +2,7 @@ import Lambder from './core/Lambder.js';
 export default Lambder;
 export { initLambder } from './core/Lambder.js';
 export { default as LambderCaller } from "./client/LambderCaller.js";
+export { createIdempotencyKey, createIdempotencyKeyScope } from "./shared/wire/LambderIdempotencyKeyScope.js";
 // Transports: how a caller reaches a server (fetch in production, a handler in-process for tests, a cookie jar over either)
 export { lambderFetchTransport } from "./client/lambderFetchTransport.js";
 export { buildTransportEnvelope, LambderTransportFailure, isLambderTransportFailure } from "./shared/transport/LambderApiTransport.js";
@@ -23,13 +24,14 @@ export { RELOAD_LOOP_WINDOW_MS } from "./client/LambderReloadLoopBreaker.js";
 export { compareDottedVersions, isDottedVersion } from "./shared/wire/LambderVersionOrder.js";
 export { buildApiEnvelope, envelopeAnswer, refusalAnswer, validationAnswer, apiNotFoundAnswer, sessionExpiredAnswer, versionExpiredAnswer, invalidPayloadAnswer, crashAnswer, API_ANSWER_CONTENT_TYPE, } from "./api/LambderApiEnvelope.js";
 export { LambderApiValidationRefusal, isLambderApiValidationRefusal } from "./api/LambderApiValidationRefusal.js";
+export { LambderApiOutputValidationError } from "./api/LambderApiOutputValidationError.js";
 // Calling a Lambder app from another lambda (server-only: the Lambda SDK, zlib)
 export { LambderInvokeError, isLambderInvokeError } from "./invoke/LambderInvokeOutcome.js";
 export { default as LambderInvokeCaller, LAMBDER_INVOKE_MAX_EVENT_BYTES, } from "./invoke/LambderInvokeCaller.js";
 // A crash described for a caller allowed to see it (the envelope's `crash` field)
 export { describeCrash, errorFromCrashDetail } from "./shared/wire/LambderCrashDetail.js";
 // Typed API refusals (isomorphic: shared code may throw them from anywhere)
-export { LambderApiRefusal, isLambderApiRefusal, refuse, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
+export { LambderApiRefusal, isLambderApiRefusal, refuse, refusalMessageOf, LAMBDER_REFUSAL_CODES } from "./shared/wire/LambderApiRefusal.js";
 export { default as LambderResponseBuilder } from "./core/LambderResponseBuilder.js";
 export { default as LambderResolver } from "./core/LambderResolver.js";
 export { default as LambderSessionManager } from "./session/LambderSessionManager.js";
@@ -55,8 +57,8 @@ export { resolveCompressionOption, LAMBDER_ENCODINGS } from "./shared/wire/Lambd
 export { compressText, restoreBytes, restoreText, LambderCompressionError, LAMBDER_RESTORE_FAILURES, } from "./shared/wire/LambderCompressionCodec.js";
 export { LambderSessionDataRefreshError, LambderSessionReadError } from "./session/LambderSessionManager.js";
 export { LambderSessionNotFoundError, LambderSessionAmbiguousError } from "./session/LambderSessionController.js";
-// DynamoDB-backed compressed cache (standalone, server-only)
 export { LambderDdbCache } from "./stores/LambderDdbCache.js";
+export { LambderMemoryCache } from "./stores/LambderMemoryCache.js";
 // Fixed-window rate limiting: the shared vocabulary, the DynamoDB limiter and the in-memory one
 export { RATE_LIMIT_WINDOWS } from "./shared/contracts/LambderRateLimiter.js";
 export { LambderDdbRateLimiter } from "./stores/LambderDdbRateLimiter.js";
@@ -74,8 +76,7 @@ export { resolveApiOutcome } from "./shared/wire/LambderApiOutcome.js";
 export { createContext, isV2HttpEvent } from "./core/LambderContext.js";
 // Request payload compression: the wire format LambderCaller and the server share.
 export { COMPRESSED_PAYLOAD_GZ_FIELD, COMPRESSED_PAYLOAD_BR_FIELD, COMPRESSED_PAYLOAD_BYTES_FIELD, DEFAULT_REQUEST_COMPRESSION_SETTINGS, DEFAULT_MAX_RESTORED_PAYLOAD_BYTES, 
-// The Brotli twin of the browser's compressPayloadGzip, beside it now
-// rather than inside LambderInvokeCaller; the root entry's name is unchanged.
+// The Brotli twin of the browser's compressPayloadGzip, and its defaults.
 DEFAULT_INVOKE_REQUEST_COMPRESSION_SETTINGS, compressPayloadBrotli, } from "./shared/wire/LambderRequestPayload.js";
 // Cookies (res.setCookie / res.clearCookie build on these; exported for code holding a LambderResponse)
 export { serializeCookie, serializeClearCookie, resolveCookieDomain } from "./shared/wire/LambderCookie.js";

package/dist/invoke/LambderInvokeCaller.d.ts

@@ -2,17 +2,17 @@
  * Calling a Lambder app from another lambda, or from any server code that
  * holds AWS credentials and lambda:InvokeFunction on it.
  *
- * API Gateway delivers an HTTP request to a Lambder app as a JSON event and
- * takes a JSON response object back; a direct InvokeCommand carries JSON in
- * both directions too. So this caller builds the payload-format-2.0 event
- * API Gateway would have built, invokes the function with it, and reads the
- * response object Lambder returns. The callee is an unmodified Lambder app,
- * and everything it offers over HTTP (zod validation, the inferred contract,
- * refusals, guards, idempotency keys, Brotli answers, logList, the crash
- * detail its global error handler chooses to send) applies unchanged. The
- * callee tells an invoke from a browser only by the x-lambder-invoke header,
- * which is a marker for guards and hooks, never an authorization: the IAM
- * grant is that.
+ * Builds the payload-format-2.0 event API Gateway would have built, invokes
+ * the function with it directly, and reads the response object Lambder
+ * returns. The callee is an unmodified Lambder app, so everything it offers
+ * over HTTP (zod validation, the inferred contract, refusals, guards,
+ * idempotency keys, Brotli answers, logList, the crash detail its error
+ * handler chooses to send) applies unchanged. The callee tells an invoke
+ * apart by the event's requestContext.apiId, which no gateway lets a client
+ * write, and reads no forwarding header on one, so `clientIp` and `host` are
+ * the only address and host it sees. The x-lambder-invoke header is a marker
+ * for guards and hooks, never an authorization: the IAM grant is the
+ * authorization.
  *
  * Server-only (zlib, the Lambda SDK), so it is exported from the root entry
  * and never from lambder/client. The SDK is an optional peer dependency
@@ -72,23 +72,18 @@ type LambderInvokeCallerBaseOptions = {
     /** Function name or ARN. */
     functionName: string;
     /**
-     * A ready client, e.g. one shared with the rest of the app. It keeps
-     * whatever `maxAttempts` it was built with, which is the SDK's own 3
-     * unless the app said otherwise: `clientConfig` below is not consulted
-     * for a client this caller did not create, and a retry at that layer
-     * re-executes a callee whose response was merely lost. Build it with
-     * `{ maxAttempts: 1 }`, or send an `idempotencyKey` and let the callee
-     * settle the repeat.
+     * A ready client, e.g. one shared with the rest of the app. `clientConfig`
+     * does not apply to it, so it keeps its own `maxAttempts` (the SDK's 3 by
+     * default), and a retry re-executes a callee whose response was merely
+     * lost: build it with `{ maxAttempts: 1 }`, or send an `idempotencyKey`.
      */
     client?: LambdaClient;
     /**
      * Otherwise the client is created from this on the first call (region,
-     * credentials, maxAttempts). `maxAttempts` defaults to 1 here rather than
-     * to the SDK's 3: a RequestResponse invoke whose response is lost has
-     * already run the callee, so a retry at this layer executes the operation
-     * a second time, and the transport contract says one call is one delivery
-     * attempt. Raise it deliberately if the callee is idempotent, or send an
-     * `idempotencyKey` and let the callee settle it.
+     * credentials, maxAttempts). `maxAttempts` defaults to 1 rather than the
+     * SDK's 3, since a lost response means the callee already ran and a retry
+     * would run it twice. Raise it only for an idempotent callee, or send an
+     * `idempotencyKey`.
      */
     clientConfig?: LambdaClientConfig;
     /** Must match the callee's apiPath. Default: "/api". */
@@ -118,10 +113,10 @@ type LambderInvokeCallerBaseOptions = {
     /** Receives each answer's logList. Default: console.log with the function and api name. A throw is logged and otherwise ignored. */
     onLogList?: LambderInvokeLogListHandler;
     /**
-     * Called, and awaited, for every failed call before api() throws or
-     * apiOutcome() returns, so failures are reported in one place whichever
-     * method the site used, and before the lambda answers. A throw inside it
-     * is logged and otherwise ignored: apiOutcome() never throws.
+     * Called and awaited for every failed call before api() throws or
+     * apiOutcome() returns, so failures are reported in one place, before the
+     * lambda answers. A throw inside it is logged and otherwise ignored, so
+     * apiOutcome() never throws.
      */
     onFailure?: LambderInvokeFailureHandler;
     /** The session token cookie's name, when a session is carried and the callee uses a non-default `tokenCookieKey`. The CSRF value rides in the envelope's `token` field, which has no name to configure. */
@@ -195,10 +190,9 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
      * Lambda would: a thrown error becomes a FunctionError payload. For
      * tests that want the real handlers behind the real envelope.
      *
-     * It honours the signal the way lambderHandlerTransport does, by ending
-     * the wait: a function call in this process cannot be cancelled, so the
-     * handler runs to completion regardless and what a timeout buys is the
-     * caller's answer. Ignoring it made timeoutMs a no-op here.
+     * It honours the signal by ending the wait, as lambderHandlerTransport
+     * does: an in-process call cannot be cancelled, so the handler runs to
+     * completion regardless, but timeoutMs still frees the caller.
      */
     static localTransport(handler: (event: APIGatewayProxyEventV2, context: Context) => Promise<unknown>, context?: Partial<Context>): LambderInvokeTransport;
     private loadSdk;
@@ -208,25 +202,26 @@ export default class LambderInvokeCaller<TContract extends LambderApiContractSha
     /** Builds the failure and its error, reports it once, and hands it back. */
     private failureOutcome;
     private surfaceLogs;
-    /** One call, one outcome. Never throws; api() is what throws. */
+    /**
+     * One call, one outcome. Never throws; api() is what throws. A key scope
+     * is told how the attempt ended, as it is on LambderCaller.
+     */
     private dispatch;
+    private dispatchAttempt;
     /**
      * Full-fidelity call: resolves to a discriminated LambderInvokeOutcome
-     * instead of throwing. Never throws; for sites that degrade gracefully.
-     *
-     * The output is computed from the contract in the return type rather than
-     * taken as a type parameter, so a call site cannot replace it by
-     * annotating what it assigns to.
+     * instead of throwing, for sites that degrade gracefully. The output type
+     * comes from the contract rather than a type parameter, so a call site
+     * cannot replace it by annotating what it assigns to.
      */
     apiOutcome<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderInvokeOutcome<LambderContractOutputOf<TContract, TApiName>>>;
     /**
      * The declared output, or a thrown LambderInvokeError carrying the
      * outcome. A failed dependency is a failed request: the throw reaches the
      * app's global error handler with the callee's error as its cause. The
-     * result is the callee's output type as it declared it: the resolver
-     * only lets a handler answer null when the output allows it or beside a
-     * reason (LambderApiAnswer), so a nullable output is the one place null
-     * arrives.
+     * resolver lets a handler answer null only when the output allows it or
+     * beside a reason (LambderApiAnswer), so null arrives only for a
+     * nullable output.
      */
     api<TApiName extends keyof TContract & string = string>(apiName: TApiName, ...rest: LambderCallArgs<TContract, TApiName, TProvidedGuards, LambderInvokeCallOptions>): Promise<LambderContractOutputOf<TContract, TApiName>>;
     /**