@starklabs/forge 1.3.25-builtin-configs.0 → 2.0.0

package/dist/oauth/OAuthProvider.d.ts

@@ -0,0 +1,80 @@
+import { BadGatewayError } from "../errors/index.js";
+/** Credentials and tweaks every provider accepts. */
+export interface OAuthClientOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Replaces the provider's default scopes. */
+    scopes?: string[];
+    /** Extra authorization-URL parameters (e.g. Google `prompt: "select_account"`). Security parameters cannot be overridden. */
+    authorizationParams?: Record<string, string>;
+    /** Inject a custom `fetch` (tests, proxies, retries). */
+    fetch?: typeof fetch;
+    /** Network timeout for calls to the provider. @default 10000 */
+    timeoutMs?: number;
+}
+/** What the provider returned from the token endpoint. */
+export interface TokenSet {
+    accessToken: string;
+    tokenType?: string | undefined;
+    scope?: string | undefined;
+    idToken?: string | undefined;
+    raw: Record<string, unknown>;
+}
+/** The provider-independent view of "who just signed in". */
+export interface OAuthProfile {
+    /** The provider's stable user id (never the e-mail address). */
+    providerUserId: string;
+    email?: string | undefined;
+    /** True only if the *provider* vouches that the user controls `email`. */
+    emailVerified: boolean;
+    name?: string | undefined;
+    avatarUrl?: string | undefined;
+}
+export interface AuthorizationParams {
+    state: string;
+    redirectUri: string;
+    /** PKCE S256 challenge. Ignored when the provider does not support PKCE. */
+    codeChallenge?: string | undefined;
+}
+export interface ProviderResponse {
+    status: number;
+    ok: boolean;
+    body: unknown;
+}
+/**
+ * Base class for "Sign in with ..." providers (OAuth 2.0 authorization-code flow).
+ *
+ * It implements everything the providers share - authorization URL, PKCE, the code
+ * exchange and error mapping. A concrete provider only declares its endpoints and how
+ * to turn the access token into an {@link OAuthProfile}. See `GoogleProvider` and
+ * `GitHubProvider`; a new provider is typically 40 lines.
+ */
+export declare abstract class OAuthProvider {
+    protected readonly options: OAuthClientOptions;
+    /** URL segment and identifier: lowercase letters, digits and dashes (e.g. `"google"`). */
+    abstract readonly name: string;
+    /** Human-readable name for buttons ("Google"). */
+    abstract readonly displayName: string;
+    protected abstract readonly authorizationEndpoint: string;
+    protected abstract readonly tokenEndpoint: string;
+    protected abstract readonly defaultScopes: readonly string[];
+    /** Set to `false` for providers that reject PKCE parameters. State protection stays on. */
+    readonly usesPkce: boolean;
+    protected readonly scopeSeparator: string;
+    /** Parameters this provider always adds to the authorization URL. */
+    protected readonly defaultAuthorizationParams: Readonly<Record<string, string>>;
+    constructor(options: OAuthClientOptions);
+    /** Turns an access token into the user's profile. Provider specific. */
+    abstract fetchProfile(tokens: TokenSet): Promise<OAuthProfile>;
+    /** The URL to send the browser to. */
+    buildAuthorizationUrl(params: AuthorizationParams): string;
+    /** Swaps the one-time `code` for tokens (server-to-server, with the client secret). */
+    exchangeCode(code: string, redirectUri: string, codeVerifier?: string): Promise<TokenSet>;
+    /** GET a JSON resource from the provider's API with the user's access token. */
+    protected getJson(url: string, tokens: TokenSet, headers?: Record<string, string>): Promise<ProviderResponse>;
+    protected request(url: string, init: RequestInit): Promise<ProviderResponse>;
+    /** A safe-to-show upstream failure: only the provider's short error *code* is exposed, never bodies or secrets. */
+    protected failure(operation: string, status: number, providerError?: string): BadGatewayError;
+    protected asRecord(value: unknown): Record<string, unknown>;
+}
+//# sourceMappingURL=OAuthProvider.d.ts.map

package/dist/oauth/OAuthProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProvider.d.ts","sourceRoot":"","sources":["../../src/oauth/OAuthProvider.ts"],"names":[],"mappings":"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"}

