Principal Agent Protocol (PAP)

1.1. Problem Statement

Existing agent-to-agent protocols authenticate agents as platform entities, not as delegates of human principals. None enforce context minimization at the protocol level. Disclosure is implementation-dependent. Session ephemerality is undefined. Execution isolation is absent--agents run in the same address space as the orchestrator or other services, creating blast radius problems even when disclosure is minimized. Economic models underneath these protocols are compatible with platform capture through cloud compute metering.¶

1.2. Design Goals

PAP is designed to satisfy the following goals:¶

1. The human principal is the root of trust for every transaction.¶
2. Context disclosure is enforced by the protocol at the request boundary (via SD-JWT).¶
3. Execution is isolated at the process boundary via OS-level capabilities.¶
4. Sessions are ephemeral by design; no persistent correlation.¶
5. Delegation is hierarchical with cryptographically enforced bounds.¶
6. Co-signed receipts prove both disclosure scope and execution constraints.¶
7. No novel cryptography, no token economy, no central registry.¶
8. Any compliant implementation MUST be buildable from this document alone, without reference to a specific programming language.¶
9. PAP is fully operational without any language model. LLMs are an optional enhancement layer that operates outside the protocol trust boundary -- they MAY improve intent detection or output presentation but MUST NOT issue mandates, authorize disclosure, or sign receipts.¶

1.3. Protocol Overview

A PAP transaction involves:¶

• A human principal who holds a device-bound keypair.¶
• An orchestrator agent operating under a root mandate.¶
• One or more downstream agents operating under delegated mandates, each executing in sandboxed isolation.¶
• A marketplace for agent discovery and disclosure filtering.¶
• A 6-phase session handshake between pairs of agents.¶
• Request boundary security via SD-JWT selective disclosure (minimize what the agent sees).¶
• Execution boundary security via OS sandboxing (minimize what the agent can do).¶
• Co-signed receipts recording property references and enforcement proof, never values.¶

2.1. Definitions

Agent: A software process acting under delegated authority from a human principal. The term is used in its legal/agency sense: an agent acts on behalf of a principal, within the scope the principal granted, and is accountable to that principal for its actions. A PAP agent MAY be a deterministic function, a microservice, a hardware device, or any other software process -- it does not imply autonomy, AI, or any capability beyond what its mandate explicitly permits. The conflation of "agent" with "autonomous AI system" common in industry usage does not apply here.¶

Principal: A human user who holds the root keypair and is the ultimate authority over all agent actions taken on their behalf.¶

Orchestrator: An agent that holds the root mandate from the principal. The orchestrator is the only agent that MAY hold the principal's full context. It delegates scoped mandates to downstream agents. The orchestrator's primary function is to protect the principal from over-disclosure -- it is a deny-by-default gatekeeper, not an autonomous decision-maker.¶

Mandate: A signed authorization object that specifies what an agent is permitted to do, what context it may disclose, and when the authorization expires.¶

Mandate Chain: An ordered sequence of mandates from root to leaf, each cryptographically linked to its parent.¶

Scope: The set of actions a mandate permits. Deny-by-default: an empty scope permits nothing.¶

Disclosure Set: The set of context classes an agent holds and the conditions under which they may be shared.¶

Capability Token: A single-use, signed authorization to open a session with a specific agent for a specific action.¶

Session DID: An ephemeral did:key identifier generated for a single session and discarded at session close.¶

Receipt: A co-signed record of a transaction that contains property type references but never property values.¶

Decay State: The lifecycle state of a mandate as it approaches or passes its TTL without renewal.¶

3.1. Trust Hierarchy

The PAP trust hierarchy is:¶

Human Principal (device-bound keypair, root of trust)
  +-- Orchestrator Agent (root mandate, full principal context)
       +-- Downstream Agent (task mandate, scoped context)
            +-- Marketplace Agent (own principal chain)

The principal's device-bound keypair is the sole root of trust. Every agent in a transaction MUST carry a cryptographically verifiable mandate chain traceable to this root.¶

3.2. Trust Assumptions

3.3. Threat Model

PAP is designed to defend against the following threats:¶

T1. Context profiling. An adversary correlates a principal's transactions across sessions to build a behavioral profile. Mitigation: Ephemeral session DIDs (Section 6.3) ensure each session is cryptographically unlinkable.¶

T2. Over-disclosure. An agent discloses more principal context than the principal authorized. Mitigation: SD-JWT selective disclosure (Section 7) structurally prevents disclosure of claims not included in the disclosure set. Marketplace filtering (Section 9.3) excludes agents whose requirements exceed the mandate before any session is established.¶

T3. Delegation bypass. A downstream agent acts outside its delegated scope. Mitigation: Scope containment (Section 5.4) and TTL bounds (Section 5.5) are verified cryptographically at each level of the mandate chain.¶

T4. Replay attacks. An adversary replays a captured capability token to open an unauthorized session. Mitigation: Nonce consumption (Section 6.2) ensures each token is single-use.¶

T5. Mandate tampering. An adversary modifies a mandate in the chain. Mitigation: Parent hash binding (Section 5.3) and Ed25519 signatures (Section 5.2) detect any modification.¶

T6. Platform capture. A platform operator accumulates control over agent transactions through infrastructure dependency. Mitigation: Federated discovery (Section 10), no central registry, no token economy, principal-held keys. Marketplace registries MUST NOT rank query results by operator metrics (Section 9.6) -- ranking power is platform capture power. Trust evaluation is the principal's responsibility.¶

T7. Payment linkability. A payment is correlated with the principal's identity. Mitigation: Chaumian ecash blind-signed tokens (Section 13.1) provide unlinkable proof of value transfer.¶

3.4. Explicit Non-Goals

The following are explicitly out of scope for PAP:¶

1. Compatibility with token economy monetization.¶
2. Enclave-as-equivalent-to-local trust models.¶
3. Identity recovery through platform operators.¶
4. Central registries for agent discovery.¶
5. Runtime scope expansion of mandates.¶
6. Arbitrary code execution in the orchestrator context.¶
7. Any extension that trades trust guarantees for adoption ease.¶

4.1. DID Method

