Agent Passports

Subject identifier and schema

did:chio identifiers

Every Agent Passport subject is a did:chio identifier whose method-specific part is the lowercase hex form of an Ed25519 public key. Because the identifier embeds the key, a verifier checks signatures without a registry lookup, DID resolver, or network call.

did:chio:{64-lowercase-hex-Ed25519-public-key}

Parsing rules in chio-did:

• The string starts with did:chio:.
• The suffix is exactly 64 hexadecimal characters.
• The decoded public key is Ed25519. P-256 and other algorithms are rejected with DidError::UnsupportedKeyAlgorithm.

Resolution returns a W3C-compliant DID document with the embedded Ed25519 verification method in multibase encoding, plus optional service endpoints:

pub const RECEIPT_LOG_SERVICE_TYPE: &str = "ChioReceiptLogService";
pub const PASSPORT_STATUS_SERVICE_TYPE: &str = "ChioPassportStatusService";

The resolving environment attaches service endpoints. Two operators resolving the same did:chio can return different service URLs while sharing one verification method.

Passport schema

The native Agent Passport (schema tag chio.agent-passport.v1) is an unsigned bundle of independently verifiable credentials. Each ReputationCredential inside it is signed by its issuer, and verification walks the bundle credential by credential.

pub struct AgentPassport {
    pub schema: String,
    pub subject: String,
    pub credentials: Vec<ReputationCredential>,
    pub merkle_roots: Vec<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub enterprise_identity_provenance: Vec<EnterpriseIdentityProvenance>,
    pub issued_at: String,
    pub valid_until: String,
    /// Trust tier synthesized from the operator's compliance score and
    /// behavioral-anomaly signal. Optional for wire back-compat: passports
    /// without the field omit it entirely.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub trust_tier: Option<TrustTier>,
}

Two serde attributes sit above the struct at crates/trust/chio-credentials/src/passport.rs:1-2. rename_all = "camelCase" makes the wire keys merkleRoots, enterpriseIdentityProvenance, issuedAt, and validUntil. deny_unknown_fields fails deserialization on any key the type does not declare. issued_at and valid_until are RFC 3339 strings.

• subject binds the passport to a single Ed25519 keypair through did:chio.
• credentials holds the issuer-signed reputation attestations carrying scorecards.
• merkle_roots holds receipt-log checkpoint roots, so a verifier can spot-check receipt evidence.
• enterprise_identity_provenance records which identity provider authenticated the principal that issued each credential.

The financial passport and its schema id

AgentPassportV2 carries signed, individually verifiable, selectively disclosable financial credentials from the chio.fincred.* families beside the reputation credentials. Its wire id is chio.financial-agent-passport.v1, the value of FINANCIAL_AGENT_PASSPORT_SCHEMA_V1; the string chio.agent-passport.v2 never appears on the wire.

decode_versioned_agent_passport reads the schema string and branches on it. chio.agent-passport.v1 yields VersionedAgentPassport::V1. The financial id yields VersionedAgentPassport::V2 after validate_agent_passport_v2_contract accepts the body. Any other string is refused as unsupported versioned passport schema: {0}, so a producer emitting a literal chio.agent-passport.v2 gets that refusal.

fn decode_versioned_agent_passport_value(
    value: serde_json::Value,
) -> Result<VersionedAgentPassport, CredentialError> {
    let schema = value
        .as_object()
        .and_then(|object| object.get("schema"))
        .and_then(serde_json::Value::as_str)
        .ok_or_else(|| {
            CredentialError::InvalidVersionedPassport("passport schema is missing".to_string())
        })?;
    match schema {
        PASSPORT_SCHEMA => serde_json::from_value(value)
            .map(VersionedAgentPassport::V1)
            .map_err(|error| CredentialError::InvalidVersionedPassport(error.to_string())),
        FINANCIAL_AGENT_PASSPORT_SCHEMA_V1 => {
            let passport = serde_json::from_value(value)
                .map_err(|error| CredentialError::InvalidVersionedPassport(error.to_string()))?;
            validate_agent_passport_v2_contract(&passport)
                .map_err(|error| CredentialError::InvalidVersionedPassport(error.to_string()))?;
            Ok(VersionedAgentPassport::V2(Box::new(passport)))
        }
        other => Err(CredentialError::UnsupportedVersionedPassportSchema(
            other.to_string(),
        )),
    }
}