package/dist/oauth/OAuthProvider.js

@@ -0,0 +1,127 @@
+import { BadGatewayError, BadRequestError, ConfigurationError, ErrorCode } from "../errors/index.js";
+/** Parameters the framework controls: configuration can never weaken or replace them. */
+const RESERVED = new Set(["response_type", "client_id", "redirect_uri", "scope", "state", "code_challenge", "code_challenge_method"]);
+/** Token-endpoint errors that mean "this code is no good" (user can simply retry) rather than "the provider is broken". */
+const CODE_ERRORS = new Set(["invalid_grant", "bad_verification_code"]);
+/**
+ * Base class for "Sign in with ..." providers (OAuth 2.0 authorization-code flow).
+ *
+ * It implements everything the providers share - authorization URL, PKCE, the code
+ * exchange and error mapping. A concrete provider only declares its endpoints and how
+ * to turn the access token into an {@link OAuthProfile}. See `GoogleProvider` and
+ * `GitHubProvider`; a new provider is typically 40 lines.
+ */
+export class OAuthProvider {
+    options;
+    /** Set to `false` for providers that reject PKCE parameters. State protection stays on. */
+    usesPkce = true;
+    scopeSeparator = " ";
+    /** Parameters this provider always adds to the authorization URL. */
+    defaultAuthorizationParams = {};
+    constructor(options) {
+        this.options = options;
+        if (!options.clientId || typeof options.clientId !== "string") {
+            throw new ConfigurationError({ message: "An OAuth provider needs a non-empty 'clientId'." });
+        }
+        if (!options.clientSecret || typeof options.clientSecret !== "string") {
+            throw new ConfigurationError({ message: "An OAuth provider needs a non-empty 'clientSecret'." });
+        }
+    }
+    /** The URL to send the browser to. */
+    buildAuthorizationUrl(params) {
+        const query = new URLSearchParams({
+            response_type: "code",
+            client_id: this.options.clientId,
+            redirect_uri: params.redirectUri,
+            scope: (this.options.scopes ?? this.defaultScopes).join(this.scopeSeparator),
+            state: params.state,
+        });
+        if (this.usesPkce && params.codeChallenge) {
+            query.set("code_challenge", params.codeChallenge);
+            query.set("code_challenge_method", "S256");
+        }
+        for (const [key, value] of Object.entries({ ...this.defaultAuthorizationParams, ...this.options.authorizationParams })) {
+            if (!RESERVED.has(key))
+                query.set(key, value);
+        }
+        return `${this.authorizationEndpoint}?${query.toString()}`;
+    }
+    /** Swaps the one-time `code` for tokens (server-to-server, with the client secret). */
+    async exchangeCode(code, redirectUri, codeVerifier) {
+        const form = new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: this.options.clientId,
+            client_secret: this.options.clientSecret,
+        });
+        if (this.usesPkce && codeVerifier)
+            form.set("code_verifier", codeVerifier);
+        const res = await this.request(this.tokenEndpoint, {
+            method: "POST",
+            headers: { accept: "application/json", "content-type": "application/x-www-form-urlencoded" },
+            body: form.toString(),
+        });
+        const body = this.asRecord(res.body);
+        const providerError = typeof body.error === "string" ? body.error : undefined;
+        // Some providers (GitHub) answer 200 with an `error` field.
+        if (!res.ok || providerError) {
+            if (providerError && CODE_ERRORS.has(providerError)) {
+                throw new BadRequestError({
+                    message: "The sign-in code is invalid or has expired. Please try again.",
+                    code: ErrorCode.OAUTH_CODE_INVALID,
+                });
+            }
+            throw this.failure("token exchange", res.status, providerError);
+        }
+        if (typeof body.access_token !== "string" || !body.access_token)
+            throw this.failure("token exchange", res.status, "missing_access_token");
+        return {
+            accessToken: body.access_token,
+            tokenType: typeof body.token_type === "string" ? body.token_type : undefined,
+            scope: typeof body.scope === "string" ? body.scope : undefined,
+            idToken: typeof body.id_token === "string" ? body.id_token : undefined,
+            raw: body,
+        };
+    }
+    /** GET a JSON resource from the provider's API with the user's access token. */
+    async getJson(url, tokens, headers = {}) {
+        return this.request(url, { method: "GET", headers: { accept: "application/json", authorization: `Bearer ${tokens.accessToken}`, ...headers } });
+    }
+    async request(url, init) {
+        const doFetch = this.options.fetch ?? fetch;
+        let res;
+        try {
+            // Never follow redirects with credentials attached.
+            res = await doFetch(url, { ...init, redirect: "error", signal: AbortSignal.timeout(this.options.timeoutMs ?? 10_000) });
+        }
+        catch (cause) {
+            throw new BadGatewayError({
+                message: `${this.displayName} could not be reached. Please try again.`,
+                code: ErrorCode.OAUTH_PROVIDER_ERROR,
+                details: { provider: this.name },
+                cause,
+            });
+        }
+        let body;
+        try {
+            body = await res.json();
+        }
+        catch {
+            body = undefined;
+        }
+        return { status: res.status, ok: res.ok, body };
+    }
+    /** A safe-to-show upstream failure: only the provider's short error *code* is exposed, never bodies or secrets. */
+    failure(operation, status, providerError) {
+        return new BadGatewayError({
+            message: `${this.displayName} rejected the ${operation}.`,
+            code: ErrorCode.OAUTH_PROVIDER_ERROR,
+            details: { provider: this.name, operation, status, ...(providerError ? { providerError: providerError.slice(0, 64) } : {}) },
+        });
+    }
+    asRecord(value) {
+        return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+    }
+}
+//# sourceMappingURL=OAuthProvider.js.map

