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

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

@@ -1,26 +1,21 @@
 import { createHash, randomBytes } from 'node:crypto';
-import {
-  ConnectorVerifyError,
-  type OAuthTokens,
-} from './connector-verify.js';
-import type { OAuthServer } from './oauth-discovery.js';
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { whyUnreachable } from './connector-reach.js';
+import { ConnectorVerifyError, refused } from './connector-url.js';
+import type { OAuthTokens } from './connector-mcp.js';
+import type { OAuthServer } from './connector-discovery.js';
 
 const TOKEN_TIMEOUT_MS = 15_000;
 const CLIENT_NAME = 'Metro';
 
+export class OAuthInvalidGrant extends ConnectorVerifyError {}
+
 export interface OAuthClient {
   clientId: string;
   clientSecret?: string;
 }
 
-function refused(message: string): ConnectorVerifyError {
-  return new ConnectorVerifyError(message, 400);
-}
-
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 export function newVerifier(): string {
   return randomBytes(32).toString('base64url');
 }
@@ -32,14 +27,17 @@ export function challengeOf(verifier: string): string {
 export async function registerClient(
   server: OAuthServer,
   redirectUri: string,
+  fetchImpl: FetchLike = fetch,
 ): Promise<OAuthClient> {
   if (server.registrationEndpoint === null)
     throw refused(
-      'That server requires OAuth but does not accept client registration, so Metro cannot sign in to it.',
+      'That server signs in with OAuth but registers no clients on its own. ' +
+        `Register an app with it yourself, with ${redirectUri} as its redirect URL, ` +
+        "and add the connector again with that app's client ID.",
     );
   let res: Response;
   try {
-    res = await fetch(server.registrationEndpoint, {
+    res = await fetchImpl(server.registrationEndpoint, {
       method: 'POST',
       redirect: 'manual',
       signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
@@ -52,8 +50,8 @@ export async function registerClient(
         token_endpoint_auth_method: 'none',
       }),
     });
-  } catch {
-    throw refused('Metro could not reach that server to register.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to register: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
   if (!res.ok || !isRecord(body) || typeof body.client_id !== 'string')
@@ -83,21 +81,37 @@ export function authorizeUrl(input: AuthorizeInput): string {
   url.searchParams.set('code_challenge', challengeOf(input.verifier));
   url.searchParams.set('code_challenge_method', 'S256');
   url.searchParams.set('resource', input.resource);
+  if (input.server.scopes.length > 0)
+    url.searchParams.set('scope', input.server.scopes.join(' '));
   return url.toString();
 }
 
+function validateOptionalTokens(body: Record<string, unknown>): void {
+  const refresh = body.refresh_token;
+  if (Object.hasOwn(body, 'refresh_token') && (typeof refresh !== 'string' || !/^[\x21-\x7e]{1,16384}$/.test(refresh))) throw refused('That server returned an invalid refresh token.');
+  if (Object.hasOwn(body, 'token_type') && (typeof body.token_type !== 'string' || body.token_type.toLowerCase() !== 'bearer')) throw refused('That server returned an unsupported token type.');
+}
+
+function expiryFrom(body: Record<string, unknown>): number | undefined {
+  if (!Object.hasOwn(body, 'expires_in')) return undefined;
+  const expires = body.expires_in;
+  if (typeof expires !== 'number' || !Number.isFinite(expires) || expires <= 0) throw refused('That server returned an invalid token expiry.');
+  const at = Date.now() + expires * 1000;
+  if (!Number.isSafeInteger(at)) throw refused('That server returned an invalid token expiry.');
+  return at;
+}
+
 function tokensFrom(body: Record<string, unknown>): OAuthTokens {
   const access = body.access_token;
-  if (typeof access !== 'string' || access === '')
-    throw refused('That server did not return an access token.');
+  if (typeof access !== 'string' || !/^[\x21-\x7e]{1,16377}$/.test(access))
+    throw refused('That server did not return a sendable access token.');
+  validateOptionalTokens(body);
+  const expiresAt = expiryFrom(body);
   const refresh = body.refresh_token;
-  const expires = body.expires_in;
   return {
     accessToken: access,
     ...(typeof refresh === 'string' ? { refreshToken: refresh } : {}),
-    ...(typeof expires === 'number'
-      ? { expiresAt: Date.now() + expires * 1000 }
-      : {}),
+    ...(expiresAt === undefined ? {} : { expiresAt }),
   };
 }
 
@@ -105,6 +119,7 @@ async function postToken(
   server: OAuthServer,
   client: OAuthClient,
   form: Record<string, string>,
+  fetchImpl: FetchLike,
 ): Promise<OAuthTokens> {
   const params = new URLSearchParams({
     ...form,
@@ -115,7 +130,7 @@ async function postToken(
   });
   let res: Response;
   try {
-    res = await fetch(server.tokenEndpoint, {
+    res = await fetchImpl(server.tokenEndpoint, {
       method: 'POST',
       redirect: 'manual',
       signal: AbortSignal.timeout(TOKEN_TIMEOUT_MS),
@@ -125,10 +140,11 @@ async function postToken(
       },
       body: params.toString(),
     });
-  } catch {
-    throw refused('Metro could not reach that server to finish signing in.');
+  } catch (err) {
+    throw refused(`Metro could not reach that server to finish signing in: ${whyUnreachable(err)}`);
   }
   const body: unknown = await res.json().catch(() => null);
+  if (form.grant_type === 'refresh_token' && res.status === 400 && isRecord(body) && body.error === 'invalid_grant') throw new OAuthInvalidGrant('That server requires a new sign-in.', 400);
   if (!res.ok || !isRecord(body))
     throw refused('That server refused to complete the sign-in.');
   return tokensFrom(body);
@@ -138,6 +154,7 @@ export function exchangeCode(
   server: OAuthServer,
   client: OAuthClient,
   input: { code: string; redirectUri: string; verifier: string; resource: string },
+  fetchImpl: FetchLike = fetch,
 ): Promise<OAuthTokens> {
   return postToken(server, client, {
     grant_type: 'authorization_code',
@@ -145,7 +162,7 @@ export function exchangeCode(
     redirect_uri: input.redirectUri,
     code_verifier: input.verifier,
     resource: input.resource,
-  });
+  }, fetchImpl);
 }
 
 export function refreshTokens(
@@ -153,10 +170,13 @@ export function refreshTokens(
   client: OAuthClient,
   refreshToken: string,
   resource: string,
+  scope?: string,
+  fetchImpl: FetchLike = fetch,
 ): Promise<OAuthTokens> {
   return postToken(server, client, {
     grant_type: 'refresh_token',
     refresh_token: refreshToken,
     resource,
-  });
+    ...(scope === undefined ? {} : { scope }),
+  }, fetchImpl);
 }

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

@@ -0,0 +1,56 @@
+import { isRecord } from '@metro-labs/core/is-record';
+
+export type ConnectorDecision = 'allow' | 'ask' | 'deny';
+
+export interface ConnectorPolicy {
+  read?: ConnectorDecision;
+  write?: ConnectorDecision;
+  tools?: Record<string, ConnectorDecision>;
+}
+
+const RANK: Record<ConnectorDecision, number> = { allow: 0, ask: 1, deny: 2 };
+const TOOL_RE = /^[A-Za-z0-9_.:/-]{1,256}$/;
+
+const decision = (value: unknown): value is ConnectorDecision => value === 'allow' || value === 'ask' || value === 'deny';
+
+export function connectorPolicyOf(value: unknown): ConnectorPolicy {
+  if (!isRecord(value) || Object.keys(value).some((key) => !['read', 'write', 'tools'].includes(key))) throw new Error('Invalid connector policy.');
+  const out: ConnectorPolicy = {};
+  for (const group of ['read', 'write'] as const) {
+    if (!Object.hasOwn(value, group)) continue;
+    const field = value[group];
+    if (!decision(field)) throw new Error('Invalid connector policy.');
+    out[group] = field;
+  }
+  if (Object.hasOwn(value, 'tools')) out.tools = toolPolicyOf(value.tools);
+  return out;
+}
+
+function toolPolicyOf(value: unknown): Record<string, ConnectorDecision> {
+  if (!isRecord(value) || Object.keys(value).length > 2000) throw new Error('Invalid connector policy.');
+  const out: Record<string, ConnectorDecision> = {};
+  for (const [name, rule] of Object.entries(value)) {
+    if (!TOOL_RE.test(name) || ['__proto__', 'constructor', 'prototype'].includes(name) || !decision(rule)) throw new Error('Invalid connector policy.');
+    out[name] = rule;
+  }
+  return out;
+}
+
+const strictest = (...values: (ConnectorDecision | undefined)[]): ConnectorDecision => values.reduce<ConnectorDecision>((held, next) => next !== undefined && RANK[next] > RANK[held] ? next : held, 'allow');
+
+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)),
+  };
+  const names = new Set(policies.flatMap((policy) => Object.keys(policy.tools ?? {})));
+  if (names.size > 0) {
+    out.tools = {};
+    for (const name of names) out.tools[name] = strictest(...policies.flatMap((policy) => [policy.read, policy.write, policy.tools?.[name]]));
+  }
+  return out;
+}

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

@@ -0,0 +1,27 @@
+import { errMsg } from '@metro-labs/core/log';
+
+const HINTS: Record<string, string> = {
+  ENOTFOUND: 'the name does not resolve',
+  EAI_AGAIN: 'the name did not resolve in time',
+  ECONNREFUSED: 'nothing is listening there',
+  ECONNRESET: 'the server dropped the connection',
+  ETIMEDOUT: 'the server did not answer in time',
+  ConnectionRefused: 'nothing is listening there',
+  CERT_HAS_EXPIRED: 'its certificate has expired',
+  DEPTH_ZERO_SELF_SIGNED_CERT: 'its certificate is self-signed',
+  UNABLE_TO_VERIFY_LEAF_SIGNATURE: 'its certificate could not be verified',
+  ERR_TLS_CERT_ALTNAME_INVALID: 'its certificate is for another name',
+  SELF_SIGNED_CERT_IN_CHAIN: 'its certificate chain is not trusted',
+};
+
+const codeOf = (err: unknown): string =>
+  err !== null && typeof err === 'object' && 'code' in err && typeof err.code === 'string' ? err.code : '';
+
+export function whyUnreachable(err: unknown): string {
+  const inner = err instanceof Error && err.cause instanceof Error ? err.cause : err;
+  const message = errMsg(inner).trim();
+  const code = codeOf(inner) || codeOf(err);
+  const said = message !== '' && message !== 'fetch failed' ? message : code || 'no answer';
+  const hint = HINTS[code];
+  return hint === undefined ? said : `${said} (${hint})`;
+}

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

@@ -4,22 +4,17 @@ export class ConnectorVerifyError extends ApiError {}
 
 export class ConnectorUnauthorized extends ConnectorVerifyError {}
 
-export class ConnectorNotMcp extends ConnectorVerifyError {}
-
-export const POLICY_MESSAGE =
-  'Metro connects from its own server, so it cannot reach a URL on your machine. localhost and private addresses are not usable as connectors.';
-
-const IPV4 = /^\d{1,3}(?:\.\d{1,3}){3}$/;
-const PRIVATE_SUFFIX = /(?:^|\.)(?:localhost|local|internal|flycast)$/;
-
 export function refused(message: string): ConnectorVerifyError {
   return new ConnectorVerifyError(message, 400);
 }
 
-function hostAllowed(host: string): boolean {
-  if (host === '' || host.startsWith('[')) return false;
-  if (IPV4.test(host) || !host.includes('.')) return false;
-  return !PRIVATE_SUFFIX.test(host);
+function refuseShape(url: URL): void {
+  if (url.protocol !== 'https:' && url.protocol !== 'http:')
+    throw refused('a connector url must start with https:// or http://');
+  if (url.username !== '' || url.password !== '')
+    throw refused('a connector url must not carry a user:password');
+  if (url.hash !== '')
+    throw refused('a connector url must not carry a #fragment');
 }
 
 export function parseConnectorUrl(raw: unknown): URL {
@@ -31,13 +26,7 @@ export function parseConnectorUrl(raw: unknown): URL {
   } catch {
     throw refused('that is not a valid url');
   }
-  if (url.protocol !== 'https:')
-    throw refused('a connector url must start with https://');
-  if (url.username !== '' || url.password !== '')
-    throw refused('a connector url must not carry a user:password');
-  if (url.hash !== '')
-    throw refused('a connector url must not carry a #fragment');
-  if (!hostAllowed(url.hostname.toLowerCase())) throw refused(POLICY_MESSAGE);
+  refuseShape(url);
   return url;
 }
 
@@ -46,12 +35,3 @@ export function connectorUrlText(url: URL): string {
   if (url.pathname !== '/' || url.search !== '') return text;
   return text.endsWith('/') ? text.slice(0, -1) : text;
 }
-
-export function safeIconSrc(raw: unknown): string {
-  if (typeof raw !== 'string' || raw === '') return '';
-  try {
-    return new URL(raw).protocol === 'https:' ? raw.slice(0, 500) : '';
-  } catch {
-    return '';
-  }
-}

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

@@ -0,0 +1,56 @@
+const P = 2n ** 255n - 19n;
+
+interface Point {
+  x: bigint;
+  y: bigint;
+}
+
+const mod = (a: bigint): bigint => ((a % P) + P) % P;
+
+function pow(base: bigint, exp: bigint): bigint {
+  let result = 1n;
+  let b = mod(base);
+  for (let e = exp; e > 0n; e >>= 1n) {
+    if ((e & 1n) === 1n) result = (result * b) % P;
+    b = (b * b) % P;
+  }
+  return result;
+}
+
+const inv = (a: bigint): bigint => pow(a, P - 2n);
+const D = mod(-121665n * inv(121666n));
+const SQRT_M1 = pow(2n, (P - 1n) / 4n);
+
+function rootOf(u: bigint, v: bigint): bigint | null {
+  const x = mod(u * pow(v, 3n) * pow(mod(u * pow(v, 7n)), (P - 5n) / 8n));
+  const vx2 = mod(v * x * x);
+  if (vx2 === u) return x;
+  return vx2 === mod(-u) ? mod(x * SQRT_M1) : null;
+}
+
+function decode(bytes: Buffer): Point | null {
+  if (bytes.length !== 32) return null;
+  const last = bytes[31] ?? 0;
+  const sign = BigInt(last >> 7);
+  const copy = Buffer.from(bytes);
+  copy[31] = last & 0x7f;
+  const y = BigInt(`0x${copy.reverse().toString('hex')}`);
+  if (y >= P) return null;
+  const y2 = (y * y) % P;
+  const x = rootOf(mod(y2 - 1n), mod(D * y2 + 1n));
+  if (x === null || (x === 0n && sign === 1n)) return null;
+  return { x: (x & 1n) === sign ? x : mod(-x), y };
+}
+
+function add(a: Point, b: Point): Point {
+  const t = mod(D * a.x * b.x * a.y * b.y);
+  return { x: mod((a.x * b.y + a.y * b.x) * inv(mod(1n + t))), y: mod((a.y * b.y + a.x * b.x) * inv(mod(1n - t))) };
+}
+
+export function strongEd25519(raw: Buffer): boolean {
+  const point = decode(raw);
+  if (point === null) return false;
+  let eight = point;
+  for (let i = 0; i < 3; i += 1) eight = add(eight, eight);
+  return !(eight.x === 0n && eight.y === 1n);
+}

package/runtime/node_modules/@metro-labs/{mcp/src/daemon/session-api.ts → http/src/mode-api.ts}

@@ -1,11 +1,20 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
-import { apiSession, cors, sendJson } from './api-http.js';
+import { cors, sendJson } from './api-http.js';
 
-const PATH = '/api/session';
+const PATH = '/api/mode';
 
-export function handleSessionApiRequest(
+export type DaemonMode = 'hosted' | 'local';
+
+export interface ModeInfo {
+  mode: DaemonMode;
+  owner: string | null;
+  version: string;
+}
+
+export function handleModeRequest(
   req: IncomingMessage,
   res: ServerResponse,
+  info: () => ModeInfo,
 ): boolean {
   const path = (req.url ?? '').split('?')[0] ?? '';
   if (path !== PATH) return false;
@@ -17,11 +26,6 @@ export function handleSessionApiRequest(
     sendJson(req, res, 405, { error: 'method not allowed' });
     return true;
   }
-  const session = apiSession(req);
-  if (!session) {
-    sendJson(req, res, 401, { error: 'unauthorized' });
-    return true;
-  }
-  sendJson(req, res, 200, { email: session.email });
+  sendJson(req, res, 200, info());
   return true;
 }

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

@@ -0,0 +1,25 @@
+const PREVIEW = /^([a-z0-9-]+--)?metro-ui\.netlify\.app$/;
+
+export function allowedWebHost(host: string): boolean {
+  if (host === 'metro.box' || host === 'localhost' || host === '127.0.0.1')
+    return true;
+  return PREVIEW.test(host);
+}
+
+export const APP_RETURN = 'metro://auth';
+
+export const isAppReturn = (returnTo: string): boolean => returnTo === APP_RETURN;
+
+export function validateReturnTo(returnTo: string): boolean {
+  let url: URL;
+  try {
+    url = new URL(returnTo);
+  } catch {
+    return false;
+  }
+  const host = url.hostname;
+  if (url.protocol === 'http:' && (host === 'localhost' || host === '127.0.0.1'))
+    return true;
+  if (url.protocol !== 'https:') return false;
+  return allowedWebHost(host);
+}

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

@@ -0,0 +1,90 @@
+const enc = new TextEncoder();
+
+const hex = (bytes: Uint8Array): string =>
+  [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+export async function sha256Hex(data: string | Uint8Array<ArrayBuffer>): Promise<string> {
+  const bytes = typeof data === 'string' ? enc.encode(data) : data;
+  return hex(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)));
+}
+
+async function hmac(key: Uint8Array<ArrayBuffer>, data: string): Promise<Uint8Array<ArrayBuffer>> {
+  const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  return new Uint8Array(await crypto.subtle.sign('HMAC', cryptoKey, enc.encode(data)));
+}
+
+const encodeRfc3986 = (value: string): string =>
+  encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+
+const byPair = (a: [string, string], b: [string, string]): number =>
+  a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0;
+
+function canonicalQuery(url: URL): string {
+  const pairs: [string, string][] = [];
+  url.searchParams.forEach((value, key) => {
+    pairs.push([encodeRfc3986(key), encodeRfc3986(value)]);
+  });
+  return pairs.sort(byPair).map(([k, v]) => `${k}=${v}`).join('&');
+}
+
+export const amzDate = (date: Date): string =>
+  date.toISOString().replace(/[-:]/g, '').replace(/\.\d{3}Z$/, 'Z');
+
+export interface SignInput {
+  method: string;
+  url: string;
+  headers: Record<string, string>;
+  body: string;
+  region: string;
+  service: string;
+  accessKeyId: string;
+  secretAccessKey: string;
+  sessionToken?: string;
+  date?: Date;
+}
+
+export interface Signed {
+  headers: Record<string, string>;
+  canonicalRequest: string;
+  stringToSign: string;
+  signature: string;
+}
+
+function canonicalHeaders(input: SignInput, url: URL, date: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [key, value] of Object.entries(input.headers)) out[key.toLowerCase()] = value.trim().replace(/\s+/g, ' ');
+  out.host = url.host;
+  out['x-amz-date'] = date;
+  if (input.sessionToken !== undefined) out['x-amz-security-token'] = input.sessionToken;
+  return out;
+}
+
+async function signingKey(input: SignInput, day: string): Promise<Uint8Array<ArrayBuffer>> {
+  const kDate = await hmac(enc.encode(`AWS4${input.secretAccessKey}`), day);
+  const kRegion = await hmac(kDate, input.region);
+  const kService = await hmac(kRegion, input.service);
+  return hmac(kService, 'aws4_request');
+}
+
+export async function signV4(input: SignInput): Promise<Signed> {
+  const url = new URL(input.url);
+  const date = amzDate(input.date ?? new Date());
+  const day = date.slice(0, 8);
+  const headers = canonicalHeaders(input, url, date);
+  const names = Object.keys(headers).sort();
+  const signedHeaders = names.join(';');
+  const canonicalRequest = [
+    input.method.toUpperCase(),
+    url.pathname === '' ? '/' : url.pathname,
+    canonicalQuery(url),
+    names.map((name) => `${name}:${headers[name] ?? ''}\n`).join(''),
+    signedHeaders,
+    await sha256Hex(input.body),
+  ].join('\n');
+  const scope = `${day}/${input.region}/${input.service}/aws4_request`;
+  const stringToSign = ['AWS4-HMAC-SHA256', date, scope, await sha256Hex(canonicalRequest)].join('\n');
+  const signature = hex(await hmac(await signingKey(input, day), stringToSign));
+  const authorization = `AWS4-HMAC-SHA256 Credential=${input.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+  const sendable = Object.fromEntries(Object.entries(headers).filter(([name]) => name !== 'host'));
+  return { headers: { ...sendable, authorization }, canonicalRequest, stringToSign, signature };
+}

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