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

package/dist/kiosk/pin.policy.js

@@ -0,0 +1,143 @@
+// What a PIN may be. A PIN is a weak secret: it is only ever checked on an enrolled
+// device, under per-device and per-user failure limits (`kiosk.store.ts`), so it is
+// short; it is still held to NIST SP 800-63B's floor for a secret that unlocks a
+// device-bound authenticator (six digits, section 5.1.9.1), and the values guessed
+// first are refused (NIST SP 800-63B 5.1.1.2's blocklist of commonly used values).
+//
+// The blocklist is the one Apple's iOS uses for 6-digit passcodes, as Markert et al.
+// extracted and described it, widened to every length a PIN may have, plus the most
+// common 6-digit PINs of the leaked-password data:
+//
+// - Markert, Bailey, Golla, Dürmuth, Aviv, "This PIN Can Be Easily Guessed: Analyzing
+//   the Security of Smartphone Unlock PINs", IEEE S&P 2020, and its data
+//   (https://this-pin-can-be-easily-guessed.github.io): the iOS 6-digit blocklist
+//   (2910 PINs) is exactly the patterns `aaaaaa`, `abcabc`, `abccba`, `ababab`,
+//   `ababa?`, 14 series and 6 common PINs, every one of which `pinDefect` refuses;
+//   and the 29 most common 6-digit PINs of the RockYou leak (the paper's data-driven list of 29).
+// - Wang, Gu, Huang, Wang, "Understanding Human-Chosen PINs: Characteristics,
+//   Distribution and Security", ASIA CCS 2017: the common PINs iOS takes from it.
+//
+// DataGenetics' well-known list is of 4-digit PINs, shorter than any PIN here. Dates
+// are not refused: they are a tenth of the 6-digit space, and the failure limits,
+// not the blocklist, are what hold a guesser to a few tries.
+/** The shortest and longest PIN, in digits. */
+export const PIN_LENGTH = { min: 6, max: 12 };
+const DIGITS = /^[0-9]+$/;
+/**
+ * Common PINs no pattern below covers: the RockYou top 29 and iOS's series and
+ * common PINs, less those the patterns refuse already.
+ */
+const COMMON_PINS = new Set([
+    // RockYou's most common 6-digit PINs (Markert et al.'s data-driven list).
+    "789456",
+    "123654",
+    "246810",
+    "159357",
+    "147852",
+    "159753",
+    "147258",
+    // iOS's series.
+    "098765",
+    "321654",
+    // iOS's common PINs (Wang et al.).
+    "030379",
+    "101471",
+    "520131",
+]);
+/**
+ * The phone keypad's lines of three, both ways: rows, columns, diagonals, and the
+ * middle column down to 0. A PIN made of them only (`147258`, `159753`, `789456`) is
+ * a shape on the keypad, not a number.
+ */
+const KEYPAD_LINES = new Set([
+    "123",
+    "456",
+    "789",
+    "147",
+    "258",
+    "369",
+    "159",
+    "357",
+    "580",
+    "280",
+].flatMap((line) => [line, [...line].reverse().join("")]));
+/** Whether `pin` repeats itself with a period at most half its length (`121212`, `123123`). */
+const periodic = (pin, upTo) => {
+    for (let period = 1; period <= upTo; period += 1) {
+        let repeats = true;
+        for (let at = period; at < pin.length && repeats; at += 1) {
+            repeats = pin[at] === pin[at - period];
+        }
+        if (repeats) {
+            return true;
+        }
+    }
+    return false;
+};
+/** Whether `pin` reads the same backwards (`123321`). */
+const palindrome = (pin) => pin === [...pin].reverse().join("");
+/** Whether `pin` is a straight run up or down (`123456`, `987654`). */
+const straightRun = (pin) => {
+    let up = true;
+    let down = true;
+    for (let at = 1; at < pin.length; at += 1) {
+        const step = pin.charCodeAt(at) - pin.charCodeAt(at - 1);
+        up &&= step === 1;
+        down &&= step === -1;
+    }
+    return up || down;
+};
+/** Whether `pin` is equal runs of one digit each, two or more long (`112233`, `111222`). */
+const doubledDigits = (pin) => {
+    for (let size = 2; size <= pin.length / 2; size += 1) {
+        if (pin.length % size !== 0) {
+            continue;
+        }
+        let runs = true;
+        for (let at = 0; at < pin.length && runs; at += 1) {
+            runs = pin[at] === pin[at - (at % size)];
+        }
+        if (runs) {
+            return true;
+        }
+    }
+    return false;
+};
+/** Whether `pin` is keypad lines of three only (`147258`, `159753`, `147258369`). */
+const keypadShape = (pin) => {
+    if (pin.length % 3 !== 0) {
+        return false;
+    }
+    for (let at = 0; at < pin.length; at += 3) {
+        if (!KEYPAD_LINES.has(pin.slice(at, at + 3))) {
+            return false;
+        }
+    }
+    return true;
+};
+/** Why a PIN is refused at `setPin`, or `undefined` when it is accepted. */
+export const pinDefect = (pin) => {
+    if (typeof pin !== "string" ||
+        !DIGITS.test(pin) ||
+        pin.length < PIN_LENGTH.min ||
+        pin.length > PIN_LENGTH.max) {
+        return `A PIN is ${PIN_LENGTH.min} to ${PIN_LENGTH.max} digits.`;
+    }
+    const guessable = COMMON_PINS.has(pin) ||
+        // One digit repeated, or a block repeated (`000000`, `121212`, `123123`).
+        periodic(pin, Math.floor(pin.length / 2)) ||
+        // Two digits alternating, then any last digit (iOS's `ababa?`).
+        periodic(pin.slice(0, -1), 2) ||
+        palindrome(pin) ||
+        straightRun(pin) ||
+        doubledDigits(pin) ||
+        keypadShape(pin);
+    return guessable
+        ? "That PIN is one of the first a guesser tries (a common PIN, a repeated or mirrored pattern, a straight run, or a shape on the keypad): choose another."
+        : undefined;
+};
+/** Whether a PIN could be one `setPin` accepted: its shape only, for a switch. */
+export const pinShaped = (pin) => typeof pin === "string" &&
+    DIGITS.test(pin) &&
+    pin.length >= PIN_LENGTH.min &&
+    pin.length <= PIN_LENGTH.max;

