Skip to content

HeyAira Bridge 0.0.1 protocol

Bridge 0.0.1 proves the trust boundary between one macOS machine and a HeyAira project. It does not launch agents, control terminals, expose a remote shell, or provide desktop automation.

Transport and authentication

The Bridge initiates outbound HTTPS requests through the selected Tailscale route. The Mac does not expose an inbound listener. Tailscale provides network reachability only; the Bridge API still authenticates every request.

Pairing is a one-time code created by an operator with:

heyaira-admin create-bridge-pairing \
  --project-id <project-id> \
  --code-file /run/heyaira-secrets/bridge-pairing-code

The Bridge creates a random stable node_id and an Ed25519 public/private key pair. The private key remains in the macOS Keychain. The pairing response contains a short-lived access token and a longer-lived refresh token; the Bridge stores both in the Keychain. PostgreSQL stores only hashes.

Endpoints

POST /bridge/v1/pair

Consumes a one-time pairing code and registers the node. The code is never logged or returned by the server. The request includes the public identity and bounded machine metadata. A successful response returns the node ID and credentials.

POST /bridge/v1/token

Consumes a refresh credential and returns a new short-lived access token. The node ID in the JSON body must match the authenticated refresh credential.

POST /bridge/v1/heartbeat

Consumes the access credential and a monotonically increasing sequence number. Duplicate or older sequences are idempotently acknowledged without changing the node state. A newer sequence updates health and sets the node to connected.

GET /bridge/v1/node

Returns the authenticated node's bounded metadata and one of connected, offline, or revoked.

GET /bridge/v1/nodes

Returns nodes belonging to the project selected by an existing project-scoped HeyAira bearer token. It is an operator/API surface, not a Bridge credential surface.

POST /bridge/v1/nodes/{node_id}/revoke

Revokes the node and all of its active credentials using a project-scoped HeyAira bearer token. The node must pair again to become trusted.

0.0.1 acceptance criteria

  • an unpaired node cannot register;
  • pairing is one-time and expires;
  • node identity survives a Bridge restart;
  • heartbeats move the node to connected;
  • missing heartbeats are reported as offline;
  • duplicate heartbeat sequences are safe;
  • revocation blocks further heartbeats;
  • reset removes local identity and credentials;
  • secrets are absent from logs, API responses other than the initial pairing response, and database rows.