@plitzi/sdk-server 0.32.24 → 0.33.0

package/dist/core/auth/identity.js

@@ -0,0 +1,164 @@
+import { domainAllowed } from "./domains.js";
+//#region src/core/auth/identity.ts
+var createIdentity = ({ tokens, carriers, adapters, config = {}, presentedOrigin }) => {
+	const { platformHosts = [], platformOrigins = [], allowWithoutOrigin = false, log } = config;
+	/**
+	* The single user-token validator. Every transport goes through it, so there is one expiry rule and one status
+	* rule — the alternative, which this replaced, was a variant per role where only one of them checked `status`.
+	*/
+	const resolveActorFromToken = async (token) => {
+		const verified = tokens.verifyUserToken(token);
+		if (!verified.ok) return verified;
+		const actor = await adapters.findAccountByToken(token);
+		if (!actor || String(actor.id) !== verified.payload.sub) return {
+			ok: false,
+			reason: "revoked"
+		};
+		if (!actor.expiresAt || actor.expiresAt < Math.round(Date.now() / 1e3)) return {
+			ok: false,
+			reason: "expired"
+		};
+		return {
+			ok: true,
+			actor
+		};
+	};
+	const resolveActor = async (carrier) => {
+		const candidates = carriers.userTokenCandidates(carrier);
+		if (candidates.length === 0) return {
+			ok: false,
+			reason: "missing"
+		};
+		let lastFailure = "missing";
+		for (const candidate of candidates) {
+			const result = await resolveActorFromToken(candidate);
+			if (result.ok) return result;
+			if (result.reason !== "wrong-type") lastFailure = result.reason;
+		}
+		return {
+			ok: false,
+			reason: lastFailure
+		};
+	};
+	const originAllowed = (origin, origins) => origins.includes("*") || [...platformOrigins, ...origins].includes(origin);
+	const resolveGrantFromToken = async (token, origin, { skipOrigin = false, host } = {}) => {
+		const verified = tokens.verifySpaceToken(token);
+		if (!verified.ok) return verified;
+		const { spaceId, spaceScope: scope, origins } = verified.payload;
+		const stored = await adapters.findSpaceToken?.(token);
+		if (!stored || stored.spaceId !== spaceId) return {
+			ok: false,
+			reason: "revoked"
+		};
+		if (stored.scope !== scope) return {
+			ok: false,
+			reason: "scope-mismatch"
+		};
+		const grant = {
+			spaceId,
+			scope,
+			userId: stored.userId,
+			origins
+		};
+		if (scope === "render" && host !== void 0 && !domainAllowed(host, origins, platformHosts)) {
+			log?.("Access Not Authorized - Domain", {
+				spaceId,
+				host,
+				origins
+			});
+			return {
+				ok: false,
+				reason: "domain-not-allowed"
+			};
+		}
+		if (skipOrigin) return {
+			ok: true,
+			grant
+		};
+		if (origins.length === 0 && !allowWithoutOrigin) {
+			log?.("Access Not Authorized - Origin", {
+				spaceId,
+				allowWithoutOrigin: false
+			});
+			return {
+				ok: false,
+				reason: "origin-not-allowed"
+			};
+		}
+		if (!origin) return allowWithoutOrigin ? {
+			ok: true,
+			grant
+		} : {
+			ok: false,
+			reason: "origin-not-allowed"
+		};
+		if (!originAllowed(origin, origins)) {
+			log?.("Access Not Authorized - Origin", {
+				spaceId,
+				origin,
+				origins
+			});
+			return {
+				ok: false,
+				reason: "origin-not-allowed"
+			};
+		}
+		return {
+			ok: true,
+			grant
+		};
+	};
+	const resolveGrant = async (carrier, options = {}) => {
+		const candidates = carriers.spaceTokenCandidates(carrier);
+		if (candidates.length === 0) return {
+			ok: false,
+			reason: "missing"
+		};
+		const origin = presentedOrigin(carrier);
+		const host = options.host ?? carrier.hostname;
+		let lastFailure = "missing";
+		for (const candidate of candidates) {
+			const result = await resolveGrantFromToken(candidate, origin, {
+				...options,
+				host
+			});
+			if (result.ok) return result;
+			if (result.reason !== "wrong-type") lastFailure = result.reason;
+		}
+		return {
+			ok: false,
+			reason: lastFailure
+		};
+	};
+	/**
+	* May this actor do this, here?
+	*
+	* Both halves are required. The global capability says the account is allowed to do this kind of thing at all;
+	* the space role says it may do it *in this space*. A global permission is a property of the account and never an
+	* assertion about a particular space, which is why neither half alone is an answer.
+	*/
+	const can = async (actor, spaceId, permission) => {
+		if (!actor.verified || !actor.permissions.includes(permission)) return false;
+		const membership = await adapters.findMembership?.(actor.id, spaceId);
+		return membership !== void 0 && membership.permissions.includes(permission);
+	};
+	/**
+	* An `agent` grant carries no session — its authority is the member who consented, resolved live, so that losing
+	* access to the space revokes every agent token that member authorised.
+	*/
+	const grantCan = async (grant, permission) => {
+		if (grant.scope !== "agent" || !grant.userId) return false;
+		const membership = await adapters.findMembership?.(grant.userId, grant.spaceId);
+		return membership !== void 0 && membership.permissions.includes(permission);
+	};
+	return {
+		resolveActor,
+		resolveActorFromToken,
+		resolveGrant,
+		resolveGrantFromToken,
+		can,
+		grantCan
+	};
+};
+//#endregion
+export { createIdentity };