package/dist/kiosk/session-use.marker.d.ts

@@ -0,0 +1,4 @@
+/** On a Better Auth API call's input: the request it reads the session for may change something. */
+export declare const SESSION_USE: unique symbol;
+/** Whether a request with this method (upper-cased; `undefined` when unknown) may change something. */
+export declare const mayChange: (method: string | undefined) => boolean;

package/dist/kiosk/session-use.marker.js

@@ -0,0 +1,16 @@
+// What counts as a till's use of its session, for the kiosk profile's idle timer: a
+// request that may change something (any method but GET, HEAD and OPTIONS, or one
+// whose method is unknown), never a read. A page left open on a till keeps reading
+// (Better Auth's client polls `/get-session`, a dashboard refreshes), and those reads
+// must not keep its session alive for whoever walks up next.
+//
+// `access.state` reads the session through Better Auth's API, where the hook sees
+// `/get-session` and no request: it marks the call with {@link SESSION_USE} when the
+// framework's request is a write. The mark is a symbol, so no caller of the API can
+// spell it by accident.
+/** On a Better Auth API call's input: the request it reads the session for may change something. */
+export const SESSION_USE = Symbol("aventara-access.session-use");
+/** The methods that change nothing. */
+const READS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** Whether a request with this method (upper-cased; `undefined` when unknown) may change something. */
+export const mayChange = (method) => method === undefined || !READS.has(method);

package/dist/lock/lock-contract.d.ts

