@kici-dev/orchestrator 0.14.1 → 0.15.0

package/dist/cluster/coordinator-credential.d.ts

@@ -17,6 +17,27 @@ export declare enum CredentialIssueReason {
     FileMissing = "credential-file-missing",
     FileMismatch = "credential-file-mismatch"
 }
+/** What a coordinator's own cluster database says about a credential a peer rejected. */
+export declare enum RejectionCorroboration {
+    /** An unrevoked, unexpired row holds this credential: the peer's rejection is not this cluster's view. */
+    HeldValid = "held-valid",
+    /** No live row holds it: the rejection is right, and the file goes. */
+    NotHeld = "not-held",
+    /** The database could not be read: keep the file and retry on the next attempt. */
+    Unreadable = "unreadable"
+}
+/**
+ * The `corroborateRejection` callback a coordinator's `PeerAuthCoordinator`
+ * runs before it deletes its credential file after a peer rejected it. Any
+ * dialled endpoint can send a rejection, so the coordinator's own database
+ * decides: an expired or revoked row does not hold the credential, and the file
+ * then goes so the self-issue path reconciles.
+ */
+export declare function coordinatorRejectionCorroborator(opts: {
+    db: Kysely<Database>;
+    instanceId: string;
+    logger?: Logger;
+}): (credential: string) => Promise<RejectionCorroboration>;
 export declare const COORDINATOR_CREDENTIAL_REVOKED_MESSAGE = "Peer credential for this coordinator was revoked; not issuing a new one";
 export type CoordinatorCredentialStore = Pick<PeerCredentialStore, 'save' | 'findUnrevokedByInstanceId' | 'findLatestRevokedByInstanceId' | 'retireSelfIssued'>;
 export interface EnsureCoordinatorCredentialOptions {

package/dist/cluster/index.d.ts

@@ -6,11 +6,11 @@
  */
 export { PeerRegistry } from './peer-registry.js';
 export type { PeerInfo, PeerAgentInfo, PeerRegistryOptions } from './peer-registry.js';
-export { PeerClient } from './peer-client.js';
+export { PeerClient, PeerDialOrigin } from './peer-client.js';
 export type { PeerClientOptions } from './peer-client.js';
-export { PeerAuthCoordinator } from './peer-auth-coordinator.js';
-export { coordinatorSelfIssuer } from './coordinator-credential.js';
-export type { AuthDecision, RejectionAction } from './peer-auth-coordinator.js';
+export { PeerAuthCoordinator, RejectionAction } from './peer-auth-coordinator.js';
+export { coordinatorRejectionCorroborator, coordinatorSelfIssuer, RejectionCorroboration, } from './coordinator-credential.js';
+export type { AuthDecision } from './peer-auth-coordinator.js';
 export { createPeerHandler } from './peer-handler.js';
 export type { PeerHandlerDeps } from './peer-handler.js';
 export { PeerCredentialStore, readCredentialFile, writeCredentialFile, } from './peer-credentials.js';

package/dist/cluster/join-client.d.ts

@@ -1,16 +1,16 @@
 /**
- * Join client for zero-knowledge cluster bootstrap.
+ * Join client: the joiner side of `kici-admin join` (join protocol v2).
  *
- * Provides the joiner-side logic for `kici-admin join`:
- * 1. Connect to Platform relay (WS) or direct peer (HTTP POST)
- * 2. Send join.request with the join token
- * 3. Receive join.response with encrypted config bundle
- * 4. Decrypt bundle using token-derived AES-256-GCM key
- * 5. Write the decrypted config as an env file the orchestrator boots from
+ * 1. Build a join.request from the token: its routing part, a one-time X25519
+ *    public key, a nonce, and a proof that this host holds the token secret.
+ *    The secret itself stays on this host.
+ * 2. Send it through the Platform relay (WS) or directly to a peer (HTTP POST).
+ * 3. Check the existing orchestrator's proof in the join.response, then open the
+ *    configuration bundle sealed to the one-time key.
+ * 4. Write the bundle as the env file the orchestrator boots from.
  *
- * The token carries routing info (cleartext for Platform relay) and a secret
- * (used for HKDF key derivation). Only the joiner and the token creator
- * can derive the encryption key -- the Platform relay sees only ciphertext.
+ * A relay sees the routing part, the public keys, the nonces, the proofs and the
+ * ciphertext; none of them lets it read or change the bundle.
  */
 import { type JoinRequest, type JoinResponse } from '@kici-dev/engine';
 import type { ConfigBundle } from './join-handler.js';
@@ -27,10 +27,12 @@ interface JoinClientOptions {
 }
 /** Default path the join writes its env file to. */
 export declare const DEFAULT_JOIN_ENV_FILE = "./kici-orchestrator.env";
-/**
- * Decrypt a base64-encoded encrypted config bundle using a derived encryption key.
- */
-export declare function decryptAndParseBundle(encryptedB64: string, encryptionKey: Buffer): ConfigBundle;
+/** How long a join waits for the join.response, through either transport. */
+export declare const JOIN_TIMEOUT_MS = 30000;
+/** POST target for `--peer`, keeping any base path of the peer URL. */
+export declare function joinEndpointUrl(peerUrl: string): string;
+/** One-line operator message for a refused join. */
+export declare function describeJoinRefusal(response: JoinResponse): string;
 /**
  * Startup environment variable each `ConfigBundle.storage` field is delivered
  * through.
@@ -67,19 +69,19 @@ export declare class JoinClient {
     private readonly options;
     constructor(options: JoinClientOptions);
     /**
-     * Execute the join flow:
-     * 1. Send join.request with token to Platform relay or direct peer
-     * 2. Receive join.response with encrypted config bundle
-     * 3. Decrypt bundle using token-derived key
-     * 4. Write the env file the orchestrator boots from
+     * Execute the join flow: send the v2 join.request, check the existing
+     * orchestrator's proof, open the sealed bundle, and write the env file. Nothing
+     * is written when the response fails its proof.
      */
     join(): Promise<void>;
     /**
-     * Join via Platform relay: connect WS, authenticate, send join.request, receive join.response.
+     * Join via Platform relay: connect WS, authenticate with the API key, send the
+     * join.request, receive the join.response.
      */
     joinViaPlatform(request: JoinRequest): Promise<JoinResponse>;
     /**
-     * Join via direct peer: POST to peer's join endpoint.
+     * Join via direct peer: POST the join.request to the peer's join endpoint.
+     * There is no fallback to an earlier join protocol.
      */
     joinViaPeer(request: JoinRequest): Promise<JoinResponse>;
 }

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

