@aventara/access 0.1.0-rc.0 → 1.0.0-rc.1

package/CHANGELOG.md

@@ -1,6 +1,58 @@
 # @aventara/access
 
-## Unreleased
+## 1.0.0-rc.1
+
+The first release candidate of 1.0, released beside `@aventara/core` `1.0.0-rc.11`: Access moves to 1.0 with the
+framework. It is tested with `@aventara/core` `1.0.0-rc.11`, and still works with `1.0.0-rc.10` or
+later.
+
+- An engine whose beacons were not checked refuses with a message that names the call an app makes,
+  `await access.policy.checkBeacons(beacon, beaconPins, environment)` (`engine.checkBeacons` on an engine of one's own),
+  where it said `engine.checkBeacons(reader, pins, environment)`. The `code` is unchanged.
+- `ACCESS_REFERENCE_UNREADABLE` names `resources: { users: true }` when the target is Better Auth's `user` table and
+  `createAccess` (or the plugin) keeps it closed, since no read grant on it is taken until the key opens it. The same
+  holds for the other tables a `resources` key opens.
+- `ACCESS_REFERENCE_UNREADABLE` also warns when the only read grant that would reach the target is a `*` grant and the
+  target is one of Better Auth's tables that `createAccess` (or the plugin) keeps closed: the built-in deny refuses
+  every action on such a table, a `*` read included, so every write of a reference to it is refused. The warning
+  names the `resources` key that opens the table. It was silent before. Nothing the engine decides changes.
+- `govern` takes a mode per field beside the list form: `.govern("Member", { role: "write" })` keeps the field readable
+  and lets only a grant that names it write it; `{ nationalId: "read" }` keeps it writable and lets only a grant that
+  names it read it; `"both"`, and the list form as before, govern each. A field governed twice with two modes is a type
+  error and refused when the rules compile. The policies file gains the optional member `governModes` (the `"read"`
+  and `"write"` fields; a file without it reads as before, and the list form compiles to the same file and hash). The
+  engine's `governed` lists the fields governed for reading only, typed as a list (`readonly "email"[]`, no longer
+  the tuple the rules wrote), and `avaccess diff` names a field whose mode changed. When `resources` opens Better Auth's tables, Access governs `User.role` and the organization `member`
+  table's `role` as `"write"`: a create or update grant sets one only when it names it (govern it in the rules too, so
+  a grant can name it). An update grant on `User` that named no field set the role before; it sets nothing now.
+- The request state's `me` is a frozen copy of the plain data `principal` returns (plain objects and arrays), held
+  as a read-only member of the state: no code that runs during a request can replace the principal
+  or change it, an access token's scopes included. The app's own objects are never frozen or marked; one object
+  `principal` returns for two users is still refused (`ACCESS_OPTIONS_INVALID`), now over an access token too. Only
+  the returned object is checked. A class instance, `Map`, `Set`, `Date`, typed array or getter inside the principal is
+  not frozen, and a top-level one is `me` as returned. Under an OAuth access token a `Map` or `Set` principal is not
+  supported, and a class instance loses its `#private` fields.
+- A field governed as `"read"` that is one of its Resource's identifiers warns `ACCESS_READ_GOVERNED_UNIQUE` when the
+  rules compile and when the engine is built: a write that sends a value another row holds fails on the duplicate,
+  which tells the writer the value exists. An empty `governModes` is refused.
+- The README links the framework's documentation at `https://aventara.razor34.dev/framework`.
+- The package ships an agent skill in `skill/` (`SKILL.md` and `reference/*.md`): setup and wiring, the rule
+  language, recipes and deny patterns, signed-out callers and cached reads, and the codes an agent meets. Copy it into
+  your agent's skills folder or point the agent at it; the README's "AI agents" section says how. Its TypeScript
+  examples compile in the packed-install gate. No new export and no new command.
+- Proven against the framework's Operation Sets (`POST {api}/_all`) and cached reads, with nothing in Access changed
+  for either. Each entry of a set is decided as its single route would be, under one principal derived once for the
+  whole request; a refused entry changes nothing for the others. A cached read `for: "anonymous"` is `public` only
+  when Access finds no one in the request (its principal is `null`): a caller with a valid session cookie or bearer
+  token gets a `private` answer, and a token that verifies to no one gets the signed-out answer.
+
+## 0.1.0-rc.0
+
+The first release candidate: the policy engine, Better Auth with Access beside it (`@aventara/access/auth`), the
+policy registry and the org's guardrails, the audit log, the `avaccess` bin with its generator, and the standalone
+host (`@aventara/access/standalone`). The published package listed the first group of entries below under
+"Unreleased": they were made after this candidate was first written up and before it was published, and they ship
+in it (the container image the later entries describe was removed then).
 
 - The engine warns, as a Node.js warning `ACCESS_REFERENCE_UNREADABLE`, when a role may create or update a reference
   (a to-one relation's reference fields) to a Resource no read grant reaches for that role. Aventara holds a reference
@@ -311,12 +363,6 @@
 - New exports: `AccessBeaconReader`, `AccessBeaconStore`, `AccessBeaconPins`; new codes `ACCESS_FOREIGN_CROSS_DATABASE`
   and `ACCESS_BEACON_MISMATCH`. `aventara-access/lock@1` takes an optional `foreign` pin.
 
-## 0.1.0-rc.0
-
-The first release candidate: the policy engine, Better Auth with Access beside it (`@aventara/access/auth`), the
-policy registry and the org's guardrails, the audit log, the `avaccess` bin with its generator, and the standalone
-host (`@aventara/access/standalone`) with its container image.
-
 - `definePolicies(model)` writes role-first rules, typed from your app's schema (an Aventara discovery artifact's
   `model`). Global roles come from the principal's claims; roles held on a row (`on`, `where`) come from your own
   tables. `.govern()` keeps fields out of every result unless a grant names them. `.grants()` and `.denies()` take the

