BrightNexus — Secure Enclave bridge + BrightLink agent

What it is

One menu-bar app, two protocol roles.

BrightNexus is a SwiftUI status-bar application for macOS Apple Silicon. It opens a single Unix domain socket in your home directory and serves two layered protocols on it:

🔐 Enclave Bridge Protocol (EBP/1)

The original Enclave Bridge wire surface, preserved byte-for-byte. JSON-over-Unix-socket commands that proxy a curated subset of cryptographic operations: ECDSA signing with a non-extractable Secure Enclave P-256 key, ECIES decryption with a host-resident secp256k1 key, optional TOTP-gated key export. Reference client is @digitaldefiance/enclave-bridge-client.

🛰️ BrightLink agent

Renamed from Enclave Bridge. This project was previously published as Enclave Bridge. The rename reflects the broader role: BrightLink agent + BrightChain hardware nexus, not just a single-purpose ECIES decrypt proxy. The EBP/1 wire surface is unchanged. Existing Node clients keep working — see the migration notes below.

Architecture

Single socket, two trust domains.

The bridge is a small SwiftUI app that lives in your menu bar. It opens an AF_UNIX socket under your home directory, accepts concurrent client connections, and dispatches each accepted file descriptor to its own DispatchQueue. The protocol framing is plain UTF-8 JSON, one object per request, one per response.

┌──────────────────────┐ Unix socket ┌────────────────────────────┐ │ Node.js application │ ~/.brightchain/brightnexus/ │ BrightNexus (SwiftUI) │ │ │ brightnexus.sock │ │ │ ┌────────────────┐ │ ──────────────────────────► │ BridgeProtocolHandler │ │ │ enclave-bridge │ │ │ ├─ ECIES (secp256k1) │ │ │ -client │ │ EBP/1 + BrightLink JSON │ ├─ SecureEnclaveKeyMgr │ │ └────────────────┘ │ ◄───────────────────────────│ ├─ TOTP (RFC 6238) │ │ ┌────────────────┐ │ │ └─ AppState / SocketSrv │ │ │ node-ecies-lib │ │ │ │ │ └────────────────┘ │ │ │ │ └──────────────────────┘ │ ▼ │ │ ┌──────────────────────┐ │ │ │ Apple Secure Enclave │ │ │ │ (P-256, hardware) │ │ │ └──────────────────────┘ │ └────────────────────────────┘

🔑 Two keys, two trust domains

Secure Enclave P-256 — generated inside the SEP with kSecAttrAccessibleWhenUnlockedThisDeviceOnly and .privateKeyUsage. Bytes are non-extractable. Signs with ECDSA-SHA256.

Host-resident secp256k1 — 32 raw bytes at ~/.brightchain/brightnexus/ecies-privkey.bin (mode 0600). Used for ECIES decryption with AES-256-GCM (12-byte IV, 16-byte tag) and HKDF-SHA256, byte-compatible with @digitaldefiance/node-ecies-lib.

📁 Disk layout

One per-user directory tree under ~/.brightchain/, mode 0700 throughout:

~/.brightchain/ vendor namespace ~/.brightchain/brightnexus/ app state ~/.brightchain/brightnexus/brightnexus.sock EBP/1 + BrightLink socket ~/.brightchain/brightnexus/ecies-privkey.bin secp256k1 priv (0600) ~/.brightchain/brightnexus/totp-config.json TOTP secrets (0600) ~/.brightchain/brightnexus/brightnexus.geo.path geo socket pointer (v3)

For backward compatibility, BrightNexus also binds a secondary socket at ~/.enclave/enclave-bridge.sock and routes traffic from both into the same protocol handler. On first launch it migrates ecies-privkey.bin and totp-config.json from ~/.enclave/ into ~/.brightchain/brightnexus/ via atomic rename(2). Existing keys are preserved.

EBP/1 — current and stable

Fourteen commands, all JSON.

Every request is a JSON object with at least a cmd field; every response is either a command-specific success object or {"error":"<reason>"}. Binary fields (public keys, signatures, ciphertexts) are standard Base64 with padding. There is no length prefix and no newline delimiter — the server reads complete JSON objects from the byte stream.

