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

package/dist/access/request.state.js

@@ -20,7 +20,7 @@
 import { decodeProtectedHeader } from "jose";
 import { mayChange, SESSION_USE } from "../kiosk/session-use.marker.js";
 import { hasAventaraScope, withGrant, } from "../mcp/agent.grant.js";
-import { carrySubject } from "./principal.subject.js";
+import { carrySubject, claimReturned } from "./principal.subject.js";
 import { readsSessionCookie, } from "./profile.policy.js";
 import { isAccessTokenType } from "./token.verifier.js";
 const bearerOf = (headers) => /^Bearer[ \t]+([^ \t]+)[ \t]*$/i.exec(headers.get("authorization") ?? "")?.[1];
@@ -166,20 +166,90 @@ export const requestState = (identityOf, principal) => {
     return async ({ headers, request }) => {
         const caller = await identityOf(headers, request);
         if (caller === null) {
-            return { me: null };
+            return stateOf(null);
         }
         const { grant } = caller;
         const identity = grant === undefined
             ? caller.identity
             : withGrant(caller.identity, grant);
         const mapped = principal === undefined ? identity : await principal(identity);
-        const me = grant === undefined ? mapped : withGrant(mapped, grant);
+        // One object handed out for two users is refused (a cache keyed wrongly would
+        // serve one as the other), without writing to it.
+        claimReturned(mapped, identity.sub);
+        // A copy of the plain data: the app's own objects are never frozen.
+        const made = new Map();
+        const copied = plainCopy(mapped, made);
+        const me = grant === undefined ? copied : withGrant(copied, grant);
+        // Access's own objects: the copies, and the one `withGrant` makes. A value the
+        // app returned that is not plain data (a class instance, a `Map`) is `me` as given.
+        const ours = typeof me === "object" &&
+            me !== null &&
+            (grant !== undefined || made.get(mapped) === me);
         // The `sub` travels with `me`: whichever instance the host asks for the
         // policy (under Next, another bundle's) reads it for the audit's `userId`.
-        carrySubject(me, identity.sub);
-        return { me: me ?? null };
+        carrySubject(me, identity.sub, ours);
+        for (const copy of made.values()) {
+            Object.freeze(copy);
+        }
+        if (ours) {
+            Object.freeze(me);
+        }
+        return stateOf(me ?? null);
     };
 };
+/**
+ * The state over `me`: `me` is a non-writable member of the state, and nothing of
+ * its plain data changes once it is derived, so no code that runs during the request
+ * (a pipeline, a hook, a computed field) can make the policy see another principal.
+ */
+const stateOf = (me) => Object.defineProperty({}, "me", {
+    value: me,
+    enumerable: true,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Plain data: an array, or an object made by `{}`, JSON or `Object.create(null)`. A
+ * class instance is not: its `#private` fields cannot be copied, so it is kept as
+ * the app gave it, as a `Map` is.
+ */
+const isPlainData = (value) => {
+    const prototype = Object.getPrototypeOf(value);
+    return Array.isArray(value)
+        ? prototype === Array.prototype
+        : prototype === Object.prototype || prototype === null;
+};
+/**
+ * A copy of `value`'s plain data, all the way down: each array and plain object (on
+ * the same prototype), with every own property, its non-enumerable and symbol-keyed
+ * ones included. `made` maps each original to its copy (so a cycle stays one).
+ * Anything else (a primitive, a class instance, a `Map`, a `Set`, a `Date`, a typed
+ * array, a function) is kept as the app gave it, and so is a getter.
+ */
+const plainCopy = (value, made) => {
+    if (typeof value !== "object" || value === null || !isPlainData(value)) {
+        return value;
+    }
+    const done = made.get(value);
+    if (done !== undefined) {
+        return done;
+    }
+    const copy = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    made.set(value, copy);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined) {
+            continue;
+        }
+        if ("value" in descriptor) {
+            descriptor.value = plainCopy(descriptor.value, made);
+        }
+        Object.defineProperty(copy, key, descriptor);
+    }
+    return copy;
+};
 /**
  * Refuses a token for a session the store no longer has (revoked, signed out,
  * expired): with Better Auth's cookie cache on, a session read from its cookie may

package/dist/access-warning.emitter.d.ts

@@ -1,2 +1,4 @@
+/** `names` as a warning lists them: `a`, `a and b`, `a, b and c`. */
+export declare const listed: (names: readonly string[]) => string;
 /** Emits `message` under `code`, once per process and `namespace`. */
 export declare const emitAccessWarning: (code: string, namespace: string | undefined, message: string) => void;

