Skip to content

Bridge identity and policy binding

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. Pending identities cannot create a BridgePrincipal, receive a credential lease, or produce an OpenBao policy binding. A separate proof-of-possession/enrollment operation must explicitly activate the identity. The proof mechanism and public-key storage are outside this first contract and must be implemented before production activation.

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. A consumed or expired challenge cannot be replayed. Private keys, raw nonces, signatures and full public keys are not persisted by this stage.

Activation is idempotent only for the same project, Bridge metadata and account binding. Reusing a Bridge ID with different device or public-key metadata is rejected. Revocation is terminal for that identity record; a new installation must use a new Bridge identity rather than silently reactivating the revoked one.

Policy binding

An active identity may be combined with an approved credential record and a session to produce a metadata-only binding:

project, bridge, device, provider, account, credential reference/version,
session, OpenBao path

The binding contains no token, raw credential, response body, or private key. The existing credential broker still enforces the project, Bridge, device and account checks before reading from OpenBao. The OpenBao path remains scoped to the project/provider/account/reference/version; the Bridge and device scope is enforced by the authenticated HeyAira broker and recorded in the binding.

Persistence and rollout boundary

Migrations 013_bridge_identities.sql and 014_bridge_enrollment_challenges.sql are additive. Migration 015_bridge_enrollment_transport.sql adds only hashed bootstrap credentials and Bridge access-token metadata. The local phase-1 transport is reviewed behind this boundary; production migration and activation remain separate.

No production OpenBao policy is written, no Bridge is activated, and no client receives new credentials as part of this stage.