@stage-labs/metro 0.1.0-beta.13 → 0.1.0-beta.131

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

@@ -0,0 +1,310 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import {
+  apiFailure,
+  apiSession,
+  projectParam,
+  bodyField,
+  cors,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} 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 './model.js';
+
+const PREFIX = '/api/connectors';
+
+const asText = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+export interface ConnectorApiDeps extends OAuthRouteDeps {
+  listConnectors: (subject: string, project: string) => Promise<Connector[]>;
+  createConnector: (
+    subject: string,
+    project: string,
+    input: ConnectorInput,
+  ) => Promise<Connector>;
+  verifyConnector: (subject: string, id: string) => Promise<ConnectorCheck>;
+  disconnectConnector: (subject: string, id: string) => Promise<Connector>;
+  renameConnector: (
+    subject: string,
+    id: string,
+    name: string,
+  ) => Promise<Connector>;
+  deleteConnector: (subject: string, id: string) => Promise<DeletedConnector>;
+}
+
+type Routable =
+  | { kind: 'collection' }
+  | { kind: 'callback' }
+  | { kind: 'connector'; id: string }
+  | { kind: 'verify'; id: string }
+  | { kind: 'connect'; id: string }
+  | { kind: 'disconnect'; id: string }
+  | { kind: 'rename'; 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 === 'connect') return { kind: 'connect', id };
+  if (head === 'disconnect') return { kind: 'disconnect', id };
+  if (head === 'rename') return { kind: 'rename', 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,
+  detail = false,
+): Record<string, unknown> {
+  const { catalog, ...summary } = row.verified;
+  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,
+  };
+}
+
+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.subject, project);
+  sendJson(req, res, 200, {
+    connectors: rows.map((row) => connectorPayload(row)),
+  });
+}
+
+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() !== '';
+  try {
+    const created = await deps.createConnector(session.subject, project, {
+      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, session, project, body, (row) =>
+      connectorPayload(row),
+    );
+  }
+}
+
+async function handleVerify(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const check = await deps.verifyConnector(session.subject, 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,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const row = await deps.disconnectConnector(session.subject, 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,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const gone = await deps.deleteConnector(session.subject, 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,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  if (req.method !== 'GET') {
+    await handleDelete(req, res, deps, session, id);
+    return;
+  }
+  const row = await deps.getConnector(session.subject, id);
+  sendJson(req, res, 200, connectorPayload(row, true));
+}
+
+async function handleRename(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  session: ApiSession,
+  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(session.subject, id, name);
+  log.info({ id: row.id, name: row.name }, 'connector-api: renamed connector');
+  sendJson(req, res, 200, connectorPayload(row));
+}
+
+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);
+  } catch (err) {
+    apiFailure(req, res, err, 'connector-api');
+  }
+}
+
+const ALLOWED: Record<Routable['kind'], string[]> = {
+  collection: ['GET', 'POST'],
+  callback: ['GET'],
+  connector: ['GET', 'DELETE'],
+  verify: ['POST'],
+  connect: ['POST'],
+  disconnect: ['POST'],
+  rename: ['POST'],
+};
+
+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, session, 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) => {
+    log.warn({ err: errMsg(err) }, 'connector-api: unhandled error');
+    if (!res.headersSent)
+      sendJson(req, res, 500, { error: 'connector api failed' });
+  });
+  return true;
+}

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

@@ -0,0 +1,63 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { cors, sendJson, type AgentIdentity } from '@metro-labs/http/api-http';
+import { loopbackBase } from '../files/attach-serve.js';
+import { relayServersJson, type RelayServerEntry } from './json.js';
+import { agentIdForKey } from '../agents/keys.js';
+
+const PATH = '/api/cli/mcp';
+
+export interface LocalCliDeps {
+  agentName: (agentId: string) => string | null;
+  connectorEntries: (agentId: string) => Promise<RelayServerEntry[]>;
+}
+
+function keyOf(req: IncomingMessage): string {
+  const header = req.headers.authorization ?? '';
+  if (header.toLowerCase().startsWith('bearer ')) return header.slice(7).trim();
+  const query = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+  return query.get('token')?.trim() ?? '';
+}
+
+export function keyIdentity(req: IncomingMessage): AgentIdentity | null {
+  const key = keyOf(req);
+  const agentId = key === '' ? undefined : agentIdForKey(key);
+  return agentId === undefined ? null : { subject: 'agent-key', agentId };
+}
+
+export function handleLocalCliRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: LocalCliDeps,
+): boolean {
+  const path = (req.url ?? '').split('?')[0] ?? '';
+  if (path !== PATH && !path.startsWith('/api/cli/')) return false;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (path !== PATH) {
+    sendJson(req, res, 404, { error: 'not on a local daemon' });
+    return true;
+  }
+  if (req.method !== 'GET') {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  const who = keyIdentity(req);
+  if (who === null) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return true;
+  }
+  deps
+    .connectorEntries(who.agentId)
+    .then((entries) => {
+      const agent = deps.agentName(who.agentId) ?? '';
+      sendJson(req, res, 200, { json: relayServersJson(entries, loopbackBase(), keyOf(req)), agent });
+    })
+    .catch((err: unknown) => {
+      log.warn({ err: errMsg(err) }, 'local cli: request failed');
+      if (!res.headersSent) sendJson(req, res, 500, { error: 'cli failed' });
+    });
+  return true;
+}

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

