Skip to content

Bridge identity

A Bridge is an installed execution runtime, not a project owner and not a secret store. HeyAira keeps only its public registration metadata:

  • project and Bridge identifiers;
  • device identifier and display name;
  • public-key fingerprint;
  • lifecycle status (pending, active, or revoked);
  • allowed account references and timestamps.

Registration lifecycle

Registration creates a pending identity. A pending identity cannot take work; a separate proof-of-possession enrollment explicitly activates it.

The enrollment contract uses an Ed25519 key pair. The server returns a one-time, expiring challenge nonce and stores only its SHA-256 hash. The Bridge signs the nonce and returns the signature plus its public key. The server checks the signature and the registered sha256: fingerprint before activating the identity. An expired or superseded challenge cannot be completed, and a consumed challenge never activates anything a second time. Private keys, raw nonces, signatures and full public keys are not persisted by this stage.

Activation is idempotent for the same challenge and the same device key: a retried proof (lost response, concurrent retry, new idempotency key) is verified again and returns the token that activation minted, without minting a second one, for as long as that token is the Bridge's active token.

A Bridge ID whose enrollment never completed (pending, no consumed challenge, no token ever issued) can be enrolled again with a fresh one-time bootstrap credential, with the same or a new device key. The new challenge supersedes the earlier ones. Once activation has completed, the Bridge ID is never re-enrolled: a different key, or the same key, is rejected with bridge_identity_conflict; token rotation and operator recovery own that case. Revocation is terminal for that identity record; a new installation must use a new Bridge identity rather than silently reactivating the revoked one.

Provider accounts

Provider credentials stay on the Mac. An identity carries only the account slots it may use (allowed_account_ids); a task runs under one of them. The planned OpenBao policy binding and in-process credential broker were never wired into the server and have been removed (see credential broker boundary).

Persistence

Migrations 013_bridge_identities.sql and 014_bridge_enrollment_challenges.sql hold identities and challenges. Migration 015_bridge_enrollment_transport.sql adds only hashed bootstrap credentials and Bridge access-token metadata. The server activates Bridges through the enrollment HTTP contract. It writes no OpenBao policy for a Bridge.