Add crypto boundary self tests

Author: 01rabbit

README.md

@@ -303,6 +303,8 @@ PHANTASM_STATE_DIR=/path/to/state python3 main.py init
 
 Phantasm is intended for localhost or USB Ethernet gadget access. It should not be exposed to an untrusted network and should not be deployed as an Internet-facing service. Remote management, telemetry, cloud unlock, and analytics are intentionally out of scope.
 
+At startup, Phantasm runs local primitive self-tests for the cryptographic operations it depends on. These checks improve failure detection and reviewability; they are not a validated cryptographic-module certification.
+
 Restricted local data-loss behavior should be understood primarily as key-material destruction and local access-path invalidation. Best-effort overwrite may be attempted, but SD card behavior means overwrite must not be treated as guaranteed secure deletion.
 
 For high-risk deployments, do not store all recovery conditions on the same physical medium. Phantasm is strongest when the encrypted container, local state, memorized password, physical-object cue, and optional external key material are separated.

docs/REVIEW_VALIDATION_RECORD.md

@@ -24,7 +24,7 @@ python3 -m unittest discover -s tests
 Result:
 
 ```text
-2026-05-02, macOS Darwin arm64, python3 -m unittest discover -s tests, 147 tests passed.
+2026-05-02, macOS Darwin arm64, python3 -m unittest discover -s tests, 151 tests passed.
 ```
 
 Restricted-flow scenario matrix:

docs/SPECIFICATION.md

