@aotter/mantle 0.2.0-alpha.1 → 0.2.0-alpha.11

package/dist/auth/caller.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Request -> Caller with Better Auth's own API only: no cookie signing, expiry, refresh, revocation or token rule is
+ * re-implemented here. Nothing in this module imports Better Auth statically, so a public route that never calls
+ * `resolveCaller` never loads it, and a request without credentials never loads it either.
+ */
+import type { BetterAuthOptions } from "better-auth/types";
+import { type Caller } from "../kernel/contracts.js";
+import type { UserFields } from "../kernel/user-fields.js";
+type User = {
+    name?: string | null;
+    email?: string | null;
+    image?: string | null;
+    githubLogin?: string | null;
+    id: string;
+    role?: string | null;
+    banned?: boolean | null;
+    banExpires?: Date | string | number | null;
+};
+/** Display identity from the session this Caller already resolved; never an authority source. */
+/** The Better Auth user record the caller was resolved from (session, OAuth or service credential): name, email, image. */
+export declare const userOf: (caller: Caller) => Readonly<User> | undefined;
+/** @deprecated Use `userOf`; it covers every credential, not only sessions. */
+export declare const sessionUserOf: (caller: Caller) => Readonly<User> | undefined;
+/** The admin plugin's ban, lapsed once `banExpires` has passed (as the plugin reads it at sign-in). */
+export declare const isBanned: (user: User) => boolean;
+/** The application's `betterAuth()` instance, as far as Caller resolution reads it. */
+export interface AuthInstance {
+    readonly options: BetterAuthOptions;
+    readonly $context: Promise<unknown>;
+    readonly api: {
+        getSession(input: {
+            headers: Headers;
+            query?: {
+                disableCookieCache?: boolean;
+                disableRefresh?: boolean;
+            };
+            returnHeaders: true;
+        }): Promise<{
+            headers: Headers | null;
+            response: {
+                session: {
+                    id: string;
+                    impersonatedBy?: string | null;
+                };
+                user: User;
+            } | null;
+        }>;
+    };
+}
+/** Better Auth owns the role model; absence of its admin plugin grants no admin layer. */
+export declare function adminOptionsOf(auth: Pick<AuthInstance, "options">): {
+    adminRoles: string[];
+    adminUserIds: readonly string[];
+    defaultRole: string;
+};
+export interface AuthLoader<A extends AuthInstance = AuthInstance> {
+    /** `advanced.cookiePrefix` of the same options; read before Better Auth loads. */
+    readonly cookiePrefix: string;
+    /** The instance, imported on first use and checked against `cookiePrefix`. */
+    readonly get: () => Promise<A>;
+}
+/**
+ * `load` should be a dynamic import of the module that builds `betterAuth()`, so the bundler keeps it (and Better Auth)
+ * out of the entry module: `authLoader(() => import("./auth.js").then(m => m.auth))`.
+ */
+export declare function authLoader<A extends AuthInstance>(load: () => Promise<A>, cookiePrefix?: string): AuthLoader<A>;
+/**
+ * The Caller for a request that is not public. Public routes must not call it.
+ * - `Authorization: Bearer`: an OAuth access token verified by Better Auth's resource client for `audience`; an invalid
+ *   token is UNAUTHENTICATED, never anonymous. The user (role, ban) is read from the database on every request.
+ * - Otherwise a session cookie, validated by `auth.api.getSession` without the cookie cache, so revocation and role
+ *   changes apply on the next request. `readOnly: true` explicitly permits a bounded official cookie snapshot
+ *   only with no secondaryStorage and cookieCache {enabled:true,maxAge:1..60,refreshCache:false}.
+ *   The application classifies reads; HTTP method alone is not sufficient. No cookie means anonymous without loading Better Auth.
+ *   When Better Auth extends the session (`updateAge`) it sets a fresh cookie: pass the outgoing response's headers as
+ *   `responseHeaders` and those Set-Cookie lines are appended, so the browser cookie slides with the session.
+ */
+export declare function resolveCaller(request: Request, auth: AuthLoader, options?: {
+    readonly fields?: UserFields;
+    readonly audience?: string | readonly string[];
+    readonly readOnly?: boolean;
+    readonly responseHeaders?: Headers;
+    readonly scopes?: readonly string[];
+    readonly resolveCredential?: (request: Request) => Caller | null | Promise<Caller | null>;
+}): Promise<Caller>;
+export {};

