@stage-labs/metro 0.1.0-beta.2 → 0.1.0-beta.200

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

@@ -0,0 +1,306 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { log } from '@metro-labs/core/log';
+import { healthOf } from './health.js';
+import type { RemoteTool } from './tools.js';
+import { normalizePolicy, type ToolPolicy } from '../policy/policy.js';
+import {
+  apiFailure,
+  apiSession,
+  bodyField,
+  cors,
+  readJsonBody,
+  sendJson,
+} from '@metro-labs/http/api-http';
+import { parseId } from '@metro-labs/core/ids';
+import {
+  handleCallback,
+  handleConnect,
+  hostOf,
+  startOAuth,
+  type OAuthRouteDeps,
+} from './oauth-routes.js';
+import { ConnectorUnauthorized } from './verify.js';
+import type {
+  Connector,
+  ConnectorCheck,
+  ConnectorInput,
+  DeletedConnector,
+} from './store.js';
+
+const PREFIX = '/api/connectors';
+
+const asText = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+export interface ConnectorApiDeps extends OAuthRouteDeps {
+  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: '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: 'policy'; id: string };
+
+type Target = Routable | { kind: 'unknown' } | null;
+
+function subTarget(id: string, rest: string[]): Target {
+  if (rest.length === 0) return { kind: 'connector', id };
+  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' };
+}
+
+function target(path: string): Target {
+  if (path === PREFIX || path === `${PREFIX}/`) return { kind: 'collection' };
+  if (!path.startsWith(`${PREFIX}/`)) return null;
+  const segments = path.slice(PREFIX.length + 1).split('/').filter(Boolean);
+  const head = segments[0];
+  if (head === undefined) return { kind: 'collection' };
+  if (head === 'callback' && segments.length === 1) return { kind: 'callback' };
+  const id = parseId(head);
+  return id === null ? { kind: 'unknown' } : subTarget(id, segments.slice(1));
+}
+
+function connectorPayload(row: Connector): Record<string, unknown> {
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    auth: row.auth,
+    header: row.header,
+    clientId: row.client?.clientId ?? null,
+    signIn: row.signIn,
+    verified: row.verified,
+    policy: row.policy,
+    health: healthOf(row.id),
+  };
+}
+
+async function handleList(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+): Promise<void> {
+  const rows = await deps.listConnectors();
+  sendJson(req, res, 200, {
+    connectors: rows.map((row) => connectorPayload(row)),
+  });
+}
+
+async function handleCreate(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+): Promise<void> {
+  const body = await readJsonBody(req);
+  const offered = asText(bodyField(body, 'value')).trim() !== '';
+  try {
+    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) },
+      'connector-api: created connector',
+    );
+    sendJson(req, res, 201, connectorPayload(created));
+  } catch (err) {
+    if (offered || !(err instanceof ConnectorUnauthorized)) throw err;
+    await startOAuth(req, res, deps, body, (row) =>
+      connectorPayload(row),
+    );
+  }
+}
+
+async function handleVerify(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  id: string,
+): Promise<void> {
+  const check = await deps.verifyConnector(id);
+  log.info(
+    { id: check.id, name: check.name, ok: check.ok },
+    'connector-api: re-verified connector',
+  );
+  sendJson(req, res, 200, check);
+}
+
+async function handleDisconnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  id: string,
+): Promise<void> {
+  const row = await deps.disconnectConnector(id);
+  log.info(
+    { id: row.id, name: row.name },
+    'connector-api: signed the connector out',
+  );
+  sendJson(req, res, 200, connectorPayload(row));
+}
+
+async function handleDelete(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  id: string,
+): Promise<void> {
+  const gone = await deps.deleteConnector(id);
+  log.info(
+    { id: gone.id, name: gone.name },
+    'connector-api: deleted connector',
+  );
+  sendJson(req, res, 200, { id: gone.id, name: gone.name, deleted: true });
+}
+
+async function handleConnector(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  id: string,
+): Promise<void> {
+  if (req.method !== 'GET') {
+    await handleDelete(req, res, deps, id);
+    return;
+  }
+  const row = await deps.getConnector(id);
+  sendJson(req, res, 200, connectorPayload(row));
+}
+
+async function handleRename(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  id: string,
+): Promise<void> {
+  const name = bodyField(await readJsonBody(req), 'name');
+  if (typeof name !== 'string') {
+    sendJson(req, res, 400, { error: 'name is required' });
+    return;
+  }
+  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'>;
+
+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,
+  tgt: Routable,
+): Promise<void> {
+  try {
+    if (tgt.kind === 'callback') 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');
+  }
+}
+
+const ALLOWED: Record<Routable['kind'], string[]> = {
+  collection: ['GET', 'POST'],
+  callback: ['GET'],
+  connector: ['GET', 'DELETE'],
+  verify: ['POST'],
+  tools: ['GET'],
+  connect: ['POST'],
+  disconnect: ['POST'],
+  rename: ['POST'],
+  policy: ['PUT'],
+};
+
+async function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  tgt: Routable,
+): Promise<void> {
+  if (tgt.kind === 'callback') {
+    handleCallback(req, res, deps);
+    return;
+  }
+  const session = await apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return;
+  }
+  await route(req, res, deps, tgt);
+}
+
+export function handleConnectorApiRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+): boolean {
+  const tgt = target((req.url ?? '').split('?')[0] ?? '');
+  if (tgt === null) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (tgt.kind === 'unknown') {
+    sendJson(req, res, 404, { error: 'no such connector' });
+    return true;
+  }
+  if (!ALLOWED[tgt.kind].includes(req.method ?? '')) {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  dispatch(req, res, deps, tgt).catch((err: unknown) => {
+    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,176 @@
+import { ApiError } from '@metro-labs/http/api-error';
+import type {
+  ConnectorAuth,
+  VerifiedRecord,
+  VerifiedServer,
+} from './verify.js';
+import type { OAuthClient } from './oauth-client.js';
+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';
+
+const CONNECTOR_NAME_MAX = 64;
+const HEADER_NAME_RE = /^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/;
+const HEADER_VALUE_RE = /^[\x20-\x7e]{1,4096}$/;
+const CLIENT_ID_RE = /^[\x21-\x7e]{1,256}$/;
+const CLIENT_SECRET_RE = /^[\x21-\x7e]{1,1024}$/;
+const DEFAULT_HEADER = 'Authorization';
+
+export class ConnectorError extends ApiError {}
+
+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 text(value: unknown): string {
+  return typeof value === 'string' ? value : '';
+}
+
+function hasControlChar(value: string): boolean {
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+export function connectorName(raw: unknown): string {
+  const name = typeof raw === 'string' ? raw.trim() : '';
+  if (name === '') throw new ConnectorError('a connector needs a name', 400);
+  if (name.length > CONNECTOR_NAME_MAX)
+    throw new ConnectorError(
+      `a connector name must be ${String(CONNECTOR_NAME_MAX)} characters or fewer`,
+      400,
+    );
+  if (hasControlChar(name))
+    throw new ConnectorError(
+      'a connector name must not contain control characters',
+      400,
+    );
+  return name;
+}
+
+export function connectorAuth(
+  rawHeader: unknown,
+  rawValue: unknown,
+): ConnectorAuth {
+  const header = text(rawHeader).trim();
+  const value = text(rawValue).trim();
+  if (header === '' && value === '') return { kind: 'none' };
+  if (value === '')
+    throw new ConnectorError(
+      'that header has no value — give both a header name and its value, or neither',
+      400,
+    );
+  const name = header === '' ? DEFAULT_HEADER : header;
+  if (!HEADER_NAME_RE.test(name))
+    throw new ConnectorError('that is not a valid HTTP header name', 400);
+  if (!HEADER_VALUE_RE.test(value))
+    throw new ConnectorError('that header value is not sendable', 400);
+  return { kind: 'header', name, value };
+}
+
+export function connectorClient(
+  rawId: unknown,
+  rawSecret: unknown,
+): OAuthClient | null {
+  const clientId = text(rawId).trim();
+  const clientSecret = text(rawSecret).trim();
+  if (clientId === '' && clientSecret === '') return null;
+  if (clientId === '')
+    throw new ConnectorError('a client secret needs the client ID it belongs to', 400);
+  if (!CLIENT_ID_RE.test(clientId))
+    throw new ConnectorError('that is not a client ID Metro can send', 400);
+  if (clientSecret !== '' && !CLIENT_SECRET_RE.test(clientSecret))
+    throw new ConnectorError('that client secret is not sendable', 400);
+  return { clientId, ...(clientSecret === '' ? {} : { clientSecret }) };
+}
+
+function readClient(raw: unknown): OAuthClient | null {
+  if (!isRecord(raw)) return null;
+  const clientId = text(raw.clientId);
+  if (clientId === '') return null;
+  const clientSecret = text(raw.clientSecret);
+  return { clientId, ...(clientSecret === '' ? {} : { clientSecret }) };
+}
+
+function readOAuth(raw: Record<string, unknown>): ConnectorAuth {
+  const accessToken = text(raw.accessToken);
+  const clientId = text(raw.clientId);
+  const tokenEndpoint = text(raw.tokenEndpoint);
+  if (accessToken === '' || clientId === '' || tokenEndpoint === '')
+    return { kind: 'none' };
+  const refreshToken = text(raw.refreshToken);
+  const clientSecret = text(raw.clientSecret);
+  const scope = text(raw.scope);
+  return {
+    kind: 'oauth',
+    accessToken,
+    clientId,
+    tokenEndpoint,
+    issuer: text(raw.issuer),
+    ...(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 = text(raw.name);
+  const value = text(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: text(record.at), server: text(record.server) };
+}
+
+const TOOL_NAME_MAX = 128;
+const TOOL_GROUPS_MAX = 1000;
+
+export 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: text(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 };
+}

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

@@ -0,0 +1,72 @@
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { policyFor, setPolicies, type PolicyTarget, type ToolPolicy } from '../policy/policy.js';
+import { serverKeysOf } from './plugin-sync.js';
+import { takeGrant } from '../approvals/pending.js';
+import { NEEDS_APPROVAL } from '../approvals/needs.js';
+
+interface GateRow {
+  id: string;
+  name: string;
+  config: { policy?: ToolPolicy; toolGroups?: Record<string, ToolGroup> };
+}
+
+export interface ConnectorGate {
+  id: string;
+  name: string;
+  server: string;
+  policy: ToolPolicy;
+  tools: Record<string, ToolGroup>;
+}
+
+let gates: ConnectorGate[] = [];
+
+const normalized = (name: string): string => name.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+export function registerConnectors(rows: readonly GateRow[]): void {
+  const keys = serverKeysOf([...rows]);
+  gates = rows.map((row) => ({
+    id: row.id,
+    name: row.name,
+    server: keys.get(row.id) ?? '',
+    policy: row.config.policy ?? {},
+    tools: row.config.toolGroups ?? {},
+  }));
+  const entries = rows.flatMap((row): [PolicyTarget, ToolPolicy][] =>
+    row.config.policy === undefined ? [] : [[{ kind: 'connector', id: row.id }, row.config.policy]],
+  );
+  setPolicies('connector', entries);
+}
+
+export const connectorGates = (): readonly ConnectorGate[] => gates;
+
+export const toolGroupOf = (gate: ConnectorGate, tool: string): ToolGroup => (gate.tools[tool] === 'read' ? 'read' : 'write');
+
+const promptFor = (connectorId: string, tool: string) => (asked: string): boolean => {
+  const found = connectorToolOf(asked);
+  return found?.gate.id === connectorId && found.tool === tool;
+};
+
+export function blockedReason(connectorId: string, tool: string, args: Record<string, unknown> = {}): string | null {
+  const gate = gates.find((g) => g.id === connectorId);
+  if (gate === undefined) return null;
+  const access = policyFor({ kind: 'connector', id: connectorId }, { name: tool, group: toolGroupOf(gate, tool) });
+  if (access === 'deny') return `Blocked by the owner's policy for ${gate.name} (${tool}).`;
+  if (access === 'allow' || takeGrant(promptFor(connectorId, tool), args)) return null;
+  return NEEDS_APPROVAL(gate.name, tool);
+}
+
+function prefixesOf(gate: ConnectorGate): string[] {
+  return [`mcp__plugin_metro_${gate.server}__`, `mcp__${gate.server}__`, `mcp__${normalized(`metro.box ${gate.name}`)}__`];
+}
+
+export function connectorToolOf(toolName: string): { gate: ConnectorGate; tool: string } | undefined {
+  if (toolName.startsWith('mcp__metro__')) return undefined;
+  for (const gate of gates)
+    for (const prefix of prefixesOf(gate))
+      if (toolName.startsWith(prefix) && toolName.length > prefix.length) {
+        const called = toolName.slice(prefix.length);
+        const known = [...Object.keys(gate.tools), ...Object.keys(gate.policy.tools ?? {})];
+        return { gate, tool: known.find((name) => name === called) ?? known.find((name) => normalized(name) === called) ?? called };
+      }
+  return undefined;
+}

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

@@ -0,0 +1,18 @@
+export interface ConnectorHealth {
+  ok: boolean;
+  reason: string | null;
+  at: string;
+}
+
+const seen = new Map<string, ConnectorHealth>();
+
+export function noteHealth(id: string, ok: boolean, reason: string | null = null): void {
+  seen.set(id, { ok, reason: ok ? null : reason, at: new Date().toISOString() });
+}
+
+export const healthOf = (id: string): ConnectorHealth | null => seen.get(id) ?? null;
+
+export function forgetHealth(id?: string): void {
+  if (id === undefined) seen.clear();
+  else seen.delete(id);
+}