@naturalcycles/nodejs-lib 15.119.0 → 15.121.0

package/dist/validation/ajv/jSchema.js

@@ -5,7 +5,7 @@ import { _deepCopy, _filterNullishValues, _sortObject } from '@naturalcycles/js-
 import { _substringBefore } from '@naturalcycles/js-lib/string';
 import { _objectAssign, _typeCast, JWT_REGEX } from '@naturalcycles/js-lib/types';
 import { _inspect } from '../../string/inspect.js';
-import { BASE64URL_REGEX, COUNTRY_CODE_REGEX, CURRENCY_REGEX, IPV4_REGEX, IPV6_REGEX, LANGUAGE_TAG_REGEX, SEMVER_REGEX, SLUG_REGEX, URL_REGEX, UUID_REGEX, } from '../regexes.js';
+import { BASE64URL_REGEX, COUNTRY_CODE_REGEX, CURRENCY_REGEX, IPV4_REGEX, IPV6_REGEX, LANGUAGE_TAG_REGEX, SEMVER4_REGEX, SEMVER_REGEX, SLUG_REGEX, URL_REGEX, UUID_REGEX, } from '../regexes.js';
 import { TIMEZONES } from '../timezones.js';
 import { AjvValidationError } from './ajvValidationError.js';
 import { getAjv } from './getAjv.js';
@@ -623,9 +623,20 @@ export class JString extends JBuilder {
     slug() {
         return this.regex(SLUG_REGEX, { msg: 'is not a valid slug format' });
     }
+    /**
+     * Validates the 3-part semver format: `major.minor.patch`, e.g `1.2.3`.
+     */
     semVer() {
         return this.regex(SEMVER_REGEX, { msg: 'is not a valid semver format' });
     }
+    /**
+     * 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() {
+        return this.regex(SEMVER4_REGEX, { msg: 'is not a valid 4-part semver format' });
+    }
     languageTag() {
         return this.regex(LANGUAGE_TAG_REGEX, { msg: 'is not a valid language format' });
     }

package/dist/validation/regexes.d.ts

@@ -17,5 +17,6 @@ export declare const IPV6_REGEX: RegExp;
 export declare const LANGUAGE_TAG_REGEX: RegExp;
 export declare const MAC_ADDRESS_REGEX: RegExp;
 export declare const SEMVER_REGEX: RegExp;
+export declare const SEMVER4_REGEX: RegExp;
 export declare const SLUG_REGEX: RegExp;
 export declare const URL_REGEX: RegExp;

package/dist/validation/regexes.js

@@ -22,6 +22,8 @@ export const IPV6_REGEX = /^((([0-9a-fA-F]{1,4}:){7}([0-9a-fA-F]{1,4}|:))|(([0-9
 export const LANGUAGE_TAG_REGEX = /^[a-z]{2}(-[A-Z]{2})?$/;
 export const MAC_ADDRESS_REGEX = /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/;
 export const SEMVER_REGEX = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+// 4-part version (major.minor.patch.build)
+export const SEMVER4_REGEX = /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/;
 export const SLUG_REGEX = /^[a-z0-9-]+$/;
 // URL regex based on `ajv-formats`, but without flags for JSON Schema compatibility.
 // Uses [a-zA-Z] instead of [a-z] with i flag. Simplified to not require unicode flag.

package/package.json

@@ -1,15 +1,13 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.119.0",
+  "version": "15.121.0",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",
-    "@types/jsonwebtoken": "^9",
     "ajv": "^8",
     "ansis": "^4",
     "jose": "^6",
-    "jsonwebtoken": "^9",
     "lru-cache": "^11",
     "tinyglobby": "^0.2",
     "tslib": "^2",

package/src/jwt/index.ts

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

package/src/jwt/jwt.service.ts

@@ -1,23 +1,47 @@
+import { createPrivateKey, createPublicKey } from 'node:crypto'
+import type { KeyObject } from 'node:crypto'
 import type { ErrorData } from '@naturalcycles/js-lib/error'
 import { _assert } from '@naturalcycles/js-lib/error/assert.js'
-import { _errorDataAppend } from '@naturalcycles/js-lib/error/error.util.js'
-import type { AnyObject, JWTString } from '@naturalcycles/js-lib/types'
-import type { Algorithm, JwtHeader, SignOptions, VerifyOptions } from 'jsonwebtoken'
-import jsonwebtoken from 'jsonwebtoken'
+import { _errorDataAppend, AppError } from '@naturalcycles/js-lib/error/error.util.js'
+import type {
+  AnyObject,
+  JWTString,
+  NumberOfSeconds,
+  UnixTimestamp,
+} from '@naturalcycles/js-lib/types'
+import { decodeJwt, decodeProtectedHeader, errors, jwtVerify, SignJWT } from 'jose'
 import type { AjvSchema, JSchema } from '../validation/ajv/jSchema.js'
 
-export { jsonwebtoken }
-export type { Algorithm, JwtHeader, SignOptions, VerifyOptions }
+/**
+ * Asymmetric JWS algorithms supported by JWTService.
+ */
+export type JWTAlgorithm =
+  | 'ES256'
+  | 'ES384'
+  | 'ES512'
+  | 'RS256'
+  | 'RS384'
+  | 'RS512'
+  | 'PS256'
+  | 'PS384'
+  | 'PS512'
+  | 'EdDSA'
 
-export interface JWTServiceCfg {
+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
 
@@ -25,39 +49,151 @@ export interface JWTServiceCfg {
    * 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.)
    */
-  signOptions?: SignOptions
+  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).
+   */
+  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
 }
 
