lambder 7.0.2 → 7.2.0

package/dist/mock/LambderMockCreateOptions.js

@@ -1,9 +1 @@
-/*
- * What a mock runtime is configured with, and the shapes of what a mock
- * transport takes.
- *
- * Everything create() takes lives here, beside the rules that decide which
- * keys it accepts (the guards option and the surplus-key checks under it),
- * exactly as core/LambderCreateOptions.ts holds the server's.
- */
 export {};

package/dist/mock/LambderMockTypes.d.ts

@@ -374,6 +374,8 @@ export type LambderMockRequestEvent = {
     /** Exactly as posted, so `unknown`: the key is client data and only the idempotency engine judges it. */
     idempotencyKey: unknown;
     version: string | null;
+    /** The signature the caller sent for the endpoint; null when it carries no map. */
+    signature: string | null;
     headers: Record<string, string>;
     /** True when the request carried a session cookie. */
     hasSessionCookie: boolean;

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

@@ -10,6 +10,8 @@ export type LambderApiTransportRequest = {
     apiPath: string;
     apiName: string;
     version?: string;
+    /** The caller's signature for this endpoint, out of its LambderApiSignatureMap; absent when it carries no map. */
+    signature?: string;
     /** The CSRF token the caller read from its cookie; "" when it holds none. */
     token: string;
     /**
@@ -101,6 +103,7 @@ export type LambderApiTransport = (request: LambderApiTransportRequest) => Promi
 export declare const buildEnvelopeFields: (fields: {
     apiName: string;
     version?: string;
+    signature?: string;
     /** The CSRF token, as the envelope names it. */
     token: string;
     siteHost: string;

package/dist/shared/transport/LambderApiTransport.js

@@ -29,6 +29,7 @@ export const isLambderTransportFailure = (err) => err instanceof Error && err.is
 export const buildEnvelopeFields = (fields) => ({
     apiName: fields.apiName,
     version: fields.version,
+    ...(fields.signature !== undefined ? { signature: fields.signature } : {}),
     token: fields.token,
     siteHost: fields.siteHost,
     ...(fields.compressed ?? fields.payloadSlot ?? {}),
@@ -43,6 +44,7 @@ export const buildEnvelopeFields = (fields) => ({
 export const buildTransportEnvelope = (request) => buildEnvelopeFields({
     apiName: request.apiName,
     version: request.version,
+    signature: request.signature,
     token: request.token,
     siteHost: request.siteHost,
     payloadSlot: { payload: request.payload },

package/dist/shared/wire/LambderApiSignature.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The per-endpoint signatures a client carries, generated from the server's
+ * own registrations (Lambder.apiSignatures()) and shipped with the client
+ * build. The key is the endpoint's name hashed (apiNameKeyOf); the value is
+ * the digest of its client-facing shape (apiSignatureOf, computed on the
+ * server side). A caller given the map sends the value with every call, and
+ * the server answers versionExpired when it differs from the digest of what
+ * it serves now. So a client built against an endpoint that has since
+ * changed reloads, while one whose endpoint is unchanged keeps working
+ * across deploys.
+ *
+ * Keys are hashed so the map lists no endpoint names: the names a client
+ * calls are in its own code already, and the rest of the surface stays out
+ * of the bundle.
+ */
+export type LambderApiSignatureMap = Record<string, string>;
+/**
+ * How many hex characters a key and a signature keep. This is change
+ * detection, not authentication: 64 bits cannot collide by accident across
+ * the shapes one endpoint takes over its life, and the map stays small.
+ */
+export declare const API_SIGNATURE_HEX_LENGTH = 16;
+/**
+ * The key an endpoint's signature is stored under: SHA-256 over the prefixed
+ * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
+ * WebCrypto's digest is, and it is the only SHA-256 a browser has.
+ *
+ * Computed on the spot, every time, and nothing is kept. The digest that
+ * actually describes an endpoint is the generator's, computed once at build
+ * time; what is left here is one hash of a short name against a map already
+ * in memory, which is nothing beside the request it belongs to. A cache of
+ * it would have to be keyed by name, and on the server the name comes off
+ * the wire before anything has checked that it is an endpoint at all, so it
+ * would grow by an entry for every name a request cared to invent and never
+ * shrink.
+ */
+export declare const apiNameKeyOf: (apiName: string) => Promise<string>;
+/** The map's signature for one endpoint, or null when the map holds none for it. */
+export declare const lookupApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string | null>;
+/**
+ * The signature a caller sends for one endpoint. A name the map does not
+ * hold throws: the map was generated from a server that did not have this
+ * endpoint, so the file is stale, and a call sent without a signature would
+ * run instead of saying so.
+ */
+export declare const readApiSignature: (signatures: LambderApiSignatureMap, apiName: string) => Promise<string>;

package/dist/shared/wire/LambderApiSignature.js

@@ -0,0 +1,45 @@
+import { sha256HexOf } from "../util/LambderTextDigest.js";
+/**
+ * How many hex characters a key and a signature keep. This is change
+ * detection, not authentication: 64 bits cannot collide by accident across
+ * the shapes one endpoint takes over its life, and the map stays small.
+ */
+export const API_SIGNATURE_HEX_LENGTH = 16;
+/** Domain-separated, so a name's key can never equal a signature computed over a description that happens to read the same. */
+const API_NAME_KEY_PREFIX = "lambder-api-name:";
+/**
+ * The key an endpoint's signature is stored under: SHA-256 over the prefixed
+ * name, cut to API_SIGNATURE_HEX_LENGTH hex characters. Async because
+ * WebCrypto's digest is, and it is the only SHA-256 a browser has.
+ *
+ * Computed on the spot, every time, and nothing is kept. The digest that
+ * actually describes an endpoint is the generator's, computed once at build
+ * time; what is left here is one hash of a short name against a map already
+ * in memory, which is nothing beside the request it belongs to. A cache of
+ * it would have to be keyed by name, and on the server the name comes off
+ * the wire before anything has checked that it is an endpoint at all, so it
+ * would grow by an entry for every name a request cared to invent and never
+ * shrink.
+ */
+export const apiNameKeyOf = async (apiName) => (await sha256HexOf(API_NAME_KEY_PREFIX + apiName)).slice(0, API_SIGNATURE_HEX_LENGTH);
+/** The map's signature for one endpoint, or null when the map holds none for it. */
+export const lookupApiSignature = async (signatures, apiName) => {
+    const key = await apiNameKeyOf(apiName);
+    // Own properties only: the map is a plain object, and a key that happened
+    // to spell a prototype member would otherwise read a function.
+    const signature = Object.prototype.hasOwnProperty.call(signatures, key) ? signatures[key] : undefined;
+    return typeof signature === "string" ? signature : null;
+};
+/**
+ * The signature a caller sends for one endpoint. A name the map does not
+ * hold throws: the map was generated from a server that did not have this
+ * endpoint, so the file is stale, and a call sent without a signature would
+ * run instead of saying so.
+ */
+export const readApiSignature = async (signatures, apiName) => {
+    const signature = await lookupApiSignature(signatures, apiName);
+    if (signature === null) {
+        throw new Error(`Lambder: apiSignatures holds no signature for API "${apiName}". The map predates this endpoint; regenerate it from the server's apiSignatures().`);
+    }
+    return signature;
+};

package/dist/shared/wire/LambderVersionOrder.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Dotted version strings ("1.2.10"), compared segment by segment as numbers,
+ * so "1.2.10" sorts after "1.2.9" where a string comparison would put it
+ * first. The server's version floor (minApiVersion) reads a caller's version
+ * this way, and an app deciding whether a client is behind can read the
+ * envelope's apiVersion the same way.
+ */
+/** True for one or more decimal segments joined by dots: "7", "1.2", "1.2.10". */
+export declare const isDottedVersion: (value: string) => boolean;
+/** -1 when `a` is older than `b`, 1 when newer, 0 when equal. A missing segment counts as 0, so "1.2" equals "1.2.0". */
+export declare const compareDottedVersions: (a: string, b: string) => -1 | 0 | 1;

package/dist/shared/wire/LambderVersionOrder.js

@@ -0,0 +1,28 @@
+/**
+ * Dotted version strings ("1.2.10"), compared segment by segment as numbers,
+ * so "1.2.10" sorts after "1.2.9" where a string comparison would put it
+ * first. The server's version floor (minApiVersion) reads a caller's version
+ * this way, and an app deciding whether a client is behind can read the
+ * envelope's apiVersion the same way.
+ */
+/** True for one or more decimal segments joined by dots: "7", "1.2", "1.2.10". */
+export const isDottedVersion = (value) => /^\d+(\.\d+)*$/.test(value);
+/** A segment as a number; anything that is not one counts as 0, so a version nothing can read sorts below every real one. */
+const segmentOf = (text) => {
+    const parsed = parseInt(text, 10);
+    return Number.isFinite(parsed) ? parsed : 0;
+};
+/** -1 when `a` is older than `b`, 1 when newer, 0 when equal. A missing segment counts as 0, so "1.2" equals "1.2.0". */
+export const compareDottedVersions = (a, b) => {
+    const left = a.split(".").map(segmentOf);
+    const right = b.split(".").map(segmentOf);
+    for (let i = 0; i < Math.max(left.length, right.length); i += 1) {
+        const x = left[i] ?? 0;
+        const y = right[i] ?? 0;
+        if (x < y)
+            return -1;
+        if (x > y)
+            return 1;
+    }
+    return 0;
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lambder",
-  "version": "7.0.2",
+  "version": "7.2.0",
   "sideEffects": false,
   "description": "Opinionated serverless web framework for TypeScript on AWS Lambda: type-safe APIs from Zod schemas, DynamoDB sessions, and declarative rate limits, authorization guards and idempotency.",
   "keywords": [