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

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

@@ -0,0 +1,348 @@
+// `aventaraAccess()`: Access as a Better Auth plugin, for an app that builds Better
+// Auth itself (`betterAuth({ plugins: [aventaraAccess({ policies })] })`). It is the
+// other way in beside `createAccess`, and runs the same code: the `policies` block
+// and `principal` checked when it is called; Better Auth's options checked when
+// Better Auth initialises the plugin, as `createAccess` checks its `betterAuth` block
+// (the fixed issuer, the session cookie's site, the claims' sources, which Resource
+// is which of Better Auth's tables, no second `jwt()`); and tokens issued by Better
+// Auth's own `jwt()`, which the plugin carries inside it, with `sub` and the declared
+// claims only. `accessOf(auth)` then gives the framework its `access` option.
+//
+// Passwords are hashed with argon2id as under `createAccess` (the `passwords` block,
+// or the app's own `emailAndPassword.password`, which passes through): the plugin
+// puts the hook in Better Auth's context when Better Auth initialises it.
+//
+// The audit log is here as under `createAccess` (`audit: true` or `{ sink }`): sign-ins,
+// sign-outs, refused sign-ins and tokens from Better Auth's hooks, and the decisions
+// of `accessOf(auth).policy`.
+//
+// The registry is here too, as under `createAccess` (`registry: { enabled: true }`),
+// which makes the app the hub other services push to and pull from: its tables are
+// this plugin's schema, so Better Auth's `migrate`/`generate` create them through the
+// app's own adapter, and its routes are this plugin's endpoints, so Better Auth serves
+// them wherever the app mounts it. A service reaches them only with its namespace's
+// key; the operator's API (namespaces, keys, the org's guardrails) is
+// `accessOf(auth).registry`, in the app's own process, and no route opens it. What
+// else `createAccess` adds beside Better Auth (profiles, its `handler`, the standalone
+// host) is not here: the app owns its Better Auth instance and mounts it as it
+// already does.
+//
+// `jwt()` is carried inside this plugin, under the Access plugin's id. A Better Auth
+// plugin that looks `jwt()` up by its id (`ctx.getPlugin("jwt")`, as the OAuth
+// provider does for its issuer and keys) finds the carried one: the plugin answers
+// for that id in Better Auth's context (`getPlugin`, `hasPlugin`) when Better Auth
+// starts it, so a plugin that reads it as it starts comes after this one in
+// `plugins`.
+//
+// With `mcp` or `audience`, Access reads the tokens Better Auth's OAuth provider (in
+// `plugins` after this plugin) issues, as under `createAccess`: PKCE is required of
+// every authorization request, `accessOf(auth).mcp` is the framework's
+// `mcp.authorization`, and with `audience` the service takes only bearer tokens
+// addressed to it. Access issues no token and serves no OAuth route.
+import { AccessError } from "../access/access.error.js";
+import { ACCESS_PLUGIN_ID, cookieCacheOn, crossSiteSessionCookie, issuerOf, JWT_PLUGIN_ID, normalisedId, refuseInstalledPlugins, refuseUnverifiedInvitations, } from "../access/better-auth.hardening.js";
+import { loadBetterAuth, } from "../access/better-auth.loader.js";
+import { issuedClaims, } from "../access/claims.mapper.js";
+import { betterAuthTablesFor, checkPoliciesBlock, } from "../access/policies-block.checker.js";
+import { sessionStillLive } from "../access/request.state.js";
+import { sessionWatch } from "../access/session.hooks.js";
+import { auditDestinationOf, createAuditLog, } from "../audit/audit.log.js";
+import { auditSchema } from "../audit/audit.schema.js";
+import { authorizationServerOf, checkMcpOptions, } from "../mcp/mcp-options.js";
+import { userInfoAudience } from "../oauth/access-token.verifier.js";
+import { checkOAuthProvider, checkResourceUrl, oauthUseOf, pkceGuard, } from "../oauth/oauth-provider.hardening.js";
+import { checkPasswordsOptions, passwordHookOf, passwordRehashHook, } from "../passwords/passwords.options.js";
+import { isRecord } from "../policies.compiler.js";
+import { createRegistry, } from "../registry/access.registry.js";
+import { registryEndpoints, registryOnRequest, } from "../registry/registry.endpoints.js";
+import { registryOptionsOf, } from "../registry/registry.options.js";
+import { registrySchema } from "../registry/registry.schema.js";
+import { checkResourcesOptions, } from "../resources/auth-tables.guard.js";
+import { bridgedClaims, checkBridge, checkBridgePlugins, } from "./organization.bridge.js";
+/**
+ * What each plugin `aventaraAccess()` built was built with, by plugin: a map this
+ * module alone holds, so no object but one it returned passes for the plugin.
+ */
+const KERNELS = new WeakMap();
+const TOP_LEVEL = new Set([
+    "policies",
+    "principal",
+    "resources",
+    "organization",
+    "audit",
+    "passwords",
+    "registry",
+    "mcp",
+    "audience",
+]);
+/** The plugins `aventaraAccess()` carries itself, by id: a second one in `plugins` would answer for its routes. */
+const CARRIED = { [JWT_PLUGIN_ID]: "jwt()" };
+/**
+ * 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 function aventaraAccess(options) {
+    if (!isRecord(options)) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "aventaraAccess takes one object: `{ policies, principal?, resources?, organization?, audit?, passwords?, registry?, mcp?, audience? }`.");
+    }
+    for (const key of Object.keys(options)) {
+        if (!TOP_LEVEL.has(key)) {
+            throw new AccessError("ACCESS_OPTIONS_INVALID", `aventaraAccess does not take \`${key}\`; it takes \`policies\`, \`principal\`, \`resources\`, \`organization\`, \`audit\`, \`passwords\`, \`registry\`, \`mcp\` and \`audience\`. Better Auth's own options go to betterAuth({...}) beside it.`);
+        }
+    }
+    const given = options;
+    if (given.policies === undefined) {
+        throw new AccessError("ACCESS_OPTIONS_INVALID", "the `policies` option is missing: pass `{ rules, claims }`, the rules (`definePolicies(model)…`) and the claims they read.");
+    }
+    const checked = checkPoliciesBlock(given.policies, given.principal);
+    const resources = checkResourcesOptions(given.resources);
+    const bridge = checkBridge(given.organization, checked.claims);
+    const passwords = checkPasswordsOptions(given.passwords);
+    const registrySettings = registryOptionsOf(given.registry);
+    // The block's shape now; its resource against the issuer when Better Auth starts.
+    const mcp = checkMcpOptions(given.mcp, "mcp", "");
+    const oauthOn = oauthUseOf(mcp, given.audience === undefined
+        ? undefined
+        : checkResourceUrl(given.audience, "audience", ""), undefined);
+    const modules = loadBetterAuth();
+    // The bridge owns its two claims: neither the user's field of the same name nor
+    // `claimsOf` fills them.
+    const bridged = bridge === undefined ? [] : [bridge.claim, bridge.organizationClaim];
+    const ownClaims = {
+        ...checked.claims,
+    };
+    for (const claim of bridged) {
+        delete ownClaims[claim];
+    }
+    const claimsOf = checked.claimsOf === undefined || bridge === undefined
+        ? checked.claimsOf
+        : async (source) => {
+            const answer = await checked.claimsOf(source);
+            if (!isRecord(answer)) {
+                return answer;
+            }
+            const kept = { ...answer };
+            for (const claim of bridged) {
+                delete kept[claim];
+            }
+            return kept;
+        };
+    const claimsFor = async (context, source) => {
+        const claims = await issuedClaims(source, bridge === undefined ? checked.claims : ownClaims, claimsOf);
+        if (bridge === undefined) {
+            return claims;
+        }
+        const fromBridge = await bridgedClaims(bridge, (await context()), source);
+        return fromBridge === undefined ? claims : { ...claims, ...fromBridge };
+    };
+    const start = (block, own) => {
+        const plugins = refuseInstalledPlugins(block.plugins, {
+            by: "aventaraAccess()",
+            at: "plugins",
+            installs: CARRIED,
+            own,
+            registry: registrySettings !== undefined,
+        });
+        for (const plugin of plugins) {
+            const id = plugin?.id;
+            if (plugin !== own && normalisedId(id) === ACCESS_PLUGIN_ID) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", `plugins holds a second Access plugin (plugin id "${String(id)}") beside aventaraAccess(): Better Auth runs one. Remove it.`);
+            }
+        }
+        if (resources.members) {
+            refuseUnverifiedInvitations(plugins, "`resources: { members: true }`");
+        }
+        if (bridge !== undefined) {
+            checkBridgePlugins(plugins, bridge);
+        }
+        const issuer = issuerOf(block, modules, "baseURL");
+        const checkedMcp = checkMcpOptions(given.mcp, "mcp", issuer);
+        const audience = given.audience === undefined
+            ? undefined
+            : checkResourceUrl(given.audience, "audience", issuer);
+        const userInfo = userInfoAudience(block, modules);
+        const use = oauthUseOf(checkedMcp, audience, userInfo);
+        if (use !== undefined) {
+            checkOAuthProvider(plugins, use, { at: "plugins", own });
+        }
+        return {
+            ...(checkedMcp === undefined
+                ? {}
+                : {
+                    mcp: {
+                        resource: checkedMcp.resource,
+                        server: authorizationServerOf(issuer, "baseURL"),
+                    },
+                }),
+            ...(audience === undefined ? {} : { audience }),
+            userInfo,
+            issuer,
+            crossSite: crossSiteSessionCookie(block, "trustedOrigins"),
+            facts: betterAuthTablesFor({
+                options: block,
+                modules,
+                checked,
+                resources,
+                bridged,
+            }),
+        };
+    };
+    // Fixed when Better Auth initialises the plugin, from its options: the tokens'
+    // issuer and audience, and the context the claims, the session check and the
+    // audit log read. `jwt()` hands its payload function the session alone, never
+    // Better Auth's context, so these are the plugin's, not each context's: a plugin
+    // started again (Better Auth's migrations build another context from the same
+    // options) must find every one of them as it was, or it is refused.
+    let first;
+    const contextOf = async () => first?.context;
+    const auditTo = auditDestinationOf(given.audit);
+    const auditLog = auditTo === undefined
+        ? undefined
+        : createAuditLog(auditTo, async () => (await contextOf()));
+    const watch = sessionWatch({
+        kind: "web",
+        auditLog,
+        modules,
+        plugins: () => first?.plugins ?? [],
+    });
+    const carried = modules.jwt({
+        jwt: {
+            get issuer() {
+                return first?.issuer;
+            },
+            get audience() {
+                return first?.issuer;
+            },
+            expirationTime: `${checked.tokenTtl}s`,
+            definePayload: async (source) => {
+                if (first?.cookieCache === true) {
+                    await sessionStillLive(contextOf, source.session, () => new modules.APIError("UNAUTHORIZED", {
+                        message: "The session has ended.",
+                    }));
+                }
+                return claimsFor(contextOf, source);
+            },
+        },
+    });
+    // The registry's routes store through the adapter of the Better Auth that started
+    // the plugin: every instance it is in has the same database (`init` refuses one
+    // that does not), and no route runs before Better Auth has started it.
+    const registryStore = registrySettings === undefined
+        ? undefined
+        : createRegistry(async () => {
+            const context = first?.context;
+            if (context?.adapter === undefined) {
+                throw new AccessError("ACCESS_OPTIONS_INVALID", "the registry was asked before Better Auth started aventaraAccess(): build Better Auth with it in its plugins first.");
+            }
+            return context.adapter;
+        }, registrySettings);
+    const registryRoutes = registryStore === undefined
+        ? undefined
+        : registryEndpoints(registryStore, modules.createAuthEndpoint);
+    const carriedHooks = carried.hooks;
+    const plugin = {
+        id: ACCESS_PLUGIN_ID,
+        version: carried.version,
+        init(ctx) {
+            const { options: block } = ctx;
+            const started = start(block, plugin);
+            const now = {
+                issuer: started.issuer,
+                crossSite: started.crossSite,
+                cookieCache: cookieCacheOn(block),
+                database: block.database,
+                secondaryStorage: block.secondaryStorage,
+            };
+            if (first === undefined) {
+                first = {
+                    ...now,
+                    context: ctx,
+                    plugins: Array.isArray(block.plugins) ? block.plugins : [],
+                };
+            }
+            else if (now.issuer !== first.issuer ||
+                now.crossSite !== first.crossSite ||
+                now.cookieCache !== first.cookieCache ||
+                now.database !== first.database ||
+                now.secondaryStorage !== first.secondaryStorage) {
+                throw new AccessError("ACCESS_PLUGIN_DUPLICATE", "one aventaraAccess() plugin is in two Better Auth instances whose options differ (database, secondary storage, base URL, session cookie or cookie cache): call aventaraAccess() for each betterAuth({...}).");
+            }
+            // Better Auth's password hook, argon2id unless the app set its own: put in
+            // Better Auth's context, which Better Auth built from its options before
+            // initialising its plugins.
+            const hook = passwordHookOf(passwords, block.emailAndPassword, modules, contextOf, "emailAndPassword");
+            const watched = watch.init?.();
+            // The carried `jwt()`, found by its own id in Better Auth's context, as a plugin
+            // beside it would be: the OAuth provider reads its issuer and keys there.
+            const { getPlugin, hasPlugin } = ctx;
+            const jwtLookup = {
+                getPlugin: (id) => id === JWT_PLUGIN_ID ? carried : getPlugin(id),
+                hasPlugin: (id) => id === JWT_PLUGIN_ID || hasPlugin(id),
+            };
+            const { password } = ctx;
+            return {
+                ...watched,
+                context: {
+                    ...watched?.context,
+                    ...jwtLookup,
+                    ...(hook === undefined
+                        ? {}
+                        : {
+                            password: {
+                                ...password,
+                                hash: hook.hash,
+                                verify: hook.verify,
+                            },
+                        }),
+                },
+            };
+        },
+        endpoints: registryRoutes === undefined
+            ? carried.endpoints
+            : { ...carried.endpoints, ...registryRoutes },
+        // A push's key is checked before Better Auth reads its body, on any mount.
+        ...(registryStore === undefined
+            ? {}
+            : { onRequest: registryOnRequest(registryStore) }),
+        hooks: {
+            before: [
+                ...(carriedHooks.before ?? []),
+                ...(oauthOn === undefined ? [] : [pkceGuard(modules)]),
+                ...(watch.hooks?.before ?? []),
+            ],
+            after: [
+                ...(carriedHooks.after ?? []),
+                ...(watch.hooks?.after ?? []),
+                // Inert unless Better Auth's password hook is Access's (the app's own passes through).
+                passwordRehashHook(modules),
+            ],
+        },
+        schema: {
+            ...carried.schema,
+            ...(registrySettings === undefined ? {} : registrySchema),
+            ...(auditTo?.kind === "table" ? auditSchema : {}),
+        },
+        $Infer: {},
+    };
+    const kernel = {
+        checked,
+        resources,
+        bridge,
+        modules,
+        auditLog,
+        registry: registrySettings,
+        start,
+        claimsFor,
+    };
+    KERNELS.set(plugin, kernel);
+    // The declared return type states it; a cast restating it costs the type-checker
+    // the whole plugin type again.
+    return plugin;
+}
+/** What `aventaraAccess()` was built with, when `plugin` is one; `undefined` for any other plugin. */
+export const pluginKernelOf = (plugin) => typeof plugin === "object" && plugin !== null
+    ? KERNELS.get(plugin)
+    : undefined;

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

@@ -0,0 +1,80 @@
+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[] | {
+        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;
+};
+/** 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 {};