@serfab/cadre-host 0.13.0 → 1.0.0

package/src/orchestrator/port-allocator.ts

@@ -1,91 +1,148 @@
-import type { NodePorts } from './types.js';
-
-/**
- * Range-based port tracker. Allocations are in-memory; on orchestrator
- * restart the caller rehydrates the used-set from persisted state via
- * `markUsed(port)` before serving new allocations.
- */
-export class PortAllocator {
-  private readonly usedPorts = new Set<number>();
-
-  constructor(
-    private readonly start: number,
-    private readonly end: number,
-  ) {
-    if (!Number.isInteger(start) || !Number.isInteger(end) || start <= 0 || end < start) {
-      throw new Error(`Invalid port range: ${start}..${end}`);
-    }
-  }
-
-  allocate(): number {
-    for (let port = this.start; port <= this.end; port++) {
-      if (!this.usedPorts.has(port)) {
-        this.usedPorts.add(port);
-        return port;
-      }
-    }
-    throw new Error(`No available ports in range ${this.start}..${this.end}`);
-  }
-
-  release(port: number): void {
-    this.usedPorts.delete(port);
-  }
-
-  /** Used during restart rehydration to reserve ports already in use. */
-  markUsed(port: number): void {
-    if (port < this.start || port > this.end) {
-      return;
-    }
-    this.usedPorts.add(port);
-  }
-
-  has(port: number): boolean {
-    return this.usedPorts.has(port);
-  }
-}
-
-/**
- * Allocation order for a node's port set. Fixed so that swapping a caller onto
- * {@link allocateNodePorts} does not shift the ports an existing deployment
- * already handed out.
- */
-const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'admin'] as const;
-
-/**
- * Allocate a full NodePorts set atomically — a mid-way failure (an exhausted
- * range) releases everything already taken rather than stranding the ports it
- * got before the throw. `overrides` supply a port instead of allocating one
- * (the owner node's p2p port, which is fixed by NAT config).
- *
- * Overrides are reserved FIRST, before any allocation, so an override that
- * happens to sit inside the managed range cannot also be handed out to another
- * key. Reserving is `markUsed`, a documented no-op outside the range — which is
- * the production case for the owner node's libp2p port, and why reserving first
- * leaves every real port assignment unchanged.
- */
-export function allocateNodePorts(
-  allocator: PortAllocator,
-  overrides?: Partial<NodePorts>,
-): NodePorts {
-  const reserved: number[] = [];
-  const ports: Partial<NodePorts> = {};
-  try {
-    for (const key of NODE_PORT_KEYS) {
-      const override = overrides?.[key];
-      if (override === undefined) continue;
-      allocator.markUsed(override);
-      reserved.push(override);
-      ports[key] = override;
-    }
-    for (const key of NODE_PORT_KEYS) {
-      if (ports[key] !== undefined) continue;
-      const port = allocator.allocate();
-      reserved.push(port);
-      ports[key] = port;
-    }
-  } catch (err) {
-    for (const port of reserved) allocator.release(port);
-    throw err;
-  }
-  return ports as NodePorts;
-}
+import type { NodePorts } from './types.js';
+
+/**
+ * Range-based port tracker. Allocations are in-memory; on orchestrator
+ * restart the caller rehydrates the used-set from persisted state via
+ * `markUsed(port)` before serving new allocations.
+ */
+export class PortAllocator {
+  private readonly usedPorts = new Set<number>();
+
+  constructor(
+    private readonly start: number,
+    private readonly end: number,
+  ) {
+    if (!Number.isInteger(start) || !Number.isInteger(end) || start <= 0 || end < start) {
+      throw new Error(`Invalid port range: ${start}..${end}`);
+    }
+  }
+
+  allocate(): number {
+    for (let port = this.start; port <= this.end; port++) {
+      if (!this.usedPorts.has(port)) {
+        this.usedPorts.add(port);
+        return port;
+      }
+    }
+    throw new Error(`No available ports in range ${this.start}..${this.end}`);
+  }
+
+  release(port: number): void {
+    this.usedPorts.delete(port);
+  }
+
+  /**
+   * Used during restart rehydration to reserve ports already in use. A no-op for a
+   * port outside the range, and for a non-integer: a handle persisted by an older
+   * build lacks the ports added since, and `undefined` must not enter the used-set.
+   */
+  markUsed(port: number): void {
+    if (!Number.isInteger(port) || port < this.start || port > this.end) {
+      return;
+    }
+    this.usedPorts.add(port);
+  }
+
+  has(port: number): boolean {
+    return this.usedPorts.has(port);
+  }
+}
+
+/**
+ * Allocation order for a node's port set. Fixed so that swapping a caller onto
+ * {@link allocateNodePorts} does not shift the ports an existing deployment
+ * already handed out — which is also why a key added later goes on the end
+ * (`ws` came after the first four).
+ */
+const NODE_PORT_KEYS = ['health', 'metrics', 'p2p', 'admin', 'ws'] as const;
+
+/**
+ * Allocate a full NodePorts set atomically — a mid-way failure (an exhausted
+ * range) releases everything already taken rather than stranding the ports it
+ * got before the throw. `overrides` supply a port instead of allocating one
+ * (the owner node's p2p port, which is fixed by NAT config; a re-spawn's
+ * previous ports, see {@link reusedNodePorts}).
+ *
+ * Overrides are reserved FIRST, before any allocation, so an override that
+ * happens to sit inside the managed range cannot also be handed out to another
+ * key. Reserving is `markUsed`, a documented no-op outside the range — which is
+ * the production case for the owner node's libp2p port, and why reserving first
+ * leaves every real port assignment unchanged.
+ *
+ * NOTE: an override is trusted, not checked — `markUsed` does not refuse a port
+ * another handle already holds, nor two keys naming the same port. Safe for
+ * today's callers: a re-spawn's overrides were released by its own handle drop
+ * with no `await` in between, and the owner's `libp2pPort` can only collide if an
+ * operator configures it inside the range onto a port a node already holds. If a
+ * caller ever passes ports it did not just release, refuse an override that
+ * `allocator.has()` or that repeats another key's port.
+ */
+export function allocateNodePorts(
+  allocator: PortAllocator,
+  overrides?: Partial<NodePorts>,
+): NodePorts {
+  const reserved: number[] = [];
+  const ports: Partial<NodePorts> = {};
+  try {
+    for (const key of NODE_PORT_KEYS) {
+      const override = overrides?.[key];
+      if (override === undefined) continue;
+      allocator.markUsed(override);
+      reserved.push(override);
+      ports[key] = override;
+    }
+    for (const key of NODE_PORT_KEYS) {
+      if (ports[key] !== undefined) continue;
+      const port = allocator.allocate();
+      reserved.push(port);
+      ports[key] = port;
+    }
+  } catch (err) {
+    for (const port of reserved) allocator.release(port);
+    throw err;
+  }
+  return ports as NodePorts;
+}
+
+/**
+ * Hold a node's whole port set against `allocator` — the inverse of
+ * {@link releaseNodePorts}. A key the set lacks is skipped (see `markUsed`).
+ */
+export function reserveNodePorts(allocator: PortAllocator, ports: NodePorts): void {
+  for (const key of NODE_PORT_KEYS) allocator.markUsed(ports[key]);
+}
+
+/**
+ * Give a node's whole port set back to `allocator`. A key the set lacks releases
+ * nothing: deleting a value the used-set never held is a no-op.
+ */
+export function releaseNodePorts(allocator: PortAllocator, ports: NodePorts): void {
+  for (const key of NODE_PORT_KEYS) allocator.release(ports[key]);
+}
+
+/**
+ * The ports a re-spawn comes back on: the set the dropped handle held, as
+ * {@link allocateNodePorts} overrides. `{}` when nothing was dropped (a first
+ * spawn, or a handle lost along with `state.json`), so every port is allocated
+ * fresh.
+ *
+ * Why a re-spawn must not simply take the lowest free ports: a requester with no
+ * address of its own (a phone) reaches a lent node only by dialing the address it
+ * was given, so a node that comes back on a different port is one that requester
+ * can no longer find.
+ *
+ * A key the dropped handle lacks — `ws` on a handle persisted by an older build —
+ * is left out, and so allocated fresh. When more than one handle was dropped (only
+ * possible from a `state.json` that already held duplicates), the last one stored
+ * wins and the others' ports stay released.
+ */
+export function reusedNodePorts(dropped: readonly { ports: NodePorts }[]): Partial<NodePorts> {
+  const reused: Partial<NodePorts> = {};
+  const previous = dropped[dropped.length - 1]?.ports;
+  if (!previous) return reused;
+  for (const key of NODE_PORT_KEYS) {
+    const port = previous[key];
+    if (Number.isInteger(port)) reused[key] = port;
+  }
+  return reused;
+}

