@serfab/cadre-core 1.14.0 → 1.15.0

package/dist/control-database.d.ts

@@ -2,7 +2,7 @@ import { Database } from '@quereus/quereus';
 import type { SqlParameters } from '@quereus/quereus';
 import type { Libp2p } from '@libp2p/interface';
 import type { IRepo } from '@optimystic/db-core';
-import type { StrandRow, JoinRequestRow, JoinOutcome, PendingJoin, PeerAddressRecord, CadrePeerRow, OwnerKeyRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow, CadreInviteRow, CadreInviteUsageRow, CadreInviteRedemptionResult, CadreInviteStatus, SeedPeer } from './types.js';
+import type { StrandRow, JoinRequestRow, JoinOutcome, PendingJoin, NodeProfile, PeerAddressRecord, CadrePeerRow, OwnerKeyRow, RevocationRow, RevocationLedgerOpenResult, DeviceTokenRecord, DeviceTokenRow, CadreInviteRow, CadreInviteUsageRow, CadreInviteRedemptionResult, CadreInviteStatus, SeedPeer, MachineRemovalResult } from './types.js';
 import type { ControlTable, RevocableTable, BoundControlDomain, ControlAction, CadreInviteSignedFields } from './control-authorization.js';
 import type { ControlRetryAbandonment } from './control-retry.js';
 export type { ControlTable, RevocableTable, ControlDomain, ControlAction } from './control-authorization.js';
@@ -100,6 +100,12 @@ export interface FormationUsageResult {
     /** The single-use nonce written to `UsageStampId` (the row's primary key) — the caller's, or a freshly minted one. */
     usageStampId: string;
 }
+/**
+ * Parse a nullable stored `datetime` column into epoch ms, mapping both "absent"
+ * and "unparseable" to null — i.e. "no expiry". Shared by every `ExpiresAt`
+ * reader so the NaN guard cannot drift between them.
+ */
+export declare function parseNullableStoredDatetimeMs(value: string | number | null | undefined): number | null;
 /**
  * Build the canonical authorization message that owner signatures are bound to.
  *
@@ -325,6 +331,18 @@ export declare function projectSeedPeers(rows: readonly CadrePeerRow[], ownerKey
  */
 export declare const REAPABLE_TABLES: readonly ["CadrePeer", "DeviceToken", "ValidationKey", "JoinedStrand", "JoinRequest"];
 export type ReapableTable = (typeof REAPABLE_TABLES)[number];
+/** A `FormationInvite` row as {@link ControlDatabase.queryFormationInvite} reads it. */
+export interface FormationInviteRow {
+    token: string;
+    sAppId: string;
+    /** Parsed epoch ms of the stored `datetime`; null when the invitation never expires. */
+    expiresAtMs: number | null;
+    /** Null is unlimited. */
+    totalUses: number | null;
+    validationUrl: string | null;
+    /** A bound invitation's host strand; null on the responder-provisions path. */
+    strandId: string | null;
+}
 /**
  * Notified after a membership write (a `CadreControl.CadrePeer` or `OwnerKey` row, see
  * {@link ControlDatabase.mutateCadrePeer}) has COMMITTED.
@@ -343,6 +361,8 @@ export type MembershipChangeListener = (reason: string) => Promise<void>;
  * the writer that files the row supplies it.
  */
 export type RevokedRowRef = Pick<RevocationRow, 'tableName' | 'rowKey' | 'stampId'>;
+/** What {@link ControlDatabase.removeMachine} wrote: `CadreNode.removeMachine`'s result, less the re-vouches it made first. */
+export type MachineRemovalWrites = Pick<MachineRemovalResult, 'removedPeer' | 'removedOwnerKey' | 'removedDeviceToken' | 'withdrawnInvitations'>;
 /**
  * Notified after a guarded-table delete — and the `CadreControl.Revocation`
  * tombstone it writes in the same transaction — has COMMITTED.
@@ -972,6 +992,57 @@ export declare class ControlDatabase {
      * @throws when `key` is `ownerKey`, or is the only live owner.
      */
     deleteOwnerKey(key: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<boolean>;
+    /**
+     * Re-vouch a live `OwnerKey` row under this owner's signature: in ONE transaction, the
+     * current row's guarded delete plus tombstone ({@link deleteOwnerKey}'s body) and an insert
+     * of the same key under a fresh stamp, signed by `ownerKey` ({@link insertOwnerKeyVouched}'s
+     * body), as {@link rewritePendingJoin} re-seats a request. `OwnerKey` has `NoUpdate`, so
+     * this is the only way to rebind a row's voucher; the anchor derivation lets the re-add
+     * under a fresh stamp beat the older tombstone (`deriveOwnerAnchor`). For
+     * {@link removeMachine}: the owners a machine being removed had added keep their anchor
+     * place everywhere once their row stands on a remaining owner's signature.
+     *
+     * Through {@link mutateCadrePeer}, the membership hub. The stamp read runs inside the locked
+     * body; a row whose stamp is already retired (held without its delete) is reported as absent
+     * rather than tombstoned twice.
+     *
+     * @returns `true` when the row was re-vouched, `false` when `key` is not a live owner here.
+     * @throws when `key` is `ownerKey` (an owner cannot sign its own row's removal).
+     */
+    revouchOwnerKey(key: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<boolean>;
+    /**
+     * Remove one machine completely, in ONE transaction: its `CadrePeer` row, its `OwnerKey`
+     * row when `target.ownerKey` names one, its `DeviceToken` row when it has one, each with
+     * the `Revocation` tombstone retiring its stamp ({@link deleteGuardedRow}'s statement pair,
+     * composed bare as {@link deleteStrandAndPartyKey} composes it), plus a withdrawal tombstone
+     * for every `CadreInvite` in `target.inviteKeys` that is still live here
+     * ({@link withdrawCadreInvite}'s body). One transaction so no reader sees the machine half
+     * removed: a row gone but its push token resolvable, or its owner key gone but an invitation
+     * it could redeem again still open.
+     *
+     * Through {@link mutateCadrePeer}, the membership hub. Every stamp is read inside the locked
+     * body, and a row whose stamp is already retired (held without its delete) is skipped rather
+     * than tombstoned twice. The by-name owner refusals of {@link deleteOwnerKey} apply to the
+     * owner-key arm. Nothing to remove writes nothing and returns all false.
+     *
+     * The caller decides WHAT to remove, which owner key is the machine's and which invitations
+     * it could use, from its plan (`CadreNode.planMachineRemoval`); this method only refuses to
+     * write an inconsistent set.
+     *
+     * @throws when `target.ownerKey` is `ownerKey`, or is the only live owner here.
+     */
+    removeMachine(target: {
+        peerId: string;
+        ownerKey: string | null;
+        inviteKeys: readonly string[];
+    }, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<MachineRemovalWrites>;
+    /**
+     * The guarded removals {@link removeMachine} runs, signed over each row's current stamp:
+     * the `CadrePeer` row, the `OwnerKey` row when named, the `DeviceToken` row when present.
+     * Inside the locked body (every read `retry: false`); one `Revocation` scan serves the
+     * retired-stamp check for all three tables and the last-owner refusal.
+     */
+    private signMachineRemovals;
     /**
      * Insert a strand into the control database using an owner signature.
      *
@@ -1214,6 +1285,7 @@ export declare class ControlDatabase {
         multiaddr: string;
         updatedAt: number;
         sig: string | null;
+        profile: NodeProfile | null;
     }, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<boolean>;
     /**
      * Owner "re-touch" of an existing `CadrePeer` membership row: bump `UpdatedAt` and
@@ -1225,7 +1297,8 @@ export declare class ControlDatabase {
      * local-only (its block's cluster ≤1 at insert) is pushed to the cohort once it grows, by
      * re-issuing this monotonic bump. It is an UPDATE (not the original INSERT) because the row
      * already exists locally; a re-INSERT would hit the `PeerId` PK. Only the freshness stamp
-     * and voucher change — `PublicKey` / `Multiaddr` / `Sig` are left intact — so it is safe
+     * and voucher change — `PublicKey` / `Multiaddr` / `Sig` / `Profile` are left intact (the
+     * owner branch requires them kept: they are the machine's own claim) — so it is safe
      * over a row whose peer has not self-published (`Sig` null); the caller must skip a row
      * that already carries a self-`Sig` (that row is the owning peer's to refresh, and bumping
      * `UpdatedAt` without re-signing would invalidate its self-signature).
@@ -1449,8 +1522,8 @@ export declare class ControlDatabase {
      *   a retired stamp, and which a revoked drone cannot produce at all. The trade is
      *   recurring failure noise every cycle against removing the one stale row nobody else
      *   reads from this node (every other node already filters it by tombstone). A revoked
-     *   node therefore keeps its own copy of its own row; "a node that learns it has been
-     *   revoked should shut itself down" is a distinct behaviour and its own ticket.
+     *   node therefore keeps its own copy of its own row; learning that it was removed is a
+     *   separate behaviour (`CadreNode.removedFromCadre`, the `cadre:removed` event).
      *   `ValidationKey`, `JoinedStrand` and `JoinRequest` have no self notion and are not
      *   special-cased.
      *
@@ -1941,14 +2014,13 @@ export declare class ControlDatabase {
      * locked write body — same per-call opt-out, and for the same reason, as
      * {@link queryStampId}'s. Every unlocked caller keeps the default retried path.
      */
-    queryFormationInvite(token: string, retry?: boolean): Promise<{
-        token: string;
-        sAppId: string;
-        expiresAtMs: number | null;
-        totalUses: number | null;
-        validationUrl: string | null;
-        strandId: string | null;
-    } | null>;
+    queryFormationInvite(token: string, retry?: boolean): Promise<FormationInviteRow | null>;
+    /**
+     * Every `FormationInvite` row, expired and spent ones included, in the shape
+     * {@link queryFormationInvite} returns one. Read by a strand move
+     * (`exportStrandBundle`), which decides per row what is still redeemable.
+     */
+    queryFormationInvites(): Promise<FormationInviteRow[]>;
     /**
      * Count `FormationUsage` rows recorded against a token (uses consumed so far).
      *
@@ -2126,6 +2198,14 @@ export declare class ControlDatabase {
      * node was alone is queued for re-issue on cohort growth ({@link CadreNode.noteGuardedDelete}).
      */
     withdrawCadreInvite(key: string, ownerKey: string, signMessage: (message: Uint8Array) => string): Promise<boolean>;
+    /**
+     * The withdrawal tombstones for the `CadreInvite` rows among `keys` that are held here and
+     * not yet withdrawn, signed and ready for {@link execTombstone}: the body
+     * {@link withdrawCadreInvite} files one of and {@link removeMachine} files several of in one
+     * transaction. Inside the locked body (every read `retry: false`); an absent or already
+     * withdrawn key is logged and left out.
+     */
+    private signCadreInviteWithdrawals;
     /**
      * Redeem a seated `CadreInvite` on the owner's behalf: admit `peerId` as a cadre member and,
      * when the invitation grants ownership, as an owner — with NO owner signature. One