lambder 7.3.1 → 8.1.1

package/dist/shared/transport/LambderCookieJar.js

@@ -6,10 +6,9 @@
 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.
+ * read of such a jar uses it, so the jar behaves consistently as the browser
+ * of one unnamed host. `.invalid` is IANA-reserved, 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]". */
@@ -28,12 +27,11 @@ const urlFor = (host, path, secure) => `${secure ? "https" : "http"}://${host}${
 /**
  * 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.
+ * Max-Age and Expires are stored separately and Max-Age wins, so reading
+ * `expires` alone would call a `Max-Age=0` deletion immortal. The library's
+ * expiryTime() resolves Max-Age against whatever moment it is handed (or
+ * lastAccessed), so it cannot answer "when does this die" on a fixed clock.
+ * A browser measures Max-Age from when the cookie arrived, its creation.
  */
 const cookieExpiryAt = (cookie, now) => {
     if (typeof cookie.maxAge === "number") {
@@ -50,8 +48,8 @@ const storedFromCookie = (cookie, now) => {
         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.
+        // A jar that never learned a host parks cookies under the stand-in,
+        // 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,
@@ -68,11 +66,11 @@ 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.
+    // Cookie.parse stamps creation with the real clock, but Max-Age is
+    // measured from the caller's `now`, when this header arrived.
     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.
+    // Max-Age against Expires on the caller's clock, as the jar resolves it,
+    // 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
@@ -85,28 +83,23 @@ export const parseSetCookie = (header, now, requestPath) => {
  * 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.
+ * carry. One jar is one browser.
  *
- * 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.
+ * The rules (domain and path matching, default-path, Max-Age against Expires,
+ * Secure, HttpOnly, the __Host-/__Secure- prefixes) are tough-cookie's, the
+ * reference RFC 6265 implementation, imported for its public suffix list:
+ * counting labels can tell `Domain=com` is a registry suffix but not `co.uk`,
+ * 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.
+ * What stays Lambder's is the shape of a transport's questions: Set-Cookie
+ * header lists in (storeSetCookies), `name=value` pairs out (cookiePairs),
+ * and a target given as host and path, since a transport that never speaks
+ * HTTP has no URL. An omitted field matches anything, because a jar pointed
+ * at a single host is the ordinary case and should not have to name it.
  *
- * 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.
+ * SameSite is stored but never consulted: it answers "did another site
+ * initiate this", and every transport call is same-site by construction.
  */
 export class LambderCookieJar {
     // prefixSecurity "silent" drops a __Host-/__Secure- cookie that breaks its
@@ -129,25 +122,23 @@ export class LambderCookieJar {
      * 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.
+     * A Domain the sender is not under voids the cookie rather than narrowing
+     * it (RFC 6265 section 5.3 step 6), and so does a public-suffix Domain.
+     * Otherwise evil.example.com could 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.
+        // A cookie is judged against the channel it arrived on. Assuming https
+        // would accept Secure cookies from a plain-http answer and then never
+        // send them, leaving the jar silently holding an unusable session.
         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.
+            // tough-cookie checks Domain, prefixes and HttpOnly against the
+            // URL but leaves Secure to the caller: RFC 6265 lets plain http
+            // set one, browsers do not. 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
@@ -166,15 +157,14 @@ export class LambderCookieJar {
     }
     /**
      * 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.
+     * RFC 6265 section 5.4 order: 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, as does any test 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.
+     * Only cookies whose scope covers the target travel. An omitted target
+     * field matches anything, so a caller that cannot name its 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}`);
@@ -190,10 +180,9 @@ export class LambderCookieJar {
     }
     /**
      * 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.
+     * order. Delegated to tough-cookie whenever a host is known, the case
+     * worth getting exactly right; with no host, every cookie the jar holds
+     * is filtered by the rules that need none and ordered the same way.
      */
     matchingCookies(target, includeHttpOnly = true) {
         const secure = target.secure !== false;
@@ -209,7 +198,7 @@ export class LambderCookieJar {
                 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.
+                // name gets.
                 sort: true,
             })
                 .map((cookie) => storedFromCookie(cookie, this.now()))
@@ -218,8 +207,8 @@ export class LambderCookieJar {
                 .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.
+                // This jar takes `secure: false` at its word both ways, so
+                // what it stores and what it sends agree.
                 .filter((cookie) => secure || !cookie.secure);
         }
         return this.list()
