@pramen/server 0.0.48 → 0.0.50

package/src/runtime/read-engine.ts

@@ -6,11 +6,14 @@
 // AND/OR groups) and ACL row-level scopes be merged before compilation. Column
 // names come from developer code (schema keys); values are always parameterized.
 
+import type { WhereRule, WhereValue } from "../sdk/acl";
+import type { CellValue, Row } from "../sdk/infer";
+
 import type { Dialect } from "./driver";
 
 // In-process value coercion for evalExpr (SQLite-style booleans). SQL-side encoding
 // goes through the active Dialect; this mirrors it for the cell-ACL `when` evaluator.
-function bind(v: unknown): unknown {
+function bind(v: CellValue): CellValue {
   return typeof v === "boolean" ? (v ? 1 : 0) : v;
 }
 
@@ -23,8 +26,8 @@ export type StrMode = "contains" | "prefix" | "suffix";
 export type SqlExpr =
   | { t: "true" }
   | { t: "false" }
-  | { t: "cmp"; op: CmpOp; col: string; value: unknown }
-  | { t: "in"; col: string; values: unknown[]; negate: boolean }
+  | { t: "cmp"; op: CmpOp; col: string; value: CellValue }
+  | { t: "in"; col: string; values: CellValue[]; negate: boolean }
   | { t: "null"; col: string; negate: boolean }
   // Structured substring match — the needle is escaped and wrapped, so `%`/`_` in the
   // input match literally (unlike raw `like`, where the caller controls wildcards).
@@ -39,28 +42,28 @@ export type SqlExpr =
 
 export const TRUE: SqlExpr = { t: "true" };
 export const FALSE: SqlExpr = { t: "false" };
-export const cmp = (op: CmpOp, col: string, value: unknown): SqlExpr => ({ t: "cmp", op, col, value });
+export const cmp = (op: CmpOp, col: string, value: CellValue): SqlExpr => ({ t: "cmp", op, col, value });
 export const isNull = (col: string, negate = false): SqlExpr => ({ t: "null", col, negate });
-export const inList = (col: string, values: unknown[], negate = false): SqlExpr => ({ t: "in", col, values, negate });
+export const inList = (col: string, values: CellValue[], negate = false): SqlExpr => ({ t: "in", col, values, negate });
 export const strMatch = (col: string, needle: string, mode: StrMode): SqlExpr => ({ t: "strmatch", col, needle, mode });
 export const and = (...parts: SqlExpr[]): SqlExpr => ({ t: "and", parts });
 export const or = (...parts: SqlExpr[]): SqlExpr => ({ t: "or", parts });
 export const not = (expr: SqlExpr): SqlExpr => ({ t: "not", expr });
 
 /** Equality (null -> IS NULL). Used by ACL scope building and relation loads. */
-export const eq = (col: string, value: unknown): SqlExpr => (value === null ? isNull(col) : cmp("=", col, value));
+export const eq = (col: string, value: CellValue): SqlExpr => (value === null ? isNull(col) : cmp("=", col, value));
 
 /** Compile a structured user predicate into a SqlExpr.
  * Shapes: { col: value } (eq) | { col: { gt, lt, in, like, isNull, … } } | { AND: [...] } | { OR: [...] } */
-export function compileWhere(input: Record<string, unknown>): SqlExpr {
+export function compileWhere(input: WhereRule): SqlExpr {
   const parts: SqlExpr[] = [];
   for (const [k, v] of Object.entries(input)) {
     if (k === "AND") {
-      parts.push(and(...(v as Record<string, unknown>[]).map(compileWhere)));
+      parts.push(and(...(v as WhereRule[]).map(compileWhere)));
     } else if (k === "OR") {
-      parts.push(or(...(v as Record<string, unknown>[]).map(compileWhere)));
+      parts.push(or(...(v as WhereRule[]).map(compileWhere)));
     } else if (k === "NOT") {
-      parts.push(not(compileWhere(v as Record<string, unknown>)));
+      parts.push(not(compileWhere(v as WhereRule)));
     } else {
       parts.push(columnPredicate(k, v));
     }
@@ -68,10 +71,13 @@ export function compileWhere(input: Record<string, unknown>): SqlExpr {
   return parts.length ? and(...parts) : TRUE;
 }
 
-function columnPredicate(col: string, v: unknown): SqlExpr {
+function columnPredicate(col: string, v: WhereValue): SqlExpr {
   if (v !== null && typeof v === "object" && !Array.isArray(v)) {
     const ops: SqlExpr[] = [];
-    for (const [op, val] of Object.entries(v as Record<string, unknown>)) {
+    for (const [op, operand] of Object.entries(v as WhereRule)) {
+      // Markers are resolved upstream (runtime/acl.ts), so an operator's operand is a
+      // literal cell value by this point.
+      const val = operand as CellValue;
       switch (op) {
         case "eq": ops.push(eq(col, val)); break;
         case "ne": ops.push(val === null ? isNull(col, true) : cmp("!=", col, val)); break;
@@ -83,23 +89,23 @@ function columnPredicate(col: string, v: unknown): SqlExpr {
         case "contains": ops.push(strMatch(col, String(val), "contains")); break;
         case "startsWith": ops.push(strMatch(col, String(val), "prefix")); break;
         case "endsWith": ops.push(strMatch(col, String(val), "suffix")); break;
-        case "in": ops.push(inList(col, val as unknown[])); break;
-        case "notIn": ops.push(inList(col, val as unknown[], true)); break;
+        case "in": ops.push(inList(col, val as CellValue[])); break;
+        case "notIn": ops.push(inList(col, val as CellValue[], true)); break;
         case "isNull": ops.push(isNull(col, !val)); break; // isNull:true => IS NULL
         default: throw new Error(`unknown operator: ${op}`);
       }
     }
     return ops.length ? and(...ops) : TRUE;
   }
-  return eq(col, v);
+  return eq(col, v as CellValue);
 }
 
 export interface CompiledSql {
   readonly sql: string;
-  readonly params: unknown[];
+  readonly params: CellValue[];
 }
 
-export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] = []): CompiledSql {
+export function compileExpr(expr: SqlExpr, dialect: Dialect, params: CellValue[] = []): CompiledSql {
   switch (expr.t) {
     case "true":
       return { sql: "1", params };
@@ -168,7 +174,7 @@ function likeToRegex(pattern: string): RegExp {
  * semantics (bound-boolean coercion, NULL compares false, empty-IN, LIKE) so the
  * declarative cell-ACL `when` path can decide per-row field visibility without a
  * round-trip to SQLite. */
-export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
+export function evalExpr(expr: SqlExpr, row: Row): boolean {
   switch (expr.t) {
     case "true":
       return true;
@@ -245,7 +251,7 @@ export type AggFn = "count" | "sum" | "avg" | "min" | "max";
 const AGG_SQL: Record<AggFn, string> = { count: "COUNT", sum: "SUM", avg: "AVG", min: "MIN", max: "MAX" };
 
 export function compileCount(from: string, dialect: Dialect, where?: SqlExpr): CompiledSql {
-  const params: unknown[] = [];
+  const params: CellValue[] = [];
   let sql = `SELECT COUNT(*) AS n FROM ${dialect.id(from)}`;
   if (where && where.t !== "true") sql += ` WHERE ${compileExpr(where, dialect, params).sql}`;
   return { sql, params };
@@ -265,7 +271,7 @@ export function compileAggregate(
   },
   dialect: Dialect,
 ): CompiledSql {
-  const params: unknown[] = [];
+  const params: CellValue[] = [];
   const cols: string[] = [];
   for (const g of spec.groupBy ?? []) cols.push(dialect.id(g));
   for (const [key, agg] of Object.entries(spec.aggregations)) {
@@ -279,7 +285,7 @@ export function compileAggregate(
 }
 
 export function compileSelect(spec: QuerySpec, dialect: Dialect): CompiledSql {
-  const params: unknown[] = [];
+  const params: CellValue[] = [];
   const cols = spec.columns && spec.columns.length > 0 ? spec.columns.map((c) => dialect.id(c)).join(", ") : "*";
   let sql = `SELECT ${cols} FROM ${dialect.id(spec.from)}`;
 

package/src/runtime/registry.ts

@@ -79,7 +79,11 @@ export function parseRegistryKey(key: string): DoRef | null {
 /** Enumerate every registered `(tenant, partition)` pair from the registry KV.
  * Paginates over the full listing (cursor / list_complete) — never truncates at the
  * 1000-key page limit. */
-export async function listDOs(kv: KVNamespace): Promise<DoRef[]> {
+/** The slice of KV that DO enumeration needs — narrower than the whole namespace, so
+ * callers (and test doubles) only have to provide `list`. */
+export type KvLister = Pick<KVNamespace, "list">;
+
+export async function listDOs(kv: KvLister): Promise<DoRef[]> {
   const out: DoRef[] = [];
   let cursor: string | undefined;
   for (;;) {

package/src/runtime/schema-diff.ts

@@ -21,7 +21,7 @@ import type { FieldDef, SchemaDef } from "../sdk/schema";
 import { partitionOf } from "../sdk/schema";
 
 /** The comparable fingerprint of a single column: type + migration-relevant modifiers. */
-export interface ColumnShape {
+export interface ColumnFingerprint {
   type: string;
   notNull?: boolean;
   unique?: boolean;
@@ -33,16 +33,16 @@ export interface ColumnShape {
 }
 
 /** The comparable fingerprint of a table: its partition + each column's shape. */
-export interface TableShape {
+export interface TableFingerprint {
   partition: string;
-  columns: Record<string, ColumnShape>;
+  columns: Record<string, ColumnFingerprint>;
 }
 
 /** table -> table shape. The comparable surface of a schema. */
-export type SchemaShape = Record<string, TableShape>;
+export type SchemaFingerprint = Record<string, TableFingerprint>;
 
-function columnShape(f: FieldDef): ColumnShape {
-  const c: ColumnShape = { type: f.type };
+function columnFingerprint(f: FieldDef): ColumnFingerprint {
+  const c: ColumnFingerprint = { type: f.type };
   if (f.notNull) c.notNull = true;
   if (f.unique) c.unique = true;
   if (f.primaryKey) c.primaryKey = true;
@@ -53,27 +53,27 @@ function columnShape(f: FieldDef): ColumnShape {
   return c;
 }
 
-export function schemaShape(schema: SchemaDef): SchemaShape {
-  const out: SchemaShape = {};
+export function schemaFingerprint(schema: SchemaDef): SchemaFingerprint {
+  const out: SchemaFingerprint = {};
   for (const [table, def] of Object.entries(schema)) {
-    const columns: Record<string, ColumnShape> = {};
-    for (const [col, f] of Object.entries(def.fields)) columns[col] = columnShape(f as FieldDef);
+    const columns: Record<string, ColumnFingerprint> = {};
+    for (const [col, f] of Object.entries(def.fields)) columns[col] = columnFingerprint(f as FieldDef);
     out[table] = { partition: partitionOf(schema, table), columns };
   }
   return out;
 }
 
 /** The modifier fields compared for a `change-column` (everything but `type`). */
-const MODIFIER_KEYS: (keyof ColumnShape)[] = ["notNull", "unique", "primaryKey", "generated", "hidden", "default"];
+const MODIFIER_KEYS: (keyof ColumnFingerprint)[] = ["notNull", "unique", "primaryKey", "generated", "hidden", "default"];
 
 /** Does `next` tighten a constraint `prev` lacked (add NOT NULL / UNIQUE / PRIMARY KEY)?
  * Such a change may require the destructive gate or be skipped when the live data
  * conflicts (NULL rows / duplicates) — so the diff flags it `destructive`. */
-function tightensConstraint(prev: ColumnShape, next: ColumnShape): boolean {
+function tightensConstraint(prev: ColumnFingerprint, next: ColumnFingerprint): boolean {
   return (!!next.notNull && !prev.notNull) || (!!next.unique && !prev.unique) || (!!next.primaryKey && !prev.primaryKey);
 }
 
-function modifierDiff(prev: ColumnShape, next: ColumnShape): string | null {
+function modifierDiff(prev: ColumnFingerprint, next: ColumnFingerprint): string | null {
   const parts: string[] = [];
   for (const k of MODIFIER_KEYS) {
     if (prev[k] !== next[k]) parts.push(`${k}: ${fmt(prev[k])} → ${fmt(next[k])}`);
@@ -102,7 +102,7 @@ export interface SchemaChange {
   appliesOnBoot: boolean;
 }
 
-export function diffSchemaShape(prev: SchemaShape, next: SchemaShape): SchemaChange[] {
+export function diffSchemaFingerprint(prev: SchemaFingerprint, next: SchemaFingerprint): SchemaChange[] {
   const changes: SchemaChange[] = [];
 
   for (const table of Object.keys(next)) {

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/acl.ts

@@ -6,6 +6,8 @@
 // and/or a set of permitted `fields`. Access is deny-by-default; policies only
 // ever grant. Across the identity's roles, grants OR-merge (any role can allow).
 
+import type { CellValue, JsonValue, Row } from "./infer";
+
 export type Action = "read" | "create" | "update" | "delete";
 
 /** Runtime identity. Augment with your own properties (userId, tier, …). */
@@ -17,7 +19,7 @@ export interface Identity {
    * expiry per message (see durable-object.ts). Absent for non-expiring / synthetic
    * (callPrivileged) identities, which are therefore never treated as expired. */
   exp?: number;
-  [key: string]: unknown;
+  [key: string]: JsonValue | undefined;
 }
 
 // --- $identity markers: reference an identity property inside a where rule ---
@@ -34,8 +36,8 @@ export function $identity(path: string): IdentityMarker {
   return { [IDENTITY_MARKER]: true, path };
 }
 
-export function isIdentityMarker(v: unknown): v is IdentityMarker {
-  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[IDENTITY_MARKER] === true;
+export function isIdentityMarker(v: WhereValue): v is IdentityMarker {
+  return typeof v === "object" && v !== null && (v as Partial<IdentityMarker>)[IDENTITY_MARKER] === true;
 }
 
 // --- $input markers: reference a request-input field inside a where rule, for a
@@ -56,8 +58,8 @@ export function $input(path: string): InputMarker {
   return { [INPUT_MARKER]: true, path };
 }
 
-export function isInputMarker(v: unknown): v is InputMarker {
-  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[INPUT_MARKER] === true;
+export function isInputMarker(v: WhereValue): v is InputMarker {
+  return typeof v === "object" && v !== null && (v as Partial<InputMarker>)[INPUT_MARKER] === true;
 }
 
 // --- $now markers: the request's evaluation instant inside a where rule, for a
@@ -88,8 +90,8 @@ export function $now(): NowMarker {
   return { [NOW_MARKER]: true };
 }
 
-export function isNowMarker(v: unknown): v is NowMarker {
-  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[NOW_MARKER] === true;
+export function isNowMarker(v: WhereValue): v is NowMarker {
+  return typeof v === "object" && v !== null && (v as Partial<NowMarker>)[NOW_MARKER] === true;
 }
 
 // --- allow / deny markers ---
@@ -110,8 +112,21 @@ export function deny(): DenyMarker {
 
 // --- policy rules ---
 
-/** A where rule: column -> value, where value may be a literal or an $identity marker. */
-export type WhereRule = Record<string, unknown | IdentityMarker>;
+/** A value inside a `where` rule: a literal cell value, a per-request marker, an
+ * operator object (`{ gte: 5 }`), a nested relation predicate, or an AND/OR group. */
+export type WhereValue =
+  | CellValue
+  | IdentityMarker
+  | InputMarker
+  | NowMarker
+  | WhereRule
+  | WhereValue[];
+
+/** A where rule: column (or `AND`/`OR`/`NOT`) -> value. An interface so it can recur
+ * through `WhereValue` for nested relation predicates and boolean groups. */
+export interface WhereRule {
+  [key: string]: WhereValue;
+}
 
 /** A per-row (cell-level) field grant: `fields` are permitted only for rows that
  * match `when`. Additive over the policy's flat `fields` — a conditional grant can
@@ -125,7 +140,7 @@ export interface ConditionalFields {
 /** Escape hatch for cell-level ACL: a late per-row resolver. Given the identity and
  * the fetched (or candidate, on write) row, returns the extra permitted fields —
  * additive over `fields`; `null` means all fields for that row. */
-export type FieldsFn = (identity: Identity | null, row: Record<string, unknown>) => string[] | null;
+export type FieldsFn = (identity: Identity | null, row: Row) => string[] | null;
 
 /** Per-relation ACL inside a parent read policy. */
 export interface RelationAclRule {
@@ -143,10 +158,10 @@ export interface RelationAclRule {
 }
 
 /** A forced column value on write: a literal, or computed from the identity. */
-export type SetValue = unknown | ((identity: Identity | null) => unknown);
+export type SetValue = CellValue | ((identity: Identity | null) => CellValue);
 
 /** Server-side validation on write; throw to reject. Runs on the final values. */
-export type Validator = (args: { identity: Identity | null; values: Record<string, unknown> }) => void;
+export type Validator = (args: { identity: Identity | null; values: Row }) => void;
 
 export interface PolicyRules {
   /** Row-level predicate (AND of equalities). Omit/empty = all rows. */
@@ -175,10 +190,10 @@ export interface PolicyRules {
 export interface ResolverDb {
   find(spec: {
     from: string;
-    where?: Record<string, unknown>;
+    where?: WhereRule;
     orderBy?: { column: string; dir?: "asc" | "desc" };
     limit?: number;
-  }): Promise<Array<Record<string, unknown>>>;
+  }): Promise<Row[]>;
 }
 
 export interface ResolverContext {

package/src/sdk/handlers.ts

@@ -10,6 +10,13 @@ import type { Queue } from "../runtime/queue";
 import type { Identity } from "./acl";
 import type { Files } from "./files";
 import type { SchemaDef } from "./schema";
+import type { JsonValue } from "./infer";
+
+/** The Worker/DO environment as an open, read-only bag: Cloudflare bindings (KV, R2,
+ * D1, Queues, …) alongside vars and secrets. Deliberately open and opaque — an app
+ * declares its own bindings, so the value type cannot be enumerated here; read a value
+ * and narrow it at the use site (`ctx.env.STRIPE_SECRET_KEY as string`). */
+export type EnvBag = Readonly<Record<string, unknown>>;
 
 export interface HandlerContext<S extends SchemaDef = SchemaDef> {
   /** Schema-typed repository: find/insert/update/delete inferred from S. */
@@ -30,9 +37,16 @@ export interface HandlerContext<S extends SchemaDef = SchemaDef> {
    * Use it to call external services from handlers — Cloudflare bindings (e.g. the
    * `send_email` binding for Cloudflare Email Sending) or third-party APIs (Stripe, …). Loosely typed;
    * cast a value at the use site, e.g. `ctx.env.STRIPE_SECRET_KEY as string`. */
-  readonly env: Readonly<Record<string, unknown>>;
+  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
@@ -119,7 +133,7 @@ export interface Handler<I = unknown, O = unknown> {
   readonly run: (ctx: HandlerContext<any>, input: I) => O | Promise<O>;
   /** Optional boundary validator: parse/validate the raw request input, throwing
    * to reject (surfaced as a 400). Its return type fixes the handler's input. */
-  readonly input?: (raw: unknown) => unknown;
+  readonly input?: (raw: JsonValue) => unknown;
   /** Optional DO partition this handler runs in (static, server-side). The Worker
    * routes the request to the matching partition-DO before dispatch. Absent ⇒ the
    * default partition (routed to the bare tenant key). */
@@ -129,7 +143,7 @@ export interface Handler<I = unknown, O = unknown> {
 }
 
 export interface HandlerOpts<I> {
-  input?: (raw: unknown) => I;
+  input?: (raw: JsonValue) => I;
   /** DO partition this handler runs in. Absent ⇒ the default partition. */
   partition?: string;
   /** Authorization to CALL this handler (see HandlerAuth) — gate non-`ctx.db` handlers. */

package/src/sdk/infer.ts

@@ -11,6 +11,27 @@ export type { FileRef } from "./files";
 /** Any JSON-serializable value — the type of a `t.json()` column. */
 export type JsonValue = string | number | boolean | null | JsonValue[] | { [key: string]: JsonValue };
 
+/** A JSON object — the object arm of `JsonValue`, named so it can be referenced
+ * directly (e.g. an identity's claims, a `t.json()` column's object form). */
+export interface JsonObject {
+  [key: string]: JsonValue;
+}
+
+/** A raw value as the substrate stores/returns it, before pramen's object↔JSON codec.
+ * DO SQLite and D1 hand back exactly these; BLOB columns arrive as an ArrayBuffer. */
+export type SqlValue = string | number | bigint | boolean | null | ArrayBuffer;
+
+/** A decoded column value as handlers see it at the `Db` chokepoint: any JSON value,
+ * a `fileRef` column's metadata, or — for an eager-loaded relation — the related
+ * row(s) grafted onto the parent under the relation name. */
+export type CellValue = SqlValue | JsonValue | FileRef | Row | Row[];
+
+/** A decoded database row — column name -> decoded value. An interface (not a
+ * `Record` alias) so it can recur through `CellValue` for eager-loaded relations. */
+export interface Row {
+  [column: string]: CellValue;
+}
+
 /** SQL field type -> TypeScript value type. */
 export type FieldTsType<D extends FieldDef> = D["type"] extends "text"
   ? string