docs(phase-08): add validation strategy and resolve research decisions
This commit is contained in:
Jakub Zych
@@ -0,0 +1,82 @@
|
||||
---
|
||||
phase: 08
|
||||
slug: oauth2-1-authorization-server
|
||||
status: draft
|
||||
nyquist_compliant: false
|
||||
wave_0_complete: false
|
||||
created: 2026-09-23
|
||||
---
|
||||
|
||||
# Phase 08 — Validation Strategy
|
||||
|
||||
> Per-phase validation contract for feedback sampling during execution.
|
||||
|
||||
---
|
||||
|
||||
## Test Infrastructure
|
||||
|
||||
| Property | Value |
|
||||
|----------|-------|
|
||||
| **Framework** | Go 1.27 `testing`; existing testcontainers-backed Postgres harness; Node.js 22 plus the unchanged `fonoteka-mcp` only for end-to-end gates |
|
||||
| **Config file** | Existing `go.work`, repository package tests, `../fonoteka.go/plugins/golem15/fonoteka/classes/TestMain`, and planned `scripts/check-phase8.sh` |
|
||||
| **Quick run command** | `go test ./wristband -count=1` |
|
||||
| **App-focused command** | `cd ../fonoteka.go && go test ./plugins/golem15/fonoteka/... -run 'TestOAuth|TestMe' -count=1` |
|
||||
| **Full suite command** | `scripts/check-phase8.sh` |
|
||||
| **Estimated runtime** | Quick package checks under 30 seconds; full two-repository parity/race/e2e gate may take several minutes |
|
||||
|
||||
---
|
||||
|
||||
## Sampling Rate
|
||||
|
||||
- **After every task commit:** Run the narrowest affected package test; `go test ./wristband -count=1` is the default framework check.
|
||||
- **After every plan wave:** Run `go vet ./...` and `go test ./...` in each affected repository; storage waves also run focused real-Postgres tests.
|
||||
- **Before `$gsd-verify-work`:** `scripts/check-phase8.sh` must pass, including both repositories' vet/test/race suites, parity corpus audit, secret scan, security review, and unchanged real-MCP lifecycle.
|
||||
- **Max feedback latency:** 30 seconds for task-level sampling; slow Postgres, race, parity, and real-MCP gates run at wave/phase boundaries.
|
||||
|
||||
---
|
||||
|
||||
## Per-Task Verification Map
|
||||
|
||||
| Task ID | Plan | Wave | Requirement | Threat Ref | Secure Behavior | Test Type | Automated Command | File Exists | Status |
|
||||
|---------|------|------|-------------|------------|-----------------|-----------|-------------------|-------------|--------|
|
||||
| 08-W0-01 | TBD | 0 | AUTH-05 | T-08-PKCE / T-08-CODE-REPLAY | Metadata, authorize, PKCE S256, code exchange, refresh, DCR, and ordered redirects have deterministic framework tests | unit | `go test ./wristband -run 'Test(Metadata|Authorize|Token|Register|PKCE|Refresh)' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 08-W0-02 | TBD | 0 | AUTH-05, AUTH-07 | T-08-CODE-REPLAY / T-08-REFRESH-REPLAY | Nullability, row locks, single-use codes, committed lineage kill, sweeps, and indexes work on real Postgres | integration | `cd ../fonoteka.go && go test ./plugins/golem15/fonoteka/classes/... -run 'TestOAuth' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 08-W0-03 | TBD | 0 | AUTH-06 | T-08-DCR-FLOOD / T-08-SURFACE | Raw routing, parser rules, rate limits, 64 KiB DCR bound, exact bare bodies, and headers remain isolated from house middleware | route/integration | `cd ../fonoteka.go && go test ./plugins/golem15/fonoteka/... -run 'TestOAuth' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 08-W0-04 | TBD | 0 | AUTH-07 | T-08-SCOPE-CEILING / T-08-CROSS-USER | Consent, active-collection binding, connected-app ownership, list, and revoke semantics match PHP | Postgres integration | `cd ../fonoteka.go && go test ./plugins/golem15/fonoteka/controllers/... -run 'TestOAuth' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 08-W0-05 | TBD | 0 | AUTH-05, AUTH-06, AUTH-07 | T-08-REQUEST-LEAK / T-08-SURFACE | Nine manifest routes plus `mcp-lifecycle` replay exactly and every one of 103 PHP OAuth/security methods maps to a named Go test | parity/corpus | `cd ../fonoteka.go && go test ./parity -run 'TestOAuthFlows|TestParityCorpus' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 08-W0-06 | TBD | 0 | AUTH-07 | T-08-SURFACE | Minimal authenticated `/api/v1/fonoteka/me` lets the unchanged MCP process initialize without expanding the profile API surface | integration/e2e | `cd ../fonoteka.go && go test ./plugins/golem15/fonoteka/... -run 'TestMe|TestTokenSurface' -count=1` | ❌ W0 | ⬜ pending |
|
||||
| 08-W0-07 | TBD | 0 | AUTH-05, AUTH-07 | All T-08 threats | Real SDK discovery, DCR, PKCE, JWT consent, token, MCP tool call, refresh/replay, connected-app revoke, and post-revoke failure complete unchanged | e2e | `scripts/check-phase8.sh` | ❌ W0 | ⬜ pending |
|
||||
|
||||
*Status: ⬜ pending · ✅ green · ❌ red · ⚠️ flaky*
|
||||
|
||||
---
|
||||
|
||||
## Wave 0 Requirements
|
||||
|
||||
- [ ] `wristband/*_test.go` — metadata, authorize, token, DCR, PKCE, refresh/replay, deterministic clock/random, ordered RFC3986 encoding, and 64 KiB body-bound tests.
|
||||
- [ ] `../fonoteka.go/plugins/golem15/fonoteka/updates/*oauth*_test.go` — additive nullability/index correction with safe up/down behavior.
|
||||
- [ ] `../fonoteka.go/plugins/golem15/fonoteka/classes/auth/oauth_store_test.go` — real-Postgres transaction, row-lock, concurrent single-use, sweep, and lineage tests.
|
||||
- [ ] `../fonoteka.go/plugins/golem15/fonoteka/controllers/api/*oauth*_test.go` — exact raw/JWT endpoint bodies, headers, status codes, consent ownership, and connected-app behavior.
|
||||
- [ ] `../fonoteka.go/plugins/golem15/fonoteka/controllers/api/*me*_test.go` — minimal `inv_token`-authenticated MCP bootstrap contract.
|
||||
- [ ] `../fonoteka.go/parity/oauth_flow_test.go` and `mcp-lifecycle` fixture — projected existing flows and clean lifecycle/replay coverage.
|
||||
- [ ] `scripts/check-phase8.sh` — two-repository vet/test/race, corpus, secret, security-review, and real-MCP gate.
|
||||
- [ ] `08-SECURITY-REVIEW.md` — map every `T-08-*` threat to a failing-when-broken test and close all high-severity threats.
|
||||
|
||||
---
|
||||
|
||||
## Manual-Only Verifications
|
||||
|
||||
All phase behaviors are automated. Live Claude, ChatGPT, and Grok connections are explicitly deferred to cutover UAT; they are not Phase 8 acceptance checks.
|
||||
|
||||
---
|
||||
|
||||
## Validation Sign-Off
|
||||
|
||||
- [ ] All final plan tasks have an automated command or an explicit Wave 0 dependency.
|
||||
- [ ] Sampling continuity: no three consecutive implementation tasks lack automated verification.
|
||||
- [ ] Wave 0 covers every currently missing test/gate reference above.
|
||||
- [ ] No watch-mode flags appear in validation commands.
|
||||
- [ ] Task-level feedback remains under 30 seconds; slow suites are assigned to wave/phase gates.
|
||||
- [ ] `nyquist_compliant: true` is set after task IDs are finalized and every mapping is implemented.
|
||||
|
||||
**Approval:** pending plan verification
|
||||
Reference in New Issue
Block a user