@naturalcycles/nodejs-lib 15.119.0 → 15.121.0

package/dist/jwt/index.d.ts

@@ -1,2 +1 @@
 export * from './jwt.service.js';
-export * from './jwt.service2.js';

package/dist/jwt/index.js

@@ -1,2 +1 @@
 export * from './jwt.service.js';
-export * from './jwt.service2.js';

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

@@ -1,49 +1,166 @@
 import type { ErrorData } from '@naturalcycles/js-lib/error';
-import type { AnyObject, JWTString } from '@naturalcycles/js-lib/types';
-import type { Algorithm, JwtHeader, SignOptions, VerifyOptions } from 'jsonwebtoken';
-import jsonwebtoken from 'jsonwebtoken';
+import { AppError } from '@naturalcycles/js-lib/error/error.util.js';
+import type { AnyObject, JWTString, NumberOfSeconds, UnixTimestamp } from '@naturalcycles/js-lib/types';
 import type { AjvSchema, JSchema } from '../validation/ajv/jSchema.js';
-export { jsonwebtoken };
-export type { Algorithm, JwtHeader, SignOptions, VerifyOptions };
-export interface JWTServiceCfg {
+/**
+ * Asymmetric JWS algorithms supported by JWTService.
+ */
+export type JWTAlgorithm = 'ES256' | 'ES384' | 'ES512' | 'RS256' | 'RS384' | 'RS512' | 'PS256' | 'PS384' | 'PS512' | 'EdDSA';
+export interface JWTServiceCfg<T extends AnyObject = AnyObject> {
     /**
      * Public key is required to Verify incoming tokens.
      * Optional if you only want to Decode or Sign.
+     *
+     * PEM string/Buffer. Both SPKI ("PUBLIC KEY") and a private key PEM
+     * (public key is derived from it) are accepted.
      */
     publicKey?: string | Buffer;
     /**
      * Private key is required to Sign (create) outgoing tokens.
      * Optional if you only want to Decode or Verify.
+     *
+     * PEM string/Buffer. Both PKCS8 ("PRIVATE KEY") and SEC1 ("EC PRIVATE KEY",
+     * as generated by `openssl ecparam`) are accepted.
      */
     privateKey?: string | Buffer;
     /**
      * Recommended: ES256
      * Keys (private/public) should be generated using proper settings
      * that fit the used Algorithm.
+     *
+     * Used for Sign, and (unless `verifyAlgorithms` is set) it's also
+     * the only algorithm accepted on Verify.
      */
-    algorithm: Algorithm;
+    algorithm: JWTAlgorithm;
     /**
-     * If provided - will be applied to every Sign operation.
+     * JWS algorithms accepted on Verify. Defaults to `[algorithm]`.
+     *
+     * Only needed when one verifier must accept keys of different types
+     * (e.g a per-kid key set mixing EC and RSA keys). Keep the list as narrow as possible.
+     *
+     * The token's `alg` header chooses among these, but only within what the
+     * verification key can serve: a token/key algorithm mismatch fails with JWTInvalidError.
+     * (All JWTAlgorithms are asymmetric, so the classic algorithm-confusion attacks
+     * don't apply regardless.)
+     */
+    verifyAlgorithms?: JWTAlgorithm[];
+    /**
+     * If provided - payloads are validated against it on every Sign/Verify/Decode.
+     * Can be overridden per-call via `opt.schema`.
+     *
+     * Note: on Verify/Decode the schema is applied to the raw JWT payload, which includes
+     * the standard claims (exp/nbf/iss/aud/sub/iat/jti) if they were set on Sign.
+     * Declare (or allow) them in the schema, otherwise a strict schema will
+     * strip them from the returned payload (default AjvSchema behavior: removeAdditional).
      */
-    signOptions?: SignOptions;
+    schema?: JSchema<T, any> | AjvSchema<T>;
     /**
      * If provided - will be applied to every Sign operation.
+     * Absolute-timestamp options (expiresAt/notBefore/issuedAt) are excluded,
+     * as they would be fixed to the same moment for all tokens signed by this service.
+     */
+    signOptions?: Omit<JWTSignOptions, 'expiresAt' | 'notBefore' | 'issuedAt' | 'schema'>;
+    /**
+     * If provided - will be applied to every Verify operation.
      */
-    verifyOptions?: VerifyOptions;
+    verifyOptions?: Omit<JWTVerifyOptions, 'schema' | 'publicKey'>;
     /**
-     * If set - errors thrown from this service will be extended
+     * If set - JWTErrors thrown from this service will be extended
      * with this errorData (in err.data)
      */
     errorData?: ErrorData;
 }
+export interface JWTSignOptions<T extends AnyObject = AnyObject> {
+    /**
+     * Sets the `exp` claim, as an absolute UnixTimestamp.
+     * Convenient to build with LocalTime, e.g:
+     * `localTime.now().plus(30, 'minute').unix`
+     *
+     * Required, to protect from accidentally issuing never-expiring tokens.
+     * Pass `null` to explicitly sign a token without expiration.
+     */
+    expiresAt: UnixTimestamp | null;
+    /**
+     * Sets the `nbf` (not before) claim, as an absolute UnixTimestamp.
+     */
+    notBefore?: UnixTimestamp;
+    issuer?: string;
+    audience?: string | string[];
+    subject?: string;
+    jwtid?: string;
+    /**
+     * Sets the `iat` claim, as an absolute UnixTimestamp (e.g `localTime.nowUnix()`).
+     * By default `iat` is NOT set (same as the legacy jsonwebtoken-based JWTService
+     * with its `noTimestamp: true` default).
+     */
+    issuedAt?: UnixTimestamp;
+    /**
+     * Sets the `kid` (key id) header, required by some APIs (e.g Apple App Store Connect).
+     */
+    kid?: string;
+    /**
+     * Overrides cfg.schema for this call.
+     */
+    schema?: JSchema<T, any> | AjvSchema<T>;
+}
+export interface JWTVerifyOptions<T extends AnyObject = AnyObject> {
+    audience?: string | string[];
+    issuer?: string | string[];
+    subject?: string;
+    /**
+     * Clock skew tolerance, in seconds.
+     */
+    clockTolerance?: NumberOfSeconds;
+    /**
+     * Maximum allowed age of the token (based on its `iat` claim), in seconds.
+     */
+    maxTokenAge?: NumberOfSeconds;
+    /**
+     * "Now" override, useful in tests.
+     */
+    now?: UnixTimestamp;
+    requiredClaims?: string[];
+    /**
+     * Overrides cfg.schema for this call.
+     */
+    schema?: JSchema<T, any> | AjvSchema<T>;
+    /**
+     * Overrides cfg.publicKey for this call,
+     * e.g when verifying tokens signed with different keys (kid-based).
+     */
+    publicKey?: string | Buffer;
+}
+export interface JWTDecodeOptions<T extends AnyObject = AnyObject> {
+    /**
+     * Overrides cfg.schema for this call.
+     */
+    schema?: JSchema<T, any> | AjvSchema<T>;
+}
+export interface JWTHeader {
+    alg: string;
+    typ?: string;
+    kid?: string;
+    [k: string]: unknown;
+}
+export interface JWTDecoded<T extends AnyObject> {
+    header: JWTHeader;
+    payload: T;
+    signature: string;
+}
 /**
- * @deprecated use JWTService2 (jose-based) instead.
- * Tokens are wire-compatible in both directions, only the API differs
- * (async sign/verify, normalized JWTError).
- * JWTService2 will be renamed to JWTService when this class is dropped.
+ * Wraps the `jose` library, exposing an implementation-agnostic API:
+ * no jose types, options or errors leak out of this service.
+ * All errors are normalized into JWTError subclasses
+ * (JWTExpiredError / JWTNotYetValidError / JWTInvalidError), matchable with `instanceof`.
+ *
+ * Successor of the legacy jsonwebtoken-based JWTService. Tokens are wire-compatible
+ * in both directions, so the two services can be swapped freely for the same key pair.
+ * Difference is that Sign and Verify are async (jose is WebCrypto-based, which is Promise-only),
+ * while Decode remains sync (pure base64url/JSON parsing, no crypto).
  *
- * Wraps popular `jsonwebtoken` library.
  * You should create one instance of JWTService for each pair of private/public key.
+ * Providing cfg.schema types the service to its payload and validates it
+ * on every Sign/Verify/Decode; it can be overridden per-call via opt.schema.
  *
  * Generate key pair like this.
  * Please note that parameters should be different for different algorithms.
@@ -52,14 +169,115 @@ export interface JWTServiceCfg {
  * openssl ecparam -name prime256v1 -genkey -noout -out key.pem
  * openssl ec -in key.pem -pubout > key.pub.pem
  */
-export declare class JWTService {
-    cfg: JWTServiceCfg;
-    constructor(cfg: JWTServiceCfg);
-    sign<T extends AnyObject>(payload: T, schema?: JSchema<T, any> | AjvSchema<T>, opt?: SignOptions): JWTString;
-    verify<T extends AnyObject>(token: JWTString, schema?: JSchema<T, any> | AjvSchema<T>, opt?: VerifyOptions, publicKey?: string): T;
-    decode<T extends AnyObject>(token: JWTString, schema?: JSchema<T, any> | AjvSchema<T>): {
-        header: JwtHeader;
-        payload: T;
-        signature: string;
-    };
+export declare class JWTService<T extends AnyObject = AnyObject> {
+    cfg: JWTServiceCfg<T>;
+    private privateKey?;
+    private publicKey?;
+    constructor(cfg: JWTServiceCfg<T>);
+    sign<TT extends T = T>(payload: TT, opt: JWTSignOptions<TT>): Promise<JWTString>;
+    verify<TT extends T = T>(token: JWTString, opt?: JWTVerifyOptions<TT>): Promise<TT>;
+    /**
+     * Tries to Verify the token, returning an [error, payload] tuple instead of throwing:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, null] - verification failed
+     *
+     * Same contract as tryToVerifyOrDecode, but without the unverified-decode fallback:
+     * the payload is only returned when the token verified.
+     */
+    tryToVerify<TT extends T = T>(token: JWTString, opt?: JWTVerifyOptions<TT>): Promise<[err: null, payload: TT] | [err: Error, payload: null]>;
+    /**
+     * Tries to Verify the token, falling back to unverified Decode on failure,
+     * so the caller can "peek" into the token's content even when it doesn't verify.
+     *
+     * Returns an [error, payload] tuple - ALWAYS check the error first:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, payload] - verification failed, but the token could still be decoded.
+     *   When the error is JWTExpiredError/JWTNotYetValidError, the signature was already
+     *   verified and only the time-claim check failed, so the payload is trustworthy
+     *   (just expired/not yet valid). For any other error the payload is completely
+     *   UNVERIFIED - never trust it, only peek (e.g to log/report the claimed identity).
+     * - [error, null] - the token could not even be decoded
+     *
+     * The decode fallback is raw: opt.schema/cfg.schema are only applied on the Verify path.
+     */
+    tryToVerifyOrDecode<TT extends T = T>(token: JWTString, opt?: JWTVerifyOptions<TT>): Promise<[err: null, payload: TT] | [err: Error, payload: TT | null]>;
+    decode<TT extends T = T>(token: JWTString, opt?: JWTDecodeOptions<TT>): JWTDecoded<TT>;
+    /**
+     * Schema-validation errors on Verify/Decode are extended with cfg.errorData:
+     * a token with a non-conforming payload is as unauthorized as an invalid one.
+     * (On Sign the payload comes from own code, not from user input, so a validation
+     * error there indicates a programming error and is thrown as-is.)
+     */
+    private validate;
+    /**
+     * jose errors are normalized into JWTError subclasses (extended with cfg.errorData).
+     * Non-jose errors (e.g TypeError from passing a key that doesn't fit the algorithm)
+     * indicate a programming error and are passed through as-is.
+     */
+    private normalizeError;
+}
+/**
+ * Decodes a JWT without verifying its signature (no key needed) - never trust the result.
+ * Standalone version of JWTService.decode, for when there's no service instance at hand
+ * (no schema validation, no errorData extension).
+ *
+ * Throws JWTInvalidError if the token cannot be decoded.
+ */
+export declare function jwtDecode<T extends AnyObject>(token: JWTString): JWTDecoded<T>;
+export type JWTErrorCode = 'JWT_EXPIRED' | 'JWT_NOT_YET_VALID' | 'JWT_INVALID';
+export interface JWTErrorData extends ErrorData {
+    code: JWTErrorCode;
+}
+/**
+ * Thrown by JWTService on any Verify/Decode failure, always as one of its subclasses:
+ * - JWTExpiredError - `exp` claim check failed
+ * - JWTNotYetValidError - `nbf` claim check failed
+ * - JWTInvalidError - anything else (malformed token, wrong signature, other claim mismatches)
+ *
+ * Match errors with `instanceof`, e.g `err instanceof JWTExpiredError`.
+ * `data.code` carries the same distinction ('JWT_EXPIRED' | 'JWT_NOT_YET_VALID' | 'JWT_INVALID'),
+ * for when the error crosses a serialization boundary (e.g ErrorObject over HTTP)
+ * where `instanceof` no longer works.
+ *
+ * The underlying jose error is deliberately NOT preserved in `cause`: everything useful
+ * from it is already carried (message is copied, the failed claim is the subclass,
+ * `payload` is exposed where trustworthy), and jose nests the raw JWT payload into its own
+ * `cause`, which would otherwise survive ErrorObject serialization and leak into logs.
+ */
+export declare class JWTError extends AppError<JWTErrorData> {
+    constructor(message: string, data: JWTErrorData);
+}
+/**
+ * The token is well-formed and its signature is valid, but the `exp` claim check failed.
+ *
+ * `payload` carries the decoded token payload: signature is verified before claims are
+ * checked, so the payload is trustworthy - it's just expired.
+ * (Note: it's the raw JWT payload, incl. standard claims; cfg.schema is not applied to it.)
+ */
+export declare class JWTExpiredError extends JWTError {
+    readonly payload: AnyObject;
+    constructor(message: string, data?: ErrorData, opt?: {
+        payload?: AnyObject;
+    });
+}
+/**
+ * The token is well-formed and its signature is valid, but the `nbf` claim check failed.
+ *
+ * `payload` carries the decoded token payload: signature is verified before claims are
+ * checked, so the payload is trustworthy - it's just not valid yet.
+ * (Note: it's the raw JWT payload, incl. standard claims; cfg.schema is not applied to it.)
+ */
+export declare class JWTNotYetValidError extends JWTError {
+    readonly payload: AnyObject;
+    constructor(message: string, data?: ErrorData, opt?: {
+        payload?: AnyObject;
+    });
+}
+/**
+ * The token could not be trusted: malformed token, wrong signature,
+ * or a claim mismatch other than exp/nbf (e.g issuer/audience).
+ * No payload is exposed - nothing from such a token should be used.
+ */
+export declare class JWTInvalidError extends JWTError {
+    constructor(message: string, data?: ErrorData);
 }

package/dist/jwt/jwt.service.js

@@ -1,19 +1,21 @@
+import { createPrivateKey, createPublicKey } from 'node:crypto';
 import { _assert } from '@naturalcycles/js-lib/error/assert.js';
-import { _errorDataAppend } from '@naturalcycles/js-lib/error/error.util.js';
-import jsonwebtoken from 'jsonwebtoken';
-export { jsonwebtoken };
-// todo: define JWTError and list possible options
-// jwt expired (TokenExpiredError)
-// jwt invalid
-// jwt token is empty
+import { _errorDataAppend, AppError } from '@naturalcycles/js-lib/error/error.util.js';
+import { decodeJwt, decodeProtectedHeader, errors, jwtVerify, SignJWT } from 'jose';
 /**
- * @deprecated use JWTService2 (jose-based) instead.
- * Tokens are wire-compatible in both directions, only the API differs
- * (async sign/verify, normalized JWTError).
- * JWTService2 will be renamed to JWTService when this class is dropped.
+ * Wraps the `jose` library, exposing an implementation-agnostic API:
+ * no jose types, options or errors leak out of this service.
+ * All errors are normalized into JWTError subclasses
+ * (JWTExpiredError / JWTNotYetValidError / JWTInvalidError), matchable with `instanceof`.
+ *
+ * Successor of the legacy jsonwebtoken-based JWTService. Tokens are wire-compatible
+ * in both directions, so the two services can be swapped freely for the same key pair.
+ * Difference is that Sign and Verify are async (jose is WebCrypto-based, which is Promise-only),
+ * while Decode remains sync (pure base64url/JSON parsing, no crypto).
  *
- * Wraps popular `jsonwebtoken` library.
  * You should create one instance of JWTService for each pair of private/public key.
+ * Providing cfg.schema types the service to its payload and validates it
+ * on every Sign/Verify/Decode; it can be overridden per-call via opt.schema.
  *
  * Generate key pair like this.
  * Please note that parameters should be different for different algorithms.
@@ -24,47 +26,251 @@ export { jsonwebtoken };
  */
 export class JWTService {
     cfg;
+    privateKey;
+    publicKey;
     constructor(cfg) {
         this.cfg = cfg;
+        // KeyObjects are parsed synchronously via node:crypto (also accepts SEC1 PEMs,
+        // which jose's own async importers reject), keeping the constructor sync.
+        if (cfg.privateKey)
+            this.privateKey = createPrivateKey(cfg.privateKey);
+        if (cfg.publicKey)
+            this.publicKey = createPublicKey(cfg.publicKey);
     }
-    sign(payload, schema, opt = {}) {
-        _assert(this.cfg.privateKey, 'JWTService: privateKey is required to be able to verify, but not provided');
-        schema?.validate(payload);
-        return jsonwebtoken.sign(payload, this.cfg.privateKey, {
-            algorithm: this.cfg.algorithm,
-            noTimestamp: true,
+    async sign(payload, opt) {
+        _assert(this.privateKey, 'JWTService: privateKey is required to be able to sign, but not provided', this.cfg.errorData);
+        const { expiresAt, notBefore, issuer, audience, subject, jwtid, issuedAt, kid, schema } = {
             ...this.cfg.signOptions,
             ...opt,
+        };
+        (schema || this.cfg.schema)?.validate(payload);
+        // `kid: undefined` is dropped by JSON serialization, keeping the header unchanged when not set
+        const jwt = new SignJWT(payload).setProtectedHeader({
+            alg: this.cfg.algorithm,
+            typ: 'JWT',
+            kid,
         });
+        if (expiresAt !== null)
+            jwt.setExpirationTime(expiresAt);
+        if (notBefore !== undefined)
+            jwt.setNotBefore(notBefore);
+        if (issuer)
+            jwt.setIssuer(issuer);
+        if (audience)
+            jwt.setAudience(audience);
+        if (subject)
+            jwt.setSubject(subject);
+        if (jwtid)
+            jwt.setJti(jwtid);
+        if (issuedAt !== undefined)
+            jwt.setIssuedAt(issuedAt);
+        return await jwt.sign(this.privateKey);
     }
-    verify(token, schema, opt = {}, publicKey) {
-        _assert(this.cfg.publicKey, 'JWTService: publicKey is required to be able to verify, but not provided');
+    async verify(token, opt = {}) {
+        const { now, schema, publicKey, ...joseOpt } = {
+            ...this.cfg.verifyOptions,
+            ...opt,
+        };
+        const key = publicKey ? createPublicKey(publicKey) : this.publicKey;
+        _assert(key, 'JWTService: publicKey is required to be able to verify, but not provided', this.cfg.errorData);
+        let data;
         try {
-            const data = jsonwebtoken.verify(token, publicKey || this.cfg.publicKey, {
-                algorithms: [this.cfg.algorithm],
-                ...this.cfg.verifyOptions,
-                ...opt,
+            const { payload } = await jwtVerify(token, key, {
+                algorithms: this.cfg.verifyAlgorithms || [this.cfg.algorithm],
+                ...joseOpt,
+                currentDate: now === undefined ? undefined : new Date(now * 1000),
             });
-            schema?.validate(data);
-            return data;
+            data = payload;
+        }
+        catch (err) {
+            throw this.normalizeError(err);
+        }
+        this.validate(data, schema);
+        return data;
+    }
+    /**
+     * Tries to Verify the token, returning an [error, payload] tuple instead of throwing:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, null] - verification failed
+     *
+     * Same contract as tryToVerifyOrDecode, but without the unverified-decode fallback:
+     * the payload is only returned when the token verified.
+     */
+    async tryToVerify(token, opt = {}) {
+        try {
+            return [null, await this.verify(token, opt)];
+        }
+        catch (err) {
+            return [err, null];
+        }
+    }
+    /**
+     * Tries to Verify the token, falling back to unverified Decode on failure,
+     * so the caller can "peek" into the token's content even when it doesn't verify.
+     *
+     * Returns an [error, payload] tuple - ALWAYS check the error first:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, payload] - verification failed, but the token could still be decoded.
+     *   When the error is JWTExpiredError/JWTNotYetValidError, the signature was already
+     *   verified and only the time-claim check failed, so the payload is trustworthy
+     *   (just expired/not yet valid). For any other error the payload is completely
+     *   UNVERIFIED - never trust it, only peek (e.g to log/report the claimed identity).
+     * - [error, null] - the token could not even be decoded
+     *
+     * The decode fallback is raw: opt.schema/cfg.schema are only applied on the Verify path.
+     */
+    async tryToVerifyOrDecode(token, opt = {}) {
+        const [verifyError, payload] = await this.tryToVerify(token, opt);
+        if (!verifyError)
+            return [null, payload];
+        // Expired/not-yet-valid errors already carry the (signature-verified) payload
+        if (verifyError instanceof JWTExpiredError || verifyError instanceof JWTNotYetValidError) {
+            return [verifyError, verifyError.payload];
+        }
+        try {
+            return [verifyError, jwtDecode(token).payload];
+        }
+        catch {
+            return [verifyError, null];
+        }
+    }
+    decode(token, opt = {}) {
+        let decoded;
+        try {
+            decoded = jwtDecode(token);
         }
         catch (err) {
             if (this.cfg.errorData) {
-                _errorDataAppend(err, {
-                    ...this.cfg.errorData,
-                });
+                _errorDataAppend(err, this.cfg.errorData);
             }
             throw err;
         }
+        this.validate(decoded.payload, opt.schema);
+        return decoded;
     }
-    decode(token, schema) {
-        const data = jsonwebtoken.decode(token, {
-            complete: true,
-        });
-        _assert(data?.payload, 'invalid token, decoded value is empty', {
-            ...this.cfg.errorData,
-        });
-        schema?.validate(data.payload);
-        return data;
+    /**
+     * Schema-validation errors on Verify/Decode are extended with cfg.errorData:
+     * a token with a non-conforming payload is as unauthorized as an invalid one.
+     * (On Sign the payload comes from own code, not from user input, so a validation
+     * error there indicates a programming error and is thrown as-is.)
+     */
+    validate(payload, schema) {
+        try {
+            ;
+            (schema || this.cfg.schema)?.validate(payload);
+        }
+        catch (err) {
+            if (this.cfg.errorData) {
+                _errorDataAppend(err, this.cfg.errorData);
+            }
+            throw err;
+        }
+    }
+    /**
+     * jose errors are normalized into JWTError subclasses (extended with cfg.errorData).
+     * Non-jose errors (e.g TypeError from passing a key that doesn't fit the algorithm)
+     * indicate a programming error and are passed through as-is.
+     */
+    normalizeError(err) {
+        const { errorData } = this.cfg;
+        if (err instanceof errors.JWTExpired) {
+            return new JWTExpiredError(err.message, errorData, { payload: err.payload });
+        }
+        if (err instanceof errors.JWTClaimValidationFailed && err.claim === 'nbf') {
+            return new JWTNotYetValidError(err.message, errorData, { payload: err.payload });
+        }
+        if (err instanceof errors.JOSEError) {
+            return new JWTInvalidError(err.message, errorData);
+        }
+        if (this.cfg.verifyAlgorithms && err instanceof TypeError) {
+            // With multiple verifyAlgorithms, a token/key algorithm mismatch is reachable
+            // by untrusted input, and jose reports it as TypeError - treat it as an invalid token
+            return new JWTInvalidError(err.message, errorData);
+        }
+        return err;
+    }
+}
+/**
+ * Decodes a JWT without verifying its signature (no key needed) - never trust the result.
+ * Standalone version of JWTService.decode, for when there's no service instance at hand
+ * (no schema validation, no errorData extension).
+ *
+ * Throws JWTInvalidError if the token cannot be decoded.
+ */
+export function jwtDecode(token) {
+    let header;
+    let payload;
+    try {
+        header = decodeProtectedHeader(token);
+        payload = decodeJwt(token);
+    }
+    catch (err) {
+        // The underlying message is folded in, as it carries the only specific detail
+        throw new JWTInvalidError(`invalid token, unable to decode: ${err.message}`);
+    }
+    return {
+        header,
+        payload,
+        signature: token.split('.')[2],
+    };
+}
+/**
+ * Thrown by JWTService on any Verify/Decode failure, always as one of its subclasses:
+ * - JWTExpiredError - `exp` claim check failed
+ * - JWTNotYetValidError - `nbf` claim check failed
+ * - JWTInvalidError - anything else (malformed token, wrong signature, other claim mismatches)
+ *
+ * Match errors with `instanceof`, e.g `err instanceof JWTExpiredError`.
+ * `data.code` carries the same distinction ('JWT_EXPIRED' | 'JWT_NOT_YET_VALID' | 'JWT_INVALID'),
+ * for when the error crosses a serialization boundary (e.g ErrorObject over HTTP)
+ * where `instanceof` no longer works.
+ *
+ * The underlying jose error is deliberately NOT preserved in `cause`: everything useful
+ * from it is already carried (message is copied, the failed claim is the subclass,
+ * `payload` is exposed where trustworthy), and jose nests the raw JWT payload into its own
+ * `cause`, which would otherwise survive ErrorObject serialization and leak into logs.
+ */
+export class JWTError extends AppError {
+    constructor(message, data) {
+        // `new.target.name` makes subclasses report their own name
+        super(message, data, { name: new.target.name });
+    }
+}
+/**
+ * The token is well-formed and its signature is valid, but the `exp` claim check failed.
+ *
+ * `payload` carries the decoded token payload: signature is verified before claims are
+ * checked, so the payload is trustworthy - it's just expired.
+ * (Note: it's the raw JWT payload, incl. standard claims; cfg.schema is not applied to it.)
+ */
+export class JWTExpiredError extends JWTError {
+    payload;
+    constructor(message, data = {}, opt = {}) {
+        super(message, { ...data, code: 'JWT_EXPIRED' });
+        this.payload = opt.payload || {};
+    }
+}
+/**
+ * The token is well-formed and its signature is valid, but the `nbf` claim check failed.
+ *
+ * `payload` carries the decoded token payload: signature is verified before claims are
+ * checked, so the payload is trustworthy - it's just not valid yet.
+ * (Note: it's the raw JWT payload, incl. standard claims; cfg.schema is not applied to it.)
+ */
+export class JWTNotYetValidError extends JWTError {
+    payload;
+    constructor(message, data = {}, opt = {}) {
+        super(message, { ...data, code: 'JWT_NOT_YET_VALID' });
+        this.payload = opt.payload || {};
+    }
+}
+/**
+ * The token could not be trusted: malformed token, wrong signature,
+ * or a claim mismatch other than exp/nbf (e.g issuer/audience).
+ * No payload is exposed - nothing from such a token should be used.
+ */
+export class JWTInvalidError extends JWTError {
+    constructor(message, data = {}) {
+        super(message, { ...data, code: 'JWT_INVALID' });
     }
 }

package/dist/validation/ajv/jSchema.d.ts

@@ -271,7 +271,16 @@ export declare class JString<OUT extends string | undefined = string, Opt extend
     ipv4(): this;
     ipv6(): this;
     slug(): this;
+    /**
+     * Validates the 3-part semver format: `major.minor.patch`, e.g `1.2.3`.
+     */
     semVer(): this;
+    /**
+     * Validates the 4-part version format: `major.minor.patch.build`, e.g `1.2.3.4`.
+     *
+     * Not a semver by the spec, but is used by e.g .NET and some mobile app versions.
+     */
+    semVer4(): this;
     languageTag(): this;
     countryCode(): this;
     currency(): this;