dohertj2/natsnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
c0ec1f3341b2b821e517d94c802917841d092384
natsnet/docs/plans/2026-02-27-batch-9-auth-dirstore-ocsp-foundations-design.md
Joseph Doherty f0455a1e45 Add batch plans for batches 6-7, 9-12, 16-17 (rounds 4-7) 
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.
2026-02-27 14:56:19 -05:00

6.5 KiB
Raw Blame History

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.

Reference in New Issue View Git Blame Copy Permalink