stack/docs/scratchpads/462-fed-m3-04-scope-service.md

Scratchpad — FED-M3-04 Scope Service

Objective

Implement apps/gateway/src/federation/server/scope.service.ts for the M3 inbound federation scope-enforcement pipeline.

Scope / Constraints

• Task: FED-M3-04, issue #462.
• Branch: feat/federation-m3-scope-service from origin/main @ 0.0.48.
• Pure service: no direct DB access; native RBAC/data access is injected per evaluation call.
• Reuse parseFederationScope from M2-03.
• Workers do not edit docs/federation/TASKS.md per repo AGENTS.md.

Acceptance Criteria

1. Resource allowlist and excluded_resources enforced.
2. Native RBAC evaluated as subjectUserId through an injected evaluator.
3. Scope filter intersection supports include_teams and include_personal without widening native RBAC.
4. max_rows_per_query caps requested limits.
5. Service returns { allowed: true, filter } or a structured deny reason usable by M4 audit.
6. Unit tests cover every deny path.

Plan

1. Inspect existing federation scope/schema/auth guard contracts.
2. Add pure FederationScopeService plus typed result/filter/deny interfaces.
3. Add focused unit tests for happy paths, filter intersection, row cap, and deny paths.
4. Export/register service for future verb controllers.
5. Run situational tests, baseline gates, code review, then PR.

Budget

• Provided model tier: sonnet.
• Estimate from task row: 10K tokens.
• Working cap assumption: keep implementation focused to FED-M3-04 surfaces only.

Progress

• Intake complete; dirty base worktree avoided by creating isolated worktree at /home/jarvis/src/mosaic-mono-v1-fed-m3-04.
• Project PRD and federation task spec reviewed.
• Added FederationScopeService with structured allow/deny result types and injected native RBAC evaluator contract.
• Added unit coverage for happy path, row cap, filter intersection, and every deny path.
• Exported/registered the service for upcoming M3 verb controllers.

Verification Evidence

• pnpm --filter @mosaicstack/gateway test -- src/federation/server/__tests__/scope.service.spec.ts — pass (10 tests before review update; 11 tests after adding include_personal no-leak coverage).
• pnpm build — pass (23 successful tasks).
• pnpm typecheck — pass (41 successful tasks; re-run after review update).
• pnpm lint — pass (23 successful tasks; re-run after review update).
• pnpm format:check — pass (re-run after review update).
• pnpm test — pass after starting local postgres/valkey and running pnpm --filter @mosaicstack/db db:push for the DB-backed cross-user isolation suite (41 successful tasks; gateway 477 passed / 11 skipped).
• Code review: ~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted — approve, 0 findings.
• Security review: ~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted — risk none, 0 findings.

Risks / Blockers

• Issue #462 is already closed in provider output; likely milestone tracking mismatch. Will still reference #462 in PR body unless orchestrator redirects.
• Local full-test setup required docker compose up -d postgres valkey + db:push; containers were stopped with docker compose down after verification.