lambder 6.0.2 → 7.0.1

package/dist/shared/transport/LambderCookieJar.js

@@ -0,0 +1,246 @@
+/**
+ * The cookie jar a transport carries (LambderCookieJar), and the Set-Cookie
+ * parsing behind it. tough-cookie is reached from this module and no other, so
+ * a bundle that never carries a jar drops it.
+ */
+import { Cookie, CookieJar as ToughCookieJar, defaultPath, pathMatch } from "tough-cookie";
+/**
+ * Stands in for the host of a jar that was never told one. Every store and
+ * every read of such a jar uses it, so the jar is self-consistent: it behaves
+ * as the browser of one unnamed host. `.invalid` is reserved by the IANA and
+ * can never be a real name, so a cookie parked here can never match a real
+ * target by accident.
+ */
+const UNNAMED_JAR_HOST = "lambder-cookie-jar.invalid";
+/** The host without its port, lowercased: "App.Test:3000" is "app.test", "[::1]:8080" is "[::1]". */
+const normalizeHost = (host) => {
+    const lowered = host.trim().toLowerCase();
+    // An IPv6 literal is bracketed and full of colons, so only what follows
+    // the closing bracket can be a port; splitting on ":" would leave "[".
+    if (lowered.startsWith("[")) {
+        const close = lowered.indexOf("]");
+        return close === -1 ? lowered : lowered.slice(0, close + 1);
+    }
+    return lowered.split(":")[0] ?? lowered;
+};
+/** The URL tough-cookie works in terms of. https unless the target says it speaks plain http, which is what decides a Secure cookie. */
+const urlFor = (host, path, secure) => `${secure ? "https" : "http"}://${host}${path && path.startsWith("/") ? path : "/"}`;
+/**
+ * When a cookie actually dies, as an absolute moment.
+ *
+ * Max-Age and Expires are stored separately and Max-Age wins, so reading the
+ * `expires` field alone calls a `Max-Age=0` deletion immortal. The library's
+ * own expiryTime() resolves Max-Age against whatever moment it is handed, and
+ * against lastAccessed when handed nothing, so neither answers "when does this
+ * die" on a fixed clock. A browser measures Max-Age from when the cookie
+ * arrived, which is its creation.
+ */
+const cookieExpiryAt = (cookie, now) => {
+    if (typeof cookie.maxAge === "number") {
+        const receivedAt = cookie.creation instanceof Date ? cookie.creation.getTime() : now;
+        return receivedAt + cookie.maxAge * 1000;
+    }
+    return cookie.expires instanceof Date ? cookie.expires.getTime() : undefined;
+};
+const storedFromCookie = (cookie, now) => {
+    const hostOnly = cookie.hostOnly === true;
+    const domain = typeof cookie.domain === "string" ? cookie.domain : undefined;
+    const expiryAt = cookieExpiryAt(cookie, now);
+    return {
+        name: cookie.key ?? "",
+        value: cookie.value ?? "",
+        domain: hostOnly ? undefined : domain,
+        // A jar that never learned a host parked this under the stand-in,
+        // which is an implementation detail rather than something it knows.
+        ...(hostOnly && domain !== undefined && domain !== UNNAMED_JAR_HOST ? { host: domain } : {}),
+        path: typeof cookie.path === "string" ? cookie.path : "/",
+        expires: expiryAt,
+        httpOnly: cookie.httpOnly === true,
+        secure: cookie.secure === true,
+    };
+};
+/**
+ * One Set-Cookie header value, read the way a browser reads it. `requestPath`
+ * is the path the answer came from, which decides the default Path. Returns
+ * null for a header no browser would keep.
+ */
+export const parseSetCookie = (header, now, requestPath) => {
+    const parsed = Cookie.parse(header, { loose: false });
+    if (!parsed)
+        return null;
+    // Cookie.parse stamps creation with the real clock, but the caller's `now`
+    // is the moment this header arrived, and Max-Age is measured from there.
+    parsed.creation = new Date(now);
+    // Resolve Max-Age against Expires on the caller's clock, the way the jar
+    // itself will, so a test moving time forward reads the same expiry here.
+    return {
+        ...storedFromCookie(parsed, now),
+        // Cookie.parse leaves an absent Path absent; the default-path is the
+        // sending path's directory, which only the caller knows.
+        path: parsed.path ?? defaultPath(requestPath ?? "/"),
+    };
+};
+/**
+ * A browser's cookie storage, for transports that have no browser: the
+ * in-process handler transport in a Node test, and the mock runtime's direct
+ * transport. It stores what an answer's Set-Cookie headers set, honours their
+ * expiry and deletion, and hands back the Cookie pairs the next request should
+ * carry. One jar is one browser; two jars are two.
+ *
+ * The rules themselves are tough-cookie's, which is the reference
+ * implementation of RFC 6265 and carries the public suffix list: domain and
+ * path matching, default-path, Max-Age against Expires, Secure, HttpOnly, and
+ * the __Host-/__Secure- prefixes. That list is the part worth importing rather
+ * than writing. A hand-rolled check can tell that `Domain=com` is a registry
+ * suffix by counting labels, and cannot tell that `co.uk` is one, so a
+ * hand-rolled jar either trusts `Domain=co.uk` or bans every two-label domain.
+ *
+ * What stays Lambder's is the shape of the questions a transport asks: whole
+ * Set-Cookie header lists in (storeSetCookies), `name=value` pairs out
+ * (cookiePairs), and a target given as a host and path rather than a URL,
+ * since a transport that never speaks HTTP has no URL to give. A field the
+ * caller omits is one it could not know, and an unknown field matches
+ * anything: a jar pointed at a single host is the ordinary case, and refusing
+ * to answer it until it can name that host would make the common setup the
+ * awkward one.
+ *
+ * SameSite is stored but never consulted. It answers "did another site
+ * initiate this", and a transport call has no initiating site: every call here
+ * is same-site by construction.
+ */
+export class LambderCookieJar {
+    // prefixSecurity "silent" drops a __Host-/__Secure- cookie that breaks its
+    // own prefix rules instead of throwing, which is what a browser does.
+    jar = new ToughCookieJar(undefined, { prefixSecurity: "silent", allowSpecialUseDomain: true });
+    now;
+    host;
+    /** `host` is the host this jar is the browser of: the sender of every answer and the target of every request that names none. */
+    constructor(options = {}) {
+        this.now = options.now ?? (() => Date.now());
+        this.host = options.host === undefined ? undefined : normalizeHost(options.host);
+    }
+    /** The host a call is about, or the stand-in when neither the call nor the jar names one. */
+    hostFor(given) {
+        return given !== undefined ? normalizeHost(given) : this.host ?? UNNAMED_JAR_HOST;
+    }
+    /**
+     * Applies Set-Cookie header values as a browser would: stores, replaces,
+     * and deletes on an expiry in the past. `request` says where the answer
+     * came from. Its `host` is the sending host, which every Domain is checked
+     * against, and its `path` is the default Path of a cookie that names none.
+     *
+     * A Domain the sender is not under does not narrow a cookie, it voids it
+     * (RFC 6265 section 5.3 step 6), and so does a Domain that is a public
+     * suffix. Both are how evil.example.com would otherwise plant a cookie
+     * that bank.example.com is handed on the next call.
+     */
+    storeSetCookies(headers, request = {}) {
+        // The whole target, `secure` included: a cookie is judged against the
+        // channel it actually arrived on. Hardcoding https here accepted
+        // Secure cookies from a plain-http answer and then never sent one, so
+        // the jar held a session it could not use and said nothing.
+        const secure = request.secure !== false;
+        const url = urlFor(this.hostFor(request.host), request.path, secure);
+        const now = new Date(this.now());
+        for (const header of headers) {
+            // tough-cookie checks the Domain, the prefixes and HttpOnly
+            // against the URL, but leaves the Secure attribute to the caller:
+            // RFC 6265 lets plain http set one and browsers stopped allowing
+            // it. A cookie this jar would refuse to send is one it refuses to
+            // keep.
+            if (!secure && Cookie.parse(header, { loose: false })?.secure)
+                continue;
+            // ignoreError: a cookie a browser would refuse is one this jar
+            // refuses, silently, rather than failing the call that carried it.
+            this.jar.setCookieSync(header, url, { http: true, now, ignoreError: true });
+        }
+    }
+    /** Every live cookie. */
+    list() {
+        const now = this.now();
+        return (this.jar.serializeSync()?.cookies ?? [])
+            .map((serialized) => Cookie.fromJSON(serialized))
+            .filter((cookie) => cookie !== undefined)
+            .map((cookie) => storedFromCookie(cookie, now))
+            .filter((cookie) => cookie.expires === undefined || cookie.expires > now);
+    }
+    /**
+     * The Cookie header pairs the next request carries, as `name=value`, in
+     * the order RFC 6265 section 5.4 puts them in: the longest Path first,
+     * and among equal paths the one set first. Servers that read only the
+     * first value of a repeated name depend on that order, and so does any
+     * test reasoning about which of two same-named cookies wins.
+     *
+     * Only the cookies whose scope covers the target travel. A field the
+     * target leaves out is one the caller could not know, and matches
+     * anything: a caller that cannot name its own host still gets the cookies
+     * of the one host its jar talks to.
+     */
+    cookiePairs(target = {}) {
+        return this.matchingCookies(target).map((cookie) => `${cookie.name}=${cookie.value}`);
+    }
+    /**
+     * One cookie's value as a page's script would read it: HttpOnly cookies
+     * are invisible unless asked for, which is how the transport fills in the
+     * CSRF token the caller would have read from document.cookie.
+     */
+    get(name, options = {}) {
+        return this.matchingCookies(options, options.includeHttpOnly === true)
+            .find((cookie) => cookie.name === name)?.value;
+    }
+    /**
+     * The live cookies whose scope reaches this target, in RFC 6265 send
+     * order. Delegated to tough-cookie whenever the target names a host,
+     * which is the case worth getting exactly right; an unnamed host falls
+     * back to every cookie the jar holds, filtered by the rules that do not
+     * need one and ordered by the same rule.
+     */
+    matchingCookies(target, includeHttpOnly = true) {
+        const secure = target.secure !== false;
+        if (target.host !== undefined || this.host !== undefined) {
+            const url = urlFor(this.hostFor(target.host), target.path, secure);
+            return this.jar
+                .getCookiesSync(url, {
+                // http: false is a script reading document.cookie, which
+                // is exactly what hides an HttpOnly cookie.
+                http: includeHttpOnly,
+                // A target that named no path is asking about the jar, not
+                // about one endpoint.
+                allPaths: target.path === undefined,
+                // tough-cookie returns store order unless asked; RFC 6265
+                // order is what a server reading the first of a repeated
+                // name actually gets.
+                sort: true,
+            })
+                .map((cookie) => storedFromCookie(cookie, this.now()))
+                // getCookiesSync expires against the real clock; a jar given
+                // an injected one is usually a test moving time forward.
+                .filter((cookie) => cookie.expires === undefined || cookie.expires > this.now())
+                // tough-cookie treats a loopback or localhost target as a
+                // secure context and sends Secure cookies to it over http.
+                // This jar takes `secure: false` at its word in both
+                // directions, so what it stores and what it sends agree.
+                .filter((cookie) => secure || !cookie.secure);
+        }
+        return this.list()
+            .filter((cookie) => {
+            if (cookie.httpOnly && !includeHttpOnly)
+                return false;
+            if (cookie.secure && !secure)
+                return false;
+            if (target.path !== undefined && !pathMatch(target.path, cookie.path))
+                return false;
+            return true;
+        })
+            // The longest path first, as tough-cookie's own comparison does;
+            // the sort is stable, so equal paths keep the order they were
+            // stored in, which is the order they were created in.
+            .sort((a, b) => b.path.length - a.path.length);
+    }
+    /** Number of live cookies. */
+    get size() { return this.list().length; }
+    /** Forgets every cookie: the browser's storage cleared. */
+    clear() {
+        this.jar.removeAllCookiesSync();
+    }
+}