PAP uses the did:key method as defined in [DID-KEY]. All identifiers MUST use Ed25519 public keys with the following derivation:¶

did:key:z<base58btc(0xed01 || public_key_bytes)>

Where: - 0xed01 is the multicodec prefix for Ed25519 public keys. - public_key_bytes is the 32-byte Ed25519 public key. - base58btc is Bitcoin's base58 encoding. - The z prefix indicates base58btc multibase encoding.¶

Implementations MUST support did:key resolution by extracting the public key bytes from the DID string:¶

1. Strip the did:key:z prefix.¶
2. Base58-decode the remainder.¶
3. Verify the first two bytes are 0xed and 0x01.¶
4. The remaining 32 bytes are the Ed25519 public key.¶

4.2. DID Document

A DID document for a PAP identity MUST conform to [DID-CORE] and contain:¶

{
  "@context": "https://www.w3.org/ns/did/v1",
  "id": "did:key:z...",
  "verificationMethod": [{
    "id": "did:key:z...#key-1",
    "type": "Ed25519VerificationKey2020",
    "controller": "did:key:z...",
    "publicKeyMultibase": "z<base58btc(0xed01 ++ public_key_bytes)>"
  }],
  "authentication": ["did:key:z...#key-1"]
}

A DID document MUST NOT contain any personal information. It contains only the public key and verification method reference.¶

4.3. Principal Keypair

The principal keypair is the root of trust. It MUST be an Ed25519 keypair. In production deployments, the private key SHOULD be bound to a hardware authenticator via WebAuthn [WEBAUTHN].¶

Implementations MUST support the PrincipalSigner interface:¶

• did() -> String -- The did:key identifier.¶
• sign(message: bytes) -> bytes -- Ed25519 signature (64 bytes).¶
• verifying_key() -> Ed25519PublicKey -- The public key.¶

Implementations MAY use software keys for development and testing. Production deployments SHOULD use WebAuthn-backed keys.¶

4.4. Session Keypair

A session keypair is an ephemeral Ed25519 keypair generated fresh for each protocol session. Session keypairs:¶

• MUST be generated using a cryptographically secure random number generator.¶
• MUST NOT be derived from or linked to the principal keypair.¶
• MUST be discarded when the session closes.¶
• MUST NOT be persisted to stable storage.¶

The session DID is derived using the same did:key method as the principal DID. An observer MUST NOT be able to determine whether a did:key identifier represents a principal or a session key.¶

5.1. Mandate Object

A mandate is the core delegation primitive. It authorizes an agent to perform specific actions with specific context. A mandate MUST contain the following fields:¶

5.2. Mandate Signing

A mandate MUST be signed by the issuer's Ed25519 signing key.¶

The canonical form for signing MUST be computed as follows:¶

1. Construct a JSON object containing all mandate fields EXCEPT signature.¶
2. DateTime fields MUST be serialized as RFC 3339 strings.¶
3. Null fields MUST be included as JSON null.¶
4. Serialize the JSON object to bytes.¶
5. Compute the Ed25519 signature over these bytes.¶
6. Encode the 64-byte signature using base64url without padding (RFC 4648 Section 5, no = padding).¶

The canonical JSON object MUST contain exactly these keys:¶

{
  "principal_did": "...",
  "agent_did": "...",
  "issuer_did": "...",
  "parent_mandate_hash": null,
  "scope": { ... },
  "disclosure_set": { ... },
  "ttl": "2026-03-15T20:00:00+00:00",
  "issued_at": "2026-03-15T16:00:00+00:00",
  "payment_proof": null
}

5.3. Mandate Hashing

The mandate hash is used for parent-child linking in delegation chains. It MUST be computed as:¶

1. Compute the canonical form (Section 5.2, step 1-4).¶
2. Apply SHA-256 to the canonical bytes.¶
3. Encode the 32-byte digest using base64url without padding.¶

The hash MUST be deterministic: the same mandate MUST always produce the same hash.¶

5.4. Scope

{
  "actions": [
    {
      "action": "schema:SearchAction",
      "object": "schema:WebPage",
      "conditions": {}
    }
  ]
}

{
  "entries": [
    {
      "type": "schema:Person",
      "permitted_properties": ["schema:name", "schema:nationality"],
      "prohibited_properties": ["schema:email", "schema:telephone"],
      "session_only": true,
      "no_retention": true
    }
  ]
}

5.5. Delegation Rules

When an agent delegates a mandate to a child agent, the following rules MUST be enforced:¶

R1. Scope Containment: The child mandate's scope MUST be contained by the parent mandate's scope (Section 5.4.5). If scope containment fails, the delegation MUST be rejected.¶

R2. TTL Bound: The child mandate's ttl MUST NOT exceed the parent mandate's ttl. If the child TTL exceeds the parent TTL, the delegation MUST be rejected.¶

R3. Parent Hash Binding: The child mandate's parent_mandate_hash MUST equal the hash (Section 5.3) of the parent mandate's canonical form.¶

R4. Issuer Chain: The child mandate's issuer_did MUST equal the parent mandate's agent_did. The child mandate MUST be signed by the parent mandate's agent_did key.¶

R5. Principal Propagation: The child mandate's principal_did MUST equal the parent mandate's principal_did.¶

R6. Root Mandate: A root mandate MUST have parent_mandate_hash set to null. A root mandate's issuer_did MUST equal its principal_did.¶

5.6. Mandate Chain Verification

A mandate chain is an ordered array of mandates [M_0, M_1, ..., M_n] where M_0 is the root mandate. Verification MUST proceed as follows:¶

1. M_0.parent_mandate_hash MUST be null.¶
2. M_0.signature MUST verify against the principal's public key.¶
3. For each i from 1 to n: a. M_i.parent_mandate_hash MUST equal hash(M_{i-1}). b. M_i.scope MUST satisfy scope containment against M_{i-1}.scope (Section 5.4.5). c. M_i.ttl MUST NOT exceed M_{i-1}.ttl. d. M_i.signature MUST verify against the public key of M_{i-1}.agent_did.¶

If any check fails, the entire chain MUST be rejected.¶

5.7. Decay State Machine

A mandate's decay state tracks its lifecycle as the TTL progresses. The decay state MUST be one of:¶