@@ -0,0 +1,38 @@
+/** The format marker of every lock file. */
+export declare const LOCK_FORMAT = "aventara-access/lock@1";
+/** The lock's file name, at the project's root. */
+export declare const LOCK_FILE = "avAccess.lock.json";
+/** One pulled file: where it is, relative to the lock, and the hash it was pulled under. */
+export type AccessLockPin = {
+    /** The file's path from the lock's directory, with `/` separators: `access/campaign.policies.json`. */
+    readonly path: string;
+    /** Its `policiesHash` or `guardrailsHash`: `sha256:<hex>`. */
+    readonly hash: string;
+};
+/**
+ * `avAccess.lock.json`, as `avaccess pull` writes it. `format` is typed as a string,
+ * not its literal, so the file imported as JSON (`import lock from
+ * "./avAccess.lock.json" with { type: "json" }`) is one as it is; it is checked when
+ * the engine or `avaccess verify` reads it.
+ */
+export type AccessLock = {
+    /** `"aventara-access/lock@1"`. */
+    readonly format: string;
+    /** The namespace whose policies file is pinned. */
+    readonly namespace: string;
+    /** The namespace's policies file. */
+    readonly policies: AccessLockPin;
+    /** The org's guardrails file, or `null` when the registry had none at pull. */
+    readonly guardrails: AccessLockPin | null;
+    /**
+     * The foreign facts `avaccess pull --foreign` wrote (`access/foreign.json`): the
+     * schema entries of the other namespaces' Resources the rules read. Absent when
+     * none were pulled.
+     */
+    readonly foreign?: AccessLockPin;
+};
+/**
+ * Checks that `lock` is an `aventara-access/lock@1` lock, naming what is wrong. A
+ * pin's path stays inside the lock's directory.
+ */
+export declare const checkLock: (lock: unknown, where?: string) => AccessLock;

package/dist/lock/lock-contract.js

@@ -0,0 +1,67 @@
+// `avAccess.lock.json`, format `aventara-access/lock@1`: what a service is built with.
+// `avaccess pull` writes the namespace's current policies file and the org's
+// guardrails file into the project and pins each one's hash here; the project
+// commits all three. From then on nothing at build or start touches the network:
+// `avaccess verify` and the engine hash the files on disk and hold them to these pins
+// (`lock.verifier.ts`).
+//
+// The lock pins content, not a registry: the same lock holds against any registry
+// that has those revisions. The registry's address and key come from the
+// environment when the CLI talks to it.
+import { fail, isNamespace, isRecord } from "../policies.compiler.js";
+/** The format marker of every lock file. */
+export const LOCK_FORMAT = "aventara-access/lock@1";
+/** The lock's file name, at the project's root. */
+export const LOCK_FILE = "avAccess.lock.json";
+const HASH = /^sha256:[0-9a-f]{64}$/;
+/** The members a lock has, and a pin's. Anything else is refused. */
+const LOCK_KEYS = ["format", "namespace", "policies", "guardrails", "foreign"];
+const PIN_KEYS = ["path", "hash"];
+/** What a pin's path never holds: a backslash, a control character or a line separator. */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: the characters it refuses
+const UNSAFE = /[\\\u0000-\u001f\u007f-\u009f\u2028\u2029]/;
+/**
+ * Whether a pin's path stays inside the lock's directory on every platform: relative,
+ * `/`-separated, no `..`, no drive letter, and nothing that would end a line where
+ * it is printed or written into a comment.
+ */
+const isPinPath = (path) => typeof path === "string" &&
+    path !== "" &&
+    !path.startsWith("/") &&
+    !/^[A-Za-z]:/.test(path) &&
+    !UNSAFE.test(path) &&
+    !path.split("/").includes("..");
+const isPin = (value) => isRecord(value) &&
+    Object.keys(value).every((key) => PIN_KEYS.includes(key)) &&
+    isPinPath(value.path) &&
+    typeof value.hash === "string" &&
+    HASH.test(value.hash);
+/**
+ * Checks that `lock` is an `aventara-access/lock@1` lock, naming what is wrong. A
+ * pin's path stays inside the lock's directory.
+ */
+export const checkLock = (lock, where = "lock") => {
+    if (!isRecord(lock)) {
+        return fail(where, `${LOCK_FILE} holds an object, as \`avaccess pull\` writes it`);
+    }
+    if (lock.format !== LOCK_FORMAT) {
+        fail(where, `the lock's format is ${JSON.stringify(LOCK_FORMAT)}; it was ${JSON.stringify(lock.format)}`);
+    }
+    const unknown = Object.keys(lock).filter((key) => !LOCK_KEYS.includes(key));
+    if (unknown.length > 0) {
+        fail(where, `a lock has ${LOCK_KEYS.map((key) => `\`${key}\``).join(", ")}; it does not take ${unknown.map((key) => `\`${key}\``).join(", ")}`);
+    }
+    if (typeof lock.namespace !== "string" || !isNamespace(lock.namespace)) {
+        fail(where, `the lock's namespace ${JSON.stringify(lock.namespace)} is not a namespace name`);
+    }
+    if (!isPin(lock.policies)) {
+        fail(where, "the lock's `policies` is `{ path, hash }`: a relative path inside the project and a `sha256:` hash");
+    }
+    if (lock.guardrails !== null && !isPin(lock.guardrails)) {
+        fail(where, "the lock's `guardrails` is `{ path, hash }` (a relative path inside the project and a `sha256:` hash) or `null`");
+    }
+    if (lock.foreign !== undefined && !isPin(lock.foreign)) {
+        fail(where, "the lock's `foreign` is `{ path, hash }`: a relative path inside the project and a `sha256:` hash");
+    }
+    return lock;
+};

