@serfab/cadre-host 0.8.1 → 0.10.0

package/dist/ui/index.html

@@ -5,8 +5,8 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <meta name="color-scheme" content="light dark" />
     <title>cadre-host</title>
-    <script type="module" crossorigin src="./assets/index-BlMXQPSw.js"></script>
-    <link rel="stylesheet" crossorigin href="./assets/index-BwU5mJGF.css">
+    <script type="module" crossorigin src="./assets/index-C-iks41M.js"></script>
+    <link rel="stylesheet" crossorigin href="./assets/index-BVoqLjyX.css">
   </head>
   <body>
     <div id="app"></div>

package/dist/update/release-key.d.ts

@@ -21,7 +21,7 @@ export declare function getReleasePublicKey(env?: NodeJS.ProcessEnv): KeyObject;
  * ships in source until the release operator embeds a real public key.
  *
  * Consumers:
- *  - the publish guard (`scripts/publish-package.js`) refuses to ship a build
+ *  - the publish guard (`scripts/publish-package.mjs`) refuses to ship a build
  *    whose embedded key is still the placeholder, so a real release can never
  *    silently ship the dead key;
  *  - `UpdateService.check()` logs a diagnostic breadcrumb so a misbuilt binary

package/dist/update/release-key.js

@@ -9,11 +9,13 @@
  */
 import { createPublicKey } from 'node:crypto';
 /**
- * Raw 32-byte Ed25519 public key, base64-encoded. The all-zeros value below is
- * the placeholder that ships in source until the release operator embeds a real
- * key (`isPlaceholderReleaseKey` reports it; the publish guard refuses to ship
- * it). Mismatch with the real signer surfaces as `signature_invalid`, which the
- * UI treats as "update available but unverifiable" rather than auto-applying.
+ * Raw 32-byte Ed25519 public key, base64-encoded. This is the real production
+ * public key embedded by the release operator (see the "Release signing"
+ * runbook in `docs/cadre-host.md`). Before a real key was embedded the source
+ * shipped an all-zeros placeholder; `isPlaceholderReleaseKey` still detects that
+ * state and the publish guard refuses to ship it. Mismatch with the real signer
+ * surfaces as `signature_invalid`, which the UI treats as "update available but
+ * unverifiable" rather than auto-applying.
  */
 const PROD_KEY_BASE64 = 'XyRVnOY9DVgU6xdMgJIguOsc9B2L1o2KoU9626Nk+OE=';
 /**
@@ -36,7 +38,7 @@ export function getReleasePublicKey(env = process.env) {
  * ships in source until the release operator embeds a real public key.
  *
  * Consumers:
- *  - the publish guard (`scripts/publish-package.js`) refuses to ship a build
+ *  - the publish guard (`scripts/publish-package.mjs`) refuses to ship a build
  *    whose embedded key is still the placeholder, so a real release can never
  *    silently ship the dead key;
  *  - `UpdateService.check()` logs a diagnostic breadcrumb so a misbuilt binary

package/dist/update/release-key.js.map

@@ -1 +1 @@
-{"version":3,"file":"release-key.js","sourceRoot":"","sources":["../../src/update/release-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;GAMG;AACH,MAAM,eAAe,GAAG,8CAA8C,CAAC;AAEvE;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC5E,MAAM,QAAQ,GAAG,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,OAAO,cAAc,CAAC,yBAAyB,CAAC,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1E,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,4CAA4C,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,0DAA0D;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACrE,CAAC"}
+{"version":3,"file":"release-key.js","sourceRoot":"","sources":["../../src/update/release-key.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;GAQG;AACH,MAAM,eAAe,GAAG,8CAA8C,CAAC;AAEvE;;;GAGG;AACH,MAAM,UAAU,yBAAyB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC5E,MAAM,QAAQ,GAAG,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE,CAAC;IACvD,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,QAAQ,CAAC;IACrD,OAAO,eAAe,CAAC;AACzB,CAAC;AAED,0DAA0D;AAC1D,MAAM,UAAU,mBAAmB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACtE,OAAO,cAAc,CAAC,yBAAyB,CAAC,GAAG,CAAC,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC1E,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,yBAAyB,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,CAAC;IAClE,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IACpC,OAAO,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;AACnC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB;IAC9C,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAC7C,IAAI,GAAG,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,4CAA4C,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,0DAA0D;IAC1D,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;AACrE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serfab/cadre-host",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "type": "module",
   "description": "Self-hosted cadre node manager for basement-PC deployments",
   "main": "dist/index.js",
@@ -38,7 +38,7 @@
     "build:server": "tsc -p tsconfig.build.json",
     "build:ui": "vite build --config ui/vite.config.ts",
     "dev:ui": "vite --config ui/vite.config.ts",
-    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit",
+    "typecheck": "tsc -p tsconfig.typecheck.json --noEmit && tsc -p ui/tsconfig.json --noEmit",
     "check:svelte": "svelte-check --tsconfig tsconfig.json --workspace ui",
     "test": "vitest run --passWithNoTests",
     "dev:test": "vitest",
@@ -64,9 +64,9 @@
     "@libp2p/crypto": "^5.1.13",
     "@libp2p/interface": "^3.1.0",
     "@libp2p/peer-id": "^6.0.4",
-    "@serfab/cadre-cli": "^0.8.1",
-    "@serfab/cadre-core": "^0.8.1",
-    "@serfab/cadre-provider": "^0.8.1",
+    "@serfab/cadre-cli": "^0.10.0",
+    "@serfab/cadre-core": "^0.10.0",
+    "@serfab/cadre-provider": "^0.10.0",
     "commander": "^14.0.2",
     "debug": "^4.4.3",
     "fastify": "^5.7.1",

package/src/__tests__/build-targets.test.ts

@@ -0,0 +1,26 @@
+/**
+ * Holds this suite's stale-build target list against the package it guards.
+ *
+ * `global-setup.ts`'s `TARGETS` is hand-written. Without this, adding a workspace
+ * or linked dependency to `package.json` leaves it unguarded and says nothing —
+ * the suite goes on passing while it runs that dependency's stale `dist`.
+ *
+ * The list is deliberately wider than `dependencies` (it also covers
+ * `quereus-plugin-sereus` and the packages beneath it, reached transitively
+ * through `cadre-core`), so only missing entries fail — extra ones are the point.
+ *
+ * Both pinned names are `workspace:` deps: cadre-host declares no `link:` entry of
+ * its own — those arrive transitively through `@serfab/cadre-core`.
+ */
+
+import { describeBuildTargets, packageRootFrom } from '../../../../test-harness/build-targets-spec.js';
+import { TARGETS } from './global-setup.js';
+
+describeBuildTargets('cadre-host', {
+	packageDir: packageRootFrom(import.meta.url, '..', '..'),
+	targets: TARGETS,
+	expectFound: {
+		'@serfab/cadre-core': 'workspace',
+		'@serfab/cadre-cli': 'workspace',
+	},
+});

