@serfab/cadre-host 0.8.1 → 0.10.0

package/src/server/routes/grants.ts

@@ -0,0 +1,210 @@
+/**
+ * Grantee-facing donation routes — the HTTP surface an external cadre authority
+ * (a friend's phone) drives to have this host donate a node into *its* cadre.
+ *
+ * Mount path: `/grants`. Distinct from the loopback-only `/grants-admin` surface
+ * (issue/list/revoke, no bearer): this one is **bearer-gated** — every request
+ * carries `Authorization: Bearer <grant-token>`, and a grantee sees only the
+ * donations its own grant authorized (the single cross-grantee boundary,
+ * analogous to cadre-provider's per-customer ownership check).
+ *
+ * Reachability is out of scope here: in v1 this mounts on the loopback
+ * management server, same as the trust-circle / NAT surfaces. Physically exposing
+ * it to a remote phone is `backlog/feat-cadre-host-wan-grant-reachability`.
+ *
+ * Errors: handlers either send a `{ ok:false, error:{code,message} }` envelope
+ * inline (auth / body validation) or let the `DonationService` throw a
+ * `DonationError`, which `server/error-handler.ts` maps to the matching HTTP
+ * status and the same envelope.
+ */
+
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify';
+
+import type { DonationService, DonationProvisionRequest } from '../../donation/donation-service.js';
+import type { DonationView, GrantValidator } from '../../donation/types.js';
+
+export interface GrantsRoutesOptions {
+  donations: DonationService;
+  /** Validates the presented bearer for non-provisioning ops (provision revalidates internally). */
+  grants: GrantValidator;
+}
+
+/** Uniform error envelope (matches `error-handler.ts` and the provider API). */
+function errorResponse(reply: FastifyReply, code: string, message: string, status: number) {
+  return reply.status(status).send({ ok: false, error: { code, message } });
+}
+
+/** Pull the `Bearer <token>` value out of the Authorization header, or undefined. */
+function parseBearer(header: string | undefined): string | undefined {
+  if (!header) return undefined;
+  const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+  return match ? match[1].trim() : undefined;
+}
+
+/** Map a grant denial reason to an HTTP status for the bearer gate. */
+function denyStatus(reason: string | undefined): number {
+  if (reason === 'expired' || reason === 'revoked') return 403;
+  return 401; // unknown_token / missing
+}
+
+/**
+ * Authenticate the grant bearer for a non-provisioning op (identity + not
+ * expired/revoked; no quota). Returns the token, or null after sending the
+ * failure response. Provision does its own quota-aware validation inside
+ * `DonationService.provision`.
+ */
+function authenticate(
+  request: FastifyRequest,
+  reply: FastifyReply,
+  grants: GrantValidator,
+): string | null {
+  const token = parseBearer(request.headers.authorization);
+  if (!token) {
+    errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
+    return null;
+  }
+  const validation = grants.validate(token);
+  if (!validation.ok) {
+    const status = denyStatus(validation.reason);
+    // Keep the envelope code aligned with the status (and with the POST path,
+    // which surfaces an unknown token as `unauthorized`): 401 → unauthorized,
+    // 403 → forbidden. A 401 labelled `forbidden` is self-contradictory.
+    const code = status === 403 ? 'forbidden' : 'unauthorized';
+    errorResponse(reply, code, `Grant is ${validation.reason ?? 'invalid'}`, status);
+    return null;
+  }
+  return token;
+}
+
+/**
+ * Resolve a donation the presented grant owns. Returns the redacted view, or
+ * null after sending a 404 — an unknown id and one owned by a *different* grant
+ * are deliberately indistinguishable (a grantee never learns another grantee's
+ * donations exist).
+ */
+function requireOwned(
+  donations: DonationService,
+  id: string,
+  token: string,
+  reply: FastifyReply,
+): DonationView | null {
+  const donation = donations.get(id);
+  if (!donation || donation.grantToken !== token) {
+    errorResponse(reply, 'not_found', `No such donation: ${id}`, 404);
+    return null;
+  }
+  return donation;
+}
+
+export function registerGrantsRoutes(app: FastifyInstance, opts: GrantsRoutesOptions): void {
+  const { donations, grants } = opts;
+
+  // POST /grants — provision a donated node. The bearer's identity/expiry/
+  // revocation AND quota are validated inside provision(), which throws a
+  // DonationError (unauthorized / forbidden / quota_exceeded) the error handler
+  // maps. We only parse the bearer and validate the request body here.
+  app.post('/grants', async (request, reply) => {
+    const token = parseBearer(request.headers.authorization);
+    if (!token) {
+      return errorResponse(reply, 'unauthorized', 'Missing bearer grant token', 401);
+    }
+
+    const body = (request.body ?? {}) as Partial<DonationProvisionRequest>;
+    if (typeof body.partyId !== 'string' || body.partyId.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'partyId is required', 400);
+    }
+    if (!Array.isArray(body.bootstrapNodes) || body.bootstrapNodes.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'bootstrapNodes is required', 400);
+    }
+    if (!Array.isArray(body.ownerKeys) || body.ownerKeys.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'ownerKeys is required', 400);
+    }
+    // Element types too, not just the array: `provision`'s shape check trims each
+    // entry, so a non-string reaches the caller as an internal `.trim is not a
+    // function` rather than as a message naming what is wrong with the request.
+    if (!body.ownerKeys.every(key => typeof key === 'string')) {
+      return errorResponse(reply, 'invalid_request', 'ownerKeys must be an array of strings', 400);
+    }
+    if (body.profile !== undefined && body.profile !== 'storage' && body.profile !== 'transaction') {
+      return errorResponse(reply, 'invalid_request', 'profile must be "storage" or "transaction"', 400);
+    }
+
+    const donation = await donations.provision({
+      grantToken: token,
+      partyId: body.partyId,
+      bootstrapNodes: body.bootstrapNodes,
+      ownerKeys: body.ownerKeys,
+      ...(body.profile ? { profile: body.profile } : {}),
+    });
+    return reply.status(201).send({ ok: true, data: { donation } });
+  });
+
+  // GET /grants — list only the donations this grant authorized.
+  app.get('/grants', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    return reply.send({ ok: true, data: { donations: donations.list(token) } });
+  });
+
+  // GET /grants/:id — one donation (redacted), owned by this grant.
+  app.get<{ Params: { id: string } }>('/grants/:id', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    const donation = requireOwned(donations, request.params.id, token, reply);
+    if (!donation) return reply;
+    return reply.send({ ok: true, data: { donation } });
+  });
+
+  // GET /grants/:id/peer — live { peerId, multiaddrs } for the requester's addDrone.
+  app.get<{ Params: { id: string } }>('/grants/:id/peer', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+    const peer = await donations.getPeer(request.params.id);
+    return reply.send({ ok: true, data: peer });
+  });
+
+  // PUT /grants/:id/seed — apply the requester's phone-signed seed.
+  app.put<{ Params: { id: string } }>('/grants/:id/seed', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+
+    const body = (request.body ?? {}) as { seed?: unknown };
+    if (typeof body.seed !== 'string' || body.seed.length === 0) {
+      return errorResponse(reply, 'invalid_request', 'seed is required', 400);
+    }
+    const result = await donations.applySeed(request.params.id, body.seed);
+    // NOTE: exhaustive over today's three outcomes, and nothing forces it to stay
+    // that way — an unhandled fourth would fall out of the handler as `undefined`
+    // and hang the request rather than fail to compile. If `DonationSeedResult`
+    // ever grows a variant, add a `default:` that 500s here.
+    switch (result.outcome) {
+      case 'rejected':
+        return errorResponse(reply, 'seed_failed', result.error ?? 'Node rejected the seed', 502);
+      // The loan ended while the seed was in flight. The ending won, so the
+      // caller is told the record it seeded is no longer seedable (409) — or is
+      // gone entirely (404) — rather than a 200 that implies a live node.
+      case 'abandoned':
+        return result.status
+          ? errorResponse(
+              reply,
+              'invalid_state',
+              `Donation ${request.params.id} ended (${result.status}) while the seed was in flight`,
+              409,
+            )
+          : errorResponse(reply, 'not_found', `No such donation: ${request.params.id}`, 404);
+      case 'seeded':
+        return reply.send({ ok: true, data: { peersAdded: result.peersAdded } });
+    }
+  });
+
+  // DELETE /grants/:id — terminate the donated node.
+  app.delete<{ Params: { id: string } }>('/grants/:id', async (request, reply) => {
+    const token = authenticate(request, reply, grants);
+    if (!token) return reply;
+    if (!requireOwned(donations, request.params.id, token, reply)) return reply;
+    await donations.terminate(request.params.id);
+    return reply.send({ ok: true });
+  });
+}

