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

package/skill/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: aventara-access
+description: Set up and write authorization rules with Aventara Access (@aventara/access) in an Aventara app. Use when editing src/access.ts, src/access.policies.ts or any file that calls definePolicies, grant, deny, roles, govern, createAccess, aventaraAccess, accessOf, createAccessEngine or defineGuardrails; when wiring Access into AventaraModule, Aventara() or createFramework (the `access` option, `policy`, ctx.$state.me, a call's `{ as }`); when a read must work for signed-out callers or carries a cache({ for }) stage; and when an Access or policy code appears (A4002, A3000, ACCESS_OPTIONS_INVALID, ACCESS_CLAIMS_UNDECLARED, ACCESS_PLUGIN_DUPLICATE, ACCESS_REFERENCE_UNREADABLE, any ACCESS_* code).
+---
+
+# Aventara Access
+
+Access is the authorization layer of an Aventara app. Better Auth signs users in and issues every token; Access decides
+what each caller may do with each row and each field. You write role-first rules typed from the app's schema, Access
+compiles them to a passive policies file (`aventara-access/policies@1`), and its engine answers the framework's policy
+questions on every client and agent request. Written for `@aventara/access` 1.0.0-rc.1 with `@aventara/core`
+1.0.0-rc.11 (1.0.0-rc.10 or later works) and `better-auth` `~1.7.12`.
+
+The reference files hold the detail. Read only the one the task needs:
+
+- `reference/setup.md`: install, `createAccess`, mounting Better Auth's routes, the framework's `access` option, the
+  Better Auth plugin, the engine alone, how a request's `me` is read, server code with `{ as }`.
+- `reference/rules.md`: the rule language: principal, roles, grants, denies, `where`, governed fields, updates,
+  references, and how the rules combine.
+- `reference/recipes.md`: complete, type-checked rules for the common tasks, and the deny patterns.
+- `reference/callers.md`: anonymous and signed-out callers, cached reads (`cache({ for })`), agents over MCP, `can` in
+  the UI.
+- `reference/errors.md`: every `ACCESS_*` code, the framework codes Access causes, the warnings, and what to check on
+  a refusal.
+
+The package README (`node_modules/@aventara/access/README.md`) is the full manual: the kiosk profile, the registry and
+`avaccess`, guardrails across services, the generated client for services not on Aventara, the standalone server.
+
+## What Access does not do
+
+- **No authentication.** Better Auth signs users in. Access adds no token endpoint, no OAuth route and no sign-in
+  method of its own. Agents get their tokens from Better Auth's OAuth provider (`@better-auth/oauth-provider`).
+- **No check on server code by default.** A `framework.application.*` call is not checked unless it names a principal
+  with `{ as }` ([setup](reference/setup.md#server-code-runs-unchecked-unless-it-names-a-principal)).
+- **No revocation of a token.** A token lives until it expires (`policies.tokenTtl`, 900 seconds at most).
+
+## Where things are
+
+| File | What it is |
+|---|---|
+| `src/access.policies.ts` | The rules: `definePolicies(model)…`, typed from the discovery artifact's `model`. |
+| `src/access.ts` | `createAccess({ betterAuth, policies, principal, … })`: Better Auth with Access beside it. Default export too (Better Auth's CLI reads it). |
+| `src/main.ts` | Mounts `toNodeHandler(access)` at `/api/auth/` before Nest's body parser. |
+| `src/app.module.ts` | Adds `access` to the `config` beside `adapter`. No `policy` key, no host `state`. |
+| `src/generated/aventara/discovery.artifact.ts` | Written by `aventara:prepare`. The rules are typed from its `model`. Never edit it. |
+
+Next.js: `access` goes in `src/aventara/config.ts`, and the routes in `src/app/api/auth/[...all]/route.ts`
+([setup](reference/setup.md#nextjs)).
+
+## Rules
+
+1. **Nothing is allowed until a grant allows it.** Any matching grant allows; any matching deny wins over every grant;
+   the order of rules never matters. Write grants for what each role needs, and denies for what nobody in a situation
+   may do (a ban, an agent deleting).
+2. **Type the principal first.** `.principal<Principal>()` comes right after `definePolicies(model)`, so `me` is typed
+   in every callback. Every Resource, field, relation and enum value in a rule is checked against the schema: a type
+   error names the wrong key. Fix the key; never cast it away (`as`, `!`, `any`, `@ts-expect-error`).
+3. **Hold every write grant to the caller.** A `create` or `update` grant that writes an owner carries
+   `where: { authorId: me.id }`; an update grant's `where` is checked on the row it leaves too, so the owner cannot hand
+   the row to someone else. Use `after` for what the new row must also meet, and `write: { except: [...] }` for fields
+   the grant may not set.
+4. **Claims come only from fields the user cannot set.** A claim (`role`, `banned`) is read from the user's field of
+   the same name, which needs `input: false` in `user.additionalFields`, and no grant may let the user write that
+   field through Aventara (rule 8). Declare every claim the rules read in `policies.claims`.
+5. **A missing value fails closed.** A grant that reads a `me` value or claim the caller lacks never matches; a deny
+   that reads one matches. The anonymous caller (`me` is `null`) lacks them all. Write a deny so that a missing claim is
+   the safe case. Exception: for the anonymous caller, a deny's `if` comparing a claim with `true` never holds, so a
+   ban never closes an `anyone` grant to signed-out callers. To refuse them, leave the `anyone` grant out.
+6. **Govern every field your roles, claims or principal read, usually as `"write"`.** `.govern("Member", { role:
+   "write" })` keeps the field readable and lets only a grant that names it (`fields: ["Member.role"]`) write it, so an
+   update grant on the row cannot hand out a role. `{ nationalId: "read" }` is the other way: written as any field, read
+   back only through a grant that names it. The list form, `.govern("User", ["email"])`, governs both: out of every
+   default read, and written by no grant that does not name it. Selecting a field governed for reading without such a
+   grant is refused, not dropped.
+7. **A written reference needs read on its target.** A role that creates a `Note` with `authorId` must be able to read
+   that `User` row, or the write is refused `A4002`. Heed `ACCESS_REFERENCE_UNREADABLE`.
+8. **Better Auth's tables are closed until you open them.** A rule on `User` needs `resources: { users: true }` in
+   `createAccess`; organization members need `resources: { members: true }`. Secret columns (password hashes, tokens,
+   keys) stay sealed whatever you grant. `role` is the one `User` field Aventara writes, and Access governs it as
+   `"write"`, as it does the organization `member` table's `role`: a grant sets either only when it names it, after
+   `.govern("User", { role: "write" })` lets the rules name it. Name `User.role` only in an admin role's grant, never in
+   one for `signedIn`, `anyone` or a role users reach on their own (users edit their profile through Better Auth's
+   `/update-user`), and name a member's role only in an organization admin role's grant, held to
+   `where: { organizationId: me.org }`.
+9. **Signed-out callers get only `anyone` grants.** `signedIn` is any non-null principal; `anyone` adds the anonymous
+   caller. Grant `anyone` only on rows that are public, and give a public cached read `cache({ for: "anonymous" })`,
+   never `"everyone"` unless every caller, an admin included, gets the same answer
+   ([callers](reference/callers.md)).
+10. **One provider per app.** With `access` in the configuration, leave `policy` out and give the host no `state`
+    option. `createAccess` installs `jwt()` and the Access plugin itself: never add either to `betterAuth.plugins`.
+11. **Branch on codes, never on messages.** An `AccessError` carries `code`; a refused request answers `403 A4002`.
+    Look up any code in `reference/errors.md`.
+12. **Never edit generated or pulled files.** The discovery artifact, the policies file a pull wrote and
+    `avAccess.lock.json` are rebuilt, never patched.
+13. **Write only what changes behaviour.** Leave out what Access already does: no deny for what no grant allows
+    (nothing is allowed until a grant allows it), no `.govern` of `User.role` or the `member` table's `role` (Access
+    governs both as `"write"` once `resources` opens them; govern one only so an admin's grant can name it in
+    `fields`), no `"both"` where the list form says it, no option set to its default value, and no type annotation the
+    inference already gives.
+
+## Which tool
+
+| You want to | Use |
+|---|---|
+| Let everyone signed in do something | `grant("signedIn", action, Resource)` |
+| Let only the owner touch a row | `grant("signedIn", actions, Resource, { where: { ownerId: me.id } })` |
+| A site-wide role (admin, staff) | `.roles(() => ({ admin: { global: { claims: { role: "admin" } } } }))` |
+| A role held on a row (member of a campaign) | `.roles(({ me }) => ({ dm: { on: "Campaign", where: { members: { some: { userId: me.id, role: "DM" } } } } }))`, then `{ in: "campaign" }` on grants of related Resources |
+| Refuse something whatever the grants say | `deny(actions, Resource, { if: { claims, origin } })` or `{ where }` |
+| Keep a field out of default reads and writes | `.govern(Resource, [field])` plus a grant with `fields` |
+| Let everyone read a field and only some write it (a role) | `.govern(Resource, { field: "write" })` plus a write grant with `fields` |
+| Let a field be written and never read back (an id number) | `.govern(Resource, { field: "read" })`, and a read grant with `fields` only where it must be read |
+| Keep a field out of a write | `write: { except: [field] }` on the grant |
+| Hold the row an update leaves | `after: { … }` on the update grant |
+| Public data for signed-out callers | `grant("anyone", "read", Resource, { where })` |
+| Ask from the UI whether a button applies | the framework client's `$access.can`, or `aventaraAccessClient()`'s `can` |
+| See why a request was refused | `engine.explain(question)` in development, the audit log in production |
+
+## The shape of a setup
+
+```ts
+// src/team.policies.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** What the app derives for a request: the signed-in user. Anonymous is `null`. */
+export type TeamPrincipal = {
+	id: string;
+	claims: { role?: "admin"; banned?: boolean };
+};
+
+export const teamPolicies = definePolicies(model)
+	.principal<TeamPrincipal>()
+	.roles(() => ({
+		admin: { global: { claims: { role: "admin" } } },
+	}))
+	.govern("User", ["email"])
+	.grants(({ grant, me }) => [
+		// Each user reads their own profile, email included.
+		grant("signedIn", "read", "User", {
+			where: { id: me.id },
+			fields: ["User.email"],
+		}),
+		grant("signedIn", "read", "Note", { where: { authorId: me.id } }),
+		grant("signedIn", ["create", "update", "delete"], "Note", {
+			where: { authorId: me.id },
+		}),
+		// "*" also reaches the Better Auth tables `resources` opens (session, account).
+		grant("admin", "read", "*", { fields: ["User.email"] }),
+	])
+	.denies(({ deny }) => [
+		deny("*", "*", { if: { claims: { banned: true } } }),
+		deny("delete", "*", { if: { origin: "agent" } }),
+	]);
+```
+
+Then `createAccess({ betterAuth, policies: { rules, claims }, principal, resources: { users: true } })` in
+`src/access.ts`, and `access` in the framework's configuration ([setup](reference/setup.md)).
+
+## Before you finish
+
+- `npx tsc --noEmit` passes with no casts added.
+- The server starts. An `AccessError` names its `code` and says what to change; fix that and start again.
+- After a schema change: `npx auth@~1.7.12 generate --config src/access.ts --yes` (when Better Auth's tables changed), the
+  migration, then `npm run aventara:prepare`, so the rules see the new model.
+- A request you expect to be refused answers `403 A4002`, and one you expect to work does: try both, signed in and
+  signed out.
+
+This skill ships in the package at `node_modules/@aventara/access/skill/`. Copy the folder into your agent's skills
+folder (for example `.claude/skills/aventara-access/`), or point your agent at it; copy it again after upgrading Access.

package/skill/reference/callers.md

@@ -0,0 +1,99 @@
+# Callers: signed out, signed in, cached, agents, the UI
+
+## Who the caller is
+
+| The request carries | `ctx.$state.me` | Rules that match |
+|---|---|---|
+| Nothing (no `Authorization`, no session cookie) | `null` | `anyone` grants only |
+| A valid bearer token, or a live session cookie (from any site on a `GET`, `HEAD` or `OPTIONS` read; on a write, only from a site Better Auth trusts) | `principal(identity)`, or the identity | `signedIn`, `anyone`, and the roles it holds |
+| A bearer token that does not verify (tampered, expired, another issuer, not a token) | `null` | `anyone` grants only; the cookie is not tried |
+| A session cookie on a write (on every request, with `sameSite: "none"`) from a site Better Auth does not trust | `null` | `anyone` grants only |
+| `principal` returned `null` (a user your app does not know) | `null` | `anyone` grants only |
+| An agent's OAuth access token on the MCP endpoint | the user's principal, held to the token's scopes | the user's own, under origin `agent` |
+
+The anonymous caller is `null`: it holds no role, has no claims and lacks every `me` value.
+
+- A grant that reads `me` (`where: { authorId: me.id }`) never matches for it.
+- A deny that reads `me` in its `where` matches for it: such a deny refuses the anonymous caller on its actions. Put a
+  deny that reads `me` only on actions the anonymous caller has no grant for anyway, or accept that it closes them.
+- A deny's `if` comparing a claim with `true` (`banned: true`) never holds for it, so a ban leaves `anyone` grants
+  open. Any other comparison (`tier: "trial"`, `banned: false`) holds for it, and refuses it.
+
+So: a signed-out caller reads exactly what `anyone` grants show, and nothing else is allowed. A refused request answers
+`403 A4002`. Without any `anyone` grant, every signed-out request is refused.
+
+## Cached reads
+
+The framework's `cache({ for, maxAge })` stage serves a read as a `GET` a browser or a CDN may keep. Put it on the
+`find` family or one of its variants, in a `defineResource` block or at the root or client layer:
+
+```text
+// src/resources/campaign.resource.ts
+import { cache, defineResource } from "@aventara/core";
+import type { AvModel } from "../generated/aventara/discovery.artifact.js";
+
+export const campaign = defineResource<AvModel>()("Campaign", {
+  operations: {
+    find: { many: { pipelines: { cache: cache({ for: "anonymous", maxAge: 60 }) } } },
+  },
+});
+```
+
+Always write `for`. Under Access:
+
+| `for` | Signed out (`me` is `null`) | Signed in | Use it when |
+|---|---|---|---|
+| `"user"` (the default) | `private` | `private`, per caller | The rows or fields differ by caller. The safe choice. |
+| `"anonymous"` | `public`: one answer every signed-out caller may share | `private` | Signed-out callers all see the same public rows (an `anyone` grant) and signed-in callers may see more |
+| `"everyone"` | `public` | `public`: one answer for every caller | Only when every caller gets byte-identical rows and fields: the Resource has `anyone` read grants only (no `signedIn`, role or `"*"` read grant reaches it, an admin's included), no `where` reads `me`, nothing governed is opened, and no read deny can match some callers. If any other read grant reaches the Resource, use `"anonymous"` |
+
+- Under `"anonymous"`, `public` goes only to a caller Access finds no one in: a valid session cookie or bearer token
+  gets `private` with `Vary: Authorization, Cookie`, and a token that verifies to no one gets the signed-out answer.
+  Under `"everyone"`, every caller's answer is `public` with no `Vary`: a shared cache may hand one caller's answer to
+  any other.
+- A refusal (`A4002`) is `no-store`: no one keeps it.
+- A cached answer is served by the browser or CDN without asking Access again until `maxAge` passes. Under
+  `"everyone"`, that includes callers a deny would have refused (a banned user) and callers who sign out: use it only for
+  data that is public by design, and keep `maxAge` short where a change must show at once.
+- `"anonymous"` on a Resource with no `anyone` grant caches nothing public: every signed-out read is refused, and a
+  refusal is never kept.
+
+## Agents over MCP
+
+Better Auth's OAuth provider issues the agent's token; Access reads it. Configure `mcp: { resource }` in
+`createAccess` (with `oauthProvider()` in `betterAuth.plugins`, its `scopes` including `aventara:read` and
+`aventara:write`, its `resources` including the MCP endpoint) and give the framework
+`mcp: { path: "/mcp", authorization: access.mcp }`.
+
+- An agent acts as its user, under origin `agent`: `aventara:read` admits reads, `aventara:write` admits writes, and
+  a scope never grants what the user's own grants do not. Refusals are audited as `deny:mcp-scope` or
+  `deny:mcp-audience`.
+- The token opens the MCP endpoint only: under any other origin it is refused everything, and Access's `GET /me`
+  answers it `null`.
+- The user's claims are read on every agent request, so a ban reaches the agent on its next call.
+- Narrow agents further with origin denies: `deny("delete", "*", { if: { origin: "agent" } })`.
+- `agentOf(me)` (from `@aventara/access/auth` or `/better-auth`) answers `{ clientId, scopes }` for an agent's
+  principal and `null` otherwise.
+- Access refuses an OAuth provider setup that would weaken the agent's authorization (opaque tokens, open dynamic
+  registration without `mcp: { resource, openRegistration: true }`, a refresh reuse window, the endpoint missing from
+  its `resources`, and more) with `ACCESS_OPTIONS_INVALID`. Read the message; do not work around it. An opt-in a
+  message names (`openRegistration`, `insecureLan`, `claimsOf`) weakens security: ask the developer before setting it;
+  never set it just to get past the error.
+
+The README's "Agents over MCP" section has the full provider setup and the per-service `audience` option.
+
+## Server code
+
+A `framework.application.*` call is not checked unless it names a principal: `{ as: me }` checks it as that caller
+(`null` is the anonymous one). See [setup](setup.md#server-code-runs-unchecked-unless-it-names-a-principal).
+
+## Asking from the UI
+
+`can` only shapes the page; the real request is still checked.
+
+- The framework's generated client has `$access.can(...)` when the app is configured with `access`, answered by
+  `POST {api}/_access/can` with the engine that decides the real requests. With `createAccess`, `$access` also has
+  the verbs `signIn`, `signUp`, `signOut`, `resetPassword` and `me` (a verb the instance does not serve is left out).
+- With the Better Auth plugin, `aventaraAccessClient({ api: "/api" })` adds `authClient.access.can([...])`: one request
+  for a list of questions, one boolean each. A question with `where` asks about one row by its unique where; a row the
+  user cannot read answers `false`, as a missing one does.

package/skill/reference/errors.md

@@ -0,0 +1,89 @@
+# Errors, refusals and warnings
+
+## On a refused request
+
+A request the policy refuses answers `403` with code `A4002` (the framework's `AvAuthError` class in server code). `cause.message` names
+what was refused. Check, in this order:
+
+1. Is there a grant for this caller's role, this action and this Resource? Nothing is allowed until one allows it.
+2. Does a deny match? Any deny wins, an admin's grants included. A deny that reads a claim or `me` value the caller
+   lacks matches (it fails closed). Exception: for the anonymous caller, a deny's `if` comparing a claim with `true`
+   (`banned: true`) never holds, so it never closes an `anyone` grant.
+3. Is the caller who you think? A present but invalid `Authorization` header gives `me: null` and the cookie is not
+   tried. A cookie on a write from an untrusted origin is not read.
+4. Does the request select, filter or sort by a field governed for reading (`"read"`, `"both"` or the list form) that
+   no grant opens, or a sealed secret column? Does a create or update set a field governed for writing (`"write"`,
+   `"both"`, the list form, or Better Auth's `role`, which Access governs as `"write"`) that the grant does not name?
+   That is refused, not dropped.
+5. Is the Resource one of Better Auth's tables? Closed until `resources` opens it, and Access's own tables never open.
+6. Does a create or update send a reference (`authorId`) to a row the caller cannot read? Grant read on the target.
+7. Does an update move the row out of what its grant covers (`where` checked on the new row, `after`)? That is
+   refused and rolled back.
+
+In development, `await engine.explain(question)` (on `access.policy`) lists each rule's part in a `can` decision; it
+throws when `NODE_ENV` is `production`. In production, turn on `audit`: a decision's `reason` names the rule.
+
+## Framework codes Access causes
+
+| Code | Status | Meaning |
+|---|---|---|
+| `A4002` | 403 | The policy refused: no grant, a deny, a governed or sealed field, a closed table, an unreadable reference, or the row an update leaves |
+| `A2003` | 404 | A unique read, update or delete matched no row the caller may read. A row outside the caller's read scope answers as missing, so the answer does not reveal that it exists |
+| `A3000` | 500 | A scope or an `exists` question compares a `datetime`, `decimal` or `bigint` field (not usable through Aventara yet); or the engine refused to run (for example beacons not checked). Read the server log |
+| `A3001` | 500 | The database failed while answering an `exists` question |
+
+## `AccessError` codes
+
+Thrown by `createAccess`, its instance, `aventaraAccess()`, `accessOf(auth)`, the registry and the engine. Branch on
+`error.code` (`AccessErrorCode`); the message starts `Aventara Access:` and says what to change.
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `ACCESS_BETTER_AUTH_VERSION` | `better-auth` missing or outside `~1.7.12`; under `mcp` or `audience`, the OAuth provider or `cimd()` outside it | `npm i better-auth@~1.7.12` (and the provider packages in the same range) |
+| `ACCESS_CLAIMS_UNDECLARED` | The rules or guardrails read a claim, or a token carries one, that `policies.claims` does not declare | Declare it in `policies.claims` |
+| `ACCESS_PLUGIN_DUPLICATE` | `jwt()` or `aventaraAccess()` in `createAccess`'s `betterAuth.plugins`; a second Access plugin; one `aventaraAccess()` in two different Better Auth instances; a plugin defining `jwt()`'s endpoints or Access's routes | Remove it: Access installs it |
+| `ACCESS_OPTIONS_INVALID` | An option Access does not take or refuses as unsafe: no base URL; a claim read from a field without `input: false`; a grant on a Better Auth table `resources` leaves closed; `passwords` beside your own `emailAndPassword.password`; Node.js 22 without `@node-rs/argon2`; a `principal` object shared by two users; `sameSite: "none"` without `trustedOrigins`; an organization plugin without `requireEmailVerificationOnInvitation: true`; an OAuth provider setup that weakens agents; off Prisma's adapter without `resources.authTables` | Follow the message. Never loosen the setting it names to get past it. An opt-in the message names (`openRegistration`, `insecureLan`, `claimsOf`) weakens security: ask the developer before setting it; never set it just to get past the error |
+| `ACCESS_RESOURCE_MISSING` | A table `resources` opens is missing from Better Auth (plugin not installed) or from the rules' schema; the organization bridge without `organization()` | Add the plugin, or run `npx auth@~1.7.12 generate --yes`, migrate, `aventara:prepare` |
+| `ACCESS_QUESTION_INVALID` | A `fieldsOf` question without `access: "read"` or `"write"`, or with an `action` that does not fit | Ask `{ access: "read" }`, or `{ access: "write", action? }` |
+| `ACCESS_LOCK_MISMATCH` | A pulled file no longer hashes to its pin in `avAccess.lock.json`, files the lock does not pin, or `requireLock` with no lock | `avaccess pull` again; never edit a pulled file |
+| `ACCESS_KEY_REFUSED` | A registry key 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 grants on a Resource another namespace owns or the operator has not assigned it, or guardrails that grant (`403`) | Grant only on your own Resources |
+| `ACCESS_POLICIES_INVALID` | A pushed file the engine would not run from (`400`), or over 1 MiB (`413`) | Push the `.contract()` of your rules |
+| `ACCESS_NAMESPACE` | A namespace name that is not one, unknown, or already taken | Check the name |
+| `ACCESS_REVISION_CHANGED` | A stored revision changed outside the registry (`500`) | Restore the registry's tables; push again |
+| `ACCESS_FOREIGN_CROSS_DATABASE` | The rules read another namespace's Resources as foreign from another database (`403`) | Use the owner's database, or carry the fact in a claim |
+| `ACCESS_BEACON_MISMATCH` | The ownership beacon check failed or was not awaited at startup (`409` at push) | Point the service at the owner's database; `await access.policy.checkBeacons(...)` before serving |
+
+The last six belong to the registry and multi-service setups; the README's "The registry and avaccess" section covers
+them.
+
+## Warnings
+
+Node.js warnings (type `AventaraAccessWarning`), printed when the framework starts with the engine, once per process and namespace.
+They change no decision, but each points at a write that will be refused or a link that is not checked.
+
+| Code | Meaning | Fix |
+|---|---|---|
+| `ACCESS_READ_GOVERNED_UNIQUE` | A field governed as `"read"` is unique (one of its Resource's identifiers): a write that sends a value another row holds fails on the duplicate, which tells the writer the value exists | Govern it as `"both"`, or accept that writers learn which values exist |
+| `ACCESS_REFERENCE_UNREADABLE` | A role may create or update a reference to a Resource no read grant reaches for it; each such write is refused `A4002`. Names `resources: { users: true }` when the target is a closed Better Auth table | Grant that role read on the target (narrowed by `where`), or lock the reference with `write: { except }` |
+| `ACCESS_FOREIGN_REFERENCE_UNCHECKED` | A create or update grant may link any row of a foreign Resource by its identifier | Constrain the link through the relation: a `where` on the create grant, an `after` on the update grant |
+
+## Better Auth's answers on Access's routes
+
+| Answer | Meaning |
+|---|---|
+| `403 MISSING_OR_NULL_ORIGIN`, `403 INVALID_ORIGIN` | A request with a cookie needs an `Origin` matching `BETTER_AUTH_URL` or `trustedOrigins` |
+| `400 PASSWORD_TOO_LONG` | Longer than `emailAndPassword.maxPasswordLength` (128 by default) |
+| `429 TOO_MANY_REQUESTS` | Better Auth's rate limit, or Access's per-account limit on server-side sign-in calls |
+| `404` on `/sign-in/*`, `/sign-up/*` | The `service` profile: it hands no caller a session |
+
+## Audit reasons
+
+| `reason` | Meaning |
+|---|---|
+| `grant:<id>` | A grant allowed it |
+| `deny:<id>` | A deny matched |
+| `deny:guardrail:<id>` | An org guardrail matched |
+| `deny:better-auth:<Resource>` | A Better Auth table is closed (`…/<actions>`: a write an opened table never takes) |
+| `deny:mcp-scope`, `deny:mcp-audience` | An agent's token lacks the scope, or was used outside the MCP endpoint |
+| `no grant` | Nothing allowed it |

package/skill/reference/recipes.md

@@ -0,0 +1,281 @@
+# Recipes
+
+Complete rules for the common tasks, type-checked against a schema of `User`, `Campaign`, `Member` (`userId`,
+`campaignId`, `role`: `DM` or `PLAYER`), `Note` (`authorId`, `campaignId`, `body`, `visibility`: `PARTY`, `PRIVATE`
+or `DM_ONLY`) and `Character` (`ownerId`, `campaignId`, `name`). Rename to your own Resources and fields; the compiler
+names every key that does not exist.
+
+## A whole rule set
+
+```ts
+// src/campaign.policies.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+/** The request's principal: the signed-in user and the token's claims. Anonymous is `null`. */
+export type Principal = {
+	id: string;
+	claims: { role?: "admin"; banned?: boolean; suspended?: boolean };
+};
+
+export const campaignPolicies = definePolicies(model)
+	.principal<Principal>()
+
+	.roles(({ me }) => ({
+		// A site-wide role, from a claim only the server can set.
+		admin: { global: { claims: { role: "admin" } } },
+		// Roles held on a row: the caller's membership of a campaign.
+		dm: {
+			on: "Campaign",
+			where: { members: { some: { userId: me.id, role: "DM" } } },
+		},
+		player: {
+			on: "Campaign",
+			where: { members: { some: { userId: me.id, role: "PLAYER" } } },
+		},
+	}))
+
+	// Out of every default read and write: only a grant that names it opens it.
+	.govern("User", ["email"])
+	// The row roles read a member's role: everyone who reads the row sees it, and
+	// only a grant that names it changes it.
+	.govern("Member", { role: "write" })
+
+	.grants(({ grant, me }) => [
+		// People: yourself, and the people you share a campaign with. A note's author,
+		// a character's owner and a member's user are references to User, so writing
+		// them needs read on that User row. Campaign-mates read every User field not
+		// governed: govern any they should not see (a role, a ban).
+		grant("signedIn", "read", "User", {
+			where: {
+				OR: [
+					{ id: me.id },
+					{ members: { some: { campaign: { members: { some: { userId: me.id } } } } } },
+				],
+			},
+		}),
+		// Your own email, and nobody else's.
+		grant("signedIn", "read", "User", { where: { id: me.id }, fields: ["User.email"] }),
+
+		// Campaigns: members read them, the DM changes them.
+		grant(["dm", "player"], "read", "Campaign"),
+		grant("dm", ["update", "delete"], "Campaign"),
+
+		// Membership: the DM seats and removes players, and may change a seat's role,
+		// never who sits in it or which campaign it belongs to. The role is governed
+		// for writing, so the DM's grants name it.
+		grant(["dm", "player"], "read", "Member", { in: "campaign" }),
+		grant("dm", ["create", "delete"], "Member", {
+			in: "campaign",
+			fields: ["Member.role"],
+		}),
+		grant("dm", "update", "Member", {
+			in: "campaign",
+			write: { except: ["userId", "campaignId"] },
+			fields: ["Member.role"],
+		}),
+
+		// Notes: the author keeps their own; a player writes as themselves only and
+		// reads the party's; the DM reads, edits and removes every note of their
+		// campaign, writes as themselves only, and never changes who wrote a note.
+		grant("signedIn", ["read", "update", "delete"], "Note", { where: { authorId: me.id } }),
+		grant("player", "read", "Note", { in: "campaign", where: { visibility: "PARTY" } }),
+		grant("player", "create", "Note", { in: "campaign", where: { authorId: me.id } }),
+		grant("dm", ["read", "delete"], "Note", { in: "campaign" }),
+		grant("dm", "create", "Note", { in: "campaign", where: { authorId: me.id } }),
+		grant("dm", "update", "Note", { in: "campaign", write: { except: ["authorId"] } }),
+
+		// Characters: a player keeps their character and moves it only to a campaign
+		// they play in (`after` holds the row the update leaves).
+		grant(["dm", "player"], "read", "Character", { in: "campaign" }),
+		grant("player", "create", "Character", { in: "campaign", where: { ownerId: me.id } }),
+		grant("signedIn", "update", "Character", {
+			where: { ownerId: me.id },
+			after: { ownerId: me.id, campaign: { $role: "player" } },
+		}),
+
+		// The admin reads everything, emails included, and changes nothing. "*" also
+		// reaches the Better Auth tables `resources` opens (session, account).
+		grant("admin", "read", "*", { fields: ["User.email"] }),
+	])
+
+	.denies(({ deny }) => [
+		// A banned user does nothing, whatever the grants say. A token without the
+		// claim is refused too: a missing claim fails closed.
+		deny("*", "*", { name: "banned", if: { claims: { banned: true } } }),
+		// A suspended user reads but writes nothing.
+		deny(["create", "update", "delete"], "*", {
+			name: "suspended-read-only",
+			if: { claims: { suspended: true } },
+		}),
+		// An AI agent never deletes, even for a user who may.
+		deny("delete", "*", { name: "no-agent-deletes", if: { origin: "agent" } }),
+		// DM-only notes stay the DM's, even for their author.
+		deny(["read", "create", "update"], "Note", {
+			name: "dm-only-notes",
+			where: { visibility: "DM_ONLY", NOT: { campaign: { $role: "dm" } } },
+		}),
+	]);
+```
+
+What each pattern does:
+
+| Pattern | Rule |
+|---|---|
+| Owner only | `where: { authorId: me.id }` on every action. On `update` it is checked on the row the update leaves too, so the owner cannot hand the row away. On `create` the caller cannot write as someone else. |
+| Membership role | A row role `on: "Campaign"`, then `{ in: "campaign" }` on grants of the Resources that belong to a campaign |
+| Field lock | `write: { except: [...] }`: a relation and its reference fields are locked together |
+| Moving a row | `after` on an update grant: what the new row must also meet |
+| Sensitive field | `.govern` + a grant with `fields`, narrowed by `where` |
+| A field a role reads | `.govern(Resource, { field: "write" })`: read as any field, written only by a grant naming it |
+| Global role | `global: { claims }`, from a claim declared in `policies.claims` and read from an `input: false` field |
+| Deny by claim | `if: { claims: { banned: true } }`: compare with the value that means "refuse", so a missing claim refuses too |
+| Deny by origin | `if: { origin: "agent" }` (MCP), `"client"` (a user's request) or `"application"` (server code that names a principal) |
+| Deny by row | `where` on the deny, with `NOT` and `$role` for "unless the caller holds this role here" |
+
+Campaign creation is left out above: a new campaign has no members, so no row role covers it yet. Grant
+`grant("signedIn", "create", "Campaign")` and seat the creator as its DM from server code in the same transaction, taking the
+creator's id from `ctx.$state.me`, never from the request arguments (the framework's own skill covers hooks and
+`forceTransaction`).
+
+## A field written and never read back
+
+A government id, a tax number or a stored secret is written by the people who fill in a form and read back by almost
+nobody. Govern it as `"read"`: every grant that may write the row writes it, and only a read grant that names it reads
+it. On a schema with a `Citizen` Resource whose `nationalId` holds the id:
+
+```text
+.govern("Citizen", { nationalId: "read" })
+.grants(({ grant, me }) => [
+  // Each user registers and edits their own record, id number included.
+  grant("signedIn", ["read", "create", "update"], "Citizen", { where: { userId: me.id } }),
+  // Only the registrar reads the number back.
+  grant("registrar", "read", "Citizen", { fields: ["Citizen.nationalId"] }),
+])
+```
+
+A read that names `nationalId` without the registrar's grant is refused `A4002`, the owner's own included, and a
+default read leaves it out. Keep it out of filters and sorts too: they need read access to the field on every row they
+touch. If the field is unique, a write that sends a number another row holds fails on the duplicate, which tells the
+writer that number is taken; Access warns `ACCESS_READ_GOVERNED_UNIQUE`. Govern a unique field as `"both"` instead, so
+only a grant that names it writes it.
+
+## Public reads for signed-out callers
+
+```ts
+// src/public.policies.ts
+import { definePolicies } from "@aventara/access";
+import { model } from "./generated/aventara/discovery.artifact.js";
+
+export type Visitor = { id: string; claims: { banned?: boolean } };
+
+export const publicPolicies = definePolicies(model)
+	.principal<Visitor>()
+	.govern("User", ["email"])
+	.grants(({ grant, me }) => [
+		// Wide: anyone, signed out included, reads every campaign and every field not
+		// governed (here `id` and `name`). On your schema, narrow it with a `where` on
+		// a public flag and govern every field that is not public.
+		grant("anyone", "read", "Campaign"),
+		// Signed-in users read their own profile.
+		grant("signedIn", "read", "User", { where: { id: me.id } }),
+	])
+	// A ban is a comparison with true, which never holds for the anonymous caller,
+	// so it does not close the public grant; it does refuse a banned user.
+	.denies(({ deny }) => [deny("*", "*", { if: { claims: { banned: true } } })]);
+```
+
+Narrow a public grant to the rows that are public with a `where` on a flag the owner sets (`where: { published:
+true }`), and govern every field that is not. Do not compare `me` in an `anyone` grant's `where`: the anonymous caller
+lacks every `me` value, so such a grant never matches for them. Give the read `cache({ for: "anonymous" })` to let a CDN
+keep the signed-out answer ([callers](callers.md#cached-reads)).
+
+## Checking the rules before you ship
+
+```ts
+// scripts/rules.check.ts
+import assert from "node:assert/strict";
+import type { AccessExists } from "@aventara/access";
+import { campaignPolicies, type Principal } from "../src/campaign.policies.js";
+
+const engine = campaignPolicies.engine();
+// A principal carries every boolean claim the denies compare, as Access's tokens do:
+// one left out reads as missing, and the deny that compares it then refuses.
+const ada: Principal = { id: "ada", claims: { banned: false, suspended: false } };
+const banned: Principal = { id: "bo", claims: { banned: true, suspended: false } };
+
+// Signed out: no grant names `anyone`, so nothing is allowed.
+assert.equal(
+	await engine.can({ principal: null, origin: "client", resource: "Note", action: "read" }),
+	false,
+);
+// A banned user is refused what a grant would allow.
+assert.equal(
+	await engine.can({
+		principal: banned,
+		origin: "client",
+		resource: "Note",
+		action: "update",
+		row: { id: "n1", campaignId: "c1", authorId: "bo", body: "", visibility: "PRIVATE" },
+	}),
+	false,
+);
+// The role grants ask the database whether the caller holds a role on a row
+// (`exists`, through your ORM). Here ada holds none: every lookup answers false.
+// Without `exists`, a rule that needs one is unknown, and the engine refuses.
+const noRoles: AccessExists = async () => false;
+// The author may update their own note, and may not hand it to someone else.
+const note = { id: "n2", campaignId: "c1", authorId: "ada", body: "", visibility: "PRIVATE" };
+assert.equal(
+	await engine.can({
+		principal: ada,
+		origin: "client",
+		resource: "Note",
+		action: "update",
+		row: note,
+		exists: noRoles,
+	}),
+	true,
+);
+assert.equal(
+	await engine.can({
+		principal: ada,
+		origin: "client",
+		resource: "Note",
+		action: "update",
+		row: { ...note, authorId: "olive" },
+		before: note,
+		exists: noRoles,
+	}),
+	false,
+);
+// An agent never deletes.
+assert.equal(
+	await engine.can({ principal: ada, origin: "agent", resource: "Note", action: "delete", row: note }),
+	false,
+);
+// Which fields a signed-in user sees on User: email only on their own row.
+console.log(engine.fieldsOf({ principal: ada, origin: "client", resource: "User", access: "read" }));
+```
+
+Run it with `npx tsx scripts/rules.check.ts`. A row question that a relation decides (a role held on a row, a
+`where` through a relation) needs `exists`; give it one that answers from your test data, or through your ORM. In
+development, `await engine.explain(question)` lists each rule's part in a `can` decision, with `"unknown"` for a rule
+it could not decide.
+
+## The organization bridge (Better Auth's organization plugin)
+
+With `aventaraAccess({ organization: { claim: "orgRole", organizationClaim: "org", roles: [["owner", "admin"],
+["admin", "admin"], ["member", "member"]] } })`, declare both claims as `"string"`, copy `org` onto the principal, and
+hold every grant to it:
+
+```text
+.roles(() => ({ orgAdmin: { global: { claims: { orgRole: "admin" } } } }))
+.grants(({ grant, me }) => [
+  grant("signedIn", "read", "Campaign", { where: { organizationId: me.org } }),
+  grant("orgAdmin", ["create", "update", "delete"], "Campaign", { where: { organizationId: me.org } }),
+])
+```
+
+An organization role is that organization's, but a global role is global: without `organizationId: me.org`, an admin
+of one organization would act on every organization's rows. A principal without `org` matches no such grant.