Platform & Server

Blind Relay Protocol

HTTP/WS APIs, Challenge-AUTH Ed25519 signing, Redis offline queues, step claims, geohash beacons, and ephemeral tunnels.

Overview

The Wiltkey Blind Relay acts as a blind mailbox. It coordinates client routing, handles temporary queueing of offline messages, manages grid-based geohash beacons, and maps ephemeral connection tunnels. Cryptographic verification ensures the server learns nothing about the user's relationships, and message payloads are deleted instantly upon delivery.

GATT Challenge-AUTH Flow

Client Device Keys: identityKeyPair Blind Relay websocket.go 1. Connect WebSocket /ws 2. Frame: CHALLENGE (32B random hex) 3. Frame: AUTH (pubkey + challenge_sig) 4. Frame: AUTH_OK (userID)

How it Works

1. Challenge-Response Authentication

When a WebSocket connects to /ws, the server upgrade executes ServeWS. The server generates a random 32-byte hex challenge and writes it back as a CHALLENGE frame. Within 5 seconds, the client must reply with an AUTH frame containing its Ed25519 identity public key and a signature of the challenge hex. The server verifies this signature using VerifySignature. On success, the server derives the userID as the hex-encoded digest of SHA-256(publicKeyBytes) and registers the socket connection.

2. Message Routing & Offline Queues

When routing a message (SEND_MESSAGE):

  • The server queries Redis to verify the recipient's queue is not blocked due to a nuke command.
  • If the recipient is currently online (present in hub.clients), the envelope is forwarded immediately as a NEW_MESSAGE frame.
  • If offline, the server pushes the envelope to a Redis queue (AddMessageToQueue) with a 24-hour TTL. It is delivered and cleared instantly the moment the recipient logs in.

3. Atmospheric Charge (Pedometer Step Claims)

Wiltkey implements step claims (CLAIM_STEPS) to recharge messaging budgets. The server tracks step conversions in Redis (storing daily steps under a date key: 2006-01-02). Claims are limited to a daily cap of 10KB (10240 bytes) of keystream equivalence.

4. Geohash Beacons & RSVPs

  • DROP_BEACON: Registers an ephemeral envelope in a grid defined by a geohash coordinates bounding box. Cost: 100 Bytes of user charge. Ephemeral pubkeys are mapped directly to connection sockets.
  • GET_BEACONS: Queries Redis for active beacons within a geohash sector.
  • RSVP_EVENT: Registers a blind commitment hash to RSVP for an OSM-snapped community event. Cost: 500 Bytes of charge. Prevents duplicate RSVPs.

5. Ephemeral Tunnels

Tunnels map temporary socket routing lines between two ephemeral public keys (TUNNEL_INIT) for up to 1 hour. Tunnels enforce a strict bandwidth quota check in handleTunnelPacket: if the total data forwarded through the tunnel exceeds 1KB (1024 bytes), the server triggers a TUNNEL_CLOSED packet and wipes the route mapping, protecting against tunnel spam.

Key Files & Symbols

File Path Symbol Name Description
wiltkey_server/websocket.go ServeWS() Handles HTTP WebSocket upgrades and runs challenge signature authentication.
wiltkey_server/handlers.go handleSendMessage() Verifies queue block status and routes messages online or stores them offline.
wiltkey_server/handlers.go handleTunnelPacket() Audits bandwidth and locks/closes tunnels if packet sizes exceed 1KB.
wiltkey_server/auth.go VerifySignature() Verifies Ed25519 signatures of challenge payloads.

Gotchas & Edge Cases

⚠️ DRIFT TIME & IP BANNING POLICY
HTTP API requests (such as /api/v1/queue/status) verify signature timestamps. If the timestamp drift exceeds 30 seconds compared to the server clock, the request fails. The server records validation failures in Redis: the 1st failure bans the IP for 5 minutes, and subsequent failures ban the IP for 30 minutes, blocking all endpoints.