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.
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, applies authorization and rate limits, stores endpoint/pairing/conversation state, 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. Transport encryption does not make those records end-to-end encrypted.

Object	Lifecycle	Important boundary
Endpoint link	Active until its configured expiry, revocation, or request/reuse limit	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 token	Signed token with a 7-day expiry	Stored in browser storage; no per-token server revocation is implemented
Registered bearer token	Signed token with a 30-day expiry	Possession authorizes the corresponding account until expiry
Conversation	Unsaved: 24-hour sliding inactivity expiry; saved: retained until destroyed	Close stops messaging but does not delete the record

• 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 replay: a stolen unexpired bearer token can be replayed. TLS, expiration, origin controls, authorization, and rate limits reduce exposure but do not provide per-token revocation.
• 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.
• No E2E or zero-knowledge guarantee: The server can process and read messages and contact cards. A compromised server or operator boundary is therefore in scope.
• 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.