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

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

@@ -0,0 +1,178 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { errMsg, log } from '@metro-labs/core/log';
+import { bodyField, readJsonBody, sendJson, stringOf } from '@metro-labs/http/api-http';
+import {
+  beginOAuth,
+  completeOAuth,
+  prepareOAuth,
+  takePending,
+  type PendingAuth,
+} from './oauth.js';
+import { connectorClient, connectorName } from '@metro-labs/http/connector-input';
+import { parseConnectorUrl } from '@metro-labs/http/connector-url';
+import type { OAuthAuth } from '@metro-labs/http/connector-mcp';
+import type { Connector, PendingConnectorInput } from './store.js';
+import { agentsDir } from '../agents/files.js';
+import { withLocalMigrationOperation } from './migration-guard.js';
+import { migrationRecord } from './migration-state.js';
+import { ApiError } from '@metro-labs/http/api-error';
+
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname;
+  } catch {
+    return '';
+  }
+}
+
+export interface OAuthRouteDeps {
+  migrationDir?: string;
+  createPendingConnector: (input: PendingConnectorInput) => Promise<Connector>;
+  reconnectConnector: (id: string, auth: OAuthAuth) => Promise<Connector>;
+  getConnector: (id: string) => Promise<Connector>;
+}
+
+export async function startOAuth(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  body: unknown,
+  payload: (row: Connector) => Record<string, unknown>,
+): Promise<void> {
+  const name = connectorName(bodyField(body, 'name'));
+  await withLocalMigrationOperation('', deps.migrationDir ?? agentsDir(), async (operation) => {
+    const url = parseConnectorUrl(bodyField(body, 'url'));
+    const returnTo = stringOf(bodyField(body, 'returnTo'));
+    const clientId = bodyField(body, 'clientId');
+    const clientSecret = bodyField(body, 'clientSecret');
+    const prepared = await prepareOAuth({
+      url,
+      client: connectorClient(clientId, clientSecret),
+      returnTo,
+    }, operation.fetch);
+    const row = await deps.createPendingConnector({
+      name,
+      url: bodyField(body, 'url'),
+      clientId,
+      clientSecret,
+    });
+    operation.check();
+    const authorize = beginOAuth(prepared, {
+      name: row.name,
+      url,
+      returnTo,
+      connectorId: row.id,
+      migrationId: migrationRecord(row.id, deps.migrationDir)?.id ?? null,
+    });
+    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 });
+  }, true);
+}
+
+export async function handleConnect(
+  req: IncomingMessage,
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  id: string,
+): Promise<void> {
+  await withLocalMigrationOperation(id, deps.migrationDir ?? agentsDir(), async (operation) => {
+    const row = await deps.getConnector(id);
+    const url = parseConnectorUrl(row.url);
+    const body = await readJsonBody(req);
+    const returnTo = stringOf(bodyField(body, 'returnTo'));
+    const prepared = await prepareOAuth({ url, client: row.client, returnTo }, operation.fetch);
+    operation.check();
+    const authorize = beginOAuth(prepared, {
+      name: row.name,
+      url,
+      returnTo,
+      connectorId: row.id,
+      migrationId: migrationRecord(row.id, deps.migrationDir)?.id ?? null,
+    });
+    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 });
+  }, true);
+}
+
+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.connectorId, auth);
+}
+
+function checkGeneration(entry: PendingAuth, dir: string | undefined): void {
+  if ((entry.migrationId ?? null) !== (migrationRecord(entry.connectorId, dir)?.id ?? null)) throw new ApiError('This sign-in predates the connector migration. Start a fresh sign-in.', 409);
+}
+
+async function settleCallback(
+  res: ServerResponse,
+  deps: OAuthRouteDeps,
+  entry: PendingAuth,
+  code: string,
+): Promise<void> {
+  try {
+    const saved = await withLocalMigrationOperation(entry.connectorId, deps.migrationDir ?? agentsDir(), async (operation) => {
+      checkGeneration(entry, deps.migrationDir);
+      const auth = await completeOAuth(entry, code, operation.fetch);
+      operation.check();
+      checkGeneration(entry, deps.migrationDir);
+      return saveOAuth(deps, entry, auth);
+    }, true);
+    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 → daemon/src/connectors/oauth.ts}

@@ -1,53 +1,82 @@
-import { publicBaseOrDefault } from './attach-serve.js';
-import {
-  ConnectorVerifyError,
-  type OAuthAuth,
-  type OAuthTokens,
-} from './connector-verify.js';
-import { validateReturnTo } from './google-oauth.js';
+import { publicBaseOrDefault } from '../files/attach-serve.js';
+import { refused } from '@metro-labs/http/connector-url';
+import type { OAuthAuth, OAuthTokens } from '@metro-labs/http/connector-mcp';
+import { validateReturnTo } from '@metro-labs/http/return-to';
 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';
+  type OAuthClient,
+} from '@metro-labs/http/connector-oauth';
+import { discoverOAuth, type OAuthServer } from '@metro-labs/http/connector-discovery';
+import { ticketStore } from '@metro-labs/core/tickets';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+
+export interface PendingAuth {
+  name: string;
+  url: string;
+  resource: string;
+  returnTo: string;
+  verifier: string;
+  server: OAuthServer;
+  client: OAuthClient;
+  connectorId: string;
+  migrationId?: string | null;
+}
+
+const pending = ticketStore<PendingAuth>(10 * 60_000, 100);
 
