diff --git a/docs/authentication/.review/implementation-plan.md b/docs/authentication/.review/implementation-plan.md index 5867c61..e61fac7 100644 --- a/docs/authentication/.review/implementation-plan.md +++ b/docs/authentication/.review/implementation-plan.md @@ -3,19 +3,19 @@ artifact: swe-design-review-attestation schema_version: 5 scope_key: c2ebaf06c49668e199e08bccef68303c5cd0925e79b8f635860bb8fa8494d61b scope: {"kind": "path", "primary_target": "docs/authentication/implementation-plan.md", "repository": ".", "selector": "docs/authentication/implementation-plan.md"} -review_content_identity_sha256: 81a890d11ab505cc9c5b7fae80c652da869ce224b7b80ace73bb73dd430a767b -target_content_identity_sha256: 6521d7d1f0a3315b5973ba93866ca2929e625f9df7535ad1393154102c548224 +review_content_identity_sha256: bc445c81f584d3d0a83d7826fb052aa4e943d26a4d627fd7d7a32b2bb0b8e711 +target_content_identity_sha256: a9d3c2a74376b48f8af8fc97c2e7c18069b97e5e9b209ce3658fcff8bf8083b1 baseline_content_identity_sha256: ad1ec634421f4d4b16b5cb61c07844e945fa11d0737e7e59757b3b3aabbf21ce -target_documents: [{"executable": false, "path": "docs/authentication/implementation-plan.md", "repository": ".", "sha256": "2bf706ba336f4560a5a40409e0928cc9cd9cb91bc00934045bd79313f66c95de"}] +target_documents: [{"executable": false, "path": "docs/authentication/implementation-plan.md", "repository": ".", "sha256": "c576091af919c3ec99f0e0edb5795cf4e7bd37a44415ae24742393822317ad3d"}] baseline_documents: [{"executable": false, "path": "docs/authentication/high-level-design.md", "repository": ".", "sha256": "b6511414b3a9b485542df83c8f7abfc499dc8d06e522819b48e162a562d21c57"}, {"executable": false, "path": "docs/authentication/requirements.md", "repository": ".", "sha256": "d56e92a7cb01f131ba499650c4a5d7b2c8d17adf2cdc7d612eee7c5f53d07929"}] design_dependency_documents: [{"executable": false, "path": "docs/authentication/high-level-design.md", "repository": ".", "sha256": "b6511414b3a9b485542df83c8f7abfc499dc8d06e522819b48e162a562d21c57"}, {"executable": false, "path": "docs/authentication/requirements.md", "repository": ".", "sha256": "d56e92a7cb01f131ba499650c4a5d7b2c8d17adf2cdc7d612eee7c5f53d07929"}] -plan_binding: {"base_revision": "94994fafe8c568f608387fbecf2a32bd37fbc645", "documents": [{"executable": false, "path": "docs/authentication/implementation-plan.md", "plan_key": "arbiter-authentication", "sha256": "2bf706ba336f4560a5a40409e0928cc9cd9cb91bc00934045bd79313f66c95de", "slice_convention": "hierarchical-v1"}], "predecessors": []} +plan_binding: {"base_revision": "0aa1b60a3c13a713e4e27c0645b0763c3d2fc6a1", "documents": [{"executable": false, "path": "docs/authentication/implementation-plan.md", "plan_key": "arbiter-authentication", "sha256": "c576091af919c3ec99f0e0edb5795cf4e7bd37a44415ae24742393822317ad3d", "slice_convention": "hierarchical-v1"}], "predecessors": []} document_repository: "." document_path: "docs/authentication/implementation-plan.md" -document_revision_provenance: "94994fafe8c568f608387fbecf2a32bd37fbc645" -document_sha256: 2bf706ba336f4560a5a40409e0928cc9cd9cb91bc00934045bd79313f66c95de +document_revision_provenance: "0aa1b60a3c13a713e4e27c0645b0763c3d2fc6a1" +document_sha256: c576091af919c3ec99f0e0edb5795cf4e7bd37a44415ae24742393822317ad3d verdict: clean -attested_at: 2026-10-19T20:29:54Z +attested_at: 2026-10-20T06:27:44Z --- diff --git a/docs/authentication/README.md b/docs/authentication/README.md index cd5ee09..1134f53 100644 --- a/docs/authentication/README.md +++ b/docs/authentication/README.md @@ -2,20 +2,20 @@ Start with the [requirements baseline](requirements.md), then the [high-level design](high-level-design.md), followed by the -[implementation plan](implementation-plan.md). All three passed actual DBB and +[implementation plan](implementation-plan.md). All three passed DBB and their respective SWE reviews. Their [requirements stamp](.review/requirements.md), [HLD stamp](.review/high-level-design.md) and [plan stamp](.review/implementation-plan.md) bind exact bytes and the appropriate requirements/HLD dependencies. The delivery sequence is requirements, high-level design, then an implementation plan with slices. Each stage -is reviewed and stamped at its own level, with actual DBB review of the final +is reviewed and stamped at its own level, with DBB review of the final document bytes before stamping. The [earlier synthesis](design.md) and [candidate security contracts](security-contracts.md) retain the mechanisms already assessed by DBB as historical inputs to the HLD. They are not a completed high-level design or additional binding requirements. -The interview is closed. Actual DBB resolved findings 1–5 at design level; +The interview is closed. DBB resolved findings 1–5 at design level; finding 6 uses the owner's accepted restore/migration procedure for cooperative servers. Protocol, implementation and release readiness are not established. The B1–B5 groups supplied the HLD agenda; their implementation evidence remains @@ -31,8 +31,9 @@ by these documents. The [requirements DBB report](reviews/requirements-dbb.md) gives the current requirements-level verdict; the [HLD DBB report](reviews/hld-dbb.md) gives the exact-byte HLD pass. Earlier reports concern candidate architecture. - The [plan DBB report](reviews/plan-dbb.md) records two plan gaps, their repair - and the exact-byte round-two pass. + The [initial plan review](reviews/plan-dbb.md) records the safe artifact-prefix + and certificate-renewal repairs. The [plan sizing review](reviews/plan-sizing-dbb.md) + covers the current child-PR estimates and repaired activation/denial order. - [Original draft and interview](../archive/authentication-and-enrollment/README.md): immutable historical evidence, not required reading or instructions to resume questioning. @@ -41,10 +42,14 @@ The HLD covers B1–B5 and shared boundaries. Fourteen local Python/Go feasibili checks passed; platform, production dependency, race and crash validation remain implementation obligations. No product authentication is implemented by this work. -The plan defines eleven PRs under stable identity `arbiter-authentication`, with -per-slice acceptance, integration and review gates. Actual DBB required explicit -safe artifact-prefix tests and certificate-renewal ownership; both are now in -the stamped plan. These are plan corrections, not implemented security fixes. - -Next, with separate authorization: slice 1, operator authority setup and local -control. No implementation slice or PR has started. +The plan retains eleven milestones under stable identity `arbiter-authentication`, +split into sixty planned PRs with separate production/test estimates and confidence. +Target about 600 changed handwritten code lines per PR; the hard maximum is 1,000, +including tests. Estimates remain uncertain and can require further splits. +DBB required receipt recovery before activation and complete live denial before +ordinary API cutover; the reviewed order now enforces both. Earlier artifact-prefix +and renewal obligations remain. These are plan corrections, not implemented fixes. + +Next, with separate authorization: child PR 1.1, private authority initialization, +within milestone 1 (operator authority setup and authenticated local control). +No implementation slice or PR has started. diff --git a/docs/authentication/implementation-plan.md b/docs/authentication/implementation-plan.md index d7cbaba..0f30709 100644 --- a/docs/authentication/implementation-plan.md +++ b/docs/authentication/implementation-plan.md @@ -13,7 +13,7 @@ and [HLD](high-level-design.md), SHA-256 Their exact reviewed stamps are required dependencies of this plan's stamp. Neither governing document changes in this stage. This plan authorizes no implementation, release, live-account operation or deployment by itself. -Actual DBB must approve the exact final plan before its SWE design stamp. +DBB must approve the exact final plan before its SWE design stamp. ## Delivery identities and rules @@ -25,14 +25,52 @@ aggregate acceptance obligation. A future execution ledger records exact PR URL, revision, dependencies, checks, reviews and state for each canonical identity; there are no PRs, code changes or completed implementation slices yet. -Each numbered slice is one intended PR with one observable behavior, its own -negative/failure tests, documentation and applicable package fragments. Work -serially in the table order. Complete local review, checks, submission and the -approved remote review cycle for the current PR before advancing; approval binds +The eleven numbered slices are milestones, not individual PRs. Their child +identities below are the intended reviewable PRs, each with its own bounded +behavior, negative/failure tests, documentation and applicable fragments. Work +serially in milestone order and then the listed child order (not numeric sort). Complete local review, checks, +submission and the approved remote review cycle for the current PR before advancing; approval binds the final PR head, with restacking invalidating affected evidence as appropriate. This document does not launch those cycles. If a slice becomes too large to review, split it under its identity before implementation rather than hiding -another feature or introducing a scaffolding-only PR. +another feature. A foundation PR must implement a real consumed boundary +(setup/status, registered pending work or an executable protocol peer), not empty +interfaces, permissive stubs or a throwaway intermediate protocol. A synthetic +peer may exercise a not-yet-public transport; it cannot authorize product traffic. +Until child 2.6, the live server has no reachable enrollment activation/ready-commit +route: 2.7/2.8 may use synthetic already-activated fixture rows only in tests, never +a production trust initializer. Until child 3.5, ordinary public server dispatch +remains closed on the new native boundary. Child 3.6 installs and tests complete +live denial first through the prepared inner handlers and real synthetic sockets. +The eventual cutovers cannot rely on development-only publication policy as their +safety mechanism; the respective runtime routes must actually remain closed. + +Every implementation and review-fix commit subject, and its PR title, starts with +the short slice label in brackets. For example: +`[authentication/1.1] Private authority initialization`. The repository already +identifies Arbiter; do not repeat its name in the title prefix. This display label +maps to canonical ledger identity `arbiter-authentication/1.1`; the plan key and +tracking identities remain unchanged. Use the deeper child ID after an approved +further split, and preserve the label through restacks and corrections. A title or +PR number does not replace the execution-ledger identity. This does not rename +historical commits. + +### Milestone stacks and merge boundary + +Deliver one connected PR stack per milestone. Review and approve its child PRs +serially as described above, retaining the stack until the milestone is complete. +Before merging, require current approval and required checks for every final PR +head, the parent milestone's full acceptance and integration checks, and relevant +integration with completed milestones. Reconcile approval/check evidence after +any correction or restack. Safe intermediate behavior remains mandatory. + +Present the verified milestone stack for operator-authorized merge, bottom-up. +Do not merge automatically. Verify the resulting main-branch state before basing +the next milestone on it; do not carry the previous milestone's unmerged stack +into the next one. A delivery request may stop with the approved stack ready for +the operator to merge. Merging is separate from publishing authentication support: +all eleven milestones and the combined publication gate remain required. No +milestone merge authorizes a package release, deployment or live-account operation. Use existing towncrier release surfaces: `server/news/` for core/native-client integration behavior, `plugins/imap/news/` or `plugins/smtp/news/` for changed plugin @@ -52,11 +90,16 @@ in slice 3, anonymous legacy operation/artifact paths stay closed; an incomplete artifact path must fail safely rather than emit an ownerless/plaintext substitute. Missing authority state fails closed and directs the operator to trusted setup. -## Ordered PR queue +## Ordered milestone queue Dependencies below are direct semantic prerequisites. Serial delivery additionally requires the preceding PR to finish its review cycle. Final integration covers -every combination, not just each slice in isolation. +cross-milestone interactions, not just each milestone in isolation. The listed child order is authoritative: milestone 2 runs 2.1–2.5, 2.7, 2.8, +2.6, 2.9; milestone 3 runs 3.1–3.4, 3.6, 3.5, 3.7. These orders preserve child +identities while repairing the reviewed cutover order. The explicit +child dependencies below are technical prerequisites; serial delivery also +requires the preceding child PR to finish its review cycle. An external dependency +on a milestone means all of that milestone's children, not just its first PR. | Slice | Observable result | Direct dependencies | Governing coverage | | --- | --- | --- | --- | @@ -72,6 +115,99 @@ every combination, not just each slice in isolation. | 10 | Operator restores offline and can undo the latest restore, including after use. | 4, 5, 6, 9 | R23–R24; HLD B5 | | 11 | Operator migrates paired clients during maintenance with verified URL handoff. | 3, 4, 6, 9, 10 | R10, R14, R17, R25; HLD B5 | +## PR sizing and estimation basis + +The current breakdown contains **60 planned PRs** across eleven milestones. +This count follows the boundaries below; it is not a delivery quota or a measured +implementation size. The earlier 30–45 PR conversation estimate was preliminary. +All children are unstarted. Preserve parent identities and aggregate acceptance; +if a child later needs splitting, use `2.7.1`, `2.7.2`, etc., without renumbering +other work. The execution ledger must retain the parent closure obligation. + +Target **about 600 changed handwritten code lines** per PR. The **hard maximum is +1,000**, counting additions plus deletions in production code, tests and handwritten +fixtures across Python and Go combined. This is not 1,000 per language or per +category. Count moved/reformatted code too; avoid incidental cleanup. Do not drop +negative tests, move a PR's tests into a later PR, compress code, label handwritten +fixtures generated or weaken a boundary to fit. Estimate and report documentation, +generated fixtures/code, lockfiles and tooling output separately in the PR; they +still contribute review burden. Do not introduce new generation tooling merely to +avoid the limit. A large mechanical change should be a separate coherent PR. + +The target is flexible; the maximum is not. Before coding each child, check its +forecast against the inspected implementation and predecessor changes. If it +cannot fit, split it before proceeding. If actual changes approach/exceed 1,000, +stop expansion and split before submission. A changed split needs focused review +and updated dependency/acceptance mapping; changes to the stamped plan require +DBB/SWE re-review and replacement stamp before treating that revision as approved. +No additional owner interview is required for a mechanical split that preserves +approved requirements, HLD, size policy and acceptance. + +Ranges below estimate handwritten churn, including assertion/helpers and fixture +construction. Production and test ranges are separate; the total is their sum. +They are task-by-task engineering estimates, not statistical confidence intervals +or a guarantee that the implementation will stay within the forecast. `Medium` +means there is a close existing implementation to extend. `Low` means new protocol, +durable state, platform custody or fault behavior dominates. No high-confidence +estimate is claimed. Exact files/modules follow implementation style, not a promise +to create one file for each PR. Existing code/tests are reused rather than copied; +only new/changed lines count. Shared harness work is charged to the first child +that uses it, and later children budget their own scenario additions. + +Inspection basis (2026-10-20, checkout `9d5cfc198bb4`): + +| Existing surface | Measured lines | Consequence for estimates | +| --- | ---: | --- | +| `server/src/arbiter_server/artifacts.py` / `server/tests/unit/test_artifacts.py` | 570 / 810 | Extend the real store and tests; encryption, quota and access cutovers need separate boundaries. | +| `server/src/arbiter_server/http_work.py` / `server/tests/unit/test_artifact_http_admission.py` | 170 / 497 | Reuse bounded streaming owners and real contention barriers; do not budget cancellation as a few happy-path assertions. | +| `server/src/arbiter_server/blocking.py` / `server/tests/unit/test_blocking_pool.py` | 93 / 138 | Preserve the existing worker pool; add authority coordination rather than replace it. | +| `client/go-cli/internal/arbiterhttp/client.go` / `client/go-cli/internal/arbiterhttp/client_test.go` | 212 / 251 | Preserve API construction/error shape while changing the carrier. | +| `client/go-cli/internal/arbiterhttp/timeouts.go` / `client/go-cli/internal/arbiterhttp/timeouts_test.go` | 306 / 368 | Reuse budgets; extend real socket coverage at transport cutover. | +| `client/go-cli/internal/cli/cli.go` / `client/go-cli/internal/cli/artifact_commands_test.go` | 2,306 / 869 | Change relevant command paths; avoid an unrelated whole-file rewrite. | +| `server/tests/unit/test_native_http_protocol.py` / `server/tests/integration/test_cli_entrypoint.py` | 1,394 / 1,245 | Reuse synthetic ASGI and installed Go-wheel fixtures; charge new authenticated/process scenarios separately. | +| `server/src/arbiter_server/storage.py` / `server/src/arbiter_server/config.py` | 57 / 376 | Private generation/authority/ACL recovery is mostly new work, not an existing backup subsystem. | + +Read-through of these paths, native route/admission construction in `main.py` and +the HLD’s retained Python/Go probe results informs the estimates. Probe code is not assumed +to be production-ready or copied wholesale. Native Windows custody/durability, +full TLS adapter shutdown and dependency matrix work remain particularly uncertain. +No product tests or new feasibility probes were run for this sizing revision. + +The per-child tables define scope, a focused minimum acceptance check, code ranges, +confidence and direct dependencies. Every child also owns relevant tests from the +shared contracts and its parent milestone: a parent acceptance requirement is not +postponed until its final closure PR when the behavior already exists. Closure PRs +exercise composition, native builds and additional process-level failure cases; +they are not permission to submit earlier untested behavior. Any new runtime +setting/format is documented and tested where first consumed. Each child includes +its applicable package fragment and command/operator guidance; final documentation +passes only reconcile the complete journey. Documentation effort is not included +in the handwritten-code totals, and must be called out before each PR starts. + +### Estimate summary + +| Milestone | Planned PRs | Production churn | Test churn | Combined churn | +| --- | ---: | ---: | ---: | ---: | +| 1 | 6 | 1,340–2,240 | 1,520–2,630 | 2,860–4,870 | +| 2 | 9 | 2,160–3,490 | 2,600–4,380 | 4,760–7,870 | +| 3 | 7 | 1,400–2,410 | 1,950–3,430 | 3,350–5,840 | +| 4 | 5 | 960–1,640 | 1,420–2,440 | 2,380–4,080 | +| 5 | 5 | 960–1,650 | 1,320–2,280 | 2,280–3,930 | +| 6 | 4 | 840–1,430 | 1,080–1,880 | 1,920–3,310 | +| 7 | 6 | 1,160–2,000 | 1,680–2,920 | 2,840–4,920 | +| 8 | 5 | 810–1,430 | 1,300–2,290 | 2,110–3,720 | +| 9 | 5 | 990–1,700 | 1,420–2,450 | 2,410–4,150 | +| 10 | 5 | 920–1,580 | 1,460–2,520 | 2,380–4,100 | +| 11 | 3 | 480–860 | 860–1,500 | 1,340–2,360 | +| **Total** | **60** | **12,020–20,430** | **16,610–28,720** | **28,630–49,150** | + +These totals sum estimated PR churn, including edits to previously introduced code; +they are not final repository size or time estimates. Existing fixtures are reused. +Generated/binary fixtures, dependency locks and documentation have no credible +line forecast yet: quantify them at each child kickoff and separate them in the +review summary. Their absence here is uncertainty, not zero work. No fixed delivery +date or throughput promise follows from these ranges. + ## Shared implementation contracts ### Code ownership and schemas @@ -185,6 +321,17 @@ private material never appears in server state, logs, argv, env or ordinary APIs Test native POSIX and Windows control boundaries. Add setup/trust documentation, operator command help and an `arbiter-server` news fragment. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `1.1` — Private authority initialization | Create UUID-backed owner/server records and versioned SQLite authority schema through stopped-instance init/status; reject a second initialization. **Check:** Reopen preserves IDs; concurrent init and partial DB writes cannot publish two instances. | 200–340 | 220–380 | 420–720 | Medium | None | +| `1.2` — Role-separated credential profiles | Issue and validate setup credentials with explicit SAN/EKU/issuer profiles, exact certificate bounds and validity/renewal schedules. Publish shared profile fixtures consumed by Python now and Go in 2.1. **Check:** Reject cross-role, duplicate SAN, unregistered issuer, malformed DER and wrong key usage; verify profile time boundaries. | 260–420 | 280–450 | 540–870 | Low | 1.1 | +| `1.3` — External operator recovery file | Extend initialization with external recovery signer/decryptor, backup public configuration and registered public trust; keep private recovery material out of server state. **Check:** No overwrite or secret leakage; interrupted publication never reports successful setup with missing recovery trust. | 200–330 | 230–400 | 430–730 | Low | 1.2 | +| `1.4` — Durable application-state publication | Put initialized authority in a private generation with a durable active selector, instance lock and restart reconciliation; validate native ownership and ACLs. **Check:** Faults around flush/reference changes leave one coherent active state; Windows/POSIX locking prevents concurrent start. | 260–420 | 300–500 | 560–920 | Low | 1.3 | +| `1.5` — POSIX authenticated local control | Serve setup/status and bounded administrative messages over a private Unix socket; verify peer credentials and keep live DB writes server-owned. **Check:** Wrong UID, path replacement, oversized input and disconnect fail without loopback authority or leaked slots. | 190–330 | 230–400 | 420–730 | Medium | 1.4 | +| `1.6` — Windows authenticated local control | Provide the same real setup/status journey via named-pipe ACL and caller-token checks, with platform selection and trusted SSH instructions. **Check:** Native unauthorized caller, permissive ACL and pipe replacement fail; installed local commands work on both OS families. | 230–400 | 260–500 | 490–900 | Low | 1.5 | + ## Slice 2 — pairing a real client and reconciling activation Deliver `enrol` from a real Go CLI against a real initialized Python server: @@ -212,6 +359,19 @@ Restart invalidates uncommitted PSKs only; denial beats stale completion. Abando client/server state cleans within bounds. Add enrollment/recovery diagnostics, custody guidance and fragments for server and native client packaging as applicable. +### Child PRs +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `2.1` — Client provisional identity custody | Add real enrol key generation, private atomic client state and closed-server diagnostics; Go consumes 1.2 profile fixtures. **Check:** Restart, failed save and bad permissions leave recoverable provisional state; keys/PSK never reach argv, env or logs. | 240–380 | 260–430 | 500–810 | Low | 1.6 | +| `2.2` — Pending requests and operator approval | Add bounded public request registration and local open/list/approve/reject; bind immutable proposed keys/grants, protected PSK input and original deadlines. **Check:** Closed enrollment cannot open remotely; twenty pending entries include approved work; reopen/expiry races never reset deadlines. | 240–400 | 280–460 | 520–860 | Low | 2.1 | +| `2.3` — Bounded Python pairing responder | Wire binary WebSocket framing and Noise responder into approved pending requests with carrier/crypto reservations and authenticated first-flight accounting. **Check:** Anonymous failures spend no attempts; authenticated duplicates share one owner; five distinct attempts, byte limits and cancellation retain correct ownership. | 300–450 | 300–500 | 600–950 | Low | 2.2 | +| `2.4` — Go pairing initiator and transcript proof | Connect the real enrol command through the bounded WebSocket/Noise adapter; prove proposed keys and exact role/request transcript to the Python responder. **Check:** Wrong PSK/prologue/selector/key or fragmented oversized input cannot advance; a real Python/Go exchange verifies both peers. | 260–420 | 280–470 | 540–890 | Low | 2.3 | +| `2.5` — Prepared enrollment and durable client ready | Issue the owner-approved prepared result, verify it at the client and flush complete keys/trust/result before emitting ready proof. **Check:** Tampered prepared data, wrong issuer/IDs and save failures prevent ready; prepared certificates alone cannot authorize ordinary work. | 260–430 | 300–500 | 560–930 | Low | 2.4 | +| `2.7` — Server-authenticated inner TLS carrier | Implement bounded Python memory-BIO and Go TLS-over-WebSocket streams for fixed receipt control; verify remembered server and exporter, with no ASGI dispatch. No live activation is reachable yet; activated state exists only in synthetic test fixtures. **Check:** Wrong server/ALPN, overrun, blocked writes and cancellation fail; dedicated outer TLS exception leaks no inherited credentials or redirects. | 300–450 | 300–500 | 600–950 | Low | 2.5 | +| `2.8` — Authenticated receipt reconciliation | Implement exact-result receipt control and client reconciliation against synthetic already-activated fixture rows; no product activation route exists until 2.6. **Check:** Test lost reply, restart, wrong key, replay and denial using exact stored results without PSK; synthetic fixtures cannot become product trust or create another activation. | 200–340 | 260–450 | 460–790 | Low | 2.7 | +| `2.6` — Single activation and receipt | With 2.7/2.8 present, wire the first reachable ready/activation commit: conditionally persist identity, credential, grants and result; promote only from authenticated receipt/retrieval. **Check:** Real Python/Go crash/lost-reply/restart at ready/commit/receipt proves one durable result, authenticated promotion and denial precedence; retries create no second identity or grant. | 280–440 | 320–520 | 600–960 | Low | 2.8 | +| `2.9` — Pairing installation and overload closure | Complete prefix packaging/platform checks and process-level pairing failures, reusing earlier fixtures rather than deferring core assertions here. **Check:** Installed CLI pairs/reconciles; dependency builds, proxy fragmentation and simultaneous expiry/shutdown release real owners and keep health responsive. | 80–180 | 300–550 | 380–730 | Low | 2.6 | + ## Slice 3 — native API, account grants and live denial Route every ordinary CLI discovery/schema/invocation/download constructor through @@ -255,6 +415,17 @@ and cancellation/repeated failure release bounded staging and worker ownership. Use a legacy-store spy plus filesystem inspection, including restart cleanup; the final no-publication gate alone is not this acceptance evidence. +### Child PRs +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `3.1` — Ordinary inner mTLS caller context | Add strict access-leaf verification and single-request HTTP/1.1-to-ASGI adapter with immutable verified identity; ordinary API remains closed until 3.5. **Check:** Portable/cross-server/expired leaves fail; no proxy header or outer identity creates a caller; early body input stays admission-bounded. | 260–420 | 280–470 | 540–890 | Low | 2.9 | +| `3.2` — Live grants and admission revision | Implement local grant changes and a coordinator that admits work against current enrollment/account revision, retaining actual worker ownership. **Check:** Grant/revoke and dispatch barriers serialize; caches cannot authorize stale revisions; existing account policy remains the only operation policy. | 220–360 | 260–460 | 480–820 | Low | 3.1 | +| `3.3` — Authenticated discovery filtering | Apply verified grants to catalog, schema, policy/account summaries and direct lookup in the inner API. **Check:** Hidden accounts/policies cannot be learned by guessed paths, errors, previews or shared-account clients; existing payload contracts remain. | 160–300 | 250–430 | 410–730 | Medium | 3.2 | +| `3.4` — Authorized dispatch and closed artifact adapter | Bind account policy and immutable creator context to operation dispatch; replace plugin artifact creation/inspection with a closed adapter before native API cutover. **Check:** Real dispatch to an artifact-producing synthetic plugin rejects before legacy store entry, file/nonce/descriptor publication; upstream effects are reported honestly. | 220–370 | 280–500 | 500–870 | Low | 3.3 | +| `3.6` — Cross-connection live denial | Cancel affected admitted work/output on all connections at grant removal/enrollment denial, preserving pre-body admission and blocking-worker lifetime. Install and test this through prepared inner handlers and real synthetic sockets while the public ordinary boundary stays closed until 3.5. **Check:** Real sockets and slow/chunked bodies prove no post-denial dispatch/output; worker slots stay held until underlying calls exit; no uncertain replay. | 220–380 | 300–520 | 520–900 | Low | 3.4 | +| `3.5` — CLI transport cutover and anonymous closure | Route every Go discovery/invocation/artifact constructor to verified inner transport; atomically close anonymous legacy API/artifact routes on the server. **Check:** First reachable installed Python/Go ordinary prefix tests denial against queued admission, bodies, upstream dispatch and ongoing output with real worker retention; legacy routes stay closed and artifact creation leaves no plaintext/nonce. | 240–400 | 280–500 | 520–900 | Low | 3.6 | +| `3.7` — Native transport regression closure | Complete changed-cert/inspecting-relay/TCP-passthrough, installed-client and timeout/error compatibility checks across native routes. **Check:** Proxy sees no native secret; connect versus API/idle budgets, long active calls and eight-worker/1 MiB limits remain; no new bypass is needed. | 80–180 | 300–550 | 380–730 | Low | 3.5 | + ## Slice 4 — rotation, late completion and bounded fallback Deliver on-contact due rotation, fixed grace, durable candidate save/confirmation @@ -277,6 +448,16 @@ submission, and never replay uncertain mutation/GET. Test across both languages with real controlled clocks/sockets and malicious control transcripts. Add lifecycle configuration/help, repair guidance and server/client fragments. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `4.1` — Server pending rotation and fixed grace | Prepare a due transition on authenticated contact, bind one candidate and preserve current ordinary access until its original deadline. **Check:** Controlled 30-day/24-hour/180-day boundaries, withheld candidates and restart cannot slide grace or inactivity. | 220–360 | 260–450 | 480–810 | Low | 3.7 | +| `4.2` — Durable candidate confirmation | Save candidate state in Go, prove possession and conditionally activate/promote with one retained predecessor and idempotent result. **Check:** Crash/lost reply at save/activate/promote cannot install an unsaved key, clear denial or duplicate transition. | 240–400 | 300–500 | 540–900 | Low | 4.1 | +| `4.3` — Expired-key restricted completion | Add the fixed exporter-bound old-plus-candidate control and reissue only that pending candidate after grace/certificate expiry. **Check:** Ordinary TLS remains strict; wrong pending purpose/revision, replay, inactivity and denial cannot complete or refresh deadlines. | 260–420 | 300–520 | 560–940 | Low | 4.2 | +| `4.4` — Authenticated predecessor assistance | Return authenticated credential status and permit one authentication-only predecessor attempt after the same verified server rejects current credentials. **Check:** Never fallback after timeout, unverified peer, denial or submitted operation/consuming GET; superseding recovery discards history. | 160–280 | 240–420 | 400–700 | Low | 4.3 | +| `4.5` — Lifecycle race and clock closure | Exercise the implemented transitions through process restarts and competing denial/recovery, with final lifecycle diagnostics and retained-receipt cleanup. **Check:** Full Python/Go boundary matrix preserves unattended completion where permitted; incomplete exchanges cannot keep an inactive enrollment alive. | 80–180 | 320–550 | 400–730 | Low | 4.4 | + ## Slice 5 — owner-authorized client recovery Deliver trusted owner tooling to authorize a fresh per-server access key or @@ -302,6 +483,16 @@ before-expiry renewal, signer/key mismatch, denial and renewal races, rejection of portable credentials on ordinary TLS, restart and missed-renewal diagnostics. Certificate renewal must not become an automatic access-key replacement or grant. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `5.1` — Owner-approved pairing repair | Extend local pairing for an existing enrollment with explicit owner selection while retaining durable identity, grants and denial. **Check:** New-client enrollment cannot silently select an existing identity; repair invalidates superseded pending/current credentials without regranting. | 180–300 | 240–420 | 420–720 | Low | 4.5 | +| `5.2` — External owner challenge proofs | Implement strict ES256 recovery statements, externally held signer tooling and fresh server-bound challenge with replacement possession proof. **Check:** Shared Python/Go fixtures reject wrong algorithm, purpose, signer, server, expiry, duplicate fields and changed signed bytes. | 220–370 | 280–480 | 500–850 | Low | 5.1 | +| `5.3` — Atomic access-key recovery | Consume the exact challenge and replace access state in one conditional live-authority transaction; reconcile lost response. **Check:** Recovery/rotation/denial races consume once; revoked state stays revoked; no second per-server approval or issuer private-key sharing. | 200–330 | 260–450 | 460–780 | Low | 5.2 | +| `5.4` — Portable identity repair across servers | Apply the owner-authorized portable replacement and orchestrate distinct per-server recovery proofs using the same external owner trust. **Check:** Two real isolated servers keep independent access keys and grants; portable possession alone cannot replace access or trust another server credential. | 180–320 | 280–480 | 460–800 | Low | 5.3 | +| `5.5` — Owner and portable certificate renewal | Implement authorized before-expiry owner-issuer/portable-leaf renewal under 1.2 schedules, keeping purpose and durable IDs. **Check:** Controlled time, wrong signer, denial, concurrent renewal and restart cannot grant native access or masquerade as access-key rotation. | 180–330 | 260–450 | 440–780 | Low | 5.4 | + ## Slice 6 — server identity replacement Deliver operator-triggered planned authority replacement with old endorsement, @@ -330,6 +521,15 @@ Test expiry/restart/renewal races and ensure HTTPS renewal/URL changes do not re native identity or silently extend authority. Keep these tests distinct from access-key rotation and planned server-key replacement. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `6.1` — Planned server transition publication | Produce old endorsement plus new possession with stable server ID and durable transition history through operator tooling. **Check:** Wrong identity/key, incomplete publication and restart cannot install unsigned trust or lose the prior complete history. | 200–340 | 260–450 | 460–790 | Low | 5.5 | +| `6.2` — Client transition adoption | Fetch and verify legitimate transition chains, then durably adopt server trust for online and long-offline clients. **Check:** Missing/interleaved history, replay and failed save reject safely; credentials are withheld until destination identity is verified. | 200–340 | 260–450 | 460–790 | Low | 6.1 | +| `6.3` — Independent compromise recovery | Use registered external owner authorization for server-key compromise recovery and propagate explicit client repair diagnostics. **Check:** Stolen old server key alone cannot bless a replacement; owner proof cannot clear client denial, change server ID or duplicate grants. | 220–370 | 280–480 | 500–850 | Low | 6.2 | +| `6.4` — Server authority and leaf renewal | Renew server-authority and inner-server-leaf certificates before expiry without scheduled identity-key replacement; use independent owner recovery after missed trust validity. **Check:** Controlled clocks reject expired peer-driven trust renewal; stable IDs/keys, restart and renewal races work; outer HTTPS renewal changes no native trust. | 220–380 | 280–500 | 500–880 | Low | 6.3 | + ## Slice 7 — encrypted server artifacts and ownership Deliver server-side age encryption for the creator's registered recipient and @@ -352,6 +552,17 @@ flows exercise real artifact adapters. Legacy cleanup is idempotent and confined to server-managed ownerless files. Add storage/ownership docs and affected server/ plugin fragments; server encryption is not whole client-processing completion. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `7.1` — Artifact recipient registration and retention | Register fresh recipient possession through authenticated identity, persist bounded client/server recipient history and separate it from access-key rotation. **Check:** Wrong origin/key/version or unauthenticated change fails; keys needed by active artifacts survive access rotation until bounded expiry. | 220–370 | 260–450 | 480–820 | Low | 6.4, 3.6 | +| `7.2` — Encrypted payload and metadata writing | Add streaming age dual-recipient creation and encrypted descriptors behind the closed plugin adapter; preserve server inspection capability. **Check:** Python/Go fixtures prove both recipients, wrong-key/tamper/truncation failure and no persistent plaintext staging; disabled delivery cannot publish a usable nonce. | 240–400 | 280–480 | 520–880 | Low | 7.1 | +| `7.3` — Physical quota and encrypted-store recovery | Integrate ciphertext/metadata/staging reservations, 50 MiB plaintext and existing count/storage/retention limits, plus restart orphan cleanup. **Check:** Near-cap overhead, full disk, concurrent writers, cancellation and open readers hold reservation until actual cleanup; no cap is silently lowered. | 220–360 | 280–480 | 500–840 | Low | 7.2 | +| `7.4` — Creator-bound HEAD and consuming GET | Authorize descriptors/HEAD/GET by creator, account grant and nonce, with atomic consume-before-open and authenticated origin. **Check:** Shared account/copied URL/revocation fails; HEAD never consumes; failed/slow GET stays consumed across restart. | 220–370 | 300–500 | 520–870 | Low | 7.3 | +| `7.5` — Plugin adapter and descriptor activation | Replace the closed adapter with creator-bound encrypted creation for all artifact-producing and inline result paths, retaining legacy-route closure. **Check:** Real mock IMAP/SMTP and Python/Go dispatch cannot choose another creator or return a legacy descriptor; ownerless cleanup stays confined. | 180–320 | 260–460 | 440–780 | Low | 7.4 | +| `7.6` — Artifact contention and packaging closure | Complete real storage-lock/consume/revoke/stream races and age dependency/install checks on supported platforms. **Check:** Health stays responsive under valid/invalid nonces; disconnect/shutdown retain file/crypto owners until cleanup; no replay reopens GET. | 80–180 | 300–550 | 380–730 | Low | 7.5 | + ## Slice 8 — four client artifact paths Deliver immediate plaintext stdin, fully verified encrypted-temp-to-stdin, @@ -373,6 +584,16 @@ compose with slices 3/4/7. Explain delay/storage/partial-effects/plaintext expos in both client reference and operation help, discourage persistent agent exports, and add native-client fragments and affected skill updates. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `8.1` — Immediate authenticated plaintext stdin | Decrypt the one native GET directly to child stdin using the authenticated descriptor and bounded process ownership. **Check:** Final digest/EOF failure reports honestly after any valid prefix; no automatic retry, sensitive stdout or default plaintext file. | 180–320 | 260–450 | 440–770 | Medium | 7.6 | +| `8.2` — Verified encrypted-temp stdin | Reserve ciphertext staging, fully verify to a discard sink, then process exact immutable bytes via native handles or bounded memory fallback. **Check:** Path replacement/writable aliases, tamper/truncation and failed verification cannot start tools on POSIX or Windows; four transfers bound fallback memory. | 260–420 | 300–520 | 560–940 | Low | 8.1 | +| `8.3` — Explicit plaintext-temp path | Require explicit selection, privately stage and fully verify plaintext before tool launch, and clean up on exit/cancellation. **Check:** Bad origin, child failure, signals and path abuse cannot expose unverified files or publish a final artifact; document best-effort crash cleanup. | 150–260 | 220–400 | 370–660 | Medium | 8.2 | +| `8.4` — Deliberate save-decrypted export | Rename intentional persistent plaintext export without the ambiguous save alias; verify private staging before atomic final publication. **Check:** No partial output on full disk/tamper/cancellation; overwrite permissions and explicit user-facing warnings are tested. | 140–250 | 220–400 | 360–650 | Medium | 8.3 | +| `8.5` — Four-mode process and platform closure | Finish CLI/skill tradeoff guidance and real child-process, cleanup and rotation/revocation composition checks without adding a universal mode default. **Check:** Installed tools demonstrate all four paths; consumed GET cannot be resumed from an orphan; native platform process/handle limits are enforced. | 80–180 | 300–520 | 380–700 | Low | 8.4 | + ## Slice 9 — useful consistent encrypted export Deliver local/SSH export usable by an external startup/periodic job: capture one @@ -395,6 +616,16 @@ not a signer supplied by the bundle. Include job examples for durable storage an failure reporting without adding scheduler/cloud integration/first-enrollment gate. Add backup CLI/docs and an arbiter-server fragment. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `9.1` — Saved configuration and real secret capture | Extend private generations to active config/policies and materialized configured file-backed secrets on activation/reload. **Check:** Changed-source capture aborts before publication; arbitrary environment/host files never enter saved state; normal reload remains coherent. | 240–400 | 280–480 | 520–880 | Low | 8.5, 1.4 | +| `9.2` — Coherent authority snapshot | Fence live mutations briefly and capture SQLite plus the exact saved config/key/secret generation, releasing the fence before encrypted streaming. **Check:** Concurrent enroll/grant/revoke/rotate/reload yields one coherent snapshot; failure/shutdown releases the real admin owner and preserves service state. | 200–340 | 280–470 | 480–810 | Low | 9.1 | +| `9.3` — Signed bounded recovery records | Write versioned uncompressed records and exact-byte ES256 manifest; provide strict verification primitives consumed by export self-checks and later restore. **Check:** Reject duplicate paths/fields, links, traversal, oversized entries/count/manifest and bundle-supplied verifier substitution in shared synthetic fixtures. | 250–420 | 300–520 | 550–940 | Low | 9.2 | +| `9.4` — Encrypted local and SSH export | Stream the coherent snapshot through age to external recipient with one admin job and safe publication of complete outputs. **Check:** Private recovery signer/decryptor never enters server/job/bundle; 4 GiB limit, disconnect/full disk and cancellation preserve last good bundle. | 220–360 | 280–480 | 500–840 | Low | 9.3 | +| `9.5` — External job and concurrent-export closure | Document startup/periodic external scheduling, durable destination/alerting and round-trip verifier usage; finish process-level snapshot contention tests. **Check:** Real local/verified-SSH jobs produce usable signed encrypted snapshots; excluded transient artifacts/PSKs/client keys remain absent across failures. | 80–180 | 280–500 | 360–680 | Low | 9.4 | + ## Slice 10 — offline restore and latest undo Deliver offline restore while the server is broken/stopped, using the external @@ -421,6 +652,16 @@ restore failure, undo after use and explicit discard. Show clear repair diagnost without claiming to know unseen client history. Add full restore/undo examples, host-configuration exclusions and arbiter-server fragment. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `10.1` — Strict offline bundle validation | Decrypt against external trust, validate all record/hash/EOF/certificate/key/config constraints before exposing a restorable generation. **Check:** Malformed/traversing/duplicate/oversized records, wrong verifier and incomplete stream fail with bounded I/O and no active-state changes. | 240–400 | 300–520 | 540–920 | Low | 9.5 | +| `10.2` — Stopped-instance private restore staging | Require exclusive stopped-instance lock, available-disk reservation and same-filesystem private staging; reconcile incomplete restore on restart. **Check:** Concurrent server start/restore, disk failure and real process termination preserve active generation and existing undo. | 200–340 | 280–480 | 480–820 | Low | 10.1 | +| `10.3` — Atomic full restore activation | Publish verified generation with active/undo references in one durable control transaction, retaining saved lifecycle timestamps and host exclusions. **Check:** Empty/existing hosts restore coherently; faults at flush/reference boundaries choose only old or new complete state, never merge or extend authority. | 220–360 | 300–520 | 520–880 | Low | 10.2 | +| `10.4` — Latest undo and explicit discard | Implement offline undo without expiry or post-use hard cutoff; retain the point through ordinary operation and warn prominently before discarding later changes. **Check:** Failed restore preserves undo; next successful restore replaces it; undo after use and discard have no redo/history or upstream rollback promise. | 180–300 | 260–450 | 440–750 | Low | 10.3 | +| `10.5` — Restore-client and native crash closure | Complete controlled process-crash and native durability tests, stale client/predecessor diagnostics and useful full restore/undo examples. **Check:** Multiple paired clients either recover within bounded fallback or require explicit repair; old snapshot denial/deadlines reflect snapshot, not guessed unseen history. | 80–180 | 320–550 | 400–730 | Low | 10.4 | + ## Slice 11 — cooperative migration and handoff Deliver maintenance/migration tooling and runbook: disable source ordinary work @@ -443,10 +684,18 @@ copies. Run actual Reploy staging on its separate port using synthetic state; no live installation migration is authorized by this plan. Add maintenance/handoff docs, client diagnostics and affected server/client fragments. +### Child PRs + +| PR | Scope and focused acceptance | Production | Tests | Total | Confidence | Direct prerequisites | +| --- | --- | ---: | ---: | ---: | --- | --- | +| `11.1` — Cooperative maintenance and migration | Disable source ordinary work/admin mutations, drain real owners, export final snapshot and restore stopped destination under documented operator coordination. **Check:** Source stays disabled through failures; no new fencing/epoch/cluster mechanism or automatic old-host restart is introduced. | 180–300 | 260–450 | 440–750 | Low | 10.5 | +| `11.2` — Verified source URL handoff | Serve only a fixed authenticated destination URL from disabled source; client verifies same durable identity/transition chain before adopting and sending any credential. **Check:** Mismatch/unavailable URL/later destination replacement/lost response never replays submitted mutation or GET; handoff cannot mutate authority. | 220–380 | 280–500 | 500–880 | Low | 11.1 | +| `11.3` — Migration and combined release evidence | Finish synthetic multi-client Reploy staging on its separate port and the full combined journey/matrix; reconcile release/help/skill/dependency metadata. **Check:** Migration with grants/pending rotations and post-use undo is honest; all required checks pass or remain explicitly unverified and block publication. | 80–180 | 320–550 | 400–730 | Low | 11.2 | + ## Combined acceptance and publication gate Every slice runs prefix integration; do not defer first Python/Go composition, -platform packaging or cancellation testing until this gate. Once all eleven PRs +platform packaging or cancellation testing until this gate. Once all child PRs across the eleven milestones have approved final heads and required checks, run the complete synthetic journey: 1. Fresh private setup with no public CA/DNS or external identity account; enroll diff --git a/docs/authentication/reviews/README.md b/docs/authentication/reviews/README.md index 6ee7a63..f162a18 100644 --- a/docs/authentication/reviews/README.md +++ b/docs/authentication/reviews/README.md @@ -16,29 +16,45 @@ The [HLD](../high-level-design.md) now has its own | [Requirements DBB review](requirements-dbb.md) | Pass on the exact initial requirements baseline; safe to begin high-level design. No blocking requirements findings. | | [HLD DBB review](hld-dbb.md) | Pass on the exact HLD, with no blocking HLD findings. Wire, implementation, dependency, platform and release approval remain separate. | | [Plan DBB review](plan-dbb.md) | Two plan gaps repaired: safe slice-3 artifact prefix and certificate renewal ownership/tests. Round-two exact-byte pass; no remaining blocking plan findings. | +| [Plan sizing DBB review](plan-sizing-dbb.md) | Current sixty-child plan passed after receipt recovery moved before activation and complete live denial moved before ordinary cutover. Size forecasts and hard-cap enforcement remain implementation obligations. | The requirements stamp followed a separate primary-agent requirements review -through SWE, after the actual DBB pass. Its immutable round report is retained +through SWE, after the DBB pass. Its immutable round report is retained locally under `temp/reviews/requirements/rounds/round-01.md`. The stamp is limited to requirements maturity; no high-level design, plan, implementation or release -is approved by it. The owner requires actual DBB review before stamping each +is approved by it. The owner requires DBB review before stamping each new or modified document in this sequence. -The HLD then passed actual DBB and a separate primary-agent seven-dimension SWE +The HLD then passed DBB and a separate primary-agent seven-dimension SWE design review in its first round. Its immutable SWE report is retained locally at `temp/reviews/high-level-design/rounds/round-01.md`. Fourteen local feasibility checks, Go vet and Go 1.24 compilation passed, with limits recorded in the HLD and DBB report. Recursive stamp validation accepted the HLD and exact requirements dependency. Neither an implementation plan nor product implementation was started. -The subsequent [implementation plan](../implementation-plan.md) passed actual DBB +The initial [implementation plan](../implementation-plan.md) passed DBB in round two after those two plan repairs, then a primary-agent seven-dimension SWE review with zero findings. Its immutable report is retained locally at `temp/reviews/implementation-plan/rounds/round-01.md`. The [standardized plan stamp](../.review/implementation-plan.md) binds `arbiter-authentication` / `hierarchical-v1` and both exact governing documents; -recursive validation accepted the complete requirements/HLD/plan chain. Eleven -implementation PRs are planned, with none started or approved as code. +recursive validation accepted the complete requirements/HLD/plan chain. That +revision treated the eleven milestones as intended PRs; it is historical evidence. + +The sizing revision replaces that assumption with sixty planned child PRs, separate +production/test churn ranges and confidence, a target near 600 lines and a hard +1,000-line combined handwritten-code limit. DBB round two passed the exact revised +bytes after two ordering repairs; a new primary-agent seven-dimension SWE review +was clean. Its immutable report is retained locally at +`temp/reviews/implementation-plan/rounds/round-02.md`. The replacement plan stamp +from that review bound its exact sizing predecessor and the unchanged requirements/HLD. +The current plan also contains the later milestone/title amendment. Its +[separate DBB approval](plan-milestones-dbb.md) names the exact current plan hash +`c576091af919c3ec99f0e0edb5795cf4e7bd37a44415ae24742393822317ad3d`, +which the current replacement stamp validates against those same dependencies. +Both completed reviews are now available with their respective input identities. +No implementation PR has started. Forecasts are not measured implementation, +a guaranteed PR count or platform certification. The [initial brief](initial-brief.md) and [repair brief](repair-brief.md) preserve the historical review requests. Their pending-status text and output filenames diff --git a/docs/authentication/reviews/plan-milestones-dbb.md b/docs/authentication/reviews/plan-milestones-dbb.md new file mode 100644 index 0000000..820b9be --- /dev/null +++ b/docs/authentication/reviews/plan-milestones-dbb.md @@ -0,0 +1,97 @@ +# DBB review: authentication milestone delivery amendment + +Reviewed 2026-10-20. This is my bounded defensive-security assessment of the +implementation-plan amendment that defines milestone PR stacks, merge authority +and short title prefixes. I reviewed the exact amended plan in final context +against the unchanged requirements, HLD and previously approved 60-child sizing +and ordering plan. This is not an implementation, PR-head, dependency, platform, +deployment or release audit. + +## Verdict + +**Pass at implementation-plan amendment level.** The exact target adds a coherent +milestone delivery boundary without changing trust policy, canonical slice +identities, child contents, security-sensitive order, sizing limits or publication +requirements. It requires current final-head approvals and checks, parent milestone +acceptance and relevant prior-milestone integration before an operator-authorized +merge. It also keeps merge separate from release, deployment and live-account use. +I found no blocking or non-blocking plan-level security finding in this amendment. +These exact bytes may proceed to the separate SWE review and replacement plan +stamp. + +This verdict applies only to +[`docs/authentication/implementation-plan.md`](../implementation-plan.md) with +SHA-256 +`c576091af919c3ec99f0e0edb5795cf4e7bd37a44415ae24742393822317ad3d`, +over checkout baseline revision `0aa1b60a3c13`, against the unchanged +[`docs/authentication/requirements.md`](../requirements.md) with SHA-256 +`d56e92a7cb01f131ba499650c4a5d7b2c8d17adf2cdc7d612eee7c5f53d07929` +and +[`docs/authentication/high-level-design.md`](../high-level-design.md) with SHA-256 +`b6511414b3a9b485542df83c8f7abfc499dc8d06e522819b48e162a562d21c57`. +The approved predecessor plan had SHA-256 +`e8e27181f5f6ab25de0135b44ef188606fa55830cb9a336179c8b43431873e98`. +This report creates no stamp and authorizes no merge or implementation. + +## Assessment + +**Milestone merge boundary.** One connected stack per milestone is compatible with +the serial child-review rule. Before merge, the amendment requires current approval +and required checks for every final PR head, the complete parent milestone +acceptance and integration checks, and relevant integration with completed +milestones. Corrections and restacks invalidate affected evidence and require +reconciliation. Safe intermediate behavior remains mandatory. These conditions +prevent the stack boundary from bypassing child or parent security obligations. + +The operator remains the merge authority. The plan prohibits automatic merge, +requires bottom-up application of the verified stack, and requires verification of +the resulting main-branch state before the next milestone is based on it. The next +milestone cannot silently extend the previous unmerged stack. A request may stop +with the stack ready for the operator, so the planning text does not itself grant +authority to mutate the remote repository. + +**Identity and evidence binding.** The short title label +`[authentication/]` is only a display convention for implementation and +review-fix commit subjects and PR titles. The plan expressly maps it to the +unchanged canonical ledger identity `arbiter-authentication/`, retains +`plan_key: arbiter-authentication`, uses deeper child IDs after reviewed splits and +states that neither a title nor a PR number replaces ledger identity. This avoids +treating editable repository metadata as authorization or completion evidence. + +**Preserved security order and acceptance.** The focused delta adds 27 lines and +deletes none from the approved predecessor. The 60 unique child identities, listed +dependency order, per-child scope and estimates are unchanged. In particular, the +2.7/2.8-before-2.6 reconciliation repair and 3.6-before-3.5 live-denial repair remain +intact. The slice-3 closed artifact prefix, four-role certificate renewal ownership, +mandatory parent tests, hard 1,000-line handwritten-change limit and cooperative +migration without prohibited fencing remain unchanged. + +**Publication boundary.** A milestone merge remains development integration. The +amendment explicitly retains all eleven milestones and the combined publication +gate before authentication support can be published. No milestone merge authorizes +a package release, deployment or live-account operation. + +## Evidence and limits + +I read the complete amended plan in final context and compared it byte-for-byte +with the frozen approved predecessor at +`temp/authentication-plan-refinement/plan-round-02.md`. The comparison contained +only the 27 added lines described above. I rechecked the unchanged requirements, +HLD and prior sizing-review dispositions relevant to the amendment. + +Local read-only structural checks confirmed 60 unique children, unchanged aggregate +estimated churn of 28,630–49,150 handwritten production/test/fixture lines, a +maximum child forecast of 960 lines and no forward or missing dependency in the +authoritative listed order. The amended plan is byte-identical to +`temp/authentication-milestone-1/plan-milestone-r1.md`. + +I ran no product test, live account operation, dependency install, network scan or +new security scan. No implementation or PR stack exists to validate. This pass +approves only the plan amendment's identity, review, merge and publication +boundaries. It does not approve code, any future PR head, dependencies, supported- +platform behavior, merge execution, deployment, publication or release. + +I created only this review report. I changed no target, governing document, prior +report, product file or workflow artifact, and did not commit, push, merge, deploy +or operate a live account. Any target-byte change requires re-review before a new +verdict. diff --git a/docs/authentication/reviews/plan-sizing-dbb.md b/docs/authentication/reviews/plan-sizing-dbb.md new file mode 100644 index 0000000..405f6c5 --- /dev/null +++ b/docs/authentication/reviews/plan-sizing-dbb.md @@ -0,0 +1,152 @@ +# DBB review: authentication plan sizing and child-PR order + +Reviewed 2026-10-20. This is my bounded defensive-security assessment of the +revised implementation-plan decomposition. It checks whether the former eleven +large implementation milestones are split into reviewable child PRs without +weakening the governing requirements, HLD, parent acceptance obligations or safe +prefix behavior. It is not an implementation, dependency, platform, deployment or +release audit. + +## Verdict + +**Pass at implementation-plan sizing level.** The exact round-2 plan provides a +coherent 60-child decomposition and preserves the fixed requirements, HLD, parent +acceptance obligations and safe prefix behavior. Round-1 findings P1 and P2 are +resolved through real runtime closure and repaired child order, not through a +publication label or weakened acceptance text. I found no remaining blocking +plan-level finding. These exact plan bytes may proceed to the separate SWE review +and replacement plan stamp. + +This verdict applies only to +[`docs/authentication/implementation-plan.md`](../implementation-plan.md) with +SHA-256 +`e8e27181f5f6ab25de0135b44ef188606fa55830cb9a336179c8b43431873e98`, +against the unchanged +[`docs/authentication/requirements.md`](../requirements.md) with SHA-256 +`d56e92a7cb01f131ba499650c4a5d7b2c8d17adf2cdc7d612eee7c5f53d07929` +and +[`docs/authentication/high-level-design.md`](../high-level-design.md) with SHA-256 +`b6511414b3a9b485542df83c8f7abfc499dc8d06e522819b48e162a562d21c57`. +The historical [`plan-dbb.md`](plan-dbb.md) was evidence for this review and was +not modified. This report does not create or replace a stamp. + +## Finding disposition + +**Blocking findings: none. Required plan fixes: none.** The following dispositions +record how the exact round-2 plan closes the two round-1 findings. They are plan +contract fixes and do not claim that product behavior is implemented. + +### P1 — resolved: complete live denial precedes ordinary cutover + +**Round-1 prerequisite and impact.** Child 3.5 made ordinary traffic reachable +before child 3.6 installed cross-connection cancellation and output blocking. A +grant removal or enrollment denial during an admitted request could therefore leave +post-denial delivery possible in that prefix, contrary to R14 and the HLD +coordinator contract. + +**Round-2 disposition.** The listed order now runs 3.6 before 3.5, with a direct +3.5 dependency on 3.6. The plan expressly keeps ordinary public dispatch closed +while 3.6 installs cancellation through prepared inner handlers and real synthetic +sockets. Child 3.5 is now the first reachable ordinary prefix and owns real +Python/Go denial checks against queued admission, request bodies, upstream dispatch +and ongoing output, including real blocking-worker retention. Anonymous legacy +routes and the artifact path close in that same cutover. The repair preserves the +accepted no-uncertain-replay and closed-artifact requirements. + +### P2 — resolved: lost-receipt reconciliation precedes reachable commit + +**Round-1 prerequisite and impact.** Child 2.6 made a durable activation commit +reachable before children 2.7 and 2.8 supplied the authenticated status carrier and +exact-result retrieval. Loss of the final reply could strand active server authority +and provisional client state without the R09/HLD reconciliation path. + +**Round-2 disposition.** The listed order now runs 2.7 and 2.8 before 2.6, and 2.6 +depends directly on 2.8. Runtime text keeps the live ready/activation route absent +through 2.8. Those carrier/reconciliation children use only clearly test-only +already-activated fixture rows, which cannot initialize product trust or create an +activation. Child 2.6 then wires the first reachable commit with the carrier and +exact-result retrieval already present. Its real Python/Go checks cover crash, +lost reply and restart at ready/commit/receipt boundaries, authenticated client +promotion, denial precedence and absence of a second identity or grant. This +closes the durable ambiguity without a permissive stub or temporary protocol. + +## Accepted parts of the revision + +The sizing arithmetic is internally consistent: 60 unique child identities cover +all eleven parent milestones; their stated ranges sum to 28,630–49,150 changed +handwritten production/test/fixture lines; each row's production and test ranges +sum to its total; and the largest forecast is 960 lines. All explicit child +dependencies point backward in the serial queue. The plan correctly counts +additions plus deletions across Python and Go, forbids moving tests or disguising +handwritten fixtures to satisfy the cap, and requires a forecast and mechanical +split before a child reaches the hard 1,000-line limit. + +The estimates remain planning estimates rather than delivery guarantees. Fifty-four +of 60 children are marked low confidence, and 13 have an upper forecast of at least +900 lines. The inspected repository confirms why: authority state, protocol +carriers, cross-platform custody and coherent backup/restore are largely new, while +the existing artifact, ASGI, installed-client and timeout test surfaces are already +substantial. The mandatory stop-and-split rule is therefore necessary. It makes the +decomposition feasible without claiming that exactly 60 PRs will suffice. + +The plan preserves parent obligations in its shared rule that each child owns the +relevant parent tests as soon as behavior exists; closure PRs cannot excuse earlier +untested behavior. The two repaired cutover children now own the missing real +prefix evidence. Foundation work has a consumed setup/status, pending-request or +executable peer boundary and expressly forbids empty interfaces, permissive stubs +and temporary production protocols. + +The earlier artifact finding remains closed. Child 3.4 installs and tests the closed +plugin artifact adapter before child 3.5 makes ordinary traffic reachable. The +required authenticated Python/Go prefix evidence retains the legacy-store spy, +filesystem/route inspection, restart cleanup and resource-release checks. Children +7.2–7.4 build encrypted creation, quota recovery and creator-bound retrieval behind +that boundary; 7.5 replaces the adapter only after those prerequisites exist. + +Certificate lifecycle ownership also remains complete. Child 1.2 fixes the profiles +and renewal schedules; 5.5 owns authorized owner-issuer and portable-leaf renewal; +6.4 owns server-authority and inner-server-leaf renewal plus missed-validity owner +recovery. Their controlled-clock negative checks and the combined four-role renewal +journey retain the prior DBB disposition. These paths remain distinct from access- +key rotation and planned server identity-key replacement. + +The split does not add migration fencing, epochs, clustering or another authority. +Child 11.1 and the parent acceptance text retain the approved cooperative operator +procedure. I did not reopen that accepted trust decision. + +## Evidence and limits + +I read the complete revised plan, unchanged requirements and HLD, the historical +plan DBB review, repository instructions and the relevant current server/client +surfaces. I inspected the native API/client transport, artifact store/admission, +blocking pool, storage/configuration and existing tests to assess the sizing basis +and trust transitions. The inspected checkout revision was `9d5cfc198bb4`. + +I compared the complete round-2 target with the frozen round-1 target and report. +I also ran local read-only structural checks for child count/uniqueness, listed +order, range arithmetic, maximum forecast, estimate totals, dependency direction +and exact SHA-256 identities. + +I ran no product test, live account operation, dependency install, network scan or +new security scan. No authentication implementation exists to test; absence of +implementation was not treated as a plan defect. This pass approves only the child +order, sizing discipline and assigned verification obligations. It does not approve +code, dependencies, supported-platform behavior, deployment, publication or release. + +I changed only this review report, changed no target/governing/historical document, +and did not commit, push, publish, merge or deploy anything. + +## Round history + +| Round | Exact target | Verdict | Finding disposition | +| --- | --- | --- | --- | +| 1 — 2026-10-20 | `585af79a10f5110c58efc87ce5b4ac29c5ab444c8aea649cf733d362f08d5a33` | Changes required | P1 ordinary cutover preceded complete live denial; P2 durable commit preceded lost-receipt reconciliation. | +| 2 — 2026-10-20 | `e8e27181f5f6ab25de0135b44ef188606fa55830cb9a336179c8b43431873e98` | Pass at implementation-plan sizing level | P1 resolved; P2 resolved; no new blocking finding. | + +The frozen round-1 target and report remain at +`temp/authentication-plan-refinement/plan-round-01.md` (SHA-256 +`585af79a10f5110c58efc87ce5b4ac29c5ab444c8aea649cf733d362f08d5a33`) +and `temp/authentication-plan-refinement/dbb-round-01.md` (SHA-256 +`773f4ed126bf75cb7641c5eab0091ac433542d024dbe7f35969f7910e17c6bcc`). +Any future re-review must preserve these rows and append its exact target identity, +verdict and finding disposition.