@serfab/cadre-host 0.7.1 → 0.8.1

package/src/__tests__/orchestrator-authority.test.ts

@@ -0,0 +1,198 @@
+/**
+ * HostProcessOrchestrator authority-node lifecycle tests.
+ *
+ * Uses the `spawn.entrypoint` hook with a fake CLI that writes its startup
+ * token and binds a minimal `/admin/identity` endpoint on the admin port —
+ * enough to validate spawn, idempotency, admin-port allocation/persistence,
+ * the end-to-end AuthorityNodeClient round-trip, and init() re-attach.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { HostProcessOrchestrator, AUTHORITY_CONTAINER_ID } from '../orchestrator/host-process-orchestrator.js';
+import { StateStore } from '../orchestrator/state-store.js';
+import { isPidAlive } from '../orchestrator/pid-liveness.js';
+import { decodeDockerId } from '../orchestrator/types.js';
+import { AuthorityNodeClient } from '../authority/authority-node-client.js';
+
+const FAKE_AUTHORITY_CLI = `
+import fs from 'node:fs';
+import http from 'node:http';
+
+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 adminPort = get('--admin-port');
+const token = process.env.CADRE_STARTUP_TOKEN ?? '';
+
+if (tokenPath && token) {
+  try { fs.writeFileSync(tokenPath, token, 'utf8'); } catch (err) { console.error('token write failed', err); }
+}
+
+if (adminPort && token) {
+  const server = http.createServer((req, res) => {
+    const auth = req.headers['authorization'];
+    if (auth !== 'Bearer ' + token) {
+      res.writeHead(401, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: false, error: { code: 'not_authorized', message: 'bad token' } }));
+      return;
+    }
+    if (req.url === '/admin/identity' && req.method === 'GET') {
+      res.writeHead(200, { 'content-type': 'application/json' });
+      res.end(JSON.stringify({ ok: true, data: { peerId: 'FAKEPEER', partyId: 'fake-party' } }));
+      return;
+    }
+    res.writeHead(400, { 'content-type': 'application/json' });
+    res.end(JSON.stringify({ ok: false, error: { code: 'bad_request', message: req.url } }));
+  });
+  server.listen(parseInt(adminPort, 10), '127.0.0.1', () => {
+    console.log('admin listening on ' + adminPort);
+  });
+}
+
+process.on('SIGTERM', () => process.exit(0));
+console.log('fake authority up');
+setInterval(() => {}, 1 << 30);
+`;
+
+let tmpRoot: string;
+let scriptPath: string;
+const orchestrators: HostProcessOrchestrator[] = [];
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-auth-'));
+  scriptPath = join(tmpRoot, 'fake-authority.mjs');
+  writeFileSync(scriptPath, FAKE_AUTHORITY_CLI, 'utf8');
+});
+
+afterEach(async () => {
+  for (const orch of orchestrators) {
+    try { await orch.stopAuthorityNode(); } catch { /* ignore */ }
+    for (const dockerId of listDockerIds(orch)) {
+      try { await orch.removeContainer(dockerId); } catch { /* ignore */ }
+    }
+  }
+  orchestrators.length = 0;
+  await sleep(50);
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+function makeOrchestrator(rootDir: string): HostProcessOrchestrator {
+  mkdirSync(rootDir, { recursive: true });
+  const orch = new HostProcessOrchestrator({
+    rootDir,
+    portRange: { start: 18500, end: 18999 },
+    stopTimeoutMs: 1500,
+    spawn: { entrypoint: scriptPath },
+  });
+  orchestrators.push(orch);
+  return orch;
+}
+
+function listDockerIds(orch: HostProcessOrchestrator): string[] {
+  const state = new StateStore((orch as unknown as { rootDir: string }).rootDir);
+  return state.load().handles.map((h) => h.dockerId);
+}
+
+async function waitFor(predicate: () => boolean | Promise<boolean>, timeoutMs = 4000, intervalMs = 50): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await predicate()) return;
+    await sleep(intervalMs);
+  }
+  throw new Error('waitFor: timed out');
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+const CFG = { identityPath: 'C:/fake/identity.key', partyId: 'install-id-123', libp2pPort: 4555 };
+
+describe('HostProcessOrchestrator.ensureAuthorityNode', () => {
+  it('spawns the authority node, allocates+persists an admin port', async () => {
+    const orch = makeOrchestrator(join(tmpRoot, 'a'));
+    await orch.init();
+    const node = await orch.ensureAuthorityNode(CFG);
+
+    expect(node.id).toBe(AUTHORITY_CONTAINER_ID);
+    expect(node.authority).toBe(true);
+    expect(node.ports.admin).toBeGreaterThanOrEqual(18500);
+    expect(node.ports.p2p).toBe(4555);
+
+    const endpoint = orch.getAuthorityAdminEndpoint();
+    expect(endpoint).toBeDefined();
+    expect(endpoint!.baseUrl).toBe(`http://127.0.0.1:${node.ports.admin}`);
+
+    // Persisted with admin port + authority flag + authorityConfig.
+    const persisted = new StateStore(join(tmpRoot, 'a')).load();
+    expect(persisted.authorityConfig).toMatchObject({ partyId: 'install-id-123', libp2pPort: 4555 });
+    const ph = persisted.handles.find((h) => h.containerId === AUTHORITY_CONTAINER_ID);
+    expect(ph?.authority).toBe(true);
+    expect(typeof ph?.ports.admin).toBe('number');
+  });
+
+  it('is idempotent — a second call does not spawn a second child', async () => {
+    const orch = makeOrchestrator(join(tmpRoot, 'b'));
+    await orch.init();
+    const first = await orch.ensureAuthorityNode(CFG);
+    await waitFor(() => orch.isRunning(first.dockerId));
+
+    const second = await orch.ensureAuthorityNode(CFG);
+    expect(second.dockerId).toBe(first.dockerId);
+    expect(orch.listNodes()).toHaveLength(1);
+  });
+
+  it('the AuthorityNodeClient reaches the spawned admin channel', async () => {
+    const orch = makeOrchestrator(join(tmpRoot, 'c'));
+    await orch.init();
+    const node = await orch.ensureAuthorityNode(CFG);
+    await waitFor(() => orch.isRunning(node.dockerId));
+
+    const client = new AuthorityNodeClient(() => orch.getAuthorityAdminEndpoint());
+    await waitFor(async () => {
+      try { return (await client.getPeerId()) === 'FAKEPEER'; } catch { return false; }
+    });
+    expect(await client.getPeerId()).toBe('FAKEPEER');
+  });
+
+  it('getAuthorityAdminEndpoint() survives an init() re-attach', async () => {
+    const rootDir = join(tmpRoot, 'd');
+    const a = makeOrchestrator(rootDir);
+    await a.init();
+    const node = await a.ensureAuthorityNode(CFG);
+    await waitFor(() => a.isRunning(node.dockerId));
+    const before = a.getAuthorityAdminEndpoint();
+
+    const b = makeOrchestrator(rootDir);
+    await b.init();
+    expect(b.isAuthorityNode(AUTHORITY_CONTAINER_ID)).toBe(true);
+    expect(b.hasAuthorityConfig()).toBe(true);
+    const after = b.getAuthorityAdminEndpoint();
+    expect(after).toEqual(before);
+    expect(await b.isRunning(node.dockerId)).toBe(true);
+
+    const { pid } = decodeDockerId(node.dockerId);
+    expect(isPidAlive(pid)).toBe(true);
+  });
+
+  it('restartAuthorityNode preserves the workdir and re-spawns', async () => {
+    const orch = makeOrchestrator(join(tmpRoot, 'e'));
+    await orch.init();
+    const first = await orch.ensureAuthorityNode(CFG);
+    await waitFor(() => orch.isRunning(first.dockerId));
+    const { pid: firstPid } = decodeDockerId(first.dockerId);
+
+    const restarted = await orch.restartAuthorityNode();
+    await waitFor(() => orch.isRunning(restarted.dockerId));
+
+    // New child (different pid/token), still exactly one node, workdir reused.
+    expect(restarted.dockerId).not.toBe(first.dockerId);
+    expect(orch.listNodes()).toHaveLength(1);
+    await waitFor(() => !isPidAlive(firstPid));
+  });
+});

