natsnet/docs/plans/2026-02-27-batch-9-auth-dirstore-ocsp-foundations-plan.md

Batch 9 (Auth, DirStore, OCSP Foundations) Implementation Plan

For Codex: REQUIRED SUB-SKILL: Use executeplan to implement this plan task-by-task.

Goal: Implement and verify Batch 9 (36 features + 10 tests) across auth pinned-cert checks, directory-store parity helpers, and OCSP monitor/peer foundations, with evidence-backed status updates.

Architecture: Execute four bounded feature groups (8/12/7/9 IDs) and one mapped-test group. For every feature: read mapped Go source, implement minimal parity, build, run related tests, then promote status only after gates pass. For mapped auth-callout tests, enforce real behavioral verification; if infrastructure is missing, keep deferred with explicit blocker evidence.

Tech Stack: .NET 10, C# latest, xUnit + Shouldly + NSubstitute, PortTracker CLI, SQLite (porting.db)

Design doc: docs/plans/2026-02-27-batch-9-auth-dirstore-ocsp-foundations-design.md

---

I'm using writeplan to create the implementation plan.

Batch 9 Working Set

Batch facts:

• Batch ID: 9
• Dependencies: 4,6
• Features: 36
• Tests: 10
• Go files: server/auth.go, server/dirstore.go, server/ocsp.go, server/ocsp_peer.go

Environment note:

• dotnet is not on PATH in this workspace. Use /usr/local/share/dotnet/dotnet for all commands.

Feature groups (max ~20 each):

• F1 (8): 361,793,794,817,818,819,820,821
• F2 (12): 2443,2444,2445,2446,2447,2448,2457,2458,2459,2460,2461,2462
• F3 (7): 2450,2451,2452,2453,2454,2455,2456
• F4 (9): 2463,2464,2465,2466,2467,2468,2469,2470,2471

Test group:

• T1 (10): 118,119,124,125,128,129,130,131,134,135

---

MANDATORY VERIFICATION PROTOCOL

NON-NEGOTIABLE: No Batch 9 feature/test may be marked verified unless this exact protocol is followed.

Per-Feature Verification Loop (REQUIRED for every feature ID)

1. Read mapping + Go location:

   /usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- feature show <id> --db porting.db
   

2. Read exact Go behavior in mapped file/line range.
3. Write C# parity in mapped .NET file/class.
4. Build immediately:

   /usr/local/share/dotnet/dotnet build dotnet/
   

5. Run related tests for that feature slice (examples in each task).
6. Only after build + related tests pass, add feature ID to promotion candidates.

Per-Test Verification Loop (REQUIRED for every test ID)

1. Read mapping + Go test location:

   /usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- test show <id> --db porting.db
   

2. Implement/port real Arrange/Act/Assert behavior in mapped test method.
3. Run single mapped test method:

   /usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
     --filter "FullyQualifiedName~<ExactMethodName>" --verbosity normal
   

4. Require discovery and pass (Passed: 1, Failed: 0) before candidate promotion.

Stub Detection Check (REQUIRED after each feature/test group)

Run after each task, before any status promotion:

# Forbidden placeholder markers in touched source/tests
rg -n "NotImplementedException|TODO|PLACEHOLDER" \
  dotnet/src/ZB.MOM.NatsNet.Server \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests

# Empty method bodies in touched C# files
for f in $(git diff --name-only -- '*.cs'); do
  rg -n "^\s*(public|private|internal|protected).*\)\s*\{\s*\}\s*$" "$f"
done

Any match blocks status updates until fixed or explicitly deferred with reason.

Build Gate (REQUIRED after each feature group)

/usr/local/share/dotnet/dotnet build dotnet/

Required: 0 build errors.

Test Gate (REQUIRED before marking features verified)

All related tests for current group must pass before any verified promotion.

Baseline command template:

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "<group-specific-related-tests>" --verbosity normal

Status Update Protocol (REQUIRED)

• Maximum 15 IDs per feature batch-update or test batch-update command.
• Required evidence for each update command:
  • latest build gate output
  • related test gate output
  • stub detection output
• Status flow:
  • Features: deferred -> stub -> complete -> verified
  • Tests: deferred -> stub -> verified (or remain deferred with override reason)

Command templates:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "<max15ids>" --set-status <stub|complete|verified> --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "<max15ids>" --set-status <stub|verified> --db porting.db --execute

If audit disagrees:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature update <id> --status <status> --db porting.db \
  --override "verification evidence: <short reason>"

Checkpoint Protocol Between Tasks (REQUIRED)

After each task (F1/F2/F3/F4/T1), before moving on:

1. Full build:

   /usr/local/share/dotnet/dotnet build dotnet/
   

2. Full unit tests:

   /usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal
   

3. Commit completed slice:

   git add <touched-files> porting.db
   git commit -m "feat(batch9): <task-slice-summary>"
   

