WebSocket API

The WebSocket API provides real-time communication between the Secrets Agent and the Mobile App for secret approval requests.

Connection

Authentication Handshake

The WebSocket connection uses a challenge-response authentication flow with Ed25519 signatures:

1. Client connects to the WebSocket server
2. Server sends a challenge message with a 32-byte CSPRNG nonce
3. Client signs the nonce with its Ed25519 private key
4. Client sends an auth message with the signature and public key
5. Server verifies the signature and responds with auth_ok or auth_error

Client                          Server
  |                                |
  |  ←── challenge { nonce }       |
  |                                |
  |  ──→ auth { sig, pubkey }      |
  |                                |
  |  ←── auth_ok / auth_error      |
  |                                |

Server → Client Messages

challenge

Sent immediately after connection. Contains a one-time nonce for authentication.

auth_ok

Authentication succeeded. Connection is now authorized.

auth_error

Authentication failed. Connection will be closed.

secret_request

A secret access request pending user approval.

ping

Keepalive ping. Client must respond with pong.

Client → Server Messages

auth

Response to the challenge message.

secret_response

User's response to a secret access request.

pong

Keepalive response. Must be sent in reply to ping.

Security

• Nonce consuming: Each challenge nonce can only be used once. Replay attacks are prevented.
• Timestamp drift: Nonces older than 30 seconds are rejected.
• Ed25519 signatures: 32-byte keys, 64-byte signatures. The server verifies the client's public key is registered.
• TLS mandatory: In production, connections must use wss:// for transport encryption.
• E2E encryption: Secret values are encrypted with X25519 ECDH + AES-256-GCM between mobile and secrets agent. The WebSocket transport never sees plaintext.

JavaScript Client Example

const ws = new WebSocket('ws://localhost:8765');

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case 'challenge':
      // Sign the nonce with Ed25519 private key
      const signature = ed25519Sign(msg.nonce, privateKey);
      ws.send(JSON.stringify({
        type: 'auth',
        signature: signature,
        public_key: publicKeyHex
      }));
      break;

    case 'auth_ok':
      console.log('Authenticated:', msg.session_id);
      break;

    case 'secret_request':
      // Show approval UI to user
      showApprovalDialog(msg);
      break;

    case 'ping':
      ws.send(JSON.stringify({ type: 'pong' }));
      break;
  }
};