@stage-labs/metro 0.1.0-beta.286 → 0.1.0-beta.288

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

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
-import { syncPluginServers } from './plugin-sync.js';
-import { registerConnectors } from './gates.js';
+import { publishLocalConnectors } from './publication.js';
+import type { RelayTarget } from './relay-target.js';
+export type { RelayTarget } from './relay-target.js';
 import type { ToolPolicy } from '../policy/policy.js';
 import type { ToolGroup } from '@metro-labs/core/stations/types';
 import { listRemoteTools, type RemoteTool } from './tools.js';
@@ -8,28 +9,23 @@ import { readJson, writeSecure } from '@metro-labs/core/secure-fs';
 import { errMsg, log } from '@metro-labs/core/log';
 import {
   authHeaders,
-  connectorUrlText,
-  ConnectorVerifyError,
-  parseConnectorUrl,
   verifyRemoteMcp,
   type ConnectorAuth,
   type OAuthAuth,
   type VerifiedRecord,
-} from './verify.js';
+} from '@metro-labs/http/connector-mcp';
+import { connectorUrlText, ConnectorVerifyError, parseConnectorUrl } from '@metro-labs/http/connector-url';
 import { oauthExpired, refreshOAuth } from './oauth.js';
-import { advertisesOAuth } from './oauth-discovery.js';
+import { advertisesOAuth } from '@metro-labs/http/connector-discovery';
+import { ConnectorError, connectorAuth, connectorClient, connectorName } from '@metro-labs/http/connector-input';
 import {
-  ConnectorError,
-  connectorAuth,
-  connectorClient,
-  connectorName,
   readConfig,
   signInState,
   stamp,
   type ConnectorConfig,
   type ConnectorSignIn,
 } from './config.js';
-import type { OAuthClient } from './oauth-client.js';
+import type { OAuthClient } from '@metro-labs/http/connector-oauth';
 import { agentsDir } from '../agents/files.js';
 import { newId } from '@metro-labs/core/ids';
 import type { LoadedConnector } from '../stations/materialize.js';
@@ -119,8 +115,7 @@ export function readLocalConnectors(dir = agentsDir()): LocalConnectorRow[] {
 function writeRows(dir: string, rows: LocalConnectorRow[]): void {
   writeSecure(filePath(dir), `${JSON.stringify({ version: 1, connectors: rows }, null, 2)}\n`);
   if (dir !== agentsDir()) return;
-  syncPluginServers(rows);
-  registerConnectors(rows);
+  publishLocalConnectors(rows);
 }
 
 const missing = (): ConnectorError => new ConnectorError('no such connector', 404);
@@ -298,7 +293,7 @@ export async function localSetConnectorPolicy(id: string, policy: ToolPolicy, di
 
 export async function loadConnectorPolicies(dir = agentsDir()): Promise<void> {
   const rows = readLocalConnectors(dir);
-  registerConnectors(rows);
+  publishLocalConnectors(rows);
   for (const row of rows) if (row.config.policy !== undefined) await refreshGroups(row.id, dir);
 }
 
@@ -332,11 +327,6 @@ function refreshOnce(row: LocalConnectorRow, auth: OAuthAuth, dir: string): Prom
   return job;
 }
 
-export type RelayTarget =
-  | { kind: 'ok'; url: string; headers: Record<string, string> }
-  | { kind: 'missing' }
-  | { kind: 'signin' };
-
 function staleUsable(auth: OAuthAuth, now = Date.now()): boolean {
   return auth.expiresAt === undefined || auth.expiresAt > now;
 }

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

@@ -1,6 +1,8 @@
 import { isRecord } from '@metro-labs/core/is-record';
 import { errMsg, log } from '@metro-labs/core/log';
-import { authHeaders, INITIALIZE, mcpPost, payloadOf, refused, type ConnectorAuth } from './verify.js';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authHeaders, INITIALIZE, mcpPost, payloadOf, type ConnectorAuth } from '@metro-labs/http/connector-mcp';
+import { refused } from '@metro-labs/http/connector-url';
 
 export interface RemoteTool {
   name: string;
@@ -22,8 +24,8 @@ function resultOf(text: string, contentType: string): Record<string, unknown> |
   return isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
 }
 
