@naturalcycles/nodejs-lib 15.116.1 → 15.116.3

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

@@ -27,8 +27,23 @@ export interface JWTService2Cfg<T extends AnyObject = AnyObject> {
      * 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 JWT_INVALID.
+     * (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`.
@@ -78,6 +93,10 @@ export interface JWTSignOptions<T extends AnyObject = AnyObject> {
      * 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.
      */
@@ -170,6 +189,14 @@ export declare class JWTService2<T extends AnyObject = AnyObject> {
      */
     private normalizeError;
 }
+/**
+ * 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 JWTError with code JWT_INVALID if the token cannot be decoded.
+ */
+export declare function jwtDecode<T extends AnyObject>(token: JWTString): JWTDecoded<T>;
 export type JWTErrorCode = 'JWT_EXPIRED' | 'JWT_NOT_YET_VALID' | 'JWT_INVALID';
 export interface JWTErrorData extends ErrorData {
     code: JWTErrorCode;

package/dist/jwt/jwt.service2.js

@@ -38,12 +38,17 @@ export class JWTService2 {
     }
     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 } = {
+        const { expiresAt, notBefore, issuer, audience, subject, jwtid, issuedAt, kid, schema } = {
             ...this.cfg.signOptions,
             ...opt,
         };
         (schema || this.cfg.schema)?.validate(payload);
-        const jwt = new SignJWT(payload).setProtectedHeader({ alg: this.cfg.algorithm, typ: 'JWT' });
+        // `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)
@@ -70,7 +75,7 @@ export class JWTService2 {
         let data;
         try {
             const { payload } = await jwtVerify(token, key, {
-                algorithms: [this.cfg.algorithm],
+                algorithms: this.cfg.verifyAlgorithms || [this.cfg.algorithm],
                 ...joseOpt,
                 currentDate: now === undefined ? undefined : new Date(now * 1000),
             });
@@ -83,24 +88,18 @@ export class JWTService2 {
         return data;
     }
     decode(token, opt = {}) {
-        let header;
-        let payload;
+        let decoded;
         try {
-            header = decodeProtectedHeader(token);
-            payload = decodeJwt(token);
+            decoded = jwtDecode(token);
         }
         catch (err) {
-            throw new JWTError('invalid token, unable to decode', {
-                ...this.cfg.errorData,
-                code: 'JWT_INVALID',
-            }, { cause: err });
+            if (this.cfg.errorData) {
+                _errorDataAppend(err, this.cfg.errorData);
+            }
+            throw err;
         }
-        this.validate(payload, opt.schema);
-        return {
-            header,
-            payload,
-            signature: token.split('.')[2],
-        };
+        this.validate(decoded.payload, opt.schema);
+        return decoded;
     }
     /**
      * Schema-validation errors on Verify/Decode are extended with cfg.errorData:
@@ -136,6 +135,11 @@ export class JWTService2 {
         else if (err instanceof errors.JOSEError) {
             code = 'JWT_INVALID';
         }
+        else 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
+            code = 'JWT_INVALID';
+        }
         else {
             return err;
         }
@@ -145,6 +149,29 @@ export class JWTService2 {
         }, { cause: err });
     }
 }
+/**
+ * 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 JWTError with code JWT_INVALID if the token cannot be decoded.
+ */
+export function jwtDecode(token) {
+    let header;
+    let payload;
+    try {
+        header = decodeProtectedHeader(token);
+        payload = decodeJwt(token);
+    }
+    catch (err) {
+        throw new JWTError('invalid token, unable to decode', { code: 'JWT_INVALID' }, { cause: err });
+    }
+    return {
+        header,
+        payload,
+        signature: token.split('.')[2],
+    };
+}
 /**
  * Thrown by JWTService2 on any Verify/Decode failure.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@naturalcycles/nodejs-lib",
   "type": "module",
-  "version": "15.116.1",
+  "version": "15.116.3",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",

package/src/jwt/jwt.service2.ts

@@ -49,9 +49,25 @@ export interface JWTService2Cfg<T extends AnyObject = AnyObject> {
    * 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 JWT_INVALID.
+   * (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`.
@@ -105,6 +121,10 @@ export interface JWTSignOptions<T extends AnyObject = AnyObject> {
    * 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.
    */
@@ -198,14 +218,19 @@ export class JWTService2<T extends AnyObject = AnyObject> {
       this.cfg.errorData,
     )
 
-    const { expiresAt, notBefore, issuer, audience, subject, jwtid, issuedAt, schema } = {
+    const { expiresAt, notBefore, issuer, audience, subject, jwtid, issuedAt, kid, schema } = {
       ...this.cfg.signOptions,
       ...opt,
     }
 
     ;(schema || this.cfg.schema)?.validate(payload)
 
-    const jwt = new SignJWT(payload).setProtectedHeader({ alg: this.cfg.algorithm, typ: 'JWT' })
+    // `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)
@@ -234,7 +259,7 @@ export class JWTService2<T extends AnyObject = AnyObject> {
 
     try {
       const { payload } = await jwtVerify(token, key, {
-        algorithms: [this.cfg.algorithm],
+        algorithms: this.cfg.verifyAlgorithms || [this.cfg.algorithm],
         ...joseOpt,
         currentDate: now === undefined ? undefined : new Date(now * 1000),
       })
@@ -249,30 +274,20 @@ export class JWTService2<T extends AnyObject = AnyObject> {
   }
 
   decode<TT extends T = T>(token: JWTString, opt: JWTDecodeOptions<TT> = {}): JWTDecoded<TT> {
-    let header: JWTHeader
-    let payload: TT
+    let decoded: JWTDecoded<TT>
 
     try {
-      header = decodeProtectedHeader(token) as JWTHeader
-      payload = decodeJwt(token) as TT
+      decoded = jwtDecode<TT>(token)
     } catch (err) {
-      throw new JWTError(
-        'invalid token, unable to decode',
-        {
-          ...this.cfg.errorData,
-          code: 'JWT_INVALID',
-        },
-        { cause: err },
-      )
+      if (this.cfg.errorData) {
+        _errorDataAppend(err, this.cfg.errorData)
+      }
+      throw err
     }
 
-    this.validate(payload, opt.schema)
+    this.validate(decoded.payload, opt.schema)
 
-    return {
-      header,
-      payload,
-      signature: token.split('.')[2]!,
-    }
+    return decoded
   }
 
   /**
@@ -306,6 +321,10 @@ export class JWTService2<T extends AnyObject = AnyObject> {
       code = 'JWT_NOT_YET_VALID'
     } else if (err instanceof errors.JOSEError) {
       code = 'JWT_INVALID'
+    } else 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
+      code = 'JWT_INVALID'
     } else {
       return err as Error
     }
@@ -321,6 +340,31 @@ export class JWTService2<T extends AnyObject = AnyObject> {
   }
 }
 
+/**
+ * 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 JWTError with code JWT_INVALID 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) as T
+  } catch (err) {
+    throw new JWTError('invalid token, unable to decode', { code: 'JWT_INVALID' }, { cause: err })
+  }
+
+  return {
+    header,
+    payload,
+    signature: token.split('.')[2]!,
+  }
+}
+
 export type JWTErrorCode = 'JWT_EXPIRED' | 'JWT_NOT_YET_VALID' | 'JWT_INVALID'
 
 export interface JWTErrorData extends ErrorData {