@pramen/server 0.0.1 → 0.0.2

package/dist/sdk/infer.d.ts

@@ -45,6 +45,15 @@ export type WhereInput<F extends EntityFields> = {
     AND?: WhereInput<F>[];
     OR?: WhereInput<F>[];
 };
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5];
+type RelTargetTable<S extends SchemaDef, R> = R extends {
+    target: infer Tg;
+} ? (Tg extends keyof S ? Tg : never) : never;
+/** A `where` clause: column predicates + AND/OR, plus relation keys that take a
+ * nested `WhereClause` over the related entity (traversal). */
+export type WhereClause<S extends SchemaDef, T extends keyof S, D extends number = 5> = WhereInput<FieldsOf<S[T]>> & ([D] extends [never] ? object : {
+    [K in keyof RelationsOf<S[T]>]?: WhereClause<S, RelTargetTable<S, RelationsOf<S[T]>[K]>, PrevDepth[D]>;
+});
 /** Patch input for updates: every column optional, value typed (nullable). */
 export type InferUpdate<F extends EntityFields> = Partial<{
     [K in keyof F]: FieldTsType<F[K]> | null;

package/dist/worker.js

@@ -131,9 +131,9 @@ export function makeWorker(app) {
             // --- admin: list known tenants ---
             if (url.pathname === "/tenants") {
                 if (!isAdmin(identity))
-                    return forbidden("tenants");
+                    return withCors(forbidden("tenants"), cors);
                 const list = await env.KV.list({ prefix: "tenant:" });
-                return json({ ok: true, result: list.keys.map((k) => k.name.slice("tenant:".length)) });
+                return withCors(json({ ok: true, result: list.keys.map((k) => k.name.slice("tenant:".length)) }), cors);
             }
             // --- admin: point-in-time recovery for a tenant ---
             if (url.pathname === "/admin/recover" && request.method === "POST") {
@@ -155,17 +155,35 @@ export function makeWorker(app) {
             // --- admin: a tenant's applied schema (hash + tables) ---
             if (url.pathname === "/admin/schema") {
                 if (!isAdmin(identity))
-                    return forbidden("schema");
+                    return withCors(forbidden("schema"), cors);
                 const tenant = url.searchParams.get("tenant") ?? "main";
                 const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
-                return stub.fetch(new Request("https://do/__schema", { headers: { "x-pramen-tenant": tenant } }));
+                const res = await stub.fetch(new Request("https://do/__schema", { headers: { "x-pramen-tenant": tenant } }));
+                return withCors(res, cors);
+            }
+            // --- admin: generic data ops over a tenant's tables (browse/edit any row).
+            // Body: { tenant, table, op: list|get|create|update|delete|count, ... }. Runs
+            // in the DO under SYSTEM scope (ACL bypassed) — gated to admins here. ---
+            if (url.pathname === "/admin/data" && request.method === "POST") {
+                if (!isAdmin(identity))
+                    return forbidden("data");
+                const body = (await request.json().catch(() => ({})));
+                const tenant = typeof body.tenant === "string" && body.tenant ? body.tenant : "main";
+                const stub = env.PRAMEN.get(env.PRAMEN.idFromName(tenant));
+                const res = await stub.fetch(new Request("https://do/__admin/data", {
+                    method: "POST",
+                    headers: { "content-type": "application/json", "x-pramen-tenant": tenant },
+                    body: JSON.stringify(body),
+                }));
+                return withCors(res, cors);
             }
             const isRpc = url.pathname.startsWith("/rpc/");
             const isLive = url.pathname === "/live";
             if (!isRpc && !(isLive && isWs)) {
                 return new Response("pramen — POST /rpc/<handler> (JSON body), or WebSocket /live for live queries. " +
                     "Header X-Pramen-Tenant selects the store (default: main). " +
-                    "Admin: GET /tenants, POST /admin/recover {tenant,timestamp}, GET /admin/schema?tenant=.\n", { headers: { "content-type": "text/plain" } });
+                    "Admin: GET /tenants, POST /admin/recover {tenant,timestamp}, GET /admin/schema?tenant=, " +
+                    "POST /admin/data {tenant,table,op}.\n", { headers: { "content-type": "text/plain" } });
             }
             // Authorize the tenant against the identity before reaching the DO, so a
             // caller can't address (or register) tenants they have no claim to.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pramen/server",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "pramen server runtime — schema, ACL, ORM, live queries, files, and the createPramen(app) factory for Cloudflare Workers + Durable Objects.",
   "license": "MIT",
   "repository": {

package/src/auth.ts

@@ -197,14 +197,16 @@ export async function resolveIdentity(request: Request, strategy: VerifyStrategy
 }
 
 /** 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). */
+ * can't reach (or register) arbitrary tenants. Default policy:
+ *  - `main` is the open default tenant: any caller may reach it (anonymous too) —
+ *    data access is still governed by ACL roles (single-tenant apps live here, and
+ *    issued login tokens need no `tenants` claim to use it).
+ *  - other tenants: admins → any; everyone else → only tenants in their `tenants`
+ *    claim; anonymous → none.
+ * 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 (tenant === "main") return true;
+  if (!identity) return false;
   if (identity.roles?.includes("admin")) return true;
   const allowed = Array.isArray(identity.tenants) ? (identity.tenants as string[]) : [];
   return allowed.includes(tenant);

package/src/durable-object.ts

@@ -18,6 +18,7 @@
 import { DurableObject } from "cloudflare:workers";
 import { migrate } from "./runtime/migrate";
 import { dispatch } from "./runtime/dispatch";
+import { Db } from "./runtime/db";
 import { digest } from "./runtime/digest";
 import { compileAcl, type AclContext, type CompiledAcl } from "./runtime/acl";
 import { DoSqliteDriver, type Driver } from "./runtime/driver";
@@ -90,6 +91,7 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     const path = new URL(request.url).pathname;
     if (path === "/__recover") return this.handleRecover(request);
     if (path === "/__schema") return this.handleSchema();
+    if (path === "/__admin/data") return this.handleAdminData(request);
 
     const identity = this.identityOf(request);
 
@@ -291,8 +293,58 @@ export class PramenDOBase extends DurableObject<DoEnv> {
     return Response.json({ ok: true, result: { hash: hashRow[0]?.value ?? null, tables } });
   }
 
+  // Generic admin data ops (admin-gated at the Worker). Runs through a SYSTEM-mode
+  // Db, so ACL is bypassed — admin can browse/edit any row of any table — while the
+  // json/fileRef codec, transactions, and live-query broadcast still apply.
+  private async handleAdminData(request: Request): Promise<Response> {
+    const b = (await request.json().catch(() => ({}))) as Record<string, unknown>;
+    const table = typeof b.table === "string" ? b.table : "";
+    const op = typeof b.op === "string" ? b.op : "";
+    if (!table || !(table in this.app.schema)) {
+      return Response.json({ ok: false, error: "unknown table", code: "bad_request" }, { status: 400 });
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const db = new Db(this.driver, { acl: this.acl, identity: null, system: true }, this.app.schema) as any;
+    try {
+      let result: unknown;
+      let mutated = false;
+      switch (op) {
+        case "list":
+          result = await db.find({ from: table, where: b.where, orderBy: b.orderBy, limit: b.limit, offset: b.offset });
+          break;
+        case "count":
+          result = await db.count({ from: table, where: b.where });
+          break;
+        case "get":
+          result = (await db.find({ from: table, where: { id: b.id }, limit: 1 }))[0] ?? null;
+          break;
+        case "create":
+          result = await this.driver.transaction(() => db.insert(table, b.values));
+          mutated = true;
+          break;
+        case "update":
+          result = (await this.driver.transaction(() => db.update(table, b.id, b.patch))) ?? null;
+          mutated = true;
+          break;
+        case "delete":
+          result = await this.driver.transaction(() => db.delete(table, b.id));
+          mutated = true;
+          break;
+        default:
+          return Response.json({ ok: false, error: `unknown op: ${op}`, code: "bad_request" }, { status: 400 });
+      }
+      if (mutated && db.touched.size > 0) await this.broadcast([...db.touched]);
+      return Response.json({ ok: true, result });
+    } catch (err) {
+      const { status, body } = toResponse(err);
+      return Response.json(body, { status });
+    }
+  }
+
   private ctxFor(identity: Identity | null): AclContext {
-    return { acl: this.acl, identity };
+    // Carry the schema so any consumer of this context (not just Db) can compile
+    // relation-aware `where` rules into subqueries.
+    return { acl: this.acl, identity, schema: this.app.schema };
   }
 
   // The DO env (bindings + vars + secrets) handed to handlers as ctx.env. Loosely

package/src/index.ts

@@ -60,6 +60,7 @@ export type {
   ProjectedRow,
   RelationsOf,
   RelationsResult,
+  WhereClause,
   WhereInput,
   WhereOps,
 } from "./sdk/infer";

package/src/runtime/acl.ts

@@ -15,7 +15,6 @@ import {
   type ResolverDb,
   type Role,
   type Validator,
-  type WhereRule,
   deny,
   isAllow,
   isDeny,
@@ -23,8 +22,9 @@ import {
   isInputMarker,
   isResolver,
 } from "../sdk/acl";
-import { compileWhere, evalExpr, FALSE, or, type SqlExpr } from "./read-engine";
-import { PramenError } from "./errors";
+import { and, compileWhere, evalExpr, FALSE, or, TRUE, type SqlExpr } from "./read-engine";
+import { BadRequest, PramenError } from "./errors";
+import type { FieldDef, RelationDef, SchemaDef } from "../sdk/schema";
 
 export class AclDenied extends PramenError {
   constructor(
@@ -57,6 +57,9 @@ export interface AclContext {
   readonly resolved?: Map<number, PolicyRule>;
   /** SYSTEM mode bypasses all ACL — used for warmup reads and internal ops. */
   readonly system?: boolean;
+  /** 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;
 }
 
 /** Evaluate every resolver reachable by the identity's roles, once per request.
@@ -128,14 +131,16 @@ interface Grant {
   fieldsFns: FieldsFn[];
 }
 
-/** Build a grant from a policy/relation rule, resolving $identity markers in
- * `where` and each conditional `when`. */
-function grantOf(rule: PolicyRules | RelationAclRule, where: SqlExpr | null, identity: Identity | null, input: unknown): Grant {
+/** Build a grant from a policy/relation rule, resolving markers in `where` and each
+ * conditional `when` (the `when` predicate is single-table — evaluated in memory). */
+function grantOf(rule: PolicyRules | RelationAclRule, where: SqlExpr | null, entity: string, ctx: AclContext, depth: number): Grant {
   return {
     where,
     fields: rule.fields ?? null,
     conditional: (rule.conditionalFields ?? []).map((cf) => ({
-      when: whereToExpr(cf.when, identity, input),
+      // Cell-level `when` is evaluated per-row in memory (evalExpr), so it must stay
+      // single-table — `allowRelations: false` rejects a relation key up front.
+      when: compileScopedWhere(cf.when as Record<string, unknown>, entity, ctx, depth, false),
       fields: cf.fields,
     })),
     fieldsFns: rule.fieldsFn ? [rule.fieldsFn] : [],
@@ -173,23 +178,18 @@ function resolveValue(v: unknown, identity: Identity | null, input: unknown): un
   return v;
 }
 
-// Resolve every $identity marker in a policy where-rule (bare values, operator
-// objects, in/notIn arrays, AND/OR groups). Returns a plain WhereInput, or null
-// if any marker is unresolvable — in which case the rule matches nothing.
+// Resolve every $identity/$input marker in a SINGLE level of a where-rule (bare
+// values, operator objects, in/notIn arrays). AND/OR groups are split off by
+// `compileScopedWhere` before this runs, so this only ever sees plain columns.
+// Returns a plain WhereInput, or null if any marker is unresolvable — in which
+// case this branch matches nothing (FALSE). Note: because branches are resolved
+// independently, an unresolvable marker nullifies only its own branch, not the
+// whole rule — so `OR: [{ x: $identity(...) }, { public: true }]` still matches
+// the `public` branch for a caller whose marker can't resolve. (See the comment
+// on `compileScopedWhere`.)
 function resolveMarkers(rule: Record<string, unknown>, identity: Identity | null, input: unknown): Record<string, unknown> | null {
   const out: Record<string, unknown> = {};
   for (const [key, v] of Object.entries(rule)) {
-    if (key === "AND" || key === "OR") {
-      const groups: Record<string, unknown>[] = [];
-      for (const g of v as Record<string, unknown>[]) {
-        const resolved = resolveMarkers(g, identity, input);
-        if (resolved === null) return null;
-        groups.push(resolved);
-      }
-      out[key] = groups;
-      continue;
-    }
-
     const isMarker = isIdentityMarker(v) || isInputMarker(v);
     if (v !== null && typeof v === "object" && !isMarker && !Array.isArray(v)) {
       const ops: Record<string, unknown> = {};
@@ -222,12 +222,106 @@ function resolveMarkers(rule: Record<string, unknown>, identity: Identity | null
   return out;
 }
 
-/** Turn a policy where-rule into an expression. Supports the full user query
- * surface (operators, AND/OR) with $identity / $input markers; an unresolvable
- * marker makes the rule match nothing. */
-function whereToExpr(rule: WhereRule, identity: Identity | null, input: unknown): SqlExpr {
-  const resolved = resolveMarkers(rule as Record<string, unknown>, identity, input);
-  return resolved === null ? FALSE : compileWhere(resolved);
+/** Max relation-traversal nesting depth in a `where` (guards cyclic relations).
+ * Kept in lockstep with the `WhereClause` type's depth bound in sdk/infer.ts — if
+ * you change one, change the other. */
+export const MAX_REL_DEPTH = 5;
+
+/** Primary-key column of an entity (the column a belongsTo points at / a hasMany
+ * joins back to). Defaults to `id`. */
+function pkOf(schema: SchemaDef | undefined, entity: string): string {
+  const fields = schema?.[entity]?.fields;
+  if (fields) for (const [n, f] of Object.entries(fields)) if ((f as FieldDef).primaryKey) return n;
+  return "id";
+}
+
+/** Compile a relation predicate `{ rel: { … } }` to a subquery, AND-merging the
+ * related entity's read scope (and rejecting filters on fields it can't read) so
+ * traversal can never widen access beyond a direct read of the target. */
+function relationPredicate(rel: RelationDef, nested: unknown, parentEntity: string, ctx: AclContext, depth: number): SqlExpr {
+  if (depth >= MAX_REL_DEPTH) throw new BadRequest("relation `where` is nested too deep");
+  if (nested === null || typeof nested !== "object" || Array.isArray(nested)) {
+    throw new BadRequest(`relation filter for '${rel.target}' must be an object`);
+  }
+  let inner = compileScopedWhere(nested as Record<string, unknown>, rel.target, ctx, depth + 1);
+
+  // Security: a relation filter must respect the target's read ACL (else it leaks).
+  // Two distinct "no" outcomes, matching how the rest of the read path behaves:
+  //   - No read grant on the target at all  -> the relation simply yields no rows
+  //     to match against (FALSE, empty result) — a valid query over a table you
+  //     can't see.
+  //   - Readable target, but the filter names a column you can't read -> 403, the
+  //     same as ordering/aggregating by a hidden column (you referenced something
+  //     forbidden). Top-level user `where` enforces the same rule (Db.readWhere).
+  if (!ctx.system) {
+    const tScope = resolveScope(ctx, rel.target, "read", depth + 1);
+    if (!tScope.allowed) {
+      inner = FALSE; // can't filter through a relation you can't read
+    } else {
+      if (tScope.fields !== null) {
+        const targetRels = (ctx.schema?.[rel.target]?.relations ?? {}) as Record<string, unknown>;
+        for (const k of Object.keys(nested as Record<string, unknown>)) {
+          if (k === "AND" || k === "OR" || targetRels[k]) continue;
+          if (!tScope.fields.includes(k)) throw new AclDenied(rel.target, "read", k);
+        }
+      }
+      if (tScope.where) inner = and(inner, tScope.where);
+    }
+  }
+
+  // belongsTo: parent.<fk> IN (SELECT <target pk> FROM target WHERE inner)
+  // hasMany:   parent.<pk> IN (SELECT <target fk> FROM target WHERE inner)
+  return rel.kind === "belongsTo"
+    ? { t: "sub", outerCol: rel.column, from: rel.target, selectCol: pkOf(ctx.schema, rel.target), where: inner, negate: false }
+    : { t: "sub", outerCol: pkOf(ctx.schema, parentEntity), from: rel.target, selectCol: rel.column, where: inner, negate: false };
+}
+
+/** Compile a where-rule (user query or policy) into a SqlExpr. Plain columns go
+ * through the marker-resolving compiler; relation keys (`{ rel: { … } }`) become
+ * security-scoped subqueries. Supports operators, AND/OR, and $identity/$input
+ * markers; an unresolvable marker makes its branch match nothing. Schema-less
+ * contexts (no relations) behave exactly like the flat compiler.
+ *
+ * Marker semantics: AND/OR branches compile independently, so an unresolvable
+ * marker collapses ONLY its own branch to FALSE — it does not nullify sibling
+ * branches. `OR: [{ ownerId: $identity("userId") }, { public: true }]` therefore
+ * still grants the `public` branch to a caller whose `userId` can't resolve (and,
+ * conversely, an unresolvable marker in one OR branch no longer revokes access the
+ * other branches would grant). This is plain boolean logic; the cases are covered
+ * by the relwhere suite.
+ *
+ * `allowRelations` is false for single-table contexts (cell-level `when`, which is
+ * evaluated in memory and cannot do a SQL round-trip): a relation key then raises a
+ * clear authoring error instead of emitting a `sub` node that throws at read time. */
+export function compileScopedWhere(
+  rule: Record<string, unknown>,
+  entity: string,
+  ctx: AclContext,
+  depth = 0,
+  allowRelations = true,
+): SqlExpr {
+  const relations = (ctx.schema?.[entity]?.relations ?? {}) as Record<string, RelationDef>;
+  const parts: SqlExpr[] = [];
+  const plain: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(rule)) {
+    if (k === "AND" || k === "OR") {
+      const groups = (v as Record<string, unknown>[]).map((g) => compileScopedWhere(g, entity, ctx, depth, allowRelations));
+      parts.push(k === "AND" ? and(...groups) : or(...groups));
+    } else if (relations[k]) {
+      if (!allowRelations) {
+        throw new BadRequest(`cell-level \`when\` cannot traverse relations: '${k}' (relations need a SQL round-trip)`);
+      }
+      parts.push(relationPredicate(relations[k]!, v, entity, ctx, depth));
+    } else {
+      plain[k] = v;
+    }
+  }
+  if (Object.keys(plain).length > 0) {
+    const resolvedPlain = resolveMarkers(plain, ctx.identity, ctx.input);
+    parts.push(resolvedPlain === null ? FALSE : compileWhere(resolvedPlain));
+  }
+  if (parts.length === 0) return TRUE; // empty where -> match all
+  return parts.length === 1 ? parts[0]! : and(...parts);
 }
 
 /** The concrete rules that apply for (entity, action) under this identity — with
@@ -276,12 +370,15 @@ function mergeGrants(grants: Grant[]): Scope {
   };
 }
 
-export function resolveScope(ctx: AclContext, entity: string, action: Action): Scope {
+export function resolveScope(ctx: AclContext, entity: string, action: Action, depth = 0): Scope {
   const grants: Grant[] = [];
   for (const rule of matchedRules(ctx, entity, action)) {
     if (isDeny(rule)) continue;
     if (isAllow(rule)) grants.push(ALLOW_GRANT);
-    else grants.push(grantOf(rule, whereToExpr(rule.where ?? {}, ctx.identity, ctx.input), ctx.identity, ctx.input));
+    else {
+      const where = compileScopedWhere((rule.where ?? {}) as Record<string, unknown>, entity, ctx, depth);
+      grants.push(grantOf(rule, where, entity, ctx, depth));
+    }
   }
   return mergeGrants(grants);
 }
@@ -346,7 +443,8 @@ export function resolveRelationScope(
     if (isAllow(rule) || isDeny(rule)) continue;
     const rel = rule.relations?.[relName];
     if (rel?.directAccess) {
-      grants.push(grantOf(rel, rel.where ? whereToExpr(rel.where, ctx.identity, ctx.input) : null, ctx.identity, ctx.input));
+      const relWhere = rel.where ? compileScopedWhere(rel.where as Record<string, unknown>, target, ctx, 0) : null;
+      grants.push(grantOf(rel, relWhere, target, ctx, 0));
     }
   }
 

package/src/runtime/db.ts

@@ -14,6 +14,7 @@
 import {
   AclDenied,
   ALLOW_ALL,
+  compileScopedWhere,
   effectiveFields,
   projectRow,
   resolveRelationScope,
@@ -30,7 +31,6 @@ import {
   compileCount,
   compileExpr,
   compileSelect,
-  compileWhere,
   eq,
   inList,
   or,
@@ -42,7 +42,7 @@ import {
 import { BadRequest } from "./errors";
 import type { Dialect, Driver } from "./driver";
 import type { EntityFields, FieldDef, RelationDef, SchemaDef } from "../sdk/schema";
-import type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, RelationsOf, RelationsResult, WhereInput } from "../sdk/infer";
+import type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, RelationsOf, RelationsResult, WhereClause } from "../sdk/infer";
 
 type Row = Record<string, unknown>;
 type Action = "read" | "create" | "update" | "delete";
@@ -63,7 +63,7 @@ type OrderSpec<S extends SchemaDef, T extends keyof S> = {
 
 export interface FindSpec<S extends SchemaDef, T extends keyof S> {
   from: T;
-  where?: WhereInput<FieldsOf<S[T]>>;
+  where?: WhereClause<S, T>;
   orderBy?: OrderSpec<S, T> | OrderSpec<S, T>[];
   limit?: number;
   offset?: number;
@@ -74,7 +74,7 @@ export interface FindSpec<S extends SchemaDef, T extends keyof S> {
 /** Cursor (keyset) pagination input — `after` is an opaque cursor from a prior page. */
 export interface PageSpec<S extends SchemaDef, T extends keyof S> {
   from: T;
-  where?: WhereInput<FieldsOf<S[T]>>;
+  where?: WhereClause<S, T>;
   orderBy?: OrderSpec<S, T> | OrderSpec<S, T>[];
   limit?: number;
   after?: string;
@@ -93,7 +93,7 @@ type Aggregations<F extends EntityFields> = Record<string, { fn: AggFn; column?:
 
 export interface AggregateSpec<S extends SchemaDef, T extends keyof S> {
   from: T;
-  where?: WhereInput<FieldsOf<S[T]>>;
+  where?: WhereClause<S, T>;
   groupBy?: (keyof FieldsOf<S[T]> & string) | (keyof FieldsOf<S[T]> & string)[];
   aggregations: Aggregations<FieldsOf<S[T]>>;
 }
@@ -154,12 +154,17 @@ export class Db<S extends SchemaDef = SchemaDef> {
   /** Tables read or written during this Db's lifetime. */
   readonly touched = new Set<string>();
   private readonly dialect: Dialect;
+  private readonly acl: AclContext;
 
   constructor(
     private readonly driver: Driver,
-    private readonly acl: AclContext,
+    acl: AclContext,
     private readonly schema: SchemaDef,
   ) {
+    // The ACL context normally already carries the schema (set at the dispatch / DO
+    // boundary). Inject it as a safety net so a context built without one can still
+    // compile relation-aware `where` rules into subqueries rather than failing obscurely.
+    this.acl = acl.schema ? acl : { ...acl, schema };
     this.dialect = driver.dialect;
   }
 
@@ -224,7 +229,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     const scope = this.scopeFor(from, "read");
     if (!scope.allowed) throw new AclDenied(from, "read");
 
-    const where = this.readWhere(spec.where, scope);
+    const where = this.readWhere(from, spec.where, scope);
     const orderBy = normalizeOrder(spec.orderBy);
     if (orderBy) this.assertReadableCols(from, scope, orderBy.map((o) => o.column));
     const raw = await this.selectRaw(from, where, orderBy, spec.limit, spec.offset);
@@ -245,7 +250,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
 
     const order = this.orderWithPk(from, spec.orderBy);
     this.assertReadableCols(from, scope, order.map((o) => o.column)); // order + cursor must not leak hidden cols
-    let where = this.readWhere(spec.where, scope);
+    let where = this.readWhere(from, spec.where, scope);
     if (spec.after != null) where = and(where, keysetAfter(order, decodeCursor(spec.after)));
 
     const limit = spec.limit ?? DEFAULT_PAGE_SIZE;
@@ -261,12 +266,12 @@ export class Db<S extends SchemaDef = SchemaDef> {
   }
 
   /** Count rows visible to the caller (ACL read scope applied). */
-  async count<T extends keyof S & string>(spec: { from: T; where?: WhereInput<FieldsOf<S[T]>> }): Promise<number> {
+  async count<T extends keyof S & string>(spec: { from: T; where?: WhereClause<S, T> }): Promise<number> {
     const from = spec.from as string;
     this.touched.add(from);
     const scope = this.scopeFor(from, "read");
     if (!scope.allowed) throw new AclDenied(from, "read");
-    const where = this.readWhere(spec.where, scope);
+    const where = this.readWhere(from, spec.where, scope);
     const { sql, params } = compileCount(from, this.dialect, where);
     const rows = (await this.driver.exec(sql, params)) as { n: number }[];
     return Number(rows[0]?.n ?? 0);
@@ -282,7 +287,7 @@ export class Db<S extends SchemaDef = SchemaDef> {
     G extends (keyof FieldsOf<S[T]> & string) | (keyof FieldsOf<S[T]> & string)[] = never,
   >(spec: {
     from: T;
-    where?: WhereInput<FieldsOf<S[T]>>;
+    where?: WhereClause<S, T>;
     groupBy?: G;
     aggregations: A;
   }): Promise<AggregateResult<FieldsOf<S[T]>, G, A>[]> {
@@ -309,18 +314,41 @@ export class Db<S extends SchemaDef = SchemaDef> {
       for (const c of refs) if (!scope.fields.includes(c)) throw new AclDenied(from, "read", c);
     }
 
-    const where = this.readWhere(spec.where, scope);
+    const where = this.readWhere(from, spec.where, scope);
     const { sql, params } = compileAggregate({ from, where, groupBy, aggregations: spec.aggregations }, this.dialect);
     return (await this.driver.exec(sql, params)) as AggregateResult<FieldsOf<S[T]>, G, A>[];
   }
 
   // --- read internals shared by find/page ---
 
-  private readWhere(userWhere: unknown, scope: Scope): SqlExpr {
-    const userExpr: SqlExpr = userWhere ? compileWhere(userWhere as Row) : TRUE;
+  private readWhere(from: string, userWhere: unknown, scope: Scope): SqlExpr {
+    // Compiles the user's where relation-aware (relation keys → security-scoped
+    // subqueries), then AND-merges the entity's own ACL row scope.
+    if (userWhere) this.assertReadableWhere(from, scope, userWhere);
+    const userExpr: SqlExpr = userWhere ? compileScopedWhere(userWhere as Record<string, unknown>, from, this.acl) : TRUE;
     return scope.where ? and(userExpr, scope.where) : userExpr;
   }
 
+  /** Reject a user `where` that filters on a column the caller cannot read (closes
+   * the same info-leak as ordering by a hidden column: a filter is an oracle for a
+   * hidden field's values). Mirrors `assertReadableCols`. Relation keys are skipped
+   * here — they're filtered through the TARGET's read scope in acl.relationPredicate
+   * — and AND/OR groups recurse. Operator objects (`{ gt: … }`) sit under the column
+   * key, so checking the top-level keys is sufficient. */
+  private assertReadableWhere(from: string, scope: Scope, where: unknown): void {
+    if (scope.fields === null || where == null || typeof where !== "object") return;
+    const relations = this.schema[from]?.relations ?? {};
+    for (const [k, v] of Object.entries(where as Record<string, unknown>)) {
+      if (k === "AND" || k === "OR") {
+        for (const g of v as unknown[]) this.assertReadableWhere(from, scope, g);
+      } else if (relations[k]) {
+        continue; // relation traversal: enforced against the target's scope downstream
+      } else if (!scope.fields.includes(k)) {
+        throw new AclDenied(from, "read", k);
+      }
+    }
+  }
+
   private async selectRaw(from: string, where: SqlExpr, orderBy?: OrderBy[], limit?: number, offset?: number): Promise<Row[]> {
     const { sql, params } = compileSelect({ from, where, orderBy, limit, offset }, this.dialect);
     return this.decodeRows(from, await this.driver.exec(sql, params));

package/src/runtime/dispatch.ts

@@ -50,10 +50,10 @@ export async function dispatch(
 
   // Warmup: evaluate dynamic resolvers once, reading through a SYSTEM-mode db
   // (separate from the handler's db, so its reads don't pollute `touched`).
-  const systemDb = new Db(driver, { acl: acl.acl, identity: acl.identity, system: true }, schema);
+  const systemDb = new Db(driver, { acl: acl.acl, identity: acl.identity, system: true, schema }, schema);
   const resolved = await warmup(acl.acl, acl.identity, systemDb as unknown as ResolverDb);
 
-  const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved }, schema);
+  const db = new Db(driver, { acl: acl.acl, identity: acl.identity, input: parsed, resolved, schema }, schema);
   const ctx: HandlerContext = { db, kv, files, env, identity: acl.identity };
 
   const result =

package/src/runtime/read-engine.ts

@@ -23,7 +23,11 @@ export type SqlExpr =
   | { t: "in"; col: string; values: unknown[]; negate: boolean }
   | { t: "null"; col: string; negate: boolean }
   | { t: "and"; parts: SqlExpr[] }
-  | { t: "or"; parts: SqlExpr[] };
+  | { t: "or"; parts: SqlExpr[] }
+  // Relation traversal: `outerCol IN (SELECT selectCol FROM from WHERE where)`.
+  // Built by the ACL layer (which knows schema + the target's read scope); the
+  // inner predicate compiles inline so placeholders share the outer param sequence.
+  | { t: "sub"; outerCol: string; from: string; selectCol: string; where: SqlExpr; negate: boolean };
 
 export const TRUE: SqlExpr = { t: "true" };
 export const FALSE: SqlExpr = { t: "false" };
@@ -104,6 +108,16 @@ export function compileExpr(expr: SqlExpr, dialect: Dialect, params: unknown[] =
       const sql = expr.parts.map((p) => compileExpr(p, dialect, params).sql).join(sep);
       return { sql: expr.parts.length > 1 ? `(${sql})` : sql, params };
     }
+    case "sub": {
+      // Inner predicate shares `params`, so placeholder numbering stays correct
+      // across dialects (? and $n alike).
+      const inner = compileExpr(expr.where, dialect, params).sql;
+      const op = expr.negate ? "NOT IN" : "IN";
+      return {
+        sql: `${dialect.id(expr.outerCol)} ${op} (SELECT ${dialect.id(expr.selectCol)} FROM ${dialect.id(expr.from)} WHERE ${inner})`,
+        params,
+      };
+    }
   }
 }
 
@@ -161,6 +175,10 @@ export function evalExpr(expr: SqlExpr, row: Record<string, unknown>): boolean {
       return expr.parts.every((p) => evalExpr(p, row));
     case "or":
       return expr.parts.some((p) => evalExpr(p, row));
+    case "sub":
+      // Relation traversal needs a SQL round-trip; it isn't supported in the
+      // in-memory cell-ACL `when` evaluator (those predicates must be single-table).
+      throw new Error("relation predicates are not supported in cell-level `when`");
   }
 }
 

package/src/sdk/infer.ts

@@ -62,6 +62,23 @@ export type WhereInput<F extends EntityFields> = {
   OR?: WhereInput<F>[];
 };
 
+// --- relation-aware where (a relation key takes a nested clause over its target,
+// compiled to a security-scoped subquery). Depth-bounded so the type stays finite
+// under cyclic relations (e.g. user.notes ↔ note.owner). The bound matches the
+// runtime MAX_REL_DEPTH in runtime/acl.ts — keep the two in lockstep. ---
+
+type PrevDepth = [never, 0, 1, 2, 3, 4, 5];
+type RelTargetTable<S extends SchemaDef, R> = R extends { target: infer Tg } ? (Tg extends keyof S ? Tg : never) : never;
+
+/** A `where` clause: column predicates + AND/OR, plus relation keys that take a
+ * nested `WhereClause` over the related entity (traversal). */
+export type WhereClause<S extends SchemaDef, T extends keyof S, D extends number = 5> = WhereInput<FieldsOf<S[T]>> &
+  ([D] extends [never]
+    ? object
+    : {
+        [K in keyof RelationsOf<S[T]>]?: WhereClause<S, RelTargetTable<S, RelationsOf<S[T]>[K]>, PrevDepth[D]>;
+      });
+
 /** Patch input for updates: every column optional, value typed (nullable). */
 export type InferUpdate<F extends EntityFields> = Partial<{ [K in keyof F]: FieldTsType<F[K]> | null }>;