@kici-dev/orchestrator 0.1.22 → 0.1.23

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

@@ -3,6 +3,19 @@ import { type HostInventoryEntry, type InventorySelector, type LabelMatcher } fr
 import type { Database, HostRosterRow } from '../db/types.js';
 /** Typed host-vars bag carried by roster rows (`string | number | boolean`). */
 export type HostProperties = Record<string, string | number | boolean>;
+/**
+ * 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
+ * metadata cannot be bootstrapped. `sshKeySecret` is a scoped-secret ref
+ * (`scope/key`) the orchestrator resolves server-side; the key never lives here.
+ */
+export interface HostReach {
+    agentId: string;
+    address: string | null;
+    sshUser: string | null;
+    sshPort: number | null;
+    sshKeySecret: string | null;
+}
 /**
  * Derived (read-time) status of a roster host. Never a stored mutable column:
  * status is computed from the shared `last_seen` + `connected_instance_id` so
@@ -96,13 +109,36 @@ export declare class HostRosterStore {
     markDisconnected(agentId: string, instanceId: string): Promise<void>;
     /** Coarse heartbeat stamp — same owner-guard as markDisconnected. */
     stampLastSeen(agentId: string, instanceId: string): Promise<void>;
-    /** Operator pre-declare of a static host before its agent dials in. */
+    /**
+     * 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.
+     */
     declareStatic(input: {
         agentId: string;
-        labels: string[];
+        labels?: string[];
         hostname?: string;
         properties?: HostProperties;
-    }): Promise<void>;
+        address?: string;
+        sshUser?: string;
+        sshPort?: number;
+        sshKeySecret?: string;
+    }): Promise<{
+        created: boolean;
+    }>;
+    /**
+     * 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.
+     */
+    getReach(agentId: string): Promise<HostReach | null>;
     get(agentId: string): Promise<HostRosterRow | null>;
     listAll(): Promise<HostRosterRow[]>;
     /**

package/dist/agent/token-store.d.ts

@@ -41,6 +41,35 @@ export declare class AgentTokenStore {
      * @returns The plaintext token (shown once).
      */
     createEphemeral(agentId: string, labels: string[], ttlMs: number): Promise<string>;
+    /**
+     * Mint a single-use, short-TTL bootstrap token for an init-runner bring-up.
+     *
+     * The token is stored as `agent_type: 'ephemeral'` (so the existing expiry
+     * cleanup reaps it) and is bound to exactly the init-runner label set. It is
+     * single-use: `consumeBootstrapToken` sets `consumed_at` on first
+     * `agent.register`, and a second register is rejected. A leaked token is
+     * therefore inert after enrollment AND after its short TTL elapses.
+     *
+     * @param targetAgentId - The agent id the init-runner will register as.
+     * @param ttlMs - Time-to-live in milliseconds (short, ~10 min).
+     * @param labels - The init-runner labels the token authorizes.
+     * @returns The plaintext token (shown once) and the DB row ID.
+     */
+    mintBootstrapToken(opts: {
+        targetAgentId: string;
+        ttlMs: number;
+        labels: string[];
+    }): Promise<{
+        token: string;
+        id: string;
+    }>;
+    /**
+     * Consume a single-use bootstrap token by id. Sets `consumed_at` only when it
+     * is currently null, so the first register wins and any subsequent attempt
+     * with the same token returns false (already consumed). Returns true when
+     * this call performed the consumption.
+     */
+    consumeBootstrapToken(id: string): Promise<boolean>;
     /**
      * Validate a plaintext token against stored hashes.
      *