@pramen/server 0.0.14 → 0.0.16

package/dist/runtime/storage.d.ts

@@ -72,3 +72,10 @@ export declare function handleFileRequest(request: Request, opts: {
     adapter: StorageAdapter;
     secret: string;
 }): Promise<Response | null>;
+/** Serve a PUBLIC media blob by key: `GET /media/<key>`. Cache-friendly + nosniff, no
+ * auth (published-site assets are public; the random tenant-scoped key is the capability).
+ * Returns a Response for any `/media/*` path, or null if not a media request. Restricted
+ * to `<tenant>/media/` keys so it can't serve arbitrary (e.g. signed-private) objects. */
+export declare function handleMediaRequest(request: Request, opts: {
+    adapter: StorageAdapter;
+}): Promise<Response | null>;

package/dist/worker.d.ts

@@ -11,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). */
@@ -30,6 +40,11 @@ export interface Env {
      * 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;

package/dist/worker.js

@@ -16,8 +16,8 @@ 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;
@@ -109,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
@@ -173,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 ?? []) {
@@ -338,21 +354,29 @@ export function makeWorker(app) {
             if (useD1) {
                 if (!env.DB)
                     return badRequest("D1 store is not configured");
+                // 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);
-                // Pick where the D1 session may start its first read. A client-supplied bookmark
-                // wins (read-your-writes); otherwise default by handler kind: a mutation pins the
-                // primary so its reads see current data, a query may begin at the nearest replica.
+                // 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 (inboundBookmark)
-                    start = inboundBookmark;
-                else if (kind === "mutation")
+                if (kind === "mutation")
                     start = "first-primary";
+                else if (inboundBookmark)
+                    start = inboundBookmark;
                 else
                     start = "first-unconstrained";
                 const driver = new D1Driver(env.DB, { start });
@@ -382,14 +406,23 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.14",
+  "version": "0.0.16",
   "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 {

package/src/cli.ts

@@ -0,0 +1,336 @@
+#!/usr/bin/env bun
+// pramen CLI — ships as the `pramen` bin of @pramen/server (see package.json `bin`).
+// In-repo it's invoked via `bun run pramen <command>` (scripts/cli.ts is a thin
+// wrapper around this module); published consumers get it as `pramen <command>`.
+//
+//   pramen help
+//   pramen init [dir]
+//   pramen schema sql                 print CREATE TABLE for the schema
+//   pramen schema hash                print the schema hash
+//   pramen schema snapshot            save the current schema to .pramen/schema.json
+//   pramen schema diff                compare the schema to the snapshot (safe vs unsafe changes)
+//   pramen schema status [--tenant t] [--url u] [--token jwt]   compare a deployed tenant to the schema
+//   pramen token <sub> [roles...] [--tenant a,b]                mint a dev JWT
+//
+// The bin uses a `bun` shebang: the `schema *` commands import your app module (a .ts
+// file), and the built package's dist/ uses extensionless ESM imports — both of which
+// bun resolves out of the box. Under plain Node the extensionless imports don't resolve
+// (a property of the whole @pramen/server dist, not just this file), so run via bun.
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { createTableSql } from "./runtime/ddl";
+import { schemaHash } from "./runtime/migrate";
+import { diffSchemaShape, schemaShape, type SchemaShape } from "./runtime/schema-diff";
+import { entitiesInPartition, partitionsOf, type SchemaDef } from "./sdk/schema";
+
+/** Mint an HS256 JWT — mirrors what a real auth service would issue, for local
+ * dev/testing (`pramen token`, and the default token for `schema status`). Signs
+ * with AUTH_SECRET when set, else the dev secret from the scaffolded oblaka.ts. */
+const DEV_SECRET = "dev-secret-change-me";
+
+function bytesToB64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+const strToB64url = (s: string) => bytesToB64url(new TextEncoder().encode(s));
+
+async function sign(payload: Record<string, unknown>): Promise<string> {
+  const secret = process.env.AUTH_SECRET || DEV_SECRET;
+  const now = Math.floor(Date.now() / 1000);
+  const header = strToB64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+  const body = strToB64url(JSON.stringify({ iat: now, exp: now + 3600, ...payload }));
+  const data = `${header}.${body}`;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    new TextEncoder().encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+  return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+
+/** The sub-schema of a single partition (used to mirror the DO's per-partition hash,
+ * which migrate() computes over exactly this subset). For a single-partition app the
+ * subset equals the whole schema, so the hash is identical to the unpartitioned case. */
+function partitionSchema(schema: SchemaDef, partition: string): SchemaDef {
+  return Object.fromEntries(entitiesInPartition(schema, partition).map((t) => [t, schema[t]!]));
+}
+
+const argv = process.argv.slice(2);
+
+function flag(name: string): string | undefined {
+  const i = argv.indexOf(`--${name}`);
+  return i >= 0 ? argv[i + 1] : undefined;
+}
+function positionals(args: string[]): string[] {
+  const out: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    if (args[i]!.startsWith("--")) i++; // skip flag + its value
+    else out.push(args[i]!);
+  }
+  return out;
+}
+
+function fail(msg: string): never {
+  console.error(`pramen: ${msg}`);
+  process.exit(1);
+}
+
+async function loadApp(): Promise<{ schema: SchemaDef }> {
+  const explicit = flag("app");
+  const candidates = explicit ? [explicit] : ["./app.ts", "./example/app.ts"];
+  for (const c of candidates) {
+    const p = resolve(process.cwd(), c);
+    if (existsSync(p)) {
+      const mod = (await import(p)) as { app?: { schema?: SchemaDef } };
+      if (mod.app?.schema) return mod.app as { schema: SchemaDef };
+      fail(`${c} does not export { app }`);
+    }
+  }
+  return fail(`no app found (looked for ${candidates.join(", ")}); pass --app <path>`);
+}
+
+const HELP = `pramen — reactive backend on Cloudflare
+
+Usage: pramen <command>
+
+  help                      show this help
+  init [dir]                scaffold a new project (app.ts + worker.ts + oblaka.ts)
+  schema sql                print CREATE TABLE statements for the schema
+  schema hash               print the schema hash
+  schema snapshot           save the schema shape to .pramen/schema.json
+  schema diff               compare the schema to the snapshot (safe vs unsafe)
+  schema status             compare a deployed tenant's schema to the local schema
+                            [--tenant t] [--url u] [--token jwt]
+  token <sub> [roles...]    mint a dev JWT [--tenant a,b]
+
+Flags: --app <path> to point at your app module (default ./app.ts or ./example/app.ts).`;
+
+async function schemaCmd(sub: string | undefined): Promise<void> {
+  const snapshotPath = resolve(process.cwd(), ".pramen/schema.json");
+
+  if (sub === "sql") {
+    const { schema } = await loadApp();
+    for (const [table, def] of Object.entries(schema)) console.log(createTableSql(table, def) + ";");
+    return;
+  }
+  if (sub === "hash") {
+    const { schema } = await loadApp();
+    console.log(schemaHash(schema));
+    return;
+  }
+  if (sub === "snapshot") {
+    const { schema } = await loadApp();
+    mkdirSync(dirname(snapshotPath), { recursive: true });
+    const snap = { hash: schemaHash(schema), shape: schemaShape(schema) };
+    writeFileSync(snapshotPath, JSON.stringify(snap, null, 2) + "\n");
+    console.log(`wrote ${snapshotPath} (${Object.keys(snap.shape).length} tables)`);
+    return;
+  }
+  if (sub === "diff") {
+    const { schema } = await loadApp();
+    const next = schemaShape(schema);
+    if (!existsSync(snapshotPath)) {
+      console.log("no snapshot — run `pramen schema snapshot` to set a baseline.");
+      return;
+    }
+    const prev = (JSON.parse(readFileSync(snapshotPath, "utf8")) as { shape: SchemaShape }).shape;
+    const changes = diffSchemaShape(prev, next);
+    if (changes.length === 0) {
+      console.log("no changes since snapshot.");
+      return;
+    }
+    for (const c of changes) {
+      const where = c.column ? `${c.table}.${c.column}` : c.table;
+      const note = c.detail ? ` (${c.detail})` : "";
+      const glyph = c.destructive ? "⚠" : !c.appliesOnBoot ? "•" : "+";
+      const tags =
+        (c.destructive ? "  [destructive]" : "") + (!c.appliesOnBoot ? "  [NOT applied on boot]" : "");
+      console.log(`  ${glyph} ${c.kind} ${where}${note}${tags}`);
+    }
+    console.log(
+      "\nOn the next DO boot: additive changes (new table/column) auto-apply; destructive changes\n" +
+        "(drops, type changes, table rebuilds) are SKIPPED unless the deploy sets PRAMEN_ALLOW_DESTRUCTIVE=true\n" +
+        "(the schema hash is then left unwritten so a later opt-in deploy retries).",
+    );
+    if (changes.some((c) => c.destructive))
+      console.log(
+        "⚠ destructive changes rebuild the table and CAN lose data. A drop+add is applied as such unless\n" +
+          "  the column declares `renamedFrom` (which migrates the data).",
+      );
+    if (changes.some((c) => !c.appliesOnBoot))
+      console.log(
+        "• [NOT applied on boot] a partition move — the entity's data lives in a different Durable Object,\n" +
+          "  which needs a manual cross-DO data migration. The boot migrator won't move it; apply it yourself.\n" +
+          "  (Modifier/constraint changes on an existing column ARE applied on boot now — a tightening one\n" +
+          "  like adding NOT NULL/UNIQUE is gated by PRAMEN_ALLOW_DESTRUCTIVE and skipped if it can't apply.)",
+      );
+    return;
+  }
+  if (sub === "status") {
+    const { schema } = await loadApp();
+    const url = flag("url") ?? "http://localhost:8787";
+    const tenant = flag("tenant") ?? "main";
+    const token = flag("token") ?? (await sign({ sub: "cli", roles: ["admin"] }));
+    // Each partition is a distinct Durable Object class, migrated and hashed
+    // independently — so compare them one at a time, fetching each partition's applied
+    // schema from its DO. A single-(default-)partition app loops exactly once and reads
+    // identically to before. The default partition is addressed with no partition param.
+    const partitions = partitionsOf(schema);
+    console.log(`tenant:  ${tenant}`);
+    for (const partition of partitions) {
+      if (partitions.length > 1) console.log(`\npartition: ${partition}`);
+      const qs = partition === "default" ? "" : `&partition=${encodeURIComponent(partition)}`;
+      const res = await fetch(`${url}/admin/schema?tenant=${encodeURIComponent(tenant)}${qs}`, {
+        headers: { authorization: `Bearer ${token}` },
+      });
+      const body = (await res.json().catch(() => ({}))) as {
+        ok?: boolean;
+        result?: { hash: string | null; tables: Record<string, string[]> };
+        error?: string;
+      };
+      if (!res.ok || !body.ok || !body.result) fail(`status failed (partition ${partition}): ${body.error ?? res.status}`);
+      const live = body.result!;
+      // The DO hashes only its partition's entities — mirror that here so the compared
+      // hashes line up (for a single partition this equals the whole-schema hash).
+      const subset = partitionSchema(schema, partition);
+      const current = schemaHash(subset);
+      const upToDate = live.hash === current;
+      console.log(`live:    ${live.hash ?? "(none)"}`);
+      console.log(`current: ${current}`);
+      console.log(upToDate ? "✓ up to date" : "⚠ BEHIND — migrates on the tenant's next boot");
+      const want = schemaShape(subset);
+      for (const table of Object.keys(want)) {
+        const liveCols = new Set(live.tables[table] ?? []);
+        const missing = Object.keys(want[table]!.columns).filter((col) => !liveCols.has(col));
+        if (!live.tables[table]) console.log(`  + table ${table} (not yet created live)`);
+        else if (missing.length) console.log(`  + ${table}: ${missing.join(", ")} (not yet added live)`);
+      }
+    }
+    return;
+  }
+  console.log(HELP);
+}
+
+async function tokenCmd(args: string[]): Promise<void> {
+  const pos = positionals(args);
+  const sub = pos[0];
+  if (!sub) fail("token: <sub> required");
+  const roles = pos.slice(1);
+  const tenants = flag("tenant")?.split(",");
+  console.log(await sign({ sub, roles: roles.length ? roles : ["admin"], ...(tenants ? { tenants } : {}) }));
+}
+
+function initCmd(args: string[]): void {
+  const dir = resolve(process.cwd(), positionals(args)[0] ?? ".");
+  mkdirSync(dir, { recursive: true });
+  const write = (name: string, content: string) => {
+    const p = resolve(dir, name);
+    if (existsSync(p)) return void console.log(`  skip ${name} (exists)`);
+    writeFileSync(p, content);
+    console.log(`  + ${name}`);
+  };
+  write("app.ts", APP_TEMPLATE);
+  write("worker.ts", WORKER_TEMPLATE);
+  write("oblaka.ts", OBLAKA_TEMPLATE);
+  console.log(`\nScaffolded a pramen project in ${dir}.\n`);
+  console.log("Next steps:");
+  console.log("  1. Install deps:    bun add @pramen/server && bun add -d oblaka-iac wrangler");
+  console.log("  2. Generate config: bunx oblaka oblaka.ts    (writes wrangler.jsonc)");
+  console.log("  3. Run locally:     bunx wrangler dev         (serves http://localhost:8787)");
+  console.log("");
+  console.log("First request: POST http://localhost:8787/rpc/listNotes returns [] (not 403) —");
+  console.log("the scaffold's ACL grants the anonymous role read+create on `notes`. Tighten it");
+  console.log("in app.ts before shipping (see the comments there).");
+}
+
+const APP_TEMPLATE = `import { Entity, defineSchema, createApp, role, policy, allow } from "@pramen/server";
+
+const schema = defineSchema({
+  notes: Entity((t) => ({ id: t.id(), title: t.text(), body: t.text(), createdAt: t.int() })),
+});
+
+const { query, mutation } = createApp(schema);
+
+const handlers = {
+  listNotes: query((ctx) => ctx.db.find({ from: "notes", orderBy: { column: "id", dir: "desc" } })),
+  createNote: mutation((ctx, input: { title: string; body: string }) =>
+    ctx.db.insert("notes", { title: input.title, body: input.body, createdAt: Date.now() }),
+  ),
+};
+
+// ACL — deny-by-default; roles only GRANT. A caller with no verified token is the
+// \`anonymous\` role, so this grants the scaffold's handlers on the first request (no
+// token needed). TIGHTEN THIS before shipping: gate writes behind an authenticated
+// role and scope reads with \`$identity(...)\` (see @pramen/auth and the pramen docs).
+const acl = [
+  role("anonymous", [
+    policy("anon:notes:read", "notes", "read", allow()),
+    policy("anon:notes:create", "notes", "create", allow()),
+  ]),
+];
+
+export const app = { schema, handlers, acl };
+`;
+
+const WORKER_TEMPLATE = `// The whole server entry: hand your app to createPramen and re-export the pair.
+import { createPramen } from "@pramen/server/worker";
+import { app } from "./app";
+
+const pramen = createPramen(app);
+
+export default { fetch: pramen.fetch };
+export const PramenDO = pramen.PramenDO; // wrangler binds this by class_name
+`;
+
+const OBLAKA_TEMPLATE = `import { define, DurableObject, KVNamespace, R2Bucket, Worker } from "oblaka-iac";
+
+const PROJECT = "my-pramen-app"; // unique per project — namespaces all CF resources
+
+export default define(({ env }) => {
+  const vars =
+    env === "local" ? { AUTH_SECRET: "dev-secret-change-me", FILES_SECRET: "dev-files-secret-change-me" } : {};
+  return new Worker({
+    dir: ".",
+    name: PROJECT,
+    main: "./worker.ts",
+    compatibility_date: "2026-06-19",
+    compatibility_flags: ["nodejs_compat"],
+    observability: { enabled: true },
+    bindings: {
+      PRAMEN: new DurableObject({ name: PROJECT + "-store", className: "PramenDO" }),
+      KV: new KVNamespace({ name: PROJECT + "-kv" }),
+      FILES: new R2Bucket({ name: PROJECT + "-files" }),
+    },
+    vars,
+  });
+});
+`;
+
+async function main(): Promise<void> {
+  const cmd = argv[0];
+  switch (cmd) {
+    case undefined:
+    case "help":
+    case "-h":
+    case "--help":
+      console.log(HELP);
+      return;
+    case "init":
+      return initCmd(argv.slice(1));
+    case "schema":
+      return schemaCmd(argv[1]);
+    case "token":
+      return tokenCmd(argv.slice(1));
+    default:
+      console.error(`pramen: unknown command "${cmd}"\n`);
+      console.log(HELP);
+      process.exit(1);
+  }
+}
+
+await main();