@kici-dev/orchestrator 0.14.2 → 0.15.0

package/dist/__test-helpers__/peer-mutual-auth.d.ts

@@ -0,0 +1,42 @@
+export declare function refTranscriptHash(serverPub: Buffer, serverNonce: Buffer, authSchemes: readonly string[], clientPub: Buffer): Buffer;
+export declare function refClientProof(o: {
+    psk: Buffer;
+    th: Buffer;
+    mode: string;
+    instanceId: string;
+    role: string;
+    protocolVersion: number;
+    tokenRouting: string;
+}): Buffer;
+export declare function refServerProof(o: {
+    psk: Buffer;
+    th: Buffer;
+    clientProof: Buffer;
+    serverInstanceId: string;
+    grantedRole: string;
+    sessionCredential: string | null;
+}): Buffer;
+export declare function refAppKey(o: {
+    handshakeKey: Buffer;
+    psk: Buffer;
+    th: Buffer;
+    clientProof: Buffer;
+    serverProof: Buffer;
+}): Buffer;
+/** A join token in the production format, with its routing segment and stored hash. */
+export declare function makeTestJoinToken(routing: {
+    orgId: string;
+    routingKey: string;
+    expiry: number;
+    role: 'coordinator' | 'worker';
+}): {
+    token: string;
+    routingB64: string;
+    secretHex: string;
+    tokenHash: string;
+};
+/** The PSK a credential-mode peer proves with: the bytes of sha256(credential). */
+export declare function credentialPsk(credential: string): Buffer;
+/** The PSK a token-mode peer proves with: the bytes of the stored token hash. */
+export declare function tokenPsk(tokenHash: string): Buffer;
+//# sourceMappingURL=peer-mutual-auth.d.ts.map

package/dist/agent/host-roster.d.ts

@@ -1,6 +1,6 @@
 import { type Kysely } from 'kysely';
-import { type CanonicalLabel, type HostInventoryEntry, type InventorySelector, type LabelMatcher } from '@kici-dev/engine';
-import type { Database, HostRosterRow } from '../db/types.js';
+import { type CanonicalLabel, type FleetHostEntry, FleetHostWriteRefusal, type HostInventoryEntry, type InventorySelector, type LabelMatcher } from '@kici-dev/engine';
+import { type Database, type HostRosterRow } from '../db/types.js';
 /** Typed host-vars bag carried by roster rows (`string | number | boolean`). */
 export type HostProperties = Record<string, string | number | boolean>;
 /**
@@ -10,15 +10,60 @@ export type HostProperties = Record<string, string | number | boolean>;
  */
 export declare const STAGED_AGENT_VERSION_KEY = "kici:staged-agent-version";
 /**
- * Drop every orchestrator-reserved `kici:`-namespaced key from an
- * agent-reported host-property bag. Agent-reported properties win the roster
- * shallow-merge, so without this an agent could FORGE reserved keys the
- * orchestrator trusts — the staged-version convergence gate and the
- * root-executed restart commands both read `kici:` keys. Only orchestrator
- * writes (`recordStagedVersion`) and operator declares (`declareStatic`) set
- * this namespace; a registering agent never may.
+ * True when a host label or property key is in the orchestrator-reserved
+ * `kici:` namespace. Trimmed and case-insensitive, matching how labels fold on
+ * read (`canonicalizeLabel`).
+ */
+export declare function isReservedHostKey(key: string): boolean;
+/**
+ * Drop every reserved `kici:` key from an agent-reported host-property bag.
+ * Agent-reported properties win the roster shallow-merge, and the staged-version
+ * convergence gate and the restart commands the re-stage runs over SSH both
+ * read `kici:` keys, so a registering agent must never set them. Reserved keys
+ * come only from orchestrator code (`recordStagedVersion`) and a local
+ * `kici-admin host declare`.
  */
 export declare function stripReservedProperties(props: HostProperties): HostProperties;
