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

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

@@ -0,0 +1,78 @@
+import type { AccessEngine } from "../access.engine.js";
+import type { AccessMcpAuthorization } from "../mcp/mcp-options.js";
+import { type AccessRegistry } from "../registry/access.registry.js";
+type GovernedShape = {
+    readonly [resource: string]: readonly string[];
+};
+/** 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 `accessOf` reads of a Better Auth instance: its options, its API and its context. */
+export type AccessAuth = {
+    readonly options: {
+        readonly plugins?: readonly unknown[] | undefined;
+    };
+    readonly api: unknown;
+    readonly $context: Promise<unknown>;
+};
+/** The `aventaraAccess()` plugin among an instance's plugins, by type. */
+type AccessPluginOf<A extends AccessAuth> = Extract<NonNullable<A["options"]["plugins"]>[number], {
+    readonly id: "aventara-access";
+}>;
+/** `accessOf(auth).registry`: the operator's API when the plugin serves the registry, absent when it does not. */
+type AccessProviderRegistry<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 `accessOf(auth)` returns: the framework's `access` option, and its types. */
+export type AccessProvider<Claims, Gov extends GovernedShape, M, E extends boolean = false, P extends boolean = false> = {
+    /** The policy engine, asked about every client and agent request. */
+    readonly policy: AccessEngine<Gov>;
+    /** A request's state: `me`, from its bearer token or its session cookie, else `null`. */
+    state(input: {
+        readonly headers: RequestHeaders;
+        readonly request?: unknown;
+    }): Promise<{
+        readonly me: M | null;
+    }>;
+    /** Types only, as Better Auth's `$Infer`: `typeof access.$Infer.Me` is the principal. */
+    readonly $Infer: {
+        readonly Me: M;
+        readonly Claims: Claims;
+    };
+} & AccessProviderRegistry<E> & AccessProviderMcp<Claims, P>;
+/** `accessOf(auth).mcp`: the framework's `mcp.authorization` when the plugin has `mcp`, absent when it has not. */
+type AccessProviderMcp<Claims, P extends boolean> = [P] extends [true] ? {
+    /** The framework's `mcp.authorization`: `mcp: { path: "/mcp", authorization: access.mcp }`. */
+    readonly mcp: AccessMcpAuthorization<Claims>;
+} : [P] extends [false] ? {
+    readonly mcp?: undefined;
+} : {
+    readonly mcp?: AccessMcpAuthorization<Claims> | undefined;
+};
+/** `accessOf`'s answer for an instance, typed from its `aventaraAccess()` plugin's `$Infer`. */
+export type AccessProviderOf<A extends AccessAuth> = AccessPluginOf<A> extends {
+    readonly $Infer: infer I extends {
+        readonly AccessMe: unknown;
+        readonly AccessClaims: unknown;
+        readonly AccessGoverned: GovernedShape;
+        readonly AccessRegistryEnabled: boolean;
+        readonly AccessMcp: boolean;
+    };
+} ? AccessProvider<I["AccessClaims"], I["AccessGoverned"], I["AccessMe"], I["AccessRegistryEnabled"], I["AccessMcp"]> : AccessProvider<{
+    readonly [claim: string]: string | number | boolean;
+}, GovernedShape, unknown, boolean, boolean>;
+/**
+ * The framework's `access` option from Better Auth built with `aventaraAccess()` in
+ * its plugins: `createFramework({ ...config, access: accessOf(auth) })`. Refuses an
+ * instance without the plugin, and the configurations the plugin refuses.
+ */
+export declare function accessOf<A extends AccessAuth>(given: A): AccessProviderOf<A>;
+export {};

package/dist/better-auth/access.provider.js

