nebula-ai-core 0.1.0

package/src/pairing.ts

@@ -0,0 +1,285 @@
+// DM pairing system — one-time codes for authorizing new platform users.
+//
+// Ports hermes gateway/pairing.py 1:1 to TypeScript. Operators run
+// `nebula pairing approve telegram <code>` after the bot DMs an unrecognized
+// user a code.
+//
+// Security:
+//  - 8-char codes from 32-char unambiguous alphabet (no 0/O, 1/I)
+//  - crypto-secure randomness via randomInt
+//  - 1-hour code TTL, max 3 pending per platform
+//  - 1 request / user / 10 min rate limit
+//  - 1-hour lockout after 5 failed approvals
+//  - chmod 0600 on all data files (best-effort on non-POSIX)
+//
+// Storage layout under `dir`:
+//   <platform>-pending.json     pending codes
+//   <platform>-approved.json    approved users
+//   _rate_limits.json           rate-limit + lockout tracking
+
+import { randomInt } from 'node:crypto'
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+
+export const PAIRING_ALPHABET = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'
+export const PAIRING_CODE_LENGTH = 8
+export const PAIRING_CODE_TTL_SECONDS = 3600
+export const PAIRING_RATE_LIMIT_SECONDS = 600
+export const PAIRING_LOCKOUT_SECONDS = 3600
+export const PAIRING_MAX_PENDING_PER_PLATFORM = 3
+export const PAIRING_MAX_FAILED_ATTEMPTS = 5
+
+export interface PairingStoreOpts {
+  dir: string
+  now?: () => number
+}
+
+export interface PendingEntry {
+  userId: string
+  userName: string
+  createdAt: number
+}
+
+export interface ApprovedEntry {
+  userName: string
+  approvedAt: number
+}
+
+export interface PendingListing {
+  platform: string
+  code: string
+  userId: string
+  userName: string
+  ageMinutes: number
+  createdAt: number
+}
+
+export interface ApprovedListing {
+  platform: string
+  userId: string
+  userName: string
+  approvedAt: number
+}
+
+export interface ApproveResult {
+  userId: string
+  userName: string
+}
+
+export class PairingStore {
+  readonly #dir: string
+  readonly #now: () => number
+
+  constructor(opts: PairingStoreOpts) {
+    this.#dir = opts.dir
+    this.#now = opts.now ?? (() => Date.now() / 1000)
+    mkdirSync(this.#dir, { recursive: true })
+  }
+
+  isApproved(platform: string, userId: string): boolean {
+    const approved = this.#loadJson<Record<string, ApprovedEntry>>(this.#approvedPath(platform))
+    return userId in approved
+  }
+
+  listApproved(platform?: string): ApprovedListing[] {
+    const platforms = platform ? [platform] : this.#allPlatforms('approved')
+    const out: ApprovedListing[] = []
+    for (const p of platforms) {
+      const approved = this.#loadJson<Record<string, ApprovedEntry>>(this.#approvedPath(p))
+      for (const [uid, info] of Object.entries(approved)) {
+        out.push({ platform: p, userId: uid, userName: info.userName, approvedAt: info.approvedAt })
+      }
+    }
+    return out
+  }
+
+  generateCode(platform: string, userId: string, userName = ''): string | null {
+    this.#cleanupExpired(platform)
+    if (this.#isLockedOut(platform)) return null
+    if (this.#isRateLimited(platform, userId)) return null
+    const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(platform))
+    if (Object.keys(pending).length >= PAIRING_MAX_PENDING_PER_PLATFORM) return null
+
+    let code = ''
+    for (let i = 0; i < PAIRING_CODE_LENGTH; i++) {
+      code += PAIRING_ALPHABET[randomInt(0, PAIRING_ALPHABET.length)]
+    }
+
+    pending[code] = { userId, userName, createdAt: this.#now() }
+    this.#saveJson(this.#pendingPath(platform), pending)
+    this.#recordRateLimit(platform, userId)
+    return code
+  }
+
+  approveCode(platform: string, code: string): ApproveResult | null {
+    this.#cleanupExpired(platform)
+    const normalized = code.toUpperCase().trim()
+    const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(platform))
+    const entry = pending[normalized]
+    if (!entry) {
+      this.#recordFailedAttempt(platform)
+      return null
+    }
+    delete pending[normalized]
+    this.#saveJson(this.#pendingPath(platform), pending)
+
+    const approved = this.#loadJson<Record<string, ApprovedEntry>>(this.#approvedPath(platform))
+    approved[entry.userId] = { userName: entry.userName, approvedAt: this.#now() }
+    this.#saveJson(this.#approvedPath(platform), approved)
+
+    this.#clearFailedAttempts(platform)
+    return { userId: entry.userId, userName: entry.userName }
+  }
+
+  listPending(platform?: string): PendingListing[] {
+    const platforms = platform ? [platform] : this.#allPlatforms('pending')
+    const out: PendingListing[] = []
+    for (const p of platforms) {
+      this.#cleanupExpired(p)
+      const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(p))
+      for (const [code, info] of Object.entries(pending)) {
+        const ageMinutes = Math.floor((this.#now() - info.createdAt) / 60)
+        out.push({
+          platform: p,
+          code,
+          userId: info.userId,
+          userName: info.userName,
+          ageMinutes,
+          createdAt: info.createdAt,
+        })
+      }
+    }
+    return out
+  }
+
+  clearPending(platform?: string): number {
+    const platforms = platform ? [platform] : this.#allPlatforms('pending')
+    let count = 0
+    for (const p of platforms) {
+      const pending = this.#loadJson<Record<string, PendingEntry>>(this.#pendingPath(p))
+      count += Object.keys(pending).length
+      this.#saveJson(this.#pendingPath(p), {})
+    }
+    return count
+  }
+
+  revoke(platform: string, userId: string): boolean {
+    const path = this.#approvedPath(platform)
+    const approved = this.#loadJson<Record<string, ApprovedEntry>>(path)
+    if (!(userId in approved)) return false
+    delete approved[userId]
+    this.#saveJson(path, approved)
+    return true
+  }
+
+  isLockedOut(platform: string): boolean {
+    return this.#isLockedOut(platform)
+  }
+
+  // ----- private helpers -----
+
+  #pendingPath(platform: string): string {
+    return join(this.#dir, `${platform}-pending.json`)
+  }
+  #approvedPath(platform: string): string {
+    return join(this.#dir, `${platform}-approved.json`)
+  }
+  #rateLimitPath(): string {
+    return join(this.#dir, '_rate_limits.json')
+  }
+
+  #loadJson<T>(path: string): T {
+    if (!existsSync(path)) return {} as T
+    try {
+      return JSON.parse(readFileSync(path, 'utf8')) as T
+    } catch {
+      return {} as T
+    }
+  }
+
+  #saveJson(path: string, data: unknown): void {
+    const tmp = `${path}.tmp-${process.pid}-${Date.now().toString(36)}`
+    writeFileSync(tmp, JSON.stringify(data, null, 2), 'utf8')
+    renameSync(tmp, path)
+    try {
+      chmodSync(path, 0o600)
+    } catch {
+      // non-POSIX; permissions are advisory only
+    }
+  }
+
+  #cleanupExpired(platform: string): void {
+    const path = this.#pendingPath(platform)
+    if (!existsSync(path)) return
+    const pending = this.#loadJson<Record<string, PendingEntry>>(path)
+    const now = this.#now()
+    let changed = false
+    for (const [code, info] of Object.entries(pending)) {
+      if (now - info.createdAt > PAIRING_CODE_TTL_SECONDS) {
+        delete pending[code]
+        changed = true
+      }
+    }
+    if (changed) this.#saveJson(path, pending)
+  }
+
+  #isRateLimited(platform: string, userId: string): boolean {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    const last = limits[`${platform}:${userId}`] ?? 0
+    return this.#now() - last < PAIRING_RATE_LIMIT_SECONDS
+  }
+
+  #recordRateLimit(platform: string, userId: string): void {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    limits[`${platform}:${userId}`] = this.#now()
+    this.#saveJson(this.#rateLimitPath(), limits)
+  }
+
+  #isLockedOut(platform: string): boolean {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    const lockoutUntil = limits[`_lockout:${platform}`] ?? 0
+    return this.#now() < lockoutUntil
+  }
+
+  #recordFailedAttempt(platform: string): void {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    const failKey = `_failures:${platform}`
+    const fails = (limits[failKey] ?? 0) + 1
+    limits[failKey] = fails
+    if (fails >= PAIRING_MAX_FAILED_ATTEMPTS) {
+      limits[`_lockout:${platform}`] = this.#now() + PAIRING_LOCKOUT_SECONDS
+      limits[failKey] = 0
+    }
+    this.#saveJson(this.#rateLimitPath(), limits)
+  }
+
+  #clearFailedAttempts(platform: string): void {
+    const limits = this.#loadJson<Record<string, number>>(this.#rateLimitPath())
+    if (`_failures:${platform}` in limits) {
+      delete limits[`_failures:${platform}`]
+      this.#saveJson(this.#rateLimitPath(), limits)
+    }
+  }
+
+  #allPlatforms(suffix: 'pending' | 'approved'): string[] {
+    if (!existsSync(this.#dir)) return []
+    const entries = readdirSync(this.#dir)
+    const tail = `-${suffix}.json`
+    const platforms = new Set<string>()
+    for (const f of entries) {
+      if (f.endsWith(tail)) {
+        const p = f.slice(0, -tail.length)
+        if (!p.startsWith('_')) platforms.add(p)
+      }
+    }
+    return Array.from(platforms)
+  }
+}

package/src/paths.ts

@@ -0,0 +1,70 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+
+/** Resolve `~/.nebula` at call time so tests can override via NEBULA_ROOT or HOME. */
+function nebulaRoot(): string {
+  return process.env.NEBULA_ROOT ?? join(homedir(), '.nebula')
+}
+
+export interface AgentPaths {
+  readonly root: string
+  readonly config: string
+  readonly skills: string
+  readonly plugins: string
+  readonly agentsDir: string
+  agent(id: string): {
+    dir: string
+    keystore: string
+    cache: string
+    memoryDir: string
+    memoryIndex: string
+    agentMemoryDir: string
+    userMemoryDir: string
+    publicDir: string
+    activityLog: string
+    runtimeState: string
+    inboxDir: string
+    pairingDir: string
+  }
+}
+
+export const agentPaths: AgentPaths = {
+  get root() {
+    return nebulaRoot()
+  },
+  get config() {
+    return join(nebulaRoot(), 'config.ts')
+  },
+  get skills() {
+    return join(nebulaRoot(), 'skills')
+  },
+  get plugins() {
+    return join(nebulaRoot(), 'plugins')
+  },
+  get agentsDir() {
+    return join(nebulaRoot(), 'agents')
+  },
+  agent(id: string) {
+    const dir = join(nebulaRoot(), 'agents', id)
+    return {
+      dir,
+      keystore: join(dir, 'keystore.json'),
+      cache: join(dir, 'cache'),
+      memoryDir: join(dir, 'memory'),
+      memoryIndex: join(dir, 'memory', 'MEMORY.md'),
+      agentMemoryDir: join(dir, 'memory', 'agent'),
+      userMemoryDir: join(dir, 'memory', 'user'),
+      publicDir: join(dir, 'memory', 'public'),
+      activityLog: join(dir, 'activity.jsonl'),
+      runtimeState: join(dir, 'runtime', 'state.json'),
+      inboxDir: join(dir, 'inbox'),
+      pairingDir: join(dir, 'pairing'),
+    }
+  },
+}
+
+/** Compute the deterministic agent id from a wallet address. Stable pre-iNFT. */
+export function placeholderAgentId(walletAddress: string): string {
+  const clean = walletAddress.toLowerCase().replace(/^0x/, '')
+  return clean.slice(0, 16)
+}

package/src/permission/dangerous.ts

@@ -0,0 +1,108 @@
+/**
+ * Dangerous command pattern set ported from hermes-agent/tools/approval.py.
+ * Pattern matching is the cheap pre-LLM safety floor for `shell.run` and
+ * destructive shell-equivalent tool args. Brain still needs explicit approval
+ * for matches in `prompt` mode, but YOLO mode (`approvals.mode = "off"`) skips.
+ *
+ * Patterns adapted to JS regex flavor (no \b on hex/utf, no DOTALL by default).
+ * Each entry returns the human description used in approval prompts.
+ */
+
+const SENSITIVE_WRITE_TARGETS =
+  '/etc/[a-z]|/etc/passwd|/etc/shadow|/etc/sudoers|/boot/|/usr/local/etc/'
+
+export const DANGEROUS_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/\brm\s+(-[^\s]*\s+)*\//, 'delete in root path'],
+  [/\brm\s+-[^\s]*r/, 'recursive delete'],
+  [/\brm\s+--recursive\b/, 'recursive delete (long flag)'],
+  [/\bchmod\s+(-[^\s]*\s+)*(777|666|o\+[rwx]*w|a\+[rwx]*w)\b/, 'world/other-writable permissions'],
+  [/\bchown\s+(-[^\s]*)?R\s+root/, 'recursive chown to root'],
+  [/\bmkfs\b/, 'format filesystem'],
+  [/\bdd\s+.*if=/, 'disk copy'],
+  [/>\s*\/dev\/sd/, 'write to block device'],
+  [/\bDROP\s+(TABLE|DATABASE)\b/i, 'SQL DROP'],
+  [/\bDELETE\s+FROM\b(?!.*\bWHERE\b)/i, 'SQL DELETE without WHERE'],
+  [/\bTRUNCATE\s+(TABLE)?\s*\w/i, 'SQL TRUNCATE'],
+  [/>\s*\/etc\//, 'overwrite system config'],
+  [/\bsystemctl\s+(stop|disable|mask)\b/, 'stop/disable system service'],
+  [/\bkill\s+-9\s+-1\b/, 'kill all processes'],
+  [/\bpkill\s+-9\b/, 'force kill processes'],
+  [/:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/, 'fork bomb'],
+  [/\b(bash|sh|zsh|ksh)\s+-[^\s]*c(\s+|$)/, 'shell command via -c/-lc flag'],
+  [/\b(python[23]?|perl|ruby|node)\s+-[ec]\s+/, 'script execution via -e/-c flag'],
+  [/\b(curl|wget)\b.*\|\s*(ba)?sh\b/, 'pipe remote content to shell'],
+  [
+    /\b(bash|sh|zsh|ksh)\s+<\s*<?\s*\(\s*(curl|wget)\b/,
+    'execute remote script via process substitution',
+  ],
+  [new RegExp(`\\btee\\b.*["']?(${SENSITIVE_WRITE_TARGETS})`), 'overwrite system file via tee'],
+  [new RegExp(`>>?\\s*["']?(${SENSITIVE_WRITE_TARGETS})`), 'overwrite system file via redirection'],
+  [/\bxargs\s+.*\brm\b/, 'xargs with rm'],
+  [/\bfind\b.*-exec\s+(\/\S*\/)?rm\b/, 'find -exec rm'],
+  [/\bfind\b.*-delete\b/, 'find -delete'],
+  // Self-termination protection
+  [
+    /\b(pkill|killall)\b.*\b(nebula|cli\.ts|nebula\/bin)\b/,
+    'kill nebula process (self-termination)',
+  ],
+  [/\bkill\b.*\$\(\s*pgrep\b/, 'kill process via pgrep expansion (self-termination)'],
+  [/\bkill\b.*`\s*pgrep\b/, 'kill process via backtick pgrep expansion (self-termination)'],
+  [/\b(cp|mv|install)\b.*\s\/etc\//, 'copy/move file into /etc/'],
+  [/\bsed\s+-[^\s]*i.*\s\/etc\//, 'in-place edit of system config'],
+  [/\bsed\s+--in-place\b.*\s\/etc\//, 'in-place edit of system config (long flag)'],
+  [/\b(python[23]?|perl|ruby|node)\s+<</, 'script execution via heredoc'],
+  [/\bgit\s+reset\s+--hard\b/, 'git reset --hard (destroys uncommitted changes)'],
+  [/\bgit\s+push\b.*--force\b/, 'git force push (rewrites remote history)'],
+  [/\bgit\s+push\b.*\s-f\b/, 'git force push short flag (rewrites remote history)'],
+  [/\bgit\s+clean\s+-[^\s]*f/, 'git clean with force (deletes untracked files)'],
+  [/\bgit\s+branch\s+-D\b/, 'git branch force delete'],
+  [/\bchmod\s+\+x\b.*[;&|]+\s*\.\//, 'chmod +x followed by immediate execution'],
+] as const
+
+export interface DangerousMatch {
+  match: true
+  key: string
+  description: string
+}
+
+export interface NoMatch {
+  match: false
+}
+
+/**
+ * Pre-compiled case-insensitive twin of every pattern. `detectDangerousCommand`
+ * runs on the hot path of every shell.run; building 35 RegExp objects per call
+ * was visible in profiles. Compile once at module load, reuse forever.
+ */
+const COMPILED_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = DANGEROUS_PATTERNS.map(
+  ([pattern, description]) =>
+    [
+      pattern.flags.includes('i') ? pattern : new RegExp(pattern.source, `${pattern.flags}i`),
+      description,
+    ] as const,
+)
+
+/**
+ * Normalize a command before pattern matching: strip ANSI sequences, NULs,
+ * and Unicode lookalikes (NFKC). Mirrors hermes' defense-in-depth so
+ * obfuscation tricks don't bypass detection. The patterns below intentionally
+ * include the control characters they detect, hence the noControlCharactersInRegex
+ * suppressions.
+ */
+function normalize(command: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional ANSI matcher
+  const ansi = /\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~]|\][^\x07]*(?:\x07|\x1B\\)|P[^\x1B]*\x1B\\)/g
+  let s = command.replace(ansi, '')
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intentional NUL stripping
+  s = s.replace(/\x00/g, '')
+  s = s.normalize('NFKC')
+  return s
+}
+
+export function detectDangerousCommand(command: string): DangerousMatch | NoMatch {
+  const norm = normalize(command).toLowerCase()
+  for (const [re, description] of COMPILED_PATTERNS) {
+    if (re.test(norm)) return { match: true, key: description, description }
+  }
+  return { match: false }
+}

package/src/permission/env-redact.ts

@@ -0,0 +1,54 @@
+/**
+ * Redact secrets-bearing env vars before passing process.env to a shell
+ * subprocess. Mirrors hermes' env passthrough policy: API keys, wallet
+ * material, and provider creds never leak to a child process the brain
+ * controls. The brain may still need PATH, HOME, SHELL, LANG, TERM, etc.
+ */
+
+const ALWAYS_DENY: RegExp[] = [
+  /^NEBULA_(OPERATOR|AGENT)_PRIVKEY/i,
+  /^NEBULA_KEYCHAIN/i,
+  /^NEBULA_TEST_AGENT_PRIVKEY/i,
+  /^OPENAI_API_KEY$/i,
+  /^ANTHROPIC_API_KEY$/i,
+  /^GOOGLE_API_KEY$/i,
+  /^GEMINI_API_KEY$/i,
+  /^GROQ_API_KEY$/i,
+  /^AZURE_OPENAI_API_KEY$/i,
+  /^DEEPSEEK_API_KEY$/i,
+  /^MISTRAL_API_KEY$/i,
+  /^TOGETHER_API_KEY$/i,
+  /^XAI_API_KEY$/i,
+  /^GH_TOKEN$/i,
+  /^GITHUB_TOKEN$/i,
+  /^GITLAB_TOKEN$/i,
+  /^NPM_TOKEN$/i,
+  /^AWS_(ACCESS_KEY_ID|SECRET_ACCESS_KEY|SESSION_TOKEN)$/i,
+  /^GCP_/i,
+  /^GOOGLE_APPLICATION_CREDENTIALS$/i,
+  /^OG_(PRIVKEY|PRIVATE_KEY|MNEMONIC)/i,
+  /_(PRIVKEY|PRIVATE_KEY|SECRET|MNEMONIC|API_KEY|AUTH_TOKEN)$/i,
+  /^DATABASE_URL$/i,
+  /^TELEGRAM_BOT_TOKEN$/i,
+  /^DISCORD_BOT_TOKEN$/i,
+  /^STRIPE_SECRET_KEY$/i,
+]
+
+export interface EnvRedactResult {
+  env: Record<string, string>
+  removed: string[]
+}
+
+export function redactEnv(env: NodeJS.ProcessEnv | Record<string, string>): EnvRedactResult {
+  const out: Record<string, string> = {}
+  const removed: string[] = []
+  for (const [k, v] of Object.entries(env)) {
+    if (typeof v !== 'string') continue
+    if (ALWAYS_DENY.some(re => re.test(k))) {
+      removed.push(k)
+      continue
+    }
+    out[k] = v
+  }
+  return { env: out, removed }
+}

package/src/permission/index.ts

@@ -0,0 +1,16 @@
+export {
+  detectDangerousCommand,
+  DANGEROUS_PATTERNS,
+  type DangerousMatch,
+  type NoMatch,
+} from './dangerous'
+export { PathGuard, type PathGuardOpts, type PathGuardResult } from './path-guard'
+export { redactEnv, type EnvRedactResult } from './env-redact'
+export {
+  PermissionService,
+  type PermissionMode,
+  type PermissionDecision,
+  type PermissionRequest,
+  type PermissionPrompter,
+  type PermissionServiceOpts,
+} from './service'

package/src/permission/path-guard.ts

@@ -0,0 +1,114 @@
+import { realpathSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+
+/**
+ * Default denylist for `fs.write` / `fs.patch` writes. Hard-deny paths whose
+ * compromise would let the agent leak operator credentials or system state:
+ *
+ *   - SSH/AWS/GCP credential trees (~/.ssh, ~/.aws, ~/.config/gcloud)
+ *   - Dotenv-style files (.env, .env.local, etc.)
+ *   - System config (/etc/, /boot/, /usr/local/etc/)
+ *   - The nebula state tree itself (`agentDir` and parent `~/.nebula/`)
+ *     so the brain can't rewrite its own config or operator keystore.
+ *
+ * The constructor takes the agentDir explicitly so each ToolRegistry instance
+ * has the right denylist for its agent.
+ */
+export interface PathGuardOpts {
+  agentDir: string
+  /** Extra absolute paths to deny (test override). */
+  extraDeny?: string[]
+}
+
+export interface PathGuardResult {
+  allowed: boolean
+  reason?: string
+}
+
+const DEFAULT_DENY_PATTERNS: RegExp[] = [
+  /\.ssh(\/|$)/,
+  /\.aws(\/|$)/,
+  /\.config\/gcloud(\/|$)/,
+  /(^|\/)\.env(\.|$)/,
+  /^\/etc\//,
+  /^\/boot\//,
+  /^\/usr\/local\/etc\//,
+  /^\/var\/log\//,
+  /^\/sys(\/|$)/,
+  /^\/proc(\/|$)/,
+  /^\/dev(\/|$)/,
+]
+
+/**
+ * macOS `/var/folders/...` resolves to `/private/var/folders/...` via symlink;
+ * Linux is usually direct. `path.resolve()` does NOT follow symlinks, so a
+ * naive textual compare would let a brain that addresses the canonical form
+ * smuggle past the denylist. Canonicalise at construction (and at check time)
+ * so both forms are caught.
+ */
+function safeRealpath(p: string): string {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+/** Both forms of one denylist entry, so as-given OR canonical can match. */
+function denyEntry(p: string): string[] {
+  const raw = resolve(p)
+  const canon = safeRealpath(raw)
+  return raw === canon ? [raw] : [raw, canon]
+}
+
+export class PathGuard {
+  private readonly absolutePathsDenied: string[]
+
+  constructor(private readonly opts: PathGuardOpts) {
+    const home = homedir()
+    const nebulaRoot = resolve(home, '.nebula')
+    // Each protected location contributes BOTH the raw resolve()'d form and
+    // the realpath-canonical form. macOS resolves /var/folders to /private/...
+    // and a path being checked may not exist yet (e.g. fs.write of a new file
+    // inside agentDir), so realpath at check time would return the raw form.
+    // Storing both at construction lets either match.
+    this.absolutePathsDenied = [
+      ...denyEntry(opts.agentDir),
+      ...denyEntry(nebulaRoot),
+      ...denyEntry(resolve(home, '.ssh')),
+      ...denyEntry(resolve(home, '.aws')),
+      ...denyEntry(resolve(home, '.config', 'gcloud')),
+      ...(opts.extraDeny ?? []).flatMap(p => denyEntry(p)),
+    ]
+  }
+
+  check(rawPath: string): PathGuardResult {
+    let abs: string
+    try {
+      abs = resolve(rawPath.startsWith('~') ? rawPath.replace('~', homedir()) : rawPath)
+    } catch {
+      return { allowed: false, reason: 'unresolvable path' }
+    }
+    // Check both the as-given form (`/var/folders/.../foo`) and the canonical
+    // form (`/private/var/folders/.../foo`) — either matching the denylist
+    // is a hit. Cheap (one realpath syscall) and closes a real bypass hole.
+    const canonical = safeRealpath(abs)
+    for (const denied of this.absolutePathsDenied) {
+      if (
+        abs === denied ||
+        abs.startsWith(`${denied}/`) ||
+        canonical === denied ||
+        canonical.startsWith(`${denied}/`)
+      ) {
+        return { allowed: false, reason: `protected path: ${denied}` }
+      }
+    }
+    for (const re of DEFAULT_DENY_PATTERNS) {
+      if (re.test(abs) || re.test(canonical)) {
+        return { allowed: false, reason: `protected path pattern: ${re.source}` }
+      }
+    }
+    return { allowed: true }
+  }
+}