---

ANTI-STUB GUARDRAILS

Forbidden Patterns

Production code must not include:

• throw new NotImplementedException(...) for Batch 9 mapped methods
• empty mapped method bodies ({ })
• TODO placeholders in mapped method bodies
• fake default returns (return null;, return default;, return true;) where Go behavior is non-trivial

Test code must not include for verified status:

• Assert.True(true) / unconditional pass assertions
• tests that only assert method-name strings/constants
• empty test bodies
• single trivial assertion that does not exercise mapped behavior

Hard Limits

• Max 20 features per implementation task group
• Max 15 IDs per status update command
• No cross-group bulk verification in one cycle
• Build gate required after each feature group
• Test gate required before verified promotion
• Mandatory checkpoint commit between task groups

If You Get Stuck

Do not stub and do not fake-pass.

1. Keep blocked feature/test as deferred.
2. Record concrete blocker using --override.
3. Capture failing command output as evidence.
4. Continue with next unblocked ID.

Commands:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature update <id> --status deferred --db porting.db \
  --override "blocked: <specific missing dependency/runtime/infrastructure>"

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test update <id> --status deferred --db porting.db \
  --override "blocked: <specific missing dependency/runtime/infrastructure>"

---

Task 1: Dependency Preflight and Batch Start

Files:

• Modify: porting.db

Step 1: Verify dependency batches are complete

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 4 --db porting.db
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 6 --db porting.db

Step 2: Start Batch 9 only if dependencies are complete

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch start 9 --db porting.db

Step 3: Run checkpoint protocol and commit preflight evidence

---

Task 2: Implement Feature Group F1 (Auth + DirStore + Expiration Heap Primitives)

IDs: 361,793,794,817,818,819,820,821

Files:

• Modify: dotnet/src/ZB.MOM.NatsNet.Server/ClientConnection.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Accounts/DirJwtStore.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Accounts/DirectoryStoreTests.cs
• Modify/Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ServerTests.cs
• Modify: porting.db

Step 1: Mark F1 as stub

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "361,793,794,817,818,819,820,821" --set-status stub --db porting.db --execute

Step 2: Write/adjust failing tests for pinned-cert and DirStore parity methods

Step 3: Run focused tests and confirm FAIL first

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~DirectoryStoreTests|FullyQualifiedName~ServerTests" --verbosity normal

Step 4: Implement mapped F1 methods using Per-Feature Verification Loop

Step 5: Re-run focused tests and require PASS

Use same command as Step 3, require Failed: 0.

Step 6: Run Stub Detection + Build Gate + Test Gate

Step 7: Promote F1 to complete then verified

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "361,793,794,817,818,819,820,821" --set-status complete --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "361,793,794,817,818,819,820,821" --set-status verified --db porting.db --execute

Step 8: Run checkpoint protocol and commit

---

Task 3: Implement Feature Group F2 (OCSP Monitor Core + Helper Functions)

IDs: 2443,2444,2445,2446,2447,2448,2457,2458,2459,2460,2461,2462

Files:

• Modify: dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspTypes.cs
• Create: dotnet/src/ZB.MOM.NatsNet.Server/Auth/Ocsp/OcspHandler.cs
• Modify/Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspResponseCacheTests.cs
• Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspFoundationTests.cs
• Modify: porting.db

Step 1: Mark F2 as stub

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2443,2444,2445,2446,2447,2448,2457,2458,2459,2460,2461,2462" --set-status stub --db porting.db --execute

Step 2: Add failing OCSP foundation tests (status selection, cert parsing, issuer lookup, status-string, response validity)

Step 3: Run focused tests and confirm FAIL

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~OcspFoundationTests|FullyQualifiedName~OcspResponseCacheTests|FullyQualifiedName~CertificateIdentityProviderTests" --verbosity normal

Step 4: Implement F2 methods with per-feature loop

Step 5: Re-run focused tests and require PASS

Use same command as Step 3, require Failed: 0.

Step 6: Run Stub Detection + Build Gate + Test Gate

Step 7: Promote F2 to complete then verified

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2443,2444,2445,2446,2447,2448,2457,2458,2459,2460,2461,2462" --set-status complete --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2443,2444,2445,2446,2447,2448,2457,2458,2459,2460,2461,2462" --set-status verified --db porting.db --execute

Step 8: Run checkpoint protocol and commit

---

Task 4: Implement Feature Group F3 (NatsServer OCSP Wiring/Lifecycle)

IDs: 2450,2451,2452,2453,2454,2455,2456

Files:

• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Ocsp.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Init.cs
• Modify: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Lifecycle.cs
• Create/Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/NatsServerOcspTests.cs
• Modify: porting.db

Step 1: Mark F3 as stub

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2450,2451,2452,2453,2454,2455,2456" --set-status stub --db porting.db --execute

