@econ-v1/domain 6.7.0 → 6.10.0

package/src/services/discovery-probe-service.js

@@ -0,0 +1,196 @@
+// @ts-check
+
+/** @typedef {import("@econ-v1/ports").HomeNodeCandidate} HomeNodeCandidate */
+/** @typedef {import("@econ-v1/ports").HomeNodeClient} HomeNodeClient */
+/** @typedef {import("@econ-v1/ports").HomeNodeDialer} HomeNodeDialer */
+/** @typedef {import("./lan-candidate-refresh-service.js").LanCandidateRefreshService} LanCandidateRefreshService */
+
+import { DomainError } from "../errors/index.js";
+import { createRuntimeAbortController } from "./runtime-globals.js";
+
+/** @typedef {"probing" | "reachable" | "verified" | "unreachable"} DiscoveryCandidateStatus */
+/** @typedef {{ readonly displayName: string, readonly maskedNodeId: string }} DiscoveryFoundNode */
+/** @typedef {{ readonly address: string, readonly node?: DiscoveryFoundNode, readonly status: DiscoveryCandidateStatus }} DiscoveryCandidateRow */
+/** @typedef {{ readonly friendly_name?: unknown, readonly node_id?: unknown }} DiscoveryNodeIdentityWire */
+/** @typedef {{ readonly dialer: HomeNodeDialer, readonly onChange?: (rows: readonly DiscoveryCandidateRow[]) => void, readonly refresh: Pick<LanCandidateRefreshService, "refresh"> }} DiscoveryProbeServiceOptions */
+
+export class DiscoveryProbeService {
+  /** @readonly @type {HomeNodeDialer} */
+  #dialer;
+  /** @readonly @type {(rows: readonly DiscoveryCandidateRow[]) => void} */
+  #onChange;
+  /** @readonly @type {Pick<LanCandidateRefreshService, "refresh">} */
+  #refresh;
+  /** @type {Map<string, DiscoveryCandidateRow>} */
+  #rows = new Map();
+  #generation = 0;
+
+  /** @param {DiscoveryProbeServiceOptions} options */
+  constructor(options) {
+    this.#dialer = options.dialer;
+    this.#onChange = options.onChange ?? (() => undefined);
+    this.#refresh = options.refresh;
+  }
+
+  /** @returns {readonly DiscoveryCandidateRow[]} */
+  snapshot() {
+    return [...this.#rows.values()];
+  }
+
+  /**
+   * @param {readonly string[]} addresses
+   * @returns {Promise<readonly DiscoveryCandidateRow[]>}
+   */
+  async probe(addresses) {
+    const generation = (this.#generation += 1);
+    const unique = dedupeText(addresses);
+    this.#rows = new Map(unique.map((address) => [address, { address, status: "probing" }]));
+    this.#emit();
+
+    await Promise.all(unique.map((address) => this.#probeOne(generation, address)));
+    return this.snapshot();
+  }
+
+  /**
+   * @param {string} address
+   * @returns {Promise<void>}
+   */
+  async promote(address) {
+    const row = this.#rows.get(address);
+    if (row === undefined || row.status !== "verified") {
+      throw new DomainError({
+        code: "invalid_request",
+        message: "Only a verified discovery candidate may be promoted as the home-node route",
+      });
+    }
+    const client = await this.#dial(address);
+    await this.#refresh.refresh(client);
+  }
+
+  /**
+   * @param {number} generation
+   * @param {string} rawAddress
+   * @returns {Promise<void>}
+   */
+  async #probeOne(generation, rawAddress) {
+    /** @type {HomeNodeClient} */
+    let client;
+    try {
+      client = await this.#dial(rawAddress);
+    } catch {
+      this.#setRow(generation, rawAddress, { address: rawAddress, status: "unreachable" });
+      return;
+    }
+
+    this.#setRow(generation, rawAddress, { address: rawAddress, status: "reachable" });
+
+    try {
+      /** @type {unknown} */
+      const metadata = await client.invoke({
+        operation: "GET /api/v2/node/metadata",
+        payload: {},
+      });
+      if (!isRecord(metadata)) {
+        this.#setRow(generation, rawAddress, { address: rawAddress, status: "unreachable" });
+        return;
+      }
+      const nodeId = textOrUndefined(metadata.node_id);
+      if (nodeId === undefined) {
+        this.#setRow(generation, rawAddress, { address: rawAddress, status: "unreachable" });
+        return;
+      }
+      const displayName = textOrUndefined(metadata.friendly_name) ?? "Home Node";
+      this.#setRow(generation, rawAddress, {
+        address: rawAddress,
+        node: { displayName, maskedNodeId: maskNodeId(nodeId) },
+        status: "verified",
+      });
+    } catch {
+      this.#setRow(generation, rawAddress, { address: rawAddress, status: "unreachable" });
+    }
+  }
+
+  /**
+   * @param {string} rawAddress
+   * @returns {Promise<HomeNodeClient>}
+   */
+  async #dial(rawAddress) {
+    const origin = secureLanOrigin(rawAddress);
+    if (origin === undefined) {
+      throw new DomainError({ code: "invalid_request", message: "Discovery candidate address is invalid" });
+    }
+    /** @type {HomeNodeCandidate} */
+    const candidate = { address: origin, id: rawAddress, path: "lan-direct" };
+    const controller = createRuntimeAbortController();
+    return await this.#dialer.dial(candidate, controller.signal);
+  }
+
+  /**
+   * @param {number} generation
+   * @param {string} address
+   * @param {DiscoveryCandidateRow} row
+   * @returns {void}
+   */
+  #setRow(generation, address, row) {
+    if (generation !== this.#generation) return;
+    if (!this.#rows.has(address)) return;
+    this.#rows.set(address, row);
+    this.#emit();
+  }
+
+  /** @returns {void} */
+  #emit() {
+    this.#onChange(this.snapshot());
+  }
+}
+
+/**
+ * @param {readonly string[]} values
+ * @returns {readonly string[]}
+ */
+function dedupeText(values) {
+  return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+
+/**
+ * @param {unknown} value
+ * @returns {string | undefined}
+ */
+function textOrUndefined(value) {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {string} nodeId
+ * @returns {string}
+ */
+function maskNodeId(nodeId) {
+  if (nodeId.length <= 10) return nodeId;
+  return `${nodeId.slice(0, 6)}····${nodeId.slice(-4)}`;
+}
+
+const LAN_ADDRESS_PATTERN = /^(?:https?:\/\/)?([^/?#:\s]+)(?::(\d{1,5}))?\/?$/u;
+
+/**
+ * @param {string} address
+ * @returns {string | undefined}
+ */
+export function secureLanOrigin(address) {
+  const trimmed = address.trim();
+  if (trimmed.length === 0) return undefined;
+  const match = LAN_ADDRESS_PATTERN.exec(trimmed);
+  if (match === null) return undefined;
+  const host = match[1];
+  if (host === undefined || host.length === 0) return undefined;
+  const port = match[2] === undefined ? undefined : Number(match[2]);
+  if (port !== undefined && (port < 1 || port > 65535)) return undefined;
+  return port === undefined ? `https://${host}` : `https://${host}:${port}`;
+}

package/{dist → src}/services/gossip-service.js

@@ -1,17 +1,57 @@
+// @ts-check
+
+/**
+ * @typedef {import("@econ-v1/ports").PeerTransportPort} PeerTransportPort
+ */
+/**
+ * @typedef {import("./abort-signal.js").AbortSignalPort} AbortSignalPort
+ */
+/**
+ * @typedef {import("./peer-directory-service.js").PeerAdvertisement} PeerAdvertisement
+ */
+/**
+ * @typedef {PeerAdvertisement & { readonly version: typeof GOSSIP_VERSION; }} GossipAdvertisement
+ */
+/**
+ * @typedef {{ readonly directory: PeerDirectoryService; readonly transport: PeerTransportPort; }} GossipServiceOptions
+ */
 import { normalizeAdvertisement, PeerDirectoryService, } from "./peer-directory-service.js";
+import { decodeUtf8, encodeUtf8 } from "./runtime-globals.js";
 const GOSSIP_VERSION = 1;
 export class GossipService {
+    /**
+   * @readonly
+   * @type {PeerDirectoryService}
+   */
     #directory;
+    /**
+   * @readonly
+   * @type {PeerTransportPort}
+   */
     #transport;
+    /**
+   * @param {GossipServiceOptions} options
+   */
     constructor(options) {
         this.#directory = options.directory;
         this.#transport = options.transport;
     }
+    /**
+   * @param {string} topic
+   * @param {PeerAdvertisement} advertisement
+   * @returns {Promise<void>}
+   */
     async publishAdvertisement(topic, advertisement) {
         const normalized = normalizeAdvertisement(advertisement);
+        /** @type {GossipAdvertisement} */
         const value = { ...normalized, version: GOSSIP_VERSION };
-        await this.#transport.publish(topic, new TextEncoder().encode(JSON.stringify(value)));
+        await this.#transport.publish(topic, encodeUtf8(JSON.stringify(value)));
     }
+    /**
+   * @param {string} topic
+   * @param {AbortSignalPort} [signal]
+   * @returns {AsyncIterable<GossipAdvertisement>}
+   */
     async *advertisements(topic, signal) {
         const seen = new Set();
         for await (const payload of this.#transport.subscribe(topic, signal)) {
@@ -26,12 +66,19 @@ export class GossipService {
         }
     }
 }
+/**
+ * @param {Uint8Array} payload
+ * @returns {GossipAdvertisement | undefined}
+ */
 function parseAdvertisement(payload) {
     try {
-        const value = JSON.parse(new TextDecoder().decode(payload));
+        /** @type {unknown} */
+        const value = JSON.parse(decodeUtf8(payload));
         if (!isRecord(value) || value.version !== GOSSIP_VERSION ||
             !Array.isArray(value.directAddresses) ||
-            !value.directAddresses.every((address) => typeof address === "string") ||
+            !value.directAddresses.every(/**
+       * @returns {address is string}
+       */ (address) => typeof address === "string") ||
             typeof value.did !== "string" || typeof value.irohNodeId !== "string" || typeof value.observedAt !== "string") {
             return undefined;
         }
@@ -47,7 +94,10 @@ function parseAdvertisement(payload) {
         return undefined;
     }
 }
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-//# sourceMappingURL=gossip-service.js.map

package/src/services/invite-redemption-service.js

@@ -0,0 +1,64 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').HomeNodeClient} HomeNodeClient */
+export class InviteRedemptionService {
+  /**
+   * @readonly
+   */
+  #node;
+  /**
+   * @param {InviteRedemptionServiceOptions} options
+   */
+  constructor(options) {
+    this.#node = options.node;
+  }
+  /**
+   * @param {string} code
+   * @returns {Promise<InviteRedemptionOutcome>}
+   */
+  async redeem(code) {
+    const trimmed = code.trim();
+    if (trimmed.length === 0) return { kind: "rejected" };
+    try {
+      const wire = await this.#node.invoke({
+        operation: "POST /api/v2/invite/redeem",
+        payload: { code: trimmed },
+      });
+      if (wire.ok !== true) return { kind: "rejected" };
+      const receiverName =
+        typeof wire.receiver_name === "string" &&
+        wire.receiver_name.trim().length > 0
+          ? wire.receiver_name.trim()
+          : undefined;
+      return { kind: "redeemed", receiverName };
+    } catch {
+      return { kind: "rejected" };
+    }
+  }
+}
+/**
+ * Step 11's real action: redeem an invitation code against the node's PUBLIC
+ * `POST /api/v2/invite/redeem` (`core/adapters-network/src/http/server/invite.rs`), which
+ * takes `{ code }` or `{ token }` and needs no authentication — deliberately, because at step
+ * 11 the browser has no session at all.
+ *
+ * The response's `receiver_name` is the name the INVITER registered for this person. Prefilling
+ * step 12's display name with it (and locking it, see `OnboardingFlowService`) is what makes
+ * the invitation meaningful rather than decorative: the person who was invited as "Ada
+ * Lovelace" shows up on the inviter's node as Ada Lovelace. It is null for legacy
+ * token-shaped invites, which is a normal, non-error case.
+ *
+ * Outcomes are closed and text-free. `"rejected"` covers expired, already-used, unknown and
+ * malformed codes alike — the node's own message would tell an attacker which of those it was.
+ * @typedef {| { readonly kind: "redeemed"; readonly receiverName: string | undefined }
+ *   | { readonly kind: "rejected" }} InviteRedemptionOutcome
+ */
+/**
+ * @typedef {object} InviteRedemptionServiceOptions
+ * @property {Pick<HomeNodeClient, "invoke">} node
+ */
+/**
+ * @typedef {object} InviteRedeemWire
+ * @property {unknown} [ok]
+ * @property {unknown} [receiver_name]
+ */
+// @ts-check

package/src/services/lan-candidate-refresh-service.js

@@ -0,0 +1,164 @@
+// @ts-check
+
+/** @typedef {import("@econ-v1/ports").DeviceConnectionMetadata} DeviceConnectionMetadata */
+/** @typedef {import("@econ-v1/ports").HomeNodeCandidate} HomeNodeCandidate */
+/** @typedef {import("@econ-v1/ports").HomeNodeClient} HomeNodeClient */
+/** @typedef {import("@econ-v1/ports").HttpHomeNodeCandidate} HttpHomeNodeCandidate */
+/** @typedef {import("@econ-v1/ports").IdentityPort} IdentityPort */
+
+/** @typedef {{ readonly version: 1, readonly node_id: string, readonly wan_origin: string, readonly lan_origins: readonly string[] }} ClientTransportCandidateWire */
+/** @typedef {{ readonly identity: IdentityPort, readonly now?: () => string }} LanCandidateRefreshServiceOptions */
+
+import { parseRuntimeUrl } from "./runtime-globals.js";
+import { isPotentiallyTrustworthyOrigin } from "./transport-manager.js";
+
+const MAX_LAN_ORIGINS = 8;
+
+export class LanCandidateRefreshService {
+  /** @readonly @type {IdentityPort} */
+  #identity;
+  /** @readonly @type {() => string} */
+  #now;
+
+  /** @param {LanCandidateRefreshServiceOptions} options */
+  constructor(options) {
+    this.#identity = options.identity;
+    this.#now = options.now ?? (() => new Date().toISOString());
+  }
+
+  /**
+   * @param {HomeNodeClient} home
+   * @returns {Promise<readonly HomeNodeCandidate[]>}
+   */
+  async refresh(home) {
+    const current = await this.#identity.loadConnectionMetadata();
+    const homeNodeId = current?.homeNodeId;
+    if (!isNodeId(homeNodeId))
+      throw new TypeError("Home node transport identity is not established");
+    /** @type {unknown} */
+    const response = await home.invoke({
+      operation: "GET /api/v2/client-transport/candidates",
+      payload: {},
+    });
+    const refreshed = parseCandidates(response, homeNodeId);
+    /** @type {DeviceConnectionMetadata} */
+    /** @type {DeviceConnectionMetadata} */
+    const next = {
+      directAddresses: refreshed.lan.map((candidate) => candidate.address),
+      homeNodeId,
+      lastConnectedAt: this.#now(),
+      ...(current?.relayUrl === undefined
+        ? {}
+        : { relayUrl: current.relayUrl }),
+      wanOrigin: refreshed.wan.address,
+    };
+    await this.#identity.storeConnectionMetadata(next);
+    return refreshed.lan;
+  }
+}
+
+/**
+ * @param {unknown} value
+ * @param {string} expectedHomeNodeId
+ * @returns {{ readonly lan: readonly HttpHomeNodeCandidate[], readonly wan: HttpHomeNodeCandidate }}
+ */
+function parseCandidates(value, expectedHomeNodeId) {
+  if (
+    !isExactCandidateResponse(value) ||
+    value.node_id !== expectedHomeNodeId
+  ) {
+    throw new TypeError("Home node transport identity did not match");
+  }
+  const lan = normalizeLanOrigins(value.lan_origins);
+  const wan = canonicalHttpsOrigin(
+    value.wan_origin,
+    "Home node WAN origin was invalid",
+  );
+  return {
+    lan: lan.map((address) => ({
+      address,
+      id: expectedHomeNodeId,
+      path: "lan-direct",
+    })),
+    wan: { address: wan, id: expectedHomeNodeId, path: "wan-direct" },
+  };
+}
+
+/**
+ * @param {readonly string[]} origins
+ * @returns {readonly string[]}
+ */
+function normalizeLanOrigins(origins) {
+  const normalized = new Set();
+  for (const origin of origins) {
+    normalized.add(
+      canonicalHttpsOrigin(origin, "Home node LAN candidates were invalid"),
+    );
+    if (normalized.size === MAX_LAN_ORIGINS) break;
+  }
+  return [...normalized];
+}
+
+/**
+ * @param {string} value
+ * @param {string} message
+ * @returns {string}
+ */
+function canonicalHttpsOrigin(value, message) {
+  /** @type {import("./runtime-globals.js").RuntimeUrl} */
+  let url;
+  try {
+    url = parseRuntimeUrl(value);
+  } catch {
+    throw new TypeError(message);
+  }
+  if (
+    !isPotentiallyTrustworthyOrigin(url) ||
+    url.username !== "" ||
+    url.password !== "" ||
+    url.hostname === "" ||
+    url.origin !== value
+  ) {
+    throw new TypeError(message);
+  }
+  return url.origin;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is ClientTransportCandidateWire}
+ */
+function isExactCandidateResponse(value) {
+  if (!isRecord(value)) return false;
+  const expected = ["lan_origins", "node_id", "version", "wan_origin"];
+  if (
+    Object.keys(value).length !== expected.length ||
+    !expected.every((key) => Object.hasOwn(value, key))
+  )
+    return false;
+  return (
+    value.version === 1 &&
+    isNodeId(value.node_id) &&
+    typeof value.wan_origin === "string" &&
+    Array.isArray(value.lan_origins) &&
+    value.lan_origins.every((origin) => typeof origin === "string")
+  );
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is Record<string, unknown>}
+ */
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is string}
+ */
+function isNodeId(value) {
+  return (
+    typeof value === "string" && value.trim() === value && value.length > 0
+  );
+}

package/src/services/lcd-decision-service.js

@@ -0,0 +1,93 @@
+// @ts-check
+/** @typedef {import('@econ-v1/ports').HomeNodeClient} HomeNodeClient */
+export class LcdDecisionService {
+  /**
+   * @readonly
+   */
+  #node;
+  /**
+   * @param {LcdDecisionServiceOptions} options
+   */
+  constructor(options) {
+    this.#node = options.node;
+  }
+  /**
+   * @param {string} operationHash
+   * @returns {Promise<LcdDecisionOutcome>}
+   */
+  async confirm(operationHash) {
+    return await this.#decide(
+      "POST /api/v2/node/lcd-screen/confirm",
+      operationHash,
+    );
+  }
+  /**
+   * @param {string} operationHash
+   * @returns {Promise<LcdDecisionOutcome>}
+   */
+  async reject(operationHash) {
+    return await this.#decide(
+      "POST /api/v2/node/lcd-screen/reject",
+      operationHash,
+    );
+  }
+  /**
+   * @param {string} operation
+   * @param {string} operationHash
+   * @returns {Promise<LcdDecisionOutcome>}
+   */
+  async #decide(operation, operationHash) {
+    const trimmed = operationHash.trim();
+    // The node validates `length(min = 1)` and would answer 400; asking is pointless noise on
+    // the node's audit log for what is a client-side programming error.
+    if (trimmed.length === 0) return "not-accepted";
+    try {
+      await this.#node.invoke({
+        operation,
+        payload: { operation_hash: trimmed },
+      });
+      return "forwarded";
+    } catch {
+      // Every failure is the same instruction to the person: the node did not take this tap,
+      // so use the node. No error text, no status code, no branch.
+      return "not-accepted";
+    }
+  }
+}
+/**
+ * Forwards an LCD-pane tap to the NODE's own public decision routes — the same
+ * `onboarding.device.confirm` / `…reject` capability a physical tap on the hardware drives
+ * (`core/adapters-network/src/http/server/device_management/proxy.rs:888-975`). Both routes
+ * are in `public_routes()` and need no JWT, which is exactly right: at step 10 the browser has
+ * no session at all, so this must be constructed over `prePairingNode`.
+ *
+ * WHAT THIS CLASS IS NOT. It is not an approval. `LcdDecisionOutcome` has two values and
+ * neither of them is "approved": `"forwarded"` means the node accepted the *request*, not
+ * that the claim is confirmed. Confirmation reaches the flow through exactly one path —
+ * `OwnerClaimService.awaitConfirmation`'s poll of `GET /node/operation-status/{hash}` — and
+ * nothing here shortcuts it. That is the property design §8.3 exists to protect: the node is
+ * the authority, and a browser tap can at most ask.
+ *
+ * WHY THE FAILURE SIDE IS ONE VALUE. `enforce_physical_presence` answers 403 when a hardware
+ * LCD is present and the pending operation is an `onboard` (the physical tap is then the only
+ * path), and 503 when it cannot determine presence. Both would ideally be distinguishable
+ * here — but `AppError::Forbidden` and `AppError::ServiceUnavailable` do NOT emit the node's
+ * `{ success: false, error: { code } }` envelope (`core/foundation/src/error.rs:145-148`,
+ * `:252-254`), so `PrePairingHomeNodeClient` collapses both — and a genuine network failure —
+ * into `TransportError{ code: "unavailable" }`. Inventing a distinction the wire does not
+ * carry would be a lie, and the pane's behaviour is identical for all three anyway: render
+ * the press, say "waiting for the node", keep waiting. The pane learns whether a hardware
+ * display exists from `OwnerClaimPrepareOutcome.lcdHardware`, which the node states outright
+ * at prepare time — see `OnboardingFlowService.lcdScreen()`'s `physicalTapOnly`.
+ *
+ * The optional `setup_token` field on both requests is deliberately never sent: it is read
+ * from a file on the node's own filesystem, which a browser cannot do. A headless node with
+ * the code-match gate armed therefore answers `"not-accepted"` here, and the operator confirms
+ * through a surface that can read the token. Recorded as a named gap, not papered over.
+ * @typedef {"forwarded" | "not-accepted"} LcdDecisionOutcome
+ */
+/**
+ * @typedef {object} LcdDecisionServiceOptions
+ * @property {Pick<HomeNodeClient, "invoke">} node MUST be the pre-pairing client: step 10 runs on an unclaimed node with no session.
+ */
+// @ts-check