package/dist/oauth/OAuthProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProvider.js","sourceRoot":"","sources":["../../src/oauth/OAuthProvider.ts"],"names":[],"mappings":"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"}

package/dist/oauth/OAuthProviderFactory.d.ts

@@ -0,0 +1,21 @@
+import { OAuthProvider, type OAuthClientOptions } from "./OAuthProvider.js";
+import { OAuthProviderRegistry } from "./OAuthProviderRegistry.js";
+export type BuiltInOAuthProvider = "google" | "github";
+/** `{ provider: "google", clientId, clientSecret }` - the shorthand for the built-in providers. */
+export interface OAuthProviderConfig extends OAuthClientOptions {
+    provider: BuiltInOAuthProvider;
+}
+/** Either the shorthand config, or a ready-made provider instance (your own subclass). */
+export type OAuthProviderEntry = OAuthProviderConfig | OAuthProvider;
+/** Builds provider instances from configuration. */
+export declare class OAuthProviderFactory {
+    private static readonly builtIn;
+    static nameOf(entry: OAuthProviderEntry): string;
+    create(entry: OAuthProviderEntry, defaults?: {
+        fetch?: typeof fetch;
+    }): OAuthProvider;
+    createRegistry(entries: readonly OAuthProviderEntry[], defaults?: {
+        fetch?: typeof fetch;
+    }): OAuthProviderRegistry;
+}
+//# sourceMappingURL=OAuthProviderFactory.d.ts.map

package/dist/oauth/OAuthProviderFactory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProviderFactory.d.ts","sourceRoot":"","sources":["../../src/oauth/OAuthProviderFactory.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAEnE,MAAM,MAAM,oBAAoB,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEvD,mGAAmG;AACnG,MAAM,WAAW,mBAAoB,SAAQ,kBAAkB;IAC7D,QAAQ,EAAE,oBAAoB,CAAC;CAChC;AAED,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,mBAAmB,GAAG,aAAa,CAAC;AAIrE,oDAAoD;AACpD,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAG5B;IAEH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,MAAM,CAE/C;IAED,MAAM,CAAC,KAAK,EAAE,kBAAkB,EAAE,QAAQ,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;KAAO,GAAG,aAAa,CAYxF;IAED,cAAc,CAAC,OAAO,EAAE,SAAS,kBAAkB,EAAE,EAAE,QAAQ,GAAE;QAAE,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;KAAO,GAAG,qBAAqB,CAIrH;CACF"}

package/dist/oauth/OAuthProviderFactory.js