package/dist/core/auth/oauth/client.d.ts

@@ -0,0 +1,5 @@
+import { OAuthFlowState } from './state';
+import { OAuthProvider } from './types';
+export declare function buildAuthorizationUrl(provider: OAuthProvider, state: OAuthFlowState, challenge?: string): string;
+export declare function exchangeCodeForToken(provider: OAuthProvider, code: string, state: OAuthFlowState): Promise<string>;
+export declare function requestProfileJson<T>(url: string, headers: Record<string, string>): Promise<T>;

package/dist/core/auth/oauth/client.js

@@ -0,0 +1,47 @@
+import { OAuthFailure } from "./types.js";
+//#region src/core/auth/oauth/client.ts
+function buildAuthorizationUrl(provider, state, challenge) {
+	const params = new URLSearchParams({
+		client_id: provider.config.clientId,
+		redirect_uri: provider.config.redirectUri,
+		response_type: "code",
+		scope: provider.scope,
+		state: state.nonce,
+		...provider.authorizationParams
+	});
+	if (provider.usePkce && challenge) {
+		params.set("code_challenge", challenge);
+		params.set("code_challenge_method", "S256");
+	}
+	return `${provider.authorizationUrl}?${params.toString()}`;
+}
+async function exchangeCodeForToken(provider, code, state) {
+	const body = new URLSearchParams({
+		code,
+		client_id: provider.config.clientId,
+		client_secret: provider.config.clientSecret,
+		redirect_uri: provider.config.redirectUri,
+		grant_type: "authorization_code"
+	});
+	if (provider.usePkce) body.set("code_verifier", state.verifier);
+	const response = await fetch(provider.tokenUrl, {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/x-www-form-urlencoded",
+			Accept: "application/json",
+			...provider.tokenHeaders
+		},
+		body
+	});
+	if (!response.ok) throw new OAuthFailure("exchange_failed", `${provider.id} rejected the authorization code (${response.status})`);
+	const payload = await response.json();
+	if (!payload.access_token) throw new OAuthFailure("exchange_failed", `${provider.id} returned no access token (${payload.error ?? "unknown"})`);
+	return payload.access_token;
+}
+async function requestProfileJson(url, headers) {
+	const response = await fetch(url, { headers });
+	if (!response.ok) throw new OAuthFailure("profile_failed", `Failed to read the profile from ${url} (${response.status})`);
+	return await response.json();
+}
+//#endregion
+export { buildAuthorizationUrl, exchangeCodeForToken, requestProfileJson };

package/dist/core/auth/oauth/index.d.ts

