talon-agent 5.14.0 → 5.18.2

package/src/core/mcp-hub/guest-scope.ts

@@ -1,44 +1,69 @@
 /**
- * Guest DM tool scope.
+ * Tool scope: who gets the full agent, and who gets the conversation-only
+ * ("guest") surface.
  *
- * Anyone the operator lets DM the bot gets the same agent the operator
- * gets: shell, files, mail, mesh devices, cron, memory, cross-chat sends.
- * With `guestDmScope.enabled`, a DM from anyone who is not an operator gets a
- * conversation-only surface instead, enforced here in the hub, so it holds
- * for every backend that reaches tools through the hub:
+ * The operator gets everything: shell, files, mail, mesh devices, cron,
+ * memory, agents, cross-chat sends. Anyone else who can reach the bot (a
+ * member of an allowed group, a DM the operator let in) gets a
+ * conversation-only surface, enforced here in the hub:
  *
  *   - Talon tools: an explicit allowlist (reply, react, edit/delete own
  *     messages, read this chat's history and media, look at stickers).
  *     Nothing that runs code, touches files, schedules, remembers, spawns
  *     agents, reaches devices or acts on another chat.
- *   - Parameters: a guest session may only target its own chat and may
+ *   - Parameters: a guest turn may only target its own chat and may
  *     never attach a local file by path (`send(file_path=…)` would
  *     otherwise read any file the daemon can read and hand it over).
  *   - Plugin servers: only those named in `guestPlugins` (default: web
  *     search and the time/weather/currency extras).
  *
- * Groups are untouched: they already require the operator's membership,
- * and their tool surface is a separate decision.
+ * The decision is made per TURN, from the SENDER — not per chat. A group
+ * holds the operator and other people at once, so "this chat is allowed"
+ * says nothing about who is asking. The weaver resolves the scope when a
+ * turn starts (`resolveTurnScope`) and brackets the turn with it
+ * (`enterTurnScope`); the hub reads it on every session and every call
+ * (`isGuestTurn`). A turn that batches messages from several people, or
+ * whose sender can't be identified, is a guest turn.
  *
  * Backend built-ins that live outside the hub (the Claude SDK's own
- * Bash/Read/Write, Codex's shell) are the backend's job. The Claude SDK
- * backend drops its built-ins for guest chats (see claude-sdk/options.ts).
+ * Bash/Read/Write, Codex's shell) are the backend's job. A backend that
+ * can't drop them declares so, and the weaver refuses guest turns on it
+ * (see `guestToolScope` in agent-runtime/backend-registry.ts).
  */
 
 export type GuestDmScopeConfig = {
+  /**
+   * Guest-scope DMs from non-operators (default true). `false` is a legacy
+   * opt-out that keeps the full surface in DMs the operator allowed;
+   * groups are always scoped per sender.
+   */
   enabled?: boolean;
-  /** Chat ids that keep the full surface in addition to the admin's DM. */
+  /** DM chat ids that keep the full surface (e.g. `wa_dm_<number>`). */
   operatorChats?: readonly string[];
-  /** Plugin/hub server names a guest DM may use. */
+  /** Plugin/hub server names a guest may use. */
   guestPlugins?: readonly string[];
+  /**
+   * Full surface for everyone in a group the operator is a member of
+   * (default false). Membership is attested by the frontend per turn
+   * (`TurnScopeInput.operatorInChat`).
+   */
+  operatorGroups?: boolean;
 };
 
+export type ToolScope = "operator" | "guest";
+
+/**
+ * Sender key for the local operator — terminal and native (bridge-token
+ * authenticated) clients, which only the operator can drive.
+ */
+export const LOCAL_OPERATOR_SENDER = "local:operator";
+
 const DEFAULT_GUEST_PLUGINS: readonly string[] = [
   "brave-search",
   "extras-tools",
 ];
 
