@stage-labs/metro 0.1.0-beta.3 → 0.1.0-beta.300

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

@@ -0,0 +1,108 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authServerMetadataUrls, resourceMetadataUrls, type OAuthServer } from './connector-discovery.js';
+import { boundOAuthResource, optionalOAuthResource, parsePublicConnectorUrl, publicOAuthResource } from './connector-public-url.js';
+import { refused, ConnectorVerifyError } from './connector-url.js';
+
+const METADATA_MAX = 1024 * 1024;
+const metadataError = (): Error => refused('The provider returned invalid or unavailable public OAuth metadata. Check its public OAuth resource and try again.');
+export class OAuthResourceRequired extends ConnectorVerifyError {
+  constructor() { super('Enter the provider’s public OAuth resource before continuing. It is shown in the sign-in page; never enter a private endpoint or credentials.', 400); }
+}
+
+async function metadataBody(res: Response): Promise<Record<string, unknown>> {
+  if (res.body === null) throw metadataError();
+  const reader = res.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.length;
+      if (size > METADATA_MAX) throw metadataError();
+      chunks.push(value);
+    }
+    const body: unknown = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+    if (!isRecord(body)) throw metadataError();
+    return body;
+  } finally {
+    await reader.cancel().catch(() => undefined);
+  }
+}
+
+async function metadata(url: URL, send: FetchLike): Promise<Record<string, unknown> | null> {
+  try {
+    const res = await send(url.toString(), { redirect: 'manual', signal: AbortSignal.timeout(10_000), headers: { accept: 'application/json' } });
+    if (res.status === 404) {
+      await res.body?.cancel();
+      return null;
+    }
+    if (!res.ok) {
+      await res.body?.cancel();
+      throw metadataError();
+    }
+    return await metadataBody(res);
+  } catch {
+    throw metadataError();
+  }
+}
+
+function selectedResource(transport: URL, offered: string | undefined, body: Record<string, unknown> | null): string {
+  const advertised = body !== null && Object.hasOwn(body, 'resource') ? publicOAuthResource(body.resource) : undefined;
+  if (advertised !== undefined && offered !== undefined && advertised !== offered) throw metadataError();
+  const resource = advertised ?? offered;
+  if (resource === undefined) throw new OAuthResourceRequired();
+  return boundOAuthResource(transport.toString(), resource);
+}
+
+function issuerOf(body: Record<string, unknown> | null, transport: URL): string {
+  if (body === null || !Object.hasOwn(body, 'authorization_servers')) return transport.origin;
+  const servers = body.authorization_servers;
+  if (!Array.isArray(servers) || servers.length === 0 || servers.length > 20) throw metadataError();
+  const values = servers.map((value: unknown) => publicOAuthResource(value));
+  return values[0] ?? '';
+}
+
+function scopesOf(body: Record<string, unknown> | null): string[] {
+  if (body === null || !Object.hasOwn(body, 'scopes_supported')) return [];
+  const scopes = body.scopes_supported;
+  if (!Array.isArray(scopes) || scopes.length > 100 || scopes.some((scope: unknown) => typeof scope !== 'string' || !/^[\x21\x23-\x5b\x5d-\x7e]{1,128}$/.test(scope))) throw metadataError();
+  return [...new Set(scopes as string[])];
+}
+
+function serverOf(body: Record<string, unknown>, issuer: string, scopes: string[]): OAuthServer {
+  if (typeof body.issuer !== 'string' || publicOAuthResource(body.issuer) !== issuer) throw metadataError();
+  const endpoint = (raw: unknown): string => parsePublicConnectorUrl(raw).toString();
+  return {
+    issuer,
+    authorizationEndpoint: endpoint(body.authorization_endpoint),
+    tokenEndpoint: endpoint(body.token_endpoint),
+    registrationEndpoint: body.registration_endpoint === undefined ? null : endpoint(body.registration_endpoint),
+    supportsS256: Array.isArray(body.code_challenge_methods_supported) && body.code_challenge_methods_supported.includes('S256'),
+    scopes,
+  };
+}
+
+async function protectedMetadata(base: URL, send: FetchLike): Promise<Record<string, unknown> | null> {
+  for (const candidate of resourceMetadataUrls(base)) {
+    const body = await metadata(candidate, send);
+    if (body !== null) return body;
+  }
+  return null;
+}
+
+export async function discoverPublicOAuth(target: string, offered: unknown, send: FetchLike = fetch): Promise<{ server: OAuthServer; resource: string }> {
+  const transport = parsePublicConnectorUrl(target);
+  const explicit = optionalOAuthResource(offered);
+  if (explicit !== undefined) boundOAuthResource(target, explicit);
+  const body = await protectedMetadata(new URL(explicit ?? transport.origin), send);
+  const resource = selectedResource(transport, explicit, body);
+  const issuer = issuerOf(body, transport);
+  const scopes = scopesOf(body);
+  for (const candidate of authServerMetadataUrls(new URL(issuer))) {
+    const authorization = await metadata(candidate, send);
+    if (authorization !== null) return { server: serverOf(authorization, issuer, scopes), resource };
+  }
+  throw metadataError();
+}

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

