@serfab/cadre-core 1.16.0 → 1.18.0

package/dist/edge-node/edge-join.js

@@ -0,0 +1,227 @@
+/**
+ * `EdgeNode.joinCadre`'s sequence: redeem in place on a node already running in the credential's
+ * party, or stop the running node, start one in that party, redeem there and go back on any
+ * failure (docs/architecture.md → "An app joins an existing cadre"). The credential is a machine
+ * invitation, which admits the app as a machine, or an owner grant, which makes it a machine and
+ * an owner at once ({@link JoinCredential}). Runs over a narrow view of the runtime
+ * ({@link JoinRuntime}), inside one of its transitions.
+ */
+import { exportStrandBundle } from '../strand-move.js';
+import { isOwnerGrant } from './join-credential.js';
+import { adoptMovesInto, deferredOutcome, joinMoveRecord, toError, } from './strand-move.js';
+export async function joinCadre(runtime, credential, options, signal) {
+    signal.throwIfAborted();
+    const running = runtime.node;
+    if (running?.isRunning && runtime.runningOptions?.partyId === credential.partyId) {
+        return redeemInPlace(runtime, running, runtime.runningOptions, credential, options, signal);
+    }
+    return switchParty(runtime, credential, options, signal);
+}
+/** Redeem on the node already running in the credential's party; nothing to switch or roll back. */
+async function redeemInPlace(runtime, node, running, credential, options, signal) {
+    const admission = await redeemOnRunningNode(runtime, node, credential, options, signal);
+    reportProgress(options, { state: 'admitted', asOwner: admission.asOwner });
+    const owner = await runtime.wireJoinedOwner(node, admission.asOwner);
+    // An owner grant redeemed on a node that joined as a member finishes the move that join deferred.
+    const strandMove = await settleJoinMove(runtime, node, running.formerPartyId, owner);
+    if (owner === 'enrolled')
+        runtime.setStatus({ state: 'running', node, owner });
+    return joinResult(admission, running.formerPartyId, strandMove);
+}
+/**
+ * A machine invitation is redeemed as on a fresh node (a device already admitted is answered as
+ * such). An owner grant is redeemed for the owner slot's key: the node is a member of the party,
+ * so `redeemOwnerGrant` writes the row in its own store and the key can be wired at once.
+ */
+async function redeemOnRunningNode(runtime, node, credential, options, signal) {
+    if (!isOwnerGrant(credential))
+        return redeemInvitation(node, credential, options, signal);
+    // NOTE: a member running with no control connection to the party is refused `alone`
+    // (`OwnerKeyAddRefusedError`) by the grant's local path, where the invitation path waits for a
+    // member; if apps meet that, wait for a control connection before redeeming in place.
+    const redeemed = await node.redeemOwnerGrant(credential, await runtime.ownerSlotSigner(), redeemOptions(options, signal));
+    return { peerId: redeemed.memberPeerId, redeemedAt: new Date().toISOString(), asOwner: true };
+}
+/**
+ * Stop the running node, start one in the credential's party and redeem there; on any
+ * failure, go back to what ran before. Nothing is saved until a member has admitted this app.
+ * Leaving a party this app founded, its strands are recorded for the move first, so a refusal
+ * leaves that party running and unchanged.
+ */
+async function switchParty(runtime, credential, options, signal) {
+    const restore = runtime.runningOptions;
+    const leaving = restore ?? (await runtime.readSavedStart())?.options ?? null;
+    const founded = foundedPartyLeft(credential.partyId, leaving);
+    // The party this app founded, carried through any later join.
+    // NOTE: leaving a joined party while the move from `formerPartyId` into it is still pending
+    // (the key never wired as an owner there) leaves that record naming the party left, adopted
+    // only if the app goes back; `pendingStrandMove` keeps reporting it. If apps need the move
+    // to follow the app, retarget the record to the credential's party here.
+    const formerPartyId = founded?.partyId ?? leaving?.formerPartyId;
+    const joined = {
+        partyId: credential.partyId,
+        // None needed: the redemption retains the member that admits this app as a dial
+        // target in the party's bootstrap-peer store, which every later start reads.
+        bootstrapAddrs: [],
+        relayAddrs: options.relayAddrs ?? leaving?.relayAddrs ?? [],
+        origin: 'joined',
+    };
+    const noiseCryptoMode = options.noiseCryptoMode ?? leaving?.noiseCryptoMode;
+    if (noiseCryptoMode !== undefined)
+        joined.noiseCryptoMode = noiseCryptoMode;
+    if (formerPartyId !== undefined)
+        joined.formerPartyId = formerPartyId;
+    const movingFrom = founded ? await recordStrandMove(runtime, founded, credential) : undefined;
+    try {
+        await runtime.shutDown();
+        return await startAndRedeem(runtime, joined, credential, options, signal, movingFrom);
+    }
+    catch (err) {
+        await returnToLeftParty(runtime, restore, movingFrom);
+        throw err;
+    }
+}
+/**
+ * Export the founded party's strands and keep them in the key store for the joined party to
+ * adopt; the party's id when there was anything to move. Throws `StrandsNeedOwnerJoinError`, or
+ * the export's or the write's error: switching without the record would lose the strands.
+ * An empty export removes the party's record instead: one left by an earlier join that never
+ * finished describes strands the party no longer holds, and adopting it would bring them back.
+ */
+async function recordStrandMove(runtime, founded, credential) {
+    const running = runtime.node;
+    const bundle = running?.isRunning
+        ? await exportStrandBundle(running)
+        : await runtime.readAlone(founded, exportStrandBundle, 'export strands');
+    const record = joinMoveRecord(bundle, credential);
+    if (!record) {
+        await runtime.moves.remove(founded.partyId);
+        return undefined;
+    }
+    await runtime.moves.save(record);
+    return founded.partyId;
+}
+/**
+ * Admitted, the start is saved before the strands are adopted, so an app killed mid-adoption
+ * relaunches into the joined party and finishes the move there; `running` is reported after.
+ */
+async function startAndRedeem(runtime, joined, credential, options, signal, movingFrom) {
+    runtime.setStatus({ state: 'starting' });
+    const { node, resolved } = await runtime.bringUp(joined);
+    runtime.setStatus({ state: 'joining', node });
+    const admission = await redeemOnJoinedNode(runtime, node, credential, options, signal);
+    reportProgress(options, { state: 'admitted', asOwner: admission.asOwner });
+    const owner = await runtime.wireJoinedOwner(node, admission.asOwner);
+    await runtime.saveRunningStart(resolved);
+    if (movingFrom !== undefined && owner === 'enrolled')
+        reportProgress(options, { state: 'moving-strands' });
+    const strandMove = await settleJoinMove(runtime, node, resolved.formerPartyId, owner);
+    runtime.reportRunning(node, resolved, owner);
+    return joinResult(admission, resolved.formerPartyId, strandMove);
+}
+/**
+ * Redeem on the node started in the credential's party: a machine invitation admits the app, an
+ * owner grant makes it a machine and an owner (`CadreNode.joinWithOwnerGrant`).
+ *
+ * The grant seats the owner slot's key, created now when the slot is empty: the app's one owner
+ * key, which may already own the party the app founded and is leaving (one key, several cadres).
+ * A fresh key would need a second owner slot and a second signer per node, which the kits do not
+ * have, and replacing the slot's key would lose the left party, which a rollback restarts.
+ * Created before the redemption, the key stays in the slot when the join fails, an owner of
+ * nothing until the next founding or grant uses it.
+ */
+async function redeemOnJoinedNode(runtime, node, credential, options, signal) {
+    if (!isOwnerGrant(credential))
+        return redeemInvitation(node, credential, options, signal);
+    // NOTE: a rollback after the grant was redeemed but the self-invitation refused leaves the
+    // slot's key an owner of the credential's party while the app is back in the party it left;
+    // a later join there, with a machine invitation too, picks the ownership up through that key.
+    // NOTE: `joinWithOwnerGrant` already waits up to its own bound for the key's `OwnerKey` row
+    // and wires it; `wireJoinedOwner(node, true)` then asks again for up to the owner-step bound
+    // while it is still unwired, so a row that never arrives costs both waits before `timed-out`.
+    // If that shows up, carry `joined.ownerWired` in the admission and skip the second wait.
+    const joined = await node.joinWithOwnerGrant(credential, await runtime.ownerSlotSigner(), redeemOptions(options, signal));
+    return { peerId: joined.peerId, redeemedAt: joined.redeemedAt, asOwner: true };
+}
+async function redeemInvitation(node, invitation, options, signal) {
+    const redemption = await node.redeemCadreInvitation(invitation, redeemOptions(options, signal));
+    return { ...redemption, asOwner: false };
+}
+/**
+ * The move from `formerPartyId` as an admitted join reports it: adopted with every other move
+ * naming this party once the app's key is wired as its owner, deferred otherwise. Never throws:
+ * the app is admitted, and what is not adopted now is adopted by the next start.
+ */
+async function settleJoinMove(runtime, node, formerPartyId, owner) {
+    try {
+        if (owner === 'enrolled') {
+            const outcomes = await adoptMovesInto(node, runtime.moves);
+            return formerPartyId === undefined ? undefined : outcomes.get(formerPartyId);
+        }
+        const record = formerPartyId === undefined ? undefined : await runtime.moves.load(formerPartyId);
+        return record?.targetPartyId === node.partyId ? { state: 'deferred', reason: 'owner-key-not-wired' } : undefined;
+    }
+    catch (err) {
+        console.warn('[cadre-core/edge-node] reading the strand move records failed; the next start retries:', err);
+        return formerPartyId === undefined ? undefined : deferredOutcome(err);
+    }
+}
+/**
+ * After a failed join: discard the move record it wrote, stop the joined party's node and start
+ * again what ran before, if anything did.
+ */
+async function returnToLeftParty(runtime, restore, movingFrom) {
+    await discardStrandMove(runtime.moves, movingFrom);
+    try {
+        await runtime.shutDown();
+        if (restore)
+            await runtime.buildAndStart(restore);
+    }
+    catch (err) {
+        // The join's own error is the one its caller gets; this one is only logged.
+        console.warn('[cadre-core/edge-node] going back to the party a failed join left failed:', err);
+        if (runtime.status.state !== 'failed')
+            runtime.setStatus({ state: 'failed', error: toError(err) });
+    }
+}
+async function discardStrandMove(moves, fromPartyId) {
+    if (fromPartyId === undefined)
+        return;
+    try {
+        await moves.remove(fromPartyId);
+    }
+    catch (err) {
+        // Harmless when left: it names the party the join failed to reach, and the next join from
+        // this party replaces it.
+        console.warn(`[cadre-core/edge-node] could not discard the strand move record of party ${fromPartyId}:`, err);
+    }
+}
+/** Wait for a member: an app joining by invitation is often the only machine of the party up. The grant's options are the invitation's. */
+function redeemOptions(options, signal) {
+    return { waitForMember: true, signal, ...(options.onProgress ? { onProgress: options.onProgress } : {}) };
+}
+/** Tell the join's listener; one that throws must not fail a join a member has already admitted. */
+function reportProgress(options, progress) {
+    try {
+        options.onProgress?.(progress);
+    }
+    catch (err) {
+        console.warn('[cadre-core/edge-node] join progress listener threw:', err);
+    }
+}
+/**
+ * The start a join to `partyId` leaves, when it is of a party this app founded: the party whose
+ * strands move and which is kept as `formerPartyId` for clean-up. Null when the join leaves no
+ * start, a party this app joined, or the party it joins.
+ */
+function foundedPartyLeft(partyId, leaving) {
+    return leaving && leaving.origin !== 'joined' && leaving.partyId !== partyId ? leaving : null;
+}
+function joinResult(admission, formerPartyId, strandMove) {
+    return {
+        ...admission,
+        ...(formerPartyId !== undefined && { formerPartyId }),
+        ...(strandMove !== undefined && { strandMove }),
+    };
+}
+//# sourceMappingURL=edge-join.js.map

