Skip to content

Agent token loss has no recovery UX: rotation should reuse the identity, not mint a new one #2158

Description

@jaylfc

Agent tokens are lost routinely and there is no recovery UX

Three agents lost their bearer token in a single day (2026-07-26): taOS-website-dev,
taOSmd-dev, and hermes. In each case the token was minted, used, and then became
unfindable after a machine migration or a config change. Jay could not locate
hermes' token either.

Three losses in one day is a systems problem, not three coincidences.

What is correct today and should NOT change

  • The token is shown once at mint and stored nowhere retrievable. That is the
    right design and must stay. A credential you can look up later is a credential
    an attacker can look up later.
  • The auth-request flow works as a recovery path: request -> owner approves ->
    new identity + token.

What is missing

  1. No storage guidance at the moment it matters. The mint response hands over
    a secret with no instruction. The rule ("two migration-surviving locations,
    mode 0600, outside git") exists in our conventions and nowhere in the product.
    Say it at mint, where it is actionable.
  2. Recovery mints a NEW identity, which fights the one-agent-one-identity rule.
    Every loss creates an orphan that must be manually revoked, and if nobody
    remembers, the agent ends up with several identities and grants scattered
    across them - which is exactly the state hermes is in now, and it is why their
    SSE access appeared broken while the scope was actually held by a different
    identity they no longer had the token for.
  3. No self-service rotation. An agent that suspects its token is compromised
    or stale has no "rotate my credential" action; it has to ask a human to mint a
    replacement.
  4. Nothing detects the orphan. A revoked-or-abandoned identity holding live
    grants is invisible until something fails.

Proposed

  • Storage instruction returned WITH the token at mint, and repeated in agent
    onboarding.
  • A rotate action that replaces the credential on the same canonical identity,
    so recovery stops creating new identities. This is the substantive fix - it
    makes the one-agent-one-identity rule survivable in practice.
  • On approving a re-mint for an existing agent name, prompt to revoke the prior
    identity in the same flow rather than leaving it to memory.
  • Surface identities with no recent activity but live grants, so orphans are
    visible.

Related: #2148 (grants cannot be revoked at all), #2156
(handles must bind to one identity). This issue is the third leg of the same
problem: identity lifecycle has a mint and no maintenance.

Metadata

Metadata

Assignees

No one assigned

    Labels

    securitySecurity improvements

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions