Agent Passport

Another operator's agent arrives at your door with a passport: credentials that issuers signed about its history. You verify each signature offline, judge the claims under your own policy, and issue a local grant only after the agent proves it holds the key those credentials name.

The passport grants nothing by itself; authority still comes from a capability your kernel issues. It lets you weigh an agent from another organization without access to its operator's systems. Here you play all three parties on one machine: issuer, holder, and receiving operator.

1. Issue a passport from the agent's receipt history

chio passport create reads the subject's receipts from a receipt database, scores them, and writes a passport holding one credential signed with your issuer seed. Validity defaults to 30 days.

$ chio --receipt-db ./receipts.db passport create \
    --agent fixer \
    --signing-seed-file ./issuer.seed \
    --output ./passport.json \
    --validity-days 30

wrote passport to ./passport.json
subject:          did:chio:4daeca6fd9edd85aaa143e9059f9395d457152127e2162896afe650a4391f851
credential_count: 1
merkle_roots:     0
enterprise_provenance: 0
valid_until:      2026-10-05T06:16:56Z

You should see the subject's DID, one credential, no Merkle roots yet, and a valid_until 30 days out. The jq line takes the subject key from the receipt store, so the passport describes an agent the store has seen.

2. Verify every credential offline

A passport (schema chio.agent-passport.v1) is an unsigned bundle of reputation credentials, each signed by its own issuer. Verification needs no kernel, storage, or network, and it checks every credential:

• its Ed25519 signature against the issuer's public key;
• its subject against the passport's subject;
• its expiry;
• that the passport's valid_until ends no later than any credential it contains.

$ chio passport verify --input ./passport.json

passport verified
subject:          did:chio:4daeca6fd9edd85aaa143e9059f9395d457152127e2162896afe650a4391f851
passport_id:      b42ec4bb375f69d131be95bf1f05dd6018200314accd9ddfc03679e00d42cdf5
issuer:           did:chio:4cb5abf6ad79fbf5abbccafcc269d85cd2651ed4b885b5869f241aedf0a5ba29
issuer_count:     1
credential_count: 1
merkle_roots:     0
enterprise_provenance: 0
valid_until:      2026-10-05T06:16:56Z

You should see a passport_id, the content hash of the bundle, which is why verify prints it and create cannot. The issuer is the seed's derived DID. A second issuer appends its own credential and verify reports issuer_count 2; one credential about a different subject refuses the whole passport with PassportSubjectMismatch before any policy runs.

3. Judge the claims under your verifier policy

Signatures say who attested; your PassportVerifierPolicy says whether that is enough. Write the thresholds you require, then evaluate the passport against them. Output in this step and the next three is illustrative.

issuer_allowlist:
  - did:chio:4cb5abf6ad79fbf5abbccafcc269d85cd2651ed4b885b5869f241aedf0a5ba29
min_receipt_count: 1
max_attestation_age_days: 30
require_checkpoint_coverage: false
require_active_lifecycle: false

chio passport evaluate --input passport.json --policy verifier-policy.yaml

passport   b42ec4bb375f…cdf5
accepted   yes
matched    credential 0, issuer did:chio:4cb5ab…ba29

You should see the decision, the matched credential indexes, and the matched issuers. A valid signature can still fail policy: with require_checkpoint_coverage set, a credential whose receipts have no checkpoint roots is rejected, and CredentialPolicyEvaluation records its index, issuer, and reasons while the other credentials stand. To publish your requirements, sign the policy with chio passport policy create; relying parties read it as a SignedPassportVerifierPolicy.

4. Challenge the holder to prove the subject key

Create a challenge that names the issuers you accept and the policy you apply. The holder selects matching credentials and signs a response with the passport subject's key, and you verify the response against the exact challenge.

chio passport challenge create --verifier https://trust.larkfield.example \
    --policy verifier-policy.yaml --output challenge.json
chio passport challenge respond --input passport.json --challenge challenge.json \
    --holder-seed-file holder.seed --output response.json
chio passport challenge verify --input response.json --challenge challenge.json \
    --verifier-challenge-db challenges.db

challenge  challenge.json, expires in 300 s
response   response.json, signed by did:chio:4daeca…f851
verified   bound to challenge.json, 1 credential disclosed

You should see a response bound to your challenge. A challenge lives 300 seconds by default (--ttl-secs), and the challenge database keeps verification replay-safe. --issuer and --max-credentials limit what the holder discloses; chio passport present applies the same filter offline.

5. Issue one local grant bound to the holder's key

chio trust federated-issue verifies the presentation against the challenge and issues the single capability your policy file defines. Its subject is the key the passport names.

chio trust federated-issue --presentation-response response.json \
    --challenge challenge.json --capability-policy grant-policy.yaml

grant      cap-01b3…6a20, signed by your kernel
to         did:chio:4daeca…f851, from response.json

You should see a grant to the passport's subject. The holder's key travels in the projected credential's cnf claim, and the same key signs a DPoP proof on every request, so a copied grant alone carries no authority at your door. --delegation-policy sets a signed parent scope and lifetime ceiling; --enterprise-identity adds provider-admin gating.

6. Read the receipt for the agent's first call

Once the agent calls a tool under the grant, list the receipts your kernel signed for it, using the grant id from step 5.

chio receipt list --capability <grant-id> | jq -c '{id, tool_name, decision}'

{"id":"rcpt-01b3…2f71","tool_name":"read_file","decision":{"verdict":"allow"}}

You should see the admitted call under the grant from step 5. The receipt names the capability your kernel issued: the authority the call ran under, with the passport as the evidence behind issuing it.

Read more in Receipts.

A refused passport names the input it rejected

Most failures stop before a file is written. The two below come from chio passport create.

$ chio --receipt-db ./receipts.db passport create \
    --subject-public-key 3d067fadc2c47f5a6f125a0b06c36f38e5699277107b585847145601a905146e \
    --signing-seed-file ./issuer.seed \
    --output ./rejected.json

error[CHIO-TRUST-KEY-MALFORMED]: invalid public key: the value is not a point on the Ed25519 curve
  help: pass the agent's Ed25519 public key as 64 hex characters, as chio receipt list prints it in subject_key
  code: urn:chio:error:trust:key-malformed
  docs: https://chio.computer/docs/reference/errors#error-trust-key-malformed

Passport, credential, and policy reference

pub struct AgentPassport {
    pub schema: String,                // "chio.agent-passport.v1"
    pub subject: String,               // did:chio identifier of the agent
    pub credentials: Vec<ReputationCredential>,
    pub merkle_roots: Vec<String>,     // receipt log checkpoint roots
    pub enterprise_identity_provenance: Vec<EnterpriseIdentityProvenance>,
    pub issued_at: String,             // RFC 3339
    pub valid_until: String,           // RFC 3339
    pub trust_tier: Option<TrustTier>, // derived tier, optional
}

pub struct PassportVerification {
    pub passport_id: String,
    pub subject: String,
    pub issuer: Option<String>,
    pub issuers: Vec<String>,
    pub issuer_count: usize,
    pub credential_count: usize,
    pub merkle_root_count: usize,
    pub enterprise_identity_provenance: Vec<EnterpriseIdentityProvenance>,
    pub passport_lifecycle: Option<PassportLifecycleResolution>,
    pub verified_at: u64,
    pub valid_until: String,
}

did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038

use chio_did::DidChio;
use chio_core::PublicKey;
use std::str::FromStr;

// Create from a public key (rejects non-Ed25519 keys, so it returns a Result)
let did = DidChio::from_public_key(public_key)?;
println!("{}", did.as_str());
// did:chio:7b0f6f63...

// Parse from a string
let did = DidChio::from_str(
    "did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038"
)?;

// Resolve to a DID Document (self-certifying, no network call)
let doc = did.resolve();

$ chio did resolve \
    --did did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038",
  "verificationMethod": [
    {
      "id": "did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038#key-1",
      "type": "Ed25519VerificationKey2020",
      "controller": "did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038",
      "publicKeyMultibase": "z6MknjdqrkCzEUsqeH3AD14W14XZqKmu894CLReWFLpj97BV"
    }
  ],
  "authentication": [
    "did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038#key-1"
  ],
  "assertionMethod": [
    "did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038#key-1"
  ]
}

{
  "@context": [
    "https://www.w3.org/2018/credentials/v1",
    "https://chio.world/credentials/v1"
  ],
  "type": ["VerifiableCredential", "ChioReputationAttestation"],
  "issuer": "did:chio:...",
  "issuanceDate": "2026-04-01T00:00:00Z",
  "expirationDate": "2026-07-01T00:00:00Z",
  "credentialSubject": {
    "id": "did:chio:...",
    "metrics": { "...": "LocalReputationScorecard" }
  },
  "evidence": { "...": "ChioCredentialEvidence" },
  "proof": { "...": "CredentialProof" }
}

$ jq '.credentials[0] | {issuer, issuanceDate, expirationDate, evidence, proof}' ./passport.json

{
  "issuer": "did:chio:4cb5abf6ad79fbf5abbccafcc269d85cd2651ed4b885b5869f241aedf0a5ba29",
  "issuanceDate": "2026-09-05T06:16:56Z",
  "expirationDate": "2026-10-05T06:16:56Z",
  "evidence": {
    "query": {
      "until": 1788589016
    },
    "receiptCount": 1,
    "receiptIds": [
      "38d92b9b698aa09b3c9c5195dfb19d2ec530c15669aa5f74d56f92a82008ec0b"
    ],
    "checkpointRoots": [],
    "lineageRecords": 1,
    "uncheckpointedReceipts": 1
  },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "2026-09-05T06:16:56Z",
    "proofPurpose": "assertionMethod",
    "verificationMethod": "did:chio:4cb5abf6ad79fbf5abbccafcc269d85cd2651ed4b885b5869f241aedf0a5ba29#key-1",
    "proofValue": "f9625bcfc650ea984f856054de534df5b80b67e93765ce5b374ad869cb3351f31f064de0aaba9dc5f2d5e015f0132ab9d72247385c482eebf40007f40a625e09"
  }
}

pub struct PassportVerifierPolicy {
    pub issuer_allowlist: BTreeSet<String>,       // only accept from these issuers
    pub min_composite_score: Option<f64>,          // 0.0 - 1.0
    pub min_reliability: Option<f64>,              // 0.0 - 1.0
    pub min_least_privilege: Option<f64>,           // 0.0 - 1.0
    pub min_delegation_hygiene: Option<f64>,        // 0.0 - 1.0
    pub max_boundary_pressure: Option<f64>,         // 0.0 - 1.0 (lower is better)
    pub min_receipt_count: Option<usize>,           // minimum receipts in evidence
    pub min_lineage_records: Option<usize>,         // minimum lineage depth
    pub min_history_days: Option<u64>,              // minimum operational history
    pub max_attestation_age_days: Option<u32>,      // reject stale attestations
    pub require_checkpoint_coverage: bool,          // all receipts must be checkpointed
    pub require_receipt_log_urls: bool,             // evidence must include log URLs
    pub require_enterprise_identity_provenance: bool,
    pub require_active_lifecycle: bool,             // passport must be in active state
}

$ chio passport generate \
    --agent did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038 \
    --compliance-score 950 \
    --validity-days 30 \
    --output ./generated.json

passport generated
subject:          did:chio:7b0f6f631f6e66207140ead0b6b2e9418916d2c4b3c7448ba5f7ed27f5c8d038
compliance_score: 950
behavioral_anomaly: false
trust_tier:       premier
valid_until:      1791181017
output:           ./generated.json

pub struct EnterpriseIdentityProvenance {
    pub provider_id: String,            // identity provider identifier
    pub provider_kind: String,          // e.g., "azure-ad", "okta"
    pub federation_method: EnterpriseFederationMethod,
    pub principal: String,              // verified principal name
    pub subject_key: String,            // bound agent public key
    pub tenant_id: Option<String>,
    pub organization_id: Option<String>,
    pub groups: Vec<String>,
    pub roles: Vec<String>,
    // ...
}

Next: pin the partner whose agents you admit