package/src/orchestrator/port-probe.ts

@@ -0,0 +1,31 @@
+import { createServer } from 'node:net';
+
+/** One TCP port a child binds, on the address it binds it to. */
+export interface PortBinding {
+  port: number;
+  host: string;
+}
+
+/**
+ * Resolve when `binding` can be bound right now; reject, naming the port and the
+ * OS error code, when it cannot. Binds briefly and closes again at once.
+ *
+ * Any bind error counts as "unavailable", not just `EADDRINUSE`: on Windows a
+ * port held with `SO_EXCLUSIVEADDRUSE` (which libuv sets on every TCP bind) can
+ * answer `EACCES` instead, and a child launched onto a port that fails either way
+ * would die on it.
+ */
+export function assertPortFree(binding: PortBinding): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', (err: NodeJS.ErrnoException) => {
+      reject(new Error(
+        `port ${binding.port} on ${binding.host} is unavailable (${err.code ?? err.message})`,
+        { cause: err },
+      ));
+    });
+    server.listen({ port: binding.port, host: binding.host }, () => {
+      server.close(() => resolve());
+    });
+  });
+}

package/src/orchestrator/types.ts

@@ -42,13 +42,25 @@ export interface HostProcessConfig {
  */
 export type PushCredentialsResolver = () => Promise<PushCredentials | undefined>;
 
-/** Per-child allocated ports. `admin` carries the loopback admin channel (6.6). */
+/**
+ * Per-child allocated ports. `admin` carries the loopback admin channel (6.6).
+ *
+ * A handle read back from a `state.json` written by an older build lacks every key
+ * added since, whatever this type says — the node-set helpers in `port-allocator.ts`
+ * skip a missing key rather than reserving `undefined`.
+ */
 export interface NodePorts {
   health: number;
   metrics: number;
+  /** libp2p TCP listener. */
   p2p: number;
   /** Loopback admin-channel port. Bound only by the owner node. */
   admin: number;
+  /**
+   * libp2p WebSocket listener. The one a phone dials: a phone's node has no TCP
+   * transport, so the `p2p` port is unreachable to it.
+   */
+  ws: number;
 }
 
 /** In-memory record per managed child. */

package/src/server/__tests__/bootstrap-node-validation.test.ts

@@ -2,12 +2,14 @@
  * The host's `bootstrapNodes` rule — the requester addresses a donated node is
  * started with — exercised directly.
  *
- * This is one half of a **manual tripwire**: cadre-provider carries a
- * byte-identical copy of this rule
- * (`packages/cadre-provider/src/server/bootstrap-node-validation.ts`) and the table
- * below is the same table
+ * This is one half of a **manual tripwire**: cadre-provider carries an identical
+ * copy of this rule's per-entry half
+ * (`packages/cadre-provider/src/server/bootstrap-node-validation.ts`) and the
+ * per-entry rows below are the same rows
  * `packages/cadre-provider/src/server/__tests__/bootstrap-node-validation.test.ts`
- * pins that copy to. Neither suite can observe the other package — nothing here
+ * pins that copy to. The empty-list row differs on purpose: this host accepts an
+ * empty list (a phone requester dials its lent node instead), the provider still
+ * requires one. Neither suite can observe the other package — nothing here
  * imports cadre-provider's server module — so this does not detect a change made
  * over there; what it does is fail if *this* copy is changed, which is how an
  * editor is landed on the comment pointing at the other one.
@@ -50,9 +52,11 @@ describe('validateBootstrapNodes (the host copy of the address rule)', () => {
     expect(validateBootstrapNodes([relayed])).toEqual({ nodes: [relayed] });
   });
 
-  it('treats an absent field and an empty list alike: the field is required', () => {
-    expect(errorOf(undefined)).toBe('bootstrapNodes is required');
-    expect(errorOf([])).toBe('bootstrapNodes is required');
+  // The one row that differs from cadre-provider's table: a requester with no address
+  // of its own (a phone) sends none and dials the lent node itself.
+  it('treats an absent field and an empty list alike: no addresses, nothing rejected', () => {
+    expect(validateBootstrapNodes(undefined)).toEqual({ nodes: [] });
+    expect(validateBootstrapNodes([])).toEqual({ nodes: [] });
   });
 
   it('rejects a non-array, and an array with a non-string element', () => {

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

@@ -7,7 +7,7 @@
  * the cross-package integration scenario.
  */
 
-import Fastify from 'fastify';
+import type { FastifyInstance } from 'fastify';
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
@@ -22,6 +22,7 @@ import type {
 
 import { registerErrorHandler } from '../error-handler.js';
 import { registerGrantsRoutes } from '../routes/grants.js';
+import { buildFastify } from '../server.js';
 import { DonationService } from '../../donation/donation-service.js';
 import { DonationStore } from '../../donation/donation-store.js';
 import { GrantService } from '../../donation/grant-service.js';
@@ -52,7 +53,7 @@ class FakeOrchestrator implements Orchestrator {
 }
 
 let tmpRoot: string;
-let app: ReturnType<typeof Fastify>;
+let app: FastifyInstance;
 let grants: GrantService;
 let store: DonationStore;
 let token: string;
@@ -78,7 +79,8 @@ beforeEach(() => {
   token = grants.issue({ label: 'Alice', maxNodes: 2 }).token;
   store = new DonationStore(join(tmpRoot, 'donations'));
   const donations = new DonationService({ orchestrator: new FakeOrchestrator(), grants, store });
-  app = Fastify();
+  // The production constructor, so these tests run with the same body parsing.
+  app = buildFastify();
   registerErrorHandler(app);
   registerGrantsRoutes(app, { donations, grants });
 });
@@ -182,7 +184,6 @@ describe('POST /grants', () => {
       // finds no transport for it, and the node is alone just the same.
       ['/p2p/12D3KooWA9hbnKrRnPRSPTRkzXqTHzGE8YpJ3JHZmQ5tGwLRTMmp'],
       [''],
-      [],
     ];
     for (const bootstrapNodes of bad) {
       const res = await app.inject({
@@ -196,6 +197,20 @@ describe('POST /grants', () => {
     expect((list.json() as { data: { donations: unknown[] } }).data.donations).toHaveLength(0);
   });
 
+  // A phone has no address to give, so it sends none and dials the lent node itself:
+  // leaving the field out, or sending an empty list, provisions a node with no
+  // bootstrap peers rather than being rejected.
+  it('provisions with bootstrapNodes absent or empty → 201, recording an empty list', async () => {
+    const { bootstrapNodes: _bootstrapNodes, ...withoutBootstrap } = body;
+    for (const payload of [withoutBootstrap, { ...body, bootstrapNodes: [] }]) {
+      const res = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload });
+      expect(res.statusCode, `expected 201 for ${JSON.stringify(payload)}`).toBe(201);
+      const donation = (res.json() as { data: { donation: { id: string; bootstrapNodes?: string[] } } }).data.donation;
+      expect(donation.bootstrapNodes).toEqual([]);
+      expect(store.get(donation.id)?.bootstrapNodes).toEqual([]);
+    }
+  });
+
   it('rejects a non-string partyId → 400, rather than stringifying it into the child config', async () => {
     for (const partyId of [42, { id: 'party-P' }, '   ']) {
       const res = await app.inject({
@@ -323,4 +338,57 @@ describe('DELETE /grants/:id', () => {
     const one = await app.inject({ method: 'GET', url: `/grants/${id}`, headers: bearer(token) });
     expect((one.json() as { data: { donation: { status: string } } }).data.donation.status).toBe('terminated');
   });
+
+  // The phone app sent `content-type: application/json` on its body-less DELETE, and
+  // Fastify's default parser answered 400 FST_ERR_CTP_EMPTY_JSON_BODY — so the loan,
+  // and the host's node, kept running.
+  it('ends the loan when the DELETE declares JSON but sends no body', async () => {
+    const created = await app.inject({ method: 'POST', url: '/grants', headers: bearer(token), payload: body });
+    const id = (created.json() as { data: { donation: { id: string } } }).data.donation.id;
+
+    const del = await app.inject({
+      method: 'DELETE', url: `/grants/${id}`,
+      headers: { ...bearer(token), 'content-type': 'application/json' },
+    });
+    expect(del.statusCode).toBe(200);
+    expect(store.get(id)?.status).toBe('terminated');
+  });
+});
+
+describe('JSON body parsing (buildFastify)', () => {
+  const json = (t: string) => ({ ...bearer(t), 'content-type': 'application/json' });
+
+  it('treats a declared-JSON empty body as no body, so the route answers its own 400', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', headers: json(token) });
+    expect(res.statusCode).toBe(400);
+    const error = (res.json() as { error: { code: string; message: string } }).error;
+    expect(error.code).toBe('invalid_request');
+    expect(error.message).toBe('partyId is required');
+  });
+
+  it('still rejects a non-empty malformed body → 400 FST_ERR_CTP_INVALID_JSON_BODY', async () => {
+    const res = await app.inject({ method: 'POST', url: '/grants', headers: json(token), payload: '{"partyId":' });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('FST_ERR_CTP_INVALID_JSON_BODY');
+  });
+
+  it('still refuses a prototype-poisoning body, as Fastify\'s own parser does', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants', headers: json(token),
+      payload: '{"partyId":"party-P","__proto__":{"polluted":true}}',
+    });
+    expect(res.statusCode).toBe(400);
+    expect((res.json() as { error: { code: string } }).error.code).toBe('FST_ERR_CTP_INVALID_JSON_BODY');
+    const list = await app.inject({ method: 'GET', url: '/grants', headers: bearer(token) });
+    expect((list.json() as { data: { donations: unknown[] } }).data.donations).toHaveLength(0);
+  });
+
+  it('parses a well-formed body with a charset parameter on the content type', async () => {
+    const res = await app.inject({
+      method: 'POST', url: '/grants',
+      headers: { ...bearer(token), 'content-type': 'application/json; charset=utf-8' },
+      payload: JSON.stringify(body),
+    });
+    expect(res.statusCode).toBe(201);
+  });
 });

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

@@ -4,12 +4,28 @@
  * (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 rule is a duplicate of
- * cadre-provider's copy (`packages/cadre-provider/src/server/bootstrap-node-validation.ts`)
+ * 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
@@ -58,21 +74,22 @@
  * 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 rules are kept identical —
- * see the note about manual upkeep below.
+ * 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 copies 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
+ * 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 accept/reject table, 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.
+ * 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';
@@ -155,8 +172,10 @@ function validateBootstrapNode(value: string): { node: string } | { error: strin
 }
 
 /**
- * Validate the required `bootstrapNodes` field of a provision request: a non-empty
+ * 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
@@ -167,11 +186,11 @@ function validateBootstrapNode(value: string): { node: string } | { error: strin
  * 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, so the provision request carries exactly what was validated.
+ * @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 || (Array.isArray(value) && value.length === 0)) {
-    return { error: 'bootstrapNodes is required' };
+  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' };