VeilPair Handoff Protocol (VP-Handoff/1)

VP-Handoff/1 is documentation for the currently deployed application workflow. It maps the endpoint, pairing-request, and conversation records into the following conceptual state sequence:

CREATE ──► SHARE ──► CLAIM ──► CHALLENGE ──► CONFIRM ──► CONNECT ──► EXPIRE / DESTROY
          

1. CREATE: Initiator creates endpoint with configurable lifetime (default 24h) and single/multi-use flags.
2. SHARE: Initiator posts the handoff link in a public/pseudonymous interaction.
3. CLAIM: Recipient opens the link and explicitly submits a request. A GET request alone does not claim the endpoint.
4. CHALLENGE: Server issues an isolated challenge code (e.g. KITE-583) tied to the claim.
5. CONFIRM: Recipient posts challenge code in original thread; Initiator matches code and approves.
6. CONNECT: Server upgrades claim to an active conversation room with WebSocket relay and per-room DEK generation.
7. EXPIRE/DESTROY: An unsaved conversation expires after 24 hours of inactivity, or either participant manually destroys it. Saved conversations skip automatic expiration until destroyed.

• Initiator: creates and owns an endpoint, reviews pending pairing requests, and accepts or rejects a request.
• Requester: explicitly claims an endpoint, receives a short pairing code, and waits for the Initiator's decision.
• Application server: authenticates bearer tokens with server-side session checks, stores encrypted conversation records, and relays WebSocket events.
• Original public platform: optional out-of-band context where the Requester can post the pairing code. VeilPair does not control or authenticate that platform.

The application persists endpoint, pairing-request, conversation, message, and contact-card records in its server-side datastore with server-managed envelope encryption at rest. It is not end-to-end encrypted.

Object	Lifecycle	Important boundary
Endpoint link	Active until configured expiry (normally 24h); purged after 24h grace period	The public slug is not a secret once shared
Pending pairing request and code	Pending for 15 minutes unless accepted, rejected, or removed earlier	The human-readable code is contextual evidence, not an authenticator for legal identity
Guest bearer session	Server-side revocable session with a 7-day expiry; inactive guests removed after 7 days	Immediately revocable on logout
Registered bearer session	Server-side revocable session with a 14-day expiry	Immediately revocable on logout
Conversation	Unsaved: 24-hour sliding inactivity expiry; saved: retained until destroyed	Message text and contact cards encrypted at rest with per-room AES-256-GCM DEK

• Duplicate or late decision: the server checks the current pending state; a resolved or expired request cannot be accepted as a new pending request.
• Expired endpoint/request: the operation fails and the client must create or request a new valid handoff.
• Unauthorized access: endpoints, pairings, conversations, and messages require the corresponding owner or participant bearer token.
• Concurrent requests: request and reuse limits are enforced against server state, but a public endpoint can receive unwanted pending requests before the owner approves one.
• Token revocation: server-side sessions can be revoked immediately on logout, mitigating token replay after session termination.
• WebSocket interruption: real-time delivery can disconnect; persisted server state remains authoritative when the client reconnects.

• Original Context Integrity: The protocol assumes that the original public context (e.g. Facebook group thread) is visible to the Initiator, allowing out-of-band challenge code matching.
• Transport Security: All client-server communications require TLS (HTTPS / WSS).
• No identity proof: A matching code links control of a requesting browser and a public persona at a moment in time. It does not establish a participant's real identity, age, intent, or trustworthiness.
• Server-managed encryption at rest: Messages and shared contact cards are encrypted at rest using AES-256-GCM with unique per-conversation DEKs wrapped under server KEKs. The service is NOT end-to-end encrypted or zero-knowledge.
• Client and recipient limits: The protocol cannot prevent screenshots, copied contact details, compromised browsers, phishing, coercion, or voluntary disclosure.
• Versioning: VP-Handoff/1 documents the current MVP behavior. A breaking change to actors, state transitions, token/challenge semantics, or retention must use a new protocol version and update this page.