@stage-labs/metro 0.1.0-beta.30 → 0.1.0-beta.301

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

@@ -0,0 +1,148 @@
+import { createPrivateKey, createPublicKey, generateKeyPairSync, randomBytes, type KeyObject } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { parseId } from '@metro-labs/core/ids';
+import { isRecord } from '@metro-labs/core/is-record';
+import { log } from '@metro-labs/core/log';
+import { ensureSecureDir } from '@metro-labs/core/secure-fs';
+import { agentKeyId, rawPublicKey } from '@metro-labs/http/agent-signature';
+import { ApiError } from '@metro-labs/http/api-error';
+import { isOrganizationId } from '@metro-labs/http/workos-token';
+import { agentsDir } from '../agents/files.js';
+
+const FILE = 'agent-key.json';
+
+export interface Enrollment {
+  server: string;
+  organization: string;
+  at: string;
+}
+
+export interface AgentKey {
+  keyId: string;
+  signingKey: string;
+  sealingKey: string;
+  signing: KeyObject;
+  sealing: KeyObject;
+  enrollment: Enrollment | null;
+}
+
+const pathOf = (dir: string): string => join(dir, FILE);
+
+function privateKeyOf(raw: unknown, type: 'ed25519' | 'x25519'): KeyObject | null {
+  if (typeof raw !== 'string' || raw === '') return null;
+  try {
+    const key = createPrivateKey({ key: Buffer.from(raw, 'base64'), format: 'der', type: 'pkcs8' });
+    return key.asymmetricKeyType === type ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+function enrollmentOf(raw: unknown): Enrollment | null {
+  if (!isRecord(raw) || typeof raw.organization !== 'string' || typeof raw.at !== 'string') return null;
+  const server = parseId(raw.server);
+  return server !== null && isOrganizationId(raw.organization) ? { server, organization: raw.organization, at: raw.at } : null;
+}
+
+function agentKeyOf(signing: KeyObject, sealing: KeyObject, enrollment: Enrollment | null): AgentKey {
+  const signingKey = rawPublicKey(createPublicKey(signing));
+  return { keyId: agentKeyId(signingKey), signingKey, sealingKey: rawPublicKey(createPublicKey(sealing)), signing, sealing, enrollment };
+}
+
+const unreadable = (): null => {
+  log.warn('agent-key.json: Metro cannot read this agent key, so the agent must be enrolled again');
+  return null;
+};
+
+function storedOf(path: string): Record<string, unknown> | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return unreadable();
+  }
+  return isRecord(parsed) ? parsed : unreadable();
+}
+
+function keyOf(stored: Record<string, unknown> | null): AgentKey | null {
+  if (stored === null) return null;
+  const signing = privateKeyOf(stored.signing, 'ed25519');
+  const sealing = privateKeyOf(stored.sealing, 'x25519');
+  if (stored.version !== 1 || signing === null || sealing === null) return unreadable();
+  return agentKeyOf(signing, sealing, enrollmentOf(stored.enrollment));
+}
+
+export function readAgentKey(dir = agentsDir()): AgentKey | null {
+  const path = existsSync(pathOf(dir)) ? pathOf(dir) : join(dir, 'box-key.json');
+  return existsSync(path) ? keyOf(storedOf(path)) : null;
+}
+
+const pendingPath = (dir: string): string => join(dir, 'agent-key.pending.json');
+
+function pendingFields(stored: Record<string, unknown> | null): { owner: string; ticketHash: string; expectedServer: string | null } {
+  if (typeof stored?.ticketHash !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(stored.ticketHash) || typeof stored.owner !== 'string' || !isOrganizationId(stored.owner)) {
+    throw new ApiError('Metro cannot read the pending enrollment key. Restore its file or permissions before enrolling again.', 503);
+  }
+  const expectedServer = stored.expectedServer === undefined ? null : parseId(stored.expectedServer);
+  if (stored.expectedServer !== undefined && expectedServer === null) throw new ApiError('Metro cannot read the pending enrollment identity. Restore its file before enrolling again.', 503);
+  return { owner: stored.owner, ticketHash: stored.ticketHash, expectedServer };
+}
+
+export function readPendingAgentKey(owner: string, dir: string): (AgentKey & { ticketHash: string; expectedServer: string | null }) | null {
+  if (!existsSync(pendingPath(dir))) return null;
+  const stored = storedOf(pendingPath(dir));
+  const fields = pendingFields(stored);
+  const key = keyOf(stored);
+  if (key === null) throw new ApiError('Metro cannot read the pending enrollment key. Restore its file or permissions before enrolling again.', 503);
+  return fields.owner === owner ? { ...key, ticketHash: fields.ticketHash, expectedServer: fields.expectedServer } : null;
+}
+
+function flush(path: string): void {
+  const file = openSync(path, 'r');
+  try {
+    fsyncSync(file);
+  } finally {
+    closeSync(file);
+  }
+}
+
+function writeKey(path: string, stored: Record<string, unknown>): void {
+  const dir = dirname(path);
+  ensureSecureDir(dir);
+  const temp = `${path}.${randomBytes(12).toString('hex')}.tmp`;
+  const file = openSync(temp, 'wx', 0o600);
+  try {
+    try {
+      writeFileSync(file, `${JSON.stringify(stored, null, 2)}\n`);
+      fsyncSync(file);
+    } finally {
+      closeSync(file);
+    }
+    renameSync(temp, path);
+    flush(dir);
+  } finally {
+    rmSync(temp, { force: true });
+  }
+}
+
+export function clearPendingAgentKey(dir: string): void {
+  rmSync(pendingPath(dir), { force: true });
+  flush(dir);
+}
+
+export function newAgentKey(): AgentKey {
+  return agentKeyOf(generateKeyPairSync('ed25519').privateKey, generateKeyPairSync('x25519').privateKey, null);
+}
+
+const exported = (key: KeyObject): string => key.export({ format: 'der', type: 'pkcs8' }).toString('base64');
+
+const privateKeys = (key: AgentKey): Record<string, unknown> => ({ version: 1, signing: exported(key.signing), sealing: exported(key.sealing) });
+
+export function savePendingAgentKey(key: AgentKey, owner: string, ticketHash: string, dir: string, expectedServer?: string): void {
+  writeKey(pendingPath(dir), { ...privateKeys(key), owner, ticketHash, ...(expectedServer === undefined ? {} : { expectedServer }) });
+}
+
+export function saveAgentKey(key: AgentKey, enrollment: Enrollment, dir = agentsDir()): void {
+  writeKey(pathOf(dir), { ...privateKeys(key), enrollment });
+}

