@starci/auth 0.5.0 → 0.6.0

package/dist/oidc/options.js

@@ -0,0 +1,98 @@
+import { OIDC_ALGORITHMS, OIDC_DEFAULT_ALGORITHMS, OIDC_ERROR_CODES } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+import { systemClock } from "./primitives.js";
+const MINUTE_MS = 60_000;
+const HOUR_MS = 3_600_000;
+const invalid = (key) => new OidcError(OIDC_ERROR_CODES.ConfigurationInvalid, { params: { key } });
+/** True when the address is an absolute, credential-free URL on the scheme the registration admits (https; http only when allowed). */
+export const isAdmissibleUrl = (value, insecure) => {
+    if (!URL.canParse(value))
+        return false;
+    const url = new URL(value);
+    const scheme = url.protocol === "https:" || (insecure && url.protocol === "http:");
+    return scheme && url.username === "" && url.password === "" && url.hash === "";
+};
+const positive = (value, fallback, key) => {
+    const chosen = value ?? fallback;
+    if (!Number.isFinite(chosen) || chosen <= 0)
+        throw invalid(key);
+    return chosen;
+};
+const toleranceOf = (value) => {
+    const chosen = value ?? 5;
+    if (!Number.isFinite(chosen) || chosen < 0)
+        throw invalid("clockToleranceSeconds");
+    return chosen;
+};
+const audiencesOf = (audience) => {
+    const list = typeof audience === "string" ? [audience] : audience;
+    if (list.length === 0 || list.some((entry) => entry === ""))
+        throw invalid("audience");
+    return list;
+};
+const algorithmsOf = (algorithms) => {
+    const list = algorithms ?? OIDC_DEFAULT_ALGORITHMS;
+    const admitted = OIDC_ALGORITHMS;
+    if (list.length === 0 || list.some((algorithm) => !admitted.includes(algorithm)))
+        throw invalid("algorithms");
+    return list;
+};
+const checkClient = (client, insecure) => {
+    if (client.clientId === "")
+        throw invalid("client.clientId");
+    for (const key of ["callbackUri", "postLogoutUri"]) {
+        const value = client[key];
+        if (!isAdmissibleUrl(value, insecure) || new URL(value).search !== "")
+            throw invalid(`client.${key}`);
+    }
+};
+/** The platform `fetch` as the outbound port: JSON answers are parsed, the request's deadline aborts it. */
+export const fetchHttp = {
+    async request(request) {
+        const response = await fetch(request.url, {
+            method: request.method,
+            redirect: "manual",
+            signal: AbortSignal.timeout(request.timeoutMs),
+            headers: {
+                accept: "application/json",
+                ...(request.form === undefined ? {} : { "content-type": "application/x-www-form-urlencoded" }),
+                ...(request.body === undefined ? {} : { "content-type": "application/json" }),
+                ...request.headers,
+            },
+            ...(request.form === undefined ? {} : { body: new URLSearchParams(request.form).toString() }),
+            ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+        });
+        const body = await response.json().catch(() => undefined);
+        const location = response.headers.get("location");
+        return { status: response.status, body, ...(location === null ? {} : { location }) };
+    },
+};
+/** Validates the registration and applies the defaults. A key that does not meet the contract throws a `ConfigurationInvalid` error naming it. */
+export const resolveOptions = (options) => {
+    const insecure = options.allowInsecureHttp ?? false;
+    if (!isAdmissibleUrl(options.issuer, insecure) || new URL(options.issuer).search !== "")
+        throw invalid("issuer");
+    if (options.client !== undefined)
+        checkClient(options.client, insecure);
+    const jwks = options.jwks;
+    return {
+        issuer: options.issuer,
+        audience: audiencesOf(options.audience),
+        algorithms: algorithmsOf(options.algorithms),
+        authorizedParty: options.authorizedParty,
+        client: options.client,
+        realmRoles: options.roles?.realm ?? true,
+        roleClients: options.roles?.clients ?? [],
+        roleClaims: options.roles?.claims ?? [],
+        timeoutMs: positive(options.timeoutMs, 10_000, "timeoutMs"),
+        clockToleranceSeconds: toleranceOf(options.clockToleranceSeconds),
+        discoveryTtlMs: positive(options.discoveryTtlMs, HOUR_MS, "discoveryTtlMs"),
+        jwksTtlMs: positive(jwks?.ttlMs, 10 * MINUTE_MS, "jwks.ttlMs"),
+        jwksCooldownMs: positive(jwks?.refreshCooldownMs, MINUTE_MS / 2, "jwks.refreshCooldownMs"),
+        jwksStaleMs: positive(jwks?.staleTtlMs, 24 * HOUR_MS, "jwks.staleTtlMs"),
+        jwksMaxKeys: positive(jwks?.maxKeys, 100, "jwks.maxKeys"),
+        allowInsecureHttp: insecure,
+        http: options.http ?? fetchHttp,
+        clock: options.clock ?? systemClock,
+    };
+};

