@serfab/cadre-host 0.12.0 → 1.0.0

package/src/server/__tests__/nodes-route.test.ts

@@ -85,7 +85,7 @@ const SAMPLE_NODE: ManagedNodeInfo = {
   status: 'running',
   spawnedAt: '2025-01-01T00:00:00Z',
   workdir: '',
-  ports: { health: 11, metrics: 12, p2p: 13, admin: 14 },
+  ports: { health: 11, metrics: 12, p2p: 13, admin: 14, ws: 15 },
 };
 
 describe('/api/nodes routes', () => {
@@ -200,7 +200,7 @@ describe('/api/nodes — owner node start/restart', () => {
     status: 'running',
     spawnedAt: '2025-01-01T00:00:00Z',
     workdir: '',
-    ports: { health: 1, metrics: 2, p2p: 4555, admin: 3 },
+    ports: { health: 1, metrics: 2, p2p: 4555, admin: 3, ws: 4 },
     owner: true,
   };
 

package/src/server/__tests__/publishers.test.ts

@@ -131,7 +131,7 @@ describe('publisher wiring', () => {
       status: 'stopped',
       spawnedAt: 'x',
       workdir: '/tmp',
-      ports: { health: 1, metrics: 2, p2p: 3, admin: 4 },
+      ports: { health: 1, metrics: 2, p2p: 3, admin: 4, ws: 5 },
     });
     expect(received).toContainEqual({
       type: 'node-state-changed',

package/src/server/__tests__/status-route.test.ts

@@ -64,7 +64,7 @@ describe('GET /api/status', () => {
           status: 'running',
           spawnedAt: '2025-01-01T00:00:00Z',
           workdir: '/tmp/alice',
-          ports: { health: 1, metrics: 2, p2p: 3, admin: 4 },
+          ports: { health: 1, metrics: 2, p2p: 3, admin: 4, ws: 5 },
         },
       ]),
       trustCircle: fakeTrustCircle({

package/src/server/routes/bootstrap-node-validation.ts

@@ -0,0 +1,206 @@
+/**
+ * Shape validation for the requester-supplied `bootstrapNodes` of `POST /grants`
+ * — the requester's control-network addresses the donated node is started with
+ * (written into the child's `cadre.json` as `controlNetwork.bootstrapNodes` by
+ * `orchestrator/host-process-orchestrator.ts`) and hands to `@libp2p/bootstrap`.
+ *
+ * Its own module rather than part of `grants.ts`: the per-entry rule is a duplicate
+ * of cadre-provider's copy (`packages/cadre-provider/src/server/bootstrap-node-validation.ts`)
+ * and must stay identical to it, so it is worth reading, testing and changing on
+ * its own, without a routing file around it — the same arrangement cadre-provider
+ * uses for its restatement of cadre-core's owner-key rule.
+ *
+ * ## An empty list is accepted — where this copy differs, on purpose
+ *
+ * The field may be absent or `[]`; cadre-provider's copy still requires at least one
+ * address. A lent node's requester is typically a phone, and a phone has no address
+ * to give — its node listens on nothing and can only dial out. Such a requester sends
+ * no addresses and dials the node itself, at the WebSocket address
+ * `GET /grants/:id/peer` reports. The node starts with no bootstrap peers and waits,
+ * and admits that first inbound connection because it holds no authorized members
+ * yet (`admitInboundControlConnection` / `authorizeInboundControlStream` in
+ * `cadre-core/src/cadre-node.ts`). A provider container has no such requester yet, so
+ * there an empty list is still the node-comes-up-alone failure described below
+ * (`backlog/feat-provider-drone-reachable-by-phone`).
+ *
+ * The difference is at the list level only: every entry that IS given must pass the
+ * rule below, which is identical in both packages.
+ *
+ * ## The rule, and why each clause is there
+ *
+ * An entry is usable exactly when it is a string, parses as a multiaddr, carries
+ * a `/p2p/<peerId>` component whose peer id decodes, and says where that peer is.
+ * Each clause corresponds to a distinct downstream failure the caller would
+ * otherwise never be told about — the value is forwarded verbatim into the spawned
+ * child, so every one of these surfaces where the caller cannot see it:
+ *
+ * - **Not parsable as a multiaddr → the child dies at boot.** `@libp2p/bootstrap`'s
+ *   constructor maps `multiaddr()` over the whole list *before* filtering anything,
+ *   and `multiaddr()` throws on a string that does not start with `/` (and on a
+ *   non-string outright). libp2p construction throws and the node never starts.
+ * - **No `/p2p/<peerId>` → the node starts and never joins.** The quiet one.
+ *   `/ip4/127.0.0.1/tcp/4001` parses fine, then `@libp2p/bootstrap` filters it out
+ *   ("invalid bootstrap multiaddr without peer id", logged inside the child) and
+ *   the node comes up with *zero* bootstrap peers: healthy-looking, permanently
+ *   alone, never reaching the party it was created for. cadre-core's
+ *   `getBootstrapPeerIds` (`packages/cadre-core/src/cadre-node.ts`) skips such an
+ *   entry silently for the same reason.
+ * - **Malformed peer id → the child dies at boot.** `multiaddr()` does *not*
+ *   validate the `/p2p/` value — parsing `/ip4/1.2.3.4/tcp/1/p2p/12D3KooReq` yields
+ *   a `p2p` component whose value is the junk string unchanged — but
+ *   `@libp2p/bootstrap` then calls `peerIdFromString` on it, unguarded, and it
+ *   throws `Incorrect length`. A truncated copy-paste of a 52-character peer id is
+ *   the likeliest human typo in this field.
+ * - **No location at all → the node starts and never joins.** `/p2p/<peerId>` (and
+ *   `/p2p/<relay>/p2p-circuit/p2p/<target>`) parses and names a decodable peer, and
+ *   `@libp2p/bootstrap` keeps it — but it says nothing about *where* the peer is, so
+ *   libp2p finds no transport for it and the dial fails with no valid addresses.
+ *   The node comes up with a bootstrap peer it can never reach, which looks the same
+ *   from outside as having none. Only the total absence of a location is rejected:
+ *   which transports the child can actually dial is the embedder's choice
+ *   (`NetworkConfig.transports`), invisible from here, so a partial address like
+ *   `/ip4/1.2.3.4/p2p/<peerId>` is deliberately left to the child.
+ *
+ * The peer id is read the way `@libp2p/bootstrap` reads it — the `p2p` components
+ * of `getComponents()` — rather than through the deprecated `getPeerId()`, so the
+ * two cannot disagree about which part of the address is the peer. Bootstrap uses
+ * only the *last* `p2p` component; this checks **every** one, so the relay half of
+ * a `…/p2p/<relay>/p2p-circuit/p2p/<target>` address must decode too. An address
+ * naming an undecodable relay is not dialable either, and bootstrap's own
+ * `P2P.matches` filter accepts any address carrying a `p2p` component, so nothing
+ * this accepts is dropped there.
+ *
+ * Requiring a multiaddr also closes a downstream ambiguity on the *other* side of
+ * this rule: cadre-provider joins its list with `,` into `CADRE_BOOTSTRAP_NODES`
+ * and cadre-cli's env loader splits it back on `,`, so an entry containing a comma
+ * would silently become two addresses there. This host writes JSON rather than an
+ * env var and so is not exposed to that, but the two per-entry rules are kept
+ * identical — see the note about manual upkeep below.
+ *
+ * Reachability is deliberately NOT checked: a well-formed address for a peer that
+ * happens to be down is indistinguishable here from one that is up, and no
+ * boundary check can tell them apart. This validates the *shape* the child must be
+ * able to parse, nothing more.
+ *
+ * Keeping the two per-entry rules in step is **manual** — neither package can see
+ * the other's rule, so no test can compare them. What the tests give instead is a
+ * tripwire on each side: `../__tests__/bootstrap-node-validation.test.ts` here and
+ * `packages/cadre-provider/src/server/__tests__/bootstrap-node-validation.test.ts`
+ * there each pin their own copy to the same per-entry accept/reject table (the
+ * empty-list row is the one that differs), so changing either rule fails that
+ * package's own suite — and the comment above the rule you just changed is what
+ * points at the other copy.
+ */
+
+import debug from 'debug';
+import { CODE_P2P, CODE_P2P_CIRCUIT, multiaddr, type Multiaddr } from '@multiformats/multiaddr';
+import { peerIdFromString } from '@libp2p/peer-id';
+
+const log = debug('cadre:host:bootstrap-nodes');
+
+/**
+ * Longest rejected address echoed back in an error message. Generous compared to
+ * the owner-key limit because a legitimate address is long: a plain
+ * `/ip4/…/tcp/…/p2p/<52 chars>` runs ~80 characters and a relayed
+ * `…/p2p-circuit/p2p/<52 chars>` about 150, so a smaller cap would truncate the
+ * very values an operator needs to read back.
+ */
+const REJECTED_ADDRESS_ECHO_LIMIT = 192;
+
+/**
+ * Render a rejected address for an error message, capped: `bootstrapNodes`
+ * arrives from a caller over the network, so an unbounded echo would let one junk
+ * string become a megabyte of log line.
+ */
+function describeRejectedAddress(value: string): string {
+  return value.length <= REJECTED_ADDRESS_ECHO_LIMIT
+    ? value
+    : `${value.slice(0, REJECTED_ADDRESS_ECHO_LIMIT)}… (${value.length} chars)`;
+}
+
+/** The message of a thrown parse/decode failure, whatever the thrower used. */
+function reasonOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Apply the rule above to one entry. Returns the trimmed value, so the create
+ * provision request carries exactly what was validated.
+ */
+function validateBootstrapNode(value: string): { node: string } | { error: string } {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    return { error: 'bootstrapNodes entries must not be empty or whitespace-only' };
+  }
+
+  let address: Multiaddr;
+  try {
+    address = multiaddr(trimmed);
+  } catch (error) {
+    log('rejecting bootstrapNodes entry: %s', reasonOf(error));
+    return {
+      error: `bootstrapNodes entries must be multiaddrs (could not parse "${describeRejectedAddress(trimmed)}": ${reasonOf(error)})`,
+    };
+  }
+
+  const components = address.getComponents();
+  const peerIds = components.filter(component => component.code === CODE_P2P);
+  if (peerIds.length === 0) {
+    return {
+      error: `bootstrapNodes entries must include a /p2p/<peerId> component ("${describeRejectedAddress(trimmed)}" names no peer, so the node would drop it and start with no bootstrap peers)`,
+    };
+  }
+
+  if (!components.some(component => component.code !== CODE_P2P && component.code !== CODE_P2P_CIRCUIT)) {
+    return {
+      error: `bootstrapNodes entries must name where to reach the peer ("${describeRejectedAddress(trimmed)}" names only peer ids, so no transport can dial it and the node would start with no reachable bootstrap peers)`,
+    };
+  }
+
+  for (const { value } of peerIds) {
+    try {
+      peerIdFromString(value ?? '');
+    } catch (error) {
+      log('rejecting bootstrapNodes peer id: %s', reasonOf(error));
+      return {
+        error: `bootstrapNodes entries must carry a decodable peer id ("${describeRejectedAddress(trimmed)}" names peer "${describeRejectedAddress(value ?? '')}", which does not decode: ${reasonOf(error)})`,
+      };
+    }
+  }
+
+  return { node: trimmed };
+}
+
+/**
+ * Validate the optional `bootstrapNodes` field of a provision request: absent, or an
+ * array of dialable control-network addresses (see {@link validateBootstrapNode}).
+ * Absent and `[]` alike mean the requester dials the node itself — see "An empty list
+ * is accepted" in the module comment.
+ *
+ * Provisioning is the last point at which the requester can still fix a typo, so
+ * the shape is checked here: without it a bad address is answered 201 and then
+ * produces a donated node that either dies at boot or comes up permanently alone
+ * — the requester learning about it, if ever, from donation status rather than
+ * from a 400 naming the bad address.
+ *
+ * Every rejection names the offending entry: with several addresses in one
+ * request the message is the only thing that says WHICH one.
+ *
+ * @returns the trimmed addresses (`[]` when none were given), so the provision request carries exactly what was validated.
+ */
+export function validateBootstrapNodes(value: unknown): { nodes: string[] } | { error: string } {
+  if (value === undefined) {
+    return { nodes: [] };
+  }
+  if (!Array.isArray(value) || !value.every((entry): entry is string => typeof entry === 'string')) {
+    return { error: 'bootstrapNodes must be an array of strings' };
+  }
+
+  const nodes: string[] = [];
+  for (const entry of value) {
+    const checked = validateBootstrapNode(entry);
+    if ('error' in checked) return checked;
+    nodes.push(checked.node);
+  }
+  return { nodes };
+}

package/src/server/routes/grants.ts

@@ -20,8 +20,9 @@
 
 import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
 
-import type { DonationService, DonationProvisionRequest } from '../../donation/donation-service.js';
+import type { DonationService } from '../../donation/donation-service.js';
 import type { DonationView, GrantValidator } from '../../donation/types.js';
+import { validateProvisionRequest } from './provision-request-validation.js';
 
 export interface GrantsRoutesOptions {
   donations: DonationService;
@@ -109,33 +110,15 @@ export function registerGrantsRoutes(app: FastifyInstance, opts: GrantsRoutesOpt
       return errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
     }
 
-    const body = (request.body ?? {}) as Partial<DonationProvisionRequest>;
-    if (typeof body.partyId !== 'string' || body.partyId.length === 0) {
-      return errorResponse(reply, 'invalid_request', 'partyId is required', 400);
-    }
-    if (!Array.isArray(body.bootstrapNodes) || body.bootstrapNodes.length === 0) {
-      return errorResponse(reply, 'invalid_request', 'bootstrapNodes is required', 400);
-    }
-    if (!Array.isArray(body.ownerKeys) || body.ownerKeys.length === 0) {
-      return errorResponse(reply, 'invalid_request', 'ownerKeys is required', 400);
-    }
-    // Element types too, not just the array: `provision`'s shape check trims each
-    // entry, so a non-string reaches the caller as an internal `.trim is not a
-    // function` rather than as a message naming what is wrong with the request.
-    if (!body.ownerKeys.every(key => typeof key === 'string')) {
-      return errorResponse(reply, 'invalid_request', 'ownerKeys must be an array of strings', 400);
-    }
-    if (body.profile !== undefined && body.profile !== 'storage' && body.profile !== 'transaction') {
-      return errorResponse(reply, 'invalid_request', 'profile must be "storage" or "transaction"', 400);
+    // One validator owns the whole body — see `provision-request-validation.ts`
+    // for why no per-field check lives here. Nothing is provisioned on a
+    // rejection: this runs before the service is touched.
+    const validated = validateProvisionRequest(request.body ?? {}, token);
+    if ('error' in validated) {
+      return errorResponse(reply, 'invalid_request', validated.error, 400);
     }
 
-    const donation = await donations.provision({
-      grantToken: token,
-      partyId: body.partyId,
-      bootstrapNodes: body.bootstrapNodes,
-      ownerKeys: body.ownerKeys,
-      ...(body.profile ? { profile: body.profile } : {}),
-    });
+    const donation = await donations.provision(validated.request);
     return reply.status(201).send({ ok: true, data: { donation } });
   });
 

package/src/server/routes/provision-request-validation.ts

@@ -0,0 +1,105 @@
+/**
+ * The whole shape check for `POST /grants` — one call that either yields the
+ * typed {@link DonationProvisionRequest} the `DonationService` is handed, or the
+ * message the route answers 400 with.
+ *
+ * **Why a validator rather than a few more `if`s in the route.** Every field in
+ * this body is forwarded into a child process the requester cannot see:
+ * `partyId`, `bootstrapNodes` and `profile` are written into the child's
+ * `cadre.json` (`orchestrator/host-process-orchestrator.ts`) and `ownerKeys`
+ * become its cold-start seed-trust anchors. A field the route forgets to check is
+ * not a 400 — it is a donated node that dies at boot, or comes up subtly wrong,
+ * with a 201 already sent. Routing the body through one function that *constructs*
+ * the request object means a field can only reach the spawn path by having been
+ * through here; adding a field to `DonationProvisionRequest` without validating it
+ * stops compiling rather than silently shipping.
+ *
+ * **Division of labour with `DonationService.provision`.** The Ed25519 rule for
+ * `ownerKeys` stays in the service, where it is applied by cadre-core's own
+ * `requireEd25519PublicKeyB64` — the service is also reached by the respawn path,
+ * which replays a persisted record rather than an HTTP body, so the crypto rule
+ * has to live there to cover both. What this validator owns for `ownerKeys` is the
+ * *container* shape (present, non-empty, all strings), which the service's rule
+ * assumes: a number reaching it surfaces as an internal `.trim is not a function`
+ * rather than as a message naming what is wrong with the request.
+ *
+ * The multiaddr rule has no such home — it is duplicated in cadre-provider — so it
+ * lives in `bootstrap-node-validation.ts` next to the comment saying so.
+ */
+
+import type { DonationProvisionRequest } from '../../donation/donation-service.js';
+import { validateBootstrapNodes } from './bootstrap-node-validation.js';
+
+/** `partyId` becomes `controlNetwork.partyId` in the child's config. */
+function validatePartyId(value: unknown): { partyId: string } | { error: string } {
+  if (typeof value !== 'string' || value.trim().length === 0) {
+    return { error: 'partyId is required' };
+  }
+  return { partyId: value.trim() };
+}
+
+/**
+ * Container shape only — see the module comment: the per-key Ed25519 rule is
+ * `DonationService.provision`'s, so the respawn path gets it too.
+ */
+function validateOwnerKeys(value: unknown): { ownerKeys: string[] } | { error: string } {
+  if (!Array.isArray(value) || value.length === 0) {
+    return { error: 'ownerKeys is required' };
+  }
+  if (!value.every((key): key is string => typeof key === 'string')) {
+    return { error: 'ownerKeys must be an array of strings' };
+  }
+  return { ownerKeys: value };
+}
+
+/** Absent means `storage` — see {@link DonationProvisionRequest.profile}. */
+function validateProfile(value: unknown): { profile?: DonationProvisionRequest['profile'] } | { error: string } {
+  if (value === undefined) return {};
+  if (value !== 'storage' && value !== 'transaction') {
+    return { error: 'profile must be "storage" or "transaction"' };
+  }
+  return { profile: value };
+}
+
+/**
+ * Validate a `POST /grants` body and build the request `DonationService.provision`
+ * is handed.
+ *
+ * `grantToken` comes from the `Authorization` bearer rather than the body — a
+ * requester does not get to name which grant pays for this — so it is a
+ * parameter, not a validated field. Whether that grant is live and within quota is
+ * `provision`'s call, not this function's.
+ *
+ * @returns the typed provision request, or the message to answer `invalid_request` with.
+ */
+export function validateProvisionRequest(
+  body: unknown,
+  grantToken: string,
+): { request: DonationProvisionRequest } | { error: string } {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) {
+    return { error: 'request body must be a JSON object' };
+  }
+  const fields = body as Record<string, unknown>;
+
+  const partyId = validatePartyId(fields.partyId);
+  if ('error' in partyId) return partyId;
+
+  const bootstrap = validateBootstrapNodes(fields.bootstrapNodes);
+  if ('error' in bootstrap) return bootstrap;
+
+  const ownerKeys = validateOwnerKeys(fields.ownerKeys);
+  if ('error' in ownerKeys) return ownerKeys;
+
+  const profile = validateProfile(fields.profile);
+  if ('error' in profile) return profile;
+
+  return {
+    request: {
+      grantToken,
+      partyId: partyId.partyId,
+      bootstrapNodes: bootstrap.nodes,
+      ownerKeys: ownerKeys.ownerKeys,
+      ...(profile.profile ? { profile: profile.profile } : {}),
+    },
+  };
+}