@@ -0,0 +1,100 @@
+// `accessOf(auth)`: the framework's `access` option from a Better Auth instance built
+// with `aventaraAccess()`. It satisfies the framework's access provider by shape
+// (`policy`, `state`) without importing it, as `createAccess`'s instance does, and
+// is built from the same modules: the engine with Access's built-in rules over
+// Better Auth's tables, and the request state (a bearer token against the key set,
+// or the session cookie from a trusted site). It checks `auth.options` as the
+// plugin's `init` does, so a configuration Access refuses fails the framework's
+// construction, not the first request. When the plugin serves the registry (the app
+// is the hub), `registry` is the operator's API, as `createAccess`'s instance has it:
+// it stores through the instance's own adapter, in this process, behind no route.
+// With the plugin's `mcp`, it gives the framework's `mcp.authorization` too
+// (`accessOf(auth).mcp`), and its state reads an agent's access token as
+// `createAccess`'s does; with the plugin's `audience`, it takes only bearer tokens
+// addressed to the service.
+import { AccessError } from "../access/access.error.js";
+import { guardedPolicy } from "../access/policies-block.checker.js";
+import { requestIdentity, requestState } from "../access/request.state.js";
+import { createTokenVerifier } from "../access/token.verifier.js";
+import { createAccessTokenVerifier, mcpAuthorizationOf, } from "../oauth/access-token.verifier.js";
+import { createRegistry, } from "../registry/access.registry.js";
+import { pluginKernelOf } from "./access.plugin.js";
+/**
+ * The framework's `access` option from Better Auth built with `aventaraAccess()` in
+ * its plugins: `createFramework({ ...config, access: accessOf(auth) })`. Refuses an
+ * instance without the plugin, and the configurations the plugin refuses.
+ */
+export function accessOf(given) {
+    const auth = given;
+    const plugins = Array.isArray(auth?.options?.plugins)
+        ? auth.options.plugins
+        : [];
+    let own;
+    for (const plugin of plugins) {
+        if (own === undefined && pluginKernelOf(plugin) !== undefined) {
+            own = plugin;
+        }
+    }
+    const kernel = pluginKernelOf(own);
+    if (kernel === undefined) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "accessOf takes a Better Auth instance built with aventaraAccess() in its plugins: `betterAuth({ plugins: [aventaraAccess({ policies })] })`.");
+    }
+    const { checked, resources } = kernel;
+    const start = kernel.start(auth.options, own);
+    let guarded;
+    const keys = async () => (await auth.api.getJwks());
+    const tokensFor = (resource) => createAccessTokenVerifier({
+        keys,
+        issuer: start.issuer,
+        resource,
+        userInfo: start.userInfo,
+        context: () => auth.$context,
+        claimsFor: (session) => kernel.claimsFor(() => auth.$context, session),
+    });
+    const agents = start.mcp === undefined ? undefined : tokensFor(start.mcp.resource);
+    const ownTokens = start.audience === undefined ? undefined : tokensFor(start.audience);
+    const provider = {
+        $Infer: {},
+        ...(agents === undefined || start.mcp === undefined
+            ? {}
+            : { mcp: mcpAuthorizationOf(agents, start.mcp.server) }),
+        state: requestState(requestIdentity({
+            auth: () => auth,
+            verifier: createTokenVerifier({
+                claims: checked.claims,
+                keys,
+                issuer: start.issuer,
+                tokenTtl: checked.tokenTtl,
+            }),
+            ...(agents === undefined ? {} : { agents }),
+            ...(ownTokens === undefined ? {} : { audience: ownTokens }),
+            kind: "web",
+            crossSite: start.crossSite,
+            claimsFor: (session) => kernel.claimsFor(() => auth.$context, session),
+        }), checked.principal),
+        ...(kernel.registry === undefined
+            ? {}
+            : {
+                registry: Object.freeze({
+                    ...createRegistry(async () => (await auth.$context).adapter, kernel.registry).operator,
+                }),
+            }),
+    };
+    // Built on first read, which is the framework's construction: a `resources` key
+    // whose tables are missing refuses the app's start. Not enumerable, so a walk
+    // over the provider runs no startup check.
+    Object.defineProperty(provider, "policy", {
+        get: () => {
+            guarded ??= guardedPolicy({
+                checked,
+                auditLog: kernel.auditLog,
+                resources,
+                tables: start.facts.tables,
+                naming: start.facts.naming,
+            });
+            return guarded;
+        },
+        enumerable: false,
+    });
+    return provider;
+}