package/dist/access-warning.emitter.js

@@ -3,6 +3,10 @@
 // with `--disable-warning=<code>`), else `console.warn`. Each message is emitted
 // once per process and namespace, however many Frameworks host the rules.
 const emitted = new Set();
+/** `names` as a warning lists them: `a`, `a and b`, `a, b and c`. */
+export const listed = (names) => names.length < 2
+    ? names.join("")
+    : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
 /** Emits `message` under `code`, once per process and `namespace`. */
 export const emitAccessWarning = (code, namespace, message) => {
     const key = `${code}\u0000${namespace ?? ""}\u0000${message}`;

package/dist/access.builder.d.ts

@@ -22,9 +22,36 @@ export type AccessMe<P> = {
 type Simplify<T> = {
     [K in keyof T]: T[K];
 } & {};
+/** A field's `govern` mode: governed for writing only, reading only, or both. */
+type GovernMode = "read" | "write" | "both";
+/** The `govern` block, by Resource: a mode per governed field (the list form governs each for "both"). */
 type GovernedShape = {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: {
+        readonly [field: string]: GovernMode;
+    };
+};
+/** One Resource's governed fields, whatever their mode. */
+type GovernedFieldOf<G> = keyof G & string;
+/** `govern(R, fields)` added to the block, as a mode per field. */
+type Governing<Gov, R extends string, New> = Simplify<{
+    readonly [K in keyof Gov as K extends R ? never : K]: Gov[K];
+} & {
+    readonly [K in R]: K extends keyof Gov ? Simplify<Gov[K] & New> : New;
+}>;
+/**
+ * The object form's check, at each key: a field of the Resource, not governed
+ * already in another mode. The type at a wrong key is the sentence that says what
+ * to change.
+ */
+type CheckedModes<Field extends string, R extends string, Prior, M> = {
+    readonly [K in keyof M]: K extends Field ? M[K] extends GovernMode ? K extends keyof Prior ? Prior[K] extends M[K] ? M[K] : `Error: "${R}.${K & string}" is already governed as "${Prior[K] & string}"; govern each field once, with one mode` : M[K] : `Error: "${R}.${K & string}" takes a mode, "read", "write" or "both"` : `Error: "${R}" has no field "${K & string}"`;
+};
+/** The list form's check: a field governed already in a mode other than "both" is the sentence that says so. */
+type CheckedList<R extends string, Prior, F> = {
+    readonly [I in keyof F]: F[I] extends keyof Prior ? Prior[F[I]] extends "both" ? F[I] : `Error: "${R}.${F[I] & string}" is already governed as "${Prior[F[I]] & string}"; govern each field once, with one mode` : F[I];
 };
+/** The modes `Gov` already gives Resource `R`'s fields; none when it is not governed. */
+type PriorModes<Gov, R> = R extends keyof Gov ? Gov[R] : unknown;
 /** A row role as the builder's type records it: the Resource it is held on. */
 type RoleShape = {
     readonly on: string;
@@ -181,8 +208,8 @@ type InOption<S extends AccessSchema, R, Roles, Sub> = R extends ResourceOf<S> ?
  * says to govern one first, so naming a field reads as what to change.
  */
 type GovernedRef<Gov, R> = R extends "*" ? [keyof Gov] extends [never] ? "Error: no field is governed; govern one first, .govern(<Resource>, [<field>]), and a grant can then open it" : {
-    [K in keyof Gov]: `${K & string}.${Gov[K] extends readonly (infer F extends string)[] ? F : never}`;
-}[keyof Gov] : R extends keyof Gov ? `${R & string}.${Gov[R] extends readonly (infer F extends string)[] ? F : never}` : `Error: no field of "${R & string}" is governed; govern it first, .govern("${R & string}", [<field>]), and a grant can then open it`;
+    [K in keyof Gov]: `${K & string}.${GovernedFieldOf<Gov[K]>}`;
+}[keyof Gov] : R extends keyof Gov ? `${R & string}.${GovernedFieldOf<Gov[R]>}` : `Error: no field of "${R & string}" is governed; govern it first, .govern("${R & string}", [<field>]), and a grant can then open it`;
 type ResourceWhere<S extends AccessSchema, R, Roles> = R extends ResourceOf<S> ? AccessWhereInput<S, R, Roles> : never;
 /** The options of `grant(subjects, actions, resource, options)`. */
 export type AccessGrantOptions<S extends AccessSchema, Roles, Gov, R, Sub, A> = {
@@ -245,8 +272,12 @@ export type AccessDefinition = {
     readonly roles: {
         readonly [role: string]: unknown;
     };
+    /** Each `govern` call's fields, with their modes, in order: the compiler refuses a field given two. */
     readonly govern: {
-        readonly [resource: string]: readonly string[];
+        readonly [resource: string]: readonly {
+            readonly field: string;
+            readonly mode: GovernMode;
+        }[];
     };
     readonly grants: readonly AccessGrant[];
     readonly denies: readonly AccessDeny[];
@@ -263,10 +294,20 @@ export interface AccessBuilder<S extends AccessSchema, P, Roles extends {
     }>(definitions: (tools: {
         readonly me: AccessMe<P>;
     }) => D extends CheckedRoles<S, P, D> ? D : CheckedRoles<S, P, D>): AccessBuilder<S, P, Simplify<Roles & D>, Gov>;
-    /** Governed fields: out of every default projection; only a grant that names one opens it, and only when selected. */
-    govern<R extends OwnResourceOf<S>, const F extends readonly [AccessFieldOf<S, R>, ...AccessFieldOf<S, R>[]]>(resource: R, fields: F): AccessBuilder<S, P, Roles, Simplify<Gov & {
-        readonly [K in R]: F;
+    /**
+     * Governed fields: only a grant that names one opens it. A list governs each field
+     * for reading and writing: out of every default projection, and written by no grant
+     * that does not name it. An object gives each field a mode: `"write"` (read as any
+     * other field; written only through a grant that names it: a role your rules read),
+     * `"read"` (written as any other field; read only through a grant that names it: a
+     * government id) or `"both"` (as the list).
+     */
+    govern<R extends OwnResourceOf<S>, const F extends readonly [AccessFieldOf<S, R>, ...AccessFieldOf<S, R>[]]>(resource: R, fields: F extends CheckedList<R, PriorModes<Gov, R>, F> ? F : CheckedList<R, PriorModes<Gov, R>, F>): AccessBuilder<S, P, Roles, Governing<Gov, R, {
+        readonly [K in F[number]]: "both";
     }>>;
+    govern<R extends OwnResourceOf<S>, const M extends {
+        readonly [field: string]: string;
+    }>(resource: R, fields: keyof M extends never ? 'Error: name at least one field, { <field>: "read" | "write" | "both" }' : M extends CheckedModes<AccessFieldOf<S, R>, R, PriorModes<Gov, R>, M> ? M : CheckedModes<AccessFieldOf<S, R>, R, PriorModes<Gov, R>, M>): AccessBuilder<S, P, Roles, Governing<Gov, R, M>>;
     /** Grants. Default deny; any grant allows; order never matters. */
     grants(rules: (tools: {
         readonly grant: AccessGrantFunction<S, Roles, Gov>;

package/dist/access.builder.js

@@ -34,7 +34,16 @@ const builderOf = (definition) => ({
         ...definition,
         govern: {
             ...definition.govern,
-            [resource]: [...(definition.govern[resource] ?? []), ...fields],
+            [resource]: [
+                ...(definition.govern[resource] ?? []),
+                // The list form governs each field for both; the compiler checks the rest.
+                ...(Array.isArray(fields)
+                    ? fields.map((field) => ({
+                        field,
+                        mode: "both",
+                    }))
+                    : Object.entries(fields).map(([field, mode]) => ({ field, mode }))),
+            ],
         },
     }),
     grants: (rules) => builderOf({

package/dist/access.engine.d.ts

@@ -6,9 +6,16 @@ import { type AccessCanQuestion, type AccessFields, type AccessFieldsQuestion, t
 import type { AccessPolicies, AccessPoliciesJson } from "./policies-contract.js";
 import type { AccessLookup } from "./predicate.evaluator.js";
 import { type AuthTablesGuard } from "./resources/auth-tables.guard.js";
+/** The `govern` block, by Resource: the list form (each field for both) or a mode per field. */
 type GovernedShape = {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 };
+/** One Resource's fields governed for reading: its list, or its fields not `"write"`. */
+type ReadGoverned<G> = G extends readonly string[] ? G[number] : {
+    [F in keyof G]: G[F] extends "write" ? never : F;
+}[keyof G] & string;
 /** `explain`'s answer: the decision, each rule's part in it, and the `exists` lookups. */
 export type AccessExplanation = {
     readonly allowed: boolean;
@@ -25,8 +32,14 @@ export type AccessExplanation = {
 };
 /** The engine `access.engine()` and `createAccessEngine(policies)` return. */
 export interface AccessEngine<Governed extends GovernedShape = GovernedShape> {
-    /** The governed fields, by Resource: out of every default projection. */
-    readonly governed: Governed;
+    /**
+     * The fields governed for reading (`"read"`, `"both"` or the list form), by
+     * Resource: out of every default projection. A `"write"` field is read as any other
+     * field, so it is not here.
+     */
+    readonly governed: {
+        readonly [R in keyof Governed as [ReadGoverned<Governed[R]>] extends [never] ? never : R]: Governed[R] extends readonly string[] ? Governed[R] : readonly ReadGoverned<Governed[R]>[];
+    };
     /** Every relation path and operator each rule filters on, by rule id. */
     readonly paths: {
         readonly [rule: string]: readonly (readonly string[])[];

package/dist/access.engine.js

@@ -19,9 +19,10 @@ import { foreignOwnersOf, verifyLocked } from "./lock/lock.verifier.js";
 import { checkLock } from "./lock/lock-contract.js";
 import { checkPolicies, fail, isRecord } from "./policies.compiler.js";
 import { afterChecksOf, createDecider, fieldsQuestionProblem, grantsQuestionProblem, newTrace, } from "./policies.decider.js";
+import { warnReadGovernedUnique } from "./read-governed-unique.check.js";
 import { warnReferenceReads } from "./reference-reads.check.js";
-import { guardedFields, } from "./resources/auth-tables.guard.js";
-import { nullSafe, ownOf } from "./scope.resolver.js";
+import { guardedFields, withBuiltInRules, } from "./resources/auth-tables.guard.js";
+import { governedFor, nullSafe, ownOf, } from "./scope.resolver.js";
 const ENGINE_OPTIONS = new Set(["guardrails", "lock", "requireLock"]);
 /**
  * The engine's own copy of a file handed to it: what is checked and hashed is what
@@ -313,6 +314,7 @@ export const engineOf = (policies, options, source, observe, guard) => {
     // caller does to its objects afterwards reaches what the engine runs from.
     const own = copyOf("policies", policies);
     checkPolicies(own);
+    warnReadGovernedUnique(own);
     if (options !== undefined &&
         (!isRecord(options) ||
             Object.keys(options).some((key) => !ENGINE_OPTIONS.has(key)) ||
@@ -345,9 +347,7 @@ export const engineOf = (policies, options, source, observe, guard) => {
     // lock or without, they are read only once the beacons have passed.
     const owners = foreignOwnersOf(own);
     const guarded = guardrails === undefined ? own : composeGuardrails(own, guardrails);
-    const file = deepFreeze(guard === undefined || guard.denies.length === 0
-        ? guarded
-        : { ...guarded, denies: [...guarded.denies, ...guard.denies] });
+    const file = deepFreeze(guard === undefined ? guarded : withBuiltInRules(guarded, guard));
     if (file !== own) {
         checkPolicies(file, true);
     }
@@ -357,7 +357,7 @@ export const engineOf = (policies, options, source, observe, guard) => {
     // no other namespace), otherwise why the engine answers nothing yet.
     let refusal = owners.length === 0
         ? undefined
-        : `the rules read ${owners.map((owner) => `namespace "${owner}"'s`).join(" and ")} Resources as foreign, and the beacons were not checked: \`await engine.checkBeacons(reader, pins, environment)\` when the service starts, before it takes requests, with this environment's avAccess.beacons.<environment>.json`;
+        : `the rules read ${owners.map((owner) => `namespace "${owner}"'s`).join(" and ")} Resources as foreign, and the beacons were not checked: \`await access.policy.checkBeacons(beacon, beaconPins, environment)\` (\`engine.checkBeacons\` on an engine of your own) when the service starts, before it takes requests, with this environment's avAccess.beacons.<environment>.json`;
     // A failed check latches: no later check opens the engine again.
     let failed;
     // The checks, one after another.
@@ -374,11 +374,18 @@ export const engineOf = (policies, options, source, observe, guard) => {
             ? decider.fieldsOf(question)
             : guardedFields(guard, question, decider.fieldsOf(question), {
                 fields: ownOf(file.schema, question.resource)?.fields ?? [],
-                governed: ownOf(file.govern, question.resource) ?? [],
+                // What `"all"` stands for: every field reads do not govern.
+                governed: governedFor(file, question.resource, "read"),
             });
     };
+    // The seam's `governed`: the fields reads leave out. The built-in rules govern
+    // for writing only, so the file's own reads are the same.
+    const governed = deepFreeze(Object.fromEntries(Object.keys(file.govern).flatMap((resource) => {
+        const fields = governedFor(file, resource, "read");
+        return fields.length === 0 ? [] : [[resource, [...fields]]];
+    })));
     return {
-        governed: own.govern,
+        governed: governed,
         paths: deepFreeze(pathsOf(file)),
         afterChecks: deepFreeze(afterChecksOf(file)),
         unheld: Object.freeze(Object.entries(own.schema)
@@ -421,7 +428,7 @@ export const engineOf = (policies, options, source, observe, guard) => {
                 throw new AccessError("ACCESS_QUESTION_INVALID", "`hosted` takes `{ held }`, the list of Resource names the framework holds a written reference to");
             }
             const served = new Set(held);
-            warnReferenceReads(own, served);
+            warnReferenceReads(own, served, guard?.closed);
             warnForeignReferences(own, served);
         },
         explain: async (question) => {

package/dist/better-auth/access.provider.d.ts

@@ -2,7 +2,9 @@ import type { AccessEngine } from "../access.engine.js";
 import type { AccessMcpAuthorization } from "../mcp/mcp-options.js";
 import { type AccessRegistry } from "../registry/access.registry.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/cli/policies.diff.js

@@ -52,6 +52,24 @@ const byId = (rules) => new Map((rules ?? []).map((rule) => [
     String(rule.id),
     rule,
 ]));
+/**
+ * Each governed Resource as its fields' modes (`"both"` for a field `governModes`
+ * gives none), so a change of mode is named as the field it changes.
+ */
+const governOf = (file) => {
+    const govern = (file.govern ?? {});
+    const modes = (file.governModes ?? {});
+    return new Map(Object.entries(govern).map(([resource, fields]) => [
+        resource,
+        Object.fromEntries(fields.map((field) => [
+            field,
+            (Object.hasOwn(modes, resource) &&
+                Object.hasOwn(modes[resource] ?? {}, field)
+                ? modes[resource]?.[field]
+                : undefined) ?? "both",
+        ])),
+    ]));
+};
 /** The named changes from `before` to `after`, in the order of the file's parts. */
 export const diffPolicies = (before, after) => {
     const a = canonicalOf(before);
@@ -74,7 +92,7 @@ export const diffPolicies = (before, after) => {
         ...compareEntries("claim", byKey(a.claims), byKey(b.claims)),
         ...compareEntries("schema", byKey(a.schema), byKey(b.schema)),
         ...compareEntries("role", byKey(a.roles), byKey(b.roles)),
-        ...compareEntries("govern", byKey(a.govern), byKey(b.govern)),
+        ...compareEntries("govern", governOf(a), governOf(b)),
         ...compareEntries("grant", byId(a.grants), byId(b.grants)),
         ...compareEntries("deny", byId(a.denies), byId(b.denies)),
     ];

package/dist/foreign-references.check.d.ts

@@ -1,10 +1,4 @@
 import type { AccessPolicies } from "./policies-contract.js";
-/**
- * The warnings for `policies` hosted by a framework that serves the Resources in
- * `held`, one per writing role and foreign target, each naming every reference
- * that role may write to it unconstrained.
- */
-export declare const foreignReferenceWarnings: (policies: AccessPolicies, held: ReadonlySet<string>) => readonly string[];
 /**
  * Emits `policies`' warnings under a framework that serves the Resources in
  * `held`, each once per process and namespace.

package/dist/foreign-references.check.js

@@ -22,7 +22,7 @@
 // ACCESS_REFERENCE_UNREADABLE does, for the writing Resources the framework serves
 // (`held`). It warns and never refuses: the engine answers exactly as before. Not
 // warned about: a reference the grant's `write.except` locks.
-import { emitAccessWarning } from "./access-warning.emitter.js";
+import { emitAccessWarning, listed } from "./access-warning.emitter.js";
 import { ownOf } from "./scope.resolver.js";
 const WARNING_CODE = "ACCESS_FOREIGN_REFERENCE_UNCHECKED";
 /** Whether `predicate`, holding on a row, limits which row its `relation` links. */
@@ -61,15 +61,12 @@ const grantConstrains = (policies, grant, subject, resource, action, relation, f
     constrains(grant.where, relation, fields) ||
     (action === "update" && constrains(grant.after, relation, fields)) ||
     constrains(subjectRowCondition(policies, subject, resource), relation, fields);
-const listed = (names) => names.length < 2
-    ? names.join("")
-    : `${names.slice(0, -1).join(", ")} and ${names.at(-1)}`;
 /**
  * The warnings for `policies` hosted by a framework that serves the Resources in
  * `held`, one per writing role and foreign target, each naming every reference
  * that role may write to it unconstrained.
  */
-export const foreignReferenceWarnings = (policies, held) => {
+const foreignReferenceWarnings = (policies, held) => {
     const found = new Map();
     for (const grant of policies.grants) {
         const actions = grant.actions.filter((action) => action === "create" || action === "update");

package/dist/generator/prisma7/prisma-where.translator.d.ts

@@ -25,10 +25,11 @@ export declare const toPrismaWhere: (policies: AccessPolicies, resource: string,
 export declare const toPrismaScope: (policies: AccessPolicies, resource: string, scope: boolean | AccessWhere) => PrismaWhere;
 /**
  * A `fieldsOf` read answer as Prisma's `select`: the Resource's scalar fields a read
- * shows on every row. A governed field is selected only when the answer opens it on
- * every row; a field it opens on some rows only is left out, since a `select` cannot
- * depend on the row (ask `fieldsOf` for those). Relations are never selected: a
- * related row would not be scoped.
+ * shows on every row. A field governed for reading is selected only when the answer
+ * opens it on every row (one governed for writing only is read as any other); a
+ * field it opens on some rows only is left out, since a `select` cannot depend on
+ * the row (ask `fieldsOf` for those). Relations are never selected: a related row
+ * would not be scoped.
  */
 export declare const toPrismaSelect: (policies: AccessPolicies, resource: string, fields: AccessFields) => PrismaSelect;
 /** The property of the Prisma client that holds a model's delegate: its name, first letter lowered. */

package/dist/generator/prisma7/prisma-where.translator.js

@@ -12,6 +12,7 @@
 // Prisma's `is`, because Prisma reads an empty unwrapped one as no condition at all;
 // a to-many relation's `some`, `every` and `none` keep theirs.
 import { defineMember, } from "../../aventara-where.translator.js";
+import { governedFor } from "../../scope.resolver.js";
 const isWhereNode = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 /** A record's own member, never one it inherits. */
 const own = (record, key) => record !== undefined && Object.hasOwn(record, key) ? record[key] : undefined;
@@ -72,14 +73,15 @@ export const toPrismaScope = (policies, resource, scope) => scope === true
         : toPrismaWhere(policies, resource, scope);
 /**
  * A `fieldsOf` read answer as Prisma's `select`: the Resource's scalar fields a read
- * shows on every row. A governed field is selected only when the answer opens it on
- * every row; a field it opens on some rows only is left out, since a `select` cannot
- * depend on the row (ask `fieldsOf` for those). Relations are never selected: a
- * related row would not be scoped.
+ * shows on every row. A field governed for reading is selected only when the answer
+ * opens it on every row (one governed for writing only is read as any other); a
+ * field it opens on some rows only is left out, since a `select` cannot depend on
+ * the row (ask `fieldsOf` for those). Relations are never selected: a related row
+ * would not be scoped.
  */
 export const toPrismaSelect = (policies, resource, fields) => {
     const facts = own(policies.schema, resource);
-    const governed = own(policies.govern, resource) ?? [];
+    const governed = governedFor(policies, resource, "read");
     const scalars = (facts?.fields ?? []).filter((field) => own(facts?.relations, field) === undefined);
     const select = {};
     for (const field of scalars) {

package/dist/mcp/agent-scope.gate.d.ts

@@ -1,6 +1,8 @@
 import type { AccessEngine, DecisionObserver } from "../access.engine.js";
 type GovernedShape = {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 };
 /**
  * `engine` with the token gate before it: a principal without a token's grant is

package/dist/mcp/agent-scope.gate.js

@@ -28,7 +28,7 @@ const refusalOf = (grant, origin, writes) => {
     if (grant.via === "mcp" && origin !== "agent") {
         return MCP_AUDIENCE_RULE;
     }
-    return grant.scopes.has(writes ? MCP_WRITE_SCOPE : MCP_READ_SCOPE)
+    return grant.scopes.includes(writes ? MCP_WRITE_SCOPE : MCP_READ_SCOPE)
         ? undefined
         : MCP_SCOPE_RULE;
 };

package/dist/mcp/agent.grant.d.ts

@@ -10,6 +10,10 @@ export type CarriedGrant = TokenGrant & {
     /** `mcp`: an agent's token for the MCP endpoint. `audience`: a token addressed to the service itself. */
     readonly via: "mcp" | "audience";
 };
+/** A grant as the principal carries it: frozen, its scopes a frozen list (a `Set` stays writable when frozen). */
+export type MarkedGrant = Omit<CarriedGrant, "scopes"> & {
+    readonly scopes: readonly string[];
+};
 /** Who acts for the user when a principal is an agent's: what `agentOf(me)` answers. */
 export type AccessAgent = {
     /** The OAuth client the agent's token was issued to. */
@@ -26,7 +30,7 @@ export type AccessAgent = {
  */
 export declare const withGrant: (me: unknown, grant: CarriedGrant) => unknown;
 /** What a token grants the principal it yields; `undefined` for any other principal. */
-export declare const grantOf: (principal: unknown) => CarriedGrant | undefined;
+export declare const grantOf: (principal: unknown) => MarkedGrant | undefined;
 /**
  * Whether `me` is an agent's: the principal a request with an agent's access token for
  * the MCP endpoint runs as (`ctx.$state.me`), and the identity `principal` is given

package/dist/mcp/agent.grant.js

@@ -47,7 +47,7 @@ export const withGrant = (me, grant) => {
     const copy = Object.assign(Object.create(Object.getPrototypeOf(me)), me);
     const frozen = Object.freeze({
         clientId: grant.clientId,
-        scopes: new Set(grant.scopes),
+        scopes: Object.freeze([...grant.scopes]),
         via: grant.via,
     });
     try {

package/dist/policies-contract.d.ts

@@ -139,9 +139,15 @@ export type AccessSchemaResourceFacts = {
 export type AccessClaimType = {
     readonly scalar: "string" | "number" | "boolean";
 };
-/** The `@1` policies file. `Governed` keeps the `govern` block's literal type through the builder. */
+/**
+ * The `@1` policies file. `Governed` keeps the `govern` block's literal type through
+ * the builder: per Resource, the list form (each field governed for reading and
+ * writing) or the object form (a mode per field).
+ */
 export type AccessPolicies<Governed extends {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 } = {
     readonly [resource: string]: readonly string[];
 }> = {
@@ -157,7 +163,21 @@ export type AccessPolicies<Governed extends {
     readonly roles: {
         readonly [role: string]: AccessRoleDefinition;
     };
-    readonly govern: Governed;
+    /** Every governed field, by Resource, whatever its mode. */
+    readonly govern: {
+        readonly [R in keyof Governed]: Governed[R] extends readonly string[] ? Governed[R] : readonly (keyof Governed[R] & string)[];
+    };
+    /**
+     * The governed fields governed for one access only, by Resource: `"write"`, read by
+     * default and written only through a grant that names the field; `"read"`, written
+     * by default and read only through a grant that names it. A governed field with no
+     * entry is governed for both, and a file without `governModes` has no other kind.
+     */
+    readonly governModes?: {
+        readonly [resource: string]: {
+            readonly [field: string]: "read" | "write";
+        };
+    };
     readonly grants: readonly AccessGrantRule[];
     readonly denies: readonly AccessDenyRule[];
 };
@@ -169,7 +189,9 @@ export type AccessPolicies<Governed extends {
  * is: only its outline is typed, and the engine checks the rest when it is built.
  */
 export type AccessPoliciesJson<Governed extends {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 } = {
     readonly [resource: string]: readonly string[];
 }> = {
@@ -187,6 +209,11 @@ export type AccessPoliciesJson<Governed extends {
         readonly [role: string]: object;
     };
     readonly govern: Governed;
+    readonly governModes?: {
+        readonly [resource: string]: {
+            readonly [field: string]: string;
+        };
+    };
     readonly grants: readonly object[];
     readonly denies: readonly object[];
 };

package/dist/policies.compiler.d.ts

@@ -21,7 +21,9 @@ export declare const idAllocator: () => (prefix: string, name: unknown) => strin
 export declare const compilePrincipalIf: (rule: string, condition: unknown, claimTypes: ClaimTypes) => AccessPrincipalCondition;
 /** Compiles the builder's rules to the `@1` policies file and checks it. */
 export declare const compilePolicies: <Governed extends {
-    readonly [resource: string]: readonly string[];
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
 }>(definition: AccessDefinition) => AccessPolicies<Governed>;
 export declare const checkActions: (rule: string, actions: readonly string[]) => void;
 /** Whether `value` is a name a file may give a Resource or a field. */