Command	Purpose
HEARTBEAT	Liveness probe with timestamp
VERSION / INFO	App version, build, platform, uptime
STATUS	Peer-key flag, enclave availability
METRICS	Service uptime, reserved counters
GET_PUBLIC_KEY	Bridge's secp256k1 public key (for ECIES)
GET_ENCLAVE_PUBLIC_KEY	Secure Enclave P-256 public key
SET_PEER_PUBLIC_KEY	Cache a peer's secp256k1 public key on this connection
LIST_KEYS	Enumerate keys with TOTP status & fingerprints
ENCLAVE_SIGN	ECDSA-SHA256 over P-256 in the SEP
ENCLAVE_DECRYPT	ECIES decrypt with the bridge secp256k1 private key
ENCLAVE_GENERATE_KEY	Reserved (returns error in EBP/1)
ENCLAVE_ROTATE_KEY	Reserved (returns error in EBP/1)
ENABLE_TOTP	Enable per-key TOTP, emit provisioning URI
EXPORT_KEY	Export public key, gated by TOTP if enabled

secp256k1 + AES-256-GCM P-256 ECDSA-SHA256 HKDF-SHA256 12-byte IV 16-byte tag RFC 6238 TOTP Base64 wire format

Full specification: Enclave Bridge Protocol (EBP/1).

Hardware-anchored sessions for bsh.

BSH delivers structured credential payloads to BrightNexus over a Unix socket using BrightLink Protocol. The wire is JSON on a socket. Session establishment is an EBP/1 command pair on the same socket, encrypted under the bridge's persistent secp256k1 key and signed with the device's Secure Enclave P-256 key.

Status — two commands live, five reserved. LINK_REGISTER (RFC §4.5) and LINK_DELIVER (§4.6) are implemented. Captured credentials surface in the menu-bar Credentials submenu and the Dashboard "Credentials" view with click-to-copy and live TTL countdowns. LINK_PUSH, LINK_GEO_*, and LINK_AUDIT_EMIT are reserved on the wire and ship in subsequent passes; an out-of-date BrightNexus that does not know the BrightLink surface can be distinguished from a BrightLink-aware one by the stable "<COMMAND> not implemented in this build" error string.

LINK_REGISTER over EBP/1

Client connects to the bridge socket, sends a 16-byte clientNonce and an ECIES envelope addressed to the bridge's persistent secp256k1 public key. Plaintext carries an ephemeral secp256k1 public key, a 32-byte clientShare, and a BrightDate timestamp.

Bilateral key derivation

Bridge generates its own 32-byte bridgeShare and a 16-byte sessionId, returns them in an ECIES envelope addressed to the client's ephemeral key. Both sides compute K_session = HKDF-SHA256(IKM = clientShare ∥ bridgeShare, salt = clientNonce ∥ sessionId, info = "brightlink-session-key-v1", L = 32).

SEP-signed transcript

Bridge signs the canonical 238-byte transcript (literal prefix, lengths, nonces, shares, session ID, timestamps) with its Secure Enclave P-256 key. Client verifies against a TOFU-pinned SEP public key. A future impostor bridge cannot forge the signature without the SEP.

LINK_DELIVER on the socket

Tools invoke bsh-inject (or equivalent) to send a LINK_DELIVER JSON request — {cmd, counter, type, context, iv, ciphertext, authTag} — on the same socket as the registration handshake. The counter, type, and context are bound into the AES-256-GCM AAD via a length-prefixed dir_tag, so a captured ciphertext cannot be replayed in either direction.

ECIES envelope SEP-signed transcript HKDF-SHA256 AES-256-GCM per-direction counters 8-hour session TTL TOFU pin fail-closed

# LINK_REGISTER lands a real session today...

$ yarn test:against-real-brightnexus # in test-harness/

PASS link-register.test.ts (8 tests)

PASS link-deliver.test.ts (13 tests)

# reserved commands return a stable error...

{"error":"LINK_AUDIT_EMIT not implemented in this build"}

# ...vs an out-of-date EBP/1 bridge:

{"error":"Unknown command: LINK_AUDIT_EMIT"}