-/** Talon tools a guest DM may see and call. Everything else is hidden. */
+/** Talon tools a guest may see and call. Everything else is hidden. */
 export const GUEST_TOOL_ALLOWLIST: ReadonlySet<string> = new Set([
   "end_turn",
   "send",
@@ -56,49 +81,148 @@ export const GUEST_TOOL_ALLOWLIST: ReadonlySet<string> = new Set([
   "download_sticker",
 ]);
 
+/**
+ * Tools whose output is a live credential (an install command embedding
+ * the bridge bearer token). Operator-only, and their output is delivered
+ * to the operator's private chat, never into a shared one.
+ */
+export const OPERATOR_PRIVATE_OUTPUT_TOOLS: ReadonlySet<string> = new Set([
+  "make_node_install_link",
+]);
+
 /** Parameters that name another chat. A guest may only name its own. */
 const CHAT_TARGET_PARAMS = ["chat_id", "to_chat_id", "from_chat_id"] as const;
 
 type ScopeState = {
-  enabled: boolean;
+  dmScope: boolean;
+  /** Operator identities (sender keys) and operator DM chat ids. */
   operators: Set<string>;
+  /** The operator's Telegram DM, where private output is delivered. */
+  operatorDm: string | null;
   plugins: Set<string>;
+  operatorGroups: boolean;
 };
 
 let state: ScopeState = {
-  enabled: false,
+  dmScope: true,
   operators: new Set(),
+  operatorDm: null,
   plugins: new Set(DEFAULT_GUEST_PLUGINS),
+  operatorGroups: false,
 };
 
-/** Set at bootstrap (and on config reload). */
+/**
+ * Set at bootstrap (and on config reload). `operatorIds` are sender keys
+ * in the frontend's own form: a Telegram user id, `wa_dm_<number>`,
+ * `discord:<userId>`, `teams:<userId>`.
+ */
 export function initGuestDmScope(
   cfg: GuestDmScopeConfig | undefined,
   adminUserId?: number,
+  operatorIds: readonly string[] = [],
 ): void {
-  const operators = new Set<string>(cfg?.operatorChats ?? []);
+  const operators = new Set<string>([
+    ...(cfg?.operatorChats ?? []),
+    ...operatorIds,
+  ]);
   if (adminUserId) operators.add(String(adminUserId));
   state = {
-    enabled: cfg?.enabled === true,
+    dmScope: cfg?.enabled !== false,
     operators,
+    operatorDm: adminUserId ? String(adminUserId) : null,
     plugins: new Set(cfg?.guestPlugins ?? DEFAULT_GUEST_PLUGINS),
+    operatorGroups: cfg?.operatorGroups === true,
+  };
+}
+
+/** Is any of this sender's keys a configured operator? */
+function isOperatorSender(senderKeys: readonly string[] | undefined): boolean {
+  if (!senderKeys || senderKeys.length === 0) return false;
+  return senderKeys.some(
+    (key) => key === LOCAL_OPERATOR_SENDER || state.operators.has(key),
+  );
+}
+
+/** Whether any operator identity is configured at all. */
+function hasConfiguredOperator(): boolean {
+  return state.operators.size > 0;
+}
+
+export type TurnScopeInput = {
+  chatId: string;
+  isGroup: boolean;
+  source: "message" | "pulse" | "cron" | "trigger" | "agent";
+  /** Keys of the ONE person behind this turn; absent when unknown/mixed. */
+  senderKeys?: readonly string[];
+  /** The frontend checked the operator is a member of this group chat. */
+  operatorInChat?: boolean;
+};
+
+/**
+ * Operator or guest, for one turn.
+ *
+ *   - Background turns the operator set up (cron, triggers, agent
+ *     reports) keep the full surface; guests can't create them.
+ *   - Pulse in a group reacts to whoever is talking there: guest.
+ *   - With `operatorGroups` on, any turn in a group the operator is a
+ *     member of is operator — the operator vouches for its members.
+ *   - A message turn is operator only when its sender is an operator.
+ *     Two legacy DM exceptions keep single-user installs working: the
+ *     explicit `guestDmScope.enabled: false` opt-out, and an install with
+ *     no operator configured at all (DM access is gated by the frontend's
+ *     own allowlist there).
+ */
+export function resolveTurnScope(input: TurnScopeInput): ToolScope {
+  if (input.isGroup && state.operatorGroups && input.operatorInChat) {
+    return "operator";
+  }
+  if (input.source !== "message") {
+    return input.source === "pulse" && input.isGroup ? "guest" : "operator";
+  }
+  if (isOperatorSender(input.senderKeys)) return "operator";
+  if (input.isGroup) return "guest";
+  if (!state.dmScope || !hasConfiguredOperator()) return "operator";
+  return state.operators.has(input.chatId) ? "operator" : "guest";
+}
+
+// ── Active turn scopes ──────────────────────────────────────────────────────
+
+/** chatId → scope of the turn currently running there (turns are per-chat FIFO). */
+const activeScopes = new Map<string, { scope: ToolScope }>();
+
+/**
+ * Mark `chatId`'s running turn with `scope` until the returned release is
+ * called. The release only clears its own mark.
+ */
+export function enterTurnScope(chatId: string, scope: ToolScope): () => void {
+  const mark = { scope };
+  activeScopes.set(chatId, mark);
+  return () => {
+    if (activeScopes.get(chatId) === mark) activeScopes.delete(chatId);
   };
 }
 
 /**
- * Is this chat id a one-to-one DM? Telegram DMs are the peer's positive
- * user id; WhatsApp DMs are `wa_dm_<number>`. Anything else (groups,
- * Discord, native, heartbeat) is not treated as a DM here.
+ * What a guest turn's prompt opens with. The model shares one session per
+ * chat across senders, so without it an operator turn followed by a guest
+ * turn looks like the MCP servers dropping out from under it — and the
+ * model says so in the chat, blaming restarts or a broken supervisor.
  */
-export function isDmChatId(chatId: string): boolean {
-  return /^\d+$/.test(chatId) || chatId.startsWith("wa_dm_");
+export const GUEST_SCOPE_NOTICE =
+  "[Tool scope notice: this message is from someone other than the operator, " +
+  "so this turn has the conversation-only tool set (replies, reactions, this " +
+  "chat's history, web search). Shell, files, plugins and the rest are withheld " +
+  "on purpose and come back on the operator's next message. This is access " +
+  "control, not a fault — don't report it as tools dropping or try to work around it.]";
+
+/** The prompt a backend sees for a turn of this scope. */
+export function scopePrompt(scope: ToolScope, prompt: string): string {
+  return scope === "guest" ? `${GUEST_SCOPE_NOTICE}\n\n${prompt}` : prompt;
 }
 
-/** Should this chat get the guest surface? */
-export function isGuestChat(chatId: string): boolean {
-  if (!state.enabled) return false;
-  if (!isDmChatId(chatId)) return false;
-  return !state.operators.has(chatId);
+/** Is the turn running in this chat right now guest-scoped? */
+export function isGuestTurn(chatId: string): boolean {
+  return activeScopes.get(chatId)?.scope === "guest";
 }
 
 export function isGuestToolAllowed(name: string): boolean {
@@ -109,6 +233,23 @@ export function isGuestPluginAllowed(serverName: string): boolean {
   return state.plugins.has(serverName);
 }
 
+/**
+ * Is this chat a private chat with the operator — where credential-bearing
+ * output may be shown? The operator's DMs, plus the local frontends.
+ */
+export function isOperatorPrivateChat(
+  frontend: string,
+  chatId: string,
+): boolean {
+  if (frontend === "native" || frontend === "terminal") return true;
+  return state.operators.has(chatId) && !chatId.startsWith("-");
+}
+
+/** Where private operator output is delivered, if anywhere. */
+export function operatorDmChatId(): string | null {
+  return state.operatorDm;
+}
+
 /**
  * Why a guest call with these params must be refused, or null if it is
  * fine. Checked on every guest tool call, after the allowlist.

package/src/core/mcp-hub/index.ts

@@ -28,8 +28,9 @@
  *     from the current registry — see reloadHubChildren)
  *   - orphan cleanup (children still run under the supervisor wrap)
  *
- * Endpoints live on the gateway HTTP server (127.0.0.1-bound, same
- * trust boundary as /action).
+ * Endpoints live on the gateway HTTP server (127.0.0.1-bound, behind the
+ * same token and Host/Origin guard as /action — see engine/gateway-auth.ts;
+ * every backend's hub entry carries the token as a bearer header).
  */
 
 import { randomUUID } from "node:crypto";
@@ -55,8 +56,8 @@ import {
 import type { ToolFrontend } from "../tools/types.js";
 import {
   initGuestDmScope,
-  isGuestChat,
   isGuestPluginAllowed,
+  isGuestTurn,
   type GuestDmScopeConfig,
 } from "./guest-scope.js";
 
@@ -70,10 +71,12 @@ export type HubConfig = {
   braveApiKey?: string;
   /** Surface the native tool set (bash/read/write/… + teleport). */
   nativeTools?: boolean;
-  /** Conversation-only tool surface for non-operator DMs. */
+  /** Conversation-only tool surface for non-operator senders. */
   guestDmScope?: GuestDmScopeConfig;
-  /** Operator's Telegram id — their DM always keeps the full surface. */
+  /** Operator's Telegram id — their messages keep the full surface. */
   adminUserId?: number;
+  /** Further operator sender keys (see guest-scope.ts). */
+  operatorIds?: readonly string[];
 };
 
 let hubConfig: HubConfig = {};
@@ -81,7 +84,7 @@ let hubConfig: HubConfig = {};
 /** Set at bootstrap; safe to call again on config reload. */
 export function initHub(config: HubConfig): void {
   hubConfig = config;
-  initGuestDmScope(config.guestDmScope, config.adminUserId);
+  initGuestDmScope(config.guestDmScope, config.adminUserId, config.operatorIds);
   startChildReaper();
 }
 
@@ -226,14 +229,23 @@ function buildServerFor(target: HubTarget, bridgeUrl: string) {
       disabledTools: hubConfig.disabledTools,
       disabledToolTags: hubConfig.disabledToolTags,
       includeNativeTools: hubConfig.nativeTools,
-      guest: isGuestChat(target.chatId),
+      guest: isGuestTurn(target.chatId),
     });
   }
-  return buildProxyServer(target.serverName, () =>
-    acquireChild(childKey(target.serverName, target.chatId), () =>
+  // Re-checked per request: a session opened during an operator turn must
+  // not serve a later guest turn in the same chat.
+  return buildProxyServer(target.serverName, () => {
+    if (guestPluginDenied(target)) {
+      return Promise.reject(new Error("Not available in this chat"));
+    }
+    return acquireChild(childKey(target.serverName, target.chatId), () =>
       pluginSpec(target.serverName, target.chatId, bridgeUrl),
-    ),
-  );
+    );
+  });
+}
+
+function guestPluginDenied(target: { serverName: string; chatId: string }) {
+  return isGuestTurn(target.chatId) && !isGuestPluginAllowed(target.serverName);
 }
 
 // ── Session registry ────────────────────────────────────────────────────────
@@ -293,6 +305,12 @@ function jsonRpcError(
   );
 }
 
+/** `Host` values a loopback client of the gateway at `bridgeUrl` sends. */
+function loopbackHosts(bridgeUrl: string): string[] {
+  const { port } = new URL(bridgeUrl);
+  return ["127.0.0.1", "localhost", "[::1]"].map((name) => `${name}:${port}`);
+}
+
 /**
  * Handle one request under /mcp/. `bridgeUrl` is the gateway's own base
  * URL (the gateway knows its bound port; the hub does not).
@@ -339,11 +357,7 @@ export async function handleHubRequest(
       return;
     }
 
-    if (
-      target.kind === "plugin" &&
-      isGuestChat(target.chatId) &&
-      !isGuestPluginAllowed(target.serverName)
-    ) {
+    if (target.kind === "plugin" && guestPluginDenied(target)) {
       jsonRpcError(res, 403, "Not available in this chat");
       return;
     }
@@ -351,6 +365,9 @@ export async function handleHubRequest(
     const server = buildServerFor(target, bridgeUrl);
     const transport = new StreamableHTTPServerTransport({
       sessionIdGenerator: () => randomUUID(),
+      // Defence in depth behind the gateway's own Host/Origin guard.
+      enableDnsRebindingProtection: true,
+      allowedHosts: loopbackHosts(bridgeUrl),
       onsessioninitialized: (id) => {
         sessions.set(id, { transport, lastSeen: Date.now() });
       },

package/src/core/mcp-hub/talon-server.ts

@@ -17,8 +17,20 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { composeTools } from "../tools/index.js";
 import { createBridge, textResult } from "../tools/bridge.js";
-import type { ToolFrontend, ToolTag } from "../tools/types.js";
-import { guestParamViolation, isGuestToolAllowed } from "./guest-scope.js";
+import type {
+  BridgeFunction,
+  ToolDefinition,
+  ToolFrontend,
+  ToolTag,
+} from "../tools/types.js";
+import {
+  guestParamViolation,
+  isGuestToolAllowed,
+  isGuestTurn,
+  isOperatorPrivateChat,
+  operatorDmChatId,
+  OPERATOR_PRIVATE_OUTPUT_TOOLS,
+} from "./guest-scope.js";
 
 export const VALID_TOOL_FRONTENDS: ReadonlySet<string> = new Set([
   "telegram",
@@ -39,8 +51,10 @@ export type TalonServerOptions = {
   /** Expose the native tool set (replaces the SDK built-ins). */
   includeNativeTools?: boolean;
   /**
-   * Guest DM: expose only the conversation allowlist and refuse calls that
-   * name another chat or a local file. See guest-scope.ts.
+   * Build the guest surface: expose only the conversation allowlist. Calls
+   * are re-checked against the chat's live turn scope either way, so a
+   * session opened by an operator turn can't serve a later guest turn.
+   * See guest-scope.ts.
    */
   guest?: boolean;
 };
@@ -76,17 +90,60 @@ export function buildTalonToolServer(options: TalonServerOptions): McpServer {
     : tools;
 
   for (const tool of surface) {
-    server.tool(tool.name, tool.description, tool.schema, async (params) => {
-      if (options.guest) {
-        const why = guestParamViolation(
-          options.chatId,
-          params as Record<string, unknown>,
-        );
-        if (why) return textResult(`Not available in this chat: ${why}.`);
-      }
-      return textResult(await tool.execute(params, bridge));
-    });
+    server.tool(tool.name, tool.description, tool.schema, async (params) =>
+      textResult(await callScoped(options, tool, bridge, params)),
+    );
   }
 
   return server;
 }
+
+/** A refused call: an error result the model reads as a failure. */
+function refuse(message: string): { ok: false; text: string } {
+  return { ok: false, text: message };
+}
+
+const PRIVATE_OUTPUT_RECEIPT =
+  "Done. The result carries a live bridge credential, so it was sent to the " +
+  "operator's private chat instead of this one. Do not repeat or summarise it here.";
+
+/**
+ * Run one tool call under the chat's live scope: guest turns get the
+ * allowlist and the parameter guard; credential-bearing tools only ever
+ * show their output in the operator's private chat.
+ */
+async function callScoped(
+  options: TalonServerOptions,
+  tool: ToolDefinition,
+  bridge: BridgeFunction,
+  params: Record<string, unknown>,
+): Promise<unknown> {
+  const guest = options.guest || isGuestTurn(options.chatId);
+  if (guest) {
+    if (!isGuestToolAllowed(tool.name)) {
+      return refuse("Not available in this chat.");
+    }
+    const why = guestParamViolation(options.chatId, params);
+    if (why) return refuse(`Not available in this chat: ${why}.`);
+  }
+  if (
+    !OPERATOR_PRIVATE_OUTPUT_TOOLS.has(tool.name) ||
+    isOperatorPrivateChat(options.frontend, options.chatId)
+  ) {
+    return tool.execute(params, bridge);
+  }
+  const dm = operatorDmChatId();
+  if (!dm) {
+    return refuse(
+      `${tool.name} returns a credential and can only run in the operator's private chat.`,
+    );
+  }
+  const result = (await tool.execute(params, bridge)) as {
+    ok?: boolean;
+    text?: string;
+  };
+  if (result?.ok === false) return result;
+  const text = result?.text ?? JSON.stringify(result);
+  await bridge("send_message", { text, chat_id: dm });
+  return { ok: true, text: PRIVATE_OUTPUT_RECEIPT };
+}

package/src/core/mesh/credentials/admin.ts

@@ -0,0 +1,146 @@
+/**
+ * Operator surface for per-device credentials — what `talon mesh` drives
+ * through the daemon's loopback gateway (core/engine/gateway-routes.ts).
+ *
+ * Pure policy over the store: resolve "which device?" from an id, a
+ * credential id, or a registry name, then list / revoke / rotate / re-scope.
+ * Every reply is plain data plus a human line; the CLI only renders.
+ */
+
+import type { DeviceCredentialStore } from "./store.js";
+import { normalizeScopes, type DeviceCredential } from "./types.js";
+
+type CredentialAdminOp = "revoke" | "rotate" | "scopes";
+
+/** What the admin surface needs from the mesh around it. */
+export type CredentialAdminContext = {
+  store: DeviceCredentialStore;
+  /** Registry lookup by id or name (MeshService.resolveDevice). */
+  resolveDeviceId: (query: string) => string | undefined;
+  /** Whether the shared token is still accepted from remote clients. */
+  legacySharedToken: () => boolean;
+};
+
+export type CredentialOverview = {
+  ok: true;
+  credentials: DeviceCredential[];
+  legacyDevices: { deviceId: string; lastSeen: number }[];
+  legacySharedToken: boolean;
+};
+
+export type CredentialAdminResult =
+  | { ok: true; text: string; credentials: DeviceCredential[] }
+  | { ok: false; error: string };
+
+export async function credentialOverview(
+  ctx: CredentialAdminContext,
+): Promise<CredentialOverview> {
+  await ctx.store.load();
+  return {
+    ok: true,
+    credentials: ctx.store.list(),
+    legacyDevices: ctx.store.legacyDevices(),
+    legacySharedToken: ctx.legacySharedToken(),
+  };
+}
+
+/**
+ * Resolve a CLI argument to the device id credentials are bound to. A
+ * credential id wins (it is unambiguous), then an exact device id with
+ * credentials (a device removed from the registry can still hold one), then
+ * whatever the registry resolves the text to.
+ */
+function resolveTarget(
+  ctx: CredentialAdminContext,
+  query: string,
+): { deviceId: string } | { credentialId: string } | undefined {
+  const all = ctx.store.list();
+  if (all.some((c) => c.id === query)) return { credentialId: query };
+  if (all.some((c) => c.deviceId === query)) return { deviceId: query };
+  const fromRegistry = ctx.resolveDeviceId(query);
+  return fromRegistry ? { deviceId: fromRegistry } : undefined;
+}
+
+export async function credentialAdmin(
+  ctx: CredentialAdminContext,
+  body: Record<string, unknown>,
+): Promise<CredentialAdminResult> {
+  await ctx.store.load();
+  const op = body.op;
+  const query = typeof body.device === "string" ? body.device.trim() : "";
+  if (op !== "revoke" && op !== "rotate" && op !== "scopes") {
+    return { ok: false, error: "op must be revoke, rotate or scopes" };
+  }
+  if (!query) return { ok: false, error: "device is required" };
+  const target = resolveTarget(ctx, query);
+  if (!target) {
+    return { ok: false, error: `No device or credential matches "${query}"` };
+  }
+  if ("credentialId" in target) {
+    if (op !== "revoke") {
+      return { ok: false, error: `${op} takes a device, not a credential id` };
+    }
+    const revoked = await ctx.store.revokeCredential(
+      target.credentialId,
+      "revoked by operator",
+    );
+    return done(revoked, `Revoked credential ${target.credentialId}.`, ctx);
+  }
+  return deviceOp(ctx, op, target.deviceId, body.scopes);
+}
+
+async function deviceOp(
+  ctx: CredentialAdminContext,
+  op: CredentialAdminOp,
+  deviceId: string,
+  scopes: unknown,
+): Promise<CredentialAdminResult> {
+  if (op === "revoke") {
+    const revoked = await ctx.store.revokeDevice(
+      deviceId,
+      "revoked by operator",
+    );
+    return done(
+      revoked,
+      `Revoked ${revoked.length} credential(s) for ${deviceId}; its live sessions were dropped.`,
+      ctx,
+    );
+  }
+  if (op === "rotate") {
+    const pending = await ctx.store.requestRotation(deviceId);
+    return done(
+      pending,
+      `Rotation requested for ${deviceId}: it swaps credentials on its next heartbeat (companions: next connect). The old credential expires in 7 days either way — revoke it to cut it off now.`,
+      ctx,
+    );
+  }
+  const next = normalizeScopes(
+    typeof scopes === "string" ? scopes.split(",").map((s) => s.trim()) : [],
+  );
+  if (next.length === 0) {
+    return {
+      ok: false,
+      error: "scopes must list one or more of: device, client, operator",
+    };
+  }
+  const changed = await ctx.store.setScopes(deviceId, next);
+  return done(
+    changed,
+    `${deviceId} now holds: ${next.join(", ")}. Its live sessions were dropped so the new scopes apply on reconnect.`,
+    ctx,
+  );
+}
+
+function done(
+  credentials: DeviceCredential[],
+  text: string,
+  ctx: CredentialAdminContext,
+): CredentialAdminResult {
+  if (credentials.length === 0) {
+    return { ok: false, error: "That device holds no live credential." };
+  }
+  const legacyNote = ctx.legacySharedToken()
+    ? " Note: native.legacySharedToken is on, so a device that still has the shared token can reconnect with it — rotate native.token and set legacySharedToken: false to close that door."
+    : "";
+  return { ok: true, text: text + legacyNote, credentials };
+}

package/src/core/mesh/credentials/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Per-device mesh credentials — barrel. The store (persistence + lifecycle),
+ * the token format, the scope vocabulary, and the operator surface.
+ */
+
+export { DeviceCredentialStore } from "./store.js";
+export { isDeviceCredentialToken } from "./token.js";
+export {
+  DEFAULT_COMPANION_SCOPES,
+  NODE_SCOPES,
+  type CredentialOrigin,
+  type DeviceCredential,
+  type MeshScope,
+} from "./types.js";
+export {
+  credentialAdmin,
+  credentialOverview,
+  type CredentialAdminContext,
+} from "./admin.js";