@aotter/mantle-cloudflare 0.1.0-alpha.9 → 0.1.2-alpha.1

package/dist/auth/createAuth.js

@@ -1,4 +1,7 @@
+import { AsyncLocalStorage } from "node:async_hooks";
 import { betterAuth } from "better-auth";
+import { getMigrations } from "better-auth/db/migration";
+import { D1DatabaseDriver } from "../bindings/D1DatabaseDriver.js";
 import { createDpopReplayStore, enforceDpopBinding, isDpopBindingError, parseAccessTokenAuthorization, verifyJwsAccessToken, } from "better-auth/oauth2";
 import { admin, emailOTP, jwt, magicLink } from "better-auth/plugins";
 import { createAccessControl } from "better-auth/plugins/access";
@@ -8,8 +11,22 @@ import { splitSetCookieHeader } from "better-auth/cookies";
 import { oauthProvider } from "@better-auth/oauth-provider";
 import { mcp } from "@better-auth/mcp";
 import { cimd } from "@better-auth/cimd";
-import { decodeMemberCursor, encodeMemberCursor } from "@aotter/mantle-admin";
+import { decodeMemberCursor, encodeMemberCursor, } from "@aotter/mantle-admin";
+import { signInCodeEmail, signInLinkEmail, staffInvitationEmail } from "./emailTemplates.js";
 import { STAFF_ROLES } from "@aotter/mantle-spec";
