@kici-dev/orchestrator 0.14.1 → 0.15.0

package/dist/cluster/peer-crypto.d.ts

@@ -1,9 +1,18 @@
 /**
- * ECDH key exchange and session encryption for peer-to-peer channels.
+ * ECDH key exchange, mutual-v2 authentication and session encryption for
+ * peer-to-peer channels.
  *
  * Uses X25519 for key agreement and AES-256-GCM for message encryption.
- * Session keys are derived via HKDF-SHA256 from the ECDH shared secret
- * and a caller-provided nonce (to ensure per-session uniqueness).
+ * The handshake key (K_hs) is derived via HKDF-SHA256 from the ECDH shared
+ * secret and the server nonce; it protects the authentication exchange only.
+ *
+ * mutual-v2: both sides hash the handshake transcript (TH: both ephemeral keys,
+ * the nonce and the advertised schemes). The client proves the shared key (PSK:
+ * sha256 of the peer credential, or the join token hash) with an HMAC over TH,
+ * and the server answers with its own HMAC over TH and the client proof. Every
+ * frame after acceptance uses the application key (K_app), derived from K_hs
+ * and the PSK, so a side that skipped the proof check cannot read or write them.
+ * Every field is length-prefixed, so field boundaries are unambiguous.
  *
  * Wire format for encrypted messages (base64 encoded):
  *   IV (12 bytes) || AuthTag (16 bytes) || Ciphertext
@@ -54,4 +63,52 @@ export declare function encryptMessage(plaintext: string, sessionKey: Buffer): s
  * @throws If the session key is wrong or the ciphertext has been tampered with
  */
 export declare function decryptMessage(encrypted: string, sessionKey: Buffer): string;
+/** Length of the server nonce in `peer.hello`. */
+export declare const HANDSHAKE_NONCE_BYTES = 32;
+/** Length of a mutual-v2 proof (HMAC-SHA256). */
+export declare const PEER_PROOF_BYTES = 32;
+/** Encode each field as a 4-byte big-endian length followed by its bytes. */
+export declare function lengthPrefixed(...fields: Array<Buffer | string>): Buffer;
+export interface PeerTranscriptInput {
+    serverEphemeralPublicKey: Buffer;
+    serverNonce: Buffer;
+    /** The schemes exactly as the server advertised them, unknown ones included. */
+    authSchemes: readonly string[];
+    clientEphemeralPublicKey: Buffer;
+}
+/** TH: binds both ephemeral keys, the nonce and the advertised schemes. */
+export declare function peerTranscriptHash(input: PeerTranscriptInput): Buffer;
+export interface ClientProofInput {
+    psk: Buffer;
+    transcriptHash: Buffer;
+    mode: string;
+    clientInstanceId: string;
+    role: string;
+    protocolVersion: number;
+    /** The join token's routing segment in token mode; empty in credential mode. */
+    tokenRouting: string;
+}
+export declare function computeClientProof(input: ClientProofInput): Buffer;
+export interface ServerProofInput {
+    psk: Buffer;
+    transcriptHash: Buffer;
+    clientProof: Buffer;
+    serverInstanceId: string;
+    grantedRole: string;
+    /** The credential the server issues in this response, or null when it issues none. */
+    sessionCredential: string | null;
+}
+export declare function computeServerProof(input: ServerProofInput): Buffer;
+/** A proof as sent on the wire (64 hex characters), or null when malformed. */
+export declare function decodeProof(hex: string): Buffer | null;
+/** Constant-time comparison; a length mismatch is a mismatch, never a throw. */
+export declare function proofMatches(expected: Buffer, presented: Buffer): boolean;
+/** K_app: protects every frame after acceptance, and needs the PSK as well as K_hs. */
+export declare function deriveAppKey(input: {
+    handshakeKey: Buffer;
+    psk: Buffer;
+    transcriptHash: Buffer;
+    clientProof: Buffer;
+    serverProof: Buffer;
+}): Buffer;
 //# sourceMappingURL=peer-crypto.d.ts.map