@@ -0,0 +1,94 @@
+import { isRecord } from '@metro-labs/core/is-record';
+import { errMsg, log } from '@metro-labs/core/log';
+import type { FetchLike } from '@metro-labs/core/stations/oauth';
+import { authHeaders, INITIALIZE, mcpPost, payloadOf, type ConnectorAuth } from './connector-mcp.js';
+import { ConnectorUnauthorized, refused } from './connector-url.js';
+
+export interface RemoteTool {
+  name: string;
+  title: string;
+  description: string;
+  readOnly: boolean;
+}
+
+const TIMEOUT_MS = 15_000;
+const MAX_PAGES = 100;
+const MAX_TOOLS = 2000;
+
+function resultOf(text: string, contentType: string): Record<string, unknown> | null {
+  let parsed: unknown = null;
+  try {
+    parsed = JSON.parse(payloadOf(text, contentType));
+  } catch {
+    return null;
+  }
+  return isRecord(parsed) && isRecord(parsed.result) ? parsed.result : null;
+}
+
+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(() => '');
+  if (res.status === 401 || res.status === 403) throw new ConnectorUnauthorized(`${url.hostname} rejected the credential; connect it again`, 400);
+  if (!res.ok) throw refused(`${url.hostname} answered ${String(res.status)}`);
+  return resultOf(text, res.headers.get('content-type') ?? '');
+}
+
+function toTool(raw: unknown): RemoteTool | null {
+  if (!isRecord(raw) || typeof raw.name !== 'string') return null;
+  const annotations = isRecord(raw.annotations) ? raw.annotations : {};
+  const title = typeof raw.title === 'string' && raw.title !== '' ? raw.title : raw.name;
+  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>, fetchImpl?: FetchLike): Promise<void> {
+  if (!session.has('mcp-session-id')) return;
+  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) } });
+    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');
+  }
+}
+
+function addTools(result: Record<string, unknown> | null, tools: Map<string, RemoteTool>): unknown {
+  if (result === null || !Array.isArray(result.tools)) throw refused('The provider did not return a complete tool list.');
+  for (const raw of result.tools) {
+    const tool = toTool(raw);
+    if (tool === null || tools.has(tool.name)) throw refused('The provider returned an invalid tool list.');
+    tools.set(tool.name, tool);
+    if (tools.size > MAX_TOOLS) throw refused('The provider returned too many tools.');
+  }
+  return result.nextCursor;
+}
+
+async function walkTools(url: URL, auth: ConnectorAuth, session: Map<string, string>, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
+  const tools = new Map<string, RemoteTool>();
+  const cursors = new Set<string>();
+  let cursor = '';
+  for (let page = 0; page < MAX_PAGES; page += 1) {
+    const result = await rpc(url, auth, session, { jsonrpc: '2.0', id: 2 + page, method: 'tools/list', params: cursor === '' ? {} : { cursor } }, fetchImpl);
+    const next = addTools(result, tools);
+    if (next === undefined || next === null || next === '') return [...tools.values()];
+    if (typeof next !== 'string' || cursors.has(next)) throw refused('The provider did not return a complete tool list.');
+    cursors.add(next);
+    cursor = next;
+  }
+  throw refused('The provider did not return a complete tool list.');
+}
+
+export async function listRemoteTools(url: URL, auth: ConnectorAuth, fetchImpl?: FetchLike): Promise<RemoteTool[]> {
+  const session = new Map<string, string>();
+  try {
+    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' }, fetchImpl);
+    return await walkTools(url, auth, session, fetchImpl);
+  } finally {
+    await endSession(url, auth, session, fetchImpl);
+  }
+}

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

