@raidiant/notifai 0.3.0 → 0.5.0

package/src/hook-adapter.test.ts

@@ -0,0 +1,187 @@
+import { spawnSync } from 'node:child_process'
+import {
+  chmodSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  hookAdapterPath,
+  inspectHookAdapter,
+  installHookAdapter,
+} from './hook-adapter.js'
+import { buildHookConfig, codexHookIdentityHash, type InstalledHandler } from './install-hooks.js'
+
+function isolated(): { root: string; homeDir: string } {
+  const root = mkdtempSync(path.join(os.tmpdir(), 'notifai-hook-adapter-'))
+  return { root, homeDir: path.join(root, 'home') }
+}
+
+describe('stable hook adapter', () => {
+  it('executes paths with spaces, quotes, and shell syntax without evaluating them', () => {
+    const { root, homeDir } = isolated()
+    const odd = path.join(root, "odd ' $(touch should-not-run)")
+    mkdirSync(odd, { recursive: true })
+    const script = path.join(odd, 'target script.js')
+    writeFileSync(script, 'process.stdout.write(JSON.stringify(process.argv.slice(2)))\n')
+
+    const installed = installHookAdapter({ execPath: process.execPath, scriptPath: script }, homeDir)
+    const run = spawnSync(installed.path, ['hook', 'stop', '--owner', 'notifai'], {
+      encoding: 'utf8',
+    })
+
+    expect(run.status).toBe(0)
+    expect(JSON.parse(run.stdout)).toEqual(['hook', 'stop', '--owner', 'notifai'])
+    expect(statSync(installed.path).mode & 0o777).toBe(0o700)
+    expect(inspectHookAdapter(homeDir).problems).toEqual([])
+  })
+
+  it('retargets Node and CLI paths without changing any harness definition or Codex hash', () => {
+    const { root, homeDir } = isolated()
+    const first = path.join(root, 'first.js')
+    const second = path.join(root, 'second.js')
+    writeFileSync(first, '')
+    writeFileSync(second, '')
+    const adapter = installHookAdapter({ execPath: process.execPath, scriptPath: first }, homeDir)
+    const before = buildHookConfig({
+      adapterPath: adapter.path,
+      harness: 'codex',
+    })
+    const beforeSource = readFileSync(adapter.path, 'utf8')
+
+    installHookAdapter({ execPath: process.execPath, scriptPath: second }, homeDir)
+    const after = buildHookConfig({
+      adapterPath: hookAdapterPath(homeDir),
+      harness: 'codex',
+    })
+    const afterSource = readFileSync(adapter.path, 'utf8')
+    const stop = (config: typeof before): InstalledHandler => {
+      const handler = config['Stop']![0]!.hooks[0]!
+      return {
+        event: 'Stop',
+        groupIndex: 0,
+        handlerIndex: 0,
+        command: handler.command,
+        timeout: handler.timeout,
+      }
+    }
+
+    expect(after).toEqual(before)
+    expect(afterSource).not.toBe(beforeSource)
+    expect(codexHookIdentityHash(stop(after))).toBe(codexHookIdentityHash(stop(before)))
+    expect(inspectHookAdapter(homeDir).target?.scriptPath).toBe(second)
+  })
+
+  it('uses a fixed home-relative pathname with no XDG input surface', () => {
+    const { homeDir } = isolated()
+    expect(hookAdapterPath(homeDir)).toBe(
+      path.join(homeDir, '.notifai', 'bin', 'hook-adapter'),
+    )
+  })
+
+  it('uses the OS account home even when HOME is overridden', () => {
+    const original = process.env['HOME']
+    process.env['HOME'] = '/tmp/attacker-selected-home'
+    try {
+      expect(hookAdapterPath()).toBe(
+        path.join(os.userInfo().homedir, '.notifai', 'bin', 'hook-adapter'),
+      )
+      expect(hookAdapterPath()).not.toContain('attacker-selected-home')
+    } finally {
+      if (original === undefined) delete process.env['HOME']
+      else process.env['HOME'] = original
+    }
+  })
+
+  it('repairs permissive adapter permissions without changing its path', () => {
+    const { root, homeDir } = isolated()
+    const script = path.join(root, 'target.js')
+    writeFileSync(script, '')
+    const first = installHookAdapter({ execPath: process.execPath, scriptPath: script }, homeDir)
+    chmodSync(first.path, 0o755)
+
+    const repaired = installHookAdapter({ execPath: process.execPath, scriptPath: script }, homeDir)
+
+    expect(repaired).toEqual({ path: first.path, changed: true })
+    expect(statSync(first.path).mode & 0o777).toBe(0o700)
+  })
+
+  it('refuses a symlinked adapter instead of reading or replacing its target', () => {
+    const { root, homeDir } = isolated()
+    const target = path.join(root, 'foreign')
+    const adapter = hookAdapterPath(homeDir)
+    mkdirSync(path.dirname(adapter), { recursive: true })
+    writeFileSync(target, 'leave me')
+    symlinkSync(target, adapter)
+
+    expect(() =>
+      installHookAdapter({ execPath: process.execPath, scriptPath: target }, homeDir),
+    ).toThrow(/not a regular file/)
+    expect(readFileSync(target, 'utf8')).toBe('leave me')
+  })
+
+  it('refuses a symlinked Notifai-owned parent directory', () => {
+    const { root, homeDir } = isolated()
+    const foreign = path.join(root, 'foreign-dir')
+    const script = path.join(root, 'target.js')
+    mkdirSync(homeDir, { recursive: true })
+    mkdirSync(foreign)
+    writeFileSync(script, '')
+    symlinkSync(foreign, path.join(homeDir, '.notifai'))
+
+    expect(() =>
+      installHookAdapter({ execPath: process.execPath, scriptPath: script }, homeDir),
+    ).toThrow(/not a regular directory/)
+    expect(readFileSync(script, 'utf8')).toBe('')
+  })
+
+  it('diagnoses a stale registered runtime and CLI without executing either', () => {
+    const { root, homeDir } = isolated()
+    const missingRuntime = path.join(root, 'removed-node')
+    const missingCli = path.join(root, 'removed-cli.js')
+    writeFileSync(missingRuntime, '#!/bin/sh\n')
+    chmodSync(missingRuntime, 0o700)
+    writeFileSync(missingCli, '')
+    installHookAdapter({ execPath: missingRuntime, scriptPath: missingCli }, homeDir)
+    rmSync(missingRuntime)
+    rmSync(missingCli)
+
+    expect(inspectHookAdapter(homeDir).problems).toEqual([
+      `registered runtime ${missingRuntime} is missing`,
+      `registered CLI ${missingCli} is missing`,
+    ])
+  })
+
+  it('fails closed instead of executing an unregistered PATH target after the registered target vanished', () => {
+    const { root, homeDir } = isolated()
+    const bin = path.join(root, 'new-bin')
+    const replacement = path.join(bin, 'notifai')
+    mkdirSync(bin, { recursive: true })
+    writeFileSync(replacement, '#!/bin/sh\nprintf "%s" "$*"\n')
+    chmodSync(replacement, 0o700)
+    const oldNode = path.join(root, 'old-node')
+    const oldCli = path.join(root, 'old-cli.js')
+    writeFileSync(oldNode, '#!/bin/sh\n')
+    chmodSync(oldNode, 0o700)
+    writeFileSync(oldCli, '')
+    const installed = installHookAdapter({ execPath: oldNode, scriptPath: oldCli }, homeDir)
+    rmSync(oldNode)
+    rmSync(oldCli)
+
+    const run = spawnSync(installed.path, ['hook', 'stop'], {
+      encoding: 'utf8',
+      env: { PATH: bin },
+    })
+
+    expect(run.status).toBe(127)
+    expect(run.stdout).toBe('')
+    expect(run.stderr).toMatch(/target is stale/)
+  })
+})