package/dist/cluster/peer-discovery.d.ts

@@ -0,0 +1,67 @@
+import { OrchRole } from '@kici-dev/engine';
+import { PeerDiscoveryMode } from '../config/schema.js';
+/** Discovered clients plus pending candidates, far above any real coordinator count. */
+export declare const MAX_DISCOVERED_PEER_CLIENTS = 64;
+/** A discovered client not connected for this long is dropped; a returning peer is announced again. */
+export declare const DISCOVERED_PEER_IDLE_PRUNE_MS: number;
+/** What discovery needs from a peer client. */
+export interface DiscoveryPeerClient {
+    readonly state: string;
+    connect(): void;
+    disconnect(): void;
+}
+/** Hooks a discovered client calls back. */
+export interface DiscoveredClientHooks {
+    /** Mutual authentication succeeded with the announced instance id. */
+    onAuthenticated: () => void;
+    /** Mutual authentication failed; the client closed and will not reconnect. */
+    onMutualAuthFailed: () => void;
+}
+/** One peer the Platform announced. */
+export interface PeerAnnouncement {
+    instanceId?: string;
+    address?: string | null;
+    orchRole?: OrchRole;
+}
+export interface PeerDiscoveryDeps {
+    mode: PeerDiscoveryMode;
+    selfInstanceId: string;
+    /** Every outbound peer client. Static clients sit under their URL until they authenticate. */
+    peerClients: Map<string, DiscoveryPeerClient>;
+    createClient: (address: string, expectedInstanceId: string, hooks: DiscoveredClientHooks) => DiscoveryPeerClient;
+    /** Minimum time between dials of an address whose last discovered dial failed mutual authentication. */
+    redialAfterFailureMs: number;
+    maxClients?: number;
+    idlePruneMs?: number;
+    now?: () => number;
+}
+export declare class PeerDiscovery {
+    private readonly deps;
+    private readonly discovered;
+    private readonly candidates;
+    /** Address -> when its last discovered dial failed mutual authentication. */
+    private readonly failedAt;
+    private readonly maxClients;
+    private readonly idlePruneMs;
+    private readonly now;
+    private timer;
+    constructor(deps: PeerDiscoveryDeps);
+    announce(peer: PeerAnnouncement): void;
+    /** A static client authenticated as this peer: discovery lets go of it. */
+    releaseToStatic(instanceId: string): void;
+    /** Drop discovered clients and candidates that stayed unconnected for the idle window. */
+    pruneIdle(): void;
+    start(): void;
+    stop(): void;
+    private size;
+    private dialDiscovered;
+    private dialCandidate;
+    /**
+     * The candidate authenticated. It runs before the candidate registers the
+     * peer, so the replaced client disconnects first.
+     */
+    private promote;
+    private drop;
+    private dropCandidate;
+}
+//# sourceMappingURL=peer-discovery.d.ts.map

package/dist/cluster/peer-handler.d.ts

@@ -1,13 +1,18 @@
 /**
  * WebSocket handler for incoming peer connections from other orchestrators.
  *
- * Accepts WS upgrade, performs ECDH key exchange for encrypted channel,
- * validates authentication via join token (first connect) or HMAC credential
- * proof (reconnection), registers the peer in PeerRegistry, and routes
- * messages bidirectionally. Sends periodic heartbeats to the connecting peer.
+ * Accepts WS upgrade, performs ECDH key exchange, and authenticates the peer
+ * with mutual-v2: `peer.hello` advertises the scheme, the peer proves its
+ * credential (or, on first join, its join token) with an HMAC over the
+ * handshake transcript, and this server answers with its own proof and
+ * switches to the application key. A join token never arrives here: the peer
+ * sends the token's routing segment, and the role and routing key come from
+ * the join_tokens row. A request in the scheme earlier releases used is refused
+ * with PEER_MUTUAL_AUTH_REQUIRED_REASON. Registers the peer in PeerRegistry and
+ * routes messages bidirectionally. Sends periodic heartbeats to the peer.
  */
 import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerScalerEvent, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerScalerOrphansRequest, type PeerForgetRequest, type PeerForgetResponse, type PeerScalerOrphansResponse, type PeerClusterSettingsRequest, type WorkerClusterSettings, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
