@pramen/server 0.0.49 → 0.0.51

package/dist/cli.js

@@ -22,27 +22,8 @@ import { createTableSql } from "./runtime/ddl";
 import { schemaHash } from "./runtime/migrate";
 import { diffSchemaFingerprint, schemaFingerprint } 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))}`;
-}
+import { signDevToken } from "./runtime/dev-token";
+const sign = (payload) => signDevToken(payload);
 /** 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. */

package/dist/dev.d.ts

@@ -0,0 +1 @@
+export { signDevToken, DEV_SECRET } from "./runtime/dev-token";

package/dist/dev.js

@@ -0,0 +1,9 @@
+// `@pramen/server/dev` — tooling helpers, deliberately NOT on the authoring entry point.
+//
+// `signDevToken` mints an HS256 JWT for local development: the `pramen` and `pramen-cms`
+// bins and the repo's test helper all use it. It is kept off `@pramen/server` because its
+// secret lookup reads `process.env.AUTH_SECRET`, which does not exist in a deployed
+// Worker (bindings and secrets arrive on `env`) — so an app handler importing it from the
+// main entry would silently sign with the PUBLISHED dev constant while appearing to honour
+// AUTH_SECRET. A separate subpath makes "this is dev tooling" part of the import.
+export { signDevToken, DEV_SECRET } from "./runtime/dev-token";

package/dist/durable-object.js

@@ -203,6 +203,8 @@ export class PramenDOBase extends DurableObject {
             files: this.filesFor(this.tenant),
             env: this.envBag,
             identity,
+            tenant: this.tenant,
+            store: "do",
             tasks: tasksFacade(this.driver),
             mail: createMail(this.envBag, this.kv),
             queue: createQueue(this.envBag),
@@ -533,7 +535,7 @@ export class PramenDOBase extends DurableObject {
         // Carry the schema so any consumer of this context (not just Db) can compile
         // relation-aware `where` rules into subqueries, and the active partition so Db's
         // table-access guard rejects any table outside this DO's partition.
-        return { acl: this.acl, identity, schema: this.app.schema, partition };
+        return { acl: this.acl, identity, schema: this.app.schema, partition, tenant: this.tenant };
     }
     // The DO env (bindings + vars + secrets) handed to handlers as ctx.env. Loosely
     // typed at the boundary so handlers can read any var/secret without a DoEnv cast.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger, partitionOf, DEFAULT_PARTITION } from "./sdk/schema";
 export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type { DefaultValue, FieldType, FieldDef, EntityFields, EntityDef, SchemaDef, RelationDef, RelationDefs, BelongsToDef, HasManyDef, ManyToManyDef, OneHasOneDef, OneHasOneInverseDef, OnDelete, } from "./sdk/schema";
@@ -11,6 +11,8 @@ export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, Jso
 export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET_LEN } from "./runtime/token";
+export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 export type { MailMessage, MailAddress, MailAdapter, SendEmailBinding } from "./runtime/mail";
@@ -18,6 +20,6 @@ export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discove
 export type { QueueAdapter, QueueProducerBinding, QueueSendOptions, QueueSendRequest, QueueBatchOptions, QueueContentType } from "./runtime/queue";
 export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
 export type { QueueContext, QueueHandler, QueueMessage, QueueBatch, AppQueueMap } from "./runtime/queue-consumer";
-export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
+export { PramenError, BadRequest, Unauthorized, Forbidden, Conflict } from "./runtime/errors";
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
 export type { Driver, Dialect, DriverRow } from "./runtime/driver";

package/dist/index.js

@@ -7,7 +7,7 @@
 // which only exists in the Workers runtime; keeping it separate lets the CLI, tests,
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger, partitionOf, DEFAULT_PARTITION } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 // --- app + handlers ---
 export { createApp } from "./sdk/app";
@@ -17,12 +17,16 @@ export { $identity, $input, $now, allow, deny, policy, resolve, role, isAllow, i
 // --- kv (ctx.kv) + session denylist (hard token revocation) ---
 export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+// Signed capability tokens (HMAC-SHA256) — the machinery behind signed file urls and
+// page-preview links. Exported so an app (or @pramen/cms) can mint its own capability url
+// without a second signing implementation.
+export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET_LEN } from "./runtime/token";
 // --- mail (ctx.mail) ---
 export { Mail, CloudflareEmailAdapter, KvMailAdapter, MemoryMailAdapter, UnconfiguredMailAdapter, createMail } from "./runtime/mail";
 // --- queue (ctx.queue — Cloudflare Queues) ---
 export { Queue, CloudflareQueueAdapter, MemoryQueueAdapter, createQueue, discoverQueueBindings } from "./runtime/queue";
 export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
 // --- errors ---
-export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
+export { PramenError, BadRequest, Unauthorized, Forbidden, Conflict } from "./runtime/errors";
 // --- substrate seam (advanced: bring your own SQL backend) ---
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";

package/dist/runtime/acl.d.ts

@@ -27,6 +27,14 @@ export interface AclContext {
     /** The app schema — lets `where` rules traverse relations (`{ rel: { col } }`),
      * compiled to a subquery with the related entity's read scope AND-merged in. */
     readonly schema?: SchemaDef;
+    /** The tenant this request is for — the `x-pramen-tenant` value the DO was addressed
+     * with. Carried so a handler can mint a tenant-scoped capability (e.g. a signed page
+     * preview link) without the caller supplying, and thus being able to forge, a tenant. */
+    readonly tenant?: string;
+    /** Which substrate is serving this request — `"do"` (a Durable Object, the default) or
+     * `"d1"` (the shared D1 database, selected per-request with `x-pramen-store: d1`). A
+     * handler needs this when a capability it mints can only be redeemed on one of them. */
+    readonly store?: "do" | "d1";
     /** The partition this DO serves. When set, Db rejects any access to a table that
      * lives in a different partition (a partition-DO only owns its own tables). Unset
      * (e.g. the D1/Worker shared-store path) disables the guard — a no-op. */

package/dist/runtime/dev-token.d.ts

@@ -0,0 +1,4 @@
+/** The scaffolded oblaka.ts dev secret. Used only when AUTH_SECRET is unset. */
+export declare const DEV_SECRET = "dev-secret-change-me";
+/** Sign a dev JWT (1h). Secret: the `secret` argument, else `AUTH_SECRET`, else DEV_SECRET. */
+export declare function signDevToken(payload: Record<string, unknown>, secret?: string): Promise<string>;

package/dist/runtime/dev-token.js

@@ -0,0 +1,34 @@
+// Mint an HS256 JWT for local development and tooling — what a real auth service would
+// issue, without running one.
+//
+// Extracted because it was already written twice (the `pramen` CLI and the repo's test
+// helper) and `@pramen/cms`'s own bin would have been a third. One implementation, in the
+// package that owns tokens.
+//
+// NOT an auth system: the dev fallback secret is public, so a token signed with it is
+// worthless anywhere `AUTH_SECRET` is set to something real. That is the point — it makes
+// a forgotten secret fail loudly rather than quietly accept dev tokens in production.
+/** The scaffolded oblaka.ts dev secret. Used only when AUTH_SECRET is unset. */
+export 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));
+/** Sign a dev JWT (1h). Secret: the `secret` argument, else `AUTH_SECRET`, else DEV_SECRET. */
+export async function signDevToken(payload, secret) {
+    // `||`, not `??`: an AUTH_SECRET set to the empty string previously fell through to
+    // DEV_SECRET, and signing with an empty HMAC key instead would produce tokens the server
+    // rejects with no useful message.
+    const env = globalThis.process?.env;
+    const key = secret || 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 cryptoKey = await crypto.subtle.importKey("raw", new TextEncoder().encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const sig = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(data));
+    return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}

package/dist/runtime/dispatch.js

@@ -62,6 +62,8 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
         files,
         env,
         identity: acl.identity,
+        tenant: acl.tenant ?? "main",
+        store: acl.store ?? "do",
         tasks: tasksFacade(driver, () => enqueued++),
         mail: createMail(env, kv),
         queue: createQueue(env),

package/dist/runtime/errors.d.ts

@@ -15,6 +15,12 @@ export declare class Unauthorized extends PramenError {
 export declare class Forbidden extends PramenError {
     constructor(message?: string);
 }
+/** 409 — the request conflicts with the current state of the resource. For
+ * optimistic concurrency (a stale `expectedVersion`) and for uniqueness clashes the
+ * caller could resolve by retrying with different input. */
+export declare class Conflict extends PramenError {
+    constructor(message?: string);
+}
 export interface ErrorBody {
     ok: false;
     error: string;

package/dist/runtime/errors.js

@@ -29,6 +29,14 @@ export class Forbidden extends PramenError {
         super(message, 403, "forbidden");
     }
 }
+/** 409 — the request conflicts with the current state of the resource. For
+ * optimistic concurrency (a stale `expectedVersion`) and for uniqueness clashes the
+ * caller could resolve by retrying with different input. */
+export class Conflict extends PramenError {
+    constructor(message = "conflict") {
+        super(message, 409, "conflict");
+    }
+}
 function classify(err) {
     if (err instanceof PramenError) {
         return { status: err.status, body: { ok: false, error: err.message, code: err.code } };

package/dist/runtime/storage.d.ts

@@ -1,4 +1,5 @@
 import type { Files, HeadResult } from "../sdk/files";
+import { isUsableSecret, type ExpiringToken } from "./token";
 export type { Files, FileRef, HeadResult, SignDownloadOpts, SignUploadOpts } from "../sdk/files";
 export interface PutResult {
     key: string;
@@ -40,17 +41,16 @@ export declare class MemoryAdapter implements StorageAdapter {
     head(key: string): Promise<HeadResult | null>;
     delete(key: string): Promise<void>;
 }
-interface FileToken {
+interface FileToken extends ExpiringToken {
     /** tenant */ t: string;
     /** key */ k: string;
     /** op */ op: "get" | "put";
-    /** expiry (epoch seconds) */ exp: number;
     /** content-type (put: enforced; get: disposition hint) */ ct?: string;
     /** max size in bytes (put only) */ max?: number;
     /** filename (download disposition) */ fn?: string;
 }
 /** Verify a file token's signature + expiry; returns the payload or null. */
-export declare function verifyToken(raw: string, secret: string): Promise<FileToken | null>;
+export declare const verifyFileToken: (raw: string, secret: string) => Promise<FileToken | null>;
 export interface FilesConfig {
     tenant: string;
     secret: string;
@@ -63,7 +63,7 @@ export interface FilesConfig {
  * treated as unconfigured — fail closed rather than mint forgeable urls. The dev
  * defaults satisfy it; production should set a strong, random FILES_SECRET. */
 export declare const MIN_FILES_SECRET_LEN = 16;
-export declare function isUsableFilesSecret(secret: string | undefined | null): secret is string;
+export declare const isUsableFilesSecret: typeof isUsableSecret;
 /** Construct the per-tenant `ctx.files` facade. */
 export declare function createFiles(cfg: FilesConfig): Files;
 /** Serve the file endpoints. Returns a Response for any `/files/*` path, or null

package/dist/runtime/storage.js

@@ -15,6 +15,7 @@
 // R2 binding and stays backend-agnostic. URLs are RELATIVE so the server never
 // needs to know its own public origin — the client resolves them against its base.
 import { BadRequest, PramenError } from "./errors";
+import { signToken, verifyToken, isUsableSecret, MIN_TOKEN_SECRET_LEN } from "./token";
 /** R2 — the Cloudflare default. Wraps an R2 bucket binding. Streaming: bytes flow
  * directly between the client and R2 in the Worker, never through the DO. */
 export class R2Adapter {
@@ -84,63 +85,9 @@ function bytesToStream(bytes) {
         },
     });
 }
