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

package/dist/beacon/beacon.store.js

@@ -0,0 +1,78 @@
+// A service's own beacon: one row in `_aventara_beacon` with a random value, written
+// once by the service through its own data layer and never changed. The row is
+// keyed by the namespace, so a table holds one row per namespace: in a deployment
+// with a database schema per service each schema's table holds its own service's
+// row, and in one with a single schema (or a database with none) one table holds
+// every namespace's. `avaccess push --beacon <module>` writes the row the first time
+// and sends its value with the file; the registry keeps only its hash, bound to the
+// namespace.
+//
+// In a shared schema every service with write access to the table is a co-tenant
+// of every row: one that overwrites or deletes another namespace's row cannot make
+// a reader pass (the registry holds the owner's hash, bound to the owner), but it
+// makes the readers refuse at startup until the owner's service writes and pushes
+// its beacon again. The check fails closed; give each service's database role write
+// access to its own row only where the database can.
+//
+// Access writes no SQL and names no ORM: the app hands in an `AccessBeaconStore`
+// over its own data layer (the generated client's `prismaBeacon` builds one over a
+// Prisma client).
+import { AccessError } from "../access/access.error.js";
+import { randomSecret } from "../random-secret.generator.js";
+import { BEACON, beaconHashOf } from "./beacon.check.js";
+/** The beacon table's name. */
+export const BEACON_TABLE = "_aventara_beacon";
+/** A new beacon: 256 random bits from the runtime's CSPRNG, written `avb_…`. */
+export const newBeacon = () => randomSecret("avb_");
+/** Whether `value` is a beacon. */
+export const isBeacon = (value) => typeof value === "string" && BEACON.test(value);
+/**
+ * The namespace's own beacon, for its push: a new row written now when the
+ * namespace has none, or the row it has when its hash is the one the registry holds
+ * for the namespace (`registered`, `null` when it holds none). A row this service
+ * did not write and the registry does not know is never adopted: another service
+ * with write access to the table (a co-tenant of a shared schema) could have planted
+ * it, so it is refused (`ACCESS_BEACON_MISMATCH`) until an operator verifies it or
+ * deletes it, and the next push writes a new one. A row whose value is no beacon is
+ * refused too, never overwritten.
+ */
+export const ensureBeacon = async (store, namespace, registered) => {
+    const found = await store.read(namespace);
+    if (found !== null) {
+        return { value: await known(found, namespace, registered), created: false };
+    }
+    const value = newBeacon();
+    try {
+        await store.create(namespace, value);
+    }
+    catch (error) {
+        // Another write took the namespace's row first: it is held to the registry as
+        // any row found is. Anything else is the store's own failure, reported as it was.
+        const written = await store.read(namespace);
+        if (written === null) {
+            throw error;
+        }
+        return {
+            value: await known(written, namespace, registered),
+            created: false,
+        };
+    }
+    const written = await store.read(namespace);
+    if (written !== value) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `the beacon store wrote namespace "${namespace}"'s row in ${BEACON_TABLE}, and reading it back found ${written === null ? "none" : "another value"}: check that the store's read and create use the same table`);
+    }
+    return { value, created: true };
+};
+/** A row found for the namespace, taken only when the registry holds its hash. */
+const known = async (value, namespace, registered) => {
+    if (!isBeacon(value)) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `namespace "${namespace}"'s row in ${BEACON_TABLE} holds no beacon (avb_ and 43 base64url characters): it was changed outside Access. Delete the row; the next push writes a new one`);
+    }
+    if (registered === null) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `namespace "${namespace}"'s row in ${BEACON_TABLE} is there, and the registry holds no beacon of "${namespace}": this push did not write the row, and another service with write access to the table may have. An operator verifies that "${namespace}"'s own service wrote it, or deletes it; the next push then writes a new one`);
+    }
+    if ((await beaconHashOf(namespace, value)) !== registered) {
+        throw new AccessError("ACCESS_BEACON_MISMATCH", `namespace "${namespace}"'s row in ${BEACON_TABLE} is not the beacon the registry holds for "${namespace}": it was changed outside "${namespace}"'s service, or this database's row is an old one. An operator verifies it or deletes it; the next push then writes a new one`);
+    }
+    return value;
+};

