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

package/dist/access/token.verifier.js

@@ -0,0 +1,69 @@
+// Verifies the JWTs Better Auth's `jwt()` plugin signs, against the key set it
+// publishes (`key-set.cache.ts`: read once and kept, read again when stale or when a
+// token names a key the set does not hold, the last good set kept while the key
+// store is down).
+//
+// A token is Access's own only when it carries the instance's issuer and audience
+// (the one string `createAccess` fixed, never a list holding it), `sub`, `exp` and
+// `iat`, and is no older than `tokenTtl`, nor issued in the future (a few seconds of
+// clock skew aside). An access token Better Auth's OAuth provider issued (`typ:
+// "at+jwt"`, RFC 9068) is never one, whatever it carries: it is for one resource
+// alone (`oauth/access-token.verifier.ts`).
+import { errors, jwtVerify } from "jose";
+import { acceptedClaims, } from "./claims.mapper.js";
+import { createKeySetCache } from "./key-set.cache.js";
+/** The clock skew allowed between the issuer and the verifier, in seconds. */
+export const CLOCK_TOLERANCE_S = 5;
+/**
+ * The algorithms a token may be signed with: those Better Auth's `jwt()` signs with
+ * (its `keyPairConfig.alg`), all asymmetric. A token signed otherwise is refused
+ * before its key is looked up, whatever key the set holds.
+ */
+export const JWT_ALGORITHMS = Object.freeze([
+    "EdDSA",
+    "ES256",
+    "ES512",
+    "PS256",
+    "RS256",
+]);
+/** Whether a JWT header's `typ` names an OAuth access token (RFC 9068, section 2.1: `at+jwt`, or `application/at+jwt`). */
+export const isAccessTokenType = (typ) => typeof typ === "string" && /^(?:application\/)?at\+jwt$/i.test(typ.trim());
+export const createTokenVerifier = (source) => {
+    const now = source.now ?? (() => Date.now());
+    const keySet = createKeySetCache(source.keys, now);
+    return {
+        async verify(token) {
+            let verified;
+            try {
+                verified = await keySet.withKeys((keys) => jwtVerify(token, keys, {
+                    requiredClaims: ["sub", "exp", "iat"],
+                    issuer: source.issuer,
+                    algorithms: [...JWT_ALGORITHMS],
+                    audience: source.issuer,
+                    maxTokenAge: source.tokenTtl,
+                    clockTolerance: CLOCK_TOLERANCE_S,
+                    currentDate: new Date(now()),
+                }));
+            }
+            catch (error) {
+                if (error instanceof errors.JOSEError) {
+                    return null;
+                }
+                throw error;
+            }
+            const { payload, protectedHeader } = verified;
+            if (isAccessTokenType(protectedHeader.typ)) {
+                return null;
+            }
+            const { sub, aud } = payload;
+            const claims = acceptedClaims(payload, source.claims);
+            if (typeof sub !== "string" ||
+                sub === "" ||
+                aud !== source.issuer ||
+                claims === undefined) {
+                return null;
+            }
+            return { sub, claims };
+        },
+    };
+};

package/dist/access-schema.d.ts

