@pramen/server 0.0.13 → 0.0.15

package/src/worker.ts

@@ -4,21 +4,23 @@
 // endpoints (/tenants, /admin/recover, /admin/schema). createPramen() pairs the
 // returned fetch with the matching DO class; a consumer just re-exports both.
 
-import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity, type VerifyStrategy } from "./auth";
+import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity, type VerifyOptions, type VerifyStrategy } from "./auth";
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { createMail } from "./runtime/mail";
+import { createQueue, type QueueProducerBinding } from "./runtime/queue";
+import { dispatchQueueBatch, type QueueBatch, type QueueContext } from "./runtime/queue-consumer";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
-import { D1Driver, type Driver } from "./runtime/driver";
+import { D1Driver, type D1SessionStart, type Driver } from "./runtime/driver";
 import { toResponse } from "./runtime/errors";
 import { Kv } from "./runtime/kv";
 import { listDOs, partitionDoName } from "./runtime/registry";
-import { createFiles, handleFileRequest, R2Adapter } from "./runtime/storage";
+import { createFiles, handleFileRequest, handleMediaRequest, R2Adapter } from "./runtime/storage";
 import type { Identity } from "./sdk/acl";
 import type { HandlerContext } from "./sdk/handlers";
-import { DEFAULT_PARTITION } from "./sdk/schema";
+import { DEFAULT_PARTITION, partitionsOf } from "./sdk/schema";
 import type { PramenApp } from "./pramen";
 
 export interface Env {
@@ -31,6 +33,16 @@ export interface Env {
   /** Optional: a JWKS endpoint. When set, tokens are verified as RS256 against the
    * fetched public keys (HmacStrategy/AUTH_SECRET is bypassed). */
   JWKS_URL?: string;
+  /** "true" to REJECT any bearer token with no numeric `exp` claim. Off by default
+   * (a token without exp is accepted) so existing issuers keep working; turn it on to
+   * refuse non-expiring tokens. Applies to both the HS256 and JWKS strategies. */
+  AUTH_REQUIRE_EXP?: string;
+  /** Optional required audience. When set, a token's `aud` (string or array) must
+   * contain this value or the token is rejected. Unset ⇒ `aud` is not checked. */
+  AUTH_AUDIENCE?: string;
+  /** Optional required issuer. When set, a token's `iss` must equal this exactly.
+   * Unset ⇒ `iss` is not checked. */
+  AUTH_ISSUER?: string;
   /** D1 binding. Enables the "Worker + D1 (no DO)" path — the same schema/ACL/read
    * engine over D1 instead of a Durable Object. Selected per-request via
    * `x-pramen-store: d1`. RPC only (live queries need the DO). */
@@ -45,12 +57,42 @@ export interface Env {
   CORS_ORIGINS?: string;
   /** "true" to apply destructive schema migrations on the D1 path. Off by default. */
   PRAMEN_ALLOW_DESTRUCTIVE?: string;
+  /** Default store for /rpc when no `x-pramen-store` header is sent: `"d1"` runs the
+   * Worker+D1 path by default (requires DB bound); `"do"` (the default) routes to the
+   * per-tenant Durable Object. The header still overrides per-request. /live always
+   * needs the DO regardless of this setting. */
+  PRAMEN_STORE?: string;
+  /** "true" to allow the shared D1 store to serve a non-`main` tenant. OFF by default:
+   * the D1 proof uses ONE database with no tenant column, so multiple tenants would
+   * commingle. Only set this if the app genuinely single-tenants that D1 (or has added
+   * its own tenant isolation). */
+  PRAMEN_D1_ALLOW_MULTITENANT?: string;
+  /** Cloudflare Queues producer binding for ctx.queue (declared in oblaka.ts). Optional —
+   * ctx.queue discovers any producer binding by name; this just types the common one. */
+  JOBS?: QueueProducerBinding;
 }
 
 /** The secret used to sign/verify file tokens — a dedicated FILES_SECRET if set,
  * else AUTH_SECRET (so HS256 setups work out of the box). */
 const filesSecret = (env: Env): string => env.FILES_SECRET || env.AUTH_SECRET;
 
+/** Request/response header carrying the D1 session bookmark for read-your-writes: a
+ * client echoes the last response's value on its next request, anchoring a fresh
+ * session at that write so it reads its own writes (even off a lagging replica). */
+const D1_BOOKMARK_HEADER = "x-pramen-d1-bookmark";
+
+/** Decide whether an /rpc request runs on the D1 store. **Live queries ALWAYS use the
+ * DO** (they need a single writer + a socket host), regardless of header or default —
+ * so enabling `PRAMEN_STORE=d1` never silently breaks `/live`. Otherwise an explicit
+ * `x-pramen-store` header wins (`d1`/`do`), then the `PRAMEN_STORE` default. Pure +
+ * exported for unit testing. */
+export function useD1Store(opts: { storeHeader: string | null; isLive: boolean; defaultStore: string | undefined }): boolean {
+  if (opts.isLive) return false; // live is DO-only — never the D1 path
+  if (opts.storeHeader === "d1") return true;
+  if (opts.storeHeader === "do") return false;
+  return opts.defaultStore === "d1";
+}
+
 const json = (body: unknown, status = 200) => Response.json(body, { status });
 const forbidden = (what: string) => json({ ok: false, error: `access denied: ${what}`, code: "forbidden" }, 403);
 const badRequest = (msg: string) => json({ ok: false, error: msg, code: "bad_request" }, 400);
@@ -65,7 +107,10 @@ function corsHeaders(origin: string | null, env: Env): Record<string, string> {
   return {
     "access-control-allow-origin": allow.includes("*") ? "*" : origin,
     "access-control-allow-methods": "GET, POST, OPTIONS",
-    "access-control-allow-headers": "content-type, authorization, x-pramen-tenant, x-pramen-store",
+    "access-control-allow-headers": "content-type, authorization, x-pramen-tenant, x-pramen-store, x-pramen-d1-bookmark",
+    // Expose the D1 read-your-writes bookmark so a browser client can read it off the
+    // response and carry it forward on the next request.
+    "access-control-expose-headers": "x-pramen-d1-bookmark",
     vary: "origin",
   };
 }
@@ -83,6 +128,15 @@ function withCors(res: Response, cors: Record<string, string>): Response {
  * `tenant` for the default partition (so `idFromName(tenant)` is byte-for-byte unchanged
  * — backward-compat) and `${tenant}:${partition}` for any other partition. */
 function partitionStubFor(env: Env, tenant: string, partition: string = DEFAULT_PARTITION): DurableObjectStub {
+  // Fail with a clear message rather than a cryptic `Cannot read 'get' of undefined`
+  // when the Durable Object isn't bound (e.g. a D1-only deployment that fell through to
+  // the DO path). The Worker RPC surface depends on this binding existing.
+  if (!env.PRAMEN) {
+    throw new Error(
+      "pramen: no Durable Object bound (PRAMEN). Pin the D1 store per request with the " +
+        "'x-pramen-store: d1' header (or set PRAMEN_STORE=d1), or bind the PramenDO.",
+    );
+  }
   return env.PRAMEN.get(env.PRAMEN.idFromName(partitionDoName(tenant, partition)));
 }
 
@@ -117,12 +171,20 @@ export function makeWorker(app: PramenApp) {
   // JwksStrategy caches fetched public keys, so keep one instance per isolate (keyed
   // by URL) rather than rebuilding it per request. HmacStrategy is stateless.
   let jwks: JwksStrategy | undefined;
+  // Opt-in claim validation from env — default OFF (unset) so existing tokens keep
+  // verifying. Threaded into whichever strategy the deployment uses.
+  const verifyOptsFor = (env: Env): VerifyOptions => ({
+    requireExp: env.AUTH_REQUIRE_EXP === "true",
+    audience: env.AUTH_AUDIENCE || undefined,
+    issuer: env.AUTH_ISSUER || undefined,
+  });
   const strategyFor = (env: Env): VerifyStrategy => {
+    const opts = verifyOptsFor(env);
     if (env.JWKS_URL) {
-      if (!jwks || jwks.url !== env.JWKS_URL) jwks = new JwksStrategy(env.JWKS_URL);
+      if (!jwks || jwks.url !== env.JWKS_URL) jwks = new JwksStrategy(env.JWKS_URL, undefined, opts);
       return jwks;
     }
-    return new HmacStrategy(env.AUTH_SECRET);
+    return new HmacStrategy(env.AUTH_SECRET, opts);
   };
 
   // ACL is compiled once per isolate; the Worker's D1 path reuses it (the DO compiles
@@ -151,21 +213,24 @@ export function makeWorker(app: PramenApp) {
     const files = createFiles({ tenant: "main", secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
     const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
     const kv = new Kv(env.KV);
-    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv) };
+    return { db, kv, files, env: env as unknown as Record<string, unknown>, identity, tasks: tasksFacade(driver), mail: createMail(env as unknown as Record<string, unknown>, kv), queue: createQueue(env as unknown as Record<string, unknown>) };
   };
 
   /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
    * /admin/tasks/drain route with `x-pramen-store: d1`, and by `scheduled()` (Cron). */
   const drainD1 = async (env: Env): Promise<unknown> => {
     if (!env.DB) throw new Error("D1 store is not configured");
-    const driver = new D1Driver(env.DB);
+    // The drain reads due tasks then writes their status — pin the primary so it sees
+    // and updates current outbox state (not a lagging replica).
+    const driver = new D1Driver(env.DB, { start: "first-primary" });
     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
     return drainOutbox(driver, bindTasks(app.tasks, d1TaskCtx(driver, env)), Date.now());
   };
 
   const listD1Tasks = async (env: Env, status?: string, limit?: number): Promise<unknown> => {
     if (!env.DB) throw new Error("D1 store is not configured");
-    const driver = new D1Driver(env.DB);
+    // Inspection listing — pin the primary so it reflects current outbox state.
+    const driver = new D1Driver(env.DB, { start: "first-primary" });
     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
     return listTasks(driver, { status, limit });
   };
@@ -181,6 +246,14 @@ export function makeWorker(app: PramenApp) {
       if (res) return res;
     }
 
+    // Public media serving: `GET /media/<tenant>/media/<key>` streams a CMS media blob
+    // from R2 (cache-friendly, no auth — published-site assets are public). Put Cloudflare
+    // Image Resizing (/cdn-cgi/image) in front for transforms. Restricted to media keys.
+    if (url.pathname.startsWith("/media/") && env.FILES) {
+      const res = await handleMediaRequest(request, { adapter: new R2Adapter(env.FILES) });
+      if (res) return res;
+    }
+
     // Public (pre-auth) routes — matched before identity resolution, so a
     // signature-authed webhook can live outside the JWT-gated /rpc surface.
     for (const r of app.routes ?? []) {
@@ -344,23 +417,53 @@ export function makeWorker(app: PramenApp) {
     const tenant = req.headers.get("x-pramen-tenant") ?? "main";
     if (!authorizeTenant(identity, tenant)) return withCors(forbidden(`tenant '${tenant}'`), cors);
 
-    // --- Worker + D1 (no DO): the same schema/ACL/read engine over a D1 binding,
-    // selected per-request via `x-pramen-store: d1`. RPC only — live queries need the
-    // DO (single writer + a socket host). This proof uses ONE shared D1 database
-    // across tenants; a real product would add a tenant column or a per-tenant DB.
-    if (req.headers.get("x-pramen-store") === "d1") {
+    // --- Worker + D1 (no DO): the same schema/ACL/read engine over a D1 binding.
+    // Selected per-request via `x-pramen-store: d1`, OR as the app-wide default when
+    // PRAMEN_STORE=d1 (the header still overrides: `x-pramen-store: do` forces the DO).
+    // RPC only — live queries need the DO (single writer + a socket host). This proof
+    // uses ONE shared D1 database across tenants; a real product would add a tenant
+    // column or a per-tenant DB.
+    const storeHeader = req.headers.get("x-pramen-store");
+    const useD1 = useD1Store({ storeHeader, isLive, defaultStore: env.PRAMEN_STORE });
+    if (useD1) {
       if (!env.DB) return badRequest("D1 store is not configured");
-      if (isLive) return badRequest("live queries require the default (DO) store");
+      // COMMINGLING GUARD: this D1 path is ONE shared database with no tenant column, so
+      // every tenant's rows live together. Selecting it for a non-`main` tenant (a
+      // multi-tenant scenario) would leak/mix tenants — and `PRAMEN_STORE=d1` makes it a
+      // silent global default. Fail closed unless the operator explicitly opts in.
+      if (tenant !== "main" && env.PRAMEN_D1_ALLOW_MULTITENANT !== "true") {
+        return withCors(
+          forbidden(`D1 store for tenant '${tenant}' (shared D1 has no tenant isolation — set PRAMEN_D1_ALLOW_MULTITENANT=true to allow)`),
+          cors,
+        );
+      }
+      // (isLive is excluded by useD1Store — live always routes to the DO below.)
       const name = url.pathname.replace(/^\/rpc\//, "");
       let input: unknown;
       if (request.method === "POST") input = await request.json().catch(() => undefined);
-      const driver = new D1Driver(env.DB);
+
+      // Pick where the D1 session may start its first read. A mutation ALWAYS pins the
+      // primary (`first-primary` is a superset of read-your-writes) so a read-modify-write
+      // can't run off a lagging replica — an inbound bookmark must not widen that window.
+      // A query honors a client-supplied bookmark (read-your-writes), else the nearest replica.
+      const inboundBookmark = req.headers.get(D1_BOOKMARK_HEADER);
+      const kind = app.handlers[name]?.kind;
+      let start: D1SessionStart;
+      if (kind === "mutation") start = "first-primary";
+      else if (inboundBookmark) start = inboundBookmark;
+      else start = "first-unconstrained";
+
+      const driver = new D1Driver(env.DB, { start });
       const files = createFiles({ tenant, secret: filesSecret(env), adapter: new R2Adapter(env.FILES) });
       const envBag = env as unknown as Record<string, unknown>;
       try {
         await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
         const { result } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, envBag, { acl: d1Acl, identity }, name, input);
-        return withCors(json({ ok: true, result }), cors);
+        const res = json({ ok: true, result });
+        // Thread the session's latest bookmark back so the client can read its own writes.
+        const bookmark = driver.getBookmark();
+        if (bookmark) res.headers.set(D1_BOOKMARK_HEADER, bookmark);
+        return withCors(res, cors);
       } catch (err) {
         const { status, body } = toResponse(err);
         return withCors(json(body, status), cors);
@@ -375,15 +478,39 @@ export function makeWorker(app: PramenApp) {
       const name = url.pathname.replace(/^\/rpc\//, "");
       partition = app.handlers[name]?.partition ?? DEFAULT_PARTITION;
     } else {
+      // /live's partition is client-supplied (?partition= / x-pramen-partition), so
+      // validate it against the schema's known partitions BEFORE routing — otherwise an
+      // anonymous caller could spin up unbounded junk DOs + permanent registry KV keys.
       partition = req.headers.get("x-pramen-partition") || DEFAULT_PARTITION;
+      if (!partitionsOf(app.schema).includes(partition)) {
+        return withCors(badRequest(`unknown partition '${partition}'`), cors);
+      }
     }
 
-    // Forward a trusted identity to the DO (the DO never re-derives it).
+    // Forward a trusted identity to the DO (the DO never re-derives it). Also set the
+    // tenant header so the DO learns its own name — without it, `main` (the default when
+    // the client omits x-pramen-tenant) never registers and re-runs its guard forever.
     const headers = new Headers(req.headers);
     if (identity) headers.set("x-pramen-identity", JSON.stringify(identity as Identity));
     else headers.delete("x-pramen-identity");
+    headers.set("x-pramen-tenant", tenant);
     headers.set("x-pramen-partition", partition);
 
+    // Routed to the DO but no DO is bound — return a clear, actionable error instead of
+    // crashing the whole RPC surface. (A D1-only deployment should pin the D1 store with
+    // the `x-pramen-store: d1` header; the `PRAMEN_STORE` env default can be dropped by
+    // some adapters' env proxies, so the header is the reliable way to pin it.)
+    if (!env.PRAMEN) {
+      return withCors(
+        badRequest(
+          isLive
+            ? "live queries require a Durable Object, but no PRAMEN binding is configured"
+            : "no Durable Object (PRAMEN) is bound — pin the D1 store with the 'x-pramen-store: d1' header (or bind the DO)",
+        ),
+        cors,
+      );
+    }
+
     const stub = partitionStubFor(env, tenant, partition);
     // WebSocket upgrades (101) must be returned untouched; only add CORS to HTTP.
     const res = await stub.fetch(new Request(req, { headers }));
@@ -395,5 +522,21 @@ export function makeWorker(app: PramenApp) {
     async scheduled(_event: unknown, env: Env): Promise<void> {
       if (env.DB) await drainD1(env);
     },
+
+    // Cloudflare Queues consumer entry: routes a batch to the matching `app.queues`
+    // handler (ACK on success / RETRY on throw, per message). A consumer is Worker-level
+    // (no tenant DO): its ctx carries env/kv/mail/queue + callPrivileged to reach a DO.
+    async queue(batch: QueueBatch, env: Env): Promise<void> {
+      const envBag = env as unknown as Record<string, unknown>;
+      const kv = new Kv(env.KV);
+      const ctx: QueueContext = {
+        env: envBag,
+        kv,
+        mail: createMail(envBag, kv),
+        queue: createQueue(envBag),
+        callPrivileged: (opts) => callPrivileged(env, opts),
+      };
+      await dispatchQueueBatch(app.queues ?? {}, ctx, batch);
+    },
   };
 }