buzz/beehive/native/README.md

Databricks native helper (macOS arm64 prototype)

This is a callable Rust binary, beehive-databricks, linked against this checkout's buzz_agent library. No OAuth implementation lives in JS. The helper uses databricks_oauth_config, PkceOAuthTokenSource::new_with_custody and discover_databricks_models_with_token_source. Node sends one bounded JSON request over owned pipes; secrets never enter argv or stderr. Do not invoke the helper to inspect credentials. It refuses terminal stdin/stdout.

Reproducible package step

From the exact committed checkout on macOS arm64 (no install or global changes):

ARTIFACT=/absolute/fresh/artifact-directory
RUST="$HOME/.rustup/toolchains/1.95.0-aarch64-apple-darwin/bin"
mkdir -p "$ARTIFACT/helper-package/bin"
PATH="$RUST:/usr/bin:/bin" CARGO_TARGET_DIR="$ARTIFACT/target" \
  "$RUST/cargo" build --locked --release -p buzz-agent --bin beehive-databricks
install -m 700 "$ARTIFACT/target/release/beehive-databricks" \
  "$ARTIFACT/helper-package/bin/beehive-databricks"
COPYFILE_DISABLE=1 tar -C "$ARTIFACT/helper-package" -czf \
  "$ARTIFACT/beehive-databricks-macos-arm64.tar.gz" bin/beehive-databricks
shasum -a 256 "$ARTIFACT/helper-package/bin/beehive-databricks" \
  "$ARTIFACT/beehive-databricks-macos-arm64.tar.gz"

Merge helper-package/bin/beehive-databricks into the Beehive package's bin/ when preparing each machine's next export. Do not overwrite Buzz Desktop, buzz-agent, or any other installed product. Existing Node 24.15.0 / Bun 1.4.2 packaging stays unchanged. No source-time or runtime download/build fallback. The binary is built for arm64; other platform custody/export is not implemented.

Custody and lifecycle

• Exact beehive OS generic-password entry, account provider:<uuid>, containing the workspace-bound access/refresh bundle. Native Security Framework writes and exact read-back precede public provider CAS. No Desktop services or token files. The existing public recovery-reference log precedes attempted login.
• Browser sign-in is explicit. The shared OAuth owner supplies a random CSRF state nonce, PKCE S256 verifier, loopback ephemeral callback, state rejection, grant exchange, expiry and refresh. This is OAuth authorization-code, not an OIDC identity-token login; no unvalidated ID-token identity claim is consumed. Discovery and grant endpoints must share the validated workspace origin; external-custody OAuth HTTP redirects are disabled.
• Same-account helper processes hold an OS-released advisory lock across load, grant rotation and verified storage. Only lock/attempt metadata lives in the owner-only temporary coordination directory. Per-invocation files are removed after awaited close. Node deadlines: login 180s, models/token 20s; cancellation sends TERM, then KILL after 250ms, and awaits close before settling.
• Model listing and Start preflight are headless and can refresh, never opening the browser. For catalog OS-backed Databricks runtimes, spawnAgent now starts the run-owned Node databricks-runtime-child.ts wrapper. The stock harness retains databricks_v2 and its native wire routing, but receives an ephemeral loopback endpoint and random per-run bearer capability, not the provider token. Each model/catalog request calls this unchanged native helper's token action against the immutable real workspace/reference. Native expiry/refresh/verified rotation therefore serves an ongoing run without restarting the agent.
• The proxy admits only canonical v2 catalog/model paths and the selected model; no redirects or arbitrary upstream hosts. OAuth/network failures fail closed; upstream 401/403 latches rejection for that run (explicit sign-in/new run may be needed). It does not implement a parallel forced-refresh OAuth engine. Native refresh is expiry-based; a server-side early rejection is not silently retried with another provider/workspace. No streaming extension is claimed: current canonical Buzz Agent requests/responses are non-streaming.
• Wrapper, harness and native helpers belong to the existing supervised process group. Stop fences responses, aborts fetch/helpers, awaits close, and retains the supervisor's existing TERM/KILL/absence verification. Legacy external-OAuth and explicit token-file bindings are unchanged; only OS-backed catalog bindings use the adapter. No helper binary change/rebuild is needed for this integration.
• Cancellation may follow an OS write. It cannot undo grant rotation or pretend rollback; no cancelled operation commits a new public provider. Recovery refs remain. Browser windows owned by the OS may remain open; helper/listener do not.

Tests explicitly substitute native/browser/OS custody with synthetic seams. manager-installed-loader.ts blocks this new native path in future install smokes. Fresh HOME alone is not credential or browser isolation.

Export additions for runtime integration

Include every beehive/src/*.ts and beehive/src/*.json in the Node/Bun package, especially both runtime adapter modules, harness-contract.json and model-capabilities.json. The latter is a byte-identical packaged copy of scripts/model-capabilities.json, checked by tests. Regenerate the harness contract explicitly with python3 beehive/tools/export-harnesses.py <reviewed-SHA> from the repository root; its current source is Desktop main 78618804ec86a014524ad7d1fb55928e8f5c3edf. Keep the existing helper binary in bin/beehive-databricks; do not build/install anything at runtime.

Owner session helper

The OpenTUI manager also packages beehive-owner-key. Build it with the normal repository toolchain and default features, scoped to this binary:

cargo build --locked --release -p buzz-agent --bin beehive-owner-key
install -m 700 target/release/beehive-owner-key "$PACKAGE/beehive/bin/beehive-owner-key"

This helper belongs only in the Beehive package. It makes no credential writes. On macOS its exact query is generic password service buzz-desktop, account secrets. The probe request returns metadata availability only, with Keychain interaction disabled and authenticated items skipped. Presence is not proof that the blob contains a valid owner identity; explicit read checks that next. Only explicit Desktop sign-in reads the identity member. No fallback, enumeration, agent-key selection or migration is permitted. Other platforms report unsupported; manual owner nsec remains available. The Node authority bounds output, owns the helper process and kills it on cancel or timeout. No secret returns to Bun.

Tests inject a synthetic executable or Desktop adapter. A fresh HOME is not Keychain isolation. Do not run the native read against real Desktop secrets as a smoke test. OS access/denial needs a separately authorized isolated Keychain test.