+/** Who is writing a static host declaration or removal. */
+export declare enum HostWriteAuthority {
+    /** A local `kici-admin` declare or remove. */
+    operator = "operator",
+    /** A Platform-relayed dashboard write. The default. */
+    platform = "platform"
+}
+/** A host write refused because of the writer's authority. */
+export declare class HostWriteRefusedError extends Error {
+    readonly code: FleetHostWriteRefusal;
+    readonly detail: string;
+    constructor(code: FleetHostWriteRefusal, detail: string, message: string);
+}
+/** A Platform write named a reserved `kici:` label or property key. */
+export declare class ReservedHostKeyError extends HostWriteRefusedError {
+    readonly keys: string[];
+    constructor(keys: string[]);
+}
+/** A Platform declare named a host that already exists. */
+export declare class HostExistsError extends HostWriteRefusedError {
+    constructor(agentId: string);
+}
+/** A Platform remove named a host an agent or operator confirmed. */
+export declare class HostConfirmedError extends HostWriteRefusedError {
+    constructor(agentId: string);
+}
+/** Input of {@link HostRosterStore.declareStatic}. */
+export interface DeclareStaticInput {
+    agentId: string;
+    labels?: string[];
+    hostname?: string;
+    properties?: HostProperties;
+    address?: string;
+    sshUser?: string;
+    sshPort?: number;
+    sshKeySecret?: string;
+    s3Reachable?: boolean;
+    /** Who is writing. Omitted ⇒ `platform`, the most restricted. */
+    authority?: HostWriteAuthority;
+}
 /**
  * Pre-agent reach metadata for a declared host — how to SSH to it for bootstrap
  * bring-up before it has a KiCI agent. All fields nullable: a host with no reach
@@ -144,31 +189,33 @@ export declare class HostRosterStore {
     /** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
     stampLastSeen(agentId: string, instanceId: string): Promise<void>;
     /**
-     * Operator pre-declare of a static host. A re-declare of an existing agent_id
-     * converges the operator-owned columns (labels, hostname, reach,
-     * host_properties) to the newly-declared values while preserving the
-     * agent-reported liveness/identity columns (connected_instance_id, last_seen,
-     * platform, arch, lifecycle_class, token_id, reboot_pending_until). The
-     * optional reach fields (`address`/`sshUser`/`sshPort`/`sshKeySecret`) carry
-     * how to SSH to the host for bootstrap bring-up. Each operator field is
-     * preserve-on-omit: an omitted field keeps the existing column value.
-     *
-     * Returns `{ created: true }` when the declare inserted a new row,
-     * `{ created: false }` when it converged an existing one.
+     * Declare a static host. Under `operator` authority (a local `kici-admin`),
+     * it inserts or converges the row; under `platform` authority (a dashboard
+     * write, the default) it only creates a new, unconfirmed row. Returns
+     * `{ created: true }` when the declare inserted the row.
      */
