Cleanup: retire legacy mock-server endpoints + decide identity/audit placement (follow-up to #75 + #76)

[hanwencheng]

Background

After PR #75 (issue #74 step 1) and the planned PR for issue #76 (issue #74 step 1c) land, the legacy agentkeys-mock-server surface has zero live in-tree callers for most of its endpoints. This issue tracks the cleanup work and an architectural open question about where the still-useful endpoints should live.

Cleanup scope

After #75 + #76 are merged, the following endpoints have no remaining in-tree caller and should be deleted along with their supporting code:

• POST /session/create — replaced by the agentkeys init --email|--oauth2-google flow that mints session JWTs at the broker.
• GET /session/validate — replaced by local cryptographic JWT verification at the broker (already done for /v1/mint-oidc-jwt and /v1/mint-aws-creds per PR feat(stage7): phase 2 — OIDC issuer in Rust broker + provisioner-scripts AWS-cred wiring #61; the legacy validation path remained only because of /v1/auth/exchange).
• POST /v1/auth/exchange (broker) — backward-compat shim that exchanged a legacy bearer for a session JWT. With agentkeys init --mock-token hard-cut, no in-tree caller remains.
• POST /session/child / POST /session/revoke / POST /session/recover — all in the legacy bearer flow.
• The corresponding env vars on the broker side: BROKER_BACKEND_URL, BROKER_BACKEND_TIMEOUT_SECONDS.

Code to remove:

• crates/agentkeys-broker-server/src/handlers/auth/exchange.rs
• crates/agentkeys-broker-server/src/auth.rs::validate_bearer_token + extract_bearer_token
• crates/agentkeys-mock-server/src/handlers/session.rs (validate_session_endpoint, create_session, etc. — verify nothing else needs them)
• The /v1/auth/exchange route in lib.rs
• The BROKER_BACKEND_URL constant + reachability probe in boot.rs

Verification gate: grep -rn "session/create\|session/validate\|auth/exchange" crates/ scripts/ harness/ returns empty (excluding doc/comment refs that are explicitly historical).

What stays valuable on :8090 after cleanup

Endpoint group	Status post-cleanup	Should it stay on the legacy mock-server?
/dev/* (signer)	LIVES — this is the long-lived service on the host	No — already moved to :8092 --signer-only listener per step 1b
/identity/link + /identity/resolve + /v1/wallet/{link,links,recover/lookup}	LIVES — needed for omni ↔ identity linking	Open question — see below
/audit/query (legacy) + plugin_mint_log (broker side)	LIVES — auditability is a v0.1 requirement	Open question — see below
/mock/inbox/*	LIVES — used by the email-link flow	Reasonable to keep on the backend since it's a per-user inbox primitive
/auth-request/* (pair-flow, master-approval)	LIVES — used by the legacy daemon pair-flow	Keep until daemon's pair-flow is also retired (separate issue)

Open question — identity/audit endpoint placement

The user's proposal (per the conversation that produced #76) is a broker (policy/identity oracle) + signer (execution oracle) split:

The flow is:

1. User sends linking request to broker
2. Broker constructs the payload and sends back to user
3. User locally signs it with device key and JWT and sends to signer
4. The signer signs it and submits to cloud/blockchain

In this model:

• Broker owns identity-linking, grants, audit metadata, payload construction. It knows which user owns which omni, what's allowed, what's audited.
• Signer owns the per-omni keypair and the final signing/submission step. It accepts a payload + device-key signature + session JWT, validates, signs with the omni-derived key, and submits to the appropriate sink (cloud IAM, chain, etc.).

Trust shape implications:

• The broker never holds long-term key material (already true for AWS principals post-issue-broker: mint-aws-creds is broken after cloud-setup §4 federation lands #71; this extends the property to chain/cloud submission).
• The signer never holds policy state (already true for /dev/* today; this generalizes).
• Compromise of the broker can't forge submissions because the signer's per-request device-key check stands.
• Compromise of the signer can't fabricate identity/audit history because the broker is the source of truth for those.

Endpoints to relocate / refactor under this model

Today's endpoint	Proposed home	Notes
POST /v1/wallet/link	Broker (already there)	Stays at broker; signer is informed via JWT claim only
GET /v1/wallet/links	Broker (already there)	Read-only metadata; broker is fine
POST /v1/wallet/recover/lookup	Broker (already there)	Unauth, read-only — broker stays
Legacy /identity/link + /identity/resolve (mock-server)	DELETE — superseded by /v1/wallet/* at broker	Migration: any test/script callers update to broker URLs
Audit queries (/audit/query mock-server)	Broker (/audit/query at broker side, backed by plugin_mint_log SQLite per architecture.md §11)	Already pluggable per architecture.md §7 — chain/cloud anchors swap in here
New: cloud/chain submission	Signer (POST /dev/submit-anchored-tx or similar — wire shape TBD)	This is the new surface implied by the user's flow; needs design

What this issue should produce

1. A list of concrete code-deletion patches for the cleanup scope above.
2. A short design doc (docs/spec/plans/identity-audit-placement.md?) that:
   • Confirms or refines the broker-policy / signer-execution split.
   • Proposes the new signer-side submission endpoint surface (if we go that direction).
   • Defines migration order: identity endpoints first, audit second, submission third.

Dependencies

Blocks on PR #75 + issue #76 landing first — the cleanup is only safe after the new flow is fully shipped and operators have migrated.

Out of scope

• The actual TEE worker (issue Replace dev_key_service with TEE worker for omni-anchored EVM keypair derivation #74 step 2). The cleanup happens at the wire-contract layer; the swap to TEE behind /dev/* is a separate concern.
• Daemon pair-flow retirement (/auth-request/* endpoints). Separate issue once a successor for the master-adopts-child-daemon model exists.
• On-chain audit anchoring (Heima pallets). Separate work track per heima-gaps §5.

References

• PR agentkeys: stage 7+ — issue #74 step 1 (dev_key_service signer + bootstrap chain) #75 — issue Replace dev_key_service with TEE worker for omni-anchored EVM keypair derivation #74 step 1 (dev_key_service signer + bootstrap chain)
• Issue Step 1c: device-key authentication for /dev/* signer endpoints (follow-up to #74) #76 — issue Replace dev_key_service with TEE worker for omni-anchored EVM keypair derivation #74 step 1c (device-key auth)
• docs/spec/architecture.md — canonical broker/signer/daemon doc
• docs/spec/heima-gaps-vs-desired-architecture.md

[hanwencheng]

Open question resolved in #78.

#78 commits to the broker (policy + audit-of-record) / signer (execution + audit-emitter) split, lists every endpoint to delete/add/repoint, and breaks the work into 3 phases.

The cleanup scope in this issue stands — Phase 1 of #78 is the immediate dependency:

• Add GET /v1/audit/query at broker (gap today; replaces mock-server's legacy duplicate)
• Repoint daemon /identity/resolve → broker /v1/wallet/links
• Repoint CLI cmd_link / cmd_grant / cmd_audit_query to broker
• Then delete mock-server handlers::identity + handlers::audit

Phase 2 + 3 of #78 (chain-anchor surface) depend on #76 landing, so they don't block this issue's cleanup.