@run402/functions 2.4.1 → 2.6.0

package/README.md

@@ -98,6 +98,113 @@ if (!user) return new Response("unauthorized", { status: 401 });
 
 The function's own `RUN402_PROJECT_ID` is used to scope the verification.
 
+**Note on `user.role`:** this is the JWT system role (`anon`, `authenticated`, `project_admin`, …) — the same value PostgREST uses to evaluate RLS. It is **not** your application role from a declarative `requireRole` gate (admin/moderator/etc.). For the gate-resolved application role, use `getRole(req)` (see "Function-level auth gates" below). Don't write `getUser(req).role === "admin"` thinking you're checking the gate role — `"admin"` is not a JWT role.
+
+## Function-level auth gates
+
+A function can declare auth requirements directly on its `FunctionSpec`. When you set `requireAuth: true` or `requireRole: { ... }`, the gateway enforces them **before** invoking your function — unauthorized callers get `401` / `403` without your code running, and the gateway injects the resolved identity into request headers your function can trust.
+
+This lets you delete the hand-rolled "fetch JWT, query members table, check role, return 403" boilerplate from every privileged function. Declare the gate in your `FunctionSpec`; read the resolved identity with `getUserId(req)` and `getRole(req)`.
+
+### Declaring a gate (deploy spec)
+
+```ts
+import { run402 } from "@run402/sdk/node";
+
+const r = run402();
+await r.project(projectId).apply({
+  functions: {
+    patch: {
+      set: {
+        // 1. Authentication only — any valid JWT for this project passes.
+        "list-my-items": {
+          source: { sha256, size },
+          requireAuth: true,
+        },
+
+        // 2. Authentication + role check against your members table.
+        "delete-content": {
+          source: { sha256, size },
+          requireRole: {
+            table: "members",         // project-schema table
+            idColumn: "user_id",      // FK to the user.id from the JWT
+            roleColumn: "role",       // column holding the role string
+            allowed: ["admin"],       // case-sensitive byte-equality allowlist
+            cacheTtl: 60,             // optional, seconds, default 60, max 600, 0 disables
+          },
+        },
+
+        // 3. Multi-role — any role in `allowed` passes the gate.
+        "moderate-content": {
+          source: { sha256, size },
+          requireRole: {
+            table: "members",
+            idColumn: "user_id",
+            roleColumn: "role",
+            allowed: ["admin", "moderator"],
+          },
+        },
+      },
+    },
+  },
+});
+```
+
+`requireAuth` and `requireRole` are independent. `requireRole` on its own implies authentication (no valid JWT → 401), then runs the role lookup. `requireAuth: true` alone does a session check with no DB lookup. Set neither to opt out of platform auth (your function owns the check, as today).
+
+**Single role-table per release:** all `requireRole` blocks in a single release must share the same `(table, idColumn, roleColumn)` triple. Different `allowed` sets are fine; different tables are not. The gateway rejects conflicting triples at plan time with `INVALID_SPEC`.
+
+### Reading the gate result inside your function
+
+```ts
+import { getUserId, getRole } from "@run402/functions";
+
+export default async (req: Request): Promise<Response> => {
+  const userId = getUserId(req);  // string | null
+  const role = getRole(req);      // string | null
+
+  // For a gated function reached through the gateway, both are guaranteed:
+  //   - getUserId(req) is non-null when requireAuth OR requireRole is on.
+  //   - getRole(req) is non-null when requireRole is on (and is one of `allowed`).
+  // The null case covers local invokes / direct Lambda tests / ungated functions.
+
+  if (role === "admin") {
+    // Privileged path — the gate already verified.
+  } else {
+    // role === "moderator" (the only other value `allowed` permits).
+  }
+
+  return Response.json({ ok: true, actor: userId, role });
+};
+```
+
+The two headers (`x-run402-user-id`, `x-run402-user-role`) are injected by the gateway after the gate passes, and inbound `x-run402-*` headers from the browser are stripped before injection — so the values are trustworthy without any further verification.
+
+### Direct vs routed invocation
+
+The gate applies to **both** routed (browser via `/your/route`) and direct (`POST /functions/v1/:name` with an API key plus a user JWT) invocation. Direct invocation still requires the project API key at the edge; the gate runs after API-key authentication, against the user JWT.
+
+### Deploy-time validation
+
+If a `requireRole` block references a table or column that doesn't exist in the project schema at activation time, the deploy fails with `DEPLOY_INVALID_ROLE_GATE` (HTTP 422) **before** flipping the live release. Schema-qualified identifiers (`public.members`), empty `allowed`, and out-of-range `cacheTtl` are rejected earlier at plan time with `INVALID_SPEC` (HTTP 400).
+
+### Caching and staleness
+
+Role lookups are cached per `(projectId, userId)` for `cacheTtl` seconds (default 60, max 600). **A demoted user keeps the cached role until the TTL expires** — for high-stakes operations where instant revocation matters, set `cacheTtl: 0` to issue a fresh lookup on every request. The cache is bypassed when no `requireRole` gate runs.
+
+### Relationship to `getUser`
+
+`getUser(req)` decodes the JWT and gives you `{ id, role, email }` where `role` is the JWT system role. The gate-injected headers give you the gate-resolved identity:
+
+| Helper | Source | Role meaning |
+|---|---|---|
+| `getUser(req).id` | JWT `sub` (decoded in-function) | — |
+| `getUser(req).role` | JWT `role` claim | System role (`anon`, `authenticated`, `project_admin`) |
+| `getUserId(req)` | `x-run402-user-id` header (injected by gateway) | — |
+| `getRole(req)` | `x-run402-user-role` header (injected by gateway) | Application role from your `members` table |
+
+For a gated function reached through the gateway, `getUserId(req)` and `getUser(req).id` will agree. The gate-side helpers skip the JWT decode (the gateway already did it), so they're slightly cheaper and stringly-typed against the trusted headers; use them when the gate guarantees the identity.
+
 ## `email.send(...)` — send mail from the project's mailbox
 
 Auto-discovers the project's mailbox on first call (the project must already have one — create it once with `run402 email create <slug>` or the `create_mailbox` MCP tool). After that the mailbox id is cached for the function's lifetime.

