@aventara/access 0.0.0-stage → 1.0.0-rc.1

package/skill/reference/rules.md

@@ -0,0 +1,153 @@
+# The rule language
+
+`definePolicies(model, options?)` takes the schema and returns an immutable builder; each call returns a new builder.
+In an Aventara app the schema is the discovery artifact's `model` (`./generated/aventara/discovery.artifact.js`; in
+Next.js `@/aventara/generated/discovery.artifact`). Every name in a rule is checked against it.
+
+| Call | What it does |
+|---|---|
+| `.principal<P>()` | Types `me` in every callback. Call it first. Without it, `me.id` and `claims` are type errors. |
+| `.roles(({ me }) => ({ … }))` | Names roles: `global` (from claims) or held `on` a Resource's row (`where`) |
+| `.govern(Resource, [fields])` | Governs fields for reading and writing: only a grant that names one opens it |
+| `.govern(Resource, { field: mode })` | Governs each field for `"write"`, `"read"` or `"both"` |
+| `.grants(({ grant, me }) => [ … ])` | `grant(subjects, actions, resource, options?)`. Calls add up. |
+| `.denies(({ deny, me }) => [ … ])` | `deny(actions, resource, options?)`. Calls add up. |
+| `.contract()` | Compiles to the `aventara-access/policies@1` file (`AccessPolicies`) |
+| `.engine(options?)` | The engine (`AccessEngine`), from the compiled file |
+
+Declare roles and governed fields before the grants that name them: the grant's types read them.
+
+## Subjects, actions, resources
+
+- Subjects: `"signedIn"` (any non-null principal), `"anyone"` (the anonymous caller too), or a role name. One or a
+  list: `["dm", "player"]`.
+- Actions: `"read"`, `"create"`, `"update"`, `"delete"`, one or a list. A deny also takes `"*"`.
+- Resource: one of your own Resources, or `"*"` (every Resource the file owns). A foreign Resource (`{ foreign }` in the
+  schema) is read in conditions and never granted, denied or governed on.
+
+## The principal
+
+The principal is whatever your app derives for a request: with `createAccess`, what `principal` returns (or the token's
+identity `{ sub, claims }`, typed `AccessIdentity<typeof claims>`). It is an object; `null`, an array, a function or a
+primitive is anonymous. Its values are read from its own properties only. `me.<path>` in a rule is a reference read at
+question time, never a value baked into the file.
+
+`claims` on the principal is what roles and `if` compare: `{ claims: { role?: "admin"; banned?: boolean } }`.
+
+## Roles
+
+```text
+.roles(({ me }) => ({
+  // global: held when every listed claim equals its value
+  admin: { global: { claims: { role: "admin" } } },
+  // on a row: held on each Campaign row the where matches
+  dm: { on: "Campaign", where: { members: { some: { userId: me.id, role: "DM" } } } },
+}))
+```
+
+A grant to a row role covers the rows where the caller holds it. On another Resource, `in: "<to-one relation>"` says
+the role is held on that relation's target: `grant("dm", "read", "Note", { in: "campaign" })` covers the notes of the
+campaigns where the caller is DM. In a `where`, `$role: "dm"` means the caller holds that role on this row
+(`campaign: { $role: "player" }` on the related row).
+
+## Grant options
+
+| Option | Meaning |
+|---|---|
+| `name` | The rule's id in `explain` and the audit log (default `Resource/actions/subjects#n`) |
+| `where` | The rows the grant covers. On an update grant it is checked on the row the update leaves too. |
+| `in` | The to-one relation whose target holds the subject's row role |
+| `fields` | Governed fields the grant opens, as `"Resource.field"` |
+| `write: { except: [...] }` | Fields a create or update by this grant may not set (create and update grants only) |
+| `after` | What the row an update leaves must also meet (update grants only) |
+
+## Deny options
+
+| Option | Meaning |
+|---|---|
+| `name` | The rule's id |
+| `where` | The rows the deny covers |
+| `if: { claims, origin }` | A condition on the caller alone: claim values, and the origin (`"client"`, `"agent"`, `"application"`) |
+
+A deny with neither `where` nor `if` refuses its actions on its Resource to everyone.
+
+## `where`
+
+Aventara's `where` vocabulary, typed per Resource:
+
+- a field and a value (`visibility: "PARTY"`, `authorId: me.id`), or an operator object: `equals`, `not`, `in`,
+  `notIn` (`{ visibility: { in: ["PARTY", "PRIVATE"] } }`);
+- `AND: [ … ]`, `OR: [ … ]`, `NOT: { … }`;
+- a to-one relation by its own `where` (`campaign: { … }`); a to-many by `some`, `every` or `none`;
+- `$role: "<row role on this Resource>"`.
+
+Compare values of the field's type. Through Aventara, a scope that compares a `datetime`, `decimal` or `bigint` field
+cannot be used yet (`A3000`, the request is refused): keep those comparisons out of `where` on reads, updates and
+deletes.
+
+## How the rules combine
+
+- Nothing is allowed until a grant allows it. Any grant that matches allows. Any deny that matches wins over every
+  grant, an admin's included. Order never matters.
+- A grant that reads a `me` value the principal lacks never matches. A deny that reads one in its `where` matches,
+  whatever `not` or `NOT` surrounds it. A missing or `null` property, an empty string, or a number JSON cannot carry
+  counts as missing.
+- A claim the principal lacks fails closed the same way: a global role comparing it is not held; a deny's `if`
+  comparing it holds. The anonymous caller has no claims: a comparison with `true` never holds for it (a ban does not
+  close an `anyone` grant), and any other comparison holds for a deny.
+- A row value of another type than its field's is unknown: no grant matches it, a deny that compares it matches.
+
+## Governed fields
+
+A governed field is opened only by a grant that names it in `fields`. Each field has a mode:
+
+| Form | Reads | Writes |
+|---|---|---|
+| `.govern("User", ["email"])` (the list: `"both"`) | Out of every default read; only a read grant naming `User.email` opens it, when the request selects it | Only a create or update grant naming it sets it |
+| `.govern("Member", { role: "write" })` | As any other field | Only a create or update grant naming `Member.role` sets it |
+| `.govern("Citizen", { nationalId: "read" })` | As `"both"` | As any other field |
+
+Govern every field your roles, claims or principal read, usually as `"write"`: a role held on `Member` reads
+`Member.role`, so an update grant on `Member` that does not name it must not change it. Selecting a field governed for
+reading without a grant that opens it is refused (`403 A4002`), never dropped quietly. A relation and its reference
+fields are governed together, with one mode (`"author"` with `"authorId"`). A field governed twice with two modes is a
+type error, and refused when the rules compile. `fields` on a Resource with nothing governed is a type error.
+
+Access governs Better Auth's `User.role` and the organization `member` table's `role` as `"write"` itself once
+`resources` opens them. To let an admin set one, govern it too (`.govern("User", { role: "write" })`), which lets a
+grant name it, and name it in that admin's grant.
+
+## Updates
+
+An update is checked twice: its scope (the rows an update grant's `where` covers and no update deny matches), then
+each row it leaves, which must be covered by the same grant (its `where` and `after` together) and matched by no update
+deny. So `where: { authorId: me.id }` on an update grant also stops the author from handing the row to someone else.
+Aventara runs the second check inside the update's transaction and rolls back on failure; on a database without
+interactive transactions it refuses such updates.
+
+## References
+
+A create or update that sends a reference (`Note.authorId`) to a Resource the app serves is held to the rows the caller
+may read there: no read grant on the target, no write (`A4002`), whatever the write grant allows. When the framework
+starts, Access warns `ACCESS_REFERENCE_UNREADABLE` for each role that may write a reference it cannot read. Fix it with
+a read grant on the target for that role, narrowed as far as the feature allows, or lock the reference with
+`write: { except }`.
+
+## Guardrails
+
+An org's guardrails (`defineGuardrails({ claims }).denies(…).contract()`) are deny-only rules every service adds on
+top of its own; they never grant. A service gets them with `avaccess pull` and passes them as `policies.guardrails`.
+See the README's Guardrails section.
+
+## Asking the engine
+
+| Method | Answers |
+|---|---|
+| `can({ principal, origin, resource, action, row?, before?, beforeGrants?, exists? })` | Whether the principal may do it, on `row` when given. On an update, `before` is the row as stored, and `beforeGrants` what `grantsOf` answered for it before the write |
+| `grantsOf({ principal, origin, resource, action: "update", row, exists? })` | The update grants that cover `row` as it is now. Ask it before the write |
+| `scopeOf({ principal, origin, resource, action })` | `true`, `false`, or an Aventara `where` (read, update, delete) |
+| `fieldsOf({ principal, origin, resource, access: "read" })` | The fields usable on every reachable row (`always`) and on some only (`perRow`); `access: "write"` takes an optional `action` |
+| `explain(question)` | In development, which rules took part in a `can` decision. It throws when `NODE_ENV` is `production`. |
+
+For an update, always pass `before` (the row as stored). Without it only the new row is checked, and a caller can take
+over another user's row. Prefer routing writes through the framework, which does both checks.

package/skill/reference/setup.md

@@ -0,0 +1,334 @@
+# Setup and wiring
+
+Three ways in. Pick one:
+
+| The app | Use | Section |
+|---|---|---|
+| A new or existing Aventara app, Better Auth not set up yet | `createAccess()` from `@aventara/access/auth` | [createAccess](#createaccess) |
+| An app that already calls `betterAuth({...})` itself | `aventaraAccess()` and `accessOf(auth)` from `@aventara/access/better-auth` | [The Better Auth plugin](#the-better-auth-plugin) |
+| Its own authentication, rules only | `definePolicies(…).engine()` on the framework's `policy` option | [The engine alone](#the-engine-alone) |
+
+## Install
+
+```sh
+npm install --save-exact @aventara/access@rc better-auth@~1.7.12
+# Node.js 22 only (Node.js 24.7 and later hash with crypto.argon2):
+npm install --save-exact @node-rs/argon2@2.2.2
+```
+
+Node.js `^22.23.4 || >=24.22.1`, ESM. Another Better Auth version is refused when `createAccess` runs
+(`ACCESS_BETTER_AUTH_VERSION`). Agents over MCP also need `@better-auth/oauth-provider@~1.7.12` (and
+`@better-auth/cimd@~1.7.12` for clients that register by a metadata URL).
+
+`.env` needs `DATABASE_URL`, `BETTER_AUTH_SECRET` (a long random string) and `BETTER_AUTH_URL` (the app's origin,
+`http://localhost:3000` in development). Access fixes its tokens' issuer and audience to that URL's origin and refuses
+to start without one (`ACCESS_OPTIONS_INVALID`).
+
+## createAccess
+
+```ts
+// src/access.ts
+import { createAccess } from "@aventara/access/auth";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { prismaAdapter } from "better-auth/adapters/prisma";
+import { PrismaClient } from "./generated/prisma/client.js";
+import { teamPolicies } from "./team.policies.js";
+
+/** Better Auth's own Prisma client: it reads and writes its tables through it. */
+const prisma = new PrismaClient({
+	adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL ?? "" }),
+});
+
+/** What every token carries beside `sub`, by type. */
+const claims = { role: "string", banned: "boolean" } as const;
+
+export const access = createAccess({
+	// Better Auth's options, exactly as betterAuth({...}) takes them.
+	betterAuth: {
+		database: prismaAdapter(prisma, { provider: "postgresql" }),
+		emailAndPassword: { enabled: true },
+		user: {
+			additionalFields: {
+				// input: false: the user cannot set these at sign-up or with /update-user.
+				role: { type: "string", required: false, input: false },
+				banned: { type: "boolean", required: false, input: false },
+			},
+		},
+	},
+	policies: { rules: teamPolicies, claims },
+	// Map the verified token to the rules' principal. Keep the claims as they are.
+	principal: ({ sub, claims }) => ({
+		id: sub,
+		claims: {
+			...(claims.role === "admin" ? { role: "admin" as const } : {}),
+			...(claims.banned === undefined ? {} : { banned: claims.banned }),
+		},
+	}),
+	// The rules read User, one of Better Auth's tables: open it explicitly.
+	resources: { users: true },
+});
+
+export default access;
+```
+
+- `betterAuth` is Better Auth's own options, passed through untouched. Access's concerns sit beside it: `policies`,
+  `principal`, `resources`, `audit`, `passwords`, `profile`, `registry`, `mcp`, `audience`. Anything else is refused
+  (`ACCESS_OPTIONS_INVALID`).
+- `policies.claims` declares every claim the rules (and guardrails) read: `"string"`, `"number"` or `"boolean"`. Each
+  is read from the user's field of the same name, which must have `input: false`. A token carries `sub` and the
+  declared claims only; every declared boolean claim is in it, `false` when the user's field is unset.
+- `principal` maps `{ sub, claims }` to the rules' principal. Return a new object per user, keep `claims` as given (a
+  boolean claim you drop reads as missing, and a `banned: true` deny then refuses the caller), and return `null` to
+  leave the caller anonymous. Leave `principal` out when the rules are typed with `AccessIdentity<typeof claims>`
+  (`{ sub, claims }`, from `@aventara/access/auth`).
+- `policies.tokenTtl` (seconds, 300 to 900, default 900) is how long a ban or a role change can take to reach a
+  token. Keep it short when that matters.
+- Passwords are hashed with argon2id (`"owasp-minimum"` by default). `passwords: { argon2id, legacyScrypt: true }` lets
+  users whose hashes Better Auth stored with scrypt sign in and moves them to argon2id. Do not set both `passwords` and
+  `betterAuth.emailAndPassword.password`.
+- With `emailAndPassword` on, anyone who reaches the server can sign up. When users are created another way (an admin,
+  an invitation, a social provider), set `emailAndPassword: { enabled: true, disableSignUp: true }`.
+- `audit: true` writes every sign-in, token and decision to an `accessAudit` table; `audit: { sink }` hands each
+  `AccessAuditEvent` to your function instead.
+
+### The scaffold's numeric ids
+
+`aventara new` writes `model User { id Int @id @default(autoincrement()) … }`; Better Auth's ids are strings. Before
+generating Better Auth's tables, put `advanced: { database: { generateId: "serial" } }` in the `betterAuth` block, type
+the principal's `id` as `number` and map it:
+
+```text
+principal: ({ sub, claims }) => ({ id: Number(sub), claims: { … } }),
+```
+
+A rule comparing `User.id` with a string is then a type error, which is what you want.
+
+### Better Auth's tables
+
+```sh
+npx auth@~1.7.12 generate --config src/access.ts --yes   # Better Auth's models into prisma/schema.prisma
+npx prisma validate
+npx prisma db push                                      # or your migration
+npm run aventara:prepare                                # the rules see the new model
+```
+
+`generate` reads the module's default export. Access closes every Better Auth table to every request until a
+`resources` key opens it: `users: true` opens `user` (writes: an update of `role` only), `session` and `account` (read
+only); `members: true` opens the organization plugin's `member` and `organization` (and needs
+`requireEmailVerificationOnInvitation: true` on `organization()`). `verification`, `jwks`, `invitation`, `twoFactor`,
+`deviceCode` and Access's own tables never open. Secret columns are sealed on every table: exempt them from your
+Contracts, or govern them, so a read that names no field leaves them out instead of being refused. Off Prisma's
+adapter, `resources.authTables` must map every Better Auth table to its Resource (or `null`).
+
+`users: true` lets a write through Aventara set a user's `role`, and `role` is a claim, so Access governs it as
+`"write"`: only an update grant that names `User.role` sets it. To let an admin set roles, add
+`.govern("User", { role: "write" })` to the rules (so a grant may name it) and `fields: ["User.role"]` to that admin's
+update grant, ideally with `where: { NOT: { id: me.id } }` so an admin cannot change their own role. Never name it in a
+grant for `signedIn`, `anyone` or any role a user can reach on their own. Users edit their profile through Better
+Auth's `/update-user`. With `members: true`, the `member` table's `role` is governed the same way: name it only in an
+organization admin role's grant, held to `where: { organizationId: me.org }`.
+
+## Mount the routes
+
+Access's routes are Better Auth's plus its own, under `/api/auth`. The framework mounts none of them. In NestJS (Express
+or Fastify), mount the Node.js handler before the body parser:
+
+```ts
+// src/main.ts
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { NestFactory } from "@nestjs/core";
+import { toNodeHandler } from "better-auth/node";
+import { access } from "./access.js";
+import { AppModule } from "./app.module.js";
+
+async function bootstrap() {
+	const app = await NestFactory.create(AppModule);
+	// Access's routes, under /api/auth, before Nest's body parser (listen() adds it).
+	const auth = toNodeHandler(access);
+	app.use(
+		(request: IncomingMessage, response: ServerResponse, next: () => void) =>
+			request.url?.startsWith("/api/auth/") ? auth(request, response) : next(),
+	);
+	await app.listen(process.env.PORT ?? 3000);
+}
+await bootstrap();
+```
+
+Keep the CORS and rate-limit lines the scaffold wrote, before this mount. A request to Better Auth that carries a cookie
+needs an `Origin` header matching `BETTER_AUTH_URL` or one of `trustedOrigins` (else `403 MISSING_OR_NULL_ORIGIN` or
+`INVALID_ORIGIN`).
+
+## Wire it into the framework
+
+The instance fits the framework's `access` option (`AvAccessProvider`) by shape: `access.policy` is the engine asked
+about every client and agent request, and `access.state({ headers, request })` seeds each request's `ctx.$state` with
+`{ me }`. With `access`, the configuration has no `policy` key and the host has no `state` option.
+
+```ts
+// src/app.module.ts
+import { Module } from '@nestjs/common';
+import { AppController } from './app.controller.js';
+import { AppService } from './app.service.js';
+import { AventaraModule } from '@aventara/nest';
+import { createPrismaAdapter } from '@aventara/prisma7-adapter';
+import adapter from './aventara.adapter.js';
+import { aventaraConfig } from './aventara.config.js';
+import { PrismaModule, PrismaService } from './prisma.service.js';
+import { access } from './access.js';
+
+@Module({
+  imports: [
+    PrismaModule,
+    AventaraModule.forRootAsync({
+      imports: [PrismaModule],
+      inject: [PrismaService],
+      useFactory: async (prisma: PrismaService) => ({
+        config: {
+          ...aventaraConfig,
+          adapter: await createPrismaAdapter({
+            ...adapter,
+            client: prisma,
+          }),
+          access,
+        },
+      }),
+    }),
+  ],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}
+```
+
+Anywhere else: `createFramework({ ...config, access })`. Agents over MCP: add
+`mcp: { path: "/mcp", authorization: access.mcp }` beside `access` ([callers](callers.md#agents-over-mcp)).
+
+### Next.js
+
+```text
+// src/app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from "better-auth/next-js";
+import { access } from "@/access";
+
+export const { GET, POST } = toNextJsHandler(access);
+
+// src/aventara/config.ts: put access here, not in server.ts
+import { access } from "../access";
+
+export const aventaraConfig = {
+  api: "/api",
+  // the rest of what `aventara new` wrote stays as it is
+  access,
+} as const;
+```
+
+The rules import the model from `@/aventara/generated/discovery.artifact`. With `access` only in `server.ts`, the
+framework warns `AVENTARA_PREBUILT_STALE` and governed fields miss the generated client.
+
+## The request's principal
+
+`access.state` reads each request once:
+
+- An `Authorization: Bearer <token>` header is read first. A token Access accepts is signed by the instance's key set
+  (`GET /api/auth/jwks`), has the instance's origin as `iss` and `aud`, is unexpired and no older than `tokenTtl`, and
+  carries no undeclared claim. Anything else in that header (another scheme, a tampered or expired token) gives
+  `me: null`, and the session cookie is not tried.
+- Without the header, the session cookie (profiles `web` and `kiosk`) is read from Better Auth's store, so a sign-out
+  or a revoked session is `null` at once. On a request that may change something, the cookie counts only when the
+  request comes from a site Better Auth trusts (`Origin`, or `Sec-Fetch-Site`).
+- `me` is a copy of what `principal` returns, or `null`. The framework puts it at `ctx.$state.me`. Its plain data
+  (plain objects and arrays) is frozen and the state holds it read-only: no stage can replace it or change it, so the
+  policy decides every part of the request for the same principal. A class instance, `Map`, `Set`, `Date`, typed array
+  or getter is kept as returned and not frozen, so return plain data for the fields the rules read. Your own objects
+  are never frozen. Under an OAuth access token, return a plain object: a `Map` or `Set` principal is not supported
+  there, and a class instance loses its `#private` fields. Return a new object for each user (one cached per user is fine): one `principal` already returned
+  for another user is refused (`ACCESS_OPTIONS_INVALID`). Only the returned object is checked, not what it holds.
+
+A client gets a token by trading its session: `GET /api/auth/token`. A token is not revoked by a sign-out; it expires.
+
+To read `me` typed in your own stages, declare it on the framework's state:
+
+```ts
+// src/aventara.state.ts
+import type { AvState } from "@aventara/core";
+import type { TeamPrincipal } from "./team.policies.js";
+
+declare module "@aventara/core" {
+	interface AvState {
+		/** Seeded by Access on every request: a frozen copy of the principal, or null when anonymous. */
+		readonly me?: TeamPrincipal | null;
+	}
+}
+
+/** The caller's user id, or null for an anonymous caller. */
+export const callerIdOf = (state: AvState) => state.me?.id ?? null;
+```
+
+Never parse the `Authorization` header or the cookie yourself in a stage: `ctx.$state.me` is the verified answer.
+
+## Server code runs unchecked unless it names a principal
+
+The policy checks every client and agent request. A server-side `framework.application.*` call is server code, and the
+policy does not check it unless the call names a principal with the `as` option. When server code acts for a caller,
+name them:
+
+```text
+// checked exactly as the caller's own request would be; null is the anonymous caller
+await framework.application.Note.find.many({}, { as: ctx.$state.me ?? null });
+```
+
+A `framework.client.*` call is checked either way, and `as` replaces the principal its state would give. Leave `as`
+out only for work no caller asked for (a job, a migration, a seed).
+
+## The Better Auth plugin
+
+For an app that builds `betterAuth({...})` itself: add `aventaraAccess({ policies, principal, resources, audit,
+passwords, registry, mcp, audience, organization })` to its `plugins`, and hand the framework `accessOf(auth)` as
+`access`. `accessOf(auth).mcp` is the framework's `mcp.authorization`.
+
+```text
+// src/auth.ts
+export const auth = betterAuth({
+  database: …,
+  emailAndPassword: { enabled: true },
+  user: { additionalFields: { banned: { type: "boolean", required: false, input: false } } },
+  plugins: [aventaraAccess({ policies: { rules, claims } })],
+});
+
+export const access = accessOf(auth);
+```
+
+- The plugin carries Better Auth's `jwt()` inside it: do not add `jwt()` beside it, and call `aventaraAccess()` once
+  per Better Auth instance. With `mcp` or `audience`, list `oauthProvider()` after it.
+- You mount `auth.handler` as you already do. `createAccess`'s profiles, `access.handler` and the `$access` verbs are
+  not part of the plugin.
+- `organization: { claim, organizationClaim, roles }` puts a member's role in the session's active organization into a
+  claim, and the organization into another. An organization role is that organization's: hold every grant on it to
+  the organization, `where: { organizationId: me.org }`, with the organization claim copied onto the principal. It
+  needs `organization({ requireEmailVerificationOnInvitation: true, allowUserToCreateOrganization: false })` (or a
+  function that decides who may create one).
+- `aventaraAccessClient({ api: "/api" })` in Better Auth's client adds `authClient.access.can([...])`: one
+  `POST {api}/_access/can` for the page, answered by the engine that decides the real requests.
+
+## The engine alone
+
+Without Better Auth, hand the engine to the framework's `policy` option, with a function that reads the principal from
+the request's state, which your host's `state` option fills:
+
+```text
+// src/aventara.config.ts
+export const aventaraConfig = {
+  api: "/api",
+  policy: {
+    engine: policies.engine(),
+    principal: ({ $state }: { readonly $state: AvState }) => $state.user ?? null,
+  },
+} as const;
+```
+
+`createAccessEngine(file)` builds the same engine from a compiled policies file (`policies.contract()`). Any object
+with `policy` (an engine) and `state` (`({ headers }) => ({ me })`) also fits the `access` option.
+
+Your `state` function is the whole of authentication here. Set `user` only from a credential your server verified (a
+signature-checked token, a session looked up server-side), never from a header, a cookie value, a query or the body
+as sent. Unverified is `null`.

package/src/aventara-where.translator.ts

@@ -0,0 +1,116 @@
+// Folded condition → Aventara's `where` grammar, with explicit operators
+// (`{ equals: … }`), as core validates it against the Core Contract.
+
+import type { AccessComparison, AccessLiteral } from "./policies-contract.js";
+import type { Resolved } from "./scope.resolver.js";
+
+/** A fragment of Aventara's `where` (core's `AvPolicyWhere`, by shape). */
+export type AccessWhere = { readonly [key: string]: unknown };
+
+const OPERATOR: Record<AccessComparison, string> = {
+	eq: "equals",
+	ne: "not",
+	in: "in",
+	notIn: "notIn",
+};
+
+/** The Aventara filter operator a comparison is written with. */
+export const operatorOf = (cmp: AccessComparison): string => OPERATOR[cmp];
+
+const isField = (
+	node: Resolved,
+): node is Extract<Resolved, { field: string } | { relation: string }> =>
+	node.k === "cmp" ||
+	node.k === "rel" ||
+	node.k === "some" ||
+	node.k === "every" ||
+	node.k === "none";
+
+const keyOf = (
+	node: Extract<Resolved, { field: string } | { relation: string }>,
+): string => (node.k === "cmp" ? node.field : node.relation);
+
+/**
+ * Sets `key` on `target` as its own data member. An assignment would read
+ * `__proto__` as the prototype setter and drop the condition.
+ */
+export const defineMember = (
+	target: Record<string, unknown>,
+	key: string,
+	value: unknown,
+): void => {
+	Object.defineProperty(target, key, {
+		value,
+		enumerable: true,
+		writable: true,
+		configurable: true,
+	});
+};
+
+/** An object with one own member. */
+const one = (key: string, value: unknown): AccessWhere => {
+	const where: Record<string, unknown> = {};
+	defineMember(where, key, value);
+	return where;
+};
+
+/** Merges fragments into one object when no key repeats; otherwise `undefined`. */
+export const mergeWhere = (
+	fragments: readonly AccessWhere[],
+): AccessWhere | undefined => {
+	const merged: Record<string, unknown> = {};
+	for (const fragment of fragments) {
+		for (const [key, value] of Object.entries(fragment)) {
+			if (Object.hasOwn(merged, key)) {
+				return undefined;
+			}
+			defineMember(merged, key, value);
+		}
+	}
+	return merged;
+};
+
+/** Translates a row condition that is neither `true` nor `false` at its root. */
+export const translateWhere = (node: Resolved): AccessWhere => {
+	switch (node.k) {
+		case "true":
+			return {};
+		case "false":
+			// Aventara's `where` has no `false`: the empty `OR` is its one way to match no
+			// row, and an ORM reads it so.
+			return { OR: [] };
+		case "cmp":
+			return one(node.field, {
+				[operatorOf(node.cmp)]: Array.isArray(node.value)
+					? [...(node.value as readonly AccessLiteral[])]
+					: node.value,
+			});
+		case "rel":
+			return one(node.relation, translateWhere(node.where));
+		case "some":
+		case "every":
+		case "none":
+			return one(node.relation, { [node.k]: translateWhere(node.where) });
+		case "not":
+			return { NOT: translateWhere(node.arg) };
+		case "or":
+			return { OR: node.args.map(translateWhere) };
+		case "all":
+			return { AND: node.args.map(translateWhere) };
+		case "and": {
+			// Written by the author as one object: written back as one when every part is
+			// a field condition and no field repeats.
+			if (
+				node.args.every(isField) &&
+				new Set(node.args.map(keyOf)).size === node.args.length
+			) {
+				return mergeWhere(node.args.map(translateWhere)) as AccessWhere;
+			}
+			return { AND: node.args.map(translateWhere) };
+		}
+	}
+};
+
+/** A seam answer: `true` every row, `false` none, or a `where`. */
+export const translateAnswer = (node: Resolved): boolean | AccessWhere =>
+	node.k === "true" ? true : node.k === "false" ? false : translateWhere(node);