package/dist/shared/transport/lambderCookieJarTransport.d.ts

@@ -0,0 +1,30 @@
+import { type LambderApiTransport } from "./LambderApiTransport.js";
+import type { LambderCookieJar } from "./LambderCookieJar.js";
+/**
+ * Makes any transport carry a cookie jar the way a browser carries its
+ * cookies: the jar's cookies ride on every request, the answer's Set-Cookie
+ * headers land in the jar, and, because a page's script reads the
+ * non-HttpOnly CSRF cookie the same way, the request's `token` is filled
+ * from the jar when the caller sent an empty one. This is how a session
+ * survives between calls where there is no browser: in a Node test through
+ * lambderHandlerTransport, or in the mock runtime's direct transport.
+ *
+ * The jar is only as scoped as the host it is told about. An absolute apiPath
+ * carries one, `host` names one when the path is relative, and a browser's
+ * caller falls back to its page's: an in-process or mock transport posts to a
+ * relative path from a runtime with no location, so nothing there says which
+ * host these cookies belong to. Without any of the three the jar is a single
+ * host's, refusing Domain cookies it cannot check (see LambderCookieJar), so
+ * give `host` (or the jar one) to any jar that more than one host answers
+ * into.
+ *
+ * Its own file rather than a passage inside the transport seam: it is a
+ * transport like its three siblings, and it is the one of them that pulls in
+ * tough-cookie, which a bundle that never carries a jar should be able to
+ * drop.
+ */
+export declare const lambderCookieJarTransport: (inner: LambderApiTransport, options: {
+    jar: LambderCookieJar;
+    csrfCookieKey?: string;
+    host?: string;
+}) => LambderApiTransport;

