VXPVerifiable eXchange Protocol Draft 0.1

Architecture · draft 0.1

How VXP fits together

Who takes part, which identities stay apart, where a request enters, what the company checks before anything runs, and who signs each piece of evidence. Every diagram separates what the specification requires from how the reference implementation does it.

Solid outline: contract in the specificationDashed outline: reference implementation, or outside VXP

1Participants#

Six roles. The first four appear in every operation; the operator runs the company's side, and the verifier can be anyone who later checks the evidence.

Person

The person the agent acts for, and the company's end customer. Approves exact terms, approves a relationship, and can revoke either.

Signs nothing in the chain

Personal agent

The person's OAuth client or A2A agent. Identifies with its own key, holds the delegation, asks, accepts, answers the company's requests and keeps the proof.

Proves possession of its key on each call

Company

Who executes the operation. Has its own issuer, publishes what it offers, and is the party the terms and the result belong to.

Signs terms, company_review, outcome, correction, revocation

Company system

The system of record, such as the ERP, where the effect actually lives. It is changed once and read back afterwards.

Read, never trusted as a signer

Operator

Hosts the company's side and executes on its behalf, as processor for each company. In the reference implementation, the operator is SOVRAS.

Signs request, counter, user_approval, execution, read_back

Verifier

Anyone who checks a proof package: the agent itself, a bank, an arbitrator, an auditor. Anchors the issuer on its own and derives the level of evidence.

Signs nothing; reports a verdict

2Identities#

A phone number, a customer account and a delegation answer different questions. VXP keeps them as three layers that are never merged, and moves from one to the next only through a step the company controls.

Three identity layers: channel identifier, customer at the company, delegated authorization, joined only by company-controlled steps Channel identifier e.g. a WhatsApp number Proves: someone controls this channel authentication the company controls, evidence kept · ID1 Customer at the company canonical customer, linked to the ERP Proves: which account and resources are theirs delegation the person grants to one agent Delegated authorization client_id · sub · scopes · authorization_details Proves: what this agent may ask, for this person owner = (profile, client_id, sub, account) ID3 · another key, sub or client_id sees nothing
Matching by name, email or phone never links an account (ID1), and a number shared by two customers links neither (ID2). Rules in the specification, §5.

3Native profile and discovery Experimental#

The native profile is VXP's own form: an agent that speaks neither Poppy nor PACT discovers the company, identifies, receives authority per request, operates, obtains the proof and keeps the relationship with it alone. It works alone, without either adapter (specification §8, native-only gateway), and a company can also publish it next to the adapters. All entries share one issuer, one authorization server and one set of metadata.

DocumentWhereWhat it carries
vxp.json Experimental/.well-known/vxp.json on the company's domainOrganization and domain, issuer, endpoint, capabilities with access and admission, negotiation limits, "status": "experimental". No trust members
Issuer metadataRFC 8414, under the issuervxp_proof: the proof keys, operator, custody, log and domains. vxp_relationship: the relationship key and the actions the company may start
poppy.jsonThe company's domainThe Poppy draft 0.2 document, as written, with the vxpprotocol.org/proof extension
Agent CardThe PACT provider, or redirected from the brand's domainThe PACT 1.0 card over A2A 1.0.1, as written, with https://vxpprotocol.org/ext/proof/v0.1

The trust members live in one place, the issuer metadata. Any copy in poppy.json or the Agent Card must be identical, and vxp.json carries none. Only the well-known locations and the native endpoints are fixed; every other location, such as the key sets or the log, is read from the metadata and is the implementation's own choice (implementation paths). Discovery, authorization and endpoints in detail: specification, §8.

4Entries and adapters#

A request can arrive through the native profile or through an adapter. An adapter speaks the external protocol literally; what VXP adds travels only in that protocol's extension points. All entries end in one normalized request, the same operation requirements and one enterprise execution.

Entries: native profile, Poppy adapter, PACT adapter and traditional channels converge on a normalized request, the operation requirements, one execution, and then VXP Proof and VXP Relationship Personal agent VXP native vxp.json · experimental Poppy adapter poppy.json · draft 0.2 PACT adapter Agent Card · PACT 1.0 Traditional channels SOVRAS · outside VXP Normalized request identity · authority · company · operation Operation requirements O1 to O7 owner · scope · resource · terms review · once · read-back One execution, then read-back operator · rules I2, P5, P6 Company system VXP Proof signed chain of statements VXP Relationship agreement · signed outbound
  • contract in the specification
  • reference implementation, or outside VXP
EntryIdentity and authorityWhere VXP travels
VXP native ExperimentalClient metadata, private_key_jwt, DPoP, per-request authorization_detailsIt is VXP's own profile
Poppy draft 0.2Poppy sign-in, sessions, conversations and OperationsA domain-named member, vxpprotocol.org/proof, only for an agent that lists the extension
PACT 1.0 over A2A 1.0.1PACT agent identity and delegated authorityAn A2A extension and message.metadata, next to pact.receipt
Traditional channelsNone: WhatsApp, web chat and voice are a SOVRAS capabilityNot part of VXP. A write never runs in the channel; the agent is offered the structured connection

