stack/docs/scratchpads/FED-M3-05-list-verb.md

FED-M3-05 — Federation List Verb Scratchpad

Objective

Implement POST /api/federation/v1/list/:resource.

Scope

• Wire FederationAuthGuard → FederationScopeService → read-only list query layer.
• Apply max_rows_per_query row cap and return pagination metadata when truncated.
• Tag returned rows with _source: "local".
• Keep audit writes deferred to M4.
• No request/response body persistence.

Base / branch

• Branch: feat/federation-m3-verb-list
• Base: feat/federation-m3-scope-service (PR #672), per orchestrator, because M3-04 is not merged yet.
• Rebase target after #672 merges: main.

Implementation notes

• Added ListController under apps/gateway/src/federation/server/verbs/.
• Added FederationListQueryService as the read-only query layer and native RBAC evaluator.
• Query resources supported in M3 list path:
  • tasks: project/mission scoped tasks visible through personal/team project access.
  • notes: non-empty mission_tasks.notes rows visible through personal/team mission access.
  • memory: user-owned insights and preferences rows.
  • credentials / api_keys: denied by native RBAC in M3 even if present in scope; sensitive-resource implementation is not part of FED-M3-05.
• Cursor pagination uses an opaque base64url keyset cursor over (createdAt, id); DB reads fetch at most limit + 1 rows per resource query.

Tests

• pnpm --filter @mosaicstack/gateway test -- list.controller.spec.ts list-query.service.spec.ts — PASS (9 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 --filter @mosaicstack/gateway test — FAIL in pre-existing/live-DB integration suite: apps/gateway/src/__tests__/cross-user-isolation.test.ts cleanup cannot connect to local PostgreSQL on localhost:5433. New list tests pass; failure is outside FED-M3-05.

Review evidence

• ~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted — PASS after remediation; approve, no findings.
• ~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted — PASS after cursor remediation; risk level none, no findings.
• Security-review note: read-path audit logging remains intentionally deferred to M4 per orchestrator clarification and FED-M3-05 scope.

Risks / follow-up

• This branch intentionally includes M3-04 diff until PR #672 lands; final PR must be rebased onto main after #672 merges.
• Current branch base predates the M3-07 capabilities module registration; expect a small FederationModule rebase conflict once #672 and #674 are both on main.