# clients use the distinction to gate v1 features.

Full v1 specification: BrightLink Protocol RFC. Companion paper: EBP/1. Cipher suite: DD-ECIES v1.0.

Getting started

Install BrightNexus.

🛠️

Build from source

BrightNexus is a SwiftUI app for macOS Apple Silicon. macOS 13+ and Xcode 15+ are required.

Clone

git clone https://github.com/Digital-Defiance/BrightNexus.git
cd BrightNexus

Open in Xcode & build

open BrightNexus.xcodeproj
# Select the BrightNexus scheme, then ⌘R to run.

Install the Node client

npm install @digitaldefiance/enclave-bridge-client

The client package name is unchanged from the Enclave Bridge era; the wire surface it speaks is the EBP/1 surface plus the BrightLink extension.

Sanity-check the socket

printf '%s' '{"cmd":"HEARTBEAT"}' \
  | nc -U ~/.brightchain/brightnexus/brightnexus.sock

🔁

Migrating from Enclave Bridge

If you previously installed the standalone Enclave Bridge app:

Quit the old menu-bar app first. It must not be running when BrightNexus starts.
Launch BrightNexus. On first run it migrates ~/.enclave/ecies-privkey.bin and ~/.enclave/totp-config.json into ~/.brightchain/brightnexus/ via atomic rename(2). Your secp256k1 identity, TOTP secrets, and persistent ECIES public key are preserved.
Existing Node clients keep working. The bridge binds a compatibility socket at ~/.enclave/enclave-bridge.sock for one major version. Update clients to look at ~/.brightchain/brightnexus/brightnexus.sock at your leisure.
Delete the old app from /Applications after confirming BrightNexus is healthy.

The on-disk key file format, the TOTP config JSON, and the EBP/1 wire surface are all unchanged.

Security model

What you trust, and what you don't.

✅ What's hardware-bound

The Secure Enclave P-256 private key is generated inside the SEP with kSecAttrAccessibleWhenUnlockedThisDeviceOnly and .privateKeyUsage. Even root cannot read its bytes. ENCLAVE_SIGN and the BrightLink transcript signature both pass through this key.

The host secp256k1 private key sits at rest under POSIX 0600 in your home directory. For defense in depth (encrypted with a user password before being addressed to the bridge), the SecureEnclaveKeyring consumer in brightchain-api-lib layers password-AES-GCM and ECIES-to-the-bridge into a single double-encrypted blob.

⚠️ What's in scope

Any local process running as your user that can connect(2) to the socket can issue any EBP/1 command while the bridge is running. EXPORT_KEY can be gated by RFC 6238 TOTP per key; ENCLAVE_SIGN and ENCLAVE_DECRYPT are not gated by TOTP in EBP/1. Quitting the menu-bar app revokes both capabilities until you relaunch.

No network listeners. No telemetry. No third-party services. The bridge speaks only on a Unix domain socket inside your home directory, with filesystem permissions enforced by macOS.

For the BrightLink threat model see BrightLink RFC §14.

Related projects

The BrightChain stack.

🐚

bsh — BrightShell

The zsh-compatible shell whose bsh-inject builtin delivers BrightLink credentials to BrightNexus over the EBP/1 socket. Tools speak directly to the bridge — no terminal emulator participation, no PTY scraping. site · source

📦

enclave-bridge-client

TypeScript client for EBP/1. Drop-in replacement; package name unchanged across the rename. npm · source

🔐

node-ecies-lib

The DD-ECIES wire format the bridge speaks for ENCLAVE_DECRYPT and LINK_REGISTER: secp256k1 + AES-256-GCM + HKDF-SHA256, byte-compatible across languages. npm · spec

⛓️

BrightChain

The platform consuming BrightNexus. The SecureEnclaveKeyring in brightchain-api-lib uses BrightNexus as its tier-1 key custody provider on Apple Silicon. source

🛰️

BrightDate

The decimal-SI temporal foundation referenced by BrightLink transcript and payload timestamps. site

📄

EBP/1 specification

Replication-grade specification of the bridge's command surface, ECIES wire format, and SEP key custody. read it