@naturalcycles/nodejs-lib 15.116.0 → 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.
      */
@@ -156,6 +160,13 @@ export declare class JWTService2<T extends AnyObject = AnyObject> {
     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>;
+    /**
+     * 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;
     /**
      * 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)
@@ -163,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

@@ -1,6 +1,6 @@
 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 { _errorDataAppend, 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:
@@ -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)
@@ -79,30 +84,40 @@ export class JWTService2 {
         catch (err) {
             throw this.normalizeError(err);
         }
-        ;
-        (schema || this.cfg.schema)?.validate(data);
+        this.validate(data, schema);
         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(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.)
+     */
+    validate(payload, schema) {
+        try {
+            ;
+            (schema || this.cfg.schema)?.validate(payload);
+        }
+        catch (err) {
+            if (this.cfg.errorData) {
+                _errorDataAppend(err, this.cfg.errorData);
+            }
+            throw 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).
@@ -129,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.0",
+  "version": "15.116.2",
   "dependencies": {
     "@naturalcycles/js-lib": "^15",
     "@standard-schema/spec": "^1",

package/src/jwt/jwt.service2.ts

@@ -2,7 +2,7 @@ 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 { _errorDataAppend, AppError } from '@naturalcycles/js-lib/error/error.util.js'
 import type {
   AnyObject,
   JWTString,
@@ -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)
@@ -243,35 +252,42 @@ export class JWTService2<T extends AnyObject = AnyObject> {
       throw this.normalizeError(err)
     }
 
-    ;(schema || this.cfg.schema)?.validate(data)
+    this.validate(data, schema)
 
     return data
   }
 
   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
     }
 
-    ;(opt.schema || this.cfg.schema)?.validate(payload)
+    this.validate(decoded.payload, opt.schema)
+
+    return decoded
+  }
 
-    return {
-      header,
-      payload,
-      signature: token.split('.')[2]!,
+  /**
+   * 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
     }
   }
 
@@ -304,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 {