@@ -0,0 +1,37 @@
+import { ApiError } from './api-error.js';
+
+export class ConnectorVerifyError extends ApiError {}
+
+export class ConnectorUnauthorized extends ConnectorVerifyError {}
+
+export function refused(message: string): ConnectorVerifyError {
+  return new ConnectorVerifyError(message, 400);
+}
+
+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 {
+  const text = typeof raw === 'string' ? raw.trim() : '';
+  if (text === '') throw refused('a connector url is required');
+  let url: URL;
+  try {
+    url = new URL(text);
+  } catch {
+    throw refused('that is not a valid url');
+  }
+  refuseShape(url);
+  return url;
+}
+
+export function connectorUrlText(url: URL): string {
+  const text = url.toString();
+  if (url.pathname !== '/' || url.search !== '') return text;
+  return text.endsWith('/') ? text.slice(0, -1) : text;
+}

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

@@ -0,0 +1,29 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+
+export function applyMcpCors(
+  req: IncomingMessage,
+  res: ServerResponse,
+): void {
+  const origin = req.headers.origin;
+  res.setHeader(
+    'Access-Control-Allow-Origin',
+    origin !== undefined && origin !== '' ? origin : '*',
+  );
+  res.setHeader('Vary', 'Origin');
+  res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+  res.setHeader(
+    'Access-Control-Allow-Headers',
+    'Authorization, Content-Type, Accept, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID',
+  );
+  res.setHeader('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+  res.setHeader('Access-Control-Max-Age', '86400');
+}
+
+export function handleMcpPreflight(
+  req: IncomingMessage,
+  res: ServerResponse,
+): boolean {
+  if (req.method !== 'OPTIONS') return false;
+  res.writeHead(204).end();
+  return true;
+}

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/http/src/mode-api.ts

@@ -0,0 +1,31 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { cors, sendJson } from './api-http.js';
+
+const PATH = '/api/mode';
+
+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;
+  if (req.method === 'OPTIONS') {
+    res.writeHead(204, cors(req)).end();
+    return true;
+  }
+  if (req.method !== 'GET') {
+    sendJson(req, res, 405, { error: 'method not allowed' });
+    return true;
+  }
+  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()]);
+}

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

