@bivy/bivy 0.0.0 → 0.1.0-staging.2

package/dist/github-app-connect.js

@@ -0,0 +1,235 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { SecretVault } from "./secrets.js";
+import { privateKeyIdFor, upsertGitHubApp } from "./github-apps.js";
+import { createAppJwt } from "./github-app-auth.js";
+/**
+ * Fetch the app's slug + name from GitHub with an app JWT. The slug is the
+ * unique `@`-mention handle; failure is non-fatal (we just skip registration).
+ */
+async function fetchAppIdentity(appId, privateKeyPem) {
+    try {
+        const jwt = createAppJwt(appId, privateKeyPem, Math.floor(Date.now() / 1000));
+        const res = await fetch("https://api.github.com/app", {
+            headers: { authorization: `Bearer ${jwt}`, accept: "application/vnd.github+json", "user-agent": "bivy" },
+        });
+        if (!res.ok)
+            return undefined;
+        const data = (await res.json().catch(() => ({})));
+        return { slug: String(data.slug ?? ""), name: String(data.name ?? data.slug ?? "") };
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Point the app's OWN webhook at the given URL + secret via the app JWT
+ * (PATCH /app/hook/config), mirroring the web connect flow so the CLI no longer
+ * makes the user paste the webhook by hand. Best-effort: returns false and the
+ * caller falls back to printing manual instructions if GitHub rejects it.
+ */
+async function configureAppWebhook(appId, privateKeyPem, url, secret) {
+    try {
+        const jwt = createAppJwt(appId, privateKeyPem, Math.floor(Date.now() / 1000));
+        const res = await fetch("https://api.github.com/app/hook/config", {
+            method: "PATCH",
+            headers: { authorization: `Bearer ${jwt}`, accept: "application/vnd.github+json", "user-agent": "bivy", "content-type": "application/json" },
+            body: JSON.stringify({ url, secret, content_type: "json" }),
+        });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve a GitHub App's numeric App ID. A numeric value passes through; a slug
+ * (e.g. "bivy-app") is looked up via GET /apps/{slug} — which GitHub 404s when
+ * unauthenticated, so it needs a token from --github-token or GITHUB_TOKEN /
+ * GH_TOKEN. Without a token a slug can't be resolved, so we ask for the numeric
+ * id instead (there is no other way to get it programmatically for an existing
+ * app the node doesn't yet hold a key for).
+ */
+async function resolveAppId(value, token) {
+    if (/^\d+$/.test(value))
+        return value;
+    if (!token) {
+        throw new Error(`"${value}" is not a numeric App ID. To connect by slug pass --github-token <token> ` +
+            `(or set GITHUB_TOKEN), or supply the numeric --app-id from the app's settings page.`);
+    }
+    const res = await fetch(`https://api.github.com/apps/${encodeURIComponent(value)}`, {
+        headers: { authorization: `Bearer ${token}`, accept: "application/vnd.github+json", "user-agent": "bivy" },
+    });
+    if (!res.ok)
+        throw new Error(`Could not resolve GitHub App slug "${value}" (${res.status}). Check the slug and the token's scope.`);
+    const data = (await res.json().catch(() => ({})));
+    if (!data.id)
+        throw new Error(`GitHub returned no App ID for slug "${value}".`);
+    return String(data.id);
+}
+/**
+ * `bivy github:app-connect` — connect a user-owned GitHub App (M2, flavor A).
+ *
+ * Stores the app's private key in the node vault and the app id in cli.json, then
+ * asks the control plane for a `github_app` inbound hook and prints the webhook
+ * URL + secret to paste into the app (one webhook covers every repo that app is
+ * installed on). A node may hold several apps — a private app only installs on
+ * the account that owns it, so personal repos and each org need one app each.
+ *
+ * The private key stays on the node (the node mints its own installation tokens);
+ * the control plane only ever holds the webhook signing secret. So a single app
+ * install replaces per-repo webhooks without weakening the privacy model.
+ *
+ * The app's webhook is configured automatically (PATCH /app/hook/config via the
+ * app JWT) — parity with the web connect flow — so nothing has to be pasted.
+ *
+ * Usage:
+ *   bivy github:app-connect (--app-id <id> | --slug <slug>) --key <path.pem>
+ *                           [--label bivy] [--node-label <name>]
+ *                           [--github-token <t>]   # resolve --slug -> App ID
+ *                           [--rotate-webhook]      # mint a fresh signing secret
+ */
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "..");
+const appDir = process.env.BIVY_DATA_DIR ?? path.join(repoRoot, ".bivy");
+const cliConfigPath = path.join(appDir, "cli.json");
+const relayConfigPath = path.join(appDir, "relay.json");
+function argValue(args, name) {
+    const i = args.indexOf(`--${name}`);
+    return i >= 0 && i + 1 < args.length ? args[i + 1] : undefined;
+}
+function hasFlag(args, name) {
+    return args.includes(`--${name}`);
+}
+function loadCliConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(cliConfigPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function loadRelayConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(relayConfigPath, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+async function main() {
+    const args = process.argv.slice(2);
+    const appIdOrSlug = (argValue(args, "app-id") || argValue(args, "slug") || process.env.BIVY_GITHUB_APP_ID || "").trim();
+    const keyPath = (argValue(args, "key") || "").trim();
+    const baseLabel = (argValue(args, "label") || "bivy").trim();
+    const nodeLabelArg = (argValue(args, "node-label") || "").trim();
+    const nodeLabel = nodeLabelArg ? (nodeLabelArg.includes("/") ? nodeLabelArg : `bivy/${nodeLabelArg}`) : "";
+    const githubToken = (argValue(args, "github-token") || process.env.GITHUB_TOKEN || process.env.GH_TOKEN || "").trim();
+    const rotateWebhook = hasFlag(args, "rotate-webhook");
+    if (!appIdOrSlug)
+        throw new Error("Missing --app-id (numeric App ID) or --slug (the app's slug).");
+    if (!keyPath)
+        throw new Error("Missing --key (path to the app's .pem private key).");
+    const privateKeyPem = fs.readFileSync(keyPath, "utf8");
+    if (!privateKeyPem.includes("PRIVATE KEY"))
+        throw new Error(`${keyPath} does not look like a PEM private key.`);
+    const relay = loadRelayConfig();
+    if (!relay?.controlPlaneUrl || !relay?.enrollmentToken) {
+        throw new Error("This node isn't enrolled with a control plane. Run 'bivy relay:setup' first.");
+    }
+    // A slug (e.g. "bivy-app") is resolved to the numeric App ID everything else
+    // keys on; a numeric value passes straight through.
+    const appId = await resolveAppId(appIdOrSlug, githubToken);
+    // 1) Private key → node vault (never leaves the machine). Keyed per app, so a
+    // node can hold several apps' keys side by side (personal account + orgs).
+    const keyId = privateKeyIdFor(appId);
+    new SecretVault(appDir).setLocal(keyId, privateKeyPem, `GitHub App private key (${appId})`);
+    // 2) Reuse this app's existing hook if it has one (so its already-configured
+    // webhook keeps working), otherwise ask for a new one. Each app needs its own:
+    // the hook's secret is what GitHub signs that app's deliveries with.
+    // --rotate-webhook skips the adopt step to force a fresh secret (e.g. after the
+    // old one leaked); we re-point the app's webhook at it below.
+    const existing = rotateWebhook
+        ? undefined
+        : await fetch(`${relay.controlPlaneUrl.replace(/\/$/, "")}/node/hooks/github_app?appId=${encodeURIComponent(appId)}`, { headers: { authorization: `Bearer ${relay.enrollmentToken}` } })
+            .then((r) => (r.ok ? r.json() : undefined))
+            .catch(() => undefined);
+    const res = existing?.id && existing?.url && existing?.secret
+        ? new Response(JSON.stringify(existing), { status: 200, headers: { "content-type": "application/json" } })
+        : await fetch(`${relay.controlPlaneUrl.replace(/\/$/, "")}/node/hooks`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${relay.enrollmentToken}`, "content-type": "application/json" },
+            body: JSON.stringify({ kind: "github_app" }),
+        });
+    const hook = (await res.json().catch(() => ({})));
+    if (!res.ok || !hook.url || !hook.secret) {
+        throw new Error(hook.error || `Control plane did not return a hook (${res.status}).`);
+    }
+    // 2b) Resolve the app's slug (its unique `@`-mention handle) + name and
+    // register them so mentions route correctly and the UI shows what's connected.
+    const identity = await fetchAppIdentity(appId, privateKeyPem);
+    if (hook.id && identity?.slug) {
+        await fetch(`${relay.controlPlaneUrl.replace(/\/$/, "")}/node/hooks/${encodeURIComponent(hook.id)}/app-meta`, {
+            method: "POST",
+            headers: { authorization: `Bearer ${relay.enrollmentToken}`, "content-type": "application/json" },
+            body: JSON.stringify({ mention: identity.slug, name: identity.name, appId }),
+        }).catch(() => { });
+    }
+    // 2c) Point the app's own webhook at the hook automatically (parity with the
+    // web connect flow), so there is nothing to paste by hand. Best-effort.
+    const webhookConfigured = await configureAppWebhook(appId, privateKeyPem, hook.url, hook.secret);
+    // 3) Record the app in the node's registry (app id + a secret:// reference,
+    // never the raw key). The registry is what lets one node serve several apps;
+    // the env block below only ever describes one, and is kept for container and
+    // ephemeral setups configured purely through the environment.
+    upsertGitHubApp(appDir, {
+        appId,
+        slug: identity?.slug,
+        name: identity?.name,
+        privateKeyRef: `secret://${keyId}`,
+        hookId: hook.id,
+    });
+    const config = loadCliConfig();
+    const env = (config.env && typeof config.env === "object" ? config.env : {});
+    config.env = {
+        ...env,
+        BIVY_GITHUB_HOSTED_TASKS: "1",
+        BIVY_GITHUB_LABEL: baseLabel,
+        ...(identity?.slug ? { BIVY_GITHUB_APP_SLUG: identity.slug } : {}),
+        ...(nodeLabel ? { BIVY_NODE_LABEL: nodeLabel } : {}),
+    };
+    fs.mkdirSync(appDir, { recursive: true });
+    fs.writeFileSync(cliConfigPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(cliConfigPath, 0o600);
+    }
+    catch {
+        // best effort
+    }
+    console.log("\n✓ GitHub App connected. Private key stored in this node's vault (cli.json holds only a secret:// ref).\n");
+    if (webhookConfigured) {
+        console.log("✓ Webhook configured on the app automatically — nothing to paste.");
+        console.log(`  Payload URL:  ${hook.url}`);
+        console.log("  Events:       Issues, Issue comment");
+    }
+    else {
+        console.log("Could not set the webhook automatically. Point the app's webhook at this URL by hand");
+        console.log("(one webhook covers every repo this app is installed on):");
+        console.log(`  Payload URL:  ${hook.url}`);
+        console.log(`  Secret:       ${hook.secret}`);
+        console.log("  Content type: application/json");
+        console.log("  Events:       Issues, Issue comment");
+    }
+    console.log("\nApp permissions needed: Issues (RW), Contents (RW), Pull requests (RW).");
+    console.log(`Then install the app on your repos. Work routes to label ${baseLabel}${nodeLabel ? ` / ${nodeLabel}` : ""}.`);
+    if (identity?.slug)
+        console.log(`Trigger it from an issue comment with: @${identity.slug} <instruction>`);
+    console.log("Restart the node to apply: bivy restart (or bivy start).");
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/github-app-manifest.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+/**
+ * GitHub App **manifest** flow (M2, one-click create).
+ *
+ * Instead of hand-filling the "New GitHub App" form, we POST a pre-built manifest
+ * to GitHub; the user clicks confirm; GitHub redirects back with a temporary
+ * `code`; we exchange it for the app's id, private key, and webhook secret.
+ *
+ * Custody stays flavor-A: this conversion runs **on the node**, so the private
+ * key never reaches the control plane. The node keeps the key and only hands the
+ * control plane the webhook signing secret (to verify inbound events).
+ */
+/**
+ * Build the manifest GitHub reads to pre-configure the app: the permissions and
+ * events the work queue needs, the webhook target, and the redirect back here.
+ */
+export function buildAppManifest(input) {
+    return {
+        name: input.name,
+        url: input.url,
+        hook_attributes: { url: input.hookUrl, active: true },
+        redirect_url: input.redirectUrl,
+        public: false,
+        default_permissions: {
+            issues: "write",
+            contents: "write",
+            pull_requests: "write",
+            metadata: "read",
+        },
+        default_events: ["issues", "issue_comment"],
+    };
+}
+/**
+ * Exchange a manifest `code` for the created app's credentials. GitHub returns
+ * these **once**; the caller must persist the key + secret immediately.
+ */
+export async function convertManifest(code, fetchImpl = fetch) {
+    const res = await fetchImpl(`https://api.github.com/app-manifests/${encodeURIComponent(code)}/conversions`, {
+        method: "POST",
+        headers: { accept: "application/vnd.github+json", "x-github-api-version": "2022-11-28", "user-agent": "bivy" },
+    });
+    if (!res.ok) {
+        const detail = await res.text().catch(() => "");
+        throw new Error(`GitHub manifest conversion failed (${res.status}): ${detail.slice(0, 200)}`);
+    }
+    const data = (await res.json().catch(() => ({})));
+    if (!data.id || !data.pem || !data.webhook_secret) {
+        throw new Error("GitHub manifest conversion response was missing id/pem/webhook_secret");
+    }
+    return {
+        appId: String(data.id),
+        slug: String(data.slug ?? ""),
+        name: String(data.name ?? data.slug ?? ""),
+        pem: String(data.pem),
+        webhookSecret: String(data.webhook_secret),
+        htmlUrl: String(data.html_url ?? ""),
+    };
+}
+/**
+ * A tiny auto-submitting HTML page that POSTs the manifest to GitHub. The
+ * manifest must be sent as a form field (it's too big/nested for a query
+ * string), so we render a form and submit it on load.
+ */
+export function renderManifestForm(manifest, opts) {
+    const action = opts.org
+        ? `https://github.com/organizations/${encodeURIComponent(opts.org)}/settings/apps/new?state=${encodeURIComponent(opts.state)}`
+        : `https://github.com/settings/apps/new?state=${encodeURIComponent(opts.state)}`;
+    const manifestJson = JSON.stringify(manifest)
+        .replace(/&/g, "&")
+        .replace(/"/g, """)
+        .replace(/</g, "&lt;");
+    return `<!doctype html><html><head><meta charset="utf-8"><title>Creating your Bivy GitHub App…</title></head>
+<body style="font-family:system-ui;padding:2rem">
+<p>Redirecting to GitHub to create your Bivy app…</p>
+<form id="f" method="post" action="${action}">
+<input type="hidden" name="manifest" value="${manifestJson}">
+<noscript><button type="submit">Continue to GitHub</button></noscript>
+</form>
+<script${opts.nonce ? ` nonce="${opts.nonce}"` : ""}>document.getElementById("f").submit()</script>
+</body></html>`;
+}

package/dist/github-app-sync-cli.js

@@ -0,0 +1,93 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { listGitHubApps } from "./github-apps.js";
+/**
+ * `bivy github:app-sync [on|off]` (issue #88) — opt this node in or out of
+ * cross-node GitHub App private-key sync.
+ *
+ * Off by default: a GitHub App key is a repo-write credential, so widening
+ * which nodes hold it is a deliberate, per-node decision (see the "Design
+ * decisions" section of issue #88), not automatic like model/provider auth
+ * sync. Turning sync ON on two or more nodes lets a `github:app-connect` done
+ * on ONE of them reach the others automatically, E2E-encrypted, without
+ * re-uploading the `.pem` anywhere — see docs/credential-sync.md.
+ *
+ * The flag itself lives in cli.json's env block (BIVY_GITHUB_APP_SYNC), the
+ * same place every other node-level feature flag lives (e.g.
+ * BIVY_GITHUB_HOSTED_TASKS) — `bin/bivy.mjs` spreads that block into the
+ * daemon's environment on start/service-install, so this only takes effect
+ * after `bivy restart`.
+ */
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "..");
+const appDir = process.env.BIVY_DATA_DIR ?? path.join(repoRoot, ".bivy");
+const cliConfigPath = path.join(appDir, "cli.json");
+function loadCliConfig() {
+    try {
+        return JSON.parse(fs.readFileSync(cliConfigPath, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+function saveCliConfig(config) {
+    fs.mkdirSync(appDir, { recursive: true });
+    fs.writeFileSync(cliConfigPath, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(cliConfigPath, 0o600);
+    }
+    catch {
+        // best effort
+    }
+}
+function isEnabled(config) {
+    return String(config.env?.BIVY_GITHUB_APP_SYNC ?? "").trim() === "1";
+}
+function printStatus(config) {
+    const enabled = isEnabled(config);
+    console.log(`GitHub App key sync: ${enabled ? "ON" : "OFF"} on this node.`);
+    const apps = listGitHubApps(appDir);
+    if (apps.length) {
+        console.log("\nApps this node holds a key for:");
+        for (const app of apps)
+            console.log(`  - ${app.slug ? `@${app.slug}` : app.appId} (${app.appId})`);
+    }
+    console.log(enabled
+        ? "\nThis node pushes the apps above (E2E-encrypted) for other opted-in nodes to pull, and pulls apps connected elsewhere on the account."
+        : "\nRun 'bivy github:app-sync on' to let this node send/receive GitHub App keys with the account's other opted-in nodes.");
+}
+async function main() {
+    const arg = (process.argv[2] || "").trim().toLowerCase();
+    const config = loadCliConfig();
+    if (!arg || arg === "status") {
+        printStatus(config);
+        return;
+    }
+    if (arg !== "on" && arg !== "off") {
+        console.error(`Usage: bivy github:app-sync [on|off]\n(no argument prints the current status)`);
+        process.exit(1);
+        return;
+    }
+    const env = (config.env && typeof config.env === "object" ? config.env : {});
+    if (arg === "on") {
+        config.env = { ...env, BIVY_GITHUB_APP_SYNC: "1" };
+        console.log("✓ GitHub App key sync enabled on this node.");
+        console.log("  Every GitHub App connected here (github:app-connect) will be pushed, E2E-encrypted, for the");
+        console.log("  account's other opted-in nodes to pull — and this node will pull apps connected elsewhere.");
+    }
+    else {
+        const { BIVY_GITHUB_APP_SYNC: _drop, ...rest } = env;
+        config.env = rest;
+        console.log("✓ GitHub App key sync disabled on this node.");
+        console.log("  Keys already imported here are NOT deleted; this only stops future pushes/pulls.");
+    }
+    saveCliConfig(config);
+    console.log("\nRestart the node to apply: bivy restart (or bivy start).");
+}
+main().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/github-app-vault.js

@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { randomBytes } from "node:crypto";
+import { seal, open } from "./e2e.js";
+/**
+ * GitHub App private-key vault sync (issue #88): opt-in, E2E-encrypted delivery
+ * of a connected GitHub App's private key from the node that holds it to the
+ * account's OTHER enrolled nodes, riding the same wrap-key mechanism already
+ * used for `model-auth-vault` (see src/pairing-crypto.ts, src/device-registry.ts).
+ *
+ * This module holds the parts that don't need a network round-trip: the
+ * envelope format sealed under a per-app symmetric vault key, and the local
+ * cache of resolved vault keys (one per app, since apps sync independently —
+ * a node opted into sync only has the vault keys for apps it actually holds or
+ * has pulled). The network glue (fetching/pushing against the control plane,
+ * answering key requests) lives in src/server.ts next to its `model-auth-vault`
+ * counterpart, which follows the same shape.
+ *
+ * The control plane only ever sees: ciphertext, and the vault key itself
+ * wrapped per-recipient-node under an ECDH key it cannot derive. It never sees
+ * a plaintext private key, matching the guarantee described in
+ * src/github-apps.ts and docs/credential-sync.md.
+ */
+const ENVELOPE_VERSION = 1;
+/** Seal one app's private key (+ non-secret display metadata) for the vault. */
+export function encryptGithubAppEnvelope(envelope, vaultKeyB64) {
+    const payload = { v: ENVELOPE_VERSION, ...envelope };
+    return seal(Buffer.from(vaultKeyB64, "base64"), JSON.stringify(payload));
+}
+/** Open a sealed envelope. Throws if the key is wrong/stale or the payload is malformed. */
+export function decryptGithubAppEnvelope(ciphertext, vaultKeyB64) {
+    const parsed = JSON.parse(open(Buffer.from(vaultKeyB64, "base64"), ciphertext));
+    if (!parsed || typeof parsed !== "object" || typeof parsed.appId !== "string" || typeof parsed.privateKeyPem !== "string" || !parsed.appId || !parsed.privateKeyPem) {
+        throw new Error("Malformed GitHub App vault envelope");
+    }
+    return {
+        v: typeof parsed.v === "number" ? parsed.v : ENVELOPE_VERSION,
+        appId: parsed.appId,
+        privateKeyPem: parsed.privateKeyPem,
+        slug: typeof parsed.slug === "string" ? parsed.slug : undefined,
+        name: typeof parsed.name === "string" ? parsed.name : undefined,
+        owner: typeof parsed.owner === "string" ? parsed.owner : undefined,
+        ownerType: parsed.ownerType === "Organization" || parsed.ownerType === "User" ? parsed.ownerType : undefined,
+        hookId: typeof parsed.hookId === "string" ? parsed.hookId : undefined,
+    };
+}
+function vaultKeyFilePath(dataDir) {
+    return path.join(dataDir, "github-app-vault.json");
+}
+function readLocalVaultKeys(dataDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(vaultKeyFilePath(dataDir), "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeLocalVaultKeys(dataDir, keys) {
+    fs.mkdirSync(dataDir, { recursive: true });
+    const target = vaultKeyFilePath(dataDir);
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, `${JSON.stringify(keys, null, 2)}\n`, { mode: 0o600 });
+    try {
+        fs.chmodSync(tmp, 0o600);
+    }
+    catch {
+        // best effort on platforms without chmod
+    }
+    fs.renameSync(tmp, target);
+}
+/** The cached vault key for `appId`, if this node has resolved one. */
+export function readLocalGithubAppVaultKey(dataDir, appId) {
+    const entry = readLocalVaultKeys(dataDir)[appId];
+    if (!entry?.vaultKeyB64)
+        return undefined;
+    return Buffer.from(entry.vaultKeyB64, "base64").length === 32 ? entry.vaultKeyB64 : undefined;
+}
+export function writeLocalGithubAppVaultKey(dataDir, appId, vaultKeyB64) {
+    const keys = readLocalVaultKeys(dataDir);
+    keys[appId] = { vaultKeyB64, createdAt: new Date().toISOString() };
+    writeLocalVaultKeys(dataDir, keys);
+}
+/** Drop a stale cached key (e.g. it no longer decrypts the current ciphertext
+ *  because the app was rotated) so the node re-requests a fresh wrap. */
+export function forgetLocalGithubAppVaultKey(dataDir, appId) {
+    const keys = readLocalVaultKeys(dataDir);
+    if (!(appId in keys))
+        return;
+    delete keys[appId];
+    writeLocalVaultKeys(dataDir, keys);
+}
+/**
+ * Mint a brand-new local vault key for `appId`, OVERWRITING any cached one.
+ * Used both the first time this node pushes the app, and to actually rotate:
+ * a node that was removed from the account keeps whatever vault key it last
+ * cached, so the only way to make that stale copy stop working is for a
+ * surviving node to start encrypting under a key the removed node never saw.
+ */
+export function mintLocalGithubAppVaultKey(dataDir, appId) {
+    const vaultKeyB64 = randomBytes(32).toString("base64");
+    writeLocalGithubAppVaultKey(dataDir, appId, vaultKeyB64);
+    return vaultKeyB64;
+}

package/dist/github-apps.js

@@ -0,0 +1,121 @@
+// SPDX-License-Identifier: FSL-1.1-ALv2
+// Copyright (c) 2026 Petter André Sjulstad
+import fs from "node:fs";
+import path from "node:path";
+import { resolveSecret } from "./secrets.js";
+const EMPTY = { version: 1, apps: [] };
+function registryPath(dataDir) {
+    return path.join(dataDir, "github-apps.json");
+}
+/** The conventional vault id for an app's private key. */
+export function privateKeyIdFor(appId) {
+    return `github.app.${appId}`;
+}
+function readRegistry(dataDir) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(registryPath(dataDir), "utf8"));
+        const apps = Array.isArray(raw.apps) ? raw.apps.filter((a) => a && typeof a.appId === "string" && a.appId) : [];
+        return { version: typeof raw.version === "number" ? raw.version : 1, apps };
+    }
+    catch {
+        return { ...EMPTY, apps: [] };
+    }
+}
+function writeRegistry(dataDir, file) {
+    const target = registryPath(dataDir);
+    const tmp = `${target}.tmp`;
+    fs.mkdirSync(dataDir, { recursive: true });
+    fs.writeFileSync(tmp, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+    fs.renameSync(tmp, target);
+}
+/**
+ * Single-app installs configured the node through the environment
+ * (`BIVY_GITHUB_APP_ID` + `BIVY_GITHUB_APP_PRIVATE_KEY`). Surface that as a
+ * registry entry so the rest of the code only ever deals with a list.
+ *
+ * Not written to disk: the env vars remain the source of truth for containers
+ * and ephemeral runners that are configured purely through the environment.
+ */
+function recordFromEnv(env) {
+    const appId = env.BIVY_GITHUB_APP_ID?.trim();
+    if (!appId)
+        return undefined;
+    return {
+        appId,
+        slug: env.BIVY_GITHUB_APP_SLUG?.trim() || undefined,
+        privateKeyRef: env.BIVY_GITHUB_APP_PRIVATE_KEY?.trim() || "secret://github.app-private-key",
+    };
+}
+/**
+ * Every app this node serves, the registry first and then any env-configured app
+ * that isn't already in it. Deduplicated by app id, registry wins.
+ */
+export function listGitHubApps(dataDir, env = process.env) {
+    const apps = readRegistry(dataDir).apps.slice();
+    const fromEnv = recordFromEnv(env);
+    if (fromEnv && !apps.some((a) => a.appId === fromEnv.appId))
+        apps.push(fromEnv);
+    return apps;
+}
+/** Add or update an app by id, preserving fields the caller didn't supply. */
+export function upsertGitHubApp(dataDir, record) {
+    const file = readRegistry(dataDir);
+    const i = file.apps.findIndex((a) => a.appId === record.appId);
+    if (i >= 0) {
+        file.apps[i] = { ...file.apps[i], ...record };
+    }
+    else {
+        file.apps.push({ addedAt: new Date().toISOString(), ...record });
+    }
+    writeRegistry(dataDir, file);
+    return file.apps;
+}
+/** Remove an app by id. Returns true when something was removed. */
+export function removeGitHubApp(dataDir, appId) {
+    const file = readRegistry(dataDir);
+    const before = file.apps.length;
+    file.apps = file.apps.filter((a) => a.appId !== appId);
+    if (file.apps.length === before)
+        return false;
+    writeRegistry(dataDir, file);
+    return true;
+}
+/**
+ * Resolve each app's private key. Apps whose key can't be resolved (revoked
+ * vault entry, missing 1Password item) are dropped rather than throwing — one
+ * broken app must not take down the GitHub integration for the others.
+ */
+export async function loadGitHubAppConfigs(dataDir, env = process.env) {
+    const out = [];
+    for (const record of listGitHubApps(dataDir, env)) {
+        const ref = record.privateKeyRef;
+        let privateKeyPem;
+        try {
+            privateKeyPem =
+                ref.startsWith("secret://") || ref.startsWith("op://") || ref.startsWith("env://")
+                    ? await resolveSecret(ref, dataDir)
+                    : ref;
+        }
+        catch {
+            privateKeyPem = undefined;
+        }
+        if (!privateKeyPem || !privateKeyPem.includes("PRIVATE KEY"))
+            continue;
+        out.push({ appId: record.appId, privateKeyPem, record });
+    }
+    return out;
+}
+/**
+ * Pick the order to try apps in when resolving which one covers `owner/repo`.
+ * An app owned by the same account as the repo is overwhelmingly the right one,
+ * so try it first — that turns the common case into a single API call instead of
+ * one per configured app.
+ */
+export function orderAppsForOwner(apps, owner) {
+    const lower = owner.toLowerCase();
+    return apps.slice().sort((a, b) => {
+        const aMatch = a.record.owner?.toLowerCase() === lower ? 0 : 1;
+        const bMatch = b.record.owner?.toLowerCase() === lower ? 0 : 1;
+        return aMatch - bMatch;
+    });
+}