package/dist/shared/transport/lambderCookieJarTransport.js

@@ -0,0 +1,60 @@
+import { DEFAULT_SESSION_CSRF_COOKIE_KEY } from "../wire/LambderSessionCookieNames.js";
+import { resolveApiPathTarget } from "./LambderApiTransport.js";
+/**
+ * Makes any transport carry a cookie jar the way a browser carries its
+ * cookies: the jar's cookies ride on every request, the answer's Set-Cookie
+ * headers land in the jar, and, because a page's script reads the
+ * non-HttpOnly CSRF cookie the same way, the request's `token` is filled
+ * from the jar when the caller sent an empty one. This is how a session
+ * survives between calls where there is no browser: in a Node test through
+ * lambderHandlerTransport, or in the mock runtime's direct transport.
+ *
+ * The jar is only as scoped as the host it is told about. An absolute apiPath
+ * carries one, `host` names one when the path is relative, and a browser's
+ * caller falls back to its page's: an in-process or mock transport posts to a
+ * relative path from a runtime with no location, so nothing there says which
+ * host these cookies belong to. Without any of the three the jar is a single
+ * host's, refusing Domain cookies it cannot check (see LambderCookieJar), so
+ * give `host` (or the jar one) to any jar that more than one host answers
+ * into.
+ *
+ * Its own file rather than a passage inside the transport seam: it is a
+ * transport like its three siblings, and it is the one of them that pulls in
+ * tough-cookie, which a bundle that never carries a jar should be able to
+ * drop.
+ */
+export const lambderCookieJarTransport = (inner, options) => {
+    return async (request) => {
+        // The caller's own name wins over the default, and an explicit option
+        // over both: reading the default name regardless would hand every
+        // session call an empty token whenever a caller was told a custom one
+        // through setSessionCookieKey.
+        const csrfCookieKey = options.csrfCookieKey ?? request.csrfCookieKey ?? DEFAULT_SESSION_CSRF_COOKIE_KEY;
+        // Where the call is going. An apiPath that names its own host is a
+        // fact about this request and outranks both the `host` option and the
+        // caller's siteHost: the option is the fallback for a relative path,
+        // where nothing says which host these cookies belong to, and siteHost
+        // is only the page the caller happens to be on. Read the other way
+        // round, a transport pinned to `host: "app.example.com"` sent
+        // app.example.com's session to an absolute cross-origin apiPath.
+        // siteHost is "" outside a browser, and an empty host would scope
+        // every cookie to nothing while claiming to scope it.
+        const target = resolveApiPathTarget(request.apiPath);
+        const cookieScope = {
+            host: target.host ?? options.host ?? (request.siteHost || undefined),
+            path: target.path,
+            ...(target.secure !== undefined ? { secure: target.secure } : {}),
+        };
+        const answer = await inner({
+            ...request,
+            token: request.token || options.jar.get(csrfCookieKey, cookieScope) || "",
+            cookies: [...(request.cookies ?? []), ...options.jar.cookiePairs(cookieScope)],
+        });
+        // The same scope the request was made under, so a Set-Cookie is judged
+        // against the channel it actually arrived on: a Secure cookie from a
+        // plain-http target is one this jar could never send back.
+        if (answer.setCookies?.length)
+            options.jar.storeSetCookies(answer.setCookies, cookieScope);
+        return answer;
+    };
+};