package/src/server/routes/nodes.ts

@@ -6,10 +6,11 @@
  * `onStateChange` (forwarded by `createLocalUiServer.start`) — the route
  * handlers don't re-publish.
  *
- * start/restart are real for the admin's authority node (re-spawned from the
- * persisted `AuthoritySpawnConfig`). Generic per-member node spawn from saved
- * config is out of scope and returns `not_implemented`. Stop works for any
- * running node.
+ * start/restart are real for the admin's owner node (re-spawned from the
+ * persisted `OwnerSpawnConfig`). Generic node lifecycle is owned by the
+ * grantee-facing donation surface (`/grants`) — this route no longer spawns
+ * generic nodes; start/restart of a known non-owner node points the caller
+ * there. Stop works for any running node.
  */
 
 import { existsSync, openSync, readSync, closeSync, statSync } from 'node:fs';
@@ -83,17 +84,17 @@ export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptio
     return { ok: true };
   });
 
-  // start / restart: real for the admin's authority node (spawned from the
-  // persisted AuthoritySpawnConfig). Generic per-member node spawn from saved
-  // config is out of scope — those ids return a clear not_implemented; unknown
-  // ids 404.
+  // start / restart: real for the admin's owner node (spawned from the
+  // persisted OwnerSpawnConfig). Generic node lifecycle now belongs to the
+  // donation surface (/grants) — those ids return a clear not_implemented that
+  // points there; unknown ids 404.
   app.post<{ Params: { id: string } }>('/api/nodes/:id/start', async (request, reply) => {
     const { id } = request.params;
-    if (orchestrator.isAuthorityNode(id)) {
-      if (!orchestrator.hasAuthorityConfig()) {
-        return notImplemented(reply, `start ${id}: authority node has no saved spawn config.`);
+    if (orchestrator.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `start ${id}: owner node has no saved spawn config.`);
       }
-      const node = await orchestrator.ensureAuthorityNode();
+      const node = await orchestrator.ensureOwnerNode();
       return { ok: true, data: { node } };
     }
     return startRestartFallback(reply, orchestrator, id, 'start');
@@ -101,18 +102,18 @@ export function registerNodesRoutes(app: FastifyInstance, opts: NodesRoutesOptio
 
   app.post<{ Params: { id: string } }>('/api/nodes/:id/restart', async (request, reply) => {
     const { id } = request.params;
-    if (orchestrator.isAuthorityNode(id)) {
-      if (!orchestrator.hasAuthorityConfig()) {
-        return notImplemented(reply, `restart ${id}: authority node has no saved spawn config.`);
+    if (orchestrator.isOwnerNode(id)) {
+      if (!orchestrator.hasOwnerConfig()) {
+        return notImplemented(reply, `restart ${id}: owner node has no saved spawn config.`);
       }
-      const node = await orchestrator.restartAuthorityNode();
+      const node = await orchestrator.restartOwnerNode();
       return { ok: true, data: { node } };
     }
     return startRestartFallback(reply, orchestrator, id, 'restart');
   });
 }
 
-/** 404 for unknown ids; 501 not_implemented for known non-authority nodes. */
+/** 404 for unknown ids; 501 not_implemented for known non-owner nodes. */
 function startRestartFallback(
   reply: import('fastify').FastifyReply,
   orchestrator: HostProcessOrchestrator,
@@ -127,7 +128,7 @@ function startRestartFallback(
   }
   return notImplemented(
     reply,
-    `${verb} ${id}: only the authority node is start/restart-able; generic node spawn is out of scope.`,
+    `${verb} ${id}: only the owner node is start/restart-able here; generic donated-node lifecycle is owned by the donation surface — use POST /grants to provision and DELETE /grants/:id to terminate.`,
   );
 }
 

package/src/server/routes/settings.ts

@@ -21,14 +21,19 @@ import type { NatService } from '../../nat/index.js';
 import type { UpdateService } from '../../update/index.js';
 import type { HostSettingsStore } from '../settings-store.js';
 
-const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version']);
+const FORBIDDEN_KEYS = new Set<string>(['uiPort', 'libp2pPort', 'dataDir', 'identityPath', 'installId', 'installedAt', 'installerVersion', 'version', 'ownCadre']);
 
 const WRITABLE_TOP_KEYS = new Set<string>(['upnpEnabled', 'updates']);
 const WRITABLE_UPDATES_KEYS = new Set<string>(['autoApply', 'manifestUrl']);
 
 export interface SettingsRoutesOptions {
   settingsStore: HostSettingsStore;
-  nat: NatService;
+  /**
+   * Present only when the host runs its own personal cadre. In donor-only mode
+   * an `upnpEnabled` write still persists to host.config.json but has no running
+   * NatService to propagate into.
+   */
+  nat?: NatService;
   update?: UpdateService;
 }
 
@@ -58,7 +63,10 @@ export function registerSettingsRoutes(app: FastifyInstance, opts: SettingsRoute
       // takes effect immediately. NatService persists into nat.json — that's
       // independent of host.config.json's `upnpEnabled` (which the installer
       // uses on first run to seed nat.json). Update both for consistency.
-      await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      // In donor-only mode there is no NatService — the write still persists.
+      if (nat) {
+        await nat.putSettings({ upnpEnabled: body.upnpEnabled as boolean });
+      }
     }
     if ('updates' in body) {
       const updates = body.updates as { autoApply?: boolean; manifestUrl?: string };

package/src/server/routes/status.ts

@@ -22,8 +22,10 @@ const PROCESS_STARTED_AT = process.hrtime.bigint();
 
 export interface StatusRouteOptions {
   orchestrator: HostProcessOrchestrator;
-  trustCircle: TrustCircleService;
-  nat: NatService;
+  /** Present only when the host runs its own personal cadre (`ownCadre.enabled`). */
+  trustCircle?: TrustCircleService;
+  /** Present only when the host runs its own personal cadre (`ownCadre.enabled`). */
+  nat?: NatService;
   update?: UpdateService;
 }
 
@@ -35,8 +37,10 @@ export interface StatusResponse {
     status: ManagedNodeInfo['status'];
     profile: ManagedNodeInfo['profile'];
   }>;
-  trustCircle: { members: number; pending: number };
-  connectivity: NatStatusSnapshot;
+  /** Omitted in donor-only mode (no host-own trust circle). */
+  trustCircle?: { members: number; pending: number };
+  /** Omitted in donor-only mode (no NAT service). */
+  connectivity?: NatStatusSnapshot;
   update?: { available?: string; lastChecked?: string };
 }
 
@@ -50,8 +54,6 @@ export function registerStatusRoute(app: FastifyInstance, opts: StatusRouteOptio
       status: n.status,
       profile: n.profile,
     }));
-    const tc = await opts.trustCircle.list();
-    const connectivity = opts.nat.getStatus();
 
     const response: StatusResponse = {
       service: {
@@ -60,10 +62,18 @@ export function registerStatusRoute(app: FastifyInstance, opts: StatusRouteOptio
         uptimeSeconds: secondsSince(PROCESS_STARTED_AT),
       },
       nodes,
-      trustCircle: { members: tc.members.length, pending: tc.pending.length },
-      connectivity,
     };
 
+    // Trust-circle + connectivity exist only when the host runs its own
+    // personal cadre; donor-only mode omits both.
+    if (opts.trustCircle) {
+      const tc = await opts.trustCircle.list();
+      response.trustCircle = { members: tc.members.length, pending: tc.pending.length };
+    }
+    if (opts.nat) {
+      response.connectivity = opts.nat.getStatus();
+    }
+
     if (opts.update) {
       const state = await opts.update.getState();
       const update: { available?: string; lastChecked?: string } = {};

package/src/server/routes/strands.ts

@@ -0,0 +1,54 @@
+/**
+ * Strand HTTP routes — thin adapters around `StrandHandlers`
+ * (`createStrandHandlers(service)`).
+ *
+ * Mount path: `/api/strands` — a UI-only surface with no CLI contract to
+ * preserve. (The `/auth/*` and `/nat/*` mounts sit outside `/api` only because
+ * the existing CLI already targets those URLs.) Envelope form therefore follows
+ * the other `/api/*` routes: `{ ok: true, data }`.
+ *
+ * A removal that actually issued a delete publishes `strands-changed` so other
+ * open tabs refresh. A call that found no row publishes nothing — nothing changed.
+ */
+
+import type { FastifyInstance } from 'fastify';
+
+import type { StrandHandlers } from '../../strands/types.js';
+import type { EventBus } from '../events/bus.js';
+
+export interface StrandRoutesOptions {
+  handlers: StrandHandlers;
+  events: EventBus;
+}
+
+/**
+ * The only accepted `confirm` values — the same strict pair the admin channel
+ * accepts. Not a general truthiness parser: `yes`, `on` and an empty value all
+ * count as NOT confirmed, because a guessy parser here would turn a typo into a
+ * destroyed membership key.
+ *
+ * NOTE: deliberately duplicated from cadre-cli's `admin-server.ts` rather than
+ * imported — cadre-host depends on cadre-cli for its bin path only, never its
+ * source. Keep the two in step by hand; do not DRY them into an import.
+ */
+const CONFIRM_VALUES = new Set(['1', 'true']);
+
+export function registerStrandRoutes(app: FastifyInstance, opts: StrandRoutesOptions): void {
+  const { handlers, events } = opts;
+
+  app.get('/api/strands', async () => {
+    return { ok: true, data: await handlers.listStrands() };
+  });
+
+  app.delete<{ Params: { id: string }; Querystring: { confirm?: string } }>(
+    '/api/strands/:id',
+    async (request) => {
+      const confirm = typeof request.query.confirm === 'string' && CONFIRM_VALUES.has(request.query.confirm);
+      const result = await handlers.removeStrand(request.params.id, { confirm });
+      if (result.removed) {
+        events.publish({ type: 'strands-changed', kind: 'removed' });
+      }
+      return { ok: true, data: result };
+    },
+  );
+}

package/src/strands/__tests__/strand-service.test.ts

@@ -0,0 +1,165 @@
+/**
+ * StrandService unit tests — a fake node, no HTTP.
+ *
+ * The two things this layer actually owns: id validation (which must never reach
+ * the node) and the translation of the admin channel's single
+ * `OwnerNodeUnavailableError` into a vocabulary the HTTP layer can map. The
+ * confirmation *policy* is the node's and is not re-tested here — only that the
+ * flag is forwarded verbatim.
+ */
+
+import { describe, it, expect, beforeEach } from 'vitest';
+
+import { OwnerNodeUnavailableError } from '../../owner/owner-node-client.js';
+import { StrandService } from '../strand-service.js';
+import { StrandError } from '../types.js';
+import type { CadreNodeLike } from '../strand-service.js';
+import type { StrandListSnapshot, StrandRemovalResult } from '../types.js';
+
+interface FakeNode extends CadreNodeLike {
+  calls: Array<{ strandId: string; confirm: boolean }>;
+  listCalls: number;
+  /** Thrown by both methods when set. */
+  failWith?: unknown;
+}
+
+const SNAPSHOT: StrandListSnapshot = {
+  strands: [
+    { id: 'open-one', type: 'o', running: true, status: 'active' },
+    { id: 'closed-one', type: 'c', running: false, status: null },
+  ],
+  controlConnections: 2,
+};
+
+function fakeNode(): FakeNode {
+  const node: FakeNode = {
+    calls: [],
+    listCalls: 0,
+    async listStrands() {
+      node.listCalls++;
+      if (node.failWith) throw node.failWith;
+      return SNAPSHOT;
+    },
+    async removeStrand(strandId, opts) {
+      node.calls.push({ strandId, confirm: opts.confirm });
+      if (node.failWith) throw node.failWith;
+      const result: StrandRemovalResult = {
+        strandId,
+        published: true,
+        type: 'o',
+        removed: true,
+        alone: false,
+      };
+      return result;
+    },
+  };
+  return node;
+}
+
+/** Await a call expected to reject, assert it is a StrandError, and hand it back. */
+async function catchStrandError(p: Promise<unknown>): Promise<StrandError> {
+  const err = await p.then(() => undefined, (e: unknown) => e);
+  expect(err).toBeInstanceOf(StrandError);
+  return err as StrandError;
+}
+
+let node: FakeNode;
+let service: StrandService;
+
+beforeEach(() => {
+  node = fakeNode();
+  service = new StrandService({ cadreNode: node });
+});
+
+describe('StrandService.list', () => {
+  it('passes the node snapshot through unchanged', async () => {
+    await expect(service.list()).resolves.toEqual(SNAPSHOT);
+    expect(node.listCalls).toBe(1);
+  });
+});
+
+describe('StrandService.remove — id validation', () => {
+  it.each([
+    ['blank', ''],
+    ['whitespace-only', '   '],
+    ['tab/newline only', '\t\n'],
+  ])('rejects a %s id with invalid_id and never calls the node', async (_label, id) => {
+    await expect(service.remove(id, { confirm: false })).rejects.toMatchObject({
+      name: 'StrandError',
+      code: 'invalid_id',
+    });
+    expect(node.calls).toEqual([]);
+  });
+
+  it('forwards an id containing "/" rather than refusing it', async () => {
+    // The whole chain carries it: Fastify decodes `%2F` into `params.id`,
+    // `OwnerNodeClient` re-encodes it, and the admin channel splits on the still
+    // -encoded segment and decodes it back. Refusing here would break the only
+    // form that works. `strands-route.test.ts` pins the Fastify half.
+    await service.remove('ns/strand', { confirm: true });
+    expect(node.calls).toEqual([{ strandId: 'ns/strand', confirm: true }]);
+  });
+
+  it('trims a padded id before forwarding it', async () => {
+    await service.remove('  spaced  ', { confirm: false });
+    expect(node.calls).toEqual([{ strandId: 'spaced', confirm: false }]);
+  });
+});
+
+describe('StrandService.remove — confirmation forwarding', () => {
+  it('forwards confirm: false as false', async () => {
+    await service.remove('open-one', { confirm: false });
+    expect(node.calls).toEqual([{ strandId: 'open-one', confirm: false }]);
+  });
+
+  it('forwards confirm: true as true', async () => {
+    await service.remove('closed-one', { confirm: true });
+    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: true }]);
+  });
+
+  it('does not retry a refused removal with confirmation added', async () => {
+    node.failWith = new OwnerNodeUnavailableError('needs confirmation', 'confirmation_required');
+    await expect(service.remove('closed-one', { confirm: false })).rejects.toBeInstanceOf(StrandError);
+    // Exactly one attempt, and it carried the caller's flag.
+    expect(node.calls).toEqual([{ strandId: 'closed-one', confirm: false }]);
+  });
+});
+
+describe('StrandService — error translation', () => {
+  const cases: Array<{ nodeCode: string | undefined; code: string; keepsMessage: boolean }> = [
+    { nodeCode: 'confirmation_required', code: 'confirmation_required', keepsMessage: true },
+    { nodeCode: 'bad_request', code: 'invalid_id', keepsMessage: true },
+    { nodeCode: 'not_ready', code: 'node_unavailable', keepsMessage: false },
+    { nodeCode: 'not_authorized', code: 'node_unavailable', keepsMessage: false },
+    { nodeCode: undefined, code: 'node_unavailable', keepsMessage: false },
+    { nodeCode: 'internal', code: 'internal', keepsMessage: true },
+    { nodeCode: 'something_new', code: 'internal', keepsMessage: true },
+  ];
+
+  for (const { nodeCode, code, keepsMessage } of cases) {
+    it(`maps nodeCode ${nodeCode ?? '(absent)'} → ${code}`, async () => {
+      const message = `node said ${nodeCode ?? 'nothing'}`;
+      node.failWith = new OwnerNodeUnavailableError(message, nodeCode);
+      const err = await catchStrandError(service.remove('x', { confirm: false }));
+      expect(err.code).toBe(code);
+      if (keepsMessage) {
+        expect(err.message).toBe(message);
+      } else {
+        // Wrapped, but the node's words survive inside.
+        expect(err.message).toContain(message);
+      }
+    });
+  }
+
+  it('translates a transport failure (no nodeCode) on list() too', async () => {
+    node.failWith = new OwnerNodeUnavailableError('Owner node unreachable: ECONNREFUSED');
+    const err = await catchStrandError(service.list());
+    expect(err.code).toBe('node_unavailable');
+  });
+
+  it('rethrows a non-owner-node error unchanged rather than dressing it as a strand error', async () => {
+    const boom = new TypeError('something else broke');
+    node.failWith = boom;
+    await expect(service.list()).rejects.toBe(boom);
+  });
+});

package/src/strands/index.ts

@@ -0,0 +1,14 @@
+/**
+ * Strand management for cadre-host. See ./strand-service.ts and ./types.ts.
+ */
+
+export { StrandService, createStrandHandlers } from './strand-service.js';
+export type { StrandServiceOptions, CadreNodeLike } from './strand-service.js';
+export { StrandError } from './types.js';
+export type {
+  StrandSummary,
+  StrandListSnapshot,
+  StrandRemovalResult,
+  StrandHandlers,
+  StrandErrorCode,
+} from './types.js';