-export { takePending, type PendingAuth };
+export const startPending = (entry: PendingAuth, now = Date.now()): string => pending.mint(entry, now).ticket;
+
+export const takePending = (state: string, now = Date.now()): PendingAuth | undefined => pending.take(state, now);
+
+export const pendingCount = (): number => pending.size();
 
 const REFRESH_SKEW_MS = 300_000;
 
-export const CALLBACK_PATH = '/api/connectors/callback';
+const CALLBACK_PATH = '/api/connectors/callback';
 
-export const callbackUri = (): string =>
+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 PrepareInput {
+  url: URL;
+  client: OAuthClient | null;
+  returnTo: string;
 }
 
-const resourceOf = (url: URL): string => url.toString();
+export interface PreparedOAuth {
+  server: OAuthServer;
+  client: OAuthClient;
+  redirectUri: string;
+}
+
+export async function prepareOAuth(input: PrepareInput, send: FetchLike = fetch): Promise<PreparedOAuth> {
+  if (!validateReturnTo(input.returnTo))
+    throw refused('that return address is not one Metro will send you back to');
+  const server = await discoverOAuth(input.url, send);
+  const redirectUri = callbackUri();
+  const client = input.client ?? (await registerClient(server, redirectUri, send));
+  return { server, client, redirectUri };
+}
 
 export interface BeginInput {
   connectorId: string;
-  email: string;
+  migrationId?: string | null;
   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);