package/dist/auth/caller.js

@@ -0,0 +1,128 @@
+import { ContractError } from "../kernel/contracts.js";
+import { userCaller } from "../kernel/user-caller.js";
+const users = new WeakMap();
+const withUser = (caller, user) => (users.set(caller, user), caller);
+export const userOf = (caller) => users.get(caller);
+export const sessionUserOf = userOf;
+export const isBanned = (user) => !!user.banned && (user.banExpires == null || new Date(user.banExpires).getTime() > Date.now());
+export function adminOptionsOf(auth) {
+    const plugin = auth.options.plugins?.find(plugin => plugin.id === "admin");
+    const configured = plugin?.options?.adminRoles ?? ["admin"];
+    return { adminRoles: plugin ? (typeof configured === "string" ? configured.split(",") : [...configured]).map(role => role.trim()) : [], adminUserIds: plugin?.options?.adminUserIds ?? [], defaultRole: plugin?.options?.defaultRole ?? "user" };
+}
+export function authLoader(load, cookiePrefix = "better-auth") {
+    let instance;
+    return {
+        cookiePrefix,
+        get: () => instance ??= load().then((auth) => {
+            if ((auth.options.advanced?.cookiePrefix ?? "better-auth") !== cookiePrefix)
+                throw new Error(`authLoader cookiePrefix '${cookiePrefix}' differs from the auth options' advanced.cookiePrefix.`);
+            if (auth.options.advanced?.cookies?.session_token?.name)
+                throw new Error("advanced.cookies.session_token.name is not supported: Better Auth's getSessionCookie cannot find a renamed session cookie.");
+            if (auth.options.secondaryStorage && !auth.options.session?.storeSessionInDatabase)
+                throw new ContractError("AUTH_CONFIGURATION_ERROR", "Session secondaryStorage requires session.storeSessionInDatabase: true.", "auth:session");
+            return auth;
+        }).catch((error) => { instance = undefined; throw error; }),
+    };
+}
+function checkFieldSources(instance, fields, session = false) {
+    for (const field of Object.keys(fields ?? {})) {
+        const additional = instance.options.user?.additionalFields;
+        const stored = additional && Object.hasOwn(additional, field) ? additional[field] : undefined;
+        if (!(stored ? stored.input === false : session && instance.options.plugins?.some(plugin => plugin.id === "custom-session")))
+            throw new ContractError("AUTH_CONFIGURATION_ERROR", `User field '${field}' requires an input: false additional field; customSession-only fields are available only to session credentials.`, "auth:user");
+    }
+}
+async function loadSubject(instance, id, fields, sessionUser) {
+    checkFieldSources(instance, fields, !!sessionUser);
+    const context = await instance.$context;
+    const user = await context.internalAdapter.findUserById(id);
+    if (!user || isBanned(user))
+        return null;
+    if (sessionUser)
+        for (const field of Object.keys(fields ?? {})) {
+            if (!Object.hasOwn(instance.options.user?.additionalFields ?? {}, field) && Object.hasOwn(sessionUser, field))
+                user[field] = sessionUser[field];
+        }
+    return user;
+}
+export async function resolveCaller(request, auth, options = {}) {
+    const lacks = (have) => options.scopes?.some(scope => !have.includes(scope));
+    const supplied = await options.resolveCredential?.(request);
+    if (supplied) {
+        if (supplied.kind !== "user" || supplied.credential === "session")
+            throw new ContractError("UNAUTHENTICATED", "Invalid service credential.");
+        if (lacks(supplied.scopes))
+            throw new ContractError("AUTH_DENIED", "The service credential lacks a required scope.");
+        const instance = await auth.get();
+        const user = await loadSubject(instance, supplied.subject, options.fields);
+        if (!user)
+            throw new ContractError("UNAUTHENTICATED", "The service credential's user is not active.");
+        return withUser(userCaller(user, { fields: options.fields, ...adminOptionsOf(instance), credential: supplied.credential, credentialId: supplied.credentialId, clientId: supplied.clientId, scopes: supplied.scopes, issuer: supplied.issuer }), user);
+    }
+    const authorization = request.headers.get("authorization");
+    if (authorization && /^(bearer|dpop) /i.test(authorization)) {
+        if (!options.audience)
+            throw new ContractError("UNAUTHENTICATED", "This route does not accept access tokens.");
+        const instance = await auth.get();
+        checkFieldSources(instance, options.fields);
+        const { oauthProviderResourceClient } = await import("@better-auth/oauth-provider/resource-client");
+        const { createDpopReplayStore } = await import("better-auth/oauth2");
+        const context = await instance.$context;
+        const verifier = oauthProviderResourceClient({ options: { ...instance.options, baseURL: context.baseURL, basePath: "" }, $context: instance.$context }).getActions();
+        let claims;
+        try {
+            claims = await verifier.verifyAccessTokenRequest(request, { verifyOptions: { audience: options.audience }, dpop: { replayStore: createDpopReplayStore(context.internalAdapter) } });
+        }
+        catch (cause) {
+            throw new ContractError("UNAUTHENTICATED", "The access token is not valid for this resource.", "", { cause });
+        }
+        const { assertActiveUserGrant } = await import("./oauth.js");
+        const granted = await assertActiveUserGrant(instance, claims, options.audience);
+        const user = await loadSubject(instance, granted.id, options.fields);
+        const scopes = typeof claims.scope === "string" ? claims.scope.split(/\s+/).filter(Boolean) : [];
+        if (lacks(scopes))
+            throw new ContractError("AUTH_DENIED", "The access token lacks a required scope.");
+        if (!user)
+            throw new ContractError("UNAUTHENTICATED", "The access token's user is not active.");
+        const text = (v) => (typeof v === "string" ? v : null);
+        return withUser(userCaller(user, { fields: options.fields, ...adminOptionsOf(instance), issuer: claims.iss, scopes, credential: "oauth", credentialId: text(claims.jti), clientId: text(claims.azp) ?? text(claims.client_id) }), user);
+    }
+    if (authorization !== null)
+        throw new ContractError("UNAUTHENTICATED", "The authorization header is not a supported credential.");
+    if (!request.headers.has("cookie"))
+        return { kind: "anonymous" };
+    const { getSessionCookie, splitSetCookieHeader } = await import("better-auth/cookies");
+    if (!getSessionCookie(request, { cookiePrefix: auth.cookiePrefix }))
+        return { kind: "anonymous" };
+    const instance = await auth.get();
+    checkFieldSources(instance, options.fields, true);
+    const mirror = !!instance.options.secondaryStorage;
+    const cache = instance.options.session?.cookieCache;
+    const cachedRead = options.readOnly === true && !mirror && cache?.enabled === true && cache.refreshCache === false &&
+        typeof cache.maxAge === "number" && cache.maxAge >= 1 && cache.maxAge <= 60;
+    const initial = await instance.api.getSession({ headers: request.headers, query: { disableCookieCache: !cachedRead, disableRefresh: mirror || !options.responseHeaders }, returnHeaders: true });
+    const found = initial.response;
+    if (!found)
+        return { kind: "anonymous" };
+    if (mirror) {
+        if (!instance.options.session?.storeSessionInDatabase)
+            throw new ContractError("AUTH_CONFIGURATION_ERROR", "Caller resolution with secondaryStorage requires session.storeSessionInDatabase: true.", "auth:session");
+        const context = await instance.$context;
+        const live = await context.adapter.findOne({ model: "session", where: [{ field: "id", value: found.session.id }] });
+        if (!live || live.userId !== found.user.id || !(new Date(live.expiresAt).getTime() > Date.now()))
+            return { kind: "anonymous" };
+    }
+    const user = await loadSubject(instance, found.user.id, options.fields, found.user);
+    if (!user)
+        return { kind: "anonymous" };
+    if (options.responseHeaders) {
+        const refreshed = mirror ? await instance.api.getSession({ headers: request.headers, query: { disableCookieCache: true }, returnHeaders: true }) : initial;
+        if (!refreshed.response || refreshed.response.session.id !== found.session.id || refreshed.response.user.id !== user.id)
+            return { kind: "anonymous" };
+        for (const cookie of refreshed.headers?.getSetCookie().flatMap(splitSetCookieHeader) ?? [])
+            options.responseHeaders.append("set-cookie", cookie);
+    }
+    const caller = userCaller(user, { fields: options.fields, ...adminOptionsOf(instance), credentialId: found.session.id, impersonatedBy: found.session.impersonatedBy ?? undefined });
+    return withUser(caller, user);
+}

