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

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

@@ -1,5 +1,8 @@
 import { join } from 'node:path';
+import { closeSync, fsyncSync, openSync } from 'node:fs';
 import { publishLocalConnectors } from './publication.js';
+import { assertLocalMigrationEdit, localMigrationEnabled, localMigrationIdle, migrationSource, withLocalMigrationOperation } from './migration-guard.js';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
 import type { RelayTarget } from './relay-target.js';
 export type { RelayTarget } from './relay-target.js';
 import type { ToolPolicy } from '../policy/policy.js';
@@ -126,15 +129,16 @@ function rowOrThrow(id: string, dir: string): LocalConnectorRow {
   return row;
 }
 
-function replace(dir: string, row: LocalConnectorRow): Connector {
+function replace(dir: string, row: LocalConnectorRow, refresh = false): Connector {
+  if (!refresh) assertLocalMigrationEdit(row.id, row.name, dir);
   writeRows(dir, readLocalConnectors(dir).map((r) => (r.id === row.id ? row : r)));
   return connectorFromRow(row);
 }
 
-async function oauthCapable(url: URL, auth: ConnectorAuth): Promise<boolean> {
+async function oauthCapable(url: URL, auth: ConnectorAuth, send: FetchLike): Promise<boolean> {
   if (auth.kind === 'oauth') return true;
   if (auth.kind === 'header') return false;
-  return advertisesOAuth(url);
+  return advertisesOAuth(url, send);
 }
 
 export function localImportConnectors(
@@ -153,6 +157,7 @@ export function localImportConnectors(
     url: row.url,
     config: readConfig(row.config),
   }));
+  for (const row of imported) assertLocalMigrationEdit(row.id, row.name, dir);
   const ids = new Set(imported.map((r) => r.id));
   const names = new Set(imported.map((r) => r.name));
   writeRows(dir, [...current.filter((r) => !ids.has(r.id) && !names.has(r.name)), ...imported]);
@@ -173,6 +178,7 @@ function assertNameFree(name: string, exceptId: string | null, dir: string): voi
 }
 
 function insert(dir: string, name: string, url: URL, config: ConnectorConfig): Connector {
+  assertLocalMigrationEdit('', name, dir);
   assertNameFree(name, null, dir);
   const row: LocalConnectorRow = { id: newId(), name, url: connectorUrlText(url), config };
   writeRows(dir, [...readLocalConnectors(dir), row]);
@@ -184,14 +190,10 @@ export async function localCreateConnector(input: ConnectorInput, dir = agentsDi
   const url = parseConnectorUrl(input.url);
   const auth = connectorAuth(input.header, input.value);
   const client = connectorClient(input.clientId, input.clientSecret);
-  const verified = stamp(await verifyRemoteMcp(url, auth));
-  return insert(dir, name, url, {
-    auth,
-    createdAt: new Date().toISOString(),
-    verified,
-    oauth: await oauthCapable(url, auth),
-    client,
-  });
+  return withLocalMigrationOperation('', dir, async (operation) => {
+    const verified = stamp(await verifyRemoteMcp(url, auth, operation.fetch));
+    return insert(dir, name, url, { auth, createdAt: new Date().toISOString(), verified, oauth: await oauthCapable(url, auth, operation.fetch), client });
+  }, true, name);
 }
 
 export async function localCreatePendingConnector(input: PendingConnectorInput, dir = agentsDir()): Promise<Connector> {
@@ -208,9 +210,11 @@ export async function localReconnectConnector(
   auth: OAuthAuth,
   dir = agentsDir(),
 ): Promise<Connector> {
-  const row = rowOrThrow(id, dir);
-  const verified = stamp(await verifyRemoteMcp(parseConnectorUrl(row.url), auth));
-  return replace(dir, { ...row, config: { ...row.config, auth, verified, oauth: true } });
+  return withLocalMigrationOperation(id, dir, async (operation) => {
+    const row = rowOrThrow(id, dir);
+    const verified = stamp(await verifyRemoteMcp(parseConnectorUrl(row.url), auth, operation.fetch));
+    return replace(dir, { ...row, config: { ...row.config, auth, verified, oauth: true } });
+  }, true);
 }
 
 const signedOut = (row: LocalConnectorRow): LocalConnectorRow => ({ ...row, config: { ...row.config, auth: { kind: 'none' }, oauth: true } });
@@ -234,30 +238,34 @@ async function freshAuth(row: LocalConnectorRow, dir: string): Promise<Connector
   return refreshOnce(row, auth, dir);
 }
 
-function updateRow(dir: string, id: string, config: Partial<LocalConnectorRow['config']>): void {
+function updateRow(dir: string, id: string, config: Partial<LocalConnectorRow['config']>, refresh = false): void {
+  if (!refresh && migrationSource(id, dir) !== null) return;
   const now = readLocalConnectors(dir).find((r) => r.id === id);
-  if (now !== undefined) replace(dir, { ...now, config: { ...now.config, ...config } });
+  if (now !== undefined) replace(dir, { ...now, config: { ...now.config, ...config } }, refresh);
 }
 
 export async function localVerifyConnector(id: string, dir = agentsDir()): Promise<ConnectorCheck> {
-  const row = rowOrThrow(id, dir);
-  try {
-    const url = parseConnectorUrl(row.url);
-    const auth = await freshAuth(row, dir);
-    const verified = stamp(await verifyRemoteMcp(url, auth));
-    const oauth = row.config.oauth || (await oauthCapable(url, auth));
-    updateRow(dir, row.id, { auth, verified, oauth });
-    return { id: row.id, name: row.name, ok: true, verified };
-  } catch (err) {
-    if (!(err instanceof ConnectorVerifyError)) throw err;
-    return { id: row.id, name: row.name, ok: false, reason: err.message };
-  }
+  return withLocalMigrationOperation(id, dir, async (operation) => {
+    const row = rowOrThrow(id, dir);
+    try {
+      const url = parseConnectorUrl(row.url);
+      const auth = await freshAuth(row, dir);
+      const verified = stamp(await verifyRemoteMcp(url, auth, operation.fetch));
+      const oauth = row.config.oauth || (await oauthCapable(url, auth, operation.fetch));
+      updateRow(dir, row.id, { auth, verified, oauth });
+      return { id: row.id, name: row.name, ok: true, verified };
+    } catch (err) {
+      if (!(err instanceof ConnectorVerifyError)) throw err;
+      return { id: row.id, name: row.name, ok: false, reason: err.message };
+    }
+  });
 }
 
 const groupsOf = (tools: RemoteTool[]): Record<string, ToolGroup> =>
   Object.fromEntries(tools.map((tool) => [tool.name, tool.readOnly ? 'read' : 'write'] as const));
 
 function keepGroups(dir: string, id: string, tools: RemoteTool[]): void {
+  if (migrationSource(id, dir) !== null) return;
   const now = readLocalConnectors(dir).find((r) => r.id === id);
   const groups = groupsOf(tools);
   if (now === undefined || JSON.stringify(now.config.toolGroups ?? {}) === JSON.stringify(groups)) return;
@@ -267,11 +275,12 @@ function keepGroups(dir: string, id: string, tools: RemoteTool[]): void {
 }
 
 export async function localConnectorTools(id: string, dir = agentsDir()): Promise<RemoteTool[]> {
-  const row = rowOrThrow(id, dir);
-  const url = parseConnectorUrl(row.url);
-  const tools = await listRemoteTools(url, await freshAuth(row, dir));
-  keepGroups(dir, id, tools);
-  return tools;
+  return withLocalMigrationOperation(id, dir, async (operation) => {
+    const row = rowOrThrow(id, dir);
+    const tools = await listRemoteTools(parseConnectorUrl(row.url), await freshAuth(row, dir), operation.fetch);
+    keepGroups(dir, id, tools);
+    return tools;
+  });
 }
 
 async function refreshGroups(id: string, dir: string): Promise<void> {
@@ -294,7 +303,7 @@ export async function localSetConnectorPolicy(id: string, policy: ToolPolicy, di
 export async function loadConnectorPolicies(dir = agentsDir()): Promise<void> {
   const rows = readLocalConnectors(dir);
   publishLocalConnectors(rows);
-  for (const row of rows) if (row.config.policy !== undefined) await refreshGroups(row.id, dir);
+  for (const row of rows) if (row.config.policy !== undefined && localMigrationEnabled(row.id, dir)) await refreshGroups(row.id, dir);
 }
 
 export async function localRenameConnector(id: string, raw: string, dir = agentsDir()): Promise<Connector> {
@@ -306,6 +315,7 @@ export async function localRenameConnector(id: string, raw: string, dir = agents
 
 export async function localDeleteConnector(id: string, dir = agentsDir()): Promise<DeletedConnector> {
   const row = rowOrThrow(id, dir);
+  assertLocalMigrationEdit(id, row.name, dir);
   writeRows(dir, readLocalConnectors(dir).filter((r) => r.id !== id));
   return Promise.resolve({ id: row.id, name: row.name });
 }
@@ -313,17 +323,15 @@ export async function localDeleteConnector(id: string, dir = agentsDir()): Promi
 const inflight = new Map<string, Promise<OAuthAuth>>();
 
 function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Promise<OAuthAuth> {
-  const running = inflight.get(row.id);
+  const key = JSON.stringify([dir, row.id]);
+  const running = inflight.get(key);
   if (running !== undefined) return running;
-  const job = refreshOAuth(auth, parseConnectorUrl(row.url).toString())
-    .then((fresh) => {
-      updateRow(dir, row.id, { auth: fresh });
-      return fresh;
-    })
-    .finally(() => {
-      inflight.delete(row.id);
-    });
-  inflight.set(row.id, job);
+  const job = withLocalMigrationOperation(row.id, dir, async (operation) => {
+    const fresh = await refreshOAuth(auth, parseConnectorUrl(row.url).toString(), operation.fetch);
+    updateRow(dir, row.id, { auth: fresh }, true);
+    return fresh;
+  }).finally(() => { inflight.delete(key); });
+  inflight.set(key, job);
   return job;
 }
 
@@ -366,10 +374,23 @@ export async function localRelayTarget(
   force: boolean,
   dir = agentsDir(),
 ): Promise<RelayTarget> {
-  const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
-  if (row === undefined) return { kind: 'missing' };
-  parseConnectorUrl(row.url);
-  const auth = row.config.auth;
-  if (auth.kind === 'oauth') return oauthTarget(row, auth, force, dir);
-  return fixedTarget(row.url, auth, force);
+  return withLocalMigrationOperation(connectorId, dir, async (operation) => {
+    const row = readLocalConnectors(dir).find((r) => r.id === connectorId);
+    if (row === undefined) return { kind: 'missing' };
+    parseConnectorUrl(row.url);
+    const auth = row.config.auth;
+    const target = auth.kind === 'oauth' ? await oauthTarget(row, auth, force, dir) : fixedTarget(row.url, auth, force);
+    operation.check();
+    return target;
+  });
+}
+
+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);
+  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]) {
+    const fd = openSync(path, 'r');
+    try { fsyncSync(fd); } finally { closeSync(fd); }
+  }
 }

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

@@ -46,7 +46,8 @@ async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, st
   try {
     const send = fetchImpl ?? fetch;
     const res = await send(url.toString(), { method: 'DELETE', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS), headers: { ...authHeaders(auth), ...Object.fromEntries(session) } });
-    await res.body?.cancel();
+    if (res.ok) await res.body?.pipeTo(new WritableStream<Uint8Array>());
+    else await res.body?.cancel();
   } catch (err) {
     log.debug(fetchImpl === undefined ? { host: url.hostname, err: errMsg(err) } : {}, 'connector-tools: the remote declined to end the session');
   }

package/runtime/node_modules/@metro-labs/daemon/src/routes/local-mode.ts

@@ -16,6 +16,8 @@ import { loadedAgentOf, type AgentBundle, type BundleApiDeps } from '../agents/b
 import { METRO_VERSION } from '@metro-labs/core/version';
 import type { ConnectorApiDeps } from '../connectors/api.js';
 import { connectorMigrationPreview } from '../connectors/migration-preview.js';
+import { ConnectorMigrations } from '../connectors/migration-control.js';
+import { migrationExportableRows } from '../connectors/migration-guard.js';
 import { ConnectorTransfers } from '../connectors/transfer-api.js';
 import { copyConnectorRows } from '../connectors/transfer-store.js';
 import { authenticate } from '../mcp/request-identity.js';
@@ -162,7 +164,7 @@ function bundleApi(deps: LocalModeDeps): BundleApiDeps {
       const bundle: AgentBundle = {
         version: 1,
         agent: { id: file.id, name: file.name ?? '', stations: file.stations.filter((a) => a.station !== 'gmail' || a.config.managed !== true) },
-        connectors: readLocalConnectors().map((c) => ({ id: c.id, name: c.name, url: c.url, config: { ...c.config } })),
+        connectors: migrationExportableRows(readLocalConnectors()).map((c) => ({ id: c.id, name: c.name, url: c.url, config: { ...c.config } })),
       };
       return Promise.resolve(bundle);
     },
@@ -206,7 +208,8 @@ export function localSessionApis(deps: LocalModeDeps): SessionApis {
     bundleApi: bundleApi(deps),
     connectorApi,
     connectorSyncApi: { status: orgConnectorSyncStatus, set: setOrgConnectorSync },
-    connectorTransfers: new ConnectorTransfers({ read: readLocalConnectors, copy: copyConnectorRows }),
+    connectorMigrationApi: new ConnectorMigrations(),
+    connectorTransfers: new ConnectorTransfers({ read: () => migrationExportableRows(readLocalConnectors()), copy: copyConnectorRows }),
     enrollApi: { owner: () => localOwner(), invalidate: invalidateOrgConnectorSync },
     relayApi,
     claudeApi: { liveEvents: deps.liveEvents },

package/runtime/node_modules/@metro-labs/daemon/src/routes/session-apis.ts

@@ -9,6 +9,7 @@ import {
 import type { RelayApiDeps } from '../connectors/relay.js';
 import type { ConnectorTransfers } from '../connectors/transfer-api.js';
 import { handleConnectorSyncRequest, type ConnectorSyncApiDeps } from '../connectors/org-sync-api.js';
+import { handleMigrationRequest, type MigrationApiDeps } from '../connectors/migration-api.js';
 import { handleEnrollRequest, type EnrollApiDeps } from '../connectors/enroll-api.js';
 import { handleClaudeRequest, type ClaudeApiDeps } from '../claude/api.js';
 import type { ModeInfo } from '@metro-labs/http/mode-api';
@@ -41,6 +42,7 @@ export interface SessionApis {
   connectorTransfers?: ConnectorTransfers;
   enrollApi?: EnrollApiDeps;
   connectorSyncApi?: ConnectorSyncApiDeps;
+  connectorMigrationApi?: MigrationApiDeps;
   relayApi?: RelayApiDeps;
   mode?: () => ModeInfo;
 }
@@ -60,6 +62,7 @@ export function handleSessionApis(
     ...when(apis.connectorTransfers, (d) => d.handle(req, res)),
     ...when(apis.enrollApi, (d) => handleEnrollRequest(req, res, d)),
     ...when(apis.connectorSyncApi, (d) => handleConnectorSyncRequest(req, res, d)),
+    ...when(apis.connectorMigrationApi, (d) => handleMigrationRequest(req, res, d)),
     ...when(apis.connectorApi, (d) => handleConnectorApiRequest(req, res, d)),
     ...when(apis.bundleApi, (d) => handleBundleRequest(req, res, d)),
     ...when(apis.updateApi, (d) => handleUpdateRequest(req, res, d)),

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

@@ -19,7 +19,8 @@
     "./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-delivery": "./src/connector-delivery.ts",
+    "./connector-migration": "./src/connector-migration.ts"
   },
   "scripts": {
     "build": "tsc",

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

@@ -1,54 +1,19 @@
-import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, type KeyObject } from 'node:crypto';
-import { rawPublicKey, sealingKeyOf } from './agent-signature.js';
-import { CONNECTOR_DELIVERY_MAX_BYTES, DELIVERY_PLAINTEXT_MAX, deliveryBytes, deliveryContextBytes, deliveryRecord, deliverySnapshotOf, type DeliveryContext, type DeliverySnapshot } from './connector-delivery-validation.js';
+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 interface SealedDelivery {
-  version: 1;
-  ephemeralKey: string;
-  iv: string;
-  tag: string;
-  ciphertext: string;
-}
-
-function cipherKey(privateKey: KeyObject, publicKey: KeyObject, context: Buffer, ephemeral: string, recipient: string): Buffer {
-  const shared = diffieHellman({ privateKey, publicKey });
-  if (!shared.some((byte) => byte !== 0)) throw new Error('Invalid connector delivery key.');
-  return Buffer.from(hkdfSync('sha256', shared, Buffer.concat([deliveryBytes(ephemeral, 32), deliveryBytes(recipient, 32)]), context, 32));
-}
+export type SealedDelivery = SealedTransfer;
 
 export function sealConnectorDelivery(publicKey: string, context: DeliveryContext, snapshot: DeliverySnapshot): SealedDelivery {
-  const aad = deliveryContextBytes(context);
-  const recipient = sealingKeyOf(publicKey);
-  if (recipient === null) throw new Error('Invalid connector delivery key.');
-  const bytes = Buffer.from(JSON.stringify(deliverySnapshotOf(snapshot)));
-  const pair = generateKeyPairSync('x25519');
-  const ephemeralKey = rawPublicKey(pair.publicKey);
-  const iv = randomBytes(12);
-  const cipher = createCipheriv('aes-256-gcm', cipherKey(pair.privateKey, recipient, aad, ephemeralKey, publicKey), iv);
-  cipher.setAAD(aad);
-  const ciphertext = Buffer.concat([cipher.update(bytes), cipher.final()]).toString('base64url');
-  const sealed: SealedDelivery = { version: 1, ephemeralKey, iv: iv.toString('base64url'), tag: cipher.getAuthTag().toString('base64url'), ciphertext };
+  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 {
-  const aad = deliveryContextBytes(context);
-  if (privateKey.type !== 'private' || privateKey.asymmetricKeyType !== 'x25519') throw new Error('Invalid connector delivery key.');
   if (Buffer.byteLength(JSON.stringify({ sealed: envelope })) > CONNECTOR_DELIVERY_MAX_BYTES) throw new Error('Connector delivery is too large.');
-  const value = deliveryRecord(envelope, ['version', 'ephemeralKey', 'iv', 'tag', 'ciphertext']);
-  if (value.version !== 1 || typeof value.ephemeralKey !== 'string') throw new Error('Invalid connector delivery envelope.');
-  const ephemeral = sealingKeyOf(value.ephemeralKey);
-  if (ephemeral === null) throw new Error('Invalid connector delivery key.');
-  const ciphertext = deliveryBytes(value.ciphertext);
-  if (ciphertext.length > DELIVERY_PLAINTEXT_MAX) throw new Error('Connector delivery is too large.');
-  const key = cipherKey(privateKey, ephemeral, aad, value.ephemeralKey, rawPublicKey(createPublicKey(privateKey)));
-  const decipher = createDecipheriv('aes-256-gcm', key, deliveryBytes(value.iv, 12));
-  decipher.setAAD(aad);
-  decipher.setAuthTag(deliveryBytes(value.tag, 16));
-  const plaintext = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  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/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);
+}

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

@@ -40,6 +40,9 @@ const strictest = (...values: (ConnectorDecision | undefined)[]): ConnectorDecis
 
 export function combineConnectorPolicies(global: ConnectorPolicy, assignment: ConnectorPolicy): 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)),

package/runtime/node_modules/@metro-labs/http/src/transfer-crypto.ts

@@ -0,0 +1,44 @@
+import { createCipheriv, createDecipheriv, createPublicKey, diffieHellman, generateKeyPairSync, hkdfSync, randomBytes, type KeyObject } from 'node:crypto';
+import { rawPublicKey, sealingKeyOf } from './agent-signature.js';
+import { deliveryBytes, deliveryRecord } from './connector-delivery-validation.js';
+
+export interface SealedTransfer {
+  version: 1;
+  ephemeralKey: string;
+  iv: string;
+  tag: string;
+  ciphertext: string;
+}
+
+function cipherKey(privateKey: KeyObject, publicKey: KeyObject, context: Buffer, ephemeral: string, recipient: string): Buffer {
+  const shared = diffieHellman({ privateKey, publicKey });
+  if (!shared.some((byte) => byte !== 0)) throw new Error('Invalid connector transfer key.');
+  return Buffer.from(hkdfSync('sha256', shared, Buffer.concat([deliveryBytes(ephemeral, 32), deliveryBytes(recipient, 32)]), context, 32));
+}
+
+export function sealTransfer(publicKey: string, aad: Buffer, bytes: Buffer): SealedTransfer {
+  const recipient = sealingKeyOf(publicKey);
+  if (recipient === null) throw new Error('Invalid connector transfer key.');
+  const pair = generateKeyPairSync('x25519');
+  const ephemeralKey = rawPublicKey(pair.publicKey);
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', cipherKey(pair.privateKey, recipient, aad, ephemeralKey, publicKey), iv);
+  cipher.setAAD(aad);
+  const ciphertext = Buffer.concat([cipher.update(bytes), cipher.final()]).toString('base64url');
+  return { version: 1, ephemeralKey, iv: iv.toString('base64url'), tag: cipher.getAuthTag().toString('base64url'), ciphertext };
+}
+
+export function openTransfer(privateKey: KeyObject, aad: Buffer, envelope: unknown, maxBytes: number): Buffer {
+  if (privateKey.type !== 'private' || privateKey.asymmetricKeyType !== 'x25519') throw new Error('Invalid connector transfer key.');
+  const value = deliveryRecord(envelope, ['version', 'ephemeralKey', 'iv', 'tag', 'ciphertext']);
+  if (value.version !== 1 || typeof value.ephemeralKey !== 'string') throw new Error('Invalid connector transfer envelope.');
+  const ephemeral = sealingKeyOf(value.ephemeralKey);
+  if (ephemeral === null) throw new Error('Invalid connector transfer key.');
+  const ciphertext = deliveryBytes(value.ciphertext);
+  if (ciphertext.length > maxBytes) throw new Error('Connector transfer is too large.');
+  const key = cipherKey(privateKey, ephemeral, aad, value.ephemeralKey, rawPublicKey(createPublicKey(privateKey)));
+  const decipher = createDecipheriv('aes-256-gcm', key, deliveryBytes(value.iv, 12));
+  decipher.setAAD(aad);
+  decipher.setAuthTag(deliveryBytes(value.tag, 16));
+  return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+}

package/runtime/runtime.json

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

package/runtime/sdk-runner/runner.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.0-beta.289",
+  "version": "0.1.0-beta.290",
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.287",
     "@modelcontextprotocol/sdk": "^1.29.0",