@pramen/server 0.0.1 → 0.0.2

package/dist/auth.d.ts

@@ -28,8 +28,12 @@ export declare class JwksStrategy implements VerifyStrategy {
 }
 export declare function resolveIdentity(request: Request, strategy: VerifyStrategy): Promise<Identity | 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). */
+ * 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 declare function authorizeTenant(identity: Identity | null, tenant: string): boolean;
 export declare function isAdmin(identity: Identity | null): boolean;

package/dist/auth.js

@@ -170,15 +170,18 @@ export async function resolveIdentity(request, strategy) {
     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). */
+ * 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, tenant) {
-    // 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 (tenant === "main")
+        return true;
     if (!identity)
-        return tenant === "main";
+        return false;
     if (identity.roles?.includes("admin"))
         return true;
     const allowed = Array.isArray(identity.tenants) ? identity.tenants : [];

package/dist/durable-object.d.ts

@@ -34,6 +34,7 @@ export declare class PramenDOBase extends DurableObject<DoEnv> {
     private ensureRegistered;
     private handleRecover;
     private handleSchema;
+    private handleAdminData;
     private ctxFor;
     private get envBag();
     private filesFor;

package/dist/durable-object.js

@@ -17,6 +17,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 } from "./runtime/acl";
 import { DoSqliteDriver } from "./runtime/driver";
@@ -59,6 +60,8 @@ export class PramenDOBase extends DurableObject {
             return this.handleRecover(request);
         if (path === "/__schema")
             return this.handleSchema();
+        if (path === "/__admin/data")
+            return this.handleAdminData(request);
         const identity = this.identityOf(request);
         if (request.headers.get("Upgrade") === "websocket") {
             const { 0: client, 1: server } = new WebSocketPair();
@@ -232,8 +235,59 @@ export class PramenDOBase extends DurableObject {
         }
         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.
+    async handleAdminData(request) {
+        const b = (await request.json().catch(() => ({})));
+        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);
+        try {
+            let result;
+            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 });
+        }
+    }
     ctxFor(identity) {
-        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
     // typed at the boundary so handlers can read any var/secret without a DoEnv cast.

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { query, mutation } from "./sdk/handlers";
 export type { Handler, HandlerContext, HandlerKind, HandlerMap, HandlerOpts } from "./sdk/handlers";
 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";
-export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereInput, WhereOps, } from "./sdk/infer";
+export type { Cell, FieldsOf, InferInsert, InferRow, InferUpdate, JsonValue, ProjectedRow, RelationsOf, RelationsResult, WhereClause, WhereInput, WhereOps, } from "./sdk/infer";
 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";

package/dist/runtime/acl.d.ts

@@ -1,6 +1,7 @@
 import { type Action, type FieldsFn, type Identity, type PolicyRule, type ResolverDb, type Role, type Validator } from "../sdk/acl";
 import { type SqlExpr } from "./read-engine";
 import { PramenError } from "./errors";