@@ -0,0 +1,78 @@
+import { OAuthFailureReason, OAuthProfile, OAuthProvider, OAuthProviderConfig } from './types';
+import { AccountRecord } from '../api';
+export { OAuthFailure } from './types';
+export { requestProfileJson } from './client';
+export type { OAuthFailureReason, OAuthProfile, OAuthProvider, OAuthProviderConfig } from './types';
+export type OAuthProviderFactory = (config: OAuthProviderConfig) => OAuthProvider;
+/** The adapters shipped with the server. A deployment adds its credentials and gets the provider; nothing else. */
+export declare const BUILT_IN_PROVIDERS: Partial<Record<string, OAuthProviderFactory>>;
+export interface SocialAuthConfig {
+    /** Signs the flow state the browser carries between the two legs. */
+    secret: string;
+    /** How long a started flow stays valid. Defaults to ten minutes — long enough to sign in, short enough to matter. */
+    stateTtl?: number;
+    /** Where the browser lands when the caller asked for nowhere in particular. */
+    defaultRedirect: string;
+    /** Extra origins a caller may name as its landing page. The default target's origin is always allowed. */
+    allowedRedirects?: string[];
+    /** `<base>/auth/<id>/callback` unless a provider's own config names one. */
+    callbackBaseUrl?: string;
+    loginBaseUrl?: string;
+}
+export interface SocialAuthAdapters {
+    /**
+     * Turn a provider profile into an account here, linking or creating as the deployment sees fit. Throwing an
+     * {@link OAuthFailure} reports the reason to the browser; anything else is a server error.
+     */
+    linkAccount: (provider: string, profile: OAuthProfile) => Promise<AccountRecord>;
+}
+export type StartedFlow = {
+    redirectTo: string;
+    stateCookie: string;
+    ttl: number;
+};
+export type CompletedFlow = {
+    ok: true;
+    redirectTo: string;
+    account: AccountRecord;
+} | {
+    ok: false;
+    redirectTo?: string;
+    error: string;
+    reason: OAuthFailureReason;
+};
+/**
+ * Social sign-in, as two functions and a list.
+ *
+ * The authorization-code grant is the same everywhere and none of it is anyone's product: the CSRF nonce, PKCE, the
+ * vetted redirect, the token exchange, reading the profile. What differs per deployment is which providers it has
+ * credentials for and what it does with the person who comes back — so those are the adapters, and everything else
+ * is here, once.
+ *
+ * Neither function touches a response: `start` hands back where to send the browser and the state to store, and
+ * `complete` hands back where to send it next and who came back. The binding mints the session and writes cookies.
+ */
+export declare const createSocialAuth: ({ config, adapters, providers: configured, customProviders }: {
+    config: SocialAuthConfig;
+    adapters: SocialAuthAdapters;
+    /** Credentials per provider id. One with no client id or secret is simply not registered. */
+    providers: Record<string, Partial<OAuthProviderConfig> | undefined>;
+    /** Adapters for providers the server does not ship, merged over the built-in ones and selected the same way. */
+    customProviders?: Partial<Record<string, OAuthProviderFactory>>;
+}) => {
+    /** Registered providers, so a front-end renders exactly the buttons that will work. */
+    list: () => {
+        id: string;
+        label: string;
+        url: string;
+    }[];
+    get: (id: string) => OAuthProvider | undefined;
+    start: (providerId: string, redirect: unknown) => StartedFlow | undefined;
+    complete: (providerId: string, params: {
+        code?: string;
+        state?: string;
+        error?: string;
+        stateCookie?: string;
+    }) => Promise<CompletedFlow>;
+};
+export type SocialAuth = ReturnType<typeof createSocialAuth>;

package/dist/core/auth/oauth/index.js