package/dist/shared/util/LambderBase64.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Base64 in both directions where Buffer may not exist (the browser caller,
+ * the mock runtime in a page). Buffer where there is one, since it is much
+ * faster; otherwise the platform's atob/btoa, chunked on the way in so a
+ * large payload cannot overflow the argument list of String.fromCharCode.
+ */
+export declare const bytesToBase64: (bytes: Uint8Array) => string;
+export declare const base64ToBytes: (base64: string) => Uint8Array;
+/** The base64 of UTF-8 text back to the text. */
+export declare const base64ToText: (base64: string) => string;

package/dist/shared/util/LambderBase64.js

@@ -0,0 +1,27 @@
+/**
+ * Base64 in both directions where Buffer may not exist (the browser caller,
+ * the mock runtime in a page). Buffer where there is one, since it is much
+ * faster; otherwise the platform's atob/btoa, chunked on the way in so a
+ * large payload cannot overflow the argument list of String.fromCharCode.
+ */
+export const bytesToBase64 = (bytes) => {
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("base64");
+    const chunkSize = 0x8000;
+    let binary = "";
+    for (let i = 0; i < bytes.length; i += chunkSize) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunkSize));
+    }
+    return btoa(binary);
+};
+export const base64ToBytes = (base64) => {
+    if (typeof Buffer !== "undefined")
+        return Buffer.from(base64, "base64");
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i += 1)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+};
+/** The base64 of UTF-8 text back to the text. */
+export const base64ToText = (base64) => new TextDecoder().decode(base64ToBytes(base64));