package/dist/oidc/primitives.d.ts

@@ -0,0 +1,15 @@
+/** The secret holder, the secret input, its reveal and the constant-time comparison: one copy for both editions. */
+export { revealed, sameValue } from "../server/primitives.js";
+export type { Revealable, SecretInput } from "../server/primitives.js";
+/** A record: a non-null object that is not an array (`isPlainRecord` of `@starci/common`). */
+export { isPlainRecord as isRecord } from "@starci/common";
+/** 256 unpredictable bits as base64url: a state, a nonce, a PKCE verifier or an opaque reference. */
+export declare const randomReference: () => string;
+/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). */
+export declare const pkceChallenge: (verifier: string) => string;
+/** The clock the package reads. */
+export interface OidcClock {
+    now(): Date;
+}
+/** The system clock. */
+export declare const systemClock: OidcClock;

package/dist/oidc/primitives.js

@@ -0,0 +1,11 @@
+import { createHash, randomBytes } from "node:crypto";
+/** The secret holder, the secret input, its reveal and the constant-time comparison: one copy for both editions. */
+export { revealed, sameValue } from "../server/primitives.js";
+/** A record: a non-null object that is not an array (`isPlainRecord` of `@starci/common`). */
+export { isPlainRecord as isRecord } from "@starci/common";
+/** 256 unpredictable bits as base64url: a state, a nonce, a PKCE verifier or an opaque reference. */
+export const randomReference = () => randomBytes(32).toString("base64url");
+/** The S256 challenge of a PKCE verifier: base64url(SHA-256(verifier)). */
+export const pkceChallenge = (verifier) => createHash("sha256").update(verifier).digest("base64url");
+/** The system clock. */
+export const systemClock = { now: () => new Date() };

package/dist/oidc/refresh.d.ts

@@ -0,0 +1,10 @@
+/** The refresh token of a token response and the instant it stops being accepted. */
+export interface OidcRefresh {
+    readonly refreshToken: string;
+    readonly refreshExpiresAt: Date;
+}
+/**
+ * The refresh token of a token endpoint answer and its expiry: `refresh_expires_in` (seconds from `now`), else the token's own `exp`.
+ * `undefined` when the answer holds no refresh token or no way to date it (an offline token has neither), so the caller refuses it.
+ */
+export declare const refreshOf: (body: unknown, now: Date) => OidcRefresh | undefined;

package/dist/oidc/refresh.js