package/dist/better-auth/access.client-plugin.d.ts

@@ -0,0 +1,75 @@
+import type { AventaraAccessPlugin } from "./access.plugin.js";
+/** One question to the policy: may the signed-in user run `action` on `resource`, or on the one row `where` names. */
+export type AccessQuestion<R extends string = string> = {
+    readonly resource: R;
+    readonly action: "read" | "create" | "update" | "delete";
+    /** One row, by its unique where (`{ id: "c1" }`). Omitted: may the user run `action` on `resource` at all. */
+    readonly where?: {
+        readonly [field: string]: unknown;
+    };
+};
+/** `aventaraAccessClient()`'s options. */
+export type AventaraAccessClientOptions = {
+    /**
+     * The framework's API path or URL (its `api` option), where `_access/can` is
+     * served: `"/api"`, or `"https://api.example.com/api"`. A path is read against the
+     * auth client's `baseURL`, else the page's address.
+     */
+    readonly api: string;
+    /**
+     * The ClientContract's hash the questions are asked under (the generated client's).
+     * Without it, the client reads it from `GET {api}/_contract` once, and again when
+     * the framework answers that it changed.
+     */
+    readonly contractHash?: string;
+};
+/** Why `can` has no answers: the framework's (or the network's) refusal, as Better Auth's client reports one. */
+export type AccessCanError = {
+    readonly status: number;
+    readonly statusText: string;
+    /** The framework's code (`A2005`: the client is stale), when it answered with one. */
+    readonly code?: string;
+    readonly message?: string;
+};
+/** `authClient.access.can`'s answer: one boolean per question, in order, or the error. */
+export type AccessCanResult = {
+    readonly data: readonly boolean[];
+    readonly error: null;
+} | {
+    readonly data: null;
+    readonly error: AccessCanError;
+};
+/** Better Auth's client fetch, as the plugin calls it. */
+type ClientFetch = (url: string, options?: {
+    readonly method?: string;
+    readonly body?: unknown;
+    readonly headers?: {
+        readonly [name: string]: string;
+    };
+}) => Promise<{
+    readonly data: unknown;
+    readonly error: unknown;
+}>;
+/** What `aventaraAccessClient()` returns: a Better Auth client plugin. */
+export type AventaraAccessClientPlugin = {
+    readonly id: "aventara-access";
+    /** Types only: the server plugin, whose `jwt()` routes the client infers (`authClient.token()`). */
+    readonly $InferServerPlugin: AventaraAccessPlugin;
+    readonly pathMethods: {
+        readonly "/jwks": "GET";
+    };
+    readonly getActions: ($fetch: ClientFetch, $store: unknown, options: {
+        readonly baseURL?: string | undefined;
+    } | undefined) => {
+        readonly access: {
+            /** Asks the framework, in one request, whether the signed-in user may run each question. */
+            can(questions: readonly AccessQuestion[]): Promise<AccessCanResult>;
+        };
+    };
+};
+/**
+ * The client plugin: `createAuthClient({ plugins: [aventaraAccessClient({ api: "/api" })] })`
+ * gives `authClient.access.can([{ resource, action, where? }, ...])`.
+ */
+export declare const aventaraAccessClient: (options: AventaraAccessClientOptions) => AventaraAccessClientPlugin;
+export {};

package/dist/better-auth/access.client-plugin.js

