@stage-labs/metro 0.1.0-beta.28 → 0.1.0-beta.280

package/runtime/node_modules/@metro-labs/{mcp/src/db/connector-config.ts → daemon/src/connectors/config.ts}

@@ -1,14 +1,20 @@
-import { ApiError } from '../daemon/api-error.js';
+import { ApiError } from '@metro-labs/http/api-error';
+import { stringOf } from '@metro-labs/http/api-http';
 import type {
   ConnectorAuth,
   VerifiedRecord,
   VerifiedServer,
-} from '../daemon/connector-verify.js';
-import { readStoredTools } from '../daemon/connector-tools.js';
+} 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 {}
@@ -20,14 +26,9 @@ export interface ConnectorConfig {
   createdAt: string;
   verified: VerifiedRecord;
   oauth: boolean;
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-function text(value: unknown): string {
-  return typeof value === 'string' ? value : '';
+  client: OAuthClient | null;
+  policy?: ToolPolicy;
+  toolGroups?: Record<string, ToolGroup>;
 }
 
 function hasControlChar(value: string): boolean {
@@ -58,8 +59,8 @@ export function connectorAuth(
   rawHeader: unknown,
   rawValue: unknown,
 ): ConnectorAuth {
-  const header = text(rawHeader).trim();
-  const value = text(rawValue).trim();
+  const header = stringOf(rawHeader).trim();
+  const value = stringOf(rawValue).trim();
   if (header === '' && value === '') return { kind: 'none' };
   if (value === '')
     throw new ConnectorError(
@@ -74,22 +75,48 @@ export function connectorAuth(
   return { kind: 'header', name, value };
 }
 
+export function connectorClient(
+  rawId: unknown,
+  rawSecret: unknown,
+): OAuthClient | null {
+  const clientId = stringOf(rawId).trim();
+  const clientSecret = stringOf(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 = stringOf(raw.clientId);
+  if (clientId === '') return null;
+  const clientSecret = stringOf(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);
+  const accessToken = stringOf(raw.accessToken);
+  const clientId = stringOf(raw.clientId);
+  const tokenEndpoint = stringOf(raw.tokenEndpoint);
   if (accessToken === '' || clientId === '' || tokenEndpoint === '')
     return { kind: 'none' };
-  const refreshToken = text(raw.refreshToken);
-  const clientSecret = text(raw.clientSecret);
+  const refreshToken = stringOf(raw.refreshToken);
+  const clientSecret = stringOf(raw.clientSecret);
+  const scope = stringOf(raw.scope);
   return {
     kind: 'oauth',
     accessToken,
     clientId,
     tokenEndpoint,
-    issuer: text(raw.issuer),
+    issuer: stringOf(raw.issuer),
     ...(refreshToken === '' ? {} : { refreshToken }),
     ...(clientSecret === '' ? {} : { clientSecret }),
+    ...(scope === '' ? {} : { scope }),
     ...(typeof raw.expiresAt === 'number' ? { expiresAt: raw.expiresAt } : {}),
   };
 }
@@ -98,34 +125,41 @@ 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);
+  const name = stringOf(raw.name);
+  const value = stringOf(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,
-  };
+  return { at: stringOf(record.at), server: stringOf(record.server) };
+}
+
+const TOOL_NAME_MAX = 128;
+const TOOL_GROUPS_MAX = 1000;
+
+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),
+    createdAt: stringOf(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 }),
   };
 }
 
@@ -135,13 +169,5 @@ export function signInState(config: ConnectorConfig): ConnectorSignIn {
 }
 
 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,
-  };
+  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 { NEEDS_APPROVAL, settlePrompts, takeGrant } from '../approvals/pending.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;
+  settlePrompts(promptFor(connectorId, tool), args);
+  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);
+}

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/connectors}/oauth-client.ts

@@ -1,9 +1,8 @@
 import { createHash, randomBytes } from 'node:crypto';
-import {
-  ConnectorVerifyError,
-  type OAuthTokens,
-} from './connector-verify.js';
+import { whyUnreachable } from './reach.js';
+import { refused, type OAuthTokens } from './verify.js';
 import type { OAuthServer } from './oauth-discovery.js';
