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

package/dist/auth/oauth.d.ts

@@ -0,0 +1,31 @@
+import type { oauthProvider } from "@better-auth/oauth-provider";
+import type { AuthInstance } from "./caller.js";
+/** Fail closed for unbound tokens; reconsent cannot resurrect an issued JWT. */
+export declare function assertActiveUserGrant(auth: AuthInstance, claims: Record<string, unknown>, audience: string | readonly string[]): Promise<{
+    id: string;
+}>;
+/** Add first to oauthProvider/mcp extensions; Better Auth retains ownership of referenceId. */
+export declare const oauthGrantExtension: NonNullable<Parameters<typeof oauthProvider>[0]["extensions"]>[number];
+export interface OAuthConsentRequest {
+    readonly clientName: string;
+    readonly redirectUri: string;
+    readonly scopes: readonly string[];
+    readonly oauthQuery: string;
+}
+export interface OAuthConsentInfo {
+    readonly id: string;
+    readonly clientId: string;
+    readonly clientName: string;
+    readonly scopes: readonly string[];
+}
+/** Signed-query and consent APIs over the same application-owned instance and adapter (including renamed tables). */
+export declare function oauthConsents(auth: AuthInstance & {
+    handler(request: Request): Promise<Response>;
+}): {
+    getOAuthConsentRequest: (request: Request) => Promise<OAuthConsentRequest | null>;
+    completeOAuthConsent: (request: Request, accept: boolean) => Promise<string>;
+    listOAuthConsents: (userId: string) => Promise<OAuthConsentInfo[]>;
+    revokeOAuthConsent: (userId: string, consentId: string) => Promise<boolean>;
+};
+/** Optional scheduled storage hygiene, not boot work or an authorization rule. Owned/CIMD clients survive. */
+export declare function pruneLegacyOAuthClients(auth: AuthInstance): Promise<number>;

package/dist/auth/oauth.js

