@kici-dev/orchestrator 0.14.2 → 0.16.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/coordinator.d.ts

@@ -212,8 +212,8 @@ export declare class RunCoordinator {
      *   timer: whichever fires first removes the tracking entry.
      * - `final: false` — the worker is retrying. Re-arm the window for one more
      *   attempt plus the backoff; treat the `maxAttempts`-th such relay as final.
-     * - no verdict — an older worker that retries without a bound. The window
-     *   armed at the reroute keeps running unchanged.
+     * - no verdict — a repeated report of one failed spawn. The window armed at
+     *   the reroute keeps running unchanged.
      *
      * Two guards make the re-dispatch safe. First, source provenance: the failure
      * must come from `fromPeerId === tracked.peerId` (the authenticated connection

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;