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

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

@@ -0,0 +1,226 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+import { parseId } from '@metro-labs/core/ids';
+import { ensureSecureDir, writeSecure } from '@metro-labs/core/secure-fs';
+import { ApiError } from '@metro-labs/http/api-error';
+import { agentsDir } from '../agents/files.js';
+
+interface RequestOperation {
+  id: string;
+  source: string;
+  dir: string;
+  lease: string;
+  durable: boolean;
+  abandoned: boolean;
+  refresh: boolean;
+}
+
+interface PassiveListener {
+  idle: () => boolean;
+  stop: () => void;
+}
+
+export interface MigrationOperation {
+  passiveListener: (listener: PassiveListener) => void;
+  dispatch: (send: () => Promise<Response>, options?: { protectedSource?: boolean; effectful?: boolean; refresh?: boolean }) => Promise<Response>;
+  close: () => void;
+  persistedRefresh: () => void;
+}
+
+const leases = new Map<string, Set<string>>();
+const listeners = new Map<string, PassiveListener>();
+const requests = new Map<string, RequestOperation>();
+const held = new Map<string, RequestOperation>();
+const keyOf = (source: string, dir: string): string => JSON.stringify([resolve(dir), source]);
+const unavailable = (): ApiError => new ApiError('Protected connector request records cannot be read. Restore their files before using this connector.', 503);
+const uncertain = (): ApiError => new ApiError('A previous connector request has an unknown outcome. Inspect the vendor and acknowledge it before continuing. Do not retry the tool.', 409);
+const CONTROL = new Set(['initialize', 'ping', 'tools/list', 'notifications/initialized', 'notifications/cancelled']);
+
+export function migrationRequestEffectful(method: string | undefined, body: unknown): boolean {
+  const verb = (method ?? 'GET').toUpperCase();
+  if (['GET', 'HEAD', 'DELETE'].includes(verb)) return false;
+  if (verb !== 'POST') return true;
+  const text = typeof body === 'string' ? body : body instanceof Uint8Array ? new TextDecoder().decode(body) : null;
+  if (text === null) return true;
+  try {
+    const value: unknown = JSON.parse(text);
+    const batch: unknown[] = Array.isArray(value) ? value : [value];
+    return batch.length === 0 || batch.some((item) => !isRecord(item) || item.jsonrpc !== '2.0' || typeof item.method !== 'string' || !CONTROL.has(item.method));
+  } catch { return true; }
+}
+
+function paths(source: string, dir: string): { data: string; marker: string } {
+  if (parseId(source) === null) throw unavailable();
+  const data = join(dir, `connector-migration-operations-${source}.json`);
+  return { data, marker: `${data}.initialized` };
+}
+
+function flush(path: string): void {
+  const fd = openSync(path, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function pendingOf(text: string): string[] {
+  const value: unknown = JSON.parse(text);
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.pending) || value.pending.length > 10_000) throw unavailable();
+  const ids: unknown[] = value.pending;
+  if (!ids.every((id): id is string => typeof id === 'string' && /^r?[a-f0-9]{32}$/.test(id))) throw unavailable();
+  if (new Set(ids).size !== ids.length) throw unavailable();
+  return ids;
+}
+
+function readPending(source: string, dir: string, initialize = false): string[] {
+  const { data, marker } = paths(source, dir);
+  try {
+    if (initialize && !existsSync(data) && !existsSync(marker)) return [];
+    if (readFileSync(marker, 'utf8') !== '1\n') throw unavailable();
+    return pendingOf(readFileSync(data, 'utf8'));
+  } catch { throw unavailable(); }
+}
+
+function writePending(source: string, dir: string, pending: string[]): void {
+  const { data, marker } = paths(source, dir);
+  ensureSecureDir(dir);
+  if (!existsSync(marker)) {
+    writeFileSync(marker, '1\n', { flag: 'wx', mode: 0o600 });
+    flush(marker);
+    flush(dir);
+  }
+  writeSecure(data, `${JSON.stringify({ version: 1, pending })}\n`);
+  flush(data);
+  flush(dir);
+}
+
+export function captureMigrationOperations(source: string, dir: string, initialize: boolean): void {
+  const pending = new Set(readPending(source, dir, initialize));
+  const active = [...held.values()].filter((request) => keyOf(request.source, request.dir) === keyOf(source, dir));
+  for (const request of active) pending.add(request.id);
+  writePending(source, dir, [...pending]);
+  for (const request of active) request.durable = true;
+}
+
+export function migrationUncertaintyReceipt(source: string, dir = agentsDir()): string | null {
+  const unknown = readPending(source, dir).filter((id) => !requests.has(id)).sort();
+  return unknown.length === 0 ? null : createHash('sha256').update(JSON.stringify([1, source, unknown])).digest('hex');
+}
+
+export function assertMigrationOutcomeKnown(source: string, dir = agentsDir()): void {
+  if (migrationUncertaintyReceipt(source, dir) !== null) throw uncertain();
+}
+
+export function drainMigrationListeners(source: string, dir: string): void {
+  const active = [...(leases.get(keyOf(source, dir)) ?? [])];
+  if (active.length === 0 || active.some((lease) => listeners.get(lease)?.idle() !== true)) return;
+  if (readPending(source, dir).some((id) => requests.has(id))) return;
+  for (const lease of active) {
+    const listener = listeners.get(lease);
+    listeners.delete(lease);
+    listener?.stop();
+  }
+}
+
+export function migrationOperationsIdle(source: string, dir: string, protectedSource: boolean): boolean {
+  if (leases.has(keyOf(source, dir))) return false;
+  return !protectedSource || readPending(source, dir).length === 0;
+}
+
+export function resolveMigrationUncertainty(source: string, expectedReceipt: string, dir = agentsDir()): boolean {
+  if (leases.has(keyOf(source, dir))) return false;
+  const receipt = migrationUncertaintyReceipt(source, dir);
+  if (receipt === null || receipt !== expectedReceipt) return false;
+  writePending(source, dir, []);
+  return true;
+}
+
+function finish(request: RequestOperation, completed: boolean, persisted = false): void {
+  if (request.refresh && completed && !persisted) return;
+  if (request.abandoned) return;
+  requests.delete(request.id);
+  if (completed) held.delete(request.id);
+  if (completed && request.durable) writePending(request.source, request.dir, readPending(request.source, request.dir).filter((id) => id !== request.id));
+  request.abandoned = true;
+}
+
+function observed(response: Response, request: RequestOperation): Response {
+  if (response.status === 401 || response.status === 403) {
+    finish(request, true);
+    return response;
+  }
+  if (response.body === null) {
+    finish(request, response.ok);
+    return response;
+  }
+  const reader = response.body.getReader();
+  const body = new ReadableStream<Uint8Array>({
+    async pull(controller) {
+      try {
+        const result = await reader.read();
+        if (result.done) {
+          finish(request, response.ok);
+          controller.close();
+        } else controller.enqueue(result.value);
+      } catch (error) {
+        finish(request, false);
+        controller.error(error);
+      }
+    },
+    async cancel(reason: unknown) {
+      finish(request, false);
+      await reader.cancel(reason);
+    },
+  });
+  return new Response(body, { status: response.status, statusText: response.statusText, headers: response.headers });
+}
+
+async function dispatch(source: string, dir: string, lease: string, protectedSource: boolean, effectful: boolean, refresh: boolean, send: () => Promise<Response>): Promise<Response> {
+  if (protectedSource) assertMigrationOutcomeKnown(source, dir);
+  if (!effectful) return send();
+  const request: RequestOperation = { id: `${refresh ? 'r' : ''}${randomBytes(16).toString('hex')}`, source, dir, lease, durable: false, abandoned: false, refresh };
+  if (protectedSource) {
+    const pending = readPending(source, dir);
+    if (pending.length >= 10_000) throw unavailable();
+    writePending(source, dir, [...pending, request.id]);
+    request.durable = true;
+  }
+  requests.set(request.id, request);
+  held.set(request.id, request);
+  try { return observed(await send(), request); }
+  catch (error) { finish(request, false); throw error; }
+}
+
+export function beginMigrationOperation(source: string, dir: string, protectedSource: boolean): MigrationOperation {
+  if (protectedSource) assertMigrationOutcomeKnown(source, dir);
+  const key = keyOf(source, dir);
+  const lease = randomBytes(16).toString('hex');
+  const active = leases.get(key) ?? new Set<string>();
+  active.add(lease);
+  leases.set(key, active);
+  let closed = false;
+  return {
+    passiveListener: (listener) => { if (!closed) listeners.set(lease, listener); },
+    dispatch: (send, options = {}) => {
+      if (closed) return Promise.reject(uncertain());
+      return dispatch(source, dir, lease, options.protectedSource ?? protectedSource, options.effectful ?? true, options.refresh ?? false, send);
+    },
+    persistedRefresh: () => {
+      for (const request of held.values()) if (request.lease === lease && request.refresh) finish(request, true, true);
+    },
+    close: () => {
+      if (closed) return;
+      closed = true;
+      listeners.delete(lease);
+      for (const request of held.values()) if (request.lease === lease) {
+        finish(request, false);
+        held.delete(request.id);
+      }
+      active.delete(lease);
+      if (active.size === 0) leases.delete(key);
+    },
+  };
+}
+
+export function migrationRefreshUncertain(source: string, dir = agentsDir()): boolean {
+  return readPending(source, dir).some((id) => id.startsWith('r') && !requests.has(id));
+}

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

