423 lines
18 KiB
TypeScript
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) }
|
|
}
|