@aventara/access 0.0.0-stage → 0.1.0-rc.0

package/dist/access/policies-block.checker.js

@@ -0,0 +1,138 @@
+// The `policies` block and the `principal` option, checked: one check for
+// `createAccess({ policies, principal })` and `aventaraAccess({ policies, principal })`,
+// run when each is called. It builds the engine once from the rules, the guardrails
+// and the lock, so a file the engine would refuse is refused here, and holds the
+// claims the rules and the guardrails read to `policies.claims`.
+import { engineOf, } from "../access.engine.js";
+import { decisionObserver } from "../audit/audit.log.js";
+import { agentGated } from "../mcp/agent-scope.gate.js";
+import { isRecord } from "../policies.compiler.js";
+import { authTablesOf, } from "../resources/auth-tables.catalog.js";
+import { authTableNaming, guardAuthTables, } from "../resources/auth-tables.guard.js";
+import { AccessError } from "./access.error.js";
+import { prismaAdapterOf, } from "./better-auth.hardening.js";
+import { checkClaimSources, checkClaimsDeclaration, checkRulesClaims, } from "./claims.mapper.js";
+import { subjectOf } from "./principal.subject.js";
+/** The shortest and longest a token may live, in seconds, and the default. */
+const TOKEN_TTL = { min: 300, max: 900, default: 900 };
+const POLICIES_KEYS = new Set([
+    "rules",
+    "claims",
+    "claimsOf",
+    "guardrails",
+    "lock",
+    "requireLock",
+    "tokenTtl",
+]);
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const isBuilder = (rules) => isRecord(rules) && typeof rules.contract === "function";
+/** Refuses a `policies` block (`given`) and a `principal` that Access does not take. */
+export const checkPoliciesBlock = (given, principal) => {
+    if (!isRecord(given)) {
+        return refuse("`policies` is `{ rules, claims, claimsOf?, guardrails?, lock?, requireLock?, tokenTtl? }`.");
+    }
+    for (const key of Object.keys(given)) {
+        if (!POLICIES_KEYS.has(key)) {
+            refuse(`\`policies\` does not take \`${key}\`; it takes \`rules\`, \`claims\`, \`claimsOf\`, \`guardrails\`, \`lock\`, \`requireLock\` and \`tokenTtl\`.`);
+        }
+    }
+    const claims = checkClaimsDeclaration(given.claims);
+    const { rules, claimsOf, guardrails, lock, requireLock, tokenTtl = TOKEN_TTL.default, } = given;
+    if (typeof tokenTtl !== "number" ||
+        !Number.isInteger(tokenTtl) ||
+        tokenTtl < TOKEN_TTL.min ||
+        tokenTtl > TOKEN_TTL.max) {
+        refuse(`\`policies.tokenTtl\` is how long a token lives, in whole seconds from ${TOKEN_TTL.min} to ${TOKEN_TTL.max} (5 to 15 minutes); it was ${JSON.stringify(tokenTtl)}.`);
+    }
+    if (guardrails !== undefined && !isRecord(guardrails)) {
+        refuse("`policies.guardrails` is the org's guardrails file, as pulled from the registry (`aventara-access/guardrails@1`).");
+    }
+    if (claimsOf !== undefined && typeof claimsOf !== "function") {
+        refuse("`policies.claimsOf` is a function: `({ user, session }) => ({ … })`.");
+    }
+    const file = isBuilder(rules) ? rules.contract() : rules;
+    if (!isRecord(file)) {
+        return refuse("`policies.rules` is the rules, `definePolicies(model)…`, or their compiled file, `.contract()`.");
+    }
+    if (requireLock !== undefined && typeof requireLock !== "boolean") {
+        refuse(`\`policies.requireLock\` is \`true\` (refuse to start without \`lock\`) or \`false\`; it was ${JSON.stringify(requireLock)}.`);
+    }
+    const engineOptions = guardrails === undefined && lock === undefined && requireLock === undefined
+        ? undefined
+        : {
+            ...(guardrails === undefined
+                ? {}
+                : { guardrails: guardrails }),
+            ...(lock === undefined ? {} : { lock: lock }),
+            ...(requireLock === undefined
+                ? {}
+                : { requireLock: requireLock }),
+        };
+    const source = isBuilder(rules) ? "rules" : "file";
+    // The rules, the guardrails and the lock are checked here; the engine the
+    // instance answers with is built on first read, with the built-in rules over
+    // Better Auth's tables added (`guardedPolicy`).
+    engineOf(file, engineOptions, source);
+    checkRulesClaims(file, claims);
+    if (guardrails !== undefined) {
+        checkRulesClaims(guardrails, claims, "guardrails");
+    }
+    if (principal !== undefined && typeof principal !== "function") {
+        refuse("`principal` is a function: `({ sub, claims }) => me`.");
+    }
+    return {
+        claims,
+        file: file,
+        source,
+        engineOptions,
+        claimsOf: claimsOf,
+        tokenTtl: tokenTtl,
+        principal: principal,
+    };
+};
+/**
+ * The engine the framework asks, with Access's built-in rules over Better Auth's
+ * tables (as Better Auth is built: its plugins' tables and Access's own included),
+ * named as the app's schema names them, the audit log's observer when it is on, and
+ * the agent gate before it all (`mcp/agent-scope.gate.ts`): a principal an agent's
+ * access token yielded is held to that token's audience and scopes first.
+ */
+export const guardedPolicy = (input) => {
+    const { checked, auditLog, resources, tables, naming } = input;
+    const observe = auditLog === undefined ? undefined : decisionObserver(auditLog, subjectOf);
+    return agentGated(engineOf(checked.file, checked.engineOptions, checked.source, observe, guardAuthTables({ resources, tables, naming, policies: checked.file })), observe);
+};
+/**
+ * Better Auth's tables for the options it is built with (`options`, its plugins and
+ * Access's own included), checked against the claims and the rules: a declared
+ * claim the default mapping (no `claimsOf`) reads must come from a user field the
+ * user cannot set (`bridged`, the claims the organization bridge fills, are not read
+ * from the user); and the rules' schema names each table, on the Prisma adapter by
+ * the models it reads, on any other by `resources.authTables`.
+ */
+export const betterAuthTablesFor = (input) => {
+    const { options, modules, checked, resources, bridged } = input;
+    const betterAuthTables = modules.getAuthTables(options);
+    if (checked.claimsOf === undefined) {
+        const read = {
+            ...checked.claims,
+        };
+        for (const claim of bridged ?? []) {
+            delete read[claim];
+        }
+        checkClaimSources(read, betterAuthTables.user?.fields);
+    }
+    const schema = checked.file.schema;
+    const schemaEmpty = Object.keys(schema).length === 0;
+    const naming = authTableNaming({
+        prisma: schemaEmpty
+            ? undefined
+            : prismaAdapterOf(options.database, options),
+        authTables: resources.authTables,
+        models: Object.keys(betterAuthTables),
+        schemaEmpty,
+    });
+    return { tables: authTablesOf(betterAuthTables, schema, naming), naming };
+};

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