package/src/hook-adapter.ts

@@ -0,0 +1,212 @@
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  statSync,
+} from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { atomicWriteFileSync } from './atomic-file.js'
+import { withTargetFileLock } from './file-lock.js'
+
+const ADAPTER_MARKER = '# notifai managed hook adapter'
+const ADAPTER_VERSION = 1
+
+export interface HookAdapterTarget {
+  execPath: string
+  scriptPath: string
+}
+
+export interface HookAdapterInspection {
+  path: string
+  target: HookAdapterTarget | null
+  problems: string[]
+}
+
+/**
+ * One user-level identity for every harness and every project/global install.
+ *
+ * The pathname is deliberately outside XDG configuration/state routing. XDG
+ * overrides routinely differ between shells, package managers, and harness
+ * processes; allowing one to select this path would put mutable environment
+ * back into every trusted definition. Only the user's home boundary selects
+ * it; CLI, Node, package-manager, checkout, and preference paths stay behind
+ * it and may change without changing hook identity.
+ */
+export function hookAdapterPath(homeDir: string = os.userInfo().homedir): string {
+  return path.join(homeDir, '.notifai', 'bin', 'hook-adapter')
+}
+
+/** Install or repair the stable adapter and atomically retarget its implementation. */
+export function installHookAdapter(
+  target: HookAdapterTarget,
+  homeDir?: string,
+): { path: string; changed: boolean } {
+  assertUsableTarget(target)
+  const file = hookAdapterPath(homeDir)
+  ensureManagedDirectories(homeDir ?? os.userInfo().homedir)
+  const source = hookAdapterSource(target)
+  return withTargetFileLock(file, () => {
+    const existing = existsSync(file) ? readSafeManagedFile(file) : null
+    const changed =
+      existing === null || existing.contents !== source || (existing.mode & 0o777) !== 0o700
+    if (changed) {
+      atomicWriteFileSync(file, source, {
+        mode: 0o700,
+        preserveMode: false,
+        requireCurrentUserOwner: true,
+      })
+    }
+    return { path: file, changed }
+  })
+}
+
+function assertUsableTarget(target: HookAdapterTarget): void {
+  let exec
+  try {
+    exec = statSync(target.execPath)
+  } catch {
+    throw new Error(`Hook adapter runtime ${target.execPath} does not exist.`)
+  }
+  if (!exec.isFile() || (exec.mode & 0o111) === 0) {
+    throw new Error(`Hook adapter runtime ${target.execPath} is not executable.`)
+  }
+  try {
+    if (!statSync(target.scriptPath).isFile()) {
+      throw new Error(`Hook adapter CLI ${target.scriptPath} is not a regular file.`)
+    }
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith('Hook adapter CLI ')) throw err
+    throw new Error(`Hook adapter CLI ${target.scriptPath} does not exist.`)
+  }
+}
+
+/** Inspect the shared adapter without executing either it or its registered CLI. */
+export function inspectHookAdapter(
+  homeDir?: string,
+): HookAdapterInspection {
+  const file = hookAdapterPath(homeDir)
+  if (!existsSync(file)) {
+    return { path: file, target: null, problems: [`${file} is missing; rerun \`notifai hooks install\``] }
+  }
+
+  let stat
+  try {
+    stat = lstatSync(file)
+  } catch (err) {
+    return { path: file, target: null, problems: [String(err)] }
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    return {
+      path: file,
+      target: null,
+      problems: [`${file} is not a regular file; refusing the adapter`],
+    }
+  }
+
+  const problems: string[] = []
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+  if (uid !== undefined && stat.uid !== uid) {
+    problems.push(`${file} is owned by uid ${stat.uid}, not the current user`)
+  }
+  if ((stat.mode & 0o077) !== 0 || (stat.mode & 0o700) !== 0o700) {
+    problems.push(`${file} permissions are ${(stat.mode & 0o777).toString(8)}, expected 700`)
+  }
+
+  const contents = readFileSync(file, 'utf8')
+  if (!contents.startsWith(`#!/bin/sh\n${ADAPTER_MARKER}\n`)) {
+    problems.push(`${file} has no managed adapter marker`)
+  }
+  const version = Number(/^# adapter-version: (\d+)$/m.exec(contents)?.[1] ?? Number.NaN)
+  if (version !== ADAPTER_VERSION) problems.push(`${file} uses obsolete adapter version ${version}`)
+  const target = parseTarget(contents)
+  if (target === null) {
+    problems.push(`${file} has malformed target metadata`)
+  } else {
+    try {
+      const exec = statSync(target.execPath)
+      if (!exec.isFile() || (exec.mode & 0o111) === 0) {
+        problems.push(`registered runtime ${target.execPath} is not executable`)
+      }
+    } catch {
+      problems.push(`registered runtime ${target.execPath} is missing`)
+    }
+    try {
+      if (!statSync(target.scriptPath).isFile()) {
+        problems.push(`registered CLI ${target.scriptPath} is not a regular file`)
+      }
+    } catch {
+      problems.push(`registered CLI ${target.scriptPath} is missing`)
+    }
+  }
+  return { path: file, target, problems }
+}
+
+function hookAdapterSource(target: HookAdapterTarget): string {
+  return `#!/bin/sh
+${ADAPTER_MARKER}
+# adapter-version: ${ADAPTER_VERSION}
+# target-exec-json: ${JSON.stringify(target.execPath)}
+# target-script-json: ${JSON.stringify(target.scriptPath)}
+set -eu
+
+registered_exec=${quote(target.execPath)}
+registered_script=${quote(target.scriptPath)}
+
+if [ -x "$registered_exec" ] && [ -f "$registered_script" ]; then
+  exec "$registered_exec" "$registered_script" "$@"
+fi
+
+printf '%s\n' 'Notifai hook adapter target is stale; run notifai hooks install.' >&2
+exit 127
+`
+}
+
+function parseTarget(contents: string): HookAdapterTarget | null {
+  const exec = /^# target-exec-json: (.+)$/m.exec(contents)?.[1]
+  const script = /^# target-script-json: (.+)$/m.exec(contents)?.[1]
+  if (exec === undefined || script === undefined) return null
+  try {
+    const execPath: unknown = JSON.parse(exec)
+    const scriptPath: unknown = JSON.parse(script)
+    return typeof execPath === 'string' && typeof scriptPath === 'string'
+      ? { execPath, scriptPath }
+      : null
+  } catch {
+    return null
+  }
+}
+
+function quote(value: string): string {
+  return `'${value.replaceAll("'", `'\\''`)}'`
+}
+
+function ensureManagedDirectories(homeDir: string): void {
+  if (!existsSync(homeDir)) mkdirSync(homeDir, { recursive: true, mode: 0o700 })
+  for (const dir of [path.join(homeDir, '.notifai'), path.join(homeDir, '.notifai', 'bin')]) {
+    if (!existsSync(dir)) mkdirSync(dir, { mode: 0o700 })
+    const stat = lstatSync(dir)
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      throw new Error(`${dir} is not a regular directory; refusing to install the hook adapter.`)
+    }
+    const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+    if (uid !== undefined && stat.uid !== uid) {
+      throw new Error(`${dir} is owned by uid ${stat.uid}, not the current user.`)
+    }
+    chmodSync(dir, 0o700)
+  }
+}
+
+function readSafeManagedFile(file: string): { contents: string; mode: number } {
+  const stat = lstatSync(file)
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new Error(`${file} is not a regular file; refusing to replace it.`)
+  }
+  const uid = typeof process.getuid === 'function' ? process.getuid() : undefined
+  if (uid !== undefined && stat.uid !== uid) {
+    throw new Error(`${file} is owned by uid ${stat.uid}, not the current user.`)
+  }
+  return { contents: readFileSync(file, 'utf8'), mode: stat.mode }
+}

package/src/hook-input.test.ts

@@ -0,0 +1,39 @@
+import { PassThrough } from 'node:stream'
+import { describe, expect, it } from 'vitest'
+import { readStdinWithTimeout } from './hook-input.js'
+
+describe('hook input reader', () => {
+  it('rejects a timeout when the harness pipe delivered no bytes', async () => {
+    const input = new PassThrough()
+    await expect(readStdinWithTimeout(input, 5)).rejects.toThrow(/timed out waiting 5ms/)
+  })
+
+  it('rejects a stream failure when no useful input exists', async () => {
+    const input = new PassThrough()
+    const reading = readStdinWithTimeout(input, 1_000)
+    input.destroy(new Error('stdin disappeared'))
+    await expect(reading).rejects.toThrow('stdin disappeared')
+  })
+
+  it('returns partial bytes on timeout so the hook can diagnose truncation', async () => {
+    const input = new PassThrough()
+    const reading = readStdinWithTimeout(input, 5)
+    input.write('{"session_id":')
+    await expect(reading).resolves.toBe('{"session_id":')
+  })
+
+  it('preserves complete buffered JSON when the stream fails after delivering it', async () => {
+    const input = new PassThrough()
+    const reading = readStdinWithTimeout(input, 1_000)
+    input.write('{"session_id":"kept"}')
+    input.destroy(new Error('late pipe failure'))
+    await expect(reading).resolves.toBe('{"session_id":"kept"}')
+  })
+
+  it('marks an oversized payload as truncated instead of treating it as empty', async () => {
+    const input = new PassThrough()
+    const reading = readStdinWithTimeout(input, 1_000, 12)
+    input.end('{"session_id":"far-too-long"}')
+    await expect(reading).resolves.toMatch(/hook input truncated/)
+  })
+})

package/src/hook-input.ts

@@ -0,0 +1,72 @@
+import type { Readable } from 'node:stream'
+
+const TRUNCATED_INPUT_SUFFIX = '\n[notifai: hook input truncated]\n'
+
+/**
+ * Read one harness-hook envelope without letting a stuck pipe hold the prompt.
+ *
+ * A timeout or stream error before any bytes arrive rejects, so the hook can
+ * record that its input was unavailable. Once bytes exist they are more useful
+ * than the transport failure: complete JSON can still run, while partial or
+ * capped JSON reaches the hook's malformed/truncated diagnostic.
+ */
+export function readStdinWithTimeout(
+  input: Readable = process.stdin,
+  timeoutMs = 2_000,
+  maxBytes = 1_000_000,
+): Promise<string> {
+  if ((input as Readable & { isTTY?: boolean }).isTTY === true) return Promise.resolve('')
+
+  return new Promise<string>((resolve, reject) => {
+    const chunks: Buffer[] = []
+    let total = 0
+    let settled = false
+
+    const cleanup = (): void => {
+      clearTimeout(timer)
+      input.off('data', onData)
+      input.off('end', onEnd)
+      input.off('error', onError)
+      input.destroy()
+    }
+    const finishBuffered = (): void => {
+      if (settled) return
+      settled = true
+      cleanup()
+      resolve(Buffer.concat(chunks).toString('utf8'))
+    }
+    const failEmpty = (err: Error): void => {
+      if (settled) return
+      if (chunks.length > 0) return finishBuffered()
+      settled = true
+      cleanup()
+      reject(err)
+    }
+    const onData = (chunk: Buffer | string): void => {
+      const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
+      const remaining = Math.max(0, maxBytes - total)
+      if (bytes.length <= remaining) {
+        chunks.push(bytes)
+        total += bytes.length
+        return
+      }
+      if (remaining > 0) {
+        chunks.push(bytes.subarray(0, remaining))
+        total += remaining
+      }
+      chunks.push(Buffer.from(TRUNCATED_INPUT_SUFFIX))
+      finishBuffered()
+    }
+    const onEnd = (): void => finishBuffered()
+    const onError = (err: Error): void => failEmpty(err)
+
+    const timer = setTimeout(
+      () => failEmpty(new Error(`timed out waiting ${timeoutMs}ms for hook input`)),
+      timeoutMs,
+    )
+    timer.unref?.()
+    input.on('data', onData)
+    input.once('end', onEnd)
+    input.once('error', onError)
+  })
+}