@@ -1,17 +1,14 @@
 /**
- * Join handler for processing join requests from new orchestrators.
+ * Join handler: answers join protocol v2 requests from new orchestrators, whether they
+ * arrive through the Platform relay or on POST /api/v1/cluster/join.
  *
- * Supports both Platform relay and direct peer transport. When a new orchestrator
- * sends a join.request with a kici_join_v1 token, this handler:
- * 1. Validates the token (exists in DB, not expired, not consumed)
- * 2. Builds a config bundle (DB URL, S3 config, secrets key, cluster ID)
- * 3. Encrypts the bundle with the token-derived AES-256-GCM key
- * 4. Consumes the token (one-time use)
- * 5. Returns the encrypted bundle to the joiner
- *
- * The Platform relay sees only routing metadata and ciphertext -- zero-knowledge.
+ * It finds the join token row by the request's routing fields, verifies the joiner's
+ * proof against each candidate row, claims the row by hash, and seals the configuration
+ * bundle (database URL, object storage, secrets key, cluster ID) to the joiner's
+ * one-time key. A version-1 frame (one that carries the token) is refused before any
+ * lookup.
  */
-import type { JoinRequest, JoinResponse } from '@kici-dev/engine';
+import { type JoinResponse } from '@kici-dev/engine';
 import type { Kysely } from 'kysely';
 import type { ClusterIdentity } from './cluster-identity.js';
 import type { SharedConfigStore } from '../config/shared-store.js';