@@ -0,0 +1,235 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { parseId } from '@metro-labs/core/ids';
+import { isRecord } from '@metro-labs/core/is-record';
+import { ApiError } from '@metro-labs/http/api-error';
+import { bodyField } from '@metro-labs/http/api-http';
+import { connectorAuth, connectorClient, connectorName } from '@metro-labs/http/connector-input';
+import { portableGrant } from '@metro-labs/http/connector-grant';
+import { connectorPolicyOf } from '@metro-labs/http/connector-delivery';
+import { readConfig } from './config.js';
+import type { LocalConnectorRow } from './store.js';
+import { agentsDir } from '../agents/files.js';
+import { normalizePolicy, type ToolPolicy } from '../policy/policy.js';
+import { connectorSyncScope, syncOptedIn, syncSetting } from './org-sync-setting.js';
+import { readAgentKey } from './agent-key.js';
+import { MigrationBlocked } from './migration-source.js';
+import { migrationOrigin } from './migration-url.js';
+
+export type MigrationIssue = 'invalid_config' | 'unsupported_url' | 'custom_policy' | 'oauth_sign_in' | 'header_reentry' | 'unused_oauth_client' | 'oauth_unsupported';
+
+export interface MigrationConnector {
+  id: string;
+  name: string;
+  auth: 'none' | 'header' | 'oauth' | 'invalid';
+  origin: string | null;
+  policy: ToolPolicy;
+  policySupported: boolean;
+  issues: MigrationIssue[];
+}
+
+export interface ConnectorMigrationPreview {
+  migrationSupported: true;
+  oauthResourceSupported: true;
+  moveAllSupported: true;
+  enabled: boolean;
+  enrolled: boolean;
+  agentId: string | null;
+  owner: string | null;
+  liveEnabled: boolean;
+  connectors: MigrationConnector[];
+}
+
+const invalid = (): never => { throw new Error('Invalid local connector configuration.'); };
+const onlyKeys = (raw: Record<string, unknown>, keys: readonly string[]): boolean => Object.keys(raw).every((key) => keys.includes(key));
+const nonempty = (value: unknown): value is string => typeof value === 'string' && value.trim() !== '';
+
+function optionalStrings(raw: Record<string, unknown>, keys: readonly string[]): boolean {
+  return keys.every((key) => raw[key] === undefined || typeof raw[key] === 'string');
+}
+
+function validClient(raw: unknown): boolean {
+  if (raw === undefined || raw === null) return true;
+  if (!isRecord(raw) || !onlyKeys(raw, ['clientId', 'clientSecret'])) return false;
+  if (!nonempty(raw.clientId) || !optionalStrings(raw, ['clientSecret'])) return false;
+  const client = connectorClient(raw.clientId, raw.clientSecret);
+  return client !== null && client.clientId === raw.clientId && client.clientSecret === raw.clientSecret;
+}
+
+function oauthAuth(raw: Record<string, unknown>): 'oauth' {
+  if (!onlyKeys(raw, ['kind', 'accessToken', 'refreshToken', 'clientId', 'clientSecret', 'tokenEndpoint', 'issuer', 'scope', 'expiresAt', 'resource', 'tokenEndpointAuthMethod'])) invalid();
+  return 'oauth';
+}
+
+function headerAuth(raw: Record<string, unknown>): 'header' {
+  if (raw.kind !== 'header' || !onlyKeys(raw, ['kind', 'name', 'value'])) return invalid();
+  if (!nonempty(raw.name) || !nonempty(raw.value)) return invalid();
+  const auth = connectorAuth(raw.name, raw.value);
+  return auth.kind === 'header' && auth.name === raw.name && auth.value === raw.value ? 'header' : invalid();
+}
+
+function authKind(raw: unknown): Exclude<MigrationConnector['auth'], 'invalid'> {
+  if (!isRecord(raw)) return invalid();
+  if (raw.kind === 'oauth') return oauthAuth(raw);
+  if (raw.kind === 'none' && onlyKeys(raw, ['kind'])) return 'none';
+  return headerAuth(raw);
+}
+
+function metadataValid(config: Record<string, unknown>): boolean {
+  if (!optionalStrings(config, ['createdAt'])) return false;
+  const verified = config.verified;
+  if (verified !== undefined && (!isRecord(verified) || !optionalStrings(verified, ['at', 'server']))) return false;
+  if (config.oauth !== undefined && typeof config.oauth !== 'boolean') return false;
+  const groups = config.toolGroups;
+  if (groups === undefined) return true;
+  if (!isRecord(groups) || Object.keys(groups).length > 1000) return false;
+  return Object.entries(groups).every(([name, group]) => name.length > 0 && name.length <= 128 && (group === 'read' || group === 'write'));
+}
+
+function configAuth(config: unknown): MigrationConnector['auth'] {
+  try {
+    if (!isRecord(config) || !onlyKeys(config, ['auth', 'oauth', 'client', 'createdAt', 'verified', 'policy', 'toolGroups'])) return 'invalid';
+    if (!metadataValid(config) || !validClient(config.client)) return 'invalid';
+    const kind = authKind(config.auth);
+    if (kind === 'header' && config.oauth === true) return 'invalid';
+    return kind === 'none' && config.oauth === true ? 'oauth' : kind;
+  } catch {
+    return 'invalid';
+  }
+}
+
+function policyShape(raw: Record<string, unknown>): boolean {
+  if (!onlyKeys(raw, ['read', 'write', 'tools'])) return false;
+  for (const key of ['read', 'write']) if (Object.hasOwn(raw, key) && typeof raw[key] !== 'string') return false;
+  return raw.tools === undefined || (isRecord(raw.tools) && Object.values(raw.tools).every((value) => typeof value === 'string'));
+}
+
+function strictPolicy(raw: unknown): ToolPolicy {
+  if (raw === undefined) return {};
+  if (!isRecord(raw) || !policyShape(raw)) return invalid();
+  const policy = normalizePolicy(raw);
+  if (isRecord(raw.tools)) {
+    policy.tools = Object.fromEntries(Object.entries(raw.tools).map(([name, value]) => {
+      const { read } = normalizePolicy({ read: value });
+      if (read === undefined) return invalid();
+      return [name, read];
+    }));
+  }
+  return policy;
+}
+
+function policyPreview(raw: unknown): Pick<MigrationConnector, 'policy' | 'policySupported'> & { valid: boolean } {
+  try {
+    const policy = strictPolicy(raw);
+    let policySupported = false;
+    try {
+      connectorPolicyOf(policy);
+      policySupported = true;
+    } catch {
+      policySupported = false;
+    }
+    return { policy, policySupported, valid: true };
+  } catch {
+    return { policy: {}, policySupported: false, valid: false };
+  }
+}
+
+function nameOf(raw: unknown): string | null {
+  try {
+    return connectorName(raw);
+  } catch {
+    return null;
+  }
+}
+
+function rowIdentity(row: Record<string, unknown>, index: number): { id: string; name: string; valid: boolean } {
+  const id = parseId(row.id);
+  const name = nameOf(row.name);
+  return { id: id ?? `invalid-${String(index + 1)}`, name: name ?? `Connector ${String(index + 1)}`, valid: id !== null && name !== null };
+}
+
+function grantIssues(row: Record<string, unknown>): MigrationIssue[] {
+  const grant = bodyField(row.config, 'auth');
+  if (!isRecord(grant) || grant.kind !== 'oauth') return ['oauth_sign_in'];
+  try {
+    const portable = portableGrant(grant, String(row.url));
+    return portable.expiresAt !== undefined && portable.expiresAt <= Date.now() && portable.refreshToken === undefined ? ['oauth_sign_in'] : [];
+  } catch { return ['oauth_unsupported']; }
+}
+
+function authIssues(row: Record<string, unknown>, auth: MigrationConnector['auth']): MigrationIssue[] {
+  if (auth === 'oauth') return grantIssues(row);
+  const client = bodyField(row.config, 'client');
+  return (auth === 'none' || auth === 'header') && client !== undefined && client !== null ? ['unused_oauth_client'] : [];
+}
+
+function previewRow(raw: unknown, index: number): MigrationConnector {
+  const row = isRecord(raw) ? raw : {};
+  const identity = rowIdentity(row, index);
+  const auth = configAuth(row.config);
+  const { policy, policySupported, valid } = policyPreview(bodyField(row.config, 'policy'));
+  const origin = migrationOrigin(row.url);
+  const issues: MigrationIssue[] = [];
+  if (!identity.valid || auth === 'invalid' || !valid) issues.push('invalid_config');
+  if (origin === null) issues.push('unsupported_url');
+  if (valid && !policySupported) issues.push('custom_policy');
+  issues.push(...authIssues(row, auth));
+  return { id: identity.id, name: identity.name, auth, origin, policy, policySupported, issues };
+}
+
+const unavailable = (): ApiError => new ApiError('Local connector configuration cannot be previewed. Restore its file or permissions first.', 503);
+
+function readRows(dir: string): unknown[] {
+  let text: string;
+  try {
+    text = readFileSync(join(dir, 'connectors.json'), 'utf8');
+  } catch (err) {
+    if (isRecord(err) && err.code === 'ENOENT') return [];
+    throw unavailable();
+  }
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch {
+    throw unavailable();
+  }
+  if (!isRecord(raw) || raw.version !== 1 || !Array.isArray(raw.connectors)) throw unavailable();
+  return raw.connectors;
+}
+
+function previewRows(dir: string): MigrationConnector[] {
+  const rows = readRows(dir).map(previewRow);
+  const seen = new Map<string, MigrationConnector>();
+  for (const row of rows) {
+    const prior = seen.get(row.id);
+    if (prior !== undefined) {
+      for (const duplicate of [prior, row]) if (!duplicate.issues.includes('invalid_config')) duplicate.issues.push('invalid_config');
+    }
+    seen.set(row.id, row);
+  }
+  return rows;
+}
+
+function assertTransferable(source: MigrationConnector): void {
+  if (source.issues.includes('oauth_sign_in')) throw new MigrationBlocked('sign_in', 'No usable local OAuth grant is saved. Sign in locally before moving it.');
+  if (source.issues.includes('oauth_unsupported')) throw new MigrationBlocked('unsupported_grant', 'This OAuth grant has unsupported client authentication or provider binding. Keep it local or sign in separately.');
+}
+
+export function migrationSource(id: string, dir = agentsDir(), transfer = false): LocalConnectorRow {
+  const source = previewRows(dir).find((row) => row.id === id);
+  if (source === undefined) throw new ApiError('The local connector is missing.', 404);
+  if (source.issues.some((issue) => issue !== 'oauth_sign_in' && issue !== 'oauth_unsupported')) throw new ApiError('This connector cannot be migrated without changing its settings or permissions. Resolve the preview blockers first.', 409);
+  if (transfer) assertTransferable(source);
+  const raw = readRows(dir).find((row) => isRecord(row) && row.id === id);
+  if (!isRecord(raw) || typeof raw.url !== 'string') throw unavailable();
+  return { id, name: source.name, url: raw.url, config: { ...readConfig(raw.config), oauth: source.auth === 'oauth', policy: source.policy } };
+}
+
+export function connectorMigrationPreview(owner: string | null, dir = agentsDir()): ConnectorMigrationPreview {
+  const enabled = syncOptedIn(dir) && syncSetting(dir, connectorSyncScope(owner, readAgentKey(dir))).enabled;
+  const liveEnabled = process.env.METRO_CONNECTORS_LIVE_ENABLED === 'true';
+  if (!enabled) return { migrationSupported: true, oauthResourceSupported: true, moveAllSupported: true, enabled, enrolled: false, agentId: null, owner, liveEnabled, connectors: [] };
+  const enrollment = owner === null ? null : readAgentKey(dir)?.enrollment;
+  const agentId = enrollment?.organization === owner ? enrollment?.server ?? null : null;
+  return { migrationSupported: true, oauthResourceSupported: true, moveAllSupported: true, enabled, enrolled: agentId !== null, agentId, owner, liveEnabled, connectors: previewRows(dir) };
+}

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

@@ -0,0 +1,42 @@
+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 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 = 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 {
+  const policy = value.policy;
+  const canonical = {
+    ...value,
+    policy: { read: policy.read ?? 'allow', write: policy.write ?? 'allow', tools: Object.entries(policy.tools ?? {}).sort(([a], [b]) => a.localeCompare(b)) },
+  };
+  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

@@ -0,0 +1,142 @@
+import { randomBytes } from 'node:crypto';
+import { closeSync, existsSync, fsyncSync, openSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { isRecord } from '@metro-labs/core/is-record';
+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 = 'recovering' | 'freezing' | 'preparing' | 'prepared' | 'cutover' | 'active' | 'rollback' | 'rolled_back';
+export type MigrationAuth = 'none' | 'header' | 'oauth';
+
+export interface MigrationRecord {
+  id: string;
+  owner: string;
+  agentId: string;
+  keyId: string;
+  sourceId: string;
+  name: string;
+  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[] = ['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', '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');
+const markerOf = (dir: string): string => join(dir, 'connector-migrations.initialized');
+
+function requiredId(value: unknown): string {
+  const id = parseId(value);
+  if (id === null) throw unavailable();
+  return id;
+}
+
+function field(value: unknown, pattern: RegExp): string {
+  if (typeof value !== 'string' || !pattern.test(value)) throw unavailable();
+  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 || (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),
+    phase, auth, policy: connectorPolicyOf(value.policy), reason: value.reason === null ? null : field(value.reason, /^[a-z_]{1,64}$/),
+  };
+}
+
+function recordsOf(text: string): MigrationRecord[] {
+  const value: unknown = JSON.parse(text);
+  if (!isRecord(value) || value.version !== 1 || !Array.isArray(value.records) || value.records.length > 500) throw unavailable();
+  const records = value.records.map(recordOf);
+  if (new Set(records.map((record) => record.sourceId)).size !== records.length) throw unavailable();
+  return records;
+}
+
+export function migrationRecords(dir = agentsDir()): MigrationRecord[] {
+  try {
+    const marked = existsSync(markerOf(dir));
+    if (marked && readFileSync(markerOf(dir), 'utf8') !== '1\n') throw unavailable();
+    if (!existsSync(pathOf(dir))) {
+      if (marked) throw unavailable();
+      return [];
+    }
+    if (!marked) throw unavailable();
+    return recordsOf(readFileSync(pathOf(dir), 'utf8'));
+  } catch {
+    throw unavailable();
+  }
+}
+
+export function migrationRecord(id: string, dir = agentsDir()): MigrationRecord | null {
+  return migrationRecords(dir).find((record) => record.sourceId === id) ?? null;
+}
+
+function flush(path: string): void {
+  const fd = openSync(path, 'r');
+  try { fsyncSync(fd); } finally { closeSync(fd); }
+}
+
+function markInitialized(dir: string): void {
+  const path = markerOf(dir);
+  if (existsSync(path)) return;
+  writeFileSync(path, '1\n', { flag: 'wx', mode: 0o600 });
+  flush(path);
+  flush(dir);
+}
+
+export function saveMigration(record: MigrationRecord, dir = agentsDir()): void {
+  const valid = recordOf(record);
+  const previous = migrationRecords(dir);
+  const rows = previous.filter((row) => row.sourceId !== valid.sourceId);
+  if (rows.length >= 500) throw new ApiError('There are too many connector migrations on this agent.', 409);
+  rows.push(valid);
+  ensureSecureDir(dir);
+  markInitialized(dir);
+  captureMigrationOperations(valid.sourceId, dir, !previous.some((row) => row.sourceId === valid.sourceId));
+  const path = pathOf(dir);
+  const temporary = `${path}.${randomBytes(12).toString('hex')}.tmp`;
+  const fd = openSync(temporary, 'wx', 0o600);
+  try {
+    try {
+      writeFileSync(fd, `${JSON.stringify({ version: 1, records: rows })}\n`);
+      fsyncSync(fd);
+    } finally { closeSync(fd); }
+    renameSync(temporary, path);
+    flush(dir);
+  } finally { rmSync(temporary, { force: true }); }
+}

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

@@ -0,0 +1,9 @@
+import { parsePublicConnectorUrl } from '@metro-labs/http/connector-public-url';
+
+export function migrationOrigin(raw: unknown): string | null {
+  try {
+    return parsePublicConnectorUrl(raw).origin;
+  } catch {
+    return null;
+  }
+}