title: ClawQL QR Stream Transport — Specification v0.1

ClawQL QR Stream Transport — Specification v0.1

Status: Draft · August 2026 · v0.1
Components: mcp-api-adapter (planned 8th surface; /mcp-ui is 7th, shipped) · clawql-streams (qr source type) · clawql-tee / clawql-tee-verifier
Depends on: clawql-tee-airgap-audit v0.1 · clawql-streams v0.2 · mcp-api-adapter
Related: clawql-tee · clawql-government · clawql-surveillance

1. What this is

QR stream transport is the seventh surface in mcp-api-adapter and a new event source type in clawql-streams. It enables MCP communication and event streaming over a physical optical channel — QR codes on a screen, scanned by a camera — with no network connection required.

The seven shipped surfaces (OpenAPI, GraphQL, Streamable HTTP /mcp, gRPC, gen-cli, WebSocket, /mcp-ui) assume a network (or a browser on one). QR stream is for when there is no network, must not be one, or the channel must be physically verifiable and unidirectional.

Property	Meaning
Unidirectional by default	Display → camera; no return channel required
Cryptographically verifiable	Merkle chain, per-frame HMAC, optional TEE attestation
Network-independent	Air gap is structural, not policy
Physically auditable	Thermal printer → paper QR sequence, scan/verify later

Frame format extends the TEE air-gap audit AuditFrame with MCP and election payload types.

2. Transport modes

2.1 Unidirectional stream (primary)

Air-gapped system (display only)
  │  QR frames (optical, one-way)
  ▼
External camera → clawql-streams QR source
  │
  └─ Agent DO / NATS buffer / WORM audit

Use cases: TEE audit export, voting machine ballot streaming, regulated financial export, industrial sensors, government auditor on-site export (clawql-government).

2.2 Bidirectional (interactive MCP)

Client device                         MCP server (air-gapped)
  │──── QR: tool call request ──────▶│ (server camera)
  │◀─── QR: tool call result ────────│ (server display)

Two screens, two cameras. Full MCP request/response over optical channel — slower than network, physically verifiable each step. Use cases: air-gapped KMS/HSM interaction, secure signing in isolated environments.

3. Frame format

#[derive(Serialize, Deserialize)]
pub struct QrTransportFrame {
    pub session_id: Uuid,
    pub frame_index: u32,
    pub total_frames: Option<u32>,      // None for continuous streams
    pub frame_type: QrFrameType,

    pub payload: Vec<u8>,               // CBOR + zstd + optional ChaCha20-Poly1305
    pub payload_hash: [u8; 32],
    pub prev_frame_hash: [u8; 32],
    pub chain_root: [u8; 32],
    pub hmac: [u8; 32],

    pub transport_version: u8,          // 1
    pub source_type: QrSourceType,      // Audit | Mcp | Election | Stream
}

pub enum QrFrameType {
    Header,
    McpRequest,
    McpResponse,
    AuditChunk,
    Attestation,
    StreamEvent,
    ElectionBallot,
    Footer,
    Heartbeat,
}

Encoding matches air-gap audit: CBOR → zstd → ~2 KB chunks → QR v40 ECC M; optional ChaCha20-Poly1305; Header carries ephemeral key for HMAC chain.

4. mcp-api-adapter — 8th surface (planned)

4.1 Provider interface

interface QrStreamProvider {
  streamOutput(
    toolResult: McpToolResult,
    options: QrOutputOptions,
  ): AsyncIterable<QrFrame>
  scanInput(
    camera: CameraDevice,
    options: QrInputOptions,
  ): AsyncIterable<McpToolCall>
  streamEvents(
    events: AsyncIterable<StreamEvent>,
    options: QrOutputOptions,
  ): AsyncIterable<QrFrame>
}

interface QrOutputOptions {
  output: 'hdmi' | 'serial' | 'eink' | 'thermal' | 'stdout'
  frameIntervalMs: number // default 500
  ecLevel: 'L' | 'M' | 'Q' | 'H'
  encrypt: boolean
  includeAttestation: boolean
  thermalPrinter?: { device: string }
}