@@ -20,6 +17,11 @@ interface JoinHandlerDeps {
     sharedConfigStore: SharedConfigStore;
     clusterIdentity: ClusterIdentity;
     databaseUrl: string;
+    /**
+     * This orchestrator's own secrets key (`KICI_SECRET_KEY` or its key file). The
+     * bundle carries it when the shared configuration holds no `secrets.key`.
+     */
+    secretKey?: string;
 }
 /**
  * Config bundle distributed to new orchestrators via join token.
@@ -40,18 +42,24 @@ export interface ConfigBundle {
     secretKey?: string;
     clusterId: string;
 }
+/** The answer to a failure the joiner cannot act on; the detail goes to the log. */
+export declare const JOIN_INTERNAL_ERROR_MESSAGE = "Internal error";
 export declare class JoinHandler {
     private readonly deps;
     private readonly tokenManager;
     constructor(deps: JoinHandlerDeps);
     /**
-     * Handle a join request from a new orchestrator.
-     * Validates token, builds config bundle, encrypts with token-derived key, consumes token.
-     * Echoes messageId from request for Platform relay correlation.
+     * Answer one join.request frame. Every frame gets exactly one answer, a refused
+     * version-1 or malformed one included. Echoes the request's messageId for Platform
+     * relay correlation. A failure the joiner cannot act on (a database outage) carries
+     * no errorCode and a generic message.
      */
-    handleJoinRequest(request: JoinRequest): Promise<JoinResponse>;
+    handleJoinRequest(raw: unknown): Promise<JoinResponse>;
+    private answer;
     /**
-     * Build the config bundle from SharedConfig + local config.
+     * Build the config bundle from SharedConfig + local config. The secrets key is
+     * the shared configuration's `secrets.key`, else this orchestrator's own key, so
+     * a joined orchestrator decrypts what the cluster encrypted.
      */
     buildConfigBundle(): Promise<ConfigBundle>;
 }

