audit(security): audited assail-classifications for the 3 legitimate FFI/unsafe residuals (P5) (#51)

## Summary

Closes **G18** (P5): records Axiom's inherent, reviewed FFI/`unsafe`
boundary as **audited‑legitimate residuals** in the panic‑attack
user‑classification registry — the honest alternative to blanket
suppression or a permanently‑red gate.

## What's classified (only the 3 genuine FFI/unsafe boundaries)
| File | Category | Why it's sound |
|---|---|---|
| `crypto/src/lib.rs` | UnsafeCode | The `extern "C"` cdylib surface.
Thin shim over vetted `openssl` + `pqcrypto-dilithium`; `// SAFETY:` on
every block; caller‑allocates ABI; no hand‑rolled crypto. |
| `src/verification/signing.jl` | UnsafeFFI | Julia `ccall`/`Libdl` into
that cdylib. Optional shim; runtime ABI self‑check; per‑call length
validation. |
| `src/backends/zig_ffi.jl` | UnsafeFFI | Julia `ccall`/`Libdl` into the
Zig compute backend. Availability‑checked before any dispatch;
memory‑safety logic lives Zig‑side. |

- **`audits/audit-ffi-unsafe.adoc`** — the per‑boundary rationale (the
cited audit).
- **`audits/assail-classifications.a2ml`** — the registry, which lives
**separately from the code under scan** so a newly‑added `unsafe` block
cannot self‑suppress (the suppression only holds while the audit is kept
current).

**Nothing else is suppressed.** All ProofDrift / InputBoundary /
MutationGap findings are left **visible and un‑suppressed** — they're
tracked as ordinary findings, not audited residuals.

## Verification (ground‑truthed, not self‑graded)
Re‑ran `panic-attack assail` after adding the registry:
- Exactly the **three** classified findings flip to `suppressed=true`;
the `# SPDX` header did not break the S‑expression parse.
- The other visible findings are unchanged; **0 critical** (the
`static-analysis-gate` stays green on merit, now with the FFI boundary
honestly audited rather than noisy).

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01UPFC9YQ7g9gc3VnRox42Q1

---
_Generated by [Claude
Code](https://claude.ai/code/session_01UPFC9YQ7g9gc3VnRox42Q1)_

Co-authored-by: Claude <noreply@anthropic.com>

Author: hyperpolymath

audits/assail-classifications.a2ml

@@ -0,0 +1,22 @@
+# SPDX-License-Identifier: MPL-2.0
+# Audited legitimate residuals for `panic-attack assail`.
+# Companion audit (rationale + review): audits/audit-ffi-unsafe.adoc
+# Per the user-classification protocol this registry lives separately from the
+# code under scan, so a newly-added unsafe block cannot self-suppress — the
+# suppression only holds while the cited audit is kept current.
+(assail-classifications
+  (classification
+    (file "crypto/src/lib.rs")
+    (category "UnsafeCode")
+    (audit "audits/audit-ffi-unsafe.adoc §1")
+    (rationale "C-ABI cdylib: extern-C raw-pointer surface requires unsafe; each block has a // SAFETY comment; thin shim over vetted openssl + pqcrypto-dilithium, no hand-rolled crypto"))
+  (classification
+    (file "src/verification/signing.jl")
+    (category "UnsafeFFI")
+    (audit "audits/audit-ffi-unsafe.adoc §2")
+    (rationale "Julia ccall/Libdl into the audited axiom_crypto cdylib; optional shim with a runtime ABI self-check; buffer lengths validated against ABI constants before every ccall"))
+  (classification
+    (file "src/backends/zig_ffi.jl")
+    (category "UnsafeFFI")
+    (audit "audits/audit-ffi-unsafe.adoc §3")
+    (rationale "Julia ccall/Libdl into the Zig compute backend; availability checked before dispatch; memory-safety-critical logic lives Zig-side")))

audits/audit-ffi-unsafe.adoc

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: CC-BY-SA-4.0
+= Audit — Axiom.jl FFI / unsafe boundary
+Jonathan D.A. Jewell <j.d.a.jewell@open.ac.uk>
+:revdate: 2026-07-01
+
+Records why the three FFI / `unsafe` residuals that `panic-attack assail`
+reports for Axiom.jl are *legitimate, reviewed* boundaries rather than defects.
+This is the companion document cited by `audits/assail-classifications.a2ml`.
+Per the panic-attack user-classification protocol the classification registry
+lives in a *separate* file from the code under scan, so adding a new `unsafe`
+block cannot silently self-suppress — a suppression is only honoured while this
+audit is kept current in the same review.
+
+None of these boundaries hand-rolls cryptography or safety logic; each is the
+minimal, necessary seam between Julia and a vetted native library.
+
+== §1 — `crypto/src/lib.rs` (category: UnsafeCode)
+
+`axiom_crypto` is a thin C-ABI shim (`cdylib`) exposing hybrid Ed448 +
+Dilithium5 certificate signing to Julia. A stable C ABI necessarily uses
+`extern "C"` + `#[no_mangle]` functions taking raw pointers, which Rust
+requires to be dereferenced inside `unsafe` — the UnsafeCode finding is this
+expected surface, not a soundness hole. Sound because:
+
+* *No hand-rolled crypto.* Ed448 → system libcrypto (OpenSSL 3.x) via the vetted
+  `openssl` crate; Dilithium5 → the vetted `pqcrypto-dilithium` crate (PQClean
+  reference implementation). The crate implements no primitive of its own.
+* *Every `unsafe` block carries a `// SAFETY:` comment* stating the precondition
+  it relies on (non-null pointer; caller-allocated buffer of the ABI-declared
+  length).
+* *Caller-allocates-buffer + written-length ABI* — no allocate-and-return /
+  free-fn pairs, so there is no cross-language ownership to leak or double-free.
+* *Length-checked entry points* — each function validates slice lengths against
+  the exported `axiom_crypto_*_len()` constants and returns a negative status
+  code (never UB) on a bad length or null pointer.
+
+== §2 — `src/verification/signing.jl` (category: UnsafeFFI)
+
+Loads the `axiom_crypto` cdylib via `Libdl.dlopen` and calls it via `ccall` —
+Julia's only foreign-call mechanism, inherently flagged UnsafeFFI. Sound
+because:
+
+* The shim is *optional*: if the cdylib is unbuilt, `crypto_shim_available()`
+  returns `false` and every signing entry point throws a clear, documented error
+  rather than calling through a null handle.
+* A runtime ABI self-check (`_validate_crypto_abi!`) confirms the library's
+  reported key/signature lengths match the Julia-side constants before any
+  cryptographic `ccall` (this check caught a real length mismatch in
+  development).
+* Every sign/verify call validates buffer lengths against the ABI constants
+  before the `ccall`, so no out-of-bounds pointer crosses the boundary.
+
+== §3 — `src/backends/zig_ffi.jl` (category: UnsafeFFI)
+
+Loads the Zig compute backend (`libaxiom_zig`) via `Libdl.dlopen` and dispatches
+kernels via `ccall`. Sound because:
+
+* `init_zig_backend` checks the library file exists and wraps `dlopen` in
+  `try`/`catch`, setting an availability flag; the `@zig_call` macro refuses to
+  dispatch (`error(...)`) unless `zig_available()` is true, so no call is made
+  through a null handle.
+* The memory-safety-critical compute logic lives on the *Zig* side (a
+  memory-safe systems language); Julia holds only the thin dispatch seam.
+
+== Scope
+
+Covers ONLY the three boundaries above. All other `assail` findings (ProofDrift,
+InputBoundary, MutationGap) are deliberately left *visible and un-suppressed* —
+tracked as ordinary findings, not audited-legitimate residuals.