nsauditor-ai 0.1.68 → 0.1.70

package/README.md

@@ -17,7 +17,9 @@ NSAuditor AI is the open-source core of a privacy-first security intelligence pl
 
 ## What's New
 
-- **CE 0.1.68** (current) — paired with **EE 0.8.0** (May 2026). **24 enterprise plugins** across AWS / Azure / GCP, mapped to 10 fully-covered + 4 partial AICPA TSC controls. **MINOR VERSION MILESTONE — EE-RT.23 Move B**: EE plugin 1022 Azure scanner refactored to per-dim source attribution. Each of the 4 helpers now emits findings with its own source: `azure-nsg-auditor` / `azure-rbac-auditor` / `azure-storage-auditor` / `azure-keyvault-auditor`. Closes long-standing blocker (EE 0.6.9 R1-MEDIUM-1) for routing Azure storage findings into Appendix A "Cloud Bucket Exposure Attestation" without commingling NSG / RBAC / Key Vault. **Engine `details.category` projection contract** added (`normalizeFindings` + violation surface; additive, backward-compat). **Key Vault soc2.json gap closure — 13 new mappings** (CC6.1 + CC6.3 + C1.1 + A1.2): pre-0.8.0 Key Vault dim emitted 10 distinct `details.category` values but had ZERO soc2 routing — latent silent false-clean class closed. **Appendix A multi-cloud expansion**: 3 sources (AWS S3 + GCS + Azure Storage); `computeBucketStats` dedup key now provider-qualified (closes cross-cloud bucket-name collision). **7 same-session reviewer folds** (2 R-HIGH + 3 R-MEDIUM + 2 R-LOW; 0 R-CRITICAL). **+23 new tests / +6 new suites**. **EE regression: 5805/5805 across 907 suites; 68-session 100% green streak preserved.** **Plugin count UNCHANGED at 24**; coverage matrix UNCHANGED at 10/4/33 (pure substrate-evidence depth uplift on already-covered controls — but KV gap closure was a silent false-clean class). ⚠️ **Customer migration**: suppressions targeting `match.source: 'azure-cloud-scanner'` silently no-op post-0.8.0 — must be split into per-dim entries (see EE CHANGELOG for migration snippet).
+- **CE 0.1.69** (current) — paired with **EE 0.9.0** (May 2026). **HIPAA FRAMEWORK CYCLE — first 0.9.x release**: HIPAA Security Rule §164.312 Technical Safeguards ships as the second supported compliance framework alongside SOC 2 (closes the long-standing "planned" gap in EE's roadmap for the highest-demand next framework). **Dual-framework workflow**: use `--compliance hipaa` or `--compliance soc2,hipaa` for HIPAA-only or SOC 2 + HIPAA evidence packs from a single scan. **HIPAA coverage matrix introduced at 7 covered + 3 partial + 45 OOS** within §164.312 + entire §164.308 Administrative Safeguards + entire §164.310 Physical Safeguards (architecturally OOS for any infrastructure scanner — pair with HIPAA-focused GRC platforms like Drata HIPAA / Vanta HIPAA / Compliancy Group for §164.308 + §164.310). **HHS Required vs Addressable discipline** surfaced per control. **§164.312(c)(1) Integrity ransomware-defense substrate**: EE's `aws-backup-auditor` Logically Air-Gapped Backup Vault cross-verification produces HHS-OCR-2024-enforcement-relevant evidence on ePHI backup integrity preservation against full source-account compromise. **Per-framework SLA-citation map** in EE renderer — HIPAA reports cite §164.312(b) audit-controls cadence + §164.312(d) Person/Entity Authentication (not SOC 2 CC IDs); closes the auditor-detectable cross-framework citation leak class. **Zero BAA required** — Zero Data Exfiltration architecture means ePHI never leaves customer infrastructure. **Zero engine/CLI changes**: CE's `--compliance` flag already accepts CSV (wired since EE 0.3.0). **6 same-session reviewer folds** (2 R-HIGH defensive-coding + 2 R-MEDIUM scope-broadening + 1 R-LOW comment fix + 1 docstring strengthening; 0 R-CRITICAL). **+85 new tests across 3 new suites**: load-bearing anchor-drift defense via inheritance contract (32) + engine-end-to-end fixture tests across all 10 §164.312 controls (36) + per-framework renderer citation correctness (17). **EE regression: 5890/5890 across 928 suites; 69-session 100% green streak preserved.** **AWS-dogfood verified** against operator's test account (207 findings analyzed, per-framework citation map confirmed firing, ransomware-substrate surfaces correctly). **Plugin count UNCHANGED at 24**; SOC 2 coverage matrix UNCHANGED at 10/4/33 (additive-only cycle; no SOC 2 mappings changed). **No breaking changes** — additive only.
+
+- **CE 0.1.68** — paired with **EE 0.8.0** (May 2026). **24 enterprise plugins** across AWS / Azure / GCP, mapped to 10 fully-covered + 4 partial AICPA TSC controls. **MINOR VERSION MILESTONE — EE-RT.23 Move B**: EE plugin 1022 Azure scanner refactored to per-dim source attribution. Each of the 4 helpers now emits findings with its own source: `azure-nsg-auditor` / `azure-rbac-auditor` / `azure-storage-auditor` / `azure-keyvault-auditor`. Closes long-standing blocker (EE 0.6.9 R1-MEDIUM-1) for routing Azure storage findings into Appendix A "Cloud Bucket Exposure Attestation" without commingling NSG / RBAC / Key Vault. **Engine `details.category` projection contract** added (`normalizeFindings` + violation surface; additive, backward-compat). **Key Vault soc2.json gap closure — 13 new mappings** (CC6.1 + CC6.3 + C1.1 + A1.2): pre-0.8.0 Key Vault dim emitted 10 distinct `details.category` values but had ZERO soc2 routing — latent silent false-clean class closed. **Appendix A multi-cloud expansion**: 3 sources (AWS S3 + GCS + Azure Storage); `computeBucketStats` dedup key now provider-qualified (closes cross-cloud bucket-name collision). **7 same-session reviewer folds** (2 R-HIGH + 3 R-MEDIUM + 2 R-LOW; 0 R-CRITICAL). **+23 new tests / +6 new suites**. **EE regression: 5805/5805 across 907 suites; 68-session 100% green streak preserved.** **Plugin count UNCHANGED at 24**; coverage matrix UNCHANGED at 10/4/33 (pure substrate-evidence depth uplift on already-covered controls — but KV gap closure was a silent false-clean class). ⚠️ **Customer migration**: suppressions targeting `match.source: 'azure-cloud-scanner'` silently no-op post-0.8.0 — must be split into per-dim entries (see EE CHANGELOG for migration snippet).
 
 - **CE 0.1.67** — paired with **EE 0.7.3** (May 2026). **Critical hotfix** closing 2 production bugs surfaced by EE 0.7.2 dogfood scan: cross-version `google-auth-library` fragmentation broke SA impersonation chains (R-CRITICAL — 100% false-clean impact on free-trial/gmail GCP customers + business GCP customers with no-long-lived-SA-keys policy); `GOOGLE_CLOUD_PROJECT_ID` env-var alias silently skipped (R-MEDIUM). +14 new tests across 2 new suites. EE regression 5782/5782 across 900 suites; 67-session 100% green streak preserved.
 
@@ -33,7 +35,7 @@ For prior releases, see [CHANGELOG.md](./CHANGELOG.md).
 
 → **[See a sample scan walk-through](https://www.nsauditor.com/ai/docs/sample-scan/)** — full EE 0.6.7 output against a fictional Acme Corp AWS account + home-office router. Real engine output, synthetic data, no signup required.
 
-→ **[NSAuditor AI Enterprise Edition](https://www.nsauditor.com/ai/enterprise/)** — 22 cloud plugins, signed SOC 2 evidence with RFC 3161 timestamps, native Vanta / Drata / Secureframe push, runs entirely inside your infrastructure (zero data exfiltration by architecture). Pricing from **$2k/yr (5 seats)** to **$10k+/yr (unlimited + custom SLA)**.
+→ **[NSAuditor AI Enterprise Edition](https://www.nsauditor.com/ai/enterprise/)** — 24 cloud plugins across AWS / Azure / GCP, signed SOC 2 + HIPAA §164.312 evidence with RFC 3161 timestamps, native Vanta connector (Drata / Secureframe planned), runs entirely inside your infrastructure (zero data exfiltration by architecture; no BAA required for HIPAA — ePHI never leaves customer infrastructure). Pricing from **$2k/yr (5 seats)** to **$10k+/yr (unlimited + custom SLA)**.
 
 ---
 
@@ -72,7 +74,8 @@ NSAuditor AI is available in three editions:
 | Advanced CTEM + trend analysis | — | ✅ | ✅ |
 | Cloud scanners (AWS/GCP/Azure) | — | — | ✅ |
 | Zero Trust assessment | — | — | ✅ |
-| SOC 2 compliance (10 covered + 4 partial controls post-EE 0.3.9; AWS + Azure + GCP evidence streams; PI1.5 stored-items partial via DynamoDB audit-the-auditor) | — | — | ✅ |
+| SOC 2 compliance (10 covered + 4 partial controls; AWS + Azure + GCP evidence streams; PI1.5 stored-items partial via DynamoDB audit-the-auditor) | — | — | ✅ |
+| **HIPAA §164.312 Technical Safeguards** (NEW EE 0.9.0 — 7 covered + 3 partial + 45 OOS; §164.308 admin + §164.310 physical architecturally OOS; per-control HHS Required/Addressable discipline; **Zero BAA required**) | — | — | ✅ |
 | SLA/MTTR tracking + compensating controls | — | — | ✅ |
 | Recurring-scan attestation (Type II evidence) | — | — | ✅ |
 | GRC platform connector (Vanta) | — | — | ✅ |
@@ -231,6 +234,7 @@ Results land in `./out/<host>_<timestamp>/`:
 | 1190 | AWS SES Email Integrity | Enterprise | 6 dimensions: DKIM enablement + CNAME DNS resolution + key-fingerprint pin, DMARC TXT parsing + alignment classifier, custom MailFrom alignment, config-set TLS enforcement, sending-auth policy wildcards, dedicated IP pool, suppression list (count-only — ZDE invariant: never reads addresses). **CC6.1 / CC6.6 / C1.1 / CC7.1 / Privacy** |
 | 1200 | AWS Inspector2 / GuardDuty Enablement | Enterprise | 4 dimensions across all opted-in regions (17+ incl. GovCloud / ISO): GuardDuty Detector + protection features (S3 / EKS / EBS-malware / RDS-login / Lambda / RuntimeMonitoring), Inspector2 enablement, scan-target coverage. Plus alerting-destination dim (EventBridge or SecurityHub) and per-target liveness probes for Lambda / SNS / SQS / IAM / API destination / CloudWatch Logs. **CC7.1 / CC7.2** |
 | — | SOC 2 Compliance Engine | Enterprise | AICPA TSC 2017 mapping (10 covered + 4 partial controls), chain-of-custody, RFC 3161 timestamps, suppression workflow with Ed25519 signing. |
+| — | **HIPAA Compliance Engine (NEW EE 0.9.0)** | Enterprise | HIPAA Security Rule §164.312 Technical Safeguards mapping (7 covered + 3 partial + 45 OOS within §164.312 + entire §164.308 + entire §164.310). HHS Required/Addressable discipline per control. Same institutional-grade evidence infrastructure as SOC 2 (chain-of-custody, RFC 3161 timestamps, Ed25519 suppression signing). Use `--compliance hipaa` or `--compliance soc2,hipaa` for dual-framework reports from a single scan. **Zero BAA required** — Zero Data Exfiltration architecture means ePHI never leaves customer infrastructure. |
 | — | SLA & MTTR Tracking | Enterprise | Per-severity SLA targets, compensating-control flow, finding lifecycle, Type II rolling-quarter cadence. |
 | — | Recurring-Scan Attestation | Enterprise | Multi-scan chronological matrix, cadence gap detection, scope-drift surface (CC8.1). |
 | — | GRC Platform Connector | Enterprise | Native API push to Vanta / Drata / Secureframe with retry/backoff, idempotency, rate-limit handling, per-tenant token rotation. |
@@ -543,7 +547,7 @@ nsauditor-ai --version     (or -v, or `version`)
 | `--interval <min>` | Rescan interval in minutes (requires `--watch`) | `60` |
 | `--webhook-url <url>` | Webhook URL for delta alerts | — |
 | `--alert-severity <sev>` | Minimum severity for webhook alerts | `high` |
-| `--compliance <fw>` | Compliance framework to map findings into (e.g. `soc2`). **Enterprise license required.** See `@nsasoft/nsauditor-ai-ee` README for supported frameworks | — |
+| `--compliance <fw>` | Compliance framework to map findings into. Accepts CSV for multi-framework runs (e.g. `soc2`, `hipaa`, `soc2,hipaa`). **Enterprise license required.** Supported frameworks as of EE 0.9.0: `soc2` (AICPA TSC 2017) + `hipaa` (HIPAA Security Rule §164.312 Technical Safeguards, 2013 Final Rule). See `@nsasoft/nsauditor-ai-ee` README for per-framework coverage details. | — |
 | `--compliance-scope <path>` | Optional JSON file describing the assessment scope (passed to the compliance engine for cover-page attestation) | — |
 | `--help`, `-h` | Print usage block (subcommands, flags, env vars, examples) and exit 0 | — |
 | `--version`, `-v` | Print `nsauditor-ai <version>` and exit 0 | — |

package/data/license-revocations.json

@@ -0,0 +1,7 @@
+{
+  "schema_version": 1,
+  "issued_at": "2026-05-22T00:00:00.000Z",
+  "revoked": [],
+  "signature": "",
+  "_comment": "Initial CE 0.1.70 empty blocklist. The license-manager service signs this envelope with the production ES256 private key (same key as JWT signing) and ships updates via CE patch releases. An empty/unsigned blocklist is a valid initial state — the verifier returns [] on signature failure (fail-open at the blocklist layer; tampering provides no escalation since the file lives inside the npm package and supply-chain attackers already have full privilege)."
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nsauditor-ai",
-  "version": "0.1.68",
+  "version": "0.1.70",
   "description": "Modular AI-assisted network security audit platform — Community Edition",
   "type": "module",
   "private": false,
@@ -16,6 +16,7 @@
   "files": [
     "bin/",
     "config/",
+    "data/",
     "docs/EULA-nsauditor-ai.md",
     "plugins/",
     "utils/",

package/utils/license.mjs

@@ -5,11 +5,32 @@
 // KEY ROTATION: If the private key is compromised, generate a new EC P-256 key
 // pair, update PUBLIC_KEY_PEM below, and ship a CE update. All existing JWTs
 // become invalid. See license-manager docs/architecture.md for full procedure.
+//
+// CE 0.1.70 (EE 0.9.1 paired) — air-gap operational hardening per external
+// audit 2026-05-22:
+//   • D-HIGH-1: per-host licenseId replay defense (persisted on first
+//     activation; subsequent loads with a different licenseId fail-closed
+//     to CE). Closes the seat-cloning class — a `seats:N` token cannot be
+//     installed on N+1 machines without operator-noticeable rejection.
+//   • D-HIGH-2: signed revocation blocklist baked into the package
+//     (`data/license-revocations.json`). The license-manager service
+//     signs the envelope with the production ES256 key; this verifier
+//     validates the signature before honoring the revocation list.
+//     Vendors can revoke individual licenses via CE patch bump without
+//     PUBLIC_KEY_PEM rotation (which would invalidate ALL licenses).
+//   • D-HIGH-3: monotonic-clock anchor — persisted `last_seen_unix_ts`
+//     is checked on each load; a wall-clock rewind beyond CLOCK_ROLLBACK
+//     _TOLERANCE_S fails-closed to CE. Defeats `faketime`-style attacks
+//     against the JWT `exp` claim in air-gap deployments where NTP cannot
+//     be consulted at verification time.
 
 import { jwtVerify, importSPKI } from 'jose';
 import { promises as fsp } from 'node:fs';
+import * as fsSync from 'node:fs';
 import { homedir, platform } from 'node:os';
 import { dirname, join } from 'node:path';
+import { createPublicKey, createVerify } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
 import dotenv from 'dotenv';
 import { keychainGet, keychainSet, resolveSecret } from './keychain.mjs';
 
@@ -25,6 +46,69 @@ u8cSY2dN6mfevYnOydP0SXLHCfWHr+SlpZpA2BiU6GKEk+QdIlWXOgGZsA==
 // CE (Community Edition) is free and always works without a license.
 let _verifiedTier = null;
 
+// ── CE 0.1.70 — Air-gap hardening constants ──────────────────────────────────
+//
+// Wall-clock rewind tolerance: a 5-minute slack covers NTP step adjustments,
+// DST transitions on misconfigured systems, and brief clock skew between
+// suspend/resume cycles. Beyond this, treat as clock-rollback attempt.
+// Tunable via NSAUDITOR_LICENSE_CLOCK_TOLERANCE_S for support-only use.
+const CLOCK_ROLLBACK_TOLERANCE_S = 5 * 60;
+
+// Persisted state file basename. Lives at:
+//   • Linux:   $XDG_STATE_HOME/nsauditor/license-state.json
+//              (falls back to ~/.local/state/nsauditor/license-state.json,
+//              then ~/.nsauditor/license-state.json)
+//   • Windows: %LOCALAPPDATA%\nsauditor\license-state.json
+//   • macOS:   ~/.nsauditor/license-state.json (licenseId ALSO persisted in
+//              Keychain via service=nsauditor-ai account=NSAUDITOR_LICENSE_ID;
+//              Keychain wins on read when both exist).
+const LICENSE_STATE_BASENAME = 'license-state.json';
+const LICENSE_ID_KEYCHAIN_ACCOUNT = 'NSAUDITOR_LICENSE_ID';
+
+// Shipped revocation blocklist. ES256-signed envelope at this path; updated
+// by the license-manager service and shipped in each CE patch via the
+// package.json `files` array. Verifier reads, validates signature against
+// the same PUBLIC_KEY_PEM above, and returns the `revoked` array.
+const REVOCATION_BLOCKLIST_PATH = fileURLToPath(
+  new URL('../data/license-revocations.json', import.meta.url),
+);
+
+// Escape-hatch env vars — DOCUMENTED AS SUPPORT-ONLY. Operators with edge-
+// case deployment requirements (hardware migration without vendor support,
+// emergency clock rollback for a stuck system, etc.) can disable individual
+// defenses. Accepted disable values per `_envDisabled` are case-insensitive:
+// `0` / `false` / `no` / `off` / `disabled`. Default ENABLED for all three.
+//
+// Persistent audit trail (operator-visible record of which defenses were
+// disabled across loadLicense calls) is deferred to CE 0.1.71 — see
+// `tasks/external-audit-findings-2026-05-22.md` next-cycle item. For 0.9.1
+// the disables are runtime-only; operators concerned about defense hygiene
+// should grep their env for these names at deployment time.
+const ENV_REPLAY_DEFENSE = 'NSAUDITOR_LICENSE_ID_REPLAY_DEFENSE';
+const ENV_REVOCATION_CHECK = 'NSAUDITOR_LICENSE_REVOCATION_CHECK';
+const ENV_CLOCK_ANCHOR = 'NSAUDITOR_LICENSE_CLOCK_ANCHOR';
+
+// P1.D R2-HIGH fold: accept all common falsy notations + normalize case
+// per [[aws_string_case_normalization]] discipline. Operators who set
+// `=False` (capital F) or `=off` or `=no` previously left the defense
+// enabled — silently broke the support-only docstring promise.
+const _ENV_DISABLE_VALUES = new Set(['0', 'false', 'no', 'off', 'disabled']);
+function _envDisabled(name) {
+  const raw = process.env[name];
+  if (raw === undefined || raw === null) return false;
+  return _ENV_DISABLE_VALUES.has(String(raw).trim().toLowerCase());
+}
+
+function _resolveClockToleranceS() {
+  const v = parseInt(process.env.NSAUDITOR_LICENSE_CLOCK_TOLERANCE_S ?? '', 10);
+  if (!Number.isFinite(v) || v < 0) return CLOCK_ROLLBACK_TOLERANCE_S;
+  // P1.D R2-MED fold: cap at 24h. Anything beyond a day is not a "clock
+  // skew" — it's a backdoor disable of D-HIGH-3 without going through the
+  // documented NSAUDITOR_LICENSE_CLOCK_ANCHOR=0 escape hatch. Cap surfaces
+  // the abuse via the more-visible explicit env var.
+  return Math.min(v, 24 * 60 * 60);
+}
+
 /**
  * Synchronous tier detection.
  * Returns 'pro' | 'enterprise' | 'ce'.
@@ -269,6 +353,228 @@ export function mergeLicenseIntoEnvFile(existingContent, key) {
   return `${existingContent}${sep}${newLine}\n`;
 }
 
+// ── CE 0.1.70 — Air-gap hardening helpers (D-HIGH-1, D-HIGH-2, D-HIGH-3) ─────
+
+/**
+ * Resolve the platform-appropriate path to the persisted license-state file.
+ * Tracks `licenseId` (replay defense) and `lastSeenUnixTs` (clock anchor).
+ *
+ * The state file is mode 0600 (POSIX) or profile-ACL-restricted (Windows).
+ * macOS additionally persists `licenseId` to the Keychain via the
+ * keychainGet/keychainSet helpers; the state file is the source of truth
+ * for `lastSeenUnixTs` on every platform.
+ *
+ * Exported for test inspection.
+ * @internal
+ */
+export function _getLicenseStateFilePath(opts = {}) {
+  if (opts._stateFile) return opts._stateFile;
+  // Env-var override (test infra + advanced operators who want a custom path).
+  // Honors the same NSAUDITOR_LICENSE_STATE_FILE shape used by existing
+  // tests to redirect to a temp directory during test runs.
+  if (process.env.NSAUDITOR_LICENSE_STATE_FILE) {
+    return process.env.NSAUDITOR_LICENSE_STATE_FILE;
+  }
+  const plat = opts._platform ?? platform();
+  if (plat === 'win32') {
+    const base = process.env.LOCALAPPDATA
+      ?? join(homedir(), 'AppData', 'Local');
+    return join(base, 'nsauditor', LICENSE_STATE_BASENAME);
+  }
+  // Linux: prefer XDG_STATE_HOME; fall back to ~/.local/state; finally
+  // co-locate with the existing ~/.nsauditor/.env for operators who
+  // already know that directory.
+  const xdgState = process.env.XDG_STATE_HOME;
+  if (xdgState) {
+    return join(xdgState, 'nsauditor', LICENSE_STATE_BASENAME);
+  }
+  return join(homedir(), '.nsauditor', LICENSE_STATE_BASENAME);
+}
+
+/**
+ * Read the persisted license-state file. Returns `{ licenseId, lastSeenUnixTs }`
+ * or `null` when the file does not exist or cannot be parsed.
+ *
+ * On macOS we additionally consult the Keychain for `licenseId`; when both
+ * exist and disagree, Keychain wins (it's the more tamper-resistant store).
+ * @internal
+ */
+export async function _readLicenseState(opts = {}) {
+  const statePath = _getLicenseStateFilePath(opts);
+  let state = null;
+  try {
+    const text = await fsp.readFile(statePath, 'utf8');
+    const parsed = JSON.parse(text);
+    if (parsed && typeof parsed === 'object') {
+      state = {
+        licenseId: typeof parsed.licenseId === 'string' ? parsed.licenseId : null,
+        lastSeenUnixTs: Number.isFinite(parsed.lastSeenUnixTs)
+          ? parsed.lastSeenUnixTs
+          : null,
+      };
+    }
+  } catch { /* missing or malformed — treat as no state */ }
+
+  const plat = opts._platform ?? platform();
+  // Skip Keychain when the state-file env override is set: that's the
+  // test-mode signal (no test should write to the operator's real
+  // Keychain, and no test should read from it either — bleeds state
+  // across test cases via a side channel).
+  if (plat === 'darwin' && !process.env.NSAUDITOR_LICENSE_STATE_FILE) {
+    const kget = opts._keychainGet ?? keychainGet;
+    try {
+      const kcId = await kget(LICENSE_ID_KEYCHAIN_ACCOUNT);
+      if (kcId) {
+        state = state ?? { licenseId: null, lastSeenUnixTs: null };
+        state.licenseId = kcId; // Keychain wins
+      }
+    } catch { /* keychain unavailable — keep state-file value */ }
+  }
+  return state;
+}
+
+/**
+ * Persist license state (licenseId + lastSeenUnixTs) atomically.
+ * Writes to `${path}.tmp` then renames; survives partial-crash without
+ * leaving an in-flight half-written state file.
+ *
+ * On macOS the licenseId is ALSO written to the Keychain (best-effort;
+ * a Keychain failure does not abort the file write since the file is the
+ * cross-platform fallback path).
+ *
+ * @internal
+ */
+export async function _writeLicenseState(state, opts = {}) {
+  const statePath = _getLicenseStateFilePath(opts);
+  const dir = dirname(statePath);
+  await fsp.mkdir(dir, { recursive: true, mode: 0o700 });
+  const body = JSON.stringify({
+    schema_version: 1,
+    licenseId: state.licenseId ?? null,
+    lastSeenUnixTs: Number.isFinite(state.lastSeenUnixTs) ? state.lastSeenUnixTs : null,
+  }, null, 2);
+  const tmp = `${statePath}.tmp`;
+  await fsp.writeFile(tmp, body, { mode: 0o600 });
+  await fsp.rename(tmp, statePath);
+  // Re-chmod on overwrite (writeFile honors mode only on CREATE).
+  const plat = opts._platform ?? platform();
+  if (plat !== 'win32') {
+    try { await fsp.chmod(statePath, 0o600); } catch { /* not fatal */ }
+  }
+  // Skip Keychain when the state-file env override is set: matches the
+  // read-side test-mode-skip in _readLicenseState so the test suite's
+  // per-case file-path isolation isn't bypassed by the macOS Keychain
+  // side channel.
+  if (plat === 'darwin' && state.licenseId && !process.env.NSAUDITOR_LICENSE_STATE_FILE) {
+    const kset = opts._keychainSet ?? keychainSet;
+    try { await kset(LICENSE_ID_KEYCHAIN_ACCOUNT, state.licenseId); } catch { /* not fatal */ }
+  }
+}
+
+/**
+ * Load and verify the shipped revocation blocklist. Returns the list of
+ * revoked licenseId strings on success, or `[]` on ANY failure (file
+ * missing, malformed JSON, invalid signature, unsupported schema version).
+ *
+ * Fail-open posture on tampering is deliberate: the blocklist lives in the
+ * package's `data/` directory, which is only writable by parties who
+ * already have the privilege to swap binaries (i.e., supply-chain
+ * attackers); for those, tampering provides no additional escalation. A
+ * fail-closed posture (refuse ALL licenses when the blocklist is corrupt)
+ * would brick legitimate customers via a single bad CE patch.
+ *
+ * Test seam: `opts._blocklistData` short-circuits the file load and
+ * returns a pre-loaded array. `opts._publicKeyPem` overrides the embedded
+ * production key for signature-verification unit tests.
+ *
+ * @internal
+ */
+export async function _loadAndVerifyBlocklist(opts = {}) {
+  if (Array.isArray(opts._blocklistData)) {
+    return opts._blocklistData;
+  }
+  // Env-var override mirrors the state-file env override pattern; lets
+  // existing tests redirect to a temp file without touching loadLicense
+  // call sites.
+  const path = opts._blocklistPath
+    ?? process.env.NSAUDITOR_LICENSE_REVOCATIONS_FILE
+    ?? REVOCATION_BLOCKLIST_PATH;
+  let raw;
+  try {
+    raw = await fsp.readFile(path, 'utf8');
+  } catch { return []; }
+
+  let envelope;
+  try {
+    envelope = JSON.parse(raw);
+  } catch { return []; }
+
+  if (!envelope || typeof envelope !== 'object') return [];
+  if (envelope.schema_version !== 1) return [];
+  if (!Array.isArray(envelope.revoked)) return [];
+
+  const publicKeyPem = opts._publicKeyPem ?? PUBLIC_KEY_PEM;
+  if (!_verifyBlocklistSignature(envelope, publicKeyPem)) return [];
+
+  return envelope.revoked.filter((s) => typeof s === 'string' && s.length > 0);
+}
+
+/**
+ * Verify the ES256 detached signature over the blocklist envelope. The
+ * signature covers the canonical JSON of the envelope MINUS the
+ * `signature` field itself: `JSON.stringify({schema_version, issued_at, revoked})`
+ * with stable key order.
+ *
+ * Signature is base64-encoded over the SHA-256-of-canonical-JSON,
+ * verified against the ES256 (P-256) public key.
+ *
+ * Returns `true` only on cryptographic match; any error returns `false`
+ * (fail-open at the blocklist layer is documented in _loadAndVerifyBlocklist).
+ *
+ * @internal
+ */
+export function _verifyBlocklistSignature(envelope, publicKeyPem) {
+  if (!envelope || typeof envelope.signature !== 'string') return false;
+  if (envelope.signature.length === 0) return false;
+  const canonical = _canonicalizeBlocklistForSigning(envelope);
+  if (!canonical) return false;
+  try {
+    const sigBuf = Buffer.from(envelope.signature, 'base64');
+    const pub = createPublicKey({ key: publicKeyPem, format: 'pem' });
+    // P1.D R2-HIGH fold: pin to ES256 (EC P-256) algorithm explicitly.
+    // Without this assertion, a future PUBLIC_KEY_PEM rotation to an RSA
+    // key would silently enable RS256 forgery of the blocklist (the
+    // verify code path is generic over algorithm). Mirror of the audit's
+    // own canonical-JWT-verifier hardening pattern.
+    if (pub.asymmetricKeyType !== 'ec') return false;
+    const details = pub.asymmetricKeyDetails;
+    if (!details || details.namedCurve !== 'prime256v1') return false;
+    const verifier = createVerify('SHA256');
+    verifier.update(canonical, 'utf8');
+    verifier.end();
+    return verifier.verify({ key: pub, dsaEncoding: 'der' }, sigBuf);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Canonical signing input: stable key order, no signature field.
+ * @internal
+ */
+export function _canonicalizeBlocklistForSigning(envelope) {
+  if (!envelope || typeof envelope !== 'object') return null;
+  const canonical = {
+    schema_version: envelope.schema_version,
+    issued_at: envelope.issued_at,
+    revoked: Array.isArray(envelope.revoked) ? [...envelope.revoked] : [],
+  };
+  // Deterministic stringification: sort revoked alphabetically to remove
+  // ordering ambiguity from the signing input.
+  canonical.revoked.sort();
+  return JSON.stringify(canonical);
+}
+
 /**
  * Full async JWT verification. Call once at startup.
  * On success, caches verified tier so subsequent getTierFromEnv() calls
@@ -279,10 +585,12 @@ export function mergeLicenseIntoEnvFile(existingContent, key) {
  * @param {string} [keyStr] - License key; if omitted, runs the multi-source
  *   resolution chain (env var → Keychain → ~/.nsauditor/.env). See
  *   resolveLicenseKey() above.
+ * @param {object} [opts] - Test seams (see internal helpers). All options
+ *   prefixed with `_` are documented as test-only.
  * @returns {Promise<{valid: boolean, tier: string, org?: string, seats?: number,
  *   licenseId?: string, capabilities?: string[], expiresAt?: string, reason?: string}>}
  */
-export async function loadLicense(keyStr) {
+export async function loadLicense(keyStr, opts = {}) {
   // Explicit keyStr argument wins (preserves the existing behavior for
   // callers like the `license --status` subcommand which passes the env
   // var directly). When omitted, run the multi-source resolution chain.
@@ -326,6 +634,61 @@ export async function loadLicense(keyStr) {
       return { valid: false, tier: 'ce', reason: 'tier mismatch' };
     }
 
+    // ── CE 0.1.70 air-gap hardening: 3 fail-closed checks ────────────────
+    // Order matters. (1) Revocation runs first — a revoked license should
+    // be rejected even before the per-host bind. (2) Replay defense second
+    // — a non-revoked but mismatched-host install is the next-most-likely
+    // abuse path. (3) Clock anchor third — only relevant if the prior two
+    // pass; a clock-rollback attack against a legitimately installed
+    // license is the least-common case. Each check has an env-var escape
+    // hatch documented as support-only.
+
+    const now = (opts._now ?? Date.now)();
+
+    // (1) D-HIGH-2: signed revocation blocklist.
+    if (!_envDisabled(ENV_REVOCATION_CHECK)) {
+      try {
+        const revoked = await _loadAndVerifyBlocklist(opts);
+        if (payload.licenseId && revoked.includes(payload.licenseId)) {
+          _verifiedTier = 'ce';
+          return { valid: false, tier: 'ce', reason: 'license_revoked' };
+        }
+      } catch { /* fail-open per _loadAndVerifyBlocklist contract */ }
+    }
+
+    // Read prior persisted state once for checks (2) + (3) + first-activation write.
+    let persistedState = null;
+    try { persistedState = await _readLicenseState(opts); } catch { /* missing fine */ }
+
+    // (2) D-HIGH-1: per-host licenseId replay defense.
+    if (!_envDisabled(ENV_REPLAY_DEFENSE)) {
+      if (persistedState && persistedState.licenseId
+          && payload.licenseId
+          && persistedState.licenseId !== payload.licenseId) {
+        _verifiedTier = 'ce';
+        return { valid: false, tier: 'ce', reason: 'license_id_mismatch' };
+      }
+    }
+
+    // (3) D-HIGH-3: monotonic-clock anchor.
+    if (!_envDisabled(ENV_CLOCK_ANCHOR)) {
+      if (persistedState && Number.isFinite(persistedState.lastSeenUnixTs)) {
+        const tolerance = _resolveClockToleranceS() * 1000;
+        if (now < persistedState.lastSeenUnixTs - tolerance) {
+          _verifiedTier = 'ce';
+          return { valid: false, tier: 'ce', reason: 'clock_rollback_detected' };
+        }
+      }
+    }
+
+    // All checks passed — update state (first-activation persist + heartbeat).
+    try {
+      await _writeLicenseState({
+        licenseId: payload.licenseId ?? persistedState?.licenseId ?? null,
+        lastSeenUnixTs: now,
+      }, opts);
+    } catch { /* state write failure must not block a verified license */ }
+
     // Cache verified tier for synchronous access
     _verifiedTier = payload.tier;
 
@@ -366,6 +729,11 @@ export async function loadLicense(keyStr) {
 /**
  * @internal Test-only. Reset cached verified tier between tests.
  * Disabled in production to prevent accidental tier cache clearing.
+ *
+ * Clears in-memory state only (`_verifiedTier` + permissive-warned-paths).
+ * Does NOT touch the persisted license-state file — tests that need that
+ * cleared should either rotate the state-file path via beforeEach OR call
+ * `_clearLicenseStateFileForTests()` explicitly.
  */
 export function _resetCache() {
   if (process.env.NODE_ENV === 'production') {
@@ -374,3 +742,19 @@ export function _resetCache() {
   _verifiedTier = null;
   _permissiveWarnedPaths.clear();
 }
+
+/**
+ * @internal Test-only. Remove the persisted license-state file at the path
+ * resolved by the env var or platform default. Refuses to touch the real
+ * platform-default path (only honors NSAUDITOR_LICENSE_STATE_FILE override)
+ * so a production process that accidentally imports this helper cannot
+ * wipe operator state.
+ */
+export function _clearLicenseStateFileForTests() {
+  if (process.env.NODE_ENV === 'production') {
+    throw new Error('_clearLicenseStateFileForTests is test-only');
+  }
+  const override = process.env.NSAUDITOR_LICENSE_STATE_FILE;
+  if (!override) return; // refuse to touch platform default
+  try { fsSync.unlinkSync(override); } catch { /* not fatal — file may not exist */ }
+}