package/dist/shared/util/LambderCallAbort.d.ts

@@ -0,0 +1,62 @@
+/**
+ * One call's abort wiring, shared by LambderCaller (a browser over fetch) and
+ * LambderInvokeCaller (a server over a Lambda invoke).
+ *
+ * Both give a call a `timeoutMs`, both let the site pass its own AbortSignal,
+ * and both have to answer the same three questions: which signal does the
+ * transport get, has the call already been given up on before it is sent, and
+ * did the answer arrive after it was given up on. Written twice, the two
+ * drifted: the browser caller learned not to believe a late answer and the
+ * invoke caller did not, so a 20ms timeoutMs there reported `ok: true` at
+ * 300ms and the call site acted on data it had already abandoned.
+ *
+ * The listener on an external signal is removed in detach() rather than left
+ * to `once`: a site's signal usually outlives the call (one controller per
+ * page, per view, per request), so a listener per call would accumulate on it
+ * for as long as the signal lives.
+ */
+/** How an abandoned call is reported: its own timeout fired, or the site's signal did, which is a `network` failure like any other abort. */
+type LambderCallAbortReason = "timeout" | "network";
+/** The reason and the error to report for a call that was given up on. */
+type LambderCallAbortFailure = {
+    reason: LambderCallAbortReason;
+    error: Error;
+};
+/**
+ * Where the abort was noticed, which is all that differs between the two
+ * checks: nothing was sent, or something came back too late to be used.
+ */
+export type LambderCallAbortStage = "beforeSending" | "afterAnswering";
+type LambderCallAbort = {
+    /** What the transport is handed: the chained signal when a timeout is set, the site's own otherwise, and nothing when there is neither. */
+    signal: AbortSignal | undefined;
+    /** Whether this call's own timeout is what aborted it, rather than the site's signal. */
+    timedOut: () => boolean;
+    /**
+     * The failure to report, or null while the call still stands. Run before
+     * handing the request to the transport (a call already abandoned should
+     * not reach it) and again after the transport resolves, because honouring
+     * `request.signal` is the transport's obligation and not every transport
+     * does: an answer that arrives after the abort is not a success.
+     */
+    abortFailure: (stage: LambderCallAbortStage) => LambderCallAbortFailure | null;
+    /** Clears the timer and lets go of the external signal. Belongs in a finally. */
+    detach: () => void;
+};
+export declare const createCallAbort: (options: {
+    timeoutMs?: number;
+    signal?: AbortSignal;
+}) => LambderCallAbort;
+/**
+ * Ends the wait on work that cannot be cancelled, which is what honouring
+ * `request.signal` means for a transport running a handler in this process:
+ * the callee runs to completion either way, and what the caller's timeout
+ * buys is its own answer. Used by lambderHandlerTransport and by
+ * LambderInvokeCaller.localTransport, whose in-process calls are the two
+ * places a signal has nothing to cancel.
+ *
+ * The listener is detached on either outcome, for the reason createCallAbort
+ * detaches its own.
+ */
+export declare const stopWaitingWhenAborted: <T>(pending: Promise<T>, signal: AbortSignal | undefined) => Promise<T>;
+export {};

