@bun-native/protocol 0.0.0-stage → 0.33.0

package/src/processes.ts

@@ -0,0 +1,252 @@
+import { ProtocolError } from './framing.ts'
+import { parseChunk, parseFilePath, parseRootId, parseRootPath } from './files.ts'
+import { id, integer, keys, object } from './values.ts'
+
+export const MAX_PROCESS_EXECUTABLES = 8
+export const MAX_PROCESSES = 8
+export const MAX_PROCESS_ARGS = 64
+export const MAX_PROCESS_ENV = 64
+export const MAX_PROCESS_OUTPUT_CREDIT = 4
+const MAX_PROCESS_ARG_BYTES = 4_096
+const MAX_PROCESS_ENV_NAME_BYTES = 128
+const MAX_PROCESS_ENV_VALUE_BYTES = 4_096
+const MAX_PROCESS_LAUNCH_BYTES = 32_768
+const MAX_TERMINAL_DIMENSION = 1_000
+const PROCESS_ARGUMENT = '--bun-native-process='
+const PROCESS_LIMITS_ARGUMENT = '--bun-native-process-limits='
+const MAX_PROCESS_CPU_SECONDS = 604_800
+const MIN_PROCESS_MEMORY_BYTES = 2 ** 20
+const MAX_PROCESS_MEMORY_BYTES = 2 ** 48
+const MIN_PROCESS_OPEN_FILES = 3
+const MAX_PROCESS_OPEN_FILES = 2 ** 20
+const encoder = new TextEncoder()
+const bytes = (value: string) => encoder.encode(value).byteLength
+
+/**
+ * Resource limits every child started from one executable entry runs under.
+ * A platform that cannot enforce a requested limit refuses the spawn.
+ */
+export interface ProcessLimits {
+  /** CPU time (POSIX `RLIMIT_CPU`, Windows per-process job time). */
+  cpu_seconds?: number
+  /** Memory (Linux `RLIMIT_AS`, Windows per-process job memory). */
+  memory_bytes?: number
+  /** Open descriptors (POSIX `RLIMIT_NOFILE`). */
+  open_files?: number
+}
+
+export interface ProcessExecutable {
+  id: string
+  executable: string
+  limits?: ProcessLimits
+}
+
+const LIMIT_NAMES = ['cpu_seconds', 'memory_bytes', 'open_files'] as const
+const LIMIT_BOUNDS = {
+  cpu_seconds: [1, MAX_PROCESS_CPU_SECONDS],
+  memory_bytes: [MIN_PROCESS_MEMORY_BYTES, MAX_PROCESS_MEMORY_BYTES],
+  open_files: [MIN_PROCESS_OPEN_FILES, MAX_PROCESS_OPEN_FILES],
+} as const
+
+export function parseProcessLimits(value: unknown): ProcessLimits {
+  const data = object(value)
+  keys(data, [...LIMIT_NAMES])
+  const limits: ProcessLimits = {}
+  for (const name of LIMIT_NAMES)
+    if (name in data) {
+      const [min, max] = LIMIT_BOUNDS[name]
+      limits[name] = integer(data[name], 'process ' + name, min, max)
+    }
+  if (Object.keys(limits).length === 0)
+    throw new ProtocolError('Process limits must set at least one limit')
+  return limits
+}
+
+/** `cpu_seconds=N,memory_bytes=N,open_files=N`, only the set limits, in that order. */
+export function processLimitsArgument(limits: ProcessLimits): string {
+  const parsed = parseProcessLimits(limits)
+  return LIMIT_NAMES.filter((name) => parsed[name] !== undefined)
+    .map((name) => name + '=' + parsed[name])
+    .join(',')
+}
+
+/** Parses `processLimitsArgument`'s form strictly, as the native host does. */
+export function parseProcessLimitsArgument(text: string): ProcessLimits {
+  const data: Record<string, number> = {}
+  let last = -1
+  for (const part of text.split(',')) {
+    const match = /^([a-z_]+)=(0|[1-9][0-9]{0,19})$/.exec(part)
+    const order = LIMIT_NAMES.indexOf(match?.[1] as (typeof LIMIT_NAMES)[number])
+    if (!match || order <= last)
+      throw new ProtocolError('Process limits must be cpu_seconds=N,memory_bytes=N,open_files=N')
+    last = order
+    data[match[1]!] = Number(match[2])
+  }
+  return parseProcessLimits(data)
+}
+
+export interface TerminalSize {
+  columns: number
+  rows: number
+}
+
+export interface ProcessLaunch {
+  executable: string
+  args: string[]
+  env: Record<string, string>
+  cwd?: { grant_id: number; path: string }
+  terminal?: TerminalSize
+}
+
+export const PROCESS_SIGNALS = Object.freeze(['interrupt', 'terminate', 'kill', 'hangup'] as const)
+export type ProcessSignal = (typeof PROCESS_SIGNALS)[number]
+export type ProcessStream = 'stdout' | 'stderr' | 'terminal'
+export type ProcessExit = { code: number } | { signal: number }
+
+function executable(value: unknown): ProcessExecutable {
+  const data = object(value)
+  keys(data, ['id', 'executable', 'limits'])
+  const path = parseRootPath(data['executable'])
+  // `/` and `X:\` are the only normalized paths ending in a separator.
+  if (path.endsWith('/') || path.endsWith('\\'))
+    throw new ProtocolError('Process executable must name a file')
+  const entry: ProcessExecutable = { id: parseRootId(data['id']), executable: path }
+  if ('limits' in data) entry.limits = parseProcessLimits(data['limits'])
+  return entry
+}
+
+export function parseProcessExecutables(value: unknown): ProcessExecutable[] {
+  if (!Array.isArray(value) || value.length > MAX_PROCESS_EXECUTABLES)
+    throw new ProtocolError(
+      'At most ' + MAX_PROCESS_EXECUTABLES + ' process executables may be granted'
+    )
+  const entries = value.map(executable)
+  if (new Set(entries.map((entry) => entry.id)).size !== entries.length)
+    throw new ProtocolError('Process executable IDs must be unique')
+  return entries
+}
+
+/**
+ * The reserved native launch arguments for one validated executable: the
+ * executable itself, then its limits when it has any.
+ */
+export function processArguments(value: ProcessExecutable): string[] {
+  const entry = executable(value)
+  const argv = [PROCESS_ARGUMENT + entry.id + ':' + entry.executable]
+  if (entry.limits)
+    argv.push(PROCESS_LIMITS_ARGUMENT + entry.id + ':' + processLimitsArgument(entry.limits))
+  return argv
+}
+
+export function processesFromArguments(argv: readonly string[]): ProcessExecutable[] {
+  // One pass, as the host parses them: limits name an executable granted by
+  // an earlier argument, at most once.
+  const entries: ProcessExecutable[] = []
+  for (const argument of argv) {
+    if (argument.startsWith(PROCESS_ARGUMENT)) {
+      const [entry, ...path] = argument.slice(PROCESS_ARGUMENT.length).split(':')
+      entries.push({ id: entry!, executable: path.join(':') })
+    } else if (argument.startsWith(PROCESS_LIMITS_ARGUMENT)) {
+      const text = argument.slice(PROCESS_LIMITS_ARGUMENT.length)
+      const separator = text.indexOf(':')
+      const entry = entries.find((item) => item.id === text.slice(0, separator))
+      if (separator < 0 || !entry || entry.limits)
+        throw new ProtocolError('Process limits must name one granted executable once')
+      entry.limits = parseProcessLimitsArgument(text.slice(separator + 1))
+    }
+  }
+  return parseProcessExecutables(entries)
+}
+
+function plain(value: unknown, limit: number, field: string): string {
+  if (
+    typeof value !== 'string' ||
+    !value.isWellFormed() ||
+    value.includes('\0') ||
+    bytes(value) > limit
+  )
+    throw new ProtocolError(field + ' must be a NUL-free string of at most ' + limit + ' bytes')
+  return value
+}
+
+export function parseTerminalSize(value: unknown): TerminalSize {
+  const data = object(value)
+  keys(data, ['columns', 'rows'])
+  return {
+    columns: integer(data['columns'], 'terminal columns', 1, MAX_TERMINAL_DIMENSION),
+    rows: integer(data['rows'], 'terminal rows', 1, MAX_TERMINAL_DIMENSION),
+  }
+}
+
+function parseEnvName(value: string): string {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value) || value.length > MAX_PROCESS_ENV_NAME_BYTES)
+    throw new ProtocolError(
+      'Environment names must be ASCII letters, digits and "_", not starting with a digit'
+    )
+  return value
+}
+
+export function parseProcessLaunch(value: unknown): ProcessLaunch {
+  const data = object(value)
+  keys(data, ['executable', 'args', 'env', 'cwd', 'terminal'])
+  const args = data['args']
+  if (!Array.isArray(args) || args.length > MAX_PROCESS_ARGS)
+    throw new ProtocolError('Process arguments must be an array of at most ' + MAX_PROCESS_ARGS)
+  const parsedArgs = args.map((item) => plain(item, MAX_PROCESS_ARG_BYTES, 'Process argument'))
+  const env = object(data['env'])
+  const names = Object.keys(env)
+  if (names.length > MAX_PROCESS_ENV)
+    throw new ProtocolError('At most ' + MAX_PROCESS_ENV + ' environment variables may be set')
+  const parsedEnv: Record<string, string> = {}
+  for (const name of names)
+    parsedEnv[parseEnvName(name)] = plain(
+      env[name],
+      MAX_PROCESS_ENV_VALUE_BYTES,
+      'Environment value'
+    )
+  const total =
+    parsedArgs.reduce((sum, item) => sum + bytes(item), 0) +
+    names.reduce((sum, name) => sum + bytes(name) + bytes(parsedEnv[name]!), 0)
+  if (total > MAX_PROCESS_LAUNCH_BYTES)
+    throw new ProtocolError('Process arguments and environment exceed 32768 bytes')
+  const launch: ProcessLaunch = {
+    executable: parseRootId(data['executable']),
+    args: parsedArgs,
+    env: parsedEnv,
+  }
+  if ('cwd' in data) {
+    const cwd = object(data['cwd'])
+    keys(cwd, ['grant_id', 'path'])
+    launch.cwd = { grant_id: id(cwd['grant_id']), path: parseFilePath(cwd['path']) }
+  }
+  if ('terminal' in data) launch.terminal = parseTerminalSize(data['terminal'])
+  return launch
+}
+
+export function parseProcessSignal(value: unknown): ProcessSignal {
+  if (!PROCESS_SIGNALS.includes(value as ProcessSignal))
+    throw new ProtocolError('Unknown process signal')
+  return value as ProcessSignal
+}
+
+export function parseProcessStream(value: unknown): ProcessStream {
+  if (value !== 'stdout' && value !== 'stderr' && value !== 'terminal')
+    throw new ProtocolError('Unknown process stream')
+  return value
+}
+
+export function parseProcessOutput(value: unknown): string {
+  const data = parseChunk(value)
+  if (!data) throw new ProtocolError('Process output chunks are nonempty')
+  return data
+}
+
+export function parseProcessExit(value: unknown): ProcessExit {
+  const data = object(value)
+  keys(data, ['code', 'signal'])
+  if ('code' in data && !('signal' in data))
+    return { code: integer(data['code'], 'exit code', 0, 255) }
+  if ('signal' in data && !('code' in data))
+    return { signal: integer(data['signal'], 'exit signal', 1, 64) }
+  throw new ProtocolError('A process exit has exactly one exit code or signal')
+}