package/dist/cluster/join-protocol-v2.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Join protocol v2: the key schedule, transcripts, proofs and sealed bundle.
+ *
+ * The joiner proves it holds the join token, and the existing orchestrator proves the
+ * same back, without either side sending the token secret. Both key from
+ * H = SHA-256(secret), the value `join_tokens.token_hash` stores. The bundle is sealed
+ * under a key that mixes an ephemeral X25519 agreement with a token-derived binding
+ * key, so a relay that records every frame can neither open nor forge it.
+ *
+ * Key schedule (HKDF-SHA256, salt "kici-join-v2"):
+ * - requestKey = HKDF(H, info "joiner-proof"), responseKey = HKDF(H, info "server-proof"),
+ *   bindingKey = HKDF(H, info "bundle-binding")
+ * - T1 = SHA-256("kici-join-v2/request" || lp(routing) || lp(E_j) || lp(n_j))
+ * - T2 = SHA-256(T1 || lp(E_s) || lp(n_s))
+ * - joinerProof = HMAC(requestKey, T1), serverProof = HMAC(responseKey, T2)
+ * - bundleKey = HKDF(ikm X25519(e_s, E_j), salt bindingKey, info "kici-join-v2/bundle" || T2)
+ * - encryptedBundle = AES-256-GCM(bundleKey, aad T2), packed IV || tag || ciphertext
+ *
+ * lp(x) is a 4-byte big-endian length, then x.
+ */
+import { type KeyObject } from 'node:crypto';
+import { type EcdhKeyPair } from './peer-crypto.js';
+export declare const JOIN_PROTOCOL_V2: 2;
+export declare const SERVER_PROOF_MISMATCH_MESSAGE = "The join response did not come from an orchestrator that holds this token";
+export interface JoinKeys {
+    requestKey: Buffer;
+    responseKey: Buffer;
+    bindingKey: Buffer;
+}
+/** Derive the proof and binding keys from H = SHA-256(secret), as 32 raw bytes. */
+export declare function deriveJoinKeys(tokenHash: Buffer): JoinKeys;
+export declare function requestTranscript(routingB64: string, joinerPublicKey: Buffer, joinerNonce: Buffer): Buffer;
+export declare function responseTranscript(requestT: Buffer, serverPublicKey: Buffer, serverNonce: Buffer): Buffer;
+export declare const computeJoinerProof: (keys: JoinKeys, t1: Buffer) => string;
+export declare const verifyJoinerProof: (keys: JoinKeys, t1: Buffer, presented: string) => boolean;
+export declare const computeServerProof: (keys: JoinKeys, t2: Buffer) => string;
+export declare const verifyServerProof: (keys: JoinKeys, t2: Buffer, presented: string) => boolean;
+/** Load a DER SPKI public key, refusing anything but X25519. */
+export declare function loadX25519PublicKey(der: Buffer): KeyObject;
+/** A low-order peer key yields an all-zero agreement, which carries no secret. */
+export declare function assertNonZeroSharedSecret(shared: Buffer): void;
+export declare function agreeSharedSecret(privateKey: KeyObject, peerPublicKeyDer: Buffer): Buffer;
+export declare function deriveBundleKey(shared: Buffer, bindingKey: Buffer, responseT: Buffer): Buffer;
+/** AES-256-GCM with a random 12-byte IV; packed IV || tag || ciphertext. */
+export declare function sealBundle(plaintext: string, key: Buffer, aad: Buffer): Buffer;
+export declare function openBundle(sealed: Buffer, key: Buffer, aad: Buffer): string;
+export interface JoinRequestV2Fields {
+    joinProtocol: typeof JOIN_PROTOCOL_V2;
+    routing: string;
+    joinerPublicKey: string;
+    joinerNonce: string;
+    joinerProof: string;
+}
+/** What the joiner keeps between its request and the response. Never leaves the host. */
+export interface JoinerState {
+    keys: JoinKeys;
+    requestT: Buffer;
+    ephemeral: EcdhKeyPair;
+}
+/** Joiner: build the request fields from the token's routing part and H. */
+export declare function createJoinRequest(input: {
+    routingB64: string;
+    tokenHash: Buffer;
+}): {
+    fields: JoinRequestV2Fields;
+    state: JoinerState;
+};
+export interface SealedJoinResponse {
+    joinProtocol: typeof JOIN_PROTOCOL_V2;
+    serverPublicKey: string;
+    serverNonce: string;
+    serverProof: string;
+    encryptedBundle: string;
+}
+/** Existing orchestrator: seal the bundle to the joiner's one-time key, with a fresh key of its own. */
+export declare function sealJoinResponse(input: {
+    keys: JoinKeys;
+    requestT: Buffer;
+    joinerPublicKey: Buffer;
+    bundle: object;
+}): SealedJoinResponse;
+/** Joiner: check the server proof first, then open the bundle. */
+export declare function openJoinResponse(state: JoinerState, response: SealedJoinResponse): unknown;
+//# sourceMappingURL=join-protocol-v2.d.ts.map

package/dist/cluster/join-token.d.ts

@@ -1,18 +1,19 @@
 /**
- * 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)
+ * - 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.
  *
- * 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>
+ * 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).
  */
+import { OrchRole } from '@kici-dev/engine';
 import { Kysely } from 'kysely';
+import { z } from 'zod';
 /**
  * Silence the module-level logger (e.g. when a CLI is emitting JSON on stdout
  * and a stray log line would break the contract).
@@ -20,16 +21,41 @@ import { Kysely } from 'kysely';
 export declare function silenceJoinTokenLogger(): void;
 export declare const TOKEN_ALREADY_USED_MESSAGE = "Join token has already been used. Create a new token with: kici-admin peer create-token";
 export declare const TOKEN_EXPIRED_MESSAGE = "Join token has expired. Create a new token with: kici-admin peer create-token";
-interface TokenRouting {
+export declare const INVALID_JOIN_TOKEN_MESSAGE = "Invalid join token";
+/** Rows sharing one routing triple that a lookup will try; bounds HMAC work per request. */
+export declare const JOIN_TOKEN_ROUTING_CANDIDATE_CAP = 16;
+export type JoinTokenRole = OrchRole;
+export interface TokenRouting {
     orgId: string;
     routingKey: string;
     expiry: number;
-    role: 'coordinator' | 'worker';
+    role: JoinTokenRole;
 }