package/dist/lock/lock.verifier.d.ts

@@ -0,0 +1,27 @@
+import type { AccessPolicies } from "../policies-contract.js";
+import { type AccessLock } from "./lock-contract.js";
+/** What is held to a lock: the namespace the rules name, and the pulled files. */
+type LockedFiles = {
+    /** The namespace the rules or the policies file name (`undefined`: none). */
+    readonly namespace: string | undefined;
+    /**
+     * The namespace's pulled policies file; left out when the engine runs from the
+     * typed rules, whose source is the project's own.
+     */
+    readonly policies?: unknown;
+    /** The org's pulled guardrails file, or `undefined` when none is used. */
+    readonly guardrails: unknown;
+};
+/**
+ * Holds `files` to `lock`: the same namespace, the policies file (when given) and
+ * the guardrails file each hashing to its pin, and guardrails used exactly when the
+ * lock pins some. Throws `ACCESS_LOCK_MISMATCH`, naming the file and both hashes.
+ * The lock is checked first (`checkLock`).
+ */
+export declare const verifyLocked: (lock: AccessLock, files: LockedFiles) => void;
+/**
+ * The namespaces whose Resources a policies file reads as foreign, sorted: those
+ * whose beacons a service started from a lock checks (`checkBeacons`).
+ */
+export declare const foreignOwnersOf: (policies: AccessPolicies) => readonly string[];
+export {};

package/dist/lock/lock.verifier.js

