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

package/runtime/node_modules/@metro-labs/http/src/connector-migration.ts

@@ -0,0 +1,178 @@
+import type { KeyObject } from 'node:crypto';
+import { parseId } from '@metro-labs/core/ids';
+import { sealingKeyOf } from './agent-signature.js';
+import { deliveryBytes, deliveryRecord } from './connector-delivery-validation.js';
+import { connectorAuth, connectorClient, connectorName } from './connector-input.js';
+import type { OAuthClient } from './connector-oauth.js';
+import { portableGrant, type PortableGrant } from './connector-grant.js';
+import { connectorPolicyOf, type ConnectorPolicy } from './connector-policy.js';
+import { boundOAuthResource, parsePublicConnectorUrl } from './connector-public-url.js';
+import { openTransfer, sealTransfer, type SealedTransfer } from './transfer-crypto.js';
+import { isOrganizationId } from './workos-token.js';
+
+export const CONNECTOR_MIGRATION_MAX_BYTES = 96 * 1024;
+const PAYLOAD_MAX = 60 * 1024;
+
+export interface MigrationContext {
+  owner: string;
+  agent: string;
+  keyId: string;
+  operationId: string;
+  sourceId: string;
+  destinationId: string;
+}
+
+export interface MigrationPayload {
+  name: string;
+  url: string;
+  auth: { kind: 'none' } | { kind: 'header'; name: string; value: string } | { kind: 'oauth'; grant?: PortableGrant };
+  client: OAuthClient | null;
+  oauthResource?: string;
+  policy: ConnectorPolicy;
+  sourceStamp: string;
+}
+
+export interface MigrationView {
+  operationId: string;
+  sourceId: string;
+  destinationId: string;
+  phase: 'preparing' | 'prepared' | 'active' | 'rolled_back';
+  readiness: 'pending' | 'ready' | 'signin' | 'changed' | 'unavailable' | 'refresh_uncertain';
+  grantImported?: boolean;
+  name: string | null;
+  auth: 'none' | 'header' | 'oauth' | null;
+  policy: ConnectorPolicy | null;
+  sourceStamp: string | null;
+}
+
+export interface MigrationResponse {
+  migration: MigrationView;
+  receiving?: { publicKey: string; context: MigrationContext };
+}
+
+export type MigrationRequest = { action: 'begin' | 'status' | 'activate' | 'rollback'; operationId: string; sourceId: string } | { action: 'prepare' | 'handover'; operationId: string; sourceId: string; sealed: unknown };
+
+const invalid = (): Error => new Error('Invalid connector migration.');
+const idOf = (value: unknown): string => {
+  const id = parseId(value);
+  if (id === null) throw invalid();
+  return id;
+};
+
+export function migrationRequestOf(raw: unknown): MigrationRequest {
+  const value = deliveryRecord(raw, ['action', 'operationId', 'sourceId', 'sealed']);
+  const operationId = idOf(value.operationId);
+  const sourceId = idOf(value.sourceId);
+  if ((value.action === 'prepare' || value.action === 'handover') && Object.hasOwn(value, 'sealed')) return { action: value.action, operationId, sourceId, sealed: value.sealed };
+  if (Object.hasOwn(value, 'sealed')) throw invalid();
+  if (value.action !== 'begin' && value.action !== 'status' && value.action !== 'activate' && value.action !== 'rollback') throw invalid();
+  return { action: value.action, operationId, sourceId };
+}
+
+function contextOf(raw: unknown): MigrationContext {
+  const value = deliveryRecord(raw, ['owner', 'agent', 'keyId', 'operationId', 'sourceId', 'destinationId']);
+  if (typeof value.owner !== 'string' || !isOrganizationId(value.owner) || typeof value.keyId !== 'string') throw invalid();
+  deliveryBytes(value.keyId, 32);
+  return { owner: value.owner, agent: idOf(value.agent), keyId: value.keyId, operationId: idOf(value.operationId), sourceId: idOf(value.sourceId), destinationId: idOf(value.destinationId) };
+}
+
+function contextBytes(context: MigrationContext): Buffer {
+  const value = contextOf(context);
+  return Buffer.from(JSON.stringify(['metro-connector-migration/v1', value.owner, value.agent, value.keyId, value.operationId, value.sourceId, value.destinationId]));
+}
+
+function headerOf(value: Record<string, unknown>): MigrationPayload['auth'] {
+  const auth = connectorAuth(value.name, value.value);
+  if (auth.kind !== 'header' || auth.name !== value.name || auth.value !== value.value || ['__proto__', 'constructor', 'prototype'].includes(auth.name)) throw invalid();
+  return auth;
+}
+
+function authOf(raw: unknown, target: string): MigrationPayload['auth'] {
+  const value = deliveryRecord(raw, ['kind', 'name', 'value', 'grant']);
+  if (value.kind !== 'oauth' && Object.hasOwn(value, 'grant')) throw invalid();
+  if (value.kind === 'header') return headerOf(value);
+  if ((value.kind !== 'none' && value.kind !== 'oauth') || Object.hasOwn(value, 'name') || Object.hasOwn(value, 'value')) throw invalid();
+  if (value.kind === 'none' || value.grant === undefined) return { kind: value.kind };
+  return { kind: 'oauth', grant: portableGrant(value.grant, target) };
+}
+
+function clientOf(raw: unknown): OAuthClient | null {
+  if (raw === null) return null;
+  const value = deliveryRecord(raw, ['clientId', 'clientSecret']);
+  const client = connectorClient(value.clientId, value.clientSecret);
+  if (client === null || client.clientId !== value.clientId || client.clientSecret !== value.clientSecret) throw invalid();
+  return client;
+}
+
+function migrationClient(auth: MigrationPayload['auth'], input: Record<string, unknown>): OAuthClient | null {
+  const client = clientOf(input.client);
+  if (auth.kind !== 'oauth' && (client !== null || Object.hasOwn(input, 'oauthResource'))) throw invalid();
+  return client;
+}
+
+export function migrationPayloadOf(raw: unknown): MigrationPayload {
+  const value = deliveryRecord(raw, ['name', 'url', 'auth', 'client', 'oauthResource', 'policy', 'sourceStamp']);
+  if (typeof value.name !== 'string' || connectorName(value.name) !== value.name || typeof value.url !== 'string' || typeof value.sourceStamp !== 'string') throw invalid();
+  parsePublicConnectorUrl(value.url);
+  deliveryBytes(value.sourceStamp, 32);
+  const auth = authOf(value.auth, value.url);
+  const client = migrationClient(auth, value);
+  const payload = { name: value.name, url: value.url, auth, client, ...(Object.hasOwn(value, 'oauthResource') ? { oauthResource: boundOAuthResource(value.url, value.oauthResource) } : {}), policy: connectorPolicyOf(value.policy), sourceStamp: value.sourceStamp };
+  if (Buffer.byteLength(JSON.stringify(payload)) > PAYLOAD_MAX) throw invalid();
+  return payload;
+}
+
+function phaseOf(value: unknown): MigrationView['phase'] {
+  if (value !== 'preparing' && value !== 'prepared' && value !== 'active' && value !== 'rolled_back') throw invalid();
+  return value;
+}
+
+function readinessOf(value: unknown): MigrationView['readiness'] {
+  if (value !== 'pending' && value !== 'ready' && value !== 'signin' && value !== 'changed' && value !== 'unavailable' && value !== 'refresh_uncertain') throw invalid();
+  return value;
+}
+
+function authKindOf(value: unknown): MigrationView['auth'] {
+  if (value !== null && value !== 'none' && value !== 'header' && value !== 'oauth') throw invalid();
+  return value;
+}
+
+function nullableName(value: unknown): string | null {
+  if (value === null) return null;
+  if (typeof value !== 'string' || connectorName(value) !== value) throw invalid();
+  return value;
+}
+
+function nullableStamp(value: unknown): string | null {
+  if (value === null) return null;
+  if (typeof value !== 'string') throw invalid();
+  deliveryBytes(value, 32);
+  return value;
+}
+
+function viewOf(raw: unknown): MigrationView {
+  const view = deliveryRecord(raw, ['operationId', 'sourceId', 'destinationId', 'phase', 'readiness', 'name', 'auth', 'policy', 'sourceStamp', 'grantImported']);
+  if (view.grantImported !== undefined && typeof view.grantImported !== 'boolean') throw invalid();
+  return { ...(view.grantImported === undefined ? {} : { grantImported: view.grantImported }), operationId: idOf(view.operationId), sourceId: idOf(view.sourceId), destinationId: idOf(view.destinationId), phase: phaseOf(view.phase), readiness: readinessOf(view.readiness), name: nullableName(view.name), auth: authKindOf(view.auth), policy: view.policy === null ? null : connectorPolicyOf(view.policy), sourceStamp: nullableStamp(view.sourceStamp) };
+}
+
+export function migrationResponseOf(raw: unknown): MigrationResponse {
+  const value = deliveryRecord(raw, ['migration', 'receiving']);
+  const migration = viewOf(value.migration);
+  if (!Object.hasOwn(value, 'receiving')) return { migration };
+  const receiving = deliveryRecord(value.receiving, ['publicKey', 'context']);
+  if (typeof receiving.publicKey !== 'string' || sealingKeyOf(receiving.publicKey) === null) throw invalid();
+  const context = contextOf(receiving.context);
+  if (context.operationId !== migration.operationId || context.sourceId !== migration.sourceId || context.destinationId !== migration.destinationId) throw invalid();
+  return { migration, receiving: { publicKey: receiving.publicKey, context } };
+}
+
+export function sealConnectorMigration(publicKey: string, context: MigrationContext, payload: MigrationPayload): SealedTransfer {
+  return sealTransfer(publicKey, contextBytes(context), Buffer.from(JSON.stringify(migrationPayloadOf(payload))));
+}
+
+export function openConnectorMigration(privateKey: KeyObject, context: MigrationContext, sealed: unknown): MigrationPayload {
+  if (Buffer.byteLength(JSON.stringify(sealed)) > CONNECTOR_MIGRATION_MAX_BYTES) throw invalid();
+  const plain = openTransfer(privateKey, contextBytes(context), sealed, PAYLOAD_MAX);
+  return migrationPayloadOf(JSON.parse(plain.toString('utf8')) as unknown);
+}

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