package/dist/shared/util/LambderCallAbort.js

@@ -0,0 +1,80 @@
+/**
+ * One call's abort wiring, shared by LambderCaller (a browser over fetch) and
+ * LambderInvokeCaller (a server over a Lambda invoke).
+ *
+ * Both give a call a `timeoutMs`, both let the site pass its own AbortSignal,
+ * and both have to answer the same three questions: which signal does the
+ * transport get, has the call already been given up on before it is sent, and
+ * did the answer arrive after it was given up on. Written twice, the two
+ * drifted: the browser caller learned not to believe a late answer and the
+ * invoke caller did not, so a 20ms timeoutMs there reported `ok: true` at
+ * 300ms and the call site acted on data it had already abandoned.
+ *
+ * The listener on an external signal is removed in detach() rather than left
+ * to `once`: a site's signal usually outlives the call (one controller per
+ * page, per view, per request), so a listener per call would accumulate on it
+ * for as long as the signal lives.
+ */
+export const createCallAbort = (options) => {
+    const { timeoutMs, signal: external } = options;
+    let timedOut = false;
+    let signal = external;
+    let timeoutId;
+    let detachExternal;
+    if (timeoutMs !== undefined) {
+        // The timeout gets its own controller chained to the site's signal, so
+        // either source aborts the call and only this one knows which did.
+        const controller = new AbortController();
+        if (external) {
+            if (external.aborted) {
+                controller.abort(external.reason);
+            }
+            else {
+                const forwardAbort = () => controller.abort(external.reason);
+                external.addEventListener("abort", forwardAbort, { once: true });
+                detachExternal = () => external.removeEventListener("abort", forwardAbort);
+            }
+        }
+        timeoutId = setTimeout(() => { timedOut = true; controller.abort(); }, timeoutMs);
+        signal = controller.signal;
+    }
+    return {
+        signal,
+        timedOut: () => timedOut,
+        abortFailure: (stage) => {
+            if (!signal?.aborted)
+                return null;
+            const detail = stage === "beforeSending"
+                ? "the call was given up on before it was sent"
+                : "the answer arrived too late to be used";
+            return timedOut
+                ? { reason: "timeout", error: new Error(`Request timed out after ${timeoutMs}ms; ${detail}.`) }
+                : { reason: "network", error: new Error(`Request aborted; ${detail}.`) };
+        },
+        detach: () => {
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            detachExternal?.();
+        },
+    };
+};
+/**
+ * Ends the wait on work that cannot be cancelled, which is what honouring
+ * `request.signal` means for a transport running a handler in this process:
+ * the callee runs to completion either way, and what the caller's timeout
+ * buys is its own answer. Used by lambderHandlerTransport and by
+ * LambderInvokeCaller.localTransport, whose in-process calls are the two
+ * places a signal has nothing to cancel.
+ *
+ * The listener is detached on either outcome, for the reason createCallAbort
+ * detaches its own.
+ */
+export const stopWaitingWhenAborted = (pending, signal) => {
+    if (!signal)
+        return pending;
+    return new Promise((resolve, reject) => {
+        const onAbort = () => reject(signal.reason);
+        signal.addEventListener("abort", onAbort, { once: true });
+        pending.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+    });
+};