@@ -0,0 +1,12 @@
+/**
+ * Marks `me` as derived from `sub`: a non-enumerable property, so a spread,
+ * `JSON.stringify` or `Object.keys` of the principal does not show it.
+ *
+ * Refuses an object that already stands for another `sub`: one object handed out
+ * for two users (a principal function that returns a shared object) would carry
+ * whichever user came last, and the audit would name the wrong user for the other
+ * one's decisions.
+ */
+export declare const carrySubject: (me: unknown, sub: string) => void;
+/** The `sub` of a principal Access derived; `null` for any other principal. */
+export declare const subjectOf: (principal: unknown) => string | null;

package/dist/access/principal.subject.js

@@ -0,0 +1,60 @@
+// The `sub` a principal came from, carried on the principal itself: a decision
+// event's `userId`. The framework hands the policy engine `ctx.$state.me` and
+// nothing else, and a host may ask one Access instance for the state and another
+// for the policy: Next evaluates the app's `access.ts` once per bundle, and
+// `@aventara/next` shares the framework (and so one bundle's `access.policy`)
+// through `globalThis`. So the `sub` travels with `me`, under a key every copy of
+// Access names the same (`Symbol.for`), never in a map one instance keeps.
+import { AccessError } from "./access.error.js";
+/** The key the `sub` is carried under: the same in every bundle and every copy of Access. */
+const SUBJECT = Symbol.for("@aventara/access:sub");
+/** The key of the one map, per process, holding the `sub` of a principal that takes no property (a frozen one). */
+const FROZEN = Symbol.for("@aventara/access:frozen-subjects");
+const frozenSubjects = () => {
+    const holder = globalThis;
+    holder[FROZEN] ??= new WeakMap();
+    return holder[FROZEN];
+};
+/**
+ * Marks `me` as derived from `sub`: a non-enumerable property, so a spread,
+ * `JSON.stringify` or `Object.keys` of the principal does not show it.
+ *
+ * Refuses an object that already stands for another `sub`: one object handed out
+ * for two users (a principal function that returns a shared object) would carry
+ * whichever user came last, and the audit would name the wrong user for the other
+ * one's decisions.
+ */
+export const carrySubject = (me, sub) => {
+    if (typeof me !== "object" || me === null) {
+        return;
+    }
+    const carried = subjectOf(me);
+    if (carried !== null && carried !== sub) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "`principal` returned an object it already returned for another user: the audit names the user each principal stands for, and one object cannot stand for two. Return a new object for each user (one cached per user is fine).");
+    }
+    if (Object.isExtensible(me)) {
+        try {
+            Object.defineProperty(me, SUBJECT, {
+                value: sub,
+                enumerable: false,
+                writable: false,
+                configurable: true,
+            });
+            return;
+        }
+        catch {
+            // A proxy that refuses the property: kept in the process's map below.
+        }
+    }
+    frozenSubjects().set(me, sub);
+};
+/** The `sub` of a principal Access derived; `null` for any other principal. */
+export const subjectOf = (principal) => {
+    if (typeof principal !== "object" || principal === null) {
+        return null;
+    }
+    const carried = Reflect.get(principal, SUBJECT);
+    return typeof carried === "string"
+        ? carried
+        : (frozenSubjects().get(principal) ?? null);
+};