interface QrInputOptions {
  camera: string // camera:/dev/video0 | rtsp://... | v4l2://...
  verifyMerkleChain: boolean
  expectedMeasurement?: string
  timeoutMs: number
}

4.2 CLI (planned)

# Unidirectional: stream MCP tool results as QR on HDMI
npx mcp-api-adapter \
  --mcp-url http://127.0.0.1:8080/mcp \
  --qr-output hdmi --qr-mode stream --qr-frame-interval-ms 500

# Bidirectional
npx mcp-api-adapter \
  --mcp-url http://127.0.0.1:8080/mcp \
  --qr-output hdmi --qr-input camera:/dev/video0 --qr-mode bidirectional

# Thermal audit export
npx mcp-api-adapter \
  --mcp-url http://127.0.0.1:8080/mcp \
  --qr-output thermal --qr-printer /dev/usb/lp0 --qr-mode audit-export

Env: CLAWQL_QR_OUTPUT, CLAWQL_QR_INPUT, MCP_API_ADAPTER_QR_*.

4.3 HTTP surface (planned)

Route	Role
`GET /qr/session`	Current QR session status
`GET /qr/frame/:index`	Frame as PNG (testing)
`POST /qr/scan`	Submit scanned frame bytes (bidirectional)
`GET /qr/stream`	SSE of QR PNGs (dev preview only, not air-gap)

WIT (cellrt WASM world): import clawql:transport/qr-stream.

5. clawql-streams — `qr` source type

Air-gapped system (no network)
  │  QR stream (optical, out only)
  ▼
Camera → clawql-streams QrStreamSourceProvider
  ├─ Decode frames → verify Merkle → decode payload
  ├─ NATS publish + WORM entry
  └─ significance filter → Agent DO (memory_*, notify, execute…)

5.1 `stream_subscribe` example

stream_subscribe({
  sourceType: 'qr',
  device: 'camera:/dev/video0',
  topic: 'airgap.financial.audit',
  verifyMerkleChain: true,
  expectedMeasurement: 'sha256:abc...', // optional TEE verify
  significance: {
    type: 'pattern',
    path: '$.frameType',
    pattern: 'AuditChunk|ElectionBallot|StreamEvent',
  },
  prompt: `Process air-gapped QR stream data. Verify Merkle integrity.
Ingest structured payloads; flag gaps / invalid proofs; notify #security-ops on failure.`,
  allowedTools: ['memory_ingest', 'memory_recall', 'notify', 'audit'],
  auditLevel: 'WORM',
})

5.2 Continuous stream batching

significance: {
  type: "rate",
  count: 50,
  windowMs: 30000,
  immediatePatterns: ["MerkleChainBroken", "AttestationFailed", "InvalidProof"],
}

Batch normal frames; spawn immediately on anomalies.

6. Election module

End-to-end verifiable voting using homomorphic encryption + ZK proofs, with QR as air-gap transport and ClawQL as real-time verification/tally layer. Closest existing research systems: Helios, STAR-Vote, Microsoft ElectionGuard — ClawQL adds TEE attestation, QR transport, LTX/WORM, and Streams agents.

6.1 Machine-side flow

Voting machine (clawql-tee, air-gapped)
  ├─ Voter authenticates locally
  ├─ Selects candidates
  ├─ Machine produces:
  │    ├─ E(vote) — ElGamal (or similar) ciphertext
  │    ├─ ZK proof — valid ballot, 1 vote/race, no reveal
  │    ├─ Commitment H(vote || nonce) — voter receipt
  │    └─ Ballot ID from commitment
  ├─ Paper printout — voter reviews plaintext + commitment; confirm or void
  └─ After polls close — QR stream:
       Header → ElectionBallot frames → Attestation → Footer

6.2 Ballot payload