package/dist/shared/util/LambderClientIp.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The client address as one textual form, and the rule for which header may
+ * name it. Shared by every adapter that builds a request (the Lambda server,
+ * the mock's invoke transport), so a `per: "ip"` rate limit keys the same
+ * address the same way whichever runtime served the call.
+ */
+/**
+ * The loopback address an in-process caller is given when nothing names a
+ * client: the handler transport and the mock runtime both default to it, so
+ * a per-IP rate limit exercised in a test keys the same way on both.
+ */
+export declare const LOOPBACK_CLIENT_IP = "127.0.0.1";
+/**
+ * One textual form per address, so a rate-limit counter cannot be split.
+ * A forwarding proxy may write the RFC 7239 bracket-and-port form
+ * ([2001:db8::1]:443) or a plain host:port, and IPv6 has many spellings for
+ * one address; each variant would otherwise be its own counter, which is a
+ * limit that does not limit. Anything longer than the longest valid address
+ * is truncated rather than trusted as a key.
+ */
+export declare const normalizeClientIp: (value: string) => string;
+/**
+ * The first trusted header that carries anything, leftmost entry, else the
+ * address the gateway observed. Nothing is trusted by default, and there is
+ * no exception for an invoke: the marker header that would have signalled
+ * one is an ordinary request header that any HTTP caller can set, so
+ * honouring it would hand every caller the value again. A genuine invoke
+ * needs no exception, because the synthesized event carries the end user's
+ * address in requestContext.http.sourceIp, which is where `sourceIp` comes
+ * from anyway.
+ */
+export declare const resolveClientIp: (lowercasedHeaders: Record<string, string>, sourceIp: string, trustedClientIpHeaders?: readonly string[]) => string;

package/dist/shared/util/LambderClientIp.js

@@ -0,0 +1,56 @@
+/**
+ * The client address as one textual form, and the rule for which header may
+ * name it. Shared by every adapter that builds a request (the Lambda server,
+ * the mock's invoke transport), so a `per: "ip"` rate limit keys the same
+ * address the same way whichever runtime served the call.
+ */
+/**
+ * The loopback address an in-process caller is given when nothing names a
+ * client: the handler transport and the mock runtime both default to it, so
+ * a per-IP rate limit exercised in a test keys the same way on both.
+ */
+export const LOOPBACK_CLIENT_IP = "127.0.0.1";
+/** Longest textual IPv6 address (39) plus a scope id; beyond this the value is not an address. */
+const MAX_CLIENT_IP_LENGTH = 45;
+/**
+ * One textual form per address, so a rate-limit counter cannot be split.
+ * A forwarding proxy may write the RFC 7239 bracket-and-port form
+ * ([2001:db8::1]:443) or a plain host:port, and IPv6 has many spellings for
+ * one address; each variant would otherwise be its own counter, which is a
+ * limit that does not limit. Anything longer than the longest valid address
+ * is truncated rather than trusted as a key.
+ */
+export const normalizeClientIp = (value) => {
+    let ip = value.trim();
+    if (ip.startsWith("[")) {
+        // [v6] or [v6]:port
+        const close = ip.indexOf("]");
+        if (close > 0)
+            ip = ip.slice(1, close);
+    }
+    else if (ip.split(":").length === 2) {
+        // host:port, which only an IPv4 address or a hostname can be: a bare
+        // IPv6 address always carries more than one colon.
+        ip = ip.slice(0, ip.indexOf(":"));
+    }
+    return ip.toLowerCase().slice(0, MAX_CLIENT_IP_LENGTH);
+};
+/**
+ * The first trusted header that carries anything, leftmost entry, else the
+ * address the gateway observed. Nothing is trusted by default, and there is
+ * no exception for an invoke: the marker header that would have signalled
+ * one is an ordinary request header that any HTTP caller can set, so
+ * honouring it would hand every caller the value again. A genuine invoke
+ * needs no exception, because the synthesized event carries the end user's
+ * address in requestContext.http.sourceIp, which is where `sourceIp` comes
+ * from anyway.
+ */
+export const resolveClientIp = (lowercasedHeaders, sourceIp, trustedClientIpHeaders = []) => {
+    for (const name of trustedClientIpHeaders) {
+        const value = lowercasedHeaders[name.toLowerCase()];
+        const first = value ? (value.split(",")[0] ?? "").trim() : "";
+        if (first)
+            return normalizeClientIp(first);
+    }
+    return normalizeClientIp(sourceIp) || "";
+};