[GabrielMachado11]

Summary

wave-usage-api (BFF/API/Accounts, all Express) and potentially other wave-*-api services can't use registerPermissionAuth as-is — it's Fastify-only. This ships the Express-compatible sibling, expressRegisterPermissionAuth, on a new @wave-tech/framework/auth-permission/express subpath, sharing the same underlying permission/session-token/broker-scope logic instead of duplicating it.

• Generalized shared layer: readApiKey/readBearerToken/readBrokerId/resolveBrokerScope (renamed from resolveBrokerContext), checkApiKeyPermission, authenticateWithSessionToken now operate on a minimal WaveRequest shape (headers, rawHeaders, query) instead of FastifyRequest. A real Express Request satisfies it natively; Fastify gets one small per-request adapter (to-wave-request.ts) since it nests rawHeaders under .raw.
• Pure functions, not mutation: checkApiKeyPermission/authenticateWithSessionToken now return the resolved BrokerContext (or undefined) instead of writing request.brokerContext directly. Each framework's own orchestrator assigns it onto its own native request — no observable behavior change for the existing Fastify hook, covered by the unmodified register-permission-auth.spec.ts suite.
• expressRegisterPermissionAuth: mirrors the Fastify hook's contract (public-path bypass, credential-before-routing, deny-by-default, brokerScoped/acceptsSessionToken support) with two documented, deliberate divergences:
  • publicPaths defaults to [], not Fastify's — this middleware is meant for a sub-router, where req.path is router-relative (GET /api arrives as /), so reusing Fastify's defaults would silently make a router's own root public.
  • An unmapped-but-real path answers 403, never a synthetic 404 — Express gives a .use()-mounted middleware no equivalent to Fastify's already-resolved route before real handlers run, and letting a miss fall through unauthenticated would defeat deny-by-default.
• Route resolution uses path-to-regexp against the same "METHOD path" map, matching in the map's own insertion order — mirroring Express's real first-registered-wins tie-break on overlapping patterns (a real, unavoidable overlap between two fixed paths already exists in wave-usage-api's own bff module: /accounts/by-external-code/:externalCode vs /accounts/:accountId/balances).
• Separate subpath (not the existing ./auth-permission barrel) specifically so an Express-only consumer never pulls in @fastify/rate-limit, which register-permission-auth.ts imports as a value. No rate-limiting option on the Express side — that's Fastify-only for now.
• express/@types/express move from a regular dependency/devDependency to an optional peer dependency (mirroring the existing fastify pattern), @types/express aligned to the 4.x line to match the actual express runtime version.

This is Part 1 of a two-part effort (see internal plan) — wiring this into wave-usage-api itself is a separate, later PR.

Test plan

• pnpm run lint
• pnpm test — 237/237 passing, including 16 new tests (express-register-permission-auth.spec.ts, route-matcher.spec.ts) and the existing register-permission-auth.spec.ts suite unchanged and still green after the pure-function refactor
• pnpm run build — confirmed dist/auth-permission/express/{index.js,index.d.ts} exist and that subpath's compiled output has zero require('fastify')/require('@fastify/rate-limit') in its dependency graph

🤖 Generated with Claude Code