@@ -0,0 +1,133 @@
+// `aventaraAccessClient()`: the client plugin of `aventaraAccess()`, for Better
+// Auth's `createAuthClient({ plugins: [...] })`. It adds `authClient.access.can`,
+// which asks the framework, not Better Auth: one `POST {api}/_access/can` for the
+// whole list of questions, answered by the same engine that decides the real calls
+// (`accessOf(auth).policy`, with the row looked up within the caller's scope), one
+// boolean per question. So the two paths have one evaluator. The answer only shapes
+// the UI: the real call is still checked.
+//
+// It sends Better Auth's own fetch, so the session cookie (or the bearer token the
+// app gives Better Auth's client) goes with it, and answers as Better Auth's client
+// actions do, `{ data, error }`. It names no Node.js API and loads nothing from
+// `better-auth` at runtime: it runs in the browser.
+/** The framework protocol version the questions are asked under. */
+const PROTOCOL_VERSION = "1";
+/** A protocol envelope's code, when a body is one. */
+const codeOf = (body) => {
+    const code = body?.code;
+    return typeof code === "string" ? code : undefined;
+};
+const failure = (status, statusText, body) => {
+    const code = codeOf(body);
+    const message = body?.message;
+    return {
+        data: null,
+        error: {
+            status,
+            statusText,
+            ...(code === undefined ? {} : { code }),
+            ...(typeof message === "string" ? { message } : {}),
+        },
+    };
+};
+/** Whether every answer is a boolean. */
+const allBooleans = (answers) => {
+    for (const answer of answers) {
+        if (typeof answer !== "boolean") {
+            return false;
+        }
+    }
+    return true;
+};
+/** A Better Auth fetch error as `can` reports it. */
+const fetchFailure = (error) => {
+    const { status, statusText } = (error ?? {});
+    return failure(typeof status === "number" ? status : 0, typeof statusText === "string" ? statusText : "", error);
+};
+/**
+ * The client plugin: `createAuthClient({ plugins: [aventaraAccessClient({ api: "/api" })] })`
+ * gives `authClient.access.can([{ resource, action, where? }, ...])`.
+ */
+export const aventaraAccessClient = (options) => {
+    const { api, contractHash: given } = options ?? {};
+    if (typeof api !== "string" || api === "") {
+        throw new TypeError('Aventara Access: aventaraAccessClient takes `{ api }`, the framework\'s API path or URL ("/api").');
+    }
+    return {
+        id: "aventara-access",
+        $InferServerPlugin: {},
+        pathMethods: { "/jwks": "GET" },
+        getActions: ($fetch, _$store, clientOptions) => {
+            const base = clientOptions?.baseURL ??
+                globalThis
+                    .location?.href;
+            /** `{api}/<route>`, absolute, so Better Auth's fetch does not read it against its own base path. */
+            const route = (path) => new URL(`${api.replace(/\/+$/, "")}/${path}`, base).href;
+            let discovered;
+            /** The ClientContract's hash: the one given, else `GET {api}/_contract`'s. */
+            const hashOf = async () => {
+                if (given !== undefined) {
+                    return given;
+                }
+                if (discovered !== undefined) {
+                    return discovered;
+                }
+                const { data, error } = await $fetch(route("_contract"), {
+                    method: "GET",
+                });
+                const hash = data?.protocol?.hash;
+                if (error !== null && error !== undefined) {
+                    return fetchFailure(error);
+                }
+                if (typeof hash !== "string") {
+                    return failure(500, "The framework's /_contract answer carries no protocol hash");
+                }
+                discovered = hash;
+                return hash;
+            };
+            const ask = async (questions, hash) => $fetch(route("_access/can"), {
+                method: "POST",
+                body: { questions },
+                headers: {
+                    "aventara-protocol-version": PROTOCOL_VERSION,
+                    "aventara-contract-hash": hash,
+                },
+            });
+            const can = async (questions) => {
+                if (questions.length === 0) {
+                    return { data: [], error: null };
+                }
+                let hash = await hashOf();
+                if (typeof hash !== "string") {
+                    return hash;
+                }
+                let answer = await ask(questions, hash);
+                // A hash read from `_contract` is stale once the framework redeploys: read it
+                // again, once.
+                if (given === undefined &&
+                    codeOf(answer.error) === "A2005" &&
+                    answer.error.status === 409) {
+                    discovered = undefined;
+                    hash = await hashOf();
+                    if (typeof hash !== "string") {
+                        return hash;
+                    }
+                    answer = await ask(questions, hash);
+                }
+                if (answer.error !== null && answer.error !== undefined) {
+                    return fetchFailure(answer.error);
+                }
+                const answers = answer.data
+                    ?.data;
+                if (codeOf(answer.data) !== "A1000" ||
+                    !Array.isArray(answers) ||
+                    answers.length !== questions.length ||
+                    !allBooleans(answers)) {
+                    return failure(500, "The framework's /_access/can answer is not one boolean per question", answer.data);
+                }
+                return { data: answers, error: null };
+            };
+            return { access: { can } };
+        },
+    };
+};

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