Active --> Degraded --> ReadOnly --> Suspended
  ^            |            |
  |            |            |
  +-- renewal -+-- renewal -+

function compute_decay_state(mandate, decay_window_seconds):
  now = current_utc_time()
  if now > mandate.ttl:
    if mandate.decay_state == Suspended:
      return Suspended
    else:
      return ReadOnly
  else:
    remaining = mandate.ttl - now (in seconds)
    if remaining <= decay_window_seconds:
      return Degraded
    else:
      return Active

6.1. Session State Machine

A session tracks the state of a transaction between two agents. The session state MUST be one of:¶

Valid transitions:¶

Initiated --> Open --> Executed --> Closed
    |                                 ^
    +----------> Closed (early) ------+
                     ^
    Open -------> Closed (early) -----+

Any transition not listed above MUST be rejected.¶

6.2. Capability Token

A capability token is a single-use authorization to open a session. It MUST contain the following fields:¶

{
  "id": "...",
  "target_did": "...",
  "action": "...",
  "nonce": "...",
  "issuer_did": "...",
  "issued_at": "...",
  "expires_at": "..."
}

6.3. Six-Phase Handshake

The session handshake consists of six phases. Each phase involves a message exchange between the initiating agent (I) and the receiving agent (R).¶

Phase  Direction  Message              Data
-----  ---------  -------------------  --------------------------------
1a     I -> R     TokenPresentation    CapabilityToken
1b     R -> I     TokenAccepted        session_id, receiver_session_did
       R -> I     TokenRejected        reason (terminates handshake)

2a     I -> R     SessionDidExchange   initiator_session_did
2b     R -> I     SessionDidAck        (empty)

3a     I -> R     DisclosureOffer      disclosures (may be empty array)
3b     R -> I     DisclosureAccepted   (empty)

4      R -> I     ExecutionResult      result (Schema.org JSON-LD)

5a     I -> R     ReceiptForCoSign     half-signed TransactionReceipt
5b     R -> I     ReceiptCoSigned      fully co-signed TransactionReceipt

6a     I -> R     SessionClose         session_id
6b     R -> I     SessionClosed        (empty)

7.1. Overview

PAP uses Selective Disclosure JWT (SD-JWT) as defined in [SD-JWT-08] for context disclosure during the session handshake. SD-JWT allows the principal to hold multiple claims but disclose only those permitted by the mandate.¶

7.2. SD-JWT Object

An SD-JWT MUST contain:¶

The claims and salts fields are private to the holder and MUST NOT be transmitted in their entirety. Only selected disclosures (Section 7.3) are transmitted.¶

7.3. Disclosure Object

A disclosure reveals a single claim. It MUST contain:¶

7.4. Commitment Computation

The SD-JWT commitment is signed to bind all possible disclosures.¶

1. For each claim (key, value) with salt s:¶

   • Construct: {"salt": s, "key": key, "value": value}¶
   • Hash: SHA-256(JSON_bytes(disclosure))¶
   • Encode: base64url-no-pad¶

2. Collect all hashes and sort lexicographically.¶

3. Construct commitment bytes:¶

   {
    "issuer": "<issuer_did>",
    "disclosure_hashes": ["<sorted_hash_1>", "<sorted_hash_2>", ...]
   }
   

   ¶

4. Sign: Ed25519_sign(JSON_bytes(commitment))¶

7.5. Disclosure Verification

A verifier MUST:¶

1. Verify the SD-JWT signature over the commitment bytes using the issuer's public key.¶
2. For each received disclosure: a. Compute hash = base64url(SHA-256(JSON_bytes(disclosure))). b. Verify that hash is present in the signed disclosure_hashes array.¶

If any disclosure hash is not found in the commitment, the verification MUST fail.¶

7.6. Zero-Disclosure Sessions

A session MAY proceed with zero disclosures. In this case:¶

• The DisclosureOffer message carries an empty disclosures array.¶
• The SD-JWT signature MUST still verify (the commitment contains hashes for all claims, but none are revealed).¶
• The receiver MUST accept an empty disclosure set without error.¶

8.1. Protocol Message Types

All protocol messages are serialized as JSON objects with a type discriminator field. The following message types are defined:¶

8.2. Envelope

Protocol messages are transmitted inside an envelope that provides routing, sequencing, and integrity.¶

SHA-256(session_id_bytes || sequence_big_endian_8_bytes || payload_json_bytes)

9.1. Agent Advertisement

An agent advertisement declares an agent's capabilities, disclosure requirements, and return types. Advertisements use Schema.org vocabulary and JSON-LD structure.¶

9.2. Provider Object

9.3. Disclosure Filtering

A marketplace registry MUST support two query modes:¶

Query by action: Return all advertisements whose capability array contains the requested action type.¶

Query by action with disclosure satisfiability: Return only advertisements where: 1. The capability array contains the requested action type, AND 2. Every entry in requires_disclosure is present in the caller's available properties list.¶

This filtering MUST occur before any mandate is issued or session is established. Agents whose disclosure requirements exceed the principal's authorization MUST be excluded. The principal MUST NOT be asked to over-disclose.¶

9.4. Advertisement Signing

The canonical form for advertisement signing MUST include all fields except signature:¶

{
  "@context": "https://schema.org",
  "@type": "schema:Service",
  "name": "...",
  "provider": { ... },
  "capability": [...],
  "object_types": [...],
  "requires_disclosure": [...],
  "returns": [...],
  "ttl_min": 300,
  "signed_by": "did:key:z..."
}

Signing follows the same Ed25519/base64url-no-pad procedure as mandate signing (Section 5.2).¶

A marketplace registry MUST reject unsigned advertisements.¶

9.5. Advertisement Hashing

The content hash of an advertisement MUST be computed as:¶

base64url(SHA-256(canonical_bytes))

This hash is used for deduplication in federated registries (Section 10).¶

9.6. Operator Metrics

An agent advertisement MAY include an operator_metrics field containing self-reported operational statistics. Metrics are informational metadata for principal evaluation and MUST NOT be used by marketplace registries for ranking, sorting, or filtering query results.¶