@@ -1,26 +1,21 @@
 import { createHash, randomBytes } from 'node:crypto';
-import {
-  ConnectorVerifyError,
-  type OAuthTokens,
-} from './connector-verify.js';
-import type { OAuthServer } from './oauth-discovery.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { whyUnreachable } from './connector-reach.js';
+import { ConnectorVerifyError, refused } from './connector-url.js';
+import type { OAuthTokens } from './connector-mcp.js';
+import type { OAuthServer } from './connector-discovery.js';
 
 const TOKEN_TIMEOUT_MS = 15_000;
 const CLIENT_NAME = 'Metro';
 
+export class OAuthInvalidGrant extends ConnectorVerifyError {}
+
 export interface OAuthClient {
   clientId: string;
   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');
 }
@@ -32,14 +27,17 @@ export function challengeOf(verifier: string): string {
 export async function registerClient(
   server: OAuthServer,
   redirectUri: string,
+  fetchImpl: FetchLike = fetch,
 ): 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 {
-    res = await fetch(server.registrationEndpoint, {
+    res = await fetchImpl(server.registrationEndpoint, {
       method: 'POST',
       redirect: 'manual',
       signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
@@ -52,8 +50,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,21 +81,37 @@ 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();
 }
 
+function validateOptionalTokens(body: Record<string, unknown>): void {
+  const refresh = body.refresh_token;
+  if (Object.hasOwn(body, 'refresh_token') && (typeof refresh !== 'string' || !/^[\x21-\x7e]{1,16384}$/.test(refresh))) throw refused('That server returned an invalid refresh token.');
+  if (Object.hasOwn(body, 'token_type') && (typeof body.token_type !== 'string' || body.token_type.toLowerCase() !== 'bearer')) throw refused('That server returned an unsupported token type.');
+}
+
+function expiryFrom(body: Record<string, unknown>): number | undefined {
+  if (!Object.hasOwn(body, 'expires_in')) return undefined;
+  const expires = body.expires_in;
+  if (typeof expires !== 'number' || !Number.isFinite(expires) || expires <= 0) throw refused('That server returned an invalid token expiry.');
+  const at = Date.now() + expires * 1000;
+  if (!Number.isSafeInteger(at)) throw refused('That server returned an invalid token expiry.');
+  return at;
+}
+
 function tokensFrom(body: Record<string, unknown>): OAuthTokens {
   const access = body.access_token;
-  if (typeof access !== 'string' || access === '')
-    throw refused('That server did not return an access token.');
+  if (typeof access !== 'string' || !/^[\x21-\x7e]{1,16377}$/.test(access))
+    throw refused('That server did not return a sendable access token.');
+  validateOptionalTokens(body);
+  const expiresAt = expiryFrom(body);
   const refresh = body.refresh_token;
-  const expires = body.expires_in;
   return {
     accessToken: access,
     ...(typeof refresh === 'string' ? { refreshToken: refresh } : {}),
-    ...(typeof expires === 'number'
-      ? { expiresAt: Date.now() + expires * 1000 }
-      : {}),
+    ...(expiresAt === undefined ? {} : { expiresAt }),
   };
 }
 
@@ -105,6 +119,7 @@ async function postToken(
   server: OAuthServer,
   client: OAuthClient,
   form: Record<string, string>,
+  fetchImpl: FetchLike,
 ): Promise<OAuthTokens> {
   const params = new URLSearchParams({
     ...form,
@@ -115,7 +130,7 @@ async function postToken(
   });
   let res: Response;
   try {
-    res = await fetch(server.tokenEndpoint, {
+    res = await fetchImpl(server.tokenEndpoint, {
       method: 'POST',
       redirect: 'manual',
       signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
@@ -125,10 +140,11 @@ 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 (form.grant_type === 'refresh_token' && res.status === 400 && isRecord(body) && body.error === 'invalid_grant') throw new OAuthInvalidGrant('That server requires a new sign-in.', 400);
   if (!res.ok || !isRecord(body))
     throw refused('That server refused to complete the sign-in.');
   return tokensFrom(body);
@@ -138,6 +154,7 @@ export function exchangeCode(
   server: OAuthServer,
   client: OAuthClient,
   input: { code: string; redirectUri: string; verifier: string; resource: string },
+  fetchImpl: FetchLike = fetch,
 ): Promise<OAuthTokens> {
   return postToken(server, client, {
     grant_type: 'authorization_code',
@@ -145,7 +162,7 @@ export function exchangeCode(
     redirect_uri: input.redirectUri,
     code_verifier: input.verifier,
     resource: input.resource,
-  });
+  }, fetchImpl);
 }
 
 export function refreshTokens(
@@ -153,10 +170,13 @@ export function refreshTokens(
   client: OAuthClient,
   refreshToken: string,
   resource: string,
+  scope?: string,
+  fetchImpl: FetchLike = fetch,
 ): Promise<OAuthTokens> {
   return postToken(server, client, {
     grant_type: 'refresh_token',
     refresh_token: refreshToken,
     resource,
-  });
+    ...(scope === undefined ? {} : { scope }),
+  }, fetchImpl);
 }

package/runtime/node_modules/@metro-labs/http/src/connector-policy.ts

@@ -0,0 +1,92 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+export type ConnectorDecision = 'allow' | 'ask' | 'deny';
+
+type ToolGroup = 'read' | 'write';
+
+export interface ConnectorPolicy {
+  read?: ConnectorDecision;
+  write?: ConnectorDecision;
+  tools?: Record<string, ConnectorDecision>;
+}
+
+export interface ConnectorPolicyLayers {
+  organization: ConnectorPolicy;
+  agent: ConnectorPolicy;
+}
+
+const RANK: Record<ConnectorDecision, number> = { allow: 0, ask: 1, deny: 2 };
+const TOOL_RE = /^[A-Za-z0-9_.:/-]{1,256}$/;
+
+export const validConnectorToolName = (name: string): boolean => TOOL_RE.test(name) && !['__proto__', 'constructor', 'prototype'].includes(name);
+
+const decision = (value: unknown): value is ConnectorDecision => value === 'allow' || value === 'ask' || value === 'deny';
+
+export function connectorPolicyOf(value: unknown): ConnectorPolicy {
+  if (!isRecord(value) || Object.keys(value).some((key) => !['read', 'write', 'tools'].includes(key))) throw new Error('Invalid connector policy.');
+  const out: ConnectorPolicy = {};
+  for (const group of ['read', 'write'] as const) {
+    if (!Object.hasOwn(value, group)) continue;
+    const field = value[group];
+    if (!decision(field)) throw new Error('Invalid connector policy.');
+    out[group] = field;
+  }
+  if (Object.hasOwn(value, 'tools')) out.tools = toolPolicyOf(value.tools);
+  return out;
+}
+
+function toolPolicyOf(value: unknown): Record<string, ConnectorDecision> {
+  if (!isRecord(value) || Object.keys(value).length > 2000) throw new Error('Invalid connector policy.');
+  const out: Record<string, ConnectorDecision> = {};
+  for (const [name, rule] of Object.entries(value)) {
+    if (!validConnectorToolName(name) || !decision(rule)) throw new Error('Invalid connector policy.');
+    out[name] = rule;
+  }
+  return out;
+}
+
+export function connectorPolicyLayersOf(value: unknown): ConnectorPolicyLayers {
+  if (!isRecord(value) || Object.keys(value).some((key) => !['organization', 'agent'].includes(key))) throw new Error('Invalid connector policy layers.');
+  return { organization: connectorPolicyOf(value.organization), agent: connectorPolicyOf(value.agent) };
+}
+
+const strictest = (...values: (ConnectorDecision | undefined)[]): ConnectorDecision => values.reduce<ConnectorDecision>((held, next) => next !== undefined && RANK[next] > RANK[held] ? next : held, 'allow');
+const toolRule = (policy: ConnectorPolicy, name: string): ConnectorDecision | undefined => policy.tools !== undefined && Object.hasOwn(policy.tools, name) ? policy.tools[name] : undefined;
+const toolGroup = (groups: Record<string, ToolGroup>, name: string): ToolGroup => Object.hasOwn(groups, name) && groups[name] === 'read' ? 'read' : 'write';
+const access = (policy: ConnectorPolicy, name: string, group: ToolGroup): ConnectorDecision => toolRule(policy, name) ?? policy[group] ?? 'allow';
+
+export function combineConnectorPolicies(global: ConnectorPolicy, assignment: ConnectorPolicy, groups?: Record<string, ToolGroup>): ConnectorPolicy {
+  const policies = [connectorPolicyOf(global), connectorPolicyOf(assignment)];
+  const neutral = (policy: ConnectorPolicy): boolean => (policy.read ?? 'allow') === 'allow' && (policy.write ?? 'allow') === 'allow' && Object.keys(policy.tools ?? {}).length === 0;
+  if (neutral(assignment)) return connectorPolicyOf(global);
+  if (neutral(global)) return connectorPolicyOf(assignment);
+  const out: ConnectorPolicy = {
+    read: strictest(...policies.map((policy) => policy.read)),
+    write: strictest(...policies.map((policy) => policy.write)),
+  };
+  const names = new Set(policies.flatMap((policy) => Object.keys(policy.tools ?? {})));
+  if (groups === undefined && names.size > 2000) return { read: 'deny', write: 'deny' };
+  if (names.size > 0) {
+    out.tools = {};
+    for (const name of names) {
+      out.tools[name] = groups === undefined
+        ? strictest(...policies.flatMap((policy) => [policy.read, policy.write, toolRule(policy, name)]))
+        : strictest(...policies.map((policy) => access(policy, name, toolGroup(groups, name))));
+    }
+  }
+  return out;
+}
+
+export function effectiveConnectorPolicy(row: { policy: ConnectorPolicy; policyLayers?: ConnectorPolicyLayers }, groups: Record<string, ToolGroup>): ConnectorPolicy {
+  const layers = row.policyLayers;
+  return layers === undefined ? connectorPolicyOf(row.policy) : combineConnectorPolicies(layers.organization, layers.agent, groups);
+}
+
+export function connectorPoliciesBlocked(layers: ConnectorPolicyLayers): boolean {
+  const policies = [layers.organization, layers.agent];
+  const names = new Set(policies.flatMap((policy) => Object.keys(policy.tools ?? {})));
+  return (['read', 'write'] as const).every((group) =>
+    strictest(...policies.map((policy) => policy[group])) === 'deny' &&
+    [...names].every((name) => strictest(...policies.map((policy) => access(policy, name, group))) === 'deny'),
+  );
+}

package/runtime/node_modules/@metro-labs/http/src/connector-public-url.ts

@@ -0,0 +1,64 @@
+import { BlockList, isIP } from 'node:net';
+import { parseConnectorUrl, refused } from './connector-url.js';
+
+const blocked = new BlockList();
+for (const [address, prefix] of [
+  ['0.0.0.0', 8], ['10.0.0.0', 8], ['100.64.0.0', 10], ['127.0.0.0', 8], ['169.254.0.0', 16], ['172.16.0.0', 12],
+  ['192.0.0.0', 24], ['192.0.2.0', 24], ['192.88.99.0', 24], ['192.168.0.0', 16], ['198.18.0.0', 15],
+  ['198.51.100.0', 24], ['203.0.113.0', 24], ['224.0.0.0', 4], ['240.0.0.0', 4],
+] as const) blocked.addSubnet(address, prefix, 'ipv4');
+for (const [address, prefix] of [
+  ['2001::', 32], ['2001:10::', 28], ['2001:20::', 28], ['2001:db8::', 32], ['2002::', 16],
+] as const) blocked.addSubnet(address, prefix, 'ipv6');
+const globalV6 = new BlockList();
+globalV6.addSubnet('2000::', 3, 'ipv6');
+
+export function publicConnectorAddress(address: string, family: number): boolean {
+  if (family === 4) return isIP(address) === 4 && !blocked.check(address, 'ipv4');
+  return isIP(address) === 6 && globalV6.check(address, 'ipv6') && !blocked.check(address, 'ipv6');
+}
+
+function publicHost(host: string): boolean {
+  const family = isIP(host);
+  if (family !== 0) return publicConnectorAddress(host, family);
+  if (/(^|\.)(localhost|local|internal|lan|home|invalid|test|onion)$/.test(host)) return false;
+  return host.includes('.') && host.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
+}
+
+function invalidText(raw: string): boolean {
+  return raw.length > 2048 || /[\s\\#]/.test(raw) || /%(?![0-9a-f]{2})/i.test(raw);
+}
+
+export function parsePublicConnectorUrl(raw: unknown): URL {
+  const invalid = (): never => { throw refused('An organization endpoint must be a public HTTPS URL without user information or a fragment.'); };
+  if (typeof raw !== 'string' || invalidText(raw)) return invalid();
+  const authority = /^https:\/\/([^/ ?#]+)/i.exec(raw)?.[1];
+  if (authority === undefined || authority.includes('@')) return invalid();
+  let url: URL;
+  try { url = parseConnectorUrl(raw); } catch { return invalid(); }
+  if (url.toString().length > 2048 || !publicHost(url.hostname.replace(/^\[|\]$/g, ''))) return invalid();
+  return url;
+}
+
+export function publicOAuthResource(raw: unknown): string {
+  try {
+    const url = parsePublicConnectorUrl(raw);
+    if (typeof raw === 'string' && !raw.includes('?') && url.search === '') return raw;
+  } catch {
+    throw refused('The public OAuth resource must be a public HTTPS identifier without a query, user information or a fragment. Do not enter credentials.');
+  }
+  throw refused('The public OAuth resource must be a public HTTPS identifier without a query, user information or a fragment. Do not enter credentials.');
+}
+
+export function optionalOAuthResource(raw: unknown): string | undefined {
+  return raw === undefined || raw === '' ? undefined : publicOAuthResource(raw);
+}
+
+export function boundOAuthResource(target: string, raw: unknown): string {
+  const resource = publicOAuthResource(raw);
+  const transport = parsePublicConnectorUrl(target);
+  const url = new URL(resource);
+  const path = url.pathname.replace(/\/$/, '');
+  if (url.origin !== transport.origin || !(path === '' || transport.pathname === path || transport.pathname.startsWith(`${path}/`))) throw refused('The public OAuth resource does not identify this endpoint. Check the provider’s documented resource.');
+  return resource;
+}

package/runtime/node_modules/@metro-labs/http/src/connector-reach.ts

@@ -0,0 +1,27 @@
+import { errMsg } from '@metro-labs/core/log';
+
+const HINTS: Record<string, string> = {
+  ENOTFOUND: 'the name does not resolve',
+  EAI_AGAIN: 'the name did not resolve in time',
+  ECONNREFUSED: 'nothing is listening there',
+  ECONNRESET: 'the server dropped the connection',
+  ETIMEDOUT: 'the server did not answer in time',
+  ConnectionRefused: 'nothing is listening there',
+  CERT_HAS_EXPIRED: 'its certificate has expired',
+  DEPTH_ZERO_SELF_SIGNED_CERT: 'its certificate is self-signed',
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'its certificate could not be verified',
+  ERR_TLS_CERT_ALTNAME_INVALID: 'its certificate is for another name',
+  SELF_SIGNED_CERT_IN_CHAIN: 'its certificate chain is not trusted',
+};
+
+const codeOf = (err: unknown): string =>
+  err !== null && typeof err === 'object' && 'code' in err && typeof err.code === 'string' ? err.code : '';
+
+export function whyUnreachable(err: unknown): string {
+  const inner = err instanceof Error && err.cause instanceof Error ? err.cause : err;
+  const message = errMsg(inner).trim();
+  const code = codeOf(inner) || codeOf(err);
+  const said = message !== '' && message !== 'fetch failed' ? message : code || 'no answer';
+  const hint = HINTS[code];
+  return hint === undefined ? said : `${said} (${hint})`;
+}

package/runtime/node_modules/@metro-labs/http/src/connector-resource.ts

@@ -0,0 +1,108 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authServerMetadataUrls, resourceMetadataUrls, type OAuthServer } from './connector-discovery.js';
+import { boundOAuthResource, optionalOAuthResource, parsePublicConnectorUrl, publicOAuthResource } from './connector-public-url.js';
+import { refused, ConnectorVerifyError } from './connector-url.js';
+
+const METADATA_MAX = 1024 * 1024;
+const metadataError = (): Error => refused('The provider returned invalid or unavailable public OAuth metadata. Check its public OAuth resource and try again.');
+export class OAuthResourceRequired extends ConnectorVerifyError {
+  constructor() { super('Enter the provider’s public OAuth resource before continuing. It is shown in the sign-in page; never enter a private endpoint or credentials.', 400); }
+}
+
+async function metadataBody(res: Response): Promise<Record<string, unknown>> {
+  if (res.body === null) throw metadataError();
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > METADATA_MAX) throw metadataError();
+      chunks.push(value);
+    }
+    const body: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!isRecord(body)) throw metadataError();
+    return body;
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+async function metadata(url: URL, send: FetchLike): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await send(url.toString(), { redirect: 'manual', signal: AbortSignal.timeout(10_000), headers: { accept: 'application/json' } });
+    if (res.status === 404) {
+      await res.body?.cancel();
+      return null;
+    }
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw metadataError();
+    }
+    return await metadataBody(res);
+  } catch {
+    throw metadataError();
+  }
+}
+
+function selectedResource(transport: URL, offered: string | undefined, body: Record<string, unknown> | null): string {
+  const advertised = body !== null && Object.hasOwn(body, 'resource') ? publicOAuthResource(body.resource) : undefined;
+  if (advertised !== undefined && offered !== undefined && advertised !== offered) throw metadataError();
+  const resource = advertised ?? offered;
+  if (resource === undefined) throw new OAuthResourceRequired();
+  return boundOAuthResource(transport.toString(), resource);
+}
+
+function issuerOf(body: Record<string, unknown> | null, transport: URL): string {
+  if (body === null || !Object.hasOwn(body, 'authorization_servers')) return transport.origin;
+  const servers = body.authorization_servers;
+  if (!Array.isArray(servers) || servers.length === 0 || servers.length > 20) throw metadataError();
+  const values = servers.map((value: unknown) => publicOAuthResource(value));
+  return values[0] ?? '';
+}
+
+function scopesOf(body: Record<string, unknown> | null): string[] {
+  if (body === null || !Object.hasOwn(body, 'scopes_supported')) return [];
+  const scopes = body.scopes_supported;
+  if (!Array.isArray(scopes) || scopes.length > 100 || scopes.some((scope: unknown) => typeof scope !== 'string' || !/^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/.test(scope))) throw metadataError();
+  return [...new Set(scopes as string[])];
+}
+
+function serverOf(body: Record<string, unknown>, issuer: string, scopes: string[]): OAuthServer {
+  if (typeof body.issuer !== 'string' || publicOAuthResource(body.issuer) !== issuer) throw metadataError();
+  const endpoint = (raw: unknown): string => parsePublicConnectorUrl(raw).toString();
+  return {
+    issuer,
+    authorizationEndpoint: endpoint(body.authorization_endpoint),
+    tokenEndpoint: endpoint(body.token_endpoint),
+    registrationEndpoint: body.registration_endpoint === undefined ? null : endpoint(body.registration_endpoint),
+    supportsS256: Array.isArray(body.code_challenge_methods_supported) && body.code_challenge_methods_supported.includes('S256'),
+    scopes,
+  };
+}
+
+async function protectedMetadata(base: URL, send: FetchLike): Promise<Record<string, unknown> | null> {
+  for (const candidate of resourceMetadataUrls(base)) {
+    const body = await metadata(candidate, send);
+    if (body !== null) return body;
+  }
+  return null;
+}
+
+export async function discoverPublicOAuth(target: string, offered: unknown, send: FetchLike = fetch): Promise<{ server: OAuthServer; resource: string }> {
+  const transport = parsePublicConnectorUrl(target);
+  const explicit = optionalOAuthResource(offered);
+  if (explicit !== undefined) boundOAuthResource(target, explicit);
+  const body = await protectedMetadata(new URL(explicit ?? transport.origin), send);
+  const resource = selectedResource(transport, explicit, body);
+  const issuer = issuerOf(body, transport);
+  const scopes = scopesOf(body);
+  for (const candidate of authServerMetadataUrls(new URL(issuer))) {
+    const authorization = await metadata(candidate, send);
+    if (authorization !== null) return { server: serverOf(authorization, issuer, scopes), resource };
+  }
+  throw metadataError();
+}