pub struct ElectionBallotPayload {
    pub ballot_id: String,
    pub commitment_hash: [u8; 32],
    pub encrypted_ballot: ElGamalCiphertext,
    pub election_public_key_id: String,
    pub validity_proof: BallotValidityProof,
    pub proof_system: String,           // groth16 | plonk | bulletproofs
    pub precinct_id: String,
    pub ballot_style: String,
    pub cast_timestamp: DateTime<Utc>,  // no voter identity
    pub paper_verified: bool,
}

6.3 Observer Streams subscription

Agent verifies ZK proofs, checks duplicate commitments, updates homomorphic running tally (ciphertext multiply — never decrypts individuals), ingests public registry, WORM-audits every ballot. allowedTools exclude execute during ballot processing (no external side effects).

E(v1) ⊕ E(v2) = E(v1 + v2) — authority decrypts only the final aggregate.

6.4 What becomes provably harder

Threat	Mitigation
Remote hacking	Air-gapped machine; no inbound network
Software tampering	TEE attestation + Cosign measurement
Ballot stuffing	ZK validity proofs rejected if malformed
Post-cast manipulation	Merkle + voter commitment receipt
Vote suppression	Public commitment list vs QR frame count
Individual vote reveal	Homomorphic + ZK (math, not policy)
QR interception/mod	Merkle + HMAC + TEE attestation

6.5 Honest limitations

Voter interface — crypto cannot detect display-A / encrypt-B; paper review is mandatory.
Key ceremony — who holds ElGamal shares is a trust question; prefer threshold decryption.
ZK library correctness — buggy proofs undermine the system; TEE proves certified code runs, not that the certification is bug-free.
Physical perimeter — air gap only as strong as custody and seals.
Political context — ClawQL provides infrastructure, not electoral policy; certification and law are out of band.

7. `clawql-tee-verifier` additions

clawql-tee-verifier verify-qr --input recording.mp4 --expected-measurement sha256:…
clawql-tee-verifier verify-qr --camera /dev/video0 --mode paper-scan
clawql-tee-verifier verify-election \
  --camera /dev/video0 \
  --election-public-key election-2026-key.json \
  --expected-measurement sha256:… \
  --output verification-certificate.pdf

Certificate includes session/Merkle status, TEE result, election ballot counts / proof ratio / aggregate ciphertext, verifier Cosign identity, timestamp.

8. Helm values (planned)

mcpApiAdapter:
  qrTransport:
    enabled: false
    mode: stream # stream | bidirectional | audit-export
    output:
      device: hdmi
      frameIntervalMs: 500
      ecLevel: M
      encrypt: true
      includeAttestation: false
    input:
      device: ''
      verifyMerkleChain: true
      expectedMeasurement: ''

streams:
  sources:
    qr:
      enabled: false
      defaultDevice: ''
      verifyMerkleChain: true
      batchFrames: 50
      batchWindowMs: 30000

election:
  enabled: false # explicit opt-in
  electionPublicKeyPath: ''
  certifiedMeasurement: ''
  precinctId: ''

9. Positioning

Surface	Network	Role
OpenAPI	Yes	REST / OpenAPI panels
GraphQL	Yes	GraphQL stacks
Streamable HTTP `/mcp`	Yes	IDE clients
gRPC	Yes	Mesh / protobuf
gen-cli	Build	Shell / ops
WebSocket	Yes	Real-time / DO hibernation
`/mcp-ui`	Yes	Browser HTMX playground (7th surface)
QR stream	No	Air-gap, elections, regulated optical channel (8th planned)

Seven surfaces connect over a network today (including /mcp-ui). QR stream connects air-gapped systems to the ClawQL agent surface over a physical channel with per-frame crypto and optional TEE binding.

Challenge the Footage / legal evidence: browser platforms that fingerprint recordings still trust platform servers. QR + TEE makes capture/export integrity hardware-verifiable and operator-independent — same underlying problem as government outcome records and surveillance evidence (clawql-surveillance).