The operator_metrics field MUST be excluded from the advertisement content hash (Section 9.5) and signature computation (Section 9.4). Metrics change over time while the advertisement identity remains stable.¶

Anti-ranking requirement: Marketplace registries MUST return query results in insertion order. Registries MUST NOT rank, sort, or filter results based on operator metrics. The principal's orchestrator is responsible for evaluating metrics and making selection decisions. This requirement prevents marketplace registries from accumulating ranking power, which would constitute platform capture.¶

10.1. Overview

Federation enables independent marketplace registries to discover and share agent advertisements. Federation is peer-to-peer with no central coordinator.¶

10.2. Registry Peer

A federation peer is identified by:¶

10.3. Federation Messages

Federation uses the following message types, discriminated by a type field:¶

10.4. Federation Endpoints

A federation server MUST expose the following HTTP endpoints:¶

10.5. Content-Hash Deduplication

When merging remote advertisements, a federated registry MUST:¶

1. Compute the content hash of each advertisement (Section 9.5).¶
2. If the hash already exists in the local seen-hashes set, skip the advertisement.¶
3. If the advertisement has no signature, skip it.¶
4. Otherwise, register the advertisement and add its hash to the seen-hashes set.¶

This ensures idempotent synchronization and prevents duplicate entries.¶

10.6. Peer Discovery

A registry MAY discover new peers transitively:¶

1. Query a known peer's /federation/peers endpoint.¶
2. For each peer in the response not already known, add it to the local peer list.¶

Implementations SHOULD implement rate limiting and SHOULD validate that newly discovered peers are reachable before adding them.¶

10.7. Peer Trust Signals

A federation peer MAY present trust signals to establish credibility with other registries. Trust signals are additive -- more signals increase confidence but no single signal is sufficient alone.¶

11.1. Transaction Receipt

A transaction receipt is a co-signed record of a completed session. Receipts contain property type references only -- never values.¶

11.2. Receipt Signing

The canonical form for receipt signing MUST include all fields except signatures:¶

{
  "session_id": "...",
  "action": "...",
  "initiating_agent_did": "...",
  "receiving_agent_did": "...",
  "disclosed_by_initiator": [...],
  "disclosed_by_receiver": [...],
  "executed": "...",
  "returned": "...",
  "timestamp": "..."
}

11.3. Co-Signing Protocol

1. The initiator constructs a receipt from the completed session.¶
2. The initiator computes Ed25519_sign(canonical_bytes) using its session key and appends the base64url-no-pad encoded signature to signatures.¶
3. The initiator sends the half-signed receipt to the receiver.¶
4. The receiver verifies the initiator's signature against the initiator's session public key.¶
5. The receiver computes Ed25519_sign(canonical_bytes) using its session key and appends its signature to signatures.¶
6. The receiver returns the fully co-signed receipt.¶

11.4. Receipt Verification

To verify a co-signed receipt:¶

1. The signatures array MUST contain exactly 2 entries.¶
2. signatures[0] MUST verify against the initiator's session public key.¶
3. signatures[1] MUST verify against the receiver's session public key.¶

11.5. Privacy Properties

Receipts MUST NOT contain: - Personal data values (names, emails, etc.) - SD-JWT claim values - Raw execution inputs or outputs¶

Receipts MUST contain only: - Schema.org property type references (e.g., schema:Person.schema:name) - Operator-defined category references (e.g., operator:search_executed) - Human-readable action/result descriptions¶

This ensures receipts are auditable by both principals without revealing the data exchanged in the transaction.¶

11.6. Session Attestation

A session attestation is a signed statement by a session participant recording their assessment of the session outcome.¶

A receipt with attestations from both the initiating and receiving agents is bilaterally attested. Bilaterally attested receipts carry higher evidentiary weight for operator metric computation.¶

Attestations are per-action-type. An operator's reputation in one action domain (e.g., schema:SearchAction) MUST NOT be conflated with reputation in another domain (e.g., schema:ReserveAction).¶

12.1. Overview

PAP mandates MAY be wrapped in a W3C Verifiable Credential (VC) envelope for interoperability with existing credential ecosystems. The VC envelope is OPTIONAL; implementations MUST support bare mandates and MAY additionally support VC-wrapped mandates.¶

12.2. VC Structure

A PAP Verifiable Credential MUST conform to [VC-DATA-MODEL-2.0]:¶

{
  "@context": [
    "https://www.w3.org/ns/credentials/v2",
    "https://www.w3.org/ns/credentials/examples/v2"
  ],
  "id": "urn:uuid:<uuid-v4>",
  "type": ["VerifiableCredential", "PAPMandateCredential"],
  "issuer": "<issuer_did>",
  "issuanceDate": "<rfc3339>",
  "expirationDate": "<rfc3339>",
  "credentialSubject": { <mandate_payload> },
  "proof": {
    "type": "Ed25519Signature2020",
    "created": "<rfc3339>",
    "verificationMethod": "<did>#key-1",
    "proofPurpose": "assertionMethod",
    "proofValue": "<base64url-no-pad>"
  }
}

The type array MUST include both "VerifiableCredential" and "PAPMandateCredential" for discoverability.¶

12.3. Credential Signing

The canonical form for VC signing MUST include all fields except proof:¶

{
  "@context": [...],
  "id": "...",
  "type": [...],
  "issuer": "...",
  "issuanceDate": "...",
  "expirationDate": "..." or null,
  "credentialSubject": { ... }
}

The proofValue is base64url(Ed25519_sign(JSON_bytes(canonical))).¶

13.1. Payment Proof

A mandate MAY carry a payment_proof field containing a zero-knowledge payment commitment. PAP does not define the payment protocol; it defines the integration point. Only cryptographic commitments are stored -- never amounts, destinations, mints, or other identifying payment data.¶

The PaymentProof type is a tagged enum with two variants:¶

{
  "type": "Lightning",
  "hash": "<base64url-no-pad SHA-256>"
}

{
  "type": "Ecash",
  "hash": "<base64url-no-pad SHA-256>"
}

cargo test -p pap-ecash -- --nocapture

13.2. Payment Proof Verification