@@ -0,0 +1,164 @@
+import type { jwt } from "better-auth/plugins/jwt";
+import type { AccessPoliciesOptions } from "../access/access-options.js";
+import { type BetterAuthBlock } from "../access/better-auth.hardening.js";
+import { type BetterAuthModules } from "../access/better-auth.loader.js";
+import { type AccessClaimsDeclaration, type AccessClaimsOf, type AccessClaimsSource, type AccessIdentity } from "../access/claims.mapper.js";
+import { type BetterAuthTablesFacts, type CheckedPolicies } from "../access/policies-block.checker.js";
+import { type AuditLog } from "../audit/audit.log.js";
+import type { AccessAuditOptions } from "../audit/audit-event.js";
+import { type AccessMcpOptions } from "../mcp/mcp-options.js";
+import { type AccessPasswordsOptions } from "../passwords/passwords.options.js";
+import { type RegistrySettings } from "../registry/access.registry.js";
+import { type AccessRegistryOptions } from "../registry/registry.options.js";
+import { type AccessResourcesOptions, type ResourcesChoice } from "../resources/auth-tables.guard.js";
+import { type AccessOrganizationBridge, type CheckedBridge } from "./organization.bridge.js";
+type GovernedShape = {
+    readonly [resource: string]: readonly string[];
+};
+/**
+ * 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>;
+};
+/** `aventaraAccess()`'s options. */
+export type AventaraAccessOptions<C extends AccessClaimsDeclaration, R, Gov extends GovernedShape, M, E extends boolean = false> = {
+    /** The rules and the claims they read, as `createAccess` takes them. */
+    readonly policies: AccessPoliciesOptions<C, R, Gov>;
+    /**
+     * Which Resource of the rules' schema is each of Better Auth's tables, and which
+     * of them are Resources of the rules, as `createAccess` takes it. Every other
+     * table of Better Auth's is closed, and no grant opens a secret column.
+     */
+    readonly resources?: AccessResourcesOptions;
+    /**
+     * The organization bridge: a member's role in the session's active organization
+     * (Better Auth's `organization()` plugin) fills one claim of the token, and the
+     * organization another. Each grant on the role must be held to the organization.
+     */
+    readonly organization?: AccessOrganizationBridge<C>;
+    /**
+     * The audit log, as `createAccess` takes it: `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;
+    /**
+     * How passwords are hashed, as `createAccess` takes it: argon2id at
+     * `"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.
+     * An app that sets Better Auth's `emailAndPassword.password` hashes its
+     * own way, and may not set this too.
+     */
+    readonly passwords?: AccessPasswordsOptions;
+    /**
+     * The policy registry, as `createAccess` takes it: `{ enabled: true }` makes the
+     * app the hub other services push their files to and pull them from, its tables
+     * this plugin's (Better Auth's `generate`/`migrate` create them) and its routes
+     * this plugin's endpoints under `/access/v1/namespaces`; `accessOf(auth).registry`
+     * is the operator's API. Off by default: no tables, no routes.
+     */
+    readonly registry?: AccessRegistryOptions<E>;
+    /**
+     * Access as the authorization layer of an MCP endpoint, as `createAccess`
+     * takes it: `{ resource }`, the endpoint's URL. Better Auth's OAuth provider
+     * (`@better-auth/oauth-provider`) goes in `plugins` after this plugin, with the
+     * endpoint among its `resources`; `accessOf(auth).mcp` is the framework's
+     * `mcp.authorization`.
+     */
+    readonly mcp?: AccessMcpOptions;
+    /**
+     * The service's own audience, an opt-in, as `createAccess` takes it (RFC 8707): with
+     * it, `accessOf(auth).state` takes a bearer token only when it is the OAuth
+     * provider's access token addressed to this audience alone, and refuses the
+     * one-org token `GET /token` issues. Off by default.
+     */
+    readonly audience?: string;
+} & AccessPrincipalOption<C, R, M>;
+/** The `jwt()` plugin `aventaraAccess()` carries inside it. */
+type JwtPlugin = ReturnType<typeof jwt>;
+/** What `aventaraAccess()` returns: a Better Auth plugin, with `jwt()`'s endpoints, hooks and table. */
+export type AventaraAccessPlugin<C extends AccessClaimsDeclaration = AccessClaimsDeclaration, Gov extends GovernedShape = GovernedShape, M = unknown, E extends boolean = boolean, P extends boolean = boolean> = {
+    readonly id: "aventara-access";
+    readonly version: string;
+    readonly init: (context: unknown) => void;
+    readonly endpoints: JwtPlugin["endpoints"];
+    readonly hooks: JwtPlugin["hooks"];
+    readonly schema: JwtPlugin["schema"];
+    /** Types only, as Better Auth's plugins carry theirs: `typeof auth.$Infer.AccessMe` is the principal. */
+    readonly $Infer: {
+        readonly AccessMe: M;
+        readonly AccessClaims: AccessClaimsOf<C>;
+        readonly AccessGoverned: Gov;
+        /** Whether the plugin serves the registry (`registry: { enabled: true }`): `accessOf(auth).registry` is typed present exactly then. */
+        readonly AccessRegistryEnabled: E;
+        /** Whether `mcp` is given: `accessOf(auth).mcp` is there exactly then. */
+        readonly AccessMcp: P;
+    };
+};
+/** What Better Auth's options at `init` (or `auth.options`) fixed: the facts the request state and the engine read. */
+type PluginStart = {
+    readonly issuer: string;
+    readonly crossSite: boolean;
+    readonly facts: BetterAuthTablesFacts;
+    /** With `mcp`: the MCP endpoint, and the authorization server `accessOf(auth).mcp` names (the issuer). */
+    readonly mcp?: {
+        readonly resource: string;
+        readonly server: string;
+    };
+    /** With `audience`: the service's own audience. */
+    readonly audience?: string;
+    /** The provider's UserInfo URL, which a token asked with `openid` names beside its resource. */
+    readonly userInfo: string | undefined;
+};
+/** What `aventaraAccess()` was built with, for `accessOf`. */
+type PluginKernel = {
+    readonly checked: CheckedPolicies;
+    readonly resources: ResourcesChoice;
+    readonly bridge: CheckedBridge | undefined;
+    readonly modules: BetterAuthModules;
+    /** The audit log, when `audit` is on: the decisions of `accessOf(auth).policy` go to it. */
+    readonly auditLog: AuditLog | undefined;
+    /** The registry's settings when the plugin serves it, for `accessOf(auth).registry`; `undefined` when it is off. */
+    readonly registry: RegistrySettings | undefined;
+    /** Better Auth's options, checked as `init` checks them. */
+    start(options: BetterAuthBlock, own: unknown): PluginStart;
+    /** A session's claims, as its token is issued with them; `context` is Better Auth's. */
+    claimsFor(context: () => Promise<unknown>, source: AccessClaimsSource): Promise<{
+        readonly [claim: string]: string | number | boolean;
+    }>;
+};
+/**
+ * The Access plugin for Better Auth: `betterAuth({ plugins: [aventaraAccess({ policies })] })`.
+ * It carries Better Auth's `jwt()` (whose tokens carry `sub` and the declared claims,
+ * under the app's base URL as issuer and audience), so `jwt()` is not added beside
+ * it. `accessOf(auth)` is the framework's `access` option. `better-auth` is loaded
+ * here, and must be in Access's range, `~1.7.12` (1.7.12 or a later 1.7 patch).
+ */
+export declare function aventaraAccess<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: AventaraAccessOptions<C, R, Gov, M, E> & {
+    readonly mcp?: X;
+}): AventaraAccessPlugin<C, Gov, AccessPrincipalOf<R, M>, E, [
+    X
+] extends [undefined] ? false : [X] extends [AccessMcpOptions] ? true : boolean>;
+/** What `aventaraAccess()` was built with, when `plugin` is one; `undefined` for any other plugin. */
+export declare const pluginKernelOf: (plugin: unknown) => PluginKernel | undefined;
+export {};