@serfab/cadre-core 1.13.0 → 1.15.0

package/dist/node-claim-payload.d.ts

@@ -0,0 +1,74 @@
+/** Version 1 of the payload; the only one either side reads. */
+export declare const NODE_CLAIM_PAYLOAD_PREFIX = "sereus-join:1.";
+export interface NodeClaimPayload {
+    /** The node's peer id. */
+    peerId: string;
+    /** Addresses the phone may dial the node at, each ending in `/p2p/<peerId>`. */
+    multiaddrs: string[];
+    /** The node's claim secret, base64url (`parseClaimSecret`). */
+    secret: string;
+}
+/** Encode a payload as the text the host shows. Refuses what {@link decodeNodeClaimPayload} would. */
+export declare function encodeNodeClaimPayload(payload: NodeClaimPayload): string;
+/**
+ * Decode the text a phone scanned or pasted. Refuses, naming the problem: any version but
+ * 1, a body that is not base64url JSON of the right shape, a peer id that does not parse,
+ * an empty address list, an address that does not parse or whose last `/p2p/` is not that
+ * peer id, and a secret {@link parseClaimSecret} refuses. The secret is never echoed.
+ */
+export declare function decodeNodeClaimPayload(text: string): NodeClaimPayload;
+/** How {@link selectNodeClaimAddresses} narrows a node's addresses. */
+export interface NodeClaimAddressOptions {
+    /**
+     * The machine's LAN address, the one a phone at home reaches it on. A string keeps only
+     * the private addresses on that IP (dropping Docker bridges, VPN and other interfaces no
+     * phone can reach); `null` drops every private address (a machine reached only by its
+     * public name); absent keeps them all, for a caller that cannot tell.
+     */
+    lan?: string | null;
+    /** Keep addresses a phone cannot dial: plain TCP. Default false, since phones dial WebSocket and relay only. */
+    includeTcp?: boolean;
+}
+/**
+ * The addresses a node code should carry, from the ones a node knows it has (`/status`,
+ * a NAT layer's public addresses). A phone dials them in turn, each on its own timeout, so
+ * every address it cannot reach only delays a failing claim, and makes the QR code bigger.
+ *
+ * - Each gains `/p2p/<peerId>` when it lacks a destination; loopback, unspecified and
+ *   unparsable ones are dropped, and so is plain TCP unless `includeTcp`.
+ * - Public names (`/dns*`) come first: they work away from home. Public IP addresses are
+ *   kept only when there is no public name, since they reach the same machine.
+ * - Private addresses follow, narrowed by {@link NodeClaimAddressOptions.lan}; relay
+ *   addresses last.
+ *
+ * Pure and dependency-light, like the codec beside it, so it loads on React Native too.
+ * Finding the LAN address is the caller's (Node: `@serfab/cadre-core/primary-lan-address`).
+ */
+export declare function selectNodeClaimAddresses(reported: readonly string[], peerId: string, options?: NodeClaimAddressOptions): string[];
+/**
+ * `addr` as a node code carries it: with `/p2p/<peerId>` appended unless it already names a
+ * destination. A relay address that ends at its hop (`…/p2p/<relay>/p2p-circuit`) names none,
+ * so it gains the node's id too. Throws when `addr` does not parse. For callers that take
+ * exact addresses from an operator; {@link selectNodeClaimAddresses} applies it itself.
+ */
+export declare function withClaimDestination(addr: string, peerId: string): string;
+/**
+ * Where a phone could dial an address from: a relayed address (`/p2p-circuit`), a public name,
+ * a public IP, a private (LAN, VPN, link-local) IP, or this machine's own loopback.
+ */
+export type DialAddressKind = 'relay' | 'name' | 'public' | 'private' | 'loopback';
+/**
+ * Classify `addr` for a phone dialing it, or undefined when no phone can dial it at all: it
+ * does not parse, names the unspecified address, or is plain TCP without `includeTcp` (phones
+ * dial WebSocket and relay only).
+ */
+export declare function classifyDialAddress(addr: string, options?: {
+    includeTcp?: boolean;
+}): DialAddressKind | undefined;
+/**
+ * The peer an address reaches: its last `/p2p/` component. A relayed address
+ * (`…/p2p/<relay>/p2p-circuit/p2p/<destination>`) names its destination after the
+ * circuit hop; one that ends at the hop names nobody. Same rule as
+ * `groupAddrsByPeerId` in `peer-addr-book.ts`. Throws when `addr` does not parse.
+ */
+export declare function destinationPeerIdOf(addr: string): string | null;

