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

package/dist/access/request.state.js

@@ -0,0 +1,266 @@
+// A request's state, `{ me }`: who the request's bearer token or session cookie says
+// the caller is, verified, and mapped to the app's principal. `createAccess`'s
+// `state` and `accessOf(auth).state` are this one function over their own Better
+// Auth instance, so both ways in read a request alike: the bearer token against the
+// key set, never a cookie beside an `Authorization` header, and a session cookie only
+// from a site Better Auth trusts.
+//
+// A bearer token may also be an access token Better Auth's OAuth provider issued for
+// one resource (`typ: "at+jwt"`), read by the verifier of that resource alone
+// (`oauth/access-token.verifier.ts`), never as a session token:
+//
+// - with `mcp`, one for the MCP endpoint: an agent's, whose principal carries what the
+//   token grants (`mcp/agent.grant.ts`), which the policy holds it to before the rules
+//   (`mcp/agent-scope.gate.ts`), and which `agentOf(me)` reads;
+// - with `audience` (the service's opt-in), one addressed to this service, and carrying
+//   one of Access's scopes (`aventara:read`, `aventara:write`): the user's, held to
+//   those scopes under every origin. One with neither is nobody's. The service then
+//   takes no other bearer token: the one-org token `GET /token` issues (its audience
+//   the issuer) is refused.
+import { decodeProtectedHeader } from "jose";
+import { mayChange, SESSION_USE } from "../kiosk/session-use.marker.js";
+import { hasAventaraScope, withGrant, } from "../mcp/agent.grant.js";
+import { carrySubject, claimReturned } from "./principal.subject.js";
+import { readsSessionCookie, } from "./profile.policy.js";
+import { isAccessTokenType } from "./token.verifier.js";
+const bearerOf = (headers) => /^Bearer[ \t]+([^ \t]+)[ \t]*$/i.exec(headers.get("authorization") ?? "")?.[1];
+/**
+ * Whether a request may be read by its session cookie, where the browser could have
+ * sent it from another site: its `Origin` is one Better Auth trusts, or, without
+ * one, the browser says it is not cross-site (`Sec-Fetch-Site` `same-origin` or
+ * `none`). A request with neither header is no browser's, and passes.
+ */
+const fromTrustedSite = (headers, trusted) => {
+    const origin = headers.get("origin");
+    if (origin !== null) {
+        return origin !== "null" && trusted(origin);
+    }
+    const site = headers.get("sec-fetch-site");
+    return site === null || site === "same-origin" || site === "none";
+};
+/** The methods that change nothing: a cookie on them is read whatever site sent it (with `sameSite: "lax"`, a browser sends it from another site only on a top-level `GET`). */
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS"]);
+/** The method the client sent, from the host's request (Express, Fastify or a Web `Request`); `undefined` when there is none. */
+const methodOf = (request) => {
+    const { method, originalMethod } = (request ?? {});
+    // Express's method-override keeps the method the client sent here.
+    const sent = typeof originalMethod === "string" ? originalMethod : method;
+    return typeof sent === "string" ? sent.toUpperCase() : undefined;
+};
+const headersOf = (given) => {
+    const headers = new Headers();
+    given.forEach((value, name) => {
+        headers.append(name, value);
+    });
+    return headers;
+};
+/** Whether a JWT's header names an OAuth access token; `false` for anything that is not a JWT. */
+const isAccessToken = (token) => {
+    try {
+        return isAccessTokenType(decodeProtectedHeader(token).typ);
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * Who Access's own `GET /me` route answers a request as: the identity of a session
+ * token, a session cookie or a token addressed to the service; `null` for nobody, and
+ * for an agent's access token, which opens nothing over HTTP but the MCP endpoint.
+ */
+export const meOf = (caller) => caller === null || caller.grant?.via === "mcp" ? null : caller.identity;
+/**
+ * Who `access.client.verbs.me` answers a request as: the identity `{ sub, claims }`
+ * of any credential the state reads, an agent's included (the framework's MCP `me`
+ * tool calls it in-process with the agent's headers). A token's identity is a copy
+ * carrying what it grants, so `agentOf` tells an agent's apart.
+ */
+export const verbMeOf = (caller) => caller === null
+    ? null
+    : caller.grant === undefined
+        ? caller.identity
+        : withGrant(caller.identity, caller.grant);
+/**
+ * A request's identity over one Better Auth instance (`auth`, built on first use):
+ * from a bearer token the verifier accepts (an agent's access token, the agent
+ * verifier, when `mcp` is on), or (profile `web`) from the session Better Auth's
+ * store holds for the request's cookie, with the claims `claimsFor` gives that
+ * session.
+ */
+export const requestIdentity = (input) => {
+    const { auth, verifier, agents, audience, kind, crossSite, claimsFor } = input;
+    const identityOf = async (headers, request) => {
+        // An Authorization header names the credential: a bearer token, or nothing
+        // Access reads. The session cookie beside it is not a fallback.
+        if (headers.has("authorization")) {
+            const token = bearerOf(headers);
+            if (token === undefined) {
+                return null;
+            }
+            // An access token is read by the verifiers of the resources this instance
+            // reads tokens for, never by the session verifier (which refuses one too).
+            if (isAccessToken(token)) {
+                const agent = await agents?.verify(token);
+                if (agent !== undefined && agent !== null) {
+                    return {
+                        identity: agent.identity,
+                        grant: { ...agent.grant, via: "mcp" },
+                    };
+                }
+                const own = await audience?.verify(token);
+                // Scopes narrow, never widen: a token addressed to the service with none of
+                // Access's scopes grants nothing, and is nobody's.
+                return own === undefined ||
+                    own === null ||
+                    !hasAventaraScope(own.grant.scopes)
+                    ? null
+                    : {
+                        identity: own.identity,
+                        grant: { ...own.grant, via: "audience" },
+                    };
+            }
+            // A service that opts in to its own audience takes no one-org token.
+            if (audience !== undefined) {
+                return null;
+            }
+            const identity = await verifier.verify(token);
+            return identity === null ? null : { identity };
+        }
+        if (!readsSessionCookie(kind) || !headers.has("cookie")) {
+            return null;
+        }
+        // A cookie counts only from a site Better Auth trusts: on every request that
+        // may change something (any method but GET, HEAD and OPTIONS, and a request
+        // whose method the host did not pass), and with `sameSite: "none"`, on all.
+        const method = methodOf(request);
+        if (crossSite || method === undefined || !SAFE_METHODS.has(method)) {
+            const context = (await auth().$context);
+            if (!fromTrustedSite(headers, (origin) => context.isTrustedOrigin(origin))) {
+                return null;
+            }
+        }
+        // The store, never the cookie cache: a revoked session is gone at once.
+        const session = await auth().api.getSession({
+            headers: headersOf(headers),
+            query: { disableCookieCache: true },
+            // A write is the till's use of its session (the kiosk's idle timer); a read is not.
+            ...(mayChange(method) ? { [SESSION_USE]: true } : {}),
+        });
+        if (session === null) {
+            return null;
+        }
+        return {
+            identity: { sub: session.user.id, claims: await claimsFor(session) },
+        };
+    };
+    return identityOf;
+};
+/**
+ * The request state over a request's identity (`requestIdentity`): `me` is the
+ * identity, or what the app's `principal` maps it to, with the `sub` carried on it
+ * for the audit, and, for an OAuth access token, a copy of it carrying what the
+ * token grants. The identity `principal` is given for such a token carries the grant
+ * too, so `agentOf(identity)` tells the app an agent's request while it maps it.
+ */
+export const requestState = (identityOf, principal) => {
+    return async ({ headers, request }) => {
+        const caller = await identityOf(headers, request);
+        if (caller === null) {
+            return stateOf(null);
+        }
+        const { grant } = caller;
+        const identity = grant === undefined
+            ? caller.identity
+            : withGrant(caller.identity, grant);
+        const mapped = principal === undefined ? identity : await principal(identity);
+        // One object handed out for two users is refused (a cache keyed wrongly would
+        // serve one as the other), without writing to it.
+        claimReturned(mapped, identity.sub);
+        // A copy of the plain data: the app's own objects are never frozen.
+        const made = new Map();
+        const copied = plainCopy(mapped, made);
+        const me = grant === undefined ? copied : withGrant(copied, grant);
+        // Access's own objects: the copies, and the one `withGrant` makes. A value the
+        // app returned that is not plain data (a class instance, a `Map`) is `me` as given.
+        const ours = typeof me === "object" &&
+            me !== null &&
+            (grant !== undefined || made.get(mapped) === me);
+        // The `sub` travels with `me`: whichever instance the host asks for the
+        // policy (under Next, another bundle's) reads it for the audit's `userId`.
+        carrySubject(me, identity.sub, ours);
+        for (const copy of made.values()) {
+            Object.freeze(copy);
+        }
+        if (ours) {
+            Object.freeze(me);
+        }
+        return stateOf(me ?? null);
+    };
+};
+/**
+ * The state over `me`: `me` is a non-writable member of the state, and nothing of
+ * its plain data changes once it is derived, so no code that runs during the request
+ * (a pipeline, a hook, a computed field) can make the policy see another principal.
+ */
+const stateOf = (me) => Object.defineProperty({}, "me", {
+    value: me,
+    enumerable: true,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Plain data: an array, or an object made by `{}`, JSON or `Object.create(null)`. A
+ * class instance is not: its `#private` fields cannot be copied, so it is kept as
+ * the app gave it, as a `Map` is.
+ */
+const isPlainData = (value) => {
+    const prototype = Object.getPrototypeOf(value);
+    return Array.isArray(value)
+        ? prototype === Array.prototype
+        : prototype === Object.prototype || prototype === null;
+};
+/**
+ * A copy of `value`'s plain data, all the way down: each array and plain object (on
+ * the same prototype), with every own property, its non-enumerable and symbol-keyed
+ * ones included. `made` maps each original to its copy (so a cycle stays one).
+ * Anything else (a primitive, a class instance, a `Map`, a `Set`, a `Date`, a typed
+ * array, a function) is kept as the app gave it, and so is a getter.
+ */
+const plainCopy = (value, made) => {
+    if (typeof value !== "object" || value === null || !isPlainData(value)) {
+        return value;
+    }
+    const done = made.get(value);
+    if (done !== undefined) {
+        return done;
+    }
+    const copy = Array.isArray(value)
+        ? []
+        : Object.create(Object.getPrototypeOf(value));
+    made.set(value, copy);
+    for (const key of Reflect.ownKeys(value)) {
+        const descriptor = Object.getOwnPropertyDescriptor(value, key);
+        if (descriptor === undefined) {
+            continue;
+        }
+        if ("value" in descriptor) {
+            descriptor.value = plainCopy(descriptor.value, made);
+        }
+        Object.defineProperty(copy, key, descriptor);
+    }
+    return copy;
+};
+/**
+ * Refuses a token for a session the store no longer has (revoked, signed out,
+ * expired): with Better Auth's cookie cache on, a session read from its cookie may
+ * have been revoked since, so a token is issued only for one the store still has.
+ */
+export const sessionStillLive = async (store, session, refuse) => {
+    const { token } = session;
+    const found = typeof token === "string"
+        ? await (await store()).internalAdapter.findSession(token)
+        : null;
+    if (found === null || found.session.expiresAt.getTime() <= Date.now()) {
+        throw refuse();
+    }
+};

package/dist/access/session.hooks.d.ts

@@ -0,0 +1,114 @@
+import { type AuditLog, type SignInIdentifier } from "../audit/audit.log.js";
+import type { BetterAuthModules } from "./better-auth.loader.js";
+import { type AccessProfileKind } from "./profile.policy.js";
+/** A session row, as Better Auth's database hooks hand it over. */
+type HookSession = {
+    readonly userId?: unknown;
+} | null | undefined;
+/** The endpoint context Better Auth hands a hook's matcher and its database hooks. */
+type HookContext = {
+    readonly request?: unknown;
+    readonly path?: unknown;
+} | null | undefined;
+/** Where Better Auth's context names its session cookies. */
+type CookieContext = {
+    readonly authCookies?: {
+        readonly sessionToken?: {
+            readonly name?: unknown;
+        };
+        readonly sessionData?: {
+            readonly name?: unknown;
+        };
+    };
+};
+/** The part of a response's headers the service profile's cookie strip reads and changes. */
+type ResponseCookies = {
+    getSetCookie(): string[];
+    delete(name: string): void;
+    append(name: string, value: string): void;
+};
+/** The session cookies' bare names: the token's, and the cookie cache's, which carries the session too. */
+export declare const sessionCookies: (context: CookieContext) => readonly string[];
+/**
+ * The service profile's last word on what `access.handler` answers, after Better
+ * Auth's router and every plugin's `onResponse`: no session cookie (`names`,
+ * through `sessionCookies`), whatever set it. The headers are changed in place; a
+ * response whose headers cannot change is answered with a bare 404 instead.
+ */
+export declare const withoutSessionCookies: (response: {
+    readonly headers: ResponseCookies;
+}, names: readonly string[]) => {
+    readonly headers: ResponseCookies;
+};
+/**
+ * The identifier a sign-in names, read as Better Auth 1.7.12 to 1.7.14 reads it on that route
+ * and nowhere else (any other field of the body is the caller's to fill): an email
+ * lower-cased, as `/sign-in/email` and `/sign-in/email-otp` look it up; a username
+ * through the `username()` plugin's `usernameNormalization` (lower-cased by default,
+ * as given with `false`); a phone number as given, as `/sign-in/phone-number` looks
+ * it up.
+ */
+export declare const signInIdentifier: (plugins: readonly unknown[] | (() => readonly unknown[])) => SignInIdentifier;
+/**
+ * The Access plugin's members for sessions (`init` with its database hooks, and
+ * `hooks`), for the profile and the audit log; none when neither needs them.
+ */
+export declare const sessionWatch: (input: {
+    readonly kind: AccessProfileKind;
+    readonly auditLog: AuditLog | undefined;
+    readonly modules: Pick<BetterAuthModules, "createAuthMiddleware" | "APIError">;
+    /** The app's Better Auth plugins (or, for the Access plugin, a read of them once Better Auth starts it): how they read a sign-in's identifier. */
+    readonly plugins: readonly unknown[] | (() => readonly unknown[]);
+    /** The kiosk profile's own step before a session is created (`kioskPlugin`'s `sessionCreating`): it binds one on an enrolled device. */
+    readonly sessionCreating?: (session: {
+        readonly kioskDeviceId?: unknown;
+    } | null | undefined, context: HookContext) => Promise<false | {
+        readonly data: object;
+    } | undefined>;
+    /** The kiosk profile's own step once a session is created (`kioskPlugin`'s `sessionCreated`). */
+    readonly sessionCreated?: (session: HookSession, context: HookContext) => Promise<void>;
+}) => {
+    init?: never;
+    hooks?: never;
+} | {
+    init: () => {
+        options: {
+            databaseHooks: {
+                session: {
+                    delete?: {
+                        after: (session: {
+                            readonly userId?: unknown;
+                            readonly impersonatedBy?: unknown;
+                        } | null | undefined, context: {
+                            readonly request?: unknown;
+                            readonly path?: unknown;
+                            readonly body?: unknown;
+                            readonly context?: {
+                                readonly secret?: unknown;
+                            } | undefined;
+                        } | null | undefined) => Promise<void>;
+                    };
+                    create: {
+                        after?: (session: HookSession, context: HookContext) => Promise<void>;
+                        before?: (session: {
+                            readonly kioskDeviceId?: unknown;
+                        } | null | undefined, context: HookContext) => Promise<false | {
+                            readonly data: object;
+                        } | undefined>;
+                    };
+                };
+            };
+        };
+    };
+    hooks: {
+        before: {
+            matcher: (ctx: HookContext) => boolean;
+            handler: unknown;
+        }[];
+        after: {
+            matcher: (ctx: HookContext) => boolean;
+            handler: unknown;
+        }[];
+    };
+};
+export {};

package/dist/access/session.hooks.js

@@ -0,0 +1,258 @@
+// The Better Auth hooks the Access plugin installs over sessions: the service
+// profile's refusals, and the audit log's events from Better Auth's request path.
+//
+// - Service profile: no request through `access.handler` gets a session. A route
+//   that starts one (`startsSession`, by Better Auth's own endpoint path, `ctx.path`)
+//   is refused with a 404 before it runs. Any other route (a plugin's the list does
+//   not know) cannot create one either: Better Auth's `session.create` before-hook
+//   refuses the row, so no session exists even for a moment, and once the endpoint
+//   has answered, the answer is replaced by a bare 404, its cookies and headers
+//   dropped. So is an answer that sets the session cookie of a session that already
+//   existed. And `access.handler` itself strips any session cookie from what Better
+//   Auth answers (`withoutSessionCookies`), after every plugin's `onResponse`, which
+//   also covers a route that returns its own `Response` (Better Auth runs no after
+//   hook on one). A route that puts a session token in a JSON body is
+//   not covered: no built-in plugin does. The server's own calls to Better Auth's
+//   API with no request sign users in as before.
+// - Audit: sign-ins and sign-outs from Better Auth's session hooks, refused sign-ins
+//   and issued tokens from its endpoint hooks (`audit.log.ts` says what each event
+//   holds).
+import { endpointAudit, sessionAuditHooks, } from "../audit/audit.log.js";
+import { KIOSK_SWITCH_PATH } from "../kiosk/kiosk-verbs.schema.js";
+import { servesRoute, startsSession, } from "./profile.policy.js";
+/** Whether the call came through `access.handler`: a request, not the server's own API call. */
+const fromOutside = (context) => typeof context?.request === "object" && context.request !== null;
+/** A cookie name as a browser could match it to Better Auth's: no case, no `__Secure-`/`__Host-` prefix. */
+const bareCookie = (name) => name
+    .trim()
+    .toLowerCase()
+    .replace(/^__(?:secure|host)-/, "");
+/** The session cookies' bare names: the token's, and the cookie cache's, which carries the session too. */
+export const sessionCookies = (context) => {
+    const names = [];
+    for (const name of [
+        context.authCookies?.sessionToken?.name,
+        context.authCookies?.sessionData?.name,
+    ]) {
+        if (typeof name === "string") {
+            names.push(bareCookie(name));
+        }
+    }
+    return names;
+};
+/** The bare name a `Set-Cookie` line sets, and whether it sets a value (not one that deletes it). */
+const cookieSet = (line) => {
+    const [pair = ""] = line.split(";");
+    const equals = pair.indexOf("=");
+    return {
+        name: bareCookie(equals < 0 ? pair : pair.slice(0, equals)),
+        value: equals >= 0 && pair.slice(equals + 1).trim() !== "",
+    };
+};
+/**
+ * Whether a cookie's bare name is a session cookie's: one of `names`, or the
+ * `multiSession()` plugin's `<session_token>_multi-<token>`.
+ */
+const isSessionCookie = (name, names) => {
+    for (const session of names) {
+        if (name === session || name.startsWith(`${session}_multi-`)) {
+            return true;
+        }
+    }
+    return false;
+};
+/** Whether response headers set one of `names` to a value. */
+const setsCookie = (headers, names) => {
+    for (const line of headers?.getSetCookie() ?? []) {
+        const set = cookieSet(line);
+        if (set.value && isSessionCookie(set.name, names)) {
+            return true;
+        }
+    }
+    return false;
+};
+/**
+ * The service profile's last word on what `access.handler` answers, after Better
+ * Auth's router and every plugin's `onResponse`: no session cookie (`names`,
+ * through `sessionCookies`), whatever set it. The headers are changed in place; a
+ * response whose headers cannot change is answered with a bare 404 instead.
+ */
+export const withoutSessionCookies = (response, names) => {
+    const lines = response.headers.getSetCookie();
+    const kept = [];
+    for (const line of lines) {
+        if (!isSessionCookie(cookieSet(line).name, names)) {
+            kept.push(line);
+        }
+    }
+    if (kept.length === lines.length) {
+        return response;
+    }
+    try {
+        response.headers.delete("set-cookie");
+        for (const line of kept) {
+            response.headers.append("set-cookie", line);
+        }
+        return response;
+    }
+    catch {
+        return new Response(null, { status: 404 });
+    }
+};
+/** The sign-in routes that name their user, by the body field each reads it from. */
+const IDENTIFIED = {
+    "/sign-in/email": "email",
+    "/sign-in/email-otp": "email",
+    "/sign-in/username": "username",
+    "/sign-in/phone-number": "phoneNumber",
+};
+/**
+ * The identifier a sign-in names, read as Better Auth 1.7.12 to 1.7.14 reads it on that route
+ * and nowhere else (any other field of the body is the caller's to fill): an email
+ * lower-cased, as `/sign-in/email` and `/sign-in/email-otp` look it up; a username
+ * through the `username()` plugin's `usernameNormalization` (lower-cased by default,
+ * as given with `false`); a phone number as given, as `/sign-in/phone-number` looks
+ * it up.
+ */
+export const signInIdentifier = (plugins) => {
+    let normalization;
+    let read = false;
+    /** The `username()` plugin's normalization, read once: the plugins known now, or (the Access plugin) when Better Auth starts it. */
+    const normalizationOf = () => {
+        if (!read) {
+            read = true;
+            for (const plugin of typeof plugins === "function"
+                ? plugins()
+                : plugins) {
+                const { id, options } = (plugin ?? {});
+                if (id === "username") {
+                    normalization = options?.usernameNormalization;
+                }
+            }
+        }
+        return normalization;
+    };
+    if (typeof plugins !== "function") {
+        normalizationOf();
+    }
+    return (path, body) => {
+        const field = typeof path === "string" ? IDENTIFIED[path] : undefined;
+        const value = field === undefined
+            ? undefined
+            : body?.[field];
+        if (field === undefined || typeof value !== "string") {
+            return undefined;
+        }
+        if (field !== "username") {
+            return `${field}:${field === "email" ? value.toLowerCase() : value}`;
+        }
+        try {
+            const normalized = normalizationOf() === false
+                ? value
+                : typeof normalizationOf() === "function"
+                    ? normalizationOf()(value)
+                    : value.toLowerCase();
+            return typeof normalized === "string"
+                ? `username:${normalized}`
+                : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+};
+/**
+ * The Access plugin's members for sessions (`init` with its database hooks, and
+ * `hooks`), for the profile and the audit log; none when neither needs them.
+ */
+export const sessionWatch = (input) => {
+    const { kind, auditLog, modules, sessionCreating, sessionCreated } = input;
+    const service = kind === "service";
+    if (!service &&
+        auditLog === undefined &&
+        sessionCreated === undefined &&
+        sessionCreating === undefined) {
+        return {};
+    }
+    const identify = signInIdentifier(input.plugins);
+    /** The requests through the handler whose session the service profile refused. */
+    const refused = new WeakSet();
+    const audit = auditLog === undefined ? undefined : sessionAuditHooks(auditLog, identify);
+    const created = audit === undefined && sessionCreated === undefined
+        ? undefined
+        : async (session, context) => {
+            await audit?.session.create.after(session, context);
+            await sessionCreated?.(session, context);
+        };
+    const databaseHooks = {
+        session: {
+            create: {
+                ...(service
+                    ? {
+                        before: async (_session, context) => {
+                            if (!fromOutside(context)) {
+                                return undefined;
+                            }
+                            refused.add(context.request);
+                            return false;
+                        },
+                    }
+                    : sessionCreating === undefined
+                        ? {}
+                        : { before: sessionCreating }),
+                ...(created === undefined ? {} : { after: created }),
+            },
+            ...(audit === undefined ? {} : { delete: audit.session.delete }),
+        },
+    };
+    const notFound = () => new modules.APIError("NOT_FOUND");
+    const before = service
+        ? [
+            {
+                matcher: (ctx) => fromOutside(ctx) && !servesRoute(kind, ctx.path),
+                handler: modules.createAuthMiddleware(async () => {
+                    throw notFound();
+                }),
+            },
+        ]
+        : [];
+    const after = [
+        ...(auditLog === undefined
+            ? []
+            : [
+                {
+                    // The kiosk's PIN switch logs its own refusals, with their device.
+                    matcher: (ctx) => (startsSession(ctx?.path) && ctx?.path !== KIOSK_SWITCH_PATH) ||
+                        ctx?.path === "/token",
+                    handler: modules.createAuthMiddleware(endpointAudit(auditLog, startsSession, identify)),
+                },
+            ]),
+        ...(service
+            ? [
+                {
+                    matcher: fromOutside,
+                    handler: modules.createAuthMiddleware(async ({ request, context }) => {
+                        const headers = context.responseHeaders;
+                        const handsOutSession = (typeof request === "object" &&
+                            request !== null &&
+                            refused.has(request)) ||
+                            setsCookie(headers, sessionCookies(context));
+                        if (!handsOutSession) {
+                            return undefined;
+                        }
+                        for (const name of [...(headers?.keys() ?? [])]) {
+                            headers?.delete(name);
+                        }
+                        // A Response, not an error: Better Auth keeps the status an
+                        // endpoint refused with over an after hook's error.
+                        return new Response(null, { status: 404 });
+                    }),
+                },
+            ]
+            : []),
+    ];
+    return {
+        init: () => ({ options: { databaseHooks } }),
+        hooks: { before, after },
+    };
+};

package/dist/access/token.verifier.d.ts

@@ -0,0 +1,35 @@
+import { type JSONWebKeySet } from "jose";
+import { type AccessClaimsDeclaration } from "./claims.mapper.js";
+/** Where the key set comes from, and what a token must state. */
+type TokenVerifierSource = {
+    /** The published key set: `{ keys: [...] }`. */
+    readonly keys: () => Promise<JSONWebKeySet>;
+    readonly claims: AccessClaimsDeclaration;
+    /** The `iss` and the `aud` every token carries: the instance's fixed issuer. */
+    readonly issuer: string;
+    /** How long a token lives, in seconds: one issued longer ago is refused. */
+    readonly tokenTtl: number;
+    /** Milliseconds since the epoch; a test passes its own clock. */
+    readonly now?: () => number;
+};
+export type TokenVerifier = {
+    /** The identity a token proves, or `null` for a token that is not valid, current and Access's own. */
+    verify(token: string): Promise<{
+        readonly sub: string;
+        readonly claims: {
+            readonly [claim: string]: string | number | boolean;
+        };
+    } | null>;
+};
+/** The clock skew allowed between the issuer and the verifier, in seconds. */
+export declare const CLOCK_TOLERANCE_S = 5;
+/**
+ * The algorithms a token may be signed with: those Better Auth's `jwt()` signs with
+ * (its `keyPairConfig.alg`), all asymmetric. A token signed otherwise is refused
+ * before its key is looked up, whatever key the set holds.
+ */
+export declare const JWT_ALGORITHMS: readonly ["EdDSA", "ES256", "ES512", "PS256", "RS256"];
+/** Whether a JWT header's `typ` names an OAuth access token (RFC 9068, section 2.1: `at+jwt`, or `application/at+jwt`). */
+export declare const isAccessTokenType: (typ: unknown) => boolean;
+export declare const createTokenVerifier: (source: TokenVerifierSource) => TokenVerifier;
+export {};