# 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.