KYA: know your agent

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.

A budget's mandate can require that every agent it pays has been verified by a verification provider. The provider attests, as a signed statement, which named checks an agent's address has passed. Dynamo compares the attested level with the level the mandate requires. This release has one provider interface and one adapter, mock, which runs against a test provider only. KYA is off by default.

Status: Preview.

Levels

Each level names the checks the provider reports as passed. A level is never a score.

LevelChecks the provider attests
nonenone
key_boundkey_control: the agent proved it controls the key at its address
operator_identifiedkey_control, operator_identity: the party running the agent is identified
operator_verifiedkey_control, operator_identity, operator_identity_verified: that identity is verified by the provider

Require a level in a mandate (owner-api 1.8.0)

Send Dynamo-Version: 1.8.0 and name the lowest level in the mandate:

{ "funding": "none", "capTotal": "5000000", "mandate": { "categories": "*", "maxDepth": 3, "minAgentVerification": "operator_identified" } }

The same field works on POST /owner/v1/budgets/:id/streams (root and child streams), POST /owner/v1/streams/:id/amend and POST /owner/v1/card-agent-programs/fundings (when card agent programs are on). Other routes that take a mandate (budget adoption, child adoption, top-ups) do not accept it in this release; their streams inherit it from a parent that has it. A client not pinned at 1.8.0 is refused as for any unknown field.

The rules:

raise it; a lower level is refused (mandate_widen). An amendment can raise the level of a running stream, never lower it.

authorizes a payment only when the serviceNode has a current attestation at or above the strictest level on its path. An agent the provider does not know, an expired attestation, or a provider that is off or unavailable is refused (mandate_verification). Nothing is allocated or billed.

and the hop records carry no verification fields.

(payeeVerification, payeeVerificationProvider, payeeVerificationAttestation).

minAgentVerification sits beside minPayeeAssurance, the payee's identity level from economic accounts. Each one narrows on its own.

In the SDKs. @dynamoprotocol/sdk 3.3.0 takes the field in a mandate (minAgentVerification: "operator_identified") and reads it back from the core. When it signs its own hop it inherits the field into the child mandate, so the hop's mandateHash matches the one the core writes. It refuses to sign a child that would lower the level. The Python dynamoprotocol client does the same (min_agent_verification is accepted too). Both offline evidence verifiers check the narrowing. The shared vectors identity/valid-agent-verification and identity/agent-verification-lowered give the same verdict in both. A wallet policy (@dynamoprotocol/wallet-policies) cannot express an attested level, so a mandate carrying the field does not compile to one: it is refused as an unknown field.

Check an agent

POST /owner/v1/kya/checks               {serviceNode}
  → {serviceNode, status: "attested", governsAdmission: true, level, checks, provider, attestationId, issuer, issuedAt, expiresAt, checkedAt}
GET  /owner/v1/kya/agents/:serviceNode  the stored attestation (no provider call)
GET  /owner/v1/kya                      the switch state, provider, signer and levels

Dynamo stores an attestation only when it verifies: it is signed by the pinned provider signer, it is about this address, its level has exactly that level's checks, and it is fresh (30 days at most). Admission reads stored attestations only and makes no network call. The scheduler checks stored agents again before their attestations expire. On the multi-tenant tier each tenant's checks are its own: another tenant's check never verifies an agent for you.

In the console, People and payments shows the KYA switch state.

Turn it on (operators)

VariableMeaning
CORE_KYAoff (default) or mock
CORE_KYA_MOCK_URLthe provider's base URL (https, or http on loopback)
CORE_KYA_MOCK_API_KEYa test key, kya_test_<secret>. A kya_live_ or kya_prod_ key in any variable refuses boot (kya_live_key)
CORE_KYA_MOCK_SIGNERthe address of the provider's attestation signer

The key is never logged or stored. On the multi-tenant tier KYA serves test-environment tenants only. The provider protocol the adapter speaks is in packages/core-host/src/kya/mock.ts; an offline mock provider for tests is in packages/core-host/src/kya/mock-provider.ts.

Errors

mandate_verification, kya_off, kya_unavailable, kya_subject_unknown.