A receiving agent that requires payment MUST: 1. Extract the payment_proof from the mandate. 2. Validate the proof's structural integrity (valid base64url, 32-byte SHA-256 commitment). 3. Verify the proof against the payment network (out of band): - Lightning: verify the BOLT-11 payment hash preimage - Ecash: verify the Cashu token with the issuing mint 4. Accept or reject the session based on verification.¶

13.3. Continuity Tokens

A continuity token enables stateful relationships across sessions without requiring the vendor to retain state.¶

13.4. Auto-Approval Policies

An auto-approval policy allows the principal to pre-authorize certain categories of actions without per-transaction approval.¶

13.5. M-of-N Social Recovery

Principal identity recovery via a designated notary quorum. No central recovery authority. The principal designates N notary DIDs at setup time; any M co-signers from that set can authorize key rotation.¶

13.6. TEE Attestation

A mandate or session MAY carry a Trusted Execution Environment (TEE) attestation to provide evidence that an agent is executing within an isolated enclave. TEE attestation is OPTIONAL and does NOT elevate a TEE to equivalence with local trust (Section 3.4).¶

13.7. Payment Proof Validation

Section 13.1 defines the payment proof integration point. This section specifies the validation requirements that a conformant implementation MUST satisfy when payment proofs are present.¶

13.8. Chat and Real-Time Communication

{
  "type": "https://didcomm.org/basicmessage/2.0/message",
  "id": "<UUID>",
  "body": {
    "content": "<text of message>"
  }
}

13.9. Agent Continuation and Output-Scoped Forwarding

{
  "continuation": {
    "target": "pap://agent-uri-or-did",
    "action": "schema:SelectAction",
    "forward_scope": ["schema:SearchResult.url", "schema:SearchResult.name"],
    "ttl": 300
  }
}

SearchAction -> SelectAction -> ReserveAction -> PayAction

14.1. HTTP/JSON Transport

PAP defines an HTTP/JSON transport binding for the 6-phase handshake. This binding is the default transport for PAP v1.0. Implementations MAY define additional transport bindings.¶

14.2. Agent Server Endpoints

A receiving agent MUST expose the following HTTP endpoints:¶

The {id} path parameter is the session ID returned in Phase 1.¶

14.3. Agent Handler Interface

Implementations MUST implement a handler interface with the following operations:¶

14.4. Endpoint Resolution

Endpoint resolution maps a DID to a transport endpoint URL. In production, this SHOULD be backed by DID Document service endpoints. Implementations MAY use in-memory registries for development and testing.¶

14.5. Content Type

All HTTP request and response bodies MUST use Content-Type: application/json. Implementations SHOULD set Accept: application/json on requests.¶

14.6. Error Handling

If a phase handler returns an error, the server MUST respond with HTTP status 500 and a ProtocolMessage::Error payload containing a code and message.¶

If the request body does not match the expected message type for the endpoint, the server MUST respond with HTTP status 400.¶

14.7. WebSocket Transport

Implementations MAY support a WebSocket transport binding as an alternative to the HTTP/JSON binding. The WebSocket binding is OPTIONAL and provides full-duplex communication for sessions that benefit from lower-latency message exchange.¶

{
  "id": "did:key:z...#pap-ws",
  "type": "PAPWebSocket",
  "serviceEndpoint": "wss://agent.example.com/pap/ws"
}

14.8. Oblivious HTTP (OHTTP) Transport

Implementations MAY support Oblivious HTTP [RFC9458] as a transport binding. OHTTP provides request unlinkability at the network layer, preventing the receiving agent's operator from correlating requests by IP address.¶

Initiator -> OHTTP Relay -> Receiving Agent (Gateway)

{
  "id": "did:key:z...#pap-ohttp",
  "type": "PAPObliviousHTTP",
  "serviceEndpoint": "https://agent.example.com/pap/ohttp",
  "ohttpKeyConfig": "<base64url-encoded-key-config>"
}

14.9. DIDComm Transport

Implementations MAY support DIDComm Messaging v2 [DIDCOMM-V2] as a transport binding. DIDComm provides authenticated encryption at the message layer, enabling transport-independent secure messaging between agents identified by DIDs.¶

{
  "id": "did:key:z...#pap-didcomm",
  "type": "DIDCommMessaging",
  "serviceEndpoint": {
    "uri": "https://agent.example.com/pap/didcomm",
    "accept": ["didcomm/v2"]
  }
}

14.10. Transport Negotiation

When an agent supports multiple transport bindings, the initiating agent MUST select a transport by inspecting the receiving agent's DID Document service array. The preference order SHOULD be:¶

1. OHTTP (strongest privacy properties)¶
2. DIDComm (authenticated encryption at message layer)¶
3. WebSocket (lower latency for interactive sessions)¶
4. HTTP/JSON (default, widest compatibility)¶

If the receiving agent's DID Document contains no service entries, the initiating agent MUST fall back to HTTP/JSON with endpoint resolution (Section 14.4).¶

14.11. DIDComm v2 Envelope Compatibility

PAP defines an optional DIDComm v2 envelope compatibility layer that wraps PAP protocol envelopes inside DIDComm v2 message formats. This allows PAP agents to interoperate with DIDComm-native agents without changing the PAP protocol itself. This section specifies the detailed wire formats used by the DIDComm transport binding (Section 14.9).¶

{
  "id": "<uuid>",
  "typ": "application/didcomm-plain+json",
  "type": "https://pap.example.com/proto/1.0/<message-slug>",
  "from": "<sender-did>",
  "to": ["<recipient-did>"],
  "created_time": <unix-timestamp>,
  "body": { <full PAP Envelope as JSON> }
}

{
  "payload": "<base64url(plaintext-json)>",
  "signatures": [{
    "protected": "<base64url({\"typ\":\"application/didcomm-signed+json\",\"alg\":\"EdDSA\"})>",
    "signature": "<base64url(Ed25519-signature)>"
  }]
}

{
  "protected": "<base64url(header-json)>",
  "recipients": [{
    "header": { "kid": "<recipient-did>" },
    "encrypted_key": ""
  }],
  "iv": "<base64url(96-bit-nonce)>",
  "ciphertext": "<base64url(aes-gcm-ciphertext)>",
  "tag": "<base64url(128-bit-auth-tag)>"
}