-    declareStatic(input: {
-        agentId: string;
-        labels?: string[];
-        hostname?: string;
-        properties?: HostProperties;
-        address?: string;
-        sshUser?: string;
-        sshPort?: number;
-        sshKeySecret?: string;
-        s3Reachable?: boolean;
-    }): Promise<{
+    declareStatic(input: DeclareStaticInput): Promise<{
         created: boolean;
     }>;
+    /**
+     * A Platform declare: create a new `platform` row, never touch an existing
+     * one. Reserved `kici:` labels or properties refuse the whole write before
+     * any SQL, and the insert-or-nothing statement leaves no check-then-write race.
+     */
+    private createPlaceholder;
+    /**
+     * An operator declare. A re-declare converges the operator-owned columns
+     * (labels, hostname, reach, host_properties) and preserves the agent-reported
+     * liveness and identity columns (connected_instance_id, last_seen, platform,
+     * arch, lifecycle_class, token_id, reboot_pending_until). Each operator field
+     * is preserve-on-omit, and properties shallow-merge — except on a row a
+     * dashboard declare created: there the operator's values replace labels,
+     * hostname and properties outright, so no Platform-chosen value survives the
+     * confirmation, and the row becomes `operator`. An `agent` row stays `agent`.
+     * PostgreSQL evaluates every SET expression against the existing row, so each
+     * CASE reads the source before this statement changes it.
+     */
+    private declareAsOperator;
     /**
      * Read a host's pre-agent reach metadata. Returns null when the host is not
      * in the roster; a host declared without reach fields reads back with nulls.
@@ -181,12 +228,14 @@ export declare class HostRosterStore {
      * reserved key so the convergence gate can compare it against the target
      * INDEPENDENTLY of the agent's own self-reported bundle version (two payloads
      * can carry the same self-report but different staged keys). Shallow-merged, so
-     * it survives agent re-register (the agent never reports this reserved key).
+     * it survives an agent re-register (the agent's reserved keys are stripped).
      */
     recordStagedVersion(agentId: string, version: string): Promise<void>;
     /** Read a host's recorded staged agent-payload version, or null when never staged. */
     getStagedVersion(agentId: string): Promise<string | null>;
     listAll(): Promise<HostRosterRow[]>;
+    /** Every confirmed roster row (agent- or operator-set identity), by agent id. */
+    private listConfirmed;
     /**
      * Resolve EVERY roster host matching a label predicate (OR-of-AND include
      * groups, minus exclude labels), tagged with its derived status. Returns
@@ -232,22 +281,36 @@ export declare class HostRosterStore {
      * Query the roster as canonical {@link HostInventoryEntry} records. With a
      * selector, reuses `findMatching`'s label filtering (server-side, glob/regex);
      * property filtering is done client-side in the workflow. Omit the selector ⇒
-     * every host.
+     * every host. Unconfirmed rows a dashboard declare created are omitted.
      */
     queryInventory(selector: InventorySelector | undefined, graceMs: number): Promise<HostInventoryEntry[]>;
-    /** Single-host inventory lookup; null when the agent is not in the roster. */
+    /** Single-host inventory lookup; null when the agent is absent or unconfirmed. */
     getInventory(agentId: string, graceMs: number): Promise<HostInventoryEntry | null>;
+    /** A roster row as the dashboard sees it: the inventory entry plus `confirmed`. */
+    toFleetEntry(row: HostRosterRow, graceMs: number): FleetHostEntry;
+    /** Every roster host for the dashboard, unconfirmed placeholders included. */
+    listFleetHosts(graceMs: number): Promise<FleetHostEntry[]>;
+    /** One roster host for the dashboard, or null when the agent id has no row. */
+    getFleetHost(agentId: string, graceMs: number): Promise<FleetHostEntry | null>;
     /**
      * Count `static` (declared) hosts whose derived status is `unreachable` —
      * the "declared-but-absent" alarm population. Reuses the single-source
      * {@link deriveHostStatus} so the count never diverges from what
      * `kici-admin host list` shows. A not-currently-connected static host reads
      * `unreachable` regardless of grace (only the connected-but-stale case
-     * depends on `graceMs`).
+     * depends on `graceMs`). An unconfirmed dashboard-created row never raises
+     * the alarm.
      */
     countStaticUnreachable(graceMs: number): Promise<number>;
-    /** Remove a host from the roster by agent id. Returns rows deleted. */
-    removeStatic(agentId: string): Promise<number>;
+    /**
+     * Remove a host from the roster by agent id. Returns rows deleted (0 when no
+     * row matches). Under `platform` authority (the default) only an unconfirmed
+     * row a dashboard declare created is removed; a confirmed row throws
+     * {@link HostConfirmedError}.
+     */
+    removeStatic(agentId: string, opts?: {
+        authority?: HostWriteAuthority;
+    }): Promise<number>;
     /** Delete ephemeral rows whose last_seen is older than ttl. Returns count. */
     reapEphemeralPastTtl(ttlMs: number): Promise<number>;
     /**

package/dist/app.d.ts

@@ -278,6 +278,8 @@ export interface AppDependencies {
      * pre-flight (before any App exists). Passed into the admin source routes.
      */
     resolveGithubWebhookUrl?: AdminRouteDeps['resolveGithubWebhookUrl'];
+    /** Builds the direct-ingress URL for `source list`. Passed into the admin source routes. */
+    resolveSourceIngressUrl?: AdminRouteDeps['resolveSourceIngressUrl'];
     /** Config admin API route dependencies. Optional -- mounted when config management is available. */
     configRouteDeps?: ConfigRouteDeps;
     /** Event router for internal event delivery. Optional -- if not set, event routing is inactive. */
@@ -367,8 +369,8 @@ export interface AppDependencies {
         sendToPeer: (targetInstanceId: string, msg: PeerToPeerMessage) => boolean;
         getConnectionCount: () => number;
     };
-    /** Optional join handler for direct peer join requests. */
-    onJoinRequest?: (msg: import('@kici-dev/engine').JoinRequest) => Promise<import('@kici-dev/engine').JoinResponse>;
+    /** Optional join handler for direct peer join requests; answers any join.request frame. */
+    onJoinRequest?: (raw: unknown) => Promise<import('@kici-dev/engine').JoinResponse>;
     /** Optional callback when agent inventory changes (connect/disconnect). Triggers peer heartbeat broadcast. */
     onAgentInventoryChanged?: () => void;
     /** Run coordinator for multi-orch claim/reroute. Optional -- if not set, jobs dispatch locally. */

package/dist/cli/commands/host.d.ts

@@ -4,9 +4,12 @@
  *   host list      List all roster hosts with derived status
  *   host get       Show one roster host
  *   host declare   Pre-declare a static host before its agent connects
+ *   host remove    Remove a host from the roster
  *
  * Reads/writes the orchestrator DB directly (via withDb), so this lives in
  * kici-admin — never in the public `kici` or the Platform `kici-platform-admin`.
+ * Writes run as the operator: they may set reserved `kici:` labels and
+ * properties, change any host, and confirm a host the dashboard created.
  */
 import type { Command } from 'commander';
 export declare function registerHostCommands(program: Command): void;

package/dist/cli/commands/source-manifest.d.ts

@@ -19,9 +19,9 @@ export interface ManifestSetupOptions {
     githubOrg?: string;
     /**
      * Self-hosted webhook URL override. When set, it is baked verbatim into the
-     * App manifest's `hook_attributes.url` and the platform-mode webhook-URL
-     * resolution is skipped — so the flow works even where the auto-resolved KiCI
-     * platform URL is unavailable. KiCI adds no ingress at this URL; the operator
+     * App manifest's `hook_attributes.url` instead of the URL the orchestrator
+     * resolves for its mode — so the flow works even where that URL is
+     * unavailable. KiCI adds no ingress at this URL; the operator
      * owns delivery. Advanced/self-hosted only.
      */
     webhookUrl?: string;

package/dist/cli/commands/source.d.ts

@@ -21,6 +21,28 @@
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
+/** Structural row a listed generic/local source exposes for text rendering.
+ *  Both the HTTP `GenericSourceResponse` and the DB `GenericWebhookSource`
+ *  satisfy it, so `renderSourceListText` renders either transport's output. */
+interface ListableGenericRow {
+    id: string;
+    name: string;
+    routing_key: string;
+    enabled: boolean;
+    deleted_at?: unknown;
+}
+/** Render the human-readable `source list` output shared by the HTTP and the
+ *  direct-DB branches. `hasOrg` mirrors whether `--org` was passed (generic
+ *  sources are only listed for a specific org). `opts.directDb` marks a direct
+ *  DB read, which has no ingress URLs to print. */
+export declare function renderSourceListText(githubSources: Array<{
+    routingKey: string;
+    name: string;
+    provider: string;
+    ingressUrl?: string | null;
+}>, genericSources: ListableGenericRow[], hasOrg: boolean, opts: {
+    directDb: boolean;
+}): void;
 /** Error shown when both the private key and the webhook secret ask for stdin. */
 export declare const BOTH_STDIN_ERROR = "cannot read both the private key and the webhook secret from stdin \u2014 use @file or --from-env for one of them";
 /**
@@ -34,4 +56,5 @@ export declare function resolveWebhookSecret(opts: {
     privateKeyFromStdin: boolean;
 }, readStdin?: () => Promise<string>): Promise<string | undefined>;
 export declare function registerSourceCommands(program: Command, getClient: () => AdminApiClient): void;
+export {};
 //# sourceMappingURL=source.d.ts.map

package/dist/cli/join.d.ts

@@ -2,8 +2,8 @@
  * `kici-admin join` command.
  *
  * Bootstraps a new orchestrator by connecting to an existing cluster via
- * Platform relay or direct peer, receiving an encrypted config bundle, and
- * writing an env file the orchestrator boots from.
+ * Platform relay or direct peer, receiving the configuration bundle sealed to
+ * this host, and writing an env file the orchestrator boots from.
  *
  * Usage:
  *   kici-admin join --token kici_join_v1.xxx.yyy --platform wss://api.kici.dev/ws --api-key KEY

package/dist/cli/kici-admin.d.ts

@@ -8,6 +8,11 @@
  * Global options:
  *   --url / -u    Orchestrator URL (env: KICI_ADMIN_URL, default: http://localhost:8080)
  *   --token / -t  Admin API token (env: KICI_ADMIN_TOKEN, required)
+ *   -V / --cli-version / --version  Print the CLI version (--version only before a command)
+ *
+ * A command that declares its own option under one of these flags (for
+ * example `orchestrator upgrade --url`) owns that flag after its name; see
+ * `root-option-routing.ts`.
  */
 import { Command } from 'commander';
 /**

package/dist/cli/local-github-ingress-url.d.ts

@@ -5,4 +5,10 @@
  * KICI_WEBHOOK_PUBLIC_URL" note instead of a fabricated URL).
  */
 export declare function buildLocalGithubIngressUrl(webhookPublicUrl: string | undefined, orgId: string, sourceId: string): string | null;
+/**
+ * Build the orchestrator's OWN org-scoped GitHub App ingress URL
+ * (`<base>/webhook/<orgId>/github`), served by the org-scoped direct route.
+ * Null when no public base is configured.
+ */
+export declare function buildLocalGithubAppIngressUrl(webhookPublicUrl: string | undefined, orgId: string): string | null;
 //# sourceMappingURL=local-github-ingress-url.d.ts.map

package/dist/cli/root-option-routing.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Decide which command each root-option token in a kici-admin argv belongs to.
+ *
+ * Commander matches a program option anywhere in argv: the root's own
+ * `parseOptions` consumes `-u, --url`, `-t, --token` and `-V, --cli-version`
+ * even after a command name. That lets an operator put a global option after
+ * the command (`kici-admin runs list -u <url>`), but on its own it would also
+ * take an option away from any command that declares one with the same flag,
+ * such as `orchestrator upgrade --url <archive-url>` or
+ * `join --token <join-token>`.
+ *
+ * {@link routeRootArgs} prepares the argv for the root's `parseOptions`:
+ *
+ * - A flag that the command being run declares, and that also names a root
+ *   option, belongs to that command when it comes after the command's name. It
+ *   is hidden from the root behind an opaque stand-in token, which the root
+ *   classifies as an unknown option and so hands on to the subcommand; the
+ *   stand-ins are mapped back to the original tokens before the subcommand
+ *   parses them.
+ * - `--version` before the first command name is the root's version flag. The
+ *   root cannot register `--version` itself (`orchestrator upgrade` and
+ *   `agent upgrade` own `--version <version>`), so it is rewritten to the
+ *   registered `--cli-version`. After a command name it is left alone.
+ *
+ * - The value of a command option, when it is shaped like an option (`-uP4ss`,
+ *   `--url`), is hidden from the root the same way, so the root does not read
+ *   it as one of its own flags.
+ *
+ * Every other token reaches the root unchanged, so a root option after a
+ * command that does not declare that flag still sets the global option.
+ */
+import type { Command } from 'commander';
+/** The flag the root registers its version option under. */
+export declare const ROOT_VERSION_FLAG = "--cli-version";
+/** The root's argv, routed, and the map from each stand-in back to its token. */
+export interface RoutedRootArgs {
+    readonly args: string[];
+    /** Map a token from the root's parse result back to the original token. */
+    readonly restore: (token: string) => string;
+}
+/**
+ * Route a kici-admin argv (the user arguments, without `node` and the script)
+ * for the root command's `parseOptions`. See the module comment.
+ */
+export declare function routeRootArgs(root: Command, args: readonly string[]): RoutedRootArgs;
+//# sourceMappingURL=root-option-routing.d.ts.map

package/dist/cli/webhook-url-notes.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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.
+ */
+import { WebhookUrlNote } from '../sources/webhook-url-resolvers.js';
+/**
+ * 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.
+ */
+export declare function webhookNoteReason(note: WebhookUrlNote | string | undefined): string;
+/** Actionable next-step hint paired with {@link webhookNoteReason}. */
+export declare function webhookNoteHint(note: WebhookUrlNote | string | undefined): string;
+//# sourceMappingURL=webhook-url-notes.d.ts.map