@aotter/mantle 0.2.0-alpha.6 → 0.2.0-alpha.7

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,154 @@
+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);
+/** 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 const userOf = (caller) => users.get(caller);
+/** @deprecated Use `userOf`; it covers every credential, not only sessions. */
+export const sessionUserOf = userOf;
+/** The admin plugin's ban, lapsed once `banExpires` has passed (as the plugin reads it at sign-in). */
+export const isBanned = (user) => !!user.banned && (user.banExpires == null || new Date(user.banExpires).getTime() > Date.now());
+/** Better Auth owns the role model; absence of its admin plugin grants no admin layer. */
+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" };
+}
+/**
+ * `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 function authLoader(load, cookiePrefix = "better-auth") {
+    let instance;
+    return {
+        cookiePrefix,
+        get: () => instance ??= load().then((auth) => {
+            // Better Auth's getSessionCookie looks the cookie up by prefix only: any other spelling would make every signed-in user anonymous.
+            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");
+    }
+}
+/** All credentials read current authority from the same Better Auth user record. */
+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;
+}
+/**
+ * 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 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(instance).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.");
+    // With no Cookie header at all getSessionCookie returns null: skip even loading the helper.
+    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;
+    // Only an application-classified read may use Better Auth's bounded signed snapshot. KV remains primary-guarded.
+    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) {
+        // disableCookieCache bypasses browser cookies, not KV. Only mirrors need a primary authority re-read.
+        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" };
+    // Never let a stale secondary snapshot extend an already-expired primary session before the check above.
+    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/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,40 @@
+/** Optional app-owned Better Auth configuration; no Better Auth runtime import. */
+import { AsyncLocalStorage } from "node:async_hooks";
+const retention = new AsyncLocalStorage();
+/** Wrap the app's auth handler call with the current Worker's ctx.waitUntil.bind(ctx). Concurrent requests stay isolated. */
+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);
+}
+/** Keyed HMAC prevents enumeration of the six-digit OTP space after a database leak. */
+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(/=+$/, "");
+}
+/** Never default to a client-controlled X-Forwarded-For. The host must overwrite the configured headers. */
+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 } },
+        // Shared across isolates; Better Auth's defaults and plugin rules (e.g. 3/min per OTP path) set the limits.
+        rateLimit: { enabled: true, storage: "database" }, onAPIError: { errorURL: `${target.pathname}${target.search}` } };
+}
+/** Accept the provider-owned profile only on explicitly trusted callbacks, never sign-up/update JSON. */
+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 } };
+}
+/** First-deploy facade: failed setup never falls back to an anonymous/successful auth response. */
+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 } 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: Postgres, 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 {};

package/dist/auth/identity.js

