docs(phase-08): add validation strategy and resolve research decisions

This commit is contained in:
Jakub Zych
2026-09-23 12:32:31 +02:00
parent a3a4636c29
commit 37fbcdc6de
3 changed files with 92 additions and 8 deletions

View File

@@ -2,7 +2,7 @@
**Researched:** 2026-09-23
**Domain:** OAuth 2.1-style authorization-code server, PKCE, dynamic registration, refresh rotation, and exact PHP/client wire parity
**Confidence:** HIGH for the PHP/client contract and RFC requirements; MEDIUM for the final end-to-end gate until the `/api/v1/fonoteka/me` scope conflict is resolved
**Confidence:** HIGH for the PHP/client contract, RFC requirements, and final end-to-end gate after the `/api/v1/fonoteka/me` scope decision was resolved
<user_constraints>
## User Constraints (from CONTEXT.md)
@@ -465,19 +465,19 @@ The locked source suite contains 103 named methods: 11 authorize, 8 client-comma
| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | Additive schema-correction `down` behavior may need to refuse when null lifecycle rows exist rather than destructively coercing them. | Required Schema Correction | Planner must choose a safe rollback contract; careless down migration can destroy pending/client data. |
| A2 | A small explicit `/register` request-body bound should be added despite raw-group exemption; exact byte value is not locked. | Threat map / Security | Without a decision, DCR rate/cap controls do not bound per-request memory; an arbitrary cap could diverge on oversized inputs no real client sends. |
| A2 | Resolved by CONTEXT D-21: `/register` has a 64 KiB request-body bound and oversized input returns `invalid_client_metadata`. | Threat map / Security | Closed by the user decision; plans must retain the exact bound and endpoint-native error contract. |
## Open Questions
## Resolved Planning Questions
1. **How is D-14's real MCP tool call reconciled with the Phase Boundary?**
1. **How is D-14's real MCP tool call reconciled with the Phase Boundary? — Resolved: add the prerequisite route.**
- What we know: `fonoteka-mcp` calls `/api/v1/fonoteka/me` before it constructs the MCP server; that route is absent from current Go routes and from the Phase 8 endpoint list. [VERIFIED: MCP source and Go routes]
- What's unclear: whether Phase 8 may port this one prerequisite route or D-14 should stop at token + direct bearer proof until the API phase. [VERIFIED: context conflict]
- Recommendation: add the minimal exact `/api/v1/fonoteka/me` personal-token route to Phase 8 as an explicitly approved prerequisite; this is the only choice that preserves the locked “real MCP tool call unchanged” acceptance. [ASSUMED]
- Decision: add the minimal exact `/api/v1/fonoteka/me` personal-token route to Phase 8 as an explicitly approved prerequisite; this preserves the locked “real MCP tool call unchanged” acceptance. [LOCKED: user decision 2026-09-23; CONTEXT D-20]
2. **What request-body limit should raw OAuth machine endpoints enforce?**
2. **What request-body limit should raw OAuth machine endpoints enforce? — Resolved: 64 KiB.**
- What we know: the raw group intentionally bypasses the house body-limit middleware; `ParseForm` has an internal 10 MB cap, but the JSON register decoder is otherwise unbounded. Valid registration data is limited to five 512-character redirect URIs plus small metadata. [VERIFIED: surf/raw behavior; CITED: https://go.dev/pkg/net/http/; VERIFIED: PHP validation]
- What's unclear: the desired explicit cap and error body for an oversized DCR document. [ASSUMED]
- Recommendation: configure a conservative `wristband` max request size (64 KiB is ample for the locked metadata shape) and return the endpoint's normal `invalid_client_metadata` response. [ASSUMED]
- Decision: configure a 64 KiB `wristband` maximum registration request size and return the endpoint's normal `invalid_client_metadata` response. [LOCKED: user decision 2026-09-23; CONTEXT D-21]
## Sources