Skip to content

Full arch.md §10.2 agent-bootstrap ceremony (HDKD omni + broker link-code endpoints) #144

@hanwencheng

Description

@hanwencheng

Problem

scripts/heima-agent-create.sh is a stub of arch.md §10.2 and inverts the trust model:

  • The agent's private key is generated on the master (cast wallet new, L120) and persisted to ~/.agentkeys/agents/<label>.json on the operator laptop, then shipped to the agent machine.
  • The link code is a literal stub: LINK_CODE_REDEMPTION="0x$(openssl rand -hex 32)" # stub for §10.2 ceremony (L173).
  • The proof-of-possession sig is computed on the master (which holds the key → proves nothing).

Per arch.md §10.2, the agent daemon must generate (D_priv, D_pub) on the agent machine (never leaves it); the master only mints a one-time link code; the agent redeems it proving possession; the broker mints J1_agent and binds the device on-chain.

Two prerequisites (discovered while scoping the pragmatic fix)

  1. HDKD omni model. arch.md §10.2 derives O_agent = HDKD(O_master, "//label") (hard child-derivation; agent has no EVM wallet, only a device key). The code derives O_agent = SHA256("agentkeys"||"evm"||agent_wallet) from the agent's own wallet. No HDKD child-derivation exists in the repo. Going literal means: implement HDKD, drop the agent EVM wallet, make J1_agent the agent session, and rework mint-oidc-jwt (which re-derives the tag from a wallet today) + the per-actor STS relay's session source.
  2. Broker chain-write. §10.2 step 8 has the broker bind (O_agent, D_pub) on-chain. The broker is read-only to the chain today (cast call for cap verification); registerAgentDevice is master-submitted. Either give the broker a signer or keep the binding master-submitted (and reconcile arch.md).

Scope (full fidelity)

  • Broker: POST /v1/agent/create (verify J1_master + K11; HDKD-derive O_agent; mint one-time link code, TTL 600s) + POST /v1/auth/link-code/redeem (verify pop_sig; consume code; bind device; mint J1_agent).
  • CLI: agentkeys agent create --label.
  • Daemon: device keygen at startup + --init-link-code redemption (arch.md §10.2 steps 5–9).
  • HDKD child derivation in agentkeys-core/broker identity.
  • Decide + implement broker-vs-master chain-write for the device binding.

Interim

The pragmatic "current solution" (agent key generated in the sandbox, wallet-derived omni, real one-time link code + pop_sig, master submits registerAgentDevice after redemption, fresh pairing each run, visible install/approve) is being implemented now under PR #141. This issue tracks converging that to the full HDKD-literal §10.2.

Acceptance

  • Agent device key is generated on the agent machine and never present on the master.
  • O_agent = HDKD(O_master, path), verifiable by recomputation.
  • Broker mints J1_agent on link-code redemption; mint-oidc-jwt reads actor_omni from the J1 claim.
  • harness/phase1-wire-demo.sh runs the real ceremony each run with no master-held agent key.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/brokerBroker server, cap-token issuance, OIDC issuancearea/cliagentkeys CLI, operator workstationarea/daemonagentkeys-daemon (sidecar) workarea/identityHDKD actor tree, K-key inventory, identity ceremonyenhancementNew feature or request

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions