@serfab/cadre-host 1.12.0 → 1.14.0

package/dist/donation/donation-service.d.ts

@@ -1,389 +0,0 @@
-import type { Orchestrator } from '@serfab/cadre-provider';
-import type { DonationStore } from './donation-store.js';
-import type { DonationStatus, DonationView, GrantValidator } from './types.js';
-/**
- * Default age after which a donation still stuck in `awaiting_seed` is
- * auto-terminated: the requester provisioned a node but never presented a seed
- * (it vanished, or abandoned the flow), leaving an orphaned child holding host
- * ports. 30 minutes.
- *
- * NOTE: not operator-configurable yet — a single module constant. If hosts need
- * to tune the grace period, promote this to `host.config.json`.
- */
-export declare const DONATION_AWAITING_SEED_TTL_MS: number;
-/**
- * Default age after which a donation still stuck in `provisioning` is
- * auto-terminated: the host wrote the row before starting the child, and a
- * crash/kill in that window (or during the spawn itself) leaves nothing to
- * advance it across a restart. A real spawn (identity key read/gen, port
- * allocation, process spawn) completes in well under a second normally, so 5
- * minutes is generously past "any plausible spawn" without risking a false
- * reap of one still genuinely in flight under heavy load.
- */
-export declare const DONATION_PROVISIONING_TTL_MS: number;
-/** How often the reap sweep runs while cadre-host is up. 5 minutes. */
-export declare const DONATION_REAP_SWEEP_MS: number;
-/** A grantee-driven request to provision one donated node. */
-export interface DonationProvisionRequest {
-    /** The grant token that authorizes this donation (the quota key). */
-    grantToken: string;
-    /** The REQUESTER's cadre — the party the donated node joins. */
-    partyId: string;
-    /**
-     * Requester control-network bootstrap multiaddrs (dialable, with `/p2p/`). Empty
-     * means the requester dials the node itself: a phone has no address to give, so it
-     * reaches the node at the WebSocket address {@link DonationService.getPeer} reports
-     * rather than being dialed by it.
-     */
-    bootstrapNodes: string[];
-    /**
-     * The requester's owner public key(s), base64url. Pinned as cold-start
-     * seed-trust anchors on the donated node so it accepts the requester-signed
-     * seed presented in {@link DonationService.applySeed}. Without these the node's
-     * node-local trusted-owner anchor holds no key for the requester's party, and
-     * the default anchored policy rejects every seed.
-     *
-     * Shape-validated on the way in ({@link DonationService.provision}): every entry
-     * must decode as a base64url 32-byte Ed25519 public key, the same rule the node
-     * itself applies to `CADRE_OWNER_KEYS`. So everything downstream — the persisted
-     * record, the child's environment, a later respawn replaying it — carries values
-     * the node can actually start with. Curve membership is NOT checked (see
-     * `requireEd25519PublicKeyB64`): a well-formed key naming the wrong signer still
-     * fails at seed time, as any wrong key would.
-     */
-    ownerKeys: string[];
-    /** Node profile; defaults to `storage` so the node participates and is dialable. */
-    profile?: 'storage' | 'transaction';
-}
-/**
- * Outcome of {@link DonationService.applySeed}.
- *
- * - `seeded` — the node accepted the seed and the record now says so.
- * - `rejected` — the node refused the seed (its own seed-trust policy). Nothing
- *   written.
- * - `abandoned` — the seed reached the node, but the loan ended while the
- *   request was in flight. The ending wins: the record is left exactly as the
- *   ending wrote it. `status` is the status that won, absent when the row is
- *   gone entirely.
- */
-export type DonationSeedResult = {
-    outcome: 'seeded';
-    peersAdded: number;
-} | {
-    outcome: 'rejected';
-    error?: string;
-} | {
-    outcome: 'abandoned';
-    status?: DonationStatus;
-};
-/** Live peer identity of a donated node. */
-export interface DonationPeerInfo {
-    peerId: string;
-    multiaddrs: string[];
-}
-/**
- * Outcome of {@link DonationService.respawn}. Three distinct non-throwing ends,
- * which a bare `DonationView | undefined` conflated:
- *
- * - `respawned` — a new child is up and the record now names its handles.
- * - `not_respawnable` — the record predates persisted spawn inputs, so there is
- *   nothing to replay. Permanent; no child was spawned.
- * - `abandoned` — the loan ended (or the record vanished) while the spawn was in
- *   flight. The ending wins: the record is left exactly as the ending wrote it
- *   and the new child is cleaned up. `status` is the status that won, absent
- *   when the row is gone entirely.
- */
-export type RespawnResult = {
-    outcome: 'respawned';
-    donation: DonationView;
-} | {
-    outcome: 'not_respawnable';
-} | {
-    outcome: 'abandoned';
-    status?: DonationStatus;
-};
-/**
- * Orchestrator capabilities the donation cleanup paths need beyond the base
- * `Orchestrator`. Both are optional — only `HostProcessOrchestrator` implements
- * them; absent on a test double or a future orchestrator, the cleanup degrades
- * to terminalizing the record with nothing to reclaim.
- */
-export interface DonationOrchestrator extends Orchestrator {
-    /**
-     * Resolve a spawn's friendly containerId (== a donation's id) back to its
-     * current dockerId, so a stuck-`provisioning` reap can find and reclaim a
-     * child that was actually spawned before the host died.
-     */
-    resolveDockerId?(containerId: string): string | undefined;
-    /**
-     * Remove the working directory a spawn created for `containerId` when no
-     * handle owns it — the cleanup of last resort for a record that never got a
-     * `dockerId`. Returns whether anything was removed. Refuses when a handle
-     * still resolves (that child's directory belongs to `removeContainer`).
-     */
-    reclaimWorkdir?(containerId: string): boolean;
-}
-/** Constructor options. */
-export interface DonationServiceOptions {
-    /** Orchestrator that spawns/stops the donated node child process. */
-    orchestrator: DonationOrchestrator;
-    /** Grant validator (identity/expiry/revocation + quota). */
-    grants: GrantValidator;
-    /** Persistent donation store (`donations.json`). */
-    store: DonationStore;
-    /** Clock override for tests. */
-    now?: () => Date;
-}
-/**
- * DonationService — drives the donate-a-node lifecycle on behalf of an external
- * requester (a friend's phone). It is cadre-host's analogue of cadre-provider's
- * `ContainerService`, minus Docker/billing, plus the grant-token gate.
- *
- * The host contributes capacity only: it spawns a generic node into the
- * *requester's* cadre (`partyId`), pins the requester's owner key(s) so the node
- * will accept a requester-signed seed, and presents that seed to the node's
- * `POST /seed` — it never holds the requester's authority private key.
- *
- * Scope note: this class covers the service surface the node-donation
- * integration test drives directly (`provision` / `getPeer` / `applySeed` /
- * `terminate` / `get` / `list`). The grantee-facing HTTP routes, the `bin/host.ts`
- * wiring, and the stale-`awaiting_seed` reap sweep are owned by the
- * `2-donation-service` ticket and land alongside this file.
- */
-export declare class DonationService {
-    private readonly orchestrator;
-    private readonly grants;
-    private readonly store;
-    private readonly now;
-    /**
-     * Per-grant-token serialization tail. `provision` chains onto the prior
-     * operation for the same token so the quota check and record-create are
-     * atomic — two concurrent requests at `count = maxNodes - 1` can't both pass.
-     * `terminateGrant` chains onto it too, so a revoke's teardown cannot miss a
-     * record that a provision already queued for the grant is about to write.
-     *
-     * NOTE: one entry per distinct token, never evicted. Fine at household scale
-     * (a handful of grants); if grant counts ever grow large, evict the tail once
-     * it resolves.
-     */
-    private readonly grantTail;
-    constructor(opts: DonationServiceOptions);
-    /**
-     * Provision a donated node for a validated grant. Serialized per grant token
-     * so the quota check and record-create are atomic. On any orchestrator failure
-     * the reserved resources are reclaimed and the record is marked `error`.
-     *
-     * The owner-key pins are shape-checked FIRST — ahead of the per-grant lock, the
-     * quota check and the record write — so a malformed request costs nothing: no
-     * waiting behind another provision, no grant quota slot burned, no workdir or
-     * port taken, and no `error` record to explain later. Without it the request is
-     * answered as provisioned and the child dies at boot, which is the one place the
-     * caller cannot act on the typo.
-     */
-    provision(request: DonationProvisionRequest): Promise<DonationView>;
-    private provisionLocked;
-    /**
-     * Mark a still-`provisioning` record as failed — and ONLY such a record. A row
-     * that went `terminated` while the spawn was in flight is the borrower's own
-     * ending and must not be rewritten as a host fault; a row that vanished must
-     * not be recreated.
-     *
-     * Best-effort (mirroring {@link storeRespawnAttempt}): we are already unwinding a
-     * provision failure, and a store error here must not mask the error being
-     * reported to the caller.
-     */
-    private markProvisionFailed;
-    /**
-     * Live peer identity of a donated node, read fresh from its `/status` every
-     * call (no cache) so a re-keyed identity / remapped multiaddr is never served
-     * stale. Throws `peer_unavailable` while the node has no peer identity yet.
-     */
-    getPeer(id: string): Promise<DonationPeerInfo>;
-    /**
-     * Present the requester's phone-signed seed to the donated node's `POST /seed`,
-     * authenticated with the host↔node `seedToken`. On success the donation moves
-     * to `seeded`. The node still enforces its own seed-trust policy, so a seed
-     * signed by a key the node did not pin comes back `rejected`.
-     *
-     * **An ending that lands mid-seed wins.** The record is re-read after the node
-     * answers; if the loan ended (or the row vanished) while the request was in
-     * flight, that write stands and we report `abandoned` rather than marking a
-     * dead loan `seeded`. Unlike an abandoned respawn there is nothing to clean up
-     * — the record named its `dockerId` the whole time, so the ending's own
-     * `terminate` already stopped and reclaimed the child.
-     */
-    applySeed(id: string, encodedSeed: string): Promise<DonationSeedResult>;
-    /**
-     * Re-spawn a donated node that is no longer running, replaying the spawn
-     * inputs persisted on the record. The node keeps its workdir — and with it its
-     * identity key, trusted-owner anchor, and retained bootstrap peers — so it
-     * comes back as the *same* peer and rejoins from its own durable node-local
-     * stores. Only the host-side handles change: `dockerId`, `seedEndpoint`,
-     * `seedToken` are written back fresh.
-     *
-     * **Status is deliberately unchanged.** A `seeded` node stays `seeded` (it
-     * needs no re-seeding); an `awaiting_seed` node stays `awaiting_seed` and the
-     * borrower's later seed goes to the new endpoint/token.
-     *
-     * **An ending that lands mid-spawn wins.** The record is re-read after the
-     * orchestrator returns; if it went `terminated` (or `error`, or vanished)
-     * while the child was starting, that write stands and the new child is
-     * abandoned — see {@link abandonRespawn}. Both non-`respawned` outcomes are
-     * skips, not failures, so a sweep over the store keeps going. Orchestrator
-     * failures DO throw; the caller owns backoff/give-up.
-     *
-     * NOTE: not serialized. Two overlapping calls for the same id both spawn a
-     * child, and the second spawn drops the first's orchestrator handle — leaving
-     * an unmanaged process. A supervisor with more than one trigger (timer +
-     * exit event) must not let its passes overlap on one id.
-     */
-    respawn(id: string): Promise<RespawnResult>;
-    /**
-     * Give up on a respawn whose loan ended while the child was starting: stop the
-     * new child and, unless the record went `error`, reclaim it.
-     *
-     * Reclaim, not merely stop. The ending's own cleanup already ran and found
-     * nothing: `HostProcessOrchestrator.createContainer` calls `dropStaleHandle`
-     * *while* spawning, so by the time the concurrent `terminate` reached its
-     * stop/reclaim the old handle was gone and both calls were swallowed as
-     * best-effort no-ops. The new handle is now the only thing holding that
-     * spawn's ports and workdir, so stopping alone would leak both. On a
-     * `terminated` record the loan is over and the workdir (identity key +
-     * node-local stores) goes with it — which is what `terminate` intended.
-     *
-     * `error` is the deliberate exception: `removeContainer` deletes the workdir,
-     * and `DonationSupervisor.giveUp` keeps it on purpose so the identity key the
-     * borrower's cadre approved survives. Since both spawns share one workdir
-     * (`<rootDir>/<containerId>`), reclaiming here would delete exactly what
-     * `giveUp` meant to keep.
-     *
-     * NOTE: that skipped reclaim leaks the new spawn's ports — the record
-     * still names the *previous* `dockerId`, so a later `terminate` cleans up the
-     * old handle, not this one. Unreachable today (`giveUp` is only called from
-     * the supervisor's serialized pass, so it cannot overlap a respawn); if a
-     * second `respawn` caller ever appears, write the new `dockerId` onto the
-     * `error` record here so that later `terminate` reclaims the right child.
-     */
-    private abandonRespawn;
-    /**
-     * Terminate a donation: mark the record `terminated` FIRST, then stop + remove
-     * the child process (kept in the store for audit, excluded from the live-node
-     * tally).
-     *
-     * Order matters: stopping the child fires the orchestrator's `onStateChange`,
-     * and a respawn supervisor listening there must already see a terminal record
-     * — otherwise it observes "node gone, record still `seeded`" and resurrects a
-     * loan the borrower just ended. The tradeoff: a crash between the write and
-     * the stop leaves a `terminated` record with a live child (reaped on the next
-     * host start), which is strictly better than resurrecting an ended loan.
-     */
-    terminate(id: string): Promise<void>;
-    /**
-     * Terminate every donation under one grant that is not already `terminated` —
-     * the teardown behind an admin revoke. Returns the ids it terminated.
-     *
-     * Includes `error` records on purpose: the supervisor's give-up keeps such a
-     * record's workdir (its identity key) for a later `terminate`, and once the
-     * grant is revoked the grantee can no longer make that call, so this is the
-     * last thing that can reclaim it.
-     *
-     * Serialized with `provision` on the same per-grant queue. The caller revokes
-     * the grant first, and `provisionLocked` re-validates the grant inside that
-     * queue, so a provision queued ahead of this call finishes and is then
-     * terminated here, while one queued behind it is refused as revoked.
-     *
-     * Idempotent, and best-effort per record like the reap sweeps: a failed
-     * terminate is logged and the loop continues, and running it again terminates
-     * whatever is still left.
-     */
-    terminateGrant(token: string): Promise<string[]>;
-    private terminateGrantLocked;
-    /**
-     * Auto-terminate donations still `awaiting_seed` past `ttlMs` — a requester
-     * that provisioned a node but never presented a seed leaves an orphaned child
-     * holding host ports. Run on a periodic sweep and once at startup for records
-     * recovered from disk. Age is measured from the record's `updatedAt` (set when
-     * it entered `awaiting_seed`). Best-effort per record: a failed terminate is
-     * logged and the sweep continues. Returns the reaped donation ids.
-     */
-    reapStaleAwaitingSeed(ttlMs?: number): Promise<string[]>;
-    /**
-     * Auto-terminate donations stuck in `provisioning` past `ttlMs` — the record
-     * is written before the child spawn starts, so a host crash/kill anywhere in
-     * that window (including mid-spawn) leaves nothing to advance it across a
-     * restart: there is no in-flight `provisionLocked` call left to reach its
-     * post-spawn re-read. Run on the same periodic sweep and startup pass as
-     * {@link reapStaleAwaitingSeed}. Age is measured from `updatedAt`, which for a
-     * genuinely-stuck row equals `createdAt` — `provisionLocked` never touches a
-     * `provisioning` record again except to advance it out of this predicate.
-     * Best-effort per record: a failed reap is logged and the sweep continues.
-     * Returns the reaped donation ids.
-     */
-    reapStaleProvisioning(ttlMs?: number): Promise<string[]>;
-    /**
-     * Terminalize a stuck-`provisioning` record as `error` and reclaim any child
-     * the orchestrator can still find for it. Status is written FIRST (same
-     * ordering rule as {@link terminate}): reclaiming fires `onStateChange`, and
-     * anything listening must already see a terminal record.
-     *
-     * NOTE: the stop only reaches a child the orchestrator has a handle for.
-     * `HostProcessOrchestrator.launchChild` spawns the process and persists the
-     * handle in the same synchronous step, so the only child this misses is one
-     * whose host died between the OS spawn and that write — an orphan *process*
-     * this reap terminalizes the record for but cannot kill (its ports stay held
-     * until a reboot). Its working directory is no longer out of reach, though:
-     * with no handle to resolve we fall back to reclaiming by container name,
-     * which also covers the far commoner case of a host that died before any
-     * child existed at all. If the spawn→persist window ever widens (an async
-     * step added between the two), the orchestrator still needs its own orphan
-     * *process* sweep — a record that names no handle cannot get one after the
-     * fact.
-     */
-    private reclaimStuckProvisioning;
-    /** One donation (redacted), or undefined when unknown. */
-    get(id: string): DonationView | undefined;
-    /** All donations (redacted), optionally scoped to one grant token. */
-    list(grantToken?: string): DonationView[];
-    private requireDonation;
-    /** Best-effort stop; logs but never throws (cleanup path). */
-    private safeStop;
-    /**
-     * Persist a failed respawn's attempt counters — plus, when the spawn itself
-     * succeeded and it was the record write that failed, the new child's handles.
-     * Merged onto whatever is on disk now, never written wholesale: the caller's
-     * copy predates the orchestrator round-trip and `store.put` replaces the whole
-     * row, so writing it back would undo a `terminate` that landed while the spawn
-     * was in flight and resurrect a loan the borrower just ended.
-     *
-     * `status` and `updatedAt` are deliberately untouched — the attempt did not
-     * succeed, and `updatedAt` is what defers the stale-`awaiting_seed` reap.
-     *
-     * Recording `spawned` is what keeps the record pointing at the child that
-     * actually exists: `createContainer` already dropped the handle the record
-     * previously named, so leaving the old `dockerId` there would send every later
-     * stop/reclaim at an id the orchestrator cannot resolve — stranding the node's
-     * workdir on disk forever.
-     *
-     * Best-effort: we are already unwinding a respawn failure, and a store error
-     * here must not mask it. Losing the write costs the caller one extra attempt
-     * before backoff; the supervisor's next pass re-reads the record, finds the
-     * named child not running, and respawns again — which drops whatever handle is
-     * current, so the ports self-heal either way.
-     */
-    private storeRespawnAttempt;
-    /** Best-effort remove; logs but never throws (cleanup path). */
-    private safeReclaim;
-    /**
-     * Best-effort removal of the working directory of a donation whose spawn
-     * never produced a `dockerId`; logs but never throws (cleanup path). A no-op
-     * on an orchestrator without the capability, and on one that refuses because
-     * a live handle still owns the directory.
-     */
-    private safeReclaimWorkdir;
-    /**
-     * Run `fn` after any in-flight provision or grant teardown for the same grant
-     * token, so the quota check + record-create pair is atomic per grant and a
-     * teardown sees every record a queued provision writes.
-     */
-    private serializeByGrant;
-}