@@ -0,0 +1,35 @@
+import { ConfigurationError } from "../errors/index.js";
+import { GitHubProvider } from "./GitHubProvider.js";
+import { GoogleProvider } from "./GoogleProvider.js";
+import { OAuthProvider } from "./OAuthProvider.js";
+import { OAuthProviderRegistry } from "./OAuthProviderRegistry.js";
+/** Builds provider instances from configuration. */
+export class OAuthProviderFactory {
+    static builtIn = new Map([
+        ["google", GoogleProvider],
+        ["github", GitHubProvider],
+    ]);
+    static nameOf(entry) {
+        return entry instanceof OAuthProvider ? entry.name : entry.provider;
+    }
+    create(entry, defaults = {}) {
+        if (entry instanceof OAuthProvider)
+            return entry;
+        const { provider, ...options } = entry;
+        const Type = OAuthProviderFactory.builtIn.get(provider);
+        if (!Type) {
+            throw new ConfigurationError({
+                message: `Unknown OAuth provider '${String(provider)}'.`,
+                hint: `Built-in providers: ${[...OAuthProviderFactory.builtIn.keys()].join(", ")}. For any other provider, pass an instance of your own OAuthProvider subclass.`,
+            });
+        }
+        return new Type({ ...(defaults.fetch ? { fetch: defaults.fetch } : {}), ...options });
+    }
+    createRegistry(entries, defaults = {}) {
+        const registry = new OAuthProviderRegistry();
+        for (const entry of entries)
+            registry.register(this.create(entry, defaults));
+        return registry;
+    }
+}
+//# sourceMappingURL=OAuthProviderFactory.js.map

package/dist/oauth/OAuthProviderFactory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProviderFactory.js","sourceRoot":"","sources":["../../src/oauth/OAuthProviderFactory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACrD,OAAO,EAAE,aAAa,EAA2B,MAAM,oBAAoB,CAAC;AAC5E,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAcnE,oDAAoD;AACpD,MAAM,OAAO,oBAAoB;IACvB,MAAM,CAAU,OAAO,GAAuC,IAAI,GAAG,CAAwB;QACnG,CAAC,QAAQ,EAAE,cAAc,CAAC;QAC1B,CAAC,QAAQ,EAAE,cAAc,CAAC;KAC3B,CAAC,CAAC;IAEH,MAAM,CAAC,MAAM,CAAC,KAAyB;QACrC,OAAO,KAAK,YAAY,aAAa,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,QAAQ,CAAC;IACtE,CAAC;IAED,MAAM,CAAC,KAAyB,EAAE,QAAQ,GAA6B,EAAE;QACvE,IAAI,KAAK,YAAY,aAAa;YAAE,OAAO,KAAK,CAAC;QAEjD,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QACvC,MAAM,IAAI,GAAG,oBAAoB,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,MAAM,IAAI,kBAAkB,CAAC;gBAC3B,OAAO,EAAE,2BAA2B,MAAM,CAAC,QAAQ,CAAC,IAAI;gBACxD,IAAI,EAAE,uBAAuB,CAAC,GAAG,oBAAoB,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,gFAAgF;aACjK,CAAC,CAAC;QACL,CAAC;QACD,OAAO,IAAI,IAAI,CAAC,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACxF,CAAC;IAED,cAAc,CAAC,OAAsC,EAAE,QAAQ,GAA6B,EAAE;QAC5F,MAAM,QAAQ,GAAG,IAAI,qBAAqB,EAAE,CAAC;QAC7C,KAAK,MAAM,KAAK,IAAI,OAAO;YAAE,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;QAC7E,OAAO,QAAQ,CAAC;IAClB,CAAC;CACF"}

package/dist/oauth/OAuthProviderRegistry.d.ts

@@ -0,0 +1,11 @@
+import type { OAuthProvider } from "./OAuthProvider.js";
+/** The sign-in providers enabled for this app. Add one at any time before the app is built. */
+export declare class OAuthProviderRegistry {
+    private readonly providers;
+    register(provider: OAuthProvider): this;
+    has(name: string): boolean;
+    get(name: string): OAuthProvider;
+    list(): OAuthProvider[];
+    get size(): number;
+}
+//# sourceMappingURL=OAuthProviderRegistry.d.ts.map