@@ -0,0 +1,113 @@
+import { OAuthFailure } from "./types.js";
+import { buildAuthorizationUrl, exchangeCodeForToken, requestProfileJson } from "./client.js";
+import { createGitHubProvider } from "./providers/github.js";
+import { createGoogleProvider } from "./providers/google.js";
+import { codeChallenge, consumeFlow, startFlow } from "./state.js";
+//#region src/core/auth/oauth/index.ts
+/** The adapters shipped with the server. A deployment adds its credentials and gets the provider; nothing else. */
+var BUILT_IN_PROVIDERS = {
+	google: createGoogleProvider,
+	github: createGitHubProvider
+};
+var originOf = (value) => {
+	try {
+		return new URL(value).origin;
+	} catch {
+		return null;
+	}
+};
+/**
+* Social sign-in, as two functions and a list.
+*
+* The authorization-code grant is the same everywhere and none of it is anyone's product: the CSRF nonce, PKCE, the
+* vetted redirect, the token exchange, reading the profile. What differs per deployment is which providers it has
+* credentials for and what it does with the person who comes back — so those are the adapters, and everything else
+* is here, once.
+*
+* Neither function touches a response: `start` hands back where to send the browser and the state to store, and
+* `complete` hands back where to send it next and who came back. The binding mints the session and writes cookies.
+*/
+var createSocialAuth = ({ config, adapters, providers: configured, customProviders = {} }) => {
+	const stateTtl = config.stateTtl ?? 600;
+	const registry = /* @__PURE__ */ new Map();
+	for (const [id, credentials] of Object.entries(configured)) {
+		const factory = customProviders[id] ?? BUILT_IN_PROVIDERS[id];
+		if (!factory || !credentials?.clientId || !credentials.clientSecret) continue;
+		registry.set(id, factory({
+			clientId: credentials.clientId,
+			clientSecret: credentials.clientSecret,
+			redirectUri: credentials.redirectUri || `${config.callbackBaseUrl ?? ""}/auth/${id}/callback`
+		}));
+	}
+	const sanitizeRedirect = (target) => {
+		const fallback = config.defaultRedirect;
+		if (typeof target !== "string" || target === "") return fallback;
+		if (target.startsWith("/") && !target.startsWith("//") && !target.startsWith("/\\")) return target;
+		const origin = originOf(target);
+		if (!origin) return fallback;
+		return [fallback, ...config.allowedRedirects ?? []].map(originOf).filter((value) => value !== null).includes(origin) ? target : fallback;
+	};
+	const withError = (target, reason) => `${target}${target.includes("?") ? "&" : "?"}error=${encodeURIComponent(reason)}`;
+	return {
+		/** Registered providers, so a front-end renders exactly the buttons that will work. */
+		list: () => [...registry.values()].map((provider) => ({
+			id: provider.id,
+			label: provider.label,
+			url: `${config.loginBaseUrl ?? config.callbackBaseUrl ?? ""}/auth/${provider.id}/login`
+		})),
+		get: (id) => registry.get(id),
+		start: (providerId, redirect) => {
+			const provider = registry.get(providerId);
+			if (!provider) return;
+			const { state, cookie } = startFlow(provider.id, sanitizeRedirect(redirect), config.secret, stateTtl);
+			return {
+				redirectTo: buildAuthorizationUrl(provider, state, codeChallenge(state.verifier)),
+				stateCookie: cookie,
+				ttl: stateTtl
+			};
+		},
+		complete: async (providerId, params) => {
+			const provider = registry.get(providerId);
+			if (!provider) return {
+				ok: false,
+				error: "Unknown provider",
+				reason: "invalid_state"
+			};
+			const flow = consumeFlow(params.stateCookie, provider.id, params.state, config.secret);
+			if (!flow) return {
+				ok: false,
+				error: "Invalid or expired authorization state",
+				reason: "invalid_state"
+			};
+			if (params.error || !params.code) {
+				const reason = params.error ? "access_denied" : "invalid_state";
+				return {
+					ok: false,
+					redirectTo: withError(flow.redirect, reason),
+					error: params.error ?? "",
+					reason
+				};
+			}
+			try {
+				const accessToken = await exchangeCodeForToken(provider, params.code, flow);
+				const profile = await provider.fetchProfile(accessToken);
+				const account = await adapters.linkAccount(provider.id, profile);
+				return {
+					ok: true,
+					redirectTo: flow.redirect,
+					account
+				};
+			} catch (error) {
+				const reason = error instanceof OAuthFailure ? error.reason : "server_error";
+				return {
+					ok: false,
+					redirectTo: withError(flow.redirect, reason),
+					error: error instanceof Error ? error.message : "server_error",
+					reason
+				};
+			}
+		}
+	};
+};
+//#endregion
+export { BUILT_IN_PROVIDERS, OAuthFailure, createSocialAuth, requestProfileJson };

package/dist/core/auth/oauth/providers/github.d.ts

@@ -0,0 +1,2 @@
+import { OAuthProvider, OAuthProviderConfig } from '../types';
+export declare const createGitHubProvider: (config: OAuthProviderConfig) => OAuthProvider;

package/dist/core/auth/oauth/providers/github.js

