docs(agent): audit analytics public id responses #149

Merged

pdurlej merged 1 commit from codex/analytics-public-id-response-audit into main

2026-06-03 21:31:31 +02:00

codex commented

2026-06-03 09:49:17 +02:00

Collaborator

Canary status: missing — fire 3+3 review before merge

Summary

Fixes #124 by adding a repo-tracked audit of analytics/read-model response shapes for internal database ID exposure.

Scope

Adds docs/audits/analytics-public-id-response-audit.md.
Checks these external read paths:
- getRecentActivity,
- getTransitionHistory,
- getFlowMetrics,
- getBoardFlowMetrics,
- MCP wrappers for recent activity, transition history, and flow metrics.
Documents that audited response contracts expose stable public IDs and aggregate counts, not raw internal id, cardId, listId, boardId, or workspaceId keys.
Records static search notes and a follow-up guardrail for future response-level tests.

Non-goals

No runtime/API behavior change.
No production deploy or restart.
No DB schema or migration.
No exhaustive audit of every Kan router/UI response.
No raw production data review.

Spec sources read

#124
AGENTS.md public ID rule
docs/agent-mcp-contract.md
packages/api/src/routers/agent.ts
packages/mcp/src/index.ts
packages/mcp/src/client.ts

Tests / smoke

Static code audit via rg "getRecentActivity|flow-metrics|flow-health|transition|activityPublicId|cardId|listId|workspaceId|boardId" packages/api/src/routers/agent.ts packages/api/integration-tests/agent.integration.test.ts packages/mcp/src/index.ts packages/mcp/src/client.ts.
pnpm exec prettier --check docs/audits/analytics-public-id-response-audit.md — passed.

Rollback

Revert fc626d0f. Docs-only; no data migration.

Owner gates

No production-impacting action taken. Merge decision remains with Piotr.

Canary status: missing — fire 3+3 review before merge ## Summary Fixes #124 by adding a repo-tracked audit of analytics/read-model response shapes for internal database ID exposure. ## Scope - Adds `docs/audits/analytics-public-id-response-audit.md`. - Checks these external read paths: - `getRecentActivity`, - `getTransitionHistory`, - `getFlowMetrics`, - `getBoardFlowMetrics`, - MCP wrappers for recent activity, transition history, and flow metrics. - Documents that audited response contracts expose stable public IDs and aggregate counts, not raw internal `id`, `cardId`, `listId`, `boardId`, or `workspaceId` keys. - Records static search notes and a follow-up guardrail for future response-level tests. ## Non-goals - No runtime/API behavior change. - No production deploy or restart. - No DB schema or migration. - No exhaustive audit of every Kan router/UI response. - No raw production data review. ## Spec sources read - #124 - `AGENTS.md` public ID rule - `docs/agent-mcp-contract.md` - `packages/api/src/routers/agent.ts` - `packages/mcp/src/index.ts` - `packages/mcp/src/client.ts` ## Tests / smoke - Static code audit via `rg "getRecentActivity|flow-metrics|flow-health|transition|activityPublicId|cardId|listId|workspaceId|boardId" packages/api/src/routers/agent.ts packages/api/integration-tests/agent.integration.test.ts packages/mcp/src/index.ts packages/mcp/src/client.ts`. - `pnpm exec prettier --check docs/audits/analytics-public-id-response-audit.md` — passed. ## Rollback Revert `fc626d0f`. Docs-only; no data migration. ## Owner gates No production-impacting action taken. Merge decision remains with Piotr.

Rows
Columns