@@ -0,0 +1,149 @@
+import type { IncomingMessage } from 'node:http';
+import { createPublicKey, verify, type JsonWebKey, type KeyObject } from 'node:crypto';
+
+const WORKOS_API = 'https://api.workos.com';
+const ORG_RE = /^org_[A-Za-z0-9]{10,64}$/;
+export const isOrganizationId = (value: string): boolean => ORG_RE.test(value);
+export const DEFAULT_CLIENT_ID = 'client_01M2TJJJ6RM9CT081QB4XZK3G2';
+const SKEW_S = 60;
+const REFETCH_COOLDOWN_MS = 60_000;
+const FETCH_MS = 10_000;
+
+export interface Session {
+  userId: string;
+  sessionId: string;
+  organization: string | null;
+  role: string | null;
+  expiresAt: number;
+}
+
+export interface KeyStore {
+  read: () => string | null;
+  write: (text: string) => void;
+}
+
+export const filled = (value: string | undefined): string | null => {
+  const text = value?.trim() ?? '';
+  return text === '' ? null : text;
+};
+
+export const clientId = (env: NodeJS.ProcessEnv = process.env): string => filled(env.WORKOS_CLIENT_ID) ?? DEFAULT_CLIENT_ID;
+export const workosBase = (env: NodeJS.ProcessEnv = process.env): string => filled(env.WORKOS_API_BASE) ?? WORKOS_API;
+export const jwksUrl = (id: string, base = WORKOS_API): string => `${base}/sso/jwks/${id}`;
+
+function jwksKeys(text: string): Map<string, KeyObject> {
+  const keys = new Map<string, KeyObject>();
+  const parsed: unknown = JSON.parse(text);
+  const list = typeof parsed === 'object' && parsed !== null ? (parsed as { keys?: unknown }).keys : undefined;
+  if (!Array.isArray(list)) return keys;
+  for (const jwk of list) {
+    if (typeof jwk !== 'object' || jwk === null) continue;
+    const { kid, kty } = jwk as { kid?: unknown; kty?: unknown };
+    if (typeof kid !== 'string' || kty !== 'RSA') continue;
+    try {
+      keys.set(kid, createPublicKey({ key: jwk as JsonWebKey, format: 'jwk' }));
+    } catch {
+      continue;
+    }
+  }
+  return keys;
+}
+
+export class SigningKeys {
+  private keys = new Map<string, KeyObject>();
+  private lastMiss = 0;
+  private loaded = false;
+
+  constructor(
+    private readonly url: string,
+    private readonly store?: KeyStore,
+  ) {}
+
+  private load(): void {
+    if (this.loaded) return;
+    this.loaded = true;
+    const cached = this.store?.read() ?? null;
+    if (cached !== null) this.keys = jwksKeys(cached);
+  }
+
+  private async refresh(now: number): Promise<void> {
+    if (now - this.lastMiss < REFETCH_COOLDOWN_MS) return;
+    const res = await fetch(this.url, { signal: AbortSignal.timeout(FETCH_MS) });
+    if (!res.ok) throw new Error(`the signing keys answered ${String(res.status)}`);
+    const text = await res.text();
+    const keys = jwksKeys(text);
+    if (keys.size === 0) throw new Error('the signing keys answered no RSA key');
+    this.keys = keys;
+    this.store?.write(text);
+  }
+
+  async keyFor(kid: string, now = Date.now()): Promise<KeyObject | null> {
+    this.load();
+    const held = this.keys.get(kid);
+    if (held !== undefined) return held;
+    await this.refresh(now);
+    const fetched = this.keys.get(kid);
+    if (fetched === undefined) this.lastMiss = now;
+    return fetched ?? null;
+  }
+}
+
+const b64url = (text: string): Buffer => Buffer.from(text.replace(/-/g, '+').replace(/_/g, '/'), 'base64');
+
+function jsonPart(text: string): Record<string, unknown> | null {
+  try {
+    const parsed: unknown = JSON.parse(b64url(text).toString('utf8'));
+    return typeof parsed === 'object' && parsed !== null ? (parsed as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+const str = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null);
+
+const issuedBy = (iss: unknown, issuer: string): boolean => typeof iss === 'string' && (iss === issuer || iss.startsWith(`${issuer}/`));
+
+function sessionOf(claims: Record<string, unknown>, issuer: string, now: number): Session | null {
+  const exp = typeof claims.exp === 'number' ? claims.exp : null;
+  const userId = str(claims.sub);
+  const sessionId = str(claims.sid);
+  if (!issuedBy(claims.iss, issuer) || exp === null || userId === null || sessionId === null) return null;
+  if (exp * 1000 < now - SKEW_S * 1000) return null;
+  return { userId, sessionId, organization: str(claims.org_id), role: str(claims.role), expiresAt: exp * 1000 };
+}
+
+interface Parts {
+  signed: string;
+  body: string;
+  signature: Buffer;
+  kid: string;
+}
+
+function parseToken(token: string): Parts | null {
+  const [head, body, sig] = token.split('.');
+  if (head === undefined || body === undefined || sig === undefined) return null;
+  const header = jsonPart(head);
+  const kid = str(header?.kid);
+  if (header?.alg !== 'RS256' || kid === null) return null;
+  return { signed: `${head}.${body}`, body, signature: b64url(sig), kid };
+}
+
+export async function verifyToken(token: string, keys: SigningKeys, issuer = WORKOS_API, now = Date.now()): Promise<Session | null> {
+  const parts = parseToken(token);
+  if (parts === null) return null;
+  const key = await keys.keyFor(parts.kid, now).catch(() => null);
+  if (key === null || !verify('sha256', Buffer.from(parts.signed), key, parts.signature)) return null;
+  const claims = jsonPart(parts.body);
+  return claims === null ? null : sessionOf(claims, issuer, now);
+}
+
+export function bearerToken(req: IncomingMessage): string | null {
+  const header = req.headers.authorization ?? '';
+  const [scheme, token] = header.trim().split(/\s+/);
+  return scheme?.toLowerCase() === 'bearer' && token?.includes('.') === true ? token : null;
+}
+
+export async function bearerSession(req: IncomingMessage, keys: SigningKeys, issuer = WORKOS_API): Promise<Session | null> {
+  const token = bearerToken(req);
+  return token === null ? null : verifyToken(token, keys, issuer);
+}