ds-harness-remote-fast/packages/plugin/src/config.ts

423 lines
18 KiB
TypeScript

import { hostname } from 'node:os'
import type { Volatile, VolatileSnapshot } from '@deepseek-ai/cordis'
import s from '@deepseek-ai/schemastery'
import { z } from 'zod'
export const DEFAULT_REMOTE_SERVER_URL = 'https://dsh.r2049.cn'
export interface Config {
enabled?: boolean
role?: 'host' | 'client' | 'both'
serverUrl?: string
/** Additional hosts or CIDR ranges that may use HTTP for a self-hosted Server. */
httpServerAllowlist?: string[]
deviceName?: string
terminal?: { enabled?: boolean }
remoteTools?: { enabled?: boolean }
/** Where the Desktop client shows the Remote entry: beside Settings or in the account row. */
sidebar?: { entry?: 'standard' | 'compact' }
hostControl?: { enabled?: boolean }
loopback?: { ports?: number[] }
forceRelay?: boolean
/**
* When a known peer device presents a NEW identity key after re-authorizing with the
* same account membership (e.g. the peer reinstalled the Harness), rotate the pinned
* key instead of rejecting the connection. The new key is validated against the
* account directory before this policy applies. Default: false (pin strictly).
*/
rotatePinnedPeerKey?: boolean
logLevel?: 'debug' | 'info' | 'warn' | 'error'
/**
* Send remote clients only what they need: the initial history page keeps the latest
* few messages and oversized plugin projections are dropped. Cuts the first-paint
* payload from megabytes to kilobytes on large sessions. Default: false.
*/
liteMode?: boolean
reconnect?: boolean | {
initialDelayMs?: number
maxDelayMs?: number
jitter?: number
}
/** Optional Codex domain carried by the existing authenticated Remote Plugin. */
codex?: {
enabled?: boolean
binary?: string
}
/** Optional Cursor ACP domain carried by the existing authenticated Remote Plugin. */
cursor?: {
enabled?: boolean
binary?: string
}
acp?: { enabled?: boolean; backends?: Array<{ id:string; enabled?: boolean; command?: string; args?: string[]; cwd?: string }>; backend?: string; command?: string; args?: string[]; cwd?: string }
}
export interface ResolvedCodexConfig {
enabled: boolean
binary: string
}
export interface ResolvedCursorConfig {
enabled: boolean
binary: string
}
export interface ResolvedAcpBackendConfig {
id: string
enabled: boolean
command: string
args: string[]
cwd?: string
}
export interface ResolvedAcpConfig {
enabled: boolean
backends: ResolvedAcpBackendConfig[]
}
export interface ResolvedConfig {
enabled: boolean
role: 'host' | 'client' | 'both'
serverUrl?: string
httpServerAllowlist: string[]
deviceName: string
forceRelay: boolean
rotatePinnedPeerKey: boolean
logLevel: 'debug' | 'info' | 'warn' | 'error'
liteMode: boolean
reconnect: {
enabled: boolean
initialDelayMs: number
maxDelayMs: number
jitter: number
}
terminal: { enabled: boolean }
remoteTools?: { enabled: boolean }
sidebar: { entry: 'standard' | 'compact' }
hostControl?: { enabled: boolean }
loopback: { ports: number[] }
codex: ResolvedCodexConfig
cursor: ResolvedCursorConfig
acp?: ResolvedAcpConfig
}
/** The entry's volatile Cordis config: one stable reference for the whole section. */
export type EntryConfig = Volatile<Config>
/** Config accepted by {@link resolveConfig}: the composition seed or a live snapshot. */
export type ConfigInput = Config | VolatileSnapshot<Config>
/**
* Schemastery schema for the plugin entry. On DSH 0.1.7-rc.1 and newer the
* whole section is `.volatile()` (DSH-0.1.7-RC1-04): the Loader hands `apply`
* a single live reference whose `.get()` always returns the latest committed
* value, and the settings service persists edits in the active profile's
* `cordis.patch.yml` under this entry id. On older hosts the helper above keeps
* the plain schema required by the namespace-registration API.
*/
export const entryConfigSchema = s.object({
enabled: s.boolean(),
role: s.union(['host', 'client', 'both'] as const),
serverUrl: s.string(),
httpServerAllowlist: s.array(s.string()),
deviceName: s.string(),
terminal: s.object({ enabled: s.boolean() }),
remoteTools: s.object({ enabled: s.boolean() }),
sidebar: s.object({ entry: s.union(['standard', 'compact'] as const) }),
hostControl: s.object({ enabled: s.boolean() }),
loopback: s.object({ ports: s.array(s.number()) }),
forceRelay: s.boolean(),
rotatePinnedPeerKey: s.boolean(),
logLevel: s.union(['debug', 'info', 'warn', 'error'] as const),
liteMode: s.boolean().default(true),
reconnect: s.union([
s.boolean(),
s.object({
initialDelayMs: s.number(),
maxDelayMs: s.number(),
jitter: s.number(),
}),
]),
codex: s.object({
enabled: s.boolean(),
binary: s.string(),
}),
cursor: s.object({
enabled: s.boolean(),
binary: s.string(),
}),
acp: s.object({ enabled: s.boolean(), backends: s.array(s.object({ id:s.string(), enabled:s.boolean(), command:s.string(), args:s.array(s.string()), cwd:s.string() })) }),
})
/**
* Mark the entry as live-editable when the host Schemastery supports the
* 0.1.7 volatile schema mode. Older DSH releases ship an earlier Schemastery
* where the method does not exist; their settings registry expects the plain
* schema and must still be able to import the plugin without throwing.
*/
export function withVolatileSchema<T>(schema: T): T {
const volatile = (schema as { volatile?: unknown }).volatile
return typeof volatile === 'function'
? (volatile as (this: T) => T).call(schema)
: schema
}
export const Config: s<Config> = withVolatileSchema(entryConfigSchema) as unknown as s<Config>
const reconnectSchema = z.union([
z.boolean(),
z.object({
initialDelayMs: z.number().int().min(100).max(60_000).optional(),
maxDelayMs: z.number().int().min(1_000).max(300_000).optional(),
jitter: z.number().min(0).max(1).optional(),
}).strict(),
])
const configSchema = z.object({
enabled: z.boolean().optional(),
role: z.enum(['host', 'client', 'both']).optional(),
serverUrl: z.string().url().optional(),
httpServerAllowlist: z.array(z.string().trim().min(1).max(128)).max(64).optional(),
deviceName: z.string().trim().min(1).max(80).optional(),
terminal: z.object({ enabled: z.boolean().optional() }).strict().optional(),
remoteTools: z.object({ enabled: z.boolean().optional() }).strict().optional(),
sidebar: z.object({ entry: z.enum(['standard', 'compact']).optional() }).strict().optional(),
hostControl: z.object({ enabled: z.boolean().optional() }).strict().optional(),
loopback: z.object({ ports: z.array(z.number().int().min(1024).max(65535)).max(16).optional() }).strict().optional(),
forceRelay: z.boolean().optional(),
rotatePinnedPeerKey: z.boolean().optional(),
logLevel: z.enum(['debug', 'info', 'warn', 'error']).optional(),
liteMode: z.boolean().optional(),
reconnect: reconnectSchema.optional(),
codex: z.object({
enabled: z.boolean().optional(),
binary: z.string().trim().min(1).max(4096).optional(),
}).strict().optional(),
cursor: z.object({
enabled: z.boolean().optional(),
binary: z.string().trim().min(1).max(4096).optional(),
}).strict().optional(),
acp: z.object({ enabled:z.boolean().optional(), backends:z.array(z.object({ id:z.string().trim().regex(/^[a-z0-9][a-z0-9._-]{0,31}$/i), enabled:z.boolean().optional(), command:z.string().trim().min(1).max(4096).optional(), args:z.array(z.string().max(4096)).max(32).optional(), cwd:z.string().max(4096).optional() }).strict()).max(12).optional(), backend:z.string().trim().regex(/^[a-z0-9][a-z0-9._-]{0,31}$/i).optional(), command:z.string().trim().min(1).max(4096).optional(), args:z.array(z.string().max(4096)).max(32).optional(), cwd:z.string().max(4096).optional() }).strict().optional(),
}).strict()
export function resolveConfig(input: ConfigInput = {}, env: NodeJS.ProcessEnv = process.env): ResolvedConfig {
const parsed = configSchema.parse(input)
const configuredCursorBackend = parsed.acp?.backends?.find(item => item.id === 'cursor')
const legacyCursorEnabled = parsed.acp?.backend === 'cursor' ? parsed.acp.enabled : undefined
const cursorEnabled = configuredCursorBackend?.enabled
?? parsed.cursor?.enabled
?? legacyCursorEnabled
?? false
const codexBackend = parsed.acp?.backends?.find(item => item.id === 'codex')
const codexEnabled = codexBackend?.enabled ?? parsed.codex?.enabled ?? true
const acpEnabled = parsed.acp?.enabled ?? true
const reconnect = typeof parsed.reconnect === 'object' ? parsed.reconnect : {}
const configuredServerUrl = parsed.serverUrl ?? env.DSH_REMOTE_SERVER
const httpServerAllowlist = normalizeHttpServerAllowlist(
parsed.httpServerAllowlist ?? parseHttpServerAllowlistEnv(env.DSH_REMOTE_HTTP_SERVER_ALLOWLIST),
)
const serverUrl = configuredServerUrl === undefined ? undefined : normalizeServerUrl(configuredServerUrl, httpServerAllowlist)
const initialDelayMs = reconnect.initialDelayMs ?? 4_000
const maxDelayMs = reconnect.maxDelayMs ?? 30_000
if (maxDelayMs < initialDelayMs) {
throw new TypeError('reconnect.maxDelayMs must be greater than or equal to reconnect.initialDelayMs')
}
return {
enabled: parsed.enabled ?? true,
role: parsed.role ?? 'host',
...(serverUrl === undefined ? {} : { serverUrl }),
httpServerAllowlist,
deviceName: parsed.deviceName ?? env.DSH_REMOTE_DEVICE_NAME ?? hostname(),
hostControl: { enabled: parsed.hostControl?.enabled ?? true },
terminal: { enabled: parsed.terminal?.enabled ?? (env.DSH_REMOTE_TERMINAL_ENABLED === undefined || env.DSH_REMOTE_TERMINAL_ENABLED === 'true') },
remoteTools: { enabled: parsed.remoteTools?.enabled ?? true },
sidebar: { entry: parsed.sidebar?.entry === 'compact' ? 'compact' : 'standard' },
loopback: { ports: [...new Set(parsed.loopback?.ports ?? [])] },
forceRelay: parsed.forceRelay ?? false,
rotatePinnedPeerKey: parsed.rotatePinnedPeerKey ?? false,
logLevel: parsed.logLevel ?? 'info',
liteMode: parsed.liteMode !== false,
reconnect: {
enabled: parsed.reconnect !== false,
initialDelayMs,
maxDelayMs,
jitter: reconnect.jitter ?? 0.2,
},
codex: {
enabled: acpEnabled && codexEnabled,
binary: codexBackend?.command ?? parsed.codex?.binary ?? 'codex',
},
cursor: {
enabled: cursorEnabled,
binary: configuredCursorBackend?.command ?? parsed.cursor?.binary ?? env.DSH_REMOTE_CURSOR_BINARY ?? env.DSH_REMOTE_ACP_BINARY ?? 'agent',
},
acp: {
enabled: acpEnabled,
backends: [...new Set(['codex', 'cursor', 'antigravity', 'pi', 'claude', 'opencode', 'hermes', ...(parsed.acp?.backends?.filter(item => item.id !== 'kimi').map(item => item.id) ?? [])])].map(id => {
const configured = parsed.acp?.backends?.find(item => item.id === id)
const legacy = parsed.acp?.backend === id ? parsed.acp : undefined
const defaults: Record<string, string> = { codex: 'codex', cursor: 'agent', antigravity: 'agy', pi: 'pi-acp', claude: 'claude-agent-acp', opencode: 'opencode', hermes: 'hermes' }
const cursorCommand = id === 'codex' ? parsed.codex?.binary : id === 'cursor'
? parsed.cursor?.binary ?? env.DSH_REMOTE_CURSOR_BINARY ?? env.DSH_REMOTE_ACP_BINARY
: undefined
const cwd = configured?.cwd ?? legacy?.cwd
return {
id,
enabled: configured?.enabled ?? legacy?.enabled
// Hermes opts in explicitly: a Host without it installed must not spawn it by default.
?? (id === 'codex' ? codexEnabled : id === 'cursor' ? cursorEnabled : id === 'pi' ? true : id === 'claude' ? true
: id === 'opencode' ? true : id === 'hermes' ? false : parsed.acp !== undefined),
command: configured?.command ?? legacy?.command ?? cursorCommand ?? defaults[id] ?? id,
args: id === 'codex' ? ['app-server'] : configured?.args ?? legacy?.args
?? (id === 'pi' || id === 'claude' ? [] : id === 'hermes' ? ['acp']
: id === 'antigravity' ? ['--input-format', 'stream-json', '--output-format', 'stream-json'] : ['acp']),
...(cwd === undefined ? {} : { cwd }),
}
}),
},
}
}
const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]'])
function isPrivateIpv6(hostname: string): boolean {
const host = (hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname).toLowerCase()
if (!host.includes(':') || !/^[0-9a-f:]+$/.test(host)) return false
if (host === '::1') return true
return /^f[cd][0-9a-f]{2}:/.test(host) || /^fe[89ab][0-9a-f]:/.test(host)
}
/** IPv4/IPv6 hosts that are only reachable on loopback, a LAN, link-local, or CGNAT/VPN networks. */
function isPrivateNetworkHostname(hostname: string): boolean {
if (LOCAL_HOSTS.has(hostname)) return true
if (isPrivateIpv6(hostname)) return true
const match = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(hostname)
if (match === null) return false
const octets = match.slice(1).map(Number)
if (octets.some(value => value > 255)) return false
const [a, b] = octets
return (
a === 10 ||
(a === 172 && b >= 16 && b <= 31) ||
(a === 192 && b === 168) ||
(a === 169 && b === 254) ||
(a === 100 && b >= 64 && b <= 127)
)
}
export function normalizeServerUrl(value: string, httpServerAllowlist: readonly string[] = []): string {
const url = new URL(value)
const privateHttp = url.protocol === 'http:'
&& (isPrivateNetworkHostname(url.hostname) || matchesHttpServerAllowlist(url.hostname, httpServerAllowlist))
if (url.protocol !== 'https:' && !privateHttp) {
throw new TypeError('serverUrl must use HTTPS (HTTP is allowed only for localhost or private-network addresses)')
}
if (url.username !== '' || url.password !== '') {
throw new TypeError('serverUrl must not contain credentials')
}
if (url.search !== '' || url.hash !== '') {
throw new TypeError('serverUrl must not contain query parameters or fragments')
}
if (url.pathname !== '' && url.pathname !== '/') {
throw new TypeError('serverUrl must be an origin without a path')
}
return url.origin
}
interface ParsedIpAddress {
version: 4 | 6
value: bigint
}
function parseHttpServerAllowlistEnv(value: string | undefined): string[] | undefined {
if (value === undefined) return undefined
return value.split(',').map(item => item.trim()).filter(item => item !== '')
}
function normalizeHttpServerAllowlist(values: readonly string[] | undefined): string[] {
if (values === undefined) return []
const normalized = [...new Set(values.map(value => value.trim()).filter(value => value !== ''))]
for (const value of normalized) {
if (!isValidHttpServerAllowlistEntry(value)) {
throw new TypeError(`httpServerAllowlist contains an invalid host or CIDR: ${value}`)
}
}
return normalized
}
function isValidHttpServerAllowlistEntry(value: string): boolean {
const slash = value.indexOf('/')
if (slash === -1) return parseIpAddress(value) !== undefined || isAllowlistedHostname(value)
if (slash !== value.lastIndexOf('/')) return false
const address = parseIpAddress(value.slice(0, slash))
const prefix = Number(value.slice(slash + 1))
return address !== undefined && Number.isInteger(prefix) && prefix >= 0 && prefix <= (address.version === 4 ? 32 : 128)
}
function isAllowlistedHostname(value: string): boolean {
return value.length <= 253
&& !value.startsWith('.')
&& !value.endsWith('.')
&& /^[A-Za-z0-9](?:[A-Za-z0-9.-]*[A-Za-z0-9])?$/.test(value)
}
function matchesHttpServerAllowlist(hostname: string, allowlist: readonly string[]): boolean {
const host = hostname.startsWith('[') && hostname.endsWith(']') ? hostname.slice(1, -1) : hostname
const address = parseIpAddress(host)
const normalizedHost = host.toLowerCase()
return allowlist.some(entry => {
const slash = entry.indexOf('/')
if (slash === -1) {
const exact = parseIpAddress(entry)
return exact === undefined ? entry.toLowerCase() === normalizedHost : address !== undefined && exact.version === address.version && exact.value === address.value
}
if (address === undefined) return false
const network = parseIpAddress(entry.slice(0, slash))
const prefix = Number(entry.slice(slash + 1))
if (network === undefined || network.version !== address.version) return false
const bits = network.version === 4 ? 32n : 128n
const mask = prefix === 0 ? 0n : ((1n << BigInt(prefix)) - 1n) << (bits - BigInt(prefix))
return (network.value & mask) === (address.value & mask)
})
}
function parseIpAddress(value: string): ParsedIpAddress | undefined {
const normalized = value.startsWith('[') && value.endsWith(']') ? value.slice(1, -1) : value
return parseIpv4(normalized) ?? parseIpv6(normalized)
}
function parseIpv4(value: string): ParsedIpAddress | undefined {
const parts = value.split('.')
if (parts.length !== 4 || parts.some(part => !/^\d{1,3}$/.test(part))) return undefined
const octets = parts.map(Number)
if (octets.some(octet => octet > 255)) return undefined
return { version: 4, value: octets.reduce((result, octet) => (result << 8n) | BigInt(octet), 0n) }
}
function parseIpv6(value: string): ParsedIpAddress | undefined {
const normalized = value.toLowerCase()
if (!normalized.includes(':') || normalized.includes('%')) return undefined
const sections = normalized.split('::')
if (sections.length > 2) return undefined
const expand = (section: string): number[] | undefined => {
if (section === '') return []
const parts = section.split(':')
const result: number[] = []
for (const part of parts) {
if (part.includes('.')) {
const ipv4 = parseIpv4(part)
if (ipv4 === undefined) return undefined
result.push(Number((ipv4.value >> 16n) & 0xffffn), Number(ipv4.value & 0xffffn))
} else if (/^[0-9a-f]{1,4}$/.test(part)) {
result.push(Number.parseInt(part, 16))
} else return undefined
}
return result
}
const left = expand(sections[0]!)
const right = expand(sections.length === 2 ? sections[1]! : '')
if (left === undefined || right === undefined) return undefined
const hextets = sections.length === 2 ? [...left, ...Array(8 - left.length - right.length).fill(0), ...right] : left
if (hextets.length !== 8) return undefined
return { version: 6, value: hextets.reduce((result, hextet) => (result << 16n) | BigInt(hextet), 0n) }
}