@@ -0,0 +1,62 @@
+// The check of pulled files against `avAccess.lock.json`, offline: each file is hashed
+// with the same code the registry keys its revisions by (`policiesHash`,
+// `guardrailsHash`) and held to the hash the lock pins for it. `avaccess verify` runs
+// it over the files on disk, in a build's `aventara:prepare` chain; the engine runs
+// it again over the files it is built with (`createAccessEngine(file, { lock })`).
+// A file edited after `avaccess pull` fails both, with `ACCESS_LOCK_MISMATCH`.
+import { AccessError } from "../access/access.error.js";
+import { guardrailsHash } from "../guardrails/guardrails.hash.js";
+import { policiesHash } from "../policies.hash.js";
+import { LOCK_FILE, } from "./lock-contract.js";
+const mismatch = (message) => {
+    throw new AccessError("ACCESS_LOCK_MISMATCH", message);
+};
+const AGAIN = "Pull it again with `avaccess pull`; a pulled file is never edited by hand";
+/** The hash of a pulled file, or a mismatch naming why it has none (it is no file the engine runs from). */
+const hashOf = (pin, file, hash) => {
+    try {
+        return hash(file);
+    }
+    catch (error) {
+        return mismatch(`${pin.path} is pinned in ${LOCK_FILE} under ${pin.hash}, and is no longer a file the engine runs from (${String(error.message).replace(/^Aventara Access: /, "")}): it was changed after it was pulled. ${AGAIN}`);
+    }
+};
+const holdTo = (pin, file, hash) => {
+    const found = hashOf(pin, file, hash);
+    if (found !== pin.hash) {
+        mismatch(`${pin.path} hashes to ${found}, and ${LOCK_FILE} pins ${pin.hash}: it was changed after it was pulled. ${AGAIN}`);
+    }
+};
+/**
+ * Holds `files` to `lock`: the same namespace, the policies file (when given) and
+ * the guardrails file each hashing to its pin, and guardrails used exactly when the
+ * lock pins some. Throws `ACCESS_LOCK_MISMATCH`, naming the file and both hashes.
+ * The lock is checked first (`checkLock`).
+ */
+export const verifyLocked = (lock, files) => {
+    if (files.policies !== undefined) {
+        holdTo(lock.policies, files.policies, policiesHash);
+    }
+    if (files.namespace !== lock.namespace) {
+        mismatch(files.namespace === undefined
+            ? `${LOCK_FILE} pins namespace "${lock.namespace}", and the rules name no namespace: write \`definePolicies(model, { namespace: "${lock.namespace}" })\``
+            : `${LOCK_FILE} pins namespace "${lock.namespace}", and the rules are namespace "${files.namespace}"'s: pull this project's own namespace (\`avaccess pull --namespace ${files.namespace}\`)`);
+    }
+    if (lock.guardrails === null) {
+        if (files.guardrails !== undefined) {
+            mismatch(`${LOCK_FILE} pins no guardrails file (the registry had none at pull), and guardrails were given: pull them with \`avaccess pull\`, or leave them out`);
+        }
+        return;
+    }
+    if (files.guardrails === undefined) {
+        mismatch(`${LOCK_FILE} pins the org's guardrails (${lock.guardrails.path}, ${lock.guardrails.hash}), and none were given: pass the pulled file as \`guardrails\`, so the org's denies apply`);
+    }
+    holdTo(lock.guardrails, files.guardrails, guardrailsHash);
+};
+/**
+ * The namespaces whose Resources a policies file reads as foreign, sorted: those
+ * whose beacons a service started from a lock checks (`checkBeacons`).
+ */
+export const foreignOwnersOf = (policies) => [
+    ...new Set(Object.values(policies.schema).flatMap((facts) => facts.foreign === undefined ? [] : [facts.foreign])),
+].sort();

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

