@run402/functions 2.4.1 → 2.6.0

package/dist/runtime-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-context.d.ts","sourceRoot":"","sources":["../src/runtime-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD;oCACoC;AACpC,MAAM,WAAW,iBAAiB;IAChC,4DAA4D;IAC5D,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB;yBACqB;IACrB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;qDACiD;IACjD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;yDACqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb;;;uBAGmB;IACnB,OAAO,EAAE;QACP,MAAM,EAAE,MAAM,CAAC;QACf,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;KACxD,CAAC;IACF;;;oBAGgB;IAChB,kBAAkB,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;IACvC;;;8CAG0C;IAC1C,MAAM,EAAE;QAAE,KAAK,EAAE,OAAO,CAAA;KAAE,CAAC;CAC5B;AAED;oEACoE;AACpE,eAAO,MAAM,GAAG,sCAA6C,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,GAAG,SAAS,CAEjE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAC9B,OAAO,EAAE,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,GAAG,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,iBAAiB,EAAE,oBAAoB,GAAG,QAAQ,CAAC,CAAC,EACrI,QAAQ,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,GAC7B,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAOhB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,gCAAiC,SAAQ,KAAK;IACzD,QAAQ,CAAC,IAAI,sCAAsC;IACnD,QAAQ,CAAC,IAAI,gEAAgE;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,kBAAkB,CAAC;gBAEtC,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,kBAAkB;CAc1E;AAED;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAS3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAKvC;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,kBAAkB,EAAE,WAAW,CAAC,MAAM,CAUjD,CAAC;AAEH;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAC/D,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,GAChC,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAe7B"}

package/dist/runtime-context.js

