Skip to content

Control protocol

The desktop speaks countersign.v1 over an outbound WebSocket at /v1/companion on its paired HTTPS origin. The Gateway sends one versioned frame in each HTTPS POST under /v1/gateway/. Integrator application backends use a separate Broker API.

Frame

This authenticated Companion request lists the opaque IDs in its inbox.

{"version":1,"request_id":"list-1","type":"inbox","body":{}}

The envelope has four required fields. request_id correlates a request and reply on the channel. The decoder chooses the permitted message types for that direction, rejects unsupported versions and unknown fields, and bounds the original JSON before decoding the body. Treat IDs in notifications as lookup hints. An authenticated fetch returns the authoritative offer. Envelope and message definitions

Wire value Bound or encoding
Frame and nesting At most 1 MiB and 24 JSON nesting levels
Opaque ID 1–256 UTF-8 bytes, without control characters
Fingerprint 32 SHA-256 bytes, standard base64 on the wire. The UI displays hex.
Public DER chain 1–16 certificates, at most 256 KiB decoded in total
TLS signing input / signature Nonempty base64 strings, at most 256 KiB / 2,048 bytes decoded
Device proof Compact JWS, base64url without padding, signed by the pairing key

The protocol uses Unix milliseconds for absolute times and separate numeric fields for duration and lease budget. Wire value validation

Companion channel

Stage Traffic Binding checked
Pair or reconnect enroll with a public P-256 key, or authenticate with the existing pairing and key IDs. Answer the Broker's challenge with proof. One challenge binds the origin, user, key, connection, purpose, nonce and expiry. Pairing also requires authenticated browser and local confirmation. Reconnecting establishes a new channel generation.
Find requests notify or inbox, followed by fetch → offer. The offer carries its own ID, approval version, target device, Workload, initiating host, effective scope, certificate hints and duration limits.
Decide decide on that offer with approval, denial or cancellation. Approval includes the selected public chain, fingerprint and duration. A concurrent decision on another eligible Companion can win first.
Activate The Broker sends activate. The winning Companion checks its local approval receipt and replies activated. The grant binds the winning device, job, worker, destination scope and certificate. The Broker reports readiness separately from a committed approval.
Sign sign → signed, or cancel / error. Each operation carries the full grant, exact host, TLS connection and operation ID. The request names the TLS version, signature scheme, handshake input and deadline.
Retire or revoke The Broker can send retire. The Companion can send revoke_approval and receives revoke_recorded once recorded. An offline queued action stays distinguishable from a recorded revocation.

Gateway operations

The Gateway supplies a Workload bearer token and its boot identity in X-Countersign-Gateway-Instance. A shared Gateway also supplies its independent service credential in X-Countersign-Gateway. The Broker checks the token audience, Workload generation and scope. A single process cannot claim an existing grant assigned to another supervisor.

POST suffix Message type Use
connect, lookup connect, lookup Admit a Workload and host, then retrieve the pending or activated decision.
lease renew_lease Request a bounded lease for one ingress or egress enforcer, instance, generation and sequence.
sign, cancel sign, cancel Request or cancel the signature for one handshake. The Broker holds an independent lease while relaying it.
watch watch Wait for retirement of the bound grant. All traffic relays still maintain lease deadlines.
observed observed Report upstream mTLS acceptance or a socket closure for a particular connection and enforcer.

An approval ID alone cannot address a signer. A changed pairing channel, certificate, Workload or worker generation changes the binding. Late signatures are discarded after cancellation, expiry or loss of that binding. The Gateway verifies correlation and the returned signature before using it in TLS. Gateway operations · Protocol compatibility and rejection tests