package/dist/access/profile.policy.d.ts

@@ -0,0 +1,74 @@
+import { type LanRange } from "../kiosk/lan-range.policy.js";
+import type { AccessClaimsDeclaration, AccessIdentity } from "./claims.mapper.js";
+/** The profiles `createAccess` takes. */
+export type AccessProfileKind = "web" | "service" | "kiosk";
+/**
+ * The `kiosk` profile: `web`, plus staff switching by PIN on enrolled devices. A
+ * PIN session is bound to the device it was opened on and locks when idle.
+ */
+export type AccessKioskProfile<C extends AccessClaimsDeclaration> = {
+    readonly kind: "kiosk";
+    /**
+     * Who may enroll a device, or revoke one: asked with the identity of a fresh
+     * session opened with full credentials (a password, never a PIN). Without a `true`
+     * the call is refused.
+     */
+    readonly canEnrollDevice: (identity: AccessIdentity<C>) => boolean | Promise<boolean>;
+    /**
+     * Seconds without a request that may change something (any method but GET, HEAD
+     * or OPTIONS; a page that only reads does not count) after which any session
+     * bound to an enrolled device locks, a PIN session or one opened there with a
+     * password: from 60 to 3600, 300 by default.
+     */
+    readonly idleTimeout?: number;
+    /**
+     * Opt-in for an on-prem till network without TLS: the private IPv4 ranges (CIDRs,
+     * a /16 or narrower, inside 10.0.0.0/8, 172.16.0.0/12 or 192.168.0.0/16) on whose
+     * addresses the kiosk takes a plain http: base URL, such as
+     * `"http://192.168.1.10:3000"`. The device's credential, the PIN sessions and the
+     * PINs then cross that network in the clear, so it must be the tills' alone (a
+     * router of their own, WPA3, no guests). Without it, http: is taken on a loopback
+     * host only.
+     */
+    readonly insecureLan?: readonly [
+        `${number}.${number}.${number}.${number}/${number}`,
+        ...`${number}.${number}.${number}.${number}/${number}`[]
+    ];
+};
+/** The `profile` block: `{ kind: "web" }` (the default), `{ kind: "service" }` or the kiosk profile. */
+export type AccessProfileOptions<C extends AccessClaimsDeclaration> = {
+    readonly kind: "web";
+} | {
+    readonly kind: "service";
+} | AccessKioskProfile<C>;
+/** The checked kiosk profile. */
+export type KioskSettings = {
+    readonly canEnrollDevice: (identity: {
+        readonly sub: string;
+        readonly claims: {
+            readonly [claim: string]: unknown;
+        };
+    }) => unknown;
+    /** In seconds. */
+    readonly idleTimeout: number;
+    /** `profile.insecureLan`, read: the ranges an http: base URL may be on. */
+    readonly insecureLan?: readonly LanRange[];
+};
+/** The checked `profile` block: its kind, and the kiosk's settings when it is the kiosk. */
+type CheckedProfile = {
+    readonly kind: AccessProfileKind;
+    readonly kiosk?: KioskSettings;
+};
+/**
+ * The checked `profile` block: `web` when none is given. One kind only: the kiosk's
+ * keys on another kind, or two kinds at once (`kind: ["kiosk", "service"]`), are
+ * refused, since a service hands no caller a session and a kiosk is made of them.
+ */
+export declare const checkProfile: (profile: unknown) => CheckedProfile;
+/** Whether the Better Auth endpoint at `path` (its declared path, as `ctx.path` holds it) starts a session. */
+export declare const startsSession: (path: unknown) => boolean;
+/** Whether a profile serves the endpoint at `path` to a request from outside. */
+export declare const servesRoute: (kind: AccessProfileKind, path: unknown) => boolean;
+/** Whether a profile reads a request's principal from its session cookie. */
+export declare const readsSessionCookie: (kind: AccessProfileKind) => boolean;
+export {};

