🔐 Secure Enclave bridge + SDI agent
BrightNexus

A macOS status-bar app that bridges Node.js and the BrightChain stack to Apple's Secure Enclave, and hosts the SDI agent for the bsh shell. Hardware-backed P-256 signing, host-resident secp256k1 ECIES, TOTP-gated key export — all over a local Unix socket. Zero network surface.

# probe the bridge — JSON in, JSON out, no newlines
$ printf '%s' '{"cmd":"HEARTBEAT"}' \
> | nc -U ~/.brightchain/brightnexus/brightnexus.sock
{"ok":true,"timestamp":"2026-05-21T17:02:11Z","service":"enclave-bridge"}
# sign with the Secure Enclave (P-256, hardware)
$ node -e "..." # via @digitaldefiance/enclave-bridge-client
signature: MEUCIQ...== (DER)
# private bytes never leave the SEP. ever.
$ Install → View on GitHub
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.

🛰️ SDI agent (SDI-EB v3)

The SDI (Secure Semantic Data Injection) agent role for the bsh shell. In v3 the SDI agent is no longer a separate daemon — the bridge hosts SDI_REGISTER, SDI_PUSH, SDI_GEO_*, SDI_AUDIT_EMIT on the same EBP/1 socket. Sessions are anchored to the device's Secure Enclave via a P-256 transcript signature. The v3 command surface is reserved on the wire today and ships in upcoming releases.

Renamed from Enclave Bridge. This project was previously published as Enclave Bridge. The rename reflects the broader role: SDI 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 + SDI-EB 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 + SDI 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
HEARTBEATLiveness probe with timestamp
VERSION / INFOApp version, build, platform, uptime
STATUSPeer-key flag, enclave availability
METRICSService uptime, reserved counters
GET_PUBLIC_KEYBridge's secp256k1 public key (for ECIES)
GET_ENCLAVE_PUBLIC_KEYSecure Enclave P-256 public key
SET_PEER_PUBLIC_KEYCache a peer's secp256k1 public key on this connection
LIST_KEYSEnumerate keys with TOTP status & fingerprints
ENCLAVE_SIGNECDSA-SHA256 over P-256 in the SEP
ENCLAVE_DECRYPTECIES decrypt with the bridge secp256k1 private key
ENCLAVE_GENERATE_KEYReserved (returns error in EBP/1)
ENCLAVE_ROTATE_KEYReserved (returns error in EBP/1)
ENABLE_TOTPEnable per-key TOTP, emit provisioning URI
EXPORT_KEYExport 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).

SDI-EB v3 — reserved surface

Hardware-anchored sessions for bsh.

BSH emits structured credential and geo-context payloads as OSC 7777 terminal escape sequences. SDI v1 and v2 ran a separate SDIAgent daemon next to the Enclave Bridge. v3 (SDI-EB) collapses the two: BrightNexus is the SDI agent. Session establishment becomes an EBP/1 command pair on the existing socket, encrypted under the bridge's persistent secp256k1 key and signed with the device's Secure Enclave P-256 key.

Status — reserved on the wire. The v3 command names are recognized by this build but return the stable error "<COMMAND> not implemented in this build". v3-aware clients can use that signal to detect they are talking to a BrightNexus that knows the v3 surface but has not yet shipped it. The OSC 7777 envelope, geo socket, replay protection, and audit log arrive in subsequent passes.

1

SDI_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.

2

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 = "sdi-session-key-v3", L = 32).

3

SEP-signed transcript

Bridge signs the canonical 234-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.

4

OSC 7777 traffic + SDI_PUSH

bsh emits credential and geo-context payloads as OSC 7777 sequences encrypted under K_session with per-direction monotonic counters and an AAD-bound direction tag. Bridge → shell pushes flow over a long-lived SDI_PUSH subscription; the client unescapes and writes them to /dev/tty.

ECIES envelope SEP-signed transcript HKDF-SHA256 AES-256-GCM per-direction counters 8-hour session TTL TOFU pin fail-closed
# the v3 surface is recognized today...
$ printf '%s' '{"cmd":"SDI_REGISTER","protocolVersion":3}' \
> | nc -U ~/.brightchain/brightnexus/brightnexus.sock
{"error":"SDI_REGISTER not implemented in this build"}
# ...as opposed to an unrelated bridge:
{"error":"Unknown command: SDI_REGISTER"}
# clients use the distinction to gate v3 features.

Full v3 specification: SDI-EB v3 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.

1

Clone

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

Open in Xcode & build

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

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 unchanged. A brightnexus-client shim package may follow as v3 SDI commands ship.

4

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 SDI-EB v3 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 v3 SDI threat model see SDI-EB §9 and §11.

Related projects

The BrightChain stack.

🐚

bsh — BrightShell

The zsh-compatible shell that emits OSC 7777 SDI sequences and talks to BrightNexus as its SDI agent under v3. 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 SDI_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 SDI-EB v3 geo-context timestamps and registration handshake. site

📄

EBP/1 specification

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