@serfab/cadre-host 0.8.1 → 0.10.0

package/dist/donation/donation-supervisor.js

@@ -0,0 +1,341 @@
+import debug from 'debug';
+const log = debug('cadre:host:donation-supervisor');
+/**
+ * Unit of the doubling respawn backoff: the wait after `n` consecutive failed
+ * attempts is `base * 2^n`, capped at {@link DONATION_RESPAWN_BACKOFF_MAX_MS}.
+ * So the first retry waits 10s (one attempt is already recorded by then), the
+ * second 20s, and so on. A node with no recorded attempt is respawned
+ * immediately.
+ */
+export const DONATION_RESPAWN_BACKOFF_BASE_MS = 5000;
+/**
+ * Ceiling on the doubling respawn backoff. 5 minutes.
+ *
+ * NOTE: not reachable at the current {@link DONATION_RESPAWN_MAX_ATTEMPTS} of 5
+ * — the longest wait actually served is the one before the 5th attempt,
+ * `5s * 2^4` = 80s, and the 5th failure gives up. The cap only starts clamping
+ * once a record can reach 6 recorded attempts (`5s * 2^6` = 320s), so raising
+ * the attempt cap without revisiting this one changes nothing.
+ */
+export const DONATION_RESPAWN_BACKOFF_MAX_MS = 5 * 60000;
+/**
+ * Consecutive respawn attempts after which the host stops trying and marks the
+ * donation `error` — a node that will not stay up is a host-side fault the
+ * borrower cannot see, so surface it instead of spinning forever.
+ */
+export const DONATION_RESPAWN_MAX_ATTEMPTS = 5;
+/**
+ * How long a respawned node must stay up before its attempt budget is refilled.
+ * The last respawn produced something that survived, so the next crash starts
+ * from a fresh budget rather than inheriting an old crash loop's count.
+ */
+export const DONATION_RESPAWN_HEALTHY_MS = 10 * 60000;
+/** How often the supervisor sweep runs while cadre-host is up. 1 minute. */
+export const DONATION_RESPAWN_SWEEP_MS = 60000;
+/**
+ * Statuses the supervisor considers. `provisioning` is a provision still in
+ * flight (its own code path owns the child); `error` and `terminated` are
+ * terminal — a loan the host gave up on or the borrower ended, neither of which
+ * may come back on its own.
+ */
+const SUPERVISED_STATUSES = new Set([
+    'awaiting_seed',
+    'seeded',
+]);
+/**
+ * DonationSupervisor — owns the invariant *a non-terminal donation is expected
+ * to be running*.
+ *
+ * Nothing else re-spawns a donated node: `bin/host.ts` re-spawns only the host's
+ * own owner node, the `/api/nodes/:id/{start,restart}` routes refuse non-owner
+ * ids, and the stale-`awaiting_seed` reap only terminates. So without this class
+ * a crashed, OOM-killed, or reboot-killed donated node stays dead with its
+ * record still reading `seeded`, silently costing the borrower a node and their
+ * grant a quota slot.
+ *
+ * One code path ({@link reconcile}) behind three triggers:
+ *
+ * - **host startup** — one pass after `orchestrator.init()`, which catches every
+ *   node that died while the host was down;
+ * - **exit signal** — the orchestrator's `onStateChange`, so a crash is noticed
+ *   in milliseconds rather than at the next sweep;
+ * - **periodic sweep** — the backstop for deaths no exit event covers (host was
+ *   down, listener missed, orchestrator re-attached to an already-dead pid).
+ *
+ * Passes are serialized: `DonationService.respawn` is not itself serialized, and
+ * two overlapping respawns of one id both spawn a child while the second drops
+ * the first's orchestrator handle (see its docstring). Since two of the three
+ * triggers can fire at once, the serialization lives here.
+ */
+export class DonationSupervisor {
+    constructor(opts) {
+        /** Serialization tail — see the class docstring. */
+        this.tail = Promise.resolve();
+        /** At most one exit-triggered pass queued at a time (crash storms coalesce). */
+        this.exitPassQueued = false;
+        /** Set by `stop()` so an in-flight pass abandons its remaining records. */
+        this.disposed = false;
+        this.service = opts.service;
+        this.store = opts.store;
+        this.orchestrator = opts.orchestrator;
+        this.now = opts.now ?? (() => new Date());
+        log('DonationSupervisor initialized');
+    }
+    /**
+     * One reconcile pass over the donation store. Serialized against every other
+     * pass, so a caller may get a queued pass rather than an immediate one.
+     * Returns the donation ids it respawned in *its own* pass.
+     */
+    reconcile() {
+        const run = () => this.reconcileOnce();
+        const next = this.tail.then(run, run);
+        // The stored tail swallows outcomes — a failed pass must not reject the
+        // next caller's wait, only sequence after it.
+        this.tail = next.then(() => undefined, () => undefined);
+        return next;
+    }
+    /**
+     * Subscribe to child exits, start the periodic sweep, and run the startup
+     * pass. Idempotent — a second call while started is a no-op.
+     */
+    start() {
+        if (this.timer)
+            return;
+        this.disposed = false;
+        // Subscribe before the first pass so an exit during it is not missed.
+        this.unsubscribe = this.orchestrator.onStateChange((info) => { this.onNodeState(info); });
+        this.timer = setInterval(() => { this.sweep('timer'); }, DONATION_RESPAWN_SWEEP_MS);
+        this.timer.unref();
+        this.sweep('startup');
+    }
+    /**
+     * Stop the timer and unsubscribe. A pass already in flight abandons its
+     * remaining records rather than being awaited — every record it has not
+     * reached is picked up by the next host start's startup pass.
+     */
+    stop() {
+        this.disposed = true;
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        this.unsubscribe?.();
+        this.unsubscribe = undefined;
+        log('DonationSupervisor stopped');
+    }
+    /** Fire-and-forget pass for the timer / exit / startup triggers. */
+    sweep(trigger) {
+        void this.reconcile()
+            .then((ids) => {
+            if (ids.length)
+                log('%s sweep respawned %d donation(s): %o', trigger, ids.length, ids);
+        })
+            .catch((err) => {
+            console.error(`donation respawn sweep failed: ${errorMessage(err)}`);
+        });
+    }
+    /**
+     * Exit-event trigger. Deliberately cheap: it does not map the handle back to a
+     * donation (that needs a store read per event), it just asks for a pass. Owner
+     * node exits are not ours — `bin/host.ts` owns re-spawning that one.
+     */
+    onNodeState(info) {
+        if (info.owner || info.status !== 'stopped')
+            return;
+        if (this.exitPassQueued)
+            return;
+        this.exitPassQueued = true;
+        void this.reconcile()
+            .catch((err) => { console.error(`donation respawn sweep failed: ${errorMessage(err)}`); })
+            .finally(() => { this.exitPassQueued = false; });
+    }
+    /** The unserialized body of one pass. */
+    async reconcileOnce() {
+        const respawned = [];
+        let candidates;
+        try {
+            candidates = this.store.list().filter((d) => SUPERVISED_STATUSES.has(d.status));
+        }
+        catch (err) {
+            // A malformed donations.json throws on every load; log rather than let an
+            // unhandled rejection escape the timer.
+            log('reconcile could not list donations: %s', errorMessage(err));
+            return respawned;
+        }
+        for (const donation of candidates) {
+            if (this.disposed)
+                break;
+            try {
+                const id = await this.reconcileOne(donation);
+                if (id)
+                    respawned.push(id);
+            }
+            catch (err) {
+                // One bad record must never end the sweep — the others are still down.
+                log('reconcile of donation %s failed: %s', donation.id, errorMessage(err));
+            }
+        }
+        return respawned;
+    }
+    /** Reconcile one record. Returns its id when this pass respawned it. */
+    async reconcileOne(donation) {
+        // No handle means nothing was ever spawned — `provision` owns that record
+        // until it writes one, and replaying it here would race that provision.
+        if (!donation.dockerId)
+            return undefined;
+        if (await this.orchestrator.isRunning(donation.dockerId)) {
+            this.refillBudgetIfHealthy(donation);
+            return undefined;
+        }
+        if (!this.backoffElapsed(donation)) {
+            log('donation %s is down but still inside its respawn backoff', donation.id);
+            return undefined;
+        }
+        return this.attemptRespawn(donation);
+    }
+    /**
+     * Whether enough time has passed since the last attempt. A record with no
+     * attempt history (or an unparsable timestamp — never wedge a node on bad
+     * data) is eligible immediately.
+     */
+    backoffElapsed(donation) {
+        const respawn = donation.respawn;
+        if (!respawn)
+            return true;
+        const last = Date.parse(respawn.lastAttemptAt);
+        if (Number.isNaN(last))
+            return true;
+        const delay = Math.min(DONATION_RESPAWN_BACKOFF_BASE_MS * 2 ** respawn.attempts, DONATION_RESPAWN_BACKOFF_MAX_MS);
+        return this.now().getTime() - last >= delay;
+    }
+    /**
+     * Clear the attempt count once a respawned node has been up long enough to
+     * count as healthy, so the next crash gets a full budget instead of inheriting
+     * the previous crash loop's.
+     *
+     * `updatedAt` is deliberately left alone: it is the age the stale-`awaiting_seed`
+     * reap measures, and a liveness observation is not borrower activity.
+     */
+    refillBudgetIfHealthy(donation) {
+        if (!this.budgetRefillDue(donation))
+            return;
+        // Re-read before writing: `donation` comes from the snapshot this pass
+        // started from, which can be several awaits old, and `store.put` replaces
+        // the whole row — writing the stale copy back would undo a concurrent seed
+        // or terminate that landed mid-pass.
+        const current = this.store.get(donation.id);
+        if (!current?.respawn || !this.budgetRefillDue(current))
+            return;
+        try {
+            this.store.put({ ...current, respawn: { ...current.respawn, attempts: 0 } });
+            log('donation %s is healthy again — respawn budget refilled', donation.id);
+        }
+        catch (err) {
+            // Costs one attempt off the next crash's budget, nothing more.
+            log('failed to refill respawn budget for %s: %s', donation.id, errorMessage(err));
+        }
+    }
+    /**
+     * Whether a record carries a crash-loop count old enough to clear. An
+     * unparsable timestamp is treated as not-due — unlike the backoff check,
+     * being wrong here would erase real attempt history rather than free a node.
+     */
+    budgetRefillDue(donation) {
+        const respawn = donation.respawn;
+        if (!respawn || respawn.attempts === 0)
+            return false;
+        const last = Date.parse(respawn.lastAttemptAt);
+        if (Number.isNaN(last))
+            return false;
+        return this.now().getTime() - last > DONATION_RESPAWN_HEALTHY_MS;
+    }
+    /** One respawn attempt, with the give-up check on failure. */
+    async attemptRespawn(donation) {
+        try {
+            const result = await this.service.respawn(donation.id);
+            switch (result.outcome) {
+                case 'not_respawnable':
+                    // A record written before the spawn inputs were persisted. Not
+                    // respawnable and never will be; skip it every pass (cheap — no
+                    // orchestrator call is reached) rather than fail the sweep.
+                    log('donation %s is down but not respawnable (no persisted spawn inputs)', donation.id);
+                    return undefined;
+                case 'abandoned':
+                    // The loan ended while the spawn was in flight and the ending won.
+                    // Nothing threw, so no attempt is persisted and the give-up path is
+                    // never entered — correct: this is not a failed attempt.
+                    log('respawn of donation %s was abandoned (record went %s mid-spawn)', donation.id, result.status ?? 'missing');
+                    return undefined;
+                case 'respawned':
+                    log('respawned donation %s → %s', donation.id, result.donation.dockerId);
+                    return donation.id;
+            }
+        }
+        catch (err) {
+            const message = errorMessage(err);
+            // `respawn` persists the incremented counter; re-read it rather than
+            // recomputing, so a give-up decision is made on what is actually on disk.
+            const attempts = this.store.get(donation.id)?.respawn?.attempts ?? 0;
+            log('respawn attempt %d for donation %s failed: %s', attempts, donation.id, message);
+            if (attempts >= DONATION_RESPAWN_MAX_ATTEMPTS) {
+                await this.giveUp(donation.id, attempts, message);
+            }
+            return undefined;
+        }
+    }
+    /**
+     * Stop trying: mark the donation `error` and stop whatever child the record
+     * still names. `error` is outside the store's live statuses, so the grant's
+     * quota frees and the borrower can provision a fresh node.
+     *
+     * The record is written BEFORE the stop for the same reason `terminate` does
+     * it in that order — the stop fires `onStateChange`, and a pass triggered by
+     * it must not see "node gone, record still `seeded`" and start respawning
+     * again.
+     *
+     * The child is stopped but NOT removed: `removeContainer` deletes the workdir,
+     * and the workdir holds the identity key the borrower's cadre approved. A
+     * later `terminate()` still works on an `error` record and reclaims it.
+     *
+     * NOTE: an `error`-after-give-up record therefore keeps its workdir forever
+     * unless someone calls `terminate`. If stale `error` workdirs ever pile up on
+     * real hosts, extend the reap sweep in `donation-service.ts` to cover them.
+     */
+    async giveUp(id, attempts, lastError) {
+        const donation = this.store.get(id);
+        if (!donation)
+            return;
+        // The record may have gone terminal while the failing attempt was in flight
+        // — a `terminate` mid-pass is exactly why `respawn` threw. Overwriting that
+        // with `error` would rewrite the borrower's own ending as a host fault, and
+        // the stop below would fire against a child `terminate` already reclaimed.
+        if (!SUPERVISED_STATUSES.has(donation.status)) {
+            log('donation %s went %s before give-up — leaving it alone', id, donation.status);
+            return;
+        }
+        this.store.put({
+            ...donation,
+            status: 'error',
+            error: `respawn gave up after ${attempts} attempts: ${lastError}`,
+            updatedAt: this.now().toISOString(),
+        });
+        log('gave up respawning donation %s after %d attempts: %s', id, attempts, lastError);
+        if (donation.dockerId) {
+            try {
+                await this.orchestrator.stopContainer(donation.dockerId);
+            }
+            catch (err) {
+                // The record names a live handle in the ordinary case — a failed respawn
+                // restores the handle it dropped, and a respawn that spawned but failed
+                // to record writes the new one onto the record. Still guarded: a handle
+                // can be lost to a host restart (state.json gone, or the child already
+                // reaped), and the child is dead either way, which is why we are here.
+                log('failed to stop container %s while giving up: %s', donation.dockerId, errorMessage(err));
+            }
+        }
+    }
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+//# sourceMappingURL=donation-supervisor.js.map

package/dist/donation/donation-supervisor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"donation-supervisor.js","sourceRoot":"","sources":["../../src/donation/donation-supervisor.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,71 @@
+import type { GrantStore } from './grant-store.js';
+import type { Grant, GrantAdminHandlers, GrantValidation, GrantValidator } from './types.js';
+/** Default node cap when the admin doesn't specify one. */
+export declare const DEFAULT_MAX_NODES = 1;
+/** Constructor options. */
+export interface GrantServiceOptions {
+    /** Persistent grant store (`grants.json`). */
+    store: GrantStore;
+    /** Clock override for tests. */
+    now?: () => Date;
+}
+/**
+ * GrantService — issues, validates, lists, and revokes donation grant tokens.
+ *
+ * It is the authority for a grant's *identity, expiry, and revocation*, and
+ * for the per-grantee *node cap* (`maxNodes`). It is deliberately **not** the
+ * authority for how many nodes are currently live under a grant — that tally
+ * belongs to the donation service (`2-donation-service`), which persists the
+ * grant→node records and can see terminations. `validateForProvision` takes
+ * the count as a parameter so the two never drift.
+ *
+ * All methods are synchronous: issuance/validation/revocation are pure local
+ * store operations with no node round-trip (unlike the trust-circle flow,
+ * which delegates to the owner node).
+ */
+export declare class GrantService implements GrantValidator {
+    private readonly store;
+    private readonly now;
+    constructor(opts: GrantServiceOptions);
+    /**
+     * Issue a new grant. Generates a high-entropy base64url token, persists it,
+     * and returns the whole `Grant` (the CLI/UI prints/QR-encodes the token).
+     */
+    issue(opts: {
+        label: string;
+        maxNodes?: number;
+        ttlMs?: number;
+    }): Grant;
+    /**
+     * Validate a presented bearer token for a non-provisioning op: it must name a
+     * known grant that is neither revoked nor expired. No quota check. Never
+     * throws for a bad token — returns a denial.
+     */
+    validate(token: string): GrantValidation;
+    /**
+     * Validate for a *new* provision request. Runs the identity/expiry/revocation
+     * checks of `validate`, then — only if those pass — consults the
+     * caller-supplied live-node tally against the grant's `maxNodes`.
+     *
+     * Concurrency boundary: this is a pure function of the passed count. Two
+     * provision requests racing at the quota edge (both seeing count = N-1)
+     * would both pass here; serialising them so only one wins is the donation
+     * service's responsibility (`2-donation-service` owns the grant→node lock).
+     */
+    validateForProvision(token: string, liveNodeCount: (token: string) => number): GrantValidation;
+    /**
+     * Revoke a grant by token: mark it revoked (denies future requests). Existing
+     * live nodes are **not** torn down here — that is a separate admin action via
+     * the donation service's terminate (`2-donation-service`). Throws not_found
+     * when the token is unknown.
+     */
+    revoke(token: string): void;
+    /** Enumerate all grants (for the CLI / UI). */
+    list(): Grant[];
+}
+/**
+ * Wrap a GrantService into the typed handler shape consumed by the loopback
+ * management server's `/grants-admin` routes. Errors propagate as GrantError;
+ * the server maps `.code` → HTTP status.
+ */
+export declare function createGrantAdminHandlers(service: GrantService): GrantAdminHandlers;

package/dist/donation/grant-service.js

@@ -0,0 +1,163 @@
+import { randomBytes } from 'node:crypto';
+import debug from 'debug';
+import { GrantError } from './types.js';
+const log = debug('cadre:host:grant-service');
+/** Token byte length (base64url-encoded; ~43 chars). Matches trust-circle. */
+const TOKEN_BYTES = 32;
+/** Default node cap when the admin doesn't specify one. */
+export const DEFAULT_MAX_NODES = 1;
+/**
+ * GrantService — issues, validates, lists, and revokes donation grant tokens.
+ *
+ * It is the authority for a grant's *identity, expiry, and revocation*, and
+ * for the per-grantee *node cap* (`maxNodes`). It is deliberately **not** the
+ * authority for how many nodes are currently live under a grant — that tally
+ * belongs to the donation service (`2-donation-service`), which persists the
+ * grant→node records and can see terminations. `validateForProvision` takes
+ * the count as a parameter so the two never drift.
+ *
+ * All methods are synchronous: issuance/validation/revocation are pure local
+ * store operations with no node round-trip (unlike the trust-circle flow,
+ * which delegates to the owner node).
+ */
+export class GrantService {
+    constructor(opts) {
+        this.store = opts.store;
+        this.now = opts.now ?? (() => new Date());
+    }
+    /**
+     * Issue a new grant. Generates a high-entropy base64url token, persists it,
+     * and returns the whole `Grant` (the CLI/UI prints/QR-encodes the token).
+     */
+    issue(opts) {
+        const label = normaliseLabel(opts.label);
+        const maxNodes = normaliseMaxNodes(opts.maxNodes);
+        const created = this.now();
+        const grant = {
+            token: generateToken(),
+            label,
+            maxNodes,
+            createdAt: created.toISOString(),
+        };
+        if (opts.ttlMs !== undefined) {
+            if (!Number.isFinite(opts.ttlMs) || opts.ttlMs <= 0) {
+                throw new GrantError('invalid_ttl', `Invalid ttlMs: ${opts.ttlMs}`);
+            }
+            grant.expiresAt = new Date(created.getTime() + opts.ttlMs).toISOString();
+        }
+        this.store.add(grant);
+        log('issued grant "%s" (token=%s, maxNodes=%d, expires=%s)', label, grant.token, maxNodes, grant.expiresAt ?? 'never');
+        return grant;
+    }
+    /**
+     * Validate a presented bearer token for a non-provisioning op: it must name a
+     * known grant that is neither revoked nor expired. No quota check. Never
+     * throws for a bad token — returns a denial.
+     */
+    validate(token) {
+        if (!token)
+            return { ok: false, reason: 'unknown_token' };
+        const grant = this.store.get(token);
+        if (!grant)
+            return { ok: false, reason: 'unknown_token' };
+        // Revocation is an explicit admin action; check it before expiry so a
+        // grant that is both revoked and expired reports the stronger signal.
+        if (grant.revokedAt)
+            return { ok: false, grant, reason: 'revoked' };
+        if (grant.expiresAt) {
+            const expiresAt = new Date(grant.expiresAt);
+            if (Number.isFinite(expiresAt.getTime()) && this.now() > expiresAt) {
+                return { ok: false, grant, reason: 'expired' };
+            }
+        }
+        return { ok: true, grant };
+    }
+    /**
+     * Validate for a *new* provision request. Runs the identity/expiry/revocation
+     * checks of `validate`, then — only if those pass — consults the
+     * caller-supplied live-node tally against the grant's `maxNodes`.
+     *
+     * Concurrency boundary: this is a pure function of the passed count. Two
+     * provision requests racing at the quota edge (both seeing count = N-1)
+     * would both pass here; serialising them so only one wins is the donation
+     * service's responsibility (`2-donation-service` owns the grant→node lock).
+     */
+    validateForProvision(token, liveNodeCount) {
+        const base = this.validate(token);
+        if (!base.ok || !base.grant)
+            return base;
+        const live = liveNodeCount(token);
+        if (live >= base.grant.maxNodes) {
+            return { ok: false, grant: base.grant, reason: 'quota_exceeded' };
+        }
+        return { ok: true, grant: base.grant };
+    }
+    /**
+     * Revoke a grant by token: mark it revoked (denies future requests). Existing
+     * live nodes are **not** torn down here — that is a separate admin action via
+     * the donation service's terminate (`2-donation-service`). Throws not_found
+     * when the token is unknown.
+     */
+    revoke(token) {
+        if (!this.store.markRevoked(token, this.now().toISOString())) {
+            throw new GrantError('not_found', `Unknown grant: ${token}`);
+        }
+        log('revoked grant (token=%s)', token);
+    }
+    /** Enumerate all grants (for the CLI / UI). */
+    list() {
+        return this.store.list();
+    }
+}
+/**
+ * Wrap a GrantService into the typed handler shape consumed by the loopback
+ * management server's `/grants-admin` routes. Errors propagate as GrantError;
+ * the server maps `.code` → HTTP status.
+ */
+export function createGrantAdminHandlers(service) {
+    return {
+        async postGrant(body) {
+            if (!body || typeof body.label !== 'string') {
+                throw new GrantError('invalid_label', 'label is required');
+            }
+            const grant = service.issue({
+                label: body.label,
+                ...(body.maxNodes !== undefined ? { maxNodes: body.maxNodes } : {}),
+                ...(body.ttlMs !== undefined ? { ttlMs: body.ttlMs } : {}),
+            });
+            return { grant };
+        },
+        async listGrants() {
+            return { grants: service.list() };
+        },
+        async deleteGrant(token) {
+            service.revoke(token);
+        },
+    };
+}
+function generateToken() {
+    // base64url so it survives in URLs, QR codes, and shell arguments.
+    return randomBytes(TOKEN_BYTES).toString('base64url');
+}
+function normaliseLabel(label) {
+    if (typeof label !== 'string') {
+        throw new GrantError('invalid_label', 'label must be a string');
+    }
+    const trimmed = label.trim();
+    if (trimmed.length === 0) {
+        throw new GrantError('invalid_label', 'label must not be empty');
+    }
+    if (trimmed.length > 200) {
+        throw new GrantError('invalid_label', 'label must be 200 characters or fewer');
+    }
+    return trimmed;
+}
+function normaliseMaxNodes(maxNodes) {
+    if (maxNodes === undefined)
+        return DEFAULT_MAX_NODES;
+    if (typeof maxNodes !== 'number' || !Number.isInteger(maxNodes) || maxNodes < 1) {
+        throw new GrantError('invalid_max_nodes', `maxNodes must be a positive integer (got ${JSON.stringify(maxNodes)})`);
+    }
+    return maxNodes;
+}
+//# sourceMappingURL=grant-service.js.map

package/dist/donation/grant-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"grant-service.js","sourceRoot":"","sources":["../../src/donation/grant-service.ts"],"names":[],"mappings":"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"}

package/dist/donation/grant-store.d.ts

@@ -0,0 +1,38 @@
+import type { Grant, GrantFile } from './types.js';
+/**
+ * Atomic JSON store for `grants.json`. Modelled on `auth/trust-circle-store.ts`:
+ * a single file, written to `<path>.tmp` then renamed, with an in-memory cache
+ * keyed by token.
+ *
+ * Unlike the trust-circle pending rows, grants are **not** self-reaping: a
+ * grant may legitimately outlive many nodes, so expiry is evaluated at
+ * validate time (in `GrantService`) and the admin removes stale grants
+ * explicitly. This store keeps no clock.
+ *
+ * Concurrency assumption: only one cadre-host process owns a given rootDir
+ * (the orchestrator already enforces this). No file-locking primitives.
+ */
+export declare class GrantStore {
+    private readonly path;
+    private cache;
+    constructor(rootDir: string);
+    filePath(): string;
+    /**
+     * Load (with caching). A missing file returns an empty store (fresh
+     * install). A present-but-malformed file throws — silently wiping it would
+     * revoke every grantee at once.
+     */
+    load(): GrantFile;
+    /** Persist the current state atomically (write then rename). */
+    save(state: GrantFile): void;
+    add(grant: Grant): void;
+    get(token: string): Grant | undefined;
+    list(): Grant[];
+    remove(token: string): boolean;
+    /**
+     * Mark a grant revoked at the given ISO instant. Idempotent: an
+     * already-revoked grant keeps its original `revokedAt`. Returns false when
+     * the token is unknown.
+     */
+    markRevoked(token: string, at: string): boolean;
+}