+import type { SchemaDef } from "../sdk/schema";
 export declare class AclDenied extends PramenError {
     readonly entity: string;
     readonly action: Action;
@@ -22,6 +23,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.
  * Resolvers read through a SYSTEM-mode db (ACL bypassed) to avoid recursion. */
@@ -44,7 +48,29 @@ export interface Scope {
     readonly fieldsFns: FieldsFn[];
 }
 export declare const ALLOW_ALL: Scope;
-export declare function resolveScope(ctx: AclContext, entity: string, action: Action): Scope;
+/** 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 declare const MAX_REL_DEPTH = 5;
+/** 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 declare function compileScopedWhere(rule: Record<string, unknown>, entity: string, ctx: AclContext, depth?: number, allowRelations?: boolean): SqlExpr;
+export declare function resolveScope(ctx: AclContext, entity: string, action: Action, depth?: number): Scope;
 /** Effective visible fields for one row = base ∪ matching-conditional ∪ fn-output.
  * Returns null (all fields) when the base is null or a resolver grants everything. */
 export declare function effectiveFields(scope: Scope, row: Record<string, unknown>, identity: Identity | null): string[] | null;

package/dist/runtime/acl.js

@@ -3,8 +3,8 @@
 // granted, the row-level predicate to merge into the query, and any field
 // restriction. Deny-by-default; grants OR-merge across the identity's roles.
 import { deny, isAllow, isDeny, isIdentityMarker, isInputMarker, isResolver, } from "../sdk/acl";
-import { compileWhere, evalExpr, FALSE, or } from "./read-engine";
-import { PramenError } from "./errors";
+import { and, compileWhere, evalExpr, FALSE, or, TRUE } from "./read-engine";
+import { BadRequest, PramenError } from "./errors";
 export class AclDenied extends PramenError {
     entity;
     action;
@@ -55,14 +55,16 @@ export function compileAcl(roles) {
 }
 export const ALLOW_ALL = { allowed: true, where: null, fields: null, conditional: [], fieldsFns: [] };
 const DENIED = { allowed: false, where: null, fields: null, conditional: [], fieldsFns: [] };
-/** Build a grant from a policy/relation rule, resolving $identity markers in
- * `where` and each conditional `when`. */
-function grantOf(rule, where, identity, input) {
+/** 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, where, entity, ctx, depth) {
     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, entity, ctx, depth, false),
             fields: cf.fields,
         })),
         fieldsFns: rule.fieldsFn ? [rule.fieldsFn] : [],
@@ -97,23 +99,18 @@ function resolveValue(v, identity, input) {
     }
     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, identity, input) {
     const out = {};
     for (const [key, v] of Object.entries(rule)) {
-        if (key === "AND" || key === "OR") {
-            const groups = [];
-            for (const g of v) {
-                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 = {};
@@ -153,12 +150,106 @@ function resolveMarkers(rule, identity, input) {
     }
     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, identity, input) {
-    const resolved = resolveMarkers(rule, 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, entity) {
+    const fields = schema?.[entity]?.fields;
+    if (fields)
+        for (const [n, f] of Object.entries(fields))
+            if (f.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, nested, parentEntity, ctx, depth) {
+    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, 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 ?? {});
+                for (const k of Object.keys(nested)) {
+                    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, entity, ctx, depth = 0, allowRelations = true) {
+    const relations = (ctx.schema?.[entity]?.relations ?? {});
+    const parts = [];
+    const plain = {};
+    for (const [k, v] of Object.entries(rule)) {
+        if (k === "AND" || k === "OR") {
+            const groups = v.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
  * resolvers replaced by their warmup result and resolver/unresolved entries dropped. */
@@ -211,15 +302,17 @@ function mergeGrants(grants) {
         fieldsFns,
     };
 }
-export function resolveScope(ctx, entity, action) {
+export function resolveScope(ctx, entity, action, depth = 0) {
     const grants = [];
     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 ?? {}), entity, ctx, depth);
+            grants.push(grantOf(rule, where, entity, ctx, depth));
+        }
     }
     return mergeGrants(grants);
 }
@@ -272,7 +365,8 @@ export function resolveRelationScope(ctx, parentEntity, relName, target) {
             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, target, ctx, 0) : null;
+            grants.push(grantOf(rel, relWhere, target, ctx, 0));
         }
     }
     return mergeGrants(grants);

package/dist/runtime/db.d.ts

@@ -2,7 +2,7 @@ import { type AclContext } from "./acl";
 import { type AggFn } from "./read-engine";
 import type { Driver } from "./driver";
 import type { EntityFields, 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 Id = string | number | bigint;
 type OrderSpec<S extends SchemaDef, T extends keyof S> = {
@@ -11,7 +11,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;
@@ -21,7 +21,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;
@@ -40,7 +40,7 @@ type Aggregations<F extends EntityFields> = Record<string, {
 }>;
 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]>>;
 }