@@ -0,0 +1,13 @@
+import type { AccessEngine, DecisionObserver } from "../access.engine.js";
+type GovernedShape = {
+    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
+ * asked of `engine` as it is. `observe` (the audit log's hook) hears the gate's own
+ * refusals of `can`; the engine reports the rest itself.
+ */
+export declare const agentGated: <Governed extends GovernedShape>(engine: AccessEngine<Governed>, observe: DecisionObserver | undefined) => AccessEngine<Governed>;
+export {};

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

@@ -0,0 +1,75 @@
+// The gate a token's principal passes before the rules: what its access token grants
+// (`agent.grant.ts`) narrows what its user's grants allow, and never widens it.
+//
+// - An agent's token is for the MCP endpoint alone (RFC 8707): the principal it
+//   yields is refused every question asked under any origin but `agent`, so the
+//   token opens nothing through the protocol routes, `_access/can` or a server-side
+//   call.
+// - A token addressed to the service itself (`audience`) is taken under every origin.
+// - Either way, `aventara:read` admits the read questions (`can` and `scopeOf` of
+//   `read`, `fieldsOf` of `read`) and `aventara:write` the write ones (`create`,
+//   `update`, `delete`, and `fieldsOf` of `write`); a question its scopes do not
+//   admit is refused. One they admit is the user's own, answered by the rules as
+//   they answer the user under that origin: a token never acts beyond the user who
+//   consented, and the rules may narrow it further by origin.
+//
+// A refused `can` is a decision like any other: the audit log has it, with the reason
+// `deny:mcp-audience` (the wrong origin) or `deny:mcp-scope` (a scope missing).
+import { grantOf, MCP_READ_SCOPE, MCP_WRITE_SCOPE, } from "./agent.grant.js";
+/** The audit's names for the gate's two refusals. */
+const MCP_AUDIENCE_RULE = "mcp-audience";
+const MCP_SCOPE_RULE = "mcp-scope";
+const NO_FIELDS = Object.freeze({
+    always: Object.freeze([]),
+    perRow: Object.freeze({}),
+});
+/** Why the gate refuses a question of a token's principal, or `undefined` when it passes it to the rules. */
+const refusalOf = (grant, origin, writes) => {
+    if (grant.via === "mcp" && origin !== "agent") {
+        return MCP_AUDIENCE_RULE;
+    }
+    return grant.scopes.includes(writes ? MCP_WRITE_SCOPE : MCP_READ_SCOPE)
+        ? undefined
+        : MCP_SCOPE_RULE;
+};
+/**
+ * `engine` with the token gate before it: a principal without a token's grant is
+ * asked of `engine` as it is. `observe` (the audit log's hook) hears the gate's own
+ * refusals of `can`; the engine reports the rest itself.
+ */
+export const agentGated = (engine, observe) => ({
+    // The startup facts, `explain` and the beacon check, as the engine has them.
+    ...engine,
+    can(question) {
+        const grant = grantOf(question.principal);
+        if (grant === undefined) {
+            return engine.can(question);
+        }
+        const refused = refusalOf(grant, question.origin, question.action !== "read");
+        if (refused === undefined) {
+            return engine.can(question);
+        }
+        if (observe === undefined) {
+            return false;
+        }
+        return Promise.resolve(observe(question, false, { kind: "deny", id: refused })).then(() => false);
+    },
+    scopeOf(question) {
+        const grant = grantOf(question.principal);
+        if (grant !== undefined &&
+            refusalOf(grant, question.origin, question.action !== "read") !==
+                undefined) {
+            return false;
+        }
+        return engine.scopeOf(question);
+    },
+    fieldsOf(question) {
+        const grant = grantOf(question.principal);
+        if (grant !== undefined &&
+            refusalOf(grant, question.origin, question.access === "write") !==
+                undefined) {
+            return NO_FIELDS;
+        }
+        return engine.fieldsOf(question);
+    },
+});

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

@@ -0,0 +1,40 @@
+import type { TokenGrant } from "../oauth/access-token.verifier.js";
+/** The scope that lets an agent read: every `read` question its user's grants answer. */
+export declare const MCP_READ_SCOPE = "aventara:read";
+/** The scope that lets an agent write: every `create`, `update` and `delete` question its user's grants answer. */
+export declare const MCP_WRITE_SCOPE = "aventara:write";
+/** Whether a token's scopes name one of Access's: what a token addressed to the service must carry. */
+export declare const hasAventaraScope: (scopes: ReadonlySet<string>) => boolean;
+/** What an access token grants the principal it yields: its client, its scopes, and which resource it was for. */
+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. */
+    readonly clientId: string;
+    /** The token's scopes. */
+    readonly scopes: readonly string[];
+};
+/**
+ * The principal a token's request runs as: a copy of `me` (its own enumerable
+ * fields, on the same prototype) marked with the grant, by a non-enumerable property,
+ * so a spread, `JSON.stringify` or `Object.keys` of it does not show the mark. `null`
+ * stays `null` (an anonymous caller). A principal that is not an object cannot carry
+ * the grant, and is refused: such a request never runs as an unmarked principal.
+ */
+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) => 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
+ * for one. Answers the client the token was issued to and its scopes; `null` for any
+ * other principal (a user's session, a token addressed to the service, nobody).
+ */
+export declare const agentOf: (me: unknown) => AccessAgent | null;

package/dist/mcp/agent.grant.js

@@ -0,0 +1,92 @@
+// What an OAuth access token grants the caller it yields, carried on the principal
+// its request runs as. The framework hands the policy engine `ctx.$state.me` and the
+// request's origin, nothing else, so the grant travels with `me`, as the `sub` does
+// (`principal.subject.ts`): under a key every copy of Access names the same
+// (`Symbol.for`), so whichever instance the host asks for the policy (under Next,
+// another bundle's) reads it.
+//
+// Two tokens carry one: an agent's, for the MCP endpoint (`via: "mcp"`), and one
+// addressed to the service itself (`via: "audience"`, the opt-in). The policy holds
+// either to its scopes before the rules (`agent-scope.gate.ts`). An agent's is public
+// too: `agentOf(me)` tells app code that a principal is an agent's, and which client
+// acts with which scopes.
+//
+// The principal a token's request runs as is a copy of the one `principal` returned:
+// an app may hand out one object per user (cached), and the grant marks this
+// request's object only, never the user's own requests that share it.
+import { AccessError } from "../access/access.error.js";
+/** The scope that lets an agent read: every `read` question its user's grants answer. */
+export const MCP_READ_SCOPE = "aventara:read";
+/** The scope that lets an agent write: every `create`, `update` and `delete` question its user's grants answer. */
+export const MCP_WRITE_SCOPE = "aventara:write";
+/** Whether a token's scopes name one of Access's: what a token addressed to the service must carry. */
+export const hasAventaraScope = (scopes) => scopes.has(MCP_READ_SCOPE) || scopes.has(MCP_WRITE_SCOPE);
+/** The key the grant is carried under: the same in every bundle and every copy of Access. */
+const GRANT = Symbol.for("@aventara/access:agent-grant");
+/** The key of the one map, per process, holding the grant of a principal that takes no property. */
+const UNMARKABLE = Symbol.for("@aventara/access:agent-grants");
+const unmarkable = () => {
+    const holder = globalThis;
+    holder[UNMARKABLE] ??= new WeakMap();
+    return holder[UNMARKABLE];
+};
+/**
+ * The principal a token's request runs as: a copy of `me` (its own enumerable
+ * fields, on the same prototype) marked with the grant, by a non-enumerable property,
+ * so a spread, `JSON.stringify` or `Object.keys` of it does not show the mark. `null`
+ * stays `null` (an anonymous caller). A principal that is not an object cannot carry
+ * the grant, and is refused: such a request never runs as an unmarked principal.
+ */
+export const withGrant = (me, grant) => {
+    if (me === null || me === undefined) {
+        return null;
+    }
+    if (typeof me !== "object") {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "`principal` returned a value that is not an object for a request with an OAuth access token: Access marks the principal it runs as with what its token grants, so the policies hold it to its scopes, and only an object carries the mark. Return an object (or `null`).");
+    }
+    const copy = Object.assign(Object.create(Object.getPrototypeOf(me)), me);
+    const frozen = Object.freeze({
+        clientId: grant.clientId,
+        scopes: Object.freeze([...grant.scopes]),
+        via: grant.via,
+    });
+    try {
+        Object.defineProperty(copy, GRANT, {
+            value: frozen,
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    }
+    catch {
+        unmarkable().set(copy, frozen);
+    }
+    return copy;
+};
+/** What a token grants the principal it yields; `undefined` for any other principal. */
+export const grantOf = (principal) => {
+    if (typeof principal !== "object" || principal === null) {
+        return undefined;
+    }
+    const carried = Reflect.get(principal, GRANT);
+    if (carried !== undefined) {
+        return carried;
+    }
+    return unmarkable().get(principal);
+};
+/**
+ * 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
+ * for one. Answers the client the token was issued to and its scopes; `null` for any
+ * other principal (a user's session, a token addressed to the service, nobody).
+ */
+export const agentOf = (me) => {
+    const grant = grantOf(me);
+    if (grant === undefined || grant.via !== "mcp") {
+        return null;
+    }
+    return Object.freeze({
+        clientId: grant.clientId,
+        scopes: Object.freeze([...grant.scopes]),
+    });
+};

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

@@ -0,0 +1,60 @@
+/** The `mcp` block. */
+export type AccessMcpOptions = {
+    /**
+     * The MCP endpoint's URL, as its protected-resource metadata names it (RFC 9728
+     * `resource`): `https://app.example.com/mcp`. Every access token an agent is
+     * issued for it carries it as the audience (RFC 8707), and `access.mcp.verify`
+     * takes no token that does not. List it in the OAuth provider's `resources` too.
+     */
+    readonly resource: string;
+    /**
+     * Takes the OAuth provider's open dynamic client registration
+     * (`allowUnauthenticatedClientRegistration: true`), which Access refuses otherwise:
+     * a client registered that way is whoever it says it is, by its name, its logo and
+     * its redirect URI. Prefer Client ID Metadata Documents (`@better-auth/cimd`), whose
+     * client is the domain its document is served from. Off by default.
+     */
+    readonly openRegistration?: boolean;
+};
+/** `access.mcp`: the framework's `mcp.authorization`, `mcp: { path, authorization: access.mcp }`. */
+export type AccessMcpAuthorization<Claims> = {
+    /** The authorization server an agent's token comes from: Access's issuer, alone. */
+    readonly servers: readonly [string];
+    /**
+     * Checks one bearer token: an access token Better Auth's OAuth provider issued
+     * for the MCP endpoint, current, of a client that is not disabled, a user who
+     * still exists and still consents to its scopes and the endpoint, and the session it
+     * was issued in, which has not ended. Resolves to who the agent acts for, with the claims
+     * that user holds now, the client and the scopes; `null` for any other token.
+     */
+    verify(token: string): Promise<AccessAgentIdentity<Claims> | null>;
+};
+/** Who an agent's access token acts for, as `access.mcp.verify` resolves it. */
+export type AccessAgentIdentity<Claims> = {
+    /** The user the agent acts for. */
+    readonly sub: string;
+    /** The claims that user holds now, as a token `GET /token` issued now would carry them. */
+    readonly claims: Claims;
+    /** The OAuth client the token was issued to. */
+    readonly clientId: string;
+    /** The token's scopes. */
+    readonly scopes: readonly string[];
+};
+/** The checked `mcp` block. */
+type CheckedMcp = {
+    readonly resource: string;
+    readonly openRegistration: boolean;
+};
+/**
+ * The `mcp` block, checked: `{ resource, openRegistration? }`, the MCP endpoint's URL
+ * as its protected-resource metadata writes it (`checkResourceUrl`), and whether open
+ * registration is taken. `undefined` when the block is absent.
+ */
+export declare const checkMcpOptions: (value: unknown, at: string, issuer: string) => CheckedMcp | undefined;
+/**
+ * The authorization server `access.mcp.servers` names: the issuer, when it is https,
+ * or http on `127.0.0.1` or `[::1]` (the framework's rule). `localhost` is
+ * refused with the address to write instead.
+ */
+export declare const authorizationServerOf: (issuer: string, baseURLAt: string) => string;
+export {};