-import type { PeerRegistry } from './peer-registry.js';
+import { type PeerRegistry } from './peer-registry.js';
 import { type PEER_FORGET_TIMEOUT, type PeerForgetRequestHandler } from './peer-forget.js';
 import { type SCALER_ORPHANS_TIMEOUT, type ScalerOrphansRequestHandler } from './scaler-orphans-peer.js';
 import type { PeerCredentialStore } from './peer-credentials.js';
@@ -120,6 +125,13 @@ export interface PeerHandlerDeps {
      */
     onPeerForgetRequest?: PeerForgetRequestHandler;
 }
+/** The schemes this server lists in peer.hello, in order. */
+export declare const ADVERTISED_PEER_AUTH_SCHEMES: readonly string[];
+/**
+ * A peer.auth.request from a release before mutual authentication: it carries
+ * a proof or a token, or names no scheme.
+ */
+export declare function isLegacyPeerAuthRequest(raw: unknown): boolean;
 /**
  * Create a handler function for incoming peer WebSocket connections.
  *

package/dist/cluster/peer-registry.d.ts

@@ -5,7 +5,17 @@
  * enabling routing decisions without real-time queries. Follows the
  * same label-matching semantics as agent/registry.ts for consistency.
  */
-import type { PeerHeartbeat, PeerCapabilities, ScalerCapacitySummary } from '@kici-dev/engine';
+import type { PeerAuthScheme, PeerHeartbeat, PeerCapabilities, ScalerCapacitySummary } from '@kici-dev/engine';
+/** Which side of a peer link authenticated: the peer dialled us, or we dialled it. */
+export declare enum PeerLinkDirection {
+    Inbound = "inbound",
+    Outbound = "outbound"
+}
+/** The scheme each direction of a peer link authenticated with; null while that direction is down. */
+export interface PeerAuthSchemes {
+    inbound: PeerAuthScheme | null;
+    outbound: PeerAuthScheme | null;
+}
 export interface PeerAgentInfo {
     agentId: string;
     labels: string[];
@@ -52,6 +62,8 @@ export interface PeerInfo {
     clusterSettingsVersion: number;
     /** Cluster role of the peer. */
     role: 'coordinator' | 'worker';
+    /** The authentication scheme of each link direction. */
+    authScheme: PeerAuthSchemes;
     hostname?: string;
     osRelease?: string;
     totalMemoryMb?: number;
@@ -119,6 +131,8 @@ export declare class PeerRegistry {
         routingKeys: string[];
         role?: 'coordinator' | 'worker';
     }): void;
+    /** Record the scheme one direction of the link authenticated with, or null when it closed. */
+    setAuthScheme(instanceId: string, direction: PeerLinkDirection, scheme: PeerAuthScheme | null): void;
     /**
      * Remove a peer entirely from the registry.
      */

package/dist/config/schema.d.ts

@@ -10,6 +10,12 @@
  * and PgSecretStore, not through config schemas.
  */
 import { z } from 'zod';
+/** Whether a coordinator dials the peers the Platform announces. */
+export declare const PeerDiscoveryMode: z.ZodEnum<{
+    platform: "platform";
+    static: "static";
+}>;
+export type PeerDiscoveryMode = z.infer<typeof PeerDiscoveryMode>;
 /**
  * Schema for the local YAML configuration file.
  * All fields optional except database.url.
@@ -105,6 +111,10 @@ export declare const sharedConfigSchema: z.ZodObject<{
         }>>;
         coordinatorUrl: z.ZodOptional<z.ZodString>;
         peerStaleTimeoutMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        peerDiscovery: z.ZodOptional<z.ZodEnum<{
+            platform: "platform";
+            static: "static";
+        }>>;
     }, z.core.$strip>>;
     webhookPayloadDir: z.ZodOptional<z.ZodString>;
     cacheTtlDays: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -193,6 +203,10 @@ export declare const appConfigSchema: z.ZodObject<{
         }>>;
         coordinatorUrl: z.ZodOptional<z.ZodString>;
         peerStaleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        peerDiscovery: z.ZodDefault<z.ZodEnum<{
+            platform: "platform";
+            static: "static";
+        }>>;
     }, z.core.$strip>>;
     webhookPayloadDir: z.ZodOptional<z.ZodString>;
     cacheTtlDays: z.ZodDefault<z.ZodCoercedNumber<unknown>>;

package/dist/config/types.d.ts

@@ -7,6 +7,7 @@
  * - AppConfig: merged result type used throughout the codebase
  */
 import type { OrchestratorMode } from '@kici-dev/engine';
+import type { PeerDiscoveryMode } from './schema.js';
 /**
  * Per-orchestrator settings loaded from YAML file.
  * These are instance-specific and never shared across orchestrators.
@@ -85,6 +86,7 @@ export interface SharedConfig {
         raftHeartbeatMs?: number;
         peerHeartbeatIntervalMs?: number;
         peerMaxReconnectDelayMs?: number;
+        peerDiscovery?: PeerDiscoveryMode;
     };
     webhookPayloadDir?: string;
     cacheTtlDays?: number;
@@ -189,6 +191,8 @@ export interface AppConfig {
         coordinatorUrl?: string;
         /** Stale peer timeout in ms. */
         peerStaleTimeoutMs: number;
+        /** Whether this coordinator dials Platform-announced peers. */
+        peerDiscovery: PeerDiscoveryMode;
     };
     /** Webhook payload storage directory */
     webhookPayloadDir?: string;

