@stage-labs/metro 0.1.0-beta.24 → 0.1.0-beta.241

package/runtime/node_modules/@metro-labs/daemon/src/connectors/store.ts

@@ -0,0 +1,385 @@
+import { join } from 'node:path';
+import { syncPluginServers } from './plugin-sync.js';
+import { registerConnectors } from './gates.js';
+import type { ToolPolicy } from '../policy/policy.js';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { listRemoteTools, type RemoteTool } from './tools.js';
+import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
+import { errMsg, log } from '@metro-labs/core/log';
+import {
+  authHeaders,
+  connectorUrlText,
+  ConnectorVerifyError,
+  parseConnectorUrl,
+  verifyRemoteMcp,
+  type ConnectorAuth,
+  type OAuthAuth,
+  type VerifiedRecord,
+} from './verify.js';
+import { oauthExpired, refreshOAuth } from './oauth.js';
+import { advertisesOAuth } from './oauth-discovery.js';
+import {
+  ConnectorError,
+  connectorAuth,
+  connectorClient,
+  connectorName,
+  readConfig,
+  signInState,
+  stamp,
+  type ConnectorConfig,
+  type ConnectorSignIn,
+} from './config.js';
+import type { OAuthClient } from './oauth-client.js';
+import { agentsDir } from '../agents/files.js';
+import { newId } from '@metro-labs/core/ids';
+import type { LoadedConnector } from '../stations/materialize.js';
+
+export interface LocalConnectorRow {
+  id: string;
+  name: string;
+  url: string;
+  config: ConnectorConfig;
+}
+
+export interface Connector {
+  id: string;
+  name: string;
+  url: string;
+  auth: ConnectorAuth['kind'];
+  header: string | null;
+  signIn: ConnectorSignIn;
+  verified: VerifiedRecord;
+  client: OAuthClient | null;
+  policy: ToolPolicy;
+}
+
+export interface PendingConnectorInput {
+  name: unknown;
+  url: unknown;
+  clientId: unknown;
+  clientSecret: unknown;
+}
+
+export interface ConnectorInput extends PendingConnectorInput {
+  header: unknown;
+  value: unknown;
+}
+
+export type ConnectorCheck =
+  | { id: string; name: string; ok: true; verified: VerifiedRecord }
+  | { id: string; name: string; ok: false; reason: string };
+
+export interface DeletedConnector {
+  id: string;
+  name: string;
+}
+
+const UNVERIFIED = { at: '', server: '' };
+
+function connectorFromRow(row: LocalConnectorRow): Connector {
+  const auth = row.config.auth;
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    auth: auth.kind,
+    header: auth.kind === 'header' ? auth.name : null,
+    signIn: signInState(row.config),
+    verified: row.config.verified,
+    client: row.config.client,
+    policy: row.config.policy ?? {},
+  };
+}
+
+const FILE = 'connectors.json';
+const filePath = (dir: string): string => join(dir, FILE);
+
+const isRow = (v: unknown): v is { id: string; name: string; url: string; config?: unknown } =>
+  typeof v === 'object' &&
+  v !== null &&
+  typeof (v as { id?: unknown }).id === 'string' &&
+  typeof (v as { name?: unknown }).name === 'string' &&
+  typeof (v as { url?: unknown }).url === 'string';
+
+const asList = (value: unknown): unknown[] =>
+  Array.isArray(value) ? value.map((item: unknown) => item) : [];
+
+export function readLocalConnectors(dir = agentsDir()): LocalConnectorRow[] {
+  const raw = readJson<{ connectors?: unknown }>(filePath(dir), {}, {
+    warn: 'connectors.json: malformed, ignoring',
+  });
+  return asList(raw.connectors).filter(isRow).map((r) => ({
+    id: r.id,
+    name: r.name,
+    url: r.url,
+    config: readConfig(r.config),
+  }));
+}
+
+function writeRows(dir: string, rows: LocalConnectorRow[]): void {
+  writeSecure(filePath(dir), `${JSON.stringify({ version: 1, connectors: rows }, null, 2)}\n`);
+  if (dir !== agentsDir()) return;
+  syncPluginServers(rows);
+  registerConnectors(rows);
+}
+
+const missing = (): ConnectorError => new ConnectorError('no such connector', 404);
+
+function rowOrThrow(id: string, dir: string): LocalConnectorRow {
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row === undefined) throw missing();
+  return row;
+}
+
+function replace(dir: string, row: LocalConnectorRow): Connector {
+  writeRows(dir, readLocalConnectors(dir).map((r) => (r.id === row.id ? row : r)));
+  return connectorFromRow(row);
+}
+
+async function oauthCapable(url: URL, auth: ConnectorAuth): Promise<boolean> {
+  if (auth.kind === 'oauth') return true;
+  if (auth.kind === 'header') return false;
+  return advertisesOAuth(url);
+}
+
+export function localImportConnectors(
+  rows: LoadedConnector[],
+  dir = agentsDir(),
+  mode: 'append' | 'overwrite' = 'overwrite',
+): number {
+  const current = readLocalConnectors(dir);
+  const fresh =
+    mode === 'overwrite'
+      ? rows
+      : rows.filter((row) => !current.some((r) => r.id === row.id || r.name === row.name));
+  const imported: LocalConnectorRow[] = fresh.map((row) => ({
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    config: readConfig(row.config),
+  }));
+  const ids = new Set(imported.map((r) => r.id));
+  const names = new Set(imported.map((r) => r.name));
+  writeRows(dir, [...current.filter((r) => !ids.has(r.id) && !names.has(r.name)), ...imported]);
+  return imported.length;
+}
+
+export async function localListConnectors(dir = agentsDir()): Promise<Connector[]> {
+  return Promise.resolve(readLocalConnectors(dir).map(connectorFromRow));
+}
+
+export async function localGetConnector(id: string, dir = agentsDir()): Promise<Connector> {
+  return Promise.resolve(connectorFromRow(rowOrThrow(id, dir)));
+}
+
+function assertNameFree(name: string, exceptId: string | null, dir: string): void {
+  if (readLocalConnectors(dir).some((r) => r.id !== exceptId && r.name === name))
+    throw new ConnectorError(`a connector named '${name}' already exists on this daemon`, 409);
+}
+
+function insert(dir: string, name: string, url: URL, config: ConnectorConfig): Connector {
+  assertNameFree(name, null, dir);
+  const row: LocalConnectorRow = { id: newId(), name, url: connectorUrlText(url), config };
+  writeRows(dir, [...readLocalConnectors(dir), row]);
+  return connectorFromRow(row);
+}
+
+export async function localCreateConnector(input: ConnectorInput, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const auth = connectorAuth(input.header, input.value);
+  const client = connectorClient(input.clientId, input.clientSecret);
+  const verified = stamp(await verifyRemoteMcp(url, auth));
+  return insert(dir, name, url, {
+    auth,
+    createdAt: new Date().toISOString(),
+    verified,
+    oauth: await oauthCapable(url, auth),
+    client,
+  });
+}
+
+export async function localCreatePendingConnector(input: PendingConnectorInput, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(input.name);
+  const url = parseConnectorUrl(input.url);
+  const client = connectorClient(input.clientId, input.clientSecret);
+  return Promise.resolve(
+    insert(dir, name, url, { auth: { kind: 'none' }, createdAt: new Date().toISOString(), verified: UNVERIFIED, oauth: true, client }),
+  );
+}
+
+export async function localReconnectConnector(
+  id: string,
+  auth: OAuthAuth,
+  dir = agentsDir(),
+): Promise<Connector> {
+  const row = rowOrThrow(id, dir);
+  const verified = stamp(await verifyRemoteMcp(parseConnectorUrl(row.url), auth));
+  return replace(dir, { ...row, config: { ...row.config, auth, verified, oauth: true } });
+}
+
+const signedOut = (row: LocalConnectorRow): LocalConnectorRow => ({ ...row, config: { ...row.config, auth: { kind: 'none' }, oauth: true } });
+
+export async function localDisconnectConnector(id: string, dir = agentsDir()): Promise<Connector> {
+  const row = rowOrThrow(id, dir);
+  if (row.config.auth.kind !== 'oauth') throw new ConnectorError('that connector is not signed in', 400);
+  return Promise.resolve(replace(dir, signedOut(row)));
+}
+
+export function localMarkSignedOut(id: string, dir = agentsDir()): void {
+  const row = readLocalConnectors(dir).find((r) => r.id === id);
+  if (row?.config.auth.kind !== 'oauth') return;
+  log.info({ id, name: row.name }, 'local relay: the vendor refused the token after a refresh; the connector is signed out');
+  replace(dir, signedOut(row));
+}
+
+async function freshAuth(row: LocalConnectorRow, dir: string): Promise<ConnectorAuth> {
+  const auth = row.config.auth;
+  if (auth.kind !== 'oauth' || !oauthExpired(auth)) return auth;
+  return refreshOnce(row, auth, dir);
+}
+
+function updateRow(dir: string, id: string, config: Partial<LocalConnectorRow['config']>): void {
+  const now = readLocalConnectors(dir).find((r) => r.id === id);
+  if (now !== undefined) replace(dir, { ...now, config: { ...now.config, ...config } });
+}
+
+export async function localVerifyConnector(id: string, dir = agentsDir()): Promise<ConnectorCheck> {
+  const row = rowOrThrow(id, dir);
+  try {
+    const url = parseConnectorUrl(row.url);
+    const auth = await freshAuth(row, dir);
+    const verified = stamp(await verifyRemoteMcp(url, auth));
+    const oauth = row.config.oauth || (await oauthCapable(url, auth));
+    updateRow(dir, row.id, { auth, verified, oauth });
+    return { id: row.id, name: row.name, ok: true, verified };
+  } catch (err) {
+    if (!(err instanceof ConnectorVerifyError)) throw err;
+    return { id: row.id, name: row.name, ok: false, reason: err.message };
+  }
+}
+
+const groupsOf = (tools: RemoteTool[]): Record<string, ToolGroup> =>
+  Object.fromEntries(tools.map((tool) => [tool.name, tool.readOnly ? 'read' : 'write'] as const));
+
+function keepGroups(dir: string, id: string, tools: RemoteTool[]): void {
+  const now = readLocalConnectors(dir).find((r) => r.id === id);
+  const groups = groupsOf(tools);
+  if (now === undefined || JSON.stringify(now.config.toolGroups ?? {}) === JSON.stringify(groups)) return;
+  const config = { ...now.config };
+  delete config.toolGroups;
+  replace(dir, { ...now, config: Object.keys(groups).length > 0 ? { ...config, toolGroups: groups } : config });
+}
+
+export async function localConnectorTools(id: string, dir = agentsDir()): Promise<RemoteTool[]> {
+  const row = rowOrThrow(id, dir);
+  const url = parseConnectorUrl(row.url);
+  const tools = await listRemoteTools(url, await freshAuth(row, dir));
+  keepGroups(dir, id, tools);
+  return tools;
+}
+
+async function refreshGroups(id: string, dir: string): Promise<void> {
+  try {
+    await localConnectorTools(id, dir);
+  } catch (err) {
+    log.warn({ id, err: errMsg(err) }, 'connector policy: could not list the tools; the last known read and write groups stay');
+  }
+}
+
+export async function localSetConnectorPolicy(id: string, policy: ToolPolicy, dir = agentsDir()): Promise<Connector> {
+  const row = rowOrThrow(id, dir);
+  const config = { ...row.config };
+  delete config.policy;
+  const saved = replace(dir, { ...row, config: Object.keys(policy).length > 0 ? { ...config, policy } : config });
+  await refreshGroups(id, dir);
+  return saved;
+}
+
+export async function loadConnectorPolicies(dir = agentsDir()): Promise<void> {
+  const rows = readLocalConnectors(dir);
+  registerConnectors(rows);
+  for (const row of rows) if (row.config.policy !== undefined) await refreshGroups(row.id, dir);
+}
+
+export async function localRenameConnector(id: string, raw: string, dir = agentsDir()): Promise<Connector> {
+  const name = connectorName(raw);
+  const row = rowOrThrow(id, dir);
+  assertNameFree(name, id, dir);
+  return Promise.resolve(replace(dir, { ...row, name }));
+}
+
+export async function localDeleteConnector(id: string, dir = agentsDir()): Promise<DeletedConnector> {
+  const row = rowOrThrow(id, dir);
+  writeRows(dir, readLocalConnectors(dir).filter((r) => r.id !== id));
+  return Promise.resolve({ id: row.id, name: row.name });
+}
+
+const inflight = new Map<string, Promise<OAuthAuth>>();
+
+function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Promise<OAuthAuth> {
+  const running = inflight.get(row.id);
+  if (running !== undefined) return running;
+  const job = refreshOAuth(auth, parseConnectorUrl(row.url).toString())
+    .then((fresh) => {
+      updateRow(dir, row.id, { auth: fresh });
+      return fresh;
+    })
+    .finally(() => {
+      inflight.delete(row.id);
+    });
+  inflight.set(row.id, job);
+  return job;
+}
+
+export type RelayTarget =
+  | { kind: 'ok'; url: string; headers: Record<string, string> }
+  | { kind: 'missing' }
+  | { kind: 'signin' };
+
+function staleUsable(auth: OAuthAuth, now = Date.now()): boolean {
+  return auth.expiresAt === undefined || auth.expiresAt > now;
+}
+
+function unrefreshedTarget(
+  url: string,
+  auth: OAuthAuth,
+  force: boolean,
+  now = Date.now(),
+): RelayTarget {
+  if (force) return { kind: 'signin' };
+  return { kind: 'ok', url, headers: staleUsable(auth, now) ? authHeaders(auth) : {} };
+}
+
+function fixedTarget(
+  url: string,
+  auth: Exclude<ConnectorAuth, OAuthAuth>,
+  force: boolean,
+): RelayTarget {
+  if (force) return { kind: 'signin' };
+  return { kind: 'ok', url, headers: authHeaders(auth) };
+}
+
+async function oauthTarget(row: LocalConnectorRow, auth: OAuthAuth, force: boolean, dir: string): Promise<RelayTarget> {
+  if (!force && !oauthExpired(auth)) return { kind: 'ok', url: row.url, headers: authHeaders(auth) };
+  try {
+    const fresh = await refreshOnce(row, auth, dir);
+    return { kind: 'ok', url: row.url, headers: authHeaders(fresh) };
+  } catch (err) {
+    log.warn({ id: row.id, err: errMsg(err) }, 'local relay: token refresh failed');
+    return unrefreshedTarget(row.url, auth, force);
+  }
+}
+
+export async function localRelayTarget(
+  connectorId: string,
+  force: boolean,
+  dir = agentsDir(),
+): Promise<RelayTarget> {
+  const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
+  if (row === undefined) return { kind: 'missing' };
+  parseConnectorUrl(row.url);
+  const auth = row.config.auth;
+  if (auth.kind === 'oauth') return oauthTarget(row, auth, force, dir);
+  return fixedTarget(row.url, auth, force);
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/tools.ts

@@ -0,0 +1,81 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import { authHeaders, INITIALIZE, mcpPost, payloadOf, refused, type ConnectorAuth } from './verify.js';
+
+export interface RemoteTool {
+  name: string;
+  title: string;
+  description: string;
+  readOnly: boolean;
+}
+
+const TIMEOUT_MS = 15_000;
+const MAX_PAGES = 10;
+
+function resultOf(text: string, contentType: string): Record<string, unknown> | null {
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(payloadOf(text, contentType));
+  } catch {
+    return null;
+  }
+  return isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+}
+
+async function rpc(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown): Promise<Record<string, unknown> | null> {
+  const res = await mcpPost(url, auth, body, { timeoutMs: TIMEOUT_MS, headers: Object.fromEntries(session) });
+  const id = res.headers.get('mcp-session-id');
+  if (id !== null && id !== '') session.set('mcp-session-id', id);
+  const text = await res.text().catch(() => '');
+  if (res.status === 401 || res.status === 403) throw refused(`${url.hostname} rejected the credential; connect it again`);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)}`);
+  return resultOf(text, res.headers.get('content-type') ?? '');
+}
+
+function toTool(raw: unknown): RemoteTool | null {
+  if (!isRecord(raw) || typeof raw.name !== 'string') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : {};
+  const title = typeof raw.title === 'string' && raw.title !== '' ? raw.title : raw.name;
+  return { name: raw.name, title, description: typeof raw.description === 'string' ? raw.description : '', readOnly: annotations.readOnlyHint === true };
+}
+
+async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, string>): Promise<void> {
+  if (!session.has('mcp-session-id')) return;
+  try {
+    const res = await fetch(url, { method: 'DELETE', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS), headers: { ...authHeaders(auth), ...Object.fromEntries(session) } });
+    await res.body?.cancel();
+  } catch (err) {
+    log.debug({ host: url.hostname, err: errMsg(err) }, 'connector-tools: the remote declined to end the session');
+  }
+}
+
+const toolsOf = (result: Record<string, unknown>): RemoteTool[] =>
+  Array.isArray(result.tools) ? result.tools.flatMap((raw: unknown) => toTool(raw) ?? []) : [];
+
+function nextCursor(result: Record<string, unknown>, current: string): string | null {
+  const next = result.nextCursor;
+  return typeof next !== 'string' || next === '' || next === current ? null : next;
+}
+
+async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>): Promise<RemoteTool[]> {
+  const tools: RemoteTool[] = [];
+  let cursor: string | null = '';
+  for (let page = 0; page < MAX_PAGES && cursor !== null; page += 1) {
+    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } });
+    if (result === null) break;
+    tools.push(...toolsOf(result));
+    cursor = nextCursor(result, cursor);
+  }
+  return tools;
+}
+
+export async function listRemoteTools(url: URL, auth: ConnectorAuth): Promise<RemoteTool[]> {
+  const session = new Map<string, string>();
+  const init = await rpc(url, auth, session, INITIALIZE);
+  if (init === null || typeof init.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+  session.set('mcp-protocol-version', init.protocolVersion);
+  await rpc(url, auth, session, { jsonrpc: '2.0', method: 'notifications/initialized' });
+  const tools = await walkTools(url, auth, session);
+  await endSession(url, auth, session);
+  return tools;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/transfer-api.ts

@@ -0,0 +1,116 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { randomUUID, type KeyObject } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import { log } from '@metro-labs/core/log';
+import { ApiError } from '@metro-labs/http/api-error';
+import { apiSession, cors, readJsonBody, requireAdmin, sendJson } from '@metro-labs/http/api-http';
+import { openTransfer, sealTransfer, transferKeys } from './transfer-crypto.js';
+import type { LocalConnectorRow } from './store.js';
+import type { ConnectorCopyResult } from './transfer-store.js';
+
+const PREFIX = '/api/connectors/transfer';
+const MAX_BODY = 4 * 1024 * 1024 + 4096;
+const TTL = 5 * 60_000;
+
+export interface ConnectorTransferDeps {
+  read: () => LocalConnectorRow[];
+  copy: (value: unknown) => ConnectorCopyResult[];
+  now?: () => number;
+}
+
+interface Ticket {
+  privateKey: KeyObject;
+  organization: string;
+  expiresAt: number;
+}
+
+function selectedIds(raw: unknown): string[] | null {
+  if (raw === null) return null;
+  if (!Array.isArray(raw) || raw.length === 0 || raw.length > 500) throw new ApiError('choose connectors to copy', 400);
+  return [...new Set(raw.map((id: unknown) => {
+    if (typeof id !== 'string' || parseId(id) === null) throw new ApiError('choose connectors to copy', 400);
+    return id;
+  }))];
+}
+
+export class ConnectorTransfers {
+  private readonly tickets = new Map<string, Ticket>();
+
+  constructor(private readonly deps: ConnectorTransferDeps) {}
+
+  private prepare(organization: string): unknown {
+    const now = (this.deps.now ?? Date.now)();
+    for (const [id, ticket] of this.tickets) if (ticket.expiresAt <= now) this.tickets.delete(id);
+    if (this.tickets.size >= 64) throw new ApiError('too many pending connector copies, try again later', 429);
+    const { publicKey, privateKey } = transferKeys();
+    const ticket = randomUUID();
+    this.tickets.set(ticket, { privateKey, organization, expiresAt: now + TTL });
+    return { ticket, publicKey };
+  }
+
+  private export(body: Record<string, unknown>): unknown {
+    if (typeof body.publicKey !== 'string') throw new ApiError('invalid transfer key', 400);
+    const ids = selectedIds(body.ids);
+    const all = this.deps.read();
+    const rows = ids === null ? all : all.filter((row) => ids.includes(row.id));
+    const expected = ids?.length ?? rows.length;
+    if (rows.length !== expected) throw new ApiError('a selected connector no longer exists', 409);
+    if (rows.length > 500) throw new ApiError('copy at most 500 connectors at once', 413);
+    try {
+      return sealTransfer({ version: 1, connectors: rows }, body.publicKey);
+    } catch (err) {
+      if (err instanceof ApiError) throw err;
+      throw new ApiError('invalid transfer key', 400);
+    }
+  }
+
+  private receive(body: Record<string, unknown>, organization: string): unknown {
+    const id = typeof body.ticket === 'string' ? body.ticket : '';
+    const ticket = this.tickets.get(id);
+    if (ticket?.organization !== organization || ticket.expiresAt <= (this.deps.now ?? Date.now)()) {
+      this.tickets.delete(id);
+      throw new ApiError('this connector copy has expired, start again', 410);
+    }
+    let value: unknown;
+    try {
+      value = openTransfer(body.envelope, ticket.privateKey);
+    } catch {
+      throw new ApiError('invalid encrypted connector copy', 400);
+    }
+    const results = this.deps.copy(value);
+    this.tickets.delete(id);
+    return { results };
+  }
+
+  private async answer(req: IncomingMessage, path: string): Promise<unknown> {
+    const session = await apiSession(req);
+    if (session === null) throw new ApiError('unauthorized', 401);
+    requireAdmin(session);
+    const body = await readJsonBody(req, MAX_BODY);
+    if (!isRecord(body) || body.confirmed !== true) throw new ApiError('confirm copying saved logins and settings', 400);
+    if (path === `${PREFIX}/prepare`) return this.prepare(session.subject);
+    if (path === `${PREFIX}/export`) return this.export(body);
+    return this.receive(body, session.subject);
+  }
+
+  handle(req: IncomingMessage, res: ServerResponse): boolean {
+    const path = (req.url ?? '').split('?')[0] ?? '';
+    if (![`${PREFIX}/prepare`, `${PREFIX}/export`, `${PREFIX}/receive`].includes(path)) return false;
+    if (req.method === 'OPTIONS') {
+      res.writeHead(204, cors(req)).end();
+      return true;
+    }
+    if (req.method !== 'POST') {
+      sendJson(req, res, 405, { error: 'method not allowed' });
+      return true;
+    }
+    this.answer(req, path).then((body) => {
+      sendJson(req, res, 200, body);
+    }).catch((err: unknown) => {
+      if (!(err instanceof ApiError)) log.warn('connector-transfer: request failed');
+      sendJson(req, res, err instanceof ApiError ? err.status : 500, { error: err instanceof ApiError ? err.message : 'connector copy failed' });
+    });
+    return true;
+  }
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/transfer-crypto.ts

@@ -0,0 +1,44 @@
+import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, type KeyObject } from 'node:crypto';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+
+export interface TransferEnvelope {
+  key: string;
+  iv: string;
+  tag: string;
+  data: string;
+}
+
+export const transferKeys = (): { publicKey: string; privateKey: KeyObject } => {
+  const pair = generateKeyPairSync('x25519');
+  return { publicKey: pair.publicKey.export({ type: 'spki', format: 'pem' }).toString(), privateKey: pair.privateKey };
+};
+
+function sharedKey(privateKey: KeyObject, pem: string): ArrayBuffer {
+  if (pem.length > 1024) throw new ApiError('invalid transfer key', 400);
+  const publicKey = createPublicKey(pem);
+  if (publicKey.asymmetricKeyType !== 'x25519') throw new ApiError('invalid transfer key', 400);
+  return hkdfSync('sha256', diffieHellman({ privateKey, publicKey }), '', 'metro-connector-copy-v1', 32);
+}
+
+export function sealTransfer(value: unknown, publicKey: string): TransferEnvelope {
+  const pair = transferKeys();
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', Buffer.from(sharedKey(pair.privateKey, publicKey)), iv);
+  const plain = JSON.stringify(value);
+  if (Buffer.byteLength(plain) > 3 * 1024 * 1024) throw new ApiError('too many connector settings for one copy', 413);
+  const data = Buffer.concat([cipher.update(plain, 'utf8'), cipher.final()]);
+  return { key: pair.publicKey, iv: iv.toString('base64'), tag: cipher.getAuthTag().toString('base64'), data: data.toString('base64') };
+}
+
+export function openTransfer(raw: unknown, privateKey: KeyObject): unknown {
+  if (!isRecord(raw) || typeof raw.key !== 'string' || typeof raw.iv !== 'string' || typeof raw.tag !== 'string' || typeof raw.data !== 'string')
+    throw new ApiError('invalid encrypted transfer', 400);
+  const iv = Buffer.from(raw.iv, 'base64');
+  const tag = Buffer.from(raw.tag, 'base64');
+  if (iv.length !== 12 || tag.length !== 16) throw new ApiError('invalid encrypted transfer', 400);
+  const decipher = createDecipheriv('aes-256-gcm', Buffer.from(sharedKey(privateKey, raw.key)), iv);
+  decipher.setAuthTag(tag);
+  const plain = Buffer.concat([decipher.update(Buffer.from(raw.data, 'base64')), decipher.final()]);
+  return JSON.parse(plain.toString('utf8')) as unknown;
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/transfer-store.ts

@@ -0,0 +1,48 @@
+import { isDeepStrictEqual } from 'node:util';
+import { isRecord } from '@metro-labs/core/is-record';
+import { newId, parseId } from '@metro-labs/core/ids';
+import { ApiError } from '@metro-labs/http/api-error';
+import { connectorAuth, connectorName, readConfig } from './config.js';
+import { parseConnectorUrl } from './url.js';
+import { normalizePolicy } from '../policy/policy.js';
+import { localImportConnectors, readLocalConnectors, type LocalConnectorRow } from './store.js';
+
+export interface ConnectorCopyResult {
+  sourceId: string | null;
+  id?: string;
+  status: 'copied' | 'skipped' | 'invalid';
+}
+
+function copyRow(raw: unknown): LocalConnectorRow {
+  if (!isRecord(raw) || typeof raw.id !== 'string' || parseId(raw.id) === null || !isRecord(raw.config)) throw new ApiError('invalid connector', 400);
+  const name = connectorName(raw.name);
+  const url = parseConnectorUrl(raw.url).toString();
+  if (raw.config.policy !== undefined) normalizePolicy(raw.config.policy);
+  const config = readConfig(raw.config);
+  if (!isDeepStrictEqual(config, raw.config)) throw new ApiError('invalid connector settings', 400);
+  if (config.auth.kind === 'header') connectorAuth(config.auth.name, config.auth.value);
+  return { id: raw.id, name, url, config };
+}
+
+export function copyConnectorRows(value: unknown, dir?: string): ConnectorCopyResult[] {
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.connectors) || value.connectors.length > 500)
+    throw new ApiError('invalid connector transfer', 400);
+  const names = new Set(readLocalConnectors(dir).map((row) => row.name));
+  const imported: LocalConnectorRow[] = [];
+  const results: ConnectorCopyResult[] = value.connectors.map((raw: unknown) => {
+    const sourceId = isRecord(raw) && typeof raw.id === 'string' ? parseId(raw.id) : null;
+    let row: LocalConnectorRow;
+    try {
+      row = copyRow(raw);
+    } catch {
+      return { sourceId, status: 'invalid' };
+    }
+    if (names.has(row.name)) return { sourceId, status: 'skipped' };
+    names.add(row.name);
+    const id = newId();
+    imported.push({ ...row, id });
+    return { sourceId, id, status: 'copied' };
+  });
+  if (imported.length > 0) localImportConnectors(imported.map((row) => ({ ...row, config: { ...row.config } })), dir, 'append');
+  return results;
+}