+import { isRecord } from '@metro-labs/core/is-record';
 
 const TOKEN_TIMEOUT_MS = 15_000;
 const CLIENT_NAME = 'Metro';
@@ -13,14 +12,6 @@ export interface OAuthClient {
   clientSecret?: string;
 }
 
-function refused(message: string): ConnectorVerifyError {
-  return new ConnectorVerifyError(message, 400);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 export function newVerifier(): string {
   return randomBytes(32).toString('base64url');
 }
@@ -35,7 +26,9 @@ export async function registerClient(
 ): Promise<OAuthClient> {
   if (server.registrationEndpoint === null)
     throw refused(
-      'That server requires OAuth but does not accept client registration, so Metro cannot sign in to it.',
+      'That server signs in with OAuth but registers no clients on its own. ' +
+        `Register an app with it yourself, with ${redirectUri} as its redirect URL, ` +
+        "and add the connector again with that app's client ID.",
     );
   let res: Response;
   try {
@@ -52,8 +45,8 @@ export async function registerClient(
         token_endpoint_auth_method: 'none',
       }),
     });
-  } catch {
-    throw refused('Metro could not reach that server to register.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to register: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body) || typeof body.client_id !== 'string')
@@ -83,6 +76,8 @@ export function authorizeUrl(input: AuthorizeInput): string {
   url.searchParams.set('code_challenge', challengeOf(input.verifier));
   url.searchParams.set('code_challenge_method', 'S256');
   url.searchParams.set('resource', input.resource);
+  if (input.server.scopes.length > 0)
+    url.searchParams.set('scope', input.server.scopes.join(' '));
   return url.toString();
 }
 
@@ -125,8 +120,8 @@ async function postToken(
       },
       body: params.toString(),
     });
