docs: document security threat model

[wemeetagain]

Summary

• add a concise normative threat model covering assets, actors, trust boundaries, consensus trust invariants, security objectives, and finding classification
• separate volatile integration maturity, current call paths, cache mechanics, persistence details, controls, and open questions into a dated implementation map with an explicit owner
• require reviewers and contributors in AGENTS.md to consult both documents and revisit them when security-relevant integration boundaries change

Why

Security reports have produced faulty findings because Lodestar and Ethereum trust assumptions were implicit. In particular, agents treated trusted beacon states and local ERA/database data as hostile, confused ancestry checks with full validation, and overlooked validation performed by Lodestar-ts.

Separating the stable security contract from current implementation mappings also reduces verbosity and limits documentation bitrot. The normative core changes only when trust or classification changes; implementation details can evolve in the audit map.

Impact

Documentation only. Maintainers and automated reviewers gain a shorter basis for distinguishing security vulnerabilities, integration-readiness issues, consensus bugs, boundary hardening, trusted-input reliability problems, and operator misuse.

AI assistance

This documentation was primarily AI-authored through an extended collaborative threat-modeling discussion with maintainer-provided Lodestar and Ethereum domain guidance.

[lodekeeper-z]

The structure and attacker/path/classification discipline are strong, but I found five threat-model accuracy gaps that should be resolved before this becomes the review baseline. The most important are the DA ordering claim and the process-wide pubkey-cache rollback/finalization description. Details are inline.

Review scope: AGENTS.md and THREAT_MODEL.md at b8d60d4. I also checked the corresponding Lodestar-ts block verification path and current Lodestar-z state-transition/cache code. CI is green on Ubuntu, ARM, bindings, title, and spec preparation; macOS was still pending at the time of review.

[lodekeeper-z]

Supplemental review after the independent security and consistency passes completed. These are distinct from the five findings in my first review and focus on boundary coverage and terminology.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6d54ee28ab

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[lodekeeper-z]

Re-reviewed at 2639d32.

The split addresses my main maintainability concern: THREAT_MODEL.md is now a substantially shorter normative contract, while current integration status and implementation mechanics are isolated in docs/security/IMPLEMENTATION_MAP.md with ownership, a review date, and explicit update triggers in AGENTS.md.

The revised text also resolves the substantive issues from my earlier reviews: planned-path classification, host-process confidentiality, N-API validation wording, concurrent DA/STF gating, append-only pubkey-cache behavior, the JavaScript/native and Zig/native boundaries, cumulative exhaustion, state provenance versus eligibility, and the Gloas status distinction. The two deliberately out-of-scope cases are now stated consistently rather than left ambiguous.

I found no remaining blocking issues. Relative links and git diff --check pass. The primary build and binding checks are green; the remaining spec matrix is still running.

[lodekeeper-z]

Follow-up verification against the current Lodestar-ts and Lodestar-z sources found several accuracy gaps that the implementation map is intended to prevent. This review supersedes my earlier approval. The normative/implementation split remains a strong improvement; the requested changes are scoped corrections to the resulting baseline.

[lodekeeper-z]

Re-reviewed at 9848319. The follow-up resolves all five accuracy gaps from my changes-requested review: JavaScript and native Zig callers now have distinct capability models; authenticated anchors are included in eligible trusted pre-states; the BLS/pubkey-cache surfaces are correctly classified as exported but not wired into Lodestar-ts production; the current Lodestar-ts checkpoint decode/authentication path is documented; live-chain import is separated from archive-only backfill; and the process-global reused epoch-transition cache plus its borrowed-lifetime serialization requirements are explicit.

I cross-checked the changed wording against the current Lodestar-ts and Lodestar-z sources. git diff --check passes, all relative documentation links resolve, and the current CI checks are green or still running with no failures. No blocking issues remain.

[lodekeeper-z]

Re-reviewed the simplification at 552c360. The shorter runtime trust model preserves the earlier integration and shared-cache corrections, and the implementation-map links and source anchors validate. One scope regression remains: the rewrite drops supply-chain and release-artifact integrity from the protected assets, objectives, boundaries, and implementation map. That makes dependency, workflow, or artifact-substitution findings impossible to classify under the document's own required-objective framework. Please retain a concise supply-chain/release objective and boundary.

[lodekeeper-z]

Blocking: The simplification removes source-dependency and native release-artifact integrity from the protected assets, and the later objectives/boundaries no longer cover build or release trust. Because classification now requires a violated security objective, a malicious dependency pin, workflow, or substituted published addon would fall outside this baseline even though it is a Lodestar-z security path. Please retain a concise artifact-integrity asset/objective and a build/release trust boundary; volatile workflow details can remain in the implementation map.

[lodekeeper-z]

Re-reviewed at 489787d. This restores the missing supply-chain and release-artifact integrity coverage across the protected assets, attacker model, security objectives, trust boundaries, and implementation map. I verified the cited dependency pins and release workflow controls (SHA-pinned actions, ReleaseSafe artifacts, frozen lockfile, and npm provenance); relative links and git diff --check pass. No blocking issues remain.

[spiral-ladder]

overall looks good, we can tweak the doc according as we find issues