Ticket 0007a: Anchorer core API in cog-anchor

[noctem-o]

What

Ticket 0007a — the anchoring core inside cog-anchor (split A of parent ticket 0007). Adds the real API the emitter will use:

• Anchorer / AnchorRequest / AnchorError and generate_key_file.
• Anchorer::open is now the sole LogWriter construction site in the deadbolt estate (CLAUDE.md law 3).
• Dev-grade key custody: a 64-lowercase-hex Ed25519 seed file, created create_new (refuses to overwrite), never auto-generated.
• Deps added: serde + serde_json only. OS randomness via BCryptGenRandom (Windows) / /dev/urandom (Unix) FFI — no new cargo deps.
• tests/smoke.rs refactored to route through Anchorer so LogWriter::open has exactly one call site.

Nothing outside cog-anchor imports it yet; emission into cog-cli is 0007b (parked until this merges — it imports this API).

Review (independently verified, not from the worker's summary)

Check	Result
cargo test -p cog-anchor	✅ 7/7 green (5 anchorer.rs + 2 smoke.rs)
cargo clippy -p cog-anchor --all-targets -- -D warnings	✅ clean
cargo tree -i magpie-log	✅ exactly one dependent (cog-anchor)
LogWriter::open grep	✅ single site, in Anchorer::open
cog-anchor imported outside crate	✅ none
Refuse-overwrite test asserts error and unchanged bytes	✅
Non-idempotence documented (2× → len 3)	✅
Hostile: malformed root → AnchorError::Log, len unchanged	✅
Hostile: wrong key on existing log → open fails	✅

Reviewer notes (non-blocking)

1. smoke.rs modified — outside 0007a's enumerated file list but within crates/cog-anchor/** and necessary: it was a second LogWriter::open site, so routing it through Anchorer is what makes the "sole construction site" criterion true.
2. RNG via unsafe FFI — chosen to honor "serde-only, no new deps." Small and correct-looking; flagging the platform unsafe as a design trade vs. an explicit getrandom dep. Minor nit: decode_seed_hex strips \n but not \r\n (irrelevant to the newline-free file it generates).

Provenance

Implemented by Codex (gpt-5.5) via the delegation wrapper; ticket authored and diff reviewed by Claude. Human is the merge authority.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: aa2964cbbe

ℹ️ 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".

[chatgpt-codex-connector]

Restrict generated seed file permissions

On Unix hosts with a permissive umask such as 022, this OpenOptions create path uses the platform default create mode, so the generated Ed25519 seed file can end up group/world-readable (for example 0644). Because that seed is sufficient to append anchors as deadbolt, the generator should create it with restrictive permissions such as 0600 on Unix instead of relying on the caller's umask.

Useful? React with 👍 / 👎.

[noctem-o]

Revise pass applied (architect ruling) — re-recommend ACCEPT

Force of the ruling: the "no new deps" constraint was meant to stop scope creep, not to force hand-rolling the crate's most security-critical operation. Hand-rolled entropy fails silent-and-permanent (Debian-OpenSSL-shaped); getrandom is the audited answer.

Four changes (commit 8d84409):

• getrandom = "0.4" added — dedupes with the 0.4.2 already in the tree, no second major version.
• generate_key_file now fills the seed via getrandom::fill; all cfg(windows)/cfg(unix) FFI deleted. Public signature, refuse-to-overwrite, and hex output format unchanged.
• #![forbid(unsafe_code)] added to the crate root — compiles clean, confirming the FFI was the crate's only unsafe. The invariant the FFI was trading away is now compiler-enforced.
• decode_seed_hex uses trim_end() so \r\n is handled, not just \n.

The smoke.rs refactor from the first pass is retained (endorsed — it's what makes the sole-LogWriter::open-site criterion true rather than merely asserted).

Validation (my runs, in the PR worktree):

Check	Result
cargo test -p cog-anchor	✅ 7/7 green, unmodified
#![forbid(unsafe_code)] compiles	✅ clean (no other unsafe in crate)
cargo clippy -p cog-anchor --all-targets -- -D warnings	✅ clean
cargo fmt --all --check	✅
cargo tree -i magpie-log	✅ one dependent
Diff scope	✅ cog-anchor/** + Cargo.lock only

Behaviour is identical to the first pass — only the entropy source and the crate's unsafe-ness changed. Recommend merge.