Whatever the entry, the company needs no conversational agent of its own: a deterministic intermediary serves the Poppy API and the PACT A2A service (I3). Interoperability rules I1 to I5: specification, §4.

5Operation requirements#

A valid identity is a starting point. What passes is the intersection of what the person delegated, what the company allows and what the resource admits. VXP states this as operation requirements O1 to O7: the behaviour every implementation shows where an external request becomes an operation. They are requirements, not a component: VXP defines no interface for them, and how an implementation builds them inside is its own decision.

Three overlapping circles: delegated by the person, allowed by the company, admitted by the resource. Only their intersection runs. Delegated by the person scope, per-request authorization Allowed by the company what it publishes, its review rule Admitted by the resource owner, precondition, one operation at a time What runs
Outside the intersection the answer is authorization_required, or the same not-found answer for someone else's resource and for a missing one.
RequirementWhat the implementation doesEvidence in VXP Proof
O1 Identity and ownerLinks an account only through an authentication the company controls; the owner is (profile, client_id, sub, account)Not shown by the chain; still required
O2 ScopeWhat is asked fits the delegation and what the company publishesNot shown by the chain; still required
O3 Own resourceSomeone else's, missing and unlinked resources answer the sameNot shown by the chain; still required
O4 Terms and commitmentThe company signs the exact revision and its commitment; a change is a new revisionterms and user_approval on the same digest
O5 Company reviewWhen its rule requires it, a person at the company decides on the same digestcompany_review
O6 One executionOne per resource, with precondition and idempotency keyOne execution on the approved digest
O7 Read-backNo succeeded without it; a contradiction goes to waiting_humanread_back, by term name
Normative

Requirement and evidence

  • Required behaviour: rules O1 to O7, defined by the specification.
  • Evidence: what VXP Proof records so that anyone can check that behaviour afterwards. A rule the chain cannot show is still required; the verifier only reports what the chain carries.
Informative

Internal controls, outside VXP

  • The catalog, policies, checks and locks that enforce the rules inside one company's systems belong to each implementation.
  • In the reference implementation they are SOVRAS's own mechanism: catalog, prior read in the ERP, policy, commitment, one execution, read-back and projection to Poppy and A2A.

Each rule with its identifiers, and the table of requirement, evidence and control: specification, §9.

6Relationship#

With an agreement the person approved, the company can start a request toward the person's agent. The agreement names its actions, a daily limit and an expiry, and ends when the delegation is revoked. Before signing or sending anything, the company checks that all of it still holds (R6). A relationship does not replace the company's authorization: inside it, each request still passes the company's own rules.

Sequence of a relationship over HTTP: consent, signed agreement, a company request, the person's approval, acceptance and a single execution Person Personal agent Company Company system 1 · relationship RAR 2 · consent, its own checkbox (R3) 3 · approves actions, limit, expiry 4 · agreement JWS (R4) later, inside the agreement 5 · signed request (R7) 6 · exact terms 7 · approves 8 · accept (R8, R9) 9 · execute once
  1. The agent asks for the relationship in the Device Authorization, with an authorization_details entry of type relationship.
  2. The consent screen shows the relationship in business language, with its own checkbox.
  3. The person approves the actions, the daily limit and the validity.
  4. The token carries relationships[] and the agreement, a JWS vxp-relationship+jwt.
  5. The company sends a JWS vxp-company-request+jwt to the agent's inbox. Proposing a change never executes it.
  6. The agent shows the person the exact terms of the new revision.
  7. The person approves.
  8. The agent accepts; the company checks again that the relationship and the delegation are in force.
  9. The operation runs once and is read back, with its own proof chain.
Delivery pathHow the agent receives and answersState
HTTP inboxPOST {inbox_uri} declared in the agent's client metadata, on the same origin as its client_idExperimental Tested only with a server of SOVRAS's own
Poppy conversationMessages with data["vxpprotocol.org/relationship"] inside the agent's conversation; offer, agreement, request, answer and a signed reply receiptRun once with a live personal agent through the Poppy adapter; no agent outside SOVRAS's runs yet
PACTNot specified yetPending

Rules R1 to R17: specification, §7.

7Proof#

Each operation leaves a chain of signed statements. Each one names the previous by its digest and is signed by the role that observed it, so a verifier knows who said what at every link. The terms digest ties the approval, the execution and the result to one exact revision. VXP Proof is not an execution engine: it records what was asked, approved, executed and observed.

Proof chain: statements alternate between the company column and the operator column, each pointing to the previous one by digest; counter, company review and correction are optional Company signs Operator signs requestdigest of what was asked termsrevision, commitment counteroptional user_approvalmethod, latest revision company_reviewoptional, by role executiononce, approved digest read_backobserved, by term name outcomestate, summary digest correctionoptional, after final each arrow is prev: the digest of the statement before
  • company
  • operator
  • optional statement
SituationWhat the chain saysRule
Read-back matches the approved termsoutcome: succeededP1
Not known whether the effect happenedoutcome: unknown; Poppy sees in_progressP3
Known laterA correction on the latest final statementP4
Read-back contradicts the termsmatches_terms: false, unknown, waiting_humanP5
The capability cannot be read backread_back.method: none, never succeededP6