package/dist/access/profile.policy.js

@@ -0,0 +1,110 @@
+// Profiles: what shape of app an Access instance serves. `web` is Better Auth as
+// configured: cookie sign-in, sessions, tokens. `service` serves callers that bring
+// a token: it hands no caller a new session, and a request's principal comes from
+// its bearer token alone. `kiosk` is `web` plus staff switching by PIN on enrolled
+// devices (`kiosk/kiosk.endpoints.ts`): a PIN session is bound to its device and
+// locks when idle.
+//
+// The service profile holds that two ways, both on Better Auth's own terms rather
+// than on the request's URL (whose spelling, base path and base URL vary): a route
+// that starts a session is refused before it runs, by its endpoint path; and any
+// request that creates a session anyway (a plugin route Access does not know) is
+// refused by that effect, the session revoked before the answer leaves.
+import { checkInsecureLan } from "../kiosk/lan-range.policy.js";
+import { AccessError } from "./access.error.js";
+/** The idle timeout's bounds and default, in seconds. */
+const KIOSK_IDLE_TIMEOUT = { min: 60, max: 3600, default: 300 };
+const KINDS = ["web", "service", "kiosk"];
+/** The keys each kind takes beside `kind`. */
+const KIND_KEYS = {
+    web: [],
+    service: [],
+    kiosk: ["canEnrollDevice", "idleTimeout", "insecureLan"],
+};
+/**
+ * The Better Auth routes (better-auth 1.7.12 to 1.7.14 and its plugins) that start a session
+ * for the caller, by endpoint path, relative to Better Auth's base path: every
+ * `/sign-in/*` and `/sign-up/*` route, the OAuth callbacks that finish a social or
+ * generic OAuth sign-in, and the plugins' routes that sign a user in by a code, a
+ * link, a token, a device, a second factor or an impersonation.
+ */
+const SESSION_STARTING = /^\/(?:sign-in|sign-up)(?:\/|$)|^\/(?:oauth2\/)?callback(?:\/|$)|^\/oauth-proxy-callback$/;
+const SESSION_STARTING_ROUTES = new Set([
+    "/verify-email",
+    "/magic-link/verify",
+    "/email-otp/verify-email",
+    "/phone-number/verify",
+    "/one-tap/callback",
+    "/one-time-token/verify",
+    "/siwe/verify",
+    "/passkey/verify-authentication",
+    "/two-factor/verify-totp",
+    "/two-factor/verify-otp",
+    "/two-factor/verify-backup-code",
+    "/device/token",
+    "/multi-session/set-active",
+    "/admin/impersonate-user",
+    "/admin/stop-impersonating",
+    // The kiosk profile's PIN switch (Access's own).
+    "/kiosk/switch-user",
+]);
+const SHAPE = '`profile` is `{ kind: "web" }` (the default), `{ kind: "service" }` or `{ kind: "kiosk", canEnrollDevice, idleTimeout?, insecureLan? }`';
+/**
+ * The checked `profile` block: `web` when none is given. One kind only: the kiosk's
+ * keys on another kind, or two kinds at once (`kind: ["kiosk", "service"]`), are
+ * refused, since a service hands no caller a session and a kiosk is made of them.
+ */
+export const checkProfile = (profile) => {
+    if (profile === undefined) {
+        return { kind: "web" };
+    }
+    const kind = profile?.kind;
+    if (typeof profile !== "object" ||
+        profile === null ||
+        Array.isArray(profile) ||
+        !KINDS.includes(kind)) {
+        const both = Array.isArray(kind) && kind.includes("kiosk") && kind.includes("service");
+        throw new AccessError("ACCESS_OPTIONS_INVALID", both
+            ? "`profile` names one kind: a `service` hands no caller a session, and a `kiosk` is made of them, so the two cannot be combined. Run the kiosk and the service as two instances."
+            : `${SHAPE}; it was ${JSON.stringify(profile)}.`);
+    }
+    const checked = kind;
+    for (const key of Object.keys(profile)) {
+        if (key !== "kind" && !KIND_KEYS[checked].includes(key)) {
+            throw new AccessError("ACCESS_OPTIONS_INVALID", KIND_KEYS.kiosk.includes(key)
+                ? `\`profile.${key}\` belongs to the kiosk profile (\`{ kind: "kiosk" }\`), and this profile is \`${checked}\`: a ${checked === "service" ? "service hands no caller a session, so it has no PIN switch" : "web profile has no PIN switch"}.`
+                : `${SHAPE}; it does not take \`${key}\`.`);
+        }
+    }
+    if (checked !== "kiosk") {
+        return { kind: checked };
+    }
+    const { canEnrollDevice, idleTimeout, insecureLan } = profile;
+    if (typeof canEnrollDevice !== "function") {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "the kiosk profile needs `canEnrollDevice: (identity) => boolean`: who may enroll a device (and revoke one), asked with the identity of a fresh session opened with full credentials.");
+    }
+    if (idleTimeout !== undefined &&
+        (typeof idleTimeout !== "number" ||
+            !Number.isInteger(idleTimeout) ||
+            idleTimeout < KIOSK_IDLE_TIMEOUT.min ||
+            idleTimeout > KIOSK_IDLE_TIMEOUT.max)) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", `\`profile.idleTimeout\` is whole seconds from ${KIOSK_IDLE_TIMEOUT.min} to ${KIOSK_IDLE_TIMEOUT.max} (${KIOSK_IDLE_TIMEOUT.default} by default); it was ${JSON.stringify(idleTimeout)}.`);
+    }
+    return {
+        kind: "kiosk",
+        kiosk: {
+            canEnrollDevice: canEnrollDevice,
+            idleTimeout: idleTimeout ?? KIOSK_IDLE_TIMEOUT.default,
+            ...(insecureLan === undefined
+                ? {}
+                : { insecureLan: checkInsecureLan(insecureLan) }),
+        },
+    };
+};
+/** Whether the Better Auth endpoint at `path` (its declared path, as `ctx.path` holds it) starts a session. */
+export const startsSession = (path) => typeof path === "string" &&
+    (SESSION_STARTING.test(path) || SESSION_STARTING_ROUTES.has(path));
+/** Whether a profile serves the endpoint at `path` to a request from outside. */
+export const servesRoute = (kind, path) => kind !== "service" || !startsSession(path);
+/** Whether a profile reads a request's principal from its session cookie. */
+export const readsSessionCookie = (kind) => kind !== "service";