-// todo: define JWTError and list possible options
-// jwt expired (TokenExpiredError)
-// jwt invalid
-// jwt token is empty
+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.
@@ -66,82 +202,286 @@ export interface JWTServiceCfg {
  * openssl ecparam -name prime256v1 -genkey -noout -out key.pem
  * openssl ec -in key.pem -pubout > key.pub.pem
  */
-export class JWTService {
-  constructor(public cfg: JWTServiceCfg) {}
-
-  sign<T extends AnyObject>(
-    payload: T,
-    schema?: JSchema<T, any> | AjvSchema<T>,
-    opt: SignOptions = {},
-  ): JWTString {
+export class JWTService<T extends AnyObject = AnyObject> {
+  private privateKey?: KeyObject
+  private publicKey?: KeyObject
+
+  constructor(public cfg: JWTServiceCfg<T>) {
+    // 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)
+  }
+
+  async sign<TT extends T = T>(payload: TT, opt: JWTSignOptions<TT>): Promise<JWTString> {
     _assert(
-      this.cfg.privateKey,
-      'JWTService: privateKey is required to be able to verify, but not provided',
+      this.privateKey,
+      'JWTService: privateKey is required to be able to sign, but not provided',
+      this.cfg.errorData,
     )
 
-    schema?.validate(payload)
-
-    return jsonwebtoken.sign(payload, this.cfg.privateKey, {
-      algorithm: this.cfg.algorithm,
-      noTimestamp: true,
+    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<T extends AnyObject>(
-    token: JWTString,
-    schema?: JSchema<T, any> | AjvSchema<T>,
-    opt: VerifyOptions = {},
-    publicKey?: string, // allows to override public key
-  ): T {
+  async verify<TT extends T = T>(token: JWTString, opt: JWTVerifyOptions<TT> = {}): Promise<TT> {
+    const { now, schema, publicKey, ...joseOpt } = {
+      ...this.cfg.verifyOptions,
+      ...opt,
+    }
+
+    const key = publicKey ? createPublicKey(publicKey) : this.publicKey
     _assert(
-      this.cfg.publicKey,
+      key,
       'JWTService: publicKey is required to be able to verify, but not provided',
+      this.cfg.errorData,
     )
 
+    let data: TT
+
+    try {
+      const { payload } = await jwtVerify(token, key, {
+        algorithms: this.cfg.verifyAlgorithms || [this.cfg.algorithm],
+        ...joseOpt,
+        currentDate: now === undefined ? undefined : new Date(now * 1000),
+      })
+      data = payload as TT
+    } 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<TT extends T = T>(
+    token: JWTString,
+    opt: JWTVerifyOptions<TT> = {},
+  ): Promise<[err: null, payload: TT] | [err: Error, payload: null]> {
+    try {
+      return [null, await this.verify<TT>(token, opt)]
+    } catch (err) {
+      return [err as Error, 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<TT extends T = T>(
+    token: JWTString,
+    opt: JWTVerifyOptions<TT> = {},
+  ): Promise<[err: null, payload: TT] | [err: Error, payload: TT | null]> {
+    const [verifyError, payload] = await this.tryToVerify<TT>(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 as TT]
+    }
+
     try {
-      const data = jsonwebtoken.verify(token, publicKey || this.cfg.publicKey, {
-        algorithms: [this.cfg.algorithm],
-        ...this.cfg.verifyOptions,
-        ...opt,
-      }) as T
+      return [verifyError, jwtDecode<TT>(token).payload]
+    } catch {
+      return [verifyError, null]
+    }
+  }
 
-      schema?.validate(data)
+  decode<TT extends T = T>(token: JWTString, opt: JWTDecodeOptions<TT> = {}): JWTDecoded<TT> {
+    let decoded: JWTDecoded<TT>
 
-      return data
+    try {
+      decoded = jwtDecode<TT>(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<T extends AnyObject>(
-    token: JWTString,
-    schema?: JSchema<T, any> | AjvSchema<T>,
-  ): {
-    header: JwtHeader
-    payload: T
-    signature: string
-  } {
-    const data = jsonwebtoken.decode(token, {
-      complete: true,
-    }) as {
-      header: JwtHeader
-      payload: T
-      signature: string
-    } | null
-
-    _assert(data?.payload, 'invalid token, decoded value is empty', {
-      ...this.cfg.errorData,
-    })
+  /**
+   * 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<TT extends T>(payload: TT, schema?: JSchema<TT, any> | AjvSchema<TT>): void {
+    try {
+      ;(schema || this.cfg.schema)?.validate(payload)
+    } catch (err) {
+      if (this.cfg.errorData) {
+        _errorDataAppend(err, this.cfg.errorData)
+      }
+      throw err
+    }
+  }
 
-    schema?.validate(data.payload)
+  /**
+   * 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(err: unknown): Error {
+    const { errorData } = this.cfg
 
-    return data
+    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 as Error
+  }
+}
+
+/**
+ * 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<T extends AnyObject>(token: JWTString): JWTDecoded<T> {
+  let header: JWTHeader
+  let payload: T
+
+  try {
+    header = decodeProtectedHeader(token) as JWTHeader
+    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 as Error).message}`)
+  }
+
+  return {
+    header,
+    payload,
+    signature: token.split('.')[2]!,
+  }
+}
+
+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 class JWTError extends AppError<JWTErrorData> {
+  constructor(message: string, data: JWTErrorData) {
+    // `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 {
+  readonly payload: AnyObject
+
+  constructor(message: string, data: ErrorData = {}, opt: { payload?: AnyObject } = {}) {
+    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 {
+  readonly payload: AnyObject
+
+  constructor(message: string, data: ErrorData = {}, opt: { payload?: AnyObject } = {}) {
+    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: string, data: ErrorData = {}) {
+    super(message, { ...data, code: 'JWT_INVALID' })
   }
 }

package/src/validation/ajv/jSchema.ts

@@ -36,6 +36,7 @@ import {
   IPV4_REGEX,
   IPV6_REGEX,
   LANGUAGE_TAG_REGEX,
+  SEMVER4_REGEX,
   SEMVER_REGEX,
   SLUG_REGEX,
   URL_REGEX,
@@ -831,10 +832,22 @@ export class JString<
     return this.regex(SLUG_REGEX, { msg: 'is not a valid slug format' })
   }
 
+  /**
+   * Validates the 3-part semver format: `major.minor.patch`, e.g `1.2.3`.
+   */
   semVer(): this {
     return this.regex(SEMVER_REGEX, { msg: 'is not a valid semver format' })
   }
 
+  /**
+   * 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 {
+    return this.regex(SEMVER4_REGEX, { msg: 'is not a valid 4-part semver format' })
+  }
+
   languageTag(): this {
     return this.regex(LANGUAGE_TAG_REGEX, { msg: 'is not a valid language format' })
   }

package/src/validation/regexes.ts

@@ -23,6 +23,8 @@ export const IPV6_REGEX =
 export const LANGUAGE_TAG_REGEX = /^[a-z]{2}(-[A-Z]{2})?$/
 export const MAC_ADDRESS_REGEX = /^([0-9A-Fa-f]{2}[:-]){5}([0-9A-Fa-f]{2})$/
 export const SEMVER_REGEX = /^[0-9]+\.[0-9]+\.[0-9]+$/
+// 4-part version (major.minor.patch.build)
+export const SEMVER4_REGEX = /^[0-9]+\.[0-9]+\.[0-9]+\.[0-9]+$/
 export const SLUG_REGEX = /^[a-z0-9-]+$/
 // URL regex based on `ajv-formats`, but without flags for JSON Schema compatibility.
 // Uses [a-zA-Z] instead of [a-z] with i flag. Simplified to not require unicode flag.