@flink-app/jwt-auth-plugin 2.0.0-alpha.83 → 2.0.0-alpha.85

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @flink-app/jwt-auth-plugin
 
+## 2.0.0-alpha.85
+
+### Minor Changes
+
+-   179c085: Add support for trailing-segment wildcard scopes in `rolePermissions`. A role scope ending in `.*` (e.g. `"license.subscription.*"`) now matches any required route permission that starts with that prefix including the trailing dot — `"license.subscription.get"` and `"license.subscription.cancel"` match, while `"license.subscription"` and `"license.subscriptions.get"` do not. Wildcards are segment-scoped to prevent accidental privilege escalation, and only trailing `.*` is special. Existing behavior (route `"*"`, role `"*"`, exact-match scopes, empty permission arrays) is unchanged.
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.85
+
+## 2.0.0-alpha.84
+
+### Patch Changes
+
+-   @flink-app/flink@2.0.0-alpha.84
+
 ## 2.0.0-alpha.83
 
 ### Patch Changes

package/dist/PermissionValidator.js

@@ -2,6 +2,23 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasValidPermissions = hasValidPermissions;
 var flink_1 = require("@flink-app/flink");
+/**
+ * Checks whether a single role scope entry matches a required route
+ * permission. Supports exact match and trailing-segment wildcards of the
+ * form `"foo.bar.*"`, which match any route permission that starts with
+ * `"foo.bar."` (segment-scoped — does NOT match `"foo.bar"` itself, and
+ * does NOT match `"foo.barbaz.x"`).
+ */
+function scopeMatches(scope, routePerm) {
+    if (scope === routePerm)
+        return true;
+    if (scope.endsWith(".*")) {
+        // Keep the trailing "." so "a.*" does not match "a" or "ab.c".
+        var prefix = scope.slice(0, -1);
+        return routePerm.startsWith(prefix);
+    }
+    return false;
+}
 /**
  * Checks if provided role has permission to access route
  * based on its permissions.
@@ -28,7 +45,7 @@ function hasValidPermissions(roles, rolePermissions, routePermissions) {
             return { value: true };
         }
         if (routePermissions.every(function (routePerm) {
-            return thisRolesPermissions.includes(routePerm);
+            return thisRolesPermissions.some(function (scope) { return scopeMatches(scope, routePerm); });
         })) {
             return { value: true };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flink-app/jwt-auth-plugin",
-  "version": "2.0.0-alpha.83",
+  "version": "2.0.0-alpha.85",
   "description": "Flink plugin for JWT auth",
   "author": "joel@frost.se",
   "license": "MIT",
@@ -19,10 +19,10 @@
     "@types/node": "22.13.10",
     "ts-node": "^10.9.2",
     "tsc-watch": "^4.2.9",
-    "@flink-app/flink": "2.0.0-alpha.83"
+    "@flink-app/flink": "2.0.0-alpha.85"
   },
   "peerDependencies": {
-    "@flink-app/flink": ">=2.0.0-alpha.83"
+    "@flink-app/flink": ">=2.0.0-alpha.85"
   },
   "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
   "scripts": {

package/readme.md

@@ -94,6 +94,44 @@ jwtAuthPlugin({
 })
 ```
 
+## Permission Matching Semantics
+
+The static `rolePermissions` map supports three forms of matching:
+
+1. **Exact match** — `"car.read"` in a role's scope list matches a route declaring `permissions: ["car.read"]`.
+2. **Role superuser** — a role whose scope list contains `"*"` is granted every permission unconditionally.
+3. **Route allows any authenticated user** — a route declaring `permissions: ["*"]` accepts any role as long as the user is authenticated.
+4. **Suffix wildcard scopes** — a scope entry ending in `.*` (e.g. `"license.subscription.*"`) matches any required route permission whose literal string starts with the prefix including the trailing dot.
+
+### Suffix wildcard scopes
+
+```typescript
+rolePermissions: {
+  restricted: [
+    "license.subscription.*", // matches license.subscription.get, license.subscription.cancel, ...
+    "license.unsubscribe",    // exact match
+  ],
+  admin: ["*"],               // every permission (superuser)
+}
+```
+
+Matching rules:
+
+| Scope entry                  | Route permission                       | Result      |
+| ---------------------------- | -------------------------------------- | ----------- |
+| `"license.subscription.*"`   | `"license.subscription.get"`           | match       |
+| `"license.subscription.*"`   | `"license.subscription.cancel"`        | match       |
+| `"license.subscription.*"`   | `"license.subscription"` (no suffix)   | **no match** — wildcard requires a segment after the prefix |
+| `"license.subscription.*"`   | `"license.subscriptions.get"`          | **no match** — segment-boundary safety, prevents accidental escalation through similarly-named scopes |
+| `"a.b.c.*"`                  | `"a.b.c.x.y"`                          | match       |
+
+Notes:
+
+- The wildcard is **segment-scoped**, not substring-scoped. `foo.*` matches `foo.bar` and `foo.bar.baz` but never `foobar.x`.
+- Only a **trailing** `.*` is special. Infix forms like `*.get` or `foo.*.bar` are not supported.
+- Wildcard scopes can be mixed freely with exact-match entries in the same role.
+- All required route permissions must be matched (the check is `every`), so a single wildcard can cover multiple required scopes only if they all fall under its prefix.
+
 ## Custom Token Extraction
 
 By default, the plugin extracts JWT tokens from the `Authorization` header as Bearer tokens:

package/spec/PermissionValidator.spec.ts

@@ -69,4 +69,96 @@ describe("PermissionValidator", () => {
     const valid = hasValidPermissions([], {}, ["*"]);
     expect(valid).toBe(false);
   });
+
+  describe("suffix wildcard scopes", () => {
+    it("should match a single-segment suffix under the wildcard", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should match a multi-segment suffix under the wildcard", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b.c"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should NOT match the wildcard prefix without a trailing segment", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a"]
+      );
+      expect(valid).toBe(false);
+    });
+
+    it("should NOT match across a segment boundary (privilege escalation guard)", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["ab.c"]
+      );
+      expect(valid).toBe(false);
+    });
+
+    it("should allow mixing wildcard and exact scopes when the required perm hits the exact one", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*", "b.get"] },
+        ["b.get"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should deny when the required perm matches neither the wildcard nor the exact entry", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*", "b.get"] },
+        ["b.put"]
+      );
+      expect(valid).toBe(false);
+    });
+
+    it("should still honor route '*' when the role only has a suffix wildcard", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["*"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should match deeply nested prefixes", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.b.c.*"] },
+        ["a.b.c.x.y"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should allow a single wildcard to cover multiple required perms", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b", "a.c"]
+      );
+      expect(valid).toBe(true);
+    });
+
+    it("should deny when one required perm is outside the wildcard namespace", () => {
+      const valid = hasValidPermissions(
+        ["user"],
+        { user: ["a.*"] },
+        ["a.b", "c.d"]
+      );
+      expect(valid).toBe(false);
+    });
+  });
 });

package/src/PermissionValidator.ts

@@ -1,5 +1,22 @@
 import { log } from "@flink-app/flink";
 
+/**
+ * Checks whether a single role scope entry matches a required route
+ * permission. Supports exact match and trailing-segment wildcards of the
+ * form `"foo.bar.*"`, which match any route permission that starts with
+ * `"foo.bar."` (segment-scoped — does NOT match `"foo.bar"` itself, and
+ * does NOT match `"foo.barbaz.x"`).
+ */
+function scopeMatches(scope: string, routePerm: string): boolean {
+  if (scope === routePerm) return true;
+  if (scope.endsWith(".*")) {
+    // Keep the trailing "." so "a.*" does not match "a" or "ab.c".
+    const prefix = scope.slice(0, -1);
+    return routePerm.startsWith(prefix);
+  }
+  return false;
+}
+
 /**
  * Checks if provided role has permission to access route
  * based on its permissions.
@@ -36,7 +53,7 @@ export function hasValidPermissions(
 
     if (
       routePermissions.every((routePerm) =>
-        thisRolesPermissions.includes(routePerm)
+        thisRolesPermissions.some((scope) => scopeMatches(scope, routePerm))
       )
     ) {
       return true;