-async function rpc(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown): Promise<Record<string, unknown> | null> {
-  const res = await mcpPost(url, auth, body, { timeoutMs: TIMEOUT_MS, headers: Object.fromEntries(session) });
+async function rpc(url: URL, auth: ConnectorAuth, session: Map<string, string>, body: unknown, fetchImpl?: FetchLike): Promise<Record<string, unknown> | null> {
+  const res = await mcpPost(url, auth, body, { timeoutMs: TIMEOUT_MS, headers: Object.fromEntries(session), fetch: fetchImpl });
   const id = res.headers.get('mcp-session-id');
   if (id !== null && id !== '') session.set('mcp-session-id', id);
   const text = await res.text().catch(() => '');
@@ -39,13 +41,14 @@ function toTool(raw: unknown): RemoteTool | null {
   return { name: raw.name, title, description: typeof raw.description === 'string' ? raw.description : '', readOnly: annotations.readOnlyHint === true };
 }
 
-async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, string>): Promise<void> {
+async function endSession(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<void> {
   if (!session.has('mcp-session-id')) return;
   try {
-    const res = await fetch(url, { method: 'DELETE', redirect: 'manual', signal: AbortSignal.timeout(TIMEOUT_MS), headers: { ...authHeaders(auth), ...Object.fromEntries(session) } });
+    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();
   } catch (err) {
-    log.debug({ host: url.hostname, err: errMsg(err) }, 'connector-tools: the remote declined to end the session');
+    log.debug(fetchImpl === undefined ? { host: url.hostname, err: errMsg(err) } : {}, 'connector-tools: the remote declined to end the session');
   }
 }
 
@@ -57,11 +60,11 @@ function nextCursor(result: Record<string, unknown>, current: string): string |
   return typeof next !== 'string' || next === '' || next === current ? null : next;
 }
 
-async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>): Promise<RemoteTool[]> {
+async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
   const tools: RemoteTool[] = [];
   let cursor: string | null = '';
   for (let page = 0; page < MAX_PAGES && cursor !== null; page += 1) {
-    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } });
+    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } }, fetchImpl);
     if (result === null) break;
     tools.push(...toolsOf(result));
     cursor = nextCursor(result, cursor);
@@ -69,13 +72,13 @@ async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, str
   return tools;
 }
 
