@naturalcycles/nodejs-lib 15.115.1 → 15.116.0

package/dist/jwt/index.d.ts

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

package/dist/jwt/index.js

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

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

@@ -37,6 +37,11 @@ export interface JWTServiceCfg {
     errorData?: ErrorData;
 }
 /**
+ * @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 popular `jsonwebtoken` library.
  * You should create one instance of JWTService for each pair of private/public key.
  *

package/dist/jwt/jwt.service.js

@@ -7,6 +7,11 @@ export { jsonwebtoken };
 // jwt invalid
 // jwt token is empty
 /**
+ * @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 popular `jsonwebtoken` library.
  * You should create one instance of JWTService for each pair of private/public key.
  *

package/dist/jwt/jwt.service2.d.ts

@@ -0,0 +1,184 @@
+import type { ErrorData } from '@naturalcycles/js-lib/error';
+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';
+/**
+ * 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.
+     */
+    algorithm: 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;
+    /**
+     * 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 with a stable `data.code`.
+ *
+ * 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 declare class JWTService2<T extends AnyObject = AnyObject> {
+    cfg: JWTService2Cfg<T>;
+    private privateKey?;
+    private publicKey?;
+    constructor(cfg: JWTService2Cfg<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>;
+    decode<TT extends T = T>(token: JWTString, opt?: JWTDecodeOptions<TT>): JWTDecoded<TT>;
+    /**
+     * jose errors are normalized into JWTError (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;
+}
+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.
+ *
+ * `data.code` is stable and implementation-agnostic:
+ * - JWT_EXPIRED - `exp` claim check failed
+ * - JWT_NOT_YET_VALID - `nbf` claim check failed
+ * - JWT_INVALID - anything else (malformed token, wrong signature, other claim mismatches)
+ *
+ * The original underlying error is preserved in `cause`.
+ */
+export declare class JWTError extends AppError<JWTErrorData> {
+    constructor(message: string, data: JWTErrorData, opt?: {
+        cause?: any;
+    });
+}

package/dist/jwt/jwt.service2.js