package/dist/config.d.ts

@@ -245,6 +245,10 @@ declare const configSchema: z.ZodObject<{
         peerStaleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
         electionGracePeriodMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
         singleNode: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>, z.ZodTransform<boolean, string | boolean>>;
+        peerDiscovery: z.ZodDefault<z.ZodEnum<{
+            platform: "platform";
+            static: "static";
+        }>>;
         trustedProxies: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string[], string>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -459,6 +463,10 @@ export declare const packagingConfigSchema: z.ZodObject<{
         peerStaleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
         electionGracePeriodMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
         singleNode: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>, z.ZodTransform<boolean, string | boolean>>;
+        peerDiscovery: z.ZodDefault<z.ZodEnum<{
+            platform: "platform";
+            static: "static";
+        }>>;
         trustedProxies: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string[], string>>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
@@ -673,6 +681,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
         peerStaleTimeoutMs: number;
         electionGracePeriodMs: number;
         singleNode: boolean;
+        peerDiscovery: "platform" | "static";
         trustedProxies: string[];
     };
 }>;

package/dist/db/migrations/157_host_roster_identity_source.d.ts

@@ -0,0 +1,21 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `host_roster.identity_source text NOT NULL DEFAULT 'operator'`, limited
+ * to `agent`, `operator` and `platform`.
+ *
+ * It records who last set a host's identity (labels, hostname, properties):
+ * the host's own agent registration, a local `kici-admin host declare`, or a
+ * Platform-relayed dashboard declare. A `platform` row is an unconfirmed
+ * placeholder that fan-out, inventory and the unreachable alarm skip.
+ *
+ * Backfill: a row whose `platform` column is set has registered at least once
+ * (only an agent registration writes `platform`), so it becomes `agent`. Every
+ * other row stays `operator`: a dashboard-created row from before this column
+ * cannot be told apart from a `kici-admin` declare, and treating it as
+ * `platform` would drop every declared, never-connected host out of fan-out.
+ *
+ * Idempotent: a re-run on a database that already has the column is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=157_host_roster_identity_source.d.ts.map

