docs: consolidate security review records
Jaime Fournier <jaimef@linbsd.org>
bca56aba2bb8568f35516db282cb008c240ae713
diff --git a/README.md b/README.md
index 7ff0fd3..792a325 100644
--- a/README.md
+++ b/README.md
@@ -107,6 +107,13 @@ README did not cover:
See [`docs/whats-new.md`](docs/whats-new.md) for the detailed module
notes and examples.
+## Documentation
+
+Use [`docs/index.md`](docs/index.md) as the maintained map for the language
+repository. Stable language, library, build, and security references live at
+top-level `docs/`; dated audits and review records live under
+[`docs/reviews/`](docs/reviews/).
+
## Examples
### Persistent HAMT Map
diff --git a/docs/ffi-audit.md b/docs/ffi-audit.md
index 291a44b..291bf47 100644
--- a/docs/ffi-audit.md
+++ b/docs/ffi-audit.md
@@ -80,6 +80,6 @@ Remaining work before closing K3-P1-01:
unexport or document unused exports.
- Keep `vendor/jsqlite` in the TCB until consumers move to the Rust sqlite
path. The accepted-risk decision is now recorded in
- `docs/vendor-jsqlite-tcb.md`, and `make audit` runs
+ `docs/reviews/2026-07-27-vendor-jsqlite-tcb.md`, and `make audit` runs
`vendor-jsqlite-security-check` to fail stale advisory reviews or drift
between the decision record and `vendor/jsqlite/README.md`.
diff --git a/docs/index.md b/docs/index.md
index 20f093d..08b36b1 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -75,6 +75,7 @@ work.
- [kimi3-security-recommmendations.md](kimi3-security-recommmendations.md) - prioritized security backlog and implementation handoff
- [safety-guide.md](safety-guide.md) - practical secure-application guide for Jerboa programs
- [release-security.md](release-security.md) - release gates and security evidence
+- [reviews/2026-07-27-vendor-jsqlite-tcb.md](reviews/2026-07-27-vendor-jsqlite-tcb.md) - accepted-risk review for the vendored SQLite-compatible engine
- [capability.md](capability.md) - object-capability model
- [limits.md](limits.md) - resource limits, sandboxing, and capability primitives
- [harden.md](harden.md) - binary hardening for release artifacts
diff --git a/docs/kimi3-security-recommmendations.md b/docs/kimi3-security-recommmendations.md
index 8191c0f..cd84eaa 100644
--- a/docs/kimi3-security-recommmendations.md
+++ b/docs/kimi3-security-recommmendations.md
@@ -609,7 +609,7 @@ not started."
`jerboa-native-rs` now denies
`unsafe_op_in_unsafe_fn`, so unsafe function bodies do not implicitly permit
unsafe operations. `vendor/jsqlite` remains in the TCB with an accepted-risk
- decision in `docs/vendor-jsqlite-tcb.md`; `make audit` now runs
+ decision in `docs/reviews/2026-07-27-vendor-jsqlite-tcb.md`; `make audit` now runs
`vendor-jsqlite-security-check`, which fails stale advisory reviews or drift
between the decision record and the vendored README compatibility target.
Remaining work: unsafe invariant comments and export shrinking/justification.
diff --git a/docs/release-security.md b/docs/release-security.md
index c6780e6..932bc4e 100644
--- a/docs/release-security.md
+++ b/docs/release-security.md
@@ -159,9 +159,9 @@ also runs `tcb-drift-check`, which requires a `data/changelog.sexp` note when
TCB-affecting manifests, C shims, native lockfiles, container locks, or
vendored C inputs change.
The same audit gate runs `vendor-jsqlite-security-check`, which requires
-`docs/vendor-jsqlite-tcb.md` to record a fresh accepted-risk review for the
-vendored pure-Jerboa SQLite-compatible engine and to match the pinned SQLite
-compatibility target in `vendor/jsqlite/README.md`.
+`docs/reviews/2026-07-27-vendor-jsqlite-tcb.md` to record a fresh
+accepted-risk review for the vendored pure-Jerboa SQLite-compatible engine and
+to match the pinned SQLite compatibility target in `vendor/jsqlite/README.md`.
It also runs `support/check-release-path-leaks.sh` against `dist/jerboa` and
requires `path_leak_status=pass` in `path-leaks.txt`. Release packaging runs
the same checker against the final `.tar.gz`, so shipped artifacts cannot
diff --git a/docs/reviews/2026-07-27-vendor-jsqlite-tcb.md b/docs/reviews/2026-07-27-vendor-jsqlite-tcb.md
new file mode 100644
index 0000000..87ee956
--- /dev/null
+++ b/docs/reviews/2026-07-27-vendor-jsqlite-tcb.md
@@ -0,0 +1,39 @@
+# Vendored jsqlite TCB Decision
+
+Last advisory review: 2026-07-27
+Review max age: 90 days
+SQLite compatibility target: 3.54.0
+Decision: accepted-risk
+Runtime dependency: none on libsqlite3
+
+`vendor/jsqlite` remains in the Jerboa TCB for now. It is a pure Jerboa
+SQLite-compatible engine, not a dynamically linked copy of upstream
+`libsqlite3`, so `cargo audit` and system SQLite package scanners do not cover
+it. The release gate therefore treats it as an internal database engine with a
+SQLite compatibility target and requires a fresh manual advisory review.
+
+The review must check at least:
+
+- SQLite's official CVE page: <https://www.sqlite.org/cves.html>
+- NVD/OpenCVE-style entries for SQLite CVEs affecting versions at or below the
+ compatibility target.
+- Whether each advisory depends on upstream C implementation memory safety,
+ optional extensions absent from jsqlite, SQL semantics that jsqlite implements,
+ or file-format behavior that jsqlite parses or writes.
+
+Current review notes:
+
+- `vendor/jsqlite/README.md` pins compatibility to SQLite 3.54.0.
+- CVE-2025-6965 affects SQLite versions before 3.50.2 according to NVD, so the
+ pinned compatibility target is beyond the fixed upstream version. The jsqlite
+ review still needs semantic applicability checks because jsqlite reimplements
+ query planning/execution rather than linking upstream C.
+- CVE-2025-70873 and similar zipfile/extension reports must be checked for
+ extension applicability; jsqlite does not currently expose SQLite's zipfile
+ extension as a runtime dependency.
+
+Release rule:
+
+`make audit` runs `support/check-vendor-jsqlite-security.sh`. The check fails
+when this decision record is missing, the README compatibility target drifts,
+or the advisory review is older than `Review max age`.
diff --git a/docs/status.md b/docs/status.md
index 002bce9..d36fca1 100644
--- a/docs/status.md
+++ b/docs/status.md
@@ -1,6 +1,6 @@
# Jerboa Production Status
-Updated 2026-06-25.
+Updated 2026-07-27.
Jerboa is a Jerboa-first toolchain and standard library on top of a vendored
Chez runtime. User code is `.ss`, public commands go through `jerboa`, and
@@ -12,9 +12,9 @@ release artifacts are built as Jerboa multicall binaries with `jerboa`,
| Area | Status |
|---|---|
| CLI | `jerboa`, `jerboa run`, `jerboa eval`, `jerboa test`, `jerboa build`, and `jerboa pkg` are the documented entry points. |
-| Language | `(jerboa prelude)` is the default import for user code. `.sls` files remain implementation internals. |
+| Language | `(jerboa prelude)` is the default import for user code and resolves to the safe surface for direct scripts; use `--unsafe-prelude` or `(jerboa prelude unsafe)` only for explicit raw access. `.sls` files remain implementation internals. |
| Standard library | `lib/std` and `lib/jerboa` contain 647 `.ss` modules at this snapshot. See [libraries.md](libraries.md) and [api-index.md](api-index.md). |
-| Security | Landlock, seccomp, capability, taint, restricted evaluation, safe FASL, safe timeout, and release evidence are implemented. Raw-fork Scheme launch APIs are retired; process isolation requires an exec-only worker backend. |
+| Security | Landlock, seccomp, capability plans, taint-aware safe-prelude sinks, restricted evaluation, safe FASL, the exec worker facade, memory rlimit pre-exec setup, security regression tests, and release evidence are implemented. Native worker Landlock/seccomp and Seatbelt/Capsicum installation remain open hardening work. |
| Native Rust | `libjerboa_native` backs crypto, secure memory, compression, regex, selected databases, OS integrations, packet capture, and rustls TLS. |
| Packaging | `jpkg` is shipped through the Jerboa multicall binary and documented in [jpkg-guide.md](jpkg-guide.md). |
| Build and release | `make binary` is the local non-Linux release build, `make docker-build` is the Linux release build, and `make release-evidence` collects audit evidence. |
@@ -63,7 +63,10 @@ make check-docs
- Keep production docs focused on shipped behavior, supported commands, and
current module paths.
-- Keep old roadmap, handoff, and audit-history notes out of `docs/`.
+- Use [docs/index.md](index.md) as the maintained map for this language
+ repository. Stable language, library, build, and security references live at
+ top-level `docs/`; dated audits and review records live under
+ `docs/reviews/`; the Kimi handoff remains the explicit security backlog.
- Use `jerboa run file.ss` in examples.
- Link to [api-index.md](api-index.md) for generated symbol coverage instead of
maintaining parallel hand-written gap matrices.
diff --git a/docs/vendor-jsqlite-tcb.md b/docs/vendor-jsqlite-tcb.md
deleted file mode 100644
index 87ee956..0000000
--- a/docs/vendor-jsqlite-tcb.md
+++ /dev/null
@@ -1,39 +0,0 @@
-# Vendored jsqlite TCB Decision
-
-Last advisory review: 2026-07-27
-Review max age: 90 days
-SQLite compatibility target: 3.54.0
-Decision: accepted-risk
-Runtime dependency: none on libsqlite3
-
-`vendor/jsqlite` remains in the Jerboa TCB for now. It is a pure Jerboa
-SQLite-compatible engine, not a dynamically linked copy of upstream
-`libsqlite3`, so `cargo audit` and system SQLite package scanners do not cover
-it. The release gate therefore treats it as an internal database engine with a
-SQLite compatibility target and requires a fresh manual advisory review.
-
-The review must check at least:
-
-- SQLite's official CVE page: <https://www.sqlite.org/cves.html>
-- NVD/OpenCVE-style entries for SQLite CVEs affecting versions at or below the
- compatibility target.
-- Whether each advisory depends on upstream C implementation memory safety,
- optional extensions absent from jsqlite, SQL semantics that jsqlite implements,
- or file-format behavior that jsqlite parses or writes.
-
-Current review notes:
-
-- `vendor/jsqlite/README.md` pins compatibility to SQLite 3.54.0.
-- CVE-2025-6965 affects SQLite versions before 3.50.2 according to NVD, so the
- pinned compatibility target is beyond the fixed upstream version. The jsqlite
- review still needs semantic applicability checks because jsqlite reimplements
- query planning/execution rather than linking upstream C.
-- CVE-2025-70873 and similar zipfile/extension reports must be checked for
- extension applicability; jsqlite does not currently expose SQLite's zipfile
- extension as a runtime dependency.
-
-Release rule:
-
-`make audit` runs `support/check-vendor-jsqlite-security.sh`. The check fails
-when this decision record is missing, the README compatibility target drifts,
-or the advisory review is older than `Review max age`.
diff --git a/support/check-vendor-jsqlite-security.sh b/support/check-vendor-jsqlite-security.sh
index 3223a42..90b449c 100755
--- a/support/check-vendor-jsqlite-security.sh
+++ b/support/check-vendor-jsqlite-security.sh
@@ -1,7 +1,7 @@
#!/bin/sh
set -eu
-doc="${1:-docs/vendor-jsqlite-tcb.md}"
+doc="${1:-docs/reviews/2026-07-27-vendor-jsqlite-tcb.md}"
readme="${2:-vendor/jsqlite/README.md}"
python3 - "$doc" "$readme" <<'PY'
@@ -75,7 +75,7 @@ age_days = (today - review_date).days
if age_days > max_age_days:
fail(
f"Last advisory review is {age_days} days old; "
- f"refresh docs/vendor-jsqlite-tcb.md before release"
+ f"refresh docs/reviews/2026-07-27-vendor-jsqlite-tcb.md before release"
)
print(