@pramen/server 0.0.1

package/src/auth.ts

@@ -0,0 +1,215 @@
+// Identity resolution at the edge. The Worker verifies a signed token and
+// forwards a trusted identity to the DO; the DO never re-derives it, and the
+// client-supplied X-Pramen-Identity header is stripped unless a token verified
+// (see src/index.ts), so a validly-signed JWT is the only path to an identity.
+//
+// Verification is pluggable via VerifyStrategy: HmacStrategy (HS256, shared secret
+// in env.AUTH_SECRET) for dev/symmetric setups, JwksStrategy (RS256 against a remote
+// JWKS, with key caching) for real identity providers. The header parse, exp/nbf
+// checks, and claim->Identity mapping are shared; only signature verification
+// differs. Claims map to Identity: `sub` -> userId, `roles`/`role` -> roles, other
+// non-standard claims pass through.
+
+import type { Identity } from "./sdk/acl";
+
+const STANDARD_CLAIMS = new Set(["exp", "iat", "nbf", "iss", "aud", "jti", "sub", "role", "roles", "userId"]);
+
+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;
+}
+
+function b64urlToString(s: string): string {
+  return new TextDecoder().decode(b64urlToBytes(s));
+}
+
+interface JwtHeader {
+  alg?: string;
+  kid?: string;
+}
+
+/** Verifies a JWT and returns its claims, or null if invalid. Implementations
+ * differ only in how they verify the signature. */
+export interface VerifyStrategy {
+  verify(token: string): Promise<Record<string, unknown> | null>;
+}
+
+/** Verify a signature over `${header}.${payload}` for the parsed header. */
+type SignatureVerifier = (signingInput: string, signature: Uint8Array, header: JwtHeader) => Promise<boolean>;
+
+// Shared JWT pipeline: parse, verify the signature via the supplied function, then
+// validate exp/nbf. Any malformed part or a verification throw -> null (reject).
+async function verifyJwt(token: string, verifySignature: SignatureVerifier): Promise<Record<string, unknown> | null> {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [h, p, sig] = parts;
+
+  let header: JwtHeader;
+  try {
+    header = JSON.parse(b64urlToString(h!));
+  } catch {
+    return null;
+  }
+
+  let valid: boolean;
+  try {
+    valid = await verifySignature(`${h}.${p}`, b64urlToBytes(sig!), header);
+  } catch {
+    return null;
+  }
+  if (!valid) return null;
+
+  let payload: Record<string, unknown>;
+  try {
+    payload = JSON.parse(b64urlToString(p!));
+  } catch {
+    return null;
+  }
+
+  const now = Math.floor(Date.now() / 1000);
+  if (typeof payload.exp === "number" && now >= payload.exp) return null;
+  if (typeof payload.nbf === "number" && now < payload.nbf) return null;
+  return payload;
+}
+
+/** HS256 via a shared secret. The dev/default strategy. */
+export class HmacStrategy implements VerifyStrategy {
+  constructor(private readonly secret: string) {}
+
+  verify(token: string): Promise<Record<string, unknown> | null> {
+    return verifyJwt(token, async (input, signature, header) => {
+      if (header.alg !== "HS256" || !this.secret) return false;
+      const key = await crypto.subtle.importKey(
+        "raw",
+        new TextEncoder().encode(this.secret),
+        { name: "HMAC", hash: "SHA-256" },
+        false,
+        ["verify"],
+      );
+      return crypto.subtle.verify("HMAC", key, signature, new TextEncoder().encode(input));
+    });
+  }
+}
+
+interface Jwk extends JsonWebKey {
+  kid?: string;
+}
+
+const SINGLE_KEY = "\0single";
+
+/** RS256 verified against a remote JWKS. Public keys are fetched once and cached
+ * (TTL); a token with an unknown `kid` triggers one forced refetch to pick up key
+ * rotation. Stale keys are kept if a refetch fails. */
+export class JwksStrategy implements VerifyStrategy {
+  private keys = new Map<string, CryptoKey>();
+  private fetchedAt = 0;
+  private inflight: Promise<void> | null = null;
+
+  constructor(
+    readonly url: string,
+    private readonly ttlMs = 600_000,
+  ) {}
+
+  verify(token: string): Promise<Record<string, unknown> | null> {
+    return verifyJwt(token, async (input, signature, header) => {
+      if (header.alg !== "RS256") return false;
+      const key = await this.keyFor(header.kid);
+      if (!key) return false;
+      return crypto.subtle.verify("RSASSA-PKCS1-v1_5", key, signature, new TextEncoder().encode(input));
+    });
+  }
+
+  private lookup(kid?: string): CryptoKey | null {
+    if (kid) return this.keys.get(kid) ?? null;
+    if (this.keys.size === 1) return [...this.keys.values()][0]!; // no kid + single key
+    return this.keys.get(SINGLE_KEY) ?? null;
+  }
+
+  private async keyFor(kid?: string): Promise<CryptoKey | null> {
+    await this.refresh(false);
+    let key = this.lookup(kid);
+    if (!key) {
+      await this.refresh(true); // unknown kid -> force a refetch (key rotation)
+      key = this.lookup(kid);
+    }
+    return key;
+  }
+
+  private async refresh(force: boolean): Promise<void> {
+    if (!force && this.keys.size > 0 && Date.now() - this.fetchedAt < this.ttlMs) return;
+    if (this.inflight) return this.inflight;
+    this.inflight = this.fetchKeys();
+    try {
+      await this.inflight;
+    } finally {
+      this.inflight = null;
+    }
+  }
+
+  private async fetchKeys(): Promise<void> {
+    try {
+      const res = await fetch(this.url);
+      if (!res.ok) return; // keep stale keys
+      const body = (await res.json()) as { keys?: Jwk[] };
+      const next = new Map<string, CryptoKey>();
+      for (const jwk of body.keys ?? []) {
+        if (jwk.kty !== "RSA") continue;
+        const key = await crypto.subtle.importKey(
+          "jwk",
+          jwk,
+          { name: "RSASSA-PKCS1-v1_5", hash: "SHA-256" },
+          false,
+          ["verify"],
+        );
+        next.set(jwk.kid ?? SINGLE_KEY, key);
+      }
+      if (next.size > 0) {
+        this.keys = next;
+        this.fetchedAt = Date.now();
+      }
+    } catch {
+      // network error -> keep whatever keys we have
+    }
+  }
+}
+
+function toIdentity(claims: Record<string, unknown>): Identity {
+  const roles = Array.isArray(claims.roles)
+    ? (claims.roles as string[])
+    : typeof claims.role === "string"
+      ? [claims.role]
+      : [];
+  const identity: Identity = { roles, userId: (claims.sub ?? claims.userId) as string | undefined };
+  for (const [k, v] of Object.entries(claims)) {
+    if (!STANDARD_CLAIMS.has(k)) identity[k] = v; // carry custom claims (tier, …)
+  }
+  return identity;
+}
+
+export async function resolveIdentity(request: Request, strategy: VerifyStrategy): Promise<Identity | null> {
+  const token = request.headers.get("authorization")?.match(/^Bearer\s+(.+)$/i)?.[1];
+  if (!token) return null;
+  const claims = await strategy.verify(token);
+  return claims ? toIdentity(claims) : null;
+}
+
+/** May this identity address the given tenant? Gates `X-Pramen-Tenant` so a caller
+ * can't reach (or register) arbitrary tenants. Default policy: admins → any
+ * tenant; everyone else → only tenants listed in their `tenants` claim. Customize
+ * for your tenancy model (e.g. tenant === identity.org, or a lookup). */
+export function authorizeTenant(identity: Identity | null, tenant: string): boolean {
+  // Anonymous (no verified token) may reach only the default tenant — enough for
+  // first-class public flows (the `anonymous` ACL role still gates the data), while
+  // not letting unauthenticated callers address/register arbitrary tenants.
+  if (!identity) return tenant === "main";
+  if (identity.roles?.includes("admin")) return true;
+  const allowed = Array.isArray(identity.tenants) ? (identity.tenants as string[]) : [];
+  return allowed.includes(tenant);
+}
+
+export function isAdmin(identity: Identity | null): boolean {
+  return identity?.roles?.includes("admin") ?? false;
+}