@@ -54,6 +54,12 @@ The default state directory is `.state/` and can be changed with `PHANTASM_STATE
 
 New local state code paths should use the typed state store for schema-versioned records, atomic writes, restrictive file permissions, and explicit transition checks. Existing binary state files remain compatibility-managed by their owning modules until a migration path is defined.
 
+## 4.1 Cryptographic Boundary
+
+Phantasm defines a local cryptographic primitive boundary in `src/phantasm/crypto_boundary.py`. Startup checks cover AES-GCM round trip behavior, HMAC-SHA-256 behavior, and random byte generation health. Failure causes local startup to stop with a neutral message in the CLI path.
+
+This boundary improves reviewability and failure detection. It is not a FIPS validation, certification claim, or replacement for independent cryptographic review.
+
 ## 5. Internal Entry Model
 
 The container uses two fixed internal storage spans. The CLI keeps a compact `--entry a` / `--entry b` selector for compatibility, while WebUI v2 maps the internal model to neutral protected-entry workflows and does not expose internal labels during normal operation.

docs/THREAT_MODEL.md

@@ -34,6 +34,7 @@ It is not a substitute for audited full-disk encryption, hardware-backed key sto
 ## Current Defenses
 
 - New stores use GhostVault v3 records: random per-record Argon2id salt, random per-record AES-GCM nonce, no plaintext magic/header, and AEAD-authenticated encrypted metadata.
+- Startup self-tests check local AES-GCM, HMAC-SHA-256, and random byte generation behavior before normal CLI/WebUI operation.
 - The local access key is mixed into Argon2id by default, so copying `vault.bin` alone is insufficient for recovery.
 - Protected entries can be stored with normal access and restricted recovery passwords that share the same object cue.
 - Store flows reject empty, duplicate, short, or highly repetitive passphrases to reduce accidental weak input.
@@ -67,6 +68,7 @@ These surfaces should not reveal the internal disclosure model, internal trial o
 - If the local access key is copied with `vault.bin`, the local access-key protection does not raise attacker cost.
 - If `vault.bin`, the configured state directory, and external key material are carried together on one medium, separation benefits are reduced.
 - Secure deletion is best-effort only. SSD wear leveling, backups, snapshots, and journaling filesystems may retain previous data.
+- Startup self-tests detect some local primitive failures but are not cryptographic certification and do not prove the host is uncompromised.
 - On flash media, recovery resistance depends primarily on key-material destruction or removal, not overwrite guarantees.
 - The v3 format avoids a plaintext format marker, but surrounding tool files can still reveal that a Phantasm-style container may be in use.
 - Dual password slots duplicate encrypted payload material within the selected internal storage span. This improves operational control but reduces maximum payload size.

src/phantasm/cli.py

@@ -9,6 +9,7 @@
 from .audit import audit_event
 from .bridge_ui import ui
 from .config import duress_mode_enabled, purge_confirmation_required
+from .crypto_boundary import CryptoSelfTestError, ensure_crypto_self_tests
 from .emergency_daemon import EmergencyDaemon
 from .face_lock import face_lock
 from .gv_core import GhostVault
@@ -191,7 +192,18 @@ def _print_operation_report(report):
         print(f"- {check['name']}: {check['status']} - {check['message']}")
 
 
+def _run_startup_checks():
+    try:
+        ensure_crypto_self_tests()
+        return True
+    except CryptoSelfTestError:
+        print("[!] Startup check failed.")
+        return False
+
+
 def main():
+    if not _run_startup_checks():
+        return
     parser = argparse.ArgumentParser(description="Phantasm - Local Protected Storage")
     parser.add_argument(
         "action",

src/phantasm/crypto_boundary.py

@@ -0,0 +1,62 @@
+"""Reviewable local cryptographic primitive boundary and self-tests."""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import os
+
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+class CryptoSelfTestError(RuntimeError):
+    """Raised when a required local primitive check fails."""
+
+
+_SELF_TEST_PASSED = False
+
+
+def ensure_crypto_self_tests():
+    global _SELF_TEST_PASSED
+    if _SELF_TEST_PASSED:
+        return True
+    try:
+        _check_aes_gcm()
+        _check_hmac_sha256()
+        _check_random_bytes()
+    except Exception as exc:
+        raise CryptoSelfTestError("cryptographic self-test failed") from exc
+    _SELF_TEST_PASSED = True
+    return True
+
+
+def random_bytes(length: int):
+    if length <= 0:
+        raise ValueError("length must be positive")
+    return os.urandom(length)
+
+
+def _check_aes_gcm():
+    key = bytes.fromhex("00" * 31 + "01")
+    nonce = bytes.fromhex("00" * 11 + "01")
+    aad = b"phantasm-self-test"
+    plaintext = b"local primitive check"
+    aesgcm = AESGCM(key)
+    ciphertext = aesgcm.encrypt(nonce, plaintext, aad)
+    recovered = aesgcm.decrypt(nonce, ciphertext, aad)
+    if recovered != plaintext:
+        raise CryptoSelfTestError("aes-gcm check failed")
+
+
+def _check_hmac_sha256():
+    digest = hmac.new(b"phantasm", b"self-test", hashlib.sha256).hexdigest()
+    expected = "e22f31e13630eceeca685522387389b16ed3ef5378b55eb4f37871fd72d29cf5"
+    if not hmac.compare_digest(digest, expected):
+        raise CryptoSelfTestError("hmac check failed")
+
+
+def _check_random_bytes():
+    first = random_bytes(32)
+    second = random_bytes(32)
+    if len(first) != 32 or len(second) != 32 or first == second:
+        raise CryptoSelfTestError("random byte check failed")

src/phantasm/web_server.py

@@ -36,6 +36,7 @@
     ui_face_enrollment_enabled,
     ui_face_lock_enabled,
 )
+from .crypto_boundary import ensure_crypto_self_tests
 from .face_lock import face_lock
 from .gv_core import GhostVault
 from .metadata import metadata_risk_report, scrub_metadata
@@ -48,6 +49,13 @@
 from . import strings as text
 
 app = FastAPI(title="Phantasm - Local Secure Interface")
+
+
+@app.on_event("startup")
+async def startup_self_tests():
+    ensure_crypto_self_tests()
+
+
 templates = Jinja2Templates(directory=str(Path(__file__).with_name("templates")))
 vault = GhostVault("vault.bin")
 WEB_TOKEN = os.environ.get("PHANTASM_WEB_TOKEN") or secrets.token_urlsafe(32)

tests/test_cli.py

@@ -143,6 +143,17 @@ def check(self, _scope):
 
         self.assertIn("Access temporarily unavailable", output.getvalue())
 
+    def test_startup_check_failure_is_neutral(self):
+        output = io.StringIO()
+
+        with unittest.mock.patch.object(
+            cli, "ensure_crypto_self_tests", side_effect=cli.CryptoSelfTestError
+        ):
+            with contextlib.redirect_stdout(output):
+                self.assertFalse(cli._run_startup_checks())
+
+        self.assertIn("Startup check failed", output.getvalue())
+
 
 if __name__ == "__main__":
     unittest.main()

tests/test_crypto_boundary.py

@@ -0,0 +1,34 @@
+import os
+import sys
+import unittest
+from unittest import mock
+
+ROOT = os.path.dirname(os.path.dirname(__file__))
+sys.path.insert(0, os.path.join(ROOT, "src"))
+
+from phantasm import crypto_boundary
+
+
+class CryptoBoundaryTests(unittest.TestCase):
+    def tearDown(self):
+        crypto_boundary._SELF_TEST_PASSED = False
+
+    def test_self_tests_pass(self):
+        self.assertTrue(crypto_boundary.ensure_crypto_self_tests())
+
+    def test_random_bytes_rejects_invalid_length(self):
+        with self.assertRaises(ValueError):
+            crypto_boundary.random_bytes(0)
+
+    def test_self_test_failure_is_neutral(self):
+        with mock.patch.object(
+            crypto_boundary, "_check_random_bytes", side_effect=RuntimeError("detail")
+        ):
+            with self.assertRaises(crypto_boundary.CryptoSelfTestError) as ctx:
+                crypto_boundary.ensure_crypto_self_tests()
+
+        self.assertEqual(str(ctx.exception), "cryptographic self-test failed")
+
+
+if __name__ == "__main__":
+    unittest.main()

tests/test_docs_and_templates.py

@@ -47,6 +47,7 @@ def test_readme_addresses_reviewer_and_use_boundaries(self):
         self.assertIn("python3 -m bandit -r src", readme)
         self.assertIn("PHANTASM_MIN_PASSPHRASE_LENGTH", readme)
         self.assertIn("PHANTASM_ACCESS_MAX_FAILURES", readme)
+        self.assertIn("not a validated cryptographic-module certification", readme)
         self.assertIn("not approved classified-data handling infrastructure", readme)
         self.assertIn("Field Mode is not a security boundary", readme)
         self.assertIn("Metadata detection and reduction are best-effort", readme)
@@ -66,6 +67,8 @@ def test_specification_defines_field_mode_and_metadata_routes(self):
         self.assertIn("Field Mode is not a security boundary", spec)
         self.assertIn("PHANTASM_MIN_PASSPHRASE_LENGTH", spec)
         self.assertIn("PHANTASM_ACCESS_LOCKOUT_SECONDS", spec)
+        self.assertIn("Cryptographic Boundary", spec)
+        self.assertIn("not a FIPS validation", spec)
 
     def test_threat_model_names_leakage_surfaces(self):
         threat = read_text("docs/THREAT_MODEL.md")