Virtual Flow Agreement — Protocol Specification
Method and System for Cryptographically Verified Multi-Entity Intent Handshake and Delegated Execution of Digital Transactions
This repository contains the protocol specification for the Virtual Flow Agreement (VFA) concept.
VFA defines a cryptographic intent verification layer for digital interactions, enabling applications and gateways to verify user consent and policy compliance before allowing access to protected services.
The specification describes:
- the handshake protocol
- the visa token format
- the verification and routing flow
- the security model
- the threat model
When a user approves an action online — for example a payment, a deployment, or granting access to data — the system is expected to execute exactly the action the user approved.
In modern distributed systems, requests often pass through multiple services, gateways, and automation layers. As a result, the action that is ultimately executed may differ from the original user intent due to bugs, misconfiguration, or malicious intermediaries.
Virtual Flow Agreement (VFA) introduces a cryptographic intent verification step that binds the user-approved action to the final execution.
In simple terms:
VFA ensures that a system executes exactly the action the user approved — and nothing else.
Authentication proves who you are.
Authorization proves what you are allowed to do.
VFA proves what you actually approved.
VFA v0.1 uses an issuer-signed visa token model.
Roles:
- Wallet — collects explicit user approval for an action
- Issuer — mints a short-lived visa token based on the approved intent
- Merchant — presents the visa token when calling the protected service
- Gateway — verifies the visa token and enforces policy
- Backend — executes only verified requests
Flow summary:
- Merchant creates a handshake request
- User approves the request in the wallet
- Issuer generates a visa token
- Merchant sends request + visa token
- Gateway verifies token and enforces policy
- Backend executes the request
The visa token is the cryptographic artifact binding:
- identity
- declared intent
- policy scope
- expiration
The wallet-signed intent model (where the user's wallet directly signs the artifact rather than an issuer) is considered a future extension and is not normative in v0.1.
Implementation and demonstration projects:
- VFA-MVP — reference implementation of the handshake flow → https://github.com/Csnyi/VFA-MVP
- VFA-Lab — architecture sandbox and gateway routing demo → https://github.com/Csnyi/VFA-Lab
- VFA-cloud-PoC — cloud operation PoC (deployment scenario) → https://github.com/Csnyi/VFA-cloud-PoC
- VFA-Spec - this repository: protocol specification
VFA-MVP implements the handshake flow defined in this specification with the following characteristics relevant to v0.1:
- Issuer role is fulfilled by the Flask backend (
backend/server.py) - Token format:
base64url(JSON payload) + "." + base64url(HMAC-SHA256(secret, payload_b64))
This is a lab-only format; production deployments MUST use asymmetric signatures (Ed25519 / ECDSA P-256) - Approval window (
ttlSec) and token lifetime (exp) are tracked separately in SQLite - Nonce / replay protection is not implemented in the MVP — listed as a known limitation
- Scope is represented as a JSON list (e.g.
["age_over_18", "loyalty_id"]) rather than the recommendednamespace:actionstring; ascopeHash(SHA-256) is stored in the visa record
VFA-Lab implements the gateway and policy enforcement layer defined in this specification:
- Policy outcomes:
prod(valid token),sandbox(missing / invalid token),deny(by policy config) - Token verification uses HMAC shared secret (lab only); asymmetric verification is the declared next step
- Revocation is implemented as a local JSON store at the gateway; distributed revocation is a known gap
- DEFAULT_ROUTE environment variable controls the unauthenticated routing policy
- The gateway demonstrates the L3.5 conceptual overlay — policy enforcement logically between IP routing and application processing; see docs/FUTURE.md for the extended vision
VFA-cloud-PoC demonstrates the VFA handshake applied to cloud operations where critical actions must be verified before execution.
Key characteristics:
- Use case: verification of user intent before sensitive operations (e.g. deployment or production actions)
- Actor mapping:
- Wallet → user approval interface
- Issuer → intent verification service
- Gateway → policy enforcement before the operation
- Backend → cloud operation executor
- Intent binding: the operation request references the verified intent artifact before execution
- Execution model: backend must execute the operation corresponding to the committed intent
- Threat focus: prevention of execution mismatch where an executed action differs from the user-approved intent
This PoC illustrates how the VFA mechanism can be applied to operational workflows such as CI/CD pipelines and production deployment controls.
| Document | Description |
|---|---|
| SPEC.md | High-level overview of the VFA concept |
| PROTOCOL.md | Handshake and interaction protocol |
| TOKEN_FORMAT.md | Visa token structure and fields |
| SECURITY_MODEL.md | Security assumptions and design |
| THREAT_MODEL.md | Threat analysis |
| GLOSSARY.md | Authoritative terminology definitions |
| CHANGELOG.md | Version history |
| docs/FUTURE.md | Post-v0.1 vision: L3.5, wallet-signed intent, delegation |
VFA-Spec
├─ README.md
├─ SPEC.md
├─ PROTOCOL.md
├─ TOKEN_FORMAT.md
├─ SECURITY_MODEL.md
├─ THREAT_MODEL.md
├─ GLOSSARY.md
├─ CHANGELOG.md
├─ PATENTS.md
├─ LICENSE
├─ diagrams/
├─ examples/
└─ docs/
└─ FUTURE.md
The VFA specification is released under the Apache 2.0 license.
This allows independent implementations of the protocol.
The VFA concept may be subject to patent applications.
The specification in this repository is published to support open research and interoperable implementations.
See the PATENTS file for additional information.
Draft specification.
Version: v0.1
This repository is experimental and may evolve as the VFA architecture matures.
Delegated authorization is considered a future extension.
Potential fields include:
delegatordelegatedelegationScopedelegationExp
Delegation is not normative in VFA v0.1.
This project is the result of iterative exploration, experimentation, and cross-domain thinking across distributed systems, security, and API design.
Special thanks to:
- the open-source community for inspiration and foundational ideas
- researchers and engineers working on zero-trust, cryptographic verification, and secure system design
- early readers, reviewers, and contributors providing feedback and direction
This work was also shaped through extensive design iteration, discussion, and prototyping with the assistance of AI-supported development tools.
If you find this work valuable, your star helps signal relevance, supports visibility, and encourages further development.
The goal of VFA is to contribute a clear and practical step forward in making user intent verifiable, enforceable, and auditable in modern systems.