feat(auth): implement @fuzefront/auth — real verifier + middleware (#117)

[izzywdev]

Fixes #117. @fuzefront/auth was a stub. Every entry point threw VERIFIER_UNAVAILABLE; the authz guard literally responded:

"@fuzefront/auth is contract-frozen; authz guard runtime not yet implemented"

So the package consuming services are told to install gave them no way to verify a FuzeFront token or check a permission. Cross-service AuthN/AuthZ was a contract, not a capability. This makes it real — installable as middleware.

Public signatures are unchanged from the v0.1.0 freeze: code written against the frozen types keeps compiling, it now also runs.

Install & use

import { createVerifier, requireAuth, requireRoles } from '@fuzefront/auth'

const verifier = createVerifier({
  mode: 'legacy-hs256',
  secret: process.env.JWT_SECRET!,
  resolver: { async resolve(userId) { /* hydrate tenantId/roles */ } },
})

app.use('/api/private', requireAuth({ verifier }))         // 401 if not authenticated
app.get('/api/private/admin', requireRoles(['admin']), h)  // 403 if not permitted
app.get('/api/private/me', (req, res) => res.json(req.identity))

Migrating to federated JWKS later is a config change, not a code change — swap mode to federated-jwks with an issuer.

Runtime

One dependency — jose covers HS256 today and RS256/JWKS for the target, so consumers don't pull two crypto libs.

• legacy-hs256 — today's session token; optional OutOfBandResolver hydrates the tenantId/roles the token doesn't carry.
• federated-jwks — RS256/ES256 against the issuer's JWKS with iss/aud validation, OIDC discovery when jwksUri is omitted, JWKS cached per issuer.
• requireAuth / requireRoles / requireTenant — real Express middleware.

Security properties — deliberate, not incidental

• Algorithms are PINNED per mode. Unpinned algorithms is exactly what enables alg: none and RS256-public-key-abused-as-HMAC-secret confusion. Tested.
• tenantId: null means UNRESOLVED, never a wildcard. requireTenant denies. Treating null as "any tenant" would hand every tenant's data to any valid legacy token lacking a resolver.
• A resolver failure DENIES rather than returning empty roles — otherwise an outage is indistinguishable from a genuine permission decision, and gets misread as one.
• requireAuth never calls next() on an unauthenticated request; the promise is driven explicitly so a rejection denies rather than hanging the request.
• 401 (authn) vs 403 (authz) kept distinct so clients aren't sent into login loops over a permission problem.
• Still never mints tokens. In federated-jwks mode a consumer holds no signing key at all — it can verify without gaining the power to forge.

Tests — 31, weighted toward the denial paths

A false allow here is a family-wide breach; a false deny is an outage. So the happy path gets one test and the refusals get the rest: algorithm confusion, forged signature, expiry, wrong issuer, wrong audience, missing subject, resolver failure, unresolved tenant, and a guard mounted without requireAuth.

The package had no test config at all — its tsconfig is build-shaped (types: ["node"], include: src only), so tests/tsconfig.json + jest.config.js were prerequisites before a single test could run. The federated tests serve a real JWKS over loopback rather than stubbing fetch, because createRemoteJWKSet does its own fetching — that also exercises discovery for real.

Verified (clean node:20 container, actually run)

tsc --noEmit  → exit 0
jest          → Test Suites: 2 passed | Tests: 31 passed, 31 total

The type-checker caught a real gap mid-work: Identity requires authMode, which I'd missed — now populated per verifier, along with issuedAt/claims.

hold — master is deploy-on-push.

Co-Authored-By: Claude

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.

[github-actions]

Automated code review (gate-code-review)

Credit balance is too low

Report-only — this check never blocks merge.