package/dist/auth/{createAuthRoutes.js → consent.js}

@@ -1,92 +1,66 @@
-import { withCaller } from "../core/withCaller.js";
-const PRIVATE = { "cache-control": "private, no-store" };
-const CONSENT = new Set(["GET /oauth/consent", "GET /oauth/consent/data", "POST /oauth/consent"]);
-const CONSENTS = new Set(["GET /oauth/consents", "GET /oauth/consents/data", "POST /oauth/consents/revoke"]);
-const WELL_KNOWN = /^\/\.well-known\/(oauth-authorization-server|oauth-protected-resource)(\/|$)/;
-/** The service's auth entry: a Response for a path it owns, `null` for any other. */
-export function createAuthRoutes(auth, options) {
-    const base = auth.basePath.replace(/\/+$/, "");
-    const consent = withCaller(options.resolver, consentSurface(auth, options));
-    return async (request, context) => {
-        const { pathname } = new URL(request.url);
-        if (pathname === `${base}/methods` && request.method === "GET")
-            return Response.json({ methods: auth.methods }, { headers: { "cache-control": "no-store" } });
-        if (pathname.startsWith(`${base}/`) || WELL_KNOWN.test(pathname))
-            return auth.handler(request, context);
-        // only an owned route resolves a caller: `/oauth/callback/github` and the rest are the service's, whatever they carry
-        const route = `${request.method} ${pathname}`;
-        return CONSENT.has(route) || (CONSENTS.has(route) && auth.listOAuthConsents && auth.revokeOAuthConsent) ? consent(request) : null;
-    };
-}
-function consentSurface(auth, options) {
+import { PRIVATE, json, readBody, redirect, text } from "./route-http.js";
+export function consentSurface(auth, options) {
     const { listOAuthConsents: list, revokeOAuthConsent: revoke } = auth;
-    return async (request, caller) => {
-        const { pathname } = new URL(request.url);
-        const route = `${request.method} ${pathname}`;
+    return async (request, caller, route) => {
         const person = caller.kind === "user" && caller.credential === "session" ? caller.subject : null;
         const locale = /zh[-_]tw/i.test(request.headers.get("accept-language") ?? "") ? "zh-TW" : "en";
         if (route === "GET /oauth/consent/data") {
             if (!person)
-                return Response.json({ consent: null }, { status: 401, headers: PRIVATE });
-            const model = await auth.getOAuthConsentRequest(request).catch(() => null); // an invalid signed query stays secret-free
-            return Response.json({ consent: model }, { status: model ? 200 : 400, headers: PRIVATE });
+                return json({ consent: null }, 401);
+            const model = await auth.getOAuthConsentRequest(request).catch(() => null);
+            return json({ consent: model }, model ? 200 : 400);
         }
         if (route === "GET /oauth/consent") {
             const model = await auth.getOAuthConsentRequest(request).catch(() => null);
-            return html(consentHtml(locale, model), model ? 200 : 400, model?.redirectUri);
+            return html(consentHtml(locale, model), model ? 200 : 400);
         }
         if (route === "POST /oauth/consent") {
             if (!person)
-                return new Response("sign in to answer this request", { status: 401 });
-            const body = await request.text();
+                return text("sign in to answer this request", 401);
+            const body = await readBody(request);
             const decision = new URLSearchParams(body).get("decision");
             if (decision !== "approve" && decision !== "deny")
-                return new Response("invalid consent decision", { status: 400 });
-            // the redirect is the one Better Auth validated against the client's registration; nothing in the request names it
+                return text("invalid consent decision", 400);
             const location = await auth.completeOAuthConsent(new Request(request, { body }), decision === "approve").catch(() => null);
             const target = location && URL.canParse(location) ? new URL(location) : null;
             if (!target || /^(javascript|data|vbscript|blob):$/i.test(target.protocol))
-                return new Response("invalid authorization request", { status: 400 });
-            // the parsed form, so a browser cannot read `https:\\evil.test` differently from the check
-            return new Response(null, { status: 302, headers: { location: target.href, ...PRIVATE } });
+                return text("invalid authorization request", 400);
+            return redirect(target.href);
         }
         if (!list || !revoke)
-            return new Response("not found", { status: 404 });
+            return text("not found", 404);
         if (route === "GET /oauth/consents") {
             if (options.connectedAppsPage)
-                return new Response(null, { status: 302, headers: { location: options.connectedAppsPage } });
+                return redirect(options.connectedAppsPage);
             if (!person)
-                return new Response("sign in to see your connected apps", { status: 401, headers: PRIVATE });
+                return text("sign in to see your connected apps", 401);
             return html(connectedAppsHtml(locale, await list(person)), 200);
         }
         if (route === "GET /oauth/consents/data") {
             if (!person)
-                return Response.json({ consents: [] }, { status: 401, headers: PRIVATE });
-            return Response.json({ consents: await list(person) }, { headers: PRIVATE });
+                return json({ consents: [] }, 401);
+            return json({ consents: await list(person) });
         }
         if (route === "POST /oauth/consents/revoke") {
             if (!person)
-                return new Response("sign in to revoke a connection", { status: 401 });
-            const id = new URLSearchParams(await request.text()).get("consent_id");
+                return text("sign in to revoke a connection", 401);
+            const body = await readBody(request);
+            const id = new URLSearchParams(body).get("consent_id");
             if (!id)
-                return new Response("invalid consent id", { status: 400 });
+                return text("invalid consent id", 400);
             if (!await revoke(person, id))
-                return new Response("consent not found", { status: 404 });
-            return new Response(null, { status: 303, headers: { location: "/oauth/consents" } });
+                return text("consent not found", 404);
+            return redirect("/oauth/consents", 303);
         }
-        return new Response("not found", { status: 404 });
+        return text("not found", 404);
     };
 }
-// ---- the pages a service without Admin shows: Admin is an optional subpath (ADR-0032 decision 13), OAuth is not tied to it
-/** A form's redirect is held to `form-action` too, so the client's callback origin is allowed. */
-function html(body, status, redirectUri) {
-    const callback = redirectUri && URL.canParse(redirectUri) ? new URL(redirectUri) : null;
-    const action = callback ? `'self' ${callback.origin === "null" ? callback.protocol : callback.origin}` : "'self'";
+function html(body, status) {
     return new Response(body, {
         status,
         headers: {
             ...PRIVATE, "content-type": "text/html; charset=UTF-8", "referrer-policy": "same-origin", "x-content-type-options": "nosniff", "x-frame-options": "DENY",
-            "content-security-policy": `default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; form-action ${action}; frame-ancestors 'none'; base-uri 'none'`,
+            "content-security-policy": "default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'",
         },
     });
 }
@@ -112,7 +86,6 @@ function consentHtml(l, model) {
     if (!model)
         return page(l, t.title, `<p>${t.eyebrow}</p><h1>${t.invalid}</h1><p>${t.invalidBody}</p>`);
     const client = esc(model.clientName);
-    // where the answer goes and what is asked, so a look-alike client name cannot hide either
     const host = URL.canParse(model.redirectUri) ? new URL(model.redirectUri).host || new URL(model.redirectUri).protocol : model.redirectUri;
     return page(l, t.title, `<p>${t.eyebrow}</p><h1>${t.heading(client)}</h1><p>${t.body(client)}</p>` +
         `<p>${t.returnsTo} <code>${esc(host)}</code></p><p>${t.scopes}</p><ul>${model.scopes.map((sc) => `<li><code>${esc(sc)}</code></li>`).join("")}</ul><form method="post" action="/oauth/consent">` +
@@ -125,4 +98,3 @@ function connectedAppsHtml(l, consents) {
         `<input type="hidden" name="consent_id" value="${esc(c.id)}"/><button type="submit">${t.revoke}</button></form></section>`).join("");
     return page(l, t.apps, `<h1>${t.apps}</h1><p>${t.appsBody}</p>${apps}`);
 }
-//# sourceMappingURL=createAuthRoutes.js.map

package/dist/auth/hardening.d.ts

@@ -0,0 +1,24 @@
+import type { BetterAuthOptions } from "better-auth/types";
+/** Wrap the app's auth handler call with the current Worker's ctx.waitUntil.bind(ctx). Concurrent requests stay isolated. */
+export declare function withAuthTasks<T>(waitUntil: (task: Promise<unknown>) => void, run: () => T): T;
+export declare function retainAuthTask(task: Promise<unknown>): void;
+/** Keyed HMAC prevents enumeration of the six-digit OTP space after a database leak. */
+export declare function hashEmailOtp(secret: string, otp: string): Promise<string>;
+/** Never default to a client-controlled X-Forwarded-For. The host must overwrite the configured headers. */
+export declare function authHardening({ ipAddressHeaders, baseURL, errorURL }: {
+    ipAddressHeaders: readonly string[];
+    baseURL: string;
+    errorURL?: string;
+}): Pick<BetterAuthOptions, "advanced" | "rateLimit" | "onAPIError">;
+export type AuthHookContext = {
+    path: string;
+    params?: Readonly<Record<string, unknown>>;
+} | null;
+/** Accept the provider-owned profile only on explicitly trusted callbacks, never sign-up/update JSON. */
+export declare function guardGithubLogin(user: Readonly<Record<string, unknown>>, ctx: AuthHookContext, trustedProviders?: readonly string[]): {
+    data: {
+        githubLogin: null;
+    };
+} | undefined;
+/** First-deploy facade: failed setup never falls back to an anonymous/successful auth response. */
+export declare const authSetupIncomplete: () => Response;

package/dist/auth/hardening.js

@@ -0,0 +1,33 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const retention = new AsyncLocalStorage();
+export function withAuthTasks(waitUntil, run) { return retention.run(waitUntil, run); }
+export function retainAuthTask(task) {
+    const settled = task.catch(() => { console.error("[mantle auth] background task failed"); });
+    retention.getStore()?.(settled);
+}
+export async function hashEmailOtp(secret, otp) {
+    if (!secret)
+        throw new Error("AUTH_SECRET is required for OTP hashing.");
+    const bytes = new TextEncoder(), key = await crypto.subtle.importKey("raw", bytes.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, bytes.encode(otp)));
+    return btoa(String.fromCharCode(...mac)).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}
+export function authHardening({ ipAddressHeaders, baseURL, errorURL = "/" }) {
+    const headers = ipAddressHeaders.map(h => h.trim()).filter(Boolean);
+    if (!headers.length || headers.some(h => !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(h)))
+        throw new Error("ipAddressHeaders must name host-trusted ingress headers.");
+    const target = new URL(errorURL, baseURL);
+    if (target.origin !== new URL(baseURL).origin)
+        throw new Error("Auth errorURL must be same-origin.");
+    return { advanced: { ipAddress: { ipAddressHeaders: headers }, backgroundTasks: { handler: retainAuthTask } },
+        rateLimit: { enabled: true, storage: "database" }, onAPIError: { errorURL: `${target.pathname}${target.search}` } };
+}
+export function guardGithubLogin(user, ctx, trustedProviders = ["github"]) {
+    if (!("githubLogin" in user))
+        return;
+    const provider = ctx?.path === "/callback/:id" ? ctx.params?.id : null;
+    if (typeof provider === "string" && trustedProviders.includes(provider))
+        return;
+    return { data: { githubLogin: null } };
+}
+export const authSetupIncomplete = () => Response.json({ error: { code: "SERVICE_UNAVAILABLE", message: "Authentication setup is incomplete.", path: "auth" } }, { status: 503, headers: { "cache-control": "no-store", "retry-after": "60" } });

package/dist/auth/identity.d.ts

@@ -0,0 +1,121 @@
+/** Optional identity operations. Better Auth owns access control, writes and user hooks. */
+import { type AuthInstance } from "./caller.js";
+import { type Caller, type Postgres, type Unsafe } from "../kernel/contracts.js";
+import type { Dialect } from "../kernel/dialect/common.js";
+import { type Reader } from "../kernel/driver/d1.js";
+type User = {
+    id: string;
+    email: string;
+    name: string;
+    role?: string | null;
+    githubLogin?: string | null;
+    emailVerified: boolean | number;
+    createdAt: string | Date;
+};
+type Api = {
+    listUsers(input: {
+        headers: Headers;
+        query: Record<string, unknown>;
+    }): Promise<{
+        users: User[];
+        total: number;
+    }>;
+    setRole(input: {
+        headers: Headers;
+        body: {
+            userId: string;
+            role: never;
+        };
+    }): Promise<unknown>;
+    createUser(input: {
+        headers: Headers;
+        body: {
+            email: string;
+            name: string;
+            role: never;
+        };
+    }): Promise<{
+        user: User;
+    }>;
+    removeUser(input: {
+        headers: Headers;
+        body: {
+            userId: string;
+        };
+    }): Promise<unknown>;
+    userHasPermission(input: {
+        headers: Headers;
+        body: {
+            permissions: {
+                user: ("list" | "delete")[];
+            };
+        };
+    }): Promise<{
+        success: boolean;
+    }>;
+};
+/** Requires Better Auth's official admin plugin. Every API receives the request's headers. */
+export interface IdentityAuth extends AuthInstance {
+    readonly api: AuthInstance["api"] & Api;
+}
+type Read = (sql: string, values: unknown[]) => PromiseLike<any[]>;
+type Member = {
+    id: string;
+    email: string;
+    name: string;
+    role: string | null;
+    githubLogin: string | null;
+    emailVerified: boolean;
+    createdAt: Date;
+};
+declare function directory(auth: IdentityAuth, _caller: Caller, headers: Headers, d: Dialect, read: Read): {
+    adminRoles: string[];
+    listUsers(): Promise<Member[]>;
+    listMembers({ search, limit, cursor, cursorDirection }?: {
+        search?: string;
+        limit?: number;
+        cursor?: string;
+        cursorDirection?: "forward" | "backward";
+    }): Promise<{
+        items: Member[];
+        previousCursor: string | null;
+        nextCursor: string | null;
+    }>;
+    setUserRole(id: string, role: string | readonly string[] | null): Promise<boolean>;
+    inviteUser(email: string, role?: string): Promise<{
+        kind: "created";
+        id: string;
+    } | {
+        kind: "exists";
+        id: string;
+    }>;
+    revokeInvite(id: string): Promise<boolean>;
+    deleteUser: (id: string) => Promise<boolean>;
+};
+export type IdentityDirectory = ReturnType<typeof directory>;
+export declare const d1Identity: (db: Reader, auth: IdentityAuth, caller: Caller, headers: Headers) => IdentityDirectory;
+export declare const postgresIdentity: (db: Unsafe, auth: IdentityAuth, caller: Caller, headers: Headers) => IdentityDirectory;
+/**
+ * Server-side reads of Better Auth users for code without a session (cron, system callers): no SQL against Better Auth's
+ * tables, each instance's own table mapping, banned users excluded. Read-only; writes stay with the caller-bound directory.
+ */
+export declare function readIdentity(auth: AuthInstance): {
+    /** The active user with this id, or null. */
+    user: (id: string) => Promise<Member | null>;
+    /** Active users in the admin layer (`adminRoles` and `adminUserIds`). ponytail: reads up to 10,000 per role; page it if an app has more admins. */
+    admins: () => Promise<Member[]>;
+};
+export type BootstrapRule = {
+    match: "email" | "github-login";
+    value: string;
+};
+type BootstrapUser = {
+    id: string;
+    email?: string | null;
+    githubLogin?: string | null;
+    emailVerified?: boolean;
+};
+type BootstrapAuth = Pick<AuthInstance, "options"> | (() => Pick<AuthInstance, "options">);
+export declare function d1BootstrapAdmin(db: Reader, rule: BootstrapRule, auth: BootstrapAuth): (user: BootstrapUser) => Promise<void>;
+export declare function postgresBootstrapAdmin(db: Postgres, rule: BootstrapRule, source: BootstrapAuth): (user: BootstrapUser) => Promise<void>;
+export {};