package/dist/better-auth/index.d.ts

@@ -0,0 +1,7 @@
+export type { AccessIdentity } from "../access/claims.mapper.js";
+export { type AccessAgent, agentOf } from "../mcp/agent.grant.js";
+export type { AccessAgentIdentity, AccessMcpAuthorization, AccessMcpOptions, } from "../mcp/mcp-options.js";
+export { type AccessCanError, type AccessCanResult, type AccessQuestion, type AventaraAccessClientOptions, type AventaraAccessClientPlugin, aventaraAccessClient, } from "./access.client-plugin.js";
+export { type AventaraAccessOptions, type AventaraAccessPlugin, aventaraAccess, } from "./access.plugin.js";
+export { type AccessAuth, type AccessProvider, type AccessProviderOf, accessOf, } from "./access.provider.js";
+export type { AccessOrganizationBridge } from "./organization.bridge.js";

package/dist/better-auth/index.js

@@ -0,0 +1,4 @@
+export { agentOf } from "../mcp/agent.grant.js";
+export { aventaraAccessClient, } from "./access.client-plugin.js";
+export { aventaraAccess, } from "./access.plugin.js";
+export { accessOf, } from "./access.provider.js";

package/dist/better-auth/organization.bridge.d.ts

@@ -0,0 +1,66 @@
+import type { AccessClaimsDeclaration, AccessClaimsSource } from "../access/claims.mapper.js";
+/** The claims of a declaration that are strings, by name: those the bridge can fill. */
+type StringClaimOf<C extends AccessClaimsDeclaration> = {
+    [K in keyof C]: C[K] extends "string" ? K : never;
+}[keyof C] & string;
+/**
+ * The `organization` option: which claims a member's role fills, and with what. A
+ * member whose roles `roles` does not name (or no member, or no active organization)
+ * gets neither claim.
+ */
+export type AccessOrganizationBridge<C extends AccessClaimsDeclaration = AccessClaimsDeclaration> = {
+    /** The claim the role's mapped value fills: one `policies.claims` declares as `"string"`. */
+    readonly claim: StringClaimOf<C>;
+    /**
+     * The claim the organization's id fills, beside the role: one `policies.claims`
+     * declares as `"string"`. Each grant on the bridged role is held to it.
+     */
+    readonly organizationClaim: StringClaimOf<C>;
+    /**
+     * Better Auth organization roles (`owner`, `admin`, `member`, or the app's own
+     * static roles), in order, each with the value the claim takes: a member with
+     * several roles gets the value of the first one listed here.
+     */
+    readonly roles: readonly (readonly [role: string, value: string])[];
+};
+/** The bridge, checked: its two claims and its roles in order. */
+export type CheckedBridge = {
+    readonly claim: string;
+    readonly organizationClaim: string;
+    readonly roles: readonly (readonly [role: string, value: string])[];
+};
+/** The `organization` option, checked against the declared claims; `undefined` when it is not given. */
+export declare const checkBridge: (value: unknown, claims: AccessClaimsDeclaration) => CheckedBridge | undefined;
+/**
+ * Refuses a bridge over Better Auth without its organization plugin, and over one
+ * that lets a member be made otherwise than the app decided: by an unverified email
+ * accepting an invitation, by any user creating an organization, or (with dynamic
+ * access control) under a role an organization's admins name.
+ */
+export declare const checkBridgePlugins: (plugins: readonly unknown[], bridge: CheckedBridge) => void;
+/** What the bridge reads of Better Auth's context: its database adapter. */
+export type BridgeContext = {
+    readonly adapter: {
+        findOne(input: {
+            readonly model: string;
+            readonly where: readonly {
+                readonly field: string;
+                readonly value: string;
+            }[];
+        }): Promise<{
+            readonly [field: string]: unknown;
+        } | null>;
+    };
+};
+/**
+ * The bridged claims for a session: the mapped value of the member's role in the
+ * session's active organization, and that organization's id, read from Better Auth's
+ * store; `undefined` when there is no active organization, no membership, or no role
+ * the bridge maps. The member's roles are read as Better Auth reads them, split on
+ * `,` and taken as they are: a stored role with whitespace in it (`member, owner`) is
+ * one Better Auth does not grant, and gives nothing here.
+ */
+export declare const bridgedClaims: (bridge: CheckedBridge, context: BridgeContext, source: AccessClaimsSource) => Promise<{
+    readonly [claim: string]: string;
+} | undefined>;
+export {};

