feat(authz): wrap Permit behind FuzeFront Security API for chat-service (#254)

[claude]

Summary

Closes the FuzeFront-repo side of #254 for one real, live consumer: chat-service no longer needs to call the Permit PDP directly to get the same authorization answer.

Key finding before writing any code: most of what #254 asks for — a FuzeFront-owned authorization API fronting Permit, a generated client, fail-closed semantics — already exists, delivered as part of the unified Security API (packages/security/openapi.yaml, backend/security/src/routes/authz.ts, published as @fuzefront/security-client v0.7.0, and consumed via @fuzefront/auth's createAuthzClient). config-service's src/middleware/authz.ts is already running this in production instead of an embedded Permit SDK. The contract's own "Delivery phasing" note says it plainly: "AuthN is delivered first…AuthZ is designed here in full and its consumer rollout is sequenced after AuthN." Rollout — not the API — was the open item.

So this PR is that rollout, for one concrete, currently-in-repo direct-Permit consumer, using the proven pattern rather than inventing a new one.

What changed

services/chat-service's agent-tool permission check (agent/executor.ts) called POST {PERMIT_PDP_URL}/allowed directly (agent/permit.ts) — exactly the "consumer product calls the PDP directly" leak #254 names. Added a flag-gated wrapped path:

• agent/securityApiPermitAdapter.ts — adapts @fuzefront/auth's createAuthzClient (AuthzClient) to the same check() shape PermitClient exposes. Fail-closed: no bearer token → deny (never guesses an identity); any AuthzError/transport failure → deny.
• agent/authzGateway.ts — the new dependency executor.ts takes instead of PermitClient directly. Selects direct (unchanged PDP call) vs wrapped (Security API) per the flag; fails closed to direct even if the flag lookup itself throws.
• agent/authzFlag.ts — fuzefront.authz.chat-agent-security-api, release flag, default OFF, registered in packages/feature-flags/flag-registry.yaml. Lazy-required @fuzefront/feature-flags, mirrors backend/security/src/utils/rootMembershipFlag.ts exactly (degrades to OFF if the package/provider is absent — never throws).
• agent/permit.ts — PermitCheck gains an optional token field (threads the caller's bearer token to whichever implementation needs it). PermitClient itself is byte-for-byte unchanged and stays live as the flag-OFF default — per the issue's explicit "keep the direct-PDP path working until the wrapped API is proven, so nothing regresses."
• executor.ts — forwards PendingExecution.token through the check; widened ToolExecutorDeps.permit to a small AuthzCheckable interface (structurally identical to the old Pick<PermitClient,'check'>, so the existing mock-based tests are untouched and still pass).
• config.ts + Helm (chat-service.yaml, values.yaml, values-prod.yaml) — SECURITY_SERVICE_URL (defaults to in-cluster fuzefront-security:3002, same convention config-service/provisioning-service already use) + the Unleash featureFlags env block, mirroring security.yaml's wiring exactly (renders nothing when unwired → safe in-code default).

Both flag states are tested (authzGateway.test.ts), including the "flag lookup itself throws" case falling back to OFF. The wrapped adapter is tested against both an injected AuthzClient (unit) and a real createAuthzClient + mocked fetch (proves the actual request shape: URL, Authorization: Bearer <token>, body). permit.test.ts and executor.test.ts are unchanged and still green.

Deferred, and why (not folded into this PR)

• services/billing-service's permit.service.ts calls the Permit cloud API (api.users.update/api.tenants.update) to sync ABAC attributes (plan_tier, plan_status) for policy evaluation. There is no equivalent operation in the frozen Security API contract (AuthzClient covers check/bulkCheck/grant/revoke/listGrants — role/permission assignment, not arbitrary subject-attribute writes). Wrapping this needs a new contract surface, which per the baseline's contract-first rule is contract-designer territory, not something to freehand here. Open question for the owner: should attribute-sync get a new PUT /authz/subjects/{id}/attributes-shaped endpoint on the Security API, or is ABAC attribute sync intentionally out of the Security API's scope (a different kind of "Permit fact" than an authorization decision or grant)?
• backend/src/config/permit.ts, backend/src/permit/*, backend/applications/src/app-registry/permit.ts — the pre-extraction monolith's own direct Permit usage. backend/security is clearly the intended replacement (it's live, deployed, and other services already consume it), but cutting the main backend's own request path over to calling its own extracted service is the actual backend→backend/security extraction — a large, separate, already-implied initiative, not a same-PR change I should make unreviewed.
• The companion MendysRobotics datasets-service migration is explicitly out of this repo per the issue itself (tracked in a companion MendysRobotics issue).

Verification

• npx tsc --noEmit (chat-service) — clean.
• npx jest (chat-service, full suite) — 27/27 suites, 153 passed / 2 pre-existing skipped, including the 4 new/changed suites (authzGateway, authzFlag, securityApiPermitAdapter, executor, permit).
• npm run build -w services/chat-service (real tsc build, not just --noEmit) — clean.
• helm lint deploy/helm/fuzefront -f values.yaml — clean.
• helm template … --output-dir for all three overlays (values.yaml, values-local.yaml, values-prod.yaml) with every optional workload enabled (mirrors helm-validate.yml's exact CI invocation) → piped through kubeconform -strict -kubernetes-version 1.29.0 -skip CustomResourceDefinition,Middleware,SealedSecret → 0 Invalid, 0 Errors on all three.
• Confirmed by rendered output: SECURITY_SERVICE_URL resolves to http://fuzefront-security:3002 in both base and prod values; the Unleash featureFlags block renders in prod (where securityService.enabled: true, so the wrapped path is reachable in-cluster once the flag flips) and correctly does not render on base values.yaml (empty unleashUrl default).
• packages/auth and packages/feature-flags built cleanly via tsup (scoped install, not a full monorepo install, per the disk-constraint instruction).

Gates

• gate-authz (semgrep .semgrep/fuze-authz.yml + OWASP/secrets packs): no new code matches any of the four seeded rules (no findById(req.params.x), no Object.assign(obj, req.body), no jwt.sign, no bcrypt.*).
• No OpenAPI contract touched — @fuzefront/auth's frozen authzTypes.ts contract is consumed as-is, not modified.
• services/chat-service's package.json bumped 1.1.0 → 1.2.0 (source changed) per gate-version's SemVer-bump check.

Open questions for the owner

1. Billing-service's Permit-cloud ABAC-attribute-sync gap above — new contract surface or intentionally out of scope?
2. Is chat-service's agent/executor.ts confirm/execute path meant to be wired into a live route soon? It currently isn't reachable from any route (index.ts never constructs a ToolExecutor) — pre-existing and unrelated to feat(authz): wrap Permit behind a FuzeFront authorization API (consumer products must not call the PDP/Permit cloud directly) #254, but it means this migration, while real and tested, has no live traffic yet to prove itself against in production before the flag flips. Worth knowing before treating "flip the flag" as low-risk in practice.
3. Should backend/src's (main backend, not backend/security) own direct Permit config be tracked as an explicit follow-up issue for the backend → backend/security extraction, separate from feat(authz): wrap Permit behind a FuzeFront authorization API (consumer products must not call the PDP/Permit cloud directly) #254?

🤖 Generated with Claude Code

https://claude.ai/code/session_013tMciHkPE8To7V67CsgKKc

---

Generated by Claude Code

[claude]

Pushed a fix for the CI/Docker build defect flagged on this PR (own-PR bug, not the unrelated config-service contract-conformance failure).

Root cause (three places, all required — none alone was sufficient):

1. package-lock.json — the root lockfile's services/chat-service entry never picked up @fuzefront/auth/@fuzefront/feature-flags as dependency edges after they were added to package.json (edited after the last npm install). npm ci is lockfile-only and silently skips a workspace whose lockfile entry is stale — which is exactly why local tsc/jest passed (ran via npm install, which re-resolves live) while CI's npm ci did not. Fixed by npm install -w services/chat-service; diff is 3 lines.
2. .github/workflows/ci.yml (chat-service-tests job) — @fuzefront/auth ships types from an uncommitted dist/ (tsup); added the same prebuild step this file already uses for @fuzefront/custom-hostname-client/@fuzefront/security-client. @fuzefront/feature-flags needs no such step — agent/authzFlag.ts only require()s it at runtime inside a try/catch, never a static import, so tsc never needs its types (confirmed by grep + by the fail-safe-OFF test case that exercises exactly the "package absent" branch).
3. services/chat-service/Dockerfile — build stage now copies + builds packages/auth and packages/feature-flags before chat-service (mirrors the existing packages/identity treatment). Production stage copies each package's package.json + dist, plus packages/auth/node_modules from the --omit=dev base stage (its runtime dep jose@^5.10.0 is NOT hoisted to /app/node_modules — root pins jose to 4.15.9 for other consumers — so it only exists nested; omitting it is the exact "builds green, pod dies at module load" bug already fixed for selection-list-service in fix(selection-list-service): ship packages/auth's jose into the prod image #817). Also copies packages/feature-flags/node_modules — even though this repo's current graph happens to hoist its runtime deps to root regardless — because scripts/check-dockerfile-lockfile.mjs (FFRNT-254) flags any dist-only copy of a file:-linked package with runtime deps unconditionally, on the correct theory that hoisting outcomes are exactly what this repo has been bitten by before.

Verified (no Docker daemon available), per #817's own approach:

• Reproduced the exact failure: removed packages/auth/dist, ran npm run -w @fuzefront/chat-service build → same TS2307.
• Ran the fix sequence: npm run -w @fuzefront/auth build then npm run -w @fuzefront/chat-service build → clean, error gone.
• Full npx jest for chat-service: 27/27 suites, 153 passed / 2 pre-existing skipped.
• Replicated the Dockerfile's manifest COPY list into a scratch dir; ran the identical npm ci --workspace=services/chat-service (both --omit=dev and full) against the real committed lockfile, ran the identical per-package build commands, assembled a "production" directory from exactly the COPY list's source/destination pairs, then had Node itself require.resolve and actually require() the built adapter/flag modules — proving real module load, not just path resolution. Confirmed jose resolves from packages/auth/node_modules.
• node scripts/check-dockerfile-lockfile.mjs → OK (15 Dockerfile(s)).

Remote HEAD 976ac747 matches local. NOT independently verified: an actual docker build (no Docker daemon in this sandbox) and the live CI run itself — the above is the closest reproduction achievable outside Docker/CI, per the same constraint and method #817 used.

---

Generated by Claude Code

[claude]

shipped code matches the frozen contract is failing, and it is not this PR's.

::error title=config-service MISSING::GET /v1/config/history is declared in
  services/config-service/openapi.yaml but no route implements it.
::error title=config-service MISSING::POST /v1/config/secrets/reveal is declared in
  services/config-service/openapi.yaml but no route implements it.
config-service: spec=9 code=7 -> 2 finding(s)

Verified rather than assumed: python3 scripts/gate_openapi_conformance.py --repo . on a
pristine master checkout — none of this PR's diff present — reproduces both findings
identically. config-service ships an openapi.yaml declaring two endpoints it does not
implement, so any client generated from that contract 404s. Pre-existing on the base branch;
this PR does not touch services/config-service/.

The fix exists: #840 implements both endpoints (config-read.routes.ts gains
GET /v1/config/history behind a new history.repository.ts + migration 004, and
secrets.write.ts adds POST /v1/config/secrets/reveal). I have read it and it clears
exactly these two findings.

Not ported into this PR, deliberately. The protocol says to port an existing fix rather
than wait — but #840 is a 25-file, ~2,000-line feature implementation including a new SQL
migration. Carrying it here would not "no-op once the base catches up"; it would put two
copies of a migration and a repository layer into conflict and widen this PR into something
nobody reviewed it as. This is the narrow case where waiting on the base is correct: #840 is
at the front of the merge queue for precisely this reason, and this PR goes green on its
first resync afterwards with no change of its own.

No re-run spent — a re-run cannot fix a deterministic contract gap.

---

Generated by Claude Code