@pramen/server 0.0.13 → 0.0.15

package/dist/worker.d.ts

@@ -1,3 +1,5 @@
+import { type QueueProducerBinding } from "./runtime/queue";
+import { type QueueBatch } from "./runtime/queue-consumer";
 import type { PramenApp } from "./pramen";
 export interface Env {
     PRAMEN: DurableObjectNamespace;
@@ -9,6 +11,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). */
@@ -23,7 +35,30 @@ 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;
 }
+/** 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 declare function useD1Store(opts: {
+    storeHeader: string | null;
+    isLive: boolean;
+    defaultStore: string | undefined;
+}): boolean;
 /** Forward a privileged mutation into a tenant's DO from a public route. The
  * synthetic identity (default `["admin"]`) is trusted because the call originates
  * in the Worker — the same internal mechanism the admin endpoints use. Returns the
@@ -40,4 +75,5 @@ export declare function callPrivileged(env: Env, opts: {
 export declare function makeWorker(app: PramenApp): {
     fetch(request: Request, env: Env): Promise<Response>;
     scheduled(_event: unknown, env: Env): Promise<void>;
+    queue(batch: QueueBatch, env: Env): Promise<void>;
 };

package/dist/worker.js

@@ -7,6 +7,8 @@ import { authorizeTenant, HmacStrategy, isAdmin, JwksStrategy, resolveIdentity }
 import { dispatch, tasksFacade, bindTasks } from "./runtime/dispatch";
 import { ensureOutbox, drainOutbox, listTasks } from "./runtime/outbox";
 import { createMail } from "./runtime/mail";
+import { createQueue } from "./runtime/queue";
+import { dispatchQueueBatch } from "./runtime/queue-consumer";
 import { migrate } from "./runtime/migrate";
 import { compileAcl } from "./runtime/acl";
 import { Db } from "./runtime/db";
@@ -14,11 +16,29 @@ import { D1Driver } 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 { DEFAULT_PARTITION } from "./sdk/schema";
+import { createFiles, handleFileRequest, handleMediaRequest, R2Adapter } from "./runtime/storage";
+import { DEFAULT_PARTITION, partitionsOf } from "./sdk/schema";
 /** 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.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) {
+    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, status = 200) => Response.json(body, { status });
 const forbidden = (what) => json({ ok: false, error: `access denied: ${what}`, code: "forbidden" }, 403);
 const badRequest = (msg) => json({ ok: false, error: msg, code: "bad_request" }, 400);
@@ -34,7 +54,10 @@ function corsHeaders(origin, env) {
     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",
     };
 }
@@ -52,6 +75,13 @@ function withCors(res, cors) {
  * `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, tenant, partition = DEFAULT_PARTITION) {
+    // 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)));
 }
 /** Forward a privileged mutation into a tenant's DO from a public route. The
@@ -79,13 +109,21 @@ export function makeWorker(app) {
     // 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;
+    // Opt-in claim validation from env — default OFF (unset) so existing tokens keep
+    // verifying. Threaded into whichever strategy the deployment uses.
+    const verifyOptsFor = (env) => ({
+        requireExp: env.AUTH_REQUIRE_EXP === "true",
+        audience: env.AUTH_AUDIENCE || undefined,
+        issuer: env.AUTH_ISSUER || undefined,
+    });
     const strategyFor = (env) => {
+        const opts = verifyOptsFor(env);
         if (env.JWKS_URL) {
             if (!jwks || jwks.url !== env.JWKS_URL)
-                jwks = new JwksStrategy(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
     // its own). Schema migration over D1 runs once per isolate (and short-circuits on a
@@ -112,21 +150,24 @@ export function makeWorker(app) {
         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, identity, tasks: tasksFacade(driver), mail: createMail(env, kv) };
+        return { db, kv, files, env: env, identity, tasks: tasksFacade(driver), mail: createMail(env, kv), queue: createQueue(env) };
     };
     /** 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) => {
         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, status, limit) => {
         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 });
     };
@@ -140,6 +181,14 @@ export function makeWorker(app) {
                 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 ?? []) {
@@ -294,26 +343,54 @@ export function makeWorker(app) {
             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;
                 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;
+                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;
                 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);
@@ -329,15 +406,33 @@ export function makeWorker(app) {
                 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));
             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 }));
@@ -349,5 +444,20 @@ export function makeWorker(app) {
             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, env) {
+            const envBag = env;
+            const kv = new Kv(env.KV);
+            const ctx = {
+                env: envBag,
+                kv,
+                mail: createMail(envBag, kv),
+                queue: createQueue(envBag),
+                callPrivileged: (opts) => callPrivileged(env, opts),
+            };
+            await dispatchQueueBatch(app.queues ?? {}, ctx, batch);
+        },
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {
@@ -30,6 +30,9 @@
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "pramen": "./dist/cli.js"
+  },
   "files": ["dist", "src"],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json"
@@ -38,6 +41,7 @@
     "access": "public"
   },
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20250101.0"
+    "@cloudflare/workers-types": "^4.20250101.0",
+    "@types/node": "^22.0.0"
   }
 }

package/src/auth.ts

@@ -40,9 +40,36 @@ export interface VerifyStrategy {
 /** Verify a signature over `${header}.${payload}` for the parsed header. */
 type SignatureVerifier = (signingInput: string, signature: Uint8Array, header: JwtHeader) => Promise<boolean>;
 
