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

package/README.md

@@ -1,3 +1,2537 @@
-# Temporary Holding Version
+# @aventara/access
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Access extends [Better Auth](https://www.better-auth.com) with policies for
+[Aventara](https://aventara.razor34.dev/framework) apps and the services beside them. Better Auth signs users in and
+issues their tokens. Access decides what each user may do with each row and each field.
+
+You write role-first rules, typed from your app's schema. Access compiles them to a policies file: plain JSON in the
+`aventara-access/policies@1` format. Its engine answers the framework's policy questions from that file: who may read,
+create, update or delete which rows, and which fields they may see.
+
+This is a release candidate. It holds:
+
+| Part | What it does |
+|---|---|
+| `@aventara/access`: `definePolicies`, `createAccessEngine` | The rules and the engine. They need no Better Auth and no server. |
+| `@aventara/access/auth`: `createAccess` | Better Auth with Access beside it: tokens with claims, the engine, the request's principal. |
+| `@aventara/access/better-auth`: `aventaraAccess`, `accessOf`, `aventaraAccessClient` | Access as a plugin of the Better Auth you build yourself, and its client plugin. |
+| `@aventara/access/standalone` | `serve(access)`: Access as its own HTTP server. |
+| The registry | Namespaces, keys and the org's guardrails, stored in Better Auth's database. |
+| `avaccess` | The command line: push, pull, verify, status, diff, keys, generate, schema, serve. |
+| The generated client | Two TypeScript files (`avAccess.ts` and `avAccess.internal.ts`) that import nothing else and decide for a service that does not run on Aventara. |
+
+Contents: [Install](#install) · [AI agents](#ai-agents) · [Write the rules](#write-the-rules) · [createAccess](#createaccess) ·
+[Mount the routes](#mount-the-routes) · [Wire it into Aventara](#wire-it-into-aventara) ·
+[The Better Auth plugin](#the-better-auth-plugin) · [The engine alone](#the-engine-alone) · [The audit log](#the-audit-log) ·
+[Users and roles as Resources](#users-and-roles-as-resources) · [The registry and avaccess](#the-registry-and-avaccess)
+· [Guardrails](#guardrails) · [Services not on Aventara](#services-not-on-aventara) ·
+[Running `avaccess serve`](#running-avaccess-serve) · [File formats and hashes](#file-formats-and-hashes) ·
+[Error codes](#error-codes)
+
+## Install
+
+Access goes into an Aventara app. To start one, create it with the Aventara CLI (here NestJS, Prisma 7 and
+PostgreSQL), then install Access in it:
+
+```sh
+npx @aventara/cli@1.0.0-rc.11 new <app> --orm prisma7 --db postgresql
+cd <app>
+npm install --save-exact @aventara/access@rc better-auth@~1.7.12
+# or, with pnpm:
+pnpm add --save-exact @aventara/access@rc better-auth@~1.7.12
+```
+
+On a terminal, `aventara new` asks for the package manager; anywhere else, add `--package-manager npm` (or `pnpm`)
+or `--yes`. Then set `DATABASE_URL` in `.env`, as the CLI says, and add Better Auth's secret and the app's origin.
+`npx auth@~1.7.12 secret` prints a new secret. Without `BETTER_AUTH_URL`, `createAccess` refuses to start
+(`ACCESS_OPTIONS_INVALID`).
+
+```sh
+# .env
+BETTER_AUTH_SECRET="<the value npx auth@~1.7.12 secret prints>"
+BETTER_AUTH_URL="http://localhost:3000"
+```
+
+Then, in this order:
+
+1. Add your models to `prisma/schema.prisma` and run `npm run aventara:prepare`
+   ([Write the rules](#write-the-rules)).
+2. Write the rules in `src/access.policies.ts`.
+3. Write `src/access.ts` with `createAccess`, keeping the scaffold's numeric ids
+   ([The scaffold's numeric ids](#the-scaffolds-numeric-ids)).
+4. Generate Better Auth's tables, push them and run `npm run aventara:prepare` again
+   ([Better Auth's tables](#better-auths-tables)).
+5. [Mount the routes](#mount-the-routes) and [wire it into Aventara](#wire-it-into-aventara).
+
+Access runs on Better Auth `~1.7.12`: 1.7.12 or any later 1.7 patch. npm installs the newest patch, and
+`--save-exact` records it. Another version (an older one, 1.8, a prerelease) is refused when `createAccess` runs
+(`ACCESS_BETTER_AUTH_VERSION`).
+
+`better-auth` is an optional peer. The engine alone (`definePolicies`, `createAccessEngine`, from `@aventara/access`)
+works without it, and type-checks without it with `skipLibCheck: false`. Only `createAccess` loads it, and it is
+imported from `@aventara/access/auth`.
+
+Access works with `@aventara/core` `1.0.0-rc.10` or later. It has no dependency on the framework: its engine and its
+instance fit the framework's types by shape. Node.js `^22.23.4 || >=24.22.1`. On Node.js 22, `createAccess` needs
+`@node-rs/argon2` to hash passwords ([Passwords](#passwords)).
+
+## AI agents
+
+The package ships an agent skill at `node_modules/@aventara/access/skill/`: a short `SKILL.md` and reference pages an
+agent loads when a task needs them (setup and wiring, the rule language, recipes, signed-out callers and cached reads,
+error codes). Its TypeScript examples compile against this release. Copy the folder into your agent's skills folder:
+
+```sh
+mkdir -p .claude/skills
+cp -R node_modules/@aventara/access/skill .claude/skills/aventara-access
+```
+
+Or point your agent at `node_modules/@aventara/access/skill/SKILL.md`. Copy it again after you upgrade Access.
+
+## Write the rules
+
+`definePolicies` takes your schema. In an Aventara app that is the discovery artifact's `model`, which
+`aventara:prepare` writes. Every name in a rule is checked against it. A Resource, field, relation or enum value that
+does not exist is a type error at the key that names it.
+
+The rules below use `Campaign`, `Member` and `Note`, which the scaffold does not have. Add your own models to
+`prisma/schema.prisma` first, then run `npm run aventara:prepare` so the model has them.
+
+The examples in this README type the principal's `id` as `string`, for a project whose `User.id` is a `String`. On
+the scaffold's `Int` ids, type it as `number` and map it with `Number(sub)`
+([The scaffold's numeric ids](#the-scaffolds-numeric-ids)).
+
+```ts
+// src/access.policies.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** What your app derives for a request: the signed-in user, or null. */
+export type Principal = {
+	id: string;
+	claims: { role?: "admin"; banned?: boolean };
+};
+
+export const policies = definePolicies(model)
+	.principal<Principal>()
+
+	.roles(({ me }) => ({
+		// A global role, read from the principal's claims.
+		admin: { global: { claims: { role: "admin" } } },
+		// Roles held on a row: a member of a campaign, as DM or player.
+		dm: {
+			on: "Campaign",
+			where: { members: { some: { userId: me.id, role: "DM" } } },
+		},
+		player: {
+			on: "Campaign",
+			where: { members: { some: { userId: me.id, role: "PLAYER" } } },
+		},
+	}))
+
+	// Governed fields: only a grant that names one opens it. The list governs reads
+	// and writes: out of every default projection, written by no grant that does not
+	// name it.
+	.govern("User", ["email"])
+	// "write": read as any other field, written only by a grant that names it. The
+	// row roles read a member's role, so no grant hands one out without naming it.
+	.govern("Member", { role: "write" })
+
+	.grants(({ grant, me }) => [
+		grant("signedIn", "read", "User"),
+		grant("signedIn", "read", "User", {
+			where: { id: me.id },
+			fields: ["User.email"],
+		}),
+		grant("admin", "read", "*", { fields: ["User.email"] }),
+		grant("signedIn", "create", "Campaign"),
+		grant(["dm", "player"], "read", "Campaign"),
+		grant("player", "read", "Note", {
+			in: "campaign",
+			where: { visibility: "PARTY" },
+		}),
+		grant("dm", ["read", "create", "update", "delete"], "Note", {
+			in: "campaign",
+		}),
+		// The DM changes a seat's role, never who sits in it: the grant names the role.
+		grant("dm", "update", "Member", {
+			in: "campaign",
+			write: { except: ["userId", "campaignId"] },
+			fields: ["Member.role"],
+		}),
+	])
+
+	.denies(({ deny }) => [
+		deny("*", "*", { if: { claims: { banned: true } } }),
+		deny("delete", "*", { if: { origin: "agent" } }),
+	]);
+```
+
+In Next.js, `aventara:prepare` writes the artifact to `src/aventara/generated/discovery.artifact.ts`. Import the model
+there as:
+
+```ts
+// src/access.policies.ts (Next.js)
+import { model } from "@/aventara/generated/discovery.artifact";
+```
+
+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. The order of rules never matters.
+- `signedIn` is any non-null principal. `anyone` also includes the anonymous caller (`null`). The principal is an
+  object, an instance of a class (an entity) included; an array, a function or a primitive is anonymous. Its values
+  are read from its own properties, never from its prototype.
+- `in: "campaign"` means the subject holds its role on the row's `campaign`.
+- A rule reads `me` values the principal may lack: an anonymous principal lacks them all, and a missing or `null`
+  property, an empty string or a number JSON cannot carry counts as missing. A grant that reads a missing value
+  never matches. A deny that reads one in its `where` matches, whatever `not` or `NOT` surrounds it: it fails
+  closed.
+- A claim the principal lacks fails closed the same way: a global role that compares it is not held, and a deny's
+  `if` that compares it holds, whatever value it compares with. A token Access issues carries every declared
+  boolean claim, `false` when the user's is unset, so `deny("*", "*", { if: { claims: { banned: true } } })` leaves
+  alone a user whose ban is unset and denies a token that lacks `banned` (one from another issuer, or from before
+  the claim was declared). The anonymous caller has no claims and no token: a comparison with `true` never holds for
+  it, so a ban does not close an `anyone` grant, and any other comparison holds for a deny.
+- `if: { origin: "agent" }` matches an AI agent's request, through the framework's MCP endpoint. The other origins are
+  `client` (a user's request) and `application` (your server's own).
+- A rule compares a value by its field's type: a `decimal` by value (`1.5`, `"1.50"` and a decimal object are equal),
+  a `datetime` by instant (a `Date`, or an ISO-8601 date or instant with its offset that reads back as written: no
+  February 30th, no hour 24, nothing past the millisecond; the compiled file holds `toISOString()`'s form), and a
+  `bigint` exactly. A row value of another type than its field's, or than the rule's `me` value, is unknown: no grant
+  matches it, and a deny that compares it matches.
+- Through Aventara, a rule that compares a `datetime`, `decimal` or `bigint` field cannot be used yet: the framework
+  validates a policy's `where` with a `Date`, a decimal object or a `bigint` where the file holds text, so a scope or
+  an `exists` question on such a field answers `A3000` (the request is refused). It fails closed; the framework's
+  seam is being changed. `can` on a row, and a generated client, compare these fields as above.
+- Writing a reference needs read on its target. When a create or an update sends a reference (a `Member`'s
+  `profileId`) to a Resource the app serves, Aventara holds it to the rows the caller may read there, and refuses the
+  write (`A4002`) otherwise. When Aventara hosts the engine (`@aventara/core` `1.0.0-rc.10` or later) it tells the
+  engine which Resources it holds references to (`engine.hosted({ held })`), and the engine warns
+  (`ACCESS_REFERENCE_UNREADABLE`, a Node.js warning) about a role that may write a reference to one of them no read
+  grant reaches for it. When that Resource is a Better Auth table `createAccess` keeps closed (`User` without
+  `resources: { users: true }`), the warning names the key that opens it. Compiling the rules warns about nothing, and
+  the engine decides as before. A reference to a
+  foreign Resource is the exception: no caller reads one, so the engine lists the rules' foreign Resources in
+  `unheld` and Aventara does not hold a reference to them ([Namespaces and foreign
+  Resources](#namespaces-and-foreign-resources)).
+- Strings compare exactly in `can`, code unit by code unit. A database column with a case- or accent-insensitive
+  collation (MySQL's default, PostgreSQL's `citext` or a nondeterministic collation) can find rows `can` would not
+  keep, so `scopeOf` and `can` disagree on them. Give the fields your rules compare a binary or deterministic
+  collation.
+
+### Updates
+
+An update is checked twice. Its scope (`scopeOf(update)`) picks the rows a grant's `where` covers and no update deny
+matches. Then the row each update leaves must still be one an update grant covers, by that grant's `where` and its
+`after` together, and no update deny may match it. A grant's `where` is checked on the new row by default: a grant
+`where: { authorId: me.id }` does not let the author hand the row to someone else. `after` adds what the new row must
+also meet:
+
+- `grant("signedIn", "update", "Character", { where: { ownerId: me.id }, after: { campaign: { $role: "player" } } })`
+  lets a player move a character only to a campaign they play in.
+
+The grant that covers the row after must also be the one that covered the row before. `can` then gets both rows
+(`row`, and `before`, the row as it was before the update), and one update grant must cover both: its `where` the row
+before, its `where` and `after` the row after. No update moves a row from the rows one grant reaches to another's.
+When two update grants with different conditions cover a Resource, a row that only one of them covers before the
+update and only the other covers after it is refused. Update denies are asked about the row after only.
+
+The engine lists in `afterChecks` every Resource whose update grants read the row (a `where`, an `after`, a role held
+on a row) or whose update denies have a `where`. Aventara asks `can` about each row such an update changed, with the
+row before it, inside the update's transaction, and rolls the update back when one fails; where it has no interactive
+transaction, it refuses those updates. The row before needs `@aventara/core` `1.0.0-rc.10` or later. An older core
+hands `can` the row after only, and `can` then lets an update in when any update grant covers that row.
+
+Which grants covered the row before is decided before the write. Aventara asks the engine's `grantsOf` about each row
+such an update will change, after it reads the row and before any of your stages or the write itself runs, and hands
+the answer back to `can` as `beforeGrants`. The grant that covers the row after must be one of those. A grant whose
+`where` reads a relation (`tags: { some: { name: "shared" } }`, a role held through a membership) is therefore judged
+on what the database held before the update: tagging a row "shared" in the same update that hands it to someone else
+does not let a grant on shared rows cover the row before. This also needs `@aventara/core` `1.0.0-rc.10` or later.
+Without `beforeGrants`, `can` asks a relation condition on the row before through `exists` at the after check, when
+the update has already written, so a nested write in the same request can make it hold. With `before` too, `can`
+still checks each listed grant's `where` on the row before in memory, so a key list replayed from another row or
+another principal fails on a scalar condition; only a relation condition is left to `grantsOf`'s answer. The keys
+`grantsOf` answers are opaque: a short hash of the policies file's grants, then a grant's place in it, never its
+conditions, so a list from another policies file covers nothing. `grantsOf` answers no key on a row an update deny
+already refuses in memory. Its answer is what the database held when it was asked: a relation fact your own stages,
+or another transaction committing in between, change before the write is not in it. Aventara may ask it about several
+rows at once, so your `exists` can be called concurrently in one transaction. It decides nothing, so it is neither
+reported to the decision observer nor explained; the `can` after it is.
+
+A generated client's `can({ action: "update", row, before })` answers the same question about the rows you pass.
+Without `before` it checks only the row the update leaves. Ask `access.grantsOf({ action: "update", row })` about the
+row before you write it, in the update's transaction and with the same `exists`, and pass its answer to `can` as
+`beforeGrants` with the row the update leaves; without it, `can` asks the row before's relation conditions when you
+ask `can`. The caller must also limit the update itself to the rows `scopeOf({ action: "update" })` returns, or an
+update could start from a row no grant covers.
+
+A row handed to `can` is a Resource's own scalar fields. A relation on it (`author: { … }`, `tags: [ … ]`) is never
+read: a relation condition is always asked through `exists`, on what the database holds. Still, never put relation
+data a client sent on a row. A to-one step whose reference fields the row carries (`campaign` through `campaignId`) is
+asked on the row those values name, so a question asked before the write sees where the row is moving; anything else
+is asked about the row itself, by its identifier.
+
+`write: { except: [...] }` keeps fields out of what a create or an update may set. A relation and its reference fields
+are locked together: `except: ["author"]` locks `authorId` too, and `except: ["authorId"]` locks `author`.
+
+### Governed fields
+
+A governed field is opened only by a grant that names it (`fields: ["User.email"]`). Each governed field has a mode:
+
+| Form | Reads | Writes |
+|---|---|---|
+| `.govern("User", ["email"])`, or `{ email: "both" }` | Out of every default projection; a read grant that names it opens it, when the request selects it | Only a create or update grant that names it sets it |
+| `.govern("Member", { role: "write" })` | As any other field | Only a create or update grant that names it 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 a `Member` row reads
+`Member.role`; governed as `"write"`, an update grant on `Member` that does not name it cannot change it, while every
+reader still sees it. `"read"` fits a field people write and almost nobody reads back: a government id, a stored
+secret.
+
+Selecting a field governed for reading without a grant that opens it is refused with `403 A4002`. The field is not
+quietly dropped from the result. Setting a field governed for writing without a grant that names it is refused the
+same way. A field governed twice with two modes is a type error, and refused when the rules compile.
+
+A relation and its reference fields tell each other (`author.id` is `authorId`), so they are governed together, with
+one mode: `.govern("Post", ["author"])` without `"authorId"`, or the reverse, is refused when the rules compile.
+
+A field governed as `"read"` that is unique (one of its Resource's identifiers) still tells writers which values
+exist: a create or update that sends a value another row holds fails on the duplicate. Compiling the rules or building
+the engine warns `ACCESS_READ_GOVERNED_UNIQUE` (a Node.js warning) for each such field. Govern it as `"both"` so only a
+grant that names it writes it, or accept the leak.
+
+In the policies file, `govern` lists every governed field, and `governModes` gives the fields governed for one access
+only: `"governModes": { "Member": { "role": "write" } }`. A field without an entry is governed for both, so the list
+form compiles to the same file, with the same hash, as `"both"`.
+
+`fields` on a Resource with no governed field is a type error that says what to do:
+`no field of "Note" is governed; govern it first, .govern("Note", [<field>]), and a grant can then open it`.
+
+### The principal type
+
+`.principal<…>()` types `me` in every callback. There are two ways to use it.
+
+- **Your own type**, as above. With `createAccess`, you then pass a `principal` function that maps the verified token to
+  it.
+- **The token's identity.** `AccessIdentity<typeof claims>` is `{ sub, claims }`, exactly what a verified token
+  carries. Pass the same `claims` object to `createAccess` and leave `principal` out.
+
+```ts
+// src/identity.policies.ts
+import { definePolicies } from "@aventara/access";
+import type { AccessIdentity } from "@aventara/access/auth";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** The claims a token carries beside `sub`, by type. */
+export const claims = { role: "string", banned: "boolean" } as const;
+
+export const identityPolicies = definePolicies(model)
+	.principal<AccessIdentity<typeof claims>>()
+	.grants(({ grant, me }) => [
+		grant("signedIn", "read", "User", { where: { id: me.sub } }),
+		grant("signedIn", "create", "Note", { where: { authorId: me.sub } }),
+	])
+	.denies(({ deny }) => [deny("*", "*", { if: { claims: { banned: true } } })]);
+```
+
+Without `.principal<…>()` the rules have no principal type, so `me.sub` in a `where` and `claims` in a role are type
+errors.
+
+### Namespaces and foreign Resources
+
+When several services share one Access server, each service owns a namespace and writes the rules for its own
+Resources. `definePolicies(model, { namespace: "chat" })` names it. A namespace name matches
+`^[a-z][a-z0-9_-]{0,62}$`.
+
+A Resource another namespace owns is marked `{ foreign: "<namespace>" }` in the schema. The rules can read it in
+conditions, but cannot grant, deny or govern on it. That is a type error, and the engine and the registry refuse it
+too. A foreign Resource is only readable while both services share one database: the ownership beacon
+([below](#the-ownership-beacon)) checks that at push, at pull and at startup.
+
+```ts
+// src/chat.policies.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** The schema with Campaign marked as the campaign namespace's. */
+const schema = {
+	...model,
+	resources: {
+		...model.resources,
+		Campaign: { ...model.resources.Campaign, foreign: "campaign" },
+	},
+} as const;
+
+export const chatPolicies = definePolicies(schema, { namespace: "chat" })
+	.principal<{ id: string }>()
+	.grants(({ grant, me }) => [
+		// Read through Campaign in a condition: allowed.
+		grant("signedIn", "read", "Note", {
+			where: { campaign: { members: { some: { userId: me.id } } } },
+		}),
+		// grant("signedIn", "read", "Campaign") would be a type error here.
+	]);
+```
+
+A row of your own can hold a reference to a foreign Resource (a chat `Room`'s `campaignId`). No caller reads a foreign
+Resource, so Aventara cannot hold such a reference to the rows the caller may read, as it does for your own Resources:
+the engine lists the rules' foreign Resources in `unheld` (`@aventara/core` `1.0.0-rc.10` or later), and the write grant
+alone decides which row may be linked. Constrain it through the relation, with a `where` on a create grant and an
+`after` on an update grant (an update grant's `where` is checked on the row it leaves too):
+
+```text
+grant("signedIn", "create", "Room", { where: { campaign: { members: { some: { userId: me.id } } } } }),
+grant("signedIn", "update", "Room", {
+  where: { ownerId: me.id },
+  after: { campaign: { members: { some: { userId: me.id } } } },
+}),
+```
+
+Without such a condition the caller can link any row of the foreign Resource by its identifier. When Aventara hosts the
+engine, it warns about each role whose create or update grant may write a reference to a foreign Resource with no
+condition through that relation (`ACCESS_FOREIGN_REFERENCE_UNCHECKED`, a Node.js warning, once per process and
+namespace). Reads are unchanged: through Aventara a read of a foreign Resource, or an include of one, is still refused
+(`A4002`).
+
+## createAccess
+
+`createAccess` builds Better Auth with Access beside it. It opens no port and mounts nothing. Better Auth's options sit
+in the `betterAuth` block, exactly as `betterAuth({...})` takes them, so you can paste them from an existing Better Auth
+setup. Access's own concerns sit in their own blocks beside it.
+
+```ts
+// src/access.ts
+import { createAccess } from "@aventara/access/auth";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { prismaAdapter } from "better-auth/adapters/prisma";
+import { policies } from "./access.policies.js";
+import { PrismaClient } from "./generated/prisma/client.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`. */
+const claims = { role: "string", banned: "boolean" } as const;
+
+export const access = createAccess({
+	// Better Auth's options, as betterAuth({...}) takes them.
+	betterAuth: {
+		database: prismaAdapter(prisma, { provider: "postgresql" }),
+		emailAndPassword: { enabled: true },
+		user: {
+			additionalFields: {
+				role: { type: "string", required: false, input: false },
+				banned: { type: "boolean", required: false, input: false },
+			},
+		},
+	},
+	// The rules, and the claims they read. Each claim is read from the user's field
+	// of the same name.
+	policies: { rules: policies, claims },
+	// The rules are typed with your own Principal, so map the token to it.
+	principal: ({ sub, claims }) => ({
+		id: sub,
+		claims: {
+			...(claims.role === "admin" ? { role: "admin" as const } : {}),
+			...(claims.banned === undefined ? {} : { banned: claims.banned }),
+		},
+	}),
+});
+
+export default access;
+```
+
+Better Auth reads `BETTER_AUTH_SECRET` and `BETTER_AUTH_URL` from the environment, as it always does, or takes
+`secret` and `baseURL` in the block. Access needs a base URL it can fix when the instance is built: its tokens' issuer
+and audience are that URL's origin (`baseURL`, else `BETTER_AUTH_URL`, or a dynamic `baseURL`'s `fallback`). With none,
+`createAccess` refuses with `ACCESS_OPTIONS_INVALID`. The issuer is the origin alone, not the path: two apps on one
+origin that share a database (and so Better Auth's key set) accept each other's tokens. Give each app its own origin,
+or its own database.
+
+Each declared claim is read from the user's field of the same name, so that field needs `input: false`, as `role` and
+`banned` have above. A field without it is one the user sets themselves, at sign-up or with `/update-user`, and a
+claim read from it would be the user's own choice: `createAccess` refuses it (`ACCESS_OPTIONS_INVALID`), for fields a
+plugin adds too. To read a claim from such a field anyway, return it from `policies.claimsOf`.
+
+`policies.claimsOf` must return every declared boolean claim, as `banned: user.banned === true`: an answer without
+one is a type error (its return type, `AccessClaimsAnswer`, requires each boolean claim's key), and at run time it is
+refused (`ACCESS_OPTIONS_INVALID`, naming the claim) and no token is issued, so a flag it forgot never reads as unset. `null` or `undefined` there is `false`. Beyond that, Access does not check what `policies.claimsOf` returns. A
+claim it reads from a field the user can set (an `email`, a
+`username`, an additional field without `input: false`) is again the user's own choice, so read claims there only from
+fields your server alone writes.
+
+### The scaffold's numeric ids
+
+The project `aventara new` creates has `model User { id Int @id @default(autoincrement()) … }`. Better Auth's ids are
+strings by default, so without the option below `npx auth@~1.7.12 generate --yes` writes `String` foreign keys
+(`Session.userId`, `Account.userId`) against that `Int`, and `prisma validate` fails. Before you generate Better Auth's
+tables, put Better Auth's option for numeric ids in the `betterAuth` block of `src/access.ts`, beside `database`, and
+map the principal's `id` to a number:
+
+```text
+betterAuth: { …, advanced: { database: { generateId: "serial" } } },
+principal: ({ sub, claims }) => ({ id: Number(sub), claims: { … } }),
+```
+
+with `id: number` in the `Principal` type of `src/access.policies.ts`. Every Better Auth table, and Access's own, then
+gets `Int @id @default(autoincrement())`, and its references are `Int`. `generate` only adds what the schema lacks: on
+a schema that already has Better Auth's models with `String` ids, it answers "Your schema is already up to date" and
+changes nothing. Delete the models it wrote (and Access's), then run it again.
+
+- Better Auth hands an id out as a string (`"1"`), so a token's `sub` is `"1"`, and `Number(sub)` is the user's id. A
+  rule that compares `User.id` with a string, such as `where: { id: me.id }` with `id: string` or `me.sub` from
+  `AccessIdentity`, is a type error.
+- Better Auth warns that its single-use checks (SAML assertion ids, DPoP proofs, `private_key_jwt` assertions) need
+  string ids and are not enforced with `"serial"`. If you use those, change `User.id` to `String` instead and leave
+  `generateId` out.
+- The scaffold's `User` is now Better Auth's `user` table, so a rule on `User` needs `resources: { users: true }`
+  ([Users and roles as Resources](#users-and-roles-as-resources)).
+
+### Better Auth's tables
+
+Better Auth's tables go into your schema the way Better Auth's docs say. With Prisma:
+
+```sh
+npx auth@~1.7.12 generate --config src/access.ts --yes
+npx prisma validate
+npx prisma db push
+npm run aventara:prepare
+```
+
+`generate` writes Better Auth's models (and Access's own tables, when `audit` or `registry` is on) into
+`prisma/schema.prisma`. It reads the module's default export. Without `--yes` it asks before it writes the file, and
+where it cannot ask (a script, CI) it writes nothing and still exits 0. Run `aventara:prepare` again so the
+framework's model has the new tables. Access closes them to every request until you open them (see
+[Users and roles as Resources](#users-and-roles-as-resources)).
+
+On its first run, `generate` may print a Babel note that an exported identifier such as `AvComputedFields`
+"is not declared in Babel's scope tracker". It comes from a type the generated discovery artifact re-exports, and
+changes nothing: the schema is written all the same.
+
+### The options
+
+| Option | Takes | Default |
+|---|---|---|
+| `betterAuth` | Better Auth's options | required |
+| `policies.rules` | The builder (`definePolicies(…)`), its `.contract()`, or a pulled policies file as JSON | required, except on a registry-only server |
+| `policies.claims` | The claims a token carries beside `sub`, by type: `{ role: "string", banned: "boolean" }` | required with `rules` |
+| `policies.claimsOf` | `({ user, session }) => claims`, when the claims are not the user's fields of the same name | each claim from the user's field |
+| `policies.guardrails` | The org's guardrails, as pulled ([Guardrails](#guardrails)) | none |
+| `policies.lock` | The project's `avAccess.lock.json` ([The lock at startup](#the-lock-at-startup)) | none |
+| `policies.requireLock` | `true`: refuse to start without `policies.lock`; recommended in production | `false` |
+| `policies.tokenTtl` | How long a token lives, in whole seconds from 300 to 900 | 900 |
+| `principal` | `(identity) => principal \| null`: maps `{ sub, claims }` to your principal | `me` is the identity |
+| `profile` | `{ kind: "web" }`, `{ kind: "service" }`, or `{ kind: "kiosk", canEnrollDevice, idleTimeout?, insecureLan? }` ([The kiosk profile](#the-kiosk-profile)) | `web` |
+| `registry` | `{ enabled: true }` turns on the registry ([The registry](#the-registry-and-avaccess)) | `{ enabled: false }` |
+| `registry.ownership` | `"first-push"` or `"assigned"`: how a Resource gets its owner ([Who owns a Resource](#who-owns-a-resource)) | `"first-push"` |
+| `audit` | `true`, `false` or `{ sink }` ([The audit log](#the-audit-log)) | off |
+| `resources` | `{ users?: boolean, members?: boolean, authTables? }` ([Users and roles](#users-and-roles-as-resources)) | both off; `authTables` required off Prisma's adapter |
+| `passwords` | `{ argon2id: "owasp-minimum" \| "rfc9106-low-memory", legacyScrypt?: boolean }` ([Passwords](#passwords)) | `"owasp-minimum"`, unless `betterAuth.emailAndPassword.password` is set |
+
+- `principal` is required when the rules are typed with your own principal, and optional when they are typed with
+  `AccessIdentity<typeof claims>`. Return `null` to leave the caller anonymous. The principal must carry the token's
+  claims (`identity.claims`) as they are: a boolean claim it drops is unknown to the rules, so a deny such as
+  `banned: true` refuses it. Return a new object for each user (one
+  cached per user is fine): the audit log names the user each principal stands for, so an object `principal` already
+  returned for another user is refused with `ACCESS_OPTIONS_INVALID`. Only the object `principal` returns is checked;
+  a `Map`, `Date` or other object inside it is not. `me` is a frozen copy of its plain data, so your object itself is
+  never frozen.
+- A claim the rules read that `policies.claims` does not declare is a type error, and is refused at construction
+  (`ACCESS_CLAIMS_UNDECLARED`). A token carries `sub` and the declared claims only. Every declared boolean claim is
+  in it: one the user's field leaves unset (absent, `null` or `undefined`), or `claimsOf` returns as `null` or
+  `undefined`, is `false`.
+- `profile: { kind: "service" }` hands no caller a new session, and reads the principal from bearer tokens only. The
+  routes that start a session answer `404`: `/sign-in/*`, `/sign-up/*`, the OAuth callbacks, and the plugins' routes
+  that sign a user in (`/phone-number/verify`, `/magic-link/verify`, `/two-factor/verify-*`, `/device/token`,
+  `/admin/impersonate-user` and the rest). They are matched by Better Auth's endpoint path, whatever the URL's spelling,
+  `basePath` or `baseURL`. Any other route cannot create a session either: Better Auth's session hook refuses the row,
+  so none exists even while the route runs, and the answer is a bare `404`, its cookies and headers dropped. So is an
+  answer that sets the session cookie of a session that already exists, and no session cookie (nor a `multiSession()`
+  cookie) leaves `access.handler` at all: it strips them itself, after Better Auth and every plugin's `onResponse`, so
+  a route that returns its own `Response` or a plugin that answers last is covered too. A route that puts a session token in a JSON body is not
+  covered; no built-in plugin does. Your server's own calls to Better Auth's API with no request still sign users in;
+  a call that forwards the host's `request` (`auth.api.signInEmail({ body, request })`) is treated as that request,
+  and refused with `NOT_FOUND`. A plugin route Access does not know may answer `500` with an empty body when its
+  session is refused. `web` is Better Auth as you configured it.
+- `tokenTtl` bounds how long a changed claim takes to reach every service. A user you ban or suspend gets the new claim
+  with their next token.
+- An option `createAccess` does not take, or a block it cannot read, is refused with `ACCESS_OPTIONS_INVALID` and a
+  sentence that says what it takes.
+
+### The plugins createAccess installs
+
+`createAccess` installs Better Auth's `jwt()` plugin and its own Access plugin (plugin id `aventara-access`, the one
+`aventaraAccess()` returns). Putting either in `betterAuth.plugins` is a type error at that plugin, which reads
+`createAccess installs jwt() itself: remove it from betterAuth.plugins`. At runtime it is refused with
+`ACCESS_PLUGIN_DUPLICATE`, under any case or spacing of its id (`"JWT"`, `"jwt "`). So is a plugin that defines one of
+`jwt()`'s endpoints (`getJwks`, `getToken`, `signJWT`, `verifyJWT`, or a route at `/jwks` or `/token`): it would answer
+for Access's key set or its tokens. Every other Better Auth plugin passes through as it is.
+
+### Passwords
+
+Better Auth hashes passwords with scrypt. `createAccess` hashes them with argon2id instead, in one of three ways. The
+Better Auth plugin, `aventaraAccess()`, takes the same `passwords` and does the same
+([The Better Auth plugin](#the-better-auth-plugin)):
+
+1. **The default.** Set neither `passwords` nor `betterAuth.emailAndPassword.password`, and passwords are hashed with
+   argon2id at the `"owasp-minimum"` profile.
+2. **A named profile.** `passwords: { argon2id: "rfc9106-low-memory" }` beside `betterAuth`. A misspelled profile is a
+   type error, and is refused at runtime with `ACCESS_OPTIONS_INVALID`. Add `legacyScrypt: true` to accept passwords
+   Better Auth already stored with scrypt (see below).
+3. **Your own hook.** Set Better Auth's `emailAndPassword.password` (`hash` and `verify`) in the `betterAuth` block,
+   and it is used as you wrote it: Access installs nothing. To keep Better Auth's scrypt, pass its own functions.
+
+```ts
+// src/access.passwords.ts
+import type { AccessPasswordsOptions } from "@aventara/access/auth";
+import type { BetterAuthOptions } from "better-auth";
+import { hashPassword, verifyPassword } from "better-auth/crypto";
+
+// 1. The default: leave `passwords` out, and `emailAndPassword.password` too.
+export const byDefault = {
+	enabled: true,
+} satisfies BetterAuthOptions["emailAndPassword"];
+
+// 2. A named profile: createAccess({ betterAuth, policies, passwords }).
+export const passwords = {
+	argon2id: "rfc9106-low-memory",
+} satisfies AccessPasswordsOptions;
+
+// 2b. The same, for an app whose users Better Auth signed up with scrypt.
+export const movingOffScrypt = {
+	argon2id: "owasp-minimum",
+	legacyScrypt: true,
+} satisfies AccessPasswordsOptions;
+
+// 3. Your own hook, here Better Auth's scrypt: betterAuth: { emailAndPassword }, and no `passwords`.
+export const emailAndPassword = {
+	enabled: true,
+	password: {
+		hash: hashPassword,
+		verify: verifyPassword,
+	},
+} satisfies BetterAuthOptions["emailAndPassword"];
+```
+
+Setting both `passwords` and `betterAuth.emailAndPassword.password` is refused with `ACCESS_OPTIONS_INVALID`, so it is
+never in doubt which one hashes.
+
+| Profile | Memory | Passes (`t`) | Lanes (`p`) | Source |
+|---|---|---|---|---|
+| `"owasp-minimum"` (the default) | 19 MiB (`m=19456`) | 2 | 1 | [OWASP Password Storage Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html), Argon2id: "m=19456 (19 MiB), t=2, p=1" |
+| `"rfc9106-low-memory"` | 64 MiB (`m=65536`) | 3 | 4 | [RFC 9106](https://www.rfc-editor.org/rfc/rfc9106.html) section 4, the second recommended option |
+
+Both use a 16-byte random salt (RFC 9106: "16 bytes is RECOMMENDED for password hashing") and a 32-byte tag. RFC 9106's
+first recommended option (2 GiB of memory per hash) is not offered: a server that signs users in concurrently cannot
+spend 2 GiB on each.
+
+- A hash is a PHC string, `$argon2id$v=19$m=19456,t=2,p=1$<salt>$<hash>`. Verifying reads the parameters from the
+  stored string, so you can move to another profile later and every older hash still verifies. The hash is compared in
+  constant time.
+- A sign-in whose password matches a hash stored at other parameters than your profile's (an older profile, a cheaper
+  or a costlier one) stores the password again at your profile, so active users' hashes follow a profile change. The
+  hook checks the password against the stored hash itself first, and writes only while the account still holds that
+  hash, so a password changed or reset meanwhile is never overwritten. A hash already at your profile costs one read
+  of the credential account per password sign-in, and no write. The one that moves costs two argon2id computations
+  more (the check again, and the new hash) and one write. The write goes through Better Auth's adapter, past its
+  `account` update hooks: it is the same password, stored anew. A failure is logged (never the password or a hash),
+  and the sign-in stands. An account with two-factor on may not be rehashed by a password sign-in its second step holds
+  back. Kiosk PINs move the same way at the next switch.
+- Hashes Better Auth stored with scrypt (`<salt>:<key>` in hex) fail the check by default, with a warning in Better
+  Auth's log. With `legacyScrypt: true` they verify, through Better Auth's own `verifyPassword`, so an existing Better
+  Auth app can move to `createAccess` without resetting passwords, and a sign-in that matches one (`/sign-in/email`,
+  `/sign-in/username`, any `/sign-in/*` route that takes a password) stores the password again with argon2id. Each
+  such account leaves scrypt at its next sign-in. Once none is left, turn `legacyScrypt` off.
+- The time a check takes does not say what an account holds. Every check costs one argon2id computation at your
+  profile, as Better Auth's hash of the guess costs for an unknown user, whether the stored value is an argon2id hash,
+  a scrypt hash or garbage. With `legacyScrypt: true`, every hash and check also costs one scrypt, so sign-up and
+  sign-in are about twice as slow while it is on. One exception: after you move to another profile, a hash stored at
+  the old one is checked at the old one's cost, so the time a sign-in takes can tell such an account apart (and that it
+  exists) until its user next signs in, which rehashes it at your profile. Active users' hashes move; an account
+  nobody signs in to keeps the old cost until its password is set again.
+- A stored hash that costs more than the largest profile (`m` over 65536, `t` over 3, `p` over 4) is refused without
+  being computed, with a warning in Better Auth's log, so a tampered row cannot make a sign-in allocate gigabytes. A
+  corrupted or tampered value, or a failure inside the argon2 computation (logged as an error), fails the check like a
+  wrong password. A check never throws.
+- A password longer than Better Auth's `emailAndPassword.maxPasswordLength` (128 by default) is never hashed: hashing
+  it is refused with Better Auth's `PASSWORD_TOO_LONG` (`400`), and checking it fails. Passwords are NFKC-normalised
+  before hashing, as Better Auth's scrypt does.
+- Better Auth's plugins that hash or check a password (`admin`, `username`, `phone-number`, `email-otp`, two-factor)
+  use the same hook, so the profile applies to them too, whether or not `emailAndPassword.enabled` is set.
+
+#### Node.js 22
+
+argon2id runs on Node.js's own `crypto.argon2`, which Node.js 24.7.0 added, with no native dependency. Node.js 22 has
+none, so there Access uses `@node-rs/argon2`, an optional peer you install yourself, at the exact version Access is
+tested against:
+
+```sh
+npm install --save-exact @node-rs/argon2@2.2.2
+```
+
+It computes the same function, and Access writes and reads the PHC strings itself, so a hash made on Node.js 22 verifies
+on Node.js 24 and back. On Node.js 24 it is never loaded, installed or not. On Node.js 22 without it, `createAccess`
+refuses with `ACCESS_OPTIONS_INVALID`, unless you hash passwords yourself (`betterAuth.emailAndPassword.password`).
+
+### What the instance holds
+
+| Member | What it is |
+|---|---|
+| `access.handler` | Better Auth's request handler, `(Request) => Promise<Response>`, with Access's routes |
+| `access.api` | Better Auth's server API, as `auth.api` |
+| `access.options` | The options Better Auth runs with: your block plus the installed plugins (what `npx auth@~1.7.12 generate --yes` reads) |
+| `access.$Infer` | Types only: `Session`, `Me` (the principal) and `Claims` |
+| `access.policy` | The policy engine. It is built on first read and is not enumerable. |
+| `access.state({ headers })` | The request's state, `{ readonly me }`: from a bearer token checked against Better Auth's key set, or (profiles `web` and `kiosk`) the session cookie; `null` when neither. `me` is a copy of the plain data `principal` returned (its plain objects and arrays, all the way down), frozen, and the state holds it read-only, so no code that runs during the request can replace or change the principal the policy decides for. A class instance, `Map`, `Set`, `Date`, typed array or getter is kept as you returned it and is not frozen: 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 |
+| `access.registry` | The registry's operator API, present only with `registry: { enabled: true }` |
+| `access.client` | Where Access is mounted and the `$access` verbs it serves, for the framework's clients ([below](#the-access-verbs)); on the kiosk profile, the kiosk's verbs too |
+| `access.kiosk` | The kiosk profile's operator API: `listDevices()` and `revokeDevice(deviceId)` ([The kiosk profile](#the-kiosk-profile)) |
+
+A bearer token that does not verify gives `me: null`, so the policies then refuse the request.
+
+### Tokens and sessions
+
+`state` takes the request's `Authorization` header first. When the header is there, the session cookie is never read:
+a valid `Bearer` token gives its identity, and anything else (another scheme, a malformed token, an empty header) gives
+`me: null`.
+
+A token is accepted when all of this holds:
+
+- it is signed by a key of the instance's key set (`GET /api/auth/jwks`). Access reads the set once, reads it again
+  every 5 minutes, and at once (no more often than every 5 seconds) for a token signed with a key it does not hold. A
+  key removed from the set stops verifying within 5 minutes. When a read fails, the last set read is kept;
+- its `iss` and its `aud` are both the instance's issuer, the base URL's origin, fixed when the instance was built. An
+  audience list that merely includes it is refused;
+- it has `sub`, `exp` and `iat`, it has not expired, and it was issued no longer ago than `tokenTtl` and not in the
+  future. 5 seconds of clock skew are allowed;
+- it carries no claim beyond the declared ones.
+
+The session cookie is read from Better Auth's store, never from its cookie cache, so a session you revoke (a sign-out,
+a revoked session, a deleted user) gives `me: null` at once. With `session.cookieCache` on, `GET /token` and the
+`set-auth-jwt` header issue a token only for a session the store still has.
+
+On a request that may change something (any method but `GET`, `HEAD` and `OPTIONS`, and a request whose method the
+host did not pass), the cookie counts only when the request comes from a site Better Auth trusts: its `Origin` is your
+base URL's or one of `trustedOrigins`, or, with no `Origin`, its `Sec-Fetch-Site` is `same-origin` or `none`. A request
+with neither header is no browser's, and its cookie is read.
+
+A token is not revoked. One issued before a sign-out, a revoked session or a deleted user keeps verifying until it
+expires, for at most `tokenTtl` (15 minutes by default). Keep `tokenTtl` short when that matters; a service that must
+see a sign-out at once reads the session instead.
+
+The session cookie is `SameSite=Lax`, Better Auth's default: a browser sends it on another site's links, never on
+another site's `POST` or `fetch`. Better Auth checks the `Origin` of its own routes that carry a cookie, and the
+framework's API takes JSON, which a cross-site HTML form cannot send. Keep it that way: an endpoint of your own that
+acts on a `GET`, or takes a form body, with the cookie as its credential, is open to cross-site requests. A session
+cookie set to `sameSite: "none"` (in `advanced.defaultCookieAttributes` or `advanced.cookies.session_token`) is
+refused with `ACCESS_OPTIONS_INVALID` unless `trustedOrigins` names the origins your app is served from. With them,
+`state` holds every request to the trusted-site rule above, `GET` included.
+
+## Mount the routes
+
+Access's routes are Better Auth's, plus its own, and they mount the way Better Auth's do. Better Auth's own helpers take
+the Access instance as it is. The framework's hosts mount no Access route.
+
+### Next.js
+
+The catch-all route file, as in Better Auth's Next.js docs:
+
+```ts
+// src/app/api/auth/[...all]/route.ts
+import { toNextJsHandler } from "better-auth/next-js";
+import { access } from "@/access";
+
+export const { GET, POST } = toNextJsHandler(access);
+```
+
+A Next.js server bundle carries Better Auth (Turbopack or webpack, and `output: "standalone"` too). Next.js evaluates
+your `access.ts` once per bundle, so one process can hold several Access instances. That is expected: each one reads
+Better Auth's key set from your database once.
+
+### NestJS, Express and Fastify
+
+Mount Better Auth's Node.js handler before the body parser. In NestJS, that is `app.use()` between
+`NestFactory.create()` and `listen()`, with a path test. It works on Express and Fastify alike:
+
+```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();
+```
+
+On Fastify, `app.use("/api/auth", …)` hands Better Auth the URL without its base path, so use the path test above. Your
+own controllers keep Nest's body parser. In a plain Express app, mount `toNodeHandler(access)` the same way, before
+`express.json()`.
+
+If you enable CORS, register it before this mount, so Access's routes answer the same origins.
+
+### Standalone
+
+`serve` runs Access as its own HTTP server around the same handler, with `GET /health` answering
+`200 {"status":"ok"}`:
+
+```ts
+// src/access.server.ts
+import { serve } from "@aventara/access/standalone";
+import access from "../access.config.js";
+
+const server = await serve(access, { port: 4000 });
+console.log(`Access listens on ${server.url}`);
+```
+
+`port` defaults to `3000`, and `0` picks a free one. `hostname` defaults to `"127.0.0.1"`, this host only; pass
+`"0.0.0.0"` to listen on every interface. `serve` resolves to `{ port, url, close() }` once the server listens.
+`avaccess serve` runs the same server from a configuration file ([Running `avaccess serve`](#running-avaccess-serve)).
+
+`serve` speaks plain HTTP. Sessions, tokens and registry keys travel in headers, so put it behind a proxy that
+terminates TLS before anything outside the host reaches it. What it does for the handler behind it:
+
+- A request body over `maxBodyBytes` (default 1 MiB, `1048576`) is refused with `413` before it is handed on: by its
+  `Content-Length` without reading it, or as soon as a streamed body passes the cap. A push to the registry has its
+  key checked before its body is read.
+- The client's address is the socket's. `X-Forwarded-For` (or the first of Better Auth's
+  `advanced.ipAddress.ipAddressHeaders`) is replaced with it, unless the socket is a proxy listed in Better Auth's
+  `advanced.ipAddress.trustedProxies`: then the proxy's header is kept, and Better Auth reads the client from it.
+  Better Auth's rate limit counts each client on its own, and no client picks its own address.
+- `close()` stops accepting connections, lets the requests in flight finish for up to 10 seconds, then ends the rest.
+
+### Sign up and sign in
+
+Better Auth's routes are under `/api/auth`. With `emailAndPassword` on, from a terminal:
+
+```sh
+# Sign up: the user is created and signed in.
+curl -X POST http://localhost:3000/api/auth/sign-up/email \
+  -H 'Content-Type: application/json' -H 'Origin: http://localhost:3000' \
+  -d '{ "email": "ada@example.com", "password": "correct-horse-battery", "name": "Ada" }'
+
+# Sign in: the session cookie goes into cookies.txt.
+curl -c cookies.txt -X POST http://localhost:3000/api/auth/sign-in/email \
+  -H 'Content-Type: application/json' -H 'Origin: http://localhost:3000' \
+  -d '{ "email": "ada@example.com", "password": "correct-horse-battery" }'
+
+# A token for a service: the session cookie traded for a JWT, sent as a bearer token.
+curl -b cookies.txt http://localhost:3000/api/auth/token
+```
+
+A browser's `fetch` to the same routes sends `Origin` itself.
+
+With `emailAndPassword` on, anyone who reaches the server can sign up. A server whose users are created another way
+(an admin, an invitation, a social provider) sets `emailAndPassword: { enabled: true, disableSignUp: true }`, and a
+server that signs in no one, such as one that only runs the registry, leaves `emailAndPassword` out.
+
+Send an `Origin` header that matches Better Auth's base URL (`BETTER_AUTH_URL`) or one of its `trustedOrigins`. A
+request that carries a cookie is refused `403 MISSING_OR_NULL_ORIGIN` without one, and `403 INVALID_ORIGIN` with
+another. The Aventara API then reads the user from the session cookie (profiles `web` and `kiosk`) or from
+`Authorization: Bearer <token>`.
+
+## Wire it into Aventara
+
+The instance fits the framework's `access` option (`AvAccessProvider`) by shape: it brings the policy engine and each
+request's `me`. With `access`, the configuration has no `policy` and the host has no `state` option.
+
+### Next.js
+
+Put `access` in `aventaraConfig`, in `src/aventara/config.ts`, not in `server.ts`:
+
+```ts
+// src/aventara/config.ts
+import { access } from "../access";
+
+export const aventaraConfig = {
+	api: "/api",
+	exposed: true,
+	// The rest of the configuration `aventara new` wrote stays as it is.
+	access,
+} as const;
+```
+
+The build (`aventara:prepare`, which `next build` runs first) reads `config.ts` to compile the Contracts. With `access`
+there, the prebuilt Contracts match what the server runs, and the governed fields reach the generated client. Given
+only in `server.ts`, the framework warns `AVENTARA_PREBUILT_STALE` and compiles the Contracts at startup. `server.ts`
+needs no change: it already spreads `aventaraConfig` into `Aventara()`.
+
+`aventara-build` runs `config.ts`, and so your `access.ts`, at build time. It reads the project's `.env` files first,
+as `avclient generate` does (a variable already set wins, then `.env.<mode>.local`, `.env.<mode>`, `.env.local` and
+`.env`), so a database client that reads `DATABASE_URL` at import finds it.
+
+### NestJS
+
+Put `access` beside `adapter` in the `config` that the scaffold's `forRootAsync` factory returns. This is the scaffold's
+`src/app.module.ts` with the two `access` lines added:
+
+```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 {}
+```
+
+Here `aventaraConfig` is the configuration without `policy`, since Access brings the engine. Nest compiles its
+Contracts at startup, so nothing goes stale.
+
+For the MCP endpoint, see [Agents over MCP](#agents-over-mcp): `mcp: { path: "/mcp", authorization: access.mcp }`.
+
+### Anywhere else
+
+`createFramework({ ...config, access })`.
+
+With the Better Auth plugin, `accessOf(auth)` is the `access` value, in each of the places above.
+
+### The `$access` verbs
+
+`access.client` is what the framework's `$access` reads (the provider's `client` member): where Access is mounted, and
+the verbs this instance serves. `url` is Better Auth's base URL with its base path (`http://localhost:3000/api/auth`),
+or the base path alone (`/api/auth`) when `baseURL` is dynamic and follows the request's host. Each verb has a method,
+a path under `url`, the JSON Schema of its arguments and of its result, and `call`:
+
+| Verb | Route | Arguments | Result |
+|---|---|---|---|
+| `signIn` | `POST /sign-in/email` | `email`, `password`, optional `callbackURL`, `rememberMe` | `redirect`, `url`, `user: { id }` |
+| `signUp` | `POST /sign-up/email` | `name`, `email`, `password`, optional `image`, `callbackURL`, `rememberMe` | `user: { id }` |
+| `signOut` | `POST /sign-out` | none | `success` |
+| `resetPassword` | `POST /reset-password` | `newPassword`, `token` | `status` |
+| `me` | `GET /me` | none | `{ sub, claims }`, or `null` when no one is signed in |
+
+The arguments are the ones Better Auth's client sends on each route. A result names the user's id and Better Auth's own
+flags, never the session token or a field of the user. `me` is the token identity: `sub` and the claims
+`policies.claims` declares, the same as the token carries, whatever `principal` maps the request to. `GET /api/auth/me`
+is Access's own route, served by `access.handler`; a plugin of yours with an endpoint at `/me` (or named `accessMe`) is
+refused with `ACCESS_PLUGIN_DUPLICATE`.
+
+A verb the instance does not serve is left out: `signIn`, `signUp` and `resetPassword` need `emailAndPassword`,
+`signUp` is left out with `disableSignUp`, a path in `disabledPaths` takes its verb out, and the `service` profile has
+no `signIn` or `signUp`.
+
+`call({ args, headers })` runs the verb on the server, in the same process, through Better Auth's API with the
+request's headers. That is how a Server Action signs a user in: Better Auth's `nextCookies()` plugin, last in
+`betterAuth.plugins`, sets the browser's cookie from the answer. The call is checked as the route would be: the
+arguments against the verb's schema (`400` naming the key, never the value), Better Auth's origin check (a cookie from
+a site Better Auth does not trust, or a `callbackURL` outside `trustedOrigins`, is refused `403`), every plugin's
+`onRequest` in the order Better Auth's router runs them (so `captcha()` refuses a call without its answer, as it refuses
+the route; a plugin's refusal is thrown as Better Auth's `APIError` with the plugin's status and body, and a plugin's new
+request is the one the route runs with), the profile's refusals, and the audit log, which records the sign-in with
+origin `client`.
+
+Better Auth's rate limit runs in its router, which a call to Better Auth's API skips, so Access limits the calls of
+`signIn`, `signUp` and `resetPassword` itself, with Better Auth's own `rateLimit` options: on when they turn it on
+(`enabled`, production by default), with the rule Better Auth's router applies to the route (3 tries in 10 seconds on
+`/sign-in/*` and `/sign-up/*` by default, a plugin's rules, `customRules`, else `window` and `max`), in the storage they
+name (`customStorage`, `secondaryStorage`, the database, or memory). Each call is counted in two buckets, and refused
+when either is full:
+
+- **by client address**, read from the request's headers as Better Auth reads it (`advanced.ipAddress`: its
+  `ipAddressHeaders`, `trustedProxies` and `ipv6Subnet`), under the key Better Auth's router uses for the route. With
+  the database, a secondary or a custom storage, a client's calls and its requests to the route spend one budget; in
+  memory they do not, since Better Auth's memory store is its own. With `disableIpTracking` there is no address bucket;
+- **by target**: the email the call names (normalized as `/sign-in/email` normalizes it), or a password reset's token,
+  as its HMAC, so guesses on one account from many addresses count together. It counts failures: 10, each within 5
+  minutes of the one before, refuse the account's next try, the right password too, until 5 minutes have passed. A
+  success clears the count, so a few failures by someone else never keep the owner out. A try is counted when it is let
+  through, so parallel guesses cannot all pass on one reading. With `customStorage`, which can count but not clear, the
+  target's count is kept in the server's memory.
+
+A refused call throws Better Auth's own `429` (`APIError` `TOO_MANY_REQUESTS`, with `X-Retry-After`), and the audit
+log records a **sign-in-failed** with reason `rate-limited`. Give the server the client's address: behind a proxy, set
+`trustedProxies`, or calls whose address cannot be read share one bucket per route, as Better Auth's requests do.
+
+### The kiosk profile
+
+`profile: { kind: "kiosk", canEnrollDevice, idleTimeout?, insecureLan? }` is the web profile plus staff switching by PIN on shared
+devices, such as the tills of a shop. A manager enrolls a device once; after that, anyone with a PIN switches the
+device to themselves with their user id and PIN, and the session that opens is bound to that device and locks when
+idle.
+
+| Option | Takes | Default |
+|---|---|---|
+| `canEnrollDevice` | `(identity) => boolean`: who may enroll, list or revoke devices, asked with `{ sub, claims }` (typed from `policies.claims`) of a fresh session opened with full credentials. Anything but `true` refuses. | required |
+| `idleTimeout` | Seconds without a request that may change something (any method but GET, HEAD or OPTIONS) after which a session on the device locks: whole seconds from 60 to 3600 | 300 |
+| `insecureLan` | The private IPv4 ranges of a till network without TLS, on whose addresses a plain http: base URL is taken ([A till network without TLS](#a-till-network-without-tls)) | none |
+
+`profile` takes one kind. The kiosk's keys on `web` or `service`, or two kinds at once (`kind: ["kiosk",
+"service"]`), are a type error and are refused with `ACCESS_OPTIONS_INVALID`: a service hands no caller a session,
+and a kiosk is made of them. The kiosk also refuses, each because it is a way around the device binding:
+
+- Better Auth's cookie cache (a locked session must end at once, and the cookie cache would keep answering it);
+- `secondaryStorage` without `session.storeSessionInDatabase: true` (the kiosk finds a device's sessions in the
+  database to end them);
+- Better Auth's `bearer()` (it hands a session's token to page code and takes it back from an `Authorization` header,
+  where the device's credential does not go). Under any other id, no answer carries its `set-auth-token` header;
+- Better Auth's `multiSession()` (it keeps the session before a switch in the browser and switches back to it);
+- `advanced.crossSubDomainCookies`, and `SameSite=None` in `advanced.defaultCookieAttributes` or on any cookie in
+  `advanced.cookies` (the credential and the sessions would reach other hosts, or come from other sites);
+- a plain http: base URL, except on a loopback host (`localhost`, 127.0.0.0/8, `[::1]`) or on an address
+  `insecureLan` lists: the credential and the PIN sessions would cross the network in the clear. A dynamic `baseURL`
+  is read whole: it takes `protocol: "https"`, unless every allowed host is a loopback host.
+
+On the web and service profiles there is no PIN route: each answers `404`.
+
+The routes, under Better Auth's base path, and the verbs `access.client.verbs` publishes for them on this profile,
+after Better Auth's (the framework's `$access` takes them as optional verbs):
+
+| Verb | Route | Arguments | Result | Who |
+|---|---|---|---|---|
+| `enrollDevice` | `POST /kiosk/enroll-device` | `name` | `device: { id, name }` | A fresh full-credential session `canEnrollDevice` allows |
+| `revokeDevice` | `POST /kiosk/revoke-device` | `deviceId` | `success` | The same |
+| `setPin` | `POST /kiosk/set-pin` | `pin` | `success` | A fresh full-credential session, for its own user |
+| `switchUser` | `POST /kiosk/switch-user` | `userId`, `pin` | `user: { id }` | An enrolled device |
+| `lock` | `POST /kiosk/lock` | none | `success` | An enrolled device |
+
+`GET /kiosk/list-devices` answers a manager (the same as `enrollDevice`) with `devices: [{ id, name, enrolledBy,
+enrolledAt, lastSwitchAt? }]`, never a credential. It is a route only: the framework's set of verbs is closed. Call the
+verbs' routes from the device, or their `call` from your server. A `call` of `switchUser`, `lock` or `enrollDevice`
+sets the session cookie and the device's credential through your cookie plugin (Better Auth's `nextCookies()` in a
+Server Action), as `signIn`'s does. Without one the browser keeps the credential the switch replaced, and the device's
+next switch is refused as a copy: call the route from the device instead.
+
+Your server has its own way in, which no route opens:
+
+| Call | Does |
+|---|---|
+| `access.kiosk.listDevices()` | The enrolled devices, as `GET /kiosk/list-devices` answers them (dates as `Date`) |
+| `access.kiosk.revokeDevice(deviceId)` | Revokes a device, ending every session on it; `false` when there is none |
+| `access.api.kioskSetUserPin({ body: { userId, pin } })` | Sets anyone's PIN, so staff who have no password get one from a manager's screen your app guards. Better Auth's server-only endpoint: its router never serves it, and a call with a PIN session's headers is refused |
+
+`access.kiosk` is there on the kiosk profile only.
+
+- **A fresh full-credential session** is one opened with a password (or any sign-in but a PIN) within Better Auth's
+  `session.freshAge`, one day by default. A PIN session never enrolls, lists, revokes or sets a PIN.
+- **Enrolling** gives the device its credential, 32 random bytes in an HTTP-only cookie (`better-auth.kiosk_device`,
+  kept 400 days, always `SameSite=Lax`; on an https base URL, `__Host-better-auth.kiosk_device`, `Secure`, at `/` and
+  with no `Domain`, whatever Better Auth's cookie options say; under `insecureLan`, `better-auth.kiosk_device`, not
+  `Secure`, at `/` and with no `Domain`). A Strict device cookie would not be sent on a link the
+  till opens from another site (a magic link from webmail), and the session it opens would not be bound. Enrolling
+  ends the session that enrolled it, so no manager's session stays on
+  a shared device: the device starts locked. Enrolling a device that already has a credential revokes the old
+  enrollment first.
+- **A PIN** is 6 to 12 digits, refused when it is set (`400 PIN_TOO_WEAK`) if it is one a guesser tries first: the
+  blocklist Apple's iOS uses for 6-digit passcodes (as Markert et al. extracted it, IEEE S&P 2020), widened to every
+  length (one digit or a block repeated, `000000`, `121212`, `123123`; two digits alternating; a palindrome,
+  `123321`; a straight run, `123456`; doubled digits, `112233`; lines of the keypad, `147258`, `159753`), and the
+  most common 6-digit PINs of leaked passwords (`789456`, `246810`, `520131`). Dates are not refused. It is hashed with
+  argon2id at the `passwords` profile, whatever hashes your users' passwords, and never stored, logged or answered.
+  Setting a PIN clears its user's failed PINs.
+- **A switch** checks the device's credential, then the PIN. A right one ends every session on the device, and any
+  other session the request carried, and opens a new one for the user named, with that user's own claims: nothing of
+  the session before it carries over. The device's credential is replaced in the same answer, so a copy of the old one
+  is spent. The audit log records a `kiosk-switch` naming the user before (`previousUserId`) and after. A session
+  Better Auth refuses to open (a user the admin plugin banned, or your own session hook) leaves the device as it was.
+- **Lock** ends the same sessions and keeps the device enrolled. A session on the device idle for `idleTimeout` is
+  ended on its next request, as if locked (`kiosk-lock`, reason `idle`). Only a request that may change something
+  counts as use: any method but GET, HEAD or OPTIONS, through Better Auth's routes or through the framework
+  (`access.state` reads the host's method). A page left open that keeps reading, such as Better Auth's client polling
+  `/get-session`, does not keep its session alive.
+- **Revoking** a device ends every session on it at once. Nothing is pushed to the till: it learns on its next
+  request, which finds no session, and its next switch is refused `KIOSK_DEVICE_NOT_ENROLLED`.
+
+What protects a PIN, a weak secret:
+
+- **Per user, on one device**: 5 wrong PINs free, then one try per backoff that doubles from 1 minute to 1 hour
+  (`429 KIOSK_PIN_LOCKED`, with `X-Retry-After`), the right PIN included. After 100 in a row (NIST SP 800-63B's
+  ceiling) the PIN alone stops working on that device (`403 KIOSK_PIN_DISABLED`); the backoff makes that take days,
+  every try logged. It is kept per device, so whoever stands at a device can slow or disable a colleague's PIN on that
+  device only. On every other device it still works, and the user's next full sign-in, or a new PIN, clears it
+  everywhere. An admin's impersonation is no full sign-in and clears nothing. The account itself is never locked.
+- **Per device**: 10 wrong PINs at once, for any users, then one more every 90 seconds (a token bucket, so no
+  window's edge lets a second burst through). A right PIN gives back its own try and no more, so knowing one PIN does
+  not reset the count between guesses at others. While the device is held, a user with no wrong PIN on it since their
+  last right one still gets one try, so one person spending a till's tries does not lock everyone else out of it.
+- Both are counted in the database before the PIN is checked, so parallel guesses cannot all pass one reading, and they
+  hold across restarts and instances. They are kept for any user id, whether it holds a PIN or names no user, and a
+  user id with no PIN costs the same argon2id check as one with a PIN, so no answer tells who holds a PIN.
+
+What binds a session to its device:
+
+- **Every session opened on an enrolled device is bound to it**: a PIN switch's, and a password sign-in's on the
+  device too. A bound session is held to the idle timeout, is issued no token (`GET /token` refuses it), and
+  `/get-session` answers it without its token, so page code never holds one. With `mcp` or `audience`, that includes
+  the OAuth provider's tokens: a bound session is refused at `/oauth2/authorize`, `/oauth2/consent` and
+  `/oauth2/continue`, a sign-in on an enrolled device that resumes an authorization request (the login page's
+  `oauth_query`) is refused before it runs, a social sign-in begun elsewhere with one, whose callback lands on the
+  till, opens no session there, and a token issued in a bound session anyway verifies as nobody. A bound session is
+  refused at the provider's routes that manage clients and consents too (`/oauth2/create-client`,
+  `/oauth2/get-consents`, `/oauth2/delete-consent` and the like). An agent is authorized, and its clients managed,
+  from a manager's own browser, off the till.
+- **The device's credential, on every request.** On every call of Better Auth's that carries a session, by its cookie
+  or by an `Authorization: Bearer` header (its routes, its API with headers or a `request`, `access.state` and `GET /me`), a bound
+  session is ended, and the call goes on without it, unless the request brings its device's current credential
+  (`kiosk-lock`, reason `device-mismatch`). A session copied to another browser, or to another enrolled device, is no
+  session there, and no longer one on the device it came from. A session bound to no device, brought with an enrolled
+  device's credential (current, or one a switch replaced), is ended the same way: it was opened off the device, so it
+  is no session on it.
+- **One credential at a time, and its whole family remembered.** The credential is replaced at every switch, and every
+  credential a switch replaced is kept as a hash for 400 days, the device cookie's life. Any of them brought back revokes the device with every session on it
+  (`kiosk-device`, reason `token-reuse`): a copy is in use somewhere, however many switches ago it was taken. The one
+  exception is the credential the last switch replaced, within 30 seconds of it: that is a request that left before
+  the device had its answer (a double tap, two calls at once), and it is refused (`409 KIOSK_DEVICE_BUSY`, logged as
+  `kiosk-device`, reason `stale-in-grace`) with the device and its cookie left as they are; so is a sign-in that brings
+  it, which opens no session. A device whose answer was lost in transit is revoked after those 30 seconds,
+  and a manager enrolls it again.
+- **No way out of the device.** A PIN session reaches only `/get-session`, `/sign-out`, `/me`, `/jwks`,
+  `/kiosk/switch-user`, `/kiosk/lock` and the routes that sign in with full credentials, whether the call comes
+  through `access.handler` or your server's own `access.api` call with its cookie; any other is refused `403
+  KIOSK_SESSION_NOT_ALLOWED`, so it mints no token, no other session (one-time tokens, impersonation), no credential
+  (passkeys, API keys, linked accounts) and changes no account.
+
+The kiosk's tables are `accessKioskDevice`, `accessKioskPin`, `accessKioskLockout` and `accessKioskRetiredSecret`,
+and Better Auth's `session` gains `kioskDeviceId`, `kioskSeenAt` and `kioskPin` (no user sets them). `npx auth@~1.7.12
+generate --yes` writes them as it writes Better Auth's own; off Prisma's adapter, name them in `resources.authTables`. Like
+Access's other tables they stay closed to every request, and a credential's or a PIN's hash is a secret column no grant
+opens.
+
+| Code | Status | When |
+|---|---|---|
+| `KIOSK_DEVICE_NOT_ENROLLED` | 401 | The request brings no current device credential |
+| `INVALID_USER_OR_PIN` | 401 | A wrong PIN, a user with none, or no such user (also `400` for a PIN that is not 6 to 12 digits) |
+| `KIOSK_PIN_LOCKED` | 429 | The user's backoff on this device, or the device's limit; `X-Retry-After` says when |
+| `KIOSK_PIN_DISABLED` | 403 | 100 wrong PINs in a row for this user on this device; a full sign-in or a new PIN restores it |
+| `KIOSK_DEVICE_BUSY` | 409 | Two switches on one device at the same moment, or a request or sign-in with the credential the last switch replaced, within 30 seconds of it; try again |
+| `KIOSK_FULL_CREDENTIAL_REQUIRED`, `SESSION_NOT_FRESH` | 403 | Enrolling, listing, revoking or setting a PIN from a PIN session, or a session older than `freshAge` |
+| `KIOSK_ENROLL_REFUSED` | 403 | `canEnrollDevice` did not answer `true` |
+| `KIOSK_SESSION_NOT_ALLOWED` | 403 | A PIN session on a route it does not reach, a device-bound session asking for a token or managing OAuth clients or consents, or a sign-in on an enrolled device that would resume an authorization request |
+| `KIOSK_DEVICE_NOT_FOUND` | 404 | Revoking a device that is not enrolled |
+| `USER_NOT_FOUND` | 404 | `kioskSetUserPin` for no such user |
+| `PIN_TOO_WEAK` | 400 | A PIN that is not 6 to 12 digits, or one a guesser tries first |
+
+A plugin in `betterAuth.plugins` with an endpoint under `/kiosk/` (or named `kioskSwitchUser` and the like) is refused
+with `ACCESS_PLUGIN_DUPLICATE` on this profile.
+
+#### A till network without TLS
+
+An on-prem shop may run its server on the tills' own network: a router of its own, WPA3, with nothing else on
+it, and no certificate a tablet would trust. `insecureLan` lists that network's ranges, and the kiosk then takes a
+plain http: base URL on an address inside one, such as `baseURL: "http://192.168.1.10:3000"` with
+`insecureLan: ["192.168.1.0/24"]`. Everything that crosses that network does so in the clear: the device's
+credential, the PIN sessions and the PINs themselves. Anyone who joins the network, or reads its radio, can take a
+till's session or learn a PIN. Use it only on a network that is the tills' alone.
+
+- **A range** is an IPv4 CIDR written in full, four decimal numbers without leading zeros and a prefix length, with
+  its host bits clear (`192.168.1.0/24`, or `192.168.1.10/32` for the server alone). It is a /16 or narrower and lies
+  wholly inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16. A hostname (`localhost` and `till.lan` included), an IPv6
+  range, a shared (100.64.0.0/10), link-local, loopback or public range, an empty list, a range listed twice and a
+  range inside another listed one are refused with `ACCESS_OPTIONS_INVALID`; the type takes a non-empty list of `a.b.c.d/n` strings, so a hostname or a
+  missing prefix length is a type error first.
+- **The base URL** is http: on an IPv4 address inside a listed range: never a hostname, which a resolver could point
+  elsewhere, and never IPv6. It is written as the browser writes it: `http://192.168.001.010` (which a browser reads
+  as 192.168.1.8) or `http://3232235786` is refused, naming the form to write, so the address you read is the one
+  used. A range's network or broadcast address (`192.168.1.0` or `192.168.1.255` in a /24) is refused too: no server
+  has it. It is a fixed `baseURL` (or `BETTER_AUTH_URL`), not a dynamic one. An https: base URL, or a loopback one,
+  ignores `insecureLan`.
+- **Cookies** follow http: Better Auth's session cookie is not `Secure`, and the device's credential is
+  `better-auth.kiosk_device`, HTTP-only, `SameSite=Lax`, at `/`, with no `Domain`, and not `Secure`. A browser drops a
+  `Secure` cookie, or one named `__Secure-` or `__Host-`, on a plain http page off a loopback host, so
+  `advanced.useSecureCookies: true`, a `secure: true` in `advanced.defaultCookieAttributes` or `advanced.cookies`, and
+  such a prefix in `advanced.cookiePrefix` or a cookie's `name` are refused here. Cookies are not kept apart by port:
+  run nothing else on the server's address. A service on another port of that address receives every till's
+  credential and session, and can set cookies in any browser that visits it. With a till's credential planted in a
+  browser, it can end that browser's session and bind its next sign-in to the till.
+- **Origins**: Better Auth's origin check takes the base URL's origin as it does on https, and refuses another, a
+  second address on the same network included.
+- **At startup** Better Auth's logger warns, naming the base URL and the ranges. `logger: { disabled: true }` in
+  `betterAuth` silences it with the rest of Better Auth's log.
+
+Everything else is as on https: the device binding, the credential replaced at every switch, the idle lock, the PIN
+limits and the refusals of tokens.
+
+#### A till that is an Expo app
+
+A till can be a React Native app on Better Auth's Expo integration (`@better-auth/expo`) instead of a browser. Its
+client keeps the cookies in SecureStore and sends them in a `Cookie` header, so the device's credential and the session
+work as they do in a browser: enrolling, switching (each switch's new credential is the one it keeps), the idle lock,
+lock and revoking. On the server:
+
+- Add Better Auth's `expo()` to `betterAuth.plugins`, and the app's scheme to `trustedOrigins` (`"tillapp://"`). The
+  app names itself in an `expo-origin` header, which `expo()` makes the request's `Origin` when it has none, and Better
+  Auth's origin check then takes it like a trusted site. A browser always sends its own `Origin`, which `expo()` leaves
+  as it is. In Expo Go the origin is `exp://` and the dev server's address; `expo()` trusts `exp://` only when
+  `NODE_ENV` is `development`.
+- Send the app's cookies to your Aventara API too (`Cookie: await authClient.getCookie()`): the device's credential is
+  one of them, and without it a bound session is ended.
+- On the till, staff sign in with their password (`signIn.email`) or switch by PIN. Two of the Expo client's sign-ins
+  open the session off the device and it is not bound, so the till ends it on its next request: a native ID-token
+  sign-in (`signIn.social` with `idToken`), which the Expo client sends with no cookie, and a sign-in in the system
+  browser handed back to the app (a magic link, social sign-in's redirect). For an ID-token sign-in on a till, pass the
+  cookies and the origin yourself, `{ headers: { cookie: await authClient.getCookie(), "expo-origin": "tillapp://" } }`
+  as `signIn.social`'s second argument, and the session is bound. A redirect sign-in cannot be bound: the system
+  browser does not hold the device's credential, and it keeps that session itself, where the next person at the till
+  could open it. On a till, use a password or a PIN; if a till must sign in that way, open the browser session as an
+  ephemeral one (`preferEphemeralSession` in `expo-web-browser`'s `openAuthSessionAsync`, on iOS), so the system
+  browser keeps nothing.
+- `expo()` hands a redirect sign-in's session cookie to the app in the redirect URL (`?cookie=`). On Android another
+  app that registers the same scheme could receive it. That is Better Auth's Expo integration, not the kiosk, and on a
+  till such a session is not bound, so the till ends it.
+- A native app has no HTTP-only cookie: the device's credential and the session token sit in SecureStore, where the
+  app's own code can read them. `/get-session` still answers a bound session without its token.
+- Under `insecureLan`, React Native refuses plain http by default: allow the server's address in Android's network
+  security configuration (`cleartextTrafficPermitted`) and in iOS's App Transport Security (an exception for the
+  address, or `NSAllowsLocalNetworking`). The Expo client sends the cookies to the base URL whatever their attributes,
+  so nothing on the till stops the credential from going over http: the network must be the tills' alone.
+
+## Agents over MCP
+
+Better Auth authenticates; Access authorizes. An agent's client gets its token from Better Auth's own OAuth provider,
+`@better-auth/oauth-provider`, which you add to `betterAuth.plugins` with its options as Better Auth's docs give them.
+Access issues no token and serves no OAuth route. With `mcp: { resource }` it reads the provider's tokens for your MCP
+endpoint, holds the agent to its user's grants and its token's scopes, and gives the framework its `mcp.authorization`.
+
+```ts
+// src/access.mcp.ts
+import { createAccess } from "@aventara/access/auth";
+import { cimd } from "@better-auth/cimd";
+import { fetchClientMetadataResource } from "@better-auth/cimd/node";
+import { oauthProvider } from "@better-auth/oauth-provider";
+import { Pool } from "pg";
+import { policies } from "./access.policies.js";
+
+/** The MCP endpoint, as its protected-resource metadata names it. */
+const resource = "https://app.example.com/mcp";
+
+const claims = { role: "string", banned: "boolean" } as const;
+
+export const access = createAccess({
+	betterAuth: {
+		database: new Pool({ connectionString: process.env.DATABASE_URL }),
+		baseURL: "https://app.example.com",
+		emailAndPassword: { enabled: true },
+		user: {
+			additionalFields: {
+				role: { type: "string", required: false, input: false },
+				banned: { type: "boolean", required: false, input: false },
+			},
+		},
+		plugins: [
+			// Better Auth's OAuth provider, as its docs give it: it issues every token.
+			oauthProvider({
+				loginPage: "/sign-in",
+				consentPage: "/consent",
+				scopes: ["aventara:read", "aventara:write", "offline_access"],
+				resources: [resource],
+				clientRegistrationDefaultResources: [resource],
+			}),
+			// Client ID Metadata Documents: an agent's client is the domain its document is served from.
+			cimd({ fetchClientMetadataResource, metadataProfile: "mcp-2026-07-28" }),
+		],
+	},
+	policies: { rules: policies, claims },
+	principal: ({ sub, claims }) => ({
+		id: sub,
+		claims: {
+			...(claims.role === "admin" ? { role: "admin" as const } : {}),
+			...(claims.banned === undefined ? {} : { banned: claims.banned }),
+		},
+	}),
+	mcp: { resource },
+});
+```
+
+Then the framework's configuration takes it in one line: `mcp: { path: "/mcp", authorization: access.mcp }`, beside
+`access`. `access.mcp` is there exactly when `mcp` is given, and is `{ servers, verify }`:
+
+- `servers` is Access's issuer, the origin of Better Auth's base URL, alone. The provider's metadata, the `iss` of each
+  authorization response (RFC 9207) and every token's `iss` carry the same string. Mount `access.handler` at
+  `/.well-known/oauth-authorization-server` too, at the root of that origin, where a client looks for the provider's
+  metadata (RFC 8414). It is https, or on this machine `http://127.0.0.1` or `http://[::1]` with any port: set
+  `baseURL` to that address, not `localhost` (a name is resolved, and may resolve elsewhere). An http issuer is for
+  development: a client that holds to RFC 8414 strictly refuses one.
+- `verify(token)` takes the provider's JWT access token for the MCP endpoint and nothing else, and resolves who the
+  agent acts for: `{ sub, claims, clientId, scopes }`, the claims read from the user now. It refuses a session token
+  (`GET /token`), a token for another resource, an opaque token (a client that sent no `resource`), a token bound to a
+  DPoP key, a client-credentials token (it acts for no user), and one whose client is disabled, whose user is gone or
+  no longer consents to its scopes, or whose session (when it was issued in one) has ended.
+- A JWT access token is not revoked by `POST /oauth2/revoke`: the provider answers that a self-contained token cannot
+  be revoked server-side, and the token keeps verifying until it expires. To stop an agent at once, revoke the user's
+  consent to its client, disable the client or end the session it was issued in (each is read on every request);
+  keep the provider's `accessTokenExpiresIn` short. A refresh token `/oauth2/revoke` does revoke.
+- With Better Auth's `secondaryStorage`, the provider requires `session.storeSessionInDatabase: true`, so the session a
+  token names is a database row; with `preserveSessionInDatabase` too, Better Auth ends that row when the session ends,
+  and the token stops.
+- Better Auth's OAuth provider (1.7.12 to 1.7.14) cannot register its resource on Better Auth's Prisma adapter: it writes
+  `allowedScopes: null` into a `String[]` column, which Prisma will not leave unset. Run Better Auth on a `pg` `Pool`
+  (its built-in Kysely) for the provider's tables, as the samples here do; the tables can still be in your Prisma
+  schema (`auth generate` writes them, `prisma db push` makes them, `resources.authTables` names each).
+
+Install the provider and `@better-auth/cimd` in the same range as Better Auth (`npm install
+@better-auth/oauth-provider@~1.7.12 @better-auth/cimd@~1.7.12`); npm takes the newest patch of each, with Better Auth's
+at the same patch. With it an agent's client registers itself by its `client_id`, the URL of its metadata document, and
+your consent page can name the domain it comes from. Open dynamic registration (`allowDynamicClientRegistration` with
+`allowUnauthenticatedClientRegistration: true`) registers any client as whoever it says it is, so Access refuses it
+unless you acknowledge it with `mcp: { resource, openRegistration: true }`. Registration by a signed-in user or with
+an initial access token needs no acknowledgement.
+
+The request state reads the same token, so `ctx.$state.me` is the user's principal, as `principal` maps it. The
+policy holds it to the token before the rules:
+
+- under the `agent` origin, `aventara:read` admits the read questions and `aventara:write` the writes (`create`,
+  `update`, `delete`); a question the scopes do not admit is refused, and one they admit is the user's own, so an agent
+  never does what its user may not. Your rules can narrow it further by origin;
+- under any other origin it is refused everything: the token opens the MCP endpoint alone, never the protocol routes,
+  `_access/can`, a server-side call or Access's own `GET /me` route, which answers it `null`;
+- a refused question is an audit event like any other, with the reason `deny:mcp-scope` or `deny:mcp-audience`.
+
+The claims are read from the user on every request, so a ban or a role taken away reaches the agent on its next call,
+not when its token expires.
+
+`me()` is the token identity, `{ sub, claims }`, everywhere, the MCP surface included: the framework's MCP `me` tool
+calls `access.client.verbs.me.call` in-process with the agent's headers, and it answers who the agent acts for, marked
+so that `agentOf` (below) tells it is an agent's. Only the HTTP route `GET /me` answers an agent's token `null`.
+
+To tell an agent's request apart in your own code, call `agentOf(me)`, exported from `@aventara/access/auth` and
+`@aventara/access/better-auth`. It answers `{ clientId, scopes }` for the principal an agent's token yields, and for the
+identity `principal` is given for one, so your mapping can see it too; for any other principal it answers `null`. The
+mark does not show in the principal's own fields, its spread or its JSON.
+
+```ts
+// src/agent.check.ts
+import { agentOf } from "@aventara/access/auth";
+
+/** Whether a request's principal is an agent acting for its user, and which client. */
+export const actingAgent = (me: unknown): string | null => agentOf(me)?.clientId ?? null;
+```
+
+Access refuses to start (`ACCESS_OPTIONS_INVALID`) on a provider that would let an agent's authorization fall short:
+none in the plugins, or two; opaque access tokens (`disableJwtPlugin`); the endpoint missing from its `resources`; no
+`aventara:read` among its `scopes`; a refresh reuse window (`refreshTokenReuseInterval` other than 0, the provider's
+default: a spent refresh token is never answered again); a `validateRedirectUri` that accepts redirect URIs the client
+did not register; a `requestUriResolver` (an authorization request by reference); a `postLogin.consentReferenceId`
+(a JWT access token does not say which reference its consent was stored under); open registration without
+`openRegistration`; an endpoint that is the provider's own UserInfo URL; or the `service` profile, which hands no
+browser a session to consent in. A provider or a `cimd()` outside `~1.7.12` is refused
+with `ACCESS_BETTER_AUTH_VERSION`. Every authorization request must use PKCE with its SHA-256 method and carry its own
+parameters: Access refuses one without, or one by reference (`request_uri`), with `400 invalid_request`, from any
+client. `verify` also refuses a token without the session it was issued in (`sid`), one signed with an algorithm
+`jwt()` does not sign with, one for a resource the provider no longer has, and one whose user's consent does not name
+the endpoint.
+
+With the plugin, pass the same `mcp` to `aventaraAccess()` and put `oauthProvider()` after it in `plugins`: Better Auth
+starts its plugins in order, and the provider reads the `jwt()` the Access plugin carries as it starts.
+`accessOf(auth).mcp` is then the framework's `mcp.authorization`.
+
+Your consent page is your app's, as Better Auth's provider leaves it. Show the client's name, the domain of its
+metadata document and the host of the redirect URI it asked for, and say what each scope lets the agent do.
+
+### One audience per service
+
+By default a service takes the one-org token `GET /token` issues, whose audience is the issuer. A service can opt in
+to tokens addressed to it alone (RFC 8707): `audience` names its URL, as a client names it when it asks the provider
+for a token (`resource`), and the provider lists it among its `resources`. Each client the service takes is linked to
+it, one by one (`auth.api.adminLinkClientResource`, the provider's own operator call), and asks for one of Access's
+scopes.
+
+```ts
+// src/access.audience.ts
+import { createAccess } from "@aventara/access/auth";
+import { oauthProvider } from "@better-auth/oauth-provider";
+import { Pool } from "pg";
+import { policies } from "./access.policies.js";
+
+/** This service, as a client names it when it asks for a token. */
+const audience = "https://app.example.com/api";
+
+const claims = { role: "string", banned: "boolean" } as const;
+
+export const access = createAccess({
+	betterAuth: {
+		database: new Pool({ connectionString: process.env.DATABASE_URL }),
+		baseURL: "https://app.example.com",
+		emailAndPassword: { enabled: true },
+		user: {
+			additionalFields: {
+				role: { type: "string", required: false, input: false },
+				banned: { type: "boolean", required: false, input: false },
+			},
+		},
+		plugins: [
+			oauthProvider({
+				loginPage: "/sign-in",
+				consentPage: "/consent",
+				scopes: ["aventara:read", "aventara:write", "offline_access"],
+				resources: [audience],
+			}),
+		],
+	},
+	policies: { rules: policies, claims },
+	principal: ({ sub, claims }) => ({
+		id: sub,
+		claims: {
+			...(claims.role === "admin" ? { role: "admin" as const } : {}),
+			...(claims.banned === undefined ? {} : { banned: claims.banned }),
+		},
+	}),
+	audience,
+});
+```
+
+With `audience`, the request state takes a bearer token only when it is the provider's access token addressed to the
+service alone, checked as `verify` checks an agent's (its client, user, consent and session), and carrying
+`aventara:read` or `aventara:write`; one with neither is nobody's. Its principal is the user's, held to those scopes
+under every origin, as an agent's is under `agent`: `aventara:read` reads, `aventara:write` writes, and a scope never
+grants what the user's own grants do not. The one-org token is refused; a session cookie is read as before. Without it
+nothing changes. `aventaraAccess()` takes the same `audience`. It cannot be the MCP endpoint, the issuer itself or the
+provider's UserInfo URL.
+
+Access refuses (`ACCESS_OPTIONS_INVALID`) a provider whose `enforcePerClientResources: false` lets any client ask for a
+token for the service, and open registration, which `audience` alone never takes. With `mcp` beside it, the service's
+audience in `clientRegistrationDefaultResources` or `clientRegistrationAllowedResources` is refused too: an agent's
+client that registers itself would be linked to the service, and a token it refreshed for it would pass for the
+service's own.
+
+## The Better Auth plugin
+
+`createAccess` builds Better Auth for you. When your app already calls `betterAuth({...})` itself, add Access to it as
+a plugin instead. `aventaraAccess()` takes the same `policies`, `principal`, `resources`, `audit`, `passwords` and
+`registry` as `createAccess`.
+`accessOf(auth)` gives the framework its `access` option from that Better Auth instance.
+
+This app's rules are its organizations' (Better Auth's `organization()` plugin): the organization bridge, below, puts a
+member's role and organization into the token, and every rule on that role is held to that organization.
+
+```ts
+// src/org.policies.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** What every token carries beside `sub`: the ban, and the organization bridge's two claims. */
+export const claims = {
+	banned: "boolean",
+	orgRole: "string",
+	org: "string",
+} as const;
+
+/** The principal: the user, with the session's active organization copied up for the rules. */
+export type Principal = {
+	id: string;
+	org?: string;
+	claims: { banned?: boolean; orgRole?: string; org?: string };
+};
+
+export const orgPolicies = definePolicies(model)
+	.principal<Principal>()
+	.roles(() => ({
+		// The bridge's role: an admin of the session's active organization.
+		orgAdmin: { global: { claims: { orgRole: "admin" } } },
+	}))
+	.grants(({ grant, me }) => [
+		// Every grant is held to the principal's organization: a role from the bridge is
+		// that organization's, never a global one.
+		grant("signedIn", "read", "Campaign", { where: { organizationId: me.org } }),
+		grant("orgAdmin", ["create", "update", "delete"], "Campaign", {
+			where: { organizationId: me.org },
+		}),
+	])
+	.denies(({ deny }) => [deny("*", "*", { if: { claims: { banned: true } } })]);
+```
+
+```ts
+// src/auth.ts
+import { accessOf, aventaraAccess } from "@aventara/access/better-auth";
+import { PrismaPg } from "@prisma/adapter-pg";
+import { betterAuth } from "better-auth";
+import { prismaAdapter } from "better-auth/adapters/prisma";
+import { organization } from "better-auth/plugins/organization";
+import { PrismaClient } from "./generated/prisma/client.js";
+import { claims, orgPolicies } from "./org.policies.js";
+
+const prisma = new PrismaClient({
+	adapter: new PrismaPg({ connectionString: process.env.DATABASE_URL ?? "" }),
+});
+
+export const auth = betterAuth({
+	database: prismaAdapter(prisma, { provider: "postgresql" }),
+	emailAndPassword: { enabled: true },
+	user: {
+		additionalFields: {
+			banned: { type: "boolean", required: false, input: false },
+		},
+	},
+	plugins: [
+		organization({
+			// Invitations are accepted only by a verified email (GHSA-fmh4-wcc4-5jm3, below).
+			requireEmailVerificationOnInvitation: true,
+			// Who may create an organization, and so own it: here, nobody but the server.
+			allowUserToCreateOrganization: false,
+		}),
+		aventaraAccess({
+			policies: { rules: orgPolicies, claims },
+			// A member's role in the session's active organization, and that organization.
+			organization: {
+				claim: "orgRole",
+				organizationClaim: "org",
+				roles: [
+					["owner", "admin"],
+					["admin", "admin"],
+					["member", "member"],
+				],
+			},
+			// The organization claim copied onto the principal, where the rules read it.
+			principal: ({ sub, claims }) => ({
+				id: sub,
+				...(claims.org === undefined ? {} : { org: claims.org }),
+				claims,
+			}),
+			// Every sign-in and every decision: `true` for the `accessAudit` table.
+			audit: { sink: (event) => console.log(event.kind, event.userId) },
+		}),
+	],
+});
+
+/** The framework's `access` option: the policy engine and each request's `me`. */
+export const access = accessOf(auth);
+```
+
+What the plugin does:
+
+- It carries Better Auth's `jwt()` inside it, so `GET /api/auth/token` and `GET /api/auth/jwks` are there, and its
+  tokens carry `sub` and the declared claims only, under your base URL's origin as issuer and audience, for
+  `policies.tokenTtl`. Do not add `jwt()` beside it. It is carried under the Access plugin's id, so a Better Auth
+  plugin that looks `jwt()` up by its own id (`"jwt"`) does not find it.
+- It runs `createAccess`'s own checks on your Better Auth options when Better Auth starts it, and `accessOf(auth)` runs
+  them again when the framework is built: a base URL to fix the issuer, a session cookie that is `sameSite: "none"`
+  only with `trustedOrigins`, a claim read from a field the user cannot set, which Resource is which of Better Auth's
+  tables (`resources.authTables` off the Prisma adapter), no `jwt()` and no second Access plugin. A refusal is the
+  same `AccessError` `createAccess` throws. Refused when Better Auth starts the plugin, Better Auth's own promise
+  rejects, so your server fails at startup with the sentence.
+- `accessOf(auth)` reads requests as `createAccess`'s `state` does: a bearer token checked against the key set, or the
+  session cookie from a site Better Auth trusts. Its engine closes Better Auth's tables and seals their secrets alike.
+  `accessOf(auth).$Infer.Me` is the principal type, and `$Infer.Claims` the claims.
+- `audit` logs what `createAccess`'s does (see [The audit log](#the-audit-log)): sign-ins, refused sign-ins,
+  sign-outs and tokens from Better Auth's hooks, and each decision of `accessOf(auth).policy`.
+- Passwords are hashed with argon2id as under `createAccess` ([Passwords](#passwords)): by default, at the profile
+  `passwords` names, or not at all when your `betterAuth({...})` sets `emailAndPassword.password` (setting both is
+  refused with `ACCESS_OPTIONS_INVALID`). The plugin puts its hook in Better Auth's context when Better Auth starts it.
+- What else `createAccess` adds around Better Auth is not here: profiles, `access.handler`, the standalone host, and
+  the `$access` verbs (`access.client`, the `me` route). You mount `auth.handler` as you already do.
+- Call `aventaraAccess()` once for each `betterAuth({...})`. One plugin in two instances whose options differ (the
+  database, secondary storage, base URL, session cookie or cookie cache) is refused with `ACCESS_PLUGIN_DUPLICATE`.
+
+`aventaraAccess()` inside `createAccess({ betterAuth: { plugins } })` is a type error and is refused with
+`ACCESS_PLUGIN_DUPLICATE`: `createAccess` installs it itself.
+
+### The app as the hub
+
+With `registry: { enabled: true }` the app that runs Better Auth is the registry other services push their files to
+and pull them from (see [The registry and avaccess](#the-registry-and-avaccess)), with no Access server beside it.
+
+```ts
+// src/hub.ts
+import { definePolicies } from "@aventara/access";
+import { accessOf, aventaraAccess } from "@aventara/access/better-auth";
+import { betterAuth } from "better-auth";
+import { Pool } from "pg";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** The hub's own rules, in its own namespace: it pushes them like any other service. */
+const rules = definePolicies(model, { namespace: "campaign" }).grants(({ grant }) => [
+	grant("signedIn", "read", "Campaign"),
+]);
+
+export const auth = betterAuth({
+	database: new Pool({ connectionString: process.env.DATABASE_URL }),
+	emailAndPassword: { enabled: true },
+	plugins: [aventaraAccess({ policies: { rules, claims: {} }, registry: { enabled: true } })],
+});
+
+/** The framework's `access` option, and the registry's operator API as `access.registry`. */
+export const access = accessOf(auth);
+```
+
+- The registry's tables are the plugin's schema, so `npx auth@~1.7.12 migrate` (or `generate` for an ORM's schema)
+  creates them beside Better Auth's, through your adapter. They are the tables `createAccess` uses, so the data moves
+  with you if you switch.
+- Its routes are the plugin's endpoints under Better Auth's base path, served wherever you mount `auth.handler`. A
+  service reaches them only with its namespace's key in `x-access-key`. A session cookie or a token of the hub opens
+  none of them, and a registry key is no session or token.
+- `access.registry` is the operator's API (`createNamespace`, `rotateKey`, `revokeKey`, `pushGuardrails`,
+  `assignResource`, `releaseResource`), typed only when the registry is on. No route opens it: run it in the app's own
+  process, or with `avaccess keys … --server src/hub.ts`, which loads the module and uses its `access` export.
+- A key is checked against the database on every request, so a revoked or rotated key is refused at once by every
+  instance of the app.
+- On any mount, a push's key is checked before Better Auth reads its body: a push with no key, or one that is not the
+  namespace's push key, is refused (`401`/`403`, logged as a push's refusal), and one whose declared length is over
+  2 MiB is answered `413`, its body unread. A push with the right key and no declared length is read as your mount
+  reads bodies; the registry refuses a policies file over 1 MiB with `413` once it is read. `serve` also caps every
+  body before reading it.
+- Better Auth's rate limit counts the registry's routes by client address, which it reads from `X-Forwarded-For`
+  unless `advanced.ipAddress.trustedProxies` names your proxy: a caller that sends its own header gets a fresh bucket
+  each time. Behind a proxy, set `trustedProxies`; on a server facing clients directly, have it set the client's
+  address itself (as `serve` does).
+- The hub's own rules never come from the registry: they are the `policies` you pass in the app's process.
+- Another plugin is refused with `ACCESS_PLUGIN_DUPLICATE` when one of its endpoints is named like one of the
+  registry's, sits at a path under `/access/v1` (a path is read as Better Auth's router reads it: `access/v1/key`
+  is `/access/v1/key`) or has parameters that can match one of the registry's routes (`/:a/v1/key`), or when one of
+  its `middlewares` has a path that can match one there (`/access/v1/**`, `/access/**`, `/**`, `/*/v1/key`). Other plugins' `onRequest` and `hooks` are not checked: every plugin you install
+  runs in your app's process, inside its trust boundary, and sees every request, registry keys included. Install only
+  plugins you trust with them.
+- The hub's tokens are Better Auth's `jwt()` tokens: one org token, with your base URL as issuer and audience. One org
+  token is one trust domain: a token any service sees works at every service that checks the hub's key set, and at
+  the hub itself, until it expires (`policies.tokenTtl`, 15 minutes by default). Access adds no token endpoint and
+  leaves `/token` as Better Auth serves it. A token bound to one service is an opt-in that comes from Better Auth's
+  OAuth provider with resource indicators ([One audience per service](#one-audience-per-service)); use it where
+  services must not trust each other's callers.
+
+### The organization bridge
+
+`organization: { claim, organizationClaim, roles }` puts a member's role in Better Auth's organization plugin into a
+claim, and the organization it holds in into another. Both must be declared in `policies.claims` as `"string"`. When a
+token is issued (and when `me` is read from the session cookie), Access reads the membership of the session's active
+organization from Better Auth's store and maps its role through `roles`, an ordered list of
+`[Better Auth role, value]`: a member with several roles gets the value of the first one listed. No active
+organization, no membership, or a role `roles` does not name gives neither claim. Removing a member, or changing their
+role, changes their next token. The bridge owns both claims: neither the user's field of the same name nor
+`policies.claimsOf` fills them.
+
+An organization role is that organization's. The rules' roles are global, so a rule on the bridged role alone
+would let an admin of one organization act on every organization's rows. Hold every grant on it to the organization:
+copy the organization claim onto the principal (`principal` above), and give each grant
+`where: { organizationId: me.org }`. A principal without the claim matches no such grant.
+
+The member's roles are read as Better Auth reads them: split on `,`, each taken as it is. A stored role with
+whitespace in it (`member, owner`) is one Better Auth does not grant, and the bridge gives nothing for it. A role in
+`roles` is one name, with no comma and no whitespace.
+
+The bridge refuses an organization plugin that lets a member be made otherwise than the app decided:
+
+- `requireEmailVerificationOnInvitation` must be `true` (GHSA-fmh4-wcc4-5jm3, below).
+- `allowUserToCreateOrganization` must be `false`, or a function that decides who may: by default any signed-in user
+  creates an organization and is its owner.
+- With `dynamicAccessControl` on, an organization's admins name roles themselves, so `roles` may map only the plugin's
+  static roles (`owner`, `admin`, `member`, or the keys of its own `roles`).
+
+Each is refused with `ACCESS_OPTIONS_INVALID`. Without `organization()` in your plugins the bridge is refused with
+`ACCESS_RESOURCE_MISSING`. `resources: { members: true }`, with `createAccess` or the plugin, needs
+`requireEmailVerificationOnInvitation: true` too.
+
+Better Auth's advisory [GHSA-fmh4-wcc4-5jm3](https://github.com/better-auth/better-auth/security/advisories/GHSA-fmh4-wcc4-5jm3)
+is why the flag is required. From `better-auth` 1.6.14 on, with Better Auth's own invitation ids, the organization
+plugin lets a signed-in user whose email is not verified accept an invitation sent to that email, unless
+`requireEmailVerificationOnInvitation` is `true`. Someone who signs up with the invited address before its owner, and
+learns the invitation's id (a forwarded email, an admin screen, an invitation list), joins at the invited role, and
+the bridge would hand them its claims. Better Auth has no fixed version: its advisory lists `>= 1.6.14` as affected
+with none. The GitHub advisory database's entry is out of date and still lists `< 1.6.11` only, so `npm audit` reports
+1.7.14 as clean. Access refuses an organization plugin without the flag (`ACCESS_OPTIONS_INVALID`, naming the
+advisory). Only `true` passes.
+
+### The client plugin
+
+`aventaraAccessClient({ api })` adds `authClient.access.can` to Better Auth's client. It asks the framework, not
+Better Auth: one `POST {api}/_access/can` for the whole page, answered by the same engine that decides the real
+requests, one boolean per question.
+
+```ts
+// src/auth-client.ts
+import { aventaraAccessClient } from "@aventara/access/better-auth";
+import { createAuthClient } from "better-auth/client";
+
+export const authClient = createAuthClient({
+	plugins: [aventaraAccessClient({ api: "/api" })],
+});
+
+/** One request for the page: may the user edit this campaign, and add notes? */
+export const pageAnswers = async (campaignId: string) => {
+	const { data, error } = await authClient.access.can([
+		{ resource: "Campaign", action: "update", where: { id: campaignId } },
+		{ resource: "Note", action: "create" },
+	]);
+	if (error !== null) {
+		throw new Error(`can: ${error.status} ${error.code ?? error.statusText}`);
+	}
+	const [editCampaign = false, createNote = false] = data;
+	return { editCampaign, createNote };
+};
+```
+
+- `api` is the framework's API path or URL. A path is read against the auth client's `baseURL`, else the page's
+  address.
+- The request goes through Better Auth's own fetch, so it carries the session cookie (or the bearer token you give
+  Better Auth's client), and the answer is Better Auth's `{ data, error }`. Your client plugins see it as they see
+  Better Auth's own requests: a fetch plugin of theirs (Better Auth's `redirectPlugin` among them) runs on it too.
+- A question with `where` asks about one row, by its unique where. A row the user cannot read answers `false`, exactly
+  as a missing one does. Without `where`, it asks whether the user may run the action on the Resource at all.
+- The questions are asked under the ClientContract's hash: `contractHash` when you give it (your generated client's),
+  else the hash `GET {api}/_contract` serves, read once and read again when the framework answers that it changed.
+- `can` only shapes the page. The real request is still checked.
+- `_access/can` is the framework's route for apps configured with `access` (`@aventara/core` `1.0.0-rc.10` or later).
+
+## The engine alone
+
+You can run the engine without Better Auth: `policies.engine()` builds it from the rules, and `createAccessEngine(file)`
+from a compiled policies file. Hand it to the framework's `policy` option, with a function that reads the principal
+from the request's state. Your host's `state` option (or your MCP `verify`) puts the user there.
+
+```ts
+// src/aventara.config.ts
+import type { AvState } from "@aventara/core";
+import { type Principal, policies } from "./access.policies.js";
+
+declare module "@aventara/core" {
+	interface AvState {
+		user?: Principal;
+	}
+}
+
+export const aventaraConfig = {
+	api: "/api",
+	exposed: true,
+	policy: {
+		engine: policies.engine(),
+		principal: ({ $state }: { readonly $state: AvState }) =>
+			$state.user ?? null,
+	},
+} as const;
+```
+
+Any object with `policy` (an engine) and `state` (`({ headers }) => ({ me })`) also fits the framework's `access`
+option, so an app with its own auth gets the same wiring.
+
+The engine answers:
+
+| Method | Answers |
+|---|---|
+| `can(question)` | Whether the principal may do `action` on `resource`; on `row` when one is given |
+| `scopeOf(question)` | The rows the principal may read, update or delete: `true`, `false`, or an Aventara `where` |
+| `fieldsOf(question)` | The fields usable on every reachable row (`always`), and those usable on some rows only (`perRow`) |
+| `grantsOf(question)` | The update grants that cover a row before it is updated, as opaque keys, for `can`'s `beforeGrants` ([Updates](#updates)) |
+| `explain(question)` | In development, which rules took part in a `can` decision. It throws when `NODE_ENV` is `production`. |
+| `checkBeacons(reader, pins, environment)` | The startup check that the service reaches each foreign owner's database ([The ownership beacon](#the-ownership-beacon)). Await it before serving. |
+| `governed` | The fields governed for reading (`"read"`, `"both"` or the list form), by Resource: out of every default projection |
+| `afterChecks` | The Resources where the row an update leaves is checked, so the host asks `grantsOf` before the write |
+| `paths` | Every relation path and operator each rule filters on, by rule id |
+| `unheld` | The Resources the rules read as foreign: Aventara holds no written reference to them to the caller's read scope |
+
+A deny on a field that may be NULL lets the NULL rows through: `can` reads `topic = 'off-the-record'` as false on a
+row whose `topic` is NULL, so the deny does not apply. `scopeOf` keeps the same rows in a database, which reads that
+comparison as unknown: on a nullable field it writes the deny's negation as
+`{ OR: [{ NOT: { topic: { equals: "off-the-record" } } }, { topic: { equals: null } }] }`. A field that is not
+nullable keeps the plain `NOT`. Which fields are nullable comes from the schema, through the policies file; a to-one
+relation is nullable when its reference field is, and a deny through it lets the rows with no related row through
+(`{ replyToId: { equals: null } }`). Access assumes the database enforces each reference: under Prisma's `relationMode = "prisma"`, which creates no foreign keys, a reference to a row that no longer exists makes `scopeOf` and `can` disagree on that row.
+
+A `where` that matches no row is written `{ OR: [] }`, an empty `OR`: Aventara's `where` has no `false`, and every
+ORM translator reads the empty `OR` as no row (Prisma does). A `scopeOf` that allows nothing answers `false` itself;
+`{ OR: [] }` appears inside a `where`, and where a generated client's Prisma functions turn `false` into a Prisma
+`where`.
+
+Each question states `principal`, `origin` and `resource`. `can` adds `action` (and, for a row, `row` and `exists`),
+`scopeOf` adds `action` (`read`, `update` or `delete`), and `fieldsOf` adds what the fields are for:
+
+```ts
+// scripts/fields.read.ts
+import { type Principal, policies } from "../src/access.policies.js";
+
+const engine = policies.engine();
+const pat: Principal = { id: "pat", claims: {} };
+
+// The fields pat may read on User.
+console.log(
+	engine.fieldsOf({ principal: pat, origin: "client", resource: "User", access: "read" }),
+);
+// The fields pat may set when she updates a Note.
+console.log(
+	engine.fieldsOf({
+		principal: pat,
+		origin: "client",
+		resource: "Note",
+		access: "write",
+		action: "update",
+	}),
+);
+```
+
+`access` is `"read"`, or `"write"` with an optional `action` (`"create"` or `"update"`; both when it is left out). A
+question without `access`, or with an `action` that does not fit it, is refused with `ACCESS_QUESTION_INVALID`.
+
+`policies.engine({ guardrails, lock, requireLock })` and `createAccessEngine(file, { guardrails, lock, requireLock })`
+take the org's guardrails and the lock (below). Any other option is refused. The engine runs from its own frozen copy of
+the file: changing the object you handed it afterwards changes nothing.
+
+## The audit log
+
+`audit: true` writes each event (sign-ins, refused sign-ins, sign-outs, tokens issued, decisions) to the `accessAudit`
+table. `npx auth@~1.7.12 generate --yes` writes it
+into an ORM's schema (Prisma: `model AccessAudit`), and `npx auth@~1.7.12 migrate` creates it, beside Better Auth's
+tables. Better Auth refuses to start while the table is missing.
+
+Read the log through your app's ORM. With Prisma:
+`prisma.accessAudit.findMany({ orderBy: { at: "desc" } })`. It is not reachable through the framework's API: Access's
+own tables stay closed to every request, whatever `resources` says. A read of `AccessAudit` is refused `403 A4002`,
+and the audit log names the rule `deny:better-auth:AccessAudit`.
+
+`audit: { sink }` hands each event to your function instead, and declares no table:
+
+```ts
+// src/audit.sink.ts
+import type { AccessAuditEvent } from "@aventara/access/auth";
+
+/** Logs every refusal with the rule that refused it. */
+export const auditSink = (event: AccessAuditEvent): void => {
+	if (event.kind === "decision" && !event.allowed) {
+		console.warn(
+			`${event.userId ?? "anonymous"} refused ${event.action} on ${event.resource}: ${event.reason}`,
+		);
+	}
+};
+```
+
+Then `audit: { sink: auditSink }`. Each event is one of:
+
+```text
+{ at, kind: "sign-in", userId, origin, impersonatedBy? }
+{ at, kind: "sign-in-failed", userId: null, route, reason, target?, deviceId?, origin, suppressed?, windowStart?, windowEnd? }
+{ at, kind: "sign-out", userId, origin, impersonatedBy? }
+{ at, kind: "token", userId, origin, impersonatedBy? }
+{ at, kind: "kiosk-switch", userId, previousUserId, deviceId, origin }
+{ at, kind: "kiosk-lock", userId, deviceId, reason, origin }
+{ at, kind: "kiosk-device", userId, deviceId, reason, origin }
+{ at, kind: "kiosk-pin", userId, origin }
+{ at, kind: "decision", userId, resource, action, allowed, reason, origin, suppressed?, windowStart?, windowEnd? }
+```
+
+- A **sign-in** is a session Better Auth created: a sign-in, or a sign-up that signs the user in. Its `origin` is
+  `client` through Access's routes and `application` when your server calls Better Auth's API. `impersonatedBy` is the
+  admin's user id when the session is an impersonation (Better Auth's `admin()` plugin).
+- A **sign-in-failed** is a route that starts a session refusing the caller: `route` is Better Auth's endpoint
+  (`/sign-in/email`) and `reason` the code it refused with (`INVALID_EMAIL_OR_PASSWORD`). `target` is an HMAC-SHA-256
+  of the identifier the route reads, as it reads it, keyed by Better Auth's secret: the email on `/sign-in/email` and
+  `/sign-in/email-otp` (lower-cased), the username on `/sign-in/username` (normalized by the `username()` plugin's
+  `usernameNormalization`, lower-cased by default), the phone number on `/sign-in/phone-number` (as given). Every
+  attempt on one identifier has the same target, whatever else the body carries, and without the secret it cannot be
+  turned back into the identifier or checked against a guess. Other routes' refusals have no target. The identifier
+  itself, and anything else the caller sent, is never kept. A server call of `signIn`, `signUp` or `resetPassword`
+  that the rate limit refuses is one too, with reason `rate-limited`, the verb's route and its target.
+- A **sign-out** is a session ended through `/sign-out`.
+- The **kiosk** events are the kiosk profile's ([The kiosk profile](#the-kiosk-profile)). A failed PIN is a
+  **sign-in-failed** on `/kiosk/switch-user`, with the device's `deviceId` and, as its `target`, the HMAC of the user
+  id it named. With `audit: true` on the kiosk profile, the table has two more columns, `deviceId` and
+  `previousUserId`.
+- A **token** is a JWT issued for a session by `GET /token`. The `set-auth-jwt` header of `/get-session` is not
+  logged: a page asks for its session on every load.
+- A **decision** is a `can` answer. A request's admission is one event, allowed or refused, however many rows it reads
+  or writes. A row question (the row a create inserts, or an update leaves) adds an event only when the rules refuse
+  that row. `scopeOf`, `fieldsOf` and `explain` log nothing.
+- `reason` names the deciding rule: `grant:<id>`, `deny:<id>`, or `no grant`. A guardrail reads `deny:guardrail:<id>`.
+- `userId` is the `sub` of the token or session the principal came from, or `null` for an anonymous caller.
+- Anonymous refusals (a refused decision with no `userId`, and every refused sign-in) are logged once a minute for
+  each origin and reason (a refused sign-in, for each route and `target` too). The first is logged; the repeats in the
+  minute are counted, and when the minute closes the count is logged as a summary: the first event's fields with
+  `suppressed` (the count), `windowStart` and `windowEnd`. The summary is written on the next event of any kind after
+  the minute, or by a timer at its end. A sign-in writes its target's summary first, so a guessed password shows after
+  its failures. A flood of anonymous requests writes two rows a minute, not one per request. At most 10,000 windows
+  are open at once: past that, a refusal that would open another closes the oldest early (its count logged, with
+  `windowEnd` then) and opens its own, so every target keeps its own rows.
+- An event holds no token, password, cookie, key or header.
+- The request waits for the write or the sink. A sink that throws, or a write that fails, does not fail the request:
+  Better Auth's logger warns and the request goes on. Queue slow work in the sink.
+
+## Users and roles as Resources
+
+Better Auth's tables are in your schema, so the framework sees them as Resources. Access runs built-in rules over every
+one of them. These rules only narrow. `resources` decides which tables your rules may open:
+
+| Key | Opens | Writes through Aventara |
+|---|---|---|
+| `users: true` | `user`, `session` and `account` (session and account read only) | on `user`, an update of `role`, by a grant that names it |
+| `members: true` | the organization plugin's `member`, and its `organization` (read only) | on `member`, a create, an update of `role` by a grant that names it, and a delete |
+
+- Every other Better Auth table stays closed: `verification`, `jwks`, the organization plugin's `invitation`,
+  `twoFactor`, `deviceCode`, and Access's own tables. A key that is off leaves its tables closed too.
+- An opened table is read as your rules grant. Writes are limited because a write through Aventara skips Better Auth's
+  hooks, its cookie cache and its secondary storage. Change a name or an email through Better Auth's API.
+- `role` is a claim, so Access governs `user`'s `role` as `"write"`: an update grant sets it only when it names it.
+  To let an admin set roles, add `.govern("User", { role: "write" })` to your rules, which lets a grant name the
+  field, 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`, `member`'s `role` is governed the same way: a create or update grant sets it only when it
+  names it. Name it only in an organization admin role's grant, held to `where: { organizationId: me.org }`.
+- `members: true` needs Better Auth's `organization()` plugin in `betterAuth.plugins`, with
+  `requireEmailVerificationOnInvitation: true`: your rules trust its memberships, and without the flag a user whose
+  email is not verified can accept an invitation sent to that address
+  ([GHSA-fmh4-wcc4-5jm3](#the-organization-bridge)). Without it, `createAccess` refuses with `ACCESS_OPTIONS_INVALID`.
+- `explain` and the audit log name a built-in deny `better-auth:<Resource>` (a closed table) or
+  `better-auth:<Resource>/<actions>` (a write an opened table never takes).
+
+Secret columns are sealed. No grant opens them, on any table, so a request that selects, filters or sorts by one is
+refused:
+
+| Table | Sealed columns |
+|---|---|
+| `account` | `password`, `accessToken`, `refreshToken`, `idToken` |
+| `session` | `token` |
+| `verification` | `identifier`, `value` |
+| `jwks` | `privateKey` |
+| `twoFactor` | `secret`, `backupCodes` |
+| `deviceCode` | `deviceCode`, `userCode` |
+| `accessKey` | `keyHash` |
+
+Exempt these columns from your Contracts, or govern them, so a read that names no field leaves them out instead of
+being refused.
+
+Access must know which Resource is which of Better Auth's tables, or it could not keep them closed and their secrets
+sealed:
+
+- With Better Auth on its Prisma adapter (`prismaAdapter`), Access finds each table by the Prisma model the adapter
+  reads it through: the model whose client delegate is the table's name (your `modelName`, or the table's own, plus
+  `s` with `usePlural`). That is exact, whatever the model is called or mapped to (`model User`, `model user`,
+  `model Users`), so there is nothing to configure. `resources.authTables` is refused there. A table whose delegate no
+  Resource answers to, while the schema has one that differs only in case or a plural `s` (an adapter without
+  `usePlural` on a plural schema), is refused: the schema and the adapter disagree.
+- With Better Auth on any other adapter (its built-in Kysely on a `pg` Pool or SQLite, Drizzle, MongoDB, your own),
+  nothing ties a table to a Resource by name: a Prisma schema can give a table any model name with `@@map`, and its
+  columns any field names with `@map`. So you name them: `resources.authTables` maps every table Better Auth is built
+  with (its plugins' and Access's own included) to its Resource, or to `null` when the rules' schema does not have it.
+  Without it, or with a table missing from it, `createAccess` refuses with `ACCESS_OPTIONS_INVALID` and lists the
+  tables. A rules' schema with no Resource at all (a registry-only server) needs no map.
+
+```ts
+// src/auth-tables.ts
+/**
+ * Better Auth on a pg Pool, its tables mapped to models of the app's own naming:
+ * `resources: { users: true, authTables }`. Better Auth here has `user`, `session`,
+ * `account`, `verification` and `jwks` (and `twoFactor` with that plugin, and so on).
+ */
+export const authTables = {
+	user: "AuthUser",
+	session: "AuthSession",
+	account: "AuthAccount",
+	verification: null,
+	jwks: null,
+};
+```
+
+`null` means "this table is not in the rules' schema", never "closed": a table that is in the schema is named, and
+then closed, or opened by its key, as any other. The map is held to the schema, and refused with
+`ACCESS_OPTIONS_INVALID` where they disagree:
+
+- a table's Resource must exist, be no other table's, and have every column of the table under the name Better Auth's
+  `fieldName` gives it (an `@map` that renames one is refused: Access could not seal what it cannot find);
+- a table mapped to `null` must not be in the schema: a Resource the map leaves unnamed that has every column of it,
+  or one of its secret columns beside another of its columns (a model that keeps only some, `{ token, userId }`), is
+  refused, naming that Resource. A table of your own with a lone `token` column is yours.
+
+A table a key opens must have each of its secret columns under Better Auth's field name for it, on either adapter.
+
+These checks run when `access.policy` is first read, which is when the framework is built. A key whose tables Better
+Auth lacks, or that the rules' schema lacks, is refused with `ACCESS_RESOURCE_MISSING`: add the plugin, or run
+`npx auth@~1.7.12 generate --yes` and regenerate the model. A grant on a closed table, or of a write the table never takes,
+is refused with `ACCESS_OPTIONS_INVALID`. The instance itself still builds, so `npx auth@~1.7.12 generate --yes` can load
+your configuration before the schema has the tables.
+
+## The registry and avaccess
+
+When several services share one Access server, the registry holds each namespace's policies file and the org's
+guardrails. Each service pushes its own file and pulls it back with the guardrails, and builds never touch the network.
+
+### The server
+
+Turn the registry on in the server's configuration. A server that only runs the registry needs no `policies`: its
+engine then denies every question, and its tokens carry `sub` alone.
+
+```ts
+// access.config.ts
+import { createAccess } from "@aventara/access/auth";
+import { Pool } from "pg";
+
+export const access = createAccess({
+	betterAuth: {
+		database: new Pool({ connectionString: process.env.DATABASE_URL }),
+	},
+	registry: { enabled: true },
+});
+
+export default access;
+```
+
+This server signs in no one: it has no `emailAndPassword`, so nobody can sign up on it. Add the sign-in methods its
+users need, and see [Sign up and sign in](#sign-up-and-sign-in) before you turn on open sign-up.
+
+The registry's tables (`accessNamespace`, `accessKey`, `accessPolicyRevision`, `accessGuardrailRevision`, `accessHead`,
+`accessPushLog`, `accessResourceOwner`) are Better Auth plugin tables, created by Better Auth's migration or by
+`npx auth@~1.7.12 generate --yes` for an ORM's schema. `access.handler` serves the registry's routes under Better Auth's base path, so every mount carries them:
+
+| Route | Does |
+|---|---|
+| `GET /access/v1/namespaces/:ns` | The namespace |
+| `GET …/:ns/revisions` | Its revisions |
+| `POST …/:ns/revisions` | Push a policies file |
+| `GET …/:ns/revisions/:hash` | One revision |
+| `GET …/:ns/head` | The current revision |
+| `GET …/:ns/guardrails` | The org's guardrails |
+| `GET …/:ns/foreign/:owner` | What `:ns` reads of `:owner` as foreign: `:owner`'s beacon hash, and its entry of each Resource `?resources=A,B` names |
+| `GET /access/v1/key` | The namespace and kind of the key sent |
+
+A service sends its key in the `x-access-key` header. With the registry off, `/access/v1/*` answers `404`. One org per
+server. A revision's `:hash` is `sha256:` and 64 lower-case hex digits; anything else answers `404`.
+
+The push log (`accessPushLog`) records every push made with a key the registry has, accepted or refused, with the key's
+id. A push with no key, or a key that is not this registry's, adds no row of its own: those are counted in one row per
+namespace per minute, its `count`.
+
+### Keys
+
+Each namespace has a push key and a read-only pull key. The registry stores only their SHA-256 hashes. The operator
+issues them from the server's own module, in their own process, never over HTTP:
+
+```sh
+avaccess keys issue campaign --server access.config.ts
+avaccess keys rotate campaign push --server access.config.ts
+avaccess keys revoke campaign pull --server access.config.ts
+```
+
+`avaccess keys` loads that module in its own process and reads no `.env`. Give it the environment the server runs with:
+`DATABASE_URL` (or whatever your database client reads), `BETTER_AUTH_SECRET`, and `BETTER_AUTH_URL`, the server's
+base URL, which Better Auth cannot infer outside a request.
+
+`issue` creates the namespace and prints both keys once. `rotate` prints the new key once. No other command prints a
+key. `--server` names the module that holds the `createAccess` instance (its default export, or `access`), or, for a
+Better Auth app that is the hub, `accessOf(auth)` ([The app as the hub](#the-app-as-the-hub)). The same
+calls are on `access.registry`: `createNamespace(name)`, `rotateKey(namespace, kind)`, `revokeKey(namespace, kind)`
+and `pushGuardrails(file)`. A namespace has one live key of each kind: two rotations at the same moment leave one.
+
+A push key pushes and reads its own namespace. A pull key only reads it. A wrong, revoked or rotated-out key, a pull key
+that pushes, or another namespace's key is refused with `ACCESS_KEY_REFUSED`. Another namespace's key gets the same
+answer as a namespace the registry does not have (`401`), so a key tells its holder nothing about other namespaces.
+
+### Who owns a Resource
+
+A namespace owns the Resources its file names as its own, and only the owner grants, denies or governs fields on them.
+The registry keeps one owner per Resource in `accessResourceOwner`, and checks and claims ownership in the push's own
+transaction, so two pushes at the same moment cannot both claim one.
+
+`registry.ownership` says how a Resource gets its owner:
+
+- `"first-push"` (the default): the first push that names it as its own, unless the operator assigned it first. A
+  Resource claimed this way is free again once the namespace's head no longer names it.
+- `"assigned"`: the operator alone. A push that names an unassigned Resource as its own is refused.
+
+The operator assigns and releases Resources on the server's instance:
+
+```ts
+// scripts/owners.assign.ts
+import access from "../access.config.js";
+
+await access.registry.assignResource("Invoice", "billing");
+await access.registry.releaseResource("Draft");
+```
+
+`assignResource(resource, namespace)` gives the Resource to the namespace, whoever named it first: from then on
+another namespace's push that names it as its own is refused. `releaseResource(resource)` takes it from its owner. A
+refusal names the Resource and the rule, never the namespace that owns it.
+
+### A service's commands
+
+The registry is `--registry <url>` or `AVACCESS_REGISTRY_URL`: the Access server's URL. With no path, Better Auth's
+`/api/auth` is added. The key is `AVACCESS_KEY`, never a flag. The URL is `https:`; `http:` is taken only on a loopback
+address (`localhost`, `127.0.0.0/8`, `[::1]`), since the key travels in a header. The CLI follows no redirect: a `3xx`
+answer stops it (exit `2`), and the key goes to no other address.
+
+| Command | Does |
+|---|---|
+| `avaccess push <rules> [--beacon <module>]` | Pushes the namespace's policies file: a `.json` file, or the module that holds the rules (default export, or `rules`), TypeScript included. `--beacon` sends the beacons too ([The ownership beacon](#the-ownership-beacon)). |
+| `avaccess pull [--namespace <ns>] [--out <dir>] [--foreign <ns>:<Resource>,…] [--beacon <module>] [--env <env>]` | Writes the namespace's current file to `access/<ns>.policies.json`, and the org's guardrails to `access/guardrails.json` when the registry has guardrails, and pins their hashes in `avAccess.lock.json` |
+| `avaccess verify [--env <env>]` | Holds the pulled files to the lock, offline. A file edited by hand fails with `ACCESS_LOCK_MISMATCH`. It holds every `avAccess.beacons.<env>.json` in the project to the rules too, and with `--env` (or `AVACCESS_ENV`) fails when that environment's file is missing. |
+| `avaccess status` | Says whether the lock is behind the registry's current revisions, and exits `1` when it is. Run it in CI. |
+| `avaccess diff [<from> [<to>]] [--namespace <ns>]` | Names the rules that changed between two revisions: `lock`, `head`, a hash, or its first seven or more hex digits. The default, `lock` to `head`, is what a pull would bring. The namespace is `--namespace`, else the lock's. |
+
+Exit codes: `0` done, `1` the check failed or the registry refused, `2` the command could not run.
+
+- `push` takes the namespace from the file. The registry stores each file once, in its canonical form, under its hash,
+  and never updates it. Pushing a file the registry already has moves the head back to it.
+- At push, a namespace may name as its own only Resources no other namespace owns, and its rules may grant, deny and
+  govern only on those (`ACCESS_OWNERSHIP`, see [Who owns a Resource](#who-owns-a-resource)). A file the engine would
+  refuse is refused too (`ACCESS_POLICIES_INVALID`), and so is a file over 1 MiB (`413`).
+- `pull` takes the namespace from `--namespace`, else the lock, else the key. It hashes each file again before it
+  writes it, and refuses a file of another namespace than the one asked for. When the lock pins the org's guardrails
+  and the registry serves none, the pull is refused and writes nothing: it would drop the org's denies. Commit the two
+  files and the lock.
+- A pull trusts the registry it reaches: a file is held to its hash, not to who wrote it. Signed revisions are not
+  built yet, so reach the registry over `https:` only.
+- `pull` and `generate` write only inside the project: a path through a symbolic link that leads out of it is refused
+  (exit `2`). A lock's paths are relative, `/`-separated, with no `..`, drive letter, backslash or control character.
+- Text the registry sends (a refusal's code and message) is printed without control characters.
+
+`avAccess.lock.json` pins content, not a registry:
+
+```json
+{
+  "format": "aventara-access/lock@1",
+  "namespace": "campaign",
+  "policies": { "path": "access/campaign.policies.json", "hash": "sha256:…" },
+  "guardrails": { "path": "access/guardrails.json", "hash": "sha256:…" }
+}
+```
+
+`guardrails` is `null` when the registry has none. Put `avaccess verify` first in `aventara:prepare`, so the build
+stops before anything is generated from a changed file:
+
+```json
+{
+  "scripts": {
+    "aventara:prepare": "avaccess verify && aventara-prisma7-generate … && aventara-build"
+  }
+}
+```
+
+In a Next.js app, put it before `aventara-build` the same way.
+
+### The lock at startup
+
+Read the lock and the pulled files as JSON and hand them to the instance:
+
+```ts
+// src/access.pulled.ts
+import { readFileSync } from "node:fs";
+import type { AccessGuardrailsJson, AccessLock } from "@aventara/access";
+
+/** A file `avaccess pull` wrote, from the project's root. */
+const pulled = (path: string): unknown =>
+	JSON.parse(readFileSync(path, "utf8"));
+
+/** avAccess.lock.json: the namespace, and the hash of each pulled file. */
+export const lock = pulled("avAccess.lock.json") as AccessLock;
+
+/** The org's guardrails, as the registry serves them to this namespace. */
+export const guardrails = pulled(
+	"access/guardrails.json",
+) as AccessGuardrailsJson;
+```
+
+Then `policies: { rules: policies, claims, guardrails, lock }`. The instance refuses to start
+(`ACCESS_LOCK_MISMATCH`) unless the guardrails hash to the lock's pin and are given exactly when it pins some, and the
+rules' namespace is the lock's. A policies file you hand over (not the typed rules, which are your own source) must hash
+to its own pin. The engine options take the same `lock`: `createAccessEngine(file, { guardrails, lock })`.
+
+The lock is optional, so a project without a registry runs without one. In production, set
+`policies: { …, lock, requireLock: true }` (or `createAccessEngine(file, { lock, requireLock: true })`): the instance
+then refuses to start without a lock (`ACCESS_LOCK_MISMATCH`), so a deploy that lost `avAccess.lock.json` stops
+instead of running files nothing pins. With `requireLock`, typed rules are held to the lock's policies hash too: a
+lock that pins other rules is refused.
+
+A pulled file imported as JSON fits these options as it is: TypeScript widens a JSON import's literals, so they take
+the file's outline (`AccessPoliciesJson`, `AccessGuardrailsJson`), and the engine checks the rest when it is built.
+
+### The ownership beacon
+
+A namespace can read another namespace's Resources in conditions (`{ foreign: "<owner>" }`) only while both services
+run on one database: the facts must come from the owner's own tables, not from a copy. The beacon proves it. Each
+service writes one row in `_aventara_beacon` (`namespace`, `value`, `createdAt`) through its own data layer, with a
+random value (`avb_…`), once. Access names no ORM and writes no SQL: you hand it an `AccessBeaconStore` over your
+data layer, a module that exports `beacon` (a generated client's `access.prismaBeacon(prisma)` is one, over a Prisma
+model of the table). The table holds one row per namespace: in a deployment with a schema per service each service's
+schema holds its own row, and in one with a single schema one table holds them all.
+
+- **At push.** `avaccess push <rules> --beacon <module>` sends the namespace's own beacon with the file, writing
+  its row the first time, and for each namespace the file reads as foreign, that namespace's row as this service's
+  connection reads it. The registry keeps each beacon's hash bound to its namespace (`sha256` of
+  `<namespace>:<value>`), never the value: a value pushed under one namespace never matches or blocks another's.
+  Only a namespace's own push registers or replaces its beacon; a reader only refers to the owner's. A file that
+  reads another namespace is stored only when the push carries that namespace's beacon and it is the one that
+  namespace pushed; otherwise the push is refused with `ACCESS_FOREIGN_CROSS_DATABASE`, which suggests carrying the
+  fact in a JWT claim instead. A beacon a namespace replaced never comes back (`ACCESS_BEACON_MISMATCH`, `409`). A
+  push never adopts a row it did not write: a row the registry holds no hash of, or another hash, is refused
+  (`ACCESS_BEACON_MISMATCH`) until an operator verifies it or deletes it, and the next push writes a new one.
+- **At pull.** First push a file that marks the Resources it reads as the owner's (`{ foreign: "campaign" }` on your
+  model's entries): the registry serves another namespace's facts only for what your current file reads as foreign.
+  Then `avaccess pull --foreign campaign:Campaign,Member --beacon <module> --env <environment>` brings the owner's
+  schema entries of those Resources into `access/foreign.json` (pinned in the lock, checked by `verify`), and
+  `avaccess schema` adds them to your model, marked as the owner's. Every pull of rules that read another namespace
+  reads that namespace's row through `--beacon` and holds it to the hash the namespace pushed; on another database it
+  is refused and nothing is written. The hashes go to `avAccess.beacons.<environment>.json`, one file per environment
+  (`--env`, or `AVACCESS_ENV`), never into the lock: a database's beacon is its own, and the lock holds against any
+  environment's registry.
+- **At startup.** An engine whose rules read another namespace decides nothing until
+  `await access.policy.checkBeacons(beacon, pins, environment)` (or `engine.checkBeacons`) has passed, with or without
+  a lock: it holds the pins to `environment`, reads each owner's row through your connection and holds it to its pin.
+  A service started against another database refuses with `ACCESS_BEACON_MISMATCH`, and a failed check latches: the
+  engine stays shut until the process restarts. Await it before the service takes requests. A generated client does
+  the same with `access.checkBeacons(reader, pins, environment)`, and throws an error with the same `code`.
+
+In a single shared schema, every service with write access to `_aventara_beacon` can overwrite or delete another
+namespace's row. It cannot make a reader pass (the registry holds the owner's hash, bound to the owner), but the
+readers then refuse at startup until the owner's row is restored and pushed again. The check fails closed; where the
+database can, give each service's role write access to its own row only.
+
+```ts
+// src/access.beacons.ts
+import { readFileSync } from "node:fs";
+import type { AccessBeaconPins, AccessBeaconStore } from "@aventara/access";
+
+/** Your data layer's view of _aventara_beacon, one row per namespace. */
+declare const beaconRows: {
+	find(namespace: string): Promise<{ readonly value: string } | null>;
+	insert(row: { readonly namespace: string; readonly value: string }): Promise<void>;
+};
+
+/** What `avaccess push --beacon src/access.beacons.ts` loads, and what the startup check reads through. */
+export const beacon: AccessBeaconStore = {
+	read: async (namespace) => (await beaconRows.find(namespace))?.value ?? null,
+	create: (namespace, value) => beaconRows.insert({ namespace, value }),
+};
+
+/** The environment this process runs in: required, never guessed. */
+export const environment = ((): string => {
+	const named = process.env.AVACCESS_ENV;
+	if (named === undefined || !/^[a-z][a-z0-9_-]{0,62}$/.test(named)) {
+		throw new Error(
+			"AVACCESS_ENV names the environment this service runs in (such as production); its beacon pins are avAccess.beacons.<environment>.json",
+		);
+	}
+	return named;
+})();
+
+/** This environment's pins, as `avaccess pull --env <environment>` wrote them. */
+export const beaconPins = JSON.parse(
+	readFileSync(`avAccess.beacons.${environment}.json`, "utf8"),
+) as AccessBeaconPins;
+```
+
+Then, before the service takes requests: `await access.policy.checkBeacons(beacon, beaconPins, environment)`.
+
+With the registry on, an Access server whose rules name a namespace keeps its own beacon through Better Auth's
+adapter: its migration creates the `aventaraBeacon` table (Prisma model `AventaraBeacon`, as Better Auth's generator
+writes it), and `access.beacon` is the store. The auth-tables guard keeps every beacon table closed, the Access
+server's and any Resource named like one (`AventaraBeacon`, `_aventara_beacon`), with its `value` sealed.
+
+## Guardrails
+
+The org's guardrails are deny-only rules that every namespace's engine adds on top of its own. They only narrow. The
+operator writes them with `defineGuardrails`, which has `.denies()` and no `.grants()`:
+
+```ts
+// src/org.guardrails.ts
+import { defineGuardrails } from "@aventara/access";
+
+export const guardrails = defineGuardrails({ claims: { suspended: "boolean" } })
+	.denies(({ deny }) => [
+		// A suspended user reads, and writes nothing, in every service.
+		deny(["create", "update", "delete"], "*", {
+			name: "suspended-read-only",
+			if: { claims: { suspended: true } },
+		}),
+	])
+	.contract();
+```
+
+- `deny(actions, resources, options?)` names whole Resources: `"*"`, or by namespace, `{ campaign: ["Note"] }` or
+  `{ chat: "*" }`.
+- A guardrail's options are a `name` and `if: { claims, origin }`. A `grant`, or a row condition (`where`, `after`), is
+  a type error.
+- `.contract()` compiles them to an `aventara-access/guardrails@1` file.
+
+Push them through the server's own instance. No namespace key can push them:
+
+```ts
+// scripts/guardrails.push.ts
+import access from "../access.config.js";
+import { guardrails } from "../src/org.guardrails.js";
+
+const pushed = await access.registry.pushGuardrails(guardrails);
+console.log(pushed);
+```
+
+Each service then gets them with `avaccess pull` and passes them as `policies.guardrails` (or the engine's
+`guardrails` option). Each guardrail becomes a deny on the Resources it reaches: every one for `"*"`, and the file's own
+namespace's list, where `{ chat: "*" }` is every Resource the file owns. A Resource the file does not list has no
+grant at all (a grant on `"*"` reaches only the file's own Resources), so nothing there is left for a guardrail to
+take away. Another namespace's list is left alone. A Resource in the file's own list that the file lacks, or
+reads as foreign, is refused, and so is a namespaced list when the file names no namespace. `createAccess` refuses
+guardrails that compare a claim `policies.claims` does not declare (`ACCESS_CLAIMS_UNDECLARED`), so declare
+`suspended` there too.
+
+A guardrail's `if` fails closed on a claim the token lacks, as a deny's does: the guardrail applies, whatever value it
+compares with. Every service that declares `suspended` issues it in each token, `false` when unset, so
+`if: { claims: { suspended: true } }` leaves alone a user who is not suspended and applies to a token without
+`suspended`, such as one a service issued before it declared the claim; `if: { claims: { tier: "trial" } }` applies to
+a user with no `tier`. Write a guardrail so that a missing claim is the safe case.
+
+Guardrails reach a service at build time, with a pull and a deploy. A change that must take effect sooner travels as
+a claim: a suspended user gets the claim with their next token, within `policies.tokenTtl`.
+
+## Services not on Aventara
+
+A service that does not run on Aventara decides with a generated client: two TypeScript files that import nothing
+else. `src/generated/avAccess.ts` is the one the service imports. It exports `access` and the client's types
+(`ResourceName`, `ResourceRows`, `ResourceFields`, `QuestionOf`, `CanQuestionOf`, `GrantsQuestionOf`,
+`ScopeQuestionOf`, `FieldsQuestionOf`, and with `--orm prisma7` only, `PrismaClientOf`, `PrismaSelectOf`,
+`PrismaWhere` and `PrismaBeaconClient`), and holds
+the pulled policies file, the denies
+the org's guardrails add to it and the namespace's Resource types. `avAccess.internal.ts` beside it holds the copy of
+Access's decisions it imports; nothing in it is the client's API. `avAccess.ts` names it with the extension the
+project's `tsconfig.json` asks for, as Prisma 7's `prisma-client` does: `.js` under `nodenext`, none under
+`moduleResolution: "bundler"` or `module: "commonjs"`, `.ts` with `allowImportingTsExtensions` or
+`rewriteRelativeImportExtensions`. The tsconfig is found and read with `get-tsconfig`, as Prisma 7 and the
+framework's `avclient` read it: the nearest one above the generated file (`extends` followed; in a solution-style
+root such as Vite's, the referenced project that includes the file), or the one `--tsconfig <file>` names. A project with no tsconfig is refused, and nothing is written: the client is TypeScript, and JavaScript projects
+are not supported yet. The service needs no Access version at runtime.
+
+`--orm` names the translator. For `generate` it is optional and defaults to `none`: a neutral client whose `access`
+has `can`, `grantsOf`, `scopeOf`, `fieldsOf` and `checkBeacons` only, answering in Aventara's `where`, with the types
+`ResourceName`, `ResourceRows`, `ResourceFields`, `QuestionOf`, `CanQuestionOf`, `GrantsQuestionOf`, `ScopeQuestionOf`
+and `FieldsQuestionOf`, and no ORM's name anywhere. `--orm prisma7` adds the Prisma 7 translator (`prismaWhere`,
+`readable`, `prismaExists`, `prismaBeacon` and the Prisma types). The generated file's banner always spells `--orm` out.
+`--out <file>` names the client's file, a `.ts` file inside the project (default `src/generated/avAccess.ts`); its
+internal file is written beside it, `<name>.internal.ts`. `schema` requires `--orm`: `prisma7` is the first.
+
+```sh
+avaccess schema --orm prisma7      # prisma/schema.prisma → src/generated/avAccess.schema.ts
+avaccess push src/access.rules.ts  # with the namespace's push key
+avaccess pull                      # with its pull key
+avaccess generate --orm prisma7    # the pulled files → src/generated/avAccess.ts and avAccess.internal.ts
+```
+
+`avaccess schema` reads the service's Prisma schema (`--schema`, default `prisma/schema.prisma`; a folder of `.prisma`
+files reads as one) into a module that exports `model`. It leaves out, and lists, what it cannot model: an
+`Unsupported(...)` column, a composite `type`, a `view`, an `@ignore`d field or model. `--out <file>` writes it to
+another `.ts` file inside the project (default `src/generated/avAccess.schema.ts`). Author the rules against it:
+
+```ts
+// src/access.rules.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/avAccess.schema.js";
+
+export const rules = definePolicies(model, { namespace: "chat" })
+	.principal<{ profileId: string }>()
+	.govern("Message", ["body"])
+	.grants(({ grant, me }) => [
+		grant("anyone", "read", "Room", { where: { kind: "PUBLIC" } }),
+		grant("signedIn", "read", "Message", {
+			where: { authorId: me.profileId },
+			fields: ["Message.body"],
+		}),
+	]);
+```
+
+`avaccess generate` runs the same check as `avaccess verify` first: a pulled file edited by hand is refused and nothing
+is written. Regenerate after each pull, for example in the service's `postinstall`:
+`avaccess verify && avaccess generate --orm prisma7`. The same pulled files, translator and Access version give the
+same bytes. Never edit the generated files.
+
+The client's `access` answers as the engine does, plus the Prisma 7 translator:
+
+```ts
+// src/messages.read.ts
+import { access } from "./generated/avAccess.js";
+import type { PrismaClient } from "./generated/prisma/client.js";
+
+/** The service's principal: the profile its token maps to, and the token's claims. */
+export type Principal = { profileId: string; claims: { role?: string } };
+
+/** A room's messages this principal may read, with the fields it sees on every row. */
+export async function readMessages(
+	prisma: PrismaClient,
+	principal: Principal | null,
+	roomId: string,
+) {
+	const question = {
+		principal,
+		origin: "client",
+		resource: "Message",
+	} as const;
+	const scope = access.scopeOf({ ...question, action: "read" });
+	if (scope === false) {
+		return null; // refused
+	}
+	return prisma.message.findMany({
+		where: { AND: [{ roomId }, access.prismaWhere("Message", scope)] },
+		select: access.readable(question),
+	});
+}
+
+/** Whether this principal may post `body` in a room, asking Prisma what the row does not carry. */
+export async function mayPost(
+	prisma: PrismaClient,
+	principal: Principal,
+	roomId: string,
+	body: string,
+) {
+	return access.can({
+		principal,
+		origin: "client",
+		action: "create",
+		resource: "Message",
+		row: { roomId, authorId: principal.profileId, body },
+		exists: (resource, where) => access.prismaExists(prisma, resource, where),
+	});
+}
+```
+
+| Member | Answers |
+|---|---|
+| `can`, `grantsOf`, `scopeOf`, `fieldsOf` | As the engine does, in Aventara's `where` |
+| `checkBeacons(reader, pins, environment)` | The startup check of the beacons of the namespaces the rules read as foreign, as the engine's ([The ownership beacon](#the-ownership-beacon)). Until it passes, `access` answers nothing when the rules read another namespace. |
+| `prismaWhere(resource, scope)` | A scope as a Prisma `where`; `false` matches no row |
+| `readable(question)` | The fields a read shows on every row, as a Prisma `select`. A governed field opened on some rows only is left out, and no relation is selected. |
+| `prismaExists(prisma, resource, where)` | `can`'s `exists`, through your Prisma client |
+| `prismaBeacon(prisma)` | The ownership beacon's store over your Prisma client's `AventaraBeacon` model: what `checkBeacons` reads, and `avaccess push --beacon` and `pull --beacon` load |
+
+The guarantees are weaker than inside Aventara. The scope covers only the queries you pass it to, and a Prisma
+`include` is not scoped. Verify the bearer token against the Access server's key set (`/api/auth/jwks`) before you
+build the principal.
+
+For an update, run it on the rows `scopeOf({ action: "update" })` returns, and ask
+`can({ action: "update", row, before })` about each row it leaves, inside the same transaction, rolling back on
+`false`. `before` is the row as you read it in that transaction before the update. Hold the update to that row (its
+values in the update's `where`), so a concurrent change makes the update miss instead of passing on a stale `before`.
+Without `before`, `can` checks only the row the update leaves. Hand `can` the row's own fields; it never reads a relation on the row, and a client's relation data never
+belongs there.
+
+## Running `avaccess serve`
+
+`avaccess serve [--config <file>] [--port <port>] [--hostname <host>] [--max-body-bytes <bytes>] [--migrate]` runs the
+standalone host from a configuration file. It finds `access.config.ts` in the working directory (or `.mts`, `.cts`, `.js`, `.mjs`,
+`.cjs`), loads it without a build step, and serves it until `SIGTERM` or `SIGINT`, on `127.0.0.1` unless `--hostname`
+says otherwise.
+
+- Better Auth's migration runs on start only with `--migrate` or `AVACCESS_MIGRATE=true` (or `1`).
+- Without it, a database Better Auth migrates itself (a `pg` Pool, a MySQL pool, SQLite) is checked before the server
+  listens. One that lacks a table, column or index the options need stops it with exit `1` and the list of what is
+  missing.
+- A database behind an ORM's adapter (Prisma, Drizzle) is the ORM's to migrate: run `npx auth@~1.7.12 generate --yes`, then
+  the ORM's migration. It is served as it is, and `--migrate` refuses it with exit `2`.
+- Better Auth's rate limit is on, whatever `NODE_ENV` says (Better Auth turns it on in production only), unless the
+  configuration sets `betterAuth.rateLimit.enabled`.
+- `--max-body-bytes` sets `serve`'s body cap (default 1 MiB).
+- `access.config.ts` is the configuration, as in [The server](#the-server): its default export (or `access`) is the
+  `createAccess` instance. It reads its secrets from the environment.
+- `GET /health` answers `200 {"status":"ok"}`, and `SIGTERM` drains the server and ends it with exit `0`.
+
+Access ships no container image. To run the server in a container, build one from a project that installs the package,
+Better Auth and whatever the configuration imports (here `pg`), from its lockfile:
+
+```dockerfile
+FROM node:24-slim
+WORKDIR /srv/access
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev --ignore-scripts
+COPY access.config.ts ./
+USER node
+EXPOSE 3000
+CMD ["node_modules/.bin/avaccess", "serve", "--hostname", "0.0.0.0"]
+```
+
+`--hostname 0.0.0.0` makes it listen on the container's interfaces. The server speaks plain HTTP: put it behind a proxy
+that terminates TLS, and set Better Auth's `advanced.ipAddress.trustedProxies` to that proxy's address, so the client's
+address comes from its `X-Forwarded-For`.
+
+## File formats and hashes
+
+Every file Access writes is passive JSON with a format string. A member the format does not define is refused, and so
+is a file of another format.
+
+| Format | Members | Written by |
+|---|---|---|
+| `aventara-access/policies@1` | `format`, `namespace` (optional), `claims`, `schema`, `roles`, `govern`, `grants`, `denies` | `.contract()`, `avaccess pull` |
+| `aventara-access/guardrails@1` | `format`, `claims`, `denies` | `defineGuardrails(…).contract()`, `avaccess pull` |
+| `aventara-access/lock@1` | `format`, `namespace`, `policies`, `guardrails`, `foreign` (optional) | `avaccess pull` |
+| `aventara-access/foreign@1` | `format`, `namespace`, `schema` (the owners' entries, each marked `foreign`) | `avaccess pull --foreign` |
+| `aventara-access/beacons@1` | `format`, `namespace`, `environment`, `beacons` (owner to beacon hash) | `avaccess pull --env` |
+
+A policies file's schema entry lists, beside its fields, the nullable ones (`nullable`) and the ones `can` compares by
+their type (`types`: `bigint`, `datetime` or `decimal`). A rule's literal is written in its field's canonical form: an
+instant as `toISOString()` writes it, a decimal without exponent or extra zeros. The engine checks every member of a
+file it is handed (each rule, condition, comparison and claim), and refuses a number JSON cannot carry: `NaN` and
+`Infinity` would be written as `null`. A Resource or field name is an identifier (never `__proto__`), each identifier,
+reference field and relation target names something the schema lists, a decimal is at most 1,000 characters, and a
+deny id never starts with `guardrail:` or `better-auth:`, the prefixes of the denies the engine adds itself.
+
+`policiesHash(file)` and `guardrailsHash(file)` return a file's canonical hash, `"sha256:<hex>"`. It is the same for
+the same rules written in any order, and a formatter's re-indent does not change it.
+
+```ts
+// scripts/policies.write.ts
+import { readFileSync, writeFileSync } from "node:fs";
+import { createAccessEngine, policiesHash } from "@aventara/access";
+import { policies } from "../src/access.policies.js";
+
+const file = policies.contract();
+writeFileSync("policies.json", `${JSON.stringify(file, null, "\t")}\n`);
+console.log(policiesHash(file)); // "sha256:…"
+
+// Later, or in another process: the same engine, from the file alone.
+const engine = createAccessEngine(
+	JSON.parse(readFileSync("policies.json", "utf8")),
+);
+console.log(Object.keys(engine.governed)); // ["User"]
+```
+
+Run it from the project's root with `npx tsx scripts/policies.write.ts`. It writes `policies.json` there.
+
+The file's parts are exported as types (`AccessPolicies`, `AccessGrantRule`, `AccessDenyRule`, `AccessGuardrails`,
+`AccessLock` and the rest), so a project that emits declarations can export any part of a file.
+
+## Error codes
+
+`createAccess`, its instance, `aventaraAccess()`, `accessOf(auth)`, the registry, and an engine checking its lock or a
+question throw `AccessError`,
+exported from `@aventara/access` (beside the engine, which throws it too). Its `code` says which
+refusal it is, and its message, which starts `Aventara Access:`, says what to change. The registry answers with
+Better Auth's `{ code, message }` body.
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `ACCESS_BETTER_AUTH_VERSION` | `better-auth` is missing, or outside `~1.7.12` (1.7.12 or a later 1.7 patch); under `mcp` or `audience`, an `@better-auth/oauth-provider` or `@better-auth/cimd` outside it | `npm i better-auth@~1.7.12`; under `mcp` or `audience`, `npm i @better-auth/oauth-provider@~1.7.12 @better-auth/cimd@~1.7.12` |
+| `ACCESS_CLAIMS_UNDECLARED` | The rules or the guardrails read a claim, or a token carries one, that `policies.claims` does not declare | Declare the claim in `policies.claims` |
+| `ACCESS_PLUGIN_DUPLICATE` | `betterAuth.plugins` holds `jwt()` or `aventaraAccess()`, which `createAccess` installs itself; Better Auth's plugins hold `jwt()` or a second Access plugin beside `aventaraAccess()`; one `aventaraAccess()` in two Better Auth instances whose options differ; or a plugin that defines `jwt()`'s endpoints, Access's own `/me` route (under `createAccess`), (kiosk profile) one under `/kiosk/`, or (registry on) a registry route | Remove it from the plugins |
+| `ACCESS_OPTIONS_INVALID` | An option `createAccess` does not take or cannot read; `passwords` beside your own `emailAndPassword.password`; Node.js 22 without `@node-rs/argon2`; a grant on a Better Auth table `resources` leaves closed; a claim read from a field the user can set; no base URL to fix the tokens' issuer; `sameSite: "none"` without `trustedOrigins`; Better Auth off its Prisma adapter without `resources.authTables`, or an opened table whose secret column is not found; a `principal` object shared by two users; an organization plugin without `requireEmailVerificationOnInvitation: true` under `resources.members` or the bridge (GHSA-fmh4-wcc4-5jm3); under the bridge, one that lets any user create an organization, or maps a role dynamic access control lets admins name; under `mcp` or `audience`, no OAuth provider or two, one listed before `aventaraAccess()`, `disableJwtPlugin`, a resource missing from its `resources`, no `aventara:read` among its `scopes`, a `refreshTokenReuseInterval` other than 0, a `validateRedirectUri`, a `requestUriResolver`, a `postLogin.consentReferenceId`, `allowUnauthenticatedClientRegistration` without `mcp.openRegistration` (never under `audience` alone), a resource that is the provider's UserInfo URL, the `service` profile, (`mcp`) an http issuer off `127.0.0.1` and `[::1]`, or (`audience`) `enforcePerClientResources: false` and, beside `mcp`, the audience in `clientRegistrationDefaultResources` or `clientRegistrationAllowedResources`; `accessOf` given an instance without `aventaraAccess()`; a `profile` of two kinds, or the kiosk's keys on another kind; the kiosk profile with Better Auth's cookie cache, with `secondaryStorage` and sessions kept out of the database, with `bearer()` or `multiSession()`, with `crossSubDomainCookies` or `SameSite=None`, or on a plain http: base URL off a loopback host and off `insecureLan`, or a dynamic `baseURL` serving a host off loopback over http:; under `insecureLan`, a range that is not a canonical private IPv4 CIDR of /16 or narrower, an empty or repeated list, a base URL that is a hostname, IPv6, outside every range or dynamic, or a cookie setting that makes a cookie `Secure` | Follow the message |
+| `ACCESS_RESOURCE_MISSING` | A table `resources` opens is missing: Better Auth lacks its plugin, or the rules' schema lacks its Resource; the organization bridge without `organization()` | Add the plugin, or run `npx auth@~1.7.12 generate --yes` and regenerate the model |
+| `ACCESS_LOCK_MISMATCH` | A pulled file no longer hashes to its pin in `avAccess.lock.json`, the engine was given files the lock does not pin, or `requireLock` is set and no lock was given | Run `avaccess pull` again; never edit a pulled file; pass the lock |
+| `ACCESS_KEY_REFUSED` | A registry key that is wrong, revoked, rotated out or another namespace's (`401`), or a pull key that pushes (`403`) | Use the namespace's current key of the right kind |
+| `ACCESS_OWNERSHIP` | A pushed file names a Resource another namespace owns, or one the operator has not assigned it (`ownership: "assigned"`), or the org's guardrails file grants (it holds `grants`, or a guardrail with `subjects`) (`403`) | Grant only on your own Resources; ask the owner or the operator, or add a guardrail |
+| `ACCESS_POLICIES_INVALID` | A pushed file is not a file the engine would run from (`400`), or is over 1 MiB (`413`) | Push the `.contract()` of your rules, or the pulled file unchanged |
+| `ACCESS_NAMESPACE` | A namespace name that is not one, one the registry does not have, or one it has already | Check the name; use `keys rotate` for an existing namespace |
+| `ACCESS_REVISION_CHANGED` | A stored revision no longer hashes to its key: it was changed outside the registry (`500`) | Restore the registry's tables; push the file again |
+| `ACCESS_FOREIGN_CROSS_DATABASE` | The rules read another namespace's Resources as foreign, and this service is on another database: the owner's beacon as its connection reads it is missing or not the one the owner pushed, or the owner pushed none (`403`) | Run the service on the owner's database, or carry the fact in a JWT claim (`policies.claims`) |
+| `ACCESS_BEACON_MISMATCH` | At startup, an owner's row in `_aventara_beacon` is missing or does not hash to this environment's pin, the pins are another environment's, a check failed before, or `checkBeacons` was not awaited; at push, a beacon the namespace replaced comes back (`409`), or the namespace's row is one the registry does not hold | Point the service at the owner's database; pull this environment's pins; await `checkBeacons` before serving; have an operator verify or delete a row the push did not write |
+| `ACCESS_QUESTION_INVALID` | A `fieldsOf` question without `access: "read"` or `access: "write"`, or with an `action` that does not fit it | Ask `{ access: "read" }`, or `{ access: "write", action? }` with `create` or `update` |
+
+## License
+
+PolyForm Shield 1.0.0 with an additional permission. See [LICENSE](./LICENSE) and
+[LICENSE-ADDITIONAL-PERMISSION.md](./LICENSE-ADDITIONAL-PERMISSION.md).