@naturalcycles/nodejs-lib 15.117.0 → 15.119.0

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

@@ -175,6 +175,31 @@ export declare class JWTService2<T extends AnyObject = AnyObject> {
     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>;
+    /**
+     * Tries to Verify the token, returning an [error, payload] tuple instead of throwing:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, null] - verification failed
+     *
+     * Same contract as tryToVerifyOrDecode, but without the unverified-decode fallback:
+     * the payload is only returned when the token verified.
+     */
+    tryToVerify<TT extends T = T>(token: JWTString, opt?: JWTVerifyOptions<TT>): Promise<[err: null, payload: TT] | [err: Error, payload: null]>;
+    /**
+     * Tries to Verify the token, falling back to unverified Decode on failure,
+     * so the caller can "peek" into the token's content even when it doesn't verify.
+     *
+     * Returns an [error, payload] tuple - ALWAYS check the error first:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, payload] - verification failed, but the token could still be decoded.
+     *   When the error is JWTExpiredError/JWTNotYetValidError, the signature was already
+     *   verified and only the time-claim check failed, so the payload is trustworthy
+     *   (just expired/not yet valid). For any other error the payload is completely
+     *   UNVERIFIED - never trust it, only peek (e.g to log/report the claimed identity).
+     * - [error, null] - the token could not even be decoded
+     *
+     * The decode fallback is raw: opt.schema/cfg.schema are only applied on the Verify path.
+     */
+    tryToVerifyOrDecode<TT extends T = T>(token: JWTString, opt?: JWTVerifyOptions<TT>): Promise<[err: null, payload: TT] | [err: Error, payload: TT | null]>;
     decode<TT extends T = T>(token: JWTString, opt?: JWTDecodeOptions<TT>): JWTDecoded<TT>;
     /**
      * Schema-validation errors on Verify/Decode are extended with cfg.errorData:

package/dist/jwt/jwt.service2.js

@@ -88,6 +88,52 @@ export class JWTService2 {
         this.validate(data, schema);
         return data;
     }
+    /**
+     * Tries to Verify the token, returning an [error, payload] tuple instead of throwing:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, null] - verification failed
+     *
+     * Same contract as tryToVerifyOrDecode, but without the unverified-decode fallback:
+     * the payload is only returned when the token verified.
+     */
+    async tryToVerify(token, opt = {}) {
+        try {
+            return [null, await this.verify(token, opt)];
+        }
+        catch (err) {
+            return [err, null];
+        }
+    }
+    /**
+     * Tries to Verify the token, falling back to unverified Decode on failure,
+     * so the caller can "peek" into the token's content even when it doesn't verify.
+     *
+     * Returns an [error, payload] tuple - ALWAYS check the error first:
+     * - [null, payload] - the token verified, payload can be trusted
+     * - [error, payload] - verification failed, but the token could still be decoded.
+     *   When the error is JWTExpiredError/JWTNotYetValidError, the signature was already
+     *   verified and only the time-claim check failed, so the payload is trustworthy
+     *   (just expired/not yet valid). For any other error the payload is completely
+     *   UNVERIFIED - never trust it, only peek (e.g to log/report the claimed identity).
+     * - [error, null] - the token could not even be decoded
+     *
+     * The decode fallback is raw: opt.schema/cfg.schema are only applied on the Verify path.
+     */
+    async tryToVerifyOrDecode(token, opt = {}) {
+        const [verifyError, payload] = await this.tryToVerify(token, opt);
+        if (!verifyError)
+            return [null, payload];
+        // Expired/not-yet-valid errors already carry the (signature-verified) payload
+        if (verifyError instanceof JWTExpiredError || verifyError instanceof JWTNotYetValidError) {
+            return [verifyError, verifyError.payload];
+        }
+        try {
+            return [verifyError, jwtDecode(token).payload];
+        }
+        catch {
+            return [verifyError, null];
+        }
+    }
     decode(token, opt = {}) {
         let decoded;
         try {

package/package.json

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

package/src/jwt/jwt.service2.ts

@@ -274,6 +274,59 @@ export class JWTService2<T extends AnyObject = AnyObject> {
     return data
   }
 
+  /**
+   * Tries to Verify the token, returning an [error, payload] tuple instead of throwing:
+   * - [null, payload] - the token verified, payload can be trusted
+   * - [error, null] - verification failed
+   *
+   * Same contract as tryToVerifyOrDecode, but without the unverified-decode fallback:
+   * the payload is only returned when the token verified.
+   */
+  async tryToVerify<TT extends T = T>(
+    token: JWTString,
+    opt: JWTVerifyOptions<TT> = {},
+  ): Promise<[err: null, payload: TT] | [err: Error, payload: null]> {
+    try {
+      return [null, await this.verify<TT>(token, opt)]
+    } catch (err) {
+      return [err as Error, null]
+    }
+  }
+
+  /**
+   * Tries to Verify the token, falling back to unverified Decode on failure,
+   * so the caller can "peek" into the token's content even when it doesn't verify.
+   *
+   * Returns an [error, payload] tuple - ALWAYS check the error first:
+   * - [null, payload] - the token verified, payload can be trusted
+   * - [error, payload] - verification failed, but the token could still be decoded.
+   *   When the error is JWTExpiredError/JWTNotYetValidError, the signature was already
+   *   verified and only the time-claim check failed, so the payload is trustworthy
+   *   (just expired/not yet valid). For any other error the payload is completely
+   *   UNVERIFIED - never trust it, only peek (e.g to log/report the claimed identity).
+   * - [error, null] - the token could not even be decoded
+   *
+   * The decode fallback is raw: opt.schema/cfg.schema are only applied on the Verify path.
+   */
+  async tryToVerifyOrDecode<TT extends T = T>(
+    token: JWTString,
+    opt: JWTVerifyOptions<TT> = {},
+  ): Promise<[err: null, payload: TT] | [err: Error, payload: TT | null]> {
+    const [verifyError, payload] = await this.tryToVerify<TT>(token, opt)
+    if (!verifyError) return [null, payload]
+
+    // Expired/not-yet-valid errors already carry the (signature-verified) payload
+    if (verifyError instanceof JWTExpiredError || verifyError instanceof JWTNotYetValidError) {
+      return [verifyError, verifyError.payload as TT]
+    }
+
+    try {
+      return [verifyError, jwtDecode<TT>(token).payload]
+    } catch {
+      return [verifyError, null]
+    }
+  }
+
   decode<TT extends T = T>(token: JWTString, opt: JWTDecodeOptions<TT> = {}): JWTDecoded<TT> {
     let decoded: JWTDecoded<TT>