package/dist/db/types.d.ts

@@ -13,6 +13,17 @@ export declare enum JobKind {
     Gate = "gate",
     Proxy = "proxy"
 }
+/**
+ * Who last set a roster host's identity (labels, hostname, properties).
+ * `platform` marks an unconfirmed placeholder created from the dashboard: it
+ * is never a fan-out, inventory, agent-pin or unreachable-alarm target until
+ * its agent registers (`agent`) or an operator declares it (`operator`).
+ */
+export declare enum HostIdentitySource {
+    agent = "agent",
+    operator = "operator",
+    platform = "platform"
+}
 /**
  * PostgreSQL-only database types.
  * Column names use snake_case matching the actual database column names.
@@ -187,8 +198,9 @@ export type ClusterMeta = Selectable<ClusterMetaTable>;
 export type NewClusterMeta = Insertable<ClusterMetaTable>;
 /**
  * Join tokens table
- * Stores hashed join tokens for zero-knowledge cluster bootstrap.
- * Tokens are one-time use (consumed_at set after validation).
+ * Stores hashed join tokens. `kici-admin join` and peer token mode find a row by
+ * its hash; a token is consumed on first use and re-usable by the instance that
+ * consumed it until it expires.
  */
 export interface JoinTokenTable {
     /** UUID primary key */
@@ -2839,6 +2851,8 @@ export interface HostRosterTable {
      * presigned URL). NULL / false ⇒ the conservative `ssh-push` fallback.
      */
     s3_reachable: ColumnType<boolean | null, boolean | null | undefined, boolean | null>;
+    /** Who last set the host's identity. See {@link HostIdentitySource}. */
+    identity_source: ColumnType<HostIdentitySource, HostIdentitySource | undefined, HostIdentitySource>;
     created_at: Generated<Date>;
     updated_at: ColumnType<Date, Date | string | undefined, Date | string>;
 }

package/dist/github-app-name-refresher/github-app-name-refresher.d.ts

@@ -10,11 +10,17 @@
  * the Platform `webhook_sources` row and the dashboard Sources tab pick up the
  * new name/slug without any extra plumbing here.
  *
+ * The same pass checks each App against the events and permissions KiCI needs
+ * (`GITHUB_APP_REQUIREMENTS`) and the permissions each installation has
+ * accepted, and logs one warning per App with gaps. A gap never blocks the name
+ * and slug sync.
+ *
  * Lifecycle mirrors `StaleRunDetector`: `start()` runs an immediate refresh
  * (so a rename made while the orchestrator was down propagates on next boot)
  * then a `setInterval`; `stop()` clears it. Per-source errors are logged and
  * never abort the loop.
  */