package/dist/better-auth/organization.bridge.js

@@ -0,0 +1,144 @@
+// The organization bridge (`aventaraAccess({ organization })`): a member's role in
+// Better Auth's organization plugin becomes two claims of the token, the role's
+// mapped value and the organization it holds in, so the rules read it as an
+// organization's role, never a global one. Both are read when the token is issued,
+// from the membership Better Auth's store holds for the session's active
+// organization: removing the member, or changing their role, changes the next token.
+//
+// An organization role is a fact about one organization. The rules' grammar has no
+// role held "in the active organization", so the bridge hands the rules the
+// organization beside the role, and each grant on the role must be held to it
+// (`where: { organizationId: me.org }`, with `principal` copying the claim onto
+// `me`). A rule on the role alone grants across every organization: the README says
+// so, and the bridge's own refusals keep the role from being self-made.
+//
+// The bridge trusts the organization plugin's memberships, so it refuses an
+// organization plugin
+// - whose invitations a user with an unverified email may accept (GHSA-fmh4-wcc4-5jm3);
+// - that lets any user create an organization, and so make themselves its owner,
+//   unless the app chose that (`allowUserToCreateOrganization` `false`, or a function);
+// - with dynamic access control, mapping a role that is not one of its static roles
+//   (an organization's admins name dynamic roles).
+import { AccessError } from "../access/access.error.js";
+import { organizationPluginOf, refuseUnverifiedInvitations, } from "../access/better-auth.hardening.js";
+import { isRecord } from "../policies.compiler.js";
+const refuse = (message) => {
+    throw new AccessError("ACCESS_OPTIONS_INVALID", message);
+};
+const SHAPE = '`organization` is `{ claim, organizationClaim, roles }`: the claim a member\'s role fills and the claim its organization fills (both declared as "string" in `policies.claims`), and each Better Auth role, in order, with its value: `[["owner", "admin"], ["admin", "admin"]]`';
+/** A role name Better Auth stores as one: not empty, no comma, no whitespace. */
+const ROLE_NAME = /^[^\s,]+$/;
+/** One of the two claims, checked: declared as a string. */
+const stringClaim = (member, claim, claims) => {
+    if (typeof claim !== "string" || claims[claim] !== "string") {
+        return refuse(`${SHAPE}; \`organization.${member}\` names ${typeof claim === "string" ? (claims[claim] === undefined ? `the claim "${claim}", which \`policies.claims\` does not declare` : `\`${claim}\`, which \`policies.claims\` declares as ${claims[claim]}`) : JSON.stringify(claim)}.`);
+    }
+    return claim;
+};
+/** The `organization` option, checked against the declared claims; `undefined` when it is not given. */
+export const checkBridge = (value, claims) => {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (!isRecord(value)) {
+        return refuse(`${SHAPE}.`);
+    }
+    for (const key of Object.keys(value)) {
+        if (key !== "claim" && key !== "organizationClaim" && key !== "roles") {
+            refuse(`${SHAPE}; it does not take \`${key}\`.`);
+        }
+    }
+    const claim = stringClaim("claim", value.claim, claims);
+    const organizationClaim = stringClaim("organizationClaim", value.organizationClaim, claims);
+    if (claim === organizationClaim) {
+        refuse(`${SHAPE}; \`claim\` and \`organizationClaim\` are both "${claim}": they are two claims.`);
+    }
+    const { roles } = value;
+    if (!Array.isArray(roles) || roles.length === 0) {
+        return refuse(`${SHAPE}; \`organization.roles\` is ${Array.isArray(roles) ? "empty" : JSON.stringify(roles)}.`);
+    }
+    const entries = [];
+    const seen = [];
+    for (const entry of roles) {
+        const [role, mapped] = Array.isArray(entry) ? entry : [];
+        if (!Array.isArray(entry) ||
+            entry.length !== 2 ||
+            typeof role !== "string" ||
+            !ROLE_NAME.test(role) ||
+            seen.includes(role) ||
+            typeof mapped !== "string" ||
+            mapped === "") {
+            return refuse(`${SHAPE}; \`organization.roles\` holds ${JSON.stringify(entry)}: each entry is a Better Auth role (one name, no comma or whitespace, listed once) and a value.`);
+        }
+        seen.push(role);
+        entries.push([role, mapped]);
+    }
+    return { claim, organizationClaim, roles: entries };
+};
+/** Better Auth's organization roles when the app names none of its own. */
+const DEFAULT_ROLES = ["owner", "admin", "member"];
+/**
+ * Refuses a bridge over Better Auth without its organization plugin, and over one
+ * that lets a member be made otherwise than the app decided: by an unverified email
+ * accepting an invitation, by any user creating an organization, or (with dynamic
+ * access control) under a role an organization's admins name.
+ */
+export const checkBridgePlugins = (plugins, bridge) => {
+    const organization = organizationPluginOf(plugins);
+    if (organization === undefined) {
+        throw new AccessError("ACCESS_RESOURCE_MISSING", "`aventaraAccess({ organization })` reads Better Auth's organization memberships, and Better Auth has no organization plugin: add organization() to plugins.");
+    }
+    refuseUnverifiedInvitations(plugins, "`aventaraAccess({ organization })`");
+    const { allowUserToCreateOrganization, dynamicAccessControl, roles } = organization.options;
+    if (allowUserToCreateOrganization !== false &&
+        typeof allowUserToCreateOrganization !== "function") {
+        refuse("`aventaraAccess({ organization })` maps an organization's roles into claims, and the organization plugin lets any user create an organization, and so be its owner. Decide who may: pass `organization({ allowUserToCreateOrganization: false })`, or a function of the user.");
+    }
+    if (isRecord(dynamicAccessControl) && dynamicAccessControl.enabled === true) {
+        const statics = isRecord(roles) ? Object.keys(roles) : DEFAULT_ROLES;
+        for (const [role] of bridge.roles) {
+            if (!statics.includes(role)) {
+                refuse(`\`aventaraAccess({ organization })\` maps the role "${role}", and with dynamic access control an organization's admins name roles themselves: map only the organization plugin's static roles (${statics.join(", ")}).`);
+            }
+        }
+    }
+};
+/**
+ * The bridged claims for a session: the mapped value of the member's role in the
+ * session's active organization, and that organization's id, read from Better Auth's
+ * store; `undefined` when there is no active organization, no membership, or no role
+ * the bridge maps. The member's roles are read as Better Auth reads them, split on
+ * `,` and taken as they are: a stored role with whitespace in it (`member, owner`) is
+ * one Better Auth does not grant, and gives nothing here.
+ */
+export const bridgedClaims = async (bridge, context, source) => {
+    const organizationId = source.session.activeOrganizationId;
+    if (typeof organizationId !== "string" || organizationId === "") {
+        return undefined;
+    }
+    const member = await context.adapter.findOne({
+        model: "member",
+        where: [
+            { field: "userId", value: source.user.id },
+            { field: "organizationId", value: organizationId },
+        ],
+    });
+    if (typeof member?.role !== "string") {
+        return undefined;
+    }
+    const held = member.role.split(",");
+    for (const role of held) {
+        if (!ROLE_NAME.test(role)) {
+            return undefined;
+        }
+    }
+    for (const [role, value] of bridge.roles) {
+        if (held.includes(role)) {
+            return {
+                [bridge.claim]: value,
+                [bridge.organizationClaim]: organizationId,
+            };
+        }
+    }
+    return undefined;
+};