15.1. Overview

The pap URI scheme identifies agents, capabilities, and resources within the Principal Agent Protocol. A pap:// URI is always an expression of intent -- resolving one initiates a PAP mandate-scoped interaction, not a raw network request.¶

The scheme family consists of three variants:¶

pap+https:// and pap+wss:// are recapture schemes. They apply PAP semantics -- mandate enforcement, selective disclosure, co-signed receipts -- to existing transports. The remote endpoint does not need to implement PAP. The client enforces the protocol locally. A pap+https:// URI is still an HTTPS request under the hood; the principal's mandate scope wraps it regardless of whether the server is PAP-aware.¶

15.2. Syntax

pap-uri         = pap-scheme "://" pap-authority pap-path [ "?" pap-query ]

pap-scheme      = "pap" / "pap+https" / "pap+wss"

pap-authority   = registry-host / did-authority / catalog-name

registry-host   = host [ ":" port ]
                  ; authority is the hostname only; agent slug appears in path

did-authority   = "did:key:" base58-multicodec-key
                  ; PAP parsers MUST treat "did:key:" as an atomic authority
                  ; token. Standard RFC 3986 host parsing (which disallows
                  ; colons) MUST NOT be applied to did-authority. A PAP URI
                  ; parser identifies did-authority by the "did:key:" prefix
                  ; before applying any other rule.

catalog-name    = 1*( ALPHA / DIGIT / "-" / "_" )
                  ; MUST NOT be a reserved word (receipt, canvas, settings)
                  ; resolved against local catalog before dispatch

pap-path        = registry-path / simple-path

registry-path   = "/agents/" agent-slug "/" schema-action-type
simple-path     = "/" schema-action-type
                  ; Schema.org action type, e.g. "SearchAction"

pap-query       = pap-param *( "&" pap-param )
pap-param       = schema-property "=" pap-value
                  ; values MUST be percent-encoded per RFC 3986 Section 2.1
                  ; "+" MUST NOT be used as a space encoding in pap-query

Examples:¶

; Networked agent via Chrysalis registry
pap://chrysalis.example.com/agents/arxiv/SearchAction?query=quantum%20computing

; Direct peer-to-peer via DID (no registry)
pap://did:key:z6MkhaXgBZDvotDkL5257faiztiGiC2QtKLGpbnnEGta2doK/SearchAction

; Local catalog shorthand -- resolved before dispatch
pap://arxiv/SearchAction?query=quantum%20computing
pap://wikipedia/ReadAction?name=Rust%20programming

; Receipt deep-link
pap://receipt/RCP_abc123

; Recapture schemes -- PAP scope over existing transports
pap+https://api.example.com/agents/bookings/BuyAction?offer=flight-abc
pap+wss://stream.example.com/agents/feed/ListenAction

15.3. Resolution

A conforming client MUST resolve a pap:// URI using the following priority chain, in order:¶

1. Special authority -- if the authority is one of the reserved words (receipt, canvas, settings), resolve locally without any network lookup. See Section 15.7. Do not proceed to subsequent steps.¶

2. did:key: authority -- if the authority begins with did:key:, resolve directly via DID Document endpoint discovery (Section 14.4). No registry lookup. Initiates a PAP handshake with the identified agent.¶

3. Catalog name -- if the authority contains no . character and does not begin with did:, the client MUST check its local agent catalog for an entry whose name field matches the authority (case-insensitive). If found, rewrite the URI to the agent's registered DID and resolve via step 1.¶

4. Registry hostname -- if the authority contains a . character, or matches localhost, or is a valid IPv4 address or IPv6 literal, treat it as a Chrysalis registry host. Resolve by querying the registry's /agents/{slug}/ routes (Section 14.1) using the path-embedded agent slug, and initiate a PAP handshake with the returned agent endpoint. The . heuristic MUST NOT be applied to localhost or IP literals; they are always treated as registry hosts.¶

If resolution fails at all steps, the client MUST render an inline error in place of the activated link, showing the unresolved URI and a human-readable explanation. The client MUST NOT navigate away from the current canvas or dismiss existing content. The client MUST NOT silently fall back to a raw HTTP request.¶

15.4. Action Type and Query Parameters

The action type path segment MUST be a Schema.org action type (e.g. SearchAction, BuyAction, ReadAction). For registry URIs the full path is /agents/{slug}/{ActionType}; for catalog and DID URIs the path is /{ActionType}. Clients SHOULD use the action type to pre-filter agents during resolution -- if a catalog agent does not advertise the requested action type in its capability array, it MUST NOT be selected.¶

Query parameters MUST use Schema.org property names as keys. Values MUST be percent-encoded per RFC 3986 Section 2.1; + MUST NOT be used as a space encoding. Clients MAY pass query parameters directly to the agent as the intent payload. Agents MAY ignore unknown parameters.¶