package/src/__tests__/global-setup.ts

@@ -0,0 +1,51 @@
+/**
+ * Vitest global setup — runs once before the whole cadre-host suite.
+ *
+ * `src/update/manifest.ts` and `src/push/index.ts` import real symbols from
+ * `@serfab/cadre-core` (`canonicalJson`, `validatePushCredentials`), and
+ * `trust-circle-integration.test.ts` imports and drives a real `CadreNode` from
+ * it too. `@serfab/cadre-core`'s compiled entry point in turn imports
+ * `@serfab/quereus-plugin-sereus`, which imports the `@optimystic/*` and
+ * `@quereus/quereus` packages linked in from their sibling checkouts.
+ * `host-process-orchestrator.ts` also resolves `@serfab/cadre-cli`'s bin path at
+ * runtime, and `@serfab/cadre-provider` is a declared dependency in its own
+ * right. Every one of those resolves through a `node_modules` symlink whose
+ * manifest points at `dist`, so an edit to any of their `src` with no following
+ * 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).
+ *
+ * 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
+ * suite's own concern.
+ */
+
+import { assertBuildFresh, type BuildTarget } from '../../../../test-harness/build-freshness.js';
+
+/**
+ * Every package this suite runs compiled code from — the `workspace:` entries of
+ * `package.json`'s `dependencies`, plus the `link:` packages reached
+ * transitively through them.
+ *
+ * Exported so `build-targets.test.ts` can hold it against this package's actual
+ * `dependencies` — a hand-written list rots silently otherwise.
+ */
+export const TARGETS: BuildTarget[] = [
+	{ packageName: '@serfab/cadre-cli', distEntry: 'dist/bin/cadre.js', location: 'workspace' },
+	{ packageName: '@serfab/cadre-core', distEntry: 'dist/index.js', location: 'workspace' },
+	{ packageName: '@serfab/cadre-provider', distEntry: 'dist/index.js', location: 'workspace' },
+	{ packageName: '@serfab/quereus-plugin-sereus', distEntry: 'dist/index.js', location: 'workspace' },
+	{ packageName: '@optimystic/db-core', distEntry: 'dist/src/index.js', location: 'linked' },
+	{ packageName: '@optimystic/db-p2p', distEntry: 'dist/src/index.js', location: 'linked' },
+	{ packageName: '@optimystic/quereus-plugin-crypto', distEntry: 'dist/index.js', location: 'linked' },
+	{ packageName: '@optimystic/quereus-plugin-optimystic', distEntry: 'dist/index.js', location: 'linked' },
+	{ packageName: '@quereus/quereus', distEntry: 'dist/src/index.js', location: 'linked' },
+];
+
+export default function setup(): void {
+	assertBuildFresh(TARGETS, import.meta.url);
+}

