fix(cli): #37 — real macOS LAContext biometric gate via objc2 FFI

[hanwencheng]

Summary

Wires real Touch ID / Face ID on macOS via LAContext.evaluatePolicy through the objc2 + block2 FFI stack. Supersedes PR #27, which landed a stub that logged a prompt and returned Ok(()) on macOS.

Closes #37.

Design — trait seam

biometric/
├── mod.rs         BiometricBackend trait + require_biometric() entry point
├── error.rs       typed BiometricError enum (all LAError codes mapped)
├── logic.rs       pure functions: parse_la_error, redact_prompt_reason
├── lacontext.rs   macOS backend — real LAContext.evaluatePolicy FFI
└── stdin.rs       non-macOS backend — stdin y/N fallback

• AGENTKEYS_BIOMETRIC=on activates the gate; default is bypass (preserves existing CLI behavior for scripts / CI).
• AGENTKEYS_ALLOW_NO_BIOMETRIC=1 (non-macOS only) skips the stdin TTY guard.
• cmd_approve, cmd_revoke, cmd_teardown call require_biometric with reason strings scrubbed via redact_prompt_reason — long opaque tokens get replaced with <redacted> so revoke <session-token> can't leak the token to terminal scrollback (the critical P2 codex flagged on PR fix(cli): #11 biometric gate for high-security master CLI actions (macOS) #27).

unsafe inventory

~4 blocks, each 2-5 lines, all annotated with // SAFETY: comments:

1. LAContext::new() — all objc2 message-sends are unsafe
2. Synchronous canEvaluatePolicy_error capability check
3. *mut NSError dereference inside the completion block (null-checked defensively even though Apple's contract guarantees non-null on failure)
4. evaluatePolicy_localizedReason_reply async method send

Deadlock / leak protections:

• 60-second recv_timeout on the channel — CLI can never hang forever
• No Retained<LAContext> captured inside the completion block (avoids retain cycle)
• Single-shot: each authenticate call builds its own LAContext

Tests — 4 layers

L1 — Pure logic (22 tests, runs on every platform)

• parse_la_error — one test per documented LAError code (-1 through -10)
• redact_prompt_reason — 0x-address preservation, long-token stripping, idempotence
• biometric_is_enabled — env-var parsing (on / 1 / true / unset / off)

L2 — FFI boundary (2 tests, #[cfg(target_os = "macos")])

• la_context_constructs_and_drops — catches dylib load / linker issues
• can_evaluate_policy_is_synchronous_on_ci_runner — smoke-test for FFI wiring

L3 — Behavioral via MockBackend

• mock_backend_receives_redacted_reason — critical regression test for PR fix(cli): #11 biometric gate for high-security master CLI actions (macOS) #27's P2 token-leak finding
• mock_backend_returns_scripted_error — scripted-response validation

L4 — Manual QA (docs/manual-test-issue-37.md)

7 scenarios requiring real macOS Touch ID hardware — cannot be automated:

1. Touch ID succeeds → action proceeds
2. User cancels → action aborts with clean message
3. Biometry lockout → passcode fallback
4. Device without biometry sensor
5. AGENTKEYS_BIOMETRIC=off escape hatch
6. Token-leak regression: revoke <raw-token> must NOT echo the token to stderr / scrollback
7. Non-macOS stdin fallback

Dependencies

Gated with [target.'cfg(target_os = "macos")'.dependencies] — zero cost on Linux / Windows builds:

objc2 = "0.6"
objc2-foundation = "0.3"
objc2-local-authentication = "0.3"
block2 = "0.6"

Test plan

• cargo test -p agentkeys-cli biometric -- --test-threads=1 → 22 passed (L1 + L3 + L2 on macOS)
• cargo test -p agentkeys-cli -- --test-threads=1 → 25 existing CLI integration tests still green with gate default-off
• cargo check -p agentkeys-cli → clean compile on macOS with full FFI stack linked
• Manual QA scenarios 1-7 from docs/manual-test-issue-37.md (requires reviewer with Touch ID hardware)

Issue

Closes #37. Supersedes #27 — PR #27 should be closed when this merges (the trait-seam design replaces its biometric.rs entirely).

[hanwencheng]

this also close #11