package/dist/oauth/OAuthProviderRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProviderRegistry.d.ts","sourceRoot":"","sources":["../../src/oauth/OAuthProviderRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAMxD,+FAA+F;AAC/F,qBAAa,qBAAqB;IAChC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoC;IAE9D,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAYtC;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzB;IAED,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,aAAa,CAS/B;IAED,IAAI,IAAI,aAAa,EAAE,CAEtB;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF"}

package/dist/oauth/OAuthProviderRegistry.js

@@ -0,0 +1,41 @@
+import { ConfigurationError, ErrorCode, NotFoundError } from "../errors/index.js";
+const NAME = /^[a-z][a-z0-9-]{1,30}$/;
+/** Used by the `/oauth/providers` route: a provider with this name would shadow it. */
+const RESERVED = new Set(["providers"]);
+/** The sign-in providers enabled for this app. Add one at any time before the app is built. */
+export class OAuthProviderRegistry {
+    providers = new Map();
+    register(provider) {
+        if (!NAME.test(provider.name) || RESERVED.has(provider.name)) {
+            throw new ConfigurationError({
+                message: `Invalid OAuth provider name '${provider.name}'.`,
+                hint: "Use 2-31 lowercase letters, digits or dashes, starting with a letter (and not 'providers').",
+            });
+        }
+        if (this.providers.has(provider.name)) {
+            throw new ConfigurationError({ message: `The OAuth provider '${provider.name}' is registered twice.` });
+        }
+        this.providers.set(provider.name, provider);
+        return this;
+    }
+    has(name) {
+        return this.providers.has(name);
+    }
+    get(name) {
+        const provider = this.providers.get(name);
+        if (!provider) {
+            throw new NotFoundError({
+                message: `Sign-in with '${name.slice(0, 40)}' is not available.`,
+                code: ErrorCode.OAUTH_PROVIDER_NOT_FOUND,
+            });
+        }
+        return provider;
+    }
+    list() {
+        return [...this.providers.values()];
+    }
+    get size() {
+        return this.providers.size;
+    }
+}
+//# sourceMappingURL=OAuthProviderRegistry.js.map

package/dist/oauth/OAuthProviderRegistry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthProviderRegistry.js","sourceRoot":"","sources":["../../src/oauth/OAuthProviderRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGlF,MAAM,IAAI,GAAG,wBAAwB,CAAC;AACtC,uFAAuF;AACvF,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;AAExC,+FAA+F;AAC/F,MAAM,OAAO,qBAAqB;IACf,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;IAE9D,QAAQ,CAAC,QAAuB;QAC9B,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,QAAQ,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAC7D,MAAM,IAAI,kBAAkB,CAAC;gBAC3B,OAAO,EAAE,gCAAgC,QAAQ,CAAC,IAAI,IAAI;gBAC1D,IAAI,EAAE,6FAA6F;aACpG,CAAC,CAAC;QACL,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YACtC,MAAM,IAAI,kBAAkB,CAAC,EAAE,OAAO,EAAE,uBAAuB,QAAQ,CAAC,IAAI,wBAAwB,EAAE,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IAED,GAAG,CAAC,IAAY;QACd,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED,GAAG,CAAC,IAAY;QACd,MAAM,QAAQ,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,aAAa,CAAC;gBACtB,OAAO,EAAE,iBAAiB,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,qBAAqB;gBAChE,IAAI,EAAE,SAAS,CAAC,wBAAwB;aACzC,CAAC,CAAC;QACL,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC;IAED,IAAI;QACF,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,CAAC;IACtC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/dist/oauth/OAuthService.d.ts