-// --- base64url (shared shape with auth.ts/jwt.ts) ---
-function bytesToB64url(bytes) {
-    let bin = "";
-    for (const b of bytes)
-        bin += String.fromCharCode(b);
-    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function b64urlToBytes(s) {
-    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
-    const bin = atob(b64);
-    const out = new Uint8Array(bin.length);
-    for (let i = 0; i < bin.length; i++)
-        out[i] = bin.charCodeAt(i);
-    return out;
-}
-const strToB64url = (s) => bytesToB64url(new TextEncoder().encode(s));
-const b64urlToStr = (s) => new TextDecoder().decode(b64urlToBytes(s));
-async function hmacKey(secret) {
-    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
-        "sign",
-        "verify",
-    ]);
-}
-async function signToken(token, secret) {
-    const data = strToB64url(JSON.stringify(token));
-    const key = await hmacKey(secret);
-    const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
-    return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
-}
+const signFileToken = (token, secret) => signToken(token, secret);
 /** Verify a file token's signature + expiry; returns the payload or null. */
-export async function verifyToken(raw, secret) {
-    const dot = raw.indexOf(".");
-    if (dot < 0)
-        return null;
-    const data = raw.slice(0, dot);
-    const sig = raw.slice(dot + 1);
-    let ok;
-    try {
-        const key = await hmacKey(secret);
-        ok = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), new TextEncoder().encode(data));
-    }
-    catch {
-        return null;
-    }
-    if (!ok)
-        return null;
-    let payload;
-    try {
-        payload = JSON.parse(b64urlToStr(data));
-    }
-    catch {
-        return null;
-    }
-    if (typeof payload.exp !== "number" || Math.floor(Date.now() / 1000) >= payload.exp)
-        return null;
-    return payload;
-}
+export const verifyFileToken = (raw, secret) => verifyToken(raw, secret);
 // --- key generation ---
 function randomKeySuffix() {
     const bytes = new Uint8Array(16);
@@ -188,10 +135,8 @@ function contentDisposition(name) {
  * would be forgeable (HMAC over an empty/weak key). Below this, file storage is
  * treated as unconfigured — fail closed rather than mint forgeable urls. The dev
  * defaults satisfy it; production should set a strong, random FILES_SECRET. */
-export const MIN_FILES_SECRET_LEN = 16;
-export function isUsableFilesSecret(secret) {
-    return typeof secret === "string" && secret.length >= MIN_FILES_SECRET_LEN;
-}
+export const MIN_FILES_SECRET_LEN = MIN_TOKEN_SECRET_LEN;
+export const isUsableFilesSecret = isUsableSecret;
 const filesUnconfigured = () => new PramenError("file storage is not configured (set a strong FILES_SECRET)", 503, "unavailable");
 /** Construct the per-tenant `ctx.files` facade. */
 export function createFiles(cfg) {
@@ -210,7 +155,7 @@ export function createFiles(cfg) {
             const seg = opts.prefix ? `${safePrefix(opts.prefix)}/` : "";
             const key = `${prefix}${seg}${randomKeySuffix()}`;
             const exp = Math.floor(Date.now() / 1000) + (opts.expiresIn ?? 900);
-            const token = await signToken({ t: cfg.tenant, k: key, op: "put", exp, ct, max: opts.maxSize, fn: opts.filename }, cfg.secret);
+            const token = await signFileToken({ t: cfg.tenant, k: key, op: "put", exp, ct, max: opts.maxSize, fn: opts.filename }, cfg.secret);
             const ref = { key, size: 0, contentType: ct, filename: opts.filename, uploadedAt: Date.now() };
             return { url: `${base}/upload?token=${encodeURIComponent(token)}`, ref };
         },
@@ -221,7 +166,7 @@ export function createFiles(cfg) {
             const key = ensureOwnKey(r.key);
             const exp = Math.floor(Date.now() / 1000) + (opts?.expiresIn ?? 3600);
             const fn = opts?.download ? (typeof ref === "string" ? undefined : ref.filename) : undefined;
-            const token = await signToken({ t: cfg.tenant, k: key, op: "get", exp, fn }, cfg.secret);
+            const token = await signFileToken({ t: cfg.tenant, k: key, op: "get", exp, fn }, cfg.secret);
             return { url: `${base}/download?token=${encodeURIComponent(token)}`, expiresAt: exp * 1000 };
         },
         head: (key) => cfg.adapter.head(ensureOwnKey(key)),
@@ -258,7 +203,7 @@ export async function handleFileRequest(request, opts) {
     const raw = url.searchParams.get("token");
     if (!raw)
         return fileError(401, "unauthorized", "missing token");
-    const token = await verifyToken(raw, opts.secret);
+    const token = await verifyFileToken(raw, opts.secret);
     if (!token)
         return fileError(403, "forbidden", "invalid or expired token");
     try {

package/dist/runtime/token.d.ts

@@ -0,0 +1,22 @@
+/** Every signed token carries an expiry (epoch seconds); `verifyToken` enforces it. */
+export interface ExpiringToken {
+    exp: number;
+}
+export declare function bytesToB64url(bytes: Uint8Array): string;
+export declare function b64urlToBytes(s: string): Uint8Array;
+export declare const strToB64url: (s: string) => string;
+export declare const b64urlToStr: (s: string) => string;
+/** Sign a payload into a capability token. */
+export declare function signToken<T extends ExpiringToken>(payload: T, secret: string): Promise<string>;
+/** Verify a token's signature and expiry; returns the payload, or `null` for anything
+ * malformed, forged, or expired. The caller decides what the payload authorizes — this
+ * only attests that we minted it and that it is still in date. */
+export declare function verifyToken<T extends ExpiringToken>(raw: string, secret: string): Promise<T | null>;
+/** A signing secret must be present and non-trivial, else tokens are forgeable (an HMAC
+ * over an empty or weak key). Below this length the feature is treated as UNCONFIGURED and
+ * fails closed, rather than minting urls that anyone can forge. */
+export declare const MIN_TOKEN_SECRET_LEN = 16;
+export declare function isUsableSecret(secret: unknown): secret is string;
+/** Resolve a signing secret from env by preference order, skipping any that is absent or
+ * too weak. Returns `undefined` when nothing usable is configured — callers fail closed. */
+export declare function resolveSecret(env: Readonly<Record<string, unknown>>, names: readonly string[]): string | undefined;

package/dist/runtime/token.js

@@ -0,0 +1,88 @@
+// Signed, self-expiring capability tokens (HMAC-SHA256 over a JSON payload).
+//
+// pramen already owns the edge and a secret, so a capability url needs no session and no
+// store: the payload IS the grant, and the signature is what makes it unforgeable. Signed
+// file urls were the first user (`runtime/storage.ts`); page preview links are the second
+// (`@pramen/cms`). Both mint in a handler and redeem in the Worker, unauthenticated.
+//
+// Pure WebCrypto — synchronous in the sense that matters (no stream I/O), so it is safe to
+// call from inside the DO's storage.transaction().
+//
+// A token is `<b64url(json)>.<b64url(sig)>`. It is deliberately NOT a JWT: no alg field to
+// confuse, no header to downgrade, one algorithm, verified before the payload is parsed.
+export function bytesToB64url(bytes) {
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+export function b64urlToBytes(s) {
+    const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+export const strToB64url = (s) => bytesToB64url(new TextEncoder().encode(s));
+export const b64urlToStr = (s) => new TextDecoder().decode(b64urlToBytes(s));
+async function hmacKey(secret) {
+    return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+        "sign",
+        "verify",
+    ]);
+}
+/** Sign a payload into a capability token. */
+export async function signToken(payload, secret) {
+    const data = strToB64url(JSON.stringify(payload));
+    const key = await hmacKey(secret);
+    const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+    return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+/** Verify a token's signature and expiry; returns the payload, or `null` for anything
+ * malformed, forged, or expired. The caller decides what the payload authorizes — this
+ * only attests that we minted it and that it is still in date. */
+export async function verifyToken(raw, secret) {
+    const dot = raw.indexOf(".");
+    if (dot < 0)
+        return null;
+    const data = raw.slice(0, dot);
+    const sig = raw.slice(dot + 1);
+    let ok;
+    try {
+        const key = await hmacKey(secret);
+        ok = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), new TextEncoder().encode(data));
+    }
+    catch {
+        return null;
+    }
+    if (!ok)
+        return null;
+    let payload;
+    try {
+        payload = JSON.parse(b64urlToStr(data));
+    }
+    catch {
+        return null;
+    }
+    if (typeof payload.exp !== "number" || Math.floor(Date.now() / 1000) >= payload.exp)
+        return null;
+    return payload;
+}
+/** A signing secret must be present and non-trivial, else tokens are forgeable (an HMAC
+ * over an empty or weak key). Below this length the feature is treated as UNCONFIGURED and
+ * fails closed, rather than minting urls that anyone can forge. */
+export const MIN_TOKEN_SECRET_LEN = 16;
+export function isUsableSecret(secret) {
+    return typeof secret === "string" && secret.length >= MIN_TOKEN_SECRET_LEN;
+}
+/** Resolve a signing secret from env by preference order, skipping any that is absent or
+ * too weak. Returns `undefined` when nothing usable is configured — callers fail closed. */
+export function resolveSecret(env, names) {
+    for (const name of names) {
+        const v = env[name];
+        if (isUsableSecret(v))
+            return v;
+    }
+    return undefined;
+}

package/dist/sdk/handlers.d.ts

@@ -34,6 +34,13 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
     readonly env: EnvBag;
     /** Resolved identity for this request (null = anonymous). */
     readonly identity: Identity | null;
+    /** The tenant this request is for (the `x-pramen-tenant` value; `"main"` by default).
+     * Server-resolved, never caller-supplied — safe to embed in a signed capability. */
+    readonly tenant: string;
+    /** Which substrate is serving this request: `"do"` (a Durable Object) or `"d1"`. Only
+     * the DO path has a stub the Worker can call back into, so a handler minting a
+     * capability redeemed through `callPrivileged` must refuse on `"d1"`. */
+    readonly store: "do" | "d1";
     /** Deferred side-effects (a transactional outbox). `tasks.enqueue` persists a task
      * row in the SAME transaction as a mutation (atomic with the data write); a drainer
      * runs the matching `app.tasks` handler after commit, off the write path, with

package/dist/worker.js

@@ -177,7 +177,9 @@ export function makeWorker(app) {
         const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
         const kv = new Kv(env.KV);
         const bag = envBag(env);
-        return { db, kv, files, env: bag, identity, tasks: tasksFacade(driver), mail: createMail(bag, kv), queue: createQueue(bag) };
+        // The D1 store is not per-tenant addressed (one shared database, no DO), so the
+        // task context runs as the default tenant — matching the `files` scope just above.
+        return { db, kv, files, env: bag, identity, tenant: "main", store: "d1", tasks: tasksFacade(driver), mail: createMail(bag, kv), queue: createQueue(bag) };
     };
     /** 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). */
@@ -423,7 +425,9 @@ export function makeWorker(app) {
                 const bag = envBag(env);
                 try {
                     await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
-                    const { result, enqueued } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, bag, { acl: d1Acl, identity }, name, input);
+                    // `tenant` matters here: a handler minting a tenant-scoped capability (a signed
+                    // preview link) would otherwise stamp it "main" while reading acme's rows.
+                    const { result, enqueued } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, bag, { acl: d1Acl, identity, tenant, store: "d1" }, name, input);
                     // Kick an immediate drain in the request tail when this handler enqueued tasks
                     // (e.g. sendMagicLinkEmail). Without this, tasks wait for the next Cron trigger
                     // — up to a full minute. `waitUntil` lets the response return now while the

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.49",
-  "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
+  "version": "0.0.51",
+  "description": "pramen server runtime \u2014 schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -26,6 +26,13 @@
       "workerd": "./src/worker-entry.ts",
       "types": "./dist/worker-entry.d.ts",
       "default": "./dist/worker-entry.js"
+    },
+    "./dev": {
+      "development": "./src/dev.ts",
+      "bun": "./src/dev.ts",
+      "workerd": "./src/dev.ts",
+      "types": "./dist/dev.d.ts",
+      "default": "./dist/dev.js"
     }
   },
   "main": "./dist/index.js",
@@ -33,7 +40,10 @@
   "bin": {
     "pramen": "./dist/cli.js"
   },
-  "files": ["dist", "src"],
+  "files": [
+    "dist",
+    "src"
+  ],
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.build.json"
   },

package/src/cli.ts

@@ -23,38 +23,12 @@ import { createTableSql } from "./runtime/ddl";
 import { schemaHash } from "./runtime/migrate";
 import { diffSchemaFingerprint, schemaFingerprint, type SchemaFingerprint } from "./runtime/schema-diff";
 import { entitiesInPartition, partitionsOf, type SchemaDef } from "./sdk/schema";
+import { signDevToken } from "./runtime/dev-token";
 
-/** 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));
-
-/** The dev JWT claims `pramen token` mints. */
+/** The dev JWT claims `pramen token` mints. See `runtime/dev-token.ts` for the signer. */
 type TokenClaims = { sub: string; roles: string[]; tenants?: string[] };
 
-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))}`;
-}
+const sign = (payload: Record<string, unknown>): Promise<string> => signDevToken(payload);
 
 /** 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

package/src/dev.ts

@@ -0,0 +1,10 @@
+// `@pramen/server/dev` — tooling helpers, deliberately NOT on the authoring entry point.
+//
+// `signDevToken` mints an HS256 JWT for local development: the `pramen` and `pramen-cms`
+// bins and the repo's test helper all use it. It is kept off `@pramen/server` because its
+// secret lookup reads `process.env.AUTH_SECRET`, which does not exist in a deployed
+// Worker (bindings and secrets arrive on `env`) — so an app handler importing it from the
+// main entry would silently sign with the PUBLISHED dev constant while appearing to honour
+// AUTH_SECRET. A separate subpath makes "this is dev tooling" part of the import.
+
+export { signDevToken, DEV_SECRET } from "./runtime/dev-token";

package/src/durable-object.ts

@@ -263,6 +263,8 @@ export class PramenDOBase extends DurableObject<DoEnv> {
       files: this.filesFor(this.tenant),
       env: this.envBag,
       identity,
+      tenant: this.tenant,
+      store: "do",
       tasks: tasksFacade(this.driver),
       mail: createMail(this.envBag, this.kv),
       queue: createQueue(this.envBag),
@@ -601,7 +603,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     // Carry the schema so any consumer of this context (not just Db) can compile
     // relation-aware `where` rules into subqueries, and the active partition so Db's
     // table-access guard rejects any table outside this DO's partition.
-    return { acl: this.acl, identity, schema: this.app.schema, partition };
+    return { acl: this.acl, identity, schema: this.app.schema, partition, tenant: this.tenant };
   }
 
   // The DO env (bindings + vars + secrets) handed to handlers as ctx.env. Loosely

package/src/index.ts

@@ -8,7 +8,7 @@
 // and codegen load an app.ts for its schema without dragging in the DO runtime.
 
 // --- schema authoring ---
-export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger } from "./sdk/schema";
+export { Entity, defineSchema, renamedFrom, notNull, unique, indexed, hidden, defaultTo, primaryKey, generated, expr, ExprDefault, trigger, partitionOf, DEFAULT_PARTITION } from "./sdk/schema";
 export type { TriggerDef, TriggerOp } from "./sdk/schema";
 export { isValidUuid } from "./sdk/uuid";
 export type {
@@ -82,6 +82,12 @@ export { Kv, denySession, allowSession, isSessionDenied } from "./runtime/kv";
 // --- files ---
 export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
 export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+
+// Signed capability tokens (HMAC-SHA256) — the machinery behind signed file urls and
+// page-preview links. Exported so an app (or @pramen/cms) can mint its own capability url
+// without a second signing implementation.
+export { signToken, verifyToken, isUsableSecret, resolveSecret, MIN_TOKEN_SECRET_LEN } from "./runtime/token";
+export type { ExpiringToken } from "./runtime/token";
 export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
 
 // --- mail (ctx.mail) ---
@@ -95,7 +101,7 @@ export { routeQueue, dispatchQueueBatch } from "./runtime/queue-consumer";
 export type { QueueContext, QueueHandler, QueueMessage, QueueBatch, AppQueueMap } from "./runtime/queue-consumer";
 
 // --- errors ---
-export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
+export { PramenError, BadRequest, Unauthorized, Forbidden, Conflict } from "./runtime/errors";
 
 // --- substrate seam (advanced: bring your own SQL backend) ---
 export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";

package/src/runtime/acl.ts

@@ -64,6 +64,14 @@ export interface AclContext {
   /** The app schema — lets `where` rules traverse relations (`{ rel: { col } }`),
    * compiled to a subquery with the related entity's read scope AND-merged in. */
   readonly schema?: SchemaDef;
+  /** The tenant this request is for — the `x-pramen-tenant` value the DO was addressed
+   * with. Carried so a handler can mint a tenant-scoped capability (e.g. a signed page
+   * preview link) without the caller supplying, and thus being able to forge, a tenant. */
+  readonly tenant?: string;
+  /** Which substrate is serving this request — `"do"` (a Durable Object, the default) or
+   * `"d1"` (the shared D1 database, selected per-request with `x-pramen-store: d1`). A
+   * handler needs this when a capability it mints can only be redeemed on one of them. */
+  readonly store?: "do" | "d1";
   /** The partition this DO serves. When set, Db rejects any access to a table that
    * lives in a different partition (a partition-DO only owns its own tables). Unset
    * (e.g. the D1/Worker shared-store path) disables the guard — a no-op. */

package/src/runtime/dev-token.ts

@@ -0,0 +1,36 @@
+// Mint an HS256 JWT for local development and tooling — what a real auth service would
+// issue, without running one.
+//
+// Extracted because it was already written twice (the `pramen` CLI and the repo's test
+// helper) and `@pramen/cms`'s own bin would have been a third. One implementation, in the
+// package that owns tokens.
+//
+// NOT an auth system: the dev fallback secret is public, so a token signed with it is
+// worthless anywhere `AUTH_SECRET` is set to something real. That is the point — it makes
+// a forgotten secret fail loudly rather than quietly accept dev tokens in production.
+
+/** The scaffolded oblaka.ts dev secret. Used only when AUTH_SECRET is unset. */
+export 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): string => bytesToB64url(new TextEncoder().encode(s));
+
+/** Sign a dev JWT (1h). Secret: the `secret` argument, else `AUTH_SECRET`, else DEV_SECRET. */
+export async function signDevToken(payload: Record<string, unknown>, secret?: string): Promise<string> {
+  // `||`, not `??`: an AUTH_SECRET set to the empty string previously fell through to
+  // DEV_SECRET, and signing with an empty HMAC key instead would produce tokens the server
+  // rejects with no useful message.
+  const env = (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env;
+  const key = secret || 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 cryptoKey = await crypto.subtle.importKey("raw", new TextEncoder().encode(key), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  const sig = await crypto.subtle.sign("HMAC", cryptoKey, new TextEncoder().encode(data));
+  return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}

package/src/runtime/dispatch.ts

@@ -92,6 +92,8 @@ export async function dispatch(
     files,
     env,
     identity: acl.identity,
+    tenant: acl.tenant ?? "main",
+    store: acl.store ?? "do",
     tasks: tasksFacade(driver, () => enqueued++),
     mail: createMail(env, kv),
     queue: createQueue(env),

package/src/runtime/errors.ts

@@ -34,6 +34,15 @@ export class Forbidden extends PramenError {
   }
 }
 
+/** 409 — the request conflicts with the current state of the resource. For
+ * optimistic concurrency (a stale `expectedVersion`) and for uniqueness clashes the
+ * caller could resolve by retrying with different input. */
+export class Conflict extends PramenError {
+  constructor(message = "conflict") {
+    super(message, 409, "conflict");
+  }
+}
+
 export interface ErrorBody {
   ok: false;
   error: string;

package/src/runtime/storage.ts

@@ -17,6 +17,7 @@
 
 import { BadRequest, PramenError } from "./errors";
 import type { Files, FileRef, HeadResult } from "../sdk/files";
+import { signToken, verifyToken, isUsableSecret, MIN_TOKEN_SECRET_LEN, type ExpiringToken } from "./token";
 
 // The portable type surface (FileRef, Files, sign opts) lives in sdk/files.ts;
 // re-export it here so runtime callers have one import site.
@@ -118,72 +119,25 @@ function bytesToStream(bytes: Uint8Array): ReadableStream {
   });
 }
 
-// --- base64url (shared shape with auth.ts/jwt.ts) ---
-
-function bytesToB64url(bytes: Uint8Array): string {
-  let bin = "";
-  for (const b of bytes) bin += String.fromCharCode(b);
-  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function b64urlToBytes(s: string): Uint8Array {
-  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
-  const bin = atob(b64);
-  const out = new Uint8Array(bin.length);
-  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
-  return out;
-}
-const strToB64url = (s: string) => bytesToB64url(new TextEncoder().encode(s));
-const b64urlToStr = (s: string) => new TextDecoder().decode(b64urlToBytes(s));
-
-// --- signed file tokens (HMAC-SHA256) ---
+// --- signed file tokens ---
+//
+// The HMAC/base64url machinery is shared with page-preview links and anything else that
+// needs a signed capability url; it lives in runtime/token.ts. This file only declares
+// what a FILE token carries.
 
-interface FileToken {
+interface FileToken extends ExpiringToken {
   /** tenant */ t: string;
   /** key */ k: string;
   /** op */ op: "get" | "put";
-  /** expiry (epoch seconds) */ exp: number;
   /** content-type (put: enforced; get: disposition hint) */ ct?: string;
   /** max size in bytes (put only) */ max?: number;
   /** filename (download disposition) */ fn?: string;
 }
 
-async function hmacKey(secret: string): Promise<CryptoKey> {
-  return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
-    "sign",
-    "verify",
-  ]);
-}
-
-async function signToken(token: FileToken, secret: string): Promise<string> {
-  const data = strToB64url(JSON.stringify(token));
-  const key = await hmacKey(secret);
-  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
-  return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
-}
+const signFileToken = (token: FileToken, secret: string): Promise<string> => signToken(token, secret);
 
 /** Verify a file token's signature + expiry; returns the payload or null. */
-export async function verifyToken(raw: string, secret: string): Promise<FileToken | null> {
-  const dot = raw.indexOf(".");
-  if (dot < 0) return null;
-  const data = raw.slice(0, dot);
-  const sig = raw.slice(dot + 1);
-  let ok: boolean;
-  try {
-    const key = await hmacKey(secret);
-    ok = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), new TextEncoder().encode(data));
-  } catch {
-    return null;
-  }
-  if (!ok) return null;
-  let payload: FileToken;
-  try {
-    payload = JSON.parse(b64urlToStr(data));
-  } catch {
-    return null;
-  }
-  if (typeof payload.exp !== "number" || Math.floor(Date.now() / 1000) >= payload.exp) return null;
-  return payload;
-}
+export const verifyFileToken = (raw: string, secret: string): Promise<FileToken | null> => verifyToken<FileToken>(raw, secret);
 
 // --- key generation ---
 
@@ -247,10 +201,8 @@ export interface FilesConfig {
  * would be forgeable (HMAC over an empty/weak key). Below this, file storage is
  * treated as unconfigured — fail closed rather than mint forgeable urls. The dev
  * defaults satisfy it; production should set a strong, random FILES_SECRET. */
-export const MIN_FILES_SECRET_LEN = 16;
-export function isUsableFilesSecret(secret: string | undefined | null): secret is string {
-  return typeof secret === "string" && secret.length >= MIN_FILES_SECRET_LEN;
-}
+export const MIN_FILES_SECRET_LEN = MIN_TOKEN_SECRET_LEN;
+export const isUsableFilesSecret = isUsableSecret;
 const filesUnconfigured = () =>
   new PramenError("file storage is not configured (set a strong FILES_SECRET)", 503, "unavailable");
 
@@ -271,7 +223,7 @@ export function createFiles(cfg: FilesConfig): Files {
       const seg = opts.prefix ? `${safePrefix(opts.prefix)}/` : "";
       const key = `${prefix}${seg}${randomKeySuffix()}`;
       const exp = Math.floor(Date.now() / 1000) + (opts.expiresIn ?? 900);
-      const token = await signToken({ t: cfg.tenant, k: key, op: "put", exp, ct, max: opts.maxSize, fn: opts.filename }, cfg.secret);
+      const token = await signFileToken({ t: cfg.tenant, k: key, op: "put", exp, ct, max: opts.maxSize, fn: opts.filename }, cfg.secret);
       const ref: FileRef = { key, size: 0, contentType: ct, filename: opts.filename, uploadedAt: Date.now() };
       return { url: `${base}/upload?token=${encodeURIComponent(token)}`, ref };
     },
@@ -282,7 +234,7 @@ export function createFiles(cfg: FilesConfig): Files {
       const key = ensureOwnKey(r.key);
       const exp = Math.floor(Date.now() / 1000) + (opts?.expiresIn ?? 3600);
       const fn = opts?.download ? (typeof ref === "string" ? undefined : ref.filename) : undefined;
-      const token = await signToken({ t: cfg.tenant, k: key, op: "get", exp, fn }, cfg.secret);
+      const token = await signFileToken({ t: cfg.tenant, k: key, op: "get", exp, fn }, cfg.secret);
       return { url: `${base}/download?token=${encodeURIComponent(token)}`, expiresAt: exp * 1000 };
     },
 
@@ -327,7 +279,7 @@ export async function handleFileRequest(
 
   const raw = url.searchParams.get("token");
   if (!raw) return fileError(401, "unauthorized", "missing token");
-  const token = await verifyToken(raw, opts.secret);
+  const token = await verifyFileToken(raw, opts.secret);
   if (!token) return fileError(403, "forbidden", "invalid or expired token");
 
   try {

package/src/runtime/token.ts

@@ -0,0 +1,94 @@
+// Signed, self-expiring capability tokens (HMAC-SHA256 over a JSON payload).
+//
+// pramen already owns the edge and a secret, so a capability url needs no session and no
+// store: the payload IS the grant, and the signature is what makes it unforgeable. Signed
+// file urls were the first user (`runtime/storage.ts`); page preview links are the second
+// (`@pramen/cms`). Both mint in a handler and redeem in the Worker, unauthenticated.
+//
+// Pure WebCrypto — synchronous in the sense that matters (no stream I/O), so it is safe to
+// call from inside the DO's storage.transaction().
+//
+// A token is `<b64url(json)>.<b64url(sig)>`. It is deliberately NOT a JWT: no alg field to
+// confuse, no header to downgrade, one algorithm, verified before the payload is parsed.
+
+/** Every signed token carries an expiry (epoch seconds); `verifyToken` enforces it. */
+export interface ExpiringToken {
+  exp: number;
+}
+
+export function bytesToB64url(bytes: Uint8Array): string {
+  let bin = "";
+  for (const b of bytes) bin += String.fromCharCode(b);
+  return btoa(bin).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+export function b64urlToBytes(s: string): Uint8Array {
+  const b64 = s.replace(/-/g, "+").replace(/_/g, "/") + "=".repeat((4 - (s.length % 4)) % 4);
+  const bin = atob(b64);
+  const out = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i);
+  return out;
+}
+
+export const strToB64url = (s: string): string => bytesToB64url(new TextEncoder().encode(s));
+export const b64urlToStr = (s: string): string => new TextDecoder().decode(b64urlToBytes(s));
+
+async function hmacKey(secret: string): Promise<CryptoKey> {
+  return crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, [
+    "sign",
+    "verify",
+  ]);
+}
+
+/** Sign a payload into a capability token. */
+export async function signToken<T extends ExpiringToken>(payload: T, secret: string): Promise<string> {
+  const data = strToB64url(JSON.stringify(payload));
+  const key = await hmacKey(secret);
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data));
+  return `${data}.${bytesToB64url(new Uint8Array(sig))}`;
+}
+
+/** Verify a token's signature and expiry; returns the payload, or `null` for anything
+ * malformed, forged, or expired. The caller decides what the payload authorizes — this
+ * only attests that we minted it and that it is still in date. */
+export async function verifyToken<T extends ExpiringToken>(raw: string, secret: string): Promise<T | null> {
+  const dot = raw.indexOf(".");
+  if (dot < 0) return null;
+  const data = raw.slice(0, dot);
+  const sig = raw.slice(dot + 1);
+  let ok: boolean;
+  try {
+    const key = await hmacKey(secret);
+    ok = await crypto.subtle.verify("HMAC", key, b64urlToBytes(sig), new TextEncoder().encode(data));
+  } catch {
+    return null;
+  }
+  if (!ok) return null;
+  let payload: T;
+  try {
+    payload = JSON.parse(b64urlToStr(data)) as T;
+  } catch {
+    return null;
+  }
+  if (typeof payload.exp !== "number" || Math.floor(Date.now() / 1000) >= payload.exp) return null;
+  return payload;
+}
+
+/** A signing secret must be present and non-trivial, else tokens are forgeable (an HMAC
+ * over an empty or weak key). Below this length the feature is treated as UNCONFIGURED and
+ * fails closed, rather than minting urls that anyone can forge. */
+export const MIN_TOKEN_SECRET_LEN = 16;
+
+export function isUsableSecret(secret: unknown): secret is string {
+  return typeof secret === "string" && secret.length >= MIN_TOKEN_SECRET_LEN;
+}
+
+/** Resolve a signing secret from env by preference order, skipping any that is absent or
+ * too weak. Returns `undefined` when nothing usable is configured — callers fail closed. */
+export function resolveSecret(env: Readonly<Record<string, unknown>>, names: readonly string[]): string | undefined {
+  for (const name of names) {
+    const v = env[name];
+    if (isUsableSecret(v)) return v;
+  }
+  return undefined;
+}

package/src/sdk/handlers.ts

@@ -40,6 +40,13 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
   readonly env: EnvBag;
   /** Resolved identity for this request (null = anonymous). */
   readonly identity: Identity | null;
+  /** The tenant this request is for (the `x-pramen-tenant` value; `"main"` by default).
+   * Server-resolved, never caller-supplied — safe to embed in a signed capability. */
+  readonly tenant: string;
+  /** Which substrate is serving this request: `"do"` (a Durable Object) or `"d1"`. Only
+   * the DO path has a stub the Worker can call back into, so a handler minting a
+   * capability redeemed through `callPrivileged` must refuse on `"d1"`. */
+  readonly store: "do" | "d1";
   /** Deferred side-effects (a transactional outbox). `tasks.enqueue` persists a task
    * row in the SAME transaction as a mutation (atomic with the data write); a drainer
    * runs the matching `app.tasks` handler after commit, off the write path, with

package/src/worker.ts

@@ -243,7 +243,9 @@ export function makeWorker(app: PramenApp) {
     const db = new Db(driver, { acl: d1Acl, identity, system: true, schema: app.schema, suppressTriggers: true }, app.schema);
     const kv = new Kv(env.KV);
     const bag = envBag(env);
-    return { db, kv, files, env: bag, identity, tasks: tasksFacade(driver), mail: createMail(bag, kv), queue: createQueue(bag) };
+    // The D1 store is not per-tenant addressed (one shared database, no DO), so the
+    // task context runs as the default tenant — matching the `files` scope just above.
+    return { db, kv, files, env: bag, identity, tenant: "main", store: "d1", tasks: tasksFacade(driver), mail: createMail(bag, kv), queue: createQueue(bag) };
   };
 
   /** Drain the D1 outbox in the Worker (no DO/alarm on this path) — called by the
@@ -501,7 +503,9 @@ export function makeWorker(app: PramenApp) {
       const bag = envBag(env);
       try {
         await ensureD1Migrated(driver, env.PRAMEN_ALLOW_DESTRUCTIVE === "true");
-        const { result, enqueued } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, bag, { acl: d1Acl, identity }, name, input);
+        // `tenant` matters here: a handler minting a tenant-scoped capability (a signed
+        // preview link) would otherwise stamp it "main" while reading acme's rows.
+        const { result, enqueued } = await dispatch(app.handlers, app.schema, driver, new Kv(env.KV), files, bag, { acl: d1Acl, identity, tenant, store: "d1" }, name, input);
         // Kick an immediate drain in the request tail when this handler enqueued tasks
         // (e.g. sendMagicLinkEmail). Without this, tasks wait for the next Cron trigger
         // — up to a full minute. `waitUntil` lets the response return now while the