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

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

@@ -0,0 +1,338 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from './log.js';
+import {
+  apiFailure,
+  apiSession,
+  projectParam,
+  bodyField,
+  cors,
+  readJsonBody,
+  sendJson,
+  type ApiSession,
+} from './api-http.js';
+import { parseId } from '../db/ids.js';
+import type { ConnectorCollectionRow } from '../db/connector-collections.js';
+import {
+  handleCallback,
+  handleConnect,
+  hostOf,
+  startOAuth,
+  type OAuthRouteDeps,
+} from './connector-oauth-routes.js';
+import { ConnectorUnauthorized } from './connector-verify.js';
+import type {
+  Connector,
+  ConnectorCheck,
+  ConnectorInput,
+  DeletedConnector,
+} from '../db/connectors.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[]>;
+  freshConnectorsByIds: (ids: string[]) => Promise<Connector[]>;
+  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>;
+}
+
+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,
+    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.email, 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.email, project, {
+      name: bodyField(body, 'name'),
+      url: bodyField(body, 'url'),
+      header: bodyField(body, 'header'),
+      value: bodyField(body, 'value'),
+    });
+    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.email, 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.email, 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.email, 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.email, 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.email, 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'],
+};
+
+function dispatch(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: ConnectorApiDeps,
+  tgt: Routable,
+): Promise<void> {
+  if (tgt.kind === 'callback') {
+    handleCallback(req, res, deps);
+    return Promise.resolve();
+  }
+  const session = apiSession(req);
+  if (!session) {
+    sendJson(req, res, 401, { error: 'unauthorized' });
+    return Promise.resolve();
+  }
+  return 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/mcp/src/daemon/connector-json.ts

@@ -0,0 +1,31 @@
+import type { ConnectorTransport } from '../db/schema.js';
+
+export interface ConnectorEntry {
+  name: string;
+  url: string;
+  transport: ConnectorTransport;
+  header: string | null;
+  secret: string | null;
+  bearer: string | null;
+}
+
+function headersOf(entry: ConnectorEntry): Record<string, string> | null {
+  const { header, secret, bearer } = entry;
+  if (typeof header === 'string' && typeof secret === 'string')
+    return { [header]: secret };
+  if (typeof bearer === 'string' && bearer !== '')
+    return { Authorization: `Bearer ${bearer}` };
+  return null;
+}
+
+function serverOf(entry: ConnectorEntry): Record<string, unknown> {
+  const base = { type: entry.transport, url: entry.url };
+  const headers = headersOf(entry);
+  return headers === null ? base : { ...base, headers };
+}
+
+export function mcpServersJson(entries: ConnectorEntry[]): string {
+  const mcpServers: Record<string, unknown> = {};
+  for (const entry of entries) mcpServers[entry.name] = serverOf(entry);
+  return JSON.stringify({ mcpServers }, null, 2);
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/connector-oauth-routes.ts

@@ -0,0 +1,157 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from './log.js';
+import { bodyField, readJsonBody, sendJson, type ApiSession } from './api-http.js';
+import {
+  beginOAuth,
+  completeOAuth,
+  takePending,
+  type PendingAuth,
+} from './connector-oauth.js';
+import { parseConnectorUrl } from './connector-verify.js';
+import type { OAuthAuth } from './connector-verify.js';
+import type { Connector } from '../db/connectors.js';
+
+const asText = (value: unknown): string =>
+  typeof value === 'string' ? value : '';
+
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return '';
+  }
+}
+
+export interface OAuthRouteDeps {
+  createPendingConnector: (
+    email: string,
+    project: string,
+    input: { name: unknown; url: unknown },
+  ) => Promise<Connector>;
+  reconnectConnector: (
+    email: string,
+    id: string,
+    auth: OAuthAuth,
+  ) => Promise<Connector>;
+  getConnector: (email: string, id: string) => Promise<Connector>;
+}
+
+export async function startOAuth(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  session: ApiSession,
+  project: string,
+  body: unknown,
+  payload: (row: Connector) => Record<string, unknown>,
+): Promise<void> {
+  const url = parseConnectorUrl(bodyField(body, 'url'));
+  const row = await deps.createPendingConnector(session.email, project, {
+    name: bodyField(body, 'name'),
+    url: bodyField(body, 'url'),
+  });
+  const authorize = await beginOAuth({
+    email: session.email,
+    name: row.name,
+    url,
+    returnTo: asText(bodyField(body, 'returnTo')),
+    connectorId: row.id,
+  });
+  log.info(
+    { id: row.id, host: url.hostname },
+    'connector-api: stored unconnected, sending the user to sign in',
+  );
+  sendJson(req, res, 201, { ...payload(row), authorizeUrl: authorize });
+}
+
+export async function handleConnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  session: ApiSession,
+  id: string,
+): Promise<void> {
+  const row = await deps.getConnector(session.email, id);
+  const url = parseConnectorUrl(row.url);
+  const body = await readJsonBody(req);
+  const authorize = await beginOAuth({
+    email: session.email,
+    name: row.name,
+    url,
+    returnTo: asText(bodyField(body, 'returnTo')),
+    connectorId: row.id,
+  });
+  log.info(
+    { id: row.id, host: url.hostname },
+    'connector-api: sending the user back to sign in',
+  );
+  sendJson(req, res, 202, { status: 'oauth', authorizeUrl: authorize });
+}
+
+function landing(entry: PendingAuth, id?: string): string {
+  const target = id ?? entry.connectorId;
+  return target === undefined ? '#/connectors' : `#/connector/${target}`;
+}
+
+function backTo(entry: PendingAuth, error?: string, id?: string): string {
+  const suffix =
+    error === undefined
+      ? ''
+      : `?connector_error=${encodeURIComponent(error)}`;
+  return `${entry.returnTo}${suffix}${landing(entry, id)}`;
+}
+
+function redirect(res: ServerResponse, location: string): void {
+  res.writeHead(302, { location, 'cache-control': 'no-store' }).end();
+}
+
+async function saveOAuth(
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  auth: OAuthAuth,
+): Promise<Connector> {
+  return deps.reconnectConnector(entry.email, entry.connectorId, auth);
+}
+
+async function settleCallback(
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  code: string,
+): Promise<void> {
+  try {
+    const auth = await completeOAuth(entry, code);
+    const saved = await saveOAuth(deps, entry, auth);
+    log.info(
+      { id: saved.id, name: saved.name, host: hostOf(saved.url) },
+      'connector-api: oauth sign-in completed',
+    );
+    redirect(res, backTo(entry, undefined, saved.id));
+  } catch (err) {
+    log.warn({ err: errMsg(err) }, 'connector-api: oauth sign-in failed');
+    redirect(res, backTo(entry, errMsg(err)));
+  }
+}
+
+export function handleCallback(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+): void {
+  const query = new URLSearchParams((req.url ?? '').split('?')[1] ?? '');
+  const entry = takePending(query.get('state') ?? '');
+  if (entry === undefined) {
+    sendJson(req, res, 400, { error: 'that sign-in has expired — start it again' });
+    return;
+  }
+  const denied = query.get('error');
+  const code = query.get('code') ?? '';
+  if (denied !== null || code === '') {
+    redirect(res, backTo(entry, denied ?? 'no authorization code came back'));
+    return;
+  }
+  settleCallback(res, deps, entry, code).catch((err: unknown) => {
+    log.warn({ err: errMsg(err) }, 'connector-api: oauth callback failed');
+    if (!res.headersSent) redirect(res, backTo(entry, 'sign-in failed'));
+  });
+}