@@ -0,0 +1,124 @@
+import { nativeAuthRead } from "./adapter.js";
+import { ContractError } from "../kernel/contracts.js";
+const pair = (field, value) => ({ field, value });
+const array = (value) => {
+    try {
+        const parsed = typeof value === "string" ? JSON.parse(value) : value;
+        return Array.isArray(parsed) && parsed.every(x => typeof x === "string") ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+};
+/** Fail closed for unbound tokens; reconsent cannot resurrect an issued JWT. */
+export async function assertActiveUserGrant(auth, claims, audience) {
+    const { sub, azp, sid, mantle_consent_id: id, mantle_consent_reference: reference, mantle_skip_consent: skip } = claims;
+    if (![sub, azp, sid].every(x => typeof x === "string" && x.length) || !(skip === true && id === null || typeof id === "string" && id.length))
+        throw new ContractError("UNAUTHENTICATED", "OAuth token is not bound to a user session.");
+    const { exec, param, now, table, column } = nativeAuthRead(auth.options);
+    const c = (field) => `c.${column("oauthConsent", field)}`, s = (field) => `s.${column("session", field)}`, client = (field) => `client.${column("oauthClient", field)}`;
+    const { rows } = await exec(`SELECT ${s("userId")} AS id, ${c("id")} AS "consentId", ${c("referenceId")} AS reference, ${c("resources")} AS resources, ${c("scopes")} AS scopes,
+      ${client("skipConsent")} AS "skipConsent", ${client("disabled")} AS disabled, ${client("scopes")} AS "clientScopes"
+    FROM ${table("oauthClient")} client JOIN ${table("session")} s ON ${s("id")} = ${param(1)} AND ${s("userId")} = ${param(2)} AND ${s("expiresAt")} > ${param(3)}
+    LEFT JOIN ${table("oauthConsent")} c ON ${c("id")} = ${param(4)} AND ${c("userId")} = ${s("userId")} AND ${c("clientId")} = ${client("clientId")}
+    WHERE ${client("clientId")} = ${param(5)}`, [sid, sub, now(Date.now()), id, azp]);
+    const grant = rows[0];
+    const provider = auth.options.plugins?.find(plugin => plugin.id === "oauth-provider");
+    const firstParty = skip === true && id === null && !!grant?.skipConsent;
+    const resources = firstParty ? (typeof claims.aud === "string" ? [claims.aud] : array(claims.aud)) : array(grant?.resources);
+    const scopes = firstParty ? array(grant?.clientScopes) ?? provider?.options?.scopes : array(grant?.scopes);
+    const requested = typeof audience === "string" ? [audience] : audience;
+    const tokenAudiences = typeof claims.aud === "string" ? [claims.aud] : array(claims.aud) ?? [];
+    const tokenScopes = typeof claims.scope === "string" ? claims.scope.split(/\s+/).filter(Boolean) : array(claims.scope);
+    if (!grant || grant.disabled || !firstParty && (!grant.consentId || (grant.reference ?? null) !== reference) || !resources || !scopes || !tokenScopes || !requested.some(x => resources.includes(x) && tokenAudiences.includes(x)) || !tokenScopes.every(x => scopes.includes(x)))
+        throw new ContractError("UNAUTHENTICATED", "OAuth authorization grant is no longer active.");
+    return { id: grant.id };
+}
+/** Add first to oauthProvider/mcp extensions; Better Auth retains ownership of referenceId. */
+export const oauthGrantExtension = {
+    claims: { accessToken: async ({ ctx, user, client, referenceId }) => {
+            if (client.skipConsent)
+                return { mantle_consent_id: null, mantle_skip_consent: true };
+            const consent = user && await ctx.context.adapter.findOne({ model: "oauthConsent", where: [pair("userId", user.id), pair("clientId", client.clientId), { field: "referenceId", value: referenceId ?? null }] });
+            return { mantle_consent_id: consent?.id ?? null, mantle_consent_reference: referenceId ?? null };
+        } },
+};
+/** A verification value that is an authorization code, with its user and client; else undefined. */
+function authCode(text) {
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return;
+    }
+    return value?.type === "authorization_code" && typeof value.userId === "string" && typeof value.query?.client_id === "string" ? value : undefined;
+}
+/** Signed-query and consent APIs over the same application-owned instance and adapter (including renamed tables). */
+export function oauthConsents(auth) {
+    const adapter = async () => (await auth.$context).adapter;
+    return {
+        getOAuthConsentRequest: async (request) => {
+            const url = new URL(request.url), clientId = url.searchParams.get("client_id");
+            if (!clientId || !url.search)
+                return null;
+            const api = auth.api;
+            const oauthQuery = url.search.slice(1);
+            const client = await api.getOAuthClientPublicPrelogin({ headers: request.headers, body: { client_id: clientId, oauth_query: oauthQuery } });
+            return { clientName: client.client_name ?? clientId, redirectUri: url.searchParams.get("redirect_uri") ?? client.redirect_uris?.[0] ?? "", scopes: (url.searchParams.get("scope") ?? "").split(/\s+/).filter(Boolean), oauthQuery };
+        },
+        completeOAuthConsent: async (request, accept) => {
+            const oauth_query = (await request.formData()).get("oauth_query");
+            if (typeof oauth_query !== "string" || !oauth_query)
+                throw new ContractError("INPUT_VALIDATION_FAILED", "Missing signed authorization request.");
+            const headers = new Headers(request.headers);
+            headers.set("content-type", "application/json");
+            headers.delete("content-length");
+            const response = await auth.handler(new Request(new URL(`${auth.options.basePath ?? "/api/auth"}/oauth2/consent`, request.url).href, { method: "POST", headers, body: JSON.stringify({ accept, oauth_query }) }));
+            const body = await response.json();
+            if (!response.ok || typeof body.url !== "string")
+                throw new ContractError("INPUT_VALIDATION_FAILED", "Invalid authorization request.");
+            return body.url;
+        },
+        listOAuthConsents: async (userId) => {
+            const { exec, param, table, column } = nativeAuthRead(auth.options);
+            const c = (field) => `c.${column("oauthConsent", field)}`, client = (field) => `client.${column("oauthClient", field)}`;
+            const { rows } = await exec(`SELECT ${c("id")} AS id, ${c("clientId")} AS "clientId", COALESCE(${client("name")}, ${c("clientId")}) AS "clientName", ${c("scopes")} AS scopes
+        FROM ${table("oauthConsent")} c LEFT JOIN ${table("oauthClient")} client ON ${client("clientId")} = ${c("clientId")}
+        WHERE ${c("userId")} = ${param(1)} ORDER BY ${c("updatedAt")} DESC, ${c("id")} ASC`, [userId]);
+            return rows.map(row => ({ id: row.id, clientId: row.clientId, clientName: row.clientName, scopes: array(row.scopes) ?? [] }));
+        },
+        revokeOAuthConsent: async (userId, consentId) => {
+            const db = await adapter();
+            const consent = await db.findOne({ model: "oauthConsent", where: [pair("id", consentId), pair("userId", userId)] });
+            if (!consent)
+                return false;
+            const where = [pair("userId", userId), pair("clientId", consent.clientId)];
+            // Delete first: even if cleanup fails, every issued JWT fails the live-grant check immediately.
+            await db.deleteMany({ model: "oauthConsent", where });
+            for (const model of ["oauthRefreshToken", "oauthAccessToken"])
+                await db.updateMany({ model, where: [...where, { field: "revoked", value: null }], update: { revoked: new Date() } });
+            // An unredeemed code would mint a new token lineage after reconsent.
+            const code = (v) => { const x = authCode(v); return x?.userId === userId && x.query.client_id === consent.clientId; };
+            const codes = [{ field: "value", operator: "contains", value: JSON.stringify(userId) }, { field: "value", operator: "contains", value: JSON.stringify(consent.clientId) }];
+            for (let offset = 0;;) {
+                const page = await db.findMany({ model: "verification", where: codes, limit: 100, offset, sortBy: { field: "id", direction: "asc" } });
+                const ids = page.filter(v => code(v.value)).map(v => v.id);
+                if (ids.length)
+                    await db.deleteMany({ model: "verification", where: [{ field: "id", operator: "in", value: ids }] });
+                if (page.length < 100)
+                    break;
+                offset += page.length - ids.length;
+            }
+            return true;
+        },
+    };
+}
+/** Optional scheduled storage hygiene, not boot work or an authorization rule. Owned/CIMD clients survive. */
+export async function pruneLegacyOAuthClients(auth) {
+    const { adapter } = await auth.$context;
+    return adapter.deleteMany({ model: "oauthClient", where: [
+            { field: "clientDiscoveryId", value: null }, { field: "userId", value: null }, { field: "referenceId", value: null },
+            { field: "createdAt", operator: "lt", value: new Date(Date.now() - 90 * 86400_000) },
+        ] });
+}

