fix(orb): make fleet telemetry work + non-optional in broker mode

A brokered self-host (ORB_ENROLLMENT_SECRET set) relies on the central Orb for
GitHub tokens + webhook relay, so fleet telemetry is part of the self-hosting
contract. But the exporter gated on a local GITHUB_APP_PRIVATE_KEY — which a
brokered instance never holds — so broker-mode telemetry never ran at all, and
ORB_AIR_GAP could suppress it. Also, brokered instances share no Orb/App id, so
they collided on the 'unknown' instanceId fallback.

- Gate export on the enrollment OR a local App key (brokered = configured).
- Air-gap suppresses export only for a self-managed (non-brokered) instance;
  a brokered instance always exports.
- Derive instanceId from the enrollment secret when no Orb/App id is present
  (hashed — the high-entropy secret never leaks; unique + stable per install).

Author: JSONbored

src/selfhost/orb-collector.ts

@@ -52,9 +52,12 @@ interface OrbExportPayload {
   events: FleetEvent[];
 }
 
-/** Stable instance identifier (hash of the Orb/App ID — no PII). */
+/** Stable instance identifier (hash of the Orb/App ID — no PII). A brokered instance holds no App id, so its
+ *  per-install enrollment secret is the stable identity (hashed, so the high-entropy secret never leaks and two
+ *  brokered instances never collide on the "unknown" fallback). */
 function instanceId(): string {
-  return createHash("sha256").update(process.env.ORB_APP_ID ?? process.env.GITHUB_APP_ID ?? "unknown").digest("hex").slice(0, 16);
+  const seed = process.env.ORB_APP_ID ?? process.env.GITHUB_APP_ID ?? process.env.ORB_ENROLLMENT_SECRET ?? "unknown";
+  return createHash("sha256").update(seed).digest("hex").slice(0, 16);
 }
 
 /** HMAC a string with the instance's own secret for anonymized export. */
@@ -154,11 +157,17 @@ function cycleTimeMs(decidedAt: string, outcomeAt: string): number | null {
  * Returns the number of events exported (0 if air-gapped, the App isn't configured, or nothing new).
  */
 export async function exportOrbBatch(db: D1Database, batchSize = 200, fetchFn: typeof fetch = fetch): Promise<number> {
-  // Always on (no opt-out). Air-gapped/offline deployments may suppress the outbound call.
-  if ((process.env.ORB_AIR_GAP ?? "").toLowerCase() === "true") return 0;
+  // A brokered self-host relies on the central Orb for tokens + webhook relay, so fleet telemetry is part of the
+  // self-hosting contract — air-gap cannot opt it out, and the export is gated on the enrollment (not a local App
+  // key, which a brokered instance never holds).
+  const brokered = Boolean((process.env.ORB_ENROLLMENT_SECRET ?? "").trim());
 
-  // No App configured → no review data to export anyway. Gate export on the App being set up.
-  if (!(process.env.GITHUB_APP_PRIVATE_KEY ?? "")) return 0;
+  // Air-gapped/offline deployments may suppress the outbound call — but ONLY a self-managed (non-brokered) instance.
+  if (!brokered && (process.env.ORB_AIR_GAP ?? "").toLowerCase() === "true") return 0;
+
+  // Gate export on the instance being CONFIGURED: a local App private key, OR brokered mode (the Orb holds the App
+  // key and mints tokens on demand, so the instance has review data to export but no local App key).
+  if (!brokered && !(process.env.GITHUB_APP_PRIVATE_KEY ?? "")) return 0;
 
   // gittensory's hosted collector. No shared secret is sent: repo/PR identifiers are HMAC'd with this
   // instance's DEDICATED anonymization secret (a 256-bit random key generated once and persisted in

test/unit/selfhost-orb-collector.test.ts

@@ -1,4 +1,5 @@
 import { DatabaseSync } from "node:sqlite";
+import { createHash } from "node:crypto";
 import { describe, expect, it, beforeEach, afterEach } from "vitest";
 import { createD1Adapter, nodeSqliteDriver } from "../../src/selfhost/d1-adapter";
 import { bucketReasonCode, exportOrbBatch, getOrCreateAnonSecret } from "../../src/selfhost/orb-collector";
@@ -77,7 +78,7 @@ describe("exportOrbBatch() — always-on; reads review_audit, ships anonymized r
     delete process.env.ORB_COLLECTOR_TOKEN;
   });
   afterEach(() => {
-    for (const k of ["GITHUB_APP_PRIVATE_KEY", "ORB_APP_ID", "ORB_ANONYMIZE", "ORB_AIR_GAP", "ORB_COLLECTOR_URL", "ORB_COLLECTOR_TOKEN", "GITHUB_APP_ID"]) delete (process.env as NodeJS.Dict<string>)[k];
+    for (const k of ["GITHUB_APP_PRIVATE_KEY", "ORB_APP_ID", "ORB_ANONYMIZE", "ORB_AIR_GAP", "ORB_COLLECTOR_URL", "ORB_COLLECTOR_TOKEN", "GITHUB_APP_ID", "ORB_ENROLLMENT_SECRET"]) delete (process.env as NodeJS.Dict<string>)[k];
   });
 
   it("returns 0 when the App private key is not configured (App not set up → nothing to export)", async () => {
@@ -88,11 +89,28 @@ describe("exportOrbBatch() — always-on; reads review_audit, ships anonymized r
     expect(await exportOrbBatch(db, 200, async () => new Response(null, { status: 200 }))).toBe(0);
   });
 
-  it("returns 0 in air-gap mode", async () => {
+  it("returns 0 in air-gap mode (self-managed instance)", async () => {
     process.env.ORB_AIR_GAP = "true";
     expect(await exportOrbBatch(makeDb(), 200, async () => new Response(null, { status: 200 }))).toBe(0);
   });
 
+  it("brokered mode exports despite air-gap AND without a local App key — telemetry is the fleet contract", async () => {
+    // A brokered self-host (ORB_ENROLLMENT_SECRET set) relies on the Orb for tokens + webhook relay, so it holds
+    // no local App key and air-gap must NOT suppress the export. With no Orb/App id, instanceId derives from the
+    // enrollment secret (stable + unique per install, not the "unknown" collision).
+    delete (process.env as NodeJS.Dict<string>).GITHUB_APP_PRIVATE_KEY;
+    delete (process.env as NodeJS.Dict<string>).ORB_APP_ID;
+    process.env.ORB_AIR_GAP = "true";
+    process.env.ORB_ENROLLMENT_SECRET = "orbsec_test_enrollment";
+    const db = makeDb();
+    await audit(db, "owner/repo", 9, "gate_decision", "merge", "2026-03-01T00:00:00Z");
+    await audit(db, "owner/repo", 9, "pr_outcome", "merged", "2026-03-01T01:00:00Z");
+    let captured: { instance_id: string } | undefined;
+    const n = await exportOrbBatch(db, 200, async (_u, init) => { captured = JSON.parse(init!.body as string); return new Response(null, { status: 200 }); });
+    expect(n).toBe(1); // exported despite air-gap + no local App key
+    expect(captured!.instance_id).toBe(createHash("sha256").update("orbsec_test_enrollment").digest("hex").slice(0, 16));
+  });
+
   it("returns 0 when nothing is resolved", async () => {
     const db = makeDb();
     await audit(db, "o/r", 1, "gate_decision", "merge", "2026-01-01T00:00:00Z"); // decision but no outcome