@nestjs/authentication 0.0.1

package/dist/oidc/oidc.client.d.ts

@@ -0,0 +1,44 @@
+import type { OAuthTokens, OidcProfile, OidcProviderConfig } from '../interfaces/oidc-provider.interface.js';
+import type { OidcTransaction, OidcClientOptions } from '../interfaces/oidc.interface.js';
+/**
+ * One OAuth 2.0 / OpenID Connect provider: authorization code flow with
+ * PKCE (S256), `state` and `nonce`.
+ *
+ * Checks, in order: IdP error, `iss` response parameter (RFC 9207, mix-up
+ * defence), token response shape, ID token signature (JWKS, RS256/ES256,
+ * alg/key binding), `iss`, `aud`, `azp`, `exp`, `iat`, `nonce`, and that
+ * userinfo's `sub` matches the ID token's (OIDC Core §5.3.2).
+ */
+export declare class OidcClient {
+    readonly name: string;
+    private readonly config;
+    private readonly options;
+    private discovery?;
+    private jwks?;
+    readonly kind: 'oidc' | 'oauth2';
+    constructor(name: string, config: OidcProviderConfig, options?: OidcClientOptions);
+    /**
+     * The provider's authorization URL, the transaction to store, and the
+     * browser binding for the transaction cookie. `state` is the SHA-256 of
+     * `binding`: the state travels in URLs (access logs, history, the error
+     * page of a failed callback), so it must not be what the cookie holds, or
+     * whoever reads a callback URL could redeem it from any client.
+     */
+    authorizationRequest(redirectUri: string, redirectTo?: string, ttlMs?: number): Promise<{
+        url: string;
+        transaction: OidcTransaction;
+        binding: string;
+    }>;
+    /** Completes the flow. The caller has already matched `state` to the browser and loaded `transaction`. */
+    callback(params: Record<string, unknown>, transaction: OidcTransaction, redirectUri: string): Promise<{
+        profile: OidcProfile;
+        tokens: OAuthTokens;
+    }>;
+    private verifyIdToken;
+    private exchange;
+    private endpoints;
+    private discover;
+    private getJson;
+    private request;
+    private now;
+}

package/dist/oidc/oidc.client.js

