@serfab/cadre-core 1.14.0 → 1.15.0

package/src/node-claim-payload.ts

@@ -13,7 +13,20 @@
  * `@libp2p/peer-id` and `uint8arrays`, so it loads on React Native and in the browser.
  */
 import { peerIdFromString } from '@libp2p/peer-id';
-import { multiaddr, CODE_P2P, CODE_P2P_CIRCUIT } from '@multiformats/multiaddr';
+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';
@@ -67,6 +80,124 @@ export function decodeNodeClaimPayload(text: string): NodeClaimPayload {
 	return requireNodeClaimPayload({ peerId, multiaddrs, secret });
 }
 
+/** 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 function selectNodeClaimAddresses(reported: readonly string[], peerId: string, options: NodeClaimAddressOptions = {}): string[] {
+	const names: string[] = [];
+	const publicIps: string[] = [];
+	const privates: string[] = [];
+	const relayed: string[] = [];
+	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: string, peerId: string): string {
+	const trimmed = addr.trim();
+	return destinationPeerIdOf(trimmed) === null ? `${trimmed}/p2p/${peerId}` : trimmed;
+}
+
+/**
+ * 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 function classifyDialAddress(addr: string, options: { includeTcp?: boolean } = {}): DialAddressKind | undefined {
+	const components = componentsOf(addr);
+	return components ? classifyComponents(components, options.includeTcp ?? false)?.kind : undefined;
+}
+
+type AddressComponents = ReturnType<ReturnType<typeof multiaddr>['getComponents']>;
+
+function componentsOf(addr: string): AddressComponents | undefined {
+	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: AddressComponents, includeTcp: boolean): { kind: DialAddressKind; ip?: string } | undefined {
+	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: string, peerId: string, options: NodeClaimAddressOptions): { kind: Exclude<DialAddressKind, 'loopback'>; addr: string } | undefined {
+	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: string): boolean {
+	if (ip.includes(':')) return /^(f[cd]|fe[89ab])/i.test(ip);
+	const [a, b] = ip.split('.').map(Number) as [number, 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: NodeClaimPayload): NodeClaimPayload {
 	const peerId = parsePeerId(payload.peerId);
@@ -112,10 +243,13 @@ function requireAddressOf(addr: string, peerId: ReturnType<typeof peerIdFromStri
  * 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`.
+ * `groupAddrsByPeerId` in `peer-addr-book.ts`. Throws when `addr` does not parse.
  */
-function destinationPeerIdOf(addr: string): string | null {
-	const components = multiaddr(addr).getComponents();
+export function destinationPeerIdOf(addr: string): string | null {
+	return destinationIn(multiaddr(addr).getComponents());
+}
+
+function destinationIn(components: AddressComponents): string | null {
 	for (let i = components.length - 1; i >= 0; i--) {
 		const component = components[i]!;
 		if (component.code === CODE_P2P_CIRCUIT) return null;

package/src/node-default-transports.ts

@@ -0,0 +1,38 @@
+/**
+ * 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';
+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 function nodeDefaultTransports({ wsPort }: ListenTransportOptions): Libp2pTransports {
+  return [
+    tcp(),
+    ...(wsPort === undefined ? [] : [webSockets()]),
+    circuitRelayTransport()
+  ];
+}

package/src/node-transports.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 type { Libp2pTransports } from '@optimystic/db-p2p';
+import { withoutRelayDiscovery } from './relay-reservation.js';
+import type { ListenTransportOptions } from './relay-addrs.js';
+import type { NetworkConfig } from './types.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: NetworkConfig | undefined,
+  listenTransports: ListenTransportOptions,
+  relaySlotsSupervised: boolean
+): { transports?: Libp2pTransports } {
+  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) };
+}