f0455a1e45
Generated design docs and implementation plans via Codex for: - Batch 6: Opts package-level functions - Batch 7: Opts class methods + Reload - Batch 9: Auth, DirStore, OCSP foundations - Batch 10: OCSP Cache + JS Events - Batch 11: FileStore Init - Batch 12: FileStore Recovery - Batch 16: Client Core (first half) - Batch 17: Client Core (second half) All plans include mandatory verification protocol and anti-stub guardrails. Updated batches.md with file paths and planned status.
145 lines
6.5 KiB
Markdown
145 lines
6.5 KiB
Markdown
# Batch 9 (Auth, DirStore, OCSP Foundations) Design
|
|
|
|
**Date:** 2026-02-27
|
|
**Scope:** Design-only plan for Batch 9 (36 features, 10 tests) covering `server/auth.go`, `server/dirstore.go`, `server/ocsp.go`, and `server/ocsp_peer.go`.
|
|
|
|
## Context Snapshot
|
|
|
|
PortTracker snapshot:
|
|
|
|
- Batch ID: `9`
|
|
- Name: `Auth, DirStore, OCSP foundations`
|
|
- Dependencies: `Batch 4`, `Batch 6`
|
|
- Features: `36` (all currently `deferred`)
|
|
- Tests: `10` (all currently `deferred`)
|
|
- Current overall project progress (`report summary`): `1924/6942 (27.7%)`
|
|
|
|
Batch 9 feature clusters from tracker mapping:
|
|
|
|
- Auth: `361` (`client.matchesPinnedCert` -> `ClientConnection.MatchesPinnedCert`)
|
|
- DirStore: `793,794,817,818,819,820,821` (`validatePathExists`, `validateDirPath`, and `expirationTracker` heap methods)
|
|
- OCSP monitor/server wiring: `2443-2462`
|
|
- OCSP peer validation: `2463-2471`
|
|
|
|
Batch 9 test mappings:
|
|
|
|
- Tests `118,119,124,125,128,129,130,131,134,135` mapped to `AuthCalloutTests.*` in `ImplBacklog`
|
|
|
|
Current .NET baseline findings:
|
|
|
|
- `DirJwtStore` exists and implements equivalent behavior, but mapped names (`ValidatePathExists`, `ValidateDirPath`, `ExpirationTracker.Len/Less/Swap/Push/Pop`) are not exposed as mapped methods.
|
|
- OCSP code is partially ported in `Auth/Ocsp/OcspTypes.cs`, but many Batch 9 mapped methods (`NatsServer.*` OCSP lifecycle + `OcspHandler` helpers + OCSP peer wiring) are not present yet.
|
|
- Mapped Batch 9 `AuthCallout` tests are not implemented in `AuthCalloutTests.Impltests.cs` yet.
|
|
|
|
## Problem Statement
|
|
|
|
Batch 9 is a foundational bridge between TLS auth, directory-backed JWT storage, and OCSP lifecycle/peer validation. The largest risk is false progress through status updates without behavior-complete parity. A second risk is trying to force infra-heavy auth-callout tests into fake unit tests.
|
|
|
|
## Constraints and Success Criteria
|
|
|
|
Constraints:
|
|
|
|
- Must respect dependency order (`4`, `6`) before execution starts.
|
|
- Must follow project standards (`.NET 10`, nullable, xUnit + Shouldly + NSubstitute).
|
|
- No placeholders/stubs for production features or tests promoted to `verified`.
|
|
- Task slicing must keep feature groups <= ~20 IDs.
|
|
|
|
Success criteria:
|
|
|
|
- All implementable Batch 9 feature IDs are ported with direct Go-parity evidence.
|
|
- Batch 9 mapped tests are either real/passing or explicitly kept `deferred` with concrete blocker reasons.
|
|
- Status transitions are evidence-backed and chunked (<=15 IDs per update command).
|
|
|
|
## Approaches
|
|
|
|
### Approach A: Minimum mapping wrappers only
|
|
|
|
Create thin wrappers for missing mapped methods and mark complete quickly.
|
|
|
|
- Pros: fast status movement.
|
|
- Cons: high semantic risk for OCSP lifecycle and peer-verification behavior.
|
|
|
|
### Approach B: Full OCSP/auth-callout infrastructure first
|
|
|
|
Attempt full runtime-complete auth callout + OCSP networking + integration-heavy tests in one pass.
|
|
|
|
- Pros: closest to end-state behavior.
|
|
- Cons: oversized scope for one batch, high blocker probability, low iteration speed.
|
|
|
|
### Approach C (Recommended): Layered parity slices with strict defer rules
|
|
|
|
Implement Batch 9 in four bounded feature groups (auth/DirStore -> OCSP core -> OCSP server wiring -> OCSP peer), each with focused tests and hard verification gates. For mapped auth-callout tests, only verify real behaviors that are executable in current infrastructure; keep infra-blocked tests deferred with explicit reasons.
|
|
|
|
- Pros: controlled risk, auditable status evidence, resilient to infra blockers.
|
|
- Cons: requires disciplined status hygiene and explicit defer documentation.
|
|
|
|
## Recommended Design
|
|
|
|
### 1. Production Code Shape
|
|
|
|
Primary files:
|
|
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/Accounts/DirJwtStore.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspTypes.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs`
|
|
|
|
Expected new files:
|
|
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Ocsp.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.OcspPeer.cs`
|
|
- `dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspHandler.cs`
|
|
|
|
Design intent:
|
|
|
|
- Add explicit mapped methods for path validation and expiration heap parity without regressing current `DirJwtStore` behavior.
|
|
- Separate OCSP responsibilities:
|
|
- monitor/cache/status helpers
|
|
- server TLS config wiring and lifecycle (enable/start/reload)
|
|
- peer verification and OCSP-peer config parsing
|
|
- Keep OCSP parsing/network behavior deterministic in unit tests by isolating pure helper paths and using controlled inputs.
|
|
|
|
### 2. Test Design
|
|
|
|
Primary/updated test files:
|
|
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Accounts/DirectoryStoreTests.cs`
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspResponseCacheTests.cs`
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/CertificateIdentityProvider/CertificateIdentityProviderTests.cs`
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AuthCalloutTests.Impltests.cs`
|
|
|
|
Expected new test files:
|
|
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspFoundationTests.cs`
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspPeerValidationTests.cs`
|
|
- `dotnet/tests/ZB.MOM.NatsNet.Server.Tests/NatsServerOcspTests.cs`
|
|
|
|
Test strategy:
|
|
|
|
- Feature-first parity tests for each group before status promotion.
|
|
- Mapped `AuthCallout` tests use strict realism checks; if internal callout transport/JWT signing pipeline is still unavailable, keep deferred with explicit reason instead of synthetic pass tests.
|
|
|
|
### 3. Execution Slicing (Feature Groups <=20)
|
|
|
|
- **F1 (8 IDs):** `361,793,794,817,818,819,820,821`
|
|
- **F2 (12 IDs):** `2443,2444,2445,2446,2447,2448,2457,2458,2459,2460,2461,2462`
|
|
- **F3 (7 IDs):** `2450,2451,2452,2453,2454,2455,2456`
|
|
- **F4 (9 IDs):** `2463,2464,2465,2466,2467,2468,2469,2470,2471`
|
|
- **T1 (10 test IDs):** `118,119,124,125,128,129,130,131,134,135`
|
|
|
|
### 4. Risks and Mitigations
|
|
|
|
1. OCSP runtime/network complexity causes partial implementations.
|
|
Mitigation: isolate pure helper logic, gate status on focused tests, defer blocked runtime-only paths with evidence.
|
|
|
|
2. Existing OCSP/DirStore code already diverges from mapped method names.
|
|
Mitigation: add explicit mapped entry points/wrappers and prove they are exercised by tests.
|
|
|
|
3. Auth callout mapped tests require unavailable infrastructure.
|
|
Mitigation: enforce no-fake-pass policy; defer with concrete blocker notes and command evidence.
|
|
|
|
## Design Decision
|
|
|
|
Proceed with **Approach C**: bounded feature groups + strict verification/defer protocol, then mapped test pass/defer resolution with zero stub tolerance.
|