Approval comes in two kinds, named by what they prove: agent_asserted (the agent said the person approved) and company_channel (the person answered from the channel the company linked to them, with a code derived from the terms digest). Format, chain rules and P1 to P8: specification, §6.

8Enterprise execution#

Execution uses the systems and permissions the company already has. The protocol fixes how many times it runs, under which conditions, and what has to be read afterwards.

  • One per resource (I2). Whatever entries arrive, one execution per resource. Each entry produces its own operation, and only the first that passes the precondition takes effect; the others end failed, without effect and with their evidence.
  • Precondition. The terms that describe the starting state are checked against the company's system right before executing. If they no longer hold, nothing runs and the operation ends failed without an execution in the chain.
  • One in progress. While a confirmed operation on a resource is in progress, no other one is opened on it; the native profile answers resource_busy.
  • Re-verification. Before executing, the grant for the resource, the policy and the precondition are evaluated again with the token of the accepting call.
  • At most once. No more than one automatic execution attempt per accepted revision.
  • Declared effects. A request that ends failed or cancelled after execution started lists effects[] per system touched. A compensation is read back before it is declared reverted.

The outcome of an operation comes from that operation's execution, never from the close of the conversation that contains it.

9States#

Eleven internal states are the source. Outside, each protocol sees only its own enum: VXP adds no values to Poppy's or A2A's. Under A2A and PACT, the internal state travels in metadata.

Scroll sideways to see the whole diagram

Projection of the eleven internal states to Poppy operation states and to A2A TaskState values Poppy operations Internal (source) A2A TaskState TASK_STATE_… received authorization_required proposed accepted waiting_human executing pending_verification succeeded failed cancelled expired no operation proposed in_progress succeeded failed cancelled expired SUBMITTED AUTH_REQUIRED INPUT_REQUIRED WORKING COMPLETED FAILED CANCELED
Filled boxes are final states, which never change; later facts go as a correction in the proof. Under PACT there are no tasks, so the A2A value is used only in metadata, next to the internal state. Legal transitions: specification, §4.

waiting_human covers two cases: the company's review before executing, and a contradiction found after executing. pending_verification is where an operation waits while nobody knows yet whether the effect happened; it is never reported as failed.

10Recovery#

What happens when something goes wrong, or when the answer is not known yet. In every case the action is not repeated and nothing is claimed that was not read back.

SituationWhat happens
The agent repeats a requestSame Idempotency-Key and same body return the same request; another body with the same key gets 409 idempotency_key_reused
The terms changed before approvalA new revision, approved again; accepting an old one gets 409 terms_changed
The result is not knownpending_verification and outcome: unknown; reading again reconciles against the system and never repeats the action
The result becomes known laterA correction in the chain; to succeeded only with a later matching read-back
The system contradicts the approved termswaiting_human, no retry, no success declared
The agent cancels while it runsA request to stop: 202, the state does not change because of it, reversal_promised: false; it ends cancelled with known effects, or in the state it reached
An approval message could not be deliveredThe operation stays proposed and does not run; a code that was never sent approves nothing
The person revoked in the meantimeAccepting a relationship's proposal gets 403 relationship_revoked, without effect
A company request could not be deliveredRecorded as failed in the company's outbox. Retries with backoff are Pending

11Verification and trust boundaries#

Who signs what, who holds each key, and what a verifier can conclude from it. In the reference implementation today, the operator holds every proof key, so the operator is the single root of trust, and the verifier says so in every verdict.

Scroll sideways to see the whole diagram

Trust boundaries: the company proof key, the operator proof key and the log key are held by the operator today; the verifier anchors the issuer metadata and reports a single root, the operator Held by the operator today · custody: operator_hosted Company proof key terms · company_review · outcome · correction · revocation Operator proof key request · counter · user_approval · execution · read_back Log key checkpoints of the transparency log published under the issuer Issuer metadata RFC 8414 · vxp_proof keys · operator · custody · log Verifier derives levels single_root: operator Personal agent key private_key_jwt and DPoP on every call; nothing in the chain is signed by the agent
The verifier anchors the issuer on its own account and reads the keys from its metadata. With every proof key held by the operator, the chain is an operator attestation: intact and ordered, and not independent of SOVRAS.

A verifier can check today

  • That the chain has not changed since it was received, is coherent and ordered.
  • Which role signed each link.
  • That the execution was on the approved revision, and the read-back matched it.
  • That nobody other than whoever controls the issuer assembled the package.

What independence still needs Pending

  • Witnesses of the log outside the operator; the list of witnesses is empty today, so no package reaches logged.
  • The company's key held outside the operator, in a way a verifier can check.
  • A second independent issuer.

The relationship has its own key, published as vxp_relationship.jwks_uri and different from the proof keys and from the Poppy and PACT keys (R5). Each statement names its key by kid; an issuer that rotates a key keeps the earlier public key published, so older proofs still verify (key rotation). How to read each part of a verdict: reading a verdict. Assurance levels and the verification algorithm: specification, §10. Check a proof yourself in Verify.

Every rule behind these diagrams, with its identifier.

Read the specification