@@ -232,9 +221,8 @@ export class LambderCookieJar {
                 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.
+            // Longest path first, as tough-cookie sorts; the sort is stable,
+            // so equal paths keep their creation order.
             .sort((a, b) => b.path.length - a.path.length);
     }
     /** Number of live cookies. */

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

@@ -3,23 +3,21 @@ 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.
+ * headers land in the jar, and, as a page's script reads the non-HttpOnly
+ * CSRF cookie, the request's `token` is filled from the jar when the caller
+ * sent an empty one. This is how a session survives between calls without a
+ * 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.
+ * 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 names the
+ * host. Without any of the three the jar is a single host's and refuses
+ * 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
+ * Its own file, like its three sibling transports, because it pulls in
  * tough-cookie, which a bundle that never carries a jar should be able to
  * drop.
  */

package/dist/shared/transport/lambderCookieJarTransport.js

@@ -3,23 +3,21 @@ 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.
+ * headers land in the jar, and, as a page's script reads the non-HttpOnly
+ * CSRF cookie, the request's `token` is filled from the jar when the caller
+ * sent an empty one. This is how a session survives between calls without a
+ * 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.
+ * 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 names the
+ * host. Without any of the three the jar is a single host's and refuses
+ * 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
+ * Its own file, like its three sibling transports, because it pulls in
  * tough-cookie, which a bundle that never carries a jar should be able to
  * drop.
  */
@@ -31,23 +29,23 @@ export const lambderCookieJarTransport = (inner, options) => {
         // 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.
+        // fact about this request and outranks both the `host` option (the
+        // fallback for a relative path) and the caller's siteHost (only the
+        // page the caller is on). The other way round, a transport pinned to
+        // `host: "app.example.com"` would send that host'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 postedToken = request.token || options.jar.get(csrfCookieKey, cookieScope) || "";
         const answer = await inner({
             ...request,
-            token: request.token || options.jar.get(csrfCookieKey, cookieScope) || "",
+            token: postedToken,
             cookies: [...(request.cookies ?? []), ...options.jar.cookiePairs(cookieScope)],
         });
         // The same scope the request was made under, so a Set-Cookie is judged
@@ -55,6 +53,9 @@ export const lambderCookieJarTransport = (inner, options) => {
         // plain-http target is one this jar could never send back.
         if (answer.setCookies?.length)
             options.jar.storeSetCookies(answer.setCookies, cookieScope);
-        return answer;
+        // The session lives in the jar, not in document.cookie, so the caller
+        // tells a sessionExpired about an older session (a poll sent before a
+        // login) by the jar's token, as a page does by its cookie.
+        return { ...answer, csrfTokens: { posted: postedToken, held: () => options.jar.get(csrfCookieKey, cookieScope) ?? "" } };
     };
 };

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

@@ -5,10 +5,9 @@
  * 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.