@@ -59,11 +59,11 @@ export type AggregateResult<F extends EntityFields, G, A extends Aggregations<F>
 };
 export declare class Db<S extends SchemaDef = SchemaDef> {
     private readonly driver;
-    private readonly acl;
     private readonly schema;
     /** Tables read or written during this Db's lifetime. */
     readonly touched: Set<string>;
     private readonly dialect;
+    private readonly acl;
     constructor(driver: Driver, acl: AclContext, schema: SchemaDef);
     /** Resolve the ACL scope for an operation, or grant everything in SYSTEM mode. */
     private scopeFor;
@@ -91,7 +91,7 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
     /** Count rows visible to the caller (ACL read scope applied). */
     count<T extends keyof S & string>(spec: {
         from: T;
-        where?: WhereInput<FieldsOf<S[T]>>;
+        where?: WhereClause<S, T>;
     }): Promise<number>;
     /** Grouped aggregation (count/sum/avg/min/max). ACL read scope is applied, and
      * every referenced column must be readable under field permissions. The result
@@ -99,11 +99,18 @@ export declare class Db<S extends SchemaDef = SchemaDef> {
      * each aggregation gets its computed value type. */
     aggregate<T extends keyof S & string, A extends Aggregations<FieldsOf<S[T]>>, 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>[]>;
     private readWhere;
+    /** 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;
     private selectRaw;
     private jsonColsOf;
     private decodeRows;

package/dist/runtime/db.js

@@ -10,8 +10,8 @@
 // Every Db also records the tables it touched during one handler run (`touched`),
 // which the live-query layer uses to decide which subscriptions to re-check.
 // Create a fresh Db per handler run so identity and `touched` are scoped.
-import { AclDenied, ALLOW_ALL, effectiveFields, projectRow, resolveRelationScope, resolveScope, resolveWriteRules, } from "./acl";
-import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, compileWhere, eq, inList, or, TRUE, } from "./read-engine";
+import { AclDenied, ALLOW_ALL, compileScopedWhere, effectiveFields, projectRow, resolveRelationScope, resolveScope, resolveWriteRules, } from "./acl";
+import { and, cmp, compileAggregate, compileCount, compileExpr, compileSelect, eq, inList, or, TRUE, } from "./read-engine";
 import { BadRequest } from "./errors";
 const DEFAULT_PAGE_SIZE = 50;
 function normalizeOrder(orderBy) {
@@ -50,15 +50,18 @@ function keysetAfter(order, values) {
 }
 export class Db {
     driver;
-    acl;
     schema;
     /** Tables read or written during this Db's lifetime. */
     touched = new Set();
     dialect;
+    acl;
     constructor(driver, acl, schema) {
         this.driver = driver;
-        this.acl = acl;
         this.schema = schema;
+        // 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;
     }
     /** Resolve the ACL scope for an operation, or grant everything in SYSTEM mode. */
@@ -116,7 +119,7 @@ export class Db {
         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));
@@ -134,7 +137,7 @@ export class Db {
             throw new AclDenied(from, "read");
         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;
@@ -154,7 +157,7 @@ export class Db {
         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));
         return Number(rows[0]?.n ?? 0);
@@ -190,15 +193,42 @@ export class Db {
                 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));
     }
     // --- read internals shared by find/page ---
-    readWhere(userWhere, scope) {
-        const userExpr = userWhere ? compileWhere(userWhere) : TRUE;
+    readWhere(from, userWhere, scope) {
+        // 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 = userWhere ? compileScopedWhere(userWhere, 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. */
+    assertReadableWhere(from, scope, where) {
+        if (scope.fields === null || where == null || typeof where !== "object")
+            return;
+        const relations = this.schema[from]?.relations ?? {};
+        for (const [k, v] of Object.entries(where)) {
+            if (k === "AND" || k === "OR") {
+                for (const g of v)
+                    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);
+            }
+        }
+    }
     async selectRaw(from, where, orderBy, limit, offset) {
         const { sql, params } = compileSelect({ from, where, orderBy, limit, offset }, this.dialect);
         return this.decodeRows(from, await this.driver.exec(sql, params));

package/dist/runtime/dispatch.js

@@ -26,9 +26,9 @@ export async function dispatch(handlers, schema, driver, kv, files, env, acl, na
     }
     // 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);
-    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 = { db, kv, files, env, identity: acl.identity };
     const result = handler.kind === "query"
         ? await handler.run(ctx, parsed)

package/dist/runtime/read-engine.d.ts

@@ -24,6 +24,13 @@ export type SqlExpr = {
 } | {
     t: "or";
     parts: SqlExpr[];
+} | {
+    t: "sub";
+    outerCol: string;
+    from: string;
+    selectCol: string;
+    where: SqlExpr;
+    negate: boolean;
 };
 export declare const TRUE: SqlExpr;
 export declare const FALSE: SqlExpr;

package/dist/runtime/read-engine.js

@@ -105,6 +105,16 @@ export function compileExpr(expr, dialect, params = []) {
             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,
+            };
+        }
     }
 }
 // SQL LIKE -> RegExp. `%` is any run, `_` is any single char; SQLite LIKE is
@@ -167,6 +177,10 @@ export function evalExpr(expr, row) {
             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`");
     }
 }
 const AGG_SQL = { count: "COUNT", sum: "SUM", avg: "AVG", min: "MIN", max: "MAX" };