package/src/durable-object.ts

@@ -0,0 +1,346 @@
+// PramenDOBase — the database. One instance per tenant (see worker.ts routing).
+// Holds the SQLite store in-process, applies the schema on boot, dispatches
+// handler RPCs over HTTP, and serves live queries over WebSockets. The concrete,
+// app-bound class is produced by pramenDO(app) (and createPramen) — the DO can't
+// take constructor args beyond (ctx, env), so the app is closed over.
+//
+// ACL: policies are compiled once on boot. Identity is resolved by the Worker
+// and forwarded in the X-Pramen-Identity header. For HTTP it's per request; for a
+// WebSocket it's fixed at connect time and stored on the socket, so live queries
+// are evaluated per-identity (row-level scopes apply to pushes too).
+//
+// Reactivity: the DO is the single writer, so it sees every mutation. After a
+// mutation commits we re-run each subscription whose read-set intersects the
+// written tables, but push only when that subscription's result actually changed
+// (digest diff). Connections use Hibernatable WebSockets; per-socket state
+// (identity + subscriptions) is stored via serializeAttachment().
+
+import { DurableObject } from "cloudflare:workers";
+import { migrate } from "./runtime/migrate";
+import { dispatch } from "./runtime/dispatch";
+import { digest } from "./runtime/digest";
+import { compileAcl, type AclContext, type CompiledAcl } from "./runtime/acl";
+import { DoSqliteDriver, type Driver } from "./runtime/driver";
+import { BadRequest, toResponse, toWsError } from "./runtime/errors";
+import { Kv } from "./runtime/kv";
+import { createFiles, R2Adapter, type Files } from "./runtime/storage";
+import type { Identity } from "./sdk/acl";
+import type { PramenApp } from "./pramen";
+import type { ClientMsg, ServerMsg, Subscription } from "./runtime/protocol";
+
+interface SocketState {
+  identity: Identity | null;
+  /** Tenant fixed at connect time (survives hibernation via the attachment). */
+  tenant: string;
+  subs: Subscription[];
+}
+
+export interface DoEnv {
+  /** Project KV — tenant registry (`tenant:`) + handler ctx.kv (`app:`). */
+  KV: KVNamespace;
+  /** R2 bucket backing ctx.files + the Worker /files/* route. */
+  FILES: R2Bucket;
+  /** HMAC secret for signing file upload/download tokens (falls back to AUTH_SECRET). */
+  FILES_SECRET?: string;
+  /** Bearer-JWT secret; also the fallback for signing file tokens. */
+  AUTH_SECRET?: string;
+  /** "true" to apply destructive schema migrations (drop/rebuild/type-change). Off by
+   * default — data-loss is gated behind this explicit opt-in. */
+  PRAMEN_ALLOW_DESTRUCTIVE?: string;
+}
+
+/** Per-socket subscription cap — bounds memory and per-mutation re-run cost. */
+const MAX_SUBSCRIPTIONS = 64;
+
+export class PramenDOBase extends DurableObject<DoEnv> {
+  private readonly app: PramenApp;
+  private readonly acl: CompiledAcl;
+  private readonly kv: Kv;
+  private readonly driver: Driver;
+  private registered = false;
+  /** Tenant this DO serves (one per idFromName). Learned from the Worker-forwarded
+   * x-pramen-tenant header; defaults to "main". */
+  private tenant = "main";
+  private files?: Files;
+
+  constructor(ctx: DurableObjectState, env: DoEnv, app: PramenApp) {
+    super(ctx, env);
+    this.app = app;
+    this.acl = compileAcl(this.app.acl ?? []);
+    this.kv = new Kv(env.KV); // app:-prefixed, handed to handlers as ctx.kv
+
+    // The data layer runs over a Driver. The DO's store is its own in-process SQLite;
+    // the D1 substrate (D1Driver) lives in the Worker (the "Worker + D1, no DO" path).
+    this.driver = new DoSqliteDriver(ctx.storage);
+
+    // Reconcile the store with the schema before any request is served (create/alter
+    // tables; destructive changes rebuild the table). Wrapped in a transaction so a
+    // partial migration can't leave a half-rebuilt table.
+    const allowDestructive = env.PRAMEN_ALLOW_DESTRUCTIVE === "true";
+    ctx.blockConcurrencyWhile(() =>
+      this.driver.transaction(() => migrate(this.driver, this.app.schema, { allowDestructive }).then(() => {})),
+    );
+  }
+
+  override async fetch(request: Request): Promise<Response> {
+    await this.ensureRegistered(request);
+    const tenantHeader = request.headers.get("x-pramen-tenant");
+    if (tenantHeader) this.tenant = tenantHeader;
+
+    const path = new URL(request.url).pathname;
+    if (path === "/__recover") return this.handleRecover(request);
+    if (path === "/__schema") return this.handleSchema();
+
+    const identity = this.identityOf(request);
+
+    if (request.headers.get("Upgrade") === "websocket") {
+      const { 0: client, 1: server } = new WebSocketPair();
+      this.ctx.acceptWebSocket(server); // hibernatable
+      this.setState(server, { identity, tenant: this.tenant, subs: [] });
+      return new Response(null, { status: 101, webSocket: client });
+    }
+
+    const name = new URL(request.url).pathname.replace(/^\/rpc\//, "");
+    let input: unknown;
+    if (request.method === "POST") {
+      input = await request.json().catch(() => undefined);
+    }
+
+    try {
+      const { result, kind, touched } = await dispatch(
+        this.app.handlers,
+        this.app.schema,
+        this.driver,
+        this.kv,
+        this.filesFor(this.tenant),
+        this.envBag,
+        this.ctxFor(identity),
+        name,
+        input,
+      );
+      if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
+      return Response.json({ ok: true, result });
+    } catch (err) {
+      const { status, body } = toResponse(err);
+      return Response.json(body, { status });
+    }
+  }
+
+  // --- Hibernatable WebSocket handlers ---
+
+  override async webSocketMessage(ws: WebSocket, raw: string | ArrayBuffer): Promise<void> {
+    let msg: ClientMsg;
+    try {
+      msg = JSON.parse(typeof raw === "string" ? raw : new TextDecoder().decode(raw));
+    } catch {
+      return this.send(ws, { type: "error", id: "", error: "invalid JSON" });
+    }
+
+    switch (msg.type) {
+      case "subscribe":
+        return this.onSubscribe(ws, msg.id, msg.name, msg.input);
+      case "unsubscribe": {
+        const state = this.getState(ws);
+        this.setState(ws, { ...state, subs: state.subs.filter((s) => s.id !== msg.id) });
+        return;
+      }
+      case "call":
+        return this.onCall(ws, msg.id, msg.name, msg.input);
+      default:
+        return this.send(ws, { type: "error", id: "", error: "unknown message type" });
+    }
+  }
+
+  override async webSocketClose(ws: WebSocket): Promise<void> {
+    ws.close();
+  }
+
+  override async webSocketError(ws: WebSocket, error: unknown): Promise<void> {
+    console.error("pramen: websocket error", error);
+    try {
+      ws.close(1011, "error");
+    } catch {
+      /* already closing */
+    }
+  }
+
+  // --- live-query internals ---
+
+  private async onSubscribe(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
+    const state = this.getState(ws);
+    try {
+      const replacing = state.subs.some((s) => s.id === id);
+      if (!replacing && state.subs.length >= MAX_SUBSCRIPTIONS) {
+        return this.send(ws, toWsError(id, new BadRequest("subscription limit reached")));
+      }
+      const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity), name, input);
+      if (kind !== "query") {
+        return this.send(ws, toWsError(id, new BadRequest(`${name} is not a query`)));
+      }
+      const subs = state.subs.filter((s) => s.id !== id);
+      subs.push({ id, name, input, tables: touched, digest: digest(result) });
+      this.setState(ws, { ...state, subs });
+      this.send(ws, { type: "data", id, result });
+    } catch (err) {
+      this.send(ws, toWsError(id, err));
+    }
+  }
+
+  private async onCall(ws: WebSocket, id: string, name: string, input: unknown): Promise<void> {
+    const state = this.getState(ws);
+    try {
+      const { result, kind, touched } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity), name, input);
+      this.send(ws, { type: "result", id, result });
+      if (kind === "mutation" && touched.length > 0) await this.broadcast(touched);
+    } catch (err) {
+      this.send(ws, toWsError(id, err));
+    }
+  }
+
+  // Re-run every subscription whose read-set intersects the written tables, each
+  // under its own socket's identity, and push only when its result changed.
+  private async broadcast(touched: string[]): Promise<void> {
+    const written = new Set(touched);
+    for (const ws of this.ctx.getWebSockets()) {
+      const state = this.getState(ws);
+      let dirty = false;
+      for (const sub of state.subs) {
+        if (!sub.tables.some((t) => written.has(t))) continue;
+        try {
+          const { result } = await dispatch(this.app.handlers, this.app.schema, this.driver, this.kv, this.filesFor(state.tenant), this.envBag, this.ctxFor(state.identity), sub.name, sub.input);
+          const next = digest(result);
+          if (next === sub.digest) continue; // result unchanged for this subscription
+          sub.digest = next;
+          dirty = true;
+          this.send(ws, { type: "data", id: sub.id, result });
+        } catch (err) {
+          this.send(ws, toWsError(sub.id, err));
+        }
+      }
+      if (dirty) this.setState(ws, state);
+    }
+  }
+
+  // --- helpers ---
+
+  // A DO addressed by idFromName(tenant) doesn't know its own name — the Worker
+  // forwards it. On the first touch ever (guarded by a persisted meta flag), the
+  // tenant records itself in the registry KV so it stays discoverable. Exactly
+  // one KV write per tenant across its whole lifetime.
+  private async ensureRegistered(request: Request): Promise<void> {
+    if (this.registered) return;
+    const name = request.headers.get("x-pramen-tenant");
+    if (!name) return;
+
+    const seen = await this.driver.exec(`SELECT 1 FROM _pramen_meta WHERE key = 'registered'`, []);
+    if (seen.length > 0) {
+      this.registered = true;
+      return;
+    }
+    await this.env.KV.put(`tenant:${name}`, JSON.stringify({ firstSeen: Date.now() }));
+    await this.driver.exec(`INSERT OR REPLACE INTO _pramen_meta (key, value) VALUES ('registered', ?)`, [name]);
+    this.registered = true;
+  }
+
+  // Point-in-time recovery (admin-gated at the Worker). Arms a restore to the
+  // given time and returns the `undo` bookmark (the point just before recovery,
+  // so the operation is reversible). We intentionally do NOT call ctx.abort()
+  // here, so this response can return the undo bookmark — the restore completes
+  // when the DO next restarts. PITR is unavailable in local dev (no change-log).
+  private async handleRecover(request: Request): Promise<Response> {
+    const body = (await request.json().catch(() => ({}))) as { timestamp?: unknown };
+    const ts = typeof body.timestamp === "number" ? body.timestamp : Date.parse(String(body.timestamp));
+    if (!Number.isFinite(ts)) {
+      return Response.json({ ok: false, error: "invalid timestamp", code: "bad_request" }, { status: 400 });
+    }
+
+    const storage = this.ctx.storage as unknown as {
+      getBookmarkForTime?: (t: number) => Promise<string>;
+      onNextSessionRestoreBookmark?: (b: string) => Promise<string>;
+    };
+
+    try {
+      const bookmark = await storage.getBookmarkForTime!(ts);
+      const undo = await storage.onNextSessionRestoreBookmark!(bookmark);
+      return Response.json({ ok: true, result: { restoredTo: ts, bookmark, undo, applied: false } });
+    } catch (err) {
+      // PITR is a platform feature — unavailable in local dev, and can otherwise
+      // fail operationally. Report 501 (not a generic 500); log the real reason.
+      console.error("pramen: recovery unavailable", err);
+      return Response.json(
+        { ok: false, error: "point-in-time recovery is unavailable in this environment", code: "unavailable" },
+        { status: 501 },
+      );
+    }
+  }
+
+  // Introspection: this tenant's applied schema hash + live table/column shape
+  // (admin-gated at the Worker). Powers the CLI's `schema status`.
+  private async handleSchema(): Promise<Response> {
+    const hashRow = (await this.driver.exec(`SELECT value FROM _pramen_meta WHERE key = 'schema_hash'`, [])) as {
+      value: string;
+    }[];
+    const tableRows = (await this.driver.exec(
+      `SELECT name FROM sqlite_master WHERE type = 'table' AND name NOT LIKE 'sqlite_%' AND name <> '_pramen_meta'`,
+      [],
+    )) as { name: string }[];
+    const tables: Record<string, string[]> = {};
+    for (const { name } of tableRows) {
+      tables[name] = ((await this.driver.exec(`PRAGMA table_info(${name})`, [])) as { name: string }[]).map((r) => r.name);
+    }
+    return Response.json({ ok: true, result: { hash: hashRow[0]?.value ?? null, tables } });
+  }
+
+  private ctxFor(identity: Identity | null): AclContext {
+    return { acl: this.acl, identity };
+  }
+
+  // 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.
+  private get envBag(): Readonly<Record<string, unknown>> {
+    return this.env as unknown as Record<string, unknown>;
+  }
+
+  // One Files facade per DO (a DO serves one tenant). Backed by the R2 binding;
+  // signing uses FILES_SECRET. Handlers mint signed urls; the bytes never enter here.
+  private filesFor(tenant: string): Files {
+    if (!this.files) {
+      const secret = this.env.FILES_SECRET || this.env.AUTH_SECRET || "";
+      this.files = createFiles({ tenant, secret, adapter: new R2Adapter(this.env.FILES) });
+    }
+    return this.files;
+  }
+
+  private identityOf(request: Request): Identity | null {
+    const raw = request.headers.get("x-pramen-identity");
+    if (!raw) return null;
+    try {
+      return JSON.parse(raw) as Identity;
+    } catch {
+      return null;
+    }
+  }
+
+  private getState(ws: WebSocket): SocketState {
+    return (ws.deserializeAttachment() as SocketState | null) ?? { identity: null, tenant: this.tenant, subs: [] };
+  }
+
+  private setState(ws: WebSocket, state: SocketState): void {
+    ws.serializeAttachment(state);
+  }
+
+  private send(ws: WebSocket, msg: ServerMsg): void {
+    ws.send(JSON.stringify(msg));
+  }
+}
+
+/** Produce the concrete, app-bound Durable Object class. A DO is constructed by the
+ * platform with just (ctx, env), so the app is closed over here. Re-export the
+ * result from your Worker entry under the class name wrangler expects ("PramenDO"). */
+export function pramenDO(app: PramenApp): typeof PramenDOBase {
+  return class PramenDO extends PramenDOBase {
+    constructor(ctx: DurableObjectState, env: DoEnv) {
+      super(ctx, env, app);
+    }
+  };
+}