Step 2: Add failing server OCSP wiring tests (config discovery, monitor creation, store dir, reload/start behavior)

Step 3: Run focused tests and confirm FAIL

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~NatsServerOcspTests|FullyQualifiedName~OcspFoundationTests" --verbosity normal

Step 4: Implement F3 methods with per-feature loop

Step 5: Re-run focused tests and require PASS

Use same command as Step 3, require Failed: 0.

Step 6: Run Stub Detection + Build Gate + Test Gate

Step 7: Promote F3 to complete then verified

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2450,2451,2452,2453,2454,2455,2456" --set-status complete --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2450,2451,2452,2453,2454,2455,2456" --set-status verified --db porting.db --execute

Step 8: Run checkpoint protocol and commit

---

Task 5: Implement Feature Group F4 (OCSP Peer Parsing + TLS Plug/Validation)

IDs: 2463,2464,2465,2466,2467,2468,2469,2470,2471

Files:

• Create: dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.OcspPeer.cs
• Modify/Create: dotnet/src/ZB.MOM.NatsNet.Server/Auth/CertificateIdentityProvider/OcspPeerConfig.cs
• Create: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/OcspPeerValidationTests.cs
• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/Auth/CertificateIdentityProvider/CertificateIdentityProviderTests.cs
• Modify: porting.db

Step 1: Mark F4 as stub

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2463,2464,2465,2466,2467,2468,2469,2470,2471" --set-status stub --db porting.db --execute

Step 2: Add failing OCSP peer tests (config parse variants, peer chain selection, tls client/server validation hooks)

Step 3: Run focused tests and confirm FAIL

/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ \
  --filter "FullyQualifiedName~OcspPeerValidationTests|FullyQualifiedName~CertificateIdentityProviderTests" --verbosity normal

Step 4: Implement F4 methods with per-feature loop

Step 5: Re-run focused tests and require PASS

Use same command as Step 3, require Failed: 0.

Step 6: Run Stub Detection + Build Gate + Test Gate

Step 7: Promote F4 to complete then verified

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2463,2464,2465,2466,2467,2468,2469,2470,2471" --set-status complete --db porting.db --execute

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  feature batch-update --ids "2463,2464,2465,2466,2467,2468,2469,2470,2471" --set-status verified --db porting.db --execute

Step 8: Run checkpoint protocol and commit

---

Task 6: Resolve Mapped Test Group T1 (AuthCalloutTests in ImplBacklog)

IDs: 118,119,124,125,128,129,130,131,134,135

Files:

• Modify: dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ImplBacklog/AuthCalloutTests.Impltests.cs
• Modify (if needed): dotnet/src/ZB.MOM.NatsNet.Server/Auth/AuthCallout.cs
• Modify (if needed): dotnet/src/ZB.MOM.NatsNet.Server/NatsServer.Auth.cs
• Modify: porting.db

Step 1: Mark T1 as stub in one chunk (10 <= 15)

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "118,119,124,125,128,129,130,131,134,135" --set-status stub --db porting.db --execute

Step 2: For each test ID, attempt real port with Per-Test Verification Loop

Step 3: If runtime dependencies are missing (internal callout pub/sub/JWT signing pipeline), keep test deferred with reason and no fake assertions

Example defer command:

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test update <id> --status deferred --db porting.db \
  --override "blocked: requires full auth-callout runtime path (internal request/reply + signed response validation)"

Step 4: Promote only genuinely passing test IDs to verified (max 15 IDs/update)

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- \
  test batch-update --ids "<verified-ids-max15>" --set-status verified --db porting.db --execute

Step 5: Run Stub Detection + Build/Test Gates + checkpoint commit

---

Task 7: Batch 9 Final Verification and Closure

Files:

• Modify: porting.db
• Generate: reports/current.md

Step 1: Full build + full unit tests

/usr/local/share/dotnet/dotnet build dotnet/
/usr/local/share/dotnet/dotnet test dotnet/tests/ZB.MOM.NatsNet.Server.Tests/ --verbosity normal

Step 2: Run global Batch 9 stub scan on touched files

rg -n "NotImplementedException|TODO|PLACEHOLDER|Assert\.True\(true\)" \
  dotnet/src/ZB.MOM.NatsNet.Server \
  dotnet/tests/ZB.MOM.NatsNet.Server.Tests

Step 3: Validate batch visibility and statuses

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch show 9 --db porting.db
/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- report summary --db porting.db

Step 4: Attempt batch completion

/usr/local/share/dotnet/dotnet run --project tools/NatsNet.PortTracker -- batch complete 9 --db porting.db

Step 5: Generate report and final commit

./reports/generate-report.sh
git add dotnet/src/ZB.MOM.NatsNet.Server \
        dotnet/tests/ZB.MOM.NatsNet.Server.Tests \
        porting.db reports/
git commit -m "feat(batch9): implement auth/dirstore/ocsp foundations"