@serfab/cadre-host 0.11.0 → 0.13.0

package/dist/server/routes/provision-request-validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provision-request-validation.js","sourceRoot":"","sources":["../../../src/server/routes/provision-request-validation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAExE,wEAAwE;AACxE,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;IAC1C,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,SAAS,iBAAiB,CAAC,KAAc;IACvC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC;IAC5C,CAAC;IACD,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,GAAG,EAAiB,EAAE,CAAC,OAAO,GAAG,KAAK,QAAQ,CAAC,EAAE,CAAC;QAClE,OAAO,EAAE,KAAK,EAAE,uCAAuC,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;AAC9B,CAAC;AAED,6EAA6E;AAC7E,SAAS,eAAe,CAAC,KAAc;IACrC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,EAAE,CAAC;IACnC,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,aAAa,EAAE,CAAC;QACnD,OAAO,EAAE,KAAK,EAAE,4CAA4C,EAAE,CAAC;IACjE,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;AAC5B,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAa,EACb,UAAkB;IAElB,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,OAAO,EAAE,KAAK,EAAE,oCAAoC,EAAE,CAAC;IACzD,CAAC;IACD,MAAM,MAAM,GAAG,IAA+B,CAAC;IAE/C,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,OAAO,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAEvC,MAAM,SAAS,GAAG,sBAAsB,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IAChE,IAAI,OAAO,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAE3C,MAAM,SAAS,GAAG,iBAAiB,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACtD,IAAI,OAAO,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC;IAE3C,MAAM,OAAO,GAAG,eAAe,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAChD,IAAI,OAAO,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAEvC,OAAO;QACL,OAAO,EAAE;YACP,UAAU;YACV,OAAO,EAAE,OAAO,CAAC,OAAO;YACxB,cAAc,EAAE,SAAS,CAAC,KAAK;YAC/B,SAAS,EAAE,SAAS,CAAC,SAAS;YAC9B,GAAG,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD;KACF,CAAC;AACJ,CAAC"}

package/dist/server/settings-store.d.ts