+export function beginOAuth(prepared: PreparedOAuth, input: BeginInput): string {
+  const { server, client, redirectUri } = prepared;
   const verifier = newVerifier();
   const resource = resourceOf(input.url);
   const state = startPending({
-    email: input.email,
     name: input.name,
     url: input.url.toString(),
     resource,
@@ -56,6 +85,7 @@ export async function beginOAuth(input: BeginInput): Promise<string> {
     server,
     client,
     connectorId: input.connectorId,
+    migrationId: input.migrationId ?? null,
   });
   return authorizeUrl({
     server,
@@ -72,10 +102,14 @@ function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
     kind: 'oauth',
     issuer: pendingAuth.server.issuer,
     tokenEndpoint: pendingAuth.server.tokenEndpoint,
+    resource: pendingAuth.resource,
     clientId: pendingAuth.client.clientId,
     ...(pendingAuth.client.clientSecret === undefined
       ? {}
       : { clientSecret: pendingAuth.client.clientSecret }),
+    ...(pendingAuth.server.scopes.length === 0
+      ? {}
+      : { scope: pendingAuth.server.scopes.join(' ') }),
     ...tokens,
   };
 }
@@ -83,13 +117,14 @@ function authOf(pendingAuth: PendingAuth, tokens: OAuthTokens): OAuthAuth {
 export async function completeOAuth(
   entry: PendingAuth,
   code: string,
+  send: FetchLike = fetch,
 ): Promise<OAuthAuth> {
   const tokens = await exchangeCode(entry.server, entry.client, {
     code,
     redirectUri: callbackUri(),
     verifier: entry.verifier,
     resource: entry.resource,
-  });
+  }, send);
   return authOf(entry, tokens);
 }
 
@@ -100,6 +135,7 @@ export function oauthExpired(auth: OAuthAuth, now = Date.now()): boolean {
 export async function refreshOAuth(
   auth: OAuthAuth,
   resource: string,
+  send: FetchLike = fetch,
 ): Promise<OAuthAuth> {
   if (auth.refreshToken === undefined)
     throw refused('that connector needs signing in again');
@@ -109,6 +145,7 @@ export async function refreshOAuth(
     tokenEndpoint: auth.tokenEndpoint,
     registrationEndpoint: null,
     supportsS256: true,
+    scopes: [],
   };
   const client = {
     clientId: auth.clientId,
@@ -116,7 +153,14 @@ export async function refreshOAuth(
       ? {}
       : { clientSecret: auth.clientSecret }),
   };
-  const tokens = await refreshTokens(server, client, auth.refreshToken, resource);
+  const tokens = await refreshTokens(
+    server,
+    client,
+    auth.refreshToken,
+    auth.resource ?? resource,
+    auth.scope,
+    send,
+  );
   return {
     ...auth,
     ...tokens,

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

@@ -0,0 +1,61 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { screenCalls, type Screened } from './relay-policy.js';
+import type { RelaySession } from './relay-session.js';
+import type { RelayTarget } from './relay-target.js';
+
+type Ready = Extract<RelayTarget, { kind: 'ok' }>;
+type Forward = (target: Ready, body: Uint8Array<ArrayBuffer> | null, signal: AbortSignal) => Promise<Response>;
+type OrgExchange =
+  | { kind: 'response'; upstream: Response; answers: Record<string, unknown>[] }
+  | { kind: 'blocked'; screened: Screened };
+
+const METHODS = new Set(['initialize', 'ping', 'tools/list', 'tools/call', 'notifications/initialized', 'notifications/cancelled']);
+
+function requestBatch(body: Uint8Array | null): boolean {
+  if (body === null) return false;
+  let parsed: unknown;
+  try { parsed = JSON.parse(new TextDecoder().decode(body)); }
+  catch { throw new ApiError('Invalid organization connector request.', 400); }
+  const batch = Array.isArray(parsed);
+  const entries: unknown[] = Array.isArray(parsed) ? parsed : [parsed];
+  if (entries.length === 0 || entries.some((item) => !validMessage(item))) throw new ApiError('This organization connector accepts MCP tool requests only.', 400);
+  return batch;
+}
+
+function validMessage(item: unknown): boolean {
+  if (!isRecord(item) || item.jsonrpc !== '2.0' || typeof item.method !== 'string' || !METHODS.has(item.method)) return false;
+  if (item.method !== 'tools/call') return true;
+  if (!isRecord(item.params) || typeof item.params.name !== 'string' || item.params.name === '') return false;
+  return item.params.arguments === undefined || isRecord(item.params.arguments);
+}
+
+function ready(session: RelaySession, signal: AbortSignal): Ready {
+  if (signal.aborted) throw new ApiError('This organization connector is no longer available.', 503);
+  const target = session.current();
+  if (target.kind === 'missing') throw new ApiError('No such organization connector.', 404);
+  if (target.kind === 'signin') throw new ApiError('This organization connector needs signing in again.', 424);
+  return target;
+}
+
+export async function exchangeOrg(id: string, session: RelaySession, body: Uint8Array<ArrayBuffer> | null, clientSignal: AbortSignal, forward: Forward): Promise<OrgExchange> {
+  const signal = AbortSignal.any([clientSignal, session.signal]);
+  const batch = requestBatch(body);
+  let pending = body;
+  const answers: Record<string, unknown>[] = [];
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    await session.target(attempt > 0);
+    ready(session, signal);
+    const screened = pending === null ? null : screenCalls(pending, id, session.blocker());
+    if (screened !== null) {
+      answers.push(...screened.answers);
+      pending = screened.forward;
+      if (pending === null) return { kind: 'blocked', screened: { forward: null, answers, batch } };
+    }
+    const target = ready(session, signal);
+    const upstream = await forward(target, pending, signal);
+    if (upstream.status !== 401 && upstream.status !== 403) return { kind: 'response', upstream, answers };
+    await upstream.body?.cancel();
+  }
+  throw new ApiError('The organization connector rejected its credential. Check its sign-in in the organization settings.', 424);
+}

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

@@ -0,0 +1,115 @@
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import type { ToolGroup } from '@metro-labs/core/stations/types';
+import { ApiError } from '@metro-labs/http/api-error';
+import { validConnectorToolName, type DeliveredConnector } from '@metro-labs/http/connector-delivery';
+import { MetroApiRefusal } from './metro-api.js';
+import { listRemoteTools } from './tools.js';
+
+export const orgUnavailable = (): ApiError => new ApiError('This organization connector is not available. Try again.', 503);
+export const orgSignin = (): ApiError => new ApiError('This organization connector needs sign-in again.', 424);
+export const orgMissing = (): ApiError => new ApiError('No such organization connector is assigned to this agent.', 404);
+
+export function orgRuntimeError(error: unknown): ApiError {
+  if (error instanceof MetroApiRefusal) return error.upstreamStatus === 401 || error.upstreamStatus === 403 ? orgSignin() : orgUnavailable();
+  const status = error instanceof ApiError ? error.status : 503;
+  if (status === 401 || status === 403 || status === 424) return orgSignin();
+  if (status === 404) return orgMissing();
+  if (status === 502) return new ApiError('The organization connector could not complete the request.', 502);
+  return orgUnavailable();
+}
+
+interface DiscoveryGuard {
+  fresh: (revision?: string) => Promise<DeliveredConnector>;
+  current: () => DeliveredConnector;
+  signal: AbortSignal;
+  fetch: FetchLike;
+}
+
+const MAX_BYTES = 2 * 1024 * 1024;
+const MAX_TOOLS = 2000;
+
+async function boundedResponse(response: Response, signal: AbortSignal): Promise<Response> {
+  const reader = response.body?.getReader();
+  if (reader === undefined) return response;
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (let part = await reader.read(); !part.done; part = await reader.read()) {
+      signal.throwIfAborted();
+      size += part.value.length;
+      if (size > MAX_BYTES) throw orgUnavailable();
+      chunks.push(part.value);
+    }
+    return new Response(Buffer.concat(chunks), { status: response.status, headers: response.headers });
+  } finally {
+    await reader.cancel();
+  }
+}
+
+function requestInit(row: DeliveredConnector, init: RequestInit | undefined, scanSignal: AbortSignal): RequestInit & { signal: AbortSignal } {
+  const headers = new Headers(init?.headers);
+  for (const [name, value] of Object.entries(row.headers)) headers.set(name, value);
+  const signals = [scanSignal, AbortSignal.timeout(15_000)];
+  if (init?.signal !== undefined && init.signal !== null) signals.push(init.signal);
+  return { ...init, headers, redirect: 'manual', signal: AbortSignal.any(signals) };
+}
+
+async function discoveryResponse(response: Response, init: RequestInit | undefined, signal: AbortSignal): Promise<Response> {
+  if (response.status >= 300) throw new ApiError('The organization connector refused tool discovery.', 502);
+  if (init?.method === 'DELETE') {
+    await boundedResponse(response, signal);
+    return new Response(null, { status: response.status });
+  }
+  return boundedResponse(response, signal);
+}
+
+async function guardedRequest(input: string, init: RequestInit | undefined, guard: DiscoveryGuard, budget: { refreshed: boolean }): Promise<Response> {
+  let revision: string | undefined;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    guard.signal.throwIfAborted();
+    await guard.fresh(revision);
+    guard.signal.throwIfAborted();
+    const row = guard.current();
+    if (input !== new URL(row.url).toString()) throw orgUnavailable();
+    const options = requestInit(row, init, guard.signal);
+    const response = await guard.fetch(input, options);
+    try {
+      guard.current();
+      options.signal.throwIfAborted();
+      if (response.status === 401 || response.status === 403) {
+        if (row.auth !== 'oauth' || budget.refreshed) throw orgSignin();
+        budget.refreshed = true;
+        revision = row.revision;
+        continue;
+      }
+      return await discoveryResponse(response, init, options.signal);
+    } finally {
+      if (!response.bodyUsed) await response.body?.cancel();
+    }
+  }
+  throw orgSignin();
+}
+
+export async function discoverOrgGroups(url: string, guard: DiscoveryGuard): Promise<Record<string, ToolGroup>> {
+  try {
+    const failure: { error: ApiError | null } = { error: null };
+    const budget = { refreshed: false };
+    const send: FetchLike = async (input, init) => {
+      try {
+        return await guardedRequest(input, init, guard, budget);
+      } catch (error) {
+        const safe = orgRuntimeError(error);
+        if (init?.method !== 'DELETE' || safe.status !== 502) failure.error = safe;
+        throw safe;
+      }
+    };
+    const tools = await listRemoteTools(new URL(url), { kind: 'none' }, send);
+    if (failure.error !== null) throw failure.error;
+    guard.current();
+    guard.signal.throwIfAborted();
+    if (tools.length > MAX_TOOLS || tools.some((tool) => !validConnectorToolName(tool.name))) throw orgUnavailable();
+    return Object.fromEntries(tools.map((tool) => [tool.name, tool.readOnly ? 'read' : 'write']));
+  } catch (error) {
+    throw orgRuntimeError(error);
+  }
+}