@stage-labs/metro 0.1.0-beta.7 → 0.1.0-beta.71

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: (
+    subject: string,
+    project: string,
+    input: { name: unknown; url: unknown },
+  ) => Promise<Connector>;
+  reconnectConnector: (
+    subject: string,
+    id: string,
+    auth: OAuthAuth,
+  ) => Promise<Connector>;
+  getConnector: (subject: 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.subject, project, {
+    name: bodyField(body, 'name'),
+    url: bodyField(body, 'url'),
+  });
+  const authorize = await beginOAuth({
+    subject: session.subject,
+    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.subject, id);
+  const url = parseConnectorUrl(row.url);
+  const body = await readJsonBody(req);
+  const authorize = await beginOAuth({
+    subject: session.subject,
+    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.subject, 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 './return-to.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 = 300_000;
+
+const CALLBACK_PATH = '/api/connectors/callback';
+
+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;
+  subject: 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({
+    subject: input.subject,
+    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 }
+      : {}),
+  };
+}

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

@@ -0,0 +1,98 @@
+import { isRecord } from './is-record.js';
+
+export const TOOL_KINDS = ['read', 'write'] as const;
+
+export type ToolKind = (typeof TOOL_KINDS)[number];
+
+export interface ToolInfo {
+  name: string;
+  title: string;
+  description: string;
+  kind: ToolKind;
+  annotated: boolean;
+  destructive: boolean;
+  idempotent: boolean;
+  openWorld: boolean;
+}
+
+const MAX_TOOLS = 500;
+const MAX_DESCRIPTION = 400;
+
+const str = (value: unknown, cap: number): string =>
+  typeof value === 'string' ? value.slice(0, cap) : '';
+
+const flag = (value: unknown, fallback: boolean): boolean =>
+  typeof value === 'boolean' ? value : fallback;
+
+export function classifyTool(annotations: unknown): ToolKind {
+  return isRecord(annotations) && annotations.readOnlyHint === true
+    ? 'read'
+    : 'write';
+}
+
+export function isDestructive(annotations: unknown): boolean {
+  if (!isRecord(annotations)) return true;
+  if (annotations.readOnlyHint === true) return false;
+  return annotations.destructiveHint !== false;
+}
+
+export function toToolInfo(raw: unknown): ToolInfo | null {
+  if (!isRecord(raw)) return null;
+  const name = str(raw.name, 200);
+  if (name === '') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : undefined;
+  return {
+    name,
+    title: str(annotations?.title ?? raw.title, 200),
+    description: str(raw.description, MAX_DESCRIPTION),
+    kind: classifyTool(raw.annotations),
+    annotated: annotations !== undefined,
+    destructive: isDestructive(raw.annotations),
+    idempotent: flag(annotations?.idempotentHint, false),
+    openWorld: flag(annotations?.openWorldHint, true),
+  };
+}
+
+export function toToolList(raw: unknown): ToolInfo[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ToolInfo[] = [];
+  for (const entry of raw) {
+    if (out.length >= MAX_TOOLS) break;
+    const tool = toToolInfo(entry);
+    if (tool !== null) out.push(tool);
+  }
+  return out;
+}
+
+function toStoredTool(raw: unknown): ToolInfo | null {
+  if (!isRecord(raw)) return null;
+  const name = str(raw.name, 200);
+  if (name === '') return null;
+  return {
+    name,
+    title: str(raw.title, 200),
+    description: str(raw.description, MAX_DESCRIPTION),
+    kind: raw.kind === 'read' ? 'read' : 'write',
+    annotated: raw.annotated === true,
+    destructive: raw.destructive !== false,
+    idempotent: raw.idempotent === true,
+    openWorld: raw.openWorld !== false,
+  };
+}
+
+export function readStoredTools(raw: unknown): ToolInfo[] {
+  if (!Array.isArray(raw)) return [];
+  const out: ToolInfo[] = [];
+  for (const entry of raw) {
+    if (out.length >= MAX_TOOLS) break;
+    const tool = toStoredTool(entry);
+    if (tool !== null) out.push(tool);
+  }
+  return out;
+}
+
+export function countByKind(tools: ToolInfo[]): Record<ToolKind, number> {
+  const counts: Record<ToolKind, number> = { read: 0, write: 0 };
+  for (const tool of tools) counts[tool.kind] += 1;
+  return counts;
+}

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

@@ -0,0 +1,70 @@
+import { ApiError } from './api-error.js';
+
+export class ConnectorVerifyError extends ApiError {}
+
+export class ConnectorUnauthorized extends ConnectorVerifyError {}
+
+export class ConnectorNotMcp extends ConnectorVerifyError {}
+
+export const POLICY_MESSAGE =
+  'Metro connects from its own server, so it cannot reach a URL on your machine. localhost and private addresses are not usable as connectors.';
+
+let localAllowed = false;
+
+export function allowLocalConnectors(on: boolean): void {
+  localAllowed = on;
+}
+
+const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
+const PRIVATE_SUFFIX = /(?:^|\.)(?:localhost|local|internal|flycast)$/;
+
+export function refused(message: string): ConnectorVerifyError {
+  return new ConnectorVerifyError(message, 400);
+}
+
+function hostAllowed(host: string): boolean {
+  if (host === '' || host.startsWith('[')) return false;
+  if (IPV4.test(host) || !host.includes('.')) return false;
+  return !PRIVATE_SUFFIX.test(host);
+}
+
+function schemeAllowed(url: URL): boolean {
+  return url.protocol === 'https:' || (localAllowed && url.protocol === 'http:');
+}
+
+function refuseShape(url: URL): void {
+  if (!schemeAllowed(url)) throw refused('a connector url must start with https://');
+  if (url.username !== '' || url.password !== '')
+    throw refused('a connector url must not carry a user:password');
+  if (url.hash !== '')
+    throw refused('a connector url must not carry a #fragment');
+  if (!localAllowed && !hostAllowed(url.hostname.toLowerCase())) throw refused(POLICY_MESSAGE);
+}
+
+export function parseConnectorUrl(raw: unknown): URL {
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (text === '') throw refused('a connector url is required');
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    throw refused('that is not a valid url');
+  }
+  refuseShape(url);
+  return url;
+}
+
+export function connectorUrlText(url: URL): string {
+  const text = url.toString();
+  if (url.pathname !== '/' || url.search !== '') return text;
+  return text.endsWith('/') ? text.slice(0, -1) : text;
+}
+
+export function safeIconSrc(raw: unknown): string {
+  if (typeof raw !== 'string' || raw === '') return '';
+  try {
+    return new URL(raw).protocol === 'https:' ? raw.slice(0, 500) : '';
+  } catch {
+    return '';
+  }
+}