package/dist/auth/resource-seeds.js

@@ -0,0 +1,10 @@
+/** Keep runtime inputs while disabling the provider's eager and bulk lazy seeding. No schema or database work. */
+// OAuth provider 1.7.7 shares plugin.options with its eager/lazy seed closures; its seedResources/checkIdentifier helpers are not exported.
+const seeds = new WeakMap();
+export function resourceSeeds(options) {
+    const inputs = (seeds.get(options) ?? options.resources ?? []);
+    if (!seeds.has(options))
+        seeds.set(options, [...inputs]);
+    options.resources = [];
+    return inputs;
+}

package/dist/auth/routes.d.ts

@@ -0,0 +1,32 @@
+/** Optional app-mounted auth routes; consent and raw admin routes resolve fresh authority. Better Auth owns tokens. */
+import { type Caller } from "../kernel/contracts.js";
+import { type AuthInstance, type AuthLoader } from "./caller.js";
+export interface AuthRoutesOptions {
+    /** Same basePath as app-owned betterAuth options. */
+    readonly basePath?: string;
+    readonly resolver?: (request: Request) => Caller | Promise<Caller>;
+    readonly methods: readonly ({
+        readonly kind: "social";
+        readonly provider: string;
+    } | {
+        readonly kind: "oauth";
+        readonly providerId: string;
+        readonly displayName?: string;
+    } | {
+        readonly kind: "email-otp" | "magic-link";
+    })[];
+    readonly connectedAppsPage?: string;
+}
+/** The service's auth entry: a Response for a path it owns, `null` for any other. */
+export declare function authRoutes(loader: AuthLoader<AuthInstance & {
+    handler(request: Request): Promise<Response>;
+}>, options: AuthRoutesOptions): (request: Request) => Promise<Response | null>;
+/**
+ * A dynamic registration whose every redirect URI is http on a loopback host and that names no application_type is a
+ * native app (RFC 8252 7.3): local MCP clients register this way. Better Auth reads the missing type as `web`, which
+ * needs https on a non-loopback host, so it would refuse them all. Mark it native, as the client could itself; a
+ * registration naming a type, mixing hosts or using any other redirect is passed through unchanged.
+ */
+export declare function loopbackClientsAreNative(request: Request): Promise<Request>;
+/** Better Auth and host fetch implementations may merge several Set-Cookie values into one header. */
+export declare function normalizeAuthResponseCookies(response: Response): Promise<Response>;

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

