@tidecloak/verify 0.13.28 → 0.13.31

package/README.md

@@ -2,7 +2,7 @@
 
 A lightweight utility for server‑side verification of TideCloak‑issued JSON Web Tokens (JWTs).
 
-This package exports a single function, `verifyTideCloakToken`, which you can use in your Next.js API routes, Node.js servers, or any backend to verify the authenticity, issuer, audience, and roles of a JWT issued by your TideCloak realm.
+This package exports a single function, `verifyTideCloakToken`, which you can use in your Next.js API routes, Node.js servers, or any backend to verify the signature, issuer, authorized party (`azp`), and roles of a JWT issued by your TideCloak realm.
 
 ---
 
@@ -47,11 +47,23 @@ Internally, `verifyTideCloakToken` uses the [jose](https://github.com/panva/jose
 1. Ensure a token is present.
 2. Construct the correct issuer URL from `config['auth-server-url']` and `config.realm`.
 3. Choose between a local JWK Set (`config.jwk.keys`) or fetch the JWK Set remotely from Tidecloak.
-4. Verify the token's signature, issuer, and `azp` (authorized party) against `config.resource`.
-5. Extract realm (`payload.realm_access.roles`) and client (`payload.resource_access[resource].roles`) roles.
-6. Check for at least one matching role if `allowedRoles` is specified.
+4. Verify the token's signature against a **pinned algorithm allowlist** (`ES256`, `ES384`, `ES512`, `EdDSA` by default), the `issuer`, and the standard time claims (`exp`/`nbf`) with a small `clockTolerance`.
+5. Verify the `azp` (authorized party) against `config.resource` — **only when `resource` is configured**.
+6. Extract realm (`payload.realm_access.roles`) and client (`payload.resource_access[resource].roles`) roles.
+7. Check for at least one matching role if `allowedRoles` is specified.
 
-On any failure, it logs an error to the console and returns `null`.
+On any failure, it logs the error message to the console and returns `null`.
+
+> **Note:** the algorithm allowlist closes algorithm-confusion attacks — without it, `jose` would accept any algorithm a key in the set can validate. A `null` result collapses both invalid tokens and infrastructure failures (e.g. an unreachable remote JWKS endpoint), so treat `null` as "not authorized" and monitor your JWKS reachability separately.
+
+### Optional config fields
+
+You can tune verification by adding these optional fields to the `config` object:
+
+| Field                       | Type                   | Default                                  | Description                                                                 |
+| --------------------------- | ---------------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
+| `tokenSignatureAlgorithms`  | `string[]`             | `['ES256','ES384','ES512','EdDSA']`      | Allowed JWS signature algorithms. Override if your realm signs with others (e.g. `['RS256']`). |
+| `clockTolerance`            | `number` \| `string`   | `'5s'`                                   | Allowed clock skew between issuer and verifier (seconds, or a jose duration string). |
 
 ---
 
@@ -172,10 +184,14 @@ export async function GET(req: NextRequest) {
 interface TidecloakConfig {
   realm: string;
   'auth-server-url': string;
-  resource: string;
+  resource?: string;
   publicClient?: boolean;
   confidentialPort?: number;
-  jwk?: { keys: Array<{ kid: string; kty: string; alg: string; use: string; x: string; crv?: string }> };
+  jwk?: { keys: Array<{ kid: string; kty: string; alg?: string; use?: string; x?: string; crv?: string; n?: string; e?: string }> };
+  /** Allowed JWS signature algorithms. Default: ['ES256','ES384','ES512','EdDSA']. */
+  tokenSignatureAlgorithms?: string[];
+  /** Allowed clock skew (seconds or a jose duration string). Default: '5s'. */
+  clockTolerance?: number | string;
   [key: string]: unknown;
 }
 

package/dist/cjs/TideJWT.js

@@ -1,14 +1,26 @@
-import { jwtVerify, createLocalJWKSet, createRemoteJWKSet } from "jose";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.verifyTideCloakToken = verifyTideCloakToken;
+const jose_1 = require("jose");
+/**
+ * Signature algorithms TideCloak realms issue tokens with. Pinning these prevents
+ * algorithm-confusion attacks: without an explicit allowlist `jose` accepts any
+ * algorithm a key in the set can validate (and falls back to permissive behaviour
+ * for keys that omit an `alg`). Override via `config.tokenSignatureAlgorithms`.
+ */
+const DEFAULT_ALLOWED_ALGORITHMS = ["ES256", "ES384", "ES512", "EdDSA"];
 /**
  * Verify a TideCloak-issued JWT on the server side using your imported config object.
  *
- * @param {object} config - Imported TideCloak configuration (parsed JSON).
+ * @param {object} config - Imported TideCloak configuration (parsed JSON). May also
+ *   carry optional `tokenSignatureAlgorithms` (string[]) and `clockTolerance`
+ *   (number of seconds, or a jose duration string) to tune verification.
  * @param {string} token - access token to verify.
  * @param {string[]} [allowedRoles] - Array of Tidecloak realm or client roles; user must have at least one.
  * @returns {Promise<object|null>} - The token payload if valid and role-check passes, otherwise null.
  */
-export async function verifyTideCloakToken(config, token, allowedRoles = []) {
-    var _a, _b, _c;
+async function verifyTideCloakToken(config, token, allowedRoles = []) {
+    var _a, _b, _c, _d;
     try {
         // Ensure token is provided
         if (!token) {
@@ -24,18 +36,27 @@ export async function verifyTideCloakToken(config, token, allowedRoles = []) {
         const issuer = `${baseUrl}${sep}realms/${config.realm}`;
         // Determine JWK set (use local JWKs if provided, otherwise fetch remotely)
         const jwkSet = config.jwk
-            ? createLocalJWKSet(config.jwk)
-            : createRemoteJWKSet(new URL(`${issuer}/protocol/openid-connect/certs`));
-        // Verify token signature and issuer
-        const { payload } = await jwtVerify(token, jwkSet, { issuer });
-        // Verify authorized party (client)
+            ? (0, jose_1.createLocalJWKSet)(config.jwk)
+            : (0, jose_1.createRemoteJWKSet)(new URL(`${issuer}/protocol/openid-connect/certs`));
+        // Verify signature (with a pinned algorithm allowlist), issuer and time claims.
+        // `clockTolerance` allows a small amount of clock drift between issuer and verifier.
+        const algorithms = Array.isArray(config.tokenSignatureAlgorithms) && config.tokenSignatureAlgorithms.length > 0
+            ? config.tokenSignatureAlgorithms
+            : DEFAULT_ALLOWED_ALGORITHMS;
+        const { payload } = await (0, jose_1.jwtVerify)(token, jwkSet, {
+            issuer,
+            algorithms,
+            clockTolerance: (_a = config.clockTolerance) !== null && _a !== void 0 ? _a : "5s",
+        });
+        // Verify authorized party (client). Only enforced when a `resource` (client id)
+        // is configured; without this guard an undefined client would reject every token.
         const client = config["resource"];
-        if (payload.azp !== client) {
-            throw new Error(`AZP mismatch: expected '${config.resource}', got '${payload.azp}'`);
+        if (client !== undefined && client !== null && payload.azp !== client) {
+            throw new Error(`AZP mismatch: expected '${client}', got '${payload.azp}'`);
         }
         // Gather all user roles from realm and client roles for the specified resource from the config.
-        const realmRoles = ((_a = payload.realm_access) === null || _a === void 0 ? void 0 : _a.roles) || [];
-        const clientRoles = ((_c = (_b = payload.resource_access) === null || _b === void 0 ? void 0 : _b[client]) === null || _c === void 0 ? void 0 : _c.roles) || [];
+        const realmRoles = ((_b = payload.realm_access) === null || _b === void 0 ? void 0 : _b.roles) || [];
+        const clientRoles = ((_d = (_c = payload.resource_access) === null || _c === void 0 ? void 0 : _c[client]) === null || _d === void 0 ? void 0 : _d.roles) || [];
         const allRoles = new Set([...realmRoles, ...clientRoles]);
         // If allowedRoles specified, ensure at least one match
         if (allowedRoles.length > 0) {
@@ -47,7 +68,11 @@ export async function verifyTideCloakToken(config, token, allowedRoles = []) {
         return payload;
     }
     catch (err) {
-        console.error("[TideJWT] Token verification failed:", err);
+        // Log only the message (not the error object, which can echo token-derived
+        // data). Note: this collapses both invalid tokens and infrastructure failures
+        // (e.g. an unreachable JWKS endpoint) into a `null` result, so callers cannot
+        // distinguish "forbidden" from "auth backend down".
+        console.error("[TideJWT] Token verification failed:", err instanceof Error ? err.message : err);
         return null;
     }
 }

package/dist/cjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/dist/esm/TideJWT.js

@@ -1,14 +1,23 @@
 import { jwtVerify, createLocalJWKSet, createRemoteJWKSet } from "jose";
+/**
+ * Signature algorithms TideCloak realms issue tokens with. Pinning these prevents
+ * algorithm-confusion attacks: without an explicit allowlist `jose` accepts any
+ * algorithm a key in the set can validate (and falls back to permissive behaviour
+ * for keys that omit an `alg`). Override via `config.tokenSignatureAlgorithms`.
+ */
+const DEFAULT_ALLOWED_ALGORITHMS = ["ES256", "ES384", "ES512", "EdDSA"];
 /**
  * Verify a TideCloak-issued JWT on the server side using your imported config object.
  *
- * @param {object} config - Imported TideCloak configuration (parsed JSON).
+ * @param {object} config - Imported TideCloak configuration (parsed JSON). May also
+ *   carry optional `tokenSignatureAlgorithms` (string[]) and `clockTolerance`
+ *   (number of seconds, or a jose duration string) to tune verification.
  * @param {string} token - access token to verify.
  * @param {string[]} [allowedRoles] - Array of Tidecloak realm or client roles; user must have at least one.
  * @returns {Promise<object|null>} - The token payload if valid and role-check passes, otherwise null.
  */
 export async function verifyTideCloakToken(config, token, allowedRoles = []) {
-    var _a, _b, _c;
+    var _a, _b, _c, _d;
     try {
         // Ensure token is provided
         if (!token) {
@@ -26,16 +35,25 @@ export async function verifyTideCloakToken(config, token, allowedRoles = []) {
         const jwkSet = config.jwk
             ? createLocalJWKSet(config.jwk)
             : createRemoteJWKSet(new URL(`${issuer}/protocol/openid-connect/certs`));
-        // Verify token signature and issuer
-        const { payload } = await jwtVerify(token, jwkSet, { issuer });
-        // Verify authorized party (client)
+        // Verify signature (with a pinned algorithm allowlist), issuer and time claims.
+        // `clockTolerance` allows a small amount of clock drift between issuer and verifier.
+        const algorithms = Array.isArray(config.tokenSignatureAlgorithms) && config.tokenSignatureAlgorithms.length > 0
+            ? config.tokenSignatureAlgorithms
+            : DEFAULT_ALLOWED_ALGORITHMS;
+        const { payload } = await jwtVerify(token, jwkSet, {
+            issuer,
+            algorithms,
+            clockTolerance: (_a = config.clockTolerance) !== null && _a !== void 0 ? _a : "5s",
+        });
+        // Verify authorized party (client). Only enforced when a `resource` (client id)
+        // is configured; without this guard an undefined client would reject every token.
         const client = config["resource"];
-        if (payload.azp !== client) {
-            throw new Error(`AZP mismatch: expected '${config.resource}', got '${payload.azp}'`);
+        if (client !== undefined && client !== null && payload.azp !== client) {
+            throw new Error(`AZP mismatch: expected '${client}', got '${payload.azp}'`);
         }
         // Gather all user roles from realm and client roles for the specified resource from the config.
-        const realmRoles = ((_a = payload.realm_access) === null || _a === void 0 ? void 0 : _a.roles) || [];
-        const clientRoles = ((_c = (_b = payload.resource_access) === null || _b === void 0 ? void 0 : _b[client]) === null || _c === void 0 ? void 0 : _c.roles) || [];
+        const realmRoles = ((_b = payload.realm_access) === null || _b === void 0 ? void 0 : _b.roles) || [];
+        const clientRoles = ((_d = (_c = payload.resource_access) === null || _c === void 0 ? void 0 : _c[client]) === null || _d === void 0 ? void 0 : _d.roles) || [];
         const allRoles = new Set([...realmRoles, ...clientRoles]);
         // If allowedRoles specified, ensure at least one match
         if (allowedRoles.length > 0) {
@@ -47,7 +65,11 @@ export async function verifyTideCloakToken(config, token, allowedRoles = []) {
         return payload;
     }
     catch (err) {
-        console.error("[TideJWT] Token verification failed:", err);
+        // Log only the message (not the error object, which can echo token-derived
+        // data). Note: this collapses both invalid tokens and infrastructure failures
+        // (e.g. an unreachable JWKS endpoint) into a `null` result, so callers cannot
+        // distinguish "forbidden" from "auth backend down".
+        console.error("[TideJWT] Token verification failed:", err instanceof Error ? err.message : err);
         return null;
     }
 }

package/dist/esm/package.json

@@ -0,0 +1 @@
+{"type":"module"}

package/dist/types/TideJWT.d.ts

@@ -1,7 +1,9 @@
 /**
  * Verify a TideCloak-issued JWT on the server side using your imported config object.
  *
- * @param {object} config - Imported TideCloak configuration (parsed JSON).
+ * @param {object} config - Imported TideCloak configuration (parsed JSON). May also
+ *   carry optional `tokenSignatureAlgorithms` (string[]) and `clockTolerance`
+ *   (number of seconds, or a jose duration string) to tune verification.
  * @param {string} token - access token to verify.
  * @param {string[]} [allowedRoles] - Array of Tidecloak realm or client roles; user must have at least one.
  * @returns {Promise<object|null>} - The token payload if valid and role-check passes, otherwise null.

package/dist/types/TideJWT.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TideJWT.d.ts","sourceRoot":"","sources":["../../src/TideJWT.js"],"names":[],"mappings":"AAEA;;;;;;;GAOG;AACH,6CALW,MAAM,SACN,MAAM,iBACN,MAAM,EAAE,GACN,OAAO,CAAC,MAAM,GAAC,IAAI,CAAC,CAsDhC"}
+{"version":3,"file":"TideJWT.d.ts","sourceRoot":"","sources":["../../src/TideJWT.js"],"names":[],"mappings":"AAUA;;;;;;;;;GASG;AACH,6CAPW,MAAM,SAGN,MAAM,iBACN,MAAM,EAAE,GACN,OAAO,CAAC,MAAM,GAAC,IAAI,CAAC,CAmEhC"}

package/package.json

@@ -1,12 +1,16 @@
 {
   "name": "@tidecloak/verify",
-  "version": "0.13.28",
+  "version": "0.13.31",
   "description": "A lightweight utility for server-side verification of TideCloak-issued JSON Web Tokens (JWTs).",
+  "main": "./dist/cjs/TideJWT.js",
+  "module": "./dist/esm/TideJWT.js",
+  "types": "./dist/types/TideJWT.d.ts",
   "exports": {
     ".": {
-      "import": "./dist/esm/TideJWT.js",
       "types": "./dist/types/TideJWT.d.ts",
-      "require": "./dist/cjs/TideJWT.js"
+      "import": "./dist/esm/TideJWT.js",
+      "require": "./dist/cjs/TideJWT.js",
+      "default": "./dist/esm/TideJWT.js"
     }
   },
   "files": [
@@ -15,7 +19,8 @@
   "scripts": {
     "build:cjs": "tsc -p tsconfig.cjs.json",
     "build:esm": "tsc -p tsconfig.esm.json",
-    "build": "npm run build:cjs && npm run build:esm",
+    "build": "npm run build:cjs && npm run build:esm && node scripts/postbuild.cjs",
+    "test": "node --test test/*.test.mjs",
     "prepare": "npm run build"
   },
   "publishConfig": {