package/README.md

@@ -1,7 +1,7 @@
 # @aventara/access
 
 Access extends [Better Auth](https://www.better-auth.com) with policies for
-[Aventara](https://aventara-framework.vercel.app) apps and the services beside them. Better Auth signs users in and
+[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
@@ -20,7 +20,7 @@ This is a release candidate. It holds:
 | `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) · [Write the rules](#write-the-rules) · [createAccess](#createaccess) ·
+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)
@@ -34,7 +34,7 @@ Access goes into an Aventara app. To start one, create it with the Aventara CLI
 PostgreSQL), then install Access in it:
 
 ```sh
-npx @aventara/cli@1.0.0-rc.10 new <app> --orm prisma7 --db postgresql
+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:
@@ -42,7 +42,26 @@ 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.
+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
@@ -56,12 +75,32 @@ Access works with `@aventara/core` `1.0.0-rc.10` or later. It has no dependency
 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";
@@ -90,9 +129,13 @@ export const policies = definePolicies(model)
 		},
 	}))
 
-	// Governed fields: out of every default projection; only a grant that names one
-	// opens it, and only when selected.
+	// 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"),
@@ -110,6 +153,12 @@ export const policies = definePolicies(model)
 		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 }) => [
@@ -160,7 +209,9 @@ How the rules combine:
   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. Compiling the rules warns about nothing, and the engine decides as before. A reference to a
+  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)).
@@ -227,12 +278,34 @@ are locked together: `except: ["author"]` locks `authorId` too, and `except: ["a
 
 ### Governed fields
 
-`.govern("User", ["email"])` takes a field out of every default projection. Only a grant that names it
-(`fields: ["User.email"]`) opens it, and only when the request selects it. Selecting a governed field without such a
-grant is refused with `403 A4002`. The field is not quietly dropped from the result.
+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 relation and its reference fields tell each other (`author.id` is `authorId`), so they are governed together:
-`.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`.
@@ -392,39 +465,54 @@ 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.
 
-Better Auth's tables go into your schema the way Better Auth's docs say. With Prisma,
-`npx auth@~1.7.12 generate --config src/access.ts` 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. Then migrate with Prisma and 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, `npx auth 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 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 `npx auth@~1.7.12 generate` writes `String` foreign keys (`Session.userId`, `Account.userId`)
-against that `Int`, and `prisma validate` fails. Better Auth has its own option for a database that assigns numeric
-ids. Put it in the `betterAuth` block of `src/access.ts`, beside `database`:
-`advanced: { database: { generateId: "serial" } }`.
-
-Every Better Auth table, and Access's own, then gets `Int @id @default(autoincrement())`, and its references are `Int`.
-Add the option before you run `npx auth@~1.7.12 generate --config src/access.ts`, then run `npx prisma validate`. The
-command 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"`. Type your principal's `id` as `number`
-  and map it, `principal: ({ sub, claims }) => ({ id: Number(sub), claims: … })`. 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.
+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 |
@@ -450,7 +538,9 @@ again.
   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`.
+  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
@@ -594,10 +684,10 @@ refuses with `ACCESS_OPTIONS_INVALID`, unless you hash passwords yourself (`bett
 |---|---|
 | `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` reads) |