package/src/index.ts

@@ -0,0 +1,77 @@
+// @pramen/server — the authoring entry: schema, handlers, ACL, files, errors, and
+// the substrate seam. A pramen project is just an app.ts (schema + handlers + ACL),
+// an oblaka.ts (topology), and a 3-line Worker entry.
+//
+// The deploy half — createPramen / the Durable Object — lives at "@pramen/server/worker"
+// (see worker-entry.ts). It is split off because it imports `cloudflare:workers`,
+// 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, defaultTo } from "./sdk/schema";
+export type {
+  DefaultValue,
+  FieldType,
+  FieldDef,
+  EntityFields,
+  EntityDef,
+  SchemaDef,
+  RelationDef,
+  RelationDefs,
+  BelongsToDef,
+  HasManyDef,
+} from "./sdk/schema";
+
+// --- app + handlers ---
+export { createApp } from "./sdk/app";
+export { query, mutation } from "./sdk/handlers";
+export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts } from "./sdk/handlers";
+
+// --- ACL ---
+export { $identity, $input, allow, deny, policy, resolve, role, isAllow, isDeny, isResolver, isIdentityMarker, isInputMarker } from "./sdk/acl";
+export type {
+  Action,
+  Identity,
+  IdentityMarker,
+  InputMarker,
+  Policy,
+  PolicyRule,
+  PolicyRules,
+  Role,
+  Validator,
+  WhereRule,
+  ConditionalFields,
+  FieldsFn,
+  RelationAclRule,
+  SetValue,
+  ResolverFn,
+  ResolverContext,
+  ResolverDb,
+} from "./sdk/acl";
+
+// --- inference (types only) ---
+export type {
+  Cell,
+  FieldsOf,
+  InferInsert,
+  InferRow,
+  InferUpdate,
+  JsonValue,
+  ProjectedRow,
+  RelationsOf,
+  RelationsResult,
+  WhereInput,
+  WhereOps,
+} from "./sdk/infer";
+
+// --- files ---
+export type { FileRef, Files, SignUploadOpts, SignDownloadOpts, HeadResult } from "./sdk/files";
+export { R2Adapter, MemoryAdapter, createFiles, handleFileRequest } from "./runtime/storage";
+export type { StorageAdapter, PutResult, GetResult } from "./runtime/storage";
+
+// --- errors ---
+export { PramenError, BadRequest, Unauthorized, Forbidden } from "./runtime/errors";
+
+// --- substrate seam (advanced: bring your own SQL backend) ---
+export { sqliteDialect, postgresDialect, DoSqliteDriver, D1Driver } from "./runtime/driver";
+export type { Driver, Dialect, Row } from "./runtime/driver";