@nestjs/authentication 0.0.1

package/dist/jwt/jwks.client.js

@@ -0,0 +1,154 @@
+import { createPublicKey } from 'node:crypto';
+import { durationOr } from '../utils/duration.util.js';
+import { JwtError } from '../errors/jwt.error.js';
+import { ASYMMETRIC_ALGORITHMS } from './jws.util.js';
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]']);
+function algorithmsFor(jwk) {
+    if (jwk.kty === 'RSA') {
+        return ['RS256'];
+    }
+    if (jwk.kty === 'EC' && jwk.crv === 'P-256') {
+        return ['ES256'];
+    }
+    if (jwk.kty === 'OKP' && jwk.crv === 'Ed25519') {
+        return ['EdDSA'];
+    }
+    return [];
+}
+/**
+ * A cached JSON Web Key Set, shared by bearer-token verification and OIDC
+ * ID tokens.
+ *
+ * - Keys are cached for `cacheTtl`; an unknown `kid` triggers a refetch
+ *   (key rotation), at most once per `cooldown`.
+ * - Concurrent refreshes share one request.
+ * - A failed refresh keeps serving the previous keys. With no keys to
+ *   serve, it is an outage (a plain `Error`, so a 500, never a 401 that
+ *   would make clients drop valid tokens), retried at most once per
+ *   `cooldown`.
+ * - Keys marked `use` ≠ `sig`, with `key_ops` lacking `verify`, of
+ *   unsupported types, or whose `alg` disagrees with the token are ignored.
+ */
+export class JwksClient {
+    constructor(uri, options = {}) {
+        this.uri = uri;
+        this.keys = [];
+        this.fetchedAt = -Infinity;
+        this.attemptedAt = -Infinity;
+        /** Number of network fetches, for tests and metrics. */
+        this.fetchCount = 0;
+        let url;
+        try {
+            url = new URL(uri);
+        }
+        catch {
+            url = undefined;
+        }
+        // Whoever serves the key set decides which tokens verify: never over plain http, but on loopback.
+        if (!url || (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOOPBACK.has(url.hostname)))) {
+            throw new TypeError(`JwksClient: the key set must be an https URL (http only on loopback), got ${JSON.stringify(uri)}.`);
+        }
+        this.options = {
+            ...options,
+            cacheTtl: durationOr(options.cacheTtl, '10m'),
+            cooldown: durationOr(options.cooldown, '30s'),
+            timeout: durationOr(options.timeout, '5s'),
+        };
+    }
+    async getKey(header) {
+        const alg = header.alg;
+        if (!ASYMMETRIC_ALGORITHMS.includes(alg)) {
+            throw new JwtError('unsupported algorithm');
+        }
+        if (this.now() - this.fetchedAt >= this.options.cacheTtl) {
+            await this.refresh(true);
+        }
+        let found = this.find(header.kid, alg);
+        if (!found && this.now() - this.attemptedAt >= this.options.cooldown) {
+            await this.refresh(false);
+            found = this.find(header.kid, alg);
+        }
+        if (!found) {
+            throw new JwtError('no matching key');
+        }
+        return found;
+    }
+    find(kid, alg) {
+        const candidates = this.keys.filter((k) => k.algorithms.includes(alg) && (!k.alg || k.alg === alg));
+        if (kid !== undefined) {
+            return candidates.find((k) => k.kid === kid)?.key;
+        }
+        // No kid: only unambiguous sets are usable.
+        return candidates.length === 1 ? candidates[0].key : undefined;
+    }
+    refresh(expired) {
+        this.inflight ??= this.load(expired).finally(() => (this.inflight = undefined));
+        return this.inflight;
+    }
+    async load(expired) {
+        // Nothing to serve and the last attempt failed recently: do not hammer a provider that is down.
+        if (this.failure && this.keys.length === 0 && this.now() - this.attemptedAt < this.options.cooldown) {
+            throw this.failure;
+        }
+        this.attemptedAt = this.now();
+        try {
+            this.fetchCount++;
+            const response = await (this.options.fetch ?? fetch)(this.uri, {
+                headers: { accept: 'application/json' },
+                signal: AbortSignal.timeout(this.options.timeout),
+                redirect: 'error',
+            });
+            if (!response.ok) {
+                throw new Error(`it answered ${response.status}`);
+            }
+            const body = (await response.json());
+            if (!Array.isArray(body.keys)) {
+                throw new Error('it has no keys array');
+            }
+            // Each entry on its own: one the client cannot read (null, `key_ops` that is no list) is skipped,
+            // and the set's other keys still load.
+            this.keys = body.keys.flatMap((entry) => {
+                try {
+                    if (typeof entry !== 'object' || entry === null) {
+                        return [];
+                    }
+                    const jwk = entry;
+                    if (jwk.use !== undefined && jwk.use !== 'sig') {
+                        return [];
+                    }
+                    if (jwk.key_ops !== undefined && !(Array.isArray(jwk.key_ops) && jwk.key_ops.includes('verify'))) {
+                        return [];
+                    }
+                    const algorithms = algorithmsFor(jwk);
+                    if (algorithms.length === 0) {
+                        return [];
+                    }
+                    // Only the public members are read; a JWKS that leaks `d` still yields a public key.
+                    const { d: _d, p: _p, q: _q, dp: _dp, dq: _dq, qi: _qi, ...publicJwk } = jwk;
+                    const key = createPublicKey({ key: publicJwk, format: 'jwk' });
+                    const kid = typeof jwk.kid === 'string' ? jwk.kid : undefined;
+                    const alg = typeof jwk.alg === 'string' ? jwk.alg : undefined;
+                    return [{ kid, alg, algorithms, key }];
+                }
+                catch {
+                    return [];
+                }
+            });
+            this.fetchedAt = this.now();
+            this.failure = undefined;
+        }
+        catch (error) {
+            // Keep serving the last good set; fail only if there is none.
+            if (this.keys.length === 0) {
+                this.failure = new Error(`JWKS ${this.uri} is unavailable: ${error.message}`, { cause: error });
+                throw this.failure;
+            }
+            if (expired) {
+                this.fetchedAt = this.now() - this.options.cacheTtl + this.options.cooldown;
+            }
+        }
+    }
+    now() {
+        return this.options.now?.() ?? Date.now();
+    }
+}