@@ -0,0 +1,286 @@
+import { createHash } from 'node:crypto';
+import { randomToken, safeEqual, sha256 } from '../utils/crypto.util.js';
+import { durationOr } from '../utils/duration.util.js';
+import { JwksClient } from '../jwt/jwks.client.js';
+import { JwtError } from '../errors/jwt.error.js';
+import { JwtVerifier } from '../jwt/jwt-verifier.service.js';
+import { OidcError } from '../errors/oidc.error.js';
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+/**
+ * Only https, except loopback http (local IdPs and tests). The URLs come from the provider's
+ * discovery document or the app's configuration, never from the user: a bad one is a
+ * misconfiguration (`unavailable`, a 502), not a failed sign-in.
+ */
+function assertSecureUrl(value, what) {
+    let url;
+    try {
+        url = new URL(value ?? '');
+    }
+    catch {
+        throw new OidcError(`${what} is not a URL`, 'unavailable');
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname))) {
+        throw new OidcError(`${what} must use https`, 'unavailable');
+    }
+    return url.toString();
+}
+/**
+ * One OAuth 2.0 / OpenID Connect provider: authorization code flow with
+ * PKCE (S256), `state` and `nonce`.
+ *
+ * Checks, in order: IdP error, `iss` response parameter (RFC 9207, mix-up
+ * defence), token response shape, ID token signature (JWKS, RS256/ES256,
+ * alg/key binding), `iss`, `aud`, `azp`, `exp`, `iat`, `nonce`, and that
+ * userinfo's `sub` matches the ID token's (OIDC Core §5.3.2).
+ */
+export class OidcClient {
+    constructor(name, config, options = {}) {
+        this.name = name;
+        this.config = config;
+        this.options = options;
+        this.kind = config.kind ?? 'oidc';
+        if (this.kind === 'oidc' && !config.issuer) {
+            throw new Error(`OIDC provider '${name}' needs an issuer`);
+        }
+        if (this.kind === 'oauth2' && (!config.authorizationEndpoint || !config.tokenEndpoint || !config.profile)) {
+            throw new Error(`OAuth 2.0 provider '${name}' needs authorizationEndpoint, tokenEndpoint and profile()`);
+        }
+    }
+    /**
+     * The provider's authorization URL, the transaction to store, and the
+     * browser binding for the transaction cookie. `state` is the SHA-256 of
+     * `binding`: the state travels in URLs (access logs, history, the error
+     * page of a failed callback), so it must not be what the cookie holds, or
+     * whoever reads a callback URL could redeem it from any client.
+     */
+    async authorizationRequest(redirectUri, redirectTo, ttlMs = 600_000) {
+        const endpoints = await this.endpoints();
+        const now = this.now();
+        const binding = randomToken();
+        const transaction = {
+            state: sha256(binding),
+            provider: this.name,
+            codeVerifier: randomToken(),
+            ...(this.kind === 'oidc' && { nonce: randomToken() }),
+            ...(redirectTo && { redirectTo }),
+            createdAt: new Date(now),
+            expiresAt: new Date(now + ttlMs),
+        };
+        const url = new URL(endpoints.authorization_endpoint);
+        const params = {
+            ...this.config.authorizationParams,
+            response_type: 'code',
+            client_id: this.config.clientId,
+            redirect_uri: redirectUri,
+            scope: (this.config.scopes ?? ['openid', 'email', 'profile']).join(' '),
+            state: transaction.state,
+            code_challenge: createHash('sha256').update(transaction.codeVerifier).digest('base64url'),
+            code_challenge_method: 'S256',
+            ...(transaction.nonce && { nonce: transaction.nonce }),
+        };
+        for (const [key, value] of Object.entries(params)) {
+            url.searchParams.set(key, value);
+        }
+        return { url: url.toString(), transaction, binding };
+    }
+    /** Completes the flow. The caller has already matched `state` to the browser and loaded `transaction`. */
+    async callback(params, transaction, redirectUri) {
+        if (typeof params.error === 'string') {
+            throw new OidcError(`provider returned ${params.error}`, 'request');
+        }
+        if (typeof params.code !== 'string' || !params.code) {
+            throw new OidcError('missing code', 'request');
+        }
+        const endpoints = await this.endpoints();
+        if (this.kind === 'oidc') {
+            if (params.iss !== undefined && params.iss !== endpoints.issuer) {
+                throw new OidcError('issuer mismatch', 'request');
+            }
+            if (params.iss === undefined && endpoints.authorization_response_iss_parameter_supported) {
+                throw new OidcError('missing iss', 'request');
+            }
+        }
+        const tokens = await this.exchange(endpoints, params.code, transaction, redirectUri);
+        const context = { provider: this.name, tokens, fetchJson: (url) => this.getJson(url, tokens.accessToken) };
+        const userinfo = (url) => this.getJson(url, tokens.accessToken, 'userinfo endpoint');
+        if (this.kind === 'oauth2') {
+            const profile = endpoints.userinfo_endpoint ? await userinfo(endpoints.userinfo_endpoint) : {};
+            return { profile: await this.config.profile(profile, context), tokens };
+        }
+        if (!tokens.idToken) {
+            throw new OidcError('missing id_token', 'verification');
+        }
+        const claims = await this.verifyIdToken(endpoints, tokens.idToken, transaction.nonce);
+        let merged = claims;
+        let info;
+        if (endpoints.userinfo_endpoint) {
+            info = await userinfo(endpoints.userinfo_endpoint);
+            if (info?.sub !== claims.sub) {
+                throw new OidcError('userinfo subject mismatch', 'verification');
+            }
+            merged = { ...info, ...claims };
+        }
+        // The address and whether it is verified come as a pair, from one source: the ID token's, or
+        // else userinfo's. `email_verified` in one says nothing about an `email` in the other.
+        const addressed = typeof claims.email === 'string' ? claims : (info ?? {});
+        const email = typeof addressed.email === 'string' ? addressed.email : undefined;
+        return {
+            profile: {
+                provider: this.name,
+                subject: claims.sub,
+                email,
+                emailVerified: email !== undefined && addressed.email_verified === true,
+                name: typeof merged.name === 'string' ? merged.name : undefined,
+                picture: typeof merged.picture === 'string' ? merged.picture : undefined,
+                claims: merged,
+            },
+            tokens,
+        };
+    }
+    async verifyIdToken(endpoints, idToken, nonce) {
+        this.jwks ??= new JwksClient(assertSecureUrl(endpoints.jwks_uri, 'jwks_uri'), {
+            ...this.options.jwks,
+            fetch: this.options.fetch,
+            now: this.options.now,
+        });
+        const verifier = new JwtVerifier({
+            jwks: this.jwks,
+            algorithms: this.config.idTokenAlgorithms ?? ['RS256', 'ES256'],
+            issuer: endpoints.issuer,
+            audience: this.config.clientId,
+            required: ['exp', 'iat', 'sub'],
+            clockTolerance: this.options.clockTolerance ?? '30s',
+            now: this.options.now,
+        });
+        let claims;
+        try {
+            claims = await verifier.verify(idToken);
+        }
+        catch (error) {
+            if (error instanceof JwtError) {
+                throw new OidcError(`id_token ${error.message}`, 'verification');
+            }
+            // The provider's key set could not be loaded: an outage (502), as any other of the provider's.
+            throw new OidcError(error.message, 'unavailable');
+        }
+        if (typeof claims.sub !== 'string' || !claims.sub) {
+            throw new OidcError('id_token without subject', 'verification');
+        }
+        const audiences = [].concat(claims.aud);
+        if ((audiences.length > 1 || claims.azp !== undefined) && claims.azp !== this.config.clientId) {
+            throw new OidcError('id_token azp mismatch', 'verification');
+        }
+        if (typeof claims.nonce !== 'string' || !safeEqual(claims.nonce, nonce)) {
+            throw new OidcError('id_token nonce mismatch', 'verification');
+        }
+        return claims;
+    }
+    async exchange(endpoints, code, transaction, redirectUri) {
+        const method = this.config.tokenEndpointAuthMethod ?? (this.config.clientSecret ? 'client_secret_basic' : 'none');
+        const body = new URLSearchParams({
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            code_verifier: transaction.codeVerifier,
+        });
+        const headers = {
+            accept: 'application/json',
+            'content-type': 'application/x-www-form-urlencoded',
+        };
+        if (method === 'client_secret_basic') {
+            // RFC 6749 §2.3.1: form-encode each part before base64.
+            const id = encodeURIComponent(this.config.clientId);
+            const secret = encodeURIComponent(this.config.clientSecret ?? '');
+            headers.authorization = `Basic ${Buffer.from(`${id}:${secret}`).toString('base64')}`;
+        }
+        else {
+            body.set('client_id', this.config.clientId);
+            if (method === 'client_secret_post') {
+                body.set('client_secret', this.config.clientSecret ?? '');
+            }
+        }
+        const response = await this.request(endpoints.token_endpoint, { method: 'POST', headers, body });
+        const json = (await response.json().catch(() => undefined));
+        const error = typeof json?.error === 'string' ? json.error : undefined;
+        if (response.status >= 500 && !error) {
+            throw new OidcError(`token endpoint unavailable (${response.status})`, 'unavailable');
+        }
+        if (!response.ok || !json || error) {
+            throw new OidcError(`token endpoint rejected the code (${error ?? response.status})`, 'verification');
+        }
+        if (typeof json.access_token !== 'string' || String(json.token_type).toLowerCase() !== 'bearer') {
+            throw new OidcError('malformed token response', 'verification');
+        }
+        return {
+            accessToken: json.access_token,
+            ...(typeof json.refresh_token === 'string' && { refreshToken: json.refresh_token }),
+            ...(typeof json.id_token === 'string' && { idToken: json.id_token }),
+            ...(typeof json.expires_in === 'number' && { expiresIn: json.expires_in }),
+            ...(typeof json.scope === 'string' && { scope: json.scope }),
+        };
+    }
+    async endpoints() {
+        if (this.kind === 'oauth2') {
+            return {
+                authorization_endpoint: assertSecureUrl(this.config.authorizationEndpoint, 'authorization_endpoint'),
+                token_endpoint: assertSecureUrl(this.config.tokenEndpoint, 'token_endpoint'),
+                ...(this.config.userinfoEndpoint && {
+                    userinfo_endpoint: assertSecureUrl(this.config.userinfoEndpoint, 'userinfo_endpoint'),
+                }),
+            };
+        }
+        const ttl = durationOr(this.options.discoveryTtl, '1h');
+        if (!this.discovery || this.now() - this.discovery.at >= ttl) {
+            const value = this.discover();
+            this.discovery = { value, at: this.now() };
+            value.catch(() => (this.discovery = undefined)); // retry next time
+        }
+        return this.discovery.value;
+    }
+    async discover() {
+        const issuer = this.config.issuer;
+        const url = `${issuer.replace(/\/$/, '')}/.well-known/openid-configuration`;
+        const response = await this.request(assertSecureUrl(url, 'issuer'), { headers: { accept: 'application/json' } });
+        if (!response.ok) {
+            throw new OidcError(`discovery failed (${response.status})`, 'unavailable');
+        }
+        const doc = (await response.json().catch(() => ({})));
+        // OIDC Discovery §4.3: the document must name exactly the issuer we asked.
+        if (doc.issuer !== issuer) {
+            throw new OidcError('discovery issuer mismatch', 'unavailable');
+        }
+        return {
+            ...doc,
+            authorization_endpoint: assertSecureUrl(this.config.authorizationEndpoint ?? doc.authorization_endpoint, 'authorization_endpoint'),
+            token_endpoint: assertSecureUrl(this.config.tokenEndpoint ?? doc.token_endpoint, 'token_endpoint'),
+            userinfo_endpoint: (this.config.userinfoEndpoint ?? doc.userinfo_endpoint) && assertSecureUrl(this.config.userinfoEndpoint ?? doc.userinfo_endpoint, 'userinfo_endpoint'),
+            jwks_uri: this.config.jwksUri ?? doc.jwks_uri,
+        };
+    }
+    async getJson(url, accessToken, what) {
+        const target = new URL(assertSecureUrl(url, 'API url'));
+        // Errors reach responses and logs: name the host and path, never a query that may carry secrets.
+        const name = what ?? `${target.host}${target.pathname}`;
+        const response = await this.request(target.toString(), {
+            headers: { accept: 'application/json', authorization: `Bearer ${accessToken}` },
+        });
+        if (response.status >= 500) {
+            throw new OidcError(`${name} unavailable (${response.status})`, 'unavailable');
+        }
+        if (!response.ok) {
+            throw new OidcError(`${name} answered ${response.status}`, 'verification');
+        }
+        return response.json();
+    }
+    async request(url, init) {
+        try {
+            return await (this.options.fetch ?? fetch)(url, { ...init, redirect: 'error', signal: AbortSignal.timeout(10_000) });
+        }
+        catch (error) {
+            throw new OidcError(`${new URL(url).host} is unreachable (${error.message})`, 'unavailable');
+        }
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+}

package/dist/oidc/oidc.presets.d.ts

@@ -0,0 +1,24 @@
+import type { OidcProviderConfig } from '../interfaces/oidc-provider.interface.js';
+type Credentials = {
+    clientId: string;
+    clientSecret: string;
+};
+export declare function google(credentials: Credentials): OidcProviderConfig;
+/**
+ * Microsoft Entra ID, single tenant, by its tenant id (a GUID). Whatever
+ * name discovery is asked with, a domain included, Entra publishes the
+ * issuer of the tenant id, which must match exactly. Multi-tenant endpoints
+ * (`common`, `organizations`, `consumers`) publish a templated issuer
+ * (`https://login.microsoftonline.com/{tenantid}/v2.0`) that needs per-token
+ * issuer validation against `tid`; not supported.
+ */
+export declare function microsoft({ tenant, ...credentials }: Credentials & {
+    tenant: string;
+}): OidcProviderConfig;
+/**
+ * GitHub is OAuth 2.0, not OIDC: no discovery, no ID token. The profile
+ * comes from `GET /user`, and the email from `GET /user/emails` (primary and
+ * verified only), since the public profile email is user-controlled.
+ */
+export declare function github(credentials: Credentials): OidcProviderConfig;
+export {};

package/dist/oidc/oidc.presets.js

@@ -0,0 +1,53 @@
+export function google(credentials) {
+    return { issuer: 'https://accounts.google.com', ...credentials };
+}
+const TENANT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Microsoft Entra ID, single tenant, by its tenant id (a GUID). Whatever
+ * name discovery is asked with, a domain included, Entra publishes the
+ * issuer of the tenant id, which must match exactly. Multi-tenant endpoints
+ * (`common`, `organizations`, `consumers`) publish a templated issuer
+ * (`https://login.microsoftonline.com/{tenantid}/v2.0`) that needs per-token
+ * issuer validation against `tid`; not supported.
+ */
+export function microsoft({ tenant, ...credentials }) {
+    if (typeof tenant !== 'string' || !TENANT_ID.test(tenant)) {
+        throw new Error(`microsoft(): pass the tenant id, a GUID (Entra admin center, Overview), not ${JSON.stringify(tenant)}: ` +
+            'for a domain, and for the multi-tenant common, organizations and consumers, Microsoft publishes an ' +
+            'issuer that is not the one discovery was asked for, and every sign-in would fail.');
+    }
+    return { issuer: `https://login.microsoftonline.com/${tenant.toLowerCase()}/v2.0`, ...credentials };
+}
+/**
+ * GitHub is OAuth 2.0, not OIDC: no discovery, no ID token. The profile
+ * comes from `GET /user`, and the email from `GET /user/emails` (primary and
+ * verified only), since the public profile email is user-controlled.
+ */
+export function github(credentials) {
+    return {
+        kind: 'oauth2',
+        authorizationEndpoint: 'https://github.com/login/oauth/authorize',
+        tokenEndpoint: 'https://github.com/login/oauth/access_token',
+        userinfoEndpoint: 'https://api.github.com/user',
+        scopes: ['read:user', 'user:email'],
+        ...credentials,
+        async profile(user, { provider, fetchJson }) {
+            if (typeof user?.id !== 'number' && typeof user?.id !== 'string') {
+                throw new Error('unexpected GitHub user');
+            }
+            const emails = await fetchJson(`${this.userinfoEndpoint}/emails`);
+            const primary = Array.isArray(emails)
+                ? emails.find((e) => e?.primary === true && e.verified === true && typeof e.email === 'string')
+                : undefined;
+            return {
+                provider,
+                subject: String(user.id),
+                email: primary?.email,
+                emailVerified: !!primary,
+                name: user.name ?? user.login,
+                picture: user.avatar_url,
+                claims: user,
+            };
+        },
+    };
+}

package/dist/oidc/oidc.service.d.ts

@@ -0,0 +1,88 @@
+import { HttpAdapterHost } from '@nestjs/core';
+import { AuthenticationScope } from '../context/authentication-scope.service.js';
+import { AuthenticationRegistry } from '../services/authentication-registry.service.js';
+import { AuthenticationStorage } from '../storage/authentication.storage.js';
+import { SessionService } from '../session/session.service.js';
+import { SignInService } from '../session/sign-in.service.js';
+import type { OidcOptions, OidcRequest, OidcRedirect, OidcStartOptions } from '../interfaces/oidc.interface.js';
+import { OidcClient } from './oidc.client.js';
+/**
+ * OpenID Connect sign-in, behind two routes of your own: a login route that
+ * redirects to the provider, and the callback route it sends the browser
+ * back to. Called from an HTTP handler, each method reads the request and
+ * sets its cookies on the response, on Express and Fastify alike:
+ *
+ * ```ts
+ * @Public()
+ * @Controller('auth/oidc')
+ * export class OidcController {
+ *   constructor(private readonly oidc: OidcService) {}
+ *
+ *   @Get(':provider/login')
+ *   @Redirect()
+ *   login(@Param('provider') provider: string, @Query('redirectTo') redirectTo?: string, @Query('link') link?: string) {
+ *     return this.oidc.start(provider, { redirectTo, link: link === 'true' });
+ *   }
+ *
+ *   @Get(':provider/callback')
+ *   @Redirect()
+ *   callback(@Param('provider') provider: string, @Query() query: Record<string, string>) {
+ *     return this.oidc.finish(provider, query);
+ *   }
+ * }
+ * ```
+ *
+ * The transaction (PKCE verifier, nonce, return path) stays server-side,
+ * keyed by `state`; the browser gets, in an `HttpOnly` cookie, the secret
+ * whose SHA-256 is the `state`. The callback must present both, which binds
+ * the response to the browser that started the login: another browser
+ * cannot finish it (login CSRF), nor can whoever reads the callback URL in a
+ * log or a history. `SameSite=Lax` lets the cookie through the IdP's
+ * top-level redirect, and the `__Host-` prefix keeps sibling subdomains from
+ * planting one.
+ *
+ * `start(provider, { link: true })` begins a link flow for the signed-in
+ * user instead of a sign-in: the callback re-checks that the same session is
+ * still live, hands `{ linkTo }` to the resolver, and keeps the session as
+ * it is.
+ */
+export declare class OidcService {
+    private readonly storage;
+    private readonly registry;
+    private readonly signIn;
+    private readonly sessions;
+    private readonly scope;
+    private readonly adapterHost?;
+    private readonly clients;
+    private readonly options?;
+    private readonly transactionTtl;
+    private readonly txCookieName;
+    constructor(storage: AuthenticationStorage, registry: AuthenticationRegistry, signIn: SignInService, sessions: SessionService, options?: {
+        oidc?: OidcOptions;
+    }, scope?: AuthenticationScope, adapterHost?: HttpAdapterHost | undefined);
+    client(name: string): OidcClient;
+    /**
+     * Starts a login: stores the transaction, sets its cookie, and returns
+     * the provider's authorization URL. 404 for a provider that isn't
+     * configured; 401 for a link flow without a signed-in session.
+     */
+    start(provider: string, { redirectTo, link, request }?: OidcStartOptions): Promise<OidcRedirect>;
+    /**
+     * Completes a login on the callback route, and returns where to send the
+     * browser: the login's `redirectTo`, else `redirectAfterLogin`. A sign-in
+     * goes through `SignInService`, which sets the session cookie on the
+     * response; the transaction cookie is cleared.
+     */
+    finish(provider: string, query: Record<string, unknown>, { request }?: {
+        request?: OidcRequest;
+    }): Promise<OidcRedirect>;
+    /** Sets the cookies (and `no-store`) on the HTTP response, if there is one. */
+    private redirect;
+    /** The options and the resolver; the module refuses to start with one and not the other. */
+    private feature;
+    /** A fully signed-in session (second factor done, if any) on this request. */
+    private currentSession;
+    private callbackUrl;
+    private txCookie;
+    private now;
+}