@@ -1,35 +1,64 @@
-import { withCaller } from "../core/withCaller.js";
+/** Optional app-mounted auth routes; consent and raw admin routes resolve fresh authority. Better Auth owns tokens. */
+import { checkOrigin, surfaceFailure, ContractError } from "../kernel/contracts.js";
+import { guardAuthAdminRequest } from "./admin.js";
+import { resolveCaller } from "./caller.js";
 const PRIVATE = { "cache-control": "private, no-store" };
-const CONSENT = new Set(["GET /oauth/consent", "GET /oauth/consent/data", "POST /oauth/consent"]);
-const CONSENTS = new Set(["GET /oauth/consents", "GET /oauth/consents/data", "POST /oauth/consents/revoke"]);
+const CONSENT = new Set(["GET /oauth/consent", "GET /oauth/consent/data", "POST /oauth/consent", "GET /oauth/consents", "GET /oauth/consents/data", "POST /oauth/consents/revoke"]);
+const MAX_BODY = 1_048_576;
+const text = (body, status) => new Response(body, { status, headers: PRIVATE });
+const json = (body, status = 200) => Response.json(body, { status, headers: PRIVATE });
+const redirect = (location, status = 302) => new Response(null, { status, headers: { location, ...PRIVATE } });
+const tooLarge = () => new ContractError("INPUT_VALIDATION_FAILED", "Request body exceeds 1 MiB.");
+const basePathOf = (options) => (options.basePath ?? "/api/auth").replace(/\/+$/, "");
 const WELL_KNOWN = /^\/\.well-known\/(oauth-authorization-server|oauth-protected-resource)(\/|$)/;
 /** The service's auth entry: a Response for a path it owns, `null` for any other. */
-export function createAuthRoutes(auth, options) {
-    const base = auth.basePath.replace(/\/+$/, "");
-    const consent = withCaller(options.resolver, consentSurface(auth, options));
-    return async (request, context) => {
+export function authRoutes(loader, options) {
+    const base = basePathOf(options);
+    if (options.connectedAppsPage && (!options.connectedAppsPage.startsWith("/") || options.connectedAppsPage.startsWith("//") || /[\\\r\n]/.test(options.connectedAppsPage)))
+        throw new Error("connectedAppsPage must be a same-origin absolute path.");
+    const resolve = options.resolver ?? ((request) => resolveCaller(request, loader));
+    return async (request) => {
         const { pathname } = new URL(request.url);
-        if (pathname === `${base}/methods` && request.method === "GET")
-            return Response.json({ methods: auth.methods }, { headers: { "cache-control": "no-store" } });
-        if (pathname.startsWith(`${base}/`) || WELL_KNOWN.test(pathname))
-            return auth.handler(request, context);
-        // only an owned route resolves a caller: `/oauth/callback/github` and the rest are the service's, whatever they carry
         const route = `${request.method} ${pathname}`;
-        return CONSENT.has(route) || (CONSENTS.has(route) && auth.listOAuthConsents && auth.revokeOAuthConsent) ? consent(request) : null;
+        if (pathname === `${base}/methods` && request.method === "GET")
+            return json({ methods: options.methods });
+        if (pathname.startsWith(`${base}/`) || WELL_KNOWN.test(pathname)) {
+            const auth = await loader.get();
+            if (basePathOf(auth.options) !== base)
+                throw new Error("authRoutes basePath differs from betterAuth options.");
+            try {
+                await guardAuthAdminRequest(request, () => resolve(request), base);
+                const registration = request.method === "POST" && pathname === `${base}/oauth2/register` ? await loopbackClientsAreNative(request) : request;
+                return await normalizeAuthResponseCookies(await auth.handler(registration));
+            }
+            catch (error) {
+                return surfaceFailure(error, undefined, `auth ${route}`);
+            }
+        }
+        if (!CONSENT.has(route))
+            return null;
+        try {
+            const caller = await resolve(request);
+            checkOrigin(request, caller);
+            if (request.method === "POST" && Number(request.headers.get("content-length")) > MAX_BODY)
+                return text("request body too large", 413);
+            return await consentSurface((await import("./oauth.js")).oauthConsents(await loader.get()), options)(request, caller, route);
+        }
+        catch (error) {
+            return surfaceFailure(error, undefined, `auth ${route}`);
+        }
     };
 }
 function consentSurface(auth, options) {
     const { listOAuthConsents: list, revokeOAuthConsent: revoke } = auth;
-    return async (request, caller) => {
-        const { pathname } = new URL(request.url);
-        const route = `${request.method} ${pathname}`;
+    return async (request, caller, route) => {
         const person = caller.kind === "user" && caller.credential === "session" ? caller.subject : null;
         const locale = /zh[-_]tw/i.test(request.headers.get("accept-language") ?? "") ? "zh-TW" : "en";
         if (route === "GET /oauth/consent/data") {
             if (!person)
-                return Response.json({ consent: null }, { status: 401, headers: PRIVATE });
+                return json({ consent: null }, 401);
             const model = await auth.getOAuthConsentRequest(request).catch(() => null); // an invalid signed query stays secret-free
-            return Response.json({ consent: model }, { status: model ? 200 : 400, headers: PRIVATE });
+            return json({ consent: model }, model ? 200 : 400);
         }
         if (route === "GET /oauth/consent") {
             const model = await auth.getOAuthConsentRequest(request).catch(() => null);
@@ -37,44 +66,45 @@ function consentSurface(auth, options) {
         }
         if (route === "POST /oauth/consent") {
             if (!person)
-                return new Response("sign in to answer this request", { status: 401 });
-            const body = await request.text();
+                return text("sign in to answer this request", 401);
+            const body = await readBody(request);
             const decision = new URLSearchParams(body).get("decision");
             if (decision !== "approve" && decision !== "deny")
-                return new Response("invalid consent decision", { status: 400 });
+                return text("invalid consent decision", 400);
             // the redirect is the one Better Auth validated against the client's registration; nothing in the request names it
             const location = await auth.completeOAuthConsent(new Request(request, { body }), decision === "approve").catch(() => null);
             const target = location && URL.canParse(location) ? new URL(location) : null;
             if (!target || /^(javascript|data|vbscript|blob):$/i.test(target.protocol))
-                return new Response("invalid authorization request", { status: 400 });
+                return text("invalid authorization request", 400);
             // the parsed form, so a browser cannot read `https:\\evil.test` differently from the check
-            return new Response(null, { status: 302, headers: { location: target.href, ...PRIVATE } });
+            return redirect(target.href);
         }
         if (!list || !revoke)
-            return new Response("not found", { status: 404 });
+            return text("not found", 404);
         if (route === "GET /oauth/consents") {
             if (options.connectedAppsPage)
-                return new Response(null, { status: 302, headers: { location: options.connectedAppsPage } });
+                return redirect(options.connectedAppsPage);
             if (!person)
-                return new Response("sign in to see your connected apps", { status: 401, headers: PRIVATE });
+                return text("sign in to see your connected apps", 401);
             return html(connectedAppsHtml(locale, await list(person)), 200);
         }
         if (route === "GET /oauth/consents/data") {
             if (!person)
-                return Response.json({ consents: [] }, { status: 401, headers: PRIVATE });
-            return Response.json({ consents: await list(person) }, { headers: PRIVATE });
+                return json({ consents: [] }, 401);
+            return json({ consents: await list(person) });
         }
         if (route === "POST /oauth/consents/revoke") {
             if (!person)
-                return new Response("sign in to revoke a connection", { status: 401 });
-            const id = new URLSearchParams(await request.text()).get("consent_id");
+                return text("sign in to revoke a connection", 401);
+            const body = await readBody(request);
+            const id = new URLSearchParams(body).get("consent_id");
             if (!id)
-                return new Response("invalid consent id", { status: 400 });
+                return text("invalid consent id", 400);
             if (!await revoke(person, id))
-                return new Response("consent not found", { status: 404 });
-            return new Response(null, { status: 303, headers: { location: "/oauth/consents" } });
+                return text("consent not found", 404);
+            return redirect("/oauth/consents", 303);
         }
-        return new Response("not found", { status: 404 });
+        return text("not found", 404);
     };
 }
 // ---- the pages a service without Admin shows: Admin is an optional subpath (ADR-0032 decision 13), OAuth is not tied to it
@@ -126,4 +156,69 @@ function connectedAppsHtml(l, consents) {
         `<input type="hidden" name="consent_id" value="${esc(c.id)}"/><button type="submit">${t.revoke}</button></form></section>`).join("");
     return page(l, t.apps, `<h1>${t.apps}</h1><p>${t.appsBody}</p>${apps}`);
 }
-//# sourceMappingURL=createAuthRoutes.js.map
+const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+/**
+ * A dynamic registration whose every redirect URI is http on a loopback host and that names no application_type is a
+ * native app (RFC 8252 7.3): local MCP clients register this way. Better Auth reads the missing type as `web`, which
+ * needs https on a non-loopback host, so it would refuse them all. Mark it native, as the client could itself; a
+ * registration naming a type, mixing hosts or using any other redirect is passed through unchanged.
+ */
+export async function loopbackClientsAreNative(request) {
+    const body = await readBody(request.clone()).then(JSON.parse).catch(error => { if (error instanceof ContractError)
+        throw error; return null; });
+    const uris = body?.redirect_uris;
+    if (!body || typeof body !== "object" || Array.isArray(body) || body.application_type !== undefined || !Array.isArray(uris) || !uris.length)
+        return request;
+    const loopback = uris.every((uri) => {
+        if (typeof uri !== "string" || !URL.canParse(uri))
+            return false;
+        const url = new URL(uri);
+        return url.protocol === "http:" && LOOPBACK_HOSTS.has(url.hostname);
+    });
+    if (!loopback)
+        return request;
+    const headers = new Headers(request.headers);
+    headers.delete("content-length");
+    return new Request(request.url, { method: "POST", headers, body: JSON.stringify({ ...body, application_type: "native" }) });
+}
+/** Bounded streaming read even without Content-Length; the native parser still owns JSON/form semantics. */
+async function readBody(request) {
+    if (Number(request.headers.get("content-length")) > MAX_BODY)
+        throw tooLarge();
+    const reader = request.body?.getReader();
+    if (!reader)
+        return "";
+    const decoder = new TextDecoder();
+    let size = 0, text = "";
+    try {
+        for (;;) {
+            const { value, done } = await reader.read();
+            if (done)
+                return text + decoder.decode();
+            size += value.byteLength;
+            if (size > MAX_BODY) {
+                void reader.cancel();
+                throw tooLarge();
+            }
+            text += decoder.decode(value, { stream: true });
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/** Better Auth and host fetch implementations may merge several Set-Cookie values into one header. */
+export async function normalizeAuthResponseCookies(response) {
+    if (!response.headers.has("set-cookie"))
+        return response;
+    const { splitSetCookieHeader } = await import("better-auth/cookies");
+    const values = response.headers.getSetCookie?.() ?? [response.headers.get("set-cookie")];
+    const cookies = values.flatMap(splitSetCookieHeader);
+    if (cookies.length < 2)
+        return response;
+    const headers = new Headers(response.headers);
+    headers.delete("set-cookie");
+    for (const cookie of cookies)
+        headers.append("set-cookie", cookie);
+    return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
+}