docs(tka): state that Tailnet Lock enforcement is active, not observe-only

[GeiserX]

What

Correct stale documentation that described Tailnet Lock (TKA) as observe-only / fail-open / inert, contradicting the live code, which actively enforces.

The peer-trust chokepoint (ts_runtime::peer_tracker::tka_snapshot_admits, mirroring Go's tkaFilterNetmapLocked) fails closed once a lock is synced: a peer presenting a missing or unauthorized key_signature is dropped at the peer-db upsert path, and the control runner publishes the verified Authority to that enforcement cell. The authority only ever reaches that path after VerifiedAumChain::verify, so a malicious control plane cannot forge a trusted key — it can only toggle the lock.

Why this matters

A maintainer reading the stale tka_sync module doc ("observe-only, fail-open … never drops a peer … enforcement is a separate, later, gated decision") could "reconcile" the contradiction with the enforcing code by removing enforcement — silently downgrading a working fail-closed security control to verify-only. This is a documentation-integrity fix flagged by security audits.

Changed docs

• ts_runtime/src/tka_sync.rs — module doc: separate the two distinct claims (a failed sync is fail-open and leaves prior enforcement untouched; a successfully synced Authority is actively enforced), with an explicit "do not remove enforcement to match an outdated reading" note.
• README.md — the ### Implemented and ### Unsupported TKA entries: "inert" / "not yet built" → actively enforcing, with the genuine remaining gaps named.
• docs/CRYPTOGRAPHY.md — "Enforcement posture — observe-only (verify-and-LOG)" → actively fail-closed (the stale tka_observe symbol no longer exists; the real path is tka_authority → tka_snapshot_admits).
• src/lib.rs — the tka_sign / tka_disable submit-only doc lines that called the posture "verify-and-log".

The authoritative posture / threat model / deferred gaps live in SECURITY.md; these are made consistent with it.

Also: fix pre-existing cargo doc breakage

cargo doc --workspace (which CI runs, and which enforces broken_intra_doc_links = "deny") was failing on main, unrelated to TKA:

• ts_control_serde/src/service_vip.rs: an unresolved [Display] link (now core::fmt::Display) and a public-doc link to the private PROTO_NAMES (now plain code text) — these are hard broken_intra_doc_links errors.
• Redundant explicit link targets in ts_runtime (peer_tracker, status) and the facade (src/lib.rs) — caught under -D warnings.

cargo doc --workspace --no-deps is now clean both plain (CI's form) and under RUSTDOCFLAGS="-D warnings".

Verification

No code or behavior change. cargo fmt --check clean; cargo doc --workspace --no-deps clean (plain + strict); doctests pass. Verified each doc claim against the live enforcement code (peer_tracker/mod.rs tka_snapshot_admits, control_runner.rs enforcement cell).

Signed-off-by: Sergio sergio@geiser.cloud

Created using Claude Code (Opus 4.8)

[coderabbitai]

Warning

Review limit reached

@GeiserX, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 42 minutes and 54 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c1214791-0c37-41c9-90fe-0a45e7ae5f80

📥 Commits

Reviewing files that changed from the base of the PR and between 26d5abc and 3e43d60.

📒 Files selected for processing (7)

• README.md
• docs/CRYPTOGRAPHY.md
• src/lib.rs
• ts_control_serde/src/service_vip.rs
• ts_runtime/src/peer_tracker/mod.rs
• ts_runtime/src/status.rs
• ts_runtime/src/tka_sync.rs

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/tka-enforcement-active

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}