package/dist/jwt/jws.util.d.ts

@@ -0,0 +1,45 @@
+import { KeyObject } from 'node:crypto';
+import type { JwsAlgorithm, JwtClaims, ClaimRules } from '../interfaces/jwt.interface.js';
+export declare const ASYMMETRIC_ALGORITHMS: readonly JwsAlgorithm[];
+export interface JwsHeader {
+    alg: string;
+    kid?: string;
+    typ?: string;
+    crit?: unknown;
+    [key: string]: unknown;
+}
+/**
+ * A key from configuration. PEM text (a string or a `Buffer`: SPKI, PKCS#1,
+ * PKCS#8, SEC1, or an X.509 certificate) is read as the key it encodes;
+ * only other text is an HMAC secret. Read as a secret, a PEM public key
+ * would let anyone who has it, which is everyone, sign HS256 tokens. So
+ * would a JWK, or a key in DER (bytes, or base64 of them), which are refused:
+ * import it with `createPublicKey({ key, format: 'jwk' })` (or `'der'`, or
+ * `createPrivateKey`) and pass the `KeyObject`.
+ */
+export declare function toKeyObject(key: KeyObject | string | Buffer): KeyObject;
+/** The algorithm a key implies: HS256 for a secret, the key's own for asymmetric keys. */
+export declare function algorithmFor(key: KeyObject): JwsAlgorithm | undefined;
+/**
+ * Whether `key` is appropriate for `alg`. This is the algorithm/key binding
+ * that stops key-confusion attacks: an RSA public key can never be used as
+ * an HMAC secret, a P-384 key never verifies ES256, and so on.
+ */
+export declare function keyFits(alg: JwsAlgorithm, key: KeyObject): boolean;
+/** Throws a `TypeError` (configuration, not a token) unless `key` can serve `alg`. */
+export declare function assertKeyFits(alg: JwsAlgorithm, key: KeyObject, owner: string): void;
+/** Throws a `TypeError` (configuration, not a token) unless `key` can sign `alg`. */
+export declare function assertSigningKey(alg: JwsAlgorithm, key: KeyObject, owner: string): void;
+export declare function signJws(header: JwsHeader & {
+    alg: JwsAlgorithm;
+}, payload: object, key: KeyObject): string;
+export interface DecodedJws {
+    header: JwsHeader;
+    payload: JwtClaims;
+    signingInput: Buffer;
+    signature: Buffer;
+}
+/** Splits and decodes without verifying. */
+export declare function decodeJws(token: string): DecodedJws;
+export declare function verifySignature(alg: JwsAlgorithm, key: KeyObject, decoded: DecodedJws): void;
+export declare function validateClaims(claims: JwtClaims, rules: ClaimRules): void;