+ * did the answer arrive after it was given up on. One implementation keeps
+ * the two from drifting apart: a caller that believed a late answer would
+ * report `ok: true` for a call its site 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
@@ -53,7 +52,8 @@ export declare const createCallAbort: (options: {
  * 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.
+ * transports a signal has nothing to cancel, and by the crash reporter's
+ * time bound (LambderCrashHandling), where the app's report runs on.
  *
  * The listener is detached on either outcome, for the reason createCallAbort
  * detaches its own.

package/dist/shared/util/LambderCallAbort.js

@@ -5,10 +5,9 @@
  * 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.
+ * did the answer arrive after it was given up on. One implementation keeps
+ * the two from drifting apart: a caller that believed a late answer would
+ * report `ok: true` for a call its site 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
@@ -64,7 +63,8 @@ export const createCallAbort = (options) => {
  * 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.
+ * transports a signal has nothing to cancel, and by the crash reporter's
+ * time bound (LambderCrashHandling), where the app's report runs on.
  *
  * The listener is detached on either outcome, for the reason createCallAbort
  * detaches its own.

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

@@ -13,20 +13,36 @@ 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.
+ * ([2001:db8::1]:443) or a plain host:port; each variant would otherwise be
+ * its own counter, which is a limit that does not limit. An unbracketed IPv6
+ * address with a port after it cannot be told apart by its text
+ * (`2001:db8::1:443` is an address too), so this leaves it alone; the header
+ * that writes that form has its port taken off by resolveClientIp, which
+ * knows where the value came from. Anything longer than the longest valid
+ * address is truncated rather than trusted as a key.
  */
 export declare const normalizeClientIp: (value: string) => string;
+/** The IPv6 prefix a per-IP rate limit counts by default: the /64 every subscriber holds at least. */
+export declare const DEFAULT_IPV6_RATE_LIMIT_PREFIX = 64;
+/**
+ * The caller a per-IP rate limit counts, which is not always the address
+ * itself. An IPv4 address is one subscriber. An IPv6 subscriber, a VPS
+ * included, holds at least a /64 and may pick any interface id inside it, so
+ * one counter per full address is a fresh counter per request for anyone
+ * who rotates: the prefix is what is counted (`2001:db8:1:2:0:0:0:0/64`). An
+ * IPv4-mapped IPv6 address (::ffff:192.0.2.1) is its IPv4 address, so the
+ * two spellings share a counter. A value that is not an address is counted
+ * as it is. ctx.ip itself stays the exact address, for logs.
+ */
+export declare const rateLimitSubjectOf: (ip: string, ipv6PrefixLength?: number) => 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.
+ * address the gateway observed; a header that always appends the port (see
+ * PORT_SUFFIXED_IP_HEADERS) has it taken off. Nothing is trusted by default,
+ * and there is no exception for an invoke: the invoke marker is an ordinary
+ * request header any HTTP caller can set, so honouring it would let every
+ * caller choose its own address. 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

@@ -12,13 +12,60 @@
 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;
+/** A dotted IPv4 address as its four octets, or null when the text is not one. */
+const parseIpv4 = (value) => {
+    const parts = value.split(".");
+    if (parts.length !== 4 || !parts.every((part) => /^\d{1,3}$/.test(part)))
+        return null;
+    const octets = parts.map(Number);
+    return octets.every((octet) => octet <= 255) ? octets : null;
+};
+/**
+ * An IPv6 address as its eight 16-bit groups, or null when the text is not
+ * one: every spelling of one address (compressed or not, any case, with an
+ * embedded IPv4 tail) parses to the same groups.
+ */
+const parseIpv6 = (value) => {
+    // A zone id names the interface an address was reached on, not the address.
+    let text = value.split("%")[0];
+    const lastColon = text.lastIndexOf(":");
+    if (lastColon === -1)
+        return null;
+    const tail = text.slice(lastColon + 1);
+    if (tail.includes(".")) {
+        const octets = parseIpv4(tail);
+        if (!octets)
+            return null;
+        text = `${text.slice(0, lastColon + 1)}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+    }
+    const halves = text.split("::");
+    if (halves.length > 2)
+        return null;
+    const groupsOf = (part) => {
+        if (part === "")
+            return [];
+        const groups = part.split(":");
+        return groups.every((group) => /^[0-9a-f]{1,4}$/i.test(group)) ? groups.map((group) => parseInt(group, 16)) : null;
+    };
+    const head = groupsOf(halves[0]);
+    const rest = halves.length === 2 ? groupsOf(halves[1]) : [];
+    if (!head || !rest)
+        return null;
+    if (halves.length === 1)
+        return head.length === 8 ? head : null;
+    const missing = 8 - head.length - rest.length;
+    return missing >= 1 ? [...head, ...new Array(missing).fill(0), ...rest] : null;
+};
 /**
  * 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.
+ * ([2001:db8::1]:443) or a plain host:port; each variant would otherwise be
+ * its own counter, which is a limit that does not limit. An unbracketed IPv6
+ * address with a port after it cannot be told apart by its text
+ * (`2001:db8::1:443` is an address too), so this leaves it alone; the header
+ * that writes that form has its port taken off by resolveClientIp, which
+ * knows where the value came from. Anything longer than the longest valid
+ * address is truncated rather than trusted as a key.
  */
 export const normalizeClientIp = (value) => {
     let ip = value.trim();
@@ -35,22 +82,58 @@ export const normalizeClientIp = (value) => {
     }
     return ip.toLowerCase().slice(0, MAX_CLIENT_IP_LENGTH);
 };
+/**
+ * Headers whose value always ends in `:port`, whatever the address before
+ * it: CloudFront-Viewer-Address writes `192.0.2.1:443` and
+ * `2001:db8::1:443` alike, with no brackets. The last colon-separated
+ * segment of such a value is the port by definition. Read from the text
+ * instead, a compressed IPv6 address with its port on still parses, the port
+ * becomes its last group, and the /64 a per-IP limit counts moves with the
+ * interface id the caller picks.
+ */
+const PORT_SUFFIXED_IP_HEADERS = new Set(["cloudfront-viewer-address"]);
+/** The IPv6 prefix a per-IP rate limit counts by default: the /64 every subscriber holds at least. */
+export const DEFAULT_IPV6_RATE_LIMIT_PREFIX = 64;
+/**
+ * The caller a per-IP rate limit counts, which is not always the address
+ * itself. An IPv4 address is one subscriber. An IPv6 subscriber, a VPS
+ * included, holds at least a /64 and may pick any interface id inside it, so
+ * one counter per full address is a fresh counter per request for anyone
+ * who rotates: the prefix is what is counted (`2001:db8:1:2:0:0:0:0/64`). An
+ * IPv4-mapped IPv6 address (::ffff:192.0.2.1) is its IPv4 address, so the
+ * two spellings share a counter. A value that is not an address is counted
+ * as it is. ctx.ip itself stays the exact address, for logs.
+ */
+export const rateLimitSubjectOf = (ip, ipv6PrefixLength = DEFAULT_IPV6_RATE_LIMIT_PREFIX) => {
+    const groups = parseIpv6(ip);
+    if (!groups)
+        return ip;
+    if (groups.slice(0, 5).every((group) => group === 0) && groups[5] === 0xffff) {
+        return `${groups[6] >> 8}.${groups[6] & 0xff}.${groups[7] >> 8}.${groups[7] & 0xff}`;
+    }
+    const masked = groups.map((group, index) => {
+        const kept = Math.max(0, Math.min(16, ipv6PrefixLength - index * 16));
+        return kept === 0 ? 0 : group & ((0xffff << (16 - kept)) & 0xffff);
+    });
+    return `${masked.map((group) => group.toString(16)).join(":")}/${ipv6PrefixLength}`;
+};
 /**
  * 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.
+ * address the gateway observed; a header that always appends the port (see
+ * PORT_SUFFIXED_IP_HEADERS) has it taken off. Nothing is trusted by default,
+ * and there is no exception for an invoke: the invoke marker is an ordinary
+ * request header any HTTP caller can set, so honouring it would let every
+ * caller choose its own address. 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 header = name.toLowerCase();
+        const value = lowercasedHeaders[header];
         const first = value ? (value.split(",")[0] ?? "").trim() : "";
         if (first)
-            return normalizeClientIp(first);
+            return normalizeClientIp(PORT_SUFFIXED_IP_HEADERS.has(header) ? first.replace(/:\d+$/, "") : first);
     }
     return normalizeClientIp(sourceIp) || "";
 };

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

@@ -0,0 +1,10 @@
+/**
+ * A Content-Disposition header for a file name of any characters: an ASCII
+ * `filename` for old clients, and the exact name as UTF-8 in `filename*`
+ * (RFC 6266). A character a header cannot carry never reaches it, so a name
+ * holding a quote or a line break cannot end the header early.
+ */
+export declare const contentDispositionHeader: ({ disposition, fileName }: {
+    disposition: "inline" | "attachment";
+    fileName?: string;
+}) => string;

package/dist/shared/util/LambderContentDisposition.js

@@ -0,0 +1,13 @@
+/**
+ * A Content-Disposition header for a file name of any characters: an ASCII
+ * `filename` for old clients, and the exact name as UTF-8 in `filename*`
+ * (RFC 6266). A character a header cannot carry never reaches it, so a name
+ * holding a quote or a line break cannot end the header early.
+ */
+export const contentDispositionHeader = ({ disposition, fileName }) => {
+    if (fileName === undefined)
+        return disposition;
+    const fallback = fileName.replace(/[^\x20-\x7e]|["\\%]/g, "_");
+    const encoded = encodeURIComponent(fileName).replace(/['()*]/g, (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`);
+    return `${disposition}; filename="${fallback}"; filename*=UTF-8''${encoded}`;
+};