feat(auth-permission): add expressRegisterPermissionAuth for Express-based services

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wave-tech/framework",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "wave tech team shared utils framework",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -25,24 +25,32 @@
   "peerDependencies": {
     "@dbos-inc/dbos-sdk": "^4.27.6",
     "@prisma/client": ">=6.3.1",
+    "@types/express": "^4.17.21",
+    "express": "^4.21.2",
     "fastify": "^5.0.0"
   },
   "peerDependenciesMeta": {
     "@dbos-inc/dbos-sdk": {
       "optional": true
     },
+    "@types/express": {
+      "optional": true
+    },
+    "express": {
+      "optional": true
+    },
     "fastify": {
       "optional": true
     }
   },
   "dependencies": {
     "@fastify/rate-limit": "^11.2.0",
     "date-fns": "^4.1.0",
-    "express": "^4.21.2",
     "google-auth-library": "^9.15.1",
     "hono": "^4.8.5",
     "jose": "^6.2.12",
     "mathjs": "^14.2.1",
+    "path-to-regexp": "8.4.2",
     "uuid": "^11.0.5",
     "winston": "^3.17.0",
     "zod": "^4.4.3"
@@ -51,7 +59,7 @@
     "@dbos-inc/dbos-sdk": "^4.27.6",
     "@eslint/js": "^9.20.0",
     "@prisma/client": "^6.3.1",
-    "@types/express": "^5.0.0",
+    "@types/express": "^4.17.21",
     "@types/node": "^24.0.0",
     "@typescript-eslint/parser": "^8.24.0",
     "cross-env": "^7.0.3",
@@ -60,6 +68,7 @@
     "eslint-plugin-import": "^2.31.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-promise": "^7.2.1",
+    "express": "^4.21.2",
     "fastify": "^5.11.2",
     "globals": "^15.14.0",
     "husky": "^9.1.7",
@@ -140,6 +149,11 @@
       "types": "./dist/auth-permission/index.d.ts",
       "require": "./dist/auth-permission/index.js",
       "default": "./dist/auth-permission/index.js"
+    },
+    "./auth-permission/express": {
+      "types": "./dist/auth-permission/express/index.d.ts",
+      "require": "./dist/auth-permission/express/index.js",
+      "default": "./dist/auth-permission/express/index.js"
     }
   },
   "typesVersions": {
@@ -176,6 +190,9 @@
       ],
       "auth-permission": [
         "./dist/auth-permission/index.d.ts"
+      ],
+      "auth-permission/express": [
+        "./dist/auth-permission/express/index.d.ts"
       ]
     }
   }

src/auth-permission/api-key/check-api-key-permission.ts

@@ -1,24 +1,30 @@
-import type { FastifyRequest } from 'fastify';
+import type { BrokerContext } from '../broker-context';
 import type { PermissionValidationResult, PermissionValidator } from './permission-validator';
 import { PermissionDeniedError } from '../errors/permission-denied-error';
 import type { RouteProperties } from '../route-properties';
-import { readBrokerId, resolveBrokerContext } from '../shared/broker-scope-resolution';
+import { readBrokerId, resolveBrokerScope } from '../shared/broker-scope-resolution';
+import type { WaveRequest } from '../shared/wave-request';
 
 /**
  * Authenticates and authorizes an `x-api-key` credential against
  * wave-auth-api: reads the broker id header (if any), calls `validate`, and
- * resolves `request.brokerContext`. Shared by the route-map hook and by the
+ * resolves the broker scope. Shared by the route-map hook and by the
  * standalone `assertHasPermission` it returns, so the two never drift on
  * this part of the contract.
+ *
+ * Pure — returns the resolved `BrokerContext` (or `undefined` for a
+ * `brokerScoped: false` route) rather than assigning it onto `request`;
+ * each framework-specific orchestrator does that assignment onto its own
+ * native request object.
  */
 export async function checkApiKeyPermission(
-  request: FastifyRequest,
+  request: WaveRequest,
   route: RouteProperties,
   apiKey: string,
   validator: PermissionValidator,
   brokerIdHeader: string,
   brokerIdMaxLength: number,
-): Promise<void> {
+): Promise<BrokerContext | undefined> {
   const brokerId = route.brokerScoped === false
     ? undefined
     : readBrokerId(request, brokerIdHeader, brokerIdMaxLength);
@@ -35,7 +41,7 @@ export async function checkApiKeyPermission(
     throw new PermissionDeniedError(`The API key does not have the ${route.permissionName} permission`);
   }
 
-  resolveBrokerContext(
+  return resolveBrokerScope(
     request,
     route,
     result.brokers,

src/auth-permission/broker-context.ts

@@ -1,25 +1,27 @@
-import type { FastifyRequest } from 'fastify';
 import { BrokerContextNotResolvedError } from './errors/broker-context-not-resolved-error';
 
-/** The broker scope `registerPermissionAuth` resolved for the in-flight request. Never empty. */
+/**
+ * The broker scope `registerPermissionAuth`/`expressRegisterPermissionAuth`
+ * resolved for the in-flight request. Never empty.
+ */
 export interface BrokerContext {
   readonly scope: readonly string[];
 }
 
-declare module 'fastify' {
-  interface FastifyRequest {
-    /** Set by `registerPermissionAuth`'s hook. Absent on public paths. */
-    brokerContext?: BrokerContext;
-  }
-}
-
 /**
  * The broker scope resolved for this request. Every route this hook actually
  * protects gets one — a missing context here is a route-wiring defect
  * (e.g. this route bypasses the hook somehow), not something a caller
  * triggered, hence the `500` instead of a `4xx`.
+ *
+ * Framework-neutral by design: the actual `brokerContext?: BrokerContext`
+ * augmentation of the real request type lives next to each framework's own
+ * orchestrator (`fastify/to-wave-request.ts` for Fastify, `express/express-request.ts`
+ * for Express), never here — this file is on the shared export path, and an
+ * Express-only consumer resolving a `declare module 'fastify'` augmentation
+ * here would drag in an unresolvable `fastify` type import for no reason.
  */
-export function requireBrokerContext(request: FastifyRequest): BrokerContext {
+export function requireBrokerContext(request: { brokerContext?: BrokerContext }): BrokerContext {
   if (request.brokerContext === undefined) {
     throw new BrokerContextNotResolvedError();
   }