Agent verification (KYA) and identity providers

Not in the preview yet. This feature is built in the repository but is off in the v2.2.6 preview (test mode). Do not treat this page as available on a preview core. See ../preview.md and the release notes.

Status: identity proofs on economic accounts are Live; agent verification (KYA) is Preview on a mock provider.

Dynamo never scores an agent. Identity and verification are objective facts: a proof verified, or a named check passed. A budget's owner can require a minimum level, and a level can only narrow what is allowed.

Agent verification (KYA)

The interface. A verification provider answers, for one agent address, a signed attestation: the agent, its level, the named checks it passed, the issuer, when it was issued and when it expires. Or it answers that it knows nothing about the agent.

LevelChecks it requires
key_boundkey_control
operator_identifiedplus operator_identity
operator_verifiedplus operator_identity_verified

The core verifies every answer itself: the signature against one pinned signer address, the agent, the level and its checks, and freshness. An attestation valid for more than 30 days is refused as not fresh.

Enforcement. A mandate's minAgentVerification sets the minimum level. Admission reads only attestations the core already stored and verified, so no network call sits in the payment path. An unknown agent, an expired attestation or an unavailable provider refuses (mandate_verification) wherever a level is required. Where no mandate requires one, KYA changes nothing.

Routes. With the switch off, GET /owner/v1/kya answers enabled: false and the other two refuse with 409 kya_off.

the verified answer

Switches.

SwitchDefaultNotes
CORE_KYAoffmock turns it on
CORE_KYA_MOCK_URLnonehttps, or http on loopback
CORE_KYA_MOCK_API_KEYnonea test key only; a live or production key anywhere refuses to start (kya_live_key)
CORE_KYA_MOCK_SIGNERnonethe provider's attestation signer address

Mocks today. No vendor is chosen. The mock adapter speaks a generic provider protocol to an offline mock provider that signs with its own key. A real provider would need its own adapter behind the same interface.

Identity proofs and economic accounts

An economic account is anchored to one address. Its identity links carry proofs, and its level is derived from the strongest verified link, never claimed by the client.

Proof typeLevel it confers
two_key (two keys sign the same challenge), web_bot_authlinked
w3c_vc (a W3C verifiable credential), sd_jwt (an SD-JWT credential), a2a_cardcredentialed
erc8004 (registered on the ERC-8004 registry)registered

Trusted credential issuers and the ERC-8004 registry reader are set by the operator's host configuration. Where no registry reader is configured, an erc8004 proof is refused proof_unavailable.

Routes: POST /owner/v1/accounts, GET /owner/v1/accounts, GET /owner/v1/accounts/{id}, POST /owner/v1/accounts/{id}/links, POST /owner/v1/link-challenges.

Link challenges (owner-api 1.9.0). A two_key, web_bot_auth or a2a_card link signs a challenge this deployment issued: POST /owner/v1/link-challenges with { "accountId": "acct_…", "proofType": "two_key" } (or web_bot_auth, a2a_card), pinned at Dynamo-Version 1.9.0 or later, answers a challenge.message, the exact dynamo-account-link-v2 text to sign. It names the proof type, this deployment, the account's address, a nonce and an expiry 300 seconds out, and links once: a used or expired challenge is refused link_challenge. A two_key proof signs message with both keys, a web_bot_auth proof with its directory key, and an a2a_card carries it in the card's challenge field. A w3c_vc JWT needs header typ vc+jwt and type VerifiableCredential; an agent card needs header typ agent-card+jws, so one token never passes as both.

Migrating. A challenge the client wrote itself (the earlier dynamo-account-link:<address>:… text) is refused proof_invalid at every Dynamo-Version, a security exception: any client could otherwise replay or pre-compute a link proof. A client pinned below 1.9.0 cannot fetch an issued challenge, so it can no longer link two_key, web_bot_auth or a2a_card; pin 1.9.0, fetch a challenge per link, and sign its message unchanged. sd_jwt links and their key-binding challenges (no proofType) are unchanged.

Minimum levels.

(mandate_assurance).

whose root funder is below the level, with 409 funder_identity. Control Mode is never refused.

Test suites

signed answers, unknown agents, outages and stale answers, levels only narrowing, tenants isolated.

levels, minPayeeAssurance admission, and the identity-level narrowing property.

and the funder minimum.

vectors.

Certification steps

  1. A provider's answers verify in process against its pinned signer.
  2. An unknown agent, an outage and a stale attestation each refuse where a

level is required.

  1. make test-kya green with the provider's adapter; for a proof type,

make test-accounts green with its verifier.