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

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

@@ -0,0 +1,115 @@
+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 { isOrganizationId } from './workos-token.js';
+
+export const CONNECTOR_DELIVERY_LEASE_MS = 90_000;
+export const CONNECTOR_DELIVERY_MAX_BYTES = 1024 * 1024;
+export const DELIVERY_PLAINTEXT_MAX = Math.floor((CONNECTOR_DELIVERY_MAX_BYTES - 1024) * 3 / 4);
+
+export interface DeliveryContext {
+  owner: string;
+  agent: string;
+  keyId: string;
+  requestId: string;
+}
+
+export interface DeliveredConnector {
+  id: string;
+  name: string;
+  url: string;
+  auth: 'none' | 'header' | 'oauth';
+  headers: Record<string, string>;
+  policy: ConnectorPolicy;
+  revision: string;
+  state: 'ready' | 'signin' | 'unavailable';
+  expiresAt?: number;
+}
+
+export interface DeliverySnapshot {
+  version: 1;
+  issuedAt: number;
+  expiresAt: number;
+  connectors: DeliveredConnector[];
+}
+
+export function deliveryBytes(value: unknown, length?: number): Buffer {
+  if (typeof value !== 'string' || !/^[A-Za-z0-9_-]+$/.test(value)) throw new Error('Invalid connector delivery encoding.');
+  const bytes = Buffer.from(value, 'base64url');
+  if (bytes.toString('base64url') !== value || (length !== undefined && bytes.length !== length)) throw new Error('Invalid connector delivery encoding.');
+  return bytes;
+}
+
+export function deliveryRecord(value: unknown, fields: string[]): Record<string, unknown> {
+  if (!isRecord(value) || Object.keys(value).some((key) => !fields.includes(key))) throw new Error('Invalid connector delivery.');
+  return value;
+}
+
+export function deliveryContextBytes(context: DeliveryContext): Buffer {
+  const value = deliveryRecord(context, ['owner', 'agent', 'keyId', 'requestId']);
+  if (typeof value.owner !== 'string' || !isOrganizationId(value.owner) || parseId(value.agent) === null) throw new Error('Invalid connector delivery context.');
+  deliveryBytes(value.keyId, 32);
+  deliveryBytes(value.requestId, 32);
+  return Buffer.from(JSON.stringify(['metro-connector-delivery/v1', value.owner, value.agent, value.keyId, value.requestId]));
+}
+
+const timestamp = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+function headerValue(name: string, text: unknown, auth: DeliveredConnector['auth']): string {
+  if (!/^[A-Za-z0-9!#$%&'*+.^_`|~-]{1,64}$/.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name) || typeof text !== 'string' || !/^[\x20-\x7e]{1,16384}$/.test(text)) throw new Error('Invalid connector delivery headers.');
+  if (auth === 'oauth' && (name !== 'Authorization' || !/^Bearer [\x21-\x7e]+$/.test(text))) throw new Error('Invalid connector delivery access token.');
+  return text;
+}
+
+function headersOf(value: unknown, auth: DeliveredConnector['auth'], state: DeliveredConnector['state']): Record<string, string> {
+  if (!isRecord(value)) throw new Error('Invalid connector delivery headers.');
+  const entries = Object.entries(value);
+  const expected = auth !== 'none' && state === 'ready' ? 1 : 0;
+  if (entries.length !== expected) throw new Error('Invalid connector delivery headers.');
+  const out: Record<string, string> = {};
+  for (const [name, text] of entries) out[name] = headerValue(name, text, auth);
+  return out;
+}
+
+function authenticationOf(value: unknown): DeliveredConnector['auth'] {
+  if (value !== 'none' && value !== 'header' && value !== 'oauth') throw new Error('Invalid delivered connector authentication.');
+  return value;
+}
+
+function stateOf(value: unknown, auth: DeliveredConnector['auth']): DeliveredConnector['state'] {
+  if (value !== 'ready' && value !== 'signin' && value !== 'unavailable') throw new Error('Invalid delivered connector state.');
+  if (value === 'signin' && auth !== 'oauth') throw new Error('Invalid delivered connector state.');
+  return value;
+}
+
+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.');
+  return value;
+}
+
+function connectorOf(raw: unknown): DeliveredConnector {
+  const value = deliveryRecord(raw, ['id', 'name', 'url', 'auth', 'headers', 'policy', 'revision', 'state', 'expiresAt']);
+  const id = parseId(value.id);
+  if (id === null || typeof value.name !== 'string' || connectorName(value.name) !== value.name) throw new Error('Invalid delivered connector.');
+  const url = urlOf(value.url);
+  const auth = authenticationOf(value.auth);
+  const state = stateOf(value.state, auth);
+  deliveryBytes(value.revision, 32);
+  if (Object.hasOwn(value, 'expiresAt') && !timestamp(value.expiresAt)) throw new Error('Invalid delivered connector expiry.');
+  return { id, name: value.name, url, auth, state, revision: String(value.revision), headers: headersOf(value.headers, auth, state), policy: connectorPolicyOf(value.policy), ...(timestamp(value.expiresAt) ? { expiresAt: value.expiresAt } : {}) };
+}
+
+export function deliverySnapshotOf(raw: unknown): DeliverySnapshot {
+  const value = deliveryRecord(raw, ['version', 'issuedAt', 'expiresAt', 'connectors']);
+  if (value.version !== 1 || !timestamp(value.issuedAt) || !timestamp(value.expiresAt) || value.expiresAt <= value.issuedAt || value.expiresAt - value.issuedAt > CONNECTOR_DELIVERY_LEASE_MS || !Array.isArray(value.connectors)) throw new Error('Invalid connector delivery snapshot.');
+  const issuedAt = value.issuedAt;
+  const connectors = value.connectors.map((entry: unknown) => connectorOf(entry));
+  if (new Set(connectors.map((connector) => connector.id)).size !== connectors.length) throw new Error('Duplicate delivered connector.');
+  if (connectors.some((connector) => connector.state === 'ready' && connector.expiresAt !== undefined && connector.expiresAt <= issuedAt)) throw new Error('Expired delivered connector.');
+  const snapshot: DeliverySnapshot = { version: 1, issuedAt: value.issuedAt, expiresAt: value.expiresAt, connectors };
+  if (Buffer.byteLength(JSON.stringify(snapshot)) > DELIVERY_PLAINTEXT_MAX) throw new Error('Connector delivery is too large.');
+  return snapshot;
+}

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

@@ -0,0 +1,19 @@
+import type { KeyObject } from 'node:crypto';
+import { CONNECTOR_DELIVERY_MAX_BYTES, DELIVERY_PLAINTEXT_MAX, deliveryContextBytes, deliverySnapshotOf, type DeliveryContext, type DeliverySnapshot } from './connector-delivery-validation.js';
+import { openTransfer, sealTransfer, type SealedTransfer } from './transfer-crypto.js';
+
+export { CONNECTOR_DELIVERY_LEASE_MS, CONNECTOR_DELIVERY_MAX_BYTES, deliverySnapshotOf, type DeliveryContext, type DeliverySnapshot, type DeliveredConnector } from './connector-delivery-validation.js';
+export { combineConnectorPolicies, connectorPolicyOf, type ConnectorPolicy } from './connector-policy.js';
+export type SealedDelivery = SealedTransfer;
+
+export function sealConnectorDelivery(publicKey: string, context: DeliveryContext, snapshot: DeliverySnapshot): SealedDelivery {
+  const sealed = sealTransfer(publicKey, deliveryContextBytes(context), Buffer.from(JSON.stringify(deliverySnapshotOf(snapshot))));
+  if (Buffer.byteLength(JSON.stringify({ sealed })) > CONNECTOR_DELIVERY_MAX_BYTES) throw new Error('Connector delivery is too large.');
+  return sealed;
+}
+
+export function openConnectorDelivery(privateKey: KeyObject, context: DeliveryContext, envelope: unknown): DeliverySnapshot {
+  if (Buffer.byteLength(JSON.stringify({ sealed: envelope })) > CONNECTOR_DELIVERY_MAX_BYTES) throw new Error('Connector delivery is too large.');
+  const plaintext = openTransfer(privateKey, deliveryContextBytes(context), envelope, DELIVERY_PLAINTEXT_MAX);
+  return deliverySnapshotOf(JSON.parse(plaintext.toString('utf8')) as unknown);
+}

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

@@ -1,4 +1,7 @@
-import { ConnectorVerifyError, parseConnectorUrl } from './connector-verify.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { stringOf } from './api-http.js';
+import { parseConnectorUrl, refused } from './connector-url.js';
 
 const DISCOVERY_TIMEOUT_MS = 10_000;
 
@@ -8,23 +11,18 @@ 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> {
+async function getJson(url: URL, fetchImpl: FetchLike): Promise<Record<string, unknown> | null> {
   let res: Response;
   try {
-    res = await fetch(url, {
+    res = await fetchImpl(url.toString(), {
       redirect: 'manual',
       signal: AbortSignal.timeout(DISCOVERY_TIMEOUT_MS),
       headers: { accept: 'application/json' },
@@ -58,9 +56,9 @@ export function resourceMetadataUrls(resource: URL): URL[] {
   return urls;
 }
 
-export async function advertisesOAuth(resource: URL): Promise<boolean> {
+export async function advertisesOAuth(resource: URL, fetchImpl: FetchLike = fetch): Promise<boolean> {
   for (const candidate of resourceMetadataUrls(resource)) {
-    const body = await getJson(candidate);
+    const body = await getJson(candidate, fetchImpl);
     const servers: unknown = body?.authorization_servers;
     const first: unknown = Array.isArray(servers) ? servers[0] : undefined;
     if (typeof first === 'string' && first !== '') return true;
@@ -68,32 +66,64 @@ 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, fetchImpl: FetchLike): Promise<ResourceMetadata> {
   for (const candidate of resourceMetadataUrls(resource)) {
-    const body = await getJson(candidate);
+    const body = await getJson(candidate, fetchImpl);
     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: [] };
+}
+
+const webAddress = (text: string): boolean => {
+  try {
+    parseConnectorUrl(text);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+function endpointOf(raw: unknown, issuer: URL): string {
+  const text = stringOf(raw);
+  if (text !== '' && !webAddress(text)) throw refused(`${issuer.hostname} advertises a sign-in address Metro will not open.`);
+  return text;
 }
 
-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 = endpointOf(body.authorization_endpoint, issuer);
+  const tokenEndpoint = endpointOf(body.token_endpoint, issuer);
   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 offered = stringOf(body.registration_endpoint);
+  const registration = webAddress(offered) ? offered : '';
   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,
   };
 }
 
@@ -108,11 +138,11 @@ export function authServerMetadataUrls(issuer: URL): URL[] {
   return [...aware, new URL(`${path}/.well-known/openid-configuration`, issuer.origin), ...urls];
 }
 
-export async function discoverOAuth(resource: URL): Promise<OAuthServer> {
-  const issuer = await authServerFor(resource);
+export async function discoverOAuth(resource: URL, fetchImpl: FetchLike = fetch): Promise<OAuthServer> {
+  const { issuer, scopes } = await resourceMetadata(resource, fetchImpl);
   for (const candidate of authServerMetadataUrls(issuer)) {
-    const body = await getJson(candidate);
-    if (body !== null) return toServer(body, issuer);
+    const body = await getJson(candidate, fetchImpl);
+    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/http/src/connector-input.ts

@@ -0,0 +1,73 @@
+import { ApiError } from './api-error.js';
+import { stringOf } from './api-http.js';
+import type { ConnectorAuth } from './connector-mcp.js';
+import type { OAuthClient } from './connector-oauth.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 {}
+
+function hasControlChar(value: string): boolean {
+  for (const ch of value) {
+    const code = ch.codePointAt(0) ?? 0;
+    if (code < 0x20 || code === 0x7f) return true;
+  }
+  return false;
+}
+
+export function connectorName(raw: unknown): string {
+  const name = typeof raw === 'string' ? raw.trim() : '';
+  if (name === '') throw new ConnectorError('a connector needs a name', 400);
+  if (name.length > CONNECTOR_NAME_MAX)
+    throw new ConnectorError(
+      `a connector name must be ${String(CONNECTOR_NAME_MAX)} characters or fewer`,
+      400,
+    );
+  if (hasControlChar(name))
+    throw new ConnectorError(
+      'a connector name must not contain control characters',
+      400,
+    );
+  return name;
+}
+
+export function connectorAuth(
+  rawHeader: unknown,
+  rawValue: unknown,
+): ConnectorAuth {
+  const header = stringOf(rawHeader).trim();
+  const value = stringOf(rawValue).trim();
+  if (header === '' && value === '') return { kind: 'none' };
+  if (value === '')
+    throw new ConnectorError(
+      'that header has no value. Give both a header name and its value, or neither.',
+      400,
+    );
+  const name = header === '' ? DEFAULT_HEADER : header;
+  if (!HEADER_NAME_RE.test(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);
+  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 }) };
+}

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

@@ -0,0 +1,106 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { ApiError } from './api-error.js';
+import { whyUnreachable } from './connector-reach.js';
+import { ConnectorUnauthorized, refused } from './connector-url.js';
+
+export interface OAuthTokens {
+  accessToken: string;
+  refreshToken?: string;
+  expiresAt?: number;
+}
+
+export interface OAuthAuth extends OAuthTokens {
+  kind: 'oauth';
+  issuer: string;
+  tokenEndpoint: string;
+  clientId: string;
+  clientSecret?: string;
+  scope?: string;
+}
+
+export type ConnectorAuth =
+  | { kind: 'none' }
+  | { kind: 'header'; name: string; value: string }
+  | OAuthAuth;
+
+export interface VerifiedServer {
+  server: string;
+}
+
+export interface VerifiedRecord extends VerifiedServer {
+  at: string;
+}
+
+const PROBE_TIMEOUT_MS = 10_000;
+
+export const INITIALIZE = {
+  jsonrpc: '2.0',
+  id: 1,
+  method: 'initialize',
+  params: { protocolVersion: '2025-11-25', capabilities: {}, clientInfo: { name: 'metro', version: '0.1.0' } },
+};
+
+export function authHeaders(auth: ConnectorAuth): Record<string, string> {
+  if (auth.kind === 'header') return { [auth.name]: auth.value };
+  if (auth.kind === 'oauth') return { Authorization: `Bearer ${auth.accessToken}` };
+  return {};
+}
+
+export function payloadOf(text: string, contentType: string): string {
+  if (!contentType.includes('text/event-stream')) return text;
+  for (const line of text.replace(/\r\n/g, '\n').split('\n')) if (line.startsWith('data:')) return line.slice(5).trim();
+  return '';
+}
+
+export async function mcpPost(
+  url: URL,
+  auth: ConnectorAuth,
+  body: unknown,
+  opts: { timeoutMs: number; headers?: Record<string, string>; fetch?: FetchLike },
+): Promise<Response> {
+  const send = opts.fetch ?? fetch;
+  try {
+    return await send(url.toString(), {
+      method: 'POST',
+      redirect: 'manual',
+      signal: AbortSignal.timeout(opts.timeoutMs),
+      headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...authHeaders(auth), ...opts.headers },
+      body: JSON.stringify(body),
+    });
+  } catch (err) {
+    if (err instanceof ApiError) throw err;
+    throw refused(`Metro could not reach ${url.hostname}: ${whyUnreachable(err)}`);
+  }
+}
+
+function serverNameOf(url: URL, text: string, contentType: string): string {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(payloadOf(text, contentType));
+  } catch {
+    throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+  }
+  const result = isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+  if (result === null || typeof result.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
+  const info = isRecord(result.serverInfo) ? result.serverInfo : {};
+  const title = typeof info.title === 'string' ? info.title : '';
+  if (title !== '') return title;
+  return typeof info.name === 'string' ? info.name : url.hostname;
+}
+
+function refuseStatus(res: Response, url: URL, auth: ConnectorAuth): void {
+  if (res.status >= 300 && res.status < 400) throw refused('that url redirects. Use the url it redirects to.');
+  if (res.status === 401 || res.status === 403)
+    throw new ConnectorUnauthorized(auth.kind === 'none' ? `${url.hostname} requires authorization.` : `${url.hostname} rejected that credential.`, 400);
+  if (res.status === 404 || res.status === 405)
+    throw refused(`${url.hostname} did not accept an MCP initialize over HTTP POST. If it is a legacy SSE server, Metro cannot verify it yet.`);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)} instead of an MCP initialize.`);
+}
+
+export async function verifyRemoteMcp(url: URL, auth: ConnectorAuth, fetchImpl: FetchLike = fetch): Promise<VerifiedServer> {
+  const res = await mcpPost(url, auth, INITIALIZE, { timeoutMs: PROBE_TIMEOUT_MS, fetch: fetchImpl });
+  const text = await res.text().catch(() => '');
+  refuseStatus(res, url, auth);
+  return { server: serverNameOf(url, text, res.headers.get('content-type') ?? '') };
+}

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

@@ -0,0 +1,176 @@
+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 { connectorPolicyOf, type ConnectorPolicy } from './connector-policy.js';
+import { parseConnectorUrl } from './connector-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' };
+  client: OAuthClient | null;
+  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';
+  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'; 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' && Object.hasOwn(value, 'sealed')) return { action: 'prepare', 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 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;
+  }
+  if ((value.kind !== 'none' && value.kind !== 'oauth') || Object.hasOwn(value, 'name') || Object.hasOwn(value, 'value')) throw invalid();
+  return { kind: value.kind };
+}
+
+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 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 {
+  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();
+  return client;
+}
+
+export function migrationPayloadOf(raw: unknown): MigrationPayload {
+  const value = deliveryRecord(raw, ['name', 'url', 'auth', 'client', '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();
+  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 };
+  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') 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']);
+  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) };
+}
+
+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);
+}