@nestjs/authentication 0.0.1 → 0.1.1

package/dist/interfaces/authentication-result.interface.d.ts

@@ -10,6 +10,13 @@ export type AuthenticatedUser = AuthenticationTypes extends {
 export type AuthenticatedSession = AuthenticationTypes extends {
     session: infer S;
 } ? S : unknown;
+/**
+ * The type of `SessionRecord.extra` declared on {@link AuthenticationTypes}
+ * (`sessionExtra`), `unknown` otherwise.
+ */
+export type SessionExtra = AuthenticationTypes extends {
+    sessionExtra: infer E;
+} ? E : unknown;
 /**
  * `pending`: first factor done, second factor outstanding. Such a result
  * does not count as signed in: `SignInService.completeMfa()` finishes it.

package/dist/interfaces/jwt-options.interface.d.ts

@@ -19,7 +19,7 @@ export interface JwksClientOptions {
 }
 export interface JwtVerifierOptions extends ClaimRules {
     /**
-     * A static key: an HS256 secret (at least 32 bytes), or a public or
+     * A static key: an HMAC secret (at least 32 bytes for HS256), or a public or
      * private key as a `KeyObject` or PEM text (a string or a `Buffer`). A
      * public key needs `issuer` and `audience`, as a `jwks` does: it is an
      * identity provider's, which signs the tokens of all its clients with it.
@@ -34,9 +34,11 @@ export interface JwtVerifierOptions extends ClaimRules {
      */
     jwks?: string | JwksClient;
     /**
-     * Accepted `alg` values. Defaults: `['HS256']` for a secret, the key's own
-     * algorithm for an asymmetric key, `['RS256', 'ES256']` for a JWKS.
-     * `none` is never accepted.
+     * Accepted `alg` values. Defaults: `['HS256']` for a secret, `['RS256']`
+     * for an RSA key, the curve's own (`ES256`, `ES384`, `ES512`) for an EC
+     * key, `['EdDSA']` for an Ed25519 key, and `['RS256', 'ES256']` for a JWKS.
+     * Others (`RS384`, `PS256`, `HS512`, …) are opted into here. `none` is
+     * never accepted, and HS algorithms never with a JWKS.
      */
     algorithms?: JwsAlgorithm[];
     /** Required `typ` header, e.g. `at+jwt` (RFC 9068). Not checked by default. */
@@ -44,12 +46,16 @@ export interface JwtVerifierOptions extends ClaimRules {
 }
 export interface JwtSignerOptions {
     /**
-     * An HS256 secret (at least 32 bytes), or a private key for RS256, ES256
-     * or EdDSA: a `KeyObject`, or PEM text (a string or a `Buffer`). A JWK, or
+     * An HMAC secret (at least as long as the hash: 32, 48 or 64 bytes), or an
+     * RSA, P-256, P-384, P-521 or Ed25519 private key: a `KeyObject`, or PEM
+     * text (a string or a `Buffer`). A JWK, or
      * DER, is refused: pass `createPrivateKey({ key: jwk, format: 'jwk' })`.
      */
     key: KeyObject | string | Buffer;
-    /** Default: HS256 for a secret, the key's own algorithm for a private key. */
+    /**
+     * Default: HS256 for a secret, RS256 for an RSA key, the curve's own for
+     * an EC key, EdDSA for an Ed25519 key.
+     */
     alg?: JwsAlgorithm;
     /** Published in the header so verifiers can pick the key from a JWKS. */
     kid?: string;

package/dist/interfaces/jwt.interface.d.ts

@@ -1,9 +1,10 @@
 import type { Duration } from './duration.interface.js';
 /**
- * Supported JWS algorithms. EdDSA means Ed25519 only: Ed448 is rejected
- * (untested here, and rare in practice).
+ * Supported JWS algorithms (RFC 7518 §3.1). EdDSA means Ed25519 only: Ed448
+ * is rejected (untested here, and rare in practice). PS256/384/512 take an
+ * RSA key, as a JWKS publishes it; Node's `rsa-pss` key type is rejected.
  */
-export type JwsAlgorithm = 'HS256' | 'RS256' | 'ES256' | 'EdDSA';
+export type JwsAlgorithm = 'HS256' | 'HS384' | 'HS512' | 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'ES256' | 'ES384' | 'ES512' | 'EdDSA';
 export interface JwtClaims {
     iss?: string;
     sub?: string;

package/dist/interfaces/magic-link.interface.d.ts

@@ -23,7 +23,8 @@ export interface MagicLinkOptions {
      * Whether a link works only in the browser that requested it. Default
      * `true`: `create()` sets a transaction cookie, and `consume()` refuses a
      * link the browser holds no cookie for (`magic-link-refused`,
-     * `not-this-browser`). Without it, anyone can request a link for their
+     * `not-this-browser`). The cookie keeps the last five links the browser
+     * requested: a "resend" does not void the link before it. Without it, anyone can request a link for their
      * own address and get someone else to open it, which signs that person's
      * browser in to the attacker's account (login CSRF). `false` trades that
      * for links that work on another device than the one that asked for them

package/dist/interfaces/oidc.interface.d.ts

@@ -45,8 +45,16 @@ export interface OidcOptions extends OidcClientOptions {
      * The public URL of your callback route, the redirect URI you register
      * with each provider. `:provider` is replaced by the provider's name:
      * `https://app.example.com/auth/oidc/:provider/callback`.
+     *
+     * An app served under several domains passes a function of the request
+     * instead, called on the login and again on the callback: both must
+     * answer the same URL, or the provider refuses the code. Check the host
+     * against your own list of domains rather than echoing the header, and
+     * register every URL it can answer with each provider. The transaction
+     * cookie is bound to the host that set it, so a login finishes on the
+     * domain where it started.
      */
-    callbackUrl: string;
+    callbackUrl: string | ((request: OidcRequest) => string | Promise<string>);
     providers: Record<string, OidcProviderConfig>;
     /** Where to land after sign-in when the login had no `redirectTo`. Default `/`. */
     redirectAfterLogin?: string;

package/dist/interfaces/session-store.interface.d.ts

@@ -1,4 +1,4 @@
-import type { MfaState } from './authentication-result.interface.js';
+import type { MfaState, SessionExtra } from './authentication-result.interface.js';
 export interface SessionRecord {
     /** SHA-256 of the cookie token. The token itself is never stored. */
     id: string;
@@ -11,6 +11,19 @@ export interface SessionRecord {
     mfa?: MfaState;
     /** App data: user agent, IP, device name, for "your sessions" pages. */
     metadata?: Record<string, unknown>;
+    /**
+     * Whatever `getSession()` read along with the session, typically its user
+     * from the same query (`JOIN users`), handed to
+     * `SessionCookieProvider.validate()` so a cookie request costs one read.
+     * Typed by `sessionExtra` on `AuthenticationTypes`.
+     *
+     * Never stored: `SessionService` leaves it out of every `createSession()`
+     * (rotations included), and `@CurrentSession()`, `request.session` and
+     * `AuthenticationContext.session` don't carry it. Join fresh data on every
+     * read; don't keep a copy of the user on the session row, which goes stale
+     * when the user changes.
+     */
+    extra?: SessionExtra;
 }
 /**
  * Where sessions live. Implement it on your database or Redis, and register
@@ -22,12 +35,16 @@ export interface SessionRecord {
  * from `SessionService`'s clock, never the store's.
  */
 export interface SessionStore {
-    /** The session, or `undefined`. Expired sessions may be returned: `SessionService` checks expiry. */
+    /**
+     * The session, or `undefined`. Expired sessions may be returned: `SessionService` checks expiry.
+     * May set `extra` to what the same query read with it (the user, joined), for
+     * `SessionCookieProvider.validate()`.
+     */
     getSession(id: string): Promise<SessionRecord | undefined>;
     /**
      * Saves a new session (a fresh random id: a plain insert). A good place
      * to delete sessions whose `expiresAt` has passed, so the store stays
-     * bounded.
+     * bounded. `record` never carries `extra`.
      */
     createSession(record: SessionRecord): Promise<void>;
     /**
@@ -36,6 +53,11 @@ export interface SessionStore {
      * WHERE id = ? AND last_active_at < ?`, `SET … XX` in Redis. A read
      * followed by a write lets a request that read the session before a
      * sign-out or rotation deleted it bring it back. Changes no other field.
+     *
+     * Best-effort: a rejection is published as `session-touch-failed` (every
+     * one) and logged (once per spell of failures), but the request goes on
+     * with the session as read. A missed touch only means the session goes idle at its previous
+     * deadline, unless a later request records activity.
      */
     touchSession(id: string, lastActiveAt: Date): Promise<void>;
     /**
@@ -46,7 +68,10 @@ export interface SessionStore {
      * rotations), only one may win.
      */
     deleteSession(id: string): Promise<boolean>;
-    /** The user's sessions, in any order (`[]` when none), expired ones included. */
+    /**
+     * The user's sessions, in any order (`[]` when none), expired ones included.
+     * Without `extra`: they feed "your sessions" pages.
+     */
     listUserSessions(userId: string): Promise<SessionRecord[]>;
     /** Deletes every session of the user ("sign out everywhere"). */
     deleteUserSessions(userId: string): Promise<void>;

package/dist/interfaces/token.interface.d.ts

@@ -1,3 +1,4 @@
+import type { AuthenticationTypes } from '../index.js';
 export interface IssueTokensOptions {
     /**
      * Claims that describe the sign-in (`amr`, `auth_time`, …): this access
@@ -19,12 +20,38 @@ export interface IssueTokensOptions {
         recoveryCode?: string;
     };
 }
-/** What a token endpoint returns to a client that signed in. */
-export interface TokenPair {
+/**
+ * What `TokenService.issue()` returns with `refreshToken: false`: an access
+ * token alone, which the client replaces by signing in again.
+ */
+export interface AccessTokenResult {
     /** A JWT signed with the `accessToken` options. */
     accessToken: string;
-    /** Opaque, single use: `refresh()` exchanges it for a new pair. */
-    refreshToken: string;
     /** Seconds until the access token expires (OAuth's `expires_in`). */
     expiresIn: number;
 }
+/** What a token endpoint returns to a client that signed in. */
+export interface TokenPair extends AccessTokenResult {
+    /** Opaque, single use: `refresh()` exchanges it for a new pair. */
+    refreshToken: string;
+}
+/**
+ * What `TokenService.issue()` returns: a {@link TokenPair}, or, for an app
+ * that declared `refreshTokens: false` on `AuthenticationTypes` (to go with
+ * the `refreshToken: false` option), an {@link AccessTokenResult}:
+ *
+ * ```ts
+ * declare module '@nestjs/authentication' {
+ *   interface AuthenticationTypes {
+ *     refreshTokens: false;
+ *   }
+ * }
+ * ```
+ *
+ * The declaration is what the compiler sees; the option is what runs. An
+ * app that sets the option without the declaration gets no `refreshToken`
+ * at run time, typed as a string, and `refresh()` throws on it.
+ */
+export type IssuedTokens<Types = AuthenticationTypes> = Types extends {
+    refreshTokens: false;
+} ? AccessTokenResult : TokenPair;

package/dist/jwt/jwks.client.js

@@ -3,12 +3,19 @@ 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]']);
+/** The algorithm of each curve a JWK can name (`crv`, RFC 7518 §6.2.1.1). Other curves are skipped. */
+const EC_ALGORITHMS = { 'P-256': 'ES256', 'P-384': 'ES384', 'P-521': 'ES512' };
+/**
+ * What a JWK can verify, by its type and curve. An RSA key serves every RS and
+ * PS algorithm: its `alg`, when published, narrows that, and the verifier's
+ * `algorithms` decide which of them are accepted at all.
+ */
 function algorithmsFor(jwk) {
     if (jwk.kty === 'RSA') {
-        return ['RS256'];
+        return ['RS256', 'RS384', 'RS512', 'PS256', 'PS384', 'PS512'];
     }
-    if (jwk.kty === 'EC' && jwk.crv === 'P-256') {
-        return ['ES256'];
+    if (jwk.kty === 'EC' && jwk.crv && EC_ALGORITHMS[jwk.crv]) {
+        return [EC_ALGORITHMS[jwk.crv]];
     }
     if (jwk.kty === 'OKP' && jwk.crv === 'Ed25519') {
         return ['EdDSA'];

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

@@ -1,5 +1,6 @@
 import { KeyObject } from 'node:crypto';
 import type { JwsAlgorithm, JwtClaims, ClaimRules } from '../interfaces/jwt.interface.js';
+/** The algorithms a public key verifies: the only ones a JWKS can serve (HS secrets are never published). */
 export declare const ASYMMETRIC_ALGORITHMS: readonly JwsAlgorithm[];
 export interface JwsHeader {
     alg: string;
@@ -18,14 +19,22 @@ export interface JwsHeader {
  * `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. */
+/**
+ * The algorithm a key implies: HS256 for a secret, RS256 for an RSA key (the
+ * key does not name a hash or padding: PS and the longer hashes are opted
+ * into with `alg`), and the curve's own for an EC key.
+ */
 export declare function algorithmFor(key: KeyObject): JwsAlgorithm | undefined;
+/** The configuration error for a key no algorithm fits: an EC key names its curve, as EC keys of other curves are. */
+export declare function unsupportedKeyError(key: KeyObject, owner: string): TypeError;
 /**
  * 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;
+/** HS256, HS384, HS512: signed and verified with the same secret, so no private key is involved. */
+export declare const isHmac: (alg: JwsAlgorithm) => 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`. */

package/dist/jwt/jws.util.js

@@ -1,7 +1,27 @@
-import { KeyObject, X509Certificate, createHmac, createPrivateKey, createPublicKey, createSecretKey, sign as cryptoSign, verify as cryptoVerify, timingSafeEqual, } from 'node:crypto';
+import { KeyObject, X509Certificate, constants, 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'];
+/** The algorithms a public key verifies: the only ones a JWKS can serve (HS secrets are never published). */
+export const ASYMMETRIC_ALGORITHMS = [
+    'RS256',
+    'RS384',
+    'RS512',
+    'PS256',
+    'PS384',
+    'PS512',
+    'ES256',
+    'ES384',
+    'ES512',
+    'EdDSA',
+];
+/** `HS384` → `sha384`: the digest every algorithm but EdDSA names in its last three digits. */
+const hashOf = (alg) => `sha${alg.slice(2)}`;
+/** The curve each ECDSA algorithm is bound to (RFC 7518 §3.4), by its OpenSSL name. */
+const CURVES = { ES256: 'prime256v1', ES384: 'secp384r1', ES512: 'secp521r1' };
+/** The reverse: the one algorithm an EC key of each curve implies. Other curves (secp256k1, …) imply none. */
+const CURVE_ALGORITHMS = { prime256v1: 'ES256', secp384r1: 'ES384', secp521r1: 'ES512' };
+/** Raw r||s length: twice the curve's coordinate size (P-521's is 66 bytes, not 64). */
+const ECDSA_SIGNATURE_BYTES = { ES256: 64, ES384: 96, ES512: 132 };
 const SEGMENT = /^[A-Za-z0-9_-]+$/;
 const PEM = /-----BEGIN ([A-Z0-9 ]+)-----/g;
 /**
@@ -40,7 +60,11 @@ export function toKeyObject(key) {
         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. */
+/**
+ * The algorithm a key implies: HS256 for a secret, RS256 for an RSA key (the
+ * key does not name a hash or padding: PS and the longer hashes are opted
+ * into with `alg`), and the curve's own for an EC key.
+ */
 export function algorithmFor(key) {
     if (key.type === 'secret') {
         return 'HS256';
@@ -49,13 +73,20 @@ export function algorithmFor(key) {
         case 'rsa':
             return 'RS256';
         case 'ec':
-            return 'ES256';
+            return CURVE_ALGORITHMS[key.asymmetricKeyDetails?.namedCurve ?? ''];
         case 'ed25519':
             return 'EdDSA';
         default:
             return undefined;
     }
 }
+/** The configuration error for a key no algorithm fits: an EC key names its curve, as EC keys of other curves are. */
+export function unsupportedKeyError(key, owner) {
+    const curve = key.asymmetricKeyType === 'ec' ? key.asymmetricKeyDetails?.namedCurve : undefined;
+    return new TypeError(curve
+        ? `${owner}: EC keys on ${curve} are not supported (use P-256, P-384 or P-521).`
+        : `${owner}: ${key.asymmetricKeyType} keys are not supported.`);
+}
 /**
  * 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
@@ -64,24 +95,53 @@ export function algorithmFor(key) {
 export function keyFits(alg, key) {
     const details = key.asymmetricKeyDetails;
     switch (alg) {
+        // A secret at least as long as the hash's output (RFC 7518 §3.2).
         case 'HS256':
             return key.type === 'secret' && (key.symmetricKeySize ?? 0) >= 32;
+        case 'HS384':
+            return key.type === 'secret' && (key.symmetricKeySize ?? 0) >= 48;
+        case 'HS512':
+            return key.type === 'secret' && (key.symmetricKeySize ?? 0) >= 64;
+        // One RSA key serves both paddings and every hash: the header names which, and the verifier's
+        // `algorithms` decide which are accepted. Node's `rsa-pss` keys are refused (asymmetricKeyType
+        // 'rsa-pss'): they restrict their own hash and salt, which a JWKS cannot even publish.
         case 'RS256':
+        case 'RS384':
+        case 'RS512':
+        case 'PS256':
+        case 'PS384':
+        case 'PS512':
             return key.asymmetricKeyType === 'rsa' && (details?.modulusLength ?? 0) >= 2048;
+        // Each ECDSA algorithm takes its own curve only: an ES256 token never verifies with a P-384 key.
         case 'ES256':
-            return key.asymmetricKeyType === 'ec' && details?.namedCurve === 'prime256v1';
+        case 'ES384':
+        case 'ES512':
+            return key.asymmetricKeyType === 'ec' && details?.namedCurve === CURVES[alg];
         case 'EdDSA':
             return key.asymmetricKeyType === 'ed25519';
         default:
             return false;
     }
 }
+/** What each algorithm needs, for the configuration error that names it. */
+const RSA_KEY = 'an RSA key of at least 2048 bits';
 const REQUIREMENTS = {
     HS256: 'a secret of at least 32 bytes (`openssl rand -base64 32`)',
-    RS256: 'an RSA key of at least 2048 bits',
+    HS384: 'a secret of at least 48 bytes (`openssl rand -base64 48`)',
+    HS512: 'a secret of at least 64 bytes (`openssl rand -base64 64`)',
+    RS256: RSA_KEY,
+    RS384: RSA_KEY,
+    RS512: RSA_KEY,
+    PS256: RSA_KEY,
+    PS384: RSA_KEY,
+    PS512: RSA_KEY,
     ES256: 'a P-256 key',
+    ES384: 'a P-384 key',
+    ES512: 'a P-521 key',
     EdDSA: 'an Ed25519 key',
 };
+/** HS256, HS384, HS512: signed and verified with the same secret, so no private key is involved. */
+export const isHmac = (alg) => alg.startsWith('HS');
 /** Throws a `TypeError` (configuration, not a token) unless `key` can serve `alg`. */
 export function assertKeyFits(alg, key, owner) {
     if (!keyFits(alg, key)) {
@@ -91,7 +151,7 @@ export function assertKeyFits(alg, key, owner) {
 /** 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') {
+    if (!isHmac(alg) && key.type !== 'private') {
         throw new TypeError(`${owner}: ${alg} signing needs a private key.`);
     }
 }
@@ -99,16 +159,28 @@ export function signJws(header, payload, key) {
     assertSigningKey(header.alg, key, 'JwtSigner');
     const input = `${encode(header)}.${encode(payload)}`;
     const data = Buffer.from(input);
+    const { alg } = header;
     let signature;
-    switch (header.alg) {
+    switch (alg) {
         case 'HS256':
-            signature = createHmac('sha256', key).update(data).digest();
+        case 'HS384':
+        case 'HS512':
+            signature = createHmac(hashOf(alg), key).update(data).digest();
             break;
         case 'RS256':
-            signature = cryptoSign('sha256', data, key);
+        case 'RS384':
+        case 'RS512':
+            signature = cryptoSign(hashOf(alg), data, key); // PKCS#1 v1.5 padding, Node's default for RSA
+            break;
+        case 'PS256':
+        case 'PS384':
+        case 'PS512':
+            signature = cryptoSign(hashOf(alg), data, pss(key));
             break;
         case 'ES256':
-            signature = cryptoSign('sha256', data, { key, dsaEncoding: 'ieee-p1363' });
+        case 'ES384':
+        case 'ES512':
+            signature = cryptoSign(hashOf(alg), data, { key, dsaEncoding: 'ieee-p1363' });
             break;
         case 'EdDSA':
             signature = cryptoSign(null, data, key);
@@ -147,19 +219,31 @@ export function verifySignature(alg, key, decoded) {
     const { signingInput, signature } = decoded;
     let valid;
     switch (alg) {
-        case 'HS256': {
-            const expected = createHmac('sha256', publicKey).update(signingInput).digest();
+        case 'HS256':
+        case 'HS384':
+        case 'HS512': {
+            const expected = createHmac(hashOf(alg), publicKey).update(signingInput).digest();
             valid = signature.length === expected.length && timingSafeEqual(signature, expected);
             break;
         }
         case 'RS256':
-            valid = cryptoVerify('sha256', signingInput, publicKey, signature);
+        case 'RS384':
+        case 'RS512':
+            valid = cryptoVerify(hashOf(alg), signingInput, publicKey, signature);
+            break;
+        // Same key as RS, other padding: a PKCS#1 v1.5 signature presented as PS (or the reverse) fails here.
+        case 'PS256':
+        case 'PS384':
+        case 'PS512':
+            valid = cryptoVerify(hashOf(alg), signingInput, pss(publicKey), signature);
             break;
         case 'ES256':
+        case 'ES384':
+        case 'ES512':
             // 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);
+                signature.length === ECDSA_SIGNATURE_BYTES[alg] &&
+                    cryptoVerify(hashOf(alg), signingInput, { key: publicKey, dsaEncoding: 'ieee-p1363' }, signature);
             break;
         case 'EdDSA':
             valid = signature.length === 64 && cryptoVerify(null, signingInput, publicKey, signature);
@@ -171,6 +255,14 @@ export function verifySignature(alg, key, decoded) {
         throw new JwtError('invalid signature');
     }
 }
+/**
+ * RSASSA-PSS options (RFC 7518 §3.5): MGF1 on the same hash (Node's default),
+ * and a salt exactly as long as the hash. Verifying with this exact length,
+ * not "any", refuses signatures made with another salt length.
+ */
+function pss(key) {
+    return { key, padding: constants.RSA_PKCS1_PSS_PADDING, saltLength: constants.RSA_PSS_SALTLEN_DIGEST };
+}
 export function validateClaims(claims, rules) {
     // JWT times are seconds (RFC 7519 §2, NumericDate).
     const now = Math.floor((rules.now?.() ?? Date.now()) / 1000);

package/dist/jwt/jwt-signer.service.js

@@ -1,6 +1,6 @@
 import { randomToken } from '../utils/crypto.util.js';
 import { durationOr, toMs } from '../utils/duration.util.js';
-import { algorithmFor, assertSigningKey, signJws, toKeyObject } from './jws.util.js';
+import { algorithmFor, assertSigningKey, signJws, toKeyObject, unsupportedKeyError } from './jws.util.js';
 /**
  * Issues signed JWTs. Adds `iat`, `exp`, `jti` and the configured
  * `iss`/`aud`; callers pass `sub` and custom claims. The module's
@@ -14,7 +14,7 @@ export class JwtSigner {
         this.key = toKeyObject(options.key);
         const alg = options.alg ?? algorithmFor(this.key);
         if (!alg) {
-            throw new TypeError(`JwtSigner: ${this.key.asymmetricKeyType} keys are not supported.`);
+            throw unsupportedKeyError(this.key, 'JwtSigner');
         }
         assertSigningKey(alg, this.key, 'JwtSigner');
         this.alg = alg;

package/dist/jwt/jwt-verifier.service.js

@@ -2,7 +2,7 @@ import { createPublicKey } from 'node:crypto';
 import { toMs } from '../utils/duration.util.js';
 import { JwtError } from '../errors/jwt.error.js';
 import { JwksClient } from './jwks.client.js';
-import { algorithmFor, assertKeyFits, decodeJws, toKeyObject, validateClaims, verifySignature } from './jws.util.js';
+import { algorithmFor, assertKeyFits, decodeJws, isHmac, toKeyObject, unsupportedKeyError, validateClaims, verifySignature, } from './jws.util.js';
 /**
  * Verifies compact JWS tokens and their registered claims. `verify()`
  * throws {@link JwtError}; a configuration that could not verify anything
@@ -26,7 +26,7 @@ export class JwtVerifier {
         if (this.key) {
             const implied = algorithmFor(this.key);
             if (!implied) {
-                throw new TypeError(`JwtVerifier: ${this.key.asymmetricKeyType} keys are not supported.`);
+                throw unsupportedKeyError(this.key, 'JwtVerifier');
             }
             this.algorithms = options.algorithms ?? [implied];
             for (const alg of this.algorithms) {
@@ -40,8 +40,10 @@ export class JwtVerifier {
         }
         else {
             this.algorithms = options.algorithms ?? ['RS256', 'ES256'];
-            if (this.algorithms.includes('HS256')) {
-                throw new TypeError('JwtVerifier: HS256 cannot be combined with a JWKS.');
+            // A JWKS publishes keys to everyone: an HMAC secret taken from one would let anyone sign.
+            const hmac = this.algorithms.find(isHmac);
+            if (hmac) {
+                throw new TypeError(`JwtVerifier: ${hmac} cannot be combined with a JWKS.`);
             }
             requireIssuerAndAudience(options, '`jwks`');
         }

package/dist/jwt/token.service.d.ts

@@ -3,13 +3,13 @@ import { AuthenticationEvents } from '../events/authentication-events.service.js
 import { MfaService } from '../mfa/mfa.service.js';
 import type { JwtSignerOptions } from '../interfaces/jwt-options.interface.js';
 import type { RefreshTokenOptions } from '../interfaces/refresh-token-options.interface.js';
-import type { IssueTokensOptions, TokenPair } from '../interfaces/token.interface.js';
+import type { IssueTokensOptions, IssuedTokens, TokenPair } from '../interfaces/token.interface.js';
 /**
  * Tokens for clients that do not keep cookies (mobile apps, CLIs): a
  * short-lived JWT access token, and an opaque refresh token that renews it.
  *
  * - `issue()` is to token clients what `SignInService.signIn()` is to
- *   browsers: a user with a confirmed authenticator gets no tokens without
+ *   browsers: with `mfa` configured, a user with a confirmed authenticator gets no tokens without
  *   a second factor.
  * - Access tokens are signed with the module's `accessToken` options, the
  *   same ones `JwtBearerProvider` verifies with by default.
@@ -19,6 +19,12 @@ import type { IssueTokensOptions, TokenPair } from '../interfaces/token.interfac
  *   concurrent presentations (`markRefreshTokenUsed()` is a compare-and-set), means two
  *   parties hold it: the whole family is revoked, and both have to sign in
  *   again (OAuth 2.0 Security BCP §4.14.2).
+ * - With `refreshToken: false`, there are none: `issue()` returns an access
+ *   token alone and stores nothing, `refresh()` and `revoke()` throw, and
+ *   `revokeAll()` does nothing. For a service that signs short-lived access
+ *   tokens and asks the client to sign in again; a service that only
+ *   verifies tokens can also leave `accessToken` out and give its
+ *   `JwtBearerProvider` the key (`super({ key })`).
  */
 export declare class TokenService {
     private readonly storage;
@@ -32,14 +38,18 @@ export declare class TokenService {
     private readonly ttl;
     private readonly absoluteTtl;
     private readonly clock?;
+    /** `refreshToken: false`: access tokens only, no families. */
+    private readonly refreshTokensOff;
     constructor(storage: AuthenticationStorage, options?: {
         accessToken?: JwtSignerOptions;
-        refreshToken?: RefreshTokenOptions;
+        refreshToken?: RefreshTokenOptions | false;
     }, events?: AuthenticationEvents, mfa?: MfaService);
     /**
      * At sign-in: signs an access token and starts a refresh-token family.
+     * With `refreshToken: false`, returns the access token alone (typed by
+     * {@link IssuedTokens}), and stores nothing.
      *
-     * A user with a confirmed authenticator must send a second factor
+     * With `mfa` configured, a user with a confirmed authenticator must send a second factor
      * (`secondFactor`). Without one, `issue()` throws an
      * `AuthenticationError` whose body says `mfa_required`, and counts
      * nothing against the user's lockout; with a wrong one, `Invalid code`.
@@ -47,11 +57,12 @@ export declare class TokenService {
      * `@Authenticate({ mfa: true })` accepts; `claims.amr` cannot (see
      * {@link IssueTokensOptions.claims}).
      */
-    issue(userId: string, { claims, method, secondFactor }?: IssueTokensOptions): Promise<TokenPair>;
+    issue(userId: string, { claims, method, secondFactor }?: IssueTokensOptions): Promise<IssuedTokens>;
     /**
      * Spends a refresh token: returns its successor, and an access token with
      * the family's claims. Throws {@link RefreshTokenError} (`invalid`,
-     * `expired`, `reused`), which a route answers with 401.
+     * `expired`, `reused`), which a route answers with 401. Throws without
+     * `accessToken`, and with `refreshToken: false`.
      */
     refresh(refreshToken: string): Promise<TokenPair>;
     /** Two parties hold the token: the family is revoked, and the theft reported. */
@@ -60,14 +71,24 @@ export declare class TokenService {
      * Signs out the client holding `refreshToken` (one device): revokes its
      * family. Spent tokens of the family work too. Resolves `false` for
      * unknown or malformed tokens, which a route should not reveal (RFC 7009
-     * §2.2).
+     * §2.2). Throws without `accessToken`, and with `refreshToken: false`, as
+     * `refresh()` does.
      */
     revoke(refreshToken: string): Promise<boolean>;
-    /** Signs the user out of every token client. Issued access tokens live until they expire. */
+    /**
+     * Signs the user out of every token client. Issued access tokens live
+     * until they expire. Without `accessToken`, or with `refreshToken: false`,
+     * this app issues no refresh tokens, and there is nothing to revoke: the
+     * store is not read. Apps that
+     * share a user database configure `accessToken` in all of them if any of
+     * them issues tokens: otherwise this one's sign-outs everywhere leave the
+     * token clients of the others signed in.
+     */
     revokeAll(userId: string): Promise<void>;
     /** `true` when a second factor was required and verified; throws when one is required and missing or wrong. */
     private checkSecondFactor;
     private pair;
+    private requireRefreshTokens;
     private requireSigner;
     private create;
     /**