fix(validator): B80-1 shim — validate_structure() → Go validator authority

[itcmsgr]

Summary

B80-1 is closed behaviorally, not structurally. Full shell-file deletion and responsibility split (check_ip_or_port / get_firewall_stats / load_spec / get_live_ruleset) are deferred to v1.81.

This patch does not change rebuild ordering, CLI output format, or caller interfaces. It replaces the body of validate_structure() in cli/lib/nftban/core/nftban_validator.sh with a thin compatibility shim over the Go validator binary (nftban-validate), making validation authority Go-only at runtime while preserving backward compatibility for all existing callers.

What this patch does

• validate_structure() now calls ${NFTBAN_LIB_DIR}/bin/nftban-validate --json and translates the Go schema into the legacy shell schema {status:OK|WARNING|ERROR, errors[], warnings[], info[]}
• Legacy text output format preserved byte-for-byte (header, status line, error/warning lists) — cmd_validate.sh:103 prints this directly to the user
• $1 preserved as output_json boolean flag (true/false) controlling text vs JSON mode
• Exit codes: 0 (OK / warnings-only), 1 (validation errors / parse failure), 2 (Go binary missing — Amend-1, distinguishes "tool absent" from "tool ran but validation failed")
• jq-missing fallback (Amend-2): when jq is not installed, shim falls back to grep-based protected-detection with minimal text output, preserving the exit-code contract
• Fail-closed paths for missing-binary and empty-output use printf (not jq -n) so they work without jq
• No independent validation logic — no load_spec, no get_live_ruleset, no nft list ruleset, no spec-field references

JSON field mismatch — intentional, documented

nftban status --json currently emits .state (see cmd_status.sh:1562). The new INV-CONS-001 smoke assertion prefers canonical keys first (.status // .protection_state // .health) and falls through to .state for current-main compatibility. If the shell key is later renamed to a canonical form, the test picks it up automatically without code change.

Scope fence

TOUCHED:
  validate_structure() body in nftban_validator.sh   (ONLY this function)
  smoke_test.sh — ONE new assertion block            (INV-CONS-001)
  NEW test file test_validate_structure_is_shim.sh   (static regression guard)

NOT TOUCHED:
  check_ip_or_port() / get_firewall_stats()          (v1.81 targets)
  load_spec() / get_live_ruleset()                   (left defined, now unused)
  cmd_check.sh / cmd_firewall.sh / cmd_status.sh     (zero caller changes)
  cmd_validate.sh                                    (zero changes — it calls validate_structure as before)
  internal/nftbanconf/commands.go ValidatorScript()   (unchanged)
  no file rename, no file deletion

Patch-size framing

The raw diff reads 477 / -167, but the runtime behavioral change is narrow:

• ~60 lines actual functional shim body
• ~50 lines Amend-2 jq-missing fallback path (compatibility scaffolding)
• ~30 lines NOTE comment block inside the shim
• ~40 lines new INV-CONS-001 smoke assertion in smoke_test.sh
• ~260 lines new test_validate_structure_is_shim.sh (17-assertion regression guardrail)
• ~130 lines removed from the old batch-jq validate_structure() body

Risk surface = the 60-line shim body. Everything else is guardrail, comment, or test.

Tests (three layers of proof)

1. Static regression guard — tests/test_validate_structure_is_shim.sh (17 assertions)

Positive: body calls Go binary, builds path via $NFTBAN_LIB_DIR, contains B80-1 NOTE, preserves legacy JSON schema, maps severity levels

Negative: body does NOT call load_spec/get_live_ruleset, does NOT use --slurpfile/nft list ruleset/spec field names, body ≤260 lines, jq ≤12 invocations, has jq-missing fallback (Amend-2 contract), uses return 2 on missing binary (Amend-1 contract)

Scope fence: file still exists, check_ip_or_port() and get_firewall_stats() preserved

2. Runtime INV-CONS-001 smoke — added to smoke_test.sh run_runtime_tests

Compares nftban status --json state (extraction: .status // .protection_state // .health // .state // empty) against nftban-validate --json .status, uppercase-normalized. First positive enforcement of INV-CONS-001 at the top-level CLI truth surface.

3. Behavioural equivalence — verified locally via fake Go binary

Go input	Shell output	Exit
protected, findings=[]	{status:OK, errors:[], warnings:[]}	0
degraded, findings=[critical, error]	{status:ERROR, errors:[CRITICAL:…]}	1
protected, findings=[warn]	{status:WARNING, warnings:[WARNING:…]}	0
(binary missing)	{status:ERROR, errors:[CRITICAL: Go validator not found…]}	2

Text rendering preserved (header + ❌ ERRORS (N): + message lines).

Test plan

• Static regression guard: 17/17 PASS locally
• Behavioural equivalence: 15/15 PASS locally (hermetic, offline)
• BotGuard rebuild sequencing (cross-regression check): 10/10 PASS
• CI pipeline
• lab2 Day-6 rebuild (GATE 8 — separate workstream, not a merge gate for this PR)
• srv1 72h anchor observation (ongoing soak, not gated by this PR)

Refs

• V1.80_ROADMAP/MASTER_TODO.md B80-1 (truth consolidation)
• V1.80_ROADMAP/10_EXECUTION_PLAN.md Day 2 (legacy validator removal)
• B80-2 is separately a no-op: cmd_status.sh already calls Go binary only (line 131). Marked CLOSED as already-satisfied.

🤖 Generated with Claude Code

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 982387e.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None