@kici-dev/orchestrator 0.14.1 → 0.15.0

package/dist/index.js

@@ -6,12 +6,12 @@ import { createLogger, createS3Client, sha256, toErrorMessage } from "@kici-dev/
 import * as fs from "node:fs";
 import { mkdtempSync, promises, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { createHash, createHmac, hkdfSync, randomBytes, randomUUID } from "node:crypto";
+import { createHash, createHmac, 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 { DEFAULT_APPROVAL_EXPIRY_HOURS, DEFAULT_APPROVAL_EXPIRY_SECONDS, ForkPolicy, HoldScope, HoldType, OrchRole, TriggerSource, approvalExpiryHoursOf, approvalExpirySecondsOf, persistedHoldTypeSpellings } from "@kici-dev/engine";
 import { z } from "zod";
-import { DEFAULT_APPROVAL_EXPIRY_HOURS, DEFAULT_APPROVAL_EXPIRY_SECONDS, ForkPolicy, HoldScope, HoldType, TriggerSource, approvalExpiryHoursOf, approvalExpirySecondsOf, persistedHoldTypeSpellings } from "@kici-dev/engine";
 import { platform, tmpdir } from "node:os";
 import { createInterface } from "node:readline";
 import { Octokit } from "@octokit/rest";
@@ -1626,12 +1626,27 @@ createLogger({ prefix: "coordinator-credential" });
 * A coordinator without a join token also wires a `selfIssue` callback. When a
 * decision finds no credential and no token, the callback issues the
 * coordinator its own credential, once per storm, under the same mutex.
+*
+* A coordinator also wires `corroborateRejection`. Any dialled endpoint can
+* send a rejection, so before it deletes the file the coordinator asks its own
+* cluster database: a credential the database holds as valid, or a database it
+* cannot read, keeps the file.
 */
 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;
+/** What `reportRejection` did with the credential file. */
+let RejectionAction = /* @__PURE__ */ function(RejectionAction) {
+	/** A sibling refreshed the file: retry with the fresh credential. */
+	RejectionAction["RetryCredential"] = "retry-credential";
+	/** The file was deleted: the next decision token-joins or self-issues. */
+	RejectionAction["Rejoin"] = "rejoin";
+	/** This cluster's database holds the credential as valid (or is unreadable): the file stays. */
+	RejectionAction["KeepCredential"] = "keep-credential";
+	return RejectionAction;
+}({});
 function deferred() {
 	let resolve;
 	return {
@@ -1647,6 +1662,7 @@ var PeerAuthCoordinator = class {
 	joinToken;
 	joinWaitTimeoutMs;
 	selfIssue;
+	corroborateRejection;
 	/** The issuance in progress; concurrent sibling clients share it. */
 	selfIssueInFlight = null;
 	/** An operator revoked this coordinator's credential: never issue again in this process. */
@@ -1661,6 +1677,7 @@ var PeerAuthCoordinator = class {
 		this.joinToken = opts.joinToken;
 		this.joinWaitTimeoutMs = opts.joinWaitTimeoutMs ?? DEFAULT_JOIN_WAIT_TIMEOUT_MS;
 		this.selfIssue = opts.selfIssue;
+		this.corroborateRejection = opts.corroborateRejection;
 	}
 	/** Run `fn` exclusively against the credential file. */
 	async withLock(fn) {
@@ -1771,6 +1788,17 @@ var PeerAuthCoordinator = class {
 				});
 				return "retry-credential";
 			}
+			if (cred && this.corroborateRejection) {
+				const verdict = await this.corroborateRejection(cred.credential);
+				if (verdict !== "not-held") {
+					logger.warn("A peer rejected a credential this cluster holds as valid; keeping the credential file", {
+						instanceId: this.instanceId,
+						reason,
+						verdict
+					});
+					return "keep-credential";
+				}
+			}
 			try {
 				await unlink(this.credentialFile);
 				logger.warn("Deleted stale credential file after server rejection", {
@@ -1790,24 +1818,49 @@ var PeerAuthCoordinator = class {
 //#endregion
 //#region src/cluster/join-token.ts
 /**
-* Join token manager for zero-knowledge cluster bootstrap.
+* Join tokens: creation, lookup and claim.
 *
 * 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)
+* - Routing JSON: { orgId, routingKey, expiry, role }. A lookup key only: the
+*   row the token was stored as decides the role and routing a claim returns.
+* - Secret: 32 random bytes as hex. The database stores token_hash =
+*   SHA-256(secret), never the secret.
 *
-* Config bundle encryption: AES-256-GCM with random 12-byte IV.
-* Wire format: <12-byte IV><16-byte auth tag><ciphertext>
+* A row is found by its hash (claimByHash, readByHash), or by its routing fields
+* plus a proof the caller checks against each candidate hash
+* (resolveLiveTokenByRouting).
 */
 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. Create a new token with: kici-admin peer create-token";
 const TOKEN_EXPIRED_MESSAGE = "Join token has expired. Create a new token with: kici-admin peer create-token";
+const INVALID_JOIN_TOKEN_MESSAGE = "Invalid join token";
+const ResolvedJoinTokenStatus = z.enum([
+	"live",
+	"expired",
+	"unknown"
+]);
+const joinRoutingClaimSchema = z.object({
+	orgId: z.string().min(1),
+	routingKey: z.string().min(1),
+	expiry: z.number().finite()
+}).passthrough();
+/** Read a `routing_info` value (object, or a JSON string) and the `role` column. */
+function routingFromRow(routingInfo, role) {
+	const raw = typeof routingInfo === "string" ? JSON.parse(routingInfo) : routingInfo;
+	const parsed = joinRoutingClaimSchema.parse(raw);
+	const rowRole = OrchRole.parse(role);
+	return {
+		role: rowRole,
+		routing: {
+			orgId: parsed.orgId,
+			routingKey: parsed.routingKey,
+			expiry: parsed.expiry,
+			role: rowRole
+		}
+	};
+}
 var JoinTokenManager = class {
 	deps;
 	constructor(deps) {
@@ -1819,8 +1872,8 @@ var JoinTokenManager = class {
 	*/
 	async createToken(opts) {
 		const expiryMs = opts.expiryMs ?? DEFAULT_EXPIRY_MS;
-		const expiry = Date.now() + expiryMs;
-		const role = opts.role ?? "coordinator";
+		const expiry = Date.now() + Math.floor(expiryMs);
+		const role = opts.role ?? OrchRole.enum.coordinator;
 		const routing = {
 			orgId: opts.orgId,
 			routingKey: opts.routingKey,
@@ -1831,10 +1884,9 @@ var JoinTokenManager = class {
 		const routingB64 = Buffer.from(JSON.stringify(routing)).toString("base64url");
 		const secretHex = secret.toString("hex");
 		const token = `${TOKEN_PREFIX}.${routingB64}.${secretHex}`;
-		const { validationHash } = deriveKeys(secret);
 		await this.deps.db.insertInto("join_tokens").values({
 			id: randomUUID(),
-			token_hash: validationHash,
+			token_hash: tokenHashOf(secretHex),
 			routing_info: JSON.stringify(routing),
 			role,
 			created_by: opts.createdBy,
@@ -1847,66 +1899,92 @@ var JoinTokenManager = class {
 		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).
+	* Peer token mode: claim the row the presented token's secret hashes to. Role and
+	* routing come from the row (`claimByHash`), never from the token's routing part.
 	*
-	* 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.
+	* 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
+	* re-presents the still-valid join token already in its env, and the coordinator
+	* issues a fresh credential without an operator action. 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({
+		return this.claimByHash(tokenHashOf(parseToken(token).secretHex), consumedBy, peerInstanceId);
+	}
+	/**
+	* Find the row whose proof the caller accepts, among rows whose routing matches
+	* the claimed routing. Consumption state is not checked here; `claimByHash` owns it.
+	* At most JOIN_TOKEN_ROUTING_CANDIDATE_CAP rows, newest first, are offered.
+	*/
+	async resolveLiveTokenByRouting(claimed, accepts) {
+		const rows = await this.deps.db.selectFrom("join_tokens").select(["token_hash", "expires_at"]).where(sql`routing_info->>'orgId'`, "=", claimed.orgId).where(sql`routing_info->>'routingKey'`, "=", claimed.routingKey).where(sql`routing_info->>'expiry'`, "=", String(claimed.expiry)).orderBy("created_at", "desc").limit(16).execute();
+		for (const row of rows) {
+			if (!accepts(row.token_hash)) continue;
+			return new Date(row.expires_at).getTime() > Date.now() ? {
+				status: ResolvedJoinTokenStatus.enum.live,
+				tokenHash: row.token_hash
+			} : { status: ResolvedJoinTokenStatus.enum.expired };
+		}
+		return { status: ResolvedJoinTokenStatus.enum.unknown };
+	}
+	/**
+	* Atomically consume the row with this hash, or re-validate it for the instance
+	* that consumed it (self-healing reuse, bounded by expires_at). Routing and role
+	* come from the row.
+	*
+	* One UPDATE ... WHERE consumed_at IS NULL wins the claim across a shared-DB
+	* multi-coordinator mesh; every other concurrent caller gets
+	* TOKEN_ALREADY_USED_MESSAGE, the message peer-handler's idempotent retry keys on.
+	* On a 0-row claim, a follow-up SELECT tells not-found, expired, already-used and
+	* reusable-by-the-same-instance apart.
+	*/
+	async claimByHash(tokenHash, consumedBy, consumerInstanceId) {
+		const claimed = 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) {
+			consumed_by_instance: consumerInstanceId
+		}).where("token_hash", "=", tokenHash).where("consumed_at", "is", null).where("expires_at", ">", /* @__PURE__ */ new Date()).returning(["routing_info", "role"]).executeTakeFirst();
+		if (claimed) {
 			joinTokenLogger.info("Consumed join token", {
 				consumedBy,
-				peerInstanceId
+				consumerInstanceId,
+				tokenFingerprint: tokenFingerprint(tokenHash)
 			});
 			return {
-				routing: parsed.routing,
-				keys
+				tokenHash,
+				...routingFromRow(claimed.routing_info, claimed.role)
 			};
 		}
-		const row = await this.deps.db.selectFrom("join_tokens").selectAll().where("token_hash", "=", keys.validationHash).executeTakeFirst();
-		if (!row) throw new Error("Invalid join token");
+		const row = await this.deps.db.selectFrom("join_tokens").select([
+			"routing_info",
+			"role",
+			"expires_at",
+			"consumed_at",
+			"consumed_by_instance"
+		]).where("token_hash", "=", tokenHash).executeTakeFirst();
+		if (!row) throw new Error(INVALID_JOIN_TOKEN_MESSAGE);
 		if (new Date(row.expires_at).getTime() <= Date.now()) throw new Error(TOKEN_EXPIRED_MESSAGE);
 		if (row.consumed_at) {
-			if (row.consumed_by_instance === peerInstanceId) {
+			if (row.consumed_by_instance === consumerInstanceId) {
 				joinTokenLogger.info("Re-validated join token for returning instance", {
 					consumedBy,
-					peerInstanceId
+					consumerInstanceId,
+					tokenFingerprint: tokenFingerprint(tokenHash)
 				});
 				return {
-					routing: parsed.routing,
-					keys
+					tokenHash,
+					...routingFromRow(row.routing_info, row.role)
 				};
 			}
 			throw new Error(TOKEN_ALREADY_USED_MESSAGE);
 		}
-		throw new Error("Invalid join token");
+		throw new Error(INVALID_JOIN_TOKEN_MESSAGE);
+	}
+	/** Role and routing of the row with this hash, or null. */
+	async readByHash(tokenHash) {
+		const row = await this.deps.db.selectFrom("join_tokens").select(["routing_info", "role"]).where("token_hash", "=", tokenHash).executeTakeFirst();
+		return row ? routingFromRow(row.routing_info, row.role) : null;
 	}
 };
 /**
@@ -1939,21 +2017,17 @@ function parseToken(token) {
 	if (!routing.orgId || !routing.routingKey || !routing.expiry) throw new Error("Invalid join token routing data");
 	return {
 		routing,
+		routingB64: parts[1],
 		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
-	};
+/** Hex SHA-256 of a token secret: the value `join_tokens.token_hash` stores. */
+function tokenHashOf(secretHex) {
+	return sha256(Buffer.from(secretHex, "hex"));
+}
+/** A log-safe tag for a token hash. Never log the hash itself: it is the join key root. */
+function tokenFingerprint(tokenHash) {
+	return sha256(`kici-join-log:${tokenHash}`).slice(0, 12);
 }
 /**
 * Reason a run was held in the security queue. Persisted verbatim in
@@ -3154,6 +3228,28 @@ function validateWebhookUrl(value) {
 	if (url.protocol !== "https:") throw new Error(`--webhook-url must be an https:// URL (got ${url.protocol}//…)`);
 	return value;
 }
+/**
+* Every permission and event a KiCI GitHub App needs. The manifest requests
+* exactly these, and `kici-admin source refresh` reports an existing App that
+* lacks any of them.
+*/
+const GITHUB_APP_REQUIREMENTS = {
+	permissions: {
+		contents: "read",
+		metadata: "read",
+		pull_requests: "read",
+		checks: "write",
+		members: "read",
+		issues: "read"
+	},
+	events: [
+		"push",
+		"pull_request",
+		"check_run",
+		"check_suite",
+		"issue_comment"
+	]
+};
 function buildGithubAppManifest(input) {
 	return {
 		name: input.name,
@@ -3165,19 +3261,8 @@ function buildGithubAppManifest(input) {
 		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"
-		]
+		default_permissions: { ...GITHUB_APP_REQUIREMENTS.permissions },
+		default_events: [...GITHUB_APP_REQUIREMENTS.events]
 	};
 }
 /**
@@ -3356,6 +3441,65 @@ function openBrowserBestEffort(url) {
 	exec(cmd, () => {});
 }
 //#endregion
+//#region src/sources/webhook-url-resolvers.ts
+/**
+* Every webhook-URL decision the orchestrator makes for a GitHub-App source,
+* by operating mode. Pure functions: the entry points (`server.ts`,
+* `standalone.ts`) pass in the mode, the public base, the org and the Platform
+* values, so each rule is unit-tested here once.
+*/
+/** Why a webhook URL could not be resolved. The CLI maps each to a reason and a hint. */
+const WebhookUrlNote = z.enum([
+	"unsupported-provider",
+	"no-public-url",
+	"platform-no-public-url",
+	"platform-unavailable",
+	"platform-url-unknown",
+	"org-not-identified",
+	"resolver-unavailable",
+	"resolve-failed"
+]);
+//#endregion
+//#region src/cli/webhook-url-notes.ts
+/**
+* The text the CLI prints when the orchestrator returns no webhook URL. Shared
+* by `kici-admin source add` and the manifest setup flow, so each
+* `WebhookUrlNote` reads the same in both.
+*/
+const DASHBOARD_HINT = "Find the webhook URL in the dashboard under Sources.";
+/**
+* Short reason shown in `(unavailable — <reason>)` when no webhook URL could be
+* resolved. Takes a plain string too, because an orchestrator of another
+* version can send a note this CLI does not know.
+*/
+function webhookNoteReason(note) {
+	switch (note) {
+		case WebhookUrlNote.enum["no-public-url"]: return "KICI_WEBHOOK_PUBLIC_URL is not set on the orchestrator";
+		case WebhookUrlNote.enum["platform-no-public-url"]: return "the Platform has no public webhook URL configured";
+		case WebhookUrlNote.enum["platform-unavailable"]: return "could not reach the Platform";
+		case WebhookUrlNote.enum["platform-url-unknown"]: return "the Platform did not send its GitHub webhook URL";
+		case WebhookUrlNote.enum["org-not-identified"]: return "the orchestrator does not know its Platform org yet";
+		case WebhookUrlNote.enum["unsupported-provider"]: return "this provider has no webhook URL to print";
+		case WebhookUrlNote.enum["resolver-unavailable"]: return "this orchestrator cannot resolve webhook URLs";
+		case WebhookUrlNote.enum["resolve-failed"]: return "resolving the webhook URL failed";
+		default: return "webhook URL could not be determined";
+	}
+}
+/** Actionable next-step hint paired with {@link webhookNoteReason}. */
+function webhookNoteHint(note) {
+	switch (note) {
+		case WebhookUrlNote.enum["no-public-url"]: return "Set KICI_WEBHOOK_PUBLIC_URL to the orchestrator's public base, then re-run; paste the printed URL into your GitHub App or repo webhook.";
+		case WebhookUrlNote.enum["platform-unavailable"]: return "Retry once the orchestrator reconnects, or find the URL in the dashboard under Sources.";
+		case WebhookUrlNote.enum["platform-url-unknown"]: return "Retry when the orchestrator is connected to the Platform, or pass --webhook-url with the URL the App must deliver to.";
+		case WebhookUrlNote.enum["org-not-identified"]: return "Retry when the orchestrator is connected to the Platform, or pass --webhook-url.";
+		case WebhookUrlNote.enum["unsupported-provider"]: return "Configure the webhook from the provider's own settings.";
+		case WebhookUrlNote.enum["resolve-failed"]: return "Retry; if it fails again, find the webhook URL in the dashboard under Sources.";
+		case WebhookUrlNote.enum["platform-no-public-url"]:
+		case WebhookUrlNote.enum["resolver-unavailable"]:
+		default: return DASHBOARD_HINT;
+	}
+}
+//#endregion
 //#region src/cli/commands/source-manifest.ts
 /**
 * `kici-admin source add github --manifest` — the one-click GitHub App setup
@@ -3406,7 +3550,7 @@ const realManifestSetupDeps = {
 /** 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.`);
+	if (!pre.webhookUrl) throw new Error(`Cannot resolve the webhook URL for the new GitHub App: ${webhookNoteReason(pre.webhookNote)}. ` + webhookNoteHint(pre.webhookNote));
 	return pre.webhookUrl;
 }
 /**
@@ -3501,6 +3645,6 @@ async function runGithubManifestSetup(opts, client, deps = realManifestSetupDeps
 	}
 }
 //#endregion
-export { AdminApiClient, DEFAULT_TRUST_POLICY, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, DepCache, HeldRunStore, JoinTokenManager, PeerAuthCoordinator, PeerCredentialStore, S3CacheStorage, SecurityHoldReason, SourceCache, TrustPolicySource, TrustPolicyStore, UserCache, createCacheStorage, createHeldRunStoreFromUrl, createJoinTokenManagerFromUrl, createPeerCredentialStoreFromUrl, createTrustPolicyStoreFromUrl, runGithubManifestSetup };
+export { AdminApiClient, DEFAULT_TRUST_POLICY, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, DepCache, HeldRunStore, JoinTokenManager, PeerAuthCoordinator, PeerCredentialStore, RejectionAction, S3CacheStorage, SecurityHoldReason, SourceCache, TrustPolicySource, TrustPolicyStore, UserCache, createCacheStorage, createHeldRunStoreFromUrl, createJoinTokenManagerFromUrl, createPeerCredentialStoreFromUrl, createTrustPolicyStoreFromUrl, runGithubManifestSetup };
 
 //# sourceMappingURL=index.js.map

package/dist/providers/github/manifest.d.ts

@@ -41,6 +41,22 @@ export interface GithubAppManifest {
  * does not receive events at it; the operator owns delivery.
  */
 export declare function validateWebhookUrl(value: string): string;
+/**
+ * Every permission and event a KiCI GitHub App needs. The manifest requests
+ * exactly these, and `kici-admin source refresh` reports an existing App that
+ * lacks any of them.
+ */
+export declare const GITHUB_APP_REQUIREMENTS: {
+    readonly permissions: {
+        readonly contents: 'read';
+        readonly metadata: 'read';
+        readonly pull_requests: 'read';
+        readonly checks: 'write';
+        readonly members: 'read';
+        readonly issues: 'read';
+    };
+    readonly events: readonly ["push", "pull_request", "check_run", "check_suite", "issue_comment"];
+};
 export declare function buildGithubAppManifest(input: GithubManifestInput): GithubAppManifest;
 /** Credentials returned by GitHub's manifest-conversion endpoint. */
 export interface GithubAppCredentials {
@@ -62,21 +78,56 @@ export interface GithubAppCredentials {
 export declare function convertManifestCode(code: string, deps?: {
     octokit?: Pick<Octokit, 'request'>;
 }): Promise<GithubAppCredentials>;
+/** What `GET /app` says about the App: identity plus its grant. */
+export interface GithubAppIdentity {
+    name: string;
+    slug: string;
+    /** Events the App subscribes to. */
+    events: string[];
+    /** The App's permissions, name → access level. */
+    permissions: Record<string, string>;
+}
 /**
  * Ask GitHub who this App is (`GET /app`, authenticated as the App via its
- * JWT) and return its authoritative display `name` + `slug`. This is the single
- * "fetch the App's identity from GitHub" helper, reused at source creation, by
- * the daily refresher, and by `kici-admin source refresh`.
+ * JWT) and return its authoritative display `name` + `slug`, plus the events
+ * and permissions the App holds, which the requirement gap check reads. This is
+ * the single "fetch the App's identity from GitHub" helper, reused at source
+ * creation, by the daily refresher, and by `kici-admin source refresh`.
  *
  * GitHub is the source of truth: a rename in the GitHub UI changes the value
  * `GET /app` returns, which is what keeps the dashboard name fresh.
  */
 export declare function fetchGithubAppIdentity(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, deps?: {
     appOctokit?: Pick<Octokit, 'request'>;
-}): Promise<{
-    name: string;
-    slug: string;
-}>;
+}): Promise<GithubAppIdentity>;
+/** One installation's grant, as the gap check reads it. */
+export interface GithubAppInstallationGrant {
+    id: number;
+    /** Login of the account the App is installed on (an enterprise's slug). */
+    account: string;
+    /** `Organization`, `User`, or null for an enterprise installation. */
+    accountType: string | null;
+    permissions: Record<string, string>;
+}
+/** Every installation of the App (`GET /app/installations`, all pages), as the App. */
+export declare function listGithubAppInstallations(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, deps?: {
+    appOctokit?: Pick<Octokit, 'request'>;
+}): Promise<GithubAppInstallationGrant[]>;
+/** Required events and permissions an App or its installations lack. */
+export interface GithubAppRequirementGaps {
+    missingEvents: string[];
+    missingPermissions: string[];
+    /** Installations that have not accepted a permission the App itself holds. */
+    installationsPendingApproval: Array<{
+        installationId: number;
+        account: string;
+        missingPermissions: string[];
+    }>;
+}
+/** Compare an App and its installations with {@link GITHUB_APP_REQUIREMENTS}. */
+export declare function findGithubAppRequirementGaps(app: Pick<GithubAppIdentity, 'events' | 'permissions'>, installations: GithubAppInstallationGrant[]): GithubAppRequirementGaps;
+/** Whether any gap array is non-empty. */
+export declare function hasRequirementGaps(gaps: GithubAppRequirementGaps): boolean;
 /**
  * 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.

package/dist/routes/admin-sources.d.ts

@@ -9,56 +9,59 @@
  * the admin auth middleware in admin.ts.
  */
 import { Hono } from 'hono';
-import { OrchestratorMode } from '@kici-dev/engine';
 import type { SourceStore } from '../sources/source-store.js';
+import { type WebhookUrlResolution } from '../sources/webhook-url-resolvers.js';
 import type { Role } from '../secrets/rbac.js';
 import { type RedeliverWindowResult } from '../providers/github/deliveries.js';
-import { type FetchGithubAppIdentity } from '../github-app-name-refresher/github-app-name-refresher.js';
+import { type FetchGithubAppIdentity, type FetchGithubAppInstallations } from '../github-app-name-refresher/github-app-name-refresher.js';
 interface SourceRouteDeps {
     sourceStore: SourceStore;
     /**
      * Resolve the public webhook URL for a freshly added source so the CLI can
-     * print it. Platform/hybrid mode registers the source with the Platform and
-     * reads the URL from the `source.register.ack`; independent mode returns a
-     * null URL with an explanatory `webhookNote`. Omitted in deployments with no
+     * print it, by mode: platform and hybrid read the Platform's URL from the
+     * `source.register.ack` (hybrid falls back to its own URL); observed and
+     * independent return this orchestrator's own per-source URL. A null URL
+     * carries a `webhookNote` that says why. Omitted in deployments with no
      * resolver wired (the route then returns `webhookUrl: null`).
      */
     resolveSourceWebhookUrl?: (params: {
         routingKey: string;
         provider: string;
         sourceId: string;
-    }) => Promise<{
-        webhookUrl: string | null;
-        webhookNote?: string;
-    }>;
+    }) => Promise<WebhookUrlResolution>;
     /**
      * Resolve the org-scoped GitHub webhook URL for the manifest setup flow
      * BEFORE any App exists. The GitHub webhook URL is org-scoped
      * (`<base>/webhook/<orgId>/github`), not app-scoped, so it can be computed
      * up front and baked into the App manifest. Returns null + a note when the
-     * orchestrator cannot yet resolve a public base or its org id.
+     * orchestrator cannot resolve it for its mode.
      */
-    resolveGithubWebhookUrl?: () => Promise<{
-        webhookUrl: string | null;
-        webhookNote?: string;
-    }>;
+    resolveGithubWebhookUrl?: () => Promise<WebhookUrlResolution>;
     /**
-     * Fetch a GitHub App's authoritative `{ name, slug }` from GitHub. Injectable
-     * for tests; defaults to the real `fetchGithubAppIdentity`. Used by the
-     * `source refresh` route.
+     * Build this orchestrator's own direct-ingress URL for a listed GitHub
+     * source, or null: platform mode serves no direct ingress, and without a
+     * public base or a known org there is no URL to print.
+     */
+    resolveSourceIngressUrl?: (row: {
+        id: string;
+        customerId: string | null;
+    }) => string | null;
+    /**
+     * Fetch a GitHub App's authoritative `{ name, slug }`, events and permissions
+     * from GitHub. Injectable for tests; defaults to the real
+     * `fetchGithubAppIdentity`. Used by the `source refresh` route.
      */
     fetchAppIdentity?: FetchGithubAppIdentity;
+    /**
+     * List a GitHub App's installations. Injectable for tests; defaults to
+     * `listGithubAppInstallations`. Used by the `source refresh` route.
+     */
+    fetchAppInstallations?: FetchGithubAppInstallations;
     /**
      * Replay a window of GitHub webhook deliveries for one App. Injectable for
      * tests; defaults to the real `redeliverWindow`.
      */
     redeliverDeliveries?: RedeliverDeliveries;
-    /**
-     * Orchestrator operating mode. `observed` refuses GitHub-App source creation:
-     * those sources are ingested through the Platform relay, and an observed
-     * orchestrator never accepts a relay. Omitted (undefined) behaves as before.
-     */
-    mode?: OrchestratorMode;
 }
 /** Replay a delivery window for a GitHub App. Matches `redeliverWindow`. */
 export type RedeliverDeliveries = (app: {