package/runtime/node_modules/@metro-labs/{mcp/src/daemon/connector-api.ts → daemon/src/connectors/api.ts}

@@ -1,93 +1,60 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { errMsg, log } from './log.js';
+import { log } from '@metro-labs/core/log';
+import { healthOf } from './health.js';
+import type { RemoteTool } from './tools.js';
+import type { ConnectorMigrationPreview } from './migration-preview.js';
+import { normalizePolicy, type ToolPolicy } from '../policy/policy.js';
 import {
   apiFailure,
   apiSession,
-  projectParam,
   bodyField,
   cors,
   readJsonBody,
+  requireAdmin,
   sendJson,
-  type ApiSession,
-} from './api-http.js';
-import { parseId } from '../db/ids.js';
-import type { ConnectorCollectionRow } from '../db/connector-collections.js';
-import type { RelayServerEntry } from './connector-json.js';
+  stringOf,
+} from '@metro-labs/http/api-http';
+import { parseId } from '@metro-labs/core/ids';
 import {
   handleCallback,
   handleConnect,
   hostOf,
   startOAuth,
   type OAuthRouteDeps,
-} from './connector-oauth-routes.js';
-import { ConnectorUnauthorized } from './connector-verify.js';
+} from './oauth-routes.js';
+import { ConnectorUnauthorized } from '@metro-labs/http/connector-url';
 import type {
   Connector,
   ConnectorCheck,
   ConnectorInput,
   DeletedConnector,
-} from '../db/connectors.js';
+} from './store.js';
 
 const PREFIX = '/api/connectors';
 