package/dist/jwt/jws.util.js

@@ -0,0 +1,282 @@
+import { KeyObject, X509Certificate, createHmac, createPrivateKey, createPublicKey, createSecretKey, sign as cryptoSign, verify as cryptoVerify, timingSafeEqual, } from 'node:crypto';
+import { toMs } from '../utils/duration.util.js';
+import { JwtError } from '../errors/jwt.error.js';
+export const ASYMMETRIC_ALGORITHMS = ['RS256', 'ES256', 'EdDSA'];
+const SEGMENT = /^[A-Za-z0-9_-]+$/;
+const PEM = /-----BEGIN ([A-Z0-9 ]+)-----/g;
+/**
+ * A key from configuration. PEM text (a string or a `Buffer`: SPKI, PKCS#1,
+ * PKCS#8, SEC1, or an X.509 certificate) is read as the key it encodes;
+ * only other text is an HMAC secret. Read as a secret, a PEM public key
+ * would let anyone who has it, which is everyone, sign HS256 tokens. So
+ * would a JWK, or a key in DER (bytes, or base64 of them), which are refused:
+ * import it with `createPublicKey({ key, format: 'jwk' })` (or `'der'`, or
+ * `createPrivateKey`) and pass the `KeyObject`.
+ */
+export function toKeyObject(key) {
+    if (key instanceof KeyObject) {
+        return key;
+    }
+    const text = typeof key === 'string' ? key : key.toString('latin1');
+    // Every block's label: `openssl ecparam -genkey` puts EC PARAMETERS before the private key, and
+    // a bundle may put a certificate first.
+    const labels = [...text.matchAll(PEM)].map((match) => match[1]);
+    if (labels.length === 0) {
+        if (isJwk(text)) {
+            throw new TypeError('The key is a JWK, which would be read as an HS256 secret. Import it and pass the KeyObject: ' +
+                "`createPublicKey({ key: JSON.parse(jwk), format: 'jwk' })`, or `createPrivateKey` for a private key.");
+        }
+        if (isEncodedKey(key)) {
+            throw new TypeError('The key is DER (binary, or base64 of it, as Keycloak shows `public_key`), which would be read as an ' +
+                "HS256 secret. Pass PEM text, or the KeyObject: `createPublicKey({ key, format: 'der', type: 'spki' })`.");
+        }
+        return createSecretKey(typeof key === 'string' ? Buffer.from(key) : key);
+    }
+    const label = labels.find((name) => name.includes('PRIVATE KEY')) ?? labels[0];
+    try {
+        return label.includes('PRIVATE KEY') ? createPrivateKey(key) : createPublicKey(key);
+    }
+    catch (error) {
+        throw new TypeError(`Cannot read the PEM ${label.toLowerCase()}: ${error.message}`);
+    }
+}
+/** The algorithm a key implies: HS256 for a secret, the key's own for asymmetric keys. */
+export function algorithmFor(key) {
+    if (key.type === 'secret') {
+        return 'HS256';
+    }
+    switch (key.asymmetricKeyType) {
+        case 'rsa':
+            return 'RS256';
+        case 'ec':
+            return 'ES256';
+        case 'ed25519':
+            return 'EdDSA';
+        default:
+            return undefined;
+    }
+}
+/**
+ * Whether `key` is appropriate for `alg`. This is the algorithm/key binding
+ * that stops key-confusion attacks: an RSA public key can never be used as
+ * an HMAC secret, a P-384 key never verifies ES256, and so on.
+ */
+export function keyFits(alg, key) {
+    const details = key.asymmetricKeyDetails;
+    switch (alg) {
+        case 'HS256':
+            return key.type === 'secret' && (key.symmetricKeySize ?? 0) >= 32;
+        case 'RS256':
+            return key.asymmetricKeyType === 'rsa' && (details?.modulusLength ?? 0) >= 2048;
+        case 'ES256':
+            return key.asymmetricKeyType === 'ec' && details?.namedCurve === 'prime256v1';
+        case 'EdDSA':
+            return key.asymmetricKeyType === 'ed25519';
+        default:
+            return false;
+    }
+}
+const REQUIREMENTS = {
+    HS256: 'a secret of at least 32 bytes (`openssl rand -base64 32`)',
+    RS256: 'an RSA key of at least 2048 bits',
+    ES256: 'a P-256 key',
+    EdDSA: 'an Ed25519 key',
+};
+/** Throws a `TypeError` (configuration, not a token) unless `key` can serve `alg`. */
+export function assertKeyFits(alg, key, owner) {
+    if (!keyFits(alg, key)) {
+        throw new TypeError(`${owner}: the key is not a valid ${alg} key; ${alg} needs ${REQUIREMENTS[alg]}.`);
+    }
+}
+/** Throws a `TypeError` (configuration, not a token) unless `key` can sign `alg`. */
+export function assertSigningKey(alg, key, owner) {
+    assertKeyFits(alg, key, owner);
+    if (alg !== 'HS256' && key.type !== 'private') {
+        throw new TypeError(`${owner}: ${alg} signing needs a private key.`);
+    }
+}
+export function signJws(header, payload, key) {
+    assertSigningKey(header.alg, key, 'JwtSigner');
+    const input = `${encode(header)}.${encode(payload)}`;
+    const data = Buffer.from(input);
+    let signature;
+    switch (header.alg) {
+        case 'HS256':
+            signature = createHmac('sha256', key).update(data).digest();
+            break;
+        case 'RS256':
+            signature = cryptoSign('sha256', data, key);
+            break;
+        case 'ES256':
+            signature = cryptoSign('sha256', data, { key, dsaEncoding: 'ieee-p1363' });
+            break;
+        case 'EdDSA':
+            signature = cryptoSign(null, data, key);
+            break;
+    }
+    return `${input}.${signature.toString('base64url')}`;
+}
+/** Splits and decodes without verifying. */
+export function decodeJws(token) {
+    const parts = token.split('.');
+    if (parts.length !== 3 || !parts.every((p) => SEGMENT.test(p))) {
+        throw new JwtError('malformed token');
+    }
+    const header = decodeJson(parts[0]);
+    if (typeof header.alg !== 'string') {
+        throw new JwtError('malformed token');
+    }
+    // One signature, one spelling: the unused low bits of the last character would otherwise give
+    // several token strings for one token, and a list or a cache keyed by the string would miss them.
+    const signature = Buffer.from(parts[2], 'base64url');
+    if (signature.toString('base64url') !== parts[2]) {
+        throw new JwtError('malformed token');
+    }
+    return {
+        header,
+        payload: decodeJson(parts[1]),
+        signingInput: Buffer.from(`${parts[0]}.${parts[1]}`),
+        signature,
+    };
+}
+export function verifySignature(alg, key, decoded) {
+    const publicKey = key.type === 'private' ? createPublicKey(key) : key;
+    if (!keyFits(alg, publicKey)) {
+        throw new JwtError(`key is not a valid ${alg} key`);
+    }
+    const { signingInput, signature } = decoded;
+    let valid;
+    switch (alg) {
+        case 'HS256': {
+            const expected = createHmac('sha256', publicKey).update(signingInput).digest();
+            valid = signature.length === expected.length && timingSafeEqual(signature, expected);
+            break;
+        }
+        case 'RS256':
+            valid = cryptoVerify('sha256', signingInput, publicKey, signature);
+            break;
+        case 'ES256':
+            // JWS uses the raw r||s form (RFC 7518 §3.4), not DER.
+            valid =
+                signature.length === 64 &&
+                    cryptoVerify('sha256', signingInput, { key: publicKey, dsaEncoding: 'ieee-p1363' }, signature);
+            break;
+        case 'EdDSA':
+            valid = signature.length === 64 && cryptoVerify(null, signingInput, publicKey, signature);
+            break;
+        default:
+            valid = false;
+    }
+    if (!valid) {
+        throw new JwtError('invalid signature');
+    }
+}
+export function validateClaims(claims, rules) {
+    // JWT times are seconds (RFC 7519 §2, NumericDate).
+    const now = Math.floor((rules.now?.() ?? Date.now()) / 1000);
+    const leeway = toMs(rules.clockTolerance ?? 0) / 1000;
+    for (const name of rules.required ?? ['exp']) {
+        if (claims[name] === undefined) {
+            throw new JwtError(`missing ${name}`);
+        }
+    }
+    for (const name of ['exp', 'nbf', 'iat']) {
+        if (claims[name] !== undefined && (typeof claims[name] !== 'number' || !Number.isFinite(claims[name]))) {
+            throw new JwtError(`invalid ${name}`);
+        }
+    }
+    // What `JwtClaims` promises `validate()`.
+    for (const name of ['iss', 'sub', 'jti']) {
+        if (claims[name] !== undefined && typeof claims[name] !== 'string') {
+            throw new JwtError(`invalid ${name}`);
+        }
+    }
+    if (claims.exp !== undefined && now >= claims.exp + leeway) {
+        throw new JwtError('token expired');
+    }
+    if (claims.nbf !== undefined && now < claims.nbf - leeway) {
+        throw new JwtError('token not yet valid');
+    }
+    if (claims.iat !== undefined && claims.iat > now + leeway) {
+        throw new JwtError('token issued in the future');
+    }
+    if (rules.maxAge !== undefined) {
+        if (claims.iat === undefined) {
+            throw new JwtError('missing iat');
+        }
+        if (now - claims.iat > toMs(rules.maxAge) / 1000 + leeway) {
+            throw new JwtError('token too old');
+        }
+    }
+    if (rules.issuer !== undefined && claims.iss !== rules.issuer) {
+        throw new JwtError('unexpected issuer');
+    }
+    if (rules.audience !== undefined && rules.audience !== false) {
+        const accepted = [].concat(rules.audience);
+        const given = [].concat(claims.aud ?? []);
+        if (!given.some((aud) => typeof aud === 'string' && accepted.includes(aud))) {
+            throw new JwtError('unexpected audience');
+        }
+    }
+}
+/**
+ * Whether the bytes are a key or a certificate in DER, given as bytes or as
+ * base64 text: never a secret (random bytes do not parse as DER), and what a
+ * key management service's `GetPublicKey` or Keycloak's `public_key` gives.
+ */
+function isEncodedKey(key) {
+    const candidates = [];
+    if (Buffer.isBuffer(key)) {
+        candidates.push(key);
+    }
+    const compact = (typeof key === 'string' ? key : key.toString('latin1')).replace(/\s+/g, '');
+    if (/^[A-Za-z0-9+/_-]{40,}={0,2}$/.test(compact)) {
+        candidates.push(Buffer.from(compact, 'base64'));
+    }
+    const readers = [
+        (der) => createPublicKey({ key: der, format: 'der', type: 'spki' }),
+        (der) => createPublicKey({ key: der, format: 'der', type: 'pkcs1' }),
+        (der) => createPrivateKey({ key: der, format: 'der', type: 'pkcs8' }),
+        (der) => createPrivateKey({ key: der, format: 'der', type: 'pkcs1' }),
+        (der) => createPrivateKey({ key: der, format: 'der', type: 'sec1' }),
+        (der) => new X509Certificate(der),
+    ];
+    return candidates.some((der) => readers.some((read) => {
+        try {
+            read(der);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+}
+/** A JSON Web Key (a JSON object with `kty`), as a JWKS or an environment variable holds one. */
+function isJwk(text) {
+    if (!text.trimStart().startsWith('{')) {
+        return false;
+    }
+    try {
+        const value = JSON.parse(text);
+        return typeof value === 'object' && value !== null && typeof value.kty === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+function encode(value) {
+    return Buffer.from(JSON.stringify(value)).toString('base64url');
+}
+function decodeJson(segment) {
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(segment, 'base64url').toString('utf8'));
+    }
+    catch {
+        throw new JwtError('malformed token');
+    }
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw new JwtError('malformed token');
+    }
+    return value;
+}

package/dist/jwt/jwt-bearer.provider.d.ts

@@ -0,0 +1,48 @@
+import { type ExecutionContext } from '@nestjs/common';
+import { AuthenticationProvider, PROVIDER_INIT, type ProviderInit } from '../providers/authentication.provider.js';
+import type { AuthenticationResult, MfaState } from '../interfaces/authentication-result.interface.js';
+import type { JwtClaims } from '../interfaces/jwt.interface.js';
+import type { JwtBearerProviderOptions } from '../interfaces/jwt-options.interface.js';
+/**
+ * Base class for `Authorization: Bearer <jwt>` authentication. Extend it,
+ * inject what `validate()` needs, and load the user:
+ *
+ * ```ts
+ * @Injectable()
+ * export class JwtAuth extends JwtBearerProvider<User> {
+ *   constructor(private readonly users: UsersRepository) {
+ *     super(); // verifies the tokens the module's `accessToken` option signs
+ *   }
+ *   validate(claims: JwtClaims) {
+ *     return this.users.findById(claims.sub!);
+ *   }
+ * }
+ * ```
+ *
+ * Without `key` or `jwks`, it verifies what the module's `accessToken`
+ * option issues: the same key, algorithm, issuer, audience and `typ`. For
+ * tokens from another issuer, pass them: `super({ jwks, issuer, audience })`
+ * (a `jwks` needs both `issuer` and `audience`).
+ *
+ * Over socket.io it also reads `handshake.auth.token`. A token shaped like
+ * an API key (`ApiKeyProvider`) is left to the other providers. `session`
+ * is the verified claim set; an `amr` claim containing `mfa`, `otp` or
+ * `hwk` marks the result as MFA-verified.
+ */
+export declare abstract class JwtBearerProvider<TUser> extends AuthenticationProvider<TUser, JwtClaims> {
+    private readonly options;
+    private moduleOptions?;
+    private verifier?;
+    private readonly realm;
+    constructor(options?: JwtBearerProviderOptions);
+    /** Maps verified claims to the user. `null` (a deleted user) rejects the token. */
+    protected abstract validate(claims: JwtClaims): TUser | null | undefined | Promise<TUser | null | undefined>;
+    authenticate(context: ExecutionContext): Promise<AuthenticationResult<TUser, JwtClaims> | null>;
+    challenge(): string;
+    protected mfaState(claims: JwtClaims): MfaState | undefined;
+    /** @internal */
+    [PROVIDER_INIT](resolve: Parameters<ProviderInit>[0]): void;
+    private getVerifier;
+    private extract;
+    private reject;
+}

package/dist/jwt/jwt-bearer.provider.js

@@ -0,0 +1,126 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+import { Inject, Optional } from '@nestjs/common';
+import { AuthenticationProvider, PROVIDER_INIT } from '../providers/authentication.provider.js';
+import { AUTHENTICATION_MODULE_OPTIONS } from '../authentication.constants.js';
+import { AuthenticationError } from '../errors/authentication.error.js';
+import { JwtError } from '../errors/jwt.error.js';
+import { API_KEY_PATTERN } from '../utils/api-key.util.js';
+import { bearerToken } from '../utils/bearer.util.js';
+import { hasMfaAmr } from './amr.util.js';
+import { JwtVerifier, verifierForSigner } from './jwt-verifier.service.js';
+/**
+ * Base class for `Authorization: Bearer <jwt>` authentication. Extend it,
+ * inject what `validate()` needs, and load the user:
+ *
+ * ```ts
+ * @Injectable()
+ * export class JwtAuth extends JwtBearerProvider<User> {
+ *   constructor(private readonly users: UsersRepository) {
+ *     super(); // verifies the tokens the module's `accessToken` option signs
+ *   }
+ *   validate(claims: JwtClaims) {
+ *     return this.users.findById(claims.sub!);
+ *   }
+ * }
+ * ```
+ *
+ * Without `key` or `jwks`, it verifies what the module's `accessToken`
+ * option issues: the same key, algorithm, issuer, audience and `typ`. For
+ * tokens from another issuer, pass them: `super({ jwks, issuer, audience })`
+ * (a `jwks` needs both `issuer` and `audience`).
+ *
+ * Over socket.io it also reads `handshake.auth.token`. A token shaped like
+ * an API key (`ApiKeyProvider`) is left to the other providers. `session`
+ * is the verified claim set; an `amr` claim containing `mfa`, `otp` or
+ * `hwk` marks the result as MFA-verified.
+ */
+export class JwtBearerProvider extends AuthenticationProvider {
+    constructor(options = {}) {
+        super();
+        this.options = options;
+        this.realm = options.realm ?? 'api';
+        // `super({ key: process.env.PARTNER_KEY })` with the variable unset must not fall back to the
+        // module's `accessToken`: this provider would take the app's own tokens as its issuer's.
+        const named = ['key', 'jwks'].filter((name) => Object.hasOwn(options, name));
+        if (named.length > 0 && !options.key && !options.jwks) {
+            throw new TypeError(`${new.target.name}: \`${named.join('` and `')}\` ${named.length > 1 ? 'are' : 'is'} empty: is the environment ` +
+                "variable it reads set? Leave both out to verify the tokens the module's `accessToken` issues.");
+        }
+        if (options.key !== undefined || options.jwks !== undefined) {
+            this.verifier = new JwtVerifier(options);
+        }
+    }
+    async authenticate(context) {
+        const token = this.extract(context);
+        if (token === undefined) {
+            return null;
+        }
+        let claims;
+        try {
+            claims = await this.getVerifier().verify(token);
+        }
+        catch (error) {
+            if (error instanceof JwtError) {
+                this.reject(error.message);
+            }
+            throw error;
+        }
+        const user = await this.validate(claims);
+        if (user === null || user === undefined) {
+            this.reject('unknown subject');
+        }
+        return { user, session: claims, mfa: this.mfaState(claims) };
+    }
+    challenge() {
+        return `Bearer realm="${this.realm}"`;
+    }
+    mfaState(claims) {
+        return hasMfaAmr(claims.amr) ? 'verified' : undefined;
+    }
+    /** @internal */
+    [PROVIDER_INIT](resolve) {
+        this.moduleOptions ??= resolve(AUTHENTICATION_MODULE_OPTIONS);
+        this.getVerifier();
+    }
+    getVerifier() {
+        if (this.verifier) {
+            return this.verifier;
+        }
+        const accessToken = this.moduleOptions?.accessToken;
+        if (!accessToken) {
+            throw new Error(`${this.constructor.name}: nothing to verify tokens with. Configure \`accessToken\` in the ` +
+                'AuthenticationModule options, or pass `key` or `jwks` to super().');
+        }
+        const { realm: _, ...rules } = this.options;
+        const defined = Object.fromEntries(Object.entries(rules).filter(([, value]) => value !== undefined));
+        this.verifier = verifierForSigner(accessToken, defined);
+        return this.verifier;
+    }
+    extract(context) {
+        const token = bearerToken(context, this.header(context, 'authorization'));
+        if (token === null) {
+            this.reject('malformed authorization header');
+        }
+        // An API key is `ApiKeyProvider`'s, which may run after this one.
+        return token === undefined || API_KEY_PATTERN.test(token) ? undefined : token;
+    }
+    reject(description) {
+        // RFC 6750 §3.1
+        throw new AuthenticationError(description, {
+            challenge: `Bearer realm="${this.realm}", error="invalid_token", error_description="${description}"`,
+        });
+    }
+}
+__decorate([
+    Optional(),
+    Inject(AUTHENTICATION_MODULE_OPTIONS),
+    __metadata("design:type", Object)
+], JwtBearerProvider.prototype, "moduleOptions", void 0);

package/dist/jwt/jwt-signer.service.d.ts

@@ -0,0 +1,19 @@
+import type { Duration } from '../interfaces/duration.interface.js';
+import type { JwtClaims } from '../interfaces/jwt.interface.js';
+import type { JwtSignerOptions } from '../interfaces/jwt-options.interface.js';
+/**
+ * Issues signed JWTs. Adds `iat`, `exp`, `jti` and the configured
+ * `iss`/`aud`; callers pass `sub` and custom claims. The module's
+ * `accessToken` option configures the one `TokenService` uses; construct
+ * others directly.
+ */
+export declare class JwtSigner {
+    private readonly options;
+    private readonly key;
+    private readonly alg;
+    /** Throws a `TypeError` for a key that cannot sign, or an invalid `ttl`. */
+    constructor(options: JwtSignerOptions);
+    sign(claims: JwtClaims, { ttl }?: {
+        ttl?: Duration;
+    }): string;
+}