-export async function listRemoteTools(url: URL, auth: ConnectorAuth): Promise<RemoteTool[]> {
+export async function listRemoteTools(url: URL, auth: ConnectorAuth, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
   const session = new Map<string, string>();
-  const init = await rpc(url, auth, session, INITIALIZE);
+  const init = await rpc(url, auth, session, INITIALIZE, fetchImpl);
   if (init === null || typeof init.protocolVersion !== 'string') throw refused(`${url.hostname} answered, but it does not speak MCP.`);
   session.set('mcp-protocol-version', init.protocolVersion);
-  await rpc(url, auth, session, { jsonrpc: '2.0', method: 'notifications/initialized' });
-  const tools = await walkTools(url, auth, session);
-  await endSession(url, auth, session);
+  await rpc(url, auth, session, { jsonrpc: '2.0', method: 'notifications/initialized' }, fetchImpl);
+  const tools = await walkTools(url, auth, session, fetchImpl);
+  await endSession(url, auth, session, fetchImpl);
   return tools;
 }

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

@@ -2,8 +2,9 @@ import { isDeepStrictEqual } from 'node:util';
 import { isRecord } from '@metro-labs/core/is-record';
 import { newId, parseId } from '@metro-labs/core/ids';
 import { ApiError } from '@metro-labs/http/api-error';
-import { connectorAuth, connectorName, readConfig } from './config.js';
-import { parseConnectorUrl } from './url.js';
+import { connectorAuth, connectorName } from '@metro-labs/http/connector-input';
+import { readConfig } from './config.js';
+import { parseConnectorUrl } from '@metro-labs/http/connector-url';
 import { normalizePolicy } from '../policy/policy.js';
 import { localImportConnectors, readLocalConnectors, type LocalConnectorRow } from './store.js';
 

package/runtime/node_modules/@metro-labs/daemon/src/mcp/frame-schema.ts

@@ -32,6 +32,10 @@ export const frameSchema = {
       type: 'object',
       description:
         'Optional: {"url": "https://…"}, a node URL that serves this widget live (2048 characters at most). ' +
+        "Stage then sends the frame's actions to that node, not to you, and the node's reply replaces the " +
+        'frame on that device, with no message to you. Only an action with "handler": "client" (e.g. ' +
+        '{"type": "ask", "handler": "client"}) still comes back to you as a Frame action; without a source, ' +
+        "every action does. Refresh is in the frame's three-dot menu, so a node needs no Refresh button. " +
         'Add to dashboard on the frame then adds a live widget loaded from that URL instead of a copy.',
       properties: { url: { type: 'string' } },
       required: ['url'],

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

@@ -32,7 +32,8 @@ export const targetKey = (target: PolicyTarget): string =>
   target.kind === 'channel' ? `channel:${target.station}/${target.account}` : `connector:${target.id}`;
 
 export function decide(policy: ToolPolicy | undefined, tool: PolicyTool): Access {
-  return policy?.tools?.[tool.name] ?? policy?.[tool.group] ?? 'allow';
+  const byTool = policy?.tools !== undefined && Object.hasOwn(policy.tools, tool.name) ? policy.tools[tool.name] : undefined;
+  return byTool ?? policy?.[tool.group] ?? 'allow';
 }
 
 export function strictest(list: readonly Access[]): Access {

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

@@ -6,7 +6,8 @@ import { assertAttachOwner, finishGmailUpgrade, startGmailAttach } from './gmail
 import { detachWithGmailRevocation } from './gmail-detach.js';
 import { recentSenders } from '../agents/senders.js';
 import { forwardTrainCall } from '../stations/train-call.js';
-import { syncPluginServers } from '../connectors/plugin-sync.js';
+import { publishLocalConnectors } from '../connectors/publication.js';
+import { invalidateOrgConnectorSync, orgConnectorRelaySession } from '../connectors/org-sync-watch.js';
 import type { AgentApiDeps } from '../agents/api.js';
 import { ATTACHABLE, type AccountApiDeps } from '../agents/accounts-api.js';
 import type { SessionApis } from './session-apis.js';
@@ -14,6 +15,7 @@ import type { ModeInfo } from '@metro-labs/http/mode-api';
 import { loadedAgentOf, type AgentBundle, type BundleApiDeps } from '../agents/bundle.js';
 import { METRO_VERSION } from '@metro-labs/core/version';
 import type { ConnectorApiDeps } from '../connectors/api.js';
+import { connectorMigrationPreview } from '../connectors/migration-preview.js';
 import { ConnectorTransfers } from '../connectors/transfer-api.js';
 import { copyConnectorRows } from '../connectors/transfer-store.js';
 import { authenticate } from '../mcp/request-identity.js';
@@ -121,9 +123,10 @@ function connectorIdsOfLocalAgents(ids: string[]): Promise<Map<string, string[]>
 }
 
 const connectorApi: ConnectorApiDeps = {
+  migrationPreview: () => connectorMigrationPreview(localOwner()),
   listConnectors: async () => {
     const rows = await localListConnectors();
-    syncPluginServers(readLocalConnectors());
+    publishLocalConnectors(readLocalConnectors());
     return rows;
   },
   createConnector: localCreateConnector,
@@ -140,6 +143,7 @@ const connectorApi: ConnectorApiDeps = {
 
 const relayApi: RelayApiDeps = {
   target: (connectorId, force) => localRelayTarget(connectorId, force),
+  open: orgConnectorRelaySession,
   identify: (req) => {
     const who = authenticate(req);
     return who?.kind === 'agent' ? { subject: 'agent-key', agentId: who.agentId } : null;
@@ -202,11 +206,16 @@ export function localSessionApis(deps: LocalModeDeps): SessionApis {
     bundleApi: bundleApi(deps),
     connectorApi,
     connectorTransfers: new ConnectorTransfers({ read: readLocalConnectors, copy: copyConnectorRows }),
+    enrollApi: { owner: () => localOwner(), invalidate: invalidateOrgConnectorSync },
     relayApi,
     claudeApi: { liveEvents: deps.liveEvents },
     updateApi: { restart: deps.restart },
     controlApi: { restart: deps.restart, stop: deps.stop },
-    ownerApi: { setOwner: (owner) => setLocalOwner(owner) },
+    ownerApi: { setOwner: (owner) => {
+      const saved = setLocalOwner(owner);
+      invalidateOrgConnectorSync();
+      return saved;
+    } },
     machineApi: {},
     modelApi: { switchModel: deps.switchModel, owner: localOwner },
     gateway: { config: readModelConfig },

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

@@ -8,6 +8,7 @@ import {
 } from '../connectors/api.js';
 import type { RelayApiDeps } from '../connectors/relay.js';
 import type { ConnectorTransfers } from '../connectors/transfer-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';
 import { handleBundleRequest, type BundleApiDeps } from '../agents/bundle.js';
@@ -37,6 +38,7 @@ export interface SessionApis {
   claudeApi?: ClaudeApiDeps;
   connectorApi?: ConnectorApiDeps;
   connectorTransfers?: ConnectorTransfers;
+  enrollApi?: EnrollApiDeps;
   relayApi?: RelayApiDeps;
   mode?: () => ModeInfo;
 }
@@ -54,6 +56,7 @@ export function handleSessionApis(
     () => handleRunEventsRequest(req, res),
     () => handleApprovalsRequest(req, res),
     ...when(apis.connectorTransfers, (d) => d.handle(req, res)),
+    ...when(apis.enrollApi, (d) => handleEnrollRequest(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

@@ -2,7 +2,7 @@
   "name": "@metro-labs/http",
   "version": "0.1.0",
   "private": true,
-  "description": "How a metro server authenticates and answers a request: CORS, the JSON helpers, ApiError, the signed-identity header, the identity registry and AWS request signing. Shared by the daemon and api.metro.box, never by a station.",
+  "description": "How a metro server authenticates and answers a request: CORS, the JSON helpers, ApiError, the signed-identity header, the identity registry, AWS request signing, the signature a box puts on its requests to api.metro.box, and the connector client both use (url checks, the MCP initialize, OAuth discovery, registration and tokens). Shared by the daemon and api.metro.box, never by a station.",
   "type": "module",
   "exports": {
     "./cors": "./src/cors.ts",
@@ -11,7 +11,15 @@
     "./return-to": "./src/return-to.ts",
     "./mode-api": "./src/mode-api.ts",
     "./workos-token": "./src/workos-token.ts",
-    "./sigv4": "./src/sigv4.ts"
+    "./sigv4": "./src/sigv4.ts",
+    "./agent-signature": "./src/agent-signature.ts",
+    "./connector-url": "./src/connector-url.ts",
+    "./connector-reach": "./src/connector-reach.ts",
+    "./connector-mcp": "./src/connector-mcp.ts",
+    "./connector-discovery": "./src/connector-discovery.ts",
+    "./connector-oauth": "./src/connector-oauth.ts",
+    "./connector-input": "./src/connector-input.ts",
+    "./connector-delivery": "./src/connector-delivery.ts"
   },
   "scripts": {
     "build": "tsc",

package/runtime/node_modules/@metro-labs/http/src/agent-signature.ts

@@ -0,0 +1,110 @@
+import { createHash, createPublicKey, diffieHellman, generateKeyPairSync, randomBytes, sign, verify, type KeyObject } from 'node:crypto';
+import { strongEd25519 } from './ed25519.js';
+
+export const AGENT_SCHEME = 'MetroAgent';
+export const AGENT_CLOCK_SKEW_MS = 5 * 60_000;
+
+const VERSION = 'metro-agent-request/v1';
+const KEY_ID_RE = /^[A-Za-z0-9_-]{43}$/;
+const NONCE_RE = /^[A-Za-z0-9_-]{22}$/;
+const SIGNATURE_RE = /^[A-Za-z0-9_-]{86}$/;
+const TIME_RE = /^[0-9]{1,15}$/;
+const RAW_KEY_RE = /^[A-Za-z0-9_-]{43}$/;
+
+export interface AgentRequest {
+  method: string;
+  host: string;
+  path: string;
+  body: Uint8Array;
+}
+
+export interface AgentProof {
+  keyId: string;
+  time: number;
+  nonce: string;
+  signature: string;
+}
+
+type Curve = 'Ed25519' | 'X25519';
+
+const digest = (bytes: Uint8Array): string => createHash('sha256').update(bytes).digest('base64url');
+
+export const agentKeyId = (signingKey: string): string => digest(Buffer.from(signingKey, 'base64url'));
+
+function publicKeyOf(raw: string, curve: Curve): KeyObject | null {
+  if (!RAW_KEY_RE.test(raw) || Buffer.from(raw, 'base64url').toString('base64url') !== raw) return null;
+  try {
+    const key = createPublicKey({ key: { kty: 'OKP', crv: curve, x: raw }, format: 'jwk' });
+    return key.asymmetricKeyType === curve.toLowerCase() ? key : null;
+  } catch {
+    return null;
+  }
+}
+
+export function signingKeyOf(raw: string): KeyObject | null {
+  const key = publicKeyOf(raw, 'Ed25519');
+  return key !== null && strongEd25519(Buffer.from(raw, 'base64url')) ? key : null;
+}
+
+function contributes(key: KeyObject): boolean {
+  try {
+    return diffieHellman({ privateKey: generateKeyPairSync('x25519').privateKey, publicKey: key }).some((byte) => byte !== 0);
+  } catch {
+    return false;
+  }
+}
+
+export function sealingKeyOf(raw: string): KeyObject | null {
+  const key = publicKeyOf(raw, 'X25519');
+  return key !== null && contributes(key) ? key : null;
+}
+
+export function rawPublicKey(key: KeyObject): string {
+  const { x } = key.export({ format: 'jwk' });
+  if (typeof x !== 'string') throw new Error('not an OKP public key');
+  return x;
+}
+
+function signingInput(request: AgentRequest, proof: Omit<AgentProof, 'signature'>): Buffer {
+  return Buffer.from([
+    VERSION,
+    request.method.toUpperCase(),
+    request.host.toLowerCase(),
+    request.path,
+    proof.keyId,
+    String(proof.time),
+    proof.nonce,
+    digest(request.body),
+  ].join('\n'));
+}
+
+export function signAgentRequest(request: AgentRequest, privateKey: KeyObject, keyId: string, time: number): string {
+  const nonce = randomBytes(16).toString('base64url');
+  const signature = sign(null, signingInput(request, { keyId, time, nonce }), privateKey).toString('base64url');
+  return `${AGENT_SCHEME} ${keyId}.${String(time)}.${nonce}.${signature}`;
+}
+
+const PARTS = [KEY_ID_RE, TIME_RE, NONCE_RE, SIGNATURE_RE];
+
+function partsOf(header: string | undefined): string[] | null {
+  if (header === undefined || header.length > 256) return null;
+  const [scheme, value, extra] = header.trim().split(' ');
+  if (scheme !== AGENT_SCHEME || value === undefined || extra !== undefined) return null;
+  const parts = value.split('.');
+  return parts.length === PARTS.length && parts.every((part, i) => PARTS[i]?.test(part) === true) ? parts : null;
+}
+
+export function readAgentProof(header: string | undefined): AgentProof | null {
+  const parts = partsOf(header);
+  if (parts === null) return null;
+  const [keyId = '', time = '', nonce = '', signature = ''] = parts;
+  return { keyId, time: Number(time), nonce, signature };
+}
+
+export const withinSkew = (time: number, now: number): boolean => Math.abs(now - time) <= AGENT_CLOCK_SKEW_MS;
+
+export function agentSignatureValid(request: AgentRequest, proof: AgentProof, signingKey: string): boolean {
+  const key = signingKeyOf(signingKey);
+  if (key === null || agentKeyId(signingKey) !== proof.keyId) return false;
+  return verify(null, signingInput(request, proof), key, Buffer.from(proof.signature, 'base64url'));
+}

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

@@ -60,7 +60,7 @@ export function apiSession(req: IncomingMessage): Promise<ApiSession | null> {
   return bearerSessions === null ? Promise.resolve(null) : bearerSessions(req);
 }
 
-export async function readJsonBody(req: IncomingMessage, max = BODY_MAX): Promise<unknown> {
+export async function readBodyBytes(req: IncomingMessage, max = BODY_MAX): Promise<Buffer> {
   const chunks: Buffer[] = [];
   let total = 0;
   let over = false;
@@ -72,7 +72,11 @@ export async function readJsonBody(req: IncomingMessage, max = BODY_MAX): Promis
     else if (total > 2 * max) break;
   }
   if (over) throw new ApiError('request body too large', 413);
-  const raw = Buffer.concat(chunks).toString('utf8').trim();
+  return Buffer.concat(chunks);
+}
+
+export async function readJsonBody(req: IncomingMessage, max = BODY_MAX): Promise<unknown> {
+  const raw = (await readBodyBytes(req, max)).toString('utf8').trim();
   if (raw === '') return {};
   try {
     return JSON.parse(raw);

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,54 @@
+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';
+
+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 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 };
+  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()]);
+  return deliverySnapshotOf(JSON.parse(plaintext.toString('utf8')) as unknown);
+}