@@ -0,0 +1,62 @@
+import type { Request } from "express";
+import type { ForgeConfig } from "../config/ForgeConfig.js";
+import type { AccountLinkPolicy } from "../auth/AccountLinkPolicy.js";
+import type { SessionService, SessionTokens } from "../auth/SessionService.js";
+import type { UserProvisioner } from "../auth/UserProvisioner.js";
+import type { DataSource, Doc } from "../data/Repository.js";
+import { type TokenService } from "../security/TokenService.js";
+import type { Logger } from "../utils/Logger.js";
+import type { OAuthProviderRegistry } from "./OAuthProviderRegistry.js";
+export interface BeginResult {
+    /** Send the browser here. */
+    url: string;
+    /** Signed envelope to keep in a cookie until the provider sends the browser back. */
+    stateToken: string;
+}
+export interface CompleteInput {
+    provider: string;
+    /** Everything below comes straight from the callback request and is untrusted. */
+    code: unknown;
+    state: unknown;
+    error: unknown;
+    stateToken: string | undefined;
+    redirectUri: string;
+}
+export interface OAuthOutcome {
+    user: Doc;
+    tokens: SessionTokens;
+    created: boolean;
+    provider: string;
+    returnTo: string | undefined;
+}
+/**
+ * The "Sign in with ..." use cases, independent of HTTP and of any one provider.
+ *
+ * Security properties:
+ * - CSRF: a random `state` is bound to the browser by a signed cookie and compared in constant time.
+ * - Code interception: PKCE (S256) on providers that support it.
+ * - Account takeover: only a *provider-verified* e-mail is accepted, and linking to an existing local
+ *   account follows `accountLinking` (see {@link OAuthService.assertMayLink}).
+ * - The provider's stable user id - not the e-mail - identifies a returning user.
+ */
+export declare class OAuthService {
+    private readonly config;
+    private readonly data;
+    private readonly userModel;
+    private readonly provisioner;
+    private readonly linkPolicy;
+    private readonly registry;
+    private readonly tokens;
+    private readonly sessions;
+    private readonly logger;
+    constructor(config: ForgeConfig, data: DataSource, userModel: string, provisioner: UserProvisioner, linkPolicy: AccountLinkPolicy, registry: OAuthProviderRegistry, tokens: TokenService, sessions: SessionService, logger: Logger);
+    private get users();
+    private get identities();
+    private get oauthConfig();
+    begin(providerName: string, redirectUri: string, returnTo?: string): BeginResult;
+    complete(input: CompleteInput, req: Request): Promise<OAuthOutcome>;
+    private verifiedEmail;
+    private resolveUser;
+    private link;
+}
+//# sourceMappingURL=OAuthService.d.ts.map

package/dist/oauth/OAuthService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthService.d.ts","sourceRoot":"","sources":["../../src/oauth/OAuthService.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AACtE,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAc,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAA0B,KAAK,YAAY,EAAE,MAAM,6BAA6B,CAAC;AACxF,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAGxE,MAAM,WAAW,WAAW;IAC1B,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,kFAAkF;IAClF,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,MAAM,GAAG,SAAS,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,GAAG,CAAC;IACV,MAAM,EAAE,aAAa,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAID;;;;;;;;;GASG;AACH,qBAAa,YAAY;IAErB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAC1B,OAAO,CAAC,QAAQ,CAAC,WAAW;IAC5B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM;IATzB,YACmB,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,eAAe,EAC5B,UAAU,EAAE,iBAAiB,EAC7B,QAAQ,EAAE,qBAAqB,EAC/B,MAAM,EAAE,YAAY,EACpB,QAAQ,EAAE,cAAc,EACxB,MAAM,EAAE,MAAM,EAC7B;IAEJ,OAAO,KAAK,KAAK,GAEhB;IAED,OAAO,KAAK,UAAU,GAErB;IAED,OAAO,KAAK,WAAW,GAEtB;IAED,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,WAAW,CAe/E;IAEK,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,CAmCxE;IAED,OAAO,CAAC,aAAa;YAkBP,WAAW;YAyBX,IAAI;CAInB"}

package/dist/oauth/OAuthService.js