@@ -0,0 +1,170 @@
+/**
+ * SSR request context primitive — capability `functions-sdk-auth-model`.
+ *
+ * The SSR Lambda runtime establishes this context via `als.run(...)`
+ * BEFORE importing or executing the Astro server bundle (or any other
+ * user-supplied code). SDK functions that need request-scoped state
+ * (`db()`, `getUser()`, `cache.*`, `assets.*`, `email.*`, `ai.*`) read
+ * from `getCurrentContext()` rather than requiring explicit context
+ * parameters at the call site.
+ *
+ * The `active` flag exists because Node's AsyncLocalStorage propagates
+ * into timers, microtasks, and unawaited promises created inside
+ * `als.run()`. Without an explicit flag, a `setTimeout(() => db()..., 60_000)`
+ * scheduled inside a handler would, when the timer fires later, still
+ * observe an `als.getStore()` pointing at the (now-completed) request —
+ * leading to stale or incorrect SDK behavior. The SSR runtime sets
+ * `active.value = false` IMMEDIATELY after the response body is fully
+ * materialized; SDK functions check the flag and throw
+ * `R402_SDK_OUTSIDE_REQUEST_CONTEXT` when it's false.
+ *
+ * Likewise `cacheBypassTainted.value` is set to `true` by `getUser()`
+ * and payment-primitive SDK calls during render; the SSR runtime returns
+ * its final value to the gateway in the Lambda response metadata envelope
+ * (NOT via in-process ALS — the gateway runs in a different process).
+ *
+ * @see openspec/changes/astro-ssr-runtime/specs/functions-sdk-auth-model/spec.md
+ * @see openspec/changes/astro-ssr-runtime/specs/routed-http-functions/spec.md
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+/** The shared ALS instance. Modules in @run402/functions read from
+ *  this; the SSR Lambda runtime (in @run402/astro) writes to it. */
+export const als = new AsyncLocalStorage();
+/**
+ * Read the current request context, or `undefined` if no SSR request
+ * is in flight. SDK functions check both this AND `active.value` to
+ * decide whether to honor the call.
+ */
+export function getCurrentContext() {
+    return als.getStore();
+}
+/**
+ * Establish a request context and run a callback inside it. The SSR
+ * Lambda runtime calls this exactly once per invocation, wrapping the
+ * full `App.render(request)` + body-materialization sequence.
+ *
+ * The `active` flag is set to `true` initially; the caller (the SSR
+ * runtime) flips it to `false` after the response body is materialized.
+ * Don't call this from user code — it's the runtime's primitive.
+ */
+export function runWithContext(context, callback) {
+    const full = {
+        ...context,
+        cacheBypassTainted: context.cacheBypassTainted ?? { value: false },
+        active: context.active ?? { value: true },
+    };
+    return als.run(full, callback);
+}
+/**
+ * Throw a structured `R402_SDK_OUTSIDE_REQUEST_CONTEXT` error. Used by
+ * SDK functions when they're invoked with no ALS store OR while the
+ * context has been marked inactive.
+ *
+ * Per the api-error-envelope spec, the thrown error carries:
+ *   - `code: 'R402_SDK_OUTSIDE_REQUEST_CONTEXT'`
+ *   - `message`: names the SDK function and the cause
+ *   - `suggestedFix`: recommends moving the call inside a handler OR
+ *     not scheduling background work that outlives the response
+ *   - `docs`: `https://docs.run402.com/sdk/errors#outside-request-context`
+ */
+export class Run402OutsideRequestContextError extends Error {
+    code = "R402_SDK_OUTSIDE_REQUEST_CONTEXT";
+    docs = "https://docs.run402.com/sdk/errors#outside-request-context";
+    suggestedFix;
+    sdkFunction;
+    cause;
+    constructor(sdkFunction, cause) {
+        const causeMsg = cause === "no_context"
+            ? "no active request context (called from module scope or outside a handler)"
+            : "request context marked inactive (called from a timer or unawaited promise after response completion)";
+        super(`${sdkFunction}: ${causeMsg}`);
+        this.name = "Run402OutsideRequestContextError";
+        this.sdkFunction = sdkFunction;
+        this.cause = cause;
+        this.suggestedFix =
+            cause === "no_context"
+                ? `Move the ${sdkFunction} call inside an HTTP request handler or Astro frontmatter. SDK functions cannot resolve project context outside an active request.`
+                : `The request that called ${sdkFunction} has already returned. Don't schedule SDK calls in setTimeout / setInterval / unawaited promises that outlive the handler.`;
+    }
+}
+/**
+ * Assert that a request context is active. Returns the context on
+ * success; throws `Run402OutsideRequestContextError` on failure.
+ *
+ * SDK functions call this as the first line, e.g.:
+ *
+ *   const ctx = requireActiveContext("db");
+ *   // use ctx.projectId, ctx.request.headers, etc.
+ */
+export function requireActiveContext(sdkFunction) {
+    const ctx = als.getStore();
+    if (ctx === undefined) {
+        throw new Run402OutsideRequestContextError(sdkFunction, "no_context");
+    }
+    if (!ctx.active.value) {
+        throw new Run402OutsideRequestContextError(sdkFunction, "context_inactive");
+    }
+    return ctx;
+}
+/**
+ * Flip the cache-bypass taint flag on the current context. Called by
+ * `getUser()` and payment-primitive SDK calls to signal that the
+ * rendered response depends on request-scoped auth state and therefore
+ * MUST NOT be cached publicly.
+ *
+ * No-op if there is no active context (rather than throwing — the taint
+ * is moot when there's no cache layer to inform).
+ */
+export function taintCacheBypass() {
+    const ctx = als.getStore();
+    if (ctx !== undefined) {
+        ctx.cacheBypassTainted.value = true;
+    }
+}
+/**
+ * Canonical registry of SDK functions that are "payment primitives" for
+ * cache-taint purposes. Calling any of these inside an active request
+ * context MUST flip `cacheBypassTainted.value = true`. The set is
+ * defined here so the spec, runtime, and docs share one source of truth.
+ *
+ * To add a new payment primitive: append to this set AND ensure the
+ * function's implementation calls `taintCacheBypass()` on every entry.
+ *
+ * @see openspec/changes/astro-ssr-runtime/specs/functions-sdk-auth-model/spec.md
+ */
+export const PAYMENT_PRIMITIVES = new Set([
+// None implemented yet — the registry exists so the contract is
+// explicit and discoverable. Payment-primitive SDK functions added
+// in future changes (per Run402 x402/MPP roadmap) will register here
+// as they land.
+// Example future entries (commented to keep the set actually empty
+// until the helpers ship):
+//   "payments.require",
+//   "payments.gate",
+//   "payments.fulfill",
+]);
+/**
+ * Helper for payment-primitive implementations. Wraps the body in a
+ * taint-on-entry call so the registry contract is enforced at the
+ * SDK layer rather than relying on each implementation to remember.
+ *
+ * Example:
+ *   export const requirePayment = withPaymentTaint("payments.require", async (opts) => {
+ *     // ... actual implementation
+ *   });
+ */
+export function withPaymentTaint(name, impl) {
+    if (!PAYMENT_PRIMITIVES.has(name)) {
+        // Doesn't throw — adding a new primitive is a code change and the
+        // dev sees this on first invocation. Throwing would block legitimate
+        // experimentation. But emit a warning so the registry stays correct.
+        // eslint-disable-next-line no-console
+        console.warn(`[run402] withPaymentTaint("${name}") called but "${name}" is not in PAYMENT_PRIMITIVES. ` +
+            `Add it to packages/functions/src/runtime-context.ts to keep the cache-taint registry consistent.`);
+    }
+    return (...args) => {
+        taintCacheBypass();
+        return impl(...args);
+    };
+}
+//# sourceMappingURL=runtime-context.js.map

package/dist/runtime-context.js.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@run402/functions",
-  "version": "2.4.1",
+  "version": "2.6.0",
   "description": "In-function helper library for Run402 serverless functions — db, adminDb, getUser, email, ai, assets. Auto-bundled into deployed functions; also installable for local TypeScript autocomplete.",
   "type": "module",
   "main": "dist/index.js",
@@ -23,12 +23,7 @@
   "engines": {
     "node": ">=18"
   },
-  "dependencies": {
-    "jsonwebtoken": "^9.0.2"
-  },
-  "devDependencies": {
-    "@types/jsonwebtoken": "^9.0.9"
-  },
+  "devDependencies": {},
   "repository": {
     "type": "git",
     "url": "git+https://github.com/kychee-com/run402.git",