package/dist/auth.d.ts

@@ -6,6 +6,52 @@ export interface User {
 /**
  * Verify the caller's JWT and return user identity.
  * Returns { id, role, email } or null if unauthenticated/invalid.
+ *
+ * NOTE: `role` here is the JWT claim (`anon`, `authenticated`,
+ * `project_admin`, …) — the PostgREST/RLS system role, NOT the
+ * application role from a declarative `requireRole` gate. For the
+ * gate-resolved application role, use {@link getRole}.
  */
-export declare function getUser(req: Request): User | null;
+export declare function getUser(req?: Request): User | null;
+/**
+ * Read the gate-resolved user id from the request.
+ *
+ * Returns the value of the `x-run402-user-id` request header, which the
+ * Run402 gateway injects when a function-level `requireAuth` or
+ * `requireRole` gate evaluates successfully on this dispatch. Inbound
+ * `x-run402-*` headers from the browser are stripped by the gateway
+ * before injection, so the value is trustworthy.
+ *
+ * Returns `null` when the function has no gate declared, or when the
+ * function is invoked outside the gateway (local test harness, direct
+ * Lambda invoke). For gated functions reached through the gateway, the
+ * value is non-null by construction.
+ *
+ * This is the gate-side companion to {@link getUser}, which decodes
+ * the JWT directly. The two layers are independent: a function with
+ * only `requireRole` runs the role lookup against the project's
+ * `members` table via gateway-side RLS-bypass; user code does not
+ * need to re-decode the JWT.
+ */
+export declare function getUserId(req?: Request): string | null;
+/**
+ * Read the gate-resolved application role from the request.
+ *
+ * Returns the value of the `x-run402-user-role` request header, which
+ * the Run402 gateway injects when a function-level `requireRole` gate
+ * evaluates successfully on this dispatch. The value is the role string
+ * from the project-schema `members.role` (or whatever
+ * `(table, idColumn, roleColumn)` triple the gate declared), already
+ * confirmed to be in `requireRole.allowed`. Inbound `x-run402-*`
+ * headers are stripped, so the value is trustworthy.
+ *
+ * Returns `null` when no `requireRole` gate ran on this dispatch
+ * (function has only `requireAuth`, no gate at all, or is invoked
+ * outside the gateway).
+ *
+ * This is the application role, NOT the JWT role from
+ * {@link getUser}. The two are independent — see the JSDoc on
+ * `getUser` for the distinction.
+ */
+export declare function getRole(req?: Request): string | null;
 //# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;GAGG;AACH,wBAAgB,OAAO,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAmBjD"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;GAQG;AACH,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,IAAI,CAsClD;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOtD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,OAAO,CAAC,GAAG,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAOpD"}

package/dist/auth.js

@@ -1,13 +1,40 @@
-import jwt from "jsonwebtoken";
+import jwt from "./lib/jwt.js";
 import { config } from "./config.js";
+import { getCurrentContext, taintCacheBypass } from "./runtime-context.js";
 /**
  * Verify the caller's JWT and return user identity.
  * Returns { id, role, email } or null if unauthenticated/invalid.
+ *
+ * NOTE: `role` here is the JWT claim (`anon`, `authenticated`,
+ * `project_admin`, …) — the PostgREST/RLS system role, NOT the
+ * application role from a declarative `requireRole` gate. For the
+ * gate-resolved application role, use {@link getRole}.
  */
 export function getUser(req) {
-    const authHeader = typeof req.headers.get === "function"
-        ? req.headers.get("authorization")
-        : req.headers?.authorization;
+    // Capability `astro-ssr-runtime` (v1.52). Taint the cache-bypass flag
+    // on the active request context, regardless of whether `getUser`
+    // resolves to a user or null — the response now depends on per-request
+    // auth state and MUST NOT be cached publicly.
+    taintCacheBypass();
+    // If no `req` was passed, read auth from the ALS context (the SSR
+    // Lambda runtime's `runWithContext` populates `request.headers`).
+    // This is what makes `await getUser()` work naturally inside Astro
+    // `[slug].astro` frontmatter without any explicit plumbing.
+    let authHeader;
+    if (req !== undefined) {
+        authHeader =
+            typeof req.headers.get === "function"
+                ? req.headers.get("authorization")
+                : req.headers?.authorization;
+    }
+    else {
+        const ctx = getCurrentContext();
+        if (ctx === undefined)
+            return null;
+        const h = ctx.request.headers;
+        const raw = h["authorization"] ?? h["Authorization"];
+        authHeader = Array.isArray(raw) ? raw[0] : raw;
+    }
     if (!authHeader || !authHeader.startsWith("Bearer "))
         return null;
     const token = authHeader.slice(7);
@@ -21,4 +48,65 @@ export function getUser(req) {
         return null;
     }
 }
+/**
+ * Read the gate-resolved user id from the request.
+ *
+ * Returns the value of the `x-run402-user-id` request header, which the
+ * Run402 gateway injects when a function-level `requireAuth` or
+ * `requireRole` gate evaluates successfully on this dispatch. Inbound
+ * `x-run402-*` headers from the browser are stripped by the gateway
+ * before injection, so the value is trustworthy.
+ *
+ * Returns `null` when the function has no gate declared, or when the
+ * function is invoked outside the gateway (local test harness, direct
+ * Lambda invoke). For gated functions reached through the gateway, the
+ * value is non-null by construction.
+ *
+ * This is the gate-side companion to {@link getUser}, which decodes
+ * the JWT directly. The two layers are independent: a function with
+ * only `requireRole` runs the role lookup against the project's
+ * `members` table via gateway-side RLS-bypass; user code does not
+ * need to re-decode the JWT.
+ */
+export function getUserId(req) {
+    if (req !== undefined)
+        return req.headers.get("x-run402-user-id");
+    const ctx = getCurrentContext();
+    if (ctx === undefined)
+        return null;
+    const raw = ctx.request.headers["x-run402-user-id"];
+    if (Array.isArray(raw))
+        return raw[0] ?? null;
+    return raw ?? null;
+}
+/**
+ * Read the gate-resolved application role from the request.
+ *
+ * Returns the value of the `x-run402-user-role` request header, which
+ * the Run402 gateway injects when a function-level `requireRole` gate
+ * evaluates successfully on this dispatch. The value is the role string
+ * from the project-schema `members.role` (or whatever
+ * `(table, idColumn, roleColumn)` triple the gate declared), already
+ * confirmed to be in `requireRole.allowed`. Inbound `x-run402-*`
+ * headers are stripped, so the value is trustworthy.
+ *
+ * Returns `null` when no `requireRole` gate ran on this dispatch
+ * (function has only `requireAuth`, no gate at all, or is invoked
+ * outside the gateway).
+ *
+ * This is the application role, NOT the JWT role from
+ * {@link getUser}. The two are independent — see the JSDoc on
+ * `getUser` for the distinction.
+ */
+export function getRole(req) {
+    if (req !== undefined)
+        return req.headers.get("x-run402-user-role");
+    const ctx = getCurrentContext();
+    if (ctx === undefined)
+        return null;
+    const raw = ctx.request.headers["x-run402-user-role"];
+    if (Array.isArray(raw))
+        return raw[0] ?? null;
+    return raw ?? null;
+}
 //# sourceMappingURL=auth.js.map

package/dist/auth.js.map

@@ -1 +1 @@
-{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,cAAc,CAAC;AAC/B,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAQrC;;;GAGG;AACH,MAAM,UAAU,OAAO,CAAC,GAAY;IAClC,MAAM,UAAU,GACd,OAAQ,GAAG,CAAC,OAA6C,CAAC,GAAG,KAAK,UAAU;QAC1E,CAAC,CAAE,GAAG,CAAC,OAAmB,CAAC,GAAG,CAAC,eAAe,CAAC;QAC/C,CAAC,CAAE,GAAG,CAAC,OAAyD,EAAE,aAAa,CAAC;IACpF,IAAI,CAAC,UAAU,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IAClE,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAClC,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,CAKlD,CAAC;QACF,IAAI,OAAO,CAAC,UAAU,KAAK,MAAM,CAAC,UAAU;YAAE,OAAO,IAAI,CAAC;QAC1D,OAAO,EAAE,EAAE,EAAE,OAAO,CAAC,GAAG,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC;IACvE,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"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"}

package/dist/cache.d.ts

@@ -0,0 +1,122 @@
+/**
+ * SSR cache invalidation SDK — capability `ssr-isr-cache`.
+ *
+ * Server-side (function-context) only. Reads the current request's
+ * project_id and host from `getCurrentContext()` (AsyncLocalStorage) to
+ * scope invalidations safely.
+ *
+ * Four operations:
+ *
+ *   - `cache.invalidate(urlOrPath)` — delete cache rows for a specific
+ *     path (or absolute URL). Returns `{ deleted, generation, host, path }`.
+ *   - `cache.invalidatePrefix({ host, prefix })` — delete all rows
+ *     under a path prefix on the given host.
+ *   - `cache.invalidateAll({ host })` — delete all rows on the given
+ *     host. Atomic with a generation bump.
+ *   - `cache.invalidateMany(urls)` — bulk invalidate in one round-trip.
+ *
+ * Host authorization: absolute-URL forms (or explicit `host` in the
+ * options bag) MUST be hosts owned by the caller's authenticated
+ * project. Cross-project hosts throw `R402_CACHE_INVALIDATION_HOST_FORBIDDEN`.
+ *
+ * Path-string form requires an active request context (the SDK reads
+ * the current host from ALS); calling it outside a handler throws
+ * `R402_CACHE_INVALIDATION_HOST_REQUIRED`.
+ *
+ * Tag-based invalidation is NOT in v1; future v1.5 work.
+ *
+ * @see openspec/changes/astro-ssr-runtime/specs/ssr-isr-cache/spec.md
+ */
+/** Result envelope returned by every invalidation API. */
+export interface CacheInvalidateResult {
+    /** Number of `internal.ssr_cache` rows DELETEd by this call. */
+    deleted: number;
+    /** Post-increment generation. Each invalidate bumps the per-(project,
+     *  host) generation counter, which gates in-flight MISS writes from
+     *  populating stale content after the invalidate. */
+    generation: bigint;
+    /** The host the invalidation targeted. */
+    host: string;
+    /** The pathname targeted (single-URL form only); undefined for
+     *  prefix/all/many. */
+    path?: string;
+}
+export interface InvalidatePrefixOptions {
+    host: string;
+    prefix: string;
+}
+export interface InvalidateAllOptions {
+    host: string;
+}
+/**
+ * Structured error thrown when path-string form is called outside an
+ * active request context. The caller has no host to scope against.
+ * Use the absolute-URL form instead OR move the call into a handler.
+ */
+export declare class CacheInvalidationHostRequiredError extends Error {
+    readonly code = "R402_CACHE_INVALIDATION_HOST_REQUIRED";
+    readonly docs = "https://docs.run402.com/cache/errors#invalidation-host-required";
+    readonly suggestedFix = "Pass an absolute URL (e.g., `new URL('https://eagles.kychon.com/the-guys')`) OR move the call into a request handler so the SDK can resolve the current host.";
+    constructor();
+}
+/**
+ * Structured error thrown when an invalidation targets a host that is
+ * not owned by the caller's authenticated project. Prevents project A
+ * from invalidating project B's cache.
+ */
+export declare class CacheInvalidationHostForbiddenError extends Error {
+    readonly code = "R402_CACHE_INVALIDATION_HOST_FORBIDDEN";
+    readonly docs = "https://docs.run402.com/cache/errors#invalidation-host-forbidden";
+    readonly host: string;
+    readonly suggestedFix: string;
+    constructor(host: string);
+}
+/**
+ * Invalidate a single cached SSR response.
+ *
+ * Accepts either:
+ *   - a path string (e.g., `'/the-guys'`) — the SDK reads the current
+ *     host from the active request context (throws
+ *     `CacheInvalidationHostRequiredError` if no context)
+ *   - an absolute URL (e.g., `new URL('https://eagles.kychon.com/the-guys')`)
+ *     — multi-host admin scenarios (host MUST be owned by caller's
+ *     project; throws `CacheInvalidationHostForbiddenError` otherwise)
+ *
+ * Deletes GET and HEAD rows for ALL locales and ALL release ids matching
+ * the exact canonical pathname + normalized search on the target host.
+ *
+ * The DELETE and the per-(project, host) generation increment happen in
+ * the same transaction; the post-increment generation is returned.
+ */
+export declare function invalidate(urlOrPath: string | URL): Promise<CacheInvalidateResult>;
+/**
+ * Invalidate all cache rows under a path prefix on the given host.
+ */
+export declare function invalidatePrefix(opts: InvalidatePrefixOptions): Promise<CacheInvalidateResult>;
+/**
+ * Invalidate all cache rows for the given host (entire-host purge).
+ * Useful for catastrophic content changes (nav restructure, layout
+ * update, etc.) where targeted invalidation would be impractical.
+ */
+export declare function invalidateAll(opts: InvalidateAllOptions): Promise<CacheInvalidateResult>;
+/**
+ * Bulk-invalidate many URLs in a single round-trip. Path-string forms
+ * use the current request context's host; absolute URLs are scoped
+ * individually.
+ *
+ * Returns a SUMMARY envelope with the total deleted count. Per-URL
+ * results are also available on the optional `results` field of the
+ * returned object (not in the result type return for the common case;
+ * use the internal endpoint if you need per-URL precision).
+ */
+export declare function invalidateMany(urls: Array<string | URL>): Promise<CacheInvalidateResult>;
+/** The full cache namespace exported via the `cache` named export from
+ *  `@run402/functions`. */
+export declare const cache: {
+    readonly invalidate: typeof invalidate;
+    readonly invalidatePrefix: typeof invalidatePrefix;
+    readonly invalidateAll: typeof invalidateAll;
+    readonly invalidateMany: typeof invalidateMany;
+};
+export type Cache = typeof cache;
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAKH,0DAA0D;AAC1D,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAC;IAChB;;yDAEqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb;2BACuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,qBAAa,kCAAmC,SAAQ,KAAK;IAC3D,QAAQ,CAAC,IAAI,2CAA2C;IACxD,QAAQ,CAAC,IAAI,qEAAqE;IAClF,QAAQ,CAAC,YAAY,mKAC6I;;CASnK;AAED;;;;GAIG;AACH,qBAAa,mCAAoC,SAAQ,KAAK;IAC5D,QAAQ,CAAC,IAAI,4CAA4C;IACzD,QAAQ,CAAC,IAAI,sEAAsE;IACnF,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;gBAElB,IAAI,EAAE,MAAM;CAMzB;AA4DD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,GAAG,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAsCxF;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,IAAI,EAAE,uBAAuB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAepG;AAED;;;;GAIG;AACH,wBAAsB,aAAa,CAAC,IAAI,EAAE,oBAAoB,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAW9F;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAAC,IAAI,EAAE,KAAK,CAAC,MAAM,GAAG,GAAG,CAAC,GAAG,OAAO,CAAC,qBAAqB,CAAC,CA0B9F;AAED;2BAC2B;AAC3B,eAAO,MAAM,KAAK;;;;;CAKR,CAAC;AAEX,MAAM,MAAM,KAAK,GAAG,OAAO,KAAK,CAAC"}

package/dist/cache.js

@@ -0,0 +1,243 @@
+/**
+ * SSR cache invalidation SDK — capability `ssr-isr-cache`.
+ *
+ * Server-side (function-context) only. Reads the current request's
+ * project_id and host from `getCurrentContext()` (AsyncLocalStorage) to
+ * scope invalidations safely.
+ *
+ * Four operations:
+ *
+ *   - `cache.invalidate(urlOrPath)` — delete cache rows for a specific
+ *     path (or absolute URL). Returns `{ deleted, generation, host, path }`.
+ *   - `cache.invalidatePrefix({ host, prefix })` — delete all rows
+ *     under a path prefix on the given host.
+ *   - `cache.invalidateAll({ host })` — delete all rows on the given
+ *     host. Atomic with a generation bump.
+ *   - `cache.invalidateMany(urls)` — bulk invalidate in one round-trip.
+ *
+ * Host authorization: absolute-URL forms (or explicit `host` in the
+ * options bag) MUST be hosts owned by the caller's authenticated
+ * project. Cross-project hosts throw `R402_CACHE_INVALIDATION_HOST_FORBIDDEN`.
+ *
+ * Path-string form requires an active request context (the SDK reads
+ * the current host from ALS); calling it outside a handler throws
+ * `R402_CACHE_INVALIDATION_HOST_REQUIRED`.
+ *
+ * Tag-based invalidation is NOT in v1; future v1.5 work.
+ *
+ * @see openspec/changes/astro-ssr-runtime/specs/ssr-isr-cache/spec.md
+ */
+import { config } from "./config.js";
+import { getCurrentContext } from "./runtime-context.js";
+/**
+ * Structured error thrown when path-string form is called outside an
+ * active request context. The caller has no host to scope against.
+ * Use the absolute-URL form instead OR move the call into a handler.
+ */
+export class CacheInvalidationHostRequiredError extends Error {
+    code = "R402_CACHE_INVALIDATION_HOST_REQUIRED";
+    docs = "https://docs.run402.com/cache/errors#invalidation-host-required";
+    suggestedFix = "Pass an absolute URL (e.g., `new URL('https://eagles.kychon.com/the-guys')`) OR move the call into a request handler so the SDK can resolve the current host.";
+    constructor() {
+        super("cache.invalidate(path) called outside a request context. " +
+            "Path-string form needs the current host from request scope.");
+        this.name = "CacheInvalidationHostRequiredError";
+    }
+}
+/**
+ * Structured error thrown when an invalidation targets a host that is
+ * not owned by the caller's authenticated project. Prevents project A
+ * from invalidating project B's cache.
+ */
+export class CacheInvalidationHostForbiddenError extends Error {
+    code = "R402_CACHE_INVALIDATION_HOST_FORBIDDEN";
+    docs = "https://docs.run402.com/cache/errors#invalidation-host-forbidden";
+    host;
+    suggestedFix;
+    constructor(host) {
+        super(`host ${host} is not owned by the current project`);
+        this.name = "CacheInvalidationHostForbiddenError";
+        this.host = host;
+        this.suggestedFix = `Use a host attached to your project. List your project's hosts with \`r.domains.list()\` or check Run402 dashboard. The cache layer rejects cross-project invalidations to preserve tenant isolation.`;
+    }
+}
+/**
+ * Internal: call the gateway's cache invalidation endpoint with the
+ * resolved scope. The gateway enforces project ownership of the host
+ * server-side; this function relies on that enforcement but ALSO
+ * validates the response shape.
+ */
+async function callCacheInvalidate(body) {
+    const url = `${config.API_BASE}/cache/v1/invalidate`;
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            "content-type": "application/json",
+            // The gateway resolves the caller's project from the service key.
+            // Cache invalidation is server-side only; the SDK is bundled into
+            // user functions and runs with RUN402_SERVICE_KEY in scope.
+            Authorization: "Bearer " + config.SERVICE_KEY,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 403) {
+        const errBody = (await response.json().catch(() => ({})));
+        const host = typeof errBody.host === "string" ? errBody.host : (body.host ?? "");
+        throw new CacheInvalidationHostForbiddenError(host);
+    }
+    if (!response.ok) {
+        const errBody = await response.text().catch(() => "");
+        throw new Error(`cache.invalidate(${body.kind}) failed: HTTP ${response.status} ${errBody.slice(0, 200)}`);
+    }
+    const json = (await response.json());
+    return {
+        deleted: json.deleted,
+        generation: BigInt(json.generation),
+        host: json.host,
+        path: json.path,
+        results: json.results?.map((r) => ({
+            ...r,
+            generation: BigInt(r.generation),
+        })),
+    };
+}
+/**
+ * Invalidate a single cached SSR response.
+ *
+ * Accepts either:
+ *   - a path string (e.g., `'/the-guys'`) — the SDK reads the current
+ *     host from the active request context (throws
+ *     `CacheInvalidationHostRequiredError` if no context)
+ *   - an absolute URL (e.g., `new URL('https://eagles.kychon.com/the-guys')`)
+ *     — multi-host admin scenarios (host MUST be owned by caller's
+ *     project; throws `CacheInvalidationHostForbiddenError` otherwise)
+ *
+ * Deletes GET and HEAD rows for ALL locales and ALL release ids matching
+ * the exact canonical pathname + normalized search on the target host.
+ *
+ * The DELETE and the per-(project, host) generation increment happen in
+ * the same transaction; the post-increment generation is returned.
+ */
+export async function invalidate(urlOrPath) {
+    let host;
+    let path;
+    if (urlOrPath instanceof URL) {
+        host = urlOrPath.host.toLowerCase();
+        path = urlOrPath.pathname + urlOrPath.search;
+    }
+    else if (typeof urlOrPath === "string" && urlOrPath.startsWith("http://")) {
+        // Allow http:// only for local-dev parity, but the gateway will
+        // typically reject it.
+        const u = new URL(urlOrPath);
+        host = u.host.toLowerCase();
+        path = u.pathname + u.search;
+    }
+    else if (typeof urlOrPath === "string" && urlOrPath.startsWith("https://")) {
+        const u = new URL(urlOrPath);
+        host = u.host.toLowerCase();
+        path = u.pathname + u.search;
+    }
+    else if (typeof urlOrPath === "string" && urlOrPath.startsWith("/")) {
+        // Path-string form: requires active request context to resolve host.
+        const ctx = getCurrentContext();
+        if (ctx === undefined || !ctx.active.value) {
+            throw new CacheInvalidationHostRequiredError();
+        }
+        host = ctx.host.toLowerCase();
+        path = urlOrPath;
+    }
+    else {
+        throw new Error(`cache.invalidate: argument must be a URL, an "https://" URL string, or a path starting with "/". Got: ${typeof urlOrPath === "string" ? `"${urlOrPath}"` : typeof urlOrPath}`);
+    }
+    const result = await callCacheInvalidate({ kind: "exact", host, path });
+    return {
+        deleted: result.deleted,
+        generation: result.generation,
+        host: result.host,
+        path: result.path ?? path,
+    };
+}
+/**
+ * Invalidate all cache rows under a path prefix on the given host.
+ */
+export async function invalidatePrefix(opts) {
+    if (!opts.host)
+        throw new Error("cache.invalidatePrefix: host is required");
+    if (!opts.prefix || !opts.prefix.startsWith("/")) {
+        throw new Error("cache.invalidatePrefix: prefix must start with '/'");
+    }
+    const result = await callCacheInvalidate({
+        kind: "prefix",
+        host: opts.host.toLowerCase(),
+        prefix: opts.prefix,
+    });
+    return {
+        deleted: result.deleted,
+        generation: result.generation,
+        host: result.host,
+    };
+}
+/**
+ * Invalidate all cache rows for the given host (entire-host purge).
+ * Useful for catastrophic content changes (nav restructure, layout
+ * update, etc.) where targeted invalidation would be impractical.
+ */
+export async function invalidateAll(opts) {
+    if (!opts.host)
+        throw new Error("cache.invalidateAll: host is required");
+    const result = await callCacheInvalidate({
+        kind: "all",
+        host: opts.host.toLowerCase(),
+    });
+    return {
+        deleted: result.deleted,
+        generation: result.generation,
+        host: result.host,
+    };
+}
+/**
+ * Bulk-invalidate many URLs in a single round-trip. Path-string forms
+ * use the current request context's host; absolute URLs are scoped
+ * individually.
+ *
+ * Returns a SUMMARY envelope with the total deleted count. Per-URL
+ * results are also available on the optional `results` field of the
+ * returned object (not in the result type return for the common case;
+ * use the internal endpoint if you need per-URL precision).
+ */
+export async function invalidateMany(urls) {
+    if (!Array.isArray(urls) || urls.length === 0) {
+        return { deleted: 0, generation: 0n, host: "" };
+    }
+    // Resolve each URL to its absolute form, using the current context
+    // for path-only entries.
+    const ctx = getCurrentContext();
+    const resolved = urls.map((u) => {
+        if (u instanceof URL)
+            return u.toString();
+        if (u.startsWith("https://") || u.startsWith("http://"))
+            return u;
+        if (u.startsWith("/")) {
+            if (ctx === undefined || !ctx.active.value) {
+                throw new CacheInvalidationHostRequiredError();
+            }
+            return `https://${ctx.host}${u}`;
+        }
+        throw new Error(`cache.invalidateMany: invalid entry "${u}"`);
+    });
+    const result = await callCacheInvalidate({ kind: "many", urls: resolved });
+    return {
+        deleted: result.deleted,
+        generation: result.generation,
+        host: result.host ?? "",
+    };
+}
+/** The full cache namespace exported via the `cache` named export from
+ *  `@run402/functions`. */
+export const cache = {
+    invalidate,
+    invalidatePrefix,
+    invalidateAll,
+    invalidateMany,
+};
+//# sourceMappingURL=cache.js.map