@@ -0,0 +1,132 @@
+import { BadRequestError, ErrorCode, ForbiddenError, UnauthorizedError } from "../errors/index.js";
+import { OAUTH_IDENTITY_MODEL } from "../data/internalModels.js";
+import { randomToken, safeEqual } from "../security/TokenService.js";
+import { pkce } from "./pkce.js";
+const EMAIL = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
+/**
+ * The "Sign in with ..." use cases, independent of HTTP and of any one provider.
+ *
+ * Security properties:
+ * - CSRF: a random `state` is bound to the browser by a signed cookie and compared in constant time.
+ * - Code interception: PKCE (S256) on providers that support it.
+ * - Account takeover: only a *provider-verified* e-mail is accepted, and linking to an existing local
+ *   account follows `accountLinking` (see {@link OAuthService.assertMayLink}).
+ * - The provider's stable user id - not the e-mail - identifies a returning user.
+ */
+export class OAuthService {
+    config;
+    data;
+    userModel;
+    provisioner;
+    linkPolicy;
+    registry;
+    tokens;
+    sessions;
+    logger;
+    constructor(config, data, userModel, provisioner, linkPolicy, registry, tokens, sessions, logger) {
+        this.config = config;
+        this.data = data;
+        this.userModel = userModel;
+        this.provisioner = provisioner;
+        this.linkPolicy = linkPolicy;
+        this.registry = registry;
+        this.tokens = tokens;
+        this.sessions = sessions;
+        this.logger = logger;
+    }
+    get users() {
+        return this.data.repository(this.userModel);
+    }
+    get identities() {
+        return this.data.repository(OAUTH_IDENTITY_MODEL);
+    }
+    get oauthConfig() {
+        return this.config.auth.oauth;
+    }
+    begin(providerName, redirectUri, returnTo) {
+        const provider = this.registry.get(providerName);
+        const state = randomToken(24);
+        const verifier = provider.usesPkce ? pkce.generateVerifier() : undefined;
+        const url = provider.buildAuthorizationUrl({
+            state,
+            redirectUri,
+            codeChallenge: verifier ? pkce.challengeFor(verifier) : undefined,
+        });
+        const stateToken = this.tokens.signOAuthState({ prv: provider.name, st: state, ...(verifier ? { cv: verifier } : {}), ...(returnTo ? { rt: returnTo } : {}) }, this.oauthConfig.stateAge);
+        return { url, stateToken };
+    }
+    async complete(input, req) {
+        const provider = this.registry.get(input.provider);
+        // 1. Is this callback the continuation of a flow *this browser* started?
+        const claims = this.tokens.verifyOAuthState(input.stateToken);
+        if (claims.prv !== provider.name || typeof input.state !== "string" || !safeEqual(claims.st, input.state)) {
+            throw new BadRequestError({
+                message: "The sign-in session does not match. Please start again.",
+                code: ErrorCode.OAUTH_STATE_INVALID,
+            });
+        }
+        // 2. The user may have pressed "Cancel" at the provider.
+        if (typeof input.error === "string" && input.error) {
+            throw new UnauthorizedError({ message: "Sign-in was cancelled or denied.", code: ErrorCode.OAUTH_ACCESS_DENIED });
+        }
+        if (typeof input.code !== "string" || input.code.length === 0 || input.code.length > 2048) {
+            throw new BadRequestError({ message: "The sign-in code is missing.", code: ErrorCode.OAUTH_CODE_INVALID });
+        }
+        // 3. Back-channel: code -> access token -> profile.
+        const tokens = await provider.exchangeCode(input.code, input.redirectUri, claims.cv);
+        const profile = await provider.fetchProfile(tokens);
+        const email = this.verifiedEmail(provider.displayName, profile);
+        // 4. Find or create the local user.
+        const { user, created } = await this.resolveUser(provider.name, profile, email);
+        return {
+            user,
+            created,
+            provider: provider.name,
+            returnTo: claims.rt,
+            tokens: await this.sessions.start(user._id, req),
+        };
+    }
+    verifiedEmail(providerName, profile) {
+        const email = profile.email?.trim().toLowerCase();
+        if (!email || !EMAIL.test(email)) {
+            throw new BadRequestError({
+                message: `${providerName} did not share an e-mail address.`,
+                code: ErrorCode.OAUTH_EMAIL_MISSING,
+                hint: "Ask for the 'email' scope, and make sure the account has an e-mail address.",
+            });
+        }
+        if (!profile.emailVerified) {
+            throw new ForbiddenError({
+                message: `Your ${providerName} e-mail address is not verified. Verify it there and try again.`,
+                code: ErrorCode.OAUTH_EMAIL_UNVERIFIED,
+            });
+        }
+        return email;
+    }
+    async resolveUser(provider, profile, email) {
+        const identity = await this.identities.findOne({ provider, providerUserId: profile.providerUserId });
+        if (identity) {
+            const user = await this.users.findById(String(identity.owner));
+            if (user) {
+                await this.identities.updateById(identity._id, { lastLoginAt: new Date(), email });
+                return { user, created: false };
+            }
+            // The local account was deleted: forget the dangling link and start fresh.
+            await this.identities.deleteById(identity._id);
+        }
+        const existing = await this.users.findOne({ [this.config.auth.fields.email]: email });
+        if (existing) {
+            this.linkPolicy.assertMayLink(this.oauthConfig.accountLinking, "OAuth sign-in");
+            await this.link(existing._id, provider, profile, email);
+            return { user: existing, created: false };
+        }
+        const user = await this.provisioner.create({ email, name: profile.name, extra: this.oauthConfig.userFromProfile?.(profile) });
+        await this.link(user._id, provider, profile, email);
+        return { user, created: true };
+    }
+    async link(userId, provider, profile, email) {
+        await this.identities.create({ owner: userId, provider, providerUserId: profile.providerUserId, email, lastLoginAt: new Date() });
+        this.logger.debug("Linked a social identity.", { provider, userId });
+    }
+}
+//# sourceMappingURL=OAuthService.js.map

