CHANGELOG.md

@@ -1,11 +0,0 @@
-# v3.0.0
-
-**Breaking Change**: Standardize error `message`s (now they're more client-friendly).
-
-# v2.1.0
-
-Feature: Add `code`, `status`, and `details` to errors.
-
-# v2.0.0
-
-**Breaking Change**: require `issuers` array (rather than `["*"]` by default).

README.md

@@ -11,7 +11,7 @@ Works great for
 
 -   [x] `jsonwebtoken` (Auth0)
 -   [x] OIDC (OpenID Connect)
--   [x] .well-known/jwks.json (Auth0, Okta)
+-   [x] .well-known/jwks.json (Auth0)
 -   [x] Other JWKs URLs
 
 Crypto Support
@@ -19,19 +19,8 @@ Crypto Support
 -   [x] JWT verification
 -   [x] RSA (all variants)
 -   [x] EC / ECDSA (NIST variants P-256, P-384)
--   [x] Sane error codes
 -   [ ] esoteric variants (excluded to keep the code featherweight and secure)
 
-# Table of Contents
-
--   Install
--   Usage
--   API
-    -   Auth0 / Okta
-    -   OIDC
--   Errors
--   Change Log
-
 # Install
 
 ```bash
@@ -259,50 +248,3 @@ keyfetch.init({
 
 There is no background task to cleanup expired keys as of yet.
 For now you can limit the number of keys fetched by having a simple whitelist.
-
-# Errors
-
-`JSON.stringify()`d errors look like this:
-
-```js
-{
-  code: "INVALID_JWT",
-  status: 401,
-  details: [ "jwt.claims.exp = 1634804500", "DEBUG: helpful message" ]
-  message: "token's 'exp' has passed or could not parsed: 1634804500"
-}
-```
-
-SemVer Compatibility:
-
--   `code` & `status` will remain the same.
--   `message` is **NOT** included in the semver compatibility guarantee (we intend to make them more client-friendly), neither is `detail` at this time (but it will be once we decide on what it should be).
--   `details` may be added to, but not subtracted from
-
-| Hint              | Code          | Status | Message (truncated)                                    |
-| ----------------- | ------------- | ------ | ------------------------------------------------------ |
-| bad gateway       | BAD_GATEWAY   | 502    | The auth token could not be verified because our se... |
-| insecure issuer   | MALFORMED_JWT | 400    | The auth token could not be verified because our se... |
-| parse error       | MALFORMED_JWT | 400    | The auth token could not be verified because it is ... |
-| no issuer         | MALFORMED_JWT | 400    | The auth token could not be verified because it doe... |
-| malformed exp     | MALFORMED_JWT | 400    | The auth token could not be verified because it's e... |
-| expired           | INVALID_JWT   | 401    | The auth token is expired. To try again, go to the ... |
-| inactive          | INVALID_JWT   | 401    | The auth token isn't valid yet. It's activation dat... |
-| bad signature     | INVALID_JWT   | 401    | The auth token did not pass verification because it... |
-| jwk not found old | INVALID_JWT   | 401    | The auth token did not pass verification because ou... |
-| jwk not found     | INVALID_JWT   | 401    | The auth token did not pass verification because ou... |
-| no jwkws uri      | INVALID_JWT   | 401    | The auth token did not pass verification because it... |
-| unknown issuer    | INVALID_JWT   | 401    | The auth token did not pass verification because it... |
-| failed claims     | INVALID_JWT   | 401    | The auth token did not pass verification because it... |
-
-# Change Log
-
-Minor Breaking changes (with a major version bump):
-
--   v3.0.0
-    -   reworked error messages (also available in v2.1.0 as `client_message`)
-    -   started using `let` and template strings (drops _really_ old node compat)
--   v2.0.0
-    -   changes from the default `issuers = ["*"]` to requiring that an issuer (or public jwk for verification) is specified
-
-See other changes in [CHANGELOG.md](./CHANGELOG.md).

keyfetch.js

@@ -19,7 +19,7 @@ async function requestAsync(req) {
 
     // differentiate potentially temporary server errors from 404
     if (!resp.ok && (resp.statusCode >= 500 || resp.statusCode < 200)) {
-        throw Errors.BAD_GATEWAY({ response: resp });
+        throw Errors.BAD_GATEWAY();
     }
 
     return resp;
@@ -37,8 +37,6 @@ function checkMinDefaultMax(opts, key, n, d, x) {
     }
 }
 
-keyfetch._errors = Errors;
-
 keyfetch._clear = function () {
     keyCache = {};
 };
@@ -48,15 +46,14 @@ keyfetch.init = function (opts) {
     staletime = checkMinDefaultMax(opts, "staletime", 1 * 60, staletime, 31 * 24 * 60 * 60);
 };
 keyfetch._oidc = async function (iss) {
-    var url = normalizeIss(iss) + "/.well-known/openid-configuration";
     var resp = await requestAsync({
-        url: url,
+        url: normalizeIss(iss) + "/.well-known/openid-configuration",
         json: true
     });
 
     var oidcConf = resp.body;
     if (!oidcConf.jwks_uri) {
-        throw Errors.NO_JWKS_URI(url);
+        throw Errors.OIDC_CONFIG_NOT_FOUND();
     }
     return oidcConf;
 };
@@ -196,7 +193,7 @@ keyfetch._setCache = function (iss, cacheable) {
 
 function normalizeIss(iss) {
     if (!iss) {
-        throw Errors.NO_ISSUER();
+        throw Errors.TOKEN_NO_ISSUER();
     }
 
     // We definitely don't want false negatives stemming
@@ -220,7 +217,7 @@ keyfetch.jwt.decode = function (jwt) {
         obj.claims = JSON.parse(Buffer.from(obj.payload, "base64"));
         return obj;
     } catch (e) {
-        var err = Errors.PARSE_ERROR(jwt);
+        var err = Errors.TOKEN_PARSE_ERROR(jwt);
         err.details = e.message;
         throw err;
     }
@@ -230,7 +227,7 @@ keyfetch.jwt.verify = async function (jwt, opts) {
         opts = {};
     }
 
-    var jws;
+    var decoded;
     var exp;
     var nbf;
     var active;
@@ -252,68 +249,60 @@ keyfetch.jwt.verify = async function (jwt, opts) {
     }
     var claims = opts.claims || {};
     if (!jwt || "string" === typeof jwt) {
-        jws = keyfetch.jwt.decode(jwt);
+        decoded = keyfetch.jwt.decode(jwt);
     } else {
-        jws = jwt;
+        decoded = jwt;
     }
 
-    if (!jws.claims.iss || !issuers.some(isTrustedIssuer(jws.claims.iss))) {
+    if (!decoded.claims.iss || !issuers.some(isTrustedIssuer(decoded.claims.iss))) {
         if (!(opts.jwk || opts.jwks)) {
-            throw Errors.UNKNOWN_ISSUER(jws.claims.iss || "");
+            throw Errors.ISSUER_NOT_TRUSTED(decoded.claims.iss || "");
         }
     }
     // Note claims.iss validates more strictly than opts.issuers (requires exact match)
-    var failedClaims = Object.keys(claims)
+    if (
-        .filter(function (key) {
+        !Object.keys(claims).every(function (key) {
-            if (claims[key] !== jws.claims[key]) {
+            if (claims[key] === decoded.claims[key]) {
                 return true;
             }
         })
-        .map(function (key) {
+    ) {
-            return "jwt.claims." + key + " = " + JSON.stringify(jws.claims[key]);
+        throw Errors.CLAIMS_MISMATCH(Object.keys(claims));
-        });
-    if (failedClaims.length) {
-        throw Errors.FAILED_CLAIMS(failedClaims, Object.keys(claims));
     }
 
-    exp = jws.claims.exp;
+    exp = decoded.claims.exp;
     if (exp && false !== opts.exp) {
         now = Date.now();
         // TODO document that opts.exp can be used as leeway? Or introduce opts.leeway?
-        // fair, but not necessary
-        exp = parseInt(exp, 10);
-        if (isNaN(exp)) {
-            throw Errors.MALFORMED_EXP(JSON.stringify(jws.claims.exp));
-        }
         then = (opts.exp || 0) + parseInt(exp, 10);
         active = then - now / 1000 > 0;
         // expiration was on the token or, if not, such a token is not allowed
         if (!active) {
-            throw Errors.EXPIRED(exp);
+            throw Errors.TOKEN_EXPIRED(exp);
         }
     }
 
-    nbf = jws.claims.nbf;
+    nbf = decoded.claims.nbf;
     if (nbf) {
         active = parseInt(nbf, 10) - Date.now() / 1000 <= 0;
         if (!active) {
-            throw Errors.INACTIVE(nbf);
+            throw Errors.TOKEN_INACTIVE(nbf);
         }
     }
     if (opts.jwks || opts.jwk) {
         return overrideLookup(opts.jwks || [opts.jwk]);
     }
 
-    var kid = jws.header.kid;
+    var kid = decoded.header.kid;
     var iss;
     var fetcher;
     var fetchOne;
     if (!opts.strategy || "oidc" === opts.strategy) {
-        iss = jws.claims.iss;
+        iss = decoded.claims.iss;
         fetcher = keyfetch.oidcJwks;
         fetchOne = keyfetch.oidcJwk;
     } else if ("auth0" === opts.strategy || "well-known" === opts.strategy) {
-        iss = jws.claims.iss;
+        iss = decoded.claims.iss;
         fetcher = keyfetch.wellKnownJwks;
         fetchOne = keyfetch.wellKnownJwk;
     } else {
@@ -328,10 +317,10 @@ keyfetch.jwt.verify = async function (jwt, opts) {
     return fetcher(iss).then(verifyAny);
 
     function verifyOne(hit) {
-        if (true === keyfetch.jws.verify(jws, hit)) {
+        if (true === keyfetch.jws.verify(decoded, hit)) {
-            return jws;
+            return decoded;
         }
-        throw Errors.BAD_SIGNATURE(jws.protected + "." + jws.payload + "." + jws.signature);
+        throw Errors.TOKEN_INVALID_SIGNATURE();
     }
 
     function verifyAny(hits) {
@@ -341,19 +330,20 @@ keyfetch.jwt.verify = async function (jwt, opts) {
                     if (kid !== hit.jwk.kid && kid !== hit.thumbprint) {
                         return;
                     }
-                    if (true === keyfetch.jws.verify(jws, hit)) {
+                    if (true === keyfetch.jws.verify(decoded, hit)) {
                         return true;
                     }
-                    throw Errors.BAD_SIGNATURE();
+                    throw Errors.TOKEN_INVALID_SIGNATURE();
-                }
+                } else {
-                if (true === keyfetch.jws.verify(jws, hit)) {
+                    if (true === keyfetch.jws.verify(decoded, hit)) {
                         return true;
                     }
+                }
             })
         ) {
-            return jws;
+            return decoded;
         }
-        throw Errors.JWK_NOT_FOUND_OLD(kid);
+        throw Errors.TOKEN_UNKNOWN_SIGNER();
     }
 
     function overrideLookup(jwks) {

lib/errors.js

@@ -19,47 +19,30 @@
  * }} opts
  * @returns {AuthError}
  */
-function create(old, msg, code, status, details) {
+function create(msg, { status = 401, code = "", details }) {
     /** @type AuthError */
     //@ts-ignore
-    let err = new Error(msg);
+    var err = new Error(msg);
-    err.message = msg;
+    err.message = err.message;
-    err._old_message = old;
-    err.code = code;
     err.status = status;
+    err.code = code;
     if (details) {
         err.details = details;
     }
     err.source = "keyfetch";
-    err.toJSON = toJSON;
-    err.toString = toString;
     return err;
 }
 
-function toJSON() {
-    /*jshint validthis:true*/
-    return {
-        message: this.message,
-        status: this.status,
-        code: this.code,
-        details: this.details
-    };
-}
-function toString() {
-    /*jshint validthis:true*/
-    return this.stack + "\n" + JSON.stringify(this);
-}
-
 // DEVELOPER_ERROR - a good token won't make a difference
 var E_DEVELOPER = "DEVELOPER_ERROR";
 
 // BAD_GATEWAY - there may be a temporary error fetching the public or or whatever
 var E_BAD_GATEWAY = "BAD_GATEWAY";
 
-// MALFORMED_JWT - the token could not be verified - not parsable, missing claims, etc
+// MALFORMED_TOKEN - the token could not be verified - not parsable, missing claims, etc
 var E_MALFORMED = "MALFORMED_JWT";
 
-// INVALID_JWT - the token's properties don't meet requirements - iss, claims, sig, exp
+// INVALID_TOKEN - the token's properties don't meet requirements - iss, claims, sig, exp
 var E_INVALID = "INVALID_JWT";
 
 module.exports = {
@@ -71,20 +54,12 @@ module.exports = {
      * @param {string} msg
      * @returns {AuthError}
      */
-    DEVELOPER_ERROR: function (old, msg, details) {
+    DEVELOPER_ERROR: function (msg) {
-        return create(old, msg || old, E_DEVELOPER, 500, details);
+        return create(msg, { status: 500, code: E_DEVELOPER });
     },
-    BAD_GATEWAY: function (err) {
+    BAD_GATEWAY: function (/*err*/) {
-        var msg =
+        var msg = "The server encountered a network error or a bad gateway.";
-            "The auth token could not be verified because our server encountered a network error (or a bad gateway) when connecting to its issuing server.";
+        return create(msg, { status: 502, code: E_BAD_GATEWAY });
-        var details = [];
-        if (err.message) {
-            details.push("error.message = " + err.message);
-        }
-        if (err.response && err.response.statusCode) {
-            details.push("response.statusCode = " + err.response.statusCode);
-        }
-        return create(msg, msg, E_BAD_GATEWAY, 502, details);
     },
 
     //
@@ -96,46 +71,25 @@ module.exports = {
      * @returns {AuthError}
      */
     INSECURE_ISSUER: function (iss) {
-        var old =
-            "'" + iss + "' is NOT secure. Set env 'KEYFETCH_ALLOW_INSECURE_HTTP=true' to allow for testing. (iss)";
-        var details = [
-            "jwt.claims.iss = " + JSON.stringify(iss),
-            "DEBUG: Set ENV 'KEYFETCH_ALLOW_INSECURE_HTTP=true' to allow insecure issuers (for testing)."
-        ];
         var msg =
-            'The auth token could not be verified because our server could connect to its issuing server ("iss") securely.';
+            "'" + iss + "' is NOT secure. Set env 'KEYFETCH_ALLOW_INSECURE_HTTP=true' to allow for testing. (iss)";
-        return create(old, msg, E_MALFORMED, 400, details);
+        return create(msg, { status: 400, code: E_MALFORMED });
     },
     /**
      * @param {string} jwt
      * @returns {AuthError}
      */
-    PARSE_ERROR: function (jwt) {
+    TOKEN_PARSE_ERROR: function (jwt) {
-        var old = "could not parse jwt: '" + jwt + "'";
+        var msg = "could not parse jwt: '" + jwt + "'";
-        var msg = "The auth token could not be verified because it is malformed.";
+        return create(msg, { status: 400, code: E_MALFORMED });
-        var details = ["jwt = " + JSON.stringify(jwt)];
-        return create(old, msg, E_MALFORMED, 400, details);
     },
     /**
      * @param {string} iss
      * @returns {AuthError}
      */
-    NO_ISSUER: function (iss) {
+    TOKEN_NO_ISSUER: function (iss) {
-        var old = "'iss' is not defined";
+        var msg = "'iss' is not defined";
-        var msg = 'The auth token could not be verified because it doesn\'t specify an issuer ("iss").';
+        return create(msg, { status: 400, code: E_MALFORMED });
-        var details = ["jwt.claims.iss = " + JSON.stringify(iss)];
-        return create(old, msg, E_MALFORMED, 400, details);
-    },
-
-    /**
-     * @param {string} iss
-     * @returns {AuthError}
-     */
-    MALFORMED_EXP: function (exp) {
-        var old = "token's 'exp' has passed or could not parsed: '" + exp + "'";
-        var msg = 'The auth token could not be verified because it\'s expiration date ("exp") could not be read';
-        var details = ["jwt.claims.exp = " + JSON.stringify(exp)];
-        return create(old, msg, E_MALFORMED, 400, details);
     },
 
     //
@@ -146,125 +100,77 @@ module.exports = {
      * @param {number} exp
      * @returns {AuthError}
      */
-    EXPIRED: function (exp) {
+    TOKEN_EXPIRED: function (exp) {
-        var old = "token's 'exp' has passed or could not parsed: '" + exp + "'";
+        //var msg = "The auth token is expired. (exp='" + exp + "')";
-        // var msg = "The auth token did not pass verification because it is expired.not properly signed.";
+        var msg = "token's 'exp' has passed or could not parsed: '" + exp + "'";
-        var msg = "The auth token is expired. To try again, go to the main page and sign in.";
+        return create(msg, { code: E_INVALID });
-        var details = ["jwt.claims.exp = " + JSON.stringify(exp)];
-        return create(old, msg, E_INVALID, 401, details);
     },
     /**
      * @param {number} nbf
      * @returns {AuthError}
      */
-    INACTIVE: function (nbf) {
+    TOKEN_INACTIVE: function (nbf) {
-        var old = "token's 'nbf' has not been reached or could not parsed: '" + nbf + "'";
+        //var msg = "The auth token is not active yet. (nbf='" + nbf + "')";
-        var msg = "The auth token isn't valid yet. It's activation date (\"nbf\") is in the future.";
+        var msg = "token's 'nbf' has not been reached or could not parsed: '" + nbf + "'";
-        var details = ["jwt.claims.nbf = " + JSON.stringify(nbf)];
+        return create(msg, { code: E_INVALID });
-        return create(old, msg, E_INVALID, 401, details);
     },
     /** @returns {AuthError} */
-    BAD_SIGNATURE: function (jwt) {
+    TOKEN_INVALID_SIGNATURE: function () {
-        var old = "token signature verification was unsuccessful";
+        //var msg = "The auth token is not properly signed and could not be verified.";
-        var msg = "The auth token did not pass verification because it is not properly signed.";
+        var msg = "token signature verification was unsuccessful";
-        var details = ["jwt = " + JSON.stringify(jwt)];
+        return create(msg, { code: E_INVALID });
-        return create(old, msg, E_INVALID, 401, details);
     },
-    /**
+    /** @returns {AuthError} */
-     * @param {string} kid
+    TOKEN_UNKNOWN_SIGNER: function () {
-     * @returns {AuthError}
+        var msg = "Retrieved a list of keys, but none of them matched the 'kid' (key id) of the token.";
-     */
+        return create(msg, { code: E_INVALID });
-    JWK_NOT_FOUND_OLD: function (kid) {
-        var old = "Retrieved a list of keys, but none of them matched the 'kid' (key id) of the token.";
-        var msg =
-            'The auth token did not pass verification because our server couldn\'t find a mutually trusted verification key ("jwk").';
-        var details = ["jws.header.kid = " + JSON.stringify(kid)];
-        return create(old, msg, E_INVALID, 401, details);
     },
     /**
      * @param {string} id
      * @returns {AuthError}
      */
     JWK_NOT_FOUND: function (id) {
-        // TODO Distinguish between when it's a kid vs thumbprint.
+        var msg = "No JWK found by kid or thumbprint '" + id + "'";
-        var old = "No JWK found by kid or thumbprint '" + id + "'";
+        return create(msg, { code: E_INVALID });
-        var msg =
-            'The auth token did not pass verification because our server couldn\'t find a mutually trusted verification key ("jwk").';
-        var details = ["jws.header.kid = " + JSON.stringify(id)];
-        return create(old, msg, E_INVALID, 401, details);
     },
     /** @returns {AuthError} */
-    NO_JWKWS_URI: function (url) {
+    OIDC_CONFIG_NOT_FOUND: function () {
-        var old = "Failed to retrieve openid configuration";
+        //var msg = "Failed to retrieve OpenID configuration for token issuer";
-        var msg =
+        var msg = "Failed to retrieve openid configuration";
-            'The auth token did not pass verification because its issuing server did not list any verification keys ("jwks").';
+        return create(msg, { code: E_INVALID });
-        var details = ["OpenID Provider Configuration: " + JSON.stringify(url)];
-        return create(old, msg, E_INVALID, 401, details);
     },
     /**
      * @param {string} iss
      * @returns {AuthError}
      */
-    UNKNOWN_ISSUER: function (iss) {
+    ISSUER_NOT_TRUSTED: function (iss) {
-        var old = "token was issued by an untrusted issuer: '" + iss + "'";
+        var msg = "token was issued by an untrusted issuer: '" + iss + "'";
-        var msg = "The auth token did not pass verification because it wasn't issued by a server that we trust.";
+        return create(msg, { code: E_INVALID });
-        var details = ["jwt.claims.iss = " + JSON.stringify(iss)];
-        return create(old, msg, E_INVALID, 401, details);
     },
     /**
-     * @param {Array<string>} details
+     * @param {Array<string>} claimNames
      * @returns {AuthError}
      */
-    FAILED_CLAIMS: function (details, claimNames) {
+    CLAIMS_MISMATCH: function (claimNames) {
-        var old = "token did not match on one or more authorization claims: '" + claimNames + "'";
+        var msg = "token did not match on one or more authorization claims: '" + claimNames + "'";
-        var msg =
+        return create(msg, { code: E_INVALID });
-            'The auth token did not pass verification because it failed some of the verification criteria ("claims").';
-        return create(old, msg, E_INVALID, 401, details);
     }
 };
-var Errors = module.exports;
 
 // for README
 if (require.main === module) {
-    let maxWidth = 54;
+    console.info("| Name | Status | Message (truncated) |");
-    let header = ["Hint", "Code", "Status", "Message (truncated)"];
+    console.info("| ---- | ------ | ------------------- |");
-    let widths = header.map(function (v) {
-        return Math.min(maxWidth, String(v).length);
-    });
-    let rows = [];
     Object.keys(module.exports).forEach(function (k) {
         //@ts-ignore
         var E = module.exports[k];
-        var e = E("test");
+        var e = E();
         var code = e.code;
         var msg = e.message;
-        var hint = k.toLowerCase().replace(/_/g, " ");
+        if ("E_" + k !== e.code) {
-        widths[0] = Math.max(widths[0], String(hint).length);
+            code = k;
-        widths[1] = Math.max(widths[1], String(code).length);
+            msg = e.details || msg;
-        widths[2] = Math.max(widths[2], String(e.status).length);
-        widths[3] = Math.min(maxWidth, Math.max(widths[3], String(msg).length));
-        rows.push([hint, code, e.status, msg]);
-    });
-    rows.forEach(function (cols, i) {
-        let cells = cols.map(function (col, i) {
-            if (col.length > maxWidth) {
-                col = col.slice(0, maxWidth - 3);
-                col += "...";
         }
-            return String(col).padEnd(widths[i], " ");
+        console.info(`| ${code} | ${e.status} | ${msg.slice(0, 45)}... |`);
     });
-        let out = `| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[3].slice(0, widths[3])} |`;
-        //out = out.replace(/\| /g, " ").replace(/\|/g, "");
-        console.info(out);
-        if (i === 0) {
-            cells = cols.map(function (col, i) {
-                return "-".padEnd(widths[i], "-");
-            });
-            console.info(`| ${cells[0]} | ${cells[1]} | ${cells[2]} | ${cells[3]} |`);
-        }
-    });
-    console.log();
-    console.log(Errors.MALFORMED_EXP());
-    console.log();
-    console.log(JSON.stringify(Errors.MALFORMED_EXP(), null, 2));
 }

package-lock.json

@@ -1,12 +1,12 @@
 {
     "name": "keyfetch",
-    "version": "3.0.2",
+    "version": "2.0.0",
     "lockfileVersion": 2,
     "requires": true,
     "packages": {
         "": {
             "name": "keyfetch",
-            "version": "3.0.2",
+            "version": "2.0.0",
             "license": "MPL-2.0",
             "dependencies": {
                 "@root/request": "^1.8.0",

package.json

@@ -1,6 +1,6 @@
 {
     "name": "keyfetch",
-    "version": "3.0.2",
+    "version": "2.0.0",
     "description": "Lightweight support for fetching JWKs.",
     "homepage": "https://git.rootprojects.org/root/keyfetch.js",
     "main": "keyfetch.js",