66 lines
4.1 KiB
Markdown
66 lines
4.1 KiB
Markdown
# FED-M3-07 — Capabilities Verb Scratchpad
|
||
|
||
## Objective
|
||
|
||
Implement `GET /api/federation/v1/capabilities` in `apps/gateway/src/federation/server/verbs/capabilities.controller.ts`.
|
||
|
||
## Scope
|
||
|
||
- Add read-only capabilities controller under federation server verbs.
|
||
- Use `FederationAuthGuard` only; active grant is sufficient and no native RBAC/scope-service eval runs.
|
||
- Response shape: `{ resources, excluded_resources, max_rows_per_query, supported_verbs }` derived from grant scope.
|
||
- Register controller in `FederationModule`.
|
||
- Unit-test happy path, defaults, no-context guard seam, and invalid scope handling.
|
||
|
||
## Constraints / assumptions
|
||
|
||
- Issue: #462.
|
||
- Branch: `feat/federation-m3-verb-capabilities` from `origin/main` (`3eeed04e`).
|
||
- Depends on M3-03 auth guard; guard attaches `request.federationContext.scope` after active-grant validation.
|
||
- ASSUMPTION: `supported_verbs` is the M3 verb set from `@mosaicstack/types` (`list`, `get`, `capabilities`).
|
||
- ASSUMPTION: `filters`/`rate_limit` are intentionally omitted for FED-M3-07 because the card’s response shape lists only the four required fields.
|
||
- Budget: no explicit hard cap from orchestrator; working cap ~4K-8K tokens for card implementation + tests + PR cycle.
|
||
|
||
## Plan
|
||
|
||
1. Write controller unit tests first.
|
||
2. Implement controller and module registration.
|
||
3. Run scoped tests + typecheck/lint/format.
|
||
4. Run Codex code/security review and remediate.
|
||
5. Commit, queue guard, push, PR via wrapper.
|
||
|
||
## Progress
|
||
|
||
- 2026-06-24: Intake complete; fresh worktree created from origin/main.
|
||
- 2026-06-24: Added `CapabilitiesController`, registered it in `FederationModule`, and added 5 unit tests.
|
||
- 2026-06-24: Code/security reviews passed with no findings.
|
||
|
||
## Tests run
|
||
|
||
- `pnpm --filter @mosaicstack/gateway test -- capabilities.controller.spec.ts` — PASS (5 tests).
|
||
- `pnpm --filter @mosaicstack/gateway typecheck` — PASS.
|
||
- `pnpm --filter @mosaicstack/gateway lint` — PASS.
|
||
- `pnpm format:check` — PASS.
|
||
- `pnpm typecheck` — PASS (41/41 turbo tasks).
|
||
- `pnpm lint` — PASS (23/23 turbo tasks).
|
||
- `pnpm test` — FAIL in pre-existing/live-DB integration suite: `apps/gateway/src/__tests__/cross-user-isolation.test.ts` cleanup hit PostgreSQL connection/schema state for the `messages` table. Changed capabilities tests passed; failure is outside FED-M3-07 surface. No `fleet-personas.spec` flake encountered.
|
||
|
||
## Review evidence
|
||
|
||
- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — PASS/approve, no findings.
|
||
- `~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted` — PASS, risk level none, no findings.
|
||
|
||
## Risks / blockers
|
||
|
||
- Full repo `pnpm test` may hit known `fleet-personas.spec` flake per orchestrator; ignore that specific flake if encountered.
|
||
- Previous card saw local DB schema issue in `cross-user-isolation.test.ts`; scoped capabilities tests should be authoritative for this surface.
|
||
|
||
## Acceptance evidence mapping
|
||
|
||
| Acceptance criterion | Evidence |
|
||
| -------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
||
| GET `/api/federation/v1/capabilities` exists | Route metadata test in `capabilities.controller.spec.ts`; scoped test PASS |
|
||
| Uses active-grant auth guard and no RBAC eval | Guard metadata test confirms only `FederationAuthGuard`; controller has no service injections/RBAC calls; scoped test PASS |
|
||
| Response enumerates resources/excluded/max rows/supported verbs from scope | Happy-path/default scope tests + response schema parse; scoped test PASS |
|
||
| Read-only/no persistence side effects | Controller only parses request `federationContext.scope` and returns a DTO; no DB/service dependency; code review PASS |
|