package/src/__tests__/{host-authority.smoke.test.ts → host-owner.smoke.test.ts}

@@ -1,14 +1,14 @@
 /**
- * Server-level smoke: the /auth/* HTTP contract over the authority-node
+ * Server-level smoke: the /auth/* HTTP contract over the owner-node
  * channel adapter. Validates the two behaviours the realignment must
  * preserve:
  *   1. With the node up, POST /auth/invites returns an encodedInvite (no 500).
  *   2. With the node refusing connections, GET /auth/trust-circle still lists
  *      local labels, and POST /auth/invites returns 503 (not a raw 500).
  *
- * The authority node is represented by a stub HTTP server matching the 6.6
+ * The owner node is represented by a stub HTTP server matching the 6.6
  * admin contract (the spawn path itself is covered by
- * orchestrator-authority.test.ts).
+ * orchestrator-owner.test.ts).
  */
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
@@ -19,7 +19,7 @@ import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
 import { TrustCircleService, TrustCircleStore, createTrustCircleHandlers } from '../auth/index.js';
-import { AuthorityNodeClient } from '../authority/index.js';
+import { OwnerNodeClient } from '../owner/index.js';
 import { registerErrorHandler } from '../server/error-handler.js';
 import { registerTrustCircleRoutes } from '../server/routes/trust-circle.js';
 import { EventBus } from '../server/events/bus.js';