-interface DerivedKeys {
-    encryptionKey: Buffer;
-    validationHash: string;
+/** The routing fields a presented token claims. A lookup key only: the row decides. */
+export type JoinRoutingClaim = Pick<TokenRouting, 'orgId' | 'routingKey' | 'expiry'>;
+/** A consumed (or same-instance re-validated) join token, as the database records it. */
+export interface ClaimedJoinToken {
+    /** Hex SHA-256 of the token secret (`join_tokens.token_hash`). */
+    tokenHash: string;
+    /** From `routing_info`, never from the presented token. */
+    routing: TokenRouting;
+    /** From the `role` column. */
+    role: JoinTokenRole;
 }
+export declare const ResolvedJoinTokenStatus: z.ZodEnum<{
+    expired: "expired";
+    live: "live";
+    unknown: "unknown";
+}>;
+export type ResolvedJoinTokenStatus = z.infer<typeof ResolvedJoinTokenStatus>;
+export type ResolvedJoinToken = {
+    status: typeof ResolvedJoinTokenStatus.enum.live;
+    tokenHash: string;
+} | {
+    status: typeof ResolvedJoinTokenStatus.enum.expired;
+} | {
+    status: typeof ResolvedJoinTokenStatus.enum.unknown;
+};
 interface JoinTokenManagerDeps {
     db: Kysely<any>;
 }
@@ -44,39 +70,44 @@ export declare class JoinTokenManager {
         orgId: string;
         routingKey: string;
         createdBy: string;
-        role?: 'coordinator' | 'worker';
+        role?: JoinTokenRole;
         expiryMs?: number;
     }): Promise<string>;
     /**
-     * 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
+     * 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.
+     */
+    validateAndConsumeToken(token: string, consumedBy: string, peerInstanceId: string): Promise<ClaimedJoinToken>;
+    /**
+     * 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.
+     */
+    resolveLiveTokenByRouting(claimed: JoinRoutingClaim, accepts: (tokenHash: string) => boolean): Promise<ResolvedJoinToken>;
+    /**
+     * 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.
      *
-     * 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.
+     * 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.
      */
-    validateAndConsumeToken(token: string, consumedBy: string, peerInstanceId: string): Promise<{
+    claimByHash(tokenHash: string, consumedBy: string, consumerInstanceId: string): Promise<ClaimedJoinToken>;
+    /** Role and routing of the row with this hash, or null. */
+    readByHash(tokenHash: string): Promise<{
         routing: TokenRouting;
-        keys: DerivedKeys;
-    }>;
+        role: JoinTokenRole;
+    } | null>;
 }
 /**
  * Build a JoinTokenManager backed by its own connection pool to the given
@@ -104,23 +135,14 @@ export declare function isTokenAlreadyUsedError(err: unknown): boolean;
  */
 export declare function parseToken(token: string): {
     routing: TokenRouting;
+    routingB64: string;
     secretHex: string;
 };
-/**
- * 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)
- */
-export declare function deriveKeys(secret: Buffer): DerivedKeys;
-/**
- * Encrypt a config bundle with the derived encryption key.
- * Format: <12-byte IV><16-byte auth tag><ciphertext>
- */
-export declare function encryptBundle(plaintext: object, encryptionKey: Buffer): Buffer;
-/**
- * Decrypt a config bundle with the derived encryption key.
- * Expects format: <12-byte IV><16-byte auth tag><ciphertext>
- */
-export declare function decryptBundle(data: Buffer, encryptionKey: Buffer): object;
+/** Hex SHA-256 of a token secret: the value `join_tokens.token_hash` stores. */
+export declare function tokenHashOf(secretHex: string): string;
+/** A log-safe tag for a token hash. Never log the hash itself: it is the join key root. */
+export declare function tokenFingerprint(tokenHash: string): string;
+/** Decode the base64url routing part of a token into its lookup fields. */
+export declare function decodeJoinRouting(routingB64: string): JoinRoutingClaim;
 export {};
 //# sourceMappingURL=join-token.d.ts.map