package/dist/canonical-json.writer.d.ts

@@ -0,0 +1,12 @@
+/** A JSON value, as the canonical writer reads it. */
+export type CanonicalJson = string | number | boolean | null | readonly CanonicalJson[] | {
+    readonly [key: string]: CanonicalJson | undefined;
+};
+/** JSON text with every object's members sorted by key and no whitespace. */
+export declare const canonicalJson: (value: CanonicalJson) => string;
+/** A copy of a list of names, sorted: the order of a list the format calls a set. */
+export declare const sortedNames: <T extends string>(list: readonly T[]) => T[];
+/** Orders rules by their `id`. */
+export declare const byId: <T extends {
+    readonly id: string;
+}>(a: T, b: T) => number;

package/dist/canonical-json.writer.js

@@ -0,0 +1,30 @@
+// The canonical JSON text both Access file formats hash (`policies.hash.ts`,
+// `guardrails/guardrails.hash.ts`): every object's members sorted by key (UTF-16
+// code units), whitespace removed, members whose value is `undefined` left out, and
+// strings and numbers written as `JSON.stringify` writes them (RFC 8785's rules for
+// the values these files hold). A number JSON cannot carry (NaN, Infinity) throws. Which lists a format treats as sets is the format's
+// own decision; this writer keeps every list in the order it is given.
+/** JSON text with every object's members sorted by key and no whitespace. */
+export const canonicalJson = (value) => {
+    if (typeof value === "number" && !Number.isFinite(value)) {
+        // `JSON.stringify` writes NaN and Infinity as `null`: two files that decide
+        // differently would share one hash.
+        throw new Error(`Aventara Access: a file holds the number ${value}, and JSON carries finite numbers only`);
+    }
+    if (value === null || typeof value !== "object") {
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalJson).join(",")}]`;
+    }
+    const record = value;
+    const members = Object.keys(record)
+        .filter((key) => record[key] !== undefined)
+        .sort()
+        .map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`);
+    return `{${members.join(",")}}`;
+};
+/** A copy of a list of names, sorted: the order of a list the format calls a set. */
+export const sortedNames = (list) => [...list].sort();
+/** Orders rules by their `id`. */
+export const byId = (a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0;

package/dist/cli/avaccess.bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/avaccess.bin.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+// The `avaccess` bin. It runs the program in the working directory, waits for its
+// lines to reach the terminal or the pipe, and exits with its code: a command that
+// loaded the Access server's module (`keys`) may leave a database pool open, and
+// the bin does not wait for it. A command that runs until stopped (`serve`) stops on
+// SIGTERM or SIGINT; the bin listens for them only once such a command asks.
+import process from "node:process";
+import { runAvaccess } from "./avaccess.program.js";
+const flushed = () => new Promise((resolve) => {
+    process.stdout.write("", () => {
+        process.stderr.write("", () => resolve());
+    });
+});
+const code = await runAvaccess(process.argv.slice(2), process.cwd(), process.env, {
+    out: (line) => {
+        process.stdout.write(`${line}\n`);
+    },
+    err: (line) => {
+        process.stderr.write(`${line}\n`);
+    },
+}, () => new Promise((resolve) => {
+    process.once("SIGTERM", () => resolve("SIGTERM"));
+    process.once("SIGINT", () => resolve("SIGINT"));
+}));
+await flushed();
+process.exit(code);

package/dist/cli/avaccess.program.d.ts

@@ -0,0 +1,15 @@
+import { type ExitCode } from "./cli.context.js";
+/** What the program prints and where. */
+type ProgramOutput = {
+    out(line: string): void;
+    err(line: string): void;
+};
+/**
+ * Runs `avaccess` with `args` (the command line after the bin's name) in `cwd`, and
+ * answers its exit code. `untilStopped` resolves when a command that runs until
+ * stopped (`serve`) should stop; the bin resolves it on SIGTERM or SIGINT.
+ */
+export declare const runAvaccess: (args: readonly string[], cwd: string, env: {
+    readonly [name: string]: string | undefined;
+}, printed: ProgramOutput, untilStopped?: () => Promise<string>) => Promise<ExitCode>;
+export {};