V2 protocol trust

Paybond's protocol-trust layer adds delegated authorization and signed settlement receipts on top of the core Harbor lifecycle. It is designed for workflows where another runtime, agent, or partner system needs portable proof of authorization and outcome.

The core Harbor, Gateway, Signal, and Kit flows remain the primary operating contract. The protocol-trust layer adds an import-and-verification surface for external mandates, recognition proofs, and receipts.

What this layer adds

• Verification of external mandates before they are bound to a Harbor intent.
• Replay-safe recognition proofs for delegated or cross-runtime actions.
• Signed authorization and settlement receipts that can be verified outside the live application.
• Discovery documents for delegated workflows and task contracts.

Gateway protocol surface

Gateway exposes the following protocol surface:

Operating model

1. A partner or runtime presents a signed AgentMandateV1 plus a replay-safe AgentRecognitionProofV1.
2. Gateway verifies the recognition proof for the exact request envelope and purpose, verifies the mandate, checks tenant scope, validates Harbor alignment for the referenced intent_id, binds the mandate digest to Harbor, and returns a signed ProtocolAuthorizationReceiptV1.
3. Later Harbor mutations flow through Gateway recognition-gated /harbor/* routes with purpose-specific proofs.
4. When the bound Harbor intent reaches a protocol-terminal state, Gateway emits ProtocolSettlementReceiptV1.

This keeps Harbor as the source of truth for money movement while making authorization and settlement artifacts portable. POST /protocol/v2/mandates imports and binds an external mandate; it does not issue a Paybond-native mandate.

Protocol source binding

Paybond is AP2-aligned at the protocol boundary: imported external mandates and exported protocol receipts carry transport_binding.source_protocol, which defaults to ap2 when omitted. Harbor remains the source of truth for settlement, evidence, and lifecycle state; the protocol source is metadata for trust-anchor lookup, receipt correlation, and operator review.

Harbor-backed mutations

Protocol-driven flows recognition-gate these Harbor mutations:

• POST /harbor/intents
• POST /harbor/intents/{intent_id}/fund
• POST /harbor/intents/{intent_id}/evidence
• POST /harbor/intents/{intent_id}/settlement/confirm
• POST /harbor/operator/v1/intents/{intent_id}/dispute/open
• POST /harbor/operator/v1/intents/{intent_id}/dispute/resolve

Settlement receipts

Receipt verification accepts both ProtocolAuthorizationReceiptV1 and ProtocolSettlementReceiptV1. In the current contract, settlement receipt lookup keeps receipt_id == Harbor intent_id.

Settlement receipts are emitted only for these protocol-terminal outcomes:

• released or refunded from the bound Harbor intent
• resolved_split or escalated_external from the tenant-scoped Gateway dispute case for a still-disputed Harbor intent

Plain disputed is not terminal enough to export a settlement receipt.

When multiple dispute cases for the same intent are protocol-terminal, the settlement receipt uses the case with the latest terminal timestamp (resolved_at, then updated_at, then created_at). Equal timestamps prefer escalated_external over resolved_split.

Runtime surfaces

TypeScript and Python Kit expose mandate import, receipt reads, receipt verification, and A2A discovery. The packaged TypeScript and Python MCP servers call the same Gateway protocol routes and recognition-gated Harbor routes under the hood.

Tenant audit export bundles (protocol include) add offline artifacts for mandate import summaries, per-intent mandate detail, export-time settlement receipts for protocol-terminal intents, and a tenant trust-registry snapshot. See audit export compliance.

Signal scope

Signal remains private and tenant-scoped. Adjacent signed artifacts such as GET /reputation/{operator_did} and GET /signal/v1/portfolio/signed-export remain authenticated rather than becoming a public reputation plane.

Trust-anchor hardening

Gateway now enforces tenant-managed trust anchors for protocol recognition and mandate import:

• recognition proof key_id must resolve in the authenticated tenant’s trusted agent key registry,
• if the same key_id exists under another tenant, Gateway rejects it with an explicit tenant-mismatch protocol error instead of treating it as local success,
• the proof-carried signing_public_key_ed25519_hex must match the registered Ed25519 key for that tenant entry,
• revoked, unregistered, tenant-mismatched, mandate-mismatched, and bound-intent key-divergence cases all fail closed with explicit protocol errors,
• imported mandate bindings persist the original signed mandate payload, the original recognition proof payload, and normalized mandate agent metadata for audit and dispute evidence,
• tenant admins manage the registry through API-first control-plane routes and the admin console machine-access workspace:
  • GET /v1/admin/protocol/agent-keys
  • POST /v1/admin/protocol/agent-keys
  • POST /v1/admin/protocol/agent-keys/{key_id}/revoke

Out of scope

• Paybond-issued mandates
• shared-SaaS Signal topology rewrite
• public reputation surfaces
• consumer checkout and merchant shopping flows

Related

• Platform overview
• Tenant model
• Intent lifecycle
• Ledger & provenance
• API documentation
• Gateway API reference
• Kit documentation