@@ -0,0 +1,48 @@
+/** A scalar field as discovery states it. */
+export type AccessSchemaScalarField = {
+    readonly kind: "scalar";
+    readonly type: {
+        readonly scalar: string;
+    } | {
+        readonly enum: string;
+    };
+    readonly nullable: boolean;
+    readonly list: boolean;
+};
+/** A relation field as discovery states it, with the `references` it holds. */
+export type AccessSchemaRelationField = {
+    readonly kind: "relation";
+    readonly target: string;
+    readonly cardinality: "one" | "many";
+    readonly nullable: boolean;
+    readonly inverse?: string;
+    readonly referenceFields?: readonly [string, ...string[]];
+    readonly references?: readonly [string, ...string[]];
+};
+/** One field of a Resource. */
+export type AccessSchemaField = AccessSchemaScalarField | AccessSchemaRelationField;
+/** One Resource: its fields and the field tuples that identify a row. */
+export type AccessSchemaResource = {
+    readonly fields: {
+        readonly [field: string]: AccessSchemaField;
+    };
+    readonly identifiers: readonly (readonly string[])[];
+    /**
+     * The namespace that owns this Resource, when another one does (`{ foreign: "campaign" }`).
+     * Rules read a foreign Resource in conditions and never grant on it.
+     */
+    readonly foreign?: string;
+};
+/** The schema facts Access reads: the enums and the Resources. */
+export type AccessSchema = {
+    readonly enums: {
+        readonly [name: string]: {
+            readonly values: readonly string[];
+        };
+    };
+    readonly resources: {
+        readonly [resource: string]: AccessSchemaResource;
+    };
+};
+/** The TypeScript value a built-in scalar compares with. Unknown scalars compare with `unknown`. */
+export type AccessScalarValue<Scalar extends string> = Scalar extends "string" ? string : Scalar extends "boolean" ? boolean : Scalar extends "int" | "float" ? number : Scalar extends "bigint" ? bigint : Scalar extends "decimal" ? number | string : Scalar extends "datetime" ? Date | string : unknown;

package/dist/access-schema.js

@@ -0,0 +1,5 @@
+// The schema shape Access is typed from and compiles against. It is a structural
+// subset of core's `AvAdapterModel` (a Prisma discovery artifact's `model`), so an
+// Aventara app passes its discovery model in and Access imports nothing from core.
+// The type test `test/core-seam.test-d.ts` holds the two together.
+export {};

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

@@ -0,0 +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

@@ -0,0 +1,24 @@
+// How the engine's checks against a hosting framework warn: Node.js's
+// `process.emitWarning` (type `AventaraAccessWarning`, the check's code, silenced
+// 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}`;
+    if (emitted.has(key)) {
+        return;
+    }
+    emitted.add(key);
+    const runtime = globalThis.process;
+    if (typeof runtime?.emitWarning === "function") {
+        runtime.emitWarning(message, { type: "AventaraAccessWarning", code });
+    }
+    else {
+        globalThis.console?.warn(`${code}: ${message}`);
+    }
+};

package/dist/access.builder.d.ts