@@ -0,0 +1,203 @@
+/** Optional identity operations. Better Auth owns access control, writes and user hooks. */
+import { adminOptionsOf, isBanned } from "./caller.js";
+import { authNames } from "./adapter.js";
+import { APIError } from "@better-auth/core/error";
+import { ContractError } from "../kernel/contracts.js";
+import { adminLayerOf, rolesFrom } from "../kernel/user-caller.js";
+import * as sqlite from "../kernel/dialect/sqlite.js";
+import * as postgres from "../kernel/dialect/postgres.js";
+import { read as d1Read } from "../kernel/driver/d1.js";
+import { read as pgRead, transaction } from "../kernel/driver/postgres.js";
+const invalid = (message) => new ContractError("INPUT_VALIDATION_FAILED", message, "identity");
+const project = ({ id, email, name, role, githubLogin, emailVerified, createdAt }) => ({ id, email, name, role: role ?? null, githubLogin: githubLogin ?? null, emailVerified: Boolean(emailVerified), createdAt: new Date(createdAt) });
+const literal = (value) => "'" + value.replaceAll("'", "''") + "'";
+const adminSql = (d, auth) => {
+    const { column } = authNames(auth.options), { adminRoles, adminUserIds } = adminOptionsOf(auth);
+    const col = (field) => column("user", field);
+    return '(' + [...adminRoles.map(role => `${d === sqlite.dialect ? "instr" : "strpos"}(',' || COALESCE(${col("role")}, '') || ',', ${literal(',' + role + ',')}) > 0`), ...adminUserIds.map(id => `${col("id")} = ${literal(id)}`), 'FALSE'].join(' OR ') + ')';
+};
+/** Translate Better Auth errors at the selected transport boundary, retaining its status and code. */
+async function api(run) {
+    try {
+        return await run();
+    }
+    catch (error) {
+        if (error instanceof APIError)
+            throw new ContractError(error.body?.code ?? "AUTH_DENIED", error.message, "identity", { status: error.statusCode, cause: error });
+        throw error;
+    }
+}
+function directory(auth, _caller, headers, d, read) {
+    const options = adminOptionsOf(auth), roles = options.adminRoles, privileged = adminSql(d, auth);
+    const { table, column, has } = authNames(auth.options), col = (field) => column("user", field);
+    const createdAt = d === sqlite.dialect ? col("createdAt") : postgres.wireTimestamp(col("createdAt")).join("");
+    const grantRole = (role = roles[0]) => { if (!role || !roles.includes(role))
+        throw invalid("Role must be configured in Better Auth adminRoles."); return role; };
+    const allowed = async (action) => {
+        if (!(await api(() => auth.api.userHasPermission({ headers, body: { permissions: { user: [action] } } }))).success)
+            throw new ContractError("AUTH_DENIED", `Requires Better Auth user:${action}.`, "identity");
+    };
+    const context = async () => await auth.$context;
+    const find = async (id) => (await context()).adapter.findOne({ model: "user", where: [{ field: "id", value: id }] });
+    const set = async (id, role) => {
+        try {
+            await api(() => auth.api.setRole({ headers, body: { userId: id, role: [...(role.length ? role : rolesFrom(options.defaultRole))] } }));
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ContractError && error.code === "USER_NOT_FOUND")
+                return false;
+            throw error;
+        }
+    };
+    const remove = async (id) => {
+        try {
+            const found = await find(id);
+            // Better Auth deletes sessions and accounts before the adapter refuses the last admin row; refuse first.
+            if (found && adminLayerOf(found, options) && !(await read(`SELECT 1 FROM ${table("user")} WHERE ${privileged} AND ${col("id")} <> ${literal(id)} AND COALESCE(${col("banned")}, ${d === sqlite.dialect ? "0" : "FALSE"}) = ${d === sqlite.dialect ? "0" : "FALSE"} LIMIT 1`, [])).length)
+                throw new ContractError("CONFLICT", "This is the last admin; promote another admin before removing this one.", "identity", { status: 409 });
+            await api(() => auth.api.removeUser({ headers, body: { userId: id } }));
+            // The admin plugin removes accounts and sessions, but email-OTP proofs are keyed by email.
+            if (found)
+                await (await context()).adapter.deleteMany({ model: "verification", where: [{ field: "identifier", operator: "in", value: ["sign-in", "email-verification", "forget-password"].map(t => `${t}-otp-${found.email.toLowerCase()}`) }] });
+            return true;
+        }
+        catch (error) {
+            if (error instanceof ContractError && error.code === "USER_NOT_FOUND")
+                return false;
+            throw error;
+        }
+    };
+    return {
+        adminRoles: roles,
+        async listUsers() {
+            const query = { sortBy: "createdAt", sortDirection: "asc" };
+            let { users, total } = await api(() => auth.api.listUsers({ headers, query }));
+            if (users.length < total)
+                ({ users } = await api(() => auth.api.listUsers({ headers, query: { ...query, limit: total } })));
+            return users.filter(user => adminLayerOf(user, options)).map(project);
+        },
+        async listMembers({ search = "", limit = 50, cursor, cursorDirection = "forward" } = {}) {
+            await allowed("list");
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100 || search.length > 200 || !["forward", "backward"].includes(cursorDirection))
+                throw invalid("Invalid member page options.");
+            const term = search.trim().toLowerCase(), scope = JSON.stringify(["members", term]);
+            let key;
+            if (cursor) {
+                try {
+                    const v = JSON.parse(decodeURIComponent(cursor.slice(2)));
+                    if (!cursor.startsWith("m:") || !Array.isArray(v) || v.length !== 3 || v[0] !== scope || typeof v[1] !== "string" || !Number.isFinite(Date.parse(v[1])) || typeof v[2] !== "string" || !v[2])
+                        throw 0;
+                    key = [v[1], v[2]];
+                }
+                catch {
+                    throw invalid("Invalid member cursor for this search.");
+                }
+            }
+            const values = [], bind = (v) => (values.push(v), d.param(values.length));
+            const conditions = [`NOT ${privileged}`];
+            if (term) {
+                const like = bind(`%${d.escapeLike(term)}%`);
+                conditions.push(`(${[`CAST(${col("id")} AS text)`, col("name"), col("email")].map(c => `${c} ${d.like(true)} ${like}${d.likeEscape}`).join(" OR ")})`);
+            }
+            const backward = cursorDirection === "backward", order = backward ? "DESC" : "ASC", op = backward ? "<" : ">";
+            if (key) {
+                const time = d.cast(bind(key[0]), "timestamptz"), id = bind(key[1]);
+                conditions.push(`(${col("createdAt")} ${op} ${time} OR (${col("createdAt")} = ${time} AND ${col("id")} ${op} ${id}))`);
+            }
+            const rows = await read(`SELECT ${["id", "email", "name", "role", "githubLogin", "emailVerified"].map(field => `${has("user", field) ? col(field) : "NULL"} AS "${field}"`).join(",")},${createdAt} AS "createdAt" FROM ${table("user")} WHERE ${conditions.join(" AND ")} ORDER BY ${col("createdAt")} ${order},${col("id")} ${order} LIMIT ${limit + 1}`, values);
+            const page = rows.slice(0, limit);
+            if (backward)
+                page.reverse();
+            const encode = (row) => `m:${encodeURIComponent(JSON.stringify([scope, typeof row.createdAt === "string" ? row.createdAt : row.createdAt.toISOString(), row.id]))}`;
+            return { items: page.map(project), previousCursor: (backward ? rows.length > limit : !!key) && page[0] ? encode(page[0]) : null, nextCursor: (backward ? !!key : rows.length > limit) && page.at(-1) ? encode(page.at(-1)) : null };
+        },
+        async setUserRole(id, role) {
+            const user = await find(id), current = rolesFrom(user?.role);
+            return set(id, role === null ? current.filter(name => !roles.includes(name)) : typeof role === "string" ? [...new Set([...current, grantRole(role)])] : role);
+        },
+        async inviteUser(email, role) {
+            const adminRole = grantRole(role), normalized = email.trim().toLowerCase();
+            if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(normalized))
+                throw invalid("Invalid invitation email.");
+            try {
+                const { user } = await api(() => auth.api.createUser({ headers, body: { email: normalized, name: normalized.split("@")[0], role: [adminRole] } }));
+                return { kind: "created", id: user.id };
+            }
+            catch (error) {
+                if (!(error instanceof ContractError) || error.code !== "USER_ALREADY_EXISTS_USE_ANOTHER_EMAIL")
+                    throw error;
+                const { users: [found] } = await api(() => auth.api.listUsers({ headers, query: { filterField: "email", filterValue: normalized, limit: 1 } }));
+                if (!found)
+                    throw error;
+                if (!found.emailVerified)
+                    throw new ContractError("AUTH_DENIED", "The existing account must verify its email before receiving admin access.", "identity:invitation");
+                await set(found.id, [...new Set([...rolesFrom(found.role), adminRole])]);
+                return { kind: "exists", id: found.id };
+            }
+        },
+        async revokeInvite(id) {
+            await allowed("delete");
+            const user = await find(id);
+            if (!user || !adminLayerOf(user, options) || user.emailVerified || await (await context()).adapter.findOne({ model: "account", where: [{ field: "userId", value: id }] }))
+                return false;
+            return remove(id);
+        },
+        deleteUser: remove,
+    };
+}
+export const d1Identity = (db, auth, caller, headers) => directory(auth, caller, headers, sqlite.dialect, (sql, v) => d1Read(db, sql, v));
+export const postgresIdentity = (db, auth, caller, headers) => directory(auth, caller, headers, postgres.dialect, (sql, v) => pgRead(db, sql, v));
+/**
+ * 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 function readIdentity(auth) {
+    const options = adminOptionsOf(auth), context = async () => await auth.$context;
+    const active = (user) => user && !isBanned(user) ? project(user) : null;
+    return {
+        /** The active user with this id, or null. */
+        user: async (id) => active(await (await context()).internalAdapter.findUserById(id)),
+        /** 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: async () => {
+            const { adapter } = await context();
+            const found = new Map();
+            for (const role of options.adminRoles)
+                for (const user of await adapter.findMany({ model: "user", where: [{ field: "role", operator: "contains", value: role }], limit: 10_000 }))
+                    found.set(user.id, user);
+            if (options.adminUserIds.length)
+                for (const user of await adapter.findMany({ model: "user", where: [{ field: "id", operator: "in", value: [...options.adminUserIds] }], limit: 10_000 }))
+                    found.set(user.id, user);
+            return [...found.values()].filter(user => adminLayerOf(user, options)).map(active).filter((user) => !!user);
+        },
+    };
+}
+const matches = (rule, user) => (rule.match === "email" ? user.emailVerified === true ? user.email : null : user.githubLogin)?.trim().toLowerCase() === rule.value.trim().toLowerCase();
+const promote = (d, param, source) => {
+    const auth = typeof source === "function" ? source() : source, { adminRoles: roles } = adminOptionsOf(auth);
+    if (!roles[0])
+        throw new ContractError("AUTH_CONFIGURATION_ERROR", "Bootstrap requires Better Auth adminRoles.", "identity");
+    const { table, column } = authNames(auth.options), role = column("user", "role"), id = column("user", "id");
+    return `UPDATE ${table("user")} SET ${role}=${literal(roles[0])} || CASE WHEN COALESCE(${role}, '') = '' THEN '' ELSE ',' || ${role} END WHERE ${id}=${param} AND NOT EXISTS (SELECT 1 FROM ${table("user")} WHERE ${adminSql(d, auth)}) RETURNING ${id}`;
+};
+/** First-admin bootstrap has no authorized session for setRole; one conditional write elects a single admin. */
+function bootstrap(rule, update) {
+    if (!rule.value.trim())
+        throw invalid("Bootstrap target cannot be empty.");
+    return async (user) => {
+        if (!matches(rule, user))
+            return;
+        if (!(await update(user.id)).length)
+            console.warn("[mantle bootstrap] promotion blocked: admin already exists.");
+    };
+}
+export function d1BootstrapAdmin(db, rule, auth) {
+    return bootstrap(rule, id => d1Read(db, promote(sqlite.dialect, "?", auth), [id]));
+}
+export function postgresBootstrapAdmin(db, rule, source) {
+    return bootstrap(rule, id => transaction(db, async (tx) => {
+        const auth = typeof source === "function" ? source() : source;
+        await tx.unsafe("SELECT pg_advisory_xact_lock(hashtext($1))", [authNames(auth.options).table("user")]);
+        return tx.unsafe(promote(postgres.dialect, "$1", auth), [id]);
+    }, { isolation: "read committed" }, "identity/bootstrap"));
+}