@@ -0,0 +1,24 @@
+import { decodeJwt } from "jose";
+import { isRecord } from "./primitives.js";
+const SECOND_MS = 1000;
+/** The `exp` of a refresh token, read without trusting it: it only dates a token the provider itself just issued over the verified channel. */
+const expiryOf = (token) => {
+    try {
+        const { exp } = decodeJwt(token);
+        return typeof exp === "number" && Number.isFinite(exp) && exp > 0 ? exp * SECOND_MS : undefined;
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The refresh token of a token endpoint answer and its expiry: `refresh_expires_in` (seconds from `now`), else the token's own `exp`.
+ * `undefined` when the answer holds no refresh token or no way to date it (an offline token has neither), so the caller refuses it.
+ */
+export const refreshOf = (body, now) => {
+    if (!isRecord(body) || typeof body.refresh_token !== "string" || body.refresh_token === "")
+        return undefined;
+    const lifetime = body.refresh_expires_in;
+    const expiresAt = typeof lifetime === "number" && Number.isFinite(lifetime) && lifetime > 0 ? now.getTime() + lifetime * SECOND_MS : expiryOf(body.refresh_token);
+    return expiresAt === undefined ? undefined : { refreshToken: body.refresh_token, refreshExpiresAt: new Date(expiresAt) };
+};

package/dist/oidc/roles.d.ts

@@ -0,0 +1,12 @@
+/** Which claims hold roles. */
+export interface RoleSources {
+    readonly realm: boolean;
+    readonly clients: readonly string[];
+    readonly claims: readonly string[];
+}
+/**
+ * The roles a verified token grants: `realm_access.roles` (when the mapping reads the realm), `resource_access.<client>.roles` of each
+ * mapped client and each mapped flat claim. Sorted, without repeats. A claim of the wrong shape, or past the bounds, makes the whole
+ * token untrusted (`undefined`): a role is an authorization input, so it is never guessed from a malformed claim.
+ */
+export declare const rolesOf: (payload: Readonly<Record<string, unknown>>, sources: RoleSources) => readonly string[] | undefined;

package/dist/oidc/roles.js

@@ -0,0 +1,51 @@
+import { OIDC_CLAIMS, OIDC_ROLE_BOUNDS } from "../contracts/oidc.js";
+import { isRecord } from "./primitives.js";
+/** The roles of a claim value shaped `{ roles: string[] }`, or undefined when the shape is wrong. */
+const rolesOfContainer = (value) => {
+    if (value === undefined)
+        return [];
+    return isRecord(value) ? rolesOfList(value.roles) : undefined;
+};
+/** The roles of a claim value shaped `string[]`, or undefined when it is not one of bounded text. */
+const rolesOfList = (value) => {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.length > OIDC_ROLE_BOUNDS.maxRoles)
+        return undefined;
+    const list = value;
+    const texts = list.filter((role) => typeof role === "string" && role.length > 0 && role.length <= OIDC_ROLE_BOUNDS.maxLength);
+    return texts.length === list.length ? texts : undefined;
+};
+/**
+ * The roles a verified token grants: `realm_access.roles` (when the mapping reads the realm), `resource_access.<client>.roles` of each
+ * mapped client and each mapped flat claim. Sorted, without repeats. A claim of the wrong shape, or past the bounds, makes the whole
+ * token untrusted (`undefined`): a role is an authorization input, so it is never guessed from a malformed claim.
+ */
+export const rolesOf = (payload, sources) => {
+    const granted = new Set();
+    const add = (roles) => {
+        if (roles === undefined)
+            return false;
+        for (const role of roles)
+            granted.add(role);
+        return true;
+    };
+    if (sources.realm && !add(rolesOfContainer(payload[OIDC_CLAIMS.realmAccess])))
+        return undefined;
+    if (sources.clients.length > 0) {
+        const access = payload[OIDC_CLAIMS.resourceAccess];
+        if (access !== undefined && !isRecord(access))
+            return undefined;
+        for (const client of sources.clients) {
+            if (!add(rolesOfContainer(access === undefined ? undefined : access[client])))
+                return undefined;
+        }
+    }
+    for (const claim of sources.claims) {
+        if (!add(rolesOfList(payload[claim])))
+            return undefined;
+    }
+    if (granted.size > OIDC_ROLE_BOUNDS.maxRoles)
+        return undefined;
+    return [...granted].sort();
+};

package/dist/oidc/tokens.d.ts

@@ -0,0 +1,26 @@
+import type { JWTPayload } from "jose";
+import type { OidcAlgorithm, OidcOutcome } from "../contracts/oidc.js";
+import type { OidcKeys } from "./jwks.js";
+import type { ResolvedOidcOptions } from "./options.js";
+/** What one verification expects beyond the issuer and the pinned algorithms. */
+export interface TokenExpectations {
+    /** The audience: the token must name one of these. */
+    readonly audience: readonly string[];
+    /** The issuers the `iss` claim may name (the registration's issuer when absent): a preset whose issuer has two spellings lists both. */
+    readonly issuer?: readonly string[] | undefined;
+    /** Claims the token must carry. */
+    readonly requiredClaims?: readonly string[] | undefined;
+}
+/**
+ * The one verifier of the provider's signed tokens (access tokens and ID tokens). The algorithm is pinned to the registration's list
+ * before any key is looked up (so `none` and a symmetric algorithm never reach a key), the key comes from the provider's JWKS by `kid`,
+ * and the issuer, audience, expiry and not-before are checked against the registration and the clock.
+ */
+export declare class OidcTokenVerifier {
+    #private;
+    constructor(options: ResolvedOidcOptions, keys: OidcKeys);
+    /** The algorithms this verifier admits. */
+    get algorithms(): readonly OidcAlgorithm[];
+    /** The claims of a token that passed every check, or a refusal naming why. A provider that cannot be reached throws `Unavailable`. */
+    verify(token: string, expectations: TokenExpectations, now?: Date): Promise<OidcOutcome<JWTPayload>>;
+}

package/dist/oidc/tokens.js

@@ -0,0 +1,79 @@
+import { decodeProtectedHeader, errors, jwtVerify } from "jose";
+import { OIDC_ACCESS_TOKEN_INVALID } from "../contracts/oidc.js";
+const refuse = (reason) => ({ kind: "refused", code: OIDC_ACCESS_TOKEN_INVALID, detail: { reason } });
+/** The reason a jose error stands for. */
+const reasonOf = (error) => {
+    if (error instanceof errors.JWTExpired)
+        return "expired";
+    if (error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JWKSNoMatchingKey || error instanceof errors.JWKSMultipleMatchingKeys)
+        return "signature";
+    if (error instanceof errors.JOSEAlgNotAllowed)
+        return "algorithm";
+    if (error instanceof errors.JWTClaimValidationFailed) {
+        switch (error.claim) {
+            case "iss":
+                return "issuer";
+            case "aud":
+                return "audience";
+            case "nbf":
+            case "iat":
+                return "not-yet-valid";
+            case "exp":
+                return "expired";
+            default:
+                return "claims";
+        }
+    }
+    return error instanceof errors.JWTInvalid || error instanceof errors.JWSInvalid ? "malformed" : "signature";
+};
+/** The header of a token read without trusting it, only to pick the verification key; `undefined` when it is not a JWS header. */
+const headerOf = (token) => {
+    try {
+        const header = decodeProtectedHeader(token);
+        return { alg: header.alg, kid: header.kid };
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The one verifier of the provider's signed tokens (access tokens and ID tokens). The algorithm is pinned to the registration's list
+ * before any key is looked up (so `none` and a symmetric algorithm never reach a key), the key comes from the provider's JWKS by `kid`,
+ * and the issuer, audience, expiry and not-before are checked against the registration and the clock.
+ */
+export class OidcTokenVerifier {
+    #options;
+    #keys;
+    constructor(options, keys) {
+        this.#options = options;
+        this.#keys = keys;
+    }
+    /** The algorithms this verifier admits. */
+    get algorithms() {
+        return this.#options.algorithms;
+    }
+    /** The claims of a token that passed every check, or a refusal naming why. A provider that cannot be reached throws `Unavailable`. */
+    async verify(token, expectations, now = this.#options.clock.now()) {
+        const header = headerOf(token);
+        if (header === undefined)
+            return refuse("malformed");
+        const admitted = this.#options.algorithms;
+        if (header.alg === undefined || !admitted.includes(header.alg))
+            return refuse("algorithm");
+        const keys = await this.#keys.keysFor(header.kid);
+        try {
+            const { payload } = await jwtVerify(token, keys, {
+                algorithms: [...this.#options.algorithms],
+                issuer: expectations.issuer === undefined ? this.#options.issuer : [...expectations.issuer],
+                audience: [...expectations.audience],
+                currentDate: now,
+                clockTolerance: this.#options.clockToleranceSeconds,
+                requiredClaims: ["exp", "sub", ...(expectations.requiredClaims ?? [])],
+            });
+            return { kind: "ok", value: payload };
+        }
+        catch (error) {
+            return refuse(reasonOf(error));
+        }
+    }
+}

package/dist/oidc/transport.d.ts

@@ -0,0 +1,8 @@
+import type { OidcHttpRequest, OidcHttpResponse, ResolvedOidcOptions } from "./options.js";
+/**
+ * Sends one request through the registration's `OidcHttp` port with its deadline. A lost connection, a timeout, a 5xx and a 429 throw
+ * `Unavailable` (a provider outage, never a refusal of the person); any other answer is returned for the caller to judge.
+ */
+export declare const send: (options: ResolvedOidcOptions, request: Omit<OidcHttpRequest, "timeoutMs">) => Promise<OidcHttpResponse>;
+/** The OAuth `error` code of an answer (`invalid_grant`), or undefined. Never the description, which may name the person. */
+export declare const errorCodeOf: (body: unknown) => string | undefined;

package/dist/oidc/transport.js

@@ -0,0 +1,19 @@
+import { OIDC_ERROR_CODES } from "../contracts/oidc.js";
+import { OidcError } from "./errors.js";
+import { isRecord } from "./primitives.js";
+/** The answers that mean the provider is struggling rather than refusing: a server error and a throttle. */
+const isOutage = (status) => status >= 500 || status === 429;
+/**
+ * Sends one request through the registration's `OidcHttp` port with its deadline. A lost connection, a timeout, a 5xx and a 429 throw
+ * `Unavailable` (a provider outage, never a refusal of the person); any other answer is returned for the caller to judge.
+ */
+export const send = async (options, request) => {
+    const response = await options.http.request({ ...request, timeoutMs: options.timeoutMs }).catch((cause) => {
+        throw new OidcError(OIDC_ERROR_CODES.Unavailable, { cause });
+    });
+    if (isOutage(response.status))
+        throw new OidcError(OIDC_ERROR_CODES.Unavailable);
+    return response;
+};
+/** The OAuth `error` code of an answer (`invalid_grant`), or undefined. Never the description, which may name the person. */
+export const errorCodeOf = (body) => (isRecord(body) && typeof body.error === "string" ? body.error : undefined);

package/dist/oidc/verifier.d.ts

@@ -0,0 +1,24 @@
+import type { JWTPayload } from "jose";
+import type { OidcOutcome, OidcPrincipal, PrincipalVerifier } from "../contracts/oidc.js";
+import type { ResolvedOidcOptions } from "./options.js";
+import type { OidcTokenVerifier } from "./tokens.js";
+/** What turning verified claims into a principal reads of a registration. */
+export type PrincipalRules = Pick<ResolvedOidcOptions, "issuer" | "authorizedParty" | "realmRoles" | "roleClients" | "roleClaims">;
+/**
+ * The principal verified access-token claims stand for: a bounded subject, an access token type (`Bearer`, or none), the authorized party when
+ * the registration names one, and roles of the right shape; any other token is a refusal naming why. Shared by the verifier of the module and
+ * the Keycloak issuer preset.
+ */
+export declare const principalOf: (claims: JWTPayload, rules: PrincipalRules) => OidcOutcome<OidcPrincipal>;
+/**
+ * The `PrincipalVerifier` of the full edition: a bearer access token of the provider, checked against the discovered issuer's JWKS
+ * (algorithm pinned, issuer, audience, expiry), becomes the principal a guard reads. The principal has the shape of `@starci/auth`'s, with
+ * the roles the issuer granted added, so guards, `@Public` and `@Credential` do not change between editions.
+ */
+export declare class OidcPrincipalVerifier implements PrincipalVerifier {
+    #private;
+    constructor(options: ResolvedOidcOptions, tokens: OidcTokenVerifier);
+    verify(token: string, now?: Date): Promise<OidcOutcome<OidcPrincipal>>;
+}
+/** The verifier of an app that serves no user session: every token is refused, so the default-deny guard admits only its public and credential doors. */
+export declare const refuseSessions: PrincipalVerifier;

package/dist/oidc/verifier.js

@@ -0,0 +1,64 @@
+import { OIDC_ACCESS_TOKEN_INVALID, OIDC_CLAIMS, OIDC_ROLE, OIDC_SUBJECT_MAX_LENGTH } from "../contracts/oidc.js";
+import { rolesOf } from "./roles.js";
+/** The `typ` claim of an access token Keycloak issues. An ID token (`ID`) or a refresh token presented as a bearer is not one. */
+const ACCESS_TOKEN_TYPE = "Bearer";
+const refuse = (reason) => ({ kind: "refused", code: OIDC_ACCESS_TOKEN_INVALID, detail: { reason } });
+const text = (value) => (typeof value === "string" && value !== "" ? value : undefined);
+/**
+ * The principal verified access-token claims stand for: a bounded subject, an access token type (`Bearer`, or none), the authorized party when
+ * the registration names one, and roles of the right shape; any other token is a refusal naming why. Shared by the verifier of the module and
+ * the Keycloak issuer preset.
+ */
+export const principalOf = (claims, rules) => {
+    const subject = text(claims.sub);
+    if (subject === undefined || subject.length > OIDC_SUBJECT_MAX_LENGTH || typeof claims.exp !== "number")
+        return refuse("claims");
+    const type = claims[OIDC_CLAIMS.tokenType];
+    if (type !== undefined && type !== ACCESS_TOKEN_TYPE)
+        return refuse("token-type");
+    if (rules.authorizedParty !== undefined && claims[OIDC_CLAIMS.authorizedParty] !== rules.authorizedParty)
+        return refuse("authorized-party");
+    const roles = rolesOf(claims, { realm: rules.realmRoles, clients: rules.roleClients, claims: rules.roleClaims });
+    if (roles === undefined)
+        return refuse("claims");
+    const email = text(claims[OIDC_CLAIMS.email]);
+    const name = text(claims[OIDC_CLAIMS.name]);
+    const username = text(claims[OIDC_CLAIMS.username]);
+    return {
+        kind: "ok",
+        value: {
+            id: subject,
+            role: OIDC_ROLE,
+            sessionId: text(claims[OIDC_CLAIMS.sessionId]) ?? text(claims[OIDC_CLAIMS.tokenId]) ?? subject,
+            ...(email === undefined ? {} : { email }),
+            ...(name === undefined ? {} : { name }),
+            ...(username === undefined ? {} : { username }),
+            roles,
+            issuer: rules.issuer,
+            expiresAt: new Date(claims.exp * 1000),
+        },
+    };
+};
+/**
+ * The `PrincipalVerifier` of the full edition: a bearer access token of the provider, checked against the discovered issuer's JWKS
+ * (algorithm pinned, issuer, audience, expiry), becomes the principal a guard reads. The principal has the shape of `@starci/auth`'s, with
+ * the roles the issuer granted added, so guards, `@Public` and `@Credential` do not change between editions.
+ */
+export class OidcPrincipalVerifier {
+    #options;
+    #tokens;
+    constructor(options, tokens) {
+        this.#options = options;
+        this.#tokens = tokens;
+    }
+    async verify(token, now = this.#options.clock.now()) {
+        const verified = await this.#tokens.verify(token, { audience: this.#options.audience }, now);
+        if (verified.kind === "refused")
+            return verified;
+        return principalOf(verified.value, this.#options);
+    }
+}
+/** The verifier of an app that serves no user session: every token is refused, so the default-deny guard admits only its public and credential doors. */
+export const refuseSessions = {
+    verify: () => Promise.resolve(refuse("claims")),
+};

package/dist/server/auth.module.d.ts

@@ -17,7 +17,7 @@ export type AuthRegisterOptions = typeof OPTIONS_TYPE;
 export type AuthRegisterAsyncOptions = typeof ASYNC_OPTIONS_TYPE;
 /**
  * The sign-in of a lite app as one Nest capability: the token signer and verifier, the passwords, the sign-in budget, the
- * rotating sessions, the refresh cookie, the passport flows (local and Google with state and PKCE) and the doors that run them.
+ * rotating sessions, the refresh cookie, the passport flows (local, and each sign-in provider with state and PKCE) and the doors that run them.
  * Registered once at the api root; the app implements the stores (`SessionStore`, `AccountDirectory`, `RateCounter`) and the
  * `AuthAuthenticator` over its own tables.
  */

package/dist/server/auth.module.js

@@ -2,15 +2,16 @@ import { ConfigurableModuleBuilder, Module } from "@nestjs/common";
 import { AuthDoors } from "./doors.js";
 import { RefreshCookie } from "./cookie.js";
 import { AuthFlows } from "./flows.js";
-import { GoogleStateClient } from "./google-state.js";
 import { AuthPasswords } from "./passwords.js";
+import { GOOGLE_PROVIDER_ID, GoogleStateClient } from "./providers/google.js";
+import { buildProviders, providersOf } from "./providers/registry.js";
 import { randomIds, systemClock } from "./runtime.js";
 import { AuthSessions } from "./sessions.js";
-import { PassportGoogleStrategy, PassportLocalStrategy } from "./strategies.js";
+import { PassportLocalStrategy } from "./strategies.js";
 import { AuthTokens } from "./tokens.js";
 import { AuthPrincipalVerifier } from "./verifier.js";
 import { SignInBudget } from "./budget.js";
-import { 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";
+import { 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 const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new ConfigurableModuleBuilder({ moduleName: "Auth" })
     .setClassMethodName("register")
     .setFactoryMethodName("createAuthOptions")
@@ -44,10 +45,23 @@ const providers = (authenticator) => [
         inject: [AUTH_AUTHENTICATOR],
         useFactory: (authenticator) => new PassportLocalStrategy(authenticator),
     },
+    {
+        provide: AUTH_PROVIDERS,
+        inject: [MODULE_OPTIONS_TOKEN, AUTH_AUTHENTICATOR, AUTH_TOKENS, AUTH_GOOGLE_STATE],
+        useFactory: (options, authenticator, tokens, googleState) => buildProviders({
+            providers: providersOf(options),
+            authenticator,
+            tokens,
+            clock: options.clock ?? systemClock,
+            ids: options.ids ?? randomIds,
+            returnOrigin: options.returnOrigin,
+            googleState,
+        }),
+    },
     {
         provide: AUTH_GOOGLE_STRATEGY,
-        inject: [MODULE_OPTIONS_TOKEN, AUTH_AUTHENTICATOR, AUTH_GOOGLE_STATE],
-        useFactory: (options, authenticator, state) => options.google === null ? null : new PassportGoogleStrategy(options.google, authenticator, state),
+        inject: [AUTH_PROVIDERS],
+        useFactory: (entries) => entries.get(GOOGLE_PROVIDER_ID)?.strategy ?? null,
     },
     {
         provide: AUTH_DOORS_SERVICE,
@@ -68,7 +82,7 @@ const withProviders = (base, authenticator) => ({
 });
 /**
  * The sign-in of a lite app as one Nest capability: the token signer and verifier, the passwords, the sign-in budget, the
- * rotating sessions, the refresh cookie, the passport flows (local and Google with state and PKCE) and the doors that run them.
+ * rotating sessions, the refresh cookie, the passport flows (local, and each sign-in provider with state and PKCE) and the doors that run them.
  * Registered once at the api root; the app implements the stores (`SessionStore`, `AccountDirectory`, `RateCounter`) and the
  * `AuthAuthenticator` over its own tables.
  */

package/dist/server/auth.tokens.d.ts

@@ -18,6 +18,8 @@ export declare const AUTH_FLOWS: unique symbol;
 export declare const AUTH_LOCAL_STRATEGY: unique symbol;
 /** Token of the Google passport strategy, or null when the deployment has no Google client. */
 export declare const AUTH_GOOGLE_STRATEGY: unique symbol;
+/** Token of the registered sign-in providers: each one's definition, state store and passport strategy, by provider id. */
+export declare const AUTH_PROVIDERS: unique symbol;
 /** Token of `AuthDoors`, what a controller calls. */
 export declare const AUTH_DOORS_SERVICE: unique symbol;
 /** Token of the `PrincipalVerifier` the identity domain injects. */

package/dist/server/auth.tokens.js

@@ -18,6 +18,8 @@ export const AUTH_FLOWS = Symbol.for("@starci/auth/flows");
 export const AUTH_LOCAL_STRATEGY = Symbol.for("@starci/auth/local-strategy");
 /** Token of the Google passport strategy, or null when the deployment has no Google client. */
 export const AUTH_GOOGLE_STRATEGY = Symbol.for("@starci/auth/google-strategy");
+/** Token of the registered sign-in providers: each one's definition, state store and passport strategy, by provider id. */
+export const AUTH_PROVIDERS = Symbol.for("@starci/auth/providers");
 /** Token of `AuthDoors`, what a controller calls. */
 export const AUTH_DOORS_SERVICE = Symbol.for("@starci/auth/doors");
 /** Token of the `PrincipalVerifier` the identity domain injects. */

package/dist/server/doors.d.ts

@@ -1,13 +1,15 @@
-import type { AccessGrant, GoogleRedirect } from "../contracts/index.js";
+import type { AccessGrant, GoogleRedirect, ProviderRedirect } from "../contracts/index.js";
 import type { RefreshCookie } from "./cookie.js";
 import type { AuthFlows } from "./flows.js";
 import type { HttpExchange } from "./http.js";
 import type { AuthLogger, SessionTokens } from "./ports.js";
 import type { AuthSessions } from "./sessions.js";
-/** The status of the Google callback redirect. */
+/** The status of a provider's callback redirect. */
 export declare const SEE_OTHER = 303;
+/** The log event of a failed sign-in through one provider (`auth.github-sign-in-failed`). */
+export declare const providerSignInFailedEvent: (provider: string) => string;
 /** The log event of a failed Google sign-in. */
-export declare const GOOGLE_SIGN_IN_FAILED_EVENT = "auth.google-sign-in-failed";
+export declare const GOOGLE_SIGN_IN_FAILED_EVENT: string;
 /** The body a sign-in, refresh or session door answers. */
 export declare const accessOf: (tokens: SessionTokens) => AccessGrant;
 /** What the doors need. */
@@ -33,12 +35,16 @@ export declare class AuthDoors {
     session(exchange: HttpExchange): Promise<AccessGrant>;
     /** Ends the session of the cookie and clears it. */
     logout(exchange: HttpExchange): Promise<void>;
-    /** Sends the browser to the Google consent screen. */
-    beginGoogle(exchange: HttpExchange): Promise<void>;
+    /** Sends the browser to the consent screen of a registered provider (`/auth/<id>`); an unregistered one is refused. */
+    beginProvider(provider: string, exchange: HttpExchange): Promise<void>;
     /**
-     * Finishes the Google round trip: state, PKCE and profile are verified, the account found, linked or created, its session opened
-     * and its cookie set. A failure never throws: the browser is sent back to the sign-in page, because a redirect-only door has
-     * nowhere to show an error body.
+     * Finishes a provider's round trip (`/auth/<id>/callback`): state, PKCE and profile are verified, the account found, linked or
+     * created, its session opened and its cookie set. A failure never throws: the browser is sent back to the sign-in page, because a
+     * redirect-only door has nowhere to show an error body.
      */
+    completeProvider(provider: string, exchange: HttpExchange): Promise<ProviderRedirect>;
+    /** Sends the browser to the Google consent screen. */
+    beginGoogle(exchange: HttpExchange): Promise<void>;
+    /** Finishes the Google round trip, as `completeProvider("google", ...)`. */
     completeGoogle(exchange: HttpExchange): Promise<GoogleRedirect>;
 }

package/dist/server/doors.js

@@ -1,7 +1,10 @@
-/** The status of the Google callback redirect. */
+import { GOOGLE_PROVIDER_ID } from "./providers/google.js";
+/** The status of a provider's callback redirect. */
 export const SEE_OTHER = 303;
+/** The log event of a failed sign-in through one provider (`auth.github-sign-in-failed`). */
+export const providerSignInFailedEvent = (provider) => `auth.${provider}-sign-in-failed`;
 /** The log event of a failed Google sign-in. */
-export const GOOGLE_SIGN_IN_FAILED_EVENT = "auth.google-sign-in-failed";
+export const GOOGLE_SIGN_IN_FAILED_EVENT = providerSignInFailedEvent(GOOGLE_PROVIDER_ID);
 /** The body a sign-in, refresh or session door answers. */
 export const accessOf = (tokens) => ({
     accessToken: tokens.accessToken,
@@ -46,26 +49,34 @@ export class AuthDoors {
         await this.#deps.sessions.end(this.#deps.cookie.read(exchange.req));
         this.#deps.cookie.clear(exchange.res, exchange.req);
     }
-    /** Sends the browser to the Google consent screen. */
-    beginGoogle(exchange) {
-        return this.#deps.flows.beginGoogle(exchange);
+    /** Sends the browser to the consent screen of a registered provider (`/auth/<id>`); an unregistered one is refused. */
+    beginProvider(provider, exchange) {
+        return this.#deps.flows.begin(provider, exchange);
     }
     /**
-     * Finishes the Google round trip: state, PKCE and profile are verified, the account found, linked or created, its session opened
-     * and its cookie set. A failure never throws: the browser is sent back to the sign-in page, because a redirect-only door has
-     * nowhere to show an error body.
+     * Finishes a provider's round trip (`/auth/<id>/callback`): state, PKCE and profile are verified, the account found, linked or
+     * created, its session opened and its cookie set. A failure never throws: the browser is sent back to the sign-in page, because a
+     * redirect-only door has nowhere to show an error body.
      */
-    async completeGoogle(exchange) {
+    async completeProvider(provider, exchange) {
         try {
-            const completion = await this.#deps.flows.completeGoogle(exchange);
+            const completion = await this.#deps.flows.complete(provider, exchange);
             const tokens = await this.#deps.sessions.start(completion.subject, this.#deps.cookie.deviceOf(exchange.req));
             this.#deps.cookie.issue(exchange.res, tokens, exchange.req);
             return { url: `${this.#deps.returnOrigin}${completion.next}`, statusCode: SEE_OTHER };
         }
         catch (cause) {
             this.#deps.cookie.clear(exchange.res, exchange.req);
-            this.#deps.logger?.warn(GOOGLE_SIGN_IN_FAILED_EVENT, { cause: String(cause) });
+            this.#deps.logger?.warn(providerSignInFailedEvent(provider), { cause: String(cause) });
             return { url: `${this.#deps.returnOrigin}/sign-in?auth=error`, statusCode: SEE_OTHER };
         }
     }
+    /** Sends the browser to the Google consent screen. */
+    beginGoogle(exchange) {
+        return this.beginProvider(GOOGLE_PROVIDER_ID, exchange);
+    }
+    /** Finishes the Google round trip, as `completeProvider("google", ...)`. */
+    completeGoogle(exchange) {
+        return this.completeProvider(GOOGLE_PROVIDER_ID, exchange);
+    }
 }