@benkovy/doh-protocol

Shared protocol package for all DOH runtime components.

Purpose

This package defines wire-level message schemas and strongly-typed envelopes used by:

• @benkovy/doh-backend
• @benkovy/doh-host
• future DOH channel clients

Using one package for contracts prevents drift between backend and host/client implementations.

Scope

Current schema set includes:

• host handshake envelopes (host.hello, backend.challenge, host.proof, backend.ready, backend.error)
• relay command envelopes (relay.send, relay.history.request, relay.conversations.request)
• relay stream envelopes (relay.event, relay.history.response, relay.conversations.response)
• client stream control envelopes (client.hello, client.subscribe, client.unsubscribe)
• backend->client stream envelopes (backend.client.ready, backend.client.event, backend.client.error)

Host auth handshake (P1-1)

Current handshake sequence:

1. Host sends host.hello
2. Backend replies with backend.challenge (challengeId, nonce, expiresAt)
3. Host sends host.proof with HMAC signature over canonical proof base
4. Backend replies backend.ready on success, or backend.error on failure

buildHostProofBase(...) is exported and should be used by both backend and connector to avoid signature drift.

Backend auth error codes

• AUTH_REQUIRED
• AUTH_INVALID_HOST
• AUTH_CHALLENGE_REQUIRED
• AUTH_CHALLENGE_EXPIRED
• AUTH_CHALLENGE_MISMATCH
• AUTH_TIMESTAMP_SKEW
• AUTH_SIGNATURE_INVALID
• AUTH_REPLAY_DETECTED
• BAD_ENVELOPE
• INTERNAL_ERROR

Validation approach

• Runtime validation uses zod
• Compile-time types are inferred from schemas
• Envelope parsing should happen at every trust boundary

Usage

import { parseBackendEnvelope } from "@benkovy/doh-protocol";

const envelope = parseBackendEnvelope(JSON.parse(raw));

Design notes

• Keep envelope type values stable and additive
• Prefer optional fields for backward compatible evolution
• Use explicit ids (eventId, requestId, clientMessageId) for idempotency and reconciliation