+// Better Auth 1.7.2 initializes its shared stores asynchronously. Seed them
+// before any request can be canceled; the accessor-identity regression test
+// pins this version-specific integration to the stores Better Auth uses.
+const betterAuthGlobalKey = Symbol.for("better-auth:global");
+const betterAuthGlobals = globalThis;
+const betterAuthGlobal = betterAuthGlobals[betterAuthGlobalKey] ??= {
+    version: "",
+    epoch: 0,
+    context: {},
+};
+betterAuthGlobal.context.requestStateAsyncStorage ??= new AsyncLocalStorage();
+betterAuthGlobal.context.endpointContextAsyncStorage ??= new AsyncLocalStorage();
+betterAuthGlobal.context.adapterAsyncStorage ??= new AsyncLocalStorage();
 export { decodeMemberCursor, encodeMemberCursor };
 export { STAFF_ROLES };
 /**
@@ -231,8 +248,7 @@ function buildMagicLinkPlugin(method) {
             const locale = pickLocale(ctx?.request, fallback);
             return method.sender.send({
                 to: data.email,
-                subject: "Your sign-in link",
-                text: `Click to sign in: ${data.url}\nThe link expires shortly. If you didn't request this, ignore this email.`,
+                ...signInLinkEmail(data.url),
                 locale,
                 category: "auth.magic-link.sign-in",
             });
@@ -259,8 +275,7 @@ function buildEmailOTPPlugin(method) {
             const locale = pickLocale(ctx?.request, fallback);
             return method.sender.send({
                 to: data.email,
-                subject: `Your sign-in code: ${data.otp}`,
-                text: `Your one-time code is ${data.otp}. It expires shortly. If you didn't request this, ignore this email.`,
+                ...signInCodeEmail(data.otp),
                 locale,
                 category: `auth.email-otp.${data.type}`,
             });
@@ -398,6 +413,9 @@ export function buildOAuthProviderOptions(config) {
     };
 }
 function buildAuth(config) {
+    if (config.hostOnlyCookies && (new URL(config.baseURL).protocol !== "https:" || config.crossSubDomainCookies?.enabled)) {
+        throw new Error("createAuth: hostOnlyCookies requires HTTPS and cannot share cookies across subdomains.");
+    }
     if (config.methods.length === 0) {
         throw new Error("createAuth: methods[] is empty — register at least one AuthMethodConfig so staff can sign in.");
     }
@@ -412,19 +430,18 @@ function buildAuth(config) {
     const providerOptions = config.oauthProvider
         ? buildOAuthProviderOptions(config.oauthProvider)
         : null;
-    // Rate limit: Better Auth's per-route limits gate on
-    // `process.env.NODE_ENV === "production"`, which is unset on
-    // Cloudflare Workers — leaving the limits silently off. When any
-    // email-shaped method is wired (free email-send-to-any-address
-    // surface) we ALWAYS turn limits on; adopter can override
-    // window/max via `config.rateLimit`.
+    // Workers may not set NODE_ENV. Explicitly enable the provider's route
+    // limits too (notably anonymous DCR: 5/minute).
+    // ponytail: memory limits are per isolate; use an ingress rate-limit rule
+    // when a deployment needs a distributed abuse quota.
     const hasEmailMethod = !!(emailOtpMethod || magicLinkMethod);
-    const rateLimitDefault = hasEmailMethod
-        ? { window: 60, max: 10, enabled: true }
-        : null;
-    const rateLimit = config.rateLimit
-        ? { ...config.rateLimit, enabled: true }
-        : rateLimitDefault;
+    const rateLimit = {
+        window: 60,
+        max: hasEmailMethod ? 10 : 100,
+        ...config.rateLimit,
+        enabled: true,
+        storage: "memory",
+    };
     // `trustedOrigins`: per-provider auto-origins (Apple needs
     // `https://appleid.apple.com`) plus adopter-owned first-party
     // origins for flows such as hosted auth across trusted subdomains.
@@ -457,6 +474,11 @@ function buildAuth(config) {
                     ? mcp({
                         ...providerOptions,
                         resource: config.oauthProvider.mcpResource,
+                        extensions: [{
+                                claims: {
+                                    accessToken: ({ referenceId }) => ({ mantle_consent_id: referenceId ?? null }),
+                                },
+                            }],
                     })
                     : oauthProvider(providerOptions),
                 ...(config.oauthProvider.mcpResource
@@ -466,7 +488,9 @@ function buildAuth(config) {
                             // runtime network boundary: resolution and connection stay
                             // on the public Internet. Better Auth owns timeout, limits,
                             // validation, caching, and redirect rejection above it.
-                            fetchClientMetadataResource: (input, init) => fetch(input, { ...init, redirect: "error" }),
+                            // Workers does not implement `redirect: "error"`; `manual`
+                            // exposes 3xx responses so Better Auth can reject them.
+                            fetchClientMetadataResource: (input, init) => fetch(input, { ...init, redirect: "manual" }),
                             metadataProfile: "mcp-2026-07-28",
                         }),
                     ]
@@ -492,6 +516,8 @@ function buildAuth(config) {
     // it (Better Auth's default raises a state-mismatch).
     const appleNeedsCrossSite = methodsRequireSameSiteNone(config.methods);
     const advancedConfig = {
+        // Cloudflare overwrites this at ingress. Never trust client-controlled XFF.
+        ipAddress: { ipAddressHeaders: ["cf-connecting-ip"] },
         ...(appleNeedsCrossSite
             ? {
                 // Browsers require `secure: true` whenever `sameSite: "none"`.
@@ -502,6 +528,13 @@ function buildAuth(config) {
             ? { crossSubDomainCookies: config.crossSubDomainCookies }
             : {}),
         ...(config.cookiePrefix ? { cookiePrefix: config.cookiePrefix } : {}),
+        ...(config.hostOnlyCookies ? {
+            // Better Auth prepends __Secure- otherwise. Secure is set explicitly below.
+            useSecureCookies: false,
+            cookiePrefix: `__Host-${config.cookiePrefix || "better-auth"}`,
+            crossSubDomainCookies: { enabled: false },
+            defaultCookieAttributes: { secure: true, path: "/", ...(appleNeedsCrossSite ? { sameSite: "none" } : {}) },
+        } : {}),
         // Fire-and-forget hook closes the user-existence timing oracle
         // on OTP send — see § "Auth as contract" notes in ADR-0014.
         backgroundTasks: {
@@ -549,16 +582,59 @@ function buildAuth(config) {
                 before: async (user, context) => guardGithubLoginProfile(user, context, config.methods),
             },
         },
+        verification: {
+            create: {
+                before: async (verification) => {
+                    if (!config.oauthProvider?.mcpResource)
+                        return;
+                    let value;
+                    try {
+                        value = JSON.parse(verification.value);
+                    }
+                    catch {
+                        return; // OTPs and other verification values are not OAuth grants.
+                    }
+                    if (value?.type !== "authorization_code" || typeof value.userId !== "string" ||
+                        typeof value.query?.client_id !== "string")
+                        return;
+                    const consent = await config.database
+                        .prepare("SELECT id FROM oauthConsent WHERE userId = ? AND clientId = ? LIMIT 1")
+                        .bind(value.userId, value.query.client_id)
+                        .first();
+                    // Better Auth carries referenceId from this code through every
+                    // refresh rotation. Never rebind an old lineage to a new consent.
+                    return { data: { value: JSON.stringify({ ...value, referenceId: consent?.id ?? "" }) } };
+                },
+            },
+        },
     };
+    const secondaryStorage = config.sessionCacheKv ? {
+        get: (key) => key.startsWith("verification:")
+            ? Promise.resolve(null)
+            : config.sessionCacheKv.get(`better-auth:${key}`),
+        set: (key, value, ttl) => key.startsWith("verification:")
+            ? Promise.resolve()
+            : config.sessionCacheKv.put(`better-auth:${key}`, value, ttl ? { expirationTtl: Math.max(60, Math.ceil(ttl)) } : undefined),
+        delete: (key) => key.startsWith("verification:")
+            ? Promise.resolve()
+            : config.sessionCacheKv.delete(`better-auth:${key}`),
+        // Verification and rate limiting stay in D1/memory below. Fail loudly if
+        // Better Auth starts routing either atomic operation through this adapter.
+        getAndDelete: async () => { throw new Error("Better Auth KV getAndDelete is disabled"); },
+        increment: async () => { throw new Error("Better Auth KV increment is disabled"); },
+    } : undefined;
     return betterAuth({
         database: config.database,
+        secondaryStorage,
+        session: { storeSessionInDatabase: true },
+        verification: { storeInDatabase: true },
         secret: config.secret,
         baseURL: config.baseURL,
         basePath: normalizeAuthBasePath(config.basePath),
         onAPIError: { errorURL: normalizeAuthErrorURL(config.errorURL, config.baseURL) },
         socialProviders,
         user: userConfig,
-        ...(rateLimit ? { rateLimit } : {}),
+        rateLimit,
         trustedOrigins,
         advanced: advancedConfig,
         plugins: sdkPlugins,
@@ -574,6 +650,34 @@ const LEGACY_DCR_TTL_MS = 90 * 24 * 60 * 60 * 1_000;
 const LEGACY_DCR_CLEANUP_INTERVAL_MS = 60 * 60 * 1_000;
 export function createAuth(config) {
     const auth = buildAuth(config);
+    const ready = auth.$context.then(() => undefined);
+    // Observe eager initialization even for low-level callers; keep the original
+    // rejection available to callers awaiting ready and Better Auth's handlers.
+    void ready.catch(() => { });
+    // Auth owns its schema even when content uses a different semantic store.
+    // Keep schema work lazy: static/plan-only routes must not prepare tables.
+    let schemaReady = null;
+    const prepareAuth = () => schemaReady ??= (async () => {
+        const context = await auth.$context;
+        const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(context.tables)));
+        const id = `auth-schema:1:${Array.from(new Uint8Array(digest), byte => byte.toString(16).padStart(2, "0")).join("")}`;
+        try {
+            const applied = await config.database.prepare("SELECT id FROM _migrations WHERE id = ?").bind(id).first();
+            if (applied?.id === id)
+                return;
+        }
+        catch (error) {
+            // A new, auth-only database has no legacy Runtime ledger yet.
+            if (!/no such table: _migrations/i.test(String(error)))
+                throw error;
+        }
+        const { compileMigrations } = await getMigrations(context.options);
+        await new D1DatabaseDriver(config.database).migrations.runAll([{
+                id,
+                description: "Selected Better Auth schema and staff-role access path",
+                sql: `${await compileMigrations()}\nCREATE INDEX IF NOT EXISTS user_role_idx ON user (role) WHERE role IS NOT NULL;`,
+            }]);
+    })().catch(error => { schemaReady = null; throw error; });
     const basePath = normalizeAuthBasePath(config.basePath);
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const api = auth.api;
@@ -588,8 +692,13 @@ export function createAuth(config) {
     };
     const verifyAccessToken = config.oauthProvider
         ? async (token, audience) => {
+            await prepareAuth();
             const context = await auth.$context;
-            return verifyOAuthJwtWithLocalJwks(token, audience, context.baseURL, async () => api.getJwks(), localJwksCacheKey);
+            const claims = await verifyOAuthJwtWithLocalJwks(token, audience, context.baseURL, async () => api.getJwks(), localJwksCacheKey);
+            if (audience === config.oauthProvider?.mcpResource) {
+                await assertActiveMcpGrant(config.database, claims, audience);
+            }
+            return claims;
         }
         : null;
     let nextDcrCleanupAt = 0;
@@ -612,18 +721,41 @@ export function createAuth(config) {
     };
     return {
         basePath,
+        ready,
         ...(config.oauthProvider?.mcpResource
             ? { mcpResource: config.oauthProvider.mcpResource }
             : {}),
         handler: async (request) => {
+            await prepareAuth();
             const pathname = new URL(request.url).pathname;
             if (pathname.startsWith(`${basePath}/oauth2/`)) {
                 await pruneExpiredDynamicClients();
             }
             return normalizeAuthResponseCookies(await auth.handler(request));
         },
-        getSession: (request) => api.getSession({ headers: request.headers }).then((r) => r ?? null),
+        getSession: async (request) => {
+            let session;
+            try {
+                session = await api.getSession({ headers: request.headers });
+            }
+            catch {
+                // Existing sessions resolve from KV without paying the schema-ledger read.
+                // A fresh database with a stale cookie prepares once, then retries safely.
+                await prepareAuth();
+                session = await api.getSession({ headers: request.headers });
+            }
+            return session
+                ? {
+                    ...session,
+                    user: {
+                        ...session.user,
+                        ...(Object.hasOwn(session.user, "role") ? { roleCurrent: true } : {}),
+                    },
+                }
+                : null;
+        },
         getUserRole: async (userId) => {
+            await prepareAuth();
             const row = await config.database
                 .prepare("SELECT role FROM user WHERE id = ? LIMIT 1")
                 .bind(userId)
@@ -631,6 +763,7 @@ export function createAuth(config) {
             return row?.role ?? null;
         },
         getUser: async (userId) => {
+            await prepareAuth();
             const row = await config.database
                 .prepare("SELECT id, email, name, image, role, githubLogin, emailVerified, createdAt FROM user WHERE id = ? LIMIT 1")
                 .bind(userId)
@@ -653,6 +786,7 @@ export function createAuth(config) {
             };
         },
         getProviderAccessToken: async (request, providerId) => {
+            await prepareAuth();
             const session = await api.getSession({ headers: request.headers });
             const userId = session?.user?.id;
             const account = userId
@@ -676,6 +810,7 @@ export function createAuth(config) {
             const clientId = url.searchParams.get("client_id");
             if (!clientId || !url.search)
                 return null;
+            await prepareAuth();
             const oauthQuery = url.search.slice(1);
             const client = await api.getOAuthClientPublicPrelogin({
                 headers: request.headers,
@@ -706,6 +841,7 @@ export function createAuth(config) {
             if (typeof oauthQuery !== "string" || oauthQuery.length === 0) {
                 throw new Error("completeOAuthConsent: oauth_query is missing.");
             }
+            await prepareAuth();
             const headers = new Headers(request.headers);
             headers.set("content-type", "application/json");
             headers.delete("content-length");
@@ -723,6 +859,57 @@ export function createAuth(config) {
             }
             return result.url;
         },
+        ...(config.oauthProvider
+            ? {
+                listOAuthConsents: async (userId) => {
+                    await prepareAuth();
+                    const result = await config.database
+                        .prepare(`SELECT consent.id, consent.clientId,
+                        COALESCE(client.name, consent.clientId) AS clientName,
+                        consent.scopes
+                   FROM oauthConsent AS consent
+                   LEFT JOIN oauthClient AS client ON client.clientId = consent.clientId
+                  WHERE consent.userId = ?
+                  ORDER BY consent.updatedAt DESC, consent.id ASC`)
+                        .bind(userId)
+                        .all();
+                    return (result.results ?? []).map((row) => ({
+                        id: row.id,
+                        clientId: row.clientId,
+                        clientName: row.clientName,
+                        scopes: parseStoredStringArray(row.scopes) ?? [],
+                    }));
+                },
+                revokeOAuthConsent: async (userId, consentId) => {
+                    await prepareAuth();
+                    const consent = await config.database
+                        .prepare("SELECT clientId FROM oauthConsent WHERE id = ? AND userId = ? LIMIT 1")
+                        .bind(consentId, userId)
+                        .first();
+                    if (!consent)
+                        return false;
+                    const revokedAt = new Date().toISOString();
+                    await config.database.batch([
+                        config.database
+                            .prepare("UPDATE oauthRefreshToken SET revoked = ? WHERE userId = ? AND clientId = ? AND revoked IS NULL")
+                            .bind(revokedAt, userId, consent.clientId),
+                        config.database
+                            .prepare("UPDATE oauthAccessToken SET revoked = ? WHERE userId = ? AND clientId = ? AND revoked IS NULL")
+                            .bind(revokedAt, userId, consent.clientId),
+                        config.database
+                            .prepare(`DELETE FROM verification
+                    WHERE CASE WHEN json_valid(value) THEN json_extract(value, '$.type') END = 'authorization_code'
+                      AND CASE WHEN json_valid(value) THEN json_extract(value, '$.userId') END = ?
+                      AND CASE WHEN json_valid(value) THEN json_extract(value, '$.query.client_id') END = ?`)
+                            .bind(userId, consent.clientId),
+                        config.database
+                            .prepare("DELETE FROM oauthConsent WHERE userId = ? AND clientId = ?")
+                            .bind(userId, consent.clientId),
+                    ]);
+                    return true;
+                },
+            }
+            : {}),
         methods: config.methods.map((m) => {
             switch (m.kind) {
                 case "social":
@@ -739,6 +926,7 @@ export function createAuth(config) {
             }
         }),
         listLinkedAccounts: async (userId) => {
+            await prepareAuth();
             const result = await config.database
                 .prepare("SELECT id, providerId, accountId, createdAt, updatedAt FROM account WHERE userId = ? ORDER BY createdAt ASC, id ASC")
                 .bind(userId)
@@ -752,6 +940,7 @@ export function createAuth(config) {
             }));
         },
         unlinkAccount: async (userId, providerId) => {
+            await prepareAuth();
             const result = await config.database
                 .prepare("DELETE FROM account WHERE userId = ? AND providerId = ?")
                 .bind(userId, providerId)
@@ -759,6 +948,7 @@ export function createAuth(config) {
             return (result.meta?.changes ?? 0) > 0;
         },
         listUsers: async () => {
+            await prepareAuth();
             const placeholders = STAFF_ROLES.map(() => "?").join(",");
             const result = await config.database
                 .prepare(`SELECT id, email, name, role, githubLogin, emailVerified, createdAt FROM user WHERE role IN (${placeholders}) ORDER BY createdAt ASC, id ASC`)
@@ -775,6 +965,7 @@ export function createAuth(config) {
             }));
         },
         listMembers: async ({ search, cursor, cursorDirection = "forward", limit }) => {
+            await prepareAuth();
             const parsedCursor = cursor ? decodeMemberCursor(cursor) : null;
             const backward = cursorDirection === "backward";
             const conditions = [
@@ -783,9 +974,9 @@ export function createAuth(config) {
             const bindings = [...STAFF_ROLES];
             const term = search?.trim().toLowerCase();
             if (term) {
-                conditions.push("(LOWER(name) LIKE ? ESCAPE '\\' OR LOWER(email) LIKE ? ESCAPE '\\')");
+                conditions.push("(LOWER(id) LIKE ? ESCAPE '\\' OR LOWER(name) LIKE ? ESCAPE '\\' OR LOWER(email) LIKE ? ESCAPE '\\')");
                 const like = `%${term.replace(/[\\%_]/g, (character) => `\\${character}`)}%`;
-                bindings.push(like, like);
+                bindings.push(like, like, like);
             }
             if (parsedCursor) {
                 const operator = backward ? "<" : ">";
@@ -822,6 +1013,14 @@ export function createAuth(config) {
             if (role !== null && !STAFF_ROLE_SET.has(role)) {
                 throw new Error(`setUserRole: '${role}' is not a staff role — expected one of [${STAFF_ROLES.join(", ")}] or null.`);
             }
+            await prepareAuth();
+            if (config.sessionCacheKv) {
+                const context = await auth.$context;
+                return !!await context.internalAdapter.updateUser(userId, {
+                    role,
+                    updatedAt: new Date(),
+                });
+            }
             const result = await config.database
                 .prepare("UPDATE user SET role = ?, updatedAt = ? WHERE id = ?")
                 .bind(role, new Date().toISOString(), userId)
@@ -832,6 +1031,7 @@ export function createAuth(config) {
             if (!STAFF_ROLE_SET.has(role)) {
                 throw new Error(`inviteUser: '${role}' is not a staff role — expected one of [${STAFF_ROLES.join(", ")}].`);
             }
+            await prepareAuth();
             const normalized = email.trim().toLowerCase();
             const existing = await config.database
                 .prepare("SELECT id FROM user WHERE email = ? LIMIT 1")
@@ -850,7 +1050,19 @@ export function createAuth(config) {
                 .run();
             return { kind: "created", id };
         },
+        ...(config.staffInvitationSender ? {
+            sendStaffInvitation: async (email, role) => {
+                const normalized = email.trim().toLowerCase();
+                await config.staffInvitationSender.send({
+                    to: normalized,
+                    ...staffInvitationEmail(role, new URL("/admin/sign-in", config.baseURL).href),
+                    locale: "en",
+                    category: "auth.staff-invitation",
+                });
+            },
+        } : {}),
         revokeInvite: async (userId) => {
+            await prepareAuth();
             const result = await config.database
                 .prepare("DELETE FROM user WHERE id = ? AND emailVerified = 0 AND NOT EXISTS (SELECT 1 FROM account WHERE account.userId = user.id)")
                 .bind(userId)
@@ -861,6 +1073,7 @@ export function createAuth(config) {
             if (!config.oauthProvider) {
                 throw new Error("registerOAuthClient: oauthProvider is not configured.");
             }
+            await prepareAuth();
             const created = await api.adminCreateOAuthClient({
                 headers: new Headers(input.requestHeaders),
                 body: {
@@ -968,6 +1181,44 @@ function scopesFromClaim(value) {
     }
     return [];
 }
+function parseStoredStringArray(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        const parsed = JSON.parse(value);
+        return Array.isArray(parsed) && parsed.every((item) => typeof item === "string")
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+async function assertActiveMcpGrant(database, claims, audience) {
+    const userId = claims["sub"];
+    const clientId = claims["azp"];
+    const sessionId = claims["sid"];
+    const consentId = claims["mantle_consent_id"];
+    if (typeof userId !== "string" ||
+        typeof clientId !== "string" ||
+        typeof sessionId !== "string" ||
+        typeof consentId !== "string" || !consentId) {
+        throw new Error("MCP token is not bound to a user session.");
+    }
+    const result = await database
+        .prepare("SELECT c.resources, c.scopes FROM oauthConsent AS c " +
+        "JOIN session AS s ON s.id = ? AND s.userId = c.userId AND s.expiresAt > ? " +
+        "WHERE c.id = ? AND c.userId = ? AND c.clientId = ?")
+        .bind(sessionId, new Date().toISOString(), consentId, userId, clientId)
+        .first();
+    const tokenScopes = scopesFromClaim(claims["scope"]);
+    const resources = parseStoredStringArray(result?.resources);
+    const scopes = parseStoredStringArray(result?.scopes);
+    const active = resources?.includes(audience) === true && scopes !== null &&
+        tokenScopes.every((scope) => scopes.includes(scope));
+    if (!active)
+        throw new Error("MCP authorization grant is no longer active.");
+}
 /** @internal exported to keep same-Worker OAuth verification off the network. */
 export function verifyOAuthJwtWithLocalJwks(token, audience, issuer, jwksFetch, jwksCacheKey) {
     return verifyJwsAccessToken(token, {