+/** Optional, opt-in claim validation layered on top of signature + exp/nbf. All
+ * default OFF (unset) so existing tokens keep verifying; a deployment turns these on
+ * to tighten what it accepts. Shared by every strategy (they all run verifyJwt). */
+export interface VerifyOptions {
+  /** Reject a token that has no numeric `exp` (RFC 7519 leaves exp optional; a strict
+   * deployment can require it so no non-expiring token is ever accepted). */
+  requireExp?: boolean;
+  /** Required audience. `payload.aud` (string or string[]) must contain at least one of
+   * these; a missing `aud` is rejected. Unset ⇒ `aud` not checked. */
+  audience?: string | string[];
+  /** Required issuer. `payload.iss` must equal this exactly. Unset ⇒ `iss` not checked. */
+  issuer?: string;
+}
+
+/** Does the token's `aud` claim satisfy the required audience? Token aud may be a
+ * string or an array; a match is any overlap with the expected audience(s). */
+function audienceMatches(aud: unknown, expected: string | string[]): boolean {
+  const claim = Array.isArray(aud) ? aud.filter((a): a is string => typeof a === "string") : typeof aud === "string" ? [aud] : [];
+  const want = Array.isArray(expected) ? expected : [expected];
+  return want.some((w) => claim.includes(w));
+}
+
 // Shared JWT pipeline: parse, verify the signature via the supplied function, then
-// validate exp/nbf. Any malformed part or a verification throw -> null (reject).
-async function verifyJwt(token: string, verifySignature: SignatureVerifier): Promise<Record<string, unknown> | null> {
+// validate exp/nbf and the opt-in exp-required/aud/iss claims. Any malformed part or a
+// verification throw -> null (reject).
+async function verifyJwt(
+  token: string,
+  verifySignature: SignatureVerifier,
+  opts: VerifyOptions = {},
+): Promise<Record<string, unknown> | null> {
   const parts = token.split(".");
   if (parts.length !== 3) return null;
   const [h, p, sig] = parts;
@@ -70,27 +97,38 @@ async function verifyJwt(token: string, verifySignature: SignatureVerifier): Pro
   }
 
   const now = Math.floor(Date.now() / 1000);
-  if (typeof payload.exp === "number" && now >= payload.exp) return null;
+  const hasExp = typeof payload.exp === "number";
+  if (opts.requireExp && !hasExp) return null;
+  if (hasExp && now >= (payload.exp as number)) return null;
   if (typeof payload.nbf === "number" && now < payload.nbf) return null;
+  if (opts.audience !== undefined && !audienceMatches(payload.aud, opts.audience)) return null;
+  if (opts.issuer !== undefined && payload.iss !== opts.issuer) return null;
   return payload;
 }
 
 /** HS256 via a shared secret. The dev/default strategy. */
 export class HmacStrategy implements VerifyStrategy {
-  constructor(private readonly secret: string) {}
+  constructor(
+    private readonly secret: string,
+    private readonly opts: VerifyOptions = {},
+  ) {}
 
   verify(token: string): Promise<Record<string, unknown> | null> {
-    return verifyJwt(token, async (input, signature, header) => {
-      if (header.alg !== "HS256" || !this.secret) return false;
-      const key = await crypto.subtle.importKey(
-        "raw",
-        new TextEncoder().encode(this.secret),
-        { name: "HMAC", hash: "SHA-256" },
-        false,
-        ["verify"],
-      );
-      return crypto.subtle.verify("HMAC", key, signature, new TextEncoder().encode(input));
-    });
+    return verifyJwt(
+      token,
+      async (input, signature, header) => {
+        if (header.alg !== "HS256" || !this.secret) return false;
+        const key = await crypto.subtle.importKey(
+          "raw",
+          new TextEncoder().encode(this.secret),
+          { name: "HMAC", hash: "SHA-256" },
+          false,
+          ["verify"],
+        );
+        return crypto.subtle.verify("HMAC", key, signature, new TextEncoder().encode(input));
+      },
+      this.opts,
+    );
   }
 }
 
@@ -111,15 +149,20 @@ export class JwksStrategy implements VerifyStrategy {
   constructor(
     readonly url: string,
     private readonly ttlMs = 600_000,
+    private readonly opts: VerifyOptions = {},
   ) {}
 
   verify(token: string): Promise<Record<string, unknown> | null> {
-    return verifyJwt(token, async (input, signature, header) => {
-      if (header.alg !== "RS256") return false;
-      const key = await this.keyFor(header.kid);
-      if (!key) return false;
-      return crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, signature, new TextEncoder().encode(input));
-    });
+    return verifyJwt(
+      token,
+      async (input, signature, header) => {
+        if (header.alg !== "RS256") return false;
+        const key = await this.keyFor(header.kid);
+        if (!key) return false;
+        return crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, signature, new TextEncoder().encode(input));
+      },
+      this.opts,
+    );
   }
 
   private lookup(kid?: string): CryptoKey | null {