-const asText = (value: unknown): string =>
-  typeof value === 'string' ? value : '';
-
 export interface ConnectorApiDeps extends OAuthRouteDeps {
-  listConnectors: (email: string, project: string) => Promise<Connector[]>;
-  connectorNamesByIds: (ids: string[]) => Promise<RelayServerEntry[]>;
-  listCollections: (
-    email: string,
-    project: string,
-  ) => Promise<ConnectorCollectionRow[]>;
-  getCollection: (email: string, id: string) => Promise<ConnectorCollectionRow>;
-  createCollection: (
-    email: string,
-    project: string,
-    name: string,
-  ) => Promise<ConnectorCollectionRow>;
-  renameCollection: (
-    email: string,
-    id: string,
-    name: string,
-  ) => Promise<ConnectorCollectionRow>;
-  deleteCollection: (
-    email: string,
-    id: string,
-  ) => Promise<{ id: string; name: string }>;
-  addToCollection: (
-    email: string,
-    id: string,
-    connectorId: string,
-  ) => Promise<ConnectorCollectionRow>;
-  removeFromCollection: (
-    email: string,
-    id: string,
-    connectorId: string,
-  ) => Promise<ConnectorCollectionRow>;
-  createConnector: (
-    email: string,
-    project: string,
-    input: ConnectorInput,
-  ) => Promise<Connector>;
-  verifyConnector: (email: string, id: string) => Promise<ConnectorCheck>;
-  disconnectConnector: (email: string, id: string) => Promise<Connector>;
-  renameConnector: (
-    email: string,
-    id: string,
-    name: string,
-  ) => Promise<Connector>;
-  deleteConnector: (email: string, id: string) => Promise<DeletedConnector>;
+  migrationPreview?: () => ConnectorMigrationPreview;
+  listConnectors: () => Promise<Connector[]>;
+  createConnector: (input: ConnectorInput) => Promise<Connector>;
+  verifyConnector: (id: string) => Promise<ConnectorCheck>;
+  connectorTools: (id: string) => Promise<RemoteTool[]>;
+  disconnectConnector: (id: string) => Promise<Connector>;
+  renameConnector: (id: string, name: string) => Promise<Connector>;
+  deleteConnector: (id: string) => Promise<DeletedConnector>;
+  setConnectorPolicy: (id: string, policy: ToolPolicy) => Promise<Connector>;
 }
 
 type Routable =
   | { kind: 'collection' }
+  | { kind: 'migration-preview' }
   | { kind: 'callback' }
   | { kind: 'connector'; id: string }
   | { kind: 'verify'; id: string }
+  | { kind: 'tools'; id: string }
   | { kind: 'connect'; id: string }
   | { kind: 'disconnect'; id: string }
-  | { kind: 'rename'; id: string };
+  | { kind: 'rename'; id: string }
+  | { kind: 'policy'; id: string };
 
 type Target = Routable | { kind: 'unknown' } | null;
 
@@ -96,9 +63,11 @@ function subTarget(id: string, rest: string[]): Target {
   if (rest.length > 1) return { kind: 'unknown' };
   const head = rest[0];
   if (head === 'verify') return { kind: 'verify', id };
+  if (head === 'tools') return { kind: 'tools', id };
   if (head === 'connect') return { kind: 'connect', id };
   if (head === 'disconnect') return { kind: 'disconnect', id };
   if (head === 'rename') return { kind: 'rename', id };
+  if (head === 'policy') return { kind: 'policy', id };
   return { kind: 'unknown' };
 }
 
@@ -109,24 +78,23 @@ function target(path: string): Target {
   const head = segments[0];
   if (head === undefined) return { kind: 'collection' };
   if (head === 'callback' && segments.length === 1) return { kind: 'callback' };
+  if (head === 'migration-preview' && segments.length === 1) return { kind: 'migration-preview' };
   const id = parseId(head);
   return id === null ? { kind: 'unknown' } : subTarget(id, segments.slice(1));
 }
 