package/dist/edge-node/edge-join.js.map

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

package/dist/edge-node/edge-node.d.ts

@@ -0,0 +1,295 @@
+/**
+ * `createEdgeNode` — build, start, stop and rebuild an edge device's `CadreNode` the prescribed
+ * way: identity and owner key in the app's key store, the four node-local stores durable and
+ * party-scoped, raw storage per scope from the app's storage, owner genesis, the last start
+ * remembered for unattended starts, and the switch to another party's cadre by machine
+ * invitation or owner grant.
+ *
+ * Nothing platform-specific is imported here. The app passes in its key store, its storage and
+ * its transports (`EdgeNodePlatform`), so a Node test runs this code over fakes, and the React
+ * Native kit's `createPhoneNode` is this over the secure store and rn-leveldb.
+ */
+import { CadreNode } from '../cadre-node.js';
+import type { ExportedOwnerKey, ImportedOwnerKey, OwnerKeyExportOptions } from '../owner-key-flows.js';
+import { type StrandMoveReport } from '../strand-move.js';
+import type { DurableSlot } from '../node-local-snapshot.js';
+import type { CadreJoinProgress, CadreNodeEvents, CadreOwnerKey, CadreRemoval, CreateOwnerGrantOptions, CreateOwnerGrantResult, OwnerGrantStatus, OwnerKeyRemovalPlan, OwnerKeyRemovalResult, RedeemCadreInvitationResult, RemoveOwnerOptions } from '../types.js';
+import { type OwnerGenesisResult } from './config.js';
+import { type DissolveFormerPartyOptions } from './dissolve.js';
+import type { JoinCredential } from './join-credential.js';
+import { type KvStoreApi } from './node-local.js';
+import { type EdgeNodeOptions, type NoiseCryptoMode, type SavedStart } from './options.js';
+import { type RedeemedOwnerGrant } from './owner-grant.js';
+import { type EdgeNodePlatform } from './platform.js';
+import { type PendingStrandMove, type StrandMoveOutcome } from './strand-move.js';
+export type EdgeNodeStatus = {
+    state: 'stopped';
+} | {
+    state: 'starting';
+}
+/** Started in the party an invitation names and redeeming it there; not admitted yet, so `EdgeNode.node` is null. */
+ | {
+    state: 'joining';
+    node: CadreNode;
+} | {
+    state: 'running';
+    node: CadreNode;
+    owner: OwnerGenesisResult;
+}
+/**
+ * An owner of `partyId` removed this app from it: the node is stopped and the party's local
+ * storage deleted. `formerPartyId` is the party this app founded and left, which the saved start
+ * now names with `autoStart: false`; absent when there is none. `start` and `joinCadre` work as
+ * from `stopped`.
+ */
+ | {
+    state: 'removed';
+    partyId: string;
+    removal: CadreRemoval;
+    formerPartyId?: string;
+} | {
+    state: 'failed';
+    error: Error;
+};
+/** A join's progress: the redemption's passes and pauses, then the steps after a member admitted the app. */
+export type EdgeJoinProgress = CadreJoinProgress
+/**
+ * A member admitted the app; the edge node is wiring its owner key and saving the start.
+ * `asOwner`: the app joined with an owner grant, so its owner slot's key is an owner of the party.
+ */
+ | {
+    state: 'admitted';
+    asOwner: boolean;
+}
+/** The app's key is wired as an owner and the strands this join recorded are being adopted. */
+ | {
+    state: 'moving-strands';
+};
+/** How {@link EdgeNode.joinCadre} runs. */
+export interface JoinCadreOptions {
+    /** Relays the joined node reserves on. Default: the running start's, else the saved one's. */
+    relayAddrs?: string[];
+    /** Default: the running start's, else the saved one's, else the platform default. */
+    noiseCryptoMode?: NoiseCryptoMode;
+    /** Cancels the join: the app goes back to the party it left, and the call throws the signal's reason. */
+    signal?: AbortSignal;
+    /**
+     * Each redemption pass and each pause while no member is ready, for a "waiting for an always-on
+     * machine" display; then `admitted`, and `moving-strands` when this join's strands are adopted.
+     * A listener that throws is logged and ignored.
+     */
+    onProgress?: (progress: EdgeJoinProgress) => void;
+}
+/** What an admitted {@link EdgeNode.joinCadre} returns. */
+export interface JoinCadreResult extends RedeemCadreInvitationResult {
+    /** The app joined with an owner grant: its owner slot's key is an owner of the party (`status.owner` says whether it is wired). */
+    asOwner: boolean;
+    /** The party this app founded and has left, when it founded one; saved as `EdgeNodeOptions.formerPartyId`. */
+    formerPartyId?: string;
+    /** How moving that party's strands into this one settled; absent when there was nothing to move. */
+    strandMove?: StrandMoveOutcome;
+}
+/** A removal a dissolve marker names that the last start tried to finish and could not: {@link EdgeNode.unfinishedRemoval}. */
+export interface UnfinishedRemoval {
+    partyId: string;
+    error: Error;
+}
+export interface EdgeNode {
+    readonly status: EdgeNodeStatus;
+    /** The running node, or null; null as soon as a stop or restart begins tearing it down, and while joining. */
+    readonly node: CadreNode | null;
+    /** The options the running node was started with, the Noise mode resolved; null unless running. */
+    readonly options: EdgeNodeOptions | null;
+    /**
+     * The removal the dissolve marker names that the last start tried to finish and could not
+     * (logged there too), for an app to show; null when the last start found no marker or finished
+     * it, or a dissolve or removal since finished it. The next start retries.
+     */
+    readonly unfinishedRemoval: UnfinishedRemoval | null;
+    /**
+     * This app's peer id, the same in every party: the node's while one is running or joining,
+     * answered at once; otherwise read from the key store, created there when absent, in turn
+     * with start, stop and join so a first start cannot generate a different key. A read the
+     * key store refuses throws.
+     */
+    identityPeerId(): Promise<string>;
+    /**
+     * Start, or join the start in flight; a running node is returned as is, whatever its options.
+     * A start called during a stop or restart runs after it. Opens the four node-local stores
+     * party-scoped, builds and starts the node, runs owner genesis (fail-soft, bounded), then saves
+     * the options with `autoStart: true`. A failed start closes everything it opened and leaves
+     * `status` `failed`; the next call starts afresh.
+     */
+    start(options: EdgeNodeOptions): Promise<CadreNode>;
+    /**
+     * The user's "disconnect": waits for a start in flight, saves `autoStart: false` so nothing
+     * starts the node unattended, stops it, and closes every store it opened — control, each
+     * strand, node-local — through `EdgeNodeStorage.close`. A platform that locks a store per
+     * name (rn-leveldb) would otherwise fail the next start on one left open.
+     */
+    stop(): Promise<void>;
+    /**
+     * Rebuild the node with new options (relays, Noise mode): libp2p reads them only when the node
+     * is built. `autoStart` is not cleared on the way, so a crash mid-restart still starts again.
+     */
+    restart(options: EdgeNodeOptions): Promise<CadreNode>;
+    /**
+     * Join the cadre `credential` names: this app's one node moves to that party, keeping its
+     * identity, so the peer id an owner targeted is the one that redeems. A machine invitation
+     * admits the app as a machine; an owner grant makes it a machine and an owner at once
+     * (`CadreNode.joinWithOwnerGrant`), seating the owner slot's key, created when the slot is
+     * empty, which is how an app brings the strands of the party it founded along. Runs in turn
+     * with start, stop and restart; a start called meanwhile runs after it, and a `stop` cancels it.
+     *
+     * Already running in that party: redeems on the running node (a device already admitted is
+     * answered as such; an owner grant is redeemed for the slot's key, `CadreNode.redeemOwnerGrant`)
+     * and wires its owner key. Otherwise: stops the running node, starts one for the credential's
+     * party with `origin: 'joined'` (status `joining`), and redeems there, waiting for a member to
+     * answer until one accepts, one refuses, the credential expires (`invite-spent`,
+     * `grant-spent`) or `options.signal` aborts. Admitted: wires the owner key when the party
+     * lists the slot's key (after an owner grant, asking again until its row arrives or the
+     * owner-step bound passes), saves the start (`autoStart: true`) and reports `running`.
+     * Anything else: stops that node, starts again what was running before (a node that was
+     * stopped stays stopped), and throws the join's error; a failure restarting is logged and
+     * leaves status `failed`.
+     *
+     * The start is saved only once admitted, so an app killed while waiting relaunches into the
+     * party it left. The left party's data stays on disk under its own names.
+     *
+     * Leaving a party this app founded moves its strands: they are exported before anything stops
+     * (from a node started for the export alone when none runs) and kept in the key store, and
+     * adopted once the app's key is wired as an owner of the joined party, before the join reports
+     * `running`; otherwise a later start adopts them (`result.strandMove` says which). Refused
+     * before anything stops, with `StrandsNeedOwnerJoinError`, when there is something to move and
+     * the credential is a machine invitation; and with the export's error when it fails.
+     */
+    joinCadre(credential: JoinCredential, options?: JoinCadreOptions): Promise<JoinCadreResult>;
+    /**
+     * The move from `formerPartyId` (the running start's, else the saved one's) still waiting to be
+     * adopted, or `undefined` when there is none. A read the key store refuses throws.
+     */
+    pendingStrandMove(): Promise<PendingStrandMove | undefined>;
+    /**
+     * Adopt the waiting move on the running node now, in turn with start, stop and join; `undefined`
+     * when no move from `formerPartyId` names the running party. On a joined party with no owner
+     * signer wired, first asks the party once more whether it lists the owner slot's key, so an
+     * owner grant whose row arrived after the join stopped waiting is picked up here,
+     * `status.owner` becoming `enrolled`. Throws what the adoption throws,
+     * `StrandMoveNotOwnerError` while the app's key is no owner there.
+     */
+    finishStrandMove(): Promise<StrandMoveReport | undefined>;
+    /**
+     * Delete the local storage of `formerPartyId`, the party this app founded and left, once the
+     * running party holds everything it holds and no other machine is in it. Runs in turn with
+     * start, stop, restart and join. Stops the running node, reads the former party from a node
+     * started for that alone, and starts the running party again, without `formerPartyId` once the
+     * former party is removed; a failure of that last start is the call's error.
+     *
+     * Refused before anything stops: with an `Error` unless running with a `formerPartyId` other
+     * than the running party, and with `StrandMovePendingError` while a move from it waits. Refused
+     * after the read, the running party started again and nothing deleted: with
+     * `FormerPartyNotEmptyError`, whose strand and pending-join ids `options.discard` may give up.
+     */
+    dissolveFormerParty(options?: DissolveFormerPartyOptions): Promise<void>;
+    /**
+     * The last start, or `undefined` when none is saved or the record is unusable. A read fault
+     * throws. Called during a stop, it answers after the stop has saved `autoStart: false`; during
+     * the edge node's response to a removal, after that has replaced the saved start.
+     */
+    loadSavedStart(): Promise<SavedStart | undefined>;
+    /**
+     * The slot `LinkRequestStore` (`@serfab/cadre-rn/app-link`) keeps the open link join request in,
+     * beside the saved start in the node-local store. Works with no node running, as
+     * `loadSavedStart` does; a read fault throws.
+     */
+    linkRequestSlot(): DurableSlot;
+    /**
+     * The slot `AppRecommendationStore` (`@serfab/cadre-rn/app-link`) keeps the apps the user allowed
+     * to join before they asked in, beside the saved start. Works with no node running, as
+     * `linkRequestSlot` does; a read fault throws.
+     */
+    recommendationSlot(): DurableSlot;
+    /**
+     * The node-local store as a key-value store, for records the app keeps beside the saved start
+     * under keys of its own: `rentalStore` (`@serfab/cadre-rn/provider`) files the provider rentals
+     * here, under `rentalsKvKey(partyId)`. Works with no node running, as `linkRequestSlot` does; a
+     * read fault throws. Keys of the form `<record>.<partyId>` are the edge node's; an app's own
+     * records take a dot-free key.
+     */
+    nodeLocalRecords(): KvStoreApi;
+    /**
+     * Subscribe to a node event for the life of this edge node, not of one `CadreNode`: the
+     * handler is re-applied to every node a start or restart builds, before it starts. Register the
+     * `strand:discovered` handler that attaches strands here, before `start` — strands joined from
+     * another party come back through it after every start. Returns an unsubscribe.
+     */
+    on<K extends keyof CadreNodeEvents>(event: K, handler: (data: CadreNodeEvents[K]) => void): () => void;
+    onStatus(listener: (status: EdgeNodeStatus) => void): () => void;
+    /**
+     * The public key (base64url) of the owner key the running node signs with, for pairing and
+     * approval prompts: the owner slot's key. Null unless running with it wired. Never private
+     * material.
+     */
+    ownerPublicKey(): string | null;
+    /**
+     * The cadre's live owner keys (cadre-core's `CadreNode.listOwnerKeys`): label, voucher, whether
+     * this app holds it and whether this device trusts it. In turn with start, stop and join, as are
+     * the calls below; this one and every other that names the node throws while none is running.
+     */
+    listOwnerKeys(): Promise<CadreOwnerKey[]>;
+    /**
+     * This app's own owner key, from the key store's owner slot, which is the key the node signs
+     * with, as export text, with the key it holds (`publicKey`). Works with no node running. Throws
+     * when the slot is empty: a member holds no owner key of its own.
+     */
+    exportOwnerKey(options?: OwnerKeyExportOptions): Promise<ExportedOwnerKey>;
+    /**
+     * Import owner-key text into the owner slot, unlocking it with `passphrase` when it is locked.
+     * With a node running, the key is wired when the party lists it as a live owner (`wired`, and
+     * `status.owner` becomes `enrolled`); stored otherwise, and wired by a later start once an owner
+     * adds it. Works with no node running. Refused with `OwnerKeySlotOccupiedError` when the slot
+     * holds a different key (one owner key per app), and with `OwnerKeyExportError` for text that
+     * is not an owner key, a locked one with no passphrase (`passphrase-required`) or the wrong
+     * passphrase. A strand move waiting on an owner key is adopted by the next start or
+     * `finishStrandMove()`.
+     */
+    importOwnerKey(text: string, passphrase?: string): Promise<ImportedOwnerKey>;
+    /** What `removeOwner(key)` would do, for the confirmation step (cadre-core's `CadreNode.planOwnerKeyRemoval`). */
+    planOwnerKeyRemoval(key: string): Promise<OwnerKeyRemovalPlan>;
+    /** Remove an owner key, re-vouching first the dependents `options.revouch` keeps (cadre-core's `CadreNode.removeOwner`). */
+    removeOwner(key: string, options?: RemoveOwnerOptions): Promise<OwnerKeyRemovalResult>;
+    /**
+     * Mint an owner grant (cadre-core's `CadreNode.createOwnerGrant`): whoever redeems the
+     * returned text first becomes an owner of the cadre. 15 minutes and one use by default;
+     * `expiresInMs: null` is a backup grant, with no expiry.
+     */
+    createOwnerGrant(options?: CreateOwnerGrantOptions): Promise<CreateOwnerGrantResult>;
+    /** Every owner grant the running node holds, with its standing (cadre-core's `CadreNode.listOwnerGrants`). */
+    listOwnerGrants(): Promise<OwnerGrantStatus[]>;
+    /** Withdraw an owner grant by its key (cadre-core's `CadreNode.withdrawOwnerGrant`); false when it is not held here or was already withdrawn. */
+    withdrawOwnerGrant(key: string): Promise<boolean>;
+    /**
+     * Become an owner of the running party with owner-grant text: the owner slot's key, created
+     * when the slot is empty, is seated (cadre-core's `CadreNode.redeemOwnerGrant`) and wired, and
+     * `status.owner` becomes `enrolled`. A slot key that is already a live owner of the party is
+     * answered `alreadyOwner` before anything is signed or written, connected or not. A member
+     * machine writes the row in its own store and wires the key at once; any other node redeems
+     * at the grant's members and asks for the row until the owner-step bound passes (`wired:
+     * false` then, and a later start wires it). A strand move waiting on an owner key is adopted
+     * by the next start or `finishStrandMove()`.
+     *
+     * Refused with the decoder's error for text that is not an owner grant (an owner key, an
+     * invitation and a join request are named), with `OwnerGrantRejectedError` `party-mismatch`
+     * for a grant of another party, and with what `CadreNode.redeemOwnerGrant` throws:
+     * `OwnerKeyAddRefusedError` `alone` on a member with no connection to the party's other
+     * machines, `OwnerGrantRejectedError` (`grant-spent` for an expired, withdrawn or used grant),
+     * `OwnerGrantIssuerUnknownError`, `OwnerGrantUnreachableError`.
+     */
+    redeemOwnerGrant(text: string): Promise<RedeemedOwnerGrant>;
+}
+/**
+ * Create the app's edge node. Call once per app. Throws when an edge node over the same storage
+ * (`platform.storage.id`) is starting or running in this process; a stopped or failed one is
+ * replaced (a development reload re-runs the module that calls this).
+ */
+export declare function createEdgeNode(platform: EdgeNodePlatform): EdgeNode;