ds-harness-remote-fast/packages/protocol/src/index.ts

1481 lines
49 KiB
TypeScript

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<TPayload = unknown> {
v: typeof PROTOCOL_VERSION
id: string
type: ControlFrameType
timestamp: number
payload: TPayload
}
/** Envelope used by the independent Relay data WebSocket. */
export interface RelayDataFrame<TPayload extends Record<string, unknown> = Record<string, unknown>> {
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<TPayload = unknown> {
v: typeof PROTOCOL_VERSION
id: string
type: MessageType
timestamp: number
payload: TPayload
}
export interface RpcRequestPayload<TParams = unknown> {
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<TResult = unknown> {
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<TData = unknown> {
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<string, unknown> | 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<HarnessApiTransferCommitResult, { kind: 'chunked' }>
}
export interface HarnessRemoteStreamClosedData {
streamId: string
reason: 'cancelled' | 'completed' | 'failed' | 'peer-disconnected'
failure?: {
code: string
message: string
details: Record<string, unknown>
}
}
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<string, unknown> }
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<string, unknown> }
}
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<string> => 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<HostDeviceDescriptor> = 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<ClientDeviceDescriptor> = z.object({
deviceId: deviceIdSchema,
name: deviceNameSchema,
role: z.literal('client'),
platform: devicePlatformSchema,
identityKey: identityKeySchema,
clientVersion: deviceVersionSchema,
}).strict()
export const accountDeviceDescriptorSchema: z.ZodType<AccountDeviceDescriptor> = z.union([
hostDeviceDescriptorSchema,
clientDeviceDescriptorSchema,
])
export const deviceRegistrationRequestSchema: z.ZodType<DeviceRegistrationRequest> = z.object({
v: z.literal(PROTOCOL_VERSION),
device: accountDeviceDescriptorSchema,
}).strict()
export const hostRegistrationCodeRequestSchema: z.ZodType<HostRegistrationCodeRequest> = 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<RegisterOwnedRoleRequest> = z.object({
v: z.literal(PROTOCOL_VERSION),
device: accountDeviceDescriptorSchema,
}).strict()
export const deviceRefreshRequestSchema: z.ZodType<DeviceRefreshRequest> = z.object({
deviceId: deviceIdSchema,
refreshToken: authTokenSchema,
}).strict()
export const deviceTokenPairSchema: z.ZodType<DeviceTokenPair> = z.object({
accessToken: authTokenSchema,
accessTokenExpiresAt: expiresAtSchema,
refreshToken: authTokenSchema,
refreshTokenExpiresAt: expiresAtSchema,
}).strict()
export const browserAuthorizationExchangeRequestSchema: z.ZodType<BrowserAuthorizationExchangeRequest> = 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<BrowserAuthorizationExchangeResponse> = 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<RemoteMessage>
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<ControlFrame>
export const relayDataFrameSchema: z.ZodType<RelayDataFrame> = 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<typeof connectionLeaseAckSchema>
const controlFramePayloadSchemas: Record<ControlFrameType, z.ZodType> = {
'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<RpcRequestPayload>
export const rpcResponsePayloadSchema = z.object({
requestId: z.string().min(1),
result: z.unknown(),
}) as unknown as z.ZodType<RpcResponsePayload>
export const rpcErrorPayloadSchema: z.ZodType<RpcErrorPayload> = 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<TPayload>(
type: MessageType,
payload: TPayload,
id = cryptoRandomId(),
): RemoteMessage<TPayload> {
return {
v: PROTOCOL_VERSION,
id,
type,
timestamp: Date.now(),
payload,
}
}
export function createControlFrame<TPayload>(
type: ControlFrameType,
payload: TPayload,
id = cryptoRandomId(),
): ControlFrame<TPayload> {
return {
v: PROTOCOL_VERSION,
id,
type,
timestamp: Date.now(),
payload,
}
}
export function createRelayDataFrame<TPayload extends Record<string, unknown>>(
type: string,
payload: TPayload,
id = cryptoRandomId(),
): RelayDataFrame<TPayload> {
return {
v: PROTOCOL_VERSION,
id,
type,
timestamp: Date.now(),
payload,
}
}
export function createRpcRequest<TParams>(
method: RpcMethod,
params: TParams,
id?: string,
): RemoteMessage<RpcRequestPayload<TParams>> {
return createMessage('rpc.request', { method, params }, id)
}
export function createRpcResponse<TResult>(
requestId: string,
result: TResult,
): RemoteMessage<RpcResponsePayload<TResult>> {
return createMessage('rpc.response', { requestId, result })
}
export function createRpcError(
requestId: string,
code: ErrorCode | (string & {}),
message: string,
details?: unknown,
retryable?: boolean,
): RemoteMessage<RpcErrorPayload> {
return createMessage('rpc.error', { requestId, code, message, details, retryable })
}
export function createEvent<TData>(
event: RemoteEventName,
data: TData,
options: { seq?: number; sessionId?: string } = {},
): RemoteMessage<EventPayload<TData>> {
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<number, FragmentAssembly>()
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)}`
}