package/src/__tests__/orchestrator-push.test.ts

@@ -0,0 +1,145 @@
+/**
+ * HostProcessOrchestrator push-credential injection tests.
+ *
+ * Verifies the orchestrator writes `config.push` into the spawned node's
+ * cadre.json when the pushResolver yields credentials, omits it otherwise,
+ * re-resolves on every (re-)spawn, and never persists a raw private key in
+ * state.json. Uses a fake CLI entrypoint that just writes its startup token.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdtempSync, mkdirSync, rmSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import type { PushCredentials } from '@serfab/cadre-core';
+import { HostProcessOrchestrator, AUTHORITY_CONTAINER_ID } from '../orchestrator/host-process-orchestrator.js';
+
+const FAKE_CLI = `
+import fs from 'node:fs';
+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 && token) { try { fs.writeFileSync(tokenPath, token, 'utf8'); } catch (e) { console.error(e); } }
+process.on('SIGTERM', () => process.exit(0));
+setInterval(() => {}, 1 << 30);
+`;
+
+const FCM = { projectId: 'proj', clientEmail: 'svc@proj.iam', privateKey: 'FCM-SECRET-PEM' };
+const APNS = { keyId: 'KID', teamId: 'TEAM', bundleId: 'com.example.app', privateKey: 'APNS-SECRET-P8', production: false };
+const CFG = { identityPath: 'C:/fake/identity.key', partyId: 'install-id-123', libp2pPort: 4655 };
+
+let tmpRoot: string;
+let scriptPath: string;
+const orchestrators: HostProcessOrchestrator[] = [];
+
+beforeEach(() => {
+  tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-push-'));
+  scriptPath = join(tmpRoot, 'fake-cli.mjs');
+  writeFileSync(scriptPath, FAKE_CLI, 'utf8');
+});
+
+afterEach(async () => {
+  for (const orch of orchestrators) {
+    try { await orch.stopAuthorityNode(); } catch { /* ignore */ }
+  }
+  orchestrators.length = 0;
+  await sleep(50);
+  try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
+});
+
+function makeOrchestrator(rootDir: string, pushResolver?: () => Promise<PushCredentials | undefined>): HostProcessOrchestrator {
+  mkdirSync(rootDir, { recursive: true });
+  const orch = new HostProcessOrchestrator({
+    rootDir,
+    portRange: { start: 18000, end: 18499 },
+    stopTimeoutMs: 1500,
+    spawn: { entrypoint: scriptPath },
+    ...(pushResolver ? { pushResolver } : {}),
+  });
+  orchestrators.push(orch);
+  return orch;
+}
+
+function readChildConfig(rootDir: string, containerId = AUTHORITY_CONTAINER_ID): Record<string, unknown> {
+  const raw = readFileSync(join(rootDir, containerId, 'cadre.json'), 'utf8');
+  return JSON.parse(raw) as Record<string, unknown>;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((res) => setTimeout(res, ms));
+}
+
+describe('HostProcessOrchestrator push injection', () => {
+  it('writes config.push into cadre.json when the resolver yields credentials', async () => {
+    const rootDir = join(tmpRoot, 'a');
+    const orch = makeOrchestrator(rootDir, async () => ({ fcm: FCM, apns: APNS, cooldownMs: 1000 }));
+    await orch.init();
+    await orch.ensureAuthorityNode(CFG);
+
+    const cfg = readChildConfig(rootDir);
+    expect(cfg.push).toEqual({ fcm: FCM, apns: APNS, cooldownMs: 1000 });
+  });
+
+  it('omits config.push when no resolver is configured', async () => {
+    const rootDir = join(tmpRoot, 'b');
+    const orch = makeOrchestrator(rootDir);
+    await orch.init();
+    await orch.ensureAuthorityNode(CFG);
+
+    const cfg = readChildConfig(rootDir);
+    expect(cfg.push).toBeUndefined();
+  });
+
+  it('omits config.push when the resolver returns undefined (push opt-in)', async () => {
+    const rootDir = join(tmpRoot, 'c');
+    const orch = makeOrchestrator(rootDir, async () => undefined);
+    await orch.init();
+    await orch.ensureAuthorityNode(CFG);
+
+    expect(readChildConfig(rootDir).push).toBeUndefined();
+  });
+
+  it('degrades to no push (does not fail the spawn) when the resolver throws', async () => {
+    const rootDir = join(tmpRoot, 'd');
+    const orch = makeOrchestrator(rootDir, async () => { throw new Error('partial creds'); });
+    await orch.init();
+    // Spawn still succeeds.
+    const node = await orch.ensureAuthorityNode(CFG);
+    expect(node.id).toBe(AUTHORITY_CONTAINER_ID);
+    expect(readChildConfig(rootDir).push).toBeUndefined();
+  });
+
+  it('re-resolves on re-spawn and never persists a raw private key in state.json', async () => {
+    const rootDir = join(tmpRoot, 'e');
+    let current: PushCredentials | undefined = { fcm: FCM };
+    const orch = makeOrchestrator(rootDir, async () => current);
+    await orch.init();
+    await orch.ensureAuthorityNode(CFG);
+    expect(readChildConfig(rootDir).push).toEqual({ fcm: FCM });
+
+    // state.json must not carry the raw key — only re-resolvable references.
+    const stateRaw = readFileSync(join(rootDir, 'state.json'), 'utf8');
+    expect(stateRaw).not.toContain('FCM-SECRET-PEM');
+
+    // Rotate the resolver's answer, then restart — the new spawn must pick it up.
+    current = { apns: APNS };
+    await orch.restartAuthorityNode();
+    const cfg2 = readChildConfig(rootDir);
+    expect(cfg2.push).toEqual({ apns: APNS });
+    expect((cfg2.push as PushCredentials).fcm).toBeUndefined();
+  });
+
+  it('injects push for a storage-profile managed node but not a transaction node', async () => {
+    const rootDir = join(tmpRoot, 'f');
+    const orch = makeOrchestrator(rootDir, async () => ({ fcm: FCM }));
+    await orch.init();
+
+    await orch.createContainer({ containerId: 'storage-1', partyId: 'p', bootstrapNodes: [], profile: 'storage' });
+    expect(readChildConfig(rootDir, 'storage-1').push).toEqual({ fcm: FCM });
+
+    await orch.createContainer({ containerId: 'txn-1', partyId: 'p', bootstrapNodes: [], profile: 'transaction' });
+    expect(readChildConfig(rootDir, 'txn-1').push).toBeUndefined();
+  });
+});

