@naturalcycles/nodejs-lib 15.116.1 → 15.116.2

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

@@ -78,6 +78,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 +174,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)
@@ -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:
@@ -145,6 +144,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.2",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",

package/src/jwt/jwt.service2.ts

@@ -105,6 +105,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 +202,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)
@@ -249,30 +258,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
   }
 
   /**
@@ -321,6 +320,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 {