@starci/auth 0.5.0 → 0.6.0

package/dist/server/flows.d.ts

@@ -1,21 +1,29 @@
 import type { HttpExchange } from "./http.js";
 import type { AuthOptions } from "./options.js";
 import type { AuthSubject } from "./ports.js";
-/** The result of the Google callback leg. */
-export interface GoogleCompletion {
+/** The result of a provider's callback leg. */
+export interface ProviderCompletion {
     /** The signed-in person. */
     readonly subject: AuthSubject;
     /** The same-site path the browser lands on. */
     readonly next: string;
 }
+/** The result of the Google callback leg (the name 0.5.0 gave it). */
+export type GoogleCompletion = ProviderCompletion;
 /** Runs the passport strategies for one request without sessions; the only caller of `passport.authenticate`. */
 export declare class AuthFlows {
     #private;
-    constructor(options: Pick<AuthOptions, "google">);
+    constructor(options: Pick<AuthOptions, "google" | "providers">);
+    /** The ids of the registered providers, in registration order. */
+    get providers(): readonly string[];
     /** Runs the local strategy over the posted body; answers the person, or throws the app's refusal. */
     authenticateLocal(exchange: HttpExchange): Promise<AuthSubject>;
-    /** Sends the browser to the Google consent screen (the response is the redirect); the optional `next` query value is kept in the state cookie. */
+    /** Sends the browser to the provider's consent screen (the response is the redirect); the optional `next` query value is kept in the state cookie. */
+    begin(id: string, exchange: HttpExchange): Promise<void>;
+    /** Finishes the provider's round trip: the state cookie, the PKCE verifier and the profile must all check out. */
+    complete(id: string, exchange: HttpExchange): Promise<ProviderCompletion>;
+    /** Sends the browser to the Google consent screen. */
     beginGoogle(exchange: HttpExchange): Promise<void>;
-    /** Finishes the Google round trip: the state cookie, the PKCE verifier and the profile must all check out. */
+    /** Finishes the Google round trip. */
     completeGoogle(exchange: HttpExchange): Promise<GoogleCompletion>;
 }

package/dist/server/flows.js

@@ -1,22 +1,31 @@
 import passport from "passport";
+import { isPlainRecord } from "@starci/common";
 import { AUTH_ERROR_CODES } from "../contracts/index.js";
 import { AuthError } from "./errors.js";
-import { isPlainRecord } from "@starci/common";
 import { sameSitePath } from "./primitives.js";
+import { GOOGLE_CODES, GOOGLE_PROVIDER_ID } from "./providers/google.js";
+import { PROVIDER_CODES } from "./providers/provider.js";
+import { providersOf } from "./providers/registry.js";
 const isSubject = (value) => isPlainRecord(value) && typeof value.userId === "string" && typeof value.email === "string";
 const isHandler = (value) => typeof value === "function";
 /** The middleware passport built; passport types it as any, so it is checked once here. */
-const handlerOf = (built) => {
+const handlerOf = (built, code) => {
     if (!isHandler(built))
-        throw new AuthError(AUTH_ERROR_CODES.GoogleUnavailable);
+        throw new AuthError(code);
     return built;
 };
 const errorOf = (error) => (error instanceof Error ? error : new Error("passport"));
+/** The code a door refuses an unregistered provider with: Google's own (as in 0.5.0), else the provider-neutral one. */
+const unavailableOf = (id) => new AuthError(id === GOOGLE_PROVIDER_ID ? GOOGLE_CODES.unavailable : PROVIDER_CODES.unavailable, { context: { provider: id } });
 /** Runs the passport strategies for one request without sessions; the only caller of `passport.authenticate`. */
 export class AuthFlows {
-    #google;
+    #providers;
     constructor(options) {
-        this.#google = options.google;
+        this.#providers = new Map(providersOf(options).map((provider) => [provider.id, provider]));
+    }
+    /** The ids of the registered providers, in registration order. */
+    get providers() {
+        return [...this.#providers.keys()];
     }
     /** Runs the local strategy over the posted body; answers the person, or throws the app's refusal. */
     authenticateLocal(exchange) {
@@ -29,25 +38,27 @@ export class AuthFlows {
                 else
                     reject(new AuthError(AUTH_ERROR_CODES.MissingCredentials));
             };
-            handlerOf(passport.authenticate("local", { session: false }, settled))(exchange.req, exchange.res, reject);
+            handlerOf(passport.authenticate("local", { session: false }, settled), AUTH_ERROR_CODES.MissingCredentials)(exchange.req, exchange.res, reject);
         });
     }
-    /** Sends the browser to the Google consent screen (the response is the redirect); the optional `next` query value is kept in the state cookie. */
-    beginGoogle(exchange) {
-        if (this.#google === null)
-            return Promise.reject(new AuthError(AUTH_ERROR_CODES.GoogleUnavailable));
+    /** Sends the browser to the provider's consent screen (the response is the redirect); the optional `next` query value is kept in the state cookie. */
+    begin(id, exchange) {
+        const provider = this.#providers.get(id);
+        if (provider === undefined)
+            return Promise.reject(unavailableOf(id));
         return new Promise((resolve, reject) => {
             exchange.res.once("finish", resolve);
-            const built = passport.authenticate("google", { session: false, prompt: "select_account" }, (error) => {
+            const built = passport.authenticate(provider.id, { session: false, ...provider.authorizeParams }, (error) => {
                 reject(errorOf(error));
             });
-            handlerOf(built)(exchange.req, exchange.res, reject);
+            handlerOf(built, provider.codes.unavailable)(exchange.req, exchange.res, reject);
         });
     }
-    /** Finishes the Google round trip: the state cookie, the PKCE verifier and the profile must all check out. */
-    completeGoogle(exchange) {
-        if (this.#google === null)
-            return Promise.reject(new AuthError(AUTH_ERROR_CODES.GoogleUnavailable));
+    /** Finishes the provider's round trip: the state cookie, the PKCE verifier and the profile must all check out. */
+    complete(id, exchange) {
+        const provider = this.#providers.get(id);
+        if (provider === undefined)
+            return Promise.reject(unavailableOf(id));
         return new Promise((resolve, reject) => {
             const settled = (error, user, info) => {
                 if (error !== null && error !== undefined) {
@@ -55,13 +66,21 @@ export class AuthFlows {
                     return;
                 }
                 if (!isSubject(user)) {
-                    reject(new AuthError(AUTH_ERROR_CODES.GoogleStateInvalid));
+                    reject(new AuthError(provider.codes.stateInvalid, { context: { provider: provider.id } }));
                     return;
                 }
                 const state = isPlainRecord(info) && isPlainRecord(info.state) ? info.state.next : undefined;
                 resolve({ subject: user, next: sameSitePath(state, "/") });
             };
-            handlerOf(passport.authenticate("google", { session: false }, settled))(exchange.req, exchange.res, reject);
+            handlerOf(passport.authenticate(provider.id, { session: false }, settled), provider.codes.unavailable)(exchange.req, exchange.res, reject);
         });
     }
+    /** Sends the browser to the Google consent screen. */
+    beginGoogle(exchange) {
+        return this.begin(GOOGLE_PROVIDER_ID, exchange);
+    }
+    /** Finishes the Google round trip. */
+    completeGoogle(exchange) {
+        return this.complete(GOOGLE_PROVIDER_ID, exchange);
+    }
 }

package/dist/server/index.d.ts

@@ -1,24 +1,24 @@
-export { AUTH_AUTHENTICATOR, AUTH_DOORS_SERVICE, AUTH_FLOWS, AUTH_GOOGLE_STATE, AUTH_GOOGLE_STRATEGY, AUTH_LOCAL_STRATEGY, AUTH_PASSWORDS, AUTH_PRINCIPAL_VERIFIER, AUTH_REFRESH_COOKIE, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET, AUTH_TOKENS } from "./auth.tokens.js";
+export { AUTH_AUTHENTICATOR, AUTH_DOORS_SERVICE, AUTH_FLOWS, AUTH_GOOGLE_STATE, AUTH_GOOGLE_STRATEGY, AUTH_LOCAL_STRATEGY, AUTH_PASSWORDS, AUTH_PRINCIPAL_VERIFIER, AUTH_PROVIDERS, AUTH_REFRESH_COOKIE, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET, AUTH_TOKENS } from "./auth.tokens.js";
 export { AuthModule, MODULE_OPTIONS_TOKEN as AUTH_OPTIONS } from "./auth.module.js";
 export type { AuthModuleExtras, AuthRegisterAsyncOptions, AuthRegisterOptions } from "./auth.module.js";
 export { SignInBudget } from "./budget.js";
 export { RefreshCookie } from "./cookie.js";
-export { AuthDoors, GOOGLE_SIGN_IN_FAILED_EVENT, SEE_OTHER, accessOf } from "./doors.js";
+export { AuthDoors, GOOGLE_SIGN_IN_FAILED_EVENT, SEE_OTHER, accessOf, providerSignInFailedEvent } from "./doors.js";
 export type { DoorsDeps } from "./doors.js";
 export { AuthError, ok, refused } from "./errors.js";
 export type { Outcome } from "./errors.js";
 export { AuthFlows } from "./flows.js";
-export type { GoogleCompletion } from "./flows.js";
-export { DEFAULT_GOOGLE_STATE_COOKIE, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient } from "./google-state.js";
+export type { GoogleCompletion, ProviderCompletion } from "./flows.js";
 export type { CookieWrite, HttpExchange, HttpRequest, HttpResponse } from "./http.js";
-export type { AuthOptions, BudgetOptions, GoogleOptions, RefreshCookieOptions, SigningKeyOptions } from "./options.js";
+export type { AuthOptions, BudgetOptions, RefreshCookieOptions, SigningKeyOptions } from "./options.js";
 export { AuthPasswords } from "./passwords.js";
-export type { AccessClaims, AccountDirectory, AccountStanding, AuthAuthenticator, AuthClock, AuthIds, AuthLogger, AuthPrincipal, AuthSubject, DeviceMeta, GoogleProfile, IssuedAccessToken, NewSession, RateCounter, RefreshTokenRecord, SessionStore, SessionTokens, SessionTransaction, } from "./ports.js";
+export type { AccessClaims, AccountDirectory, AccountStanding, AuthAuthenticator, AuthClock, AuthIds, AuthLogger, AuthPrincipal, AuthSubject, DeviceMeta, GoogleProfile, IssuedAccessToken, NewSession, ProviderProfile, RateCounter, RefreshTokenRecord, SessionStore, SessionTokens, SessionTransaction, } from "./ports.js";
 export { cookieValue, digestOf, isAcceptablePassword, isPresentablePassword, normalizeEmail, sameSitePath } from "./primitives.js";
 export type { Revealable, SecretInput } from "./primitives.js";
+export { DEFAULT_GOOGLE_STATE_COOKIE, GITHUB_ENDPOINTS, GITHUB_PROVIDER_ID, GITHUB_SCOPES, GOOGLE_CODES, GOOGLE_PROVIDER_ID, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient, OAUTH_STATE_TTL_MS, OAuthStateClient, PROVIDER_CODES, PassportGitHubStrategy, PassportGoogleStrategy, buildProviders, defineProvider, github, githubProfileOf, google, googleProfileOf, oauthStateCookie, providersOf, signInWithProvider, } from "./providers/index.js";
+export type { AnySignInProvider, GitHubOptions, GitHubRawProfile, GoogleOptions, OAuthStateDeps, OAuthStateOptions, ProviderCodes, ProviderContext, ProviderDefinition, ProviderEntry, ProviderRuntimeDeps, SignInProvider, } from "./providers/index.js";
 export { randomIds, systemClock } from "./runtime.js";
 export { AuthSessions, DEFAULT_REUSE_GRACE_MS, REFRESH_REUSE_EVENT } from "./sessions.js";
-export { googleProfileOf } from "./strategies.js";
 export { AuthTokens } from "./tokens.js";
 export { AuthPrincipalVerifier, refuseSessions } from "./verifier.js";
 export type { PrincipalVerifier } from "./verifier.js";

package/dist/server/index.js

@@ -1,15 +1,14 @@
-export { AUTH_AUTHENTICATOR, AUTH_DOORS_SERVICE, AUTH_FLOWS, AUTH_GOOGLE_STATE, AUTH_GOOGLE_STRATEGY, AUTH_LOCAL_STRATEGY, AUTH_PASSWORDS, AUTH_PRINCIPAL_VERIFIER, AUTH_REFRESH_COOKIE, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET, AUTH_TOKENS } from "./auth.tokens.js";
+export { AUTH_AUTHENTICATOR, AUTH_DOORS_SERVICE, AUTH_FLOWS, AUTH_GOOGLE_STATE, AUTH_GOOGLE_STRATEGY, AUTH_LOCAL_STRATEGY, AUTH_PASSWORDS, AUTH_PRINCIPAL_VERIFIER, AUTH_PROVIDERS, AUTH_REFRESH_COOKIE, AUTH_SESSIONS, AUTH_SIGN_IN_BUDGET, AUTH_TOKENS } from "./auth.tokens.js";
 export { AuthModule, MODULE_OPTIONS_TOKEN as AUTH_OPTIONS } from "./auth.module.js";
 export { SignInBudget } from "./budget.js";
 export { RefreshCookie } from "./cookie.js";
-export { AuthDoors, GOOGLE_SIGN_IN_FAILED_EVENT, SEE_OTHER, accessOf } from "./doors.js";
+export { AuthDoors, GOOGLE_SIGN_IN_FAILED_EVENT, SEE_OTHER, accessOf, providerSignInFailedEvent } from "./doors.js";
 export { AuthError, ok, refused } from "./errors.js";
 export { AuthFlows } from "./flows.js";
-export { DEFAULT_GOOGLE_STATE_COOKIE, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient } from "./google-state.js";
 export { AuthPasswords } from "./passwords.js";
 export { cookieValue, digestOf, isAcceptablePassword, isPresentablePassword, normalizeEmail, sameSitePath } from "./primitives.js";
+export { DEFAULT_GOOGLE_STATE_COOKIE, GITHUB_ENDPOINTS, GITHUB_PROVIDER_ID, GITHUB_SCOPES, GOOGLE_CODES, GOOGLE_PROVIDER_ID, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient, OAUTH_STATE_TTL_MS, OAuthStateClient, PROVIDER_CODES, PassportGitHubStrategy, PassportGoogleStrategy, buildProviders, defineProvider, github, githubProfileOf, google, googleProfileOf, oauthStateCookie, providersOf, signInWithProvider, } from "./providers/index.js";
 export { randomIds, systemClock } from "./runtime.js";
 export { AuthSessions, DEFAULT_REUSE_GRACE_MS, REFRESH_REUSE_EVENT } from "./sessions.js";
-export { googleProfileOf } from "./strategies.js";
 export { AuthTokens } from "./tokens.js";
 export { AuthPrincipalVerifier, refuseSessions } from "./verifier.js";

package/dist/server/options.d.ts

@@ -1,5 +1,7 @@
 import type { SecretInput } from "./primitives.js";
 import type { AccountDirectory, AuthClock, AuthIds, AuthLogger, RateCounter, SessionStore } from "./ports.js";
+import type { GoogleOptions } from "./providers/google.js";
+import type { AnySignInProvider } from "./providers/provider.js";
 /** One signing key of the key set. */
 export interface SigningKeyOptions {
     /** The public key (SPKI PEM) published at the JWKS door. Derived from the private key when absent; a verify-only key needs it. */
@@ -9,17 +11,8 @@ export interface SigningKeyOptions {
     /** The `kid` of the key; the RFC 7638 thumbprint of the public key when absent. */
     readonly keyId?: string | undefined;
 }
-/** The Google OAuth client and where Google sends the browser back. */
-export interface GoogleOptions {
-    /** The public client id. */
-    readonly clientId: string;
-    /** The client secret. */
-    readonly clientSecret: SecretInput;
-    /** The registered callback address (`<api>/auth/google/callback`). */
-    readonly callbackUrl: string;
-    /** The name of the cookie that carries one Google round trip. */
-    readonly stateCookie?: string | undefined;
-}
+/** The Google OAuth client: declared beside the Google provider, named here as 0.5.0 did. */
+export type { GoogleOptions } from "./providers/google.js";
 /** The refresh cookie. */
 export interface RefreshCookieOptions {
     /** The cookie name. */
@@ -65,8 +58,13 @@ export interface AuthOptions {
     readonly bcryptCost: number;
     /** The origin of the web app: a return address is accepted only on this origin, and the Google callback lands there. */
     readonly returnOrigin: string;
-    /** The Google client; null when the deployment has none (the Google door is then unavailable). */
-    readonly google: GoogleOptions | null;
+    /**
+     * The Google client of 0.5.0; null or absent when the deployment has none (the Google door is then unavailable). The same as listing
+     * `google({...})` in `providers`; naming Google both ways is a configuration error.
+     */
+    readonly google?: GoogleOptions | null | undefined;
+    /** The sign-in providers beyond email and password (`[google({...}), github({...})]`), each served at `/auth/<id>` and `/auth/<id>/callback`. */
+    readonly providers?: readonly AnySignInProvider[] | undefined;
     /** The refresh cookie. */
     readonly cookie: RefreshCookieOptions;
     /** The sign-in budget. */

package/dist/server/ports.d.ts

@@ -21,12 +21,19 @@ export interface GoogleProfile {
     /** The picture address, when released. */
     readonly picture: string | null;
 }
-/** The sign-in decisions the app makes for the two strategies; each throws the app's error when it refuses. */
+/** What any sign-in provider told us about the person who consented: Google's facts, with the provider that told them. */
+export interface ProviderProfile extends GoogleProfile {
+    /** The provider id (`github`); with `subject` it names the external account. */
+    readonly provider: string;
+}
+/** The sign-in decisions the app makes for the strategies; each throws the app's error when it refuses. */
 export interface AuthAuthenticator {
     /** Verifies an email and password; answers the person or throws. */
     verifyPassword(email: string, password: string): Promise<AuthSubject>;
     /** Finds, links or creates the person a verified Google profile stands for; answers the person or throws. */
     signInWithGoogle(profile: GoogleProfile): Promise<AuthSubject>;
+    /** Finds, links or creates the person another provider's profile stands for (GitHub); needed only when the app registers such a provider. */
+    signInWithProvider?(profile: ProviderProfile): Promise<AuthSubject>;
 }
 /** The account facts a refresh needs to decide that a session may go on. */
 export interface AccountStanding {

package/dist/server/providers/github.d.ts

@@ -0,0 +1,59 @@
+import OAuth2Strategy from "passport-oauth2";
+import type { AuthAuthenticator, AuthSubject, ProviderProfile } from "../ports.js";
+import type { SecretInput } from "../primitives.js";
+import type { OAuthStateClient } from "./oauth-state.js";
+import type { SignInProvider } from "./provider.js";
+/** The id of the GitHub provider: its passport strategy, its state purpose and its doors (`/auth/github`, `/auth/github/callback`). */
+export declare const GITHUB_PROVIDER_ID = "github";
+/** The GitHub endpoints the provider speaks to (github.com OAuth apps and the REST API). */
+export declare const GITHUB_ENDPOINTS: {
+    readonly authorization: "https://github.com/login/oauth/authorize";
+    readonly token: "https://github.com/login/oauth/access_token";
+    readonly user: "https://api.github.com/user";
+    readonly emails: "https://api.github.com/user/emails";
+};
+/** The scopes the provider asks for: the profile and the addresses with their verification. */
+export declare const GITHUB_SCOPES: readonly string[];
+/** The GitHub OAuth app and where GitHub sends the browser back. */
+export interface GitHubOptions {
+    /** The OAuth app's client id. */
+    readonly clientId: string;
+    /** The OAuth app's client secret. */
+    readonly clientSecret: SecretInput;
+    /** The registered callback address (`<api>/auth/github/callback`). */
+    readonly callbackUrl: string;
+    /** The name of the cookie that carries one GitHub round trip (`auth_github_state`). */
+    readonly stateCookie?: string | undefined;
+    /** The `User-Agent` the REST API requires (`starci-auth`). */
+    readonly userAgent?: string | undefined;
+}
+/** What the GitHub REST API answered for one person: `GET /user` and `GET /user/emails`. */
+export interface GitHubRawProfile {
+    readonly user: unknown;
+    readonly emails: unknown;
+}
+/** The facts the app needs from GitHub: the numeric account id is the subject (a login can be renamed and reused), the primary verified address, the name and the avatar. */
+export declare const githubProfileOf: (raw: GitHubRawProfile) => ProviderProfile;
+type ProfileDone = (error?: unknown, profile?: unknown) => void;
+/** passport-oauth2 against GitHub, with the profile read from the REST API (`/user`, `/user/emails`) under the access token. */
+declare class GitHubOAuth2Strategy extends OAuth2Strategy {
+    constructor(options: GitHubOptions, verify: OAuth2Strategy.VerifyFunction);
+    /**
+     * Called by passport-oauth2 once the code is exchanged: the person and their addresses, raw, for `githubProfileOf`. passport runs it on an
+     * `Object.create` of the registered strategy, so it reaches the client through the prototype (`this._oauth2`), never a private member.
+     */
+    userProfile(accessToken: string, done: ProfileDone): void;
+}
+declare const PassportGitHubStrategy_base: new (options: GitHubOptions) => GitHubOAuth2Strategy & {
+    validate(...args: any[]): unknown;
+};
+/** The GitHub OAuth strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
+export declare class PassportGitHubStrategy extends PassportGitHubStrategy_base {
+    #private;
+    constructor(options: GitHubOptions, authenticator: AuthAuthenticator, state: OAuthStateClient);
+    /** Called by passport with what GitHub answered; answers the person the app stands it for. */
+    validate(_accessToken: string, _refreshToken: string, raw: GitHubRawProfile): Promise<AuthSubject>;
+}
+/** The GitHub provider: `AuthModule.register({ providers: [github({ clientId, clientSecret, callbackUrl })] })`; the app implements `signInWithProvider`. */
+export declare const github: (options: GitHubOptions) => SignInProvider<GitHubOptions, GitHubRawProfile>;
+export {};

package/dist/server/providers/github.js

@@ -0,0 +1,111 @@
+import { PassportStrategy } from "@nestjs/passport";
+import { isPlainRecord } from "@starci/common";
+import OAuth2Strategy from "passport-oauth2";
+import { AUTH_ERROR_CODES } from "../../contracts/index.js";
+import { AuthError } from "../errors.js";
+import { revealed } from "../primitives.js";
+import { defineProvider, signInWithProvider } from "./provider.js";
+/** The id of the GitHub provider: its passport strategy, its state purpose and its doors (`/auth/github`, `/auth/github/callback`). */
+export const GITHUB_PROVIDER_ID = "github";
+/** The GitHub endpoints the provider speaks to (github.com OAuth apps and the REST API). */
+export const GITHUB_ENDPOINTS = {
+    authorization: "https://github.com/login/oauth/authorize",
+    token: "https://github.com/login/oauth/access_token",
+    user: "https://api.github.com/user",
+    emails: "https://api.github.com/user/emails",
+};
+/** The scopes the provider asks for: the profile and the addresses with their verification. */
+export const GITHUB_SCOPES = ["read:user", "user:email"];
+const text = (value) => (typeof value === "string" && value !== "" ? value : null);
+/** The address to trust: the primary verified one, else any verified one, else the public profile address (unverified). */
+const addressOf = (user, emails) => {
+    const listed = Array.isArray(emails) ? emails.filter(isPlainRecord) : [];
+    const verified = listed.filter((entry) => entry.verified === true && text(entry.email) !== null);
+    const chosen = verified.find((entry) => entry.primary === true) ?? verified[0];
+    if (chosen !== undefined)
+        return { email: text(chosen.email), verified: true };
+    return { email: text(user.email), verified: false };
+};
+/** The facts the app needs from GitHub: the numeric account id is the subject (a login can be renamed and reused), the primary verified address, the name and the avatar. */
+export const githubProfileOf = (raw) => {
+    const user = raw.user;
+    if (!isPlainRecord(user) || typeof user.id !== "number" || !Number.isSafeInteger(user.id) || user.id <= 0)
+        throw new AuthError(AUTH_ERROR_CODES.ProviderRejected, { context: { provider: GITHUB_PROVIDER_ID } });
+    const address = addressOf(user, raw.emails);
+    return {
+        provider: GITHUB_PROVIDER_ID,
+        subject: String(user.id),
+        email: address.email,
+        emailVerified: address.verified,
+        name: text(user.name) ?? text(user.login),
+        picture: text(user.avatar_url),
+    };
+};
+const parsed = (body) => {
+    try {
+        return JSON.parse(typeof body === "string" ? body : (body?.toString("utf8") ?? ""));
+    }
+    catch {
+        return undefined;
+    }
+};
+/** passport-oauth2 against GitHub, with the profile read from the REST API (`/user`, `/user/emails`) under the access token. */
+class GitHubOAuth2Strategy extends OAuth2Strategy {
+    constructor(options, verify) {
+        super({
+            authorizationURL: GITHUB_ENDPOINTS.authorization,
+            tokenURL: GITHUB_ENDPOINTS.token,
+            clientID: options.clientId,
+            clientSecret: revealed(options.clientSecret),
+            callbackURL: options.callbackUrl,
+            scope: [...GITHUB_SCOPES],
+            customHeaders: { "User-Agent": options.userAgent ?? "starci-auth", Accept: "application/json" },
+            state: true,
+            pkce: true,
+        }, verify);
+        this.name = GITHUB_PROVIDER_ID;
+        this._oauth2.useAuthorizationHeaderforGET(true);
+    }
+    /**
+     * Called by passport-oauth2 once the code is exchanged: the person and their addresses, raw, for `githubProfileOf`. passport runs it on an
+     * `Object.create` of the registered strategy, so it reaches the client through the prototype (`this._oauth2`), never a private member.
+     */
+    userProfile(accessToken, done) {
+        const read = (url) => new Promise((resolve, reject) => {
+            // node-oauth types the error as always present; it is null on success.
+            this._oauth2.get(url, accessToken, (error, body) => {
+                if (error === null || error === undefined)
+                    resolve(parsed(body));
+                else
+                    reject(new AuthError(AUTH_ERROR_CODES.ProviderRejected, { context: { provider: GITHUB_PROVIDER_ID, status: isPlainRecord(error) ? error.statusCode : undefined } }));
+            });
+        });
+        Promise.all([read(GITHUB_ENDPOINTS.user), read(GITHUB_ENDPOINTS.emails)]).then(([user, emails]) => {
+            done(null, { user, emails });
+        }, (error) => {
+            done(error);
+        });
+    }
+}
+/** The GitHub OAuth strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
+export class PassportGitHubStrategy extends PassportStrategy(GitHubOAuth2Strategy, GITHUB_PROVIDER_ID) {
+    #authenticator;
+    constructor(options, authenticator, state) {
+        super(options);
+        this.#authenticator = authenticator;
+        // passport-oauth2 types describe only its session stores; the stateless PKCE store replaces the one it built.
+        Object.assign(this, { _stateStore: state });
+    }
+    /** Called by passport with what GitHub answered; answers the person the app stands it for. */
+    validate(_accessToken, _refreshToken, raw) {
+        return signInWithProvider(this.#authenticator, githubProfileOf(raw));
+    }
+}
+/** The GitHub provider: `AuthModule.register({ providers: [github({ clientId, clientSecret, callbackUrl })] })`; the app implements `signInWithProvider`. */
+export const github = (options) => defineProvider({
+    id: GITHUB_PROVIDER_ID,
+    options,
+    stateCookie: options.stateCookie,
+    profileOf: githubProfileOf,
+    strategy: ({ authenticator, state }) => new PassportGitHubStrategy(options, authenticator, state),
+});

package/dist/server/providers/google.d.ts

@@ -0,0 +1,56 @@
+import { Strategy as GoogleStrategy } from "passport-google-oauth20";
+import type { Profile } from "passport-google-oauth20";
+import type { AuthOptions } from "../options.js";
+import type { AuthAuthenticator, AuthClock, AuthIds, AuthSubject, GoogleProfile } from "../ports.js";
+import type { SecretInput } from "../primitives.js";
+import type { AuthTokens } from "../tokens.js";
+import { OAuthStateClient } from "./oauth-state.js";
+import type { ProviderCodes, SignInProvider } from "./provider.js";
+/** The id of the Google provider: its passport strategy, its state purpose and its doors (`/auth/google`). */
+export declare const GOOGLE_PROVIDER_ID = "google";
+/** The cookie that carries one Google round trip, when the options name none. */
+export declare const DEFAULT_GOOGLE_STATE_COOKIE = "auth_google_state";
+/** The only path the state cookie is sent to. */
+export declare const GOOGLE_STATE_PATH: "/auth/google";
+/** How long a Google round trip may take, in milliseconds. */
+export declare const GOOGLE_STATE_TTL_MS = 600000;
+/** The codes the Google doors refuse with: the ones 0.5.0 answered, so a front end maps them as before. */
+export declare const GOOGLE_CODES: ProviderCodes;
+/** The Google OAuth client and where Google sends the browser back. */
+export interface GoogleOptions {
+    /** The public client id. */
+    readonly clientId: string;
+    /** The client secret. */
+    readonly clientSecret: SecretInput;
+    /** The registered callback address (`<api>/auth/google/callback`). */
+    readonly callbackUrl: string;
+    /** The name of the cookie that carries one Google round trip. */
+    readonly stateCookie?: string | undefined;
+}
+/**
+ * The state store of the Google round trip: the provider-neutral store with Google's cookie (`auth_google_state` on `/auth/google`) and
+ * purpose (`p: "google"`), built from the options as in 0.5.0.
+ */
+export declare class GoogleStateClient extends OAuthStateClient {
+    constructor(deps: {
+        readonly tokens: AuthTokens;
+        readonly clock: AuthClock;
+        readonly ids: AuthIds;
+        readonly options: Pick<AuthOptions, "returnOrigin" | "google">;
+    });
+}
+/** The facts the app needs from a Google profile; an account without a subject is refused. */
+export declare const googleProfileOf: (profile: Profile) => GoogleProfile;
+declare const PassportGoogleStrategy_base: new (...args: [options: import("passport-google-oauth20").StrategyOptionsWithRequest] | [options: import("passport-google-oauth20").StrategyOptions] | [options: import("passport-google-oauth20").StrategyOptions] | [options: import("passport-google-oauth20").StrategyOptionsWithRequest]) => GoogleStrategy & {
+    validate(...args: any[]): unknown;
+};
+/** The Google OAuth 2.0 strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
+export declare class PassportGoogleStrategy extends PassportGoogleStrategy_base {
+    #private;
+    constructor(google: GoogleOptions, authenticator: AuthAuthenticator, state: OAuthStateClient);
+    /** Called by passport with Google's profile; answers the person the app stands it for. */
+    validate(_accessToken: string, _refreshToken: string, profile: Profile): Promise<AuthSubject>;
+}
+/** The Google provider: `AuthModule.register({ providers: [google({ clientId, clientSecret, callbackUrl })] })`, or the `google` option of 0.5.0. */
+export declare const google: (options: GoogleOptions) => SignInProvider<GoogleOptions, Profile>;
+export {};

package/dist/server/providers/google.js

@@ -0,0 +1,87 @@
+import { PassportStrategy } from "@nestjs/passport";
+import { Strategy as GoogleStrategy } from "passport-google-oauth20";
+import { AUTH_DOORS, AUTH_ERROR_CODES } from "../../contracts/index.js";
+import { AuthError } from "../errors.js";
+import { revealed } from "../primitives.js";
+import { OAUTH_STATE_TTL_MS, OAuthStateClient } from "./oauth-state.js";
+import { defineProvider } from "./provider.js";
+/** The id of the Google provider: its passport strategy, its state purpose and its doors (`/auth/google`). */
+export const GOOGLE_PROVIDER_ID = "google";
+/** The cookie that carries one Google round trip, when the options name none. */
+export const DEFAULT_GOOGLE_STATE_COOKIE = "auth_google_state";
+/** The only path the state cookie is sent to. */
+export const GOOGLE_STATE_PATH = AUTH_DOORS.google;
+/** How long a Google round trip may take, in milliseconds. */
+export const GOOGLE_STATE_TTL_MS = OAUTH_STATE_TTL_MS;
+/** The codes the Google doors refuse with: the ones 0.5.0 answered, so a front end maps them as before. */
+export const GOOGLE_CODES = {
+    unavailable: AUTH_ERROR_CODES.GoogleUnavailable,
+    stateInvalid: AUTH_ERROR_CODES.GoogleStateInvalid,
+    rejected: AUTH_ERROR_CODES.GoogleRejected,
+};
+/**
+ * The state store of the Google round trip: the provider-neutral store with Google's cookie (`auth_google_state` on `/auth/google`) and
+ * purpose (`p: "google"`), built from the options as in 0.5.0.
+ */
+export class GoogleStateClient extends OAuthStateClient {
+    constructor(deps) {
+        super({
+            tokens: deps.tokens,
+            clock: deps.clock,
+            ids: deps.ids,
+            state: {
+                provider: GOOGLE_PROVIDER_ID,
+                cookie: deps.options.google?.stateCookie ?? DEFAULT_GOOGLE_STATE_COOKIE,
+                path: GOOGLE_STATE_PATH,
+                returnOrigin: deps.options.returnOrigin,
+            },
+        });
+    }
+}
+const verifiedOf = (profile) => {
+    const claim = profile._json.email_verified;
+    return claim === true || claim === "true";
+};
+/** The facts the app needs from a Google profile; an account without a subject is refused. */
+export const googleProfileOf = (profile) => {
+    if (profile.id === "")
+        throw new AuthError(AUTH_ERROR_CODES.GoogleRejected);
+    return {
+        subject: profile.id,
+        email: profile.emails?.[0]?.value ?? null,
+        emailVerified: verifiedOf(profile),
+        name: profile.displayName === "" ? null : profile.displayName,
+        picture: profile.photos?.[0]?.value ?? null,
+    };
+};
+/** The Google OAuth 2.0 strategy: authorization code with `state` and PKCE (S256), the round trip held in a signed cookie. */
+export class PassportGoogleStrategy extends PassportStrategy(GoogleStrategy, GOOGLE_PROVIDER_ID) {
+    #authenticator;
+    constructor(google, authenticator, state) {
+        super({
+            clientID: google.clientId,
+            clientSecret: revealed(google.clientSecret),
+            callbackURL: google.callbackUrl,
+            scope: ["openid", "email", "profile"],
+            state: true,
+            pkce: true,
+        });
+        this.#authenticator = authenticator;
+        // passport-oauth2 types describe only its session stores; the stateless PKCE store replaces the one it built.
+        Object.assign(this, { _stateStore: state });
+    }
+    /** Called by passport with Google's profile; answers the person the app stands it for. */
+    validate(_accessToken, _refreshToken, profile) {
+        return this.#authenticator.signInWithGoogle(googleProfileOf(profile));
+    }
+}
+/** The Google provider: `AuthModule.register({ providers: [google({ clientId, clientSecret, callbackUrl })] })`, or the `google` option of 0.5.0. */
+export const google = (options) => defineProvider({
+    id: GOOGLE_PROVIDER_ID,
+    options,
+    stateCookie: options.stateCookie ?? DEFAULT_GOOGLE_STATE_COOKIE,
+    authorizeParams: { prompt: "select_account" },
+    codes: GOOGLE_CODES,
+    profileOf: (raw) => ({ provider: GOOGLE_PROVIDER_ID, ...googleProfileOf(raw) }),
+    strategy: ({ authenticator, state }) => new PassportGoogleStrategy(options, authenticator, state),
+});

package/dist/server/providers/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The sign-in providers of the lite edition: `AuthModule.register({ ...options, providers: [google({...}), github({...})] })`. A next
+ * provider (Facebook) is one file beside these that calls `defineProvider`, and one more entry in that list.
+ */
+export { DEFAULT_GOOGLE_STATE_COOKIE, GOOGLE_CODES, GOOGLE_PROVIDER_ID, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient, PassportGoogleStrategy, google, googleProfileOf } from "./google.js";
+export type { GoogleOptions } from "./google.js";
+export { GITHUB_ENDPOINTS, GITHUB_PROVIDER_ID, GITHUB_SCOPES, PassportGitHubStrategy, github, githubProfileOf } from "./github.js";
+export type { GitHubOptions, GitHubRawProfile } from "./github.js";
+export { OAUTH_STATE_TTL_MS, OAuthStateClient, oauthStateCookie } from "./oauth-state.js";
+export type { OAuthStateDeps, OAuthStateOptions } from "./oauth-state.js";
+export { PROVIDER_CODES, defineProvider, signInWithProvider } from "./provider.js";
+export type { AnySignInProvider, ProviderCodes, ProviderContext, ProviderDefinition, SignInProvider } from "./provider.js";
+export { buildProviders, providersOf } from "./registry.js";
+export type { ProviderEntry, ProviderRuntimeDeps } from "./registry.js";

package/dist/server/providers/index.js

@@ -0,0 +1,9 @@
+/**
+ * The sign-in providers of the lite edition: `AuthModule.register({ ...options, providers: [google({...}), github({...})] })`. A next
+ * provider (Facebook) is one file beside these that calls `defineProvider`, and one more entry in that list.
+ */
+export { DEFAULT_GOOGLE_STATE_COOKIE, GOOGLE_CODES, GOOGLE_PROVIDER_ID, GOOGLE_STATE_PATH, GOOGLE_STATE_TTL_MS, GoogleStateClient, PassportGoogleStrategy, google, googleProfileOf } from "./google.js";
+export { GITHUB_ENDPOINTS, GITHUB_PROVIDER_ID, GITHUB_SCOPES, PassportGitHubStrategy, github, githubProfileOf } from "./github.js";
+export { OAUTH_STATE_TTL_MS, OAuthStateClient, oauthStateCookie } from "./oauth-state.js";
+export { PROVIDER_CODES, defineProvider, signInWithProvider } from "./provider.js";
+export { buildProviders, providersOf } from "./registry.js";