package/dist/oauth/OAuthService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OAuthService.js","sourceRoot":"","sources":["../../src/oauth/OAuthService.ts"],"names":[],"mappings":"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"}

package/dist/oauth/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./OAuthProvider.js";
+export * from "./GoogleProvider.js";
+export * from "./GitHubProvider.js";
+export * from "./OAuthProviderRegistry.js";
+export * from "./OAuthProviderFactory.js";
+export * from "./OAuthService.js";
+export * from "./OAuthController.js";
+export * from "./returnPath.js";
+export * from "./pkce.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/oauth/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}

package/dist/oauth/index.js

@@ -0,0 +1,10 @@
+export * from "./OAuthProvider.js";
+export * from "./GoogleProvider.js";
+export * from "./GitHubProvider.js";
+export * from "./OAuthProviderRegistry.js";
+export * from "./OAuthProviderFactory.js";
+export * from "./OAuthService.js";
+export * from "./OAuthController.js";
+export * from "./returnPath.js";
+export * from "./pkce.js";
+//# sourceMappingURL=index.js.map

package/dist/oauth/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/oauth/index.ts"],"names":[],"mappings":"AAAA,cAAc,oBAAoB,CAAC;AACnC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,2BAA2B,CAAC;AAC1C,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}

package/dist/oauth/pkce.d.ts

@@ -0,0 +1,8 @@
+/** RFC 7636 helpers (Proof Key for Code Exchange, method S256). */
+export declare const pkce: {
+    /** 43-character URL-safe random verifier (256 bits of entropy). */
+    generateVerifier: () => string;
+    /** `BASE64URL(SHA256(verifier))` */
+    challengeFor: (verifier: string) => string;
+};
+//# sourceMappingURL=pkce.d.ts.map

package/dist/oauth/pkce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.d.ts","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAEA,mEAAmE;AACnE,eAAO,MAAM,IAAI;IACf,mEAAmE;IACnE,gBAAgB,QAAM,MAAM;IAE5B,oCAAoC;IACpC,YAAY,aAAa,MAAM,KAAG,MAAM;CACzC,CAAC"}

package/dist/oauth/pkce.js

@@ -0,0 +1,9 @@
+import { createHash, randomBytes } from "node:crypto";
+/** RFC 7636 helpers (Proof Key for Code Exchange, method S256). */
+export const pkce = {
+    /** 43-character URL-safe random verifier (256 bits of entropy). */
+    generateVerifier: () => randomBytes(32).toString("base64url"),
+    /** `BASE64URL(SHA256(verifier))` */
+    challengeFor: (verifier) => createHash("sha256").update(verifier).digest("base64url"),
+};
+//# sourceMappingURL=pkce.js.map

package/dist/oauth/pkce.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pkce.js","sourceRoot":"","sources":["../../src/oauth/pkce.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAEtD,mEAAmE;AACnE,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,mEAAmE;IACnE,gBAAgB,EAAE,GAAW,EAAE,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC;IAErE,oCAAoC;IACpC,YAAY,EAAE,CAAC,QAAgB,EAAU,EAAE,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC;CACtG,CAAC"}