@pramen/server 0.0.14 → 0.0.16

package/dist/auth.d.ts

@@ -4,10 +4,24 @@ import type { Identity } from "./sdk/acl";
 export interface VerifyStrategy {
     verify(token: string): Promise<Record<string, unknown> | null>;
 }
+/** 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;
+}
 /** HS256 via a shared secret. The dev/default strategy. */
 export declare class HmacStrategy implements VerifyStrategy {
     private readonly secret;
-    constructor(secret: string);
+    private readonly opts;
+    constructor(secret: string, opts?: VerifyOptions);
     verify(token: string): Promise<Record<string, unknown> | null>;
 }
 /** RS256 verified against a remote JWKS. Public keys are fetched once and cached
@@ -16,10 +30,11 @@ export declare class HmacStrategy implements VerifyStrategy {
 export declare class JwksStrategy implements VerifyStrategy {
     readonly url: string;
     private readonly ttlMs;
+    private readonly opts;
     private keys;
     private fetchedAt;
     private inflight;
-    constructor(url: string, ttlMs?: number);
+    constructor(url: string, ttlMs?: number, opts?: VerifyOptions);
     verify(token: string): Promise<Record<string, unknown> | null>;
     private lookup;
     private keyFor;

package/dist/auth.js

@@ -21,9 +21,17 @@ function b64urlToBytes(s) {
 function b64urlToString(s) {
     return new TextDecoder().decode(b64urlToBytes(s));
 }
+/** 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, expected) {
+    const claim = Array.isArray(aud) ? aud.filter((a) => 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, verifySignature) {
+// 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, verifySignature, opts = {}) {
     const parts = token.split(".");
     if (parts.length !== 3)
         return null;
@@ -52,17 +60,26 @@ async function verifyJwt(token, verifySignature) {
         return null;
     }
     const now = Math.floor(Date.now() / 1000);
-    if (typeof payload.exp === "number" && now >= payload.exp)
+    const hasExp = typeof payload.exp === "number";
+    if (opts.requireExp && !hasExp)
+        return null;
+    if (hasExp && now >= payload.exp)
         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 {
     secret;
-    constructor(secret) {
+    opts;
+    constructor(secret, opts = {}) {
         this.secret = secret;
+        this.opts = opts;
     }
     verify(token) {
         return verifyJwt(token, async (input, signature, header) => {
@@ -70,7 +87,7 @@ export class HmacStrategy {
                 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);
     }
 }
 const SINGLE_KEY = "\0single";
@@ -80,12 +97,14 @@ const SINGLE_KEY = "\0single";
 export class JwksStrategy {
     url;
     ttlMs;
+    opts;
     keys = new Map();
     fetchedAt = 0;
     inflight = null;
-    constructor(url, ttlMs = 600_000) {
+    constructor(url, ttlMs = 600_000, opts = {}) {
         this.url = url;
         this.ttlMs = ttlMs;
+        this.opts = opts;
     }
     verify(token) {
         return verifyJwt(token, async (input, signature, header) => {
@@ -95,7 +114,7 @@ export class JwksStrategy {
             if (!key)
                 return false;
             return crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, signature, new TextEncoder().encode(input));
-        });
+        }, this.opts);
     }
     lookup(kid) {
         if (kid)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,311 @@
+#!/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 } from "./runtime/schema-diff";
+import { entitiesInPartition, partitionsOf } 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) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+const strToB64url = (s) => bytesToB64url(new TextEncoder().encode(s));
+async function sign(payload) {
+    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, partition) {
+    return Object.fromEntries(entitiesInPartition(schema, partition).map((t) => [t, schema[t]]));
+}
+const argv = process.argv.slice(2);
+function flag(name) {
+    const i = argv.indexOf(`--${name}`);
+    return i >= 0 ? argv[i + 1] : undefined;
+}
+function positionals(args) {
+    const out = [];
+    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) {
+    console.error(`pramen: ${msg}`);
+    process.exit(1);
+}
+async function loadApp() {
+    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));
+            if (mod.app?.schema)
+                return mod.app;
+            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) {
+    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")).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(() => ({})));
+            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) {
+    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) {
+    const dir = resolve(process.cwd(), positionals(args)[0] ?? ".");
+    mkdirSync(dir, { recursive: true });
+    const write = (name, content) => {
+        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() {
+    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();

package/dist/durable-object.d.ts

@@ -35,6 +35,14 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
      * task context — a DO can't introspect its own idFromName. */
     private identityPersisted;
     private identityLoaded;
+    /** Live subscriptions per socket — held IN MEMORY, not in the WS attachment. The
+     * attachment is capped at ~2 KB by workerd, and 64 subs (each with arbitrary input
+     * JSON + a read-set + digest) blow past that well before MAX_SUBSCRIPTIONS. The
+     * tradeoff: this map is lost on DO hibernation/eviction, so a woken socket has no
+     * entry and is treated as having no active subscriptions — acceptable because the
+     * client replays its subscriptions on (re)connect. Keyed by the WebSocket object;
+     * cleaned up in webSocketClose. */
+    private readonly subsBySocket;
     constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp);
     private ensureMigrated;
     fetch(request: Request): Promise<Response>;
@@ -42,13 +50,16 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
      * pending alarm; a near-future time batches a burst of enqueues into one drain. */
     private armDrain;
     /** A privileged, system-scoped context for running task handlers (outside a request).
-     * Task handlers get full db access + env (e.g. ctx.env.EMAIL) + their own ctx.tasks. */
+     * Task handlers get full db access + env (e.g. ctx.env.EMAIL) + their own ctx.tasks.
+     * Returns the `db` alongside the ctx so the drainer can broadcast the tables the task
+     * handlers touched (live queries would otherwise go stale after deferred/trigger work). */
     private taskCtx;
     /** Restore (tenant, partition) on a cold wake (e.g. an alarm with no request) so the
      * task context is scoped correctly. No-op once loaded/persisted this instance. */
     private loadIdentity;
     /** Drain due tasks. Called by the alarm (DO path) and the /__admin/tasks/drain route
-     * (manual / cron). Returns the drain stats incl. `nextRunAt` for rescheduling. */
+     * (manual / cron). Returns the drain stats incl. `nextRunAt` for rescheduling, plus
+     * the union of tables the drained task handlers touched (for a post-commit broadcast). */
     private drainTasks;
     alarm(): Promise<void>;
     private handleDrain;
@@ -67,8 +78,15 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
     private get envBag();
     private filesFor;
     private identityOf;
-    private getState;
-    private setState;
+    /** The durable per-socket auth/routing state (identity + tenant + partition), read
+     * from the WS attachment. Survives hibernation; kept tiny to stay under workerd's cap. */
+    private getAttachment;
+    private setAttachment;
+    /** This socket's live subscriptions from the in-memory map (see `subsBySocket`). A
+     * hibernated/woken socket has no entry → no active subscriptions until the client
+     * replays them on reconnect. */
+    private getSubs;
+    private setSubs;
     private send;
 }
 /** Produce the concrete, app-bound Durable Object class. A DO is constructed by the