1481 lines
49 KiB
TypeScript
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)}`
|
|
}
|