@@ -0,0 +1,340 @@
+import { type AccessEngine, type AccessEngineOptions } from "./access.engine.js";
+import type { AccessScalarValue, AccessSchema } from "./access-schema.js";
+import type { AccessAction, AccessBuiltInSubject, AccessOrigin, AccessPolicies } from "./policies-contract.js";
+declare const principalRefBrand: unique symbol;
+/**
+ * A value read off the principal when a question is asked (`me.id`). `T` is the
+ * value's type, so `me.id` compares only with a field of that type.
+ */
+export type AccessPrincipalRef<T = unknown> = {
+    readonly [principalRefBrand]: T;
+    readonly path: readonly [string, ...string[]];
+};
+/**
+ * The principal, symbolically, typed from `.principal<P>()`: one key per key of
+ * `P`, so `me.profleId` is a tsc error. `me.id` is a token the compiler writes
+ * into the file as `{ principal: ["id"] }`, never a value. A rule about `me` is
+ * false for an anonymous (null) principal, and for one that lacks the value.
+ */
+export type AccessMe<P> = {
+    readonly [K in Extract<keyof NonNullable<P>, string>]-?: AccessPrincipalRef<NonNullable<NonNullable<P>[K]>>;
+};
+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 [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;
+} | {
+    readonly global: unknown;
+};
+/** The roles in scope inside a role's own `where`: any name (the compiler checks them). */
+type AnyRoles = {
+    readonly [role: string]: {
+        readonly on: string;
+    };
+};
+type ResourceOf<S extends AccessSchema> = Extract<keyof S["resources"], string>;
+/**
+ * The file's own Resources: all but the foreign ones (`{ foreign: "<namespace>" }`).
+ * Grants, denies and governed fields name only these; a foreign Resource is read in
+ * conditions alone.
+ */
+type OwnResourceOf<S extends AccessSchema> = {
+    [R in ResourceOf<S>]: S["resources"][R] extends {
+        readonly foreign: string;
+    } ? never : R;
+}[ResourceOf<S>];
+type FieldMap<S extends AccessSchema, R extends ResourceOf<S>> = S["resources"][R]["fields"];
+/** A Resource's field names. */
+export type AccessFieldOf<S extends AccessSchema, R extends ResourceOf<S>> = Extract<keyof FieldMap<S, R>, string>;
+type NullIf<F> = F extends {
+    readonly nullable: true;
+} ? null : never;
+/** The literal a scalar field compares with: its enum's values, or its scalar's TS type. */
+type ScalarValue<S extends AccessSchema, F> = F extends {
+    readonly list: true;
+} ? never : F extends {
+    readonly type: {
+        readonly enum: infer E extends keyof S["enums"];
+    };
+} ? S["enums"][E]["values"][number] | NullIf<F> : F extends {
+    readonly type: {
+        readonly scalar: infer T extends string;
+    };
+} ? AccessScalarValue<T> | NullIf<F> : never;
+type Operand<V> = V | AccessPrincipalRef<V>;
+type ScalarCondition<V> = Operand<V> | {
+    readonly equals?: Operand<V>;
+    readonly not?: Operand<V>;
+    readonly in?: readonly Operand<V>[];
+    readonly notIn?: readonly Operand<V>[];
+};
+type RelationCondition<S extends AccessSchema, F, Roles> = F extends {
+    readonly cardinality: "one";
+    readonly target: infer T extends ResourceOf<S>;
+} ? AccessWhereInput<S, T, Roles> : F extends {
+    readonly cardinality: "many";
+    readonly target: infer T extends ResourceOf<S>;
+} ? {
+    readonly some?: AccessWhereInput<S, T, Roles>;
+    readonly every?: AccessWhereInput<S, T, Roles>;
+    readonly none?: AccessWhereInput<S, T, Roles>;
+} : never;
+type FieldCondition<S extends AccessSchema, F, Roles> = F extends {
+    readonly kind: "relation";
+} ? RelationCondition<S, F, Roles> : ScalarCondition<ScalarValue<S, F>>;
+/** The row roles held on Resource `R`. */
+type RoleOn<Roles, R extends string> = string extends keyof Roles ? string : {
+    [K in keyof Roles]: Roles[K] extends {
+        readonly on: R;
+    } ? K : never;
+}[keyof Roles] & string;
+/**
+ * A row condition on Resource `R`, in Aventara's `where` vocabulary: fields by
+ * name (a value is `equals`), `AND` / `OR` / `NOT`, a to-one relation by direct
+ * match, a to-many by `some` / `every` / `none`, and `$role`, a row role held on
+ * `R`.
+ */
+export type AccessWhereInput<S extends AccessSchema, R extends ResourceOf<S>, Roles> = {
+    readonly [F in AccessFieldOf<S, R>]?: FieldCondition<S, FieldMap<S, R>[F], Roles>;
+} & {
+    readonly AND?: readonly AccessWhereInput<S, R, Roles>[];
+    readonly OR?: readonly AccessWhereInput<S, R, Roles>[];
+    readonly NOT?: AccessWhereInput<S, R, Roles>;
+    readonly $role?: RoleOn<Roles, R>;
+};
+type ClaimsOf<P> = P extends {
+    readonly claims?: infer C;
+} ? NonNullable<C> : never;
+/** A condition on the principal's claims: each named claim equals the value. */
+export type AccessClaimsCondition<P> = [ClaimsOf<P>] extends [never] ? never : {
+    readonly [K in keyof ClaimsOf<P>]?: Exclude<ClaimsOf<P>[K], undefined>;
+};
+type RowRoleDefinition<S extends AccessSchema> = {
+    [R in ResourceOf<S>]: {
+        readonly on: R;
+        readonly where: AccessWhereInput<S, R, AnyRoles>;
+    };
+}[ResourceOf<S>];
+type GlobalRoleDefinition<P> = {
+    readonly global: {
+        readonly claims: AccessClaimsCondition<P>;
+    };
+};
+/** The `.roles({...})` argument: global roles from claims, row roles on one Resource. */
+export type AccessRoleDefinitions<S extends AccessSchema, P> = {
+    readonly [role: string]: GlobalRoleDefinition<P> | RowRoleDefinition<S>;
+};
+/** Each role of `D` checked against its own shape; built-in subject names refused. */
+type CheckedRoles<S extends AccessSchema, P, D> = {
+    readonly [K in keyof D]: K extends AccessBuiltInSubject ? never : D[K] extends {
+        readonly on: infer R extends ResourceOf<S>;
+        readonly where: infer W;
+    } ? {
+        readonly on: R;
+        readonly where: NoExtraKeys<W, AccessWhereInput<S, R, AnyRoles>, "a field, relation or operator">;
+    } : D[K] extends {
+        readonly global: {
+            readonly claims: infer C;
+        };
+    } ? {
+        readonly global: {
+            readonly claims: NoExtraKeys<C, AccessClaimsCondition<P>, "a claim of the principal">;
+        };
+    } : AccessRoleDefinitions<S, P>[string];
+};
+/** Every key of every object member of a union. */
+type KeysOfUnion<U> = U extends unknown ? keyof U : never;
+/** The type of key `K` across the object members of a union that have it. */
+type MemberOf<U, K> = U extends unknown ? K extends keyof U ? U[K] : never : never;
+/**
+ * `T` checked against `Shape`, at any depth: each key `Shape` does not have is
+ * typed as the sentence that says so, and each value as `Shape` allows it.
+ */
+type NoExtraKeys<T, Shape, Noun extends string> = T extends string | number | boolean | bigint | symbol | null | undefined | AccessPrincipalRef ? Shape : T extends readonly (infer E)[] ? Shape extends unknown ? readonly NoExtraKeys<E, NonNullable<Shape> extends readonly (infer SE)[] ? SE : never, Noun>[] : never : {
+    readonly [K in keyof T]: K extends KeysOfUnion<Exclude<Extract<NonNullable<Shape>, object>, AccessPrincipalRef>> ? NoExtraKeys<T[K], MemberOf<Exclude<Extract<NonNullable<Shape>, object>, AccessPrincipalRef>, K>, Noun> : `Error: "${K & string}" is not ${Noun} here`;
+};
+/** Who a grant is for: a built-in subject or a role. */
+type Subject<Roles> = AccessBuiltInSubject | Extract<keyof Roles, string>;
+type OneOrMany<T> = T | readonly [T, ...T[]];
+type Each<T> = T extends readonly (infer X)[] ? X : T;
+/** The Resource every subject's row role is held on; `never` when one subject is not a row role. */
+type SubjectsOn<Roles, Sub> = [Sub] extends [never] ? never : Sub extends keyof Roles ? Roles[Sub] extends {
+    readonly on: infer On extends string;
+} ? On : "~not-a-row-role" : "~not-a-row-role";
+/** The to-one relations of `R` that lead to `On`. */
+type InRelation<S extends AccessSchema, R extends ResourceOf<S>, On> = {
+    [F in AccessFieldOf<S, R>]: FieldMap<S, R>[F] extends {
+        readonly kind: "relation";
+        readonly cardinality: "one";
+        readonly target: infer T;
+    } ? T extends On ? F : never : never;
+}[AccessFieldOf<S, R>];
+type InOption<S extends AccessSchema, R, Roles, Sub> = R extends ResourceOf<S> ? "~not-a-row-role" extends SubjectsOn<Roles, Each<Sub>> ? never : InRelation<S, R, SubjectsOn<Roles, Each<Sub>>> : never;
+/**
+ * A governed field named `Resource.field`. On `"*"`, any Resource's governed fields.
+ * A Resource with no governed field has none to name: the type is the sentence that
+ * 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}.${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> = {
+    /** A name for the rule's id (else `Resource/actions/subjects#n`). */
+    readonly name?: string;
+    /** The rows the grant covers. */
+    readonly where?: ResourceWhere<S, R, Roles>;
+    /** `in: "campaign"`: each subject holds its row role on this row's `campaign`. */
+    readonly in?: InOption<S, R, Roles, Sub>;
+    /** Governed fields the grant opens, as `Resource.field`. */
+    readonly fields?: readonly GovernedRef<Gov, R>[];
+    /** Fields a create or update by this grant may not write. */
+    readonly write?: Extract<Each<A>, "create" | "update"> extends never ? never : R extends ResourceOf<S> ? {
+        readonly except: readonly AccessFieldOf<S, R>[];
+    } : never;
+    /** What the row an update leaves must still meet. */
+    readonly after?: "update" extends Each<A> ? ResourceWhere<S, R, Roles> : never;
+};
+/** The options of `deny(actions, resource, options)`. */
+export type AccessDenyOptions<S extends AccessSchema, P, Roles, R> = {
+    /** A name for the rule's id (else `Resource/actions/deny#n`). */
+    readonly name?: string;
+    /** The rows the deny covers. */
+    readonly where?: ResourceWhere<S, R, Roles>;
+    /** A condition on the principal alone: its claims and the request's origin. */
+    readonly if?: {
+        readonly claims?: AccessClaimsCondition<P>;
+        readonly origin?: AccessOrigin;
+    };
+};
+declare const grantBrand: unique symbol;
+declare const denyBrand: unique symbol;
+/** A grant, as data, before compilation. */
+export type AccessGrant = {
+    readonly [grantBrand]: true;
+    readonly subjects: OneOrMany<string>;
+    readonly actions: OneOrMany<AccessAction>;
+    readonly resource: string;
+    readonly options: {
+        readonly [option: string]: unknown;
+    };
+};
+/** A deny, as data, before compilation. */
+export type AccessDeny = {
+    readonly [denyBrand]: true;
+    readonly actions: "*" | OneOrMany<AccessAction>;
+    readonly resource: string;
+    readonly options: {
+        readonly [option: string]: unknown;
+    };
+};
+/** `grant(subjects, actions, resource, options?)`: any grant allows. */
+export type AccessGrantFunction<S extends AccessSchema, Roles, Gov> = <const Sub extends OneOrMany<Subject<Roles>>, const A extends OneOrMany<AccessAction>, const R extends OwnResourceOf<S> | "*">(subjects: Sub, actions: A, resource: R, options?: AccessGrantOptions<S, Roles, Gov, NoInfer<R>, NoInfer<Sub>, NoInfer<A>>) => AccessGrant;
+/** `deny(actions, resource, options?)`: any deny wins. */
+export type AccessDenyFunction<S extends AccessSchema, P, Roles> = <const A extends "*" | OneOrMany<AccessAction>, const R extends OwnResourceOf<S> | "*">(actions: A, resource: R, options?: AccessDenyOptions<S, P, Roles, NoInfer<R>>) => AccessDeny;
+/** The rules as written, before compilation. */
+export type AccessDefinition = {
+    readonly schema: AccessSchema;
+    readonly namespace?: string;
+    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 {
+            readonly field: string;
+            readonly mode: GovernMode;
+        }[];
+    };
+    readonly grants: readonly AccessGrant[];
+    readonly denies: readonly AccessDeny[];
+};
+/** The builder `definePolicies` returns. Each call returns a new builder; none has side effects. */
+export interface AccessBuilder<S extends AccessSchema, P, Roles extends {
+    readonly [role: string]: RoleShape;
+}, Gov extends GovernedShape> {
+    /** Types the principal. Anonymous is `null`; rules about `me` are false for it. */
+    principal<T>(): AccessBuilder<S, T, Roles, Gov>;
+    /** Global roles (`global: { claims }`) and roles held on a row (`on`, `where`). */
+    roles<const D extends {
+        readonly [role: string]: RoleShape;
+    }>(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: 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>;
+        readonly me: AccessMe<P>;
+    }) => readonly AccessGrant[]): AccessBuilder<S, P, Roles, Gov>;
+    /** Denies. Any deny wins over every grant; order never matters. */
+    denies(rules: (tools: {
+        readonly deny: AccessDenyFunction<S, P, Roles>;
+        readonly me: AccessMe<P>;
+    }) => readonly AccessDeny[]): AccessBuilder<S, P, Roles, Gov>;
+    /** The compiled `@1` policies file. */
+    contract(): AccessPolicies<Gov>;
+    /**
+     * The engine, run from the compiled file and, with `guardrails`, the org's
+     * guardrails on top of it. With `lock`, the guardrails are held to the hash
+     * `avAccess.lock.json` pins, and the rules' namespace to its namespace.
+     * Satisfies core's `AvPolicyEngine` by shape.
+     */
+    engine(options?: AccessEngineOptions): AccessEngine<Gov>;
+}
+/**
+ * Starts the rules for an app, typed from its schema (an Aventara discovery
+ * artifact's `model`, or any object of the {@link AccessSchema} shape).
+ * `namespace` names the namespace that owns these Resources; it is written into
+ * the compiled file.
+ */
+export declare const definePolicies: <const S extends AccessSchema>(schema: S, options?: {
+    readonly namespace?: string;
+}) => AccessBuilder<S, unknown, Record<never, never>, Record<never, never>>;
+export {};