-  } catch {
-    throw refused('Metro could not reach that server to finish signing in.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to finish signing in: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body))
@@ -153,10 +148,12 @@ export function refreshTokens(
   client: OAuthClient,
   refreshToken: string,
   resource: string,
+  scope?: string,
 ): Promise<OAuthTokens> {
   return postToken(server, client, {
     grant_type: 'refresh_token',
     refresh_token: refreshToken,
     resource,
+    ...(scope === undefined ? {} : { scope }),
   });
 }

package/runtime/node_modules/@metro-labs/{mcp/src/daemon → daemon/src/connectors}/oauth-discovery.ts

@@ -1,4 +1,6 @@
-import { ConnectorVerifyError, parseConnectorUrl } from './connector-verify.js';
+import { parseConnectorUrl, refused } from './verify.js';
+import { stringOf } from '@metro-labs/http/api-http';
+import { isRecord } from '@metro-labs/core/is-record';
 
 const DISCOVERY_TIMEOUT_MS = 10_000;
 
@@ -8,19 +10,14 @@ export interface OAuthServer {
   tokenEndpoint: string;
   registrationEndpoint: string | null;
   supportsS256: boolean;
+  scopes: string[];
 }
 
-function refused(message: string): ConnectorVerifyError {
-  return new ConnectorVerifyError(message, 400);
+interface ResourceMetadata {
+  issuer: URL;
+  scopes: string[];
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-const str = (value: unknown): string =>
-  typeof value === 'string' ? value : '';
-
 async function getJson(url: URL): Promise<Record<string, unknown> | null> {
   let res: Response;
   try {
@@ -68,32 +65,48 @@ export async function advertisesOAuth(resource: URL): Promise<boolean> {
   return false;
 }
 
-async function authServerFor(resource: URL): Promise<URL> {
+function scopesOf(body: Record<string, unknown> | null): string[] {
+  const raw: unknown = body?.scopes_supported;
+  if (!Array.isArray(raw)) return [];
+  const out: string[] = [];
+  for (const entry of raw) {
+    const scope = stringOf(entry).trim();
+    if (scope !== '' && !/\s/.test(scope) && !out.includes(scope)) out.push(scope);
+  }
+  return out;
+}
+
+async function resourceMetadata(resource: URL): Promise<ResourceMetadata> {
   for (const candidate of resourceMetadataUrls(resource)) {
     const body = await getJson(candidate);
     const servers: unknown = body?.authorization_servers;
     const first: unknown = Array.isArray(servers) ? servers[0] : undefined;
     if (typeof first === 'string' && first !== '')
-      return parseConnectorUrl(first);
+      return { issuer: parseConnectorUrl(first), scopes: scopesOf(body) };
   }
-  return parseConnectorUrl(resource.origin);
+  return { issuer: parseConnectorUrl(resource.origin), scopes: [] };
 }
 
-function toServer(body: Record<string, unknown>, issuer: URL): OAuthServer {
-  const authorizationEndpoint = str(body.authorization_endpoint);
-  const tokenEndpoint = str(body.token_endpoint);
+function toServer(
+  body: Record<string, unknown>,
+  issuer: URL,
+  scopes: string[],
+): OAuthServer {
+  const authorizationEndpoint = stringOf(body.authorization_endpoint);
+  const tokenEndpoint = stringOf(body.token_endpoint);
   if (authorizationEndpoint === '' || tokenEndpoint === '')
     throw refused(
       `${issuer.hostname} advertises OAuth but not where to sign in.`,
     );
   const methods = body.code_challenge_methods_supported;
-  const registration = str(body.registration_endpoint);
+  const registration = stringOf(body.registration_endpoint);
   return {
-    issuer: str(body.issuer) === '' ? issuer.origin : str(body.issuer),
+    issuer: stringOf(body.issuer) === '' ? issuer.origin : stringOf(body.issuer),
     authorizationEndpoint,
     tokenEndpoint,
     registrationEndpoint: registration === '' ? null : registration,
     supportsS256: Array.isArray(methods) ? methods.includes('S256') : false,
+    scopes,
   };
 }
 
@@ -109,10 +122,10 @@ export function authServerMetadataUrls(issuer: URL): URL[] {
 }
 
 export async function discoverOAuth(resource: URL): Promise<OAuthServer> {
-  const issuer = await authServerFor(resource);
+  const { issuer, scopes } = await resourceMetadata(resource);
   for (const candidate of authServerMetadataUrls(issuer)) {
     const body = await getJson(candidate);
-    if (body !== null) return toServer(body, issuer);
+    if (body !== null) return toServer(body, issuer, scopes);
   }
   throw refused(
     `${resource.hostname} needs authorization, but publishes no OAuth metadata Metro can use.`,

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

@@ -1,18 +1,17 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { errMsg, log } from './log.js';
-import { bodyField, readJsonBody, sendJson, type ApiSession } from './api-http.js';
+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 './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 : '';
+} from './oauth.js';
+import { connectorClient } from './config.js';
+import { parseConnectorUrl } from './verify.js';
+import type { OAuthAuth } from './verify.js';
+import type { Connector, PendingConnectorInput } from './store.js';
 
 export function hostOf(url: string): string {
   try {
@@ -23,38 +22,37 @@ export function hostOf(url: string): string {
 }
 
 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>;
+  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,
-  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, {
+  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,
+  });
+  const row = await deps.createPendingConnector({
     name: bodyField(body, 'name'),
     url: bodyField(body, 'url'),
+    clientId,
+    clientSecret,
   });
-  const authorize = await beginOAuth({
-    email: session.email,
+  const authorize = beginOAuth(prepared, {
     name: row.name,
     url,
-    returnTo: asText(bodyField(body, 'returnTo')),
+    returnTo,
     connectorId: row.id,
   });
   log.info(
@@ -68,17 +66,17 @@ 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 row = await deps.getConnector(id);
   const url = parseConnectorUrl(row.url);
   const body = await readJsonBody(req);
-  const authorize = await beginOAuth({
-    email: session.email,
+  const returnTo = stringOf(bodyField(body, 'returnTo'));
+  const prepared = await prepareOAuth({ url, client: row.client, returnTo });
+  const authorize = beginOAuth(prepared, {
     name: row.name,
     url,
-    returnTo: asText(bodyField(body, 'returnTo')),
+    returnTo,
     connectorId: row.id,
   });
   log.info(
@@ -110,7 +108,7 @@ async function saveOAuth(
   entry: PendingAuth,
   auth: OAuthAuth,
 ): Promise<Connector> {
-  return deps.reconnectConnector(entry.email, entry.connectorId, auth);
+  return deps.reconnectConnector(entry.connectorId, auth);
 }
 
 async function settleCallback(