package/src/auth/__tests__/trust-circle-integration.test.ts

@@ -2,10 +2,9 @@ import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 import { mkdtempSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { generatePrivateKey, getPublicKey } from '@optimystic/quereus-plugin-crypto';
 import { generateKeyPair } from '@libp2p/crypto/keys';
 import { peerIdFromPrivateKey } from '@libp2p/peer-id';
-import { CadreNode } from '@serfab/cadre-core';
+import { CadreNode, authorityKeyFromLibp2p } from '@serfab/cadre-core';
 
 import { TrustCircleService } from '../trust-circle.js';
 import { TrustCircleStore } from '../trust-circle-store.js';
@@ -36,18 +35,19 @@ describe('TrustCircleService — real CadreNode integration', () => {
   beforeEach(async () => {
     tmpRoot = mkdtempSync(join(tmpdir(), 'cadre-host-tc-int-'));
 
-    hostAuthorityPrivateKey = generatePrivateKey('ed25519', 'base64url') as string;
-    hostAuthorityPublicKey = getPublicKey(
-      hostAuthorityPrivateKey,
-      'ed25519',
-      'base64url',
-      'base64url'
-    ) as string;
+    // Own-authority host: the node's libp2p identity key IS its authority key
+    // (the cadre-cli `--authority` shape), so registerSelf can authority-sign the
+    // INSERT of its own CadrePeer row.
+    const hostKey = await generateKeyPair('Ed25519');
+    const authority = authorityKeyFromLibp2p(hostKey);
+    hostAuthorityPrivateKey = authority.privateKeyB64;
+    hostAuthorityPublicKey = authority.publicKeyB64;
 
     const baseId = Math.random().toString(36).slice(2);
 
     host = new CadreNode({
       controlNetwork: { partyId: `host-${baseId}`, bootstrapNodes: [] },
+      privateKey: hostKey,
       profile: 'transaction'
     });
 
@@ -59,6 +59,11 @@ describe('TrustCircleService — real CadreNode integration', () => {
 
     host.initializeSeedBootstrap(hostAuthorityPrivateKey);
 
+    // The authority writes its own CadrePeer row up-front (the implement ticket's
+    // CLI change). After this the host's own peerId is a member, so it shows up
+    // alongside any redeemed peers in the trust-circle listing.
+    await host.registerSelf();
+
     store = new TrustCircleStore(tmpRoot);
     service = new TrustCircleService({ cadreNode: host, store });
   }, 60_000);
@@ -68,7 +73,7 @@ describe('TrustCircleService — real CadreNode integration', () => {
     try { rmSync(tmpRoot, { recursive: true, force: true }); } catch { /* ignore */ }
   });
 
-  it('completes the full issue → redeem → list → remove cycle', async () => {
+  it('issues → redeems → lists against the real control DB (listMembers path)', async () => {
     // Derive a shape-valid peerId from a fresh Ed25519 key — same pattern as
     // packages/cadre-core/test/seed-bootstrap.spec.ts. The AuthorizedInsert
     // constraint only checks the signature over digest(PeerId,…); peerId
@@ -92,25 +97,39 @@ describe('TrustCircleService — real CadreNode integration', () => {
     // Verify directly against the control DB: the row is there.
     expect(await isInCadrePeer(host, phonePeerId)).toBe(true);
 
-    // List — should see the peer once, labelled.
+    // List — exercises the CadreNode.listMembers() path. CadrePeer now carries
+    // the host's own self-registered row in addition to the redeemed phone.
     const snap = await service.list();
-    expect(snap.members).toHaveLength(1);
-    expect(snap.members[0]!.peerId).toBe(phonePeerId);
-    expect(snap.members[0]!.label).toBe("Mom's phone");
+    expect(snap.members).toHaveLength(2);
+    const phoneMember = snap.members.find((m) => m.peerId === phonePeerId);
+    expect(phoneMember).toBeDefined();
+    expect(phoneMember!.label).toBe("Mom's phone");
+    // The host's own peerId is present too (unlabeled → bare peerId as label).
+    expect(snap.members.some((m) => m.peerId === host.peerId!.toString())).toBe(true);
     expect(snap.pending).toHaveLength(0);
+  }, 90_000);
+
+  // The signed `CadrePeer` DELETE previously threw a Quereus deferred-constraint
+  // error ("No row context found for column PeerId") inside cadre-core's
+  // removePeer. That upstream bug is fixed (`quereus-cadrepeer-delete-no-row-context`,
+  // landed), so the full issue → redeem → remove cycle is now exercised here.
+  it('removes a member from CadrePeer', async () => {
+    const phoneKey = await generateKeyPair('Ed25519');
+    const phonePeerId = peerIdFromPrivateKey(phoneKey).toString();
+
+    const issued = await service.issueInvite({ label: "Mom's phone" });
+    await service.redeemInvite({ token: issued.token, peerId: phonePeerId });
+    expect(await isInCadrePeer(host, phonePeerId)).toBe(true);
 
-    // Remove
     await service.removeMember(phonePeerId);
 
-    // CadrePeer row is gone (validates DELETE-with-context end-to-end).
     expect(await isInCadrePeer(host, phonePeerId)).toBe(false);
-
-    // Local label is gone.
     expect(store.getMember(phonePeerId)).toBeUndefined();
-
-    // list() reflects the removal.
     const afterRemove = await service.list();
-    expect(afterRemove.members).toHaveLength(0);
+    // The phone is gone; the host's own self-registered row remains.
+    expect(afterRemove.members.map((m) => m.peerId)).not.toContain(phonePeerId);
+    expect(afterRemove.members).toHaveLength(1);
+    expect(afterRemove.members[0]!.peerId).toBe(host.peerId!.toString());
   }, 90_000);
 });
 

package/src/auth/__tests__/trust-circle.test.ts

@@ -9,11 +9,12 @@ import { TrustCircleService, createTrustCircleHandlers } from '../trust-circle.j
 import { TrustCircleStore } from '../trust-circle-store.js';
 import { TrustCircleError } from '../types.js';
 import type { CadreNodeLike } from '../trust-circle.js';
+import { AuthorityNodeUnavailableError } from '../../authority/authority-node-client.js';
 
 /**
- * Minimal in-memory mock of CadreNode + ControlDatabase. Records calls so
- * assertions can verify the auth + redemption flow without standing up a
- * real libp2p control network.
+ * Minimal in-memory mock of the authority-node channel adapter. Records calls
+ * so assertions can verify the auth + redemption flow without standing up a
+ * real libp2p control network or admin channel.
  */
 class MockCadreNode implements CadreNodeLike {
   readonly authorizedPeers = new Set<string>();
@@ -23,8 +24,8 @@ class MockCadreNode implements CadreNodeLike {
 
   /** Toggle to make acceptPhone reject. */
   acceptShouldThrow: Error | null = null;
-  /** Toggle to make getControlDatabase return null (simulate offline). */
-  dbAvailable = true;
+  /** When false, membership calls throw AuthorityNodeUnavailableError. */
+  nodeAvailable = true;
 
   async createInvite(token?: string, expiresIn?: number) {
     this.issuedInvites.push({ token, expiresIn });
@@ -53,21 +54,14 @@ class MockCadreNode implements CadreNodeLike {
     return 'enc:' + JSON.stringify(invite);
   }
 
-  getControlDatabase() {
-    if (!this.dbAvailable) return null;
-    const peers = this.authorizedPeers;
-    return {
-      getDatabase: () => ({
-        async *eval(_sql: string, params?: unknown[]) {
-          if (params && params.length > 0) {
-            const target = params[0] as string;
-            if (peers.has(target)) yield { PeerId: target };
-            return;
-          }
-          for (const p of peers) yield { PeerId: p };
-        },
-      }),
-    } as unknown as ReturnType<CadreNodeLike['getControlDatabase']>;
+  async listMembers(): Promise<Array<{ peerId: string; multiaddr: string | null }>> {
+    if (!this.nodeAvailable) throw new AuthorityNodeUnavailableError('node down');
+    return [...this.authorizedPeers].map((peerId) => ({ peerId, multiaddr: null }));
+  }
+
+  async isMember(peerId: string): Promise<boolean> {
+    if (!this.nodeAvailable) throw new AuthorityNodeUnavailableError('node down');
+    return this.authorizedPeers.has(peerId);
   }
 }
 
@@ -204,6 +198,71 @@ describe('TrustCircleService.redeemInvite', () => {
     expect(cadreNode.authorizedPeers.has('pA')).toBe(true);
     expect(cadreNode.authorizedPeers.has('pB')).toBe(false);
   });
+
+  it('preserves the pending token when acceptPhone fails with node_unavailable', async () => {
+    const { token } = await service.issueInvite({ label: 'Transient' });
+    cadreNode.acceptShouldThrow = new AuthorityNodeUnavailableError('node down');
+
+    await expect(service.redeemInvite({ token, peerId: 'pTrans' }))
+      .rejects.toMatchObject({ code: 'node_unavailable' });
+
+    // Token must still be redeemable.
+    expect(store.getPending(token)).toBeDefined();
+    expect(cadreNode.authorizedPeers.has('pTrans')).toBe(false);
+
+    // Retry after the node recovers.
+    cadreNode.acceptShouldThrow = null;
+    await expect(service.redeemInvite({ token, peerId: 'pTrans' }))
+      .resolves.toMatchObject({ peerId: 'pTrans', label: 'Transient' });
+    expect(cadreNode.authorizedPeers.has('pTrans')).toBe(true);
+    expect(store.getPending(token)).toBeUndefined();
+  });
+
+  it('concurrent redeem during a gated node_unavailable leaves the token re-redeemable', async () => {
+    const { token } = await service.issueInvite({ label: 'GatedFail' });
+
+    // Gate acceptPhone — reject on release with a transient error so the
+    // first redeem hits node_unavailable. The second redeem should still
+    // bounce synchronously while the gate is held.
+    let release!: () => void;
+    const gate = new Promise<void>((_, reject) => { release = () => reject(new AuthorityNodeUnavailableError('node down')); });
+    cadreNode.acceptPhone = async () => {
+      await gate;
+    };
+
+    const first = service.redeemInvite({ token, peerId: 'pA' });
+    const second = service.redeemInvite({ token, peerId: 'pB' });
+
+    await expect(second).rejects.toMatchObject({ code: 'already_redeemed' });
+
+    release();
+    await expect(first).rejects.toMatchObject({ code: 'node_unavailable' });
+
+    // Pending row preserved; in-flight Set cleared via finally.
+    expect(store.getPending(token)).toBeDefined();
+    expect(cadreNode.authorizedPeers.has('pA')).toBe(false);
+    expect(cadreNode.authorizedPeers.has('pB')).toBe(false);
+
+    // Third redeem (after in-flight slot freed) succeeds against a healthy node.
+    cadreNode.acceptPhone = async (options) => {
+      cadreNode.authorizedPeers.add(options.phonePeerId);
+    };
+    await expect(service.redeemInvite({ token, peerId: 'pC' }))
+      .resolves.toMatchObject({ peerId: 'pC', label: 'GatedFail' });
+    expect(store.getPending(token)).toBeUndefined();
+    expect(cadreNode.authorizedPeers.has('pC')).toBe(true);
+  });
+
+  it('preserves the pending token on non-transient acceptPhone failures (admin must revoke)', async () => {
+    const { token } = await service.issueInvite({ label: 'OtherFail' });
+    cadreNode.acceptShouldThrow = new Error('cadre-core rejected the peer');
+
+    await expect(service.redeemInvite({ token, peerId: 'pX' }))
+      .rejects.toThrow('cadre-core rejected the peer');
+
+    expect(store.getPending(token)).toBeDefined();
+    expect(cadreNode.authorizedPeers.has('pX')).toBe(false);
+  });
 });
 
 describe('TrustCircleService.issueInvite — label length', () => {
@@ -290,16 +349,24 @@ describe('TrustCircleService.list', () => {
     expect(store.getMember('orphan')).toBeUndefined();
   });
 
-  it('falls back to local labels when control DB is unavailable', async () => {
+  it('falls back to local labels when the authority node is unavailable', async () => {
     store.addMember({ peerId: 'pZ', label: 'Zoe', addedAt: 't' });
-    cadreNode.dbAvailable = false;
+    cadreNode.nodeAvailable = false;
 
     const snap = await service.list();
     expect(snap.members.some(m => m.peerId === 'pZ' && m.label === 'Zoe')).toBe(true);
-    // Orphan check is skipped when DB is unavailable.
+    // Orphan check is skipped when the node is unavailable.
     expect(store.getMember('pZ')).toBeDefined();
   });
 
+  it('issueInvite surfaces node_unavailable when the channel is down', async () => {
+    const downNode = new MockCadreNode();
+    downNode.createInvite = async () => { throw new AuthorityNodeUnavailableError('refused'); };
+    const svc = new TrustCircleService({ cadreNode: downNode, store });
+    await expect(svc.issueInvite({ label: 'Nina' }))
+      .rejects.toMatchObject({ code: 'node_unavailable' });
+  });
+
   it('shows unlabelled CadrePeer rows with peerId as label', async () => {
     cadreNode.authorizedPeers.add('unlabeled-peer');
     const snap = await service.list();