@stage-labs/metro 0.1.0-beta.290 → 0.1.0-beta.292

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-source.ts

@@ -1,15 +1,28 @@
 import { createHash } from 'node:crypto';
 import type { MigrationPayload } from '@metro-labs/http/connector-migration';
 import { connectorPolicyOf } from '@metro-labs/http/connector-delivery';
+import { ApiError } from '@metro-labs/http/api-error';
+import { portableGrant } from '@metro-labs/http/connector-grant';
+import { boundOAuthResource } from '@metro-labs/http/connector-public-url';
 import type { LocalConnectorRow } from './store.js';
 
-export function migrationPayload(row: LocalConnectorRow): MigrationPayload {
+export class MigrationBlocked extends ApiError {
+  constructor(readonly reason: string, message: string) { super(message, 409); }
+}
+
+export function migrationPayload(row: LocalConnectorRow, oauthResource?: string, transfer = false): MigrationPayload {
   const oauth = row.config.oauth || row.config.auth.kind === 'oauth';
-  const auth = oauth ? { kind: 'oauth' as const } : row.config.auth;
-  if (auth.kind === 'oauth') {
-    return stamped({ name: row.name, url: row.url, auth: { kind: 'oauth' }, client: row.config.client, policy: connectorPolicyOf(row.config.policy ?? {}) });
-  }
-  return stamped({ name: row.name, url: row.url, auth, client: row.config.client, policy: connectorPolicyOf(row.config.policy ?? {}) });
+  const auth = sourceAuth(row, oauth, transfer);
+  if (!oauth && oauthResource !== undefined) throw new ApiError('Only an OAuth connector accepts a public OAuth resource.', 400);
+  return stamped({
+    name: row.name, url: row.url, auth, client: row.config.client, policy: connectorPolicyOf(row.config.policy ?? {}),
+    ...(oauthResource === undefined ? {} : { oauthResource: boundOAuthResource(row.url, oauthResource) }),
+  });
+}
+
+function sourceAuth(row: LocalConnectorRow, oauth: boolean, transfer: boolean): MigrationPayload['auth'] {
+  if (!oauth) return row.config.auth;
+  return transfer ? { kind: 'oauth', grant: transferableGrant(row) } : { kind: 'oauth' };
 }
 
 function stamped(value: Omit<MigrationPayload, 'sourceStamp'>): MigrationPayload {
@@ -21,3 +34,9 @@ function stamped(value: Omit<MigrationPayload, 'sourceStamp'>): MigrationPayload
   const sourceStamp = createHash('sha256').update(JSON.stringify(canonical)).digest('base64url');
   return { ...value, sourceStamp };
 }
+
+function transferableGrant(row: LocalConnectorRow): ReturnType<typeof portableGrant> {
+  if (row.config.auth.kind !== 'oauth') throw new MigrationBlocked('sign_in', 'This connector has no saved OAuth grant. Sign in locally before moving it.');
+  try { return portableGrant(row.config.auth, row.url); }
+  catch { throw new MigrationBlocked('unsupported_grant', 'This OAuth grant has unsupported client authentication or provider binding. Keep it local or sign in separately.'); }
+}

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-state.ts

@@ -6,10 +6,11 @@ import { parseId } from '@metro-labs/core/ids';
 import { ensureSecureDir } from '@metro-labs/core/secure-fs';
 import { ApiError } from '@metro-labs/http/api-error';
 import { connectorPolicyOf, type ConnectorPolicy } from '@metro-labs/http/connector-delivery';
+import { publicOAuthResource } from '@metro-labs/http/connector-public-url';
 import { agentsDir } from '../agents/files.js';
 import { captureMigrationOperations } from './migration-operations.js';
 
-export type MigrationPhase = 'preparing' | 'prepared' | 'cutover' | 'active' | 'rollback' | 'rolled_back';
+export type MigrationPhase = 'recovering' | 'freezing' | 'preparing' | 'prepared' | 'cutover' | 'active' | 'rollback' | 'rolled_back';
 export type MigrationAuth = 'none' | 'header' | 'oauth';
 
 export interface MigrationRecord {
@@ -22,14 +23,19 @@ export interface MigrationRecord {
   destinationId: string | null;
   phase: MigrationPhase;
   auth: MigrationAuth;
+  oauthResource?: string;
+  move?: boolean;
+  grantImported?: boolean;
+  captured?: boolean;
+  recoveryReceipt?: string;
   sourceStamp: string;
   policy: ConnectorPolicy;
   reason: string | null;
 }
 
-const phases: readonly MigrationPhase[] = ['preparing', 'prepared', 'cutover', 'active', 'rollback', 'rolled_back'];
+const phases: readonly MigrationPhase[] = ['recovering', 'freezing', 'preparing', 'prepared', 'cutover', 'active', 'rollback', 'rolled_back'];
 const auths: readonly MigrationAuth[] = ['none', 'header', 'oauth'];
-const fields = ['id', 'owner', 'agentId', 'keyId', 'sourceId', 'name', 'destinationId', 'phase', 'auth', 'sourceStamp', 'policy', 'reason'];
+const fields = ['id', 'owner', 'agentId', 'keyId', 'sourceId', 'name', 'destinationId', 'phase', 'auth', 'oauthResource', 'sourceStamp', 'policy', 'reason', 'move', 'grantImported', 'captured', 'recoveryReceipt'];
 const unavailable = (): ApiError => new ApiError('Protected connector migration records cannot be read. Restore their file or permissions before using connectors.', 503);
 const DIGEST = /^[A-Za-z0-9_-]{43}$/;
 const pathOf = (dir: string): string => join(dir, 'connector-migrations.json');
@@ -46,12 +52,26 @@ function field(value: unknown, pattern: RegExp): string {
   return value;
 }
 
+function movementOf(value: Record<string, unknown>): Pick<MigrationRecord, 'move' | 'grantImported' | 'captured' | 'recoveryReceipt'> {
+  const result: Pick<MigrationRecord, 'move' | 'grantImported' | 'captured' | 'recoveryReceipt'> = {};
+  for (const key of ['move', 'grantImported', 'captured'] as const) {
+    const flag = value[key];
+    if (flag === undefined) continue;
+    if (typeof flag !== 'boolean') throw unavailable();
+    result[key] = flag;
+  }
+  if (value.recoveryReceipt !== undefined) result.recoveryReceipt = field(value.recoveryReceipt, /^[a-f0-9]{64}$/);
+  return result;
+}
+
 function recordOf(value: unknown): MigrationRecord {
   if (!isRecord(value) || Object.keys(value).some((key) => !fields.includes(key))) throw unavailable();
   const phase = phases.find((item) => item === value.phase);
   const auth = auths.find((item) => item === value.auth);
-  if (phase === undefined || auth === undefined) throw unavailable();
+  if (phase === undefined || auth === undefined || (value.oauthResource !== undefined && auth !== 'oauth')) throw unavailable();
   return {
+    ...movementOf(value),
+    ...(value.oauthResource === undefined ? {} : { oauthResource: publicOAuthResource(value.oauthResource) }),
     id: requiredId(value.id), sourceId: requiredId(value.sourceId), agentId: requiredId(value.agentId),
     owner: field(value.owner, /^org_[A-Za-z0-9]{1,128}$/), keyId: field(value.keyId, DIGEST), sourceStamp: field(value.sourceStamp, DIGEST),
     name: field(value.name, /^.{1,200}$/), destinationId: value.destinationId === null ? null : requiredId(value.destinationId),

package/runtime/node_modules/@metro-labs/daemon/src/connectors/migration-url.ts

@@ -1,31 +1,8 @@
-import { BlockList, isIP } from 'node:net';
-import { parseConnectorUrl } from '@metro-labs/http/connector-url';
-
-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');
-
-function publicHost(host: string): boolean {
-  if (isIP(host) === 4) return !blocked.check(host, 'ipv4');
-  if (isIP(host) === 6) return globalV6.check(host, 'ipv6') && !blocked.check(host, 'ipv6');
-  const name = host.replace(/\.$/, '');
-  if (/(^|\.)(localhost|local|internal|lan|home|invalid|test|onion)$/.test(name)) return false;
-  return name.includes('.') && name.split('.').every((label) => /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(label));
-}
+import { parsePublicConnectorUrl } from '@metro-labs/http/connector-public-url';
 
 export function migrationOrigin(raw: unknown): string | null {
   try {
-    const url = parseConnectorUrl(raw);
-    if (url.protocol !== 'https:' || !publicHost(url.hostname.replace(/^\[|\]$/g, ''))) return null;
-    return url.origin;
+    return parsePublicConnectorUrl(raw).origin;
   } catch {
     return null;
   }

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

@@ -102,6 +102,7 @@ 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
       ? {}
@@ -156,7 +157,7 @@ export async function refreshOAuth(
     server,
     client,
     auth.refreshToken,
-    resource,
+    auth.resource ?? resource,
     auth.scope,
     send,
   );

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

@@ -327,8 +327,10 @@ function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Prom
   const running = inflight.get(key);
   if (running !== undefined) return running;
   const job = withLocalMigrationOperation(row.id, dir, async (operation) => {
-    const fresh = await refreshOAuth(auth, parseConnectorUrl(row.url).toString(), operation.fetch);
+    const fresh = await refreshOAuth(auth, parseConnectorUrl(row.url).toString(), (input, init) => operation.dispatch(() => fetch(input, init), { refresh: true }));
     updateRow(dir, row.id, { auth: fresh }, true);
+    flushMigrationSource(dir);
+    operation.persistedRefresh();
     return fresh;
   }).finally(() => { inflight.delete(key); });
   inflight.set(key, job);
@@ -369,11 +371,7 @@ async function oauthTarget(row: LocalConnectorRow, auth: OAuthAuth, force: boole
   }
 }
 
-export async function localRelayTarget(
-  connectorId: string,
-  force: boolean,
-  dir = agentsDir(),
-): Promise<RelayTarget> {
+export async function localRelayTarget(connectorId: string, force: boolean, dir = agentsDir()): Promise<RelayTarget> {
   return withLocalMigrationOperation(connectorId, dir, async (operation) => {
     const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
     if (row === undefined) return { kind: 'missing' };
@@ -385,11 +383,15 @@ export async function localRelayTarget(
   });
 }
 
-export function localRollbackMigrationSource(id: string, signOutOAuth: boolean, dir = agentsDir()): void {
-  if (migrationSource(id, dir)?.phase !== 'rollback' || !localMigrationIdle(id, dir)) throw new ConnectorError('The connector migration is not ready to roll back.', 409);
+export function localRollbackMigrationSource(id: string, signOutOAuth: boolean, dir = agentsDir(), discardUncertain = false): void {
+  if (!['rollback', 'recovering'].includes(migrationSource(id, dir)?.phase ?? '') || !localMigrationIdle(id, dir, discardUncertain && signOutOAuth)) throw new ConnectorError('The connector migration is not ready to roll back.', 409);
   const row = rowOrThrow(id, dir);
-  if (signOutOAuth && row.config.auth.kind === 'oauth') replace(dir, signedOut(row), true);
-  if (signOutOAuth) for (const path of [filePath(dir), dir]) {
+  if (signOutOAuth) replace(dir, signedOut(row), true);
+  if (signOutOAuth) flushMigrationSource(dir);
+}
+
+export function flushMigrationSource(dir = agentsDir()): void {
+  for (const path of [filePath(dir), dir]) {
     const fd = openSync(path, 'r');
     try { fsyncSync(fd); } finally { closeSync(fd); }
   }

package/runtime/node_modules/@metro-labs/http/package.json

@@ -14,13 +14,16 @@
     "./sigv4": "./src/sigv4.ts",
     "./agent-signature": "./src/agent-signature.ts",
     "./connector-url": "./src/connector-url.ts",
+    "./connector-public-url": "./src/connector-public-url.ts",
+    "./connector-resource": "./src/connector-resource.ts",
     "./connector-reach": "./src/connector-reach.ts",
     "./connector-mcp": "./src/connector-mcp.ts",
     "./connector-discovery": "./src/connector-discovery.ts",
     "./connector-oauth": "./src/connector-oauth.ts",
     "./connector-input": "./src/connector-input.ts",
     "./connector-delivery": "./src/connector-delivery.ts",
-    "./connector-migration": "./src/connector-migration.ts"
+    "./connector-migration": "./src/connector-migration.ts",
+    "./connector-grant": "./src/connector-grant.ts"
   },
   "scripts": {
     "build": "tsc",

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

@@ -2,7 +2,7 @@ import { parseId } from '@metro-labs/core/ids';
 import { isRecord } from '@metro-labs/core/is-record';
 import { connectorName } from './connector-input.js';
 import { connectorPolicyOf, type ConnectorPolicy } from './connector-policy.js';
-import { parseConnectorUrl } from './connector-url.js';
+import { parsePublicConnectorUrl } from './connector-public-url.js';
 import { isOrganizationId } from './workos-token.js';
 
 export const CONNECTOR_DELIVERY_LEASE_MS = 90_000;
@@ -85,8 +85,8 @@ function stateOf(value: unknown, auth: DeliveredConnector['auth']): DeliveredCon
 }
 
 function urlOf(value: unknown): string {
-  const url = parseConnectorUrl(value);
-  if (url.protocol !== 'https:' || url.toString().length > 2048 || typeof value !== 'string') throw new Error('Invalid delivered connector URL.');
+  parsePublicConnectorUrl(value);
+  if (typeof value !== 'string') throw new Error('Invalid delivered connector URL.');
   return value;
 }
 

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

@@ -0,0 +1,59 @@
+import { deliveryRecord } from './connector-delivery-validation.js';
+import type { OAuthAuth } from './connector-mcp.js';
+import { boundOAuthResource, parsePublicConnectorUrl } from './connector-public-url.js';
+
+export interface PortableGrant extends OAuthAuth {
+  resource: string;
+  tokenEndpointAuthMethod: 'none' | 'client_secret_post';
+}
+
+const invalid = (): never => { throw new Error('This OAuth grant cannot be transferred. Its client authentication or provider binding is unsupported. Sign in separately.'); };
+
+function text(raw: unknown, max = 16384): string {
+  if (typeof raw !== 'string' || raw.length === 0 || raw.length > max || /[^\x21-\x7e]/.test(raw)) return invalid();
+  return raw;
+}
+
+function endpoint(raw: unknown): string {
+  const value = text(raw, 2048);
+  parsePublicConnectorUrl(value);
+  return value;
+}
+
+export function grantResource(target: string, raw: unknown): string {
+  const transport = parsePublicConnectorUrl(target);
+  const resource = parsePublicConnectorUrl(raw);
+  if (resource.toString() === transport.toString() && typeof raw === 'string') return raw;
+  return boundOAuthResource(target, raw);
+}
+
+function binding(value: Record<string, unknown>): Pick<PortableGrant, 'clientId' | 'clientSecret' | 'tokenEndpointAuthMethod'> {
+  const clientSecret = value.clientSecret === undefined ? undefined : text(value.clientSecret);
+  const method = value.tokenEndpointAuthMethod ?? (clientSecret === undefined ? 'none' : 'client_secret_post');
+  if (method !== 'none' && method !== 'client_secret_post') return invalid();
+  if ((method === 'client_secret_post') !== (clientSecret !== undefined)) return invalid();
+  return { clientId: text(value.clientId), tokenEndpointAuthMethod: method, ...(clientSecret === undefined ? {} : { clientSecret }) };
+}
+
+function expiry(raw: unknown): Pick<PortableGrant, 'expiresAt'> {
+  if (raw === undefined) return {};
+  if (typeof raw !== 'number' || !Number.isSafeInteger(raw) || raw < 0) return invalid();
+  return { expiresAt: raw };
+}
+
+function scopeOf(raw: unknown): Pick<PortableGrant, 'scope'> {
+  if (raw === undefined) return {};
+  if (typeof raw !== 'string' || raw.length > 16384 || /[^\x20-\x7e]/.test(raw)) return invalid();
+  return { scope: raw };
+}
+
+export function portableGrant(raw: unknown, target: string): PortableGrant {
+  const value = deliveryRecord(raw, ['kind', 'accessToken', 'refreshToken', 'expiresAt', 'clientId', 'clientSecret', 'issuer', 'tokenEndpoint', 'scope', 'resource', 'tokenEndpointAuthMethod']);
+  if (value.kind !== 'oauth') return invalid();
+  return {
+    kind: 'oauth', accessToken: text(value.accessToken, 16377), issuer: endpoint(value.issuer), tokenEndpoint: endpoint(value.tokenEndpoint),
+    resource: grantResource(target, value.resource ?? parsePublicConnectorUrl(target).toString()),
+    ...binding(value), ...expiry(value.expiresAt), ...scopeOf(value.scope),
+    ...(value.refreshToken === undefined ? {} : { refreshToken: text(value.refreshToken) }),
+  };
+}

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

@@ -49,7 +49,7 @@ export function connectorAuth(
       400,
     );
   const name = header === '' ? DEFAULT_HEADER : header;
-  if (!HEADER_NAME_RE.test(name))
+  if (!HEADER_NAME_RE.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name))
     throw new ConnectorError('that is not a valid HTTP header name', 400);
   if (!HEADER_VALUE_RE.test(value))
     throw new ConnectorError('that header value is not sendable', 400);

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

@@ -17,6 +17,8 @@ export interface OAuthAuth extends OAuthTokens {
   clientId: string;
   clientSecret?: string;
   scope?: string;
+  resource?: string;
+  tokenEndpointAuthMethod?: string;
 }
 
 export type ConnectorAuth =

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

@@ -4,8 +4,9 @@ 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 { parseConnectorUrl } from './connector-url.js';
+import { boundOAuthResource, parsePublicConnectorUrl } from './connector-public-url.js';
 import { openTransfer, sealTransfer, type SealedTransfer } from './transfer-crypto.js';
 import { isOrganizationId } from './workos-token.js';
 
@@ -24,8 +25,9 @@ export interface MigrationContext {
 export interface MigrationPayload {
   name: string;
   url: string;
-  auth: { kind: 'none' } | { kind: 'header'; name: string; value: string } | { kind: 'oauth' };
+  auth: { kind: 'none' } | { kind: 'header'; name: string; value: string } | { kind: 'oauth'; grant?: PortableGrant };
   client: OAuthClient | null;
+  oauthResource?: string;
   policy: ConnectorPolicy;
   sourceStamp: string;
 }
@@ -35,7 +37,8 @@ export interface MigrationView {
   sourceId: string;
   destinationId: string;
   phase: 'preparing' | 'prepared' | 'active' | 'rolled_back';
-  readiness: 'pending' | 'ready' | 'signin' | 'changed' | 'unavailable';
+  readiness: 'pending' | 'ready' | 'signin' | 'changed' | 'unavailable' | 'refresh_uncertain';
+  grantImported?: boolean;
   name: string | null;
   auth: 'none' | 'header' | 'oauth' | null;
   policy: ConnectorPolicy | null;
@@ -47,7 +50,7 @@ export interface MigrationResponse {
   receiving?: { publicKey: string; context: MigrationContext };
 }
 
-export type MigrationRequest = { action: 'begin' | 'status' | 'activate' | 'rollback'; operationId: string; sourceId: string } | { action: 'prepare'; operationId: string; sourceId: string; sealed: unknown };
+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 => {
@@ -60,7 +63,7 @@ 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' && Object.hasOwn(value, 'sealed')) return { action: 'prepare', operationId, sourceId, sealed: value.sealed };
+  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 };
@@ -78,15 +81,19 @@ function contextBytes(context: MigrationContext): Buffer {
   return Buffer.from(JSON.stringify(['metro-connector-migration/v1', value.owner, value.agent, value.keyId, value.operationId, value.sourceId, value.destinationId]));
 }
 
-function authOf(raw: unknown): MigrationPayload['auth'] {
-  const value = deliveryRecord(raw, ['kind', 'name', 'value']);
-  if (value.kind === 'header') {
-    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 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();
-  return { kind: value.kind };
+  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 {
@@ -97,26 +104,20 @@ function clientOf(raw: unknown): OAuthClient | null {
   return client;
 }
 
-function canonicalResource(raw: unknown, url: URL): boolean {
-  return raw === `${url.origin}${url.pathname}` || (url.pathname === '/' && raw === url.origin);
-}
-
-function migrationClient(auth: MigrationPayload['auth'], url: URL, input: Record<string, unknown>): OAuthClient | null {
+function migrationClient(auth: MigrationPayload['auth'], input: Record<string, unknown>): OAuthClient | null {
   const client = clientOf(input.client);
-  if (auth.kind !== 'oauth' && client !== null) throw invalid();
-  if (auth.kind === 'oauth' && (url.search !== '' || !['/', '/mcp'].includes(url.pathname) || !canonicalResource(input.url, url))) throw invalid();
+  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', 'policy', 'sourceStamp']);
+  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();
-  const url = parseConnectorUrl(value.url);
-  if (url.protocol !== 'https:' || value.url.length > 2048) throw invalid();
+  parsePublicConnectorUrl(value.url);
   deliveryBytes(value.sourceStamp, 32);
-  const auth = authOf(value.auth);
-  const client = migrationClient(auth, url, value);
-  const payload = { name: value.name, url: value.url, auth, client, policy: connectorPolicyOf(value.policy), sourceStamp: value.sourceStamp };
+  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;
 }
@@ -127,7 +128,7 @@ function phaseOf(value: unknown): MigrationView['phase'] {
 }
 
 function readinessOf(value: unknown): MigrationView['readiness'] {
-  if (value !== 'pending' && value !== 'ready' && value !== 'signin' && value !== 'changed' && value !== 'unavailable') throw invalid();
+  if (value !== 'pending' && value !== 'ready' && value !== 'signin' && value !== 'changed' && value !== 'unavailable' && value !== 'refresh_uncertain') throw invalid();
   return value;
 }
 
@@ -150,8 +151,9 @@ function nullableStamp(value: unknown): string | null {
 }
 
 function viewOf(raw: unknown): MigrationView {
-  const view = deliveryRecord(raw, ['operationId', 'sourceId', 'destinationId', 'phase', 'readiness', 'name', 'auth', 'policy', 'sourceStamp']);
-  return { 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) };
+  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 {

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-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();
+}

package/runtime/runtime.json

@@ -1,3 +1,3 @@
 {
-  "version": "0.1.0-beta.290"
+  "version": "0.1.0-beta.292"
 }