@@ -0,0 +1,175 @@
+import { ApiError } from '@metro-labs/http/api-error';
+import type {
+  ConnectorAuth,
+  VerifiedRecord,
+  VerifiedServer,
+} from './verify.js';
+import { readStoredTools } from './tools.js';
+import type { OAuthClient } from './oauth-client.js';
+import { isRecord } from '@metro-labs/core/is-record';
+
+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;
+}
+
+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 : {};
+  const catalog = readStoredTools(record.catalog);
+  return {
+    at: text(record.at),
+    server: text(record.server),
+    version: text(record.version),
+    protocol: text(record.protocol),
+    icon: text(record.icon),
+    tools: typeof record.tools === 'number' ? record.tools : 0,
+    catalog,
+  };
+}
+
+export function readConfig(raw: unknown): ConnectorConfig {
+  const record = isRecord(raw) ? raw : {};
+  const auth = readAuth(record.auth);
+  return {
+    auth,
+    createdAt: text(record.createdAt),
+    verified: readVerified(record.verified),
+    oauth: record.oauth === true || auth.kind === 'oauth',
+    client: readClient(record.client),
+  };
+}
+
+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,
+    version: server.version,
+    protocol: server.protocol,
+    icon: server.icon,
+    tools: server.tools,
+    catalog: server.catalog,
+  };
+}

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

@@ -0,0 +1,21 @@
+export interface RelayServerEntry {
+  id: string;
+  name: string;
+}
+
+export const NAME_PREFIX = 'metro.box ';
+
+export function relayServersJson(
+  entries: RelayServerEntry[],
+  base: string,
+  cliToken: string,
+): string {
+  const mcpServers: Record<string, unknown> = {};
+  for (const entry of entries)
+    mcpServers[`${NAME_PREFIX}${entry.name}`] = {
+      type: 'http',
+      url: `${base}/relay/${entry.id}`,
+      headers: { Authorization: `Bearer ${cliToken}` },
+    };
+  return JSON.stringify({ mcpServers }, null, 2);
+}

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

@@ -0,0 +1,77 @@
+import type { ConnectorAuth, VerifiedRecord } from './verify.js';
+import type { OAuthClient } from './oauth-client.js';
+import { readConfig, signInState, type ConnectorSignIn } from './config.js';
+import type { ConnectorTransport } from '@metro-labs/core/station-names';
+
+export interface Connector {
+  id: string;
+  name: string;
+  url: string;
+  transport: ConnectorTransport;
+  auth: ConnectorAuth['kind'];
+  header: string | null;
+  secret: string | null;
+  bearer: string | null;
+  expiresAt: number | null;
+  signIn: ConnectorSignIn;
+  verified: VerifiedRecord;
+  client: OAuthClient | null;
+}
+
+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;
+}
+
+export interface ConnectorLike {
+  id: string;
+  name: string;
+  url: string;
+  transport: ConnectorTransport;
+  config: unknown;
+}
+
+export function connectorFromRow(row: ConnectorLike): Connector {
+  const config = readConfig(row.config);
+  const auth = config.auth;
+  return {
+    id: row.id,
+    name: row.name,
+    url: row.url,
+    transport: row.transport,
+    auth: auth.kind,
+    header: auth.kind === 'header' ? auth.name : null,
+    secret: auth.kind === 'header' ? auth.value : null,
+    bearer: auth.kind === 'oauth' ? auth.accessToken : null,
+    expiresAt: auth.kind === 'oauth' ? (auth.expiresAt ?? null) : null,
+    signIn: signInState(config),
+    verified: config.verified,
+    client: config.client,
+  };
+}
+
+export const UNVERIFIED = {
+  at: '',
+  server: '',
+  version: '',
+  protocol: '',
+  icon: '',
+  tools: 0,
+  catalog: [],
+};