package/dist/cluster/peer-auth-coordinator.d.ts

@@ -1,5 +1,5 @@
 import { type CredentialFileData } from './peer-credentials.js';
-import { CoordinatorCredentialOutcome } from './coordinator-credential.js';
+import { CoordinatorCredentialOutcome, RejectionCorroboration } from './coordinator-credential.js';
 export type AuthDecision = {
     mode: 'credential';
     credential: CredentialFileData;
@@ -10,13 +10,22 @@ export type AuthDecision = {
 } | {
     mode: 'no-auth';
 };
-export type RejectionAction = 'retry-credential' | 'rejoin';
+/** What `reportRejection` did with the credential file. */
+export declare enum RejectionAction {
+    /** A sibling refreshed the file: retry with the fresh credential. */
+    RetryCredential = "retry-credential",
+    /** The file was deleted: the next decision token-joins or self-issues. */
+    Rejoin = "rejoin",
+    /** This cluster's database holds the credential as valid (or is unreadable): the file stays. */
+    KeepCredential = "keep-credential"
+}
 export declare class PeerAuthCoordinator {
     private readonly credentialFile;
     private readonly instanceId;
     private readonly joinToken?;
     private readonly joinWaitTimeoutMs;
     private readonly selfIssue?;
+    private readonly corroborateRejection?;
     /** The issuance in progress; concurrent sibling clients share it. */
     private selfIssueInFlight;
     /** An operator revoked this coordinator's credential: never issue again in this process. */
@@ -35,6 +44,11 @@ export declare class PeerAuthCoordinator {
          * credential and no join token. Only a coordinator wires it.
          */
         selfIssue?: () => Promise<CoordinatorCredentialOutcome>;
+        /**
+         * Asks this coordinator's own cluster database whether it holds a rejected
+         * credential as valid. Only a coordinator with a database wires it.
+         */
+        corroborateRejection?: (credential: string) => Promise<RejectionCorroboration>;
     });
     /** Run `fn` exclusively against the credential file. */
     private withLock;

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

@@ -7,16 +7,36 @@
  * - Periodic heartbeat (30s default)
  * - Intentional disconnect flag to prevent reconnection
  *
- * Authentication uses ECDH key exchange followed by join token (first connect)
- * or HMAC credential proof (reconnection).
+ * Authentication is mutual-v2: after the ECDH key exchange the client proves
+ * its credential (or, on first join, its join token) with an HMAC over the
+ * handshake transcript, and accepts nothing until the server proves it holds
+ * the same credential or token. The join token never leaves this host. Every
+ * frame after acceptance uses an application key that needs the shared secret.
+ * A server that does not offer mutual-v2 gets no proof at all.
  */
 import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerScalerOrphansRequest, type PeerForgetRequest, type PeerForgetResponse, type PeerScalerOrphansResponse, type PeerClusterSettingsRequest, type PeerClusterSettingsResponse, 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 { PeerAuthCoordinator } from './peer-auth-coordinator.js';
 /** Logged when this instance has neither a credential file nor a join token. */
 export declare const NO_AUTH_METHOD_MESSAGE = "No peer auth method: this instance has no credential file and no join token";
+/** Logged when a dialled server does not offer mutual authentication. */
+export declare const PEER_MUTUAL_AUTH_UNSUPPORTED_MESSAGE = "Peer does not support mutual authentication; upgrade every orchestrator in the cluster";
+/** Where the address this client dials came from. */
+export declare enum PeerDialOrigin {
+    /** KICI_CLUSTER_PEERS or a worker's coordinator URLs: reconnects with backoff. */
+    Static = "static",
+    /** A Platform announcement: a hint, dropped for good when mutual authentication fails. */
+    Discovered = "discovered"
+}
+/** Why a server failed mutual authentication. */
+export declare enum PeerMutualAuthFailure {
+    SchemeMissing = "scheme-missing",
+    ServerProofInvalid = "server-proof-invalid",
+    InstanceIdMissing = "instance-id-missing",
+    InstanceIdMismatch = "instance-id-mismatch"
+}
 type PeerConnectionState = 'disconnected' | 'connecting' | 'handshaking' | 'authenticating' | 'connected';
 export interface PeerClientOptions {
     /** WebSocket URL of the remote peer orchestrator. */
@@ -31,6 +51,21 @@ export interface PeerClientOptions {
     instanceId: string;
     /** Peer registry to update on heartbeats from remote peer. */
     peerRegistry: PeerRegistry;
+    /**
+     * Where the dialled address came from. A static target reconnects with
+     * backoff after any failure; a discovered target that fails mutual
+     * authentication is dropped. Default: static.
+     */
+    origin?: PeerDialOrigin;
+    /** The instance id a discovered target was announced with; the server must report it. */
+    expectedInstanceId?: string;
+    /**
+     * Closes a connection that has not completed authentication within this
+     * many ms, after which the normal reconnect policy applies. Default: 15000.
+     */
+    handshakeTimeoutMs?: number;
+    /** Called when a discovered target fails mutual authentication; the client then stays down. */
+    onMutualAuthFailed?: (failure: PeerMutualAuthFailure) => void;
     /** Callback to get this orchestrator's local agent inventory for heartbeats. */
     getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
     /** Heartbeat interval in ms. Default: 30000 (30s). */
@@ -127,7 +162,13 @@ export declare class PeerClient {
     private noAuthWarned;
     private intentionalDisconnect;
     private _targetInstanceId;
+    /** The key the current frames use: K_hs while authenticating, K_app once connected. */
     private sessionKey;
+    /** The handshake in flight; cleared on acceptance or close. */
+    private handshake;
+    /** The proof this connection sent, until the server's proof is checked. */
+    private pendingProof;
+    private handshakeTimer;
     private readonly ackWaiters;
     private readonly cacheWaiters;
     private readonly configReloadWaiters;
@@ -142,11 +183,15 @@ export declare class PeerClient {
     private isJoiner;
     /** complete() callback for the in-flight token-join, if this client is joiner. */
     private joinComplete;
-    /** The credential string this client last built an HMAC proof with. */
+    /** The credential string this client last built a proof with. */
     private lastProvedCredential;
     private readonly instanceId;
     private readonly role;
     private readonly peerRegistry;
+    private readonly origin;
+    private readonly expectedInstanceId?;
+    private readonly handshakeTimeoutMs;
+    private readonly onMutualAuthFailed?;
     private readonly getLocalInventory;
     private readonly heartbeatIntervalMs;
     private readonly maxReconnectDelayMs;
@@ -248,6 +293,29 @@ export declare class PeerClient {
     getReconnectDelay(): number;
     private doConnect;
     private handleMessage;
+    private armHandshakeTimer;
+    private clearHandshakeTimer;
+    /** A token join in flight must be released so sibling clients stop waiting on it. */
+    private releaseJoin;
+    /** Forget the handshake of a connection that closed or is being torn down. */
+    private resetHandshake;
+    /** Close a connection whose handshake broke the protocol. */
+    private abortHandshake;
+    /** Close a connection whose server failed mutual authentication. */
+    private failMutualAuth;
+    /** The server's plaintext peer.hello: refuse it unless it offers mutual-v2. */
+    private handleHello;
+    /**
+     * The encrypted peer.auth.response. Any frame that is not one closes the
+     * socket. An acceptance is checked synchronously, before any state change,
+     * registry write or callback, so a frame pipelined behind an unproven
+     * acceptance meets a client that is not connected.
+     */
+    private handleAuthResponse;
+    /** Returns why the acceptance fails mutual authentication, or null when it passes. */
+    private checkAcceptance;
+    /** The server proved itself: register the peer and start the connected session. */
+    private completeAcceptance;
     /**
      * Handle a rejected peer.auth.response. For the three credential-divergence
      * reasons, delegate to the coordinator (which deletes the shared file only if