@@ -51,7 +51,7 @@ describe('host /auth delegation — node up', () => {
         }
         if (req.url === '/admin/invites' && req.method === 'POST') {
           res.writeHead(200, { 'content-type': 'application/json' });
-          res.end(JSON.stringify({ ok: true, data: { invite: { partyId: 'p', authorityAddrs: [], token: 't', createdAt: 1 }, encodedInvite: 'ENC' } }));
+          res.end(JSON.stringify({ ok: true, data: { invite: { partyId: 'p', ownerAddrs: [], token: 't', createdAt: 1 }, encodedInvite: 'ENC' } }));
           return;
         }
         if (req.url === '/admin/members' && req.method === 'GET') {
@@ -70,7 +70,7 @@ describe('host /auth delegation — node up', () => {
   afterEach(async () => { await new Promise<void>((resolve) => server.close(() => resolve())); });
 
   it('POST /auth/invites returns an encodedInvite (no 500)', async () => {
-    const client = new AuthorityNodeClient({ baseUrl, token: TOKEN });
+    const client = new OwnerNodeClient({ baseUrl, token: TOKEN });
     const service = new TrustCircleService({ cadreNode: client, store: new TrustCircleStore(tmpRoot) });
     const app = buildApp(service);
     try {
@@ -103,7 +103,7 @@ describe('host /auth delegation — node refusing connections', () => {
     const store = new TrustCircleStore(tmpRoot);
     store.addMember({ peerId: '12D3KooWLocal', label: 'My laptop', addedAt: '2025-01-01T00:00:00Z' });
 
-    const client = new AuthorityNodeClient({ baseUrl: closedBaseUrl, token: TOKEN });
+    const client = new OwnerNodeClient({ baseUrl: closedBaseUrl, token: TOKEN });
     const service = new TrustCircleService({ cadreNode: client, store });
     const app = buildApp(service);
     try {

package/src/__tests__/orchestrator-env-scrub.test.ts

@@ -0,0 +1,140 @@
+/**
+ * HostProcessOrchestrator env-scrub test — the manager's own `process.env` must
+ * not leak `CADRE_*` config-override vars into spawned children.
+ *
+ * `launchChild` used to build each child's environment as
+ * `{ ...process.env, ...extraEnv, <fixed per-child vars> }`, so ANY `CADRE_*`
+ * var set on the manager (not just the ones the orchestrator deliberately
+ * sets) reached every child. Because `@serfab/cadre-cli` treats an inherited
+ * `CADRE_*` var as a config override that beats the per-child config file, a
+ * `CADRE_PARTY_ID` set on the manager could silently pull every child into
+ * that party.
+ *
+ * A fake CLI records the vars under test from its environment to a file so
+ * the scrub 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 } from '../orchestrator/host-process-orchestrator.js';
+
+// Writes the vars under test (as seen in the child env) next to the startup token.
+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);
+  const record = {
+    CADRE_PARTY_ID: process.env.CADRE_PARTY_ID ?? null,
+    CADRE_STORAGE_PATH: process.env.CADRE_STORAGE_PATH ?? null,
+    CADRE_ADMIN_PORT: process.env.CADRE_ADMIN_PORT ?? null,
+    DEBUG: process.env.DEBUG ?? null,
+  };
+  try { fs.writeFileSync(path.join(dir, 'env-seen.json'), JSON.stringify(record), '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[] = [];
+let savedEnv: Record<string, string | undefined>;
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-env-scrub-'));
+  scriptPath = join(tmpRoot, 'fake-cli.mjs');
+  writeFileSync(scriptPath, FAKE_CLI, 'utf8');
+  savedEnv = {
+    CADRE_PARTY_ID: process.env.CADRE_PARTY_ID,
+    CADRE_STORAGE_PATH: process.env.CADRE_STORAGE_PATH,
+    CADRE_ADMIN_PORT: process.env.CADRE_ADMIN_PORT,
+    DEBUG: process.env.DEBUG,
+  };
+});
+
+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 */ }
+  for (const [key, value] of Object.entries(savedEnv)) {
+    if (value === undefined) delete process.env[key];
+    else process.env[key] = value;
+  }
+});
+
+function makeOrchestrator(rootDir: string): HostProcessOrchestrator {
+  mkdirSync(rootDir, { recursive: true });
+  const orch = new HostProcessOrchestrator({
+    rootDir,
+    portRange: { start: 18000, end: 18499 },
+    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 child env scrub', () => {
+  it('does not leak manager CADRE_* config-override vars into children, but passes through non-CADRE vars', async () => {
+    process.env.CADRE_PARTY_ID = 'conflicting-party';
+    process.env.CADRE_STORAGE_PATH = '/tmp/should-not-leak';
+    // Not an ENV_MAPPINGS config override — read directly by the cli's `start`
+    // command — so it only stays scrubbed if the scrub is prefix-wide.
+    process.env.CADRE_ADMIN_PORT = '19999';
+    process.env.DEBUG = 'some:value';
+
+    const rootDir = join(tmpRoot, 'a');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+
+    await orch.createContainer({
+      containerId: 'child-1',
+      partyId: 'party-1',
+      bootstrapNodes: [],
+      profile: 'storage',
+    });
+    await orch.createContainer({
+      containerId: 'child-2',
+      partyId: 'party-2',
+      bootstrapNodes: [],
+      profile: 'storage',
+    });
+
+    const seen1 = JSON.parse(await waitForFile(join(rootDir, 'child-1', 'env-seen.json')));
+    const seen2 = JSON.parse(await waitForFile(join(rootDir, 'child-2', 'env-seen.json')));
+
+    for (const seen of [seen1, seen2]) {
+      expect(seen.CADRE_PARTY_ID).toBeNull();
+      expect(seen.CADRE_STORAGE_PATH).toBeNull();
+      expect(seen.CADRE_ADMIN_PORT).toBeNull();
+      expect(seen.DEBUG).toBe('some:value');
+    }
+  });
+});

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

@@ -0,0 +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);
+  });
+});