package/dist/access/request.state.d.ts

@@ -0,0 +1,89 @@
+import { type CarriedGrant } from "../mcp/agent.grant.js";
+import type { AccessTokenVerifier } from "../oauth/access-token.verifier.js";
+import type { AccessClaimsSource } from "./claims.mapper.js";
+import { type AccessProfileKind } from "./profile.policy.js";
+import { type TokenVerifier } from "./token.verifier.js";
+/** A verified identity, untyped: the `sub` and the claims, each checked against its declared type. */
+type Identity = {
+    readonly sub: string;
+    readonly claims: {
+        readonly [claim: string]: string | number | boolean;
+    };
+};
+/** The headers of a request, as the framework hands them to `state`. */
+type RequestHeaders = {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callback: (value: string, name: string) => void): void;
+};
+/** What the state reads of a built Better Auth instance. */
+type StateAuth = {
+    readonly api: unknown;
+    readonly $context: Promise<unknown>;
+};
+/** Who a request's credential says the caller is, and, for an OAuth access token, what it grants. */
+type RequestCaller = {
+    readonly identity: Identity;
+    readonly grant?: CarriedGrant;
+};
+/** Who a request's bearer token or session cookie says the caller is; `null` for nobody. */
+type RequestIdentity = (headers: RequestHeaders, request: unknown) => Promise<RequestCaller | null>;
+/**
+ * Who Access's own `GET /me` route answers a request as: the identity of a session
+ * token, a session cookie or a token addressed to the service; `null` for nobody, and
+ * for an agent's access token, which opens nothing over HTTP but the MCP endpoint.
+ */
+export declare const meOf: (caller: RequestCaller | null) => Identity | null;
+/**
+ * Who `access.client.verbs.me` answers a request as: the identity `{ sub, claims }`
+ * of any credential the state reads, an agent's included (the framework's MCP `me`
+ * tool calls it in-process with the agent's headers). A token's identity is a copy
+ * carrying what it grants, so `agentOf` tells an agent's apart.
+ */
+export declare const verbMeOf: (caller: RequestCaller | null) => Identity | null;
+/** A request's state, as the framework's `access` option reads it. */
+type RequestState<M> = (input: {
+    readonly headers: RequestHeaders;
+    readonly request?: unknown;
+}) => Promise<{
+    readonly me: M | null;
+}>;
+/**
+ * A request's identity over one Better Auth instance (`auth`, built on first use):
+ * from a bearer token the verifier accepts (an agent's access token, the agent
+ * verifier, when `mcp` is on), or (profile `web`) from the session Better Auth's
+ * store holds for the request's cookie, with the claims `claimsFor` gives that
+ * session.
+ */
+export declare const requestIdentity: (input: {
+    readonly auth: () => StateAuth;
+    readonly verifier: TokenVerifier;
+    /** With `mcp`: the verifier of the access tokens agents are issued for the MCP endpoint. */
+    readonly agents?: AccessTokenVerifier;
+    /** With `audience`: the verifier of the access tokens addressed to this service, the only bearer tokens it then takes. */
+    readonly audience?: AccessTokenVerifier;
+    readonly kind: AccessProfileKind;
+    /** The session cookie is `sameSite: "none"`: read only from trusted sites, on every method. */
+    readonly crossSite: boolean;
+    /** A session's claims, as its token would be issued with them. */
+    readonly claimsFor: (session: AccessClaimsSource) => Promise<{
+        readonly [claim: string]: string | number | boolean;
+    }>;
+}) => RequestIdentity;
+/**
+ * The request state over a request's identity (`requestIdentity`): `me` is the
+ * identity, or what the app's `principal` maps it to, with the `sub` carried on it
+ * for the audit, and, for an OAuth access token, a copy of it carrying what the
+ * token grants. The identity `principal` is given for such a token carries the grant
+ * too, so `agentOf(identity)` tells the app an agent's request while it maps it.
+ */
+export declare const requestState: (identityOf: RequestIdentity, principal: ((identity: Identity) => unknown) | undefined) => RequestState<unknown>;
+/**
+ * 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
+ * have been revoked since, so a token is issued only for one the store still has.
+ */
+export declare const sessionStillLive: (store: () => Promise<unknown>, session: {
+    readonly [field: string]: unknown;
+}, refuse: () => Error) => Promise<void>;
+export {};