The version-two name lives in the schema registry. The JSON Schema for the financial passport carries $id: https://chio.world/schemas/chio/agent-passport/v2.schema.json, at spec/schemas/chio-trust/v1/financial-agent-passport.schema.json. That is a schema document identifier, separate from the value a passport puts in its own schema field. The credential families are documented at Financial Credentials.

PassportVerification

verify_agent_passport returns a PassportVerification that exposes both the single issuer field and the issuers list of unique issuer did:chio identifiers found in the bundle:

pub struct PassportVerification {
    pub passport_id: String,
    pub subject: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub issuer: Option<String>,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub issuers: Vec<String>,
    pub issuer_count: usize,
    pub credential_count: usize,
    pub merkle_root_count: usize,
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub enterprise_identity_provenance: Vec<EnterpriseIdentityProvenance>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub passport_lifecycle: Option<PassportLifecycleResolution>,
    pub verified_at: u64,
    pub valid_until: String,
}

PassportVerifierPolicy is defined in chio-credentials/src/passport.rs.

Projections and presentation

Verifiable credential projections

The SD-JWT VC projection partitions claims into those that always travel in cleartext and those the holder reveals on demand.

OID4VCI and OID4VP protocols

The SD-JWT VC projection supports two OpenID-family protocols over the same projected credential: OID4VCI for issuance and an OID4VP verifier profile for presentation.

OID4VCI issuance

The credential configuration id is chio_agent_passport, the credential format is chio-agent-passport+json, and issuer metadata is served at /.well-known/openid-credential-issuer. The pre-authorized-code grant drives the offer, token, and credential exchange, exposed through the chio passport issuance metadata|offer|token|credential CLI verbs.

pub const OID4VCI_PRE_AUTHORIZED_GRANT_TYPE: &str =
    "urn:ietf:params:oauth:grant-type:pre-authorized_code";
pub const CHIO_PASSPORT_OID4VCI_CREDENTIAL_CONFIGURATION_ID: &str = "chio_agent_passport";
pub const CHIO_PASSPORT_OID4VCI_FORMAT: &str = "chio-agent-passport+json";
pub const OID4VCI_ISSUER_METADATA_PATH: &str = "/.well-known/openid-credential-issuer";

OID4VP presentation

Presentation implements an OID4VP verifier flow for the projected application/dc+sd-jwt Agent Passport, scoped to that one credential type. A request carries a DCQL query for exactly one credential, and the verifier rejects any credential whose format is other than application/dc+sd-jwt or whose type differs from the chio-passport SD-JWT VC type. Verifier metadata is served at /.well-known/chio-oid4vp-verifier, and the chio passport oid4vp verbs drive the exchange.

impl Oid4vpDcqlQuery {
    pub fn validate(&self) -> Result<(), CredentialError> {
        if self.credentials.len() != 1 {
            return Err(CredentialError::InvalidOid4vpRequest(
                "Chio OID4VP currently supports exactly one requested credential".to_string(),
            ));
        }
        self.credentials[0].validate()
    }
}

HTTP flow

A raw client can drive both protocols without the Chio CLI. Steps one to four issue a credential; the holder presents it back through the OID4VP lane (steps five to seven) or the Chio-native challenge lane (steps eight and nine).

The OID4VP request object pins client_id_scheme=redirect_uri, response_type=vp_token, and response_mode=direct_post.jwt. Admin operations (issuance offers, challenge creation, verifier-policy CRUD, lifecycle publish and revoke) run on separate routes, so the public transport carries no verifier admin authority.

Portable envelope

The portable verifier lives at chio-kernel-core/src/passport_verify.rs. payload_canonical_bytes travels hex-encoded through the payload_bytes_hex serde module:

pub struct PortablePassportBody {
    /// Schema identifier; must equal [`PORTABLE_PASSPORT_SCHEMA`].
    pub schema: String,
    /// Subject identifier (typically the agent DID) the passport binds to.
    pub subject: String,
    /// Issuer public key that signed this envelope.
    pub issuer: PublicKey,
    /// Unix timestamp (seconds) the envelope was issued at.
    pub issued_at: u64,
    /// Unix timestamp (seconds) the envelope expires at.
    pub expires_at: u64,
    /// Canonical-JSON bytes of the authenticated payload.
    #[serde(with = "payload_bytes_hex")]
    pub payload_canonical_bytes: Vec<u8>,
}

The signed envelope wraps that body:

/// Signed portable passport envelope.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "camelCase", deny_unknown_fields)]
pub struct PortablePassportEnvelope {
    pub body: PortablePassportBody,
    pub signature: Signature,
}