@@ -0,0 +1,146 @@
+import { createPrivateKey, createPublicKey } from 'node:crypto';
+import { _assert } from '@naturalcycles/js-lib/error/assert.js';
+import { AppError } from '@naturalcycles/js-lib/error/error.util.js';
+import { decodeJwt, decodeProtectedHeader, errors, jwtVerify, SignJWT } from 'jose';
+/**
+ * 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 with a stable `data.code`.
+ *
+ * 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 {
+    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);
+    }
+    async sign(payload, opt) {
+        _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, schema } = {
+            ...this.cfg.signOptions,
+            ...opt,
+        };
+        (schema || this.cfg.schema)?.validate(payload);
+        const jwt = new SignJWT(payload).setProtectedHeader({ alg: this.cfg.algorithm, typ: 'JWT' });
+        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(token, opt = {}) {
+        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;
+        try {
+            const { payload } = await jwtVerify(token, key, {
+                algorithms: [this.cfg.algorithm],
+                ...joseOpt,
+                currentDate: now === undefined ? undefined : new Date(now * 1000),
+            });
+            data = payload;
+        }
+        catch (err) {
+            throw this.normalizeError(err);
+        }
+        ;
+        (schema || this.cfg.schema)?.validate(data);
+        return data;
+    }
+    decode(token, opt = {}) {
+        let header;
+        let payload;
+        try {
+            header = decodeProtectedHeader(token);
+            payload = decodeJwt(token);
+        }
+        catch (err) {
+            throw new JWTError('invalid token, unable to decode', {
+                ...this.cfg.errorData,
+                code: 'JWT_INVALID',
+            }, { cause: err });
+        }
+        ;
+        (opt.schema || this.cfg.schema)?.validate(payload);
+        return {
+            header,
+            payload,
+            signature: token.split('.')[2],
+        };
+    }
+    /**
+     * jose errors are normalized into JWTError (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) {
+        let code;
+        if (err instanceof errors.JWTExpired) {
+            code = 'JWT_EXPIRED';
+        }
+        else if (err instanceof errors.JWTClaimValidationFailed && err.claim === 'nbf') {
+            code = 'JWT_NOT_YET_VALID';
+        }
+        else if (err instanceof errors.JOSEError) {
+            code = 'JWT_INVALID';
+        }
+        else {
+            return err;
+        }
+        return new JWTError(err.message, {
+            ...this.cfg.errorData,
+            code,
+        }, { cause: err });
+    }
+}
+/**
+ * Thrown by JWTService2 on any Verify/Decode failure.
+ *
+ * `data.code` is stable and implementation-agnostic:
+ * - JWT_EXPIRED - `exp` claim check failed
+ * - JWT_NOT_YET_VALID - `nbf` claim check failed
+ * - JWT_INVALID - anything else (malformed token, wrong signature, other claim mismatches)
+ *
+ * The original underlying error is preserved in `cause`.
+ */
+export class JWTError extends AppError {
+    constructor(message, data, opt) {
+        super(message, data, { ...opt, name: 'JWTError' });
+    }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.115.1",
+  "version": "15.116.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",
@@ -30,7 +31,7 @@
     "./kpy": "./dist/fs/kpy.js",
     "./yaml2": "./dist/fs/yaml2.js",
     "./glob": "./dist/glob/index.js",
-    "./jwt": "./dist/jwt/jwt.service.js",
+    "./jwt": "./dist/jwt/index.js",
     "./runScript": "./dist/script/runScript.js",
     "./slack": "./dist/slack/index.js",
     "./stream": "./dist/stream/index.js",

package/src/jwt/index.ts

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

package/src/jwt/jwt.service.ts

@@ -51,6 +51,11 @@ export interface JWTServiceCfg {
 // jwt token is empty
 
 /**
+ * @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 popular `jsonwebtoken` library.
  * You should create one instance of JWTService for each pair of private/public key.
  *

package/src/jwt/jwt.service2.ts

@@ -0,0 +1,327 @@
+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 { 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.
+   */
+  algorithm: 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
+  /**
+   * 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 with a stable `data.code`.
+ *
+ * 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, schema } = {
+      ...this.cfg.signOptions,
+      ...opt,
+    }
+
+    ;(schema || this.cfg.schema)?.validate(payload)
+
+    const jwt = new SignJWT(payload).setProtectedHeader({ alg: this.cfg.algorithm, typ: 'JWT' })
+    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.algorithm],
+        ...joseOpt,
+        currentDate: now === undefined ? undefined : new Date(now * 1000),
+      })
+      data = payload as TT
+    } catch (err) {
+      throw this.normalizeError(err)
+    }
+
+    ;(schema || this.cfg.schema)?.validate(data)
+
+    return data
+  }
+
+  decode<TT extends T = T>(token: JWTString, opt: JWTDecodeOptions<TT> = {}): JWTDecoded<TT> {
+    let header: JWTHeader
+    let payload: TT
+
+    try {
+      header = decodeProtectedHeader(token) as JWTHeader
+      payload = decodeJwt(token) as TT
+    } catch (err) {
+      throw new JWTError(
+        'invalid token, unable to decode',
+        {
+          ...this.cfg.errorData,
+          code: 'JWT_INVALID',
+        },
+        { cause: err },
+      )
+    }
+
+    ;(opt.schema || this.cfg.schema)?.validate(payload)
+
+    return {
+      header,
+      payload,
+      signature: token.split('.')[2]!,
+    }
+  }
+
+  /**
+   * jose errors are normalized into JWTError (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 {
+    let code: JWTErrorCode
+
+    if (err instanceof errors.JWTExpired) {
+      code = 'JWT_EXPIRED'
+    } else if (err instanceof errors.JWTClaimValidationFailed && err.claim === 'nbf') {
+      code = 'JWT_NOT_YET_VALID'
+    } else if (err instanceof errors.JOSEError) {
+      code = 'JWT_INVALID'
+    } else {
+      return err as Error
+    }
+
+    return new JWTError(
+      (err as Error).message,
+      {
+        ...this.cfg.errorData,
+        code,
+      },
+      { cause: err },
+    )
+  }
+}
+
+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.
+ *
+ * `data.code` is stable and implementation-agnostic:
+ * - JWT_EXPIRED - `exp` claim check failed
+ * - JWT_NOT_YET_VALID - `nbf` claim check failed
+ * - JWT_INVALID - anything else (malformed token, wrong signature, other claim mismatches)
+ *
+ * The original underlying error is preserved in `cause`.
+ */
+export class JWTError extends AppError<JWTErrorData> {
+  constructor(message: string, data: JWTErrorData, opt?: { cause?: any }) {
+    super(message, data, { ...opt, name: 'JWTError' })
+  }
+}