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

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

@@ -0,0 +1,74 @@
+import type { AccessBuilder } from "../access.builder.js";
+import type { AccessGuardrails, AccessGuardrailsJson } from "../guardrails/guardrails-contract.js";
+import type { AccessLock } from "../lock/lock-contract.js";
+import type { AccessPolicies, AccessPoliciesJson } from "../policies-contract.js";
+import type { AccessClaimsAnswer, AccessClaimsDeclaration, AccessClaimsSource } from "./claims.mapper.js";
+/** The fields each Resource governs, by Resource: what the rules' engine is typed with. */
+type GovernedShape = {
+    readonly [resource: string]: readonly string[] | {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+};
+/** The builder's `govern` block: a mode per governed field. */
+type ModesShape = {
+    readonly [resource: string]: {
+        readonly [field: string]: "read" | "write" | "both";
+    };
+};
+/** The claims a rules principal type `R` reads, by name. */
+type ClaimNamesOf<R> = R extends {
+    readonly claims?: infer C;
+} ? keyof NonNullable<C> & string : never;
+/**
+ * `policies.claims`, held to the rules: a claim the rules' principal type reads and
+ * the declaration lacks is a type error here, naming it.
+ */
+type DeclaredFor<R, C extends AccessClaimsDeclaration> = [
+    Exclude<ClaimNamesOf<R>, keyof C>
+] extends [never] ? C : C & {
+    readonly [K in Exclude<ClaimNamesOf<R>, keyof C>]: `the rules read the claim "${K}": declare it here, or correct the rules' principal type`;
+};
+/**
+ * The rules an instance evaluates: `definePolicies(model)…` as written, or its
+ * compiled file (typed, or imported as JSON as `avaccess pull` wrote it).
+ */
+export type AccessRules<R, Gov extends GovernedShape> = AccessBuilder<any, R, any, Gov & ModesShape> | AccessPolicies<Gov> | AccessPoliciesJson<Gov>;
+/** The `policies` block. */
+export type AccessPoliciesOptions<C extends AccessClaimsDeclaration, R, Gov extends GovernedShape> = {
+    /** The rules this instance evaluates: the builder (its principal type is checked here) or its compiled file. */
+    readonly rules: AccessRules<R, Gov>;
+    /** The global claims a token carries beside `sub`, by type: `{ role: "string", banned: "boolean" }`. */
+    readonly claims: DeclaredFor<R, C>;
+    /**
+     * A user's claims, when a token is issued: every declared boolean claim, the
+     * others where the user has them. Without it, each declared claim is read from
+     * the user's field of the same name.
+     */
+    readonly claimsOf?: (source: AccessClaimsSource) => AccessClaimsAnswer<C> | Promise<AccessClaimsAnswer<C>>;
+    /**
+     * The org's guardrails, as pulled from the registry (`aventara-access/guardrails@1`):
+     * deny-only rules the engine adds on top of `rules`. They only narrow. Every claim
+     * they compare must be declared in `claims`.
+     */
+    readonly guardrails?: AccessGuardrails | AccessGuardrailsJson;
+    /**
+     * The project's `avAccess.lock.json`, as `avaccess pull` wrote it: the instance
+     * refuses to start (`ACCESS_LOCK_MISMATCH`) unless `guardrails`, and `rules` when
+     * they are a pulled file, hash to what the lock pins.
+     */
+    readonly lock?: AccessLock;
+    /**
+     * `true`: refuse to start without `lock` (`ACCESS_LOCK_MISMATCH`), so a deploy that
+     * lost its `avAccess.lock.json` fails at startup instead of running unpinned files;
+     * typed rules are then held to the lock's policies hash too. Recommended in
+     * production.
+     */
+    readonly requireLock?: boolean;
+    /**
+     * How long a token lives, in seconds: from 300 to 900 (5 to 15 minutes), 900 by
+     * default. A claim that must take effect soon (`banned`, `suspended`) reaches every
+     * service with the user's next token, so this is the longest such a change waits.
+     */
+    readonly tokenTtl?: number;
+};
+export {};

package/dist/access/access-options.js

@@ -0,0 +1,5 @@
+// The `policies` block's types, which `createAccess` and `aventaraAccess()` share: the
+// rules, and the claims they read, held to each other. Both are published from
+// `/auth`; what they are built from stays in this module, so a consumer's
+// declaration emit writes it out rather than naming a module it cannot import.
+export {};

package/dist/access/access.error.d.ts

@@ -0,0 +1,35 @@
+/** What an {@link AccessError} refuses. */
+export type AccessErrorCode = 
+/** `better-auth` is missing, or outside Access's range (`~1.7.12`), as is an OAuth provider or `cimd()` Access reads. */
+"ACCESS_BETTER_AUTH_VERSION"
+/** A claim the rules read, or one a token carries, that `policies.claims` does not declare. */
+ | "ACCESS_CLAIMS_UNDECLARED"
+/** `betterAuth.plugins` holds a plugin `createAccess` installs itself (under any case or spacing of its id), or one that defines `jwt()`'s endpoints or Access's `me` route. */
+ | "ACCESS_PLUGIN_DUPLICATE"
+/** An Access block (`policies`, `principal`, `profile`, `registry`, `audit`, `resources`, `passwords`) is not one `createAccess` accepts; `passwords` set beside Better Auth's own `emailAndPassword.password` hook, or argon2id asked of a runtime without `crypto.argon2` or `@node-rs/argon2`; the rules grant what the `resources` block leaves closed; a claim would be read from a field the user can set; Better Auth has no base URL to fix the tokens' issuer; the session cookie is `sameSite: "none"` without trusted origins; Better Auth off its Prisma adapter without `resources.authTables`, or an opened table's secret column not found; or `principal` returned one object for two users. */
+ | "ACCESS_OPTIONS_INVALID"
+/** A pushed file names a Resource its namespace does not own, or the org's guardrails file grants. */
+ | "ACCESS_OWNERSHIP"
+/** A registry key that is wrong, revoked or rotated out, or one whose kind or namespace does not fit the call. */
+ | "ACCESS_KEY_REFUSED"
+/** A pushed file is not a policies file, or the org's guardrails are not a guardrails file, the engine would run from. */
+ | "ACCESS_POLICIES_INVALID"
+/** A namespace name that is not one, a namespace the registry does not have (a guardrail's included), or one it has already. */
+ | "ACCESS_NAMESPACE"
+/** A stored revision no longer hashes to the hash it was pushed under: it was changed outside the registry. */
+ | "ACCESS_REVISION_CHANGED"
+/** A pulled file no longer hashes to the hash `avAccess.lock.json` pins for it, or the engine was handed files the lock does not pin. */
+ | "ACCESS_LOCK_MISMATCH"
+/** A Better Auth table `resources` opens is missing: Better Auth has none (its plugin is not installed), or the rules' schema has no Resource for it. */
+ | "ACCESS_RESOURCE_MISSING"
+/** A question the engine cannot answer as asked: a `fieldsOf` question without `access: "read"` or `access: "write"`, or with an `action` that does not fit it; or a `hosted` call whose `held` is not a list of Resource names. */
+ | "ACCESS_QUESTION_INVALID"
+/** A file reads another namespace's Resources as `foreign` while the two are on different databases: the reader's view of the owner's beacon is not the one the owner pushed, the owner has pushed none, or the push carries none. */
+ | "ACCESS_FOREIGN_CROSS_DATABASE"
+/** A beacon that is not what it should be: at startup an owner's row, read through the service's own connection, is missing or does not hash to the lock's pin (or was not checked yet); at push a namespace's own beacon is another namespace's; or a beacon row holds no beacon. */
+ | "ACCESS_BEACON_MISMATCH";
+/** A refusal by `createAccess`, the instance it built, its registry, or an engine checking its lock or a question: `code` says which, the message what to change. */
+export declare class AccessError extends Error {
+    readonly code: AccessErrorCode;
+    constructor(code: AccessErrorCode, message: string);
+}

package/dist/access/access.error.js

@@ -0,0 +1,11 @@
+// The one error `createAccess` and the instance it builds throw. Each refusal has a
+// code a program can branch on and a message that says what to change.
+/** A refusal by `createAccess`, the instance it built, its registry, or an engine checking its lock or a question: `code` says which, the message what to change. */
+export class AccessError extends Error {
+    code;
+    constructor(code, message) {
+        super(`Aventara Access: ${message}`);
+        this.name = "AccessError";
+        this.code = code;
+    }
+}

package/dist/access/access.factory.d.ts

@@ -0,0 +1,275 @@
+import type { Auth, BetterAuthOptions, BetterAuthPlugin } from "better-auth";
+import type { jwt } from "better-auth/plugins/jwt";
+import type { AccessEngine } from "../access.engine.js";
+import type { AccessAuditOptions } from "../audit/audit-event.js";
+import type { AccessBeaconStore } from "../beacon/beacon.store.js";
+import { type AccessKiosk } from "../kiosk/kiosk.plugin.js";
+import { type AccessMcpAuthorization, type AccessMcpOptions } from "../mcp/mcp-options.js";
+import { type AccessPasswordsOptions } from "../passwords/passwords.options.js";
+import { type AccessRegistry } from "../registry/access.registry.js";
+import { type AccessRegistryOptions } from "../registry/registry.options.js";
+import { type AccessResourcesOptions } from "../resources/auth-tables.guard.js";
+import type { AccessPoliciesOptions } from "./access-options.js";
+import { type AccessClaimsDeclaration, type AccessClaimsOf, type AccessIdentity } from "./claims.mapper.js";
+import { type AccessProfileOptions } from "./profile.policy.js";
+export type { AccessPoliciesOptions, AccessRules, } from "./access-options.js";
+type GovernedShape = {
+    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 = {
+    get(name: string): string | null;
+    has(name: string): boolean;
+    forEach(callback: (value: string, name: string) => void): void;
+};
+/**
+ * The principal (`me`) an instance hands the engine: the rules' principal type when
+ * the rules are the builder, else what `principal` returns (by default the identity).
+ */
+type AccessPrincipalOf<R, M> = unknown extends R ? M : R;
+/**
+ * The request's principal (`me`) from a verified identity: the app maps `sub` to its
+ * own profile, and `null` leaves the caller anonymous. With the builder as the rules,
+ * it returns their principal type.
+ */
+type AccessPrincipalFunction<C extends AccessClaimsDeclaration, R, M> = (identity: AccessIdentity<C>) => (unknown extends R ? M : NoInfer<R>) | null | Promise<(unknown extends R ? M : NoInfer<R>) | null>;
+/**
+ * The `principal` option: optional while the identity (`{ sub, claims }`) is itself
+ * the rules' principal type, and required when the rules are typed with another.
+ */
+type AccessPrincipalOption<C extends AccessClaimsDeclaration, R, M> = [
+    AccessIdentity<C>
+] extends [R] ? {
+    /** The request's principal (`me`) from the verified identity; without it, `me` is the identity, `{ sub, claims }`. */
+    readonly principal?: AccessPrincipalFunction<C, R, M>;
+} : {
+    /** The request's principal (`me`) from the verified identity, typed as the rules' principal. */
+    readonly principal: AccessPrincipalFunction<C, R, M>;
+};
+/**
+ * The plugins `createAccess` installs itself, by id, as a sentence names each.
+ */
+declare const INSTALLED_PLUGINS: {
+    readonly "aventara-access": "aventaraAccess()";
+    readonly jwt: "jwt()";
+};
+type InstalledPluginId = keyof typeof INSTALLED_PLUGINS;
+/** One `betterAuth.plugins` entry, or the sentence that refuses it. */
+type AccessPluginEntry<E> = E extends {
+    readonly id: infer I extends InstalledPluginId;
+} ? `createAccess installs ${(typeof INSTALLED_PLUGINS)[I]} itself: remove it from betterAuth.plugins` : E;
+/** Whether a plugin list holds one `createAccess` installs itself. */
+type HoldsInstalled<L extends readonly unknown[]> = true extends {
+    [K in keyof L]: L[K] extends {
+        readonly id: InstalledPluginId;
+    } ? true : false;
+}[number] ? true : false;
+/**
+ * The `betterAuth` block: Better Auth's options as given. A plugin `createAccess`
+ * installs itself is a type error at that plugin, which reads as the sentence to fix it.
+ */
+type AccessBetterAuthBlock<O extends BetterAuthOptions> = O extends {
+    readonly plugins?: infer L extends readonly unknown[];
+} ? HoldsInstalled<L> extends true ? Omit<O, "plugins"> & {
+    readonly plugins: {
+        [K in keyof L]: AccessPluginEntry<L[K]>;
+    };
+} : O : O;
+/** Better Auth's options as `createAccess` builds Better Auth with them: the app's, and `jwt()`. */
+export type AccessBetterAuthOptions<O extends BetterAuthOptions> = Omit<O, "plugins"> & {
+    plugins: [
+        ...(O extends {
+            readonly plugins?: infer L extends readonly unknown[];
+        } ? L : []),
+        ReturnType<typeof jwt>,
+        BetterAuthPlugin & {
+            readonly id: "aventara-access";
+        }
+    ];
+};
+/** `createAccess`'s options. */
+export type AccessOptions<O extends BetterAuthOptions, C extends AccessClaimsDeclaration, R, Gov extends GovernedShape, M, E extends boolean = false, X extends AccessMcpOptions | undefined = AccessMcpOptions | undefined> = {
+    /** Better Auth's options, exactly as `betterAuth({...})` takes them. `createAccess` installs `jwt()` itself. */
+    readonly betterAuth: AccessBetterAuthBlock<O>;
+    /**
+     * The shape of app this instance serves: `web` (the default), `service` (bearer
+     * tokens only; no caller is handed a new session) or `kiosk` (`web`, plus staff
+     * switching by PIN on enrolled devices, each PIN session bound to its device and
+     * locked when idle).
+     */
+    readonly profile?: AccessProfileOptions<C>;
+    /**
+     * The policy registry: namespaces, their keys, pushed files and the org's
+     * guardrails, in tables Better Auth's adapter stores and routes `access.handler`
+     * serves under `/access/v1/namespaces`. Off by default: no tables, no routes.
+     */
+    readonly registry?: AccessRegistryOptions<E>;
+    /**
+     * The audit log of sign-ins and `can` decisions: `true` writes the `accessAudit`
+     * table (Better Auth's `generate`/`migrate` create it), `{ sink }` hands each event
+     * to the app instead. Off by default.
+     */
+    readonly audit?: AccessAuditOptions;
+    /**
+     * Which of Better Auth's tables are Resources of the rules: `users` (`user`,
+     * `session`, `account`) and `members` (the organization plugin's `member`, and its
+     * `organization`). Every other table of Better Auth's is closed, and no grant ever
+     * opens a secret column. Writes through Aventara skip Better Auth's hooks and
+     * caches, so they are limited to a user's `role` and to memberships.
+     */
+    readonly resources?: AccessResourcesOptions;
+    /**
+     * How passwords are hashed: argon2id at a named parameter profile,
+     * `"owasp-minimum"` (the default) or `"rfc9106-low-memory"`, and with
+     * `legacyScrypt: true` Better Auth's scrypt hashes accepted. A hash at another
+     * profile, or scrypt, is rehashed at the profile at its account's next sign-in.
+     * Without it, and without `betterAuth.emailAndPassword.password`, the
+     * default profile is used; an app that sets that hook hashes its own way, and may
+     * not set this too.
+     */
+    readonly passwords?: AccessPasswordsOptions;
+    /**
+     * Access as the authorization layer of an MCP endpoint (the framework's `mcp`):
+     * `{ resource }`, the endpoint's URL. The tokens come from Better Auth's OAuth
+     * provider (`@better-auth/oauth-provider`), which goes in
+     * `betterAuth.plugins` with the endpoint among its `resources`; `access.mcp` is the
+     * framework's `mcp.authorization`. Not on the `service` profile.
+     */
+    readonly mcp?: X & {
+        readonly [K in Exclude<keyof X, keyof AccessMcpOptions>]: never;
+    };
+    /**
+     * The service's own audience, an opt-in (RFC 8707): its URL, as a client names it
+     * when it asks Better Auth's OAuth provider for a token for this service
+     * (`resource`). With it, a bearer token is taken only when it is the provider's
+     * access token addressed to this audience alone; the one-org token `GET /token`
+     * issues (its audience the issuer) is refused. Session cookies are read as before.
+     * Off by default. The provider goes in `betterAuth.plugins` with the audience among
+     * its `resources`. Not on the `service` profile.
+     */
+    readonly audience?: string;
+} & AccessPoliciesMember<C, R, Gov, E> & AccessPrincipalOption<C, R, M>;
+/**
+ * The `policies` block's place in the options: required, except on an instance that
+ * serves the registry (`registry: { enabled: true }`), which may have no rules of its
+ * own: it then answers every policy question with a deny.
+ */
+type AccessPoliciesMember<C extends AccessClaimsDeclaration, R, Gov extends GovernedShape, E extends boolean> = [E] extends [true] ? {
+    /** The rules and the claims they read. A registry-only server may leave it out: no claim beside `sub`, and every policy question denied. */
+    readonly policies?: AccessPoliciesOptions<C, R, Gov>;
+} : {
+    /** The rules and the claims they read. */
+    readonly policies: AccessPoliciesOptions<C, R, Gov>;
+};
+export type { AccessRegistryOptions };
+/** `access.registry`: the operator's API when the registry is on, absent when it is off. */
+type AccessRegistryMember<E extends boolean> = [E] extends [true] ? {
+    /** The registry's operator API: namespaces, keys and the org's guardrails. */
+    readonly registry: AccessRegistry;
+} : [E] extends [false] ? {
+    readonly registry?: undefined;
+} : {
+    readonly registry?: AccessRegistry | undefined;
+};
+/** What `createAccess` returns: Better Auth's surface, the policy engine and the request state. */
+export type Access<O extends BetterAuthOptions, C extends AccessClaimsDeclaration, Gov extends GovernedShape, M, E extends boolean = false, P extends boolean = false> = {
+    /** Better Auth's request handler, with Access's routes: mount it where you would mount Better Auth's. */
+    readonly handler: Auth<AccessBetterAuthOptions<O>>["handler"];
+    /** Better Auth's server API, as `auth.api`. */
+    readonly api: Auth<AccessBetterAuthOptions<O>>["api"];
+    /** The options Better Auth is built with: the `betterAuth` block plus the plugins `createAccess` installs. */
+    readonly options: AccessBetterAuthOptions<O>;
+    /** Types only, as Better Auth's `$Infer`: `typeof access.$Infer.Me` is the principal. */
+    readonly $Infer: {
+        readonly Session: Auth<AccessBetterAuthOptions<O>>["$Infer"]["Session"];
+        readonly Me: M;
+        readonly Claims: AccessClaimsOf<C>;
+    };
+    /** The policy engine, asked about every client and agent request. */
+    readonly policy: AccessEngine<Gov>;
+    /**
+     * The Access server's own beacon row in `_aventara_beacon`, through Better Auth's
+     * adapter, on an instance with the registry on whose rules name a namespace: the
+     * store `avaccess push --beacon` loads to push it, and `policy.checkBeacons` reads
+     * through.
+     */
+    readonly beacon?: AccessBeaconStore;
+    /**
+     * The kiosk profile's operator API, for the app's own server (present on that
+     * profile only, and no route opens it): `listDevices()` and `revokeDevice(id)`.
+     * Another user's PIN is set through Better Auth's server-only endpoint,
+     * `access.api.kioskSetUserPin({ body: { userId, pin } })`.
+     */
+    readonly kiosk?: AccessKiosk;
+    /** A request's state: `me`, from its bearer token or (profiles `web` and `kiosk`) its session cookie, else `null`. */
+    state(input: {
+        readonly headers: RequestHeaders;
+        readonly request?: unknown;
+    }): Promise<{
+        readonly me: M | null;
+    }>;
+    /**
+     * What the framework's `$access` needs: where Access is mounted (`url`, from
+     * Better Auth's `baseURL` and `basePath`), and each verb this instance serves,
+     * with its route under `url`, the JSON Schema of its arguments and of its result
+     * (`me`'s: the token identity, `{ sub, claims }`, with the declared claims), and
+     * its server call. `call` runs the verb in-process through Better Auth's API with
+     * the request's headers, held to the same checks as the route (origin, profile,
+     * audit), so a cookie plugin such as `nextCookies()` sets the browser's cookie
+     * from a Server Action. A verb the instance does not serve is absent: `signIn`,
+     * `signUp` and `resetPassword` need `emailAndPassword`, the `service` profile
+     * has no `signIn` or `signUp`, and only the `kiosk` profile has its verbs:
+     * `switchUser` (`{ userId, pin }`) and `lock` on an enrolled device, `setPin`
+     * (`{ pin }`) from a fresh session opened with full credentials, and
+     * `enrollDevice` (`{ name }`) and `revokeDevice` (`{ deviceId }`) from one
+     * `canEnrollDevice` allows.
+     */
+    readonly client: {
+        /** Where the app mounted Access: absolute, or root-relative (`"/api/auth"`) when Better Auth's base URL follows the request. */
+        readonly url: string;
+        readonly verbs: {
+            readonly [V in "signIn" | "signUp" | "signOut" | "resetPassword" | "me" | "switchUser" | "lock" | "setPin" | "enrollDevice" | "revokeDevice"]?: {
+                readonly method: "GET" | "POST";
+                /** Under `url`: `"/sign-in/email"`. */
+                readonly path: string;
+                /** The JSON Schema of the arguments; absent when the verb takes none. */
+                readonly args?: {
+                    readonly [key: string]: unknown;
+                };
+                /** The JSON Schema of the result (`me`: of the non-null value). */
+                readonly result: {
+                    readonly [key: string]: unknown;
+                };
+                /** The verb, run in-process with the request's headers: its result, cut to `result`. */
+                call(input: {
+                    readonly args: unknown;
+                    readonly headers: RequestHeaders;
+                    readonly request?: unknown;
+                }): Promise<unknown>;
+            };
+        };
+    };
+} & AccessRegistryMember<E> & AccessMcpMember<C, P>;
+/** Whether an `mcp` block is given: `true`, `false`, or `boolean` when the types cannot tell. */
+type McpGiven<X> = [X] extends [undefined] ? false : [X] extends [AccessMcpOptions] ? true : boolean;
+/** `access.mcp`: the framework's `mcp.authorization` when `mcp` is given, absent when it is not. */
+type AccessMcpMember<C extends AccessClaimsDeclaration, P extends boolean> = [
+    P
+] extends [true] ? {
+    /** The framework's `mcp.authorization`: `mcp: { path: "/mcp", authorization: access.mcp }`. */
+    readonly mcp: AccessMcpAuthorization<AccessClaimsOf<C>>;
+} : [P] extends [false] ? {
+    readonly mcp?: undefined;
+} : {
+    readonly mcp?: AccessMcpAuthorization<AccessClaimsOf<C>> | undefined;
+};
+/**
+ * Builds an Access instance: Better Auth (from the `betterAuth` block, with `jwt()`
+ * and the Access plugin installed), the policy engine (from `policies.rules`) and
+ * the request state the framework's `access` option reads. It mounts nothing and
+ * opens no connection; `better-auth` is loaded here, and must be the exact version
+ * Access is built against.
+ */
+export declare function createAccess<O extends BetterAuthOptions, const C extends AccessClaimsDeclaration, R = unknown, Gov extends GovernedShape = Record<never, never>, M = AccessIdentity<C>, const E extends boolean = false, X extends AccessMcpOptions | undefined = undefined>(options: AccessOptions<O, C, R, Gov, M, E, X>): Access<O, C, Gov, AccessPrincipalOf<R, M>, E, McpGiven<X>>;