@kici-dev/orchestrator 0.1.20 → 0.1.22

package/dist/index.js

@@ -3,12 +3,19 @@ import { CopyObjectCommand, DeleteObjectCommand, GetObjectCommand, HeadObjectCom
 import { Upload } from "@aws-sdk/lib-storage";
 import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
 import { createLogger, createS3Client, sha256 } from "@kici-dev/shared";
-import { promises } from "node:fs";
+import * as fs from "node:fs";
+import { mkdtempSync, promises, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { createHmac, randomBytes, randomUUID } from "node:crypto";
-import "node:fs/promises";
+import { createHmac, hkdfSync, randomBytes, randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
 import { Kysely, PostgresDialect, sql } from "kysely";
 import pg from "pg";
+import { platform, tmpdir } from "node:os";
+import { createInterface } from "node:readline";
+import { Octokit } from "@octokit/rest";
+import { createAppAuth } from "@octokit/auth-app";
+import { createServer } from "node:http";
+import { exec } from "node:child_process";
 import.meta.url;
 //#endregion
 //#region src/storage/s3.ts
@@ -558,7 +565,7 @@ function createCacheStorage(config) {
 * downloads the source tarball, extracts it, and imports the workflow entry
 * via the shared oxc-transform ESM loader hook.
 */
-const logger$2 = createLogger({ prefix: "source-cache" });
+const logger$3 = createLogger({ prefix: "source-cache" });
 /** Cache key format: source/{contentHash}.tar.gz */
 function sourceKey(contentHash) {
 	return `source/${contentHash}.tar.gz`;
@@ -571,7 +578,7 @@ var SourceCache = class {
 	async has(contentHash) {
 		const key = sourceKey(contentHash);
 		const exists = await this.storage.has(key);
-		logger$2.debug(`has(${contentHash}): ${exists}`);
+		logger$3.debug(`has(${contentHash}): ${exists}`);
 		return exists;
 	}
 	async get(contentHash) {
@@ -579,8 +586,8 @@ var SourceCache = class {
 		const data = await this.storage.get(key);
 		if (data) {
 			await this.storage.touch(key);
-			logger$2.debug(`get(${contentHash}): hit (${data.length} bytes)`);
-		} else logger$2.debug(`get(${contentHash}): miss`);
+			logger$3.debug(`get(${contentHash}): hit (${data.length} bytes)`);
+		} else logger$3.debug(`get(${contentHash}): miss`);
 		return data;
 	}
 	async getUrl(contentHash) {
@@ -588,8 +595,8 @@ var SourceCache = class {
 		const url = await this.storage.getUrl(key);
 		if (url) {
 			await this.storage.touch(key);
-			logger$2.debug(`getUrl(${contentHash}): hit`);
-		} else logger$2.debug(`getUrl(${contentHash}): miss`);
+			logger$3.debug(`getUrl(${contentHash}): hit`);
+		} else logger$3.debug(`getUrl(${contentHash}): miss`);
 		return url;
 	}
 	async getUploadUrl(contentHash) {
@@ -600,12 +607,12 @@ var SourceCache = class {
 		const key = sourceKey(contentHash);
 		await this.storage.put(key, tarball);
 		const size = typeof tarball === "string" ? Buffer.byteLength(tarball) : tarball.length;
-		logger$2.info(`store(${contentHash}): stored (${size} bytes)`);
+		logger$3.info(`store(${contentHash}): stored (${size} bytes)`);
 	}
 	async remove(contentHash) {
 		const key = sourceKey(contentHash);
 		const removed = await this.storage.delete(key);
-		logger$2.info(`remove(${contentHash}): ${removed ? "removed" : "not found"}`);
+		logger$3.info(`remove(${contentHash}): ${removed ? "removed" : "not found"}`);
 		return removed;
 	}
 };
@@ -620,7 +627,7 @@ var SourceCache = class {
 *
 * Cache key format: deps/{platform}-{arch}/{lockfileHash}.tar.gz
 */
-const logger$1 = createLogger({ prefix: "dep-cache" });
+const logger$2 = createLogger({ prefix: "dep-cache" });
 /** Default max tarball size: 500MB */
 const DEFAULT_MAX_TARBALL_BYTES = 524288e3;
 /** Build cache key for dependency tarball: deps/{platform}-{arch}/{lockfileHash}.tar.gz */
@@ -638,7 +645,7 @@ var DepCache = class {
 	async has(lockfileHash, platform, arch) {
 		const key = depKey(lockfileHash, platform, arch);
 		const exists = await this.storage.has(key);
-		logger$1.debug(`has(${lockfileHash}): ${exists}`, {
+		logger$2.debug(`has(${lockfileHash}): ${exists}`, {
 			platform,
 			arch
 		});
@@ -653,11 +660,11 @@ var DepCache = class {
 		const url = await this.storage.getUrl(key);
 		if (url) {
 			await this.storage.touch(key);
-			logger$1.debug(`getUrl(${lockfileHash}): hit`, {
+			logger$2.debug(`getUrl(${lockfileHash}): hit`, {
 				platform,
 				arch
 			});
-		} else logger$1.debug(`getUrl(${lockfileHash}): miss`, {
+		} else logger$2.debug(`getUrl(${lockfileHash}): miss`, {
 			platform,
 			arch
 		});
@@ -672,7 +679,7 @@ var DepCache = class {
 		const key = depKey(lockfileHash, platform, arch);
 		const url = await this.storage.getUrl(key);
 		if (!url) {
-			logger$1.debug(`getUrlAndHash(${lockfileHash}): miss`, {
+			logger$2.debug(`getUrlAndHash(${lockfileHash}): miss`, {
 				platform,
 				arch
 			});
@@ -681,7 +688,7 @@ var DepCache = class {
 		await this.storage.touch(key);
 		const hashKey = `deps/${platform}-${arch}/${lockfileHash}.hash`;
 		const hash = (await this.storage.get(hashKey))?.toString("utf-8") || void 0;
-		logger$1.debug(`getUrlAndHash(${lockfileHash}): hit`, {
+		logger$2.debug(`getUrlAndHash(${lockfileHash}): hit`, {
 			platform,
 			arch,
 			hasHash: !!hash
@@ -706,7 +713,7 @@ var DepCache = class {
 		if (tarballData.length > this.maxTarballBytes) throw new Error(`Dep tarball exceeds max size: ${tarballData.length} bytes > ${this.maxTarballBytes} bytes limit`);
 		const key = depKey(lockfileHash, platform, arch);
 		await this.storage.put(key, tarballData);
-		logger$1.info(`store: ${tarballData.length} bytes`, {
+		logger$2.info(`store: ${tarballData.length} bytes`, {
 			lockfileHash,
 			platform,
 			arch
@@ -723,7 +730,7 @@ var DepCache = class {
 	async remove(lockfileHash, platform, arch) {
 		const key = depKey(lockfileHash, platform, arch);
 		const removed = await this.storage.delete(key);
-		logger$1.info(`remove(${lockfileHash}): ${removed ? "removed" : "not found"}`, {
+		logger$2.info(`remove(${lockfileHash}): ${removed ? "removed" : "not found"}`, {
 			platform,
 			arch
 		});
@@ -754,7 +761,7 @@ var DepCache = class {
 * hash and size accounting outside the tarball's own (presigned, metadata-less)
 * upload.
 */
-const logger = createLogger({ prefix: "user-cache" });
+const logger$1 = createLogger({ prefix: "user-cache" });
 /**
 * Cluster-wide default quota: 5 GiB. Serves as the fallback when an org has no
 * per-org override in `org_settings.user_cache_quota_bytes`. The cluster-wide
@@ -798,7 +805,7 @@ var UserCache = class {
 		try {
 			limits = await this.orgLimitsReader(org);
 		} catch (err) {
-			logger.warn("user-cache org-limits lookup failed — using cluster defaults", {
+			logger$1.warn("user-cache org-limits lookup failed — using cluster defaults", {
 				org,
 				error: err instanceof Error ? err.message : String(err)
 			});
@@ -899,7 +906,7 @@ var UserCache = class {
 		const prefix = this.writePrefix(ref);
 		const final = this.finalKey(prefix, ref.key);
 		if (await this.storage.has(final)) {
-			logger.info("user-cache save skipped (immutable key exists)", { key: ref.key });
+			logger$1.info("user-cache save skipped (immutable key exists)", { key: ref.key });
 			return { skip: true };
 		}
 		const tempKey = `${prefix}.tmp-${randomUUID()}${TAR_SUFFIX}`;
@@ -921,7 +928,7 @@ var UserCache = class {
 		await this.storage.initMeta(final);
 		await this.storage.put(`${final}.hash`, ref.tarHash);
 		await this.storage.put(`${final}.size`, String(ref.sizeBytes));
-		logger.info("user-cache entry committed", {
+		logger$1.info("user-cache entry committed", {
 			key: ref.key,
 			sizeBytes: ref.sizeBytes
 		});
@@ -964,7 +971,7 @@ var UserCache = class {
 			await this.storage.delete(`${key}.hash`);
 			await this.storage.delete(`${key}.size`);
 			total -= size;
-			logger.info("user-cache eviction (org over quota)", {
+			logger$1.info("user-cache eviction (org over quota)", {
 				org: ref.org,
 				key,
 				freedBytes: size
@@ -996,14 +1003,24 @@ var PeerCredentialStore = class {
 		this.db = db;
 	}
 	/**
-	* Save a new peer credential.
+	* Save a new peer credential, revoking any prior active credential for the
+	* same instanceId (the `peer_credentials_active_uniq` partial unique index
+	* permits exactly one active credential per instanceId).
+	*
+	* Returns `{ revokedCount }` — how many previously-active credentials this
+	* save revoked. Because a coordinator's peer-clients share one
+	* identity-scoped credential, a `revokedCount > 0` here means every sibling
+	* peer-client of `instanceId` that was authenticating with the old
+	* credential is now invalidated and will be rejected on its next proof. The
+	* caller logs this so a revoke that cascades sibling rejections is visible in
+	* the orchestrator logs.
 	*/
 	async save(opts) {
 		const expiryDays = opts.expiryDays ?? DEFAULT_EXPIRY_DAYS;
 		const expiresAt = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1e3);
 		const runOnce = async () => {
-			await this.db.transaction().execute(async (trx) => {
-				await trx.updateTable("peer_credentials").set({ revoked_at: /* @__PURE__ */ new Date() }).where("instance_id", "=", opts.instanceId).where("revoked_at", "is", null).execute();
+			return this.db.transaction().execute(async (trx) => {
+				const revokeResult = await trx.updateTable("peer_credentials").set({ revoked_at: /* @__PURE__ */ new Date() }).where("instance_id", "=", opts.instanceId).where("revoked_at", "is", null).executeTakeFirst();
 				await trx.insertInto("peer_credentials").values({
 					instance_id: opts.instanceId,
 					credential_hash: opts.credentialHash,
@@ -1012,15 +1029,13 @@ var PeerCredentialStore = class {
 					source_token_hash: opts.sourceTokenHash ?? null,
 					expires_at: expiresAt
 				}).execute();
+				return Number(revokeResult?.numUpdatedRows ?? 0n);
 			});
 		};
 		try {
-			await runOnce();
+			return { revokedCount: await runOnce() };
 		} catch (err) {
-			if (err instanceof Error && "code" in err && err.code === "23505") {
-				await runOnce();
-				return;
-			}
+			if (err instanceof Error && "code" in err && err.code === "23505") return { revokedCount: await runOnce() };
 			throw err;
 		}
 	}
@@ -1087,6 +1102,38 @@ function mapRow(row) {
 	};
 }
 /**
+* Write credential data to a JSON file with restrictive permissions.
+*
+* Creates the parent directory (e.g., ~/.kici/) with 0700 if it doesn't exist.
+* The credential file is written with 0600 permissions (owner read/write only).
+*
+* @param filePath - Absolute path to the credential file
+* @param data - Credential data to persist
+*/
+async function writeCredentialFile(filePath, data) {
+	await mkdir(dirname(filePath), {
+		recursive: true,
+		mode: 448
+	});
+	await writeFile(filePath, JSON.stringify(data, null, 2) + "\n", { mode: 384 });
+	await chmod(filePath, 384);
+}
+/**
+* Read credential data from a JSON file.
+*
+* @param filePath - Absolute path to the credential file
+* @returns Parsed credential data, or null if the file doesn't exist
+*/
+async function readCredentialFile(filePath) {
+	try {
+		const content = await readFile(filePath, "utf-8");
+		return JSON.parse(content);
+	} catch (err) {
+		if (err.code === "ENOENT") return null;
+		throw err;
+	}
+}
+/**
 * Construct a PeerCredentialStore bound to a Postgres URL, returning the
 * store plus a disposer that closes the underlying pool. Lets tests
 * exercise the real Kysely-backed store without importing pg/kysely.
@@ -1108,6 +1155,1113 @@ async function createPeerCredentialStoreFromUrl(databaseUrl, opts) {
 	};
 }
 //#endregion
-export { DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, DepCache, PeerCredentialStore, S3CacheStorage, SourceCache, UserCache, createCacheStorage, createPeerCredentialStoreFromUrl };
+//#region src/cluster/peer-auth-coordinator.ts
+/**
+* Per-orchestrator coordinator that owns the shared peer credential file.
+*
+* A single orchestrator runs N peer-clients (one per cluster peer) that all
+* share one identity-scoped credential file. Left uncoordinated, a reconnect
+* storm makes each sibling independently token-join (each join revokes the
+* prior credential, invalidating the others) and delete the shared file on any
+* rejection — a credential revocation cascade. This coordinator serializes all
+* file access through one in-process mutex so only one peer-client token-joins
+* per storm, and it never deletes a credential file a sibling has refreshed.
+*/
+const logger = createLogger({ prefix: "peer-auth-coordinator" });
+/** How long a waiting peer-client awaits an in-flight sibling token-join. */
+const DEFAULT_JOIN_WAIT_TIMEOUT_MS = 1e4;
+/** Max read→await→re-read cycles before a waiter gives up and joins/aborts. */
+const MAX_DECIDE_ITERATIONS = 3;
+function deferred() {
+	let resolve;
+	return {
+		promise: new Promise((res) => {
+			resolve = res;
+		}),
+		resolve
+	};
+}
+var PeerAuthCoordinator = class {
+	credentialFile;
+	instanceId;
+	joinToken;
+	joinWaitTimeoutMs;
+	/** Promise-chain mutex tail; every file op awaits the prior one. */
+	lock = Promise.resolve();
+	/** Set while one peer-client is mid token-join; siblings await it. */
+	inFlightJoin = null;
+	constructor(opts) {
+		this.credentialFile = opts.credentialFile;
+		this.instanceId = opts.instanceId;
+		this.joinToken = opts.joinToken;
+		this.joinWaitTimeoutMs = opts.joinWaitTimeoutMs ?? DEFAULT_JOIN_WAIT_TIMEOUT_MS;
+	}
+	/** Run `fn` exclusively against the credential file. */
+	async withLock(fn) {
+		const run = this.lock.then(fn, fn);
+		this.lock = run.then(() => void 0, () => void 0);
+		return run;
+	}
+	async readValidCredential() {
+		const cred = await readCredentialFile(this.credentialFile);
+		return cred && cred.instanceId === this.instanceId ? cred : null;
+	}
+	async decideAuth() {
+		for (let i = 0; i < MAX_DECIDE_ITERATIONS; i++) {
+			const decision = await this.withLock(async () => {
+				const cred = await this.readValidCredential();
+				if (cred) return {
+					mode: "credential",
+					credential: cred
+				};
+				if (this.inFlightJoin) return "await-join";
+				if (this.joinToken) {
+					const join = deferred();
+					this.inFlightJoin = join;
+					return {
+						mode: "token-join",
+						token: this.joinToken,
+						complete: this.makeComplete(join)
+					};
+				}
+				return { mode: "no-auth" };
+			});
+			if (decision !== "await-join") return decision;
+			await this.awaitInFlightJoin();
+		}
+		if (this.joinToken) {
+			const join = deferred();
+			this.inFlightJoin = join;
+			return {
+				mode: "token-join",
+				token: this.joinToken,
+				complete: this.makeComplete(join)
+			};
+		}
+		return { mode: "no-auth" };
+	}
+	makeComplete(join) {
+		return (issued) => {
+			this.withLock(async () => {
+				if (issued) await writeCredentialFile(this.credentialFile, issued);
+				if (this.inFlightJoin === join) this.inFlightJoin = null;
+				join.resolve(issued);
+			});
+		};
+	}
+	async awaitInFlightJoin() {
+		const join = this.inFlightJoin;
+		if (!join) return;
+		let timer;
+		const timeout = new Promise((res) => {
+			timer = setTimeout(() => {
+				if (this.inFlightJoin === join) this.inFlightJoin = null;
+				logger.warn("In-flight peer token-join timed out; waiter will retry", { instanceId: this.instanceId });
+				res();
+			}, this.joinWaitTimeoutMs);
+		});
+		await Promise.race([join.promise.then(() => void 0), timeout]);
+		if (timer) clearTimeout(timer);
+	}
+	async reportRejection(provedCredential, reason) {
+		return this.withLock(async () => {
+			const cred = await this.readValidCredential();
+			if (cred && cred.credential !== provedCredential) {
+				logger.info("Credential refreshed by sibling; retrying credential auth", {
+					instanceId: this.instanceId,
+					reason
+				});
+				return "retry-credential";
+			}
+			try {
+				await unlink(this.credentialFile);
+				logger.warn("Deleted stale credential file after server rejection", {
+					instanceId: this.instanceId,
+					reason
+				});
+			} catch (err) {
+				if (err.code !== "ENOENT") logger.warn("Failed to delete stale credential file", {
+					instanceId: this.instanceId,
+					path: this.credentialFile
+				});
+			}
+			return "rejoin";
+		});
+	}
+};
+//#endregion
+//#region src/cluster/join-token.ts
+/**
+* Join token manager for zero-knowledge cluster bootstrap.
+*
+* Token format: kici_join_v1.<base64url(routing_json)>.<random_256bit_hex>
+* - Routing JSON: { orgId, routingKey, expiry } (cleartext for Platform relay routing)
+* - Secret: 32 random bytes as hex (used for key derivation)
+*
+* Key derivation:
+* - encryption_key = HKDF-SHA256(secret, salt="kici-join-encrypt", info="v1", length=32)
+* - validation_hash = SHA-256(secret) (stored in DB for lookup)
+*
+* Config bundle encryption: AES-256-GCM with random 12-byte IV.
+* Wire format: <12-byte IV><16-byte auth tag><ciphertext>
+*/
+const joinTokenLogger = createLogger({ prefix: "join-token" });
+const TOKEN_PREFIX = "kici_join_v1";
+const DEFAULT_EXPIRY_MS = 36e5;
+const TOKEN_ALREADY_USED_MESSAGE = "Join token has already been used. Generate a new token with: kici admin create-join-token";
+var JoinTokenManager = class {
+	deps;
+	constructor(deps) {
+		this.deps = deps;
+	}
+	/**
+	* Create a new join token.
+	* Returns the full token string (only available at creation time).
+	*/
+	async createToken(opts) {
+		const expiryMs = opts.expiryMs ?? DEFAULT_EXPIRY_MS;
+		const expiry = Date.now() + expiryMs;
+		const role = opts.role ?? "coordinator";
+		const routing = {
+			orgId: opts.orgId,
+			routingKey: opts.routingKey,
+			expiry,
+			role
+		};
+		const secret = randomBytes(32);
+		const token = `${TOKEN_PREFIX}.${Buffer.from(JSON.stringify(routing)).toString("base64url")}.${secret.toString("hex")}`;
+		const { validationHash } = deriveKeys(secret);
+		await this.deps.db.insertInto("join_tokens").values({
+			id: randomUUID(),
+			token_hash: validationHash,
+			routing_info: JSON.stringify(routing),
+			role,
+			created_by: opts.createdBy,
+			expires_at: new Date(expiry)
+		}).execute();
+		joinTokenLogger.info("Created join token", {
+			orgId: opts.orgId,
+			routingKey: opts.routingKey
+		});
+		return token;
+	}
+	/**
+	* Atomically validate and consume a token in one DB round-trip.
+	*
+	* Single UPDATE with `WHERE token_hash = ? AND consumed_at IS NULL AND
+	* expires_at > NOW()` — only one caller can win the claim across a
+	* shared-DB multi-coordinator mesh. The winner gets `{ routing, keys }`;
+	* every other concurrent caller gets `TOKEN_ALREADY_USED_MESSAGE` and is
+	* expected to fall into the idempotent recovery branch in
+	* `peer-handler.ts` (which serialises credential issuance via the
+	* `peer_credentials_active_uniq` partial unique index).
+	*
+	* On a 0-row claim, a follow-up SELECT disambiguates not-found / expired
+	* / already-used / reusable-by-same-instance so callers can branch on the
+	* specific reason — the recovery path in peer-handler.ts keys on the
+	* "already used" string specifically. The follow-up only fires on the
+	* unhappy path.
+	*
+	* Self-healing reuse: a join token is re-consumable by the same joining
+	* peer (`peerInstanceId`) until its `expires_at`. A peer that lost its
+	* credential (transient outage / deleted credential file) re-presents the
+	* still-valid join token already in its env; the coordinator accepts the
+	* reuse and issues a fresh credential — no operator action, no cluster
+	* redeploy. Reuse is bounded by BOTH `expires_at` AND the consuming
+	* instanceId, so it never widens a leaked token's usefulness beyond the
+	* instance that first consumed it.
+	*/
+	async validateAndConsumeToken(token, consumedBy, peerInstanceId) {
+		const parsed = parseToken(token);
+		const keys = deriveKeys(Buffer.from(parsed.secretHex, "hex"));
+		const updateResult = await this.deps.db.updateTable("join_tokens").set({
+			consumed_at: /* @__PURE__ */ new Date(),
+			consumed_by: consumedBy,
+			consumed_by_instance: peerInstanceId
+		}).where("token_hash", "=", keys.validationHash).where("consumed_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).executeTakeFirst();
+		if (Number(updateResult?.numUpdatedRows ?? 0n) > 0) {
+			joinTokenLogger.info("Consumed join token", {
+				consumedBy,
+				peerInstanceId
+			});
+			return {
+				routing: parsed.routing,
+				keys
+			};
+		}
+		const row = await this.deps.db.selectFrom("join_tokens").selectAll().where("token_hash", "=", keys.validationHash).executeTakeFirst();
+		if (!row) throw new Error("Invalid join token");
+		if (new Date(row.expires_at).getTime() <= Date.now()) throw new Error("Join token has expired. Generate a new token with: kici admin create-join-token");
+		if (row.consumed_at) {
+			if (row.consumed_by_instance === peerInstanceId) {
+				joinTokenLogger.info("Re-validated join token for returning instance", {
+					consumedBy,
+					peerInstanceId
+				});
+				return {
+					routing: parsed.routing,
+					keys
+				};
+			}
+			throw new Error(TOKEN_ALREADY_USED_MESSAGE);
+		}
+		throw new Error("Invalid join token");
+	}
+};
+/**
+* Build a JoinTokenManager backed by its own connection pool to the given
+* orchestrator database URL. Mirrors `createPeerCredentialStoreFromUrl`;
+* consumed by E2E tests that need to exercise token validation/reuse against
+* the real cluster DB.
+*/
+function createJoinTokenManagerFromUrl(databaseUrl, opts) {
+	const db = new Kysely({ dialect: new PostgresDialect({ pool: new pg.Pool({
+		connectionString: databaseUrl,
+		max: opts?.maxConnections ?? 3
+	}) }) });
+	return {
+		manager: new JoinTokenManager({ db }),
+		dispose: async () => {
+			await db.destroy();
+		}
+	};
+}
+/**
+* Parse a join token string into routing info and secret hex.
+*/
+function parseToken(token) {
+	const parts = token.split(".");
+	if (parts.length !== 3 || parts[0] !== TOKEN_PREFIX) throw new Error(`Invalid join token format. Expected: ${TOKEN_PREFIX}.<routing>.<secret>`);
+	const routingJson = Buffer.from(parts[1], "base64url").toString("utf-8");
+	const routing = JSON.parse(routingJson);
+	if (!routing.orgId || !routing.routingKey || !routing.expiry) throw new Error("Invalid join token routing data");
+	return {
+		routing,
+		secretHex: parts[2]
+	};
+}
+/**
+* Derive encryption key and validation hash from a token secret.
+* - encryptionKey: HKDF-SHA256 with salt="kici-join-encrypt", info="v1"
+* - validationHash: SHA-256 of secret (stored in DB for lookup)
+*/
+function deriveKeys(secret) {
+	const validationHash = sha256(secret);
+	const derived = hkdfSync("sha256", secret, Buffer.from("kici-join-encrypt"), Buffer.from("v1"), 32);
+	return {
+		encryptionKey: Buffer.from(derived),
+		validationHash
+	};
+}
+//#endregion
+//#region src/cli/api-client.ts
+/**
+* HTTP client wrapper for the kici-admin CLI.
+*
+* Communicates with the orchestrator admin API via Bearer token authentication.
+* All methods are thin wrappers around fetch() that handle JSON serialization,
+* error formatting, and URL construction.
+*/
+var AdminApiClient = class {
+	baseUrl;
+	token;
+	constructor(baseUrl, token) {
+		this.baseUrl = baseUrl;
+		this.token = token;
+	}
+	/**
+	* Make an authenticated HTTP request to the admin API.
+	*/
+	async request(method, path, body) {
+		const url = `${this.baseUrl}${path}`;
+		const headers = {
+			Authorization: `Bearer ${this.token}`,
+			"Content-Type": "application/json"
+		};
+		const res = await fetch(url, {
+			method,
+			headers,
+			body: body !== void 0 ? JSON.stringify(body) : void 0
+		});
+		if (!res.ok) {
+			const text = await res.text();
+			let errorBody;
+			try {
+				errorBody = JSON.parse(text).error ?? text;
+			} catch {
+				errorBody = text;
+			}
+			throw new Error(`HTTP ${res.status}: ${errorBody}`);
+		}
+		if (res.status === 204) return;
+		return await res.json();
+	}
+	/**
+	* Public GET request returning parsed JSON.
+	*/
+	async get(path) {
+		return this.request("GET", path);
+	}
+	/**
+	* Public POST request returning parsed JSON.
+	*/
+	async post(path, body) {
+		return this.request("POST", path, body);
+	}
+	/**
+	* Public PATCH request returning parsed JSON.
+	*/
+	async patch(path, body) {
+		return this.request("PATCH", path, body);
+	}
+	/**
+	* Public PUT request returning parsed JSON.
+	*/
+	async put(path, body) {
+		return this.request("PUT", path, body);
+	}
+	/**
+	* Public DELETE request returning parsed JSON.
+	*/
+	async delete(path) {
+		return this.request("DELETE", path);
+	}
+	/**
+	* Public GET request returning raw response text.
+	*/
+	async getText(path) {
+		const url = `${this.baseUrl}${path}`;
+		const res = await fetch(url, {
+			method: "GET",
+			headers: { Authorization: `Bearer ${this.token}` }
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+		return res.text();
+	}
+	/** Enumerate the cluster topology for `debug-bundle --fleet --list` / `--pick`. */
+	async getFleetTopology() {
+		return this.get("/admin/fleet-topology");
+	}
+	/**
+	* Drive the fleet fan-out and write the assembled ZIP to `outPath`. The
+	* response is an octet-stream, so it is read as bytes rather than parsed JSON.
+	*/
+	async downloadFleetBundle(body, outPath) {
+		const res = await fetch(`${this.baseUrl}/admin/fleet-bundle`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.token}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(body)
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+		const buf = Buffer.from(await res.arrayBuffer());
+		fs.writeFileSync(outPath, buf);
+	}
+	async listScopes(orgId) {
+		return this.request("GET", `/api/v1/admin/secrets/scopes?orgId=${encodeURIComponent(orgId)}`);
+	}
+	async listKeys(orgId, scope) {
+		const params = new URLSearchParams({
+			orgId,
+			scope
+		});
+		return this.request("GET", `/api/v1/admin/secrets/keys?${params}`);
+	}
+	async setSecret(orgId, scope, key, value) {
+		return this.request("PUT", `/api/v1/admin/secrets/${encodeURIComponent(orgId)}/${encodeURIComponent(scope)}/${encodeURIComponent(key)}`, { value });
+	}
+	async deleteSecret(orgId, scope, key) {
+		return this.request("DELETE", `/api/v1/admin/secrets/${encodeURIComponent(orgId)}/${encodeURIComponent(scope)}/${encodeURIComponent(key)}`);
+	}
+	async listVariables(orgId, environment) {
+		const params = new URLSearchParams({ orgId });
+		return this.request("GET", `/api/v1/admin/environments/${encodeURIComponent(environment)}/variables?${params}`);
+	}
+	async setVariable(orgId, environment, key, value, locked) {
+		const params = new URLSearchParams({ orgId });
+		return this.request("PUT", `/api/v1/admin/environments/${encodeURIComponent(environment)}/variables/${encodeURIComponent(key)}?${params}`, {
+			value,
+			locked
+		});
+	}
+	async deleteVariable(orgId, environment, key) {
+		const params = new URLSearchParams({ orgId });
+		return this.request("DELETE", `/api/v1/admin/environments/${encodeURIComponent(environment)}/variables/${encodeURIComponent(key)}?${params}`);
+	}
+	async rotateKey() {
+		return this.request("POST", "/api/v1/admin/rotate-key");
+	}
+	async createGenericSource(data) {
+		return this.request("POST", "/api/v1/admin/generic-sources", data);
+	}
+	async listGenericSources(orgId, includeDeleted) {
+		const params = new URLSearchParams({ orgId });
+		if (includeDeleted) params.set("includeDeleted", "true");
+		return this.request("GET", `/api/v1/admin/generic-sources?${params}`);
+	}
+	async getGenericSource(id) {
+		return this.request("GET", `/api/v1/admin/generic-sources/${encodeURIComponent(id)}`);
+	}
+	async updateGenericSource(id, data) {
+		return this.request("PATCH", `/api/v1/admin/generic-sources/${encodeURIComponent(id)}`, data);
+	}
+	async deleteGenericSource(id, hard) {
+		const qs = hard ? "?hard=true" : "";
+		return this.request("DELETE", `/api/v1/admin/generic-sources/${encodeURIComponent(id)}${qs}`);
+	}
+	async enableGenericSource(id) {
+		return this.request("POST", `/api/v1/admin/generic-sources/${encodeURIComponent(id)}/enable`);
+	}
+	async disableGenericSource(id) {
+		return this.request("POST", `/api/v1/admin/generic-sources/${encodeURIComponent(id)}/disable`);
+	}
+	async queryAudit(opts) {
+		const params = new URLSearchParams();
+		if (opts?.contextName) params.set("contextName", opts.contextName);
+		if (opts?.routingKey) params.set("routingKey", opts.routingKey);
+		if (opts?.action) params.set("action", opts.action);
+		if (opts?.from) params.set("from", opts.from);
+		if (opts?.to) params.set("to", opts.to);
+		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+		if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+		if (opts?.includeArchived) params.set("includeArchived", "true");
+		const qs = params.toString();
+		return (await this.request("GET", `/api/v1/admin/audit${qs ? `?${qs}` : ""}`)).entries;
+	}
+	async createToken(data) {
+		return this.request("POST", "/api/v1/admin/tokens", data);
+	}
+	async listTokens() {
+		return (await this.request("GET", "/api/v1/admin/tokens")).tokens;
+	}
+	async revokeToken(id) {
+		return this.request("DELETE", `/api/v1/admin/tokens/${encodeURIComponent(id)}`);
+	}
+	async createAgentToken(opts) {
+		return this.request("POST", "/api/v1/agent-tokens", opts);
+	}
+	async listAgentTokens(opts) {
+		const qs = opts?.type ? `?type=${encodeURIComponent(opts.type)}` : "";
+		return this.request("GET", `/api/v1/agent-tokens${qs}`);
+	}
+	/**
+	* Revoke an agent token.
+	*
+	* The orchestrator both flips `agent_tokens.revoked_at` AND
+	* synchronously closes every in-flight agent WS authenticated by
+	* this token. The returned `kicked` count is the number
+	* of WS connections that were closed on the wire — surface it to
+	* the operator so they know the revocation actually propagated.
+	*/
+	async revokeAgentToken(id) {
+		return this.request("DELETE", `/api/v1/agent-tokens/${encodeURIComponent(id)}`);
+	}
+	async configSeed(config, description) {
+		return this.request("POST", "/admin/config/seed", {
+			config,
+			description
+		});
+	}
+	async configGet(path) {
+		const qs = path ? `?path=${encodeURIComponent(path)}` : "";
+		return this.request("GET", `/admin/config${qs}`);
+	}
+	async configSet(path, value, description) {
+		return this.request("PUT", "/admin/config", {
+			path,
+			value,
+			description
+		});
+	}
+	async configDelete(path, description) {
+		return this.request("DELETE", "/admin/config", {
+			path,
+			description
+		});
+	}
+	async configExport() {
+		return this.request("GET", "/admin/config/export");
+	}
+	async configValidate(config, type) {
+		return this.request("POST", "/admin/config/validate", {
+			config,
+			type
+		});
+	}
+	async configDiff() {
+		return this.request("GET", "/admin/config/diff");
+	}
+	async configHistory(limit) {
+		const qs = limit !== void 0 ? `?limit=${limit}` : "";
+		return this.request("GET", `/admin/config/history${qs}`);
+	}
+	async configRollback(version) {
+		return this.request("POST", "/admin/config/rollback", { version });
+	}
+	async configReload(opts) {
+		return this.request("POST", "/admin/config/reload", opts);
+	}
+	async createApiKey(opts) {
+		return this.request("POST", "/api/v1/api-keys", opts);
+	}
+	async addRoutingKeyPermission(keyId, pattern) {
+		return this.request("POST", `/api/v1/api-keys/${encodeURIComponent(keyId)}/routing-permissions`, { pattern });
+	}
+	async addBackend(params) {
+		return this.request("POST", "/api/v1/admin/backends", params);
+	}
+	async removeBackend(name) {
+		return this.request("DELETE", `/api/v1/admin/backends/${encodeURIComponent(name)}`);
+	}
+	async listBackends() {
+		return this.request("GET", "/api/v1/admin/backends");
+	}
+	async getBackend(name) {
+		return this.request("GET", `/api/v1/admin/backends/${encodeURIComponent(name)}`);
+	}
+	async testBackend(params) {
+		return this.request("POST", "/api/v1/admin/backends/test", params);
+	}
+	async testNamedBackend(name) {
+		return this.request("POST", `/api/v1/admin/backends/${encodeURIComponent(name)}/test`);
+	}
+	async syncBackend(name) {
+		return this.request("POST", `/api/v1/admin/backends/${encodeURIComponent(name)}/sync`);
+	}
+	async syncAllBackends() {
+		return this.request("POST", "/api/v1/admin/backends/sync");
+	}
+	/**
+	* List execution runs. `status` accepts either a single status or a
+	* comma-separated list (e.g. `success,failed`). `since` is an ISO-8601
+	* timestamp; only runs with `created_at` strictly later than this value
+	* are returned.
+	*/
+	async listRuns(opts) {
+		const params = new URLSearchParams();
+		if (opts?.status) params.set("status", opts.status);
+		if (opts?.workflowName) params.set("workflowName", opts.workflowName);
+		if (opts?.repo) params.set("repo", opts.repo);
+		if (opts?.since) params.set("since", opts.since);
+		if (opts?.limit) params.set("limit", String(opts.limit));
+		if (opts?.offset) params.set("offset", String(opts.offset));
+		const qs = params.toString();
+		return this.request("GET", `/api/v1/admin/runs${qs ? `?${qs}` : ""}`);
+	}
+	/**
+	* Count matching runs without returning the row list. Wraps the list
+	* endpoint with `?count=true`, which skips the row query server-side.
+	*/
+	async countRuns(opts) {
+		const params = new URLSearchParams();
+		params.set("count", "true");
+		if (opts?.status) params.set("status", opts.status);
+		if (opts?.workflowName) params.set("workflowName", opts.workflowName);
+		if (opts?.repo) params.set("repo", opts.repo);
+		if (opts?.since) params.set("since", opts.since);
+		return this.request("GET", `/api/v1/admin/runs?${params.toString()}`);
+	}
+	/**
+	* Fetch the run header (no jobs, no steps). Use `getRunJobs` for the
+	* jobs sub-resource.
+	*/
+	async getRun(runId) {
+		return this.request("GET", `/api/v1/admin/runs/${encodeURIComponent(runId)}`);
+	}
+	/**
+	* Fetch the jobs list for a run. When `includeSteps: true`, each job
+	* entry embeds a `steps[]` array.
+	*/
+	async getRunJobs(runId, opts) {
+		const qs = opts?.includeSteps ? "?includeSteps=true" : "";
+		return this.request("GET", `/api/v1/admin/runs/${encodeURIComponent(runId)}/jobs${qs}`);
+	}
+	/**
+	* Fetch the scrub status of the run's ephemeral key. Never returns the
+	* key material itself — only `{ exists, createdAt }`.
+	*/
+	async getRunEphemeralKey(runId) {
+		return this.request("GET", `/api/v1/admin/runs/${encodeURIComponent(runId)}/ephemeral-key`);
+	}
+	/**
+	* List secret outputs for a run. Values are masked unless `reveal: true`
+	* is passed AND the calling token has the `secret.reveal` permission.
+	* Every reveal call writes a `secret-outputs.reveal` row to the
+	* secret_audit_log table.
+	*/
+	async getRunSecretOutputs(runId, opts) {
+		const params = new URLSearchParams();
+		if (opts?.outputKey) params.set("outputKey", opts.outputKey);
+		if (opts?.reveal) params.set("reveal", "true");
+		const qs = params.toString();
+		return this.request("GET", `/api/v1/admin/runs/${encodeURIComponent(runId)}/secret-outputs${qs ? `?${qs}` : ""}`);
+	}
+	async listEventLog(opts) {
+		const params = new URLSearchParams();
+		if (opts?.orgId) params.set("orgId", opts.orgId);
+		if (opts?.routingKey) params.set("routingKey", opts.routingKey);
+		if (opts?.event) params.set("event", opts.event);
+		if (opts?.action) params.set("action", opts.action);
+		if (opts?.status) params.set("status", opts.status);
+		if (opts?.from) params.set("from", opts.from);
+		if (opts?.to) params.set("to", opts.to);
+		if (opts?.deliveryId) params.set("deliveryId", opts.deliveryId);
+		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+		if (opts?.offset !== void 0) params.set("offset", String(opts.offset));
+		if (opts?.includeArchived) params.set("includeArchived", "true");
+		const qs = params.toString();
+		return this.request("GET", `/api/v1/admin/event-log${qs ? `?${qs}` : ""}`);
+	}
+	async getEventLog(deliveryId, opts) {
+		const params = new URLSearchParams({ orgId: opts.orgId });
+		if (opts.includePayload) params.set("includePayload", "true");
+		if (opts.routingKey) params.set("routingKey", opts.routingKey);
+		return this.request("GET", `/api/v1/admin/event-log/${encodeURIComponent(deliveryId)}?${params}`);
+	}
+	async listAccessLog(opts) {
+		const params = new URLSearchParams();
+		if (opts?.orgId) params.set("orgId", opts.orgId);
+		if (opts?.actorType) params.set("actorType", opts.actorType);
+		if (opts?.actorId) params.set("actorId", opts.actorId);
+		if (opts?.action) params.set("action", opts.action);
+		if (opts?.source) params.set("source", opts.source);
+		if (opts?.outcome) params.set("outcome", opts.outcome);
+		if (opts?.targetType) params.set("targetType", opts.targetType);
+		if (opts?.targetId) params.set("targetId", opts.targetId);
+		if (opts?.from) params.set("from", opts.from);
+		if (opts?.to) params.set("to", opts.to);
+		if (opts?.q) params.set("q", opts.q);
+		if (opts?.limit !== void 0) params.set("limit", String(opts.limit));
+		if (opts?.cursor) params.set("cursor", opts.cursor);
+		const qs = params.toString();
+		return this.request("GET", `/api/v1/admin/access-log${qs ? `?${qs}` : ""}`);
+	}
+	async getAccessLogEntry(id, opts) {
+		const params = new URLSearchParams();
+		if (opts?.orgId) params.set("orgId", opts.orgId);
+		const qs = params.toString();
+		return this.request("GET", `/api/v1/admin/access-log/${encodeURIComponent(id)}${qs ? `?${qs}` : ""}`);
+	}
+	async diagnose() {
+		return this.request("GET", "/admin/diagnose");
+	}
+};
+//#endregion
+//#region src/providers/github/auth.ts
+/**
+* GitHub clone token provider and authentication utilities.
+*
+* Implements the CloneTokenProvider interface from @kici-dev/engine for GitHub.
+* Uses GitHub App installation tokens for repository access.
+*/
+/**
+* Create an Octokit instance authenticated as a GitHub App installation.
+*
+* Uses @octokit/auth-app to handle:
+* - JWT generation for app-level authentication
+* - Installation token creation and automatic refresh
+*
+* Each call creates a new Octokit instance scoped to the specific installation.
+* The auth-app strategy handles token caching internally per Octokit instance.
+*
+* @param config - GitHub App credentials (appId + privateKey)
+* @param installationId - GitHub App installation ID for the target account/org
+* @returns Octokit instance with auto-refreshing installation tokens
+*/
+function createInstallationOctokit(config, installationId) {
+	return new Octokit({
+		authStrategy: createAppAuth,
+		auth: {
+			appId: config.appId,
+			privateKey: config.privateKey,
+			installationId
+		}
+	});
+}
+//#endregion
+//#region src/providers/github/manifest.ts
+/**
+* GitHub App Manifest flow helpers. The manifest encodes KiCI's exact
+* permissions + events + webhook config so the operator never picks them by
+* hand — GitHub creates a correctly-configured App from this object in one
+* click. See docs.github.com "Registering a GitHub App from a manifest".
+*
+* The webhook secret is NOT part of the manifest: GitHub generates it during
+* registration and returns it on the conversion response, so both GitHub and
+* the Platform end up sharing the same secret with zero operator effort.
+*/
+/**
+* Validate a self-hosted webhook URL supplied via `source add github
+* --webhook-url`. Must be a well-formed absolute `https://` URL. Returns the URL
+* verbatim on success; throws a clear error otherwise. The validated URL is
+* baked into `manifest.hook_attributes.url` as-is — KiCI adds no ingress and
+* does not receive events at it; the operator owns delivery.
+*/
+function validateWebhookUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`--webhook-url must be a valid absolute URL: ${value}`);
+	}
+	if (url.protocol !== "https:") throw new Error(`--webhook-url must be an https:// URL (got ${url.protocol}//…)`);
+	return value;
+}
+function buildGithubAppManifest(input) {
+	return {
+		name: input.name,
+		url: "https://kici.dev",
+		hook_attributes: {
+			url: input.webhookUrl,
+			active: true
+		},
+		redirect_url: input.redirectUrl,
+		...input.setupUrl ? { setup_url: input.setupUrl } : {},
+		public: false,
+		default_permissions: {
+			contents: "read",
+			metadata: "read",
+			pull_requests: "read",
+			checks: "write",
+			members: "read"
+		},
+		default_events: [
+			"push",
+			"pull_request",
+			"check_run",
+			"check_suite"
+		]
+	};
+}
+/**
+* Exchange the short-lived manifest `code` for the App's id, private key, and
+* webhook secret. Runs server-to-server directly against GitHub — the private
+* key never transits the Platform.
+*/
+async function convertManifestCode(code, deps = {}) {
+	const { data } = await (deps.octokit ?? new Octokit()).request("POST /app-manifests/{code}/conversions", { code });
+	const d = data;
+	if (!d.webhook_secret) throw new Error("GitHub returned no webhook secret for the new App — cannot verify inbound events. Re-run the setup, or configure a webhook secret manually with source update.");
+	return {
+		appId: String(d.id),
+		slug: d.slug,
+		name: d.name,
+		privateKey: d.pem,
+		webhookSecret: d.webhook_secret,
+		clientId: d.client_id,
+		clientSecret: d.client_secret,
+		htmlUrl: d.html_url
+	};
+}
+function appOctokitFor(creds) {
+	return new Octokit({
+		authStrategy: createAppAuth,
+		auth: {
+			appId: creds.appId,
+			privateKey: creds.privateKey
+		}
+	});
+}
+/**
+* Poll GitHub (as the App, via a JWT) until at least one installation exists,
+* returning the first installation's id + account login. Throws on timeout.
+*/
+async function waitForInstallation(creds, opts) {
+	const now = opts.now ?? Date.now;
+	const octokit = opts.appOctokit ?? appOctokitFor(creds);
+	const deadline = now() + opts.timeoutMs;
+	for (;;) {
+		const { data } = await octokit.request("GET /app/installations", { per_page: 1 });
+		const installs = data;
+		if (Array.isArray(installs) && installs.length > 0) return {
+			installationId: installs[0].id,
+			accountLogin: installs[0].account?.login ?? ""
+		};
+		if (now() >= deadline) throw new Error("Timed out waiting for the GitHub App to be installed");
+		await new Promise((r) => setTimeout(r, opts.pollMs));
+	}
+}
+/**
+* Mint an installation token from the captured private key and confirm the App
+* can reach repos — proves the key works end-to-end (the same path the agent's
+* clone uses at runtime).
+*/
+async function verifyRepoAccess(creds, installationId, deps = {}) {
+	const { data } = await (deps.octokit ?? createInstallationOctokit(creds, installationId)).request("GET /installation/repositories", { per_page: 1 });
+	return { repoCount: data.total_count };
+}
+//#endregion
+//#region src/providers/github/manifest-form.ts
+/**
+* GitHub's create-from-manifest flow is an HTML form POST (the `manifest`
+* JSON cannot ride in a query string). These helpers render the auto-submitting
+* form and the headless code-display page. Pure string builders — no IO — so
+* both the CLI loopback server and the static marketing-site page can reuse the
+* same shapes.
+*/
+function escapeHtml(s) {
+	return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function manifestCreateUrl(githubOrg) {
+	return githubOrg ? `https://github.com/organizations/${githubOrg}/settings/apps/new` : "https://github.com/settings/apps/new";
+}
+function renderManifestFormHtml(opts) {
+	return `<!doctype html><html><head><meta charset="utf-8"><title>Create your KiCI GitHub App</title></head>
+<body>
+<p>Redirecting you to GitHub to create your KiCI GitHub App…</p>
+<form id="f" method="post" action="${escapeHtml(`${opts.createUrl}?state=${encodeURIComponent(opts.state)}`)}">
+  <input type="hidden" name="manifest" value="${escapeHtml(opts.manifestJson)}">
+  <noscript><button type="submit">Continue to GitHub</button></noscript>
+</form>
+<script>document.getElementById('f').submit();<\/script>
+</body></html>`;
+}
+function renderCodeDisplayHtml(code) {
+	return `<!doctype html><html><head><meta charset="utf-8"><title>KiCI — copy your setup code</title></head>
+<body>
+<p>App created. Copy this code back into the <code>kici-admin</code> prompt:</p>
+<pre id="c" style="font-size:1.2rem;padding:12px;border:1px solid #ccc">${escapeHtml(code)}</pre>
+<button onclick="navigator.clipboard.writeText(document.getElementById('c').textContent)">Copy</button>
+</body></html>`;
+}
+//#endregion
+//#region src/cli/loopback-callback.ts
+function startManifestLoopback(opts) {
+	return new Promise((resolveServer) => {
+		let outcome;
+		const waiters = [];
+		const resolveCode = (value) => {
+			if (outcome) return;
+			outcome = {
+				ok: true,
+				value
+			};
+			for (const w of waiters) w.resolve(value);
+		};
+		const rejectCode = (error) => {
+			if (outcome) return;
+			outcome = {
+				ok: false,
+				error
+			};
+			for (const w of waiters) w.reject(error);
+		};
+		const server = createServer((req, res) => {
+			const url = new URL(req.url ?? "/", "http://127.0.0.1");
+			if (url.pathname === "/cb") {
+				const code = url.searchParams.get("code") ?? "";
+				const state = url.searchParams.get("state") ?? "";
+				res.writeHead(200, { "content-type": "text/html" });
+				res.end(renderCodeDisplayHtml(code));
+				if (state !== opts.state) rejectCode(/* @__PURE__ */ new Error("OAuth state mismatch — aborting"));
+				else resolveCode({
+					code,
+					state
+				});
+				return;
+			}
+			res.writeHead(200, { "content-type": "text/html" });
+			res.end(renderManifestFormHtml({
+				createUrl: opts.createUrl,
+				state: opts.state,
+				manifestJson: opts.manifestJson
+			}));
+		});
+		server.on("clientError", () => {});
+		server.listen(0, "127.0.0.1", () => {
+			const base = `http://127.0.0.1:${server.address().port}`;
+			resolveServer({
+				redirectUrl: `${base}/cb`,
+				formUrl: `${base}/`,
+				waitForCode: (timeoutMs) => new Promise((resolve, reject) => {
+					if (outcome) {
+						outcome.ok ? resolve(outcome.value) : reject(outcome.error);
+						return;
+					}
+					const timer = setTimeout(() => reject(/* @__PURE__ */ new Error("Timed out waiting for GitHub callback")), timeoutMs);
+					waiters.push({
+						resolve: (v) => {
+							clearTimeout(timer);
+							resolve(v);
+						},
+						reject: (e) => {
+							clearTimeout(timer);
+							reject(e);
+						}
+					});
+				}),
+				close: () => server.close()
+			});
+		});
+	});
+}
+//#endregion
+//#region src/cli/open-browser.ts
+/**
+* Open a URL in the operator's default browser, best-effort. Used by the GitHub
+* App manifest setup flow to launch the create / install pages. Failure is
+* non-fatal — the caller always prints the URL too, so a headless host (or a
+* blocked launcher) just falls back to copy-paste.
+*
+* `KICI_BROWSER_CMD` overrides the launcher: `none` suppresses it entirely
+* (E2E / headless capture), any other value is run with `{url}` substituted —
+* mirroring the `kici login` convention.
+*/
+function openBrowserBestEffort(url) {
+	const override = process.env.KICI_BROWSER_CMD;
+	if (override === "none") return;
+	if (override) {
+		exec(override.replace("{url}", url), () => {});
+		return;
+	}
+	exec(platform() === "darwin" ? `open ${JSON.stringify(url)}` : platform() === "win32" ? `start "" ${JSON.stringify(url)}` : `xdg-open ${JSON.stringify(url)}`, () => {});
+}
+//#endregion
+//#region src/cli/commands/source-manifest.ts
+/**
+* `kici-admin source add github --manifest` — the one-click GitHub App setup
+* flow. Drives GitHub's App Manifest flow end-to-end: builds a pre-configured
+* manifest (KiCI's exact permissions/events/webhook URL), hands it to GitHub via
+* an auto-submitting form, catches the returned short-lived setup code over a
+* localhost loopback (or copy-paste in --no-browser mode), exchanges it for the
+* App's id + private key + webhook secret, then reuses the existing source
+* storage + Platform-registration path.
+*
+* The private-key-bearing conversion happens entirely here on the orchestrator
+* host — it never transits the Platform (sovereignty invariant).
+*/
+/** Static marketing-site page the CLI points at in headless paste-code mode. */
+const STATIC_CALLBACK_URL = "https://kici.dev/gh-manifest-callback";
+/** How long to wait for the operator to click "Create" on GitHub. */
+const CREATE_TIMEOUT_MS = 5 * 6e4;
+/** How long to wait for the operator to install the App on at least one repo. */
+const INSTALL_TIMEOUT_MS = 5 * 6e4;
+const INSTALL_POLL_MS = 3e3;
+function defaultReadLine(prompt) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	return new Promise((resolve) => {
+		rl.question(prompt, (answer) => {
+			rl.close();
+			resolve(answer.trim());
+		});
+	});
+}
+function defaultWriteRecoveryFile(appId, pem) {
+	const file = join(mkdtempSync(join(tmpdir(), "kici-gh-app-")), `app-${appId}.private-key.pem`);
+	writeFileSync(file, pem, { mode: 384 });
+	return file;
+}
+const realManifestSetupDeps = {
+	startLoopback: startManifestLoopback,
+	openBrowser: openBrowserBestEffort,
+	readLine: defaultReadLine,
+	convert: (code) => convertManifestCode(code),
+	waitForInstallation,
+	verifyRepoAccess,
+	writeRecoveryFile: defaultWriteRecoveryFile
+};
+/** Resolve the org-scoped webhook URL via the pre-flight route; abort if null. */
+async function resolveWebhookUrl(client) {
+	const pre = await client.get("/api/v1/admin/sources/github-webhook-url");
+	if (!pre.webhookUrl) throw new Error(`Cannot resolve the GitHub webhook URL${pre.webhookNote ? ` (${pre.webhookNote})` : ""}. The manifest flow needs it to configure the App. Ensure the orchestrator is connected to the Platform and has identified its org, then retry.`);
+	return pre.webhookUrl;
+}
+/**
+* Catch the short-lived setup code: over the loopback (browser mode) or by
+* printing the static-site URL and reading the pasted code (headless mode).
+*/
+async function captureCode(opts, deps, manifestJson, state, redirectUrl, createUrl, loopback) {
+	if (opts.noBrowser) {
+		const url = `${STATIC_CALLBACK_URL}#m=${Buffer.from(manifestJson, "utf-8").toString("base64url")}&state=${encodeURIComponent(state)}&createUrl=${encodeURIComponent(createUrl)}`;
+		console.log("Open this URL in a browser to create your App:");
+		console.log(`  ${url}`);
+		console.log("After clicking \"Create\", copy the setup code shown on the page.");
+		const code = await deps.readLine("Paste the setup code here: ");
+		if (!code) throw new Error("No setup code was provided");
+		return code;
+	}
+	console.log("→ Opening GitHub to create your App…");
+	await deps.openBrowser(loopback.formUrl);
+	console.log(`  (if your browser did not open, visit ${loopback.formUrl} )`);
+	const { code } = await loopback.waitForCode(CREATE_TIMEOUT_MS);
+	return code;
+}
+/** Store credentials + register; on failure, save the PEM so the App is not orphaned. */
+async function storeAndRegister(opts, client, deps, creds) {
+	try {
+		return await client.post("/api/v1/admin/sources", {
+			provider: "github",
+			name: creds.name,
+			slug: creds.slug,
+			appId: creds.appId,
+			privateKey: creds.privateKey,
+			webhookSecret: creds.webhookSecret
+		});
+	} catch (err) {
+		const file = deps.writeRecoveryFile(creds.appId, creds.privateKey);
+		console.error("");
+		console.error("⚠ The GitHub App was created but storing it on the orchestrator failed.");
+		console.error(`  App id: ${creds.appId}`);
+		console.error(`  Private key saved to: ${file}`);
+		console.error("  Recover with:");
+		console.error(`    kici-admin source add github --name "${opts.name}" --app-id ${creds.appId} --private-key @${file} --webhook-secret ${creds.webhookSecret}`);
+		throw err;
+	}
+}
+async function runGithubManifestSetup(opts, client, deps = realManifestSetupDeps) {
+	const webhookUrl = opts.webhookUrl ? validateWebhookUrl(opts.webhookUrl) : await resolveWebhookUrl(client);
+	const state = randomBytes(16).toString("hex");
+	const createUrl = manifestCreateUrl(opts.githubOrg);
+	const loopback = await deps.startLoopback({
+		state,
+		manifestJson: "{}",
+		createUrl
+	});
+	try {
+		const manifest = buildGithubAppManifest({
+			name: opts.name,
+			webhookUrl,
+			redirectUrl: opts.noBrowser ? STATIC_CALLBACK_URL : loopback.redirectUrl
+		});
+		const manifestJson = JSON.stringify(manifest);
+		loopback.close();
+		const lb = await deps.startLoopback({
+			state,
+			manifestJson,
+			createUrl
+		});
+		try {
+			const code = await captureCode(opts, deps, manifestJson, state, lb.redirectUrl, createUrl, lb);
+			const creds = await deps.convert(code);
+			console.log(`→ ✓ App created (id ${creds.appId}), credentials captured`);
+			const stored = await storeAndRegister(opts, client, deps, creds);
+			console.log(`→ ✓ Stored on orchestrator (encrypted), registered as ${stored.routingKey}`);
+			const installUrl = `https://github.com/apps/${creds.slug}/installations/new`;
+			console.log(`→ Install the App on your repos: ${installUrl}`);
+			if (!opts.noBrowser) await deps.openBrowser(installUrl);
+			const { installationId, accountLogin } = await deps.waitForInstallation(creds, {
+				timeoutMs: INSTALL_TIMEOUT_MS,
+				pollMs: INSTALL_POLL_MS
+			});
+			console.log(`→ ✓ Installation detected (account ${accountLogin})`);
+			const { repoCount } = await deps.verifyRepoAccess(creds, installationId);
+			console.log(`→ ✓ Credentials verified (${repoCount} repositories reachable)`);
+			console.log("");
+			console.log(`GitHub App "${opts.name}" is live.`);
+			console.log(`  Webhook: ${webhookUrl}`);
+		} finally {
+			lb.close();
+		}
+	} finally {
+		loopback.close();
+	}
+}
+//#endregion
+export { AdminApiClient, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, DepCache, JoinTokenManager, PeerAuthCoordinator, PeerCredentialStore, S3CacheStorage, SourceCache, UserCache, createCacheStorage, createJoinTokenManagerFromUrl, createPeerCredentialStoreFromUrl, runGithubManifestSetup };
 
 //# sourceMappingURL=index.js.map