+| `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, `{ me }`: from a bearer token checked against Better Auth's key set, or (profiles `web` and `kiosk`) the session cookie; `null` when neither |
+| `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)) |
@@ -1034,7 +1124,7 @@ What binds a session to its device:
 
 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` writes them as it writes Better Auth's own; off Prisma's adapter, name them in `resources.authTables`. Like
+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.
 
@@ -1651,7 +1741,7 @@ The engine answers:
 | `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 governed fields, by Resource |
+| `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 |
@@ -1705,7 +1795,7 @@ 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` writes it
+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.
 
@@ -1787,13 +1877,20 @@ one of them. These rules only narrow. `resources` decides which tables your rule
 
 | Key | Opens | Writes through Aventara |
 |---|---|---|
-| `users: true` | `user`, `session` and `account` (session and account read only) | on `user`, an update of `role` |
-| `members: true` | the organization plugin's `member`, and its `organization` (read only) | on `member`, a create, an update of `role`, and a delete |
+| `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
@@ -1863,8 +1960,8 @@ A table a key opens must have each of its secret columns under Better Auth's fie
 
 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` 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` can load
+`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
@@ -1897,7 +1994,7 @@ users need, and see [Sign up and sign in](#sign-up-and-sign-in) before you turn
 
 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` for an ORM's schema. `access.handler` serves the registry's routes under Better Auth's base path, so every mount carries them:
+`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 |
 |---|---|
@@ -2336,7 +2433,7 @@ says otherwise.
 - 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`, then
+- 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`.
@@ -2423,7 +2520,7 @@ Better Auth's `{ code, message }` body.
 | `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` and regenerate the model |
+| `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 |

package/dist/access/access-options.d.ts

@@ -5,7 +5,15 @@ import type { AccessPolicies, AccessPoliciesJson } from "../policies-contract.js
 import type { AccessClaimsAnswer, AccessClaimsDeclaration, AccessClaimsSource } from "./claims.mapper.js";
 /** The fields each Resource governs, by Resource: what the rules' engine is typed with. */
 type GovernedShape = {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+};
+/** The builder's `govern` block: a mode per governed field. */
+type ModesShape = {
+    readonly [resource: string]: {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 };
 /** The claims a rules principal type `R` reads, by name. */
 type ClaimNamesOf<R> = R extends {
@@ -24,7 +32,7 @@ type DeclaredFor<R, C extends AccessClaimsDeclaration> = [
  * The rules an instance evaluates: `definePolicies(model)…` as written, or its
  * compiled file (typed, or imported as JSON as `avaccess pull` wrote it).
  */
-export type AccessRules<R, Gov extends GovernedShape> = AccessBuilder<any, R, any, Gov> | AccessPolicies<Gov> | AccessPoliciesJson<Gov>;
+export type AccessRules<R, Gov extends GovernedShape> = AccessBuilder<any, R, any, Gov & ModesShape> | AccessPolicies<Gov> | AccessPoliciesJson<Gov>;
 /** The `policies` block. */
 export type AccessPoliciesOptions<C extends AccessClaimsDeclaration, R, Gov extends GovernedShape> = {
     /** The rules this instance evaluates: the builder (its principal type is checked here) or its compiled file. */

package/dist/access/access.factory.d.ts

@@ -14,7 +14,9 @@ import { type AccessClaimsDeclaration, type AccessClaimsOf, type AccessIdentity
 import { type AccessProfileOptions } from "./profile.policy.js";
 export type { AccessPoliciesOptions, AccessRules, } from "./access-options.js";
 type GovernedShape = {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 };
 /** The headers of a request, as the framework hands them to `state`. */
 type RequestHeaders = {

package/dist/access/principal.subject.d.ts

@@ -1,12 +1,22 @@
+/**
+ * Records that `principal` returned `value` for `sub`, writing nothing to it, and
+ * refuses an object it already returned for another `sub`: a cache keyed wrongly
+ * would serve one user as another. Only the value `principal` returns is checked,
+ * not what it holds.
+ */
+export declare const claimReturned: (value: unknown, sub: string) => void;
 /**
  * Marks `me` as derived from `sub`: a non-enumerable property, so a spread,
  * `JSON.stringify` or `Object.keys` of the principal does not show it.
  *
+ * With `write` false (an object the app owns), the `sub` is kept in the process's
+ * map instead, and the object is not touched.
+ *
  * Refuses an object that already stands for another `sub`: one object handed out
  * for two users (a principal function that returns a shared object) would carry
  * whichever user came last, and the audit would name the wrong user for the other
  * one's decisions.
  */
-export declare const carrySubject: (me: unknown, sub: string) => void;
+export declare const carrySubject: (me: unknown, sub: string, write?: boolean) => void;
 /** The `sub` of a principal Access derived; `null` for any other principal. */
 export declare const subjectOf: (principal: unknown) => string | null;

package/dist/access/principal.subject.js

@@ -15,24 +15,53 @@ const frozenSubjects = () => {
     holder[FROZEN] ??= new WeakMap();
     return holder[FROZEN];
 };
+/** The key of the one map, per process, of each object `principal` returned and the `sub` it returned it for. */
+const RETURNED = Symbol.for("@aventara/access:returned-principals");
+const returnedPrincipals = () => {
+    const holder = globalThis;
+    holder[RETURNED] ??= new WeakMap();
+    return holder[RETURNED];
+};
+/** The refusal of one object `principal` handed out for two users. */
+const twoUsers = () => new AccessError("ACCESS_OPTIONS_INVALID", "`principal` returned an object it already returned for another user: the audit names the user each principal stands for, and one object cannot stand for two. Return a new object for each user (one cached per user is fine).");
+/**
+ * Records that `principal` returned `value` for `sub`, writing nothing to it, and
+ * refuses an object it already returned for another `sub`: a cache keyed wrongly
+ * would serve one user as another. Only the value `principal` returns is checked,
+ * not what it holds.
+ */
+export const claimReturned = (value, sub) => {
+    if (typeof value !== "object" || value === null) {
+        return;
+    }
+    const returned = returnedPrincipals();
+    const prior = returned.get(value);
+    if (prior !== undefined && prior !== sub) {
+        throw twoUsers();
+    }
+    returned.set(value, sub);
+};
 /**
  * Marks `me` as derived from `sub`: a non-enumerable property, so a spread,
  * `JSON.stringify` or `Object.keys` of the principal does not show it.
  *
+ * With `write` false (an object the app owns), the `sub` is kept in the process's
+ * map instead, and the object is not touched.
+ *
  * Refuses an object that already stands for another `sub`: one object handed out
  * for two users (a principal function that returns a shared object) would carry
  * whichever user came last, and the audit would name the wrong user for the other
  * one's decisions.
  */
-export const carrySubject = (me, sub) => {
+export const carrySubject = (me, sub, write = true) => {
     if (typeof me !== "object" || me === null) {
         return;
     }
     const carried = subjectOf(me);
     if (carried !== null && carried !== sub) {
-        throw new AccessError("ACCESS_OPTIONS_INVALID", "`principal` returned an object it already returned for another user: the audit names the user each principal stands for, and one object cannot stand for two. Return a new object for each user (one cached per user is fine).");
+        throw twoUsers();
     }
-    if (Object.isExtensible(me)) {
+    if (write && Object.isExtensible(me)) {
         try {
             Object.defineProperty(me, SUBJECT, {
                 value: sub,