package/runtime/node_modules/@metro-labs/mcp/src/daemon/connector-oauth.ts

@@ -0,0 +1,127 @@
+import { publicBaseOrDefault } from './attach-serve.js';
+import {
+  ConnectorVerifyError,
+  type OAuthAuth,
+  type OAuthTokens,
+} from './connector-verify.js';
+import { validateReturnTo } from './google-oauth.js';
+import {
+  authorizeUrl,
+  exchangeCode,
+  newVerifier,
+  refreshTokens,
+  registerClient,
+} from './oauth-client.js';
+import { discoverOAuth } from './oauth-discovery.js';
+import { startPending, takePending, type PendingAuth } from './oauth-pending.js';
+
+export { takePending, type PendingAuth };
+
+const REFRESH_SKEW_MS = 60_000;
+
+export const CALLBACK_PATH = '/api/connectors/callback';
+
+export const callbackUri = (): string =>
+  `${publicBaseOrDefault()}${CALLBACK_PATH}`;
+
+function refused(message: string): ConnectorVerifyError {
+  return new ConnectorVerifyError(message, 400);
+}
+
+const resourceOf = (url: URL): string => url.toString();
+
+export interface BeginInput {
+  connectorId: string;
+  email: string;
+  name: string;
+  url: URL;
+  returnTo: string;
+}
+
+export async function beginOAuth(input: BeginInput): Promise<string> {
+  if (!validateReturnTo(input.returnTo))
+    throw refused('that return address is not one Metro will send you back to');
+  const server = await discoverOAuth(input.url);
+  const redirectUri = callbackUri();
+  const client = await registerClient(server, redirectUri);
+  const verifier = newVerifier();
+  const resource = resourceOf(input.url);
+  const state = startPending({
+    email: input.email,
+    name: input.name,
+    url: input.url.toString(),
+    resource,
+    returnTo: input.returnTo,
+    verifier,
+    server,
+    client,
+    connectorId: input.connectorId,
+  });
+  return authorizeUrl({
+    server,
+    client,
+    redirectUri,
+    state,
+    verifier,
+    resource,
+  });
+}
+
+function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
+  return {
+    kind: 'oauth',
+    issuer: pendingAuth.server.issuer,
+    tokenEndpoint: pendingAuth.server.tokenEndpoint,
+    clientId: pendingAuth.client.clientId,
+    ...(pendingAuth.client.clientSecret === undefined
+      ? {}
+      : { clientSecret: pendingAuth.client.clientSecret }),
+    ...tokens,
+  };
+}
+
+export async function completeOAuth(
+  entry: PendingAuth,
+  code: string,
+): Promise<OAuthAuth> {
+  const tokens = await exchangeCode(entry.server, entry.client, {
+    code,
+    redirectUri: callbackUri(),
+    verifier: entry.verifier,
+    resource: entry.resource,
+  });
+  return authOf(entry, tokens);
+}
+
+export function oauthExpired(auth: OAuthAuth, now = Date.now()): boolean {
+  return auth.expiresAt !== undefined && auth.expiresAt - REFRESH_SKEW_MS <= now;
+}
+
+export async function refreshOAuth(
+  auth: OAuthAuth,
+  resource: string,
+): Promise<OAuthAuth> {
+  if (auth.refreshToken === undefined)
+    throw refused('that connector needs signing in again');
+  const server = {
+    issuer: auth.issuer,
+    authorizationEndpoint: '',
+    tokenEndpoint: auth.tokenEndpoint,
+    registrationEndpoint: null,
+    supportsS256: true,
+  };
+  const client = {
+    clientId: auth.clientId,
+    ...(auth.clientSecret === undefined
+      ? {}
+      : { clientSecret: auth.clientSecret }),
+  };
+  const tokens = await refreshTokens(server, client, auth.refreshToken, resource);
+  return {
+    ...auth,
+    ...tokens,
+    ...(tokens.refreshToken === undefined
+      ? { refreshToken: auth.refreshToken }
+      : {}),
+  };
+}