@run402/functions 3.12.0 → 3.14.0

package/dist/lib/project-jwt-keys.js

@@ -0,0 +1,169 @@
+/**
+ * The project-JWT verification keyset, fetched from the gateway at cold start.
+ *
+ * WHY THIS EXISTS. Until now the runtime read `RUN402_JWT_SECRET` — the
+ * PLATFORM signing key — straight out of the Lambda environment. That key is
+ * symmetric, so verification material IS signing material: every one of the
+ * fleet's tenant Lambdas held the ability to forge `anon_key`/`service_key`
+ * for EVERY project on the platform, and those carry no expiry. It also made
+ * rotation impossible, because the key arrived at deploy time and could only
+ * change by redeploying someone else's code.
+ *
+ * Fetching a PUBLIC keyset instead fixes both at once: there is nothing here
+ * that can sign, and a rotated key reaches the fleet at the next cold start
+ * with no redeployment at all.
+ *
+ * Deliberately mirrors `lib/actor-context-verify.ts`, which established this
+ * pattern for the actor-context key — same lazy single-flight fetch, same
+ * service-key auth, same "failures are non-fatal, the next request retries".
+ *
+ * TRANSITION FALLBACK. While `RUN402_JWT_SECRET` is still injected, it is kept
+ * as a SECOND verification key, tried after the fetched keyset. This is
+ * temporary scaffolding with a defined removal point, and it is load-bearing
+ * for exactly one window: after the fleet carries this runtime but BEFORE the
+ * gateway's signing key becomes asymmetric, the gateway is still minting HS256
+ * tokens that the (asymmetric-only) fetched keyset cannot verify. Removing the
+ * fallback before then would break `getUser()` on every project at once.
+ * See `openspec/changes/functions-runtime-key-decoupling/design.md`.
+ */
+import { createPublicKey } from "node:crypto";
+let cached = null;
+let fetchInFlight = null;
+/**
+ * The keys `getUser()` should verify against, most-trusted first.
+ *
+ * Returns the fetched public keyset followed by the env-injected legacy key
+ * when one is present. Order matters only for which key is TRIED first — a
+ * token verifies against exactly one key either way, since `verifyWithKey`
+ * selects on `kid` and refuses to fall back on a signature mismatch.
+ */
+export function projectJwtVerificationKeys() {
+    const keys = cached ? [...cached] : [];
+    const legacy = legacyEnvKey();
+    if (legacy)
+        keys.push(legacy);
+    return keys;
+}
+/**
+ * The env-injected key, as a kid-less LEGACY verification key.
+ *
+ * `legacy: true` is what lets it verify the kid-less tokens the gateway signs
+ * today; once the gateway signs with a `kid`, its tokens select the fetched
+ * key by id and never reach this one.
+ */
+function legacyEnvKey() {
+    const raw = process.env.RUN402_JWT_SECRET;
+    if (!raw)
+        return null;
+    return { key: Buffer.from(raw, "utf8"), alg: "HS256", legacy: true };
+}
+/**
+ * Ensure the keyset is loaded before a synchronous verify.
+ *
+ * Single-flight: concurrent invocations in the same execution environment
+ * share one fetch. Cached for the life of the environment, so a warm Lambda
+ * pays nothing. Never throws — a failed fetch leaves whatever keys are
+ * available (possibly just the env fallback) and the next request retries.
+ */
+export async function ensureProjectJwtKeysLoaded() {
+    if (cached && cached.length > 0)
+        return;
+    if (!fetchInFlight) {
+        fetchInFlight = fetchKeysFromGateway()
+            .then((fetched) => {
+            if (fetched.length > 0)
+                cached = fetched;
+        })
+            .catch(() => {
+            /* keep whatever we have; the next request retries */
+        })
+            .finally(() => {
+            fetchInFlight = null;
+        });
+    }
+    await fetchInFlight;
+}
+/** True when verification has no key at all — the caller must fail CLOSED
+ *  rather than treat the request as anonymous-but-fine. */
+export function projectJwtKeysUnavailable() {
+    return projectJwtVerificationKeys().length === 0;
+}
+async function fetchKeysFromGateway() {
+    const base = process.env.RUN402_API_BASE;
+    const serviceKey = process.env.RUN402_SERVICE_KEY;
+    if (!base || !serviceKey)
+        return [];
+    const url = `${base.replace(/\/+$/, "")}/internal/v1/project-jwt-keys`;
+    const res = await fetch(url, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${serviceKey}` },
+    });
+    if (!res.ok)
+        return [];
+    const body = (await res.json());
+    const out = [];
+    for (const jwk of body.keys ?? []) {
+        // Only the shape the gateway promises to serve. Anything else — notably
+        // anything symmetric — is ignored rather than trusted: this runtime must
+        // never end up holding key material that can sign.
+        if (jwk.kty !== "EC" || jwk.crv !== "P-256")
+            continue;
+        if (typeof jwk.x !== "string" || typeof jwk.y !== "string")
+            continue;
+        try {
+            const publicKey = createPublicKey({
+                key: { kty: "EC", crv: "P-256", x: jwk.x, y: jwk.y },
+                format: "jwk",
+            });
+            out.push({
+                ...(jwk.kid ? { kid: jwk.kid } : {}),
+                key: publicKey.export({ type: "spki", format: "der" }),
+                alg: "ES256",
+                publicKey,
+            });
+        }
+        catch {
+            /* skip a malformed entry rather than failing the whole keyset */
+        }
+    }
+    return out;
+}
+/** Test injection. NEVER call from production code. */
+export function _setProjectJwtKeysForTest(keys) {
+    cached = keys;
+    fetchInFlight = null;
+}
+/**
+ * The header carrying the gateway-minted actor token.
+ *
+ * The runtime FORWARDS this rather than minting its own. Kept here beside the
+ * keyset because the two are halves of one contract: the gateway signs both
+ * the tokens this runtime verifies and the one it forwards, and the runtime
+ * holds nothing that can produce either.
+ */
+export const DATA_PLANE_ACTOR_TOKEN_HEADER = "x-run402-actor-token";
+/** Read a header from either shape, case-insensitively. */
+export function readHeader(headers, name) {
+    if (!headers)
+        return undefined;
+    const h = headers;
+    if (typeof h.get === "function") {
+        return h.get(name) ?? undefined;
+    }
+    const rec = h;
+    const raw = rec[name] ?? rec[name.toLowerCase()] ?? rec[name.toUpperCase()];
+    return Array.isArray(raw) ? raw[0] : raw;
+}
+/**
+ * The gateway-minted actor bearer for this request, if present.
+ *
+ * Returns the `Authorization`-ready value. Absent for anonymous requests, and
+ * absent on older gateways — callers must fall through to their previous
+ * behaviour rather than failing, so a new runtime on an old gateway degrades
+ * instead of breaking.
+ */
+export function forwardedActorAuthorization(headers) {
+    const token = readHeader(headers, DATA_PLANE_ACTOR_TOKEN_HEADER);
+    return token ? `Bearer ${token}` : undefined;
+}
+//# sourceMappingURL=project-jwt-keys.js.map

package/dist/lib/project-jwt-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"project-jwt-keys.js","sourceRoot":"","sources":["../../src/lib/project-jwt-keys.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@run402/functions",
-  "version": "3.12.0",
+  "version": "3.14.0",
   "description": "In-function helper library for Run402 serverless functions - db, adminDb, getUser, email, ai, assets, verifyWebhook. Auto-bundled into deployed functions; also installable for local TypeScript autocomplete.",
   "type": "module",
   "main": "dist/index.js",