@aotter/mantle 0.1.5-alpha.1 → 0.2.0-alpha.10

package/dist/auth/adapter.js

@@ -0,0 +1,288 @@
+/**
+ * Better Auth `database` adapters on the same native handle as the data layer: a Cloudflare D1 binding, or PostgreSQL through Bun.SQL or postgres.js.
+ * No Kysely. Rules (where semantics, joins, field/model mapping, value transforms) come from Better Auth's own
+ * `createAdapterFactory`; this file only turns its already-normalised calls into parameterised SQL.
+ * `consumeOne` and `incrementOne` are single statements: D1 has no transactions, and they guard OTP consumption and
+ * attempt counting.
+ */
+import { createAdapterFactory } from "@better-auth/core/db/adapter";
+import { APIError } from "@better-auth/core/error";
+import { getAuthTables } from "@better-auth/core/db";
+import { resourceSeeds } from "./resource-seeds.js";
+import { ContractError } from "../kernel/contracts.js";
+import { adminOptionsOf } from "./caller.js";
+import * as postgres from "../kernel/dialect/postgres.js";
+import * as sqlite from "../kernel/dialect/sqlite.js";
+import * as bunSql from "../kernel/driver/postgres.js";
+import { condition as spell } from "../kernel/where.js";
+const nativeReaders = new WeakMap();
+/** Selected auth queries share this adapter's handle, dialect and Better Auth's physical model/field mapping. */
+/** Better Auth's table and column names for these options (modelName/fieldName mapping); needs no database. */
+export function authNames(options) {
+    const schema = getAuthTables(options);
+    return {
+        table: (model) => postgres.ident(schema[model].modelName),
+        column: (model, field) => postgres.ident(schema[model]?.fields[field]?.fieldName ?? field),
+        has: (model, field) => field === "id" || !!schema[model]?.fields[field],
+    };
+}
+export function nativeAuthRead(options) {
+    const native = options.database && nativeReaders.get(options.database);
+    if (!native)
+        throw new ContractError("AUTH_CONFIGURATION_ERROR", "OAuth requires Mantle's native auth database adapter.", "auth:database");
+    return { ...native, ...authNames(options) };
+}
+function customAdapter(d, exec, seed, insertOnly = false, options) {
+    const { ident } = d;
+    return ({ getFieldName, schema, getDefaultModelName }) => {
+        const condition = (bind, modelKey, w) => {
+            const col = ident(getFieldName({ model: modelKey, field: w.field }));
+            const { value, operator } = w;
+            const fold = w.mode === "insensitive" && (typeof value === "string" || (Array.isArray(value) && value.every(v => typeof v === "string")));
+            if (operator === "contains" || operator === "starts_with" || operator === "ends_with") {
+                const text = d.escapeLike(String(value));
+                return spell(d, col, "like", operator === "contains" ? `%${text}%` : operator === "starts_with" ? `${text}%` : `%${text}`, bind, fold);
+            }
+            return spell(d, col, operator === "not_in" ? "notIn" : operator, value, bind, fold);
+        };
+        /** Builds one statement (its own parameters) and runs it. `where` is `WHERE (and...) AND (or...)`, the Kysely adapter's grouping; empty without conditions. */
+        const run = (build, protectAdmin = false) => {
+            const values = [];
+            const bind = (value) => (values.push(value === undefined ? null : value), d.param(values.length));
+            const where = (modelKey, conditions, extra) => {
+                const group = (connector) => {
+                    const parts = (conditions ?? []).filter(w => (w.connector === "OR" ? "OR" : "AND") === connector).map(w => condition(bind, modelKey, w));
+                    return parts.length ? `(${parts.join(` ${connector} `)})` : null;
+                };
+                const parts = [group("AND"), group("OR"), extra ?? null].filter(Boolean);
+                return parts.length ? ` WHERE ${parts.join(" AND ")}` : "";
+            };
+            return exec(build({ bind, where }), values, protectAdmin);
+        };
+        const idOf = (modelKey) => ident(getFieldName({ model: modelKey, field: "id" }));
+        /** The WHERE plus `<id> IN (SELECT <id> FROM t WHERE ... LIMIT 1)`: the statement touches at most one row. */
+        const oneRow = (s, table, modelKey, where) => s.where(modelKey, where, `${idOf(modelKey)} IN (SELECT ${idOf(modelKey)} FROM ${ident(table)}${s.where(modelKey, where)} LIMIT 1)`);
+        /** The one row a `RETURNING *` statement changed, else null. */
+        const one = async (build) => ((await run(s => `${build(s)} RETURNING *`)).rows[0] ?? null);
+        /** The columns a write gives (an `undefined` is no value). */
+        const cols = (values) => Object.entries(values).filter(([, v]) => v !== undefined);
+        const assign = (s, values, increment = {}) => [...cols(values).map(([c, v]) => `${ident(c)} = ${s.bind(v)}`), ...Object.entries(increment).map(([c, n]) => `${ident(c)} = ${ident(c)} + ${s.bind(n)}`)].join(", ");
+        const { adminRoles: roles, adminUserIds } = options ? adminOptionsOf({ options }) : { adminRoles: [], adminUserIds: [] };
+        const holdsAdmin = (role) => typeof role === "string" && role.split(",").some(role => roles.includes(role));
+        const field = (name) => getFieldName({ model: "user", field: name });
+        const protects = (modelKey, values) => modelKey === "user" && (roles.length > 0 || adminUserIds.length > 0) &&
+            (!values || values[field("banned")] === true || values[field("banned")] === 1 || Object.hasOwn(values, field("role")) && !holdsAdmin(values[field("role")]));
+        const membership = (s, alias) => '(' + [...roles.map(role => `${d === sqlite ? "instr" : "strpos"}(',' || COALESCE(${alias}.${ident(field("role"))}, '') || ',', ${s.bind(',' + role + ',')}) > 0`), d === sqlite ? "0" : "FALSE"].join(' OR ') + ')';
+        const allowlisted = (s, alias) => `(${[...adminUserIds.map(id => `${alias}.${idOf("user")} = ${s.bind(id)}`), d === sqlite ? "0" : "FALSE"].join(" OR ")})`;
+        const administrator = (s, alias) => `(${membership(s, alias)} OR ${allowlisted(s, alias)})`;
+        const lastAdminGuard = (s, model, keepsAllowlisted = false) => {
+            const table = ident(model), other = '"_mantle_other_admin"', no = d === sqlite ? '0' : 'FALSE';
+            return `(${keepsAllowlisted ? `${allowlisted(s, table)} OR ` : ""}NOT ${administrator(s, table)} OR EXISTS (SELECT 1 FROM ${table} ${other} WHERE ${administrator(s, other)} AND ${other}.${idOf("user")} <> ${table}.${idOf("user")} AND COALESCE(${other}.${ident(field("banned"))}, ${no}) = ${no}))`;
+        };
+        const mutation = async (model, modelKey, where, values) => {
+            const protect = protects(modelKey, values);
+            const keepsAllowlisted = protect && !!values && values[field("banned")] !== true && values[field("banned")] !== 1;
+            if (protect && (where.length !== 1 || where[0].field !== field("id") || where[0].operator && where[0].operator !== "eq"))
+                throw new APIError("FORBIDDEN", { code: "AUTH_DENIED", message: "Destructive admin identity writes require one user id." });
+            const result = await run(s => `${values ? `UPDATE ${ident(model)} SET ${assign(s, values)}` : `DELETE FROM ${ident(model)}`}${s.where(modelKey, where, protect ? lastAdminGuard(s, model, keepsAllowlisted) : undefined)} RETURNING *`, protect);
+            if (protect && !result.changes && (await run(s => `SELECT ${idOf(modelKey)} FROM ${ident(model)}${s.where(modelKey, where, `NOT ${lastAdminGuard(s, model, keepsAllowlisted)}`)} LIMIT 1`)).rows.length)
+                throw new APIError("CONFLICT", { code: "CONFLICT", message: "This is the last admin; promote another admin before removing or banning this one." });
+            return result;
+        };
+        const deleteMany = async ({ model, modelKey = model, where }) => (await mutation(model, modelKey, where)).changes;
+        /** Joined rows come back as flat `__j<i>__<column>` aliases; fold them into `row[joinModel]` (object or array). */
+        const joinColumns = (join) => Object.entries(join).map(([model, config]) => {
+            const fields = schema[config.modelKey ?? getDefaultModelName(model)]?.fields ?? {};
+            return [...new Set(["id", ...Object.entries(fields).map(([field, attr]) => attr.fieldName || field)])];
+        });
+        const foldJoins = (rows, join, idColumn) => {
+            const entries = Object.entries(join);
+            const grouped = new Map();
+            rows.forEach((raw, index) => {
+                const main = {};
+                const joined = entries.map(() => ({}));
+                for (const [key, value] of Object.entries(raw)) {
+                    const m = /^__j(\d+)__(.*)$/s.exec(key);
+                    if (m)
+                        joined[Number(m[1])][m[2]] = value;
+                    else
+                        main[key] = value;
+                }
+                const key = main[idColumn] ?? index;
+                let entry = grouped.get(key);
+                if (!entry) {
+                    entry = { ...main };
+                    entries.forEach(([model, config]) => (entry[model] = config.relation === "one-to-one" ? null : []));
+                    grouped.set(key, entry);
+                }
+                entries.forEach(([model, config], i) => {
+                    const obj = joined[i];
+                    if (!Object.values(obj).some(v => v !== null && v !== undefined))
+                        return;
+                    if (config.relation === "one-to-one")
+                        entry[model] = obj;
+                    else {
+                        const list = entry[model];
+                        if (!list.some(item => item.id !== undefined && item.id === obj.id))
+                            list.push(obj);
+                    }
+                });
+            });
+            return [...grouped.values()];
+        };
+        const select = async (model, modelKey, o) => {
+            const column = (field) => getFieldName({ model: modelKey, field });
+            const sortColumn = o.sortBy?.field ? ident(column(o.sortBy.field)) : null;
+            const order = (prefix = "") => (sortColumn ? ` ORDER BY ${prefix}${sortColumn} ${o.sortBy.direction === "desc" ? "DESC" : "ASC"}` : "");
+            // With a join the primary subquery also needs the id (rows fold by it), every join key and the sort column; they are dropped again below.
+            const wanted = o.select?.length ? o.select.map(column) : null;
+            const needed = o.join ? [column("id"), ...Object.values(o.join).map(c => c.on.from), ...(o.sortBy ? [column(o.sortBy.field)] : [])] : [];
+            const { rows } = await run(s => {
+                const list = wanted ? [...new Set([...wanted, ...needed])].map(ident).join(", ") : "*";
+                const paging = `${o.limit !== undefined ? ` LIMIT ${Math.trunc(o.limit)}` : ""}${o.offset ? ` OFFSET ${Math.trunc(o.offset)}` : ""}`;
+                const primary = `SELECT ${list} FROM ${ident(model)}${s.where(modelKey, o.where)}${order()}${paging}`;
+                if (!o.join)
+                    return primary;
+                const entries = Object.entries(o.join);
+                const names = joinColumns(o.join);
+                // The CTE is MATERIALIZED so an unordered LIMIT picks the same parents in both of its uses. One-to-many: number each parent's joined rows in SQL and keep the first `limit`, so only that many rows ever leave the database.
+                const joinSql = entries.map(([joined, c], i) => {
+                    const source = c.relation === "one-to-one" ? ident(joined)
+                        : `(SELECT *, ROW_NUMBER() OVER (PARTITION BY ${ident(c.on.to)} ORDER BY ${idOf(c.modelKey ?? getDefaultModelName(joined))}) AS "__rn" FROM ${ident(joined)} WHERE ${ident(c.on.to)} IN (SELECT ${ident(c.on.from)} FROM "primary"))`;
+                    return ` LEFT JOIN ${source} AS "j${i}" ON "j${i}".${ident(c.on.to)} = "primary".${ident(c.on.from)}${c.relation === "one-to-one" ? "" : ` AND "j${i}"."__rn" <= ${Math.trunc(c.limit ?? 100)}`}`;
+                }).join("");
+                const joinSelect = entries.flatMap((_, i) => names[i].map(c => `"j${i}".${ident(c)} AS ${ident(`__j${i}__${c}`)}`)).join(", ");
+                return `WITH "primary" AS MATERIALIZED (${primary}) SELECT "primary".*, ${joinSelect} FROM "primary"${joinSql}${order('"primary".')}`;
+            });
+            if (!o.join)
+                return rows;
+            const folded = foldJoins(rows, o.join, column("id"));
+            if (wanted)
+                for (const row of folded)
+                    for (const extra of needed)
+                        if (!wanted.includes(extra))
+                            delete row[extra];
+            return folded;
+        };
+        return {
+            async create({ data, model }) {
+                const given = cols(data);
+                const { rows } = await run(s => `INSERT INTO ${ident(model)}${given.length ? ` (${given.map(([c]) => ident(c)).join(", ")}) VALUES (${given.map(([, v]) => s.bind(v)).join(", ")})` : " DEFAULT VALUES"} ${insertOnly ? "ON CONFLICT DO NOTHING " : ""}RETURNING *`);
+                return rows[0];
+            },
+            async findOne({ model, modelKey = model, where, select: fields, join }) {
+                let row = (await select(model, modelKey, { where, select: fields, limit: 1, join }))[0] ?? null;
+                if (!row && modelKey === "oauthResource" && where?.length === 1 && where[0].field === getFieldName({ model: modelKey, field: "identifier" }) && (!where[0].operator || where[0].operator === "eq") && await seed(where[0].value)) {
+                    row = (await select(model, modelKey, { where, select: fields, limit: 1, join }))[0] ?? null;
+                }
+                return row;
+            },
+            async findMany({ model, modelKey = model, where, limit, select: fields, sortBy, offset, join }) {
+                return (await select(model, modelKey, { where, select: fields, limit, offset, sortBy, join }));
+            },
+            async update({ model, modelKey = model, where, update }) {
+                if (!where.length)
+                    return null;
+                return ((await mutation(model, modelKey, where, update)).rows[0] ?? null);
+            },
+            async updateMany({ model, modelKey = model, where, update }) {
+                return (await mutation(model, modelKey, where, update)).changes;
+            },
+            async delete(options) { await deleteMany(options); },
+            deleteMany,
+            async consumeOne({ model, modelKey = model, where }) {
+                return one(s => `DELETE FROM ${ident(model)}${oneRow(s, model, modelKey, where)}`);
+            },
+            async incrementOne({ model, modelKey = model, where, increment, set }) {
+                return one(s => `UPDATE ${ident(model)} SET ${assign(s, set ?? {}, increment)}${oneRow(s, model, modelKey, where)}`);
+            },
+            async count({ model, modelKey = model, where }) {
+                const { rows } = await run(s => `SELECT COUNT(*) AS "count" FROM ${ident(model)}${s.where(modelKey, where)}`);
+                return Number(rows[0].count);
+            },
+        };
+    };
+}
+function build(d, native, adapterId, adapterName, exec, transaction, options) {
+    const resources = new Map((options.plugins ?? []).flatMap(plugin => plugin.id === "oauth-provider" ? resourceSeeds(plugin.options).map(input => {
+        const resource = typeof input === "string" ? { identifier: input } : input;
+        return [resource.identifier, { resource, options: plugin.options }];
+    }) : []).reverse()); // first configured entry wins, as upstream insertOnly does
+    // ponytail: one seed per identifier per isolate (upstream seeds once per init); disable a configured resource rather than deleting it.
+    const seeded = new Set();
+    let writer;
+    const pending = new Map();
+    const seed = (identifier) => {
+        const configured = resources.get(identifier);
+        if (!configured || seeded.has(identifier))
+            return Promise.resolve(false);
+        let work = pending.get(identifier);
+        if (!work) {
+            work = (async () => {
+                const { resource, options: oauth } = configured;
+                // Match upstream identifier validation and seed row defaults.
+                let valid;
+                try {
+                    valid = oauth.identifierValidator ? !!(await oauth.identifierValidator(identifier)) : !new URL(identifier).hash;
+                }
+                catch {
+                    valid = false;
+                }
+                if (!valid)
+                    throw new APIError("INTERNAL_SERVER_ERROR", { code: "AUTH_CONFIGURATION_ERROR", message: "Configured OAuth resource identifier failed validation." });
+                const now = new Date();
+                const data = {
+                    identifier, name: resource.name ?? identifier,
+                    ...Object.fromEntries(["accessTokenTtl", "refreshTokenTtl", "signingKeyId", "allowedScopes", "customClaims", "metadata"].map(field => [field, resource[field] ?? null])),
+                    signingAlgorithm: resource.signingAlgorithm && ["EdDSA", "ES256", "ES512", "PS256", "RS256"].includes(resource.signingAlgorithm) ? resource.signingAlgorithm : null,
+                    dpopBoundAccessTokensRequired: resource.dpopBoundAccessTokensRequired ?? false, disabled: resource.disabled ?? false,
+                    policyVersion: 1, createdAt: now, updatedAt: now,
+                };
+                // The factory owns ID generation, field mapping and native date/JSON/boolean encoding, including for seeds.
+                writer ??= createAdapterFactory({ config, adapter: customAdapter(d, exec, async () => false, true) })(options);
+                await writer.create({ model: "oauthResource", data });
+                seeded.add(identifier);
+                return true;
+            })().finally(() => pending.delete(identifier));
+            pending.set(identifier, work);
+        }
+        return work;
+    };
+    const config = {
+        adapterId, adapterName, supportsBooleans: native, supportsDates: native, supportsJSON: native, supportsUUIDs: native, transaction,
+        // Bun.SQL returns int8/numeric as strings; a `number` field must reach Better Auth as a number (the rate limiter adds to `lastRequest`). Ids stay strings.
+        customTransformOutput: ({ data, fieldAttributes, field }) => (fieldAttributes.type === "number" && typeof data === "string" && field !== "id" && !fieldAttributes.references ? Number(data) : data),
+    };
+    const factory = createAdapterFactory({ config, adapter: customAdapter(d, exec, seed, false, options) });
+    // Both native adapters implement joins; Better Auth otherwise emulates each joined read with another statement.
+    return (options) => factory({ ...options, advanced: { ...options.advanced, database: { ...options.advanced?.database, joins: options.advanced?.database?.joins ?? true } } });
+}
+/** Cloudflare D1 (SQLite). D1 has no interactive transactions, so `transaction` is off and the atomic operations are single statements. */
+export function d1Adapter(db) {
+    const exec = async (text, values) => {
+        const { results, meta } = await db.prepare(text).bind(...values).all();
+        return { rows: results, changes: meta.changes };
+    };
+    const factory = (options) => build(sqlite, false, "d1", "Mantle D1 Adapter", exec, false, options)(options);
+    nativeReaders.set(factory, { exec, param: sqlite.param, now: ms => new Date(ms).toISOString() });
+    return factory;
+}
+/**
+ * PostgreSQL through Bun.SQL or postgres.js (the `Postgres` contract the data layer uses). Transactions use `begin`,
+ * which pins every statement to one connection. On Workers, create the postgres.js client per request (or per isolate
+ * with `max: 1`), as for the data layer.
+ */
+export function postgresAdapter(sql) {
+    const executor = (handle) => async (text, values, protectAdmin) => {
+        const run = async (tx) => {
+            if (protectAdmin)
+                await tx.unsafe("SELECT pg_advisory_xact_lock(1296125516,1)", []);
+            return bunSql.run(tx, text, values);
+        };
+        return protectAdmin && handle === sql ? sql.begin("read write", tx => run(tx)) : run(handle);
+    };
+    const make = (handle, transaction) => (options) => build(postgres, true, "postgres", "Mantle PostgreSQL Adapter", executor(handle), transaction, options)(options);
+    const factory = (options) => make(sql, async (cb) => sql.begin("read write", tx => cb(make(tx, false)(options))))(options);
+    nativeReaders.set(factory, { exec: executor(sql), param: postgres.param, now: postgres.now });
+    return factory;
+}