package/src/services.ts

@@ -0,0 +1,197 @@
+import { ProtocolError } from './framing.ts'
+import { keys, number, object, string } from './values.ts'
+import { parseFilesystemRoots, type FilesystemRoot } from './files.ts'
+import { parseProcessExecutables, type ProcessExecutable } from './processes.ts'
+
+// Worst-case JSON escaping still leaves room within the 64KiB frame.
+export const MAX_CLIPBOARD_BYTES = 8_192
+export const MAX_SERVICE_REQUESTS = 8
+export const MAX_GLOBAL_SHORTCUTS = 16
+export const MAX_NOTIFICATIONS = 32
+export const MAX_NOTIFICATION_TITLE_BYTES = 256
+export const MAX_NOTIFICATION_BODY_BYTES = 2_048
+
+export interface ServicePolicy {
+  window_display: boolean
+  clipboard_read: boolean
+  clipboard_write: boolean
+  global_shortcuts: boolean
+  notifications: boolean
+  /** Owned targets that receive external file drops as untrusted names. */
+  drag_drop: boolean
+  /** Directories a window may open as scoped grants, in launch order. */
+  filesystem_roots: FilesystemRoot[]
+  /** Executables a window may start as owned processes, in launch order. */
+  processes: ProcessExecutable[]
+  /** Optional on the wire, so existing peers stay exact: absence is a denial. */
+  file_dialogs?: boolean
+  /** Optional like `file_dialogs`: the application menu bar. */
+  app_menu?: boolean
+  /** Optional like `file_dialogs`: OS message dialogs. */
+  task_dialogs?: boolean
+}
+
+type Characters<S extends string> = S extends `${infer Head}${infer Tail}`
+  ? Head | Characters<Tail>
+  : never
+
+/** A layout-level key name: a-z, 0-9 or f1-f12. */
+export type GlobalShortcutKey =
+  | Characters<'abcdefghijklmnopqrstuvwxyz0123456789'>
+  | `f${1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12}`
+
+/** The closed set of layout-level keys a global shortcut may name. */
+export const GLOBAL_SHORTCUT_KEYS = Object.freeze([
+  ...'abcdefghijklmnopqrstuvwxyz0123456789',
+  ...Array.from({ length: 12 }, (_, index) => `f${index + 1}`),
+] as GlobalShortcutKey[]) as readonly GlobalShortcutKey[]
+
+export interface ShortcutModifiers {
+  control: boolean
+  alt: boolean
+  shift: boolean
+  platform: boolean
+}
+
+export function parseShortcutModifiers(value: unknown): ShortcutModifiers {
+  const data = object(value)
+  keys(data, ['control', 'alt', 'shift', 'platform'])
+  const flag = (key: keyof ShortcutModifiers) => {
+    if (typeof data[key] !== 'boolean')
+      throw new ProtocolError('Global shortcut modifiers must state each modifier explicitly')
+    return data[key]
+  }
+  const modifiers = {
+    control: flag('control'),
+    alt: flag('alt'),
+    shift: flag('shift'),
+    platform: flag('platform'),
+  }
+  if (!modifiers.control && !modifiers.alt && !modifiers.platform)
+    throw new ProtocolError('Global shortcut requires control, alt or platform')
+  return modifiers
+}
+
+export function parseShortcutKey(value: unknown): string {
+  if (typeof value !== 'string' || !(GLOBAL_SHORTCUT_KEYS as readonly string[]).includes(value))
+    throw new ProtocolError('Global shortcut key must be one of a-z, 0-9 or f1-f12')
+  return value
+}
+
+/** Plain-text notification content: one nonempty title line and a body that
+ * may hold line feeds but no other control characters. Neither is markup. */
+export function parseNotificationContent(title: unknown, body: unknown) {
+  const parsedTitle = string(title, 'notification title', MAX_NOTIFICATION_TITLE_BYTES)
+  if (!parsedTitle || /\p{Cc}/u.test(parsedTitle))
+    throw new ProtocolError('Notification title must be nonempty and contain no control characters')
+  const parsedBody = string(body, 'notification body', MAX_NOTIFICATION_BODY_BYTES)
+  if (/[^\P{Cc}\n]/u.test(parsedBody))
+    throw new ProtocolError(
+      'Notification body may contain no control characters other than line feeds'
+    )
+  return { title: parsedTitle, body: parsedBody }
+}
+
+export const NOTIFICATION_DISMISSALS = Object.freeze(['expired', 'dismissed', 'closed'] as const)
+export type NotificationDismissal = (typeof NOTIFICATION_DISMISSALS)[number]
+
+export function parseNotificationDismissal(value: unknown): NotificationDismissal {
+  if (!NOTIFICATION_DISMISSALS.includes(value as NotificationDismissal))
+    throw new ProtocolError('Unknown notification dismissal reason')
+  return value as NotificationDismissal
+}
+
+export type ClipboardText = { kind: 'empty' } | { kind: 'text'; text: string }
+
+export function parseClipboardText(value: unknown): ClipboardText {
+  const data = object(value)
+  if (data['kind'] === 'empty') {
+    keys(data, ['kind'])
+    return { kind: 'empty' }
+  }
+  keys(data, ['kind', 'text'])
+  if (data['kind'] !== 'text') throw new ProtocolError('Unknown clipboard text result')
+  return { kind: 'text', text: string(data['text'], 'clipboard text', MAX_CLIPBOARD_BYTES) }
+}
+
+interface DisplayBounds {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface DisplaySnapshot {
+  bounds: DisplayBounds
+  scale_factor: number
+  /** Work area in the logical coordinates of `bounds` (`display_details_v1` only). */
+  visible_bounds?: DisplayBounds
+  /** Platform display identifier, lowercase hyphenated (`display_identity_v1` only). */
+  display_uuid?: string
+}
+
+const DISPLAY_UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/
+
+function displayBounds(value: unknown, name: string): DisplayBounds {
+  const bounds = object(value)
+  keys(bounds, ['x', 'y', 'width', 'height'])
+  return {
+    x: number(bounds['x'], name + ' x', -1_048_576, 1_048_576),
+    y: number(bounds['y'], name + ' y', -1_048_576, 1_048_576),
+    width: number(bounds['width'], name + ' width', Number.MIN_VALUE, 1_048_576),
+    height: number(bounds['height'], name + ' height', Number.MIN_VALUE, 1_048_576),
+  }
+}
+
+export function parseServicePolicy(value: unknown): ServicePolicy {
+  const data = object(value)
+  keys(data, [
+    'window_display',
+    'clipboard_read',
+    'clipboard_write',
+    'global_shortcuts',
+    'notifications',
+    'drag_drop',
+    'filesystem_roots',
+    'processes',
+    'file_dialogs',
+    'app_menu',
+    'task_dialogs',
+  ])
+  const grant = (key: keyof ServicePolicy) => {
+    if (typeof data[key] !== 'boolean')
+      throw new ProtocolError('Native service policy must explicitly grant or deny each operation')
+    return data[key]
+  }
+  return {
+    window_display: grant('window_display'),
+    clipboard_read: grant('clipboard_read'),
+    clipboard_write: grant('clipboard_write'),
+    global_shortcuts: grant('global_shortcuts'),
+    notifications: grant('notifications'),
+    drag_drop: grant('drag_drop'),
+    filesystem_roots: parseFilesystemRoots(data['filesystem_roots']),
+    processes: parseProcessExecutables(data['processes']),
+    ...('file_dialogs' in data ? { file_dialogs: grant('file_dialogs') } : {}),
+    ...('app_menu' in data ? { app_menu: grant('app_menu') } : {}),
+    ...('task_dialogs' in data ? { task_dialogs: grant('task_dialogs') } : {}),
+  }
+}
+
+export function parseDisplaySnapshot(value: unknown): DisplaySnapshot {
+  const data = object(value)
+  keys(data, ['bounds', 'scale_factor', 'visible_bounds', 'display_uuid'])
+  const snapshot: DisplaySnapshot = {
+    bounds: displayBounds(data['bounds'], 'display'),
+    scale_factor: number(data['scale_factor'], 'display scale factor', 0.125, 16),
+  }
+  if ('visible_bounds' in data)
+    snapshot.visible_bounds = displayBounds(data['visible_bounds'], 'display work area')
+  if ('display_uuid' in data) {
+    const uuid = string(data['display_uuid'], 'display UUID', 36)
+    if (!DISPLAY_UUID.test(uuid))
+      throw new ProtocolError('Native display identity must be a lowercase hyphenated UUID')
+    snapshot.display_uuid = uuid
+  }
+  return snapshot
+}

package/src/values.ts

@@ -0,0 +1,55 @@
+import { ProtocolError } from './framing.ts'
+
+export const MAX_TEXT_BYTES = 16_384
+export const MAX_TITLE_BYTES = 256
+const encoder = new TextEncoder()
+
+export function object(value: unknown): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    throw new ProtocolError('Message must be an object')
+  return value as Record<string, unknown>
+}
+
+export function keys(value: Record<string, unknown>, allowed: readonly string[]): void {
+  for (const key of Object.keys(value))
+    if (!allowed.includes(key)) throw new ProtocolError('Unknown message property: ' + key)
+}
+
+export function number(value: unknown, field: string, min: number, max: number): number {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max)
+    throw new ProtocolError(field + ' must be finite and between ' + min + ' and ' + max)
+  return value
+}
+
+export function integer(
+  value: unknown,
+  field: string,
+  min = 0,
+  max = Number.MAX_SAFE_INTEGER
+): number {
+  const result = number(value, field, min, max)
+  if (!Number.isSafeInteger(result)) throw new ProtocolError(field + ' must be a safe integer')
+  return result
+}
+
+export function id(value: unknown): number {
+  return integer(value, 'Identifier', 1)
+}
+
+/**
+ * UTF-8 length bound without encoding when the UTF-16 length decides it: each
+ * code unit encodes to one to three bytes (a surrogate pair to four).
+ */
+function withinBytes(value: string, limit: number): boolean {
+  if (value.length > limit) return false
+  if (value.length * 3 <= limit) return true
+  return encoder.encode(value).byteLength <= limit
+}
+
+export function string(value: unknown, field: string, limit = MAX_TEXT_BYTES): string {
+  if (typeof value !== 'string' || !withinBytes(value, limit))
+    throw new ProtocolError(field + ' must be a string within ' + limit + ' UTF-8 bytes')
+  if (!value.isWellFormed()) throw new ProtocolError(field + ' contains an unpaired surrogate')
+  if (value.includes('\0')) throw new ProtocolError(field + ' contains a NUL character')
+  return value
+}