-function connectorPayload(
-  row: Connector,
-  detail = false,
-): Record<string, unknown> {
-  const { catalog, ...summary } = row.verified;
+function connectorPayload(row: Connector): Record<string, unknown> {
   return {
     id: row.id,
     name: row.name,
     url: row.url,
-    transport: row.transport,
     auth: row.auth,
     header: row.header,
+    clientId: row.client?.clientId ?? null,
     signIn: row.signIn,
-    verified: detail ? { ...summary, catalog } : summary,
+    verified: row.verified,
+    policy: row.policy,
+    health: healthOf(row.id),
   };
 }
 
@@ -134,14 +102,8 @@ async function handleList(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
 ): Promise<void> {
-  const project = projectParam(req);
-  if (project === null) {
-    sendJson(req, res, 400, { error: 'a project is required' });
-    return;
-  }
-  const rows = await deps.listConnectors(session.email, project);
+  const rows = await deps.listConnectors();
   sendJson(req, res, 200, {
     connectors: rows.map((row) => connectorPayload(row)),
   });
@@ -151,21 +113,17 @@ async function handleCreate(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
 ): Promise<void> {
   const body = await readJsonBody(req);
-  const project = projectParam(req);
-  if (project === null) {
-    sendJson(req, res, 400, { error: 'a project is required' });
-    return;
-  }
-  const offered = asText(bodyField(body, 'value')).trim() !== '';
+  const offered = stringOf(bodyField(body, 'value')).trim() !== '';
   try {
-    const created = await deps.createConnector(session.email, project, {
+    const created = await deps.createConnector({
       name: bodyField(body, 'name'),
       url: bodyField(body, 'url'),
       header: bodyField(body, 'header'),
       value: bodyField(body, 'value'),
+      clientId: bodyField(body, 'clientId'),
+      clientSecret: bodyField(body, 'clientSecret'),
     });
     log.info(
       { id: created.id, name: created.name, host: hostOf(created.url) },
@@ -174,7 +132,7 @@ async function handleCreate(
     sendJson(req, res, 201, connectorPayload(created));
   } catch (err) {
     if (offered || !(err instanceof ConnectorUnauthorized)) throw err;
-    await startOAuth(req, res, deps, session, project, body, (row) =>
+    await startOAuth(req, res, deps, body, (row) =>
       connectorPayload(row),
     );
   }
@@ -184,10 +142,9 @@ async function handleVerify(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
   id: string,
 ): Promise<void> {
-  const check = await deps.verifyConnector(session.email, id);
+  const check = await deps.verifyConnector(id);
   log.info(
     { id: check.id, name: check.name, ok: check.ok },
     'connector-api: re-verified connector',
@@ -199,10 +156,9 @@ async function handleDisconnect(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
   id: string,
 ): Promise<void> {
-  const row = await deps.disconnectConnector(session.email, id);
+  const row = await deps.disconnectConnector(id);
   log.info(
     { id: row.id, name: row.name },
     'connector-api: signed the connector out',
@@ -214,10 +170,9 @@ async function handleDelete(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
   id: string,
 ): Promise<void> {
-  const gone = await deps.deleteConnector(session.email, id);
+  const gone = await deps.deleteConnector(id);
   log.info(
     { id: gone.id, name: gone.name },
     'connector-api: deleted connector',
@@ -229,22 +184,20 @@ async function handleConnector(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
   id: string,
 ): Promise<void> {
   if (req.method !== 'GET') {
-    await handleDelete(req, res, deps, session, id);
+    await handleDelete(req, res, deps, id);
     return;
   }
-  const row = await deps.getConnector(session.email, id);
-  sendJson(req, res, 200, connectorPayload(row, true));
+  const row = await deps.getConnector(id);
+  sendJson(req, res, 200, connectorPayload(row));
 }
 
 async function handleRename(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
   id: string,
 ): Promise<void> {
   const name = bodyField(await readJsonBody(req), 'name');
@@ -252,32 +205,53 @@ async function handleRename(
     sendJson(req, res, 400, { error: 'name is required' });
     return;
   }
-  const row = await deps.renameConnector(session.email, id, name);
+  const row = await deps.renameConnector(id, name);
   log.info({ id: row.id, name: row.name }, 'connector-api: renamed connector');
   sendJson(req, res, 200, connectorPayload(row));
 }
 
+async function handlePolicy(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  id: string,
+): Promise<void> {
+  const policy = normalizePolicy(bodyField(await readJsonBody(req), 'policy'));
+  const row = await deps.setConnectorPolicy(id, policy);
+  log.info({ id: row.id, name: row.name, policy: row.policy }, 'connector-api: tool policy set');
+  sendJson(req, res, 200, connectorPayload(row));
+}
+
+type ById = Exclude<Routable['kind'], 'collection' | 'callback' | 'migration-preview'>;
+
+const BY_ID: Record<ById, (req: IncomingMessage, res: ServerResponse, deps: ConnectorApiDeps, id: string) => Promise<void>> = {
+  verify: handleVerify,
+  tools: async (req, res, deps, id) => {
+    sendJson(req, res, 200, { tools: await deps.connectorTools(id) });
+  },
+  connect: handleConnect,
+  disconnect: handleDisconnect,
+  rename: handleRename,
+  policy: handlePolicy,
+  connector: handleConnector,
+};
+
 async function route(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
-  session: ApiSession,
   tgt: Routable,
 ): Promise<void> {
   try {
     if (tgt.kind === 'callback') return;
-    if (tgt.kind === 'verify')
-      await handleVerify(req, res, deps, session, tgt.id);
-    else if (tgt.kind === 'connect')
-      await handleConnect(req, res, deps, session, tgt.id);
-    else if (tgt.kind === 'disconnect')
-      await handleDisconnect(req, res, deps, session, tgt.id);
-    else if (tgt.kind === 'rename')
-      await handleRename(req, res, deps, session, tgt.id);
-    else if (tgt.kind === 'connector')
-      await handleConnector(req, res, deps, session, tgt.id);
-    else if (req.method === 'GET') await handleList(req, res, deps, session);
-    else await handleCreate(req, res, deps, session);
+    if (tgt.kind === 'migration-preview') {
+      if (deps.migrationPreview === undefined) sendJson(req, res, 503, { error: 'Migration preview is unavailable.' });
+      else sendJson(req, res, 200, deps.migrationPreview());
+      return;
+    }
+    if (tgt.kind !== 'collection') await BY_ID[tgt.kind](req, res, deps, tgt.id);
+    else if (req.method === 'GET') await handleList(req, res, deps);
+    else await handleCreate(req, res, deps);
   } catch (err) {
     apiFailure(req, res, err, 'connector-api');
   }
@@ -285,15 +259,18 @@ async function route(
 
 const ALLOWED: Record<Routable['kind'], string[]> = {
   collection: ['GET', 'POST'],
+  'migration-preview': ['GET'],
   callback: ['GET'],
   connector: ['GET', 'DELETE'],
   verify: ['POST'],
+  tools: ['GET'],
   connect: ['POST'],
   disconnect: ['POST'],
   rename: ['POST'],
+  policy: ['PUT'],
 };
 
-function dispatch(
+async function dispatch(
   req: IncomingMessage,
   res: ServerResponse,
   deps: ConnectorApiDeps,
@@ -301,14 +278,15 @@ function dispatch(
 ): Promise<void> {
   if (tgt.kind === 'callback') {
     handleCallback(req, res, deps);
-    return Promise.resolve();
+    return;
   }
-  const session = apiSession(req);
+  const session = await apiSession(req);
   if (!session) {
     sendJson(req, res, 401, { error: 'unauthorized' });
-    return Promise.resolve();
+    return;
   }
-  return route(req, res, deps, session, tgt);
+  if (tgt.kind === 'migration-preview') requireAdmin(session);
+  await route(req, res, deps, tgt);
 }
 
 export function handleConnectorApiRequest(
@@ -331,9 +309,8 @@ export function handleConnectorApiRequest(
     return true;
   }
   dispatch(req, res, deps, tgt).catch((err: unknown) => {
-    log.warn({ err: errMsg(err) }, 'connector-api: unhandled error');
-    if (!res.headersSent)
-      sendJson(req, res, 500, { error: 'connector api failed' });
+    if (res.headersSent) return;
+    apiFailure(req, res, err, 'connector-api');
   });
   return true;
 }

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

@@ -0,0 +1,105 @@
+import { stringOf } from '@metro-labs/http/api-http';
+import type {
+  ConnectorAuth,
+  VerifiedRecord,
+  VerifiedServer,
+} from '@metro-labs/http/connector-mcp';
+import type { OAuthClient } from '@metro-labs/http/connector-oauth';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { parsePolicy, type ToolPolicy } from '../policy/policy.js';
+
+export type ConnectorSignIn = 'connected' | 'disconnected' | null;
+
+export interface ConnectorConfig {
+  auth: ConnectorAuth;
+  createdAt: string;
+  verified: VerifiedRecord;
+  oauth: boolean;
+  client: OAuthClient | null;
+  policy?: ToolPolicy;
+  toolGroups?: Record<string, ToolGroup>;
+}
+
+function readClient(raw: unknown): OAuthClient | null {
+  if (!isRecord(raw)) return null;
+  const clientId = stringOf(raw.clientId);
+  if (clientId === '') return null;
+  const clientSecret = stringOf(raw.clientSecret);
+  return { clientId, ...(clientSecret === '' ? {} : { clientSecret }) };
+}
+
+function readOAuth(raw: Record<string, unknown>): ConnectorAuth {
+  const accessToken = stringOf(raw.accessToken);
+  const clientId = stringOf(raw.clientId);
+  const tokenEndpoint = stringOf(raw.tokenEndpoint);
+  if (accessToken === '' || clientId === '' || tokenEndpoint === '')
+    return { kind: 'none' };
+  const refreshToken = stringOf(raw.refreshToken);
+  const clientSecret = stringOf(raw.clientSecret);
+  const scope = stringOf(raw.scope);
+  return {
+    kind: 'oauth',
+    accessToken,
+    clientId,
+    tokenEndpoint,
+    issuer: stringOf(raw.issuer),
+    ...(typeof raw.resource === 'string' ? { resource: raw.resource } : {}),
+    ...(typeof raw.tokenEndpointAuthMethod === 'string' ? { tokenEndpointAuthMethod: raw.tokenEndpointAuthMethod } : {}),
+    ...(refreshToken === '' ? {} : { refreshToken }),
+    ...(clientSecret === '' ? {} : { clientSecret }),
+    ...(scope === '' ? {} : { scope }),
+    ...(typeof raw.expiresAt === 'number' ? { expiresAt: raw.expiresAt } : {}),
+  };
+}
+
+function readAuth(raw: unknown): ConnectorAuth {
+  if (!isRecord(raw)) return { kind: 'none' };
+  if (raw.kind === 'oauth') return readOAuth(raw);
+  if (raw.kind !== 'header') return { kind: 'none' };
+  const name = stringOf(raw.name);
+  const value = stringOf(raw.value);
+  if (name === '' || value === '') return { kind: 'none' };
+  return { kind: 'header', name, value };
+}
+
+function readVerified(raw: unknown): VerifiedRecord {
+  const record = isRecord(raw) ? raw : {};
+  return { at: stringOf(record.at), server: stringOf(record.server) };
+}
+
+const TOOL_NAME_MAX = 128;
+const TOOL_GROUPS_MAX = 1000;
+
+function readToolGroups(raw: unknown): Record<string, ToolGroup> | undefined {
+  if (!isRecord(raw)) return undefined;
+  const kept = Object.entries(raw)
+    .filter((entry): entry is [string, ToolGroup] => entry[0].length <= TOOL_NAME_MAX && (entry[1] === 'read' || entry[1] === 'write'))
+    .slice(0, TOOL_GROUPS_MAX);
+  return kept.length > 0 ? Object.fromEntries(kept) : undefined;
+}
+
+export function readConfig(raw: unknown): ConnectorConfig {
+  const record = isRecord(raw) ? raw : {};
+  const auth = readAuth(record.auth);
+  const policy = parsePolicy(record.policy, 'connectors.json');
+  const toolGroups = readToolGroups(record.toolGroups);
+  return {
+    auth,
+    createdAt: stringOf(record.createdAt),
+    verified: readVerified(record.verified),
+    oauth: record.oauth === true || auth.kind === 'oauth',
+    client: readClient(record.client),
+    ...(policy === undefined || Object.keys(policy).length === 0 ? {} : { policy }),
+    ...(toolGroups === undefined ? {} : { toolGroups }),
+  };
+}
+
+export function signInState(config: ConnectorConfig): ConnectorSignIn {
+  if (config.auth.kind === 'oauth') return 'connected';
+  return config.oauth ? 'disconnected' : null;
+}
+
+export function stamp(server: VerifiedServer): VerifiedRecord {
+  return { at: new Date().toISOString(), server: server.server };
+}