+import { type GithubAppIdentity, type GithubAppInstallationGrant, type GithubAppRequirementGaps } from '../providers/github/manifest.js';
 /** A source row as returned by listSources() — the slice this module needs. */
 export type SourceIdentityRow = {
     routing_key: string;
@@ -39,12 +45,14 @@ export interface RefreshableSourceStore {
 export type FetchGithubAppIdentity = (creds: {
     appId: string;
     privateKey: string;
-}) => Promise<{
-    name: string;
-    slug: string;
-}>;
-/** Outcome of a single source refresh. */
-export interface RefreshResult {
+}) => Promise<GithubAppIdentity>;
+/** List a GitHub App's installations. Matches `listGithubAppInstallations`. */
+export type FetchGithubAppInstallations = (creds: {
+    appId: string;
+    privateKey: string;
+}) => Promise<GithubAppInstallationGrant[]>;
+/** Outcome of a single source refresh: the name and slug sync plus the requirement gaps. */
+export interface RefreshResult extends GithubAppRequirementGaps {
     routingKey: string;
     changed: boolean;
     oldName: string;
@@ -54,27 +62,31 @@ export interface RefreshResult {
 }
 /**
  * Refresh one already-resolved GitHub source's identity from GitHub and persist
- * it when the name or slug drifted. The caller supplies the row it already holds,
- * so this never lists the sources table. Throws for a non-GitHub row or missing
- * credentials.
+ * it when the name or slug drifted, then compare the App and its installations
+ * with the required events and permissions. The caller supplies the row it
+ * already holds, so this never lists the sources table. Throws for a non-GitHub
+ * row or missing credentials. A failed installations listing throws after the
+ * name and slug sync has been written, so the sync never waits on the gap check.
  */
-export declare function refreshResolvedGithubSource(sourceStore: Pick<RefreshableSourceStore, 'getSourceWithSecrets' | 'updateSource'>, row: SourceIdentityRow, fetchIdentity: FetchGithubAppIdentity): Promise<RefreshResult>;
+export declare function refreshResolvedGithubSource(sourceStore: Pick<RefreshableSourceStore, 'getSourceWithSecrets' | 'updateSource'>, row: SourceIdentityRow, fetchIdentity: FetchGithubAppIdentity, fetchInstallations: FetchGithubAppInstallations): Promise<RefreshResult>;
 /**
  * Re-fetch one GitHub source's identity from GitHub and persist it when the
- * name or slug drifted. Resolves the row by routing key (one sources read) then
- * delegates. Shared by `kici-admin source refresh`. Throws for a missing or
+ * name or slug drifted, and report requirement gaps. Resolves the row by routing
+ * key (one sources read) then delegates. Shared by `kici-admin source refresh`. Throws for a missing or
  * non-GitHub routing key.
  */
-export declare function refreshGithubSourceIdentity(sourceStore: RefreshableSourceStore, routingKey: string, fetchIdentity: FetchGithubAppIdentity): Promise<RefreshResult>;
+export declare function refreshGithubSourceIdentity(sourceStore: RefreshableSourceStore, routingKey: string, fetchIdentity: FetchGithubAppIdentity, fetchInstallations: FetchGithubAppInstallations): Promise<RefreshResult>;
 export interface GithubAppNameRefresherDeps {
     sourceStore: RefreshableSourceStore;
     fetchIdentity: FetchGithubAppIdentity;
+    fetchInstallations: FetchGithubAppInstallations;
     /** Refresh cadence in ms. Default cluster value: 24h (`config.githubAppNameRefreshIntervalMs`). */
     scanIntervalMs: number;
 }
 export declare class GithubAppNameRefresher {
     private readonly sourceStore;
     private readonly fetchIdentity;
+    private readonly fetchInstallations;
     private readonly scanIntervalMs;
     private interval;
     constructor(deps: GithubAppNameRefresherDeps);

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export { SourceCache } from './cache/source-cache.js';
 export { DepCache } from './cache/dep-cache.js';
 export { UserCache, DEFAULT_USER_CACHE_QUOTA_BYTES, DEFAULT_USER_CACHE_TTL_MS, type UserCacheRef, type UserCacheRestoreResult, type UserCacheBeginSaveResult, } from './cache/user-cache.js';
 export { PeerCredentialStore, createPeerCredentialStoreFromUrl, type PeerCredential, type CredentialFileData, } from './cluster/peer-credentials.js';
-export { PeerAuthCoordinator, type AuthDecision, type RejectionAction, } from './cluster/peer-auth-coordinator.js';
+export { PeerAuthCoordinator, RejectionAction, type AuthDecision, } from './cluster/peer-auth-coordinator.js';
 export { JoinTokenManager, createJoinTokenManagerFromUrl } from './cluster/join-token.js';
 export { HeldRunStore, createHeldRunStoreFromUrl, SecurityHoldReason, } from './contexts/held-runs.js';
 export { TrustPolicyStore, createTrustPolicyStoreFromUrl, TrustPolicySource, DEFAULT_TRUST_POLICY, type StoredTrustPolicy, } from './security/trust-policy-store.js';