package/dist/node-claim-payload.js

@@ -0,0 +1,224 @@
+/**
+ * The claim payload: what a host shows as a QR code (and as text) for a node that is
+ * waiting to be claimed, and what the owner's phone scans to claim it.
+ *
+ * `sereus-join:1.<base64url of canonical JSON>` where the JSON is
+ * `{ multiaddrs, peerId, secret }`: the node's peer id, every address the phone may
+ * dial it at (each ending in `/p2p/<peerId>`), and the node's one-time claim secret
+ * (`claim-proof.ts`). The phone hands all three to `CadreNode.claimNode`. The payload
+ * carries no party id: the claim supplies it, and the node records it.
+ *
+ * The decoder lives here, beside the encoder, because the phone and the host both need
+ * it and neither depends on the other. Imports only `@multiformats/multiaddr`,
+ * `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the browser.
+ */
+import { peerIdFromString } from '@libp2p/peer-id';
+import { multiaddr, CODE_DNS, CODE_DNS4, CODE_DNS6, CODE_DNSADDR, CODE_IP4, CODE_IP6, CODE_IP6ZONE, CODE_P2P, CODE_P2P_CIRCUIT, CODE_WS, CODE_WSS, } from '@multiformats/multiaddr';
+import { fromString as uint8ArrayFromString, toString as uint8ArrayToString } from 'uint8arrays';
+import { canonicalJson } from './canonical-json.js';
+import { parseClaimSecret } from './claim-proof.js';
+/** Version 1 of the payload; the only one either side reads. */
+export const NODE_CLAIM_PAYLOAD_PREFIX = 'sereus-join:1.';
+/** Encode a payload as the text the host shows. Refuses what {@link decodeNodeClaimPayload} would. */
+export function encodeNodeClaimPayload(payload) {
+    const checked = requireNodeClaimPayload(payload);
+    const json = canonicalJson({ multiaddrs: checked.multiaddrs, peerId: checked.peerId, secret: checked.secret });
+    return `${NODE_CLAIM_PAYLOAD_PREFIX}${uint8ArrayToString(new TextEncoder().encode(json), 'base64url')}`;
+}
+/**
+ * Decode the text a phone scanned or pasted. Refuses, naming the problem: any version but
+ * 1, a body that is not base64url JSON of the right shape, a peer id that does not parse,
+ * an empty address list, an address that does not parse or whose last `/p2p/` is not that
+ * peer id, and a secret {@link parseClaimSecret} refuses. The secret is never echoed.
+ */
+export function decodeNodeClaimPayload(text) {
+    const trimmed = text.trim();
+    if (!trimmed.startsWith(NODE_CLAIM_PAYLOAD_PREFIX)) {
+        throw new Error(`A claim payload must start with "${NODE_CLAIM_PAYLOAD_PREFIX}" (this one starts with "${trimmed.slice(0, NODE_CLAIM_PAYLOAD_PREFIX.length)}")`);
+    }
+    let parsed;
+    try {
+        const json = new TextDecoder().decode(uint8ArrayFromString(trimmed.slice(NODE_CLAIM_PAYLOAD_PREFIX.length), 'base64url'));
+        parsed = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error('A claim payload must carry base64url-encoded JSON after its prefix', { cause: error });
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('A claim payload must decode to a JSON object');
+    }
+    const { peerId, multiaddrs, secret } = parsed;
+    if (typeof peerId !== 'string')
+        throw new Error('A claim payload must name the node\'s peer id');
+    if (!Array.isArray(multiaddrs) || !multiaddrs.every((a) => typeof a === 'string')) {
+        throw new Error('A claim payload must carry the node\'s addresses as a list of strings');
+    }
+    if (typeof secret !== 'string')
+        throw new Error('A claim payload must carry the claim secret');
+    return requireNodeClaimPayload({ peerId, multiaddrs, secret });
+}
+/**
+ * The addresses a node code should carry, from the ones a node knows it has (`/status`,
+ * a NAT layer's public addresses). A phone dials them in turn, each on its own timeout, so
+ * every address it cannot reach only delays a failing claim, and makes the QR code bigger.
+ *
+ * - Each gains `/p2p/<peerId>` when it lacks a destination; loopback, unspecified and
+ *   unparsable ones are dropped, and so is plain TCP unless `includeTcp`.
+ * - Public names (`/dns*`) come first: they work away from home. Public IP addresses are
+ *   kept only when there is no public name, since they reach the same machine.
+ * - Private addresses follow, narrowed by {@link NodeClaimAddressOptions.lan}; relay
+ *   addresses last.
+ *
+ * Pure and dependency-light, like the codec beside it, so it loads on React Native too.
+ * Finding the LAN address is the caller's (Node: `@serfab/cadre-core/primary-lan-address`).
+ */
+export function selectNodeClaimAddresses(reported, peerId, options = {}) {
+    const names = [];
+    const publicIps = [];
+    const privates = [];
+    const relayed = [];
+    for (const raw of reported) {
+        const classified = classifyClaimAddress(raw.trim(), peerId, options);
+        if (!classified)
+            continue;
+        ({ name: names, public: publicIps, private: privates, relay: relayed })[classified.kind].push(classified.addr);
+    }
+    return [...new Set([...names, ...(names.length > 0 ? [] : publicIps), ...privates, ...relayed])];
+}
+/**
+ * `addr` as a node code carries it: with `/p2p/<peerId>` appended unless it already names a
+ * destination. A relay address that ends at its hop (`…/p2p/<relay>/p2p-circuit`) names none,
+ * so it gains the node's id too. Throws when `addr` does not parse. For callers that take
+ * exact addresses from an operator; {@link selectNodeClaimAddresses} applies it itself.
+ */
+export function withClaimDestination(addr, peerId) {
+    const trimmed = addr.trim();
+    return destinationPeerIdOf(trimmed) === null ? `${trimmed}/p2p/${peerId}` : trimmed;
+}
+/**
+ * Classify `addr` for a phone dialing it, or undefined when no phone can dial it at all: it
+ * does not parse, names the unspecified address, or is plain TCP without `includeTcp` (phones
+ * dial WebSocket and relay only).
+ */
+export function classifyDialAddress(addr, options = {}) {
+    const components = componentsOf(addr);
+    return components ? classifyComponents(components, options.includeTcp ?? false)?.kind : undefined;
+}
+function componentsOf(addr) {
+    try {
+        return multiaddr(addr).getComponents();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** {@link classifyDialAddress}, keeping the IP for a caller that narrows private addresses by it. */
+function classifyComponents(components, includeTcp) {
+    if (components.some((c) => c.code === CODE_P2P_CIRCUIT))
+        return { kind: 'relay' };
+    if (!includeTcp && !components.some((c) => c.code === CODE_WS || c.code === CODE_WSS))
+        return undefined;
+    const host = components[0];
+    if (!host?.value)
+        return undefined;
+    if (host.code === CODE_DNS || host.code === CODE_DNS4 || host.code === CODE_DNS6 || host.code === CODE_DNSADDR) {
+        return { kind: host.value === 'localhost' ? 'loopback' : 'name' };
+    }
+    if (host.code !== CODE_IP4 && host.code !== CODE_IP6 && host.code !== CODE_IP6ZONE)
+        return undefined;
+    const ip = host.code === CODE_IP6ZONE ? components[1]?.value ?? '' : host.value;
+    if (ip === '0.0.0.0' || ip === '::')
+        return undefined;
+    if (ip.startsWith('127.') || ip === '::1')
+        return { kind: 'loopback', ip };
+    if (host.code !== CODE_IP6ZONE && !isPrivateIp(ip))
+        return { kind: 'public', ip };
+    return { kind: 'private', ip };
+}
+/** One address's place in {@link selectNodeClaimAddresses}, or undefined to drop it. */
+function classifyClaimAddress(addr, peerId, options) {
+    const components = componentsOf(addr);
+    if (!components)
+        return undefined;
+    const classified = classifyComponents(components, options.includeTcp ?? false);
+    if (!classified || classified.kind === 'loopback')
+        return undefined;
+    if (classified.kind === 'private' && (options.lan === null || (options.lan !== undefined && classified.ip !== options.lan))) {
+        return undefined;
+    }
+    return { kind: classified.kind, addr: destinationIn(components) === null ? `${addr}/p2p/${peerId}` : addr };
+}
+/** RFC 1918, carrier-grade NAT (100.64/10), link-local, and IPv6 unique-local / link-local. */
+function isPrivateIp(ip) {
+    if (ip.includes(':'))
+        return /^(f[cd]|fe[89ab])/i.test(ip);
+    const [a, b] = ip.split('.').map(Number);
+    return a === 10
+        || (a === 172 && b >= 16 && b <= 31)
+        || (a === 192 && b === 168)
+        || (a === 169 && b === 254)
+        || (a === 100 && b >= 64 && b <= 127);
+}
+/** The shape rules both directions apply. Returns the payload with its fields trimmed. */
+function requireNodeClaimPayload(payload) {
+    const peerId = parsePeerId(payload.peerId);
+    const multiaddrs = payload.multiaddrs.map((a) => a.trim());
+    if (multiaddrs.length === 0)
+        throw new Error('A claim payload must carry at least one address for the node');
+    for (const addr of multiaddrs)
+        requireAddressOf(addr, peerId);
+    // The secret is checked, never kept in a message: see `parseClaimSecret`.
+    parseClaimSecret(payload.secret);
+    return { peerId: peerId.toString(), multiaddrs, secret: payload.secret.trim() };
+}
+function parsePeerId(text) {
+    try {
+        return peerIdFromString(text.trim());
+    }
+    catch (error) {
+        throw new Error(`A claim payload's peer id does not parse ("${text}")`, { cause: error });
+    }
+}
+/** `addr` parses, and its destination (the last `/p2p/`, past any relay hop) is `peerId`. */
+function requireAddressOf(addr, peerId) {
+    let destination;
+    try {
+        destination = destinationPeerIdOf(addr);
+    }
+    catch (error) {
+        throw new Error(`A claim payload address does not parse ("${addr}")`, { cause: error });
+    }
+    if (destination === null) {
+        throw new Error(`A claim payload address must end in /p2p/${peerId.toString()} ("${addr}" names no peer)`);
+    }
+    let named;
+    try {
+        named = peerIdFromString(destination);
+    }
+    catch (error) {
+        throw new Error(`A claim payload address names a peer id that does not parse ("${addr}")`, { cause: error });
+    }
+    if (!named.equals(peerId)) {
+        throw new Error(`A claim payload address names another peer ("${addr}" is not an address of ${peerId.toString()})`);
+    }
+}
+/**
+ * The peer an address reaches: its last `/p2p/` component. A relayed address
+ * (`…/p2p/<relay>/p2p-circuit/p2p/<destination>`) names its destination after the
+ * circuit hop; one that ends at the hop names nobody. Same rule as
+ * `groupAddrsByPeerId` in `peer-addr-book.ts`. Throws when `addr` does not parse.
+ */
+export function destinationPeerIdOf(addr) {
+    return destinationIn(multiaddr(addr).getComponents());
+}
+function destinationIn(components) {
+    for (let i = components.length - 1; i >= 0; i--) {
+        const component = components[i];
+        if (component.code === CODE_P2P_CIRCUIT)
+            return null;
+        if (component.code === CODE_P2P && component.value)
+            return component.value;
+    }
+    return null;
+}
+//# sourceMappingURL=node-claim-payload.js.map

package/dist/node-claim-payload.js.map

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

package/dist/node-default-transports.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Node-only: `@optimystic/db-p2p`'s default transport list, for `NetworkConfig.defaultTransports`.
+ *
+ * A node with configured relays is built from an explicit transport list, so that libp2p's relay
+ * discovery can be switched off in it (`node-transports.ts`). A Node host that supplies no
+ * `network.transports` passes this function so that list still matches what db-p2p would have
+ * built. A subpath module (`@serfab/cadre-core/node-default-transports`), like `push-node`,
+ * because it names `@libp2p/tcp`: some bundlers (the NativeScript reference app's webpack) take
+ * its Node implementation rather than its browser stub, and that needs `net`, `os` and `path`.
+ */
+import type { Libp2pTransports } from '@optimystic/db-p2p';
+import type { ListenTransportOptions } from './relay-addrs.js';
+/**
+ * TCP, WebSocket exactly when the node's listen entries switch it on, and the circuit-relay
+ * transport.
+ *
+ * Passing an explicit list makes db-p2p ignore `wsPort` for transports, which is why WebSocket is
+ * decided here from the same switch. Its other use of `wsPort`, a default WebSocket listen
+ * address, never applies: a node with configured relays always has explicit listen entries.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s default list in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (cadre never sets its `disableTcp`). That file
+ * is the source of truth; if its defaults change, this list has to follow. If db-p2p ever takes an
+ * option to build its default list with relay discovery off, use that and drop this module and
+ * `NetworkConfig.defaultTransports`.
+ */
+export declare function nodeDefaultTransports({ wsPort }: ListenTransportOptions): Libp2pTransports;

package/dist/node-default-transports.js

@@ -0,0 +1,35 @@
+/**
+ * Node-only: `@optimystic/db-p2p`'s default transport list, for `NetworkConfig.defaultTransports`.
+ *
+ * A node with configured relays is built from an explicit transport list, so that libp2p's relay
+ * discovery can be switched off in it (`node-transports.ts`). A Node host that supplies no
+ * `network.transports` passes this function so that list still matches what db-p2p would have
+ * built. A subpath module (`@serfab/cadre-core/node-default-transports`), like `push-node`,
+ * because it names `@libp2p/tcp`: some bundlers (the NativeScript reference app's webpack) take
+ * its Node implementation rather than its browser stub, and that needs `net`, `os` and `path`.
+ */
+import { tcp } from '@libp2p/tcp';
+import { webSockets } from '@libp2p/websockets';
+import { circuitRelayTransport } from '@libp2p/circuit-relay-v2';
+/**
+ * TCP, WebSocket exactly when the node's listen entries switch it on, and the circuit-relay
+ * transport.
+ *
+ * Passing an explicit list makes db-p2p ignore `wsPort` for transports, which is why WebSocket is
+ * decided here from the same switch. Its other use of `wsPort`, a default WebSocket listen
+ * address, never applies: a node with configured relays always has explicit listen entries.
+ *
+ * NOTE: mirrors `createLibp2pNode`'s default list in
+ * `../optimystic/packages/db-p2p/src/libp2p-node.ts` (cadre never sets its `disableTcp`). That file
+ * is the source of truth; if its defaults change, this list has to follow. If db-p2p ever takes an
+ * option to build its default list with relay discovery off, use that and drop this module and
+ * `NetworkConfig.defaultTransports`.
+ */
+export function nodeDefaultTransports({ wsPort }) {
+    return [
+        tcp(),
+        ...(wsPort === undefined ? [] : [webSockets()]),
+        circuitRelayTransport()
+    ];
+}
+//# sourceMappingURL=node-default-transports.js.map

package/dist/node-default-transports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-default-transports.js","sourceRoot":"","sources":["../src/node-default-transports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,GAAG,EAAE,MAAM,aAAa,CAAC;AAClC,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAChD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAIjE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,qBAAqB,CAAC,EAAE,MAAM,EAA0B;IACtE,OAAO;QACL,GAAG,EAAE;QACL,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC;QAC/C,qBAAqB,EAAE;KACxB,CAAC;AACJ,CAAC"}

package/dist/node-transports.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `transports` option for a cadre-built libp2p node, control and strand alike.
+ *
+ * A node whose bare `/p2p-circuit` search entries cadre generated for configured relays gets its
+ * transports through {@link withoutRelayDiscovery}, so libp2p's relay discovery cannot hand those
+ * slots to some other relay-capable peer before the per-relay supervisors fill them (see
+ * `relay-reservation.ts`, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other node gets
+ * the embedder's list as it was, or no option at all, and `@optimystic/db-p2p` builds its own
+ * default list.
+ *
+ * The wrapper needs a list to wrap. React Native and browser embedders always supply one
+ * (`network.transports`); a Node host supplies the default list through
+ * `network.defaultTransports` instead, since db-p2p builds its default internally and it names
+ * `@libp2p/tcp`, which this module's graph must not reach (`node-default-transports.ts`).
+ */
+import type { Libp2pTransports } from '@optimystic/db-p2p';
+import type { ListenTransportOptions } from './relay-addrs.js';
+import type { NetworkConfig } from './types.js';
+/**
+ * The `transports` option to spread into a node's `createLibp2pNode` options.
+ *
+ * @param listenTransports what the node's resolved listen entries imply (`resolveTransportOptions`
+ *   in `relay-addrs.ts`), handed to `network.defaultTransports`.
+ * @param relaySlotsSupervised whether cadre generated this node's bare `/p2p-circuit` entries for
+ *   configured relays and runs a supervisor over them — `network.relayAddrs` on the control node,
+ *   a non-empty relay list from `strandNodeAddrs` on a strand node.
+ */
+export declare function nodeTransportsOption(network: NetworkConfig | undefined, listenTransports: ListenTransportOptions, relaySlotsSupervised: boolean): {
+    transports?: Libp2pTransports;
+};

package/dist/node-transports.js

@@ -0,0 +1,40 @@
+/**
+ * The `transports` option for a cadre-built libp2p node, control and strand alike.
+ *
+ * A node whose bare `/p2p-circuit` search entries cadre generated for configured relays gets its
+ * transports through {@link withoutRelayDiscovery}, so libp2p's relay discovery cannot hand those
+ * slots to some other relay-capable peer before the per-relay supervisors fill them (see
+ * `relay-reservation.ts`, "WHY LIBP2P'S RELAY DISCOVERY IS SWITCHED OFF"). Every other node gets
+ * the embedder's list as it was, or no option at all, and `@optimystic/db-p2p` builds its own
+ * default list.
+ *
+ * The wrapper needs a list to wrap. React Native and browser embedders always supply one
+ * (`network.transports`); a Node host supplies the default list through
+ * `network.defaultTransports` instead, since db-p2p builds its default internally and it names
+ * `@libp2p/tcp`, which this module's graph must not reach (`node-default-transports.ts`).
+ */
+import debug from 'debug';
+import { withoutRelayDiscovery } from './relay-reservation.js';
+const log = debug('sereus:cadre:node-transports');
+/**
+ * The `transports` option to spread into a node's `createLibp2pNode` options.
+ *
+ * @param listenTransports what the node's resolved listen entries imply (`resolveTransportOptions`
+ *   in `relay-addrs.ts`), handed to `network.defaultTransports`.
+ * @param relaySlotsSupervised whether cadre generated this node's bare `/p2p-circuit` entries for
+ *   configured relays and runs a supervisor over them — `network.relayAddrs` on the control node,
+ *   a non-empty relay list from `strandNodeAddrs` on a strand node.
+ */
+export function nodeTransportsOption(network, listenTransports, relaySlotsSupervised) {
+    if (!relaySlotsSupervised) {
+        return network?.transports ? { transports: network.transports } : {};
+    }
+    const transports = network?.transports ?? network?.defaultTransports?.(listenTransports);
+    if (transports === undefined) {
+        log('Relays are configured but no transport list was supplied (network.transports or ' +
+            'network.defaultTransports); libp2p relay discovery stays on and can take their slots');
+        return {};
+    }
+    return { transports: withoutRelayDiscovery(transports) };
+}
+//# sourceMappingURL=node-transports.js.map

package/dist/node-transports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-transports.js","sourceRoot":"","sources":["../src/node-transports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,OAAO,CAAC;AAE1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AAI/D,MAAM,GAAG,GAAG,KAAK,CAAC,8BAA8B,CAAC,CAAC;AAElD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAkC,EAClC,gBAAwC,EACxC,oBAA6B;IAE7B,IAAI,CAAC,oBAAoB,EAAE,CAAC;QAC1B,OAAO,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACvE,CAAC;IACD,MAAM,UAAU,GAAG,OAAO,EAAE,UAAU,IAAI,OAAO,EAAE,iBAAiB,EAAE,CAAC,gBAAgB,CAAC,CAAC;IACzF,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,GAAG,CAAC,kFAAkF;YACpF,sFAAsF,CAAC,CAAC;QAC1F,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,EAAE,UAAU,EAAE,qBAAqB,CAAC,UAAU,CAAC,EAAE,CAAC;AAC3D,CAAC"}

package/dist/owner-anchor-sync.d.ts

@@ -0,0 +1,22 @@
+import type { TrustSource } from './trusted-owner-store.js';
+import type { InvitationChain, OwnerKeyRow, RevocationRow } from './types.js';
+export interface OwnerAnchorInputs {
+    /** The party whose table is being read; every stored proof is judged for it, so a voucher or tombstone signed for another party neither seats nor removes a key. */
+    partyId: string;
+    /** The anchor at the start of the pass, every key with its provenance (`TrustedOwnerStore.sources`). */
+    anchor: ReadonlyMap<string, TrustSource>;
+    /** `OwnerKey` rows as read; rows whose stamp a tombstone in `tombstones` retires are dropped here too. */
+    rows: readonly OwnerKeyRow[];
+    /** `Revocation` rows; only those with `tableName === 'OwnerKey'` are consulted. */
+    tombstones: readonly RevocationRow[];
+    /** The usage and invitation rows, when some owner row is invitation-admitted; null skips those rows. */
+    chain: InvitationChain | null;
+}
+export interface OwnerAnchorDerivation {
+    /** The keys the anchor should hold after this pass. */
+    target: ReadonlySet<string>;
+    /** Keys whose verifiable removal was NOT applied because the anchor would have emptied. */
+    refusedRemovals: readonly string[];
+}
+/** The rule above, as one pure function. */
+export declare function deriveOwnerAnchor({ partyId, anchor, rows, tombstones, chain }: OwnerAnchorInputs): OwnerAnchorDerivation;

package/dist/owner-anchor-sync.js

@@ -0,0 +1,143 @@
+/**
+ * How the node-local trusted-owner anchor follows the replicated `OwnerKey` table along
+ * VERIFIABLE chains — the pure rule, with no I/O, so it can be tested without a database.
+ * `CadreNode.syncOwnerAnchor` reads the table, the tombstones and the invitation chain,
+ * calls {@link deriveOwnerAnchor}, and applies the difference to the store.
+ *
+ * Why not simply trust the table: an empty local copy can seat any key through the
+ * schema's genesis branch and that row replicates (`docs/architecture.md` → "Node-local
+ * trusted-owner anchor"). So every node grows its anchor only through rows whose stored
+ * proof verifies against a key it already trusts, on every membership refresh. The terms
+ * used throughout:
+ *
+ * - **base**: the anchor's entries whose provenance is not `chain` (trusted out of band).
+ * - **live row**: an `OwnerKey` row whose stamp no tombstone retires.
+ * - **kept**: a `chain` entry that still has a live row. A derived entry is state, not
+ *   recomputed from the base each pass: it entered through a proof that verified then, and
+ *   it stays until its own row is retired or a verifiable tombstone removes it. This is what
+ *   lets an owner rotate (A adds A', A' removes A): A' keeps its place after A's row is
+ *   retired, although nothing could re-derive it from the remaining base.
+ * - **derivable from S**: a live row whose stored proof verifies against S — owner-signed
+ *   (`vouchSig` set): `vouchOwner` is in S and `verifyOwnerKeyVoucher` holds;
+ *   invitation-admitted (`vouchSig` null, `vouchUsage` set): `verifyInvitationOwnerAdmission`
+ *   holds with S as the anchor. The founding row (all three null) is never derivable:
+ *   founders enter anchors only out of band.
+ * - **derived**: the least fixpoint from base ∪ kept — add every key whose live row is
+ *   derivable from what is already in the set, until nothing changes. **chainDerived** is the
+ *   keys whose live row was derivable in this pass, base keys included.
+ * - **removed**: a key K in derived is removed when an `OwnerKey` tombstone names K, its
+ *   signer is in derived and is not K, its stored signature verifies
+ *   (`verifyRevocationSigner`), AND K is not in chainDerived. The last condition is what
+ *   makes a re-add win over an older tombstone: a removed owner re-added under a fresh
+ *   stamp has a live derivable row again, and the old stamp's tombstone no longer applies.
+ * - **target** = derived minus removed. If that would be empty, no removal is applied this
+ *   pass (target = derived) and the refused removals are reported for the caller to log.
+ *
+ * Every tombstone is judged against the pass-start set (derived) at once, so the outcome
+ * does not depend on the order they are read in: a signer that is itself removed in this
+ * pass still counts, and a mutual removal of the last two owners is refused rather than
+ * decided by read order.
+ *
+ * An owner C that a removed owner B had added therefore stays where it was already derived
+ * (its row is live) and cannot be derived on a machine that never held it (the chain from
+ * that machine's base runs through B's retired row) until a remaining owner re-adds it or
+ * an invitation pins it there. The rotation case above is the same shape with C = A', so the
+ * two cannot be told apart from replicated state; keeping is the only rule under which a
+ * sole owner can rotate at all.
+ */
+import { verifyInvitationOwnerAdmission, verifyOwnerKeyVoucher, verifyRevocationSigner } from './peer-authorization.js';
+/** The rule above, as one pure function. */
+export function deriveOwnerAnchor({ partyId, anchor, rows, tombstones, chain }) {
+    const ownerTombstones = tombstones.filter(tombstone => tombstone.tableName === 'OwnerKey');
+    // NOTE: a stamp is retired by any tombstone that names it, verified or not — the same
+    // reading `queryCadrePeers` and `getOwnerKeys` give the table. A forged tombstone can
+    // therefore prune a derived entry (its row goes) but never seat or keep one; if tombstone
+    // pollution is ever closed at the write side, judge retirement by the verified signer too.
+    const retired = new Set(ownerTombstones.map(tombstone => tombstone.stampId));
+    const liveRows = rows.filter(row => !retired.has(row.stampId));
+    const derived = passStartSet(anchor, liveRows);
+    const chainDerived = deriveFixpoint(partyId, derived, liveRows, chain);
+    const removed = removedKeys(partyId, derived, chainDerived, ownerTombstones);
+    if (removed.size > 0 && removed.size === derived.size) {
+        return { target: derived, refusedRemovals: Array.from(removed) };
+    }
+    const target = new Set(Array.from(derived).filter(key => !removed.has(key)));
+    return { target, refusedRemovals: [] };
+}
+/** base ∪ kept: every out-of-band entry, and every `chain` entry whose row is still live. */
+function passStartSet(anchor, liveRows) {
+    const liveKeys = new Set(liveRows.map(row => row.key));
+    const start = new Set();
+    for (const [key, source] of anchor) {
+        if (source !== 'chain' || liveKeys.has(key)) {
+            start.add(key);
+        }
+    }
+    return start;
+}
+/**
+ * Grow `derived` to the least fixpoint and return chainDerived: every key whose live row was
+ * derivable. A row is judged once its voucher is in the set, and settled either way then:
+ * trust only grows within a pass, and a proof that failed against a trusted voucher cannot
+ * pass later, so no row is verified twice.
+ */
+function deriveFixpoint(partyId, derived, liveRows, chain) {
+    const chainDerived = new Set();
+    const pending = new Set(liveRows);
+    let progress = true;
+    while (progress) {
+        progress = false;
+        for (const row of pending) {
+            if (row.vouchOwner === null || !derived.has(row.vouchOwner)) {
+                continue;
+            }
+            pending.delete(row);
+            if (proofVerifies(partyId, row, derived, chain)) {
+                chainDerived.add(row.key);
+                derived.add(row.key);
+                progress = true;
+            }
+        }
+    }
+    return chainDerived;
+}
+/** Does `row`'s stored proof verify against `trusted`, for `partyId`, by the kind of proof it carries (see the module doc)? */
+function proofVerifies(partyId, row, trusted, chain) {
+    if (row.vouchOwner === null) {
+        return false;
+    }
+    if (row.vouchSig !== null) {
+        return verifyOwnerKeyVoucher(partyId, row.key, row.stampId, row.vouchOwner, row.vouchSig);
+    }
+    if (row.vouchUsage === null) {
+        return false;
+    }
+    const usage = chain?.usages.get(row.vouchUsage);
+    const invite = usage === undefined ? undefined : chain?.invites.get(usage.inviteKey);
+    if (usage === undefined || invite === undefined) {
+        return false;
+    }
+    return verifyInvitationOwnerAdmission(partyId, row, usage, invite, key => trusted.has(key));
+}
+/**
+ * The keys of `derived` that a verifiable tombstone removes (see the module doc), every
+ * tombstone judged against the same pass-start set. A tombstone for a key outside `derived`
+ * changes nothing and is skipped before any signature work.
+ */
+function removedKeys(partyId, derived, chainDerived, ownerTombstones) {
+    const removed = new Set();
+    for (const tombstone of ownerTombstones) {
+        const key = tombstone.rowKey;
+        if (!derived.has(key) || chainDerived.has(key) || removed.has(key)) {
+            continue;
+        }
+        if (tombstone.signerKey === key || !derived.has(tombstone.signerKey)) {
+            continue;
+        }
+        if (verifyRevocationSigner(partyId, tombstone)) {
+            removed.add(key);
+        }
+    }
+    return removed;
+}
+//# sourceMappingURL=owner-anchor-sync.js.map

package/dist/owner-anchor-sync.js.map

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