@naturalcycles/nodejs-lib 15.119.0 → 15.120.0

package/src/jwt/jwt.service2.ts

@@ -1,486 +0,0 @@
-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, 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'
-
-/**
- * Asymmetric JWS algorithms supported by JWTService2.
- */
-export type JWTAlgorithm =
-  | 'ES256'
-  | 'ES384'
-  | 'ES512'
-  | 'RS256'
-  | 'RS384'
-  | 'RS512'
-  | 'PS256'
-  | 'PS384'
-  | 'PS512'
-  | 'EdDSA'
-
-export interface JWTService2Cfg<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: JWTAlgorithm
-
-  /**
-   * 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).
-   */
-  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?: Omit<JWTVerifyOptions, 'schema' | 'publicKey'>
-
-  /**
-   * 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 legacy 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
-}
-
-/**
- * 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 JWTService (jsonwebtoken-based). 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).
- *
- * You should create one instance of JWTService2 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.
- * For ES256 (default algo in JWTService2) key should have `prime256v1` parameter:
- *
- * openssl ecparam -name prime256v1 -genkey -noout -out key.pem
- * openssl ec -in key.pem -pubout > key.pub.pem
- */
-export class JWTService2<T extends AnyObject = AnyObject> {
-  private privateKey?: KeyObject
-  private publicKey?: KeyObject
-
-  constructor(public cfg: JWTService2Cfg<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.privateKey,
-      'JWTService2: 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)
-  }
-
-  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(
-      key,
-      'JWTService2: 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 {
-      return [verifyError, jwtDecode<TT>(token).payload]
-    } catch {
-      return [verifyError, null]
-    }
-  }
-
-  decode<TT extends T = T>(token: JWTString, opt: JWTDecodeOptions<TT> = {}): JWTDecoded<TT> {
-    let decoded: JWTDecoded<TT>
-
-    try {
-      decoded = jwtDecode<TT>(token)
-    } catch (err) {
-      if (this.cfg.errorData) {
-        _errorDataAppend(err, this.cfg.errorData)
-      }
-      throw err
-    }
-
-    this.validate(decoded.payload, opt.schema)
-
-    return decoded
-  }
-
-  /**
-   * 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
-    }
-  }
-
-  /**
-   * 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
-
-    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 JWTService2.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 JWTService2 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' })
-  }
-}