15.5. Recapture Semantics (pap+https://, pap+wss://)

When a pap+https:// or pap+wss:// URI is resolved:¶

1. The active mandate scope MUST be checked before the request is made. If no mandate is in scope, the client MUST NOT proceed.¶

2. The request is made over the underlying transport (HTTPS or WSS) with the standard PAP session headers included where the server accepts them.¶

3. The client MUST record what was disclosed and generate a receipt entry regardless of whether the server participates in the PAP handshake.¶

4. The remote endpoint's response is treated as agent output and rendered via the standard block renderer pipeline.¶

For pap+wss:// URIs, the connection lifecycle (establishment, keepalive, and termination) follows the mandate-scoped session lifecycle defined in Section 5. Streaming-specific semantics (chunked responses, event framing) are deferred to v1.1.¶

This allows principals to bring existing web services under PAP governance without requiring those services to be modified.¶

v1.0 scope note: In v1.0, pap+https:// and pap+wss:// URIs are parsed and classified by conforming clients. Full mandate enforcement (steps 1-4 above) requires the mandate enforcement layer, which is deferred to a post-v1.0 milestone. v1.0 clients MUST NOT silently downgrade a pap+https:// URI to an unscoped HTTPS request. They MUST either enforce the mandate or reject the request with a clear principal-visible error explaining that recapture enforcement is not yet available.¶

15.6. Link Rendering

Any string value in a JSON-LD agent response that begins with pap://, pap+https://, or pap+wss:// MUST be rendered as a navigable link by conforming clients. Activating such a link MUST dispatch the URI as intent through the same pipeline as a principal-typed query -- it is not a browser navigation event.¶

This enables agent-rendered content to form a navigable graph of intent-links without requiring any special page routing. Every link is a new PAP interaction.¶

Agent-rendered link security: Clients MUST visually distinguish links originating from agent-rendered content from links typed directly by the principal. Before dispatching an agent-rendered pap:// link, clients SHOULD display the full URI and the identity of the agent that produced it, and require explicit principal confirmation. This prevents injection attacks where a malicious or compromised agent response induces the client to execute unintended actions.¶

Agent-rendered links MUST NOT activate the settings, canvas, or receipt special authorities (Section 15.7). Clients MUST silently reject such links and MAY log the attempt for principal review.¶

15.7. Special Authorities

The following authority values are reserved and MUST be handled by the client without registry or catalog lookup:¶

16.1. Cryptographic Algorithms

PAP v1.0 uses exclusively:¶

• Ed25519 (RFC 8032) for all signatures.¶
• SHA-256 (FIPS 180-4) for all hashes.¶
• Base64url without padding (RFC 4648 Section 5) for all binary-to-text encoding.¶
• Base58btc for DID key encoding.¶

Implementations MUST use these algorithms for PAP v1.0. All signable structures carry a SignatureAlgorithm field (serialized as the JWS alg string, e.g. "EdDSA") to enable forward-compatible algorithm negotiation. The field defaults to Ed25519 when absent. Implementations MUST reject algorithms they do not support. The did:key multicodec prefix encodes the algorithm of the public key.¶

Future versions of this specification MAY introduce additional algorithms (e.g., ML-DSA-65 for post-quantum resistance).¶

16.2. Key Management

• Principal private keys SHOULD be stored in hardware security modules or platform authenticators (WebAuthn). They MUST NOT be stored in plaintext in configuration files or environment variables in production.¶
• Session private keys MUST be held only in memory for the duration of the session. They MUST NOT be persisted to disk.¶
• Signing keys for agent operators (used to sign advertisements) SHOULD be protected with access controls appropriate to the deployment environment.¶

16.3. Nonce Management

• Capability token nonces MUST be stored in a consumed-nonce set for at least the duration of the token's validity period.¶
• Implementations SHOULD periodically purge expired nonces to prevent unbounded growth of the consumed-nonce set.¶
• If a receiver restarts and loses its consumed-nonce set, it SHOULD reject all tokens issued before the restart by comparing issued_at against its restart timestamp.¶

16.4. Replay Protection

Multiple layers provide replay protection:¶

1. Token nonces: Each capability token has a UUID v4 nonce consumed on first use.¶
2. Envelope sequencing: Sequence numbers are monotonically increasing within a session. Out-of-order envelopes MUST be rejected.¶
3. Token expiry: Tokens carry an expires_at timestamp. Expired tokens MUST be rejected.¶
4. Session ephemerality: Session keys are discarded at close. A replayed session message cannot be verified against the original session keys.¶

16.5. Denial of Service

• Implementations SHOULD rate-limit token presentation requests to prevent resource exhaustion from session initiation floods.¶
• Federation sync operations SHOULD be rate-limited per peer.¶
• Marketplace registries SHOULD limit the number of advertisements per operator DID.¶

16.6. Man-in-the-Middle

• After Phase 2 (DID exchange), all envelopes MUST be signed by the sender's session key. An attacker who intercepts envelopes cannot forge valid signatures without the session private key.¶
• The initial token presentation (Phase 1) is protected by the orchestrator's signature on the capability token. An attacker cannot forge a valid token without the orchestrator's private key.¶
• Implementations SHOULD use TLS for all HTTP transport to protect against passive eavesdropping.¶

16.7. Context Leakage

• The DisclosureOffer (Phase 3) MUST contain only SD-JWT disclosures permitted by the mandate's disclosure set.¶
• The orchestrator MUST verify that the agent's requires_disclosure is satisfiable by the mandate before issuing a capability token. An agent MUST NOT receive a token if its disclosure requirements exceed the principal's authorization.¶
• Receipts MUST NOT contain personal data values (Section 11.5).¶

16.8. Mandate Chain Depth

Implementations SHOULD enforce a maximum mandate chain depth to prevent resource exhaustion during chain verification. A maximum depth of 10 is RECOMMENDED.¶

16.9. Clock Skew

• Implementations MUST use UTC for all timestamps.¶
• Implementations SHOULD tolerate clock skew of up to 30 seconds for token expiry and mandate TTL checks.¶
• Implementations MAY use NTP or similar time synchronization protocols to minimize skew.¶

16.10. Canonical JSON Determinism

The security of mandate hashing and signature verification depends on deterministic JSON serialization. Implementations MUST ensure that the canonical JSON form produces identical bytes for the same logical content.¶

Implementations SHOULD: - Use a JSON serializer that produces consistent key ordering. - Represent numbers without unnecessary precision. - Use RFC 3339 with explicit UTC offset for all timestamps.¶

If an implementation cannot guarantee deterministic JSON output, it MUST use an alternative canonical form (e.g., JCS [RFC8785]) and document the choice.¶

16.11. Attack Surface Summary

18.1. Schema.org Vocabulary

PAP uses Schema.org (https://schema.org) as the vocabulary for action types, object types, and property references. The following Schema.org types are referenced in this specification:¶

Action Types: - schema:SearchAction -- Search for information - schema:ReserveAction -- Reserve a resource (flight, hotel, etc.) - schema:PayAction -- Make a payment - schema:CheckAction -- Check a condition or status - schema:ReadAction -- Read a resource¶

Object Types: - schema:Flight -- A flight - schema:Lodging -- Lodging accommodation - schema:WebPage -- A web page¶

Entity Types: - schema:Person -- A person - schema:Organization -- An organization - schema:Service -- A service - schema:Order -- An order - schema:Subscription -- A subscription¶

Property References: - schema:name -- Name of a person or entity - schema:email -- Email address - schema:telephone -- Phone number - schema:nationality -- Nationality¶

Implementations MAY use additional Schema.org types and properties. Implementations MAY define additional namespaced vocabularies using a prefix notation (e.g., custom:MyAction). Custom vocabularies SHOULD be documented.¶

18.2. W3C Standards

18.3. IETF Standards

18.4. WebAuthn

18.5. Multicodec

The Ed25519 public key multicodec prefix is 0xed01 as registered in the Multicodec table (https://github.com/multiformats/multicodec).¶

18.6. Reserved Namespace Prefixes

19.1. Normative References

[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997.¶

[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, May 2017.¶

[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet: Timestamps", RFC 3339, July 2002.¶

[RFC4648] Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006.¶

[RFC8032] Josefsson, S. and I. Liusvaara, "Edwards-Curve Digital Signature Algorithm (EdDSA)", RFC 8032, January 2017.¶

[DID-CORE] Sporny, M., Guy, A., Sabadello, M., and D. Reed, "Decentralized Identifiers (DIDs) v1.0", W3C Recommendation, July 2022.¶

[DID-KEY] Longley, D. and M. Sporny, "The did:key Method v0.7", W3C Community Group Report.¶

[SD-JWT-08] Fett, D., Yasuda, K., and B. Campbell, "Selective Disclosure for JWTs (SD-JWT)", Internet-Draft draft-ietf-oauth-selective-disclosure-jwt-08.¶

[VC-DATA-MODEL-2.0] Sporny, M., et al., "Verifiable Credentials Data Model v2.0", W3C Recommendation.¶

[WEBAUTHN] Balfanz, D., et al., "Web Authentication: An API for accessing Public Key Credentials Level 2", W3C Recommendation.¶

19.2. Informative References

[RFC8785] Rundgren, A., Jordan, B., and S. Erdtman, "JSON Canonicalization Scheme (JCS)", RFC 8785, June 2020.¶

[RFC9458] Thomson, M. and C. A. Wood, "Oblivious HTTP", RFC 9458, January 2024.¶

[DIDCOMM-V2] Curren, S., Looker, T., and O. Terbu, "DIDComm Messaging v2.0", Decentralized Identity Foundation, 2022.¶

[RFC6455] Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, December 2011.¶

F.1. A.1. Setup

Principal generates keypair -> did:key:zPrincipal
Orchestrator keypair -> did:key:zOrch
Search agent operator keypair -> did:key:zSearch

F.2. A.2. Root Mandate

{
  "principal_did": "did:key:zPrincipal",
  "agent_did": "did:key:zOrch",
  "issuer_did": "did:key:zPrincipal",
  "parent_mandate_hash": null,
  "scope": {
    "actions": [{"action": "schema:SearchAction"}]
  },
  "disclosure_set": {"entries": []},
  "ttl": "2026-03-15T20:00:00+00:00",
  "decay_state": "Active",
  "issued_at": "2026-03-15T16:00:00+00:00",
  "payment_proof": null,
  "signature": "<base64url>"
}

F.3. A.3. Marketplace Query

query_satisfiable("schema:SearchAction", available=[])
  -> [SearchAgent] (requires_disclosure: [])
  -> Filtered out: agents requiring personal disclosure

F.4. A.4. Session Handshake

Phase 1: Orchestrator -> SearchAgent: TokenPresentation
         SearchAgent -> Orchestrator: TokenAccepted(session_id, recv_did)

Phase 2: Orchestrator -> SearchAgent: SessionDidExchange(init_did)
         SearchAgent -> Orchestrator: SessionDidAck

Phase 3: Orchestrator -> SearchAgent: DisclosureOffer([])
         SearchAgent -> Orchestrator: DisclosureAccepted

Phase 4: SearchAgent -> Orchestrator: ExecutionResult({...})

Phase 5: Orchestrator -> SearchAgent: ReceiptForCoSign(receipt)
         SearchAgent -> Orchestrator: ReceiptCoSigned(receipt)

Phase 6: Orchestrator -> SearchAgent: SessionClose
         SearchAgent -> Orchestrator: SessionClosed

F.5. A.5. Receipt

{
  "session_id": "<uuid>",
  "action": "schema:SearchAction",
  "initiating_agent_did": "did:key:zInitSess",
  "receiving_agent_did": "did:key:zRecvSess",
  "disclosed_by_initiator": [],
  "disclosed_by_receiver": ["operator:search_executed"],
  "executed": "schema:SearchAction executed",
  "returned": "schema:SearchResult returned",
  "timestamp": "2026-03-15T16:05:00+00:00",
  "signatures": ["<initiator_sig>", "<receiver_sig>"]
}

Zero personal properties disclosed. Both session DIDs are ephemeral and discarded. The receipt is auditable but contains no personal data.¶

G.1. B.1. Disclosure Set

{
  "entries": [{
    "type": "schema:Person",
    "permitted_properties": ["schema:name", "schema:nationality"],
    "prohibited_properties": ["schema:email", "schema:telephone"],
    "session_only": true,
    "no_retention": true
  }]
}

G.2. B.2. SD-JWT Claims

Claims: {name: "Alice", email: "alice@example.com",
         nationality: "US", telephone: "+1-555-0100"}
Disclosed: [name, nationality]
Withheld: [email, telephone]  (cryptographically uncommitted)

G.3. B.3. Marketplace Filtering

SkyBook Flight Agent:  requires [name, nationality]    -> satisfiable
LuxAir Premium Agent:  requires [name, nationality, email] -> FILTERED OUT
StayWell Hotel Agent:  wrong object type               -> not matched

G.4. B.4. Receipt

{
  "disclosed_by_initiator": [
    "schema:Person.schema:name",
    "schema:Person.schema:nationality"
  ],
  "disclosed_by_receiver": ["operator:booking_confirmed"]
}

Values "Alice" and "US" never appear in the receipt.¶

I.1. D.1. Core Protocol Tests

I.2. D.2. Transport Tests

I.3. D.3. Extension Tests

I.4. D.4. Federation Tests

I.5. D.5. Trust Invariant Summary

A conformant implementation MUST demonstrate all eight trust invariants hold:¶

End of specification.¶