package/dist/auth/admin.d.ts

@@ -0,0 +1,3 @@
+import { type Caller } from "../kernel/contracts.js";
+/** Shared selected-boundary guard. Resolve fresh database authority only for Better Auth's raw admin endpoints. */
+export declare function guardAuthAdminRequest(request: Request, resolve: () => Caller | Promise<Caller>, basePath?: string): Promise<void>;

package/dist/auth/admin.js

@@ -0,0 +1,21 @@
+import { checkOrigin, isAdmin, deny, ContractError } from "../kernel/contracts.js";
+/** Shared selected-boundary guard. Resolve fresh database authority only for Better Auth's raw admin endpoints. */
+export async function guardAuthAdminRequest(request, resolve, basePath = "/api/auth") {
+    let path;
+    try {
+        path = decodeURIComponent(new URL(request.url).pathname).replace(/\/{2,}/g, "/");
+    }
+    catch { }
+    if (path === undefined || path.split("/").some(part => part === "." || part === ".."))
+        throw new ContractError("INPUT_VALIDATION_FAILED", "Malformed auth path.", "request:path");
+    const admin = `${basePath.replace(/\/+$/, "")}/admin`;
+    if (path !== admin && !path.startsWith(`${admin}/`))
+        return;
+    const caller = await resolve();
+    // Mantle policy: only the admin layer reaches Better Auth admin endpoints (oauth-provider's /admin/oauth2/* admits any
+    // session by default); Better Auth access control then decides each action.
+    // Any signed-in user may ask about their own permissions or end an impersonation.
+    const own = path === `${admin}/has-permission` || path === `${admin}/stop-impersonating`;
+    deny(caller, caller.kind === "user" && caller.credential === "session" && (own || isAdmin(caller)), "auth:admin");
+    checkOrigin(request, caller);
+}

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,155 @@
+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;
+        // Issuance uses the normalized auth context URL, not the raw origin-only baseURL option.
+        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.");
+    // 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" } });