@@ -17,7 +17,7 @@ export interface HostSettingsStoreOptions {
 export declare class HostSettingsStore {
     private readonly configPath;
     constructor(opts: HostSettingsStoreOptions);
-    /** Read the current host.config.json (runs v1→v2 migration on first read). */
+    /** Read the current host.config.json. Throws if absent, malformed, or not version 2. */
     read(): HostConfigFile;
     /** Patch and persist. */
     update(patch: Partial<Omit<HostConfigFile, 'version'>>): HostConfigFile;

package/dist/server/settings-store.js

@@ -15,7 +15,11 @@ export class HostSettingsStore {
     constructor(opts) {
         this.configPath = configPath(opts.dataDir);
     }
-    /** Read the current host.config.json (runs v1→v2 migration on first read). */
+    // NOTE: a bad config (absent, malformed, wrong version) throws a plain Error, so
+    // /api/settings answers 500 code "internal" with the read message passed through.
+    // Fine while the UI just surfaces the text; if it ever needs to tell "your config
+    // file is unreadable" apart from a genuine server bug, give this a typed error.
+    /** Read the current host.config.json. Throws if absent, malformed, or not version 2. */
     read() {
         return readHostConfig(this.configPath);
     }

package/dist/server/settings-store.js.map

@@ -1 +1 @@
-{"version":3,"file":"settings-store.js","sourceRoot":"","sources":["../../src/server/settings-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAuB,MAAM,wBAAwB,CAAC;AAO/F,MAAM,OAAO,iBAAiB;IAG5B,YAAY,IAA8B;QACxC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,8EAA8E;IAC9E,IAAI;QACF,OAAO,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAED,yBAAyB;IACzB,MAAM,CAAC,KAA+C;QACpD,OAAO,gBAAgB,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;CACF"}
+{"version":3,"file":"settings-store.js","sourceRoot":"","sources":["../../src/server/settings-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAuB,MAAM,wBAAwB,CAAC;AAO/F,MAAM,OAAO,iBAAiB;IAG5B,YAAY,IAA8B;QACxC,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,iFAAiF;IACjF,kFAAkF;IAClF,kFAAkF;IAClF,gFAAgF;IAChF,wFAAwF;IACxF,IAAI;QACF,OAAO,cAAc,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAED,yBAAyB;IACzB,MAAM,CAAC,KAA+C;QACpD,OAAO,gBAAgB,CAAC,IAAI,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IAClD,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-host",
-  "version": "0.11.0",
+  "version": "0.13.0",
   "type": "module",
   "description": "Self-hosted cadre node manager for basement-PC deployments",
   "main": "dist/index.js",
@@ -64,9 +64,10 @@
     "@libp2p/crypto": "^5.1.13",
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
-    "@serfab/cadre-cli": "^0.11.0",
-    "@serfab/cadre-core": "^0.11.0",
-    "@serfab/cadre-provider": "^0.11.0",
+    "@multiformats/multiaddr": "^12.5.1",
+    "@serfab/cadre-cli": "^0.13.0",
+    "@serfab/cadre-core": "^0.13.0",
+    "@serfab/cadre-provider": "^0.13.0",
     "commander": "^14.0.2",
     "debug": "^4.4.3",
     "fastify": "^5.7.1",

package/src/__tests__/cli.smoke.test.ts

@@ -4,7 +4,7 @@
  */
 
 import { execFileSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 import { dirname, resolve } from 'node:path';
 import { describe, it, expect, vi } from 'vitest';
@@ -33,7 +33,7 @@ describe('cadre-host CLI smoke test', () => {
     }
   });
 
-  it('prints version', () => {
+  it('prints the version from package.json', () => {
     if (!existsSync(binPath)) {
       throw new Error(`cadre-host bin not built at ${binPath}; run \`yarn build\` first`);
     }
@@ -41,6 +41,11 @@ describe('cadre-host CLI smoke test', () => {
     const stdout = execFileSync(process.execPath, [binPath, '--version'], {
       encoding: 'utf8',
     });
-    expect(stdout.trim().length).toBeGreaterThan(0);
+    // The built CLI reads package.json at runtime, so this holds even against a
+    // stale dist — it catches the version falling back to '0.0.0-unknown'.
+    const pkg = JSON.parse(
+      readFileSync(resolve(here, '../../package.json'), 'utf8'),
+    ) as { version: string };
+    expect(stdout.trim()).toBe(pkg.version);
   });
 });

package/src/__tests__/global-setup.ts

@@ -14,10 +14,15 @@
  * build is invisible here: the suite runs the previous build and reports green
  * about code it never executed. Fail the run up front instead.
  *
- * This does not cover cadre-host's *own* `src` going stale relative to its own
- * `dist` — the CLI smoke tests spawn `dist/bin/host.js` as a child process, which
- * is a same-package staleness concern, not a cross-package one `BuildTarget` is
- * meant to check (see `test-harness/build-freshness.ts`'s module comment).
+ * NOTE: accepted tradeoff — this does not cover cadre-host's *own* `src` going
+ * stale relative to its own `dist`. The CLI smoke tests spawn `dist/bin/host.js`
+ * as a child process, which is a same-package staleness concern, not the
+ * cross-package one `BuildTarget` is meant to check (see
+ * `test-harness/build-freshness.ts`'s module comment). Consequence: a `src`-only
+ * edit to `bin/host.ts` is checked by `bin/__tests__/cli-reference.test.ts`
+ * (which reads `src`) but not by the smoke tests (which read `dist`), so run
+ * `yarn workspace @serfab/cadre-host build:server` before the suite. Revisit if
+ * a stale `dist` ever produces a false green rather than merely a weaker check.
  *
  * The guard itself lives at the repo root (`test-harness/build-freshness.ts`),
  * shared with the other suites that call it; the list of packages below is this

package/src/__tests__/orchestrator-node-identity.test.ts

@@ -1,204 +1,204 @@
-/**
- * HostProcessOrchestrator per-node identity tests.
- *
- * A donated node must keep the peer id its host cadre approved across restarts,
- * and needs a durable on-disk home for its node-local stores (`cadre-cli start`
- * opens the file-backed bootstrap-peer / trusted-owner stores only when a
- * protobuf identity key file is configured). The orchestrator therefore writes
- * `<workdir>/identity.key` once per container and passes it as
- * `--identity-protobuf`.
- *
- * A fake CLI records the `--identity-protobuf` argument it was launched with, so
- * the spawn wiring is observable without a real cadre node.
- */
-
-import { afterEach, beforeEach, describe, expect, it } from 'vitest';
-import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { HostProcessOrchestrator, OWNER_CONTAINER_ID } from '../orchestrator/host-process-orchestrator.js';
-import { loadIdentity } from '../installer/identity.js';
-
-// Writes the --identity-protobuf argument (as seen on its own command line) next
-// to the startup token, then behaves like a minimal long-lived node.
-const FAKE_CLI = `
-import fs from 'node:fs';
-import path from 'node:path';
-const args = process.argv.slice(2);
-const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
-const tokenPath = get('--startup-token-file');
-const token = process.env.CADRE_STARTUP_TOKEN ?? '';
-if (tokenPath) {
-  const dir = path.dirname(tokenPath);
-  try { fs.writeFileSync(path.join(dir, 'identity-arg.txt'), get('--identity-protobuf') ?? '', 'utf8'); } catch (e) { console.error(e); }
-  if (token) { try { fs.writeFileSync(tokenPath, token, 'utf8'); } catch (e) { console.error(e); } }
-}
-process.on('SIGTERM', () => process.exit(0));
-setInterval(() => {}, 1 << 30);
-`;
-
-let tmpRoot: string;
-let scriptPath: string;
-const orchestrators: HostProcessOrchestrator[] = [];
-
-beforeEach(() => {
-  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nodeid-'));
-  scriptPath = join(tmpRoot, 'fake-cli.mjs');
-  writeFileSync(scriptPath, FAKE_CLI, 'utf8');
-});
-
-afterEach(async () => {
-  for (const orch of orchestrators) {
-    for (const n of orch.listNodes()) {
-      try { await orch.removeContainer(n.dockerId); } catch { /* ignore */ }
-    }
-  }
-  orchestrators.length = 0;
-  await sleep(50);
-  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
-});
-
-function makeOrchestrator(
-  rootDir: string,
-  portRange: { start: number; end: number } = { start: 17500, end: 17999 },
-): HostProcessOrchestrator {
-  mkdirSync(rootDir, { recursive: true });
-  const orch = new HostProcessOrchestrator({
-    rootDir,
-    portRange,
-    stopTimeoutMs: 1500,
-    spawn: { entrypoint: scriptPath },
-  });
-  orchestrators.push(orch);
-  return orch;
-}
-
-async function waitForFile(path: string, timeoutMs = 5000): Promise<string> {
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (existsSync(path)) return readFileSync(path, 'utf8');
-    await sleep(50);
-  }
-  throw new Error(`file never appeared: ${path}`);
-}
-
-function sleep(ms: number): Promise<void> {
-  return new Promise((res) => setTimeout(res, ms));
-}
-
-describe('HostProcessOrchestrator node identity', () => {
-  it('passes --identity-protobuf pointing at a real key inside the node workdir', async () => {
-    const rootDir = join(tmpRoot, 'a');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    await orch.createContainer({
-      containerId: 'donated-1',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-
-    const workdir = join(rootDir, 'donated-1');
-    const arg = await waitForFile(join(workdir, 'identity-arg.txt'));
-    expect(arg).toBe(join(workdir, 'identity.key'));
-    // Decodes as a libp2p protobuf private key → the child gets a usable identity.
-    expect(loadIdentity(arg).peerId).toMatch(/^12D3Koo/);
-  });
-
-  it('reuses the same identity when the same containerId is spawned again', async () => {
-    const rootDir = join(tmpRoot, 'b');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    const first = await orch.createContainer({
-      containerId: 'donated-2',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-    const workdir = join(rootDir, 'donated-2');
-    await waitForFile(join(workdir, 'identity-arg.txt'));
-    const before = loadIdentity(join(workdir, 'identity.key')).peerId;
-
-    // Stop (not remove — removal deletes the workdir) and re-spawn, as a restart
-    // of a live loan would.
-    await orch.stopContainer(first.dockerId);
-    await orch.createContainer({
-      containerId: 'donated-2',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-
-    const after = loadIdentity(join(workdir, 'identity.key')).peerId;
-    expect(after).toBe(before);
-  });
-
-  it('destroys the identity with the workdir when the loan is terminated', async () => {
-    const rootDir = join(tmpRoot, 'c');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    const created = await orch.createContainer({
-      containerId: 'donated-3',
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage',
-      pinnedOwnerKeys: ['key-a'],
-    });
-    const identityPath = join(rootDir, 'donated-3', 'identity.key');
-    await waitForFile(identityPath);
-
-    await orch.removeContainer(created.dockerId);
-    expect(existsSync(identityPath)).toBe(false);
-    expect(existsSync(join(rootDir, 'donated-3'))).toBe(false);
-  });
-
-  // The failure the identity step can actually produce is a damaged key file,
-  // and `DonationService.provision` turns every such throw into an `error`
-  // record and lets the grantee retry. If the spawn path reserved its ports
-  // before the step that throws, each retry would burn four more ports out of a
-  // bounded range until provisioning stopped working altogether.
-  it('reserves no ports when the identity step fails', async () => {
-    const rootDir = join(tmpRoot, 'd');
-    // Exactly one node's worth of ports (health, metrics, p2p, admin).
-    const orch = makeOrchestrator(rootDir, { start: 18100, end: 18103 });
-    await orch.init();
-
-    mkdirSync(join(rootDir, 'donated-bad'), { recursive: true });
-    writeFileSync(join(rootDir, 'donated-bad', 'identity.key'), 'not a protobuf private key', 'utf8');
-
-    const request = {
-      partyId: 'foreign-P',
-      bootstrapNodes: [],
-      profile: 'storage' as const,
-      pinnedOwnerKeys: ['key-a'],
-    };
-    await expect(orch.createContainer({ ...request, containerId: 'donated-bad' })).rejects.toThrow();
-
-    // The whole range is still free, so a healthy container still gets its four.
-    const ok = await orch.createContainer({ ...request, containerId: 'donated-good' });
-    expect(ok.p2pPort).toBeGreaterThanOrEqual(18100);
-  });
-
-  // The owner node carries the HOST's installer identity from <dataDir>, not a
-  // per-workdir key — a second key in its workdir would mean the host's own
-  // cadre node quietly changed peer id.
-  it('leaves the owner node on its own installer identity', async () => {
-    const rootDir = join(tmpRoot, 'e');
-    const orch = makeOrchestrator(rootDir);
-    await orch.init();
-
-    const hostIdentity = join(tmpRoot, 'host-identity.key');
-    await orch.ensureOwnerNode({ identityPath: hostIdentity, partyId: 'host-P', libp2pPort: 4101 });
-
-    const ownerWorkdir = join(rootDir, OWNER_CONTAINER_ID);
-    expect(await waitForFile(join(ownerWorkdir, 'identity-arg.txt'))).toBe(hostIdentity);
-    expect(existsSync(join(ownerWorkdir, 'identity.key'))).toBe(false);
-  });
-});
+/**
+ * HostProcessOrchestrator per-node identity tests.
+ *
+ * A donated node must keep the peer id its host cadre approved across restarts,
+ * and needs a durable on-disk home for its node-local stores (`cadre-cli start`
+ * opens the file-backed bootstrap-peer / trusted-owner stores only when a
+ * protobuf identity key file is configured). The orchestrator therefore writes
+ * `<workdir>/identity.key` once per container and passes it as
+ * `--identity-file`.
+ *
+ * A fake CLI records the `--identity-file` argument it was launched with, so
+ * the spawn wiring is observable without a real cadre node.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { HostProcessOrchestrator, OWNER_CONTAINER_ID } from '../orchestrator/host-process-orchestrator.js';
+import { loadIdentity } from '../installer/identity.js';
+
+// Writes the --identity-file argument (as seen on its own command line) next
+// to the startup token, then behaves like a minimal long-lived node.
+const FAKE_CLI = `
+import fs from 'node:fs';
+import path from 'node:path';
+const args = process.argv.slice(2);
+const get = (flag) => { const i = args.indexOf(flag); return i >= 0 ? args[i + 1] : undefined; };
+const tokenPath = get('--startup-token-file');
+const token = process.env.CADRE_STARTUP_TOKEN ?? '';
+if (tokenPath) {
+  const dir = path.dirname(tokenPath);
+  try { fs.writeFileSync(path.join(dir, 'identity-arg.txt'), get('--identity-file') ?? '', 'utf8'); } catch (e) { console.error(e); }
+  if (token) { try { fs.writeFileSync(tokenPath, token, 'utf8'); } catch (e) { console.error(e); } }
+}
+process.on('SIGTERM', () => process.exit(0));
+setInterval(() => {}, 1 << 30);
+`;
+
+let tmpRoot: string;
+let scriptPath: string;
+const orchestrators: HostProcessOrchestrator[] = [];
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-nodeid-'));
+  scriptPath = join(tmpRoot, 'fake-cli.mjs');
+  writeFileSync(scriptPath, FAKE_CLI, 'utf8');
+});
+
+afterEach(async () => {
+  for (const orch of orchestrators) {
+    for (const n of orch.listNodes()) {
+      try { await orch.removeContainer(n.dockerId); } catch { /* ignore */ }
+    }
+  }
+  orchestrators.length = 0;
+  await sleep(50);
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+function makeOrchestrator(
+  rootDir: string,
+  portRange: { start: number; end: number } = { start: 17500, end: 17999 },
+): HostProcessOrchestrator {
+  mkdirSync(rootDir, { recursive: true });
+  const orch = new HostProcessOrchestrator({
+    rootDir,
+    portRange,
+    stopTimeoutMs: 1500,
+    spawn: { entrypoint: scriptPath },
+  });
+  orchestrators.push(orch);
+  return orch;
+}
+
+async function waitForFile(path: string, timeoutMs = 5000): Promise<string> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (existsSync(path)) return readFileSync(path, 'utf8');
+    await sleep(50);
+  }
+  throw new Error(`file never appeared: ${path}`);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+describe('HostProcessOrchestrator node identity', () => {
+  it('passes --identity-file pointing at a real key inside the node workdir', async () => {
+    const rootDir = join(tmpRoot, 'a');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    await orch.createContainer({
+      containerId: 'donated-1',
+      partyId: 'foreign-P',
+      bootstrapNodes: [],
+      profile: 'storage',
+      pinnedOwnerKeys: ['key-a'],
+    });
+
+    const workdir = join(rootDir, 'donated-1');
+    const arg = await waitForFile(join(workdir, 'identity-arg.txt'));
+    expect(arg).toBe(join(workdir, 'identity.key'));
+    // Decodes as a libp2p protobuf private key → the child gets a usable identity.
+    expect(loadIdentity(arg).peerId).toMatch(/^12D3Koo/);
+  });
+
+  it('reuses the same identity when the same containerId is spawned again', async () => {
+    const rootDir = join(tmpRoot, 'b');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    const first = await orch.createContainer({
+      containerId: 'donated-2',
+      partyId: 'foreign-P',
+      bootstrapNodes: [],
+      profile: 'storage',
+      pinnedOwnerKeys: ['key-a'],
+    });
+    const workdir = join(rootDir, 'donated-2');
+    await waitForFile(join(workdir, 'identity-arg.txt'));
+    const before = loadIdentity(join(workdir, 'identity.key')).peerId;
+
+    // Stop (not remove — removal deletes the workdir) and re-spawn, as a restart
+    // of a live loan would.
+    await orch.stopContainer(first.dockerId);
+    await orch.createContainer({
+      containerId: 'donated-2',
+      partyId: 'foreign-P',
+      bootstrapNodes: [],
+      profile: 'storage',
+      pinnedOwnerKeys: ['key-a'],
+    });
+
+    const after = loadIdentity(join(workdir, 'identity.key')).peerId;
+    expect(after).toBe(before);
+  });
+
+  it('destroys the identity with the workdir when the loan is terminated', async () => {
+    const rootDir = join(tmpRoot, 'c');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    const created = await orch.createContainer({
+      containerId: 'donated-3',
+      partyId: 'foreign-P',
+      bootstrapNodes: [],
+      profile: 'storage',
+      pinnedOwnerKeys: ['key-a'],
+    });
+    const identityPath = join(rootDir, 'donated-3', 'identity.key');
+    await waitForFile(identityPath);
+
+    await orch.removeContainer(created.dockerId);
+    expect(existsSync(identityPath)).toBe(false);
+    expect(existsSync(join(rootDir, 'donated-3'))).toBe(false);
+  });
+
+  // The failure the identity step can actually produce is a damaged key file,
+  // and `DonationService.provision` turns every such throw into an `error`
+  // record and lets the grantee retry. If the spawn path reserved its ports
+  // before the step that throws, each retry would burn four more ports out of a
+  // bounded range until provisioning stopped working altogether.
+  it('reserves no ports when the identity step fails', async () => {
+    const rootDir = join(tmpRoot, 'd');
+    // Exactly one node's worth of ports (health, metrics, p2p, admin).
+    const orch = makeOrchestrator(rootDir, { start: 18100, end: 18103 });
+    await orch.init();
+
+    mkdirSync(join(rootDir, 'donated-bad'), { recursive: true });
+    writeFileSync(join(rootDir, 'donated-bad', 'identity.key'), 'not a protobuf private key', 'utf8');
+
+    const request = {
+      partyId: 'foreign-P',
+      bootstrapNodes: [],
+      profile: 'storage' as const,
+      pinnedOwnerKeys: ['key-a'],
+    };
+    await expect(orch.createContainer({ ...request, containerId: 'donated-bad' })).rejects.toThrow();
+
+    // The whole range is still free, so a healthy container still gets its four.
+    const ok = await orch.createContainer({ ...request, containerId: 'donated-good' });
+    expect(ok.p2pPort).toBeGreaterThanOrEqual(18100);
+  });
+
+  // The owner node carries the HOST's installer identity from <dataDir>, not a
+  // per-workdir key — a second key in its workdir would mean the host's own
+  // cadre node quietly changed peer id.
+  it('leaves the owner node on its own installer identity', async () => {
+    const rootDir = join(tmpRoot, 'e');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    const hostIdentity = join(tmpRoot, 'host-identity.key');
+    await orch.ensureOwnerNode({ identityPath: hostIdentity, partyId: 'host-P', libp2pPort: 4101 });
+
+    const ownerWorkdir = join(rootDir, OWNER_CONTAINER_ID);
+    expect(await waitForFile(join(ownerWorkdir, 'identity-arg.txt'))).toBe(hostIdentity);
+    expect(existsSync(join(ownerWorkdir, 'identity.key'))).toBe(false);
+  });
+});