feat(agent-bff): serve the permissions display endpoint

[Tonours]

fixes PRD-683

Stacked on #1802 — base is feature/prd-682-..., not main. Review and merge #1802 first.

What

GET /agent/v1/permissions?collections=a,b returns, per collection, the CRUD booleans and the per-action visibility and approval hints for the calling user.

Display hints only. It never grants access — the agent stays the authority, and finality: "display_hint" says so on every action entry. Zendesk currently gets this from probeAccessibleActions, a fail-open fan-out that probes actions one by one; this replaces it with one call.

Decisions

?collections= is optional. Absent means every exposed collection. Requiring it would force the caller to fetch the schema first just to build the list.

No new HTTP client. ForestHttpApi.getEnvironmentPermissions() and .getUsers() were already public, forest-secret-key included.

The cache clears on schema refresh, via ReadModelStore.registerGenerationScopedCache(). Without it, hints could name an action the schema just dropped, for up to 15 minutes.

Fail-closed

Situation	Response
No caller identity	401 unauthorized
Caller absent from /permissions/users	403 forest_identity_not_allowed
SaaS fails, fresh cache entry	200 from cache
SaaS fails, no fresh entry	503 permissions_unavailable + Retry-After

An expired entry is never served. A missing CRUD descriptor or action-event flag is false.

Scope

Untouched: data endpoints, action endpoints, the agent, the OAuth flow, forestadmin-client. No SaaS or DB write, cache in-memory per process. roleId and raw role arrays never reach the response.

Two additive changes outside src/permissions/:

• BffHttpError gets an optional trailing retryAfter. error-middleware.ts already read it, nothing could set it.
• ReadModel.getAllowedCollections() returns a fresh copy per call.

Cache is capped at 1000 entries, oldest evicted first: the key includes the collection set, so a caller can mint many keys by varying ?collections=.

How to test

yarn workspace @forestadmin/agent-bff test
yarn workspace @forestadmin/agent-bff lint

777 tests, 100% coverage on the new files. Manually verified against a live SaaS in normal mode: 401 unauthenticated, 403 unknown caller, fallback to all collections, unknown collection omitted, cache hit, 503 + Retry-After with the SaaS down and no cached entry, 200 from cache with the SaaS down and a fresh one.

Dev mode (roles disabled) is covered by unit tests only — the QA environment runs in normal mode.

Definition of Done

General

• Write an explicit title for the Pull Request, following Conventional Commits specification
• Test manually the implemented changes
• Validate the code quality (indentation, syntax, style, simplicity, readability)

Security

• Consider the security impact of the changes made

[linear-code]

PRD-683

[qltysh]

4 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 5): constructor	2
qlty	Structure	Function with high complexity (count = 11): createPermissionsRoutesMiddleware	2

[qltysh]

Coverage Impact

This PR will not change total coverage.

Modified Files with Diff Coverage (9)

Rating	File	% Diff	Uncovered Line #s
	packages/agent-bff/src/http/bff-http-error.ts	100.0%
	packages/agent-bff/src/read-model/read-model.ts	100.0%
	packages/agent-bff/src/cli-core.ts	100.0%
	packages/agent-bff/src/read-model/read-model-store.ts	100.0%
	packages/agent-bff/src/http/bff-local-errors.ts	100.0%
	packages/agent-bff/src/permissions/permissions-client.ts	100.0%
	...ges/agent-bff/src/permissions/permissions-routes-middleware.ts	100.0%
	packages/agent-bff/src/permissions/permissions-cache.ts	100.0%
	packages/agent-bff/src/permissions/build-permission-hints.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.