@naturalcycles/nodejs-lib 15.115.0 → 15.116.0

package/dist/cli/parseArgs.js

@@ -43,6 +43,7 @@ export function _parseArgs(options, opt = {}) {
                 options: nodeOptions,
                 allowPositionals: true,
                 allowNegative: true, // native `--no-flag` support for booleans
+                tokens: true, // needed to detect the ambiguous `--boolFlag value` space form
                 // In non-strict mode, unknown options are collected into `values` but
                 // ignored below, since we only read declared options. See `strict` docs.
                 strict,
@@ -57,6 +58,7 @@ export function _parseArgs(options, opt = {}) {
         process.stdout.write(buildHelp(options, usage));
         process.exit(0);
     }
+    assertNoSpaceValuedBoolean(parsed.tokens, options);
     const result = { _: parsed.positionals };
     for (const [name, def] of Object.entries(options)) {
         let v = values[name];
@@ -78,10 +80,32 @@ export function _parseArgs(options, opt = {}) {
         if (def.array) {
             v = Array.isArray(v) ? v : [v];
         }
+        // A non-boolean option passed as a bare flag (`--out` with no value) comes back
+        // from node's parseArgs (in non-strict mode) as boolean `true`. Reject it: the
+        // user almost certainly forgot the value, and silently coercing `true` (to `1`
+        // for numbers, `"true"` for strings, or crashing a `transform`) would hide the
+        // mistake. Only arg-sourced values are checked; a boolean `default` is left
+        // alone. `def.type === 'boolean'` legitimately produces booleans, so skip it.
+        if (fromArgs && def.type !== 'boolean') {
+            const bareFlag = Array.isArray(v)
+                ? v.some(x => typeof x === 'boolean')
+                : typeof v === 'boolean';
+            if (bareFlag) {
+                throw new ParseArgsError(`Missing value for --${name}`);
+            }
+        }
         // `transform` owns conversion, so built-in number coercion is skipped for it
         if (def.type === 'number' && !def.transform) {
             v = Array.isArray(v) ? v.map(x => toNumber(x, name)) : toNumber(v, name);
         }
+        // node's parseArgs (in non-strict mode) captures the inline value of
+        // `--flag=value` on a boolean option as a string ("false"/"true"), rather than
+        // rejecting it as strict mode does. Coerce known tokens so `--flag=false` means
+        // boolean false, not a truthy "false" string. Real booleans produced by
+        // `--flag` / `--no-flag` (and boolean defaults) pass through untouched.
+        if (def.type === 'boolean') {
+            v = Array.isArray(v) ? v.map(x => toBoolean(x, name)) : toBoolean(v, name);
+        }
         if (def.choices) {
             const list = Array.isArray(v) ? v : [v];
             for (const x of list) {
@@ -101,6 +125,28 @@ export function _parseArgs(options, opt = {}) {
     }
     return result;
 }
+/**
+ * Reject the ambiguous `--boolFlag value` space form. node never consumes the
+ * next token as a boolean's value (getopt convention), so `--arg false` would
+ * silently yield `arg: true` and leak "false" into positionals. Unlike the
+ * `=value` form (handled by toBoolean) we can't recover the intended value here,
+ * so fail loudly. Only `true`/`false` tokens are treated as ambiguous; any other
+ * positional (e.g. a filename) is left as a genuine positional.
+ */
+function assertNoSpaceValuedBoolean(tokens, options) {
+    for (let i = 0; i < tokens.length - 1; i++) {
+        const tok = tokens[i];
+        // `tok.value === undefined` => bare flag (no inline `=value`); applies to
+        // declared boolean options only (unknown options are ignored, see `strict`).
+        if (tok.kind !== 'option' || tok.value !== undefined || options[tok.name]?.type !== 'boolean') {
+            continue;
+        }
+        const next = tokens[i + 1];
+        if (next.kind === 'positional' && (next.value === 'true' || next.value === 'false')) {
+            throw new ParseArgsError(`Boolean option --${tok.name} does not take a space-separated value ("${next.value}"); use --${tok.name}=${next.value} or --${next.value === 'false' ? `no-${tok.name}` : tok.name}`);
+        }
+    }
+}
 function toNumber(raw, name) {
     const n = Number(raw);
     if (Number.isNaN(n)) {
@@ -108,6 +154,15 @@ function toNumber(raw, name) {
     }
     return n;
 }
+function toBoolean(raw, name) {
+    if (typeof raw === 'boolean')
+        return raw; // real boolean from --flag / --no-flag / default
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    throw new ParseArgsError(`Invalid boolean for --${name}: "${raw}"`);
+}
 function buildHelp(options, usage) {
     const lines = [];
     if (usage)

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.0",
+  "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",
@@ -15,8 +16,8 @@
     "yaml": "^2"
   },
   "devDependencies": {
-    "typescript": "rc",
-    "@naturalcycles/dev-lib": "18.4.2"
+    "typescript": "^7",
+    "@naturalcycles/dev-lib": "0.0.0"
   },
   "exports": {
     ".": "./dist/index.js",
@@ -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/cli/parseArgs.ts

@@ -186,6 +186,7 @@ export function _parseArgs<const O extends CliOptions>(
         options: nodeOptions,
         allowPositionals: true,
         allowNegative: true, // native `--no-flag` support for booleans
+        tokens: true, // needed to detect the ambiguous `--boolFlag value` space form
         // In non-strict mode, unknown options are collected into `values` but
         // ignored below, since we only read declared options. See `strict` docs.
         strict,
@@ -202,6 +203,8 @@ export function _parseArgs<const O extends CliOptions>(
     process.exit(0)
   }
 
+  assertNoSpaceValuedBoolean(parsed.tokens, options)
+
   const result: Record<string, unknown> = { _: parsed.positionals }
 
   for (const [name, def] of Object.entries(options)) {
@@ -225,11 +228,35 @@ export function _parseArgs<const O extends CliOptions>(
       v = Array.isArray(v) ? v : [v]
     }
 
+    // A non-boolean option passed as a bare flag (`--out` with no value) comes back
+    // from node's parseArgs (in non-strict mode) as boolean `true`. Reject it: the
+    // user almost certainly forgot the value, and silently coercing `true` (to `1`
+    // for numbers, `"true"` for strings, or crashing a `transform`) would hide the
+    // mistake. Only arg-sourced values are checked; a boolean `default` is left
+    // alone. `def.type === 'boolean'` legitimately produces booleans, so skip it.
+    if (fromArgs && def.type !== 'boolean') {
+      const bareFlag = Array.isArray(v)
+        ? v.some(x => typeof x === 'boolean')
+        : typeof v === 'boolean'
+      if (bareFlag) {
+        throw new ParseArgsError(`Missing value for --${name}`)
+      }
+    }
+
     // `transform` owns conversion, so built-in number coercion is skipped for it
     if (def.type === 'number' && !def.transform) {
       v = Array.isArray(v) ? v.map(x => toNumber(x, name)) : toNumber(v, name)
     }
 
+    // node's parseArgs (in non-strict mode) captures the inline value of
+    // `--flag=value` on a boolean option as a string ("false"/"true"), rather than
+    // rejecting it as strict mode does. Coerce known tokens so `--flag=false` means
+    // boolean false, not a truthy "false" string. Real booleans produced by
+    // `--flag` / `--no-flag` (and boolean defaults) pass through untouched.
+    if (def.type === 'boolean') {
+      v = Array.isArray(v) ? v.map(x => toBoolean(x, name)) : toBoolean(v, name)
+    }
+
     if (def.choices) {
       const list = Array.isArray(v) ? v : [v]
       for (const x of list) {
@@ -258,6 +285,34 @@ export function _parseArgs<const O extends CliOptions>(
   return result as InferCliArgs<O>
 }
 
+/**
+ * Reject the ambiguous `--boolFlag value` space form. node never consumes the
+ * next token as a boolean's value (getopt convention), so `--arg false` would
+ * silently yield `arg: true` and leak "false" into positionals. Unlike the
+ * `=value` form (handled by toBoolean) we can't recover the intended value here,
+ * so fail loudly. Only `true`/`false` tokens are treated as ambiguous; any other
+ * positional (e.g. a filename) is left as a genuine positional.
+ */
+function assertNoSpaceValuedBoolean(
+  tokens: NonNullable<ReturnType<typeof parseArgs>['tokens']>,
+  options: CliOptions,
+): void {
+  for (let i = 0; i < tokens.length - 1; i++) {
+    const tok = tokens[i]!
+    // `tok.value === undefined` => bare flag (no inline `=value`); applies to
+    // declared boolean options only (unknown options are ignored, see `strict`).
+    if (tok.kind !== 'option' || tok.value !== undefined || options[tok.name]?.type !== 'boolean') {
+      continue
+    }
+    const next = tokens[i + 1]!
+    if (next.kind === 'positional' && (next.value === 'true' || next.value === 'false')) {
+      throw new ParseArgsError(
+        `Boolean option --${tok.name} does not take a space-separated value ("${next.value}"); use --${tok.name}=${next.value} or --${next.value === 'false' ? `no-${tok.name}` : tok.name}`,
+      )
+    }
+  }
+}
+
 function toNumber(raw: unknown, name: string): number {
   const n = Number(raw)
   if (Number.isNaN(n)) {
@@ -266,6 +321,13 @@ function toNumber(raw: unknown, name: string): number {
   return n
 }
 
+function toBoolean(raw: unknown, name: string): boolean {
+  if (typeof raw === 'boolean') return raw // real boolean from --flag / --no-flag / default
+  if (raw === 'true') return true
+  if (raw === 'false') return false
+  throw new ParseArgsError(`Invalid boolean for --${name}: "${raw}"`)
+}
+
 function buildHelp(options: CliOptions, usage?: string): string {
   const lines: string[] = []
   if (usage) lines.push(usage, '')

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' })
+  }
+}