package/dist/access.builder.js

@@ -0,0 +1,75 @@
+// `definePolicies(model)`: the typed authoring API. It captures the author's
+// rules as plain data and compiles them to the `@1` policies file; the engine runs
+// from that file alone. Every name a rule uses (Resource, field,
+// relation, enum value, role, governed field) is checked at its key against the
+// schema the builder was created from.
+import { engineOf, } from "./access.engine.js";
+import { compilePolicies, PRINCIPAL_REF } from "./policies.compiler.js";
+/** The one runtime `me`: any key reads as a principal reference. */
+const me = new Proxy({}, {
+    get(_target, key) {
+        if (typeof key !== "string") {
+            return undefined;
+        }
+        return Object.freeze({
+            [PRINCIPAL_REF]: true,
+            path: Object.freeze([key]),
+        });
+    },
+});
+const grant = (subjects, actions, resource, options = {}) => Object.freeze({
+    subjects,
+    actions,
+    resource,
+    options,
+});
+const deny = (actions, resource, options = {}) => Object.freeze({ actions, resource, options });
+const builderOf = (definition) => ({
+    principal: () => builderOf(definition),
+    roles: (definitions) => builderOf({
+        ...definition,
+        roles: { ...definition.roles, ...definitions({ me }) },
+    }),
+    govern: (resource, fields) => builderOf({
+        ...definition,
+        govern: {
+            ...definition.govern,
+            [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({
+        ...definition,
+        grants: [...definition.grants, ...rules({ grant, me })],
+    }),
+    denies: (rules) => builderOf({
+        ...definition,
+        denies: [...definition.denies, ...rules({ deny, me })],
+    }),
+    contract: () => compilePolicies(definition),
+    engine: (options) => engineOf(compilePolicies(definition), options, "rules"),
+});
+/**
+ * Starts the rules for an app, typed from its schema (an Aventara discovery
+ * artifact's `model`, or any object of the {@link AccessSchema} shape).
+ * `namespace` names the namespace that owns these Resources; it is written into
+ * the compiled file.
+ */
+export const definePolicies = (schema, options) => builderOf({
+    schema,
+    ...(options?.namespace !== undefined
+        ? { namespace: options.namespace }
+        : {}),
+    roles: {},
+    govern: {},
+    grants: [],
+    denies: [],
+});