From fe65a397cf1ae0f8effd7984a76293e4c85d68e2 Mon Sep 17 00:00:00 2001 From: QQ Date: Sat, 14 Nov 2026 15:03:57 +0800 Subject: [PATCH] Import packages/protocol/src/index.ts --- packages/protocol/src/index.ts | 1480 ++++++++++++++++++++++++++++++++ 1 file changed, 1480 insertions(+) create mode 100644 packages/protocol/src/index.ts diff --git a/packages/protocol/src/index.ts b/packages/protocol/src/index.ts new file mode 100644 index 0000000..e723d8a --- /dev/null +++ b/packages/protocol/src/index.ts @@ -0,0 +1,1480 @@ +export * from './loopback.js' +import { parseWireJson } from './wire-json.js' +export { parseWireJson } from './wire-json.js' +import { z } from 'zod' + +export const WEBRTC_RESUME_CAPABILITY = 'transport.webrtc.resume.v1' +export const RELAY_RESUME_CAPABILITY = 'transport.relay.resume.v1' +export const WEBRTC_LEASE_MS = 300_000 +import { SERVER_SHUTDOWN_REASON as SERVER_SHUTDOWN_REASON_NAME } from './close-semantics.js' +export { + SERVER_SHUTDOWN_REASON, + SERVER_SHUTDOWN_CLOSE_CODES, + HEARTBEAT_TIMEOUT_CLOSE_CODE, + HEARTBEAT_TIMEOUT_REASON, + HEARTBEAT_CONNECTION_FAILED_REASON, + TRANSIENT_CONTROL_CLOSE_CODES, + TERMINAL_CONTROL_CLOSE_CODES, + isServerShutdownClose, + isHeartbeatTimeoutClose, + classifyControlClose, + type ControlCloseClassification, +} from './close-semantics.js' +/** + * WebSocket close code a Server uses when shutting down for restart. + * + * Deployments disagree on the code (`apps/server` sends 4009, the hosted + * Server sends 4001 and reserves 4009 for heartbeat expiry), so endpoints must + * classify with `isServerShutdownClose()` / `classifyControlClose()` and never + * by comparing the code alone. + */ +export const SERVER_SHUTDOWN_CLOSE_CODE = 4009 +/** Close reason paired with the shutdown code; this is the semantic key. */ +export const SERVER_SHUTDOWN_CLOSE_REASON: string = SERVER_SHUTDOWN_REASON_NAME +export const PROTOCOL_VERSION = 1 +export const MAX_CONTROL_FRAME_BYTES = 64 * 1024 +export const MAX_RELAY_FRAME_BYTES = 1024 * 1024 +export const SECURE_FRAGMENT_CHUNK_BYTES = 48 * 1024 +export const MAX_SECURE_MESSAGE_BYTES = 4 * 1024 * 1024 +/** Decoded bytes carried by one authenticated Harness business transfer chunk. */ +export const HARNESS_API_TRANSFER_CHUNK_BYTES = 512 * 1024 +/** Decoded bytes carried by one authenticated Codex domain transfer chunk. */ +export const CODEX_APP_TRANSFER_CHUNK_BYTES = 512 * 1024 +/** Decoded bytes carried by one authenticated Agent ACP domain transfer chunk. */ +export const AGENT_ACP_TRANSFER_CHUNK_BYTES = 512 * 1024 +/** + * Bounded transfer size for Harness image prompts. The upstream default admits + * up to 200 MiB of source images; their base64 JSON envelope needs roughly + * 267 MiB, so 288 MiB leaves room for the native request structure. + */ +export const MAX_HARNESS_API_TRANSFER_BYTES = 288 * 1024 * 1024 +export const MAX_CODEX_APP_TRANSFER_BYTES = 288 * 1024 * 1024 +export const MAX_AGENT_ACP_TRANSFER_BYTES = 288 * 1024 * 1024 +export const MAX_DEVICE_NAME_LENGTH = 128 +export const MAX_DEVICE_PLATFORM_LENGTH = 64 +export const MAX_DEVICE_VERSION_LENGTH = 64 +export const MAX_AUTH_TOKEN_LENGTH = 8 * 1024 +/** Maximum entries accepted in capability and workspace type advertisements. */ +export const MAX_REMOTE_CAPABILITY_ENTRIES = 128 +export const MAX_REMOTE_WORKSPACE_TYPE_ENTRIES = 32 + +// ──────────────────────────────────────────────────────────────────────────── +// §24 Default limits +// ──────────────────────────────────────────────────────────────────────────── + +/** Hello frame must arrive within this timeout after WebSocket open. */ +export const HELLO_TIMEOUT_MS = 5_000 +/** Host registration code time-to-live. */ +export const HOST_REGISTRATION_CODE_TTL_MS = 10 * 60_000 +/** Default control channel heartbeat interval. */ +export const DEFAULT_HEARTBEAT_INTERVAL_MS = 25_000 +/** Disconnection threshold: no valid pong within this window. */ +export const HEARTBEAT_DISCONNECT_MS = 75_000 +/** Maximum in-flight RPC requests per connection. */ +export const MAX_PENDING_RPC_PER_CONNECTION = 128 +/** Maximum pending permission requests per session. */ +export const MAX_PENDING_PERMISSION_PER_SESSION = 16 +/** Maximum ICE candidates收集 per connection. */ +export const MAX_ICE_CANDIDATES_PER_CONNECTION = 256 +/** Maximum active transfers per direction per connection. */ +export const MAX_ACTIVE_TRANSFERS_PER_DIRECTION = 2 +/** Transfer idle timeout before automatic cleanup. */ +export const TRANSFER_IDLE_MS = 2 * 60_000 +/** Maximum RPC text input size. */ +export const MAX_RPC_TEXT_INPUT_BYTES = 64 * 1024 +/** Maximum File Viewer range per RPC call. */ +export const MAX_FILEVIEWER_RANGE_BYTES = 512 * 1024 +/** Maximum directory entries returned by File Viewer per RPC. */ +export const MAX_FILEVIEWER_DIRECTORY_ENTRIES = 1_000 +/** Minimum event replay window by event count. */ +export const MIN_REPLAY_WINDOW_EVENTS = 10_000 +/** Minimum event replay window by time. */ +export const MIN_REPLAY_WINDOW_MS = 15 * 60_000 +/** Maximum concurrent alpha streams per connection. */ +export const MAX_ALPHA_STREAMS_PER_CONNECTION = 16 +/** Generic Agent Client Protocol capability and bounded gateway limits. */ +export const ACP_CAPABILITY = 'agent.acp.v1' as const +export const ACP_PI_CAPABILITY = 'agent.acp.pi.v1' as const +export const ACP_WORKSPACE_FILES_CAPABILITY = 'agent.acp.workspace-files.v1' as const +export const ACP_TERMINAL_CAPABILITY = 'agent.acp.terminal.v1' as const +export const ACP_ANTIGRAVITY_MODELS_CAPABILITY = 'agent.acp.antigravity.models.v1' as const +export const ACP_ANTIGRAVITY_MODEL_LOAD_CAPABILITY = 'agent.acp.antigravity.model-load.v1' as const +export const ACP_OPENCODE_CAPABILITY = 'agent.acp.opencode.v1' as const +export const ACP_OPENCODE_ARCHIVE_CAPABILITY = 'agent.acp.opencode.archive.v1' as const +export const ACP_TOOL_CALL_ENDPOINTS = ['workspaceFiles/list', 'workspaceFiles/stat', 'workspaceFiles/read', 'workspaceFiles/readBytes', 'workspaceFiles/readAll', + 'terminal/environment', 'terminal/shells', 'terminal/list', 'terminal/create', 'terminal/write', 'terminal/resize', 'terminal/rename', 'terminal/close'] as const +export const ACP_TOOL_STREAM_ENDPOINTS = ['workspaceFiles/changes', 'terminal/follow', 'terminal/retain'] as const +export interface AcpModelSelection { provider: string; model: string; reasoningEffort?: string } +export interface AcpSessionModels { + current: AcpModelSelection; routable: boolean; + groups: Array<{ id: string; name: string; models: Array<{ id: string; name: string; reasoning?: { efforts: Array<{ id: string; name: string }>; defaultEffort?: string } }> }>; + failures: Array<{ id: string; name: string; message: string }>; +} +export const MAX_ACP_PROMPT_BYTES = 64 * 1024 +export const MAX_ACP_UPDATE_BYTES = 512 * 1024 + +const SECURE_FRAGMENT_MAGIC = new Uint8Array([0x44, 0x53, 0x48, 0x46]) // DSHF +const SECURE_FRAGMENT_VERSION = 1 +const SECURE_FRAGMENT_HEADER_BYTES = 17 +const MAX_IN_FLIGHT_SECURE_MESSAGES = 8 + +export const messageTypes = [ + 'rpc.request', + 'rpc.response', + 'rpc.error', + 'event', +] as const + +export const controlFrameTypes = [ + 'hello', + 'hello.ack', + 'connect.request', + 'connect.incoming', + 'connect.accepted', + 'connect.rejected', + 'secure.handshake', + 'relay', + 'signal.offer', + 'signal.answer', + 'signal.ice', + 'transport.selected', + 'connection.lease.request', + 'connection.lease.ack', + 'connection.lease.close', + 'ping', + 'pong', + 'error', +] as const + +export const rpcMethods = [ + 'workspace.upload.open', + 'workspace.upload.chunk', + 'workspace.upload.commit', + 'workspace.upload.abort', + 'harness.transport.describe', + 'remote.history.configure', + 'harness.api.call', + 'harness.api.transfer.open', + 'harness.api.transfer.chunk', + 'harness.api.transfer.commit', + 'harness.api.transfer.read', + 'harness.api.transfer.close', + 'harness.api.respond', + 'harness.api.stream.open', + 'harness.api.stream.close', + 'harness.remote.call', + 'harness.remote.transfer.open', + 'harness.remote.transfer.chunk', + 'harness.remote.transfer.commit', + 'harness.remote.transfer.read', + 'harness.remote.transfer.close', + 'harness.remote.stream.open', + 'harness.remote.stream.close', + 'loopback.call', + 'fileviewer.call', + 'codex.app.call', + 'codex.app.respond', + 'codex.app.stream.open', + 'codex.app.stream.close', + 'codex.app.transfer.open', + 'codex.app.transfer.chunk', + 'codex.app.transfer.commit', + 'codex.app.transfer.read', + 'codex.app.transfer.close', + 'agent.acp.call', + 'agent.acp.respond', + 'agent.acp.stream.open', + 'agent.acp.stream.close', + 'agent.acp.transfer.open', + 'agent.acp.transfer.chunk', + 'agent.acp.transfer.commit', + 'agent.acp.transfer.read', + 'agent.acp.transfer.close', + 'acp.initialize', + 'acp.session.new', + 'acp.session.load', + 'acp.session.prompt', + 'acp.session.respond_permission', + 'acp.session.cancel', + 'acp.session.set_mode', + 'plugin.route.call', +] as const + +export const remoteEvents = [ + 'harness.api.frame', + 'harness.api.stream.closed', + 'harness.remote.frame', + 'harness.remote.stream.closed', + 'codex.app.frame', + 'codex.app.stream.closed', + 'agent.acp.frame', + 'agent.acp.stream.closed', + 'agent.acp.catalog.changed', + 'acp.session.update', + 'acp.session.request_permission', + 'acp.session.closed', +] as const + +export const errorCodes = [ + // Protocol / Version + 'INVALID_MESSAGE', + 'UNSUPPORTED_VERSION', + 'CAPABILITY_NOT_SUPPORTED', + 'METHOD_NOT_FOUND', + 'METHOD_NOT_ALLOWED', + 'REQUEST_CONFLICT', + 'FRAME_TOO_LARGE', + 'RATE_LIMITED', + // Auth / Device + 'AUTH_REQUIRED', + 'AUTH_INVALID', + 'ACCOUNT_AUTH_REQUIRED', + 'TOKEN_EXPIRED', + 'DEVICE_NOT_FOUND', + 'DEVICE_REVOKED', + 'DEVICE_OWNERSHIP_REQUIRED', + 'MEMBERSHIP_REQUIRED', + 'PEER_IDENTITY_MISMATCH', + 'HOST_REGISTRATION_CODE_NOT_FOUND', + 'HOST_REGISTRATION_CODE_EXPIRED', + 'HOST_REGISTRATION_CODE_CONSUMED', + // Connection / Transport + 'HOST_OFFLINE', + 'CONNECTION_NOT_FOUND', + 'CONNECTION_FAILED', + 'CONNECTION_REPLACED', + 'P2P_FAILED', + 'TURN_UNAVAILABLE', + 'RELAY_UNAVAILABLE', + 'SLOW_CONSUMER', + 'SECURE_CHANNEL_FAILED', + // Harness + 'HARNESS_UNAVAILABLE', + 'HARNESS_VERSION_INCOMPATIBLE', + 'RESPONSE_TOO_LARGE', + 'SESSION_NOT_FOUND', + 'SESSION_NOT_READY', + 'AGENT_BUSY', + 'PERMISSION_DENIED', + 'PERMISSION_NOT_PENDING', + 'RPC_TIMEOUT', + 'FULL_RESYNC_REQUIRED', + 'INTERNAL_ERROR', +] as const + +/** + * Known wire-protocol error codes from §23. + * + * This is the authoritative reference set; callers should prefer these codes but + * the wire format accepts any string to allow subsystem-specific extensions + * (e.g. CODEX_*, FILE_VIEWER_*) without a protocol version bump. + */ +export type ErrorCode = typeof errorCodes[number] + +export type MessageType = typeof messageTypes[number] +export type ControlFrameType = typeof controlFrameTypes[number] +export type RpcMethod = typeof rpcMethods[number] +export type RemoteEventName = typeof remoteEvents[number] + +export interface HostDeviceDescriptor { + deviceId: string + name: string + role: 'host' + platform: string + identityKey: string + clientVersion: string + harnessVersion?: string +} + +export interface ClientDeviceDescriptor { + deviceId: string + name: string + role: 'client' + platform: string + identityKey: string + clientVersion: string +} + +export type AccountDeviceDescriptor = HostDeviceDescriptor | ClientDeviceDescriptor + +export interface DeviceRegistrationRequest { + v: typeof PROTOCOL_VERSION + device: AccountDeviceDescriptor +} + +export interface HostRegistrationCodeRequest { + v: typeof PROTOCOL_VERSION + code: string + device: HostDeviceDescriptor +} + +export interface DeviceRefreshRequest { + deviceId: string + refreshToken: string +} + +export interface DeviceTokenPair { + accessToken: string + accessTokenExpiresAt: number + refreshToken: string + refreshTokenExpiresAt: number +} + +export interface BrowserAuthorizationExchangeRequest { + v: typeof PROTOCOL_VERSION + device: ClientDeviceDescriptor & { platform: 'browser' } +} + +export interface BrowserAuthorizationExchangeResponse extends DeviceTokenPair { + account: string +} + +export interface ControlFrame { + v: typeof PROTOCOL_VERSION + id: string + type: ControlFrameType + timestamp: number + payload: TPayload +} + +/** Envelope used by the independent Relay data WebSocket. */ +export interface RelayDataFrame = Record> { + v: typeof PROTOCOL_VERSION + id: string + type: string + timestamp: number + payload: TPayload +} + +export interface ControlFrameByteLimits { + maxControlFrameBytes?: number + maxRelayFrameBytes?: number +} + +export interface HelloPayload { + recoveryTickets?: string[] + role: 'host' | 'client' + deviceId: string + accessToken: string + protocols: number[] + capabilities: string[] + /** Version of the Client/Plugin software reporting in; symmetric to ``HelloAckPayload.serverVersion``. */ + clientVersion?: string + /** Host Harness version; sent on first hello to refresh the device record. */ + harnessVersion?: string +} + +export interface HelloAckPayload { + protocol: typeof PROTOCOL_VERSION + serverVersion: string + connectionSessionId: string + heartbeatIntervalMs: number + maxControlFrameBytes: number + maxRelayFrameBytes: number + capabilities?: string[] + /** Optional implementation extension. This field reports WebRTC DataChannel support. */ + webrtcEnabled?: boolean + /** Optional implementation extension. This field sets the Relay fallback timeout. */ + webrtcFallbackTimeoutMs?: number +} + +export interface ConnectRequestPayload { + hostDeviceId: string + preferredTransports: Array<'lan' | 'p2p' | 'turn' | 'relay'> +} + +export interface ConnectIncomingPayload { + relayRecoveryTicket?: string + recoveryTicket?: string + connectionId: string + clientDeviceId: string + clientIdentityKey: string + authorization: 'account' + preferredTransports: Array<'lan' | 'p2p' | 'turn' | 'relay'> + /** Optional independent Relay data-plane assignment. */ + relayEndpoint?: string + relayTicket?: string + relayNodeId?: string + relayEpoch?: number +} + +export interface ConnectAcceptedPayload { + relayRecoveryTicket?: string + recoveryTicket?: string + connectionId: string + /** Optional independent Relay data-plane assignment. */ + relayEndpoint?: string + relayTicket?: string + relayNodeId?: string + relayEpoch?: number +} + +export interface ConnectRejectedPayload { + connectionId: string + code?: string + message?: string +} + +export interface SecureHandshakePayload { + connectionId: string + targetDeviceId: string + step: number + data: string +} + +export interface ControlErrorPayload { + /** §23 defines standard codes. Subsystems can add names such as CODEX_* and FILE_VIEWER_*. */ + code: ErrorCode | (string & {}) + message: string + retryable?: boolean + connectionId?: string +} + +export interface RelayPayload { + connectionId: string + targetDeviceId: string + counter: number + ciphertext: string +} + +export const selectedTransports = ['lan', 'p2p', 'turn', 'relay'] as const +export type SelectedTransport = typeof selectedTransports[number] + +export interface SignalPayload { + connectionId: string + targetDeviceId: string + sdp: string +} + +export interface IceCandidatePayload { + candidate?: string + sdpMid?: string | null + sdpMLineIndex?: number | null + usernameFragment?: string | null +} + +export interface SignalIcePayload { + connectionId: string + targetDeviceId: string + candidate: IceCandidatePayload +} + +export function normalizeSdpMLineIndex(value: unknown): number | null | undefined { + if (value === undefined) return undefined + if (value === null) return null + if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) return null + return value +} + +export interface TransportSelectedPayload { + connectionId: string + targetDeviceId: string + transport: SelectedTransport + /** Relay hostname the client actually used when transport is "turn" + * (best-effort, from ICE stats; absent for other transports). */ + turnNode?: string +} + +/** Capabilities both ends announce in ``hello`` to negotiate the data plane. */ +export const transportCapabilities = [ + 'transport.lan', + 'transport.p2p', + 'transport.turn', + 'transport.relay', +] as const + +/** + * Universe of known harness/transfer/file-viewer/codex capability values (§17). + * + * This is a reference set for type checking and validation, NOT a capability + * set that a Host may advertise wholesale. A Typert Host must advertise only + * the capability matching its Session generation (harness.remote.v1 XOR + * harness.remote.v3); advertising both is a protocol violation. + */ +export const harnessCapabilityValues = [ + 'remote.history.compact.v1', + 'workspace.upload.v1', + 'harness.api.v1', + 'harness.api.transfer.v1', + 'harness.remote.v1', + 'harness.remote.v3', + 'harness.remote.transfer.v1', + 'harness.remote.stream.transfer.v1', + 'fileviewer.read.v1', + 'codex.appserver.v1', + 'codex.appserver.transfer.v1', + 'plugin.route.v1', +] as const + +export type TransportCapability = typeof transportCapabilities[number] +export type HarnessCapabilityValue = typeof harnessCapabilityValues[number] + +export function selectProtocolVersion( + offered: readonly number[], + supported: readonly number[] = [PROTOCOL_VERSION], +): number | undefined { + const supportedVersions = new Set(supported) + return [...offered] + .filter(version => supportedVersions.has(version)) + .sort((left, right) => right - left)[0] +} + +export function selectCapabilities( + offered: readonly string[], + supported: readonly string[], +): string[] { + const offeredCapabilities = new Set(offered) + return [...new Set(supported)].filter(capability => offeredCapabilities.has(capability)) +} + +export function acceptNegotiatedCapabilities( + offered: readonly string[], + negotiated: readonly string[] | undefined, +): string[] { + const accepted = negotiated ?? ['transport.relay'] + if (selectCapabilities(accepted, offered).length !== accepted.length) { + throw new Error('Server selected a capability that the peer did not offer.') + } + return [...accepted] +} + +export interface RemoteMessage { + v: typeof PROTOCOL_VERSION + id: string + type: MessageType + timestamp: number + payload: TPayload +} + +export interface RpcRequestPayload { + method: RpcMethod + params: TParams +} + +export type AcpBackend = 'cursor' | 'claude' | 'opencode' | 'pi' | 'hermes' | 'antigravity' | (string & {}) +export interface AcpInitializeParams { protocolVersion: 1; backend?: AcpBackend } +export interface AcpInitializeResult { protocolVersion: 1; capability: typeof ACP_CAPABILITY; backend: AcpBackend; capabilities: string[]; availableBackends?: AcpBackend[] } +export interface AcpSessionParams { sessionId?: string; cwd?: string; mode?: string; backend?: AcpBackend } +export interface AcpPromptParams { sessionId: string; prompt: string; images?: Array<{ mimeType: string; data: string }> } +export interface AcpPermissionResponseParams { sessionId: string; requestId: string; decision: 'allow_once' | 'deny' } +export interface AcpCancelParams { sessionId: string } +export interface AcpSetModeParams { sessionId: string; mode: string } +export interface AcpSessionUpdate { sessionId: string; update: unknown; seq: number } + +export interface RpcResponsePayload { + requestId: string + result: TResult +} + +export interface RpcErrorPayload { + requestId: string + /** §23 defines standard codes. Subsystems can add names such as CODEX_* and FILE_VIEWER_*. */ + code: ErrorCode | (string & {}) + message: string + retryable?: boolean + details?: unknown +} + +export interface EventPayload { + seq?: number + event: RemoteEventName + sessionId?: string + data: TData +} + +export interface DeviceDescriptor { + deviceId: string + name: string + role: 'host' | 'client' + platform: string + identityKey: string + clientVersion: string + harnessVersion?: string +} + +export interface TransportStats { + mode: 'LAN' | 'P2P' | 'TURN' | 'Relay' | 'Disconnected' + connected: boolean + rttMs?: number + bytesSent?: number + bytesReceived?: number +} + +/** Local plugin web route call tunneled inside the authenticated business channel. */ +export interface PluginRouteCallParams { + route: string + body: { endpoint: string; payload?: Record | null } +} + +export interface PluginRouteCallResult { + status: number + json: unknown +} + +/** Native Harness API request tunneled inside the authenticated business channel. */ +export interface HarnessApiCallParams { + method: string + rpcId: string + payload: unknown +} + +export interface HarnessApiTransferOpenParams { + transferId: string + totalBytes: number + totalChunks: number +} + +export interface HarnessApiTransferChunkParams { + transferId: string + index: number + data: string +} + +export interface HarnessApiTransferCommitParams { + transferId: string +} + +export interface HarnessApiTransferReadParams { + transferId: string + index: number +} + +export interface HarnessApiTransferCloseParams { + transferId: string +} + +export type HarnessApiTransferCommitResult = + | { kind: 'inline'; response: unknown } + | { kind: 'chunked'; transferId: string; totalBytes: number; totalChunks: number } + +export interface HarnessApiTransferReadResult { + transferId: string + index: number + data: string +} + +/** Response to an answerable native Harness server request (approval/question). */ +export interface HarnessApiRespondParams { + message: { + type: 'client-response' + rpcId: string + result: unknown + } +} + +export interface HarnessApiStreamOpenParams { + streamId: string + stream: 'mux' | 'host' + rpcId: string + payload: { + /** Optional mux focus: only forward frames for this session. */ + sessionId?: string + } +} + +export interface HarnessApiStreamCloseParams { + streamId: string +} + +export interface HarnessApiFrameData { + streamId: string + frame: { + rpcId: string + payload: unknown + } +} + +export interface HarnessApiStreamClosedData { + streamId: string + reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' +} + +/** Alpha Typert Remote carrier request after the local Gateway encoded it. */ +export interface HarnessRemoteCallParams { + endpoint: string + payload: unknown +} + +export interface HarnessRemoteStreamOpenParams { + streamId: string + endpoint: string + payload: unknown + /** Opt in only after the Host advertises harness.remote.stream.transfer.v1. */ + transferFrames?: boolean +} + +export interface HarnessRemoteStreamCloseParams { + streamId: string +} + +export interface HarnessRemoteFrameData { + streamId: string + hasValue: true + value?: unknown + /** Mutually exclusive with value; reads reconstruct the complete original frame. */ + transfer?: Extract +} + +export interface HarnessRemoteStreamClosedData { + streamId: string + reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' + failure?: { + code: string + message: string + details: Record + } +} + +export interface RemoteWorkspaceTypeDescription { + id: string + name: string + capability: string + available: boolean +} + +/** Read-only history delivery preference, scoped to one authenticated connection. */ +export interface RemoteHistoryConfigureParams { + compact: boolean +} + +export interface HarnessTransportDescription { + capabilities: string[] + workspaceTypes?: RemoteWorkspaceTypeDescription[] +} + +export type CodexPermissionPreset = 'workspace-write' | 'danger-full-access' + +/** Optional dsh/sessionHistory metadata; null means the Host has no confirmed preset. */ +export interface CodexPermissionSnapshot { + permissionPreset?: CodexPermissionPreset | null +} + +/** Fixed allowlisted Codex App Server call carried inside Remote. */ +export interface CodexAppCallParams { + method: string + params: unknown +} + +export interface CodexAppRespondParams { + requestHandle: string + decision: 'accept' | 'decline' | 'cancel' +} + +export interface CodexAppStreamOpenParams { + streamId: string + threadId: string +} + +export interface CodexAppStreamCloseParams { + streamId: string +} + +export interface CodexAppFrameData { + streamId: string + frame: { + method: string + params: unknown + } +} + +export interface CodexAppStreamClosedData { + streamId: string + reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' +} + +export interface CodexAppTransferOpenParams { + transferId: string + totalBytes: number + totalChunks: number +} + +export interface CodexAppTransferChunkParams { + transferId: string + index: number + data: string +} + +export interface CodexAppTransferCommitParams { transferId: string } +export interface CodexAppTransferReadParams { transferId: string; index: number } +export interface CodexAppTransferCloseParams { transferId: string } + +export type CodexAppTransferCommitResult = + | { kind: 'inline'; response: unknown } + | { kind: 'chunked'; transferId: string; totalBytes: number; totalChunks: number } + +export interface CodexAppTransferReadResult { + transferId: string + index: number + data: string +} + +/** Fixed allowlisted Agent ACP call carried inside Remote. */ +export interface AgentAcpCallParams { + method: string + params: unknown +} + +export interface AcpSessionArchivedData { backend: 'opencode'; sessionId: string; archived: true } + +export interface AgentAcpRespondParams { + requestHandle: string + decision: 'allow-once' | 'reject-once' | 'cancel' + /** Optional structured answer for backend extension methods (ask_question / create_plan). */ + result?: unknown +} + +export type AcpWorkspaceToolCallEndpoint = 'workspaceFiles/list' | 'workspaceFiles/stat' | 'workspaceFiles/read' | 'workspaceFiles/readBytes' | 'workspaceFiles/readAll' + | 'terminal/environment' | 'terminal/shells' | 'terminal/list' | 'terminal/create' | 'terminal/write' | 'terminal/resize' | 'terminal/rename' | 'terminal/close' +export type AcpWorkspaceToolStreamEndpoint = 'workspaceFiles/changes' | 'terminal/follow' | 'terminal/retain' +export interface AcpWorkspaceToolParams { sessionId: string; backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes'; endpoint: AcpWorkspaceToolCallEndpoint; args: Record } +export interface AcpModelParams { sessionId: string; backend: 'cursor' | 'claude' | 'antigravity' | 'pi' | 'opencode' } +export interface AcpModelSelectionParams extends AcpModelParams { model: string; reasoningEffort?: string } +export interface AgentAcpStreamOpenParams { + streamId: string + sessionId: string + tool?: { backend: 'cursor' | 'antigravity' | 'pi' | 'opencode' | 'claude' | 'hermes'; endpoint: AcpWorkspaceToolStreamEndpoint; args: Record } +} + +export interface AgentAcpStreamCloseParams { + streamId: string +} + +export interface AgentAcpFrameData { + streamId: string + frame: { + method: string + params: unknown + } +} + +export interface AgentAcpStreamClosedData { + streamId: string + reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected' +} + +export interface AgentAcpTransferOpenParams { + transferId: string + totalBytes: number + totalChunks: number +} + +export interface AgentAcpTransferChunkParams { + transferId: string + index: number + data: string +} + +export interface AgentAcpTransferCommitParams { transferId: string } +export interface AgentAcpTransferReadParams { transferId: string; index: number } +export interface AgentAcpTransferCloseParams { transferId: string } + +export type AgentAcpTransferCommitResult = + | { kind: 'inline'; response: unknown } + | { kind: 'chunked'; transferId: string; totalBytes: number; totalChunks: number } + +export interface AgentAcpTransferReadResult { + transferId: string + index: number + data: string +} + +const rpcMethodSchema = z.enum(rpcMethods) +const messageTypeSchema = z.enum(messageTypes) +const controlFrameTypeSchema = z.enum(controlFrameTypes) +export const errorCodeSchema = z.enum(errorCodes) +const uniqueStrings = (values: string[]): boolean => new Set(values).size === values.length +const uniqueNumbers = (values: number[]): boolean => new Set(values).size === values.length +const utf8Length = (value: string): number => new TextEncoder().encode(value).byteLength +const boundedUtf8Schema = (minimum: number, maximum: number): z.ZodType => z.string() + .refine(value => utf8Length(value) >= minimum && utf8Length(value) <= maximum) + +const deviceIdSchema = z.string().refine(value => ( + /^[0-9A-HJKMNP-TV-Z]{26}$/iu.test(value) + || /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/iu.test(value) +), 'Device ID must be a ULID or UUID.') +const deviceNameSchema = boundedUtf8Schema(1, MAX_DEVICE_NAME_LENGTH) + .refine(value => value.trim().length > 0, 'Device name must contain visible text.') +const devicePlatformSchema = z.string().min(1).max(MAX_DEVICE_PLATFORM_LENGTH) + .regex(/^[a-z0-9][a-z0-9._-]*$/u) +const identityKeySchema = z.string().regex(/^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/u) +const canonicalBase64UrlSchema = z.string().min(1).regex(/^[A-Za-z0-9_-]+$/u).refine(value => { + const remainder = value.length % 4 + if (remainder === 1) return false + if (remainder === 0) return true + const alphabet = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_' + const last = alphabet.indexOf(value.at(-1)!) + return remainder === 2 ? (last & 15) === 0 : (last & 3) === 0 +}, 'Value must use canonical Base64URL without padding.') +const deviceVersionSchema = boundedUtf8Schema(1, MAX_DEVICE_VERSION_LENGTH) +const authTokenSchema = boundedUtf8Schema(16, MAX_AUTH_TOKEN_LENGTH) +const expiresAtSchema = z.number().int().positive().safe() + +export const hostDeviceDescriptorSchema: z.ZodType = z.object({ + deviceId: deviceIdSchema, + name: deviceNameSchema, + role: z.literal('host'), + platform: devicePlatformSchema, + identityKey: identityKeySchema, + clientVersion: deviceVersionSchema, + harnessVersion: deviceVersionSchema.optional(), +}).strict() + +export const clientDeviceDescriptorSchema: z.ZodType = z.object({ + deviceId: deviceIdSchema, + name: deviceNameSchema, + role: z.literal('client'), + platform: devicePlatformSchema, + identityKey: identityKeySchema, + clientVersion: deviceVersionSchema, +}).strict() + +export const accountDeviceDescriptorSchema: z.ZodType = z.union([ + hostDeviceDescriptorSchema, + clientDeviceDescriptorSchema, +]) + +export const deviceRegistrationRequestSchema: z.ZodType = z.object({ + v: z.literal(PROTOCOL_VERSION), + device: accountDeviceDescriptorSchema, +}).strict() + +export const hostRegistrationCodeRequestSchema: z.ZodType = z.object({ + v: z.literal(PROTOCOL_VERSION), + code: z.string().regex(/^[A-Z0-9]{4}-[A-Z0-9]{4}$/u), + device: hostDeviceDescriptorSchema, +}).strict() + +/** §8.1.2 Register a new opposite-role device using an existing device access token. */ +export interface RegisterOwnedRoleRequest { + v: typeof PROTOCOL_VERSION + device: AccountDeviceDescriptor +} + +export const registerOwnedRoleRequestSchema: z.ZodType = z.object({ + v: z.literal(PROTOCOL_VERSION), + device: accountDeviceDescriptorSchema, +}).strict() + +export const deviceRefreshRequestSchema: z.ZodType = z.object({ + deviceId: deviceIdSchema, + refreshToken: authTokenSchema, +}).strict() + +export const deviceTokenPairSchema: z.ZodType = z.object({ + accessToken: authTokenSchema, + accessTokenExpiresAt: expiresAtSchema, + refreshToken: authTokenSchema, + refreshTokenExpiresAt: expiresAtSchema, +}).strict() + +export const browserAuthorizationExchangeRequestSchema: z.ZodType = z.object({ + v: z.literal(PROTOCOL_VERSION), + device: z.object({ + deviceId: deviceIdSchema, + name: deviceNameSchema, + role: z.literal('client'), + platform: z.literal('browser'), + identityKey: identityKeySchema, + clientVersion: deviceVersionSchema, + }).strict(), +}).strict() + +export const browserAuthorizationExchangeResponseSchema: z.ZodType = z.object({ + accessToken: authTokenSchema, + accessTokenExpiresAt: expiresAtSchema, + refreshToken: authTokenSchema, + refreshTokenExpiresAt: expiresAtSchema, + account: boundedUtf8Schema(1, 254).refine(value => value.trim().length > 0), +}).strict() + +export const remoteMessageSchema = z.object({ + v: z.literal(PROTOCOL_VERSION), + id: z.string().min(1), + type: messageTypeSchema, + timestamp: z.number().int().positive(), + payload: z.unknown(), +}) as unknown as z.ZodType + +export const controlFrameSchema = z.object({ + v: z.literal(PROTOCOL_VERSION), + id: z.string().min(1), + type: controlFrameTypeSchema, + timestamp: z.number().int().positive(), + payload: z.unknown(), +}).strict() as unknown as z.ZodType + +export const relayDataFrameSchema: z.ZodType = z.object({ + v: z.literal(PROTOCOL_VERSION), + id: z.string().min(1), + type: z.string().min(1), + timestamp: z.number().int().positive().safe(), + payload: z.record(z.string(), z.unknown()), +}).strict() + +// ──────────────────────────────────────────────────────────────────────────── +// Control frame payload schemas (protocol.md §10-§23) +// ──────────────────────────────────────────────────────────────────────────── + +const transportEnum = z.enum(['lan', 'p2p', 'turn', 'relay']) +const selectedTransportEnum = z.enum(selectedTransports) +const MAX_PROTOCOL_LIST_ENTRIES = 16 +const MAX_CAPABILITY_ENTRIES = MAX_REMOTE_CAPABILITY_ENTRIES +const MAX_WORKSPACE_TYPE_ENTRIES = MAX_REMOTE_WORKSPACE_TYPE_ENTRIES +const MAX_PREFERRED_TRANSPORT_ENTRIES = selectedTransports.length + +export const helloPayloadSchema = z.object({ + recoveryTickets: z.array(z.string().min(1).max(4096)).max(64).optional(), + role: z.enum(['host', 'client']), + deviceId: z.string().min(1), + accessToken: z.string().min(1), + protocols: z.array(z.unknown()).min(1).max(MAX_PROTOCOL_LIST_ENTRIES).pipe( + z.array(z.number().int().nonnegative().safe()).refine(uniqueNumbers), + ), + capabilities: z.array(z.unknown()).max(MAX_CAPABILITY_ENTRIES).pipe( + z.array(z.string().min(1)).refine(uniqueStrings), + ), + clientVersion: z.string().optional(), + harnessVersion: z.string().optional(), +}) + +export const helloAckPayloadSchema = z.object({ + protocol: z.literal(PROTOCOL_VERSION), + serverVersion: z.string().min(1), + connectionSessionId: z.string().min(1), + heartbeatIntervalMs: z.number().int().positive().safe(), + maxControlFrameBytes: z.number().int().positive().max(MAX_CONTROL_FRAME_BYTES), + maxRelayFrameBytes: z.number().int().positive().max(MAX_RELAY_FRAME_BYTES), + capabilities: z.array(z.unknown()).max(MAX_CAPABILITY_ENTRIES).pipe( + z.array(z.string().min(1)).refine(uniqueStrings), + ).optional(), + webrtcEnabled: z.boolean().optional(), + webrtcFallbackTimeoutMs: z.number().int().positive().safe().optional(), +}) + +export const remoteWorkspaceTypeDescriptionSchema = z.object({ + id: z.string().min(1), + name: z.string().min(1), + capability: z.string().min(1), + available: z.boolean(), +}) + +export const harnessTransportDescriptionSchema = z.object({ + capabilities: z.array(z.unknown()).max(MAX_CAPABILITY_ENTRIES).pipe( + z.array(z.string().min(1)).refine(uniqueStrings), + ), + workspaceTypes: z.array(z.unknown()).max(MAX_WORKSPACE_TYPE_ENTRIES).pipe( + z.array(remoteWorkspaceTypeDescriptionSchema), + ).optional(), +}) + +export function parseRemoteWorkspaceTypes(value: unknown): RemoteWorkspaceTypeDescription[] { + if (!Array.isArray(value)) return [] + if (value.length > MAX_WORKSPACE_TYPE_ENTRIES) return [] + const types: RemoteWorkspaceTypeDescription[] = [] + for (const item of value) { + const result = remoteWorkspaceTypeDescriptionSchema.safeParse(item) + if (result.success) { + types.push(result.data) + } + } + return types +} + +export const connectRequestPayloadSchema = z.object({ + hostDeviceId: z.string().min(1), + preferredTransports: z.array(z.unknown()).min(1).max(MAX_PREFERRED_TRANSPORT_ENTRIES).pipe( + z.array(transportEnum), + ), +}) + +export const connectIncomingPayloadSchema = z.object({ + relayRecoveryTicket: z.string().min(1).max(4096).optional(), + recoveryTicket: z.string().min(1).max(4096).optional(), + connectionId: z.string().min(1), + clientDeviceId: z.string().min(1), + clientIdentityKey: identityKeySchema, + authorization: z.literal('account'), + preferredTransports: z.array(z.unknown()).min(1).max(MAX_PREFERRED_TRANSPORT_ENTRIES).pipe( + z.array(transportEnum), + ), + relayEndpoint: z.string().url().optional(), + relayTicket: z.string().min(1).optional(), + relayNodeId: z.string().min(1).optional(), + relayEpoch: z.number().int().nonnegative().optional(), +}) + +export const connectAcceptedPayloadSchema = z.object({ + relayRecoveryTicket: z.string().min(1).max(4096).optional(), + recoveryTicket: z.string().min(1).max(4096).optional(), + connectionId: z.string().min(1), + relayEndpoint: z.string().url().optional(), + relayTicket: z.string().min(1).optional(), + relayNodeId: z.string().min(1).optional(), + relayEpoch: z.number().int().nonnegative().optional(), +}) + +export const connectRejectedPayloadSchema = z.object({ + connectionId: z.string().min(1), + code: z.string().optional(), + message: z.string().optional(), +}) + +export const secureHandshakePayloadSchema = z.object({ + connectionId: z.string().min(1), + targetDeviceId: z.string().min(1), + step: z.union([z.literal(1), z.literal(2)]), + data: canonicalBase64UrlSchema, +}) + +export const relayPayloadSchema = z.object({ + connectionId: z.string().min(1), + targetDeviceId: z.string().min(1), + counter: z.number().int().nonnegative().safe(), + ciphertext: canonicalBase64UrlSchema, +}) + +export const signalPayloadSchema = z.object({ + connectionId: z.string().min(1), + targetDeviceId: z.string().min(1), + sdp: z.string().min(1), +}) + +export const signalIcePayloadSchema = z.object({ + connectionId: z.string().min(1), + targetDeviceId: z.string().min(1), + candidate: z.object({ + candidate: z.string().optional(), + sdpMid: z.string().nullable().optional(), + sdpMLineIndex: z.preprocess(normalizeSdpMLineIndex, z.number().int().nonnegative().nullable().optional()), + usernameFragment: z.string().nullable().optional(), + }), +}) + +export const transportSelectedPayloadSchema = z.object({ + connectionId: z.string().min(1), + targetDeviceId: z.string().min(1), + transport: selectedTransportEnum, + /** Relay hostname the initiator actually used when transport is "turn" + * (best-effort, from ICE stats; absent for other transports). */ + turnNode: z.string().min(1).max(253).optional(), +}) + +export const pingPongPayloadSchema = z.object({ + nonce: z.string().min(1), +}) + +export const controlErrorPayloadSchema = z.object({ + code: z.string().min(1), + message: z.string().min(1), + retryable: z.boolean().optional(), + connectionId: z.string().min(1).optional(), +}) + +export const connectionLeaseRequestSchema = z.object({ + connectionId: z.string().min(1).max(128), + requestId: z.string().min(1).max(128), + ticket: z.string().min(1).max(4096), +}) +export const connectionLeaseAckSchema = connectionLeaseRequestSchema.extend({ + leaseMs: z.literal(WEBRTC_LEASE_MS), +}) +export type ConnectionLeaseAck = z.infer + +const controlFramePayloadSchemas: Record = { + 'hello': helloPayloadSchema, + 'hello.ack': helloAckPayloadSchema, + 'connect.request': connectRequestPayloadSchema, + 'connect.incoming': connectIncomingPayloadSchema, + 'connect.accepted': connectAcceptedPayloadSchema, + 'connect.rejected': connectRejectedPayloadSchema, + 'secure.handshake': secureHandshakePayloadSchema, + 'relay': relayPayloadSchema, + 'signal.offer': signalPayloadSchema, + 'signal.answer': signalPayloadSchema, + 'signal.ice': signalIcePayloadSchema, + 'transport.selected': transportSelectedPayloadSchema, + 'connection.lease.request': connectionLeaseRequestSchema, + 'connection.lease.ack': connectionLeaseAckSchema, + 'connection.lease.close': z.object({ connectionId: z.string().min(1).max(128) }), + 'ping': pingPongPayloadSchema, + 'pong': pingPongPayloadSchema, + 'error': controlErrorPayloadSchema, +} + +export const rpcRequestPayloadSchema = z.object({ + method: rpcMethodSchema, + params: z.unknown(), +}) as unknown as z.ZodType + +export const rpcResponsePayloadSchema = z.object({ + requestId: z.string().min(1), + result: z.unknown(), +}) as unknown as z.ZodType + +export const rpcErrorPayloadSchema: z.ZodType = z.object({ + requestId: z.string().min(1), + code: z.string().min(1), + message: z.string().min(1), + retryable: z.boolean().optional(), + details: z.unknown().optional(), +}) + +export function createMessage( + type: MessageType, + payload: TPayload, + id = cryptoRandomId(), +): RemoteMessage { + return { + v: PROTOCOL_VERSION, + id, + type, + timestamp: Date.now(), + payload, + } +} + +export function createControlFrame( + type: ControlFrameType, + payload: TPayload, + id = cryptoRandomId(), +): ControlFrame { + return { + v: PROTOCOL_VERSION, + id, + type, + timestamp: Date.now(), + payload, + } +} + +export function createRelayDataFrame>( + type: string, + payload: TPayload, + id = cryptoRandomId(), +): RelayDataFrame { + return { + v: PROTOCOL_VERSION, + id, + type, + timestamp: Date.now(), + payload, + } +} + +export function createRpcRequest( + method: RpcMethod, + params: TParams, + id?: string, +): RemoteMessage> { + return createMessage('rpc.request', { method, params }, id) +} + +export function createRpcResponse( + requestId: string, + result: TResult, +): RemoteMessage> { + return createMessage('rpc.response', { requestId, result }) +} + +export function createRpcError( + requestId: string, + code: ErrorCode | (string & {}), + message: string, + details?: unknown, + retryable?: boolean, +): RemoteMessage { + return createMessage('rpc.error', { requestId, code, message, details, retryable }) +} + +export function createEvent( + event: RemoteEventName, + data: TData, + options: { seq?: number; sessionId?: string } = {}, +): RemoteMessage> { + return createMessage('event', { event, data, ...options }) +} + +export function parseRemoteMessage(input: unknown): RemoteMessage { + return remoteMessageSchema.parse(input) +} + +export function parseControlFrame(input: unknown): ControlFrame { + const frame = controlFrameSchema.parse(input) + const payloadSchema = controlFramePayloadSchemas[frame.type] + if (payloadSchema) { + return { ...frame, payload: payloadSchema.parse(frame.payload) } + } + return frame +} + +export function encodeControlFrame(frame: ControlFrame, limits: ControlFrameByteLimits = {}): string { + const parsed = parseControlFrame(frame) + const encoded = JSON.stringify(parsed) + assertControlFrameSize(new TextEncoder().encode(encoded).byteLength, parsed.type, limits) + return encoded +} + +export function decodeControlFrame(data: Uint8Array | string, limits: ControlFrameByteLimits = {}): ControlFrame { + const encoded = typeof data === 'string' ? new TextEncoder().encode(data) : data + if (encoded.byteLength > MAX_RELAY_FRAME_BYTES) throw new Error('Control frame exceeds the Relay frame limit.') + const frame = parseControlFrame(parseWireJson(data)) + assertControlFrameSize(encoded.byteLength, frame.type, limits) + return frame +} + +export function encodeRelayDataFrame( + frame: RelayDataFrame, + limits: ControlFrameByteLimits = {}, +): string { + const parsed = parseRelayDataFrame(frame) + const encoded = JSON.stringify(parsed) + assertControlFrameSize(new TextEncoder().encode(encoded).byteLength, 'relay', limits) + return encoded +} + +export function decodeRelayDataFrame( + data: Uint8Array | string, + limits: ControlFrameByteLimits = {}, +): RelayDataFrame { + const encoded = typeof data === 'string' ? new TextEncoder().encode(data) : data + assertControlFrameSize(encoded.byteLength, 'relay', limits) + try { + return parseRelayDataFrame(parseWireJson(data)) + } catch { + throw new Error('Invalid Relay data frame.') + } +} + +function parseRelayDataFrame(input: unknown): RelayDataFrame { + const frame = relayDataFrameSchema.parse(input) + if (frame.type === 'relay') return { ...frame, payload: relayPayloadSchema.parse(frame.payload) } + if (frame.type === 'secure.handshake') return { ...frame, payload: secureHandshakePayloadSchema.parse(frame.payload) } + return frame +} + +export function encodeMessage(message: RemoteMessage): Uint8Array { + return new TextEncoder().encode(JSON.stringify(message)) +} + +export function decodeMessage(data: Uint8Array | string): RemoteMessage { + return parseRemoteMessage(parseWireJson(data)) +} + +interface FragmentAssembly { + total: number + totalBytes: number + receivedBytes: number + chunks: Uint8Array[] +} + +/** + * Splits application plaintext before Noise encryption and reassembles it + * after decryption. Noise transport messages have a 65,535-byte ceiling, so + * large native ApiProxy responses cannot be encrypted as one message. + */ +export class SecureMessageCodec { + private nextMessageId = 1 + private readonly assemblies = new Map() + + encode(message: Uint8Array): Uint8Array[] { + if (message.byteLength > MAX_SECURE_MESSAGE_BYTES) { + throw new Error('Secure message exceeds the reassembly limit.') + } + if (message.byteLength <= SECURE_FRAGMENT_CHUNK_BYTES) return [message] + + const messageId = this.nextMessageId + this.nextMessageId = messageId === 0xffff_ffff ? 1 : messageId + 1 + const total = Math.ceil(message.byteLength / SECURE_FRAGMENT_CHUNK_BYTES) + const frames: Uint8Array[] = [] + for (let index = 0; index < total; index += 1) { + const start = index * SECURE_FRAGMENT_CHUNK_BYTES + const chunk = message.subarray(start, Math.min(message.byteLength, start + SECURE_FRAGMENT_CHUNK_BYTES)) + const frame = new Uint8Array(SECURE_FRAGMENT_HEADER_BYTES + chunk.byteLength) + frame.set(SECURE_FRAGMENT_MAGIC) + frame[4] = SECURE_FRAGMENT_VERSION + const view = new DataView(frame.buffer) + view.setUint32(5, messageId) + view.setUint16(9, index) + view.setUint16(11, total) + view.setUint32(13, message.byteLength) + frame.set(chunk, SECURE_FRAGMENT_HEADER_BYTES) + frames.push(frame) + } + return frames + } + + decode(frame: Uint8Array): Uint8Array | undefined { + if (!isSecureFragment(frame)) return frame + if (frame.byteLength < SECURE_FRAGMENT_HEADER_BYTES || frame[4] !== SECURE_FRAGMENT_VERSION) { + throw new Error('Secure fragment header is invalid.') + } + const view = new DataView(frame.buffer, frame.byteOffset, frame.byteLength) + const messageId = view.getUint32(5) + const index = view.getUint16(9) + const total = view.getUint16(11) + const totalBytes = view.getUint32(13) + if (messageId === 0 || total < 2 || index >= total || totalBytes <= SECURE_FRAGMENT_CHUNK_BYTES + || totalBytes > MAX_SECURE_MESSAGE_BYTES + || total !== Math.ceil(totalBytes / SECURE_FRAGMENT_CHUNK_BYTES)) { + throw new Error('Secure fragment metadata is invalid.') + } + const expectedChunkBytes = Math.min( + SECURE_FRAGMENT_CHUNK_BYTES, + totalBytes - index * SECURE_FRAGMENT_CHUNK_BYTES, + ) + const chunk = frame.subarray(SECURE_FRAGMENT_HEADER_BYTES) + if (chunk.byteLength !== expectedChunkBytes) throw new Error('Secure fragment length is invalid.') + + let assembly = this.assemblies.get(messageId) + if (assembly === undefined) { + if (index !== 0 || this.assemblies.size >= MAX_IN_FLIGHT_SECURE_MESSAGES) { + throw new Error('Secure fragment sequence is invalid.') + } + assembly = { total, totalBytes, receivedBytes: 0, chunks: [] } + this.assemblies.set(messageId, assembly) + } + if (assembly.total !== total || assembly.totalBytes !== totalBytes || index !== assembly.chunks.length) { + this.assemblies.delete(messageId) + throw new Error('Secure fragment sequence is invalid.') + } + assembly.chunks.push(Uint8Array.from(chunk)) + assembly.receivedBytes += chunk.byteLength + if (assembly.chunks.length < total) return undefined + this.assemblies.delete(messageId) + if (assembly.receivedBytes !== totalBytes) throw new Error('Secure message length is invalid.') + const message = new Uint8Array(totalBytes) + let offset = 0 + for (const part of assembly.chunks) { + message.set(part, offset) + offset += part.byteLength + } + return message + } + + reset(): void { + this.nextMessageId = 1 + this.assemblies.clear() + } +} + +function isSecureFragment(frame: Uint8Array): boolean { + if (frame.byteLength < SECURE_FRAGMENT_MAGIC.byteLength) return false + for (let index = 0; index < SECURE_FRAGMENT_MAGIC.byteLength; index += 1) { + if (frame[index] !== SECURE_FRAGMENT_MAGIC[index]) return false + } + return true +} + +function assertControlFrameSize(bytes: number, type: ControlFrameType, limits: ControlFrameByteLimits): void { + const configured = type === 'relay' ? limits.maxRelayFrameBytes : limits.maxControlFrameBytes + const protocolMaximum = type === 'relay' ? MAX_RELAY_FRAME_BYTES : MAX_CONTROL_FRAME_BYTES + const maximum = configured === undefined ? protocolMaximum : Math.min(protocolMaximum, configured) + if (!Number.isSafeInteger(maximum) || maximum <= 0) throw new Error('Control frame limit is invalid.') + if (bytes > maximum) throw new Error(`${type === 'relay' ? 'Relay' : 'Control'} frame exceeds its limit.`) +} + +function cryptoRandomId(): string { + const g = globalThis.crypto + if (g?.randomUUID) return g.randomUUID() + return `msg_${Date.now().toString(36)}_${Math.random().toString(36).slice(2)}` +}