@@ -0,0 +1,48 @@
+import { requestProfileJson } from "../client.js";
+//#region src/core/auth/oauth/providers/github.ts
+var USER_URL = "https://api.github.com/user";
+var EMAILS_URL = "https://api.github.com/user/emails";
+var apiHeaders = (accessToken) => ({
+	Authorization: `Bearer ${accessToken}`,
+	Accept: "application/vnd.github+json",
+	"X-GitHub-Api-Version": "2022-11-28",
+	"User-Agent": "plitzi-sdk-server"
+});
+var createGitHubProvider = (config) => ({
+	id: "github",
+	label: "GitHub",
+	config,
+	authorizationUrl: "https://github.com/login/oauth/authorize",
+	tokenUrl: "https://github.com/login/oauth/access_token",
+	scope: "read:user user:email",
+	usePkce: false,
+	async verifyAudience(accessToken) {
+		const credentials = Buffer.from(`${config.clientId}:${config.clientSecret}`).toString("base64");
+		return (await fetch(`https://api.github.com/applications/${config.clientId}/token`, {
+			method: "POST",
+			headers: {
+				Authorization: `Basic ${credentials}`,
+				Accept: "application/vnd.github+json",
+				"X-GitHub-Api-Version": "2022-11-28",
+				"User-Agent": "plitzi-sdk-server",
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify({ access_token: accessToken })
+		})).ok;
+	},
+	async fetchProfile(accessToken) {
+		const headers = apiHeaders(accessToken);
+		const user = await requestProfileJson(USER_URL, headers);
+		const emails = await requestProfileJson(EMAILS_URL, headers);
+		const verified = emails.find((entry) => entry.primary && entry.verified) ?? emails.find((entry) => entry.verified);
+		const address = verified ?? emails.find((entry) => entry.primary) ?? emails.at(0);
+		return {
+			id: String(user.id),
+			email: address?.email ?? user.email ?? "",
+			emailVerified: verified !== void 0,
+			username: user.name ?? user.login
+		};
+	}
+});
+//#endregion
+export { createGitHubProvider };

package/dist/core/auth/oauth/providers/google.d.ts

@@ -0,0 +1,2 @@
+import { OAuthProvider, OAuthProviderConfig } from '../types';
+export declare const createGoogleProvider: (config: OAuthProviderConfig) => OAuthProvider;

package/dist/core/auth/oauth/providers/google.js

@@ -0,0 +1,30 @@
+import { requestProfileJson } from "../client.js";
+//#region src/core/auth/oauth/providers/google.ts
+var USERINFO_URL = "https://openidconnect.googleapis.com/v1/userinfo";
+var TOKENINFO_URL = "https://oauth2.googleapis.com/tokeninfo";
+var createGoogleProvider = (config) => ({
+	id: "google",
+	label: "Google",
+	config,
+	authorizationUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+	tokenUrl: "https://oauth2.googleapis.com/token",
+	scope: "openid email profile",
+	usePkce: true,
+	authorizationParams: { prompt: "select_account" },
+	async verifyAudience(accessToken) {
+		const response = await fetch(`${TOKENINFO_URL}?access_token=${encodeURIComponent(accessToken)}`);
+		if (!response.ok) return false;
+		return (await response.json()).aud === config.clientId;
+	},
+	async fetchProfile(accessToken) {
+		const profile = await requestProfileJson(USERINFO_URL, { Authorization: `Bearer ${accessToken}` });
+		return {
+			id: profile.sub,
+			email: profile.email ?? "",
+			emailVerified: profile.email_verified === true,
+			username: profile.name ?? ""
+		};
+	}
+});
+//#endregion
+export { createGoogleProvider };

package/dist/core/auth/oauth/state.d.ts

@@ -0,0 +1,23 @@
+export interface OAuthFlowState {
+    provider: string;
+    nonce: string;
+    verifier: string;
+    redirect: string;
+}
+export declare const codeChallenge: (verifier: string) => string;
+/**
+ * Starts a flow. The whole state is signed into a value the browser holds, and the provider only ever sees the
+ * nonce: that is what binds the callback to the browser that began it, and it keeps the PKCE verifier out of every
+ * URL the authorization code travels through.
+ *
+ * The value is returned rather than written — whoever calls this owns the cookie.
+ */
+export declare const startFlow: (provider: string, redirect: string, secret: string, ttlSeconds: number) => {
+    state: OAuthFlowState;
+    cookie: string;
+};
+/**
+ * Reads back the flow started above. Null unless the value is intact, unexpired, for this same provider, and its
+ * nonce matches the one the provider echoed back — the four things that together make a callback trustworthy.
+ */
+export declare const consumeFlow: (cookie: string | undefined, provider: string, nonce: unknown, secret: string) => OAuthFlowState | null;

package/dist/core/auth/oauth/state.js

@@ -0,0 +1,55 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import jwt from "jsonwebtoken";
+//#region src/core/auth/oauth/state.ts
+var base64Url = (value) => value.toString("base64url");
+var createCodeVerifier = () => base64Url(randomBytes(32));
+var codeChallenge = (verifier) => base64Url(createHash("sha256").update(verifier).digest());
+var equals = (a, b) => {
+	const left = Buffer.from(a);
+	const right = Buffer.from(b);
+	return left.length === right.length && timingSafeEqual(left, right);
+};
+/**
+* Starts a flow. The whole state is signed into a value the browser holds, and the provider only ever sees the
+* nonce: that is what binds the callback to the browser that began it, and it keeps the PKCE verifier out of every
+* URL the authorization code travels through.
+*
+* The value is returned rather than written — whoever calls this owns the cookie.
+*/
+var startFlow = (provider, redirect, secret, ttlSeconds) => {
+	const state = {
+		provider,
+		nonce: base64Url(randomBytes(16)),
+		verifier: createCodeVerifier(),
+		redirect
+	};
+	return {
+		state,
+		cookie: jwt.sign(state, secret, {
+			algorithm: "HS256",
+			expiresIn: ttlSeconds
+		})
+	};
+};
+/**
+* Reads back the flow started above. Null unless the value is intact, unexpired, for this same provider, and its
+* nonce matches the one the provider echoed back — the four things that together make a callback trustworthy.
+*/
+var consumeFlow = (cookie, provider, nonce, secret) => {
+	if (!cookie || typeof nonce !== "string" || nonce === "") return null;
+	let claims;
+	try {
+		claims = jwt.verify(cookie, secret, { algorithms: ["HS256"] });
+	} catch {
+		return null;
+	}
+	if (claims.provider !== provider || !equals(claims.nonce, nonce)) return null;
+	return {
+		provider: claims.provider,
+		nonce: claims.nonce,
+		verifier: claims.verifier,
+		redirect: claims.redirect
+	};
+};
+//#endregion
+export { codeChallenge, consumeFlow, startFlow };

package/dist/core/auth/oauth/types.d.ts

@@ -0,0 +1,51 @@
+export interface OAuthProviderConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+/**
+ * The identity a provider reports back. `emailVerified` is what makes linking safe: an incoming account may only be
+ * matched onto an existing one by an address the provider itself checked.
+ */
+export interface OAuthProfile {
+    id: string;
+    email: string;
+    emailVerified: boolean;
+    username: string;
+}
+/**
+ * What every social provider declares. Everything shared by the authorization-code grant — the redirect, the CSRF
+ * nonce, PKCE, the token exchange, issuing the session — is the flow's; an adapter only names this provider's
+ * endpoints and maps its user payload onto {@link OAuthProfile}.
+ */
+export interface OAuthProvider {
+    /** Route segment (`/auth/<id>`) and the value stored against the linked identity. Never change it once users exist. */
+    id: string;
+    label: string;
+    config: OAuthProviderConfig;
+    authorizationUrl: string;
+    tokenUrl: string;
+    scope: string;
+    /** PKCE is only sent to providers that implement RFC 7636; GitHub OAuth apps ignore the challenge. */
+    usePkce: boolean;
+    /** Provider-specific extras for the authorization request (Google's `prompt`, for instance). */
+    authorizationParams?: Record<string, string>;
+    /** Extra headers on the token request. GitHub returns form-encoded bodies unless asked for JSON. */
+    tokenHeaders?: Record<string, string>;
+    fetchProfile: (accessToken: string) => Promise<OAuthProfile>;
+    /**
+     * Proves a token was issued **for this application**, and not merely that it is a valid token belonging to
+     * somebody. Only the credential exchange needs it, where the token arrives from a browser rather than from a code
+     * this server redeemed itself — without it, any other site the user signed into with the same provider could
+     * present their token here and be issued a session as them. An adapter that cannot check leaves it undefined, and
+     * the exchange refuses that provider outright.
+     */
+    verifyAudience?: (accessToken: string) => Promise<boolean>;
+}
+export type OAuthFailureReason = 'access_denied' | 'invalid_state' | 'exchange_failed' | 'profile_failed' | 'email_unverified' | 'email_missing' | 'account_inactive' | 'server_error';
+/** Carried all the way to the browser as `?error=<reason>` on the redirect target, so a front-end can tell "you
+ *  cancelled" from "that account is disabled" without parsing prose. */
+export declare class OAuthFailure extends Error {
+    readonly reason: OAuthFailureReason;
+    constructor(reason: OAuthFailureReason, message: string);
+}

package/dist/core/auth/oauth/types.js

@@ -0,0 +1,13 @@
+//#region src/core/auth/oauth/types.ts
+/** Carried all the way to the browser as `?error=<reason>` on the redirect target, so a front-end can tell "you
+*  cancelled" from "that account is disabled" without parsing prose. */
+var OAuthFailure = class extends Error {
+	reason;
+	constructor(reason, message) {
+		super(message);
+		this.name = "OAuthFailure";
+		this.reason = reason;
+	}
+};
+//#endregion
+export { OAuthFailure };