Node.js 22 Native Capability Permission Model and I/O Boundary Guardrail

Enforces Node.js 22 native runtime permission flags and programmatic capability checks to restrict filesystem I/O, child process spawning, worker creation, and native addon execution. This invariant prevents compromised third-party dependencies from accessing sensitive credentials, spawning rogue binaries, or exfiltrating data without requiring container or OS-level virtualization. All I/O interfaces must implement explicit capability pre-flight checks and operate under the least-privilege permission model.

--- description: Node.js 22 Native Capability Permission Model and I/O Boundary Guardrail - Enforces Node.js 22 native runtime permission flags and programmatic capability checks to restrict filesystem I/O, child process spawning, worker creation, and native addon execution. This invariant prevents compromised third-party dependencies from accessing sensitive credentials, spawning rogue binaries, or exfiltrating data without requiring container or OS-level virtualization. All I/O interfaces must implement explicit capability pre-flight checks and operate under the least-privilege permission model. globs: src/**/*.{ts,js,mjs,cjs}, package.json, scripts/**/*.{sh,ts,js} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/nodejs-22-permission-model-io-boundary" --- # Node.js 22 Native Capability Permission Model and I/O Boundary Guardrail > **Severity**: CRITICAL | **Category**: security > **Anti-Pattern Warning**: Unconstrained Ambient Runtime Authority Allowing Third-Party Supply-Chain Remote Code Execution and Data Exfiltration ## System Constraints You are a Principal Security Architect enforcing Node.js 22 Capability Permission Model I/O boundaries. The application runs in high-risk environments vulnerable to npm dependency hijacking and supply-chain exfiltration. You must mandate runtime-enforced permission barriers (--permission, --allow-fs-read, --allow-fs-write, --allow-child-process, --allow-worker), programmatic capability checks using process.permission.has(), and fail-closed architectures that restrict ambient authority across all execution paths. ## Strict Guidelines - Engineers MUST ALWAYS enforce the Node.js 22 native permission model in execution manifests and npm run scripts via the `--permission` CLI flag. - Engineers MUST explicitly restrict filesystem access to dedicated, granular directories using `--allow-fs-read` and `--allow-fs-write` with absolute or explicit relative path boundaries, never wildcarding `/` or root drives. - Engineers MUST NOT grant `--allow-child-process`, `--allow-addons`, or `--allow-wasi` unless an isolated service domain explicitly requires native binary execution, verified via architectural sign-off. - Services MUST query `process.permission.has(scope, reference)` before attempting filesystem, worker, or process-level operations to gracefully handle restricted capabilities and fail closed. - Components NEVER execute dynamic shell commands (`child_process.exec`, `child_process.spawn`) without validating runtime permission capability and using sanitized argument vectors instead of raw shell interpreters. ## Bad vs Good Implementations ### Ambient Filesystem & Child Process Access vs. Capability-Bounded Runtime Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The code assumes unrestricted ambient authority. It reads sensitive filesystem paths directly and spawns arbitrary child processes via a shell string. A supply-chain payload in an imported package could steal credentials or run arbitrary binaries without container containment. ```typescript import { execSync } from 'node:child_process'; import * as fs from 'node:fs/promises'; import * as path from 'node:path'; // ANTI-PATTERN: Relies on ambient runtime authority. // Any compromised transitive dependency can access root secrets or spawn shells. export async function processUserUpload(uploadPath: string): Promise<string> { // Arbitrary read outside intended application boundary const secret = await fs.readFile(path.resolve('/etc/app-secrets/token.key'), 'utf-8'); // Spawns shell without capability isolation const result = execSync(`magick convert ${uploadPath} -resize 100x100 output.png`); return result.toString(); } ``` #### Production Standard (Correct) > **Standard**: Validates runtime boundaries using Node 22's 'process.permission.has()' for scoped read, write, and child process capabilities. Path traversal is prevented using path.basename, shell expansion is disabled, and the application fails closed if ambient permissions were restricted by `--permission --allow-fs-read=/var/app/data/uploads --allow-fs-write=/var/app/data/processed`. ```typescript import { spawn } from 'node:child_process'; import * as fs from 'node:fs/promises'; import * as path from 'node:path'; const ALLOWED_UPLOAD_DIR = '/var/app/data/uploads'; const ALLOWED_OUTPUT_DIR = '/var/app/data/processed'; // PRODUCTION PATTERN: Enforces Node 22 programmatic permission checks and strict boundary validation export async function processUserUpload(filename: string): Promise<string> { const resolvedInput = path.resolve(ALLOWED_UPLOAD_DIR, path.basename(filename)); const resolvedOutput = path.resolve(ALLOWED_OUTPUT_DIR, `${path.basename(filename)}.png`); // Programmatic verification against Node 22 Permission Model if (typeof process.permission !== 'undefined') { if (!process.permission.has('fs.read', resolvedInput)) { throw new Error(`Security Exception: Read capability denied for path: ${resolvedInput}`); } if (!process.permission.has('fs.write', resolvedOutput)) { throw new Error(`Security Exception: Write capability denied for path: ${resolvedOutput}`); } if (!process.permission.has('child')) { throw new Error('Security Exception: Child process execution capability not granted'); } } // Safe child process execution without shell expansion return new Promise((resolve, reject) => { const child = spawn('/usr/bin/convert', [resolvedInput, '-resize', '100x100', resolvedOutput], { shell: false, stdio: ['ignore', 'pipe', 'pipe'] }); child.on('error', reject); child.on('close', (code) => { if (code === 0) resolve(resolvedOutput); else reject(new Error(`Conversion failed with exit code: ${code}`)); }); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Node.js 22 Native Capability Permission Model and I/O Boundary Guardrail

Node.js 22 Native Capability Permission Model and I/O Boundary Guardrail defines an industrial-grade behavioral standard for security engineering. Enforces Node.js 22 native runtime permission flags and programmatic capability checks to restrict filesystem I/O, child process spawning, worker creation, and native addon execution. This invariant prevents compromised third-party dependencies from accessing sensitive credentials, spawning rogue binaries, or exfiltrating data without requiring container or OS-level virtualization. All I/O interfaces must implement explicit capability pre-flight checks and operate under the least-privilege permission model. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Unconstrained Ambient Runtime Authority Allowing Third-Party Supply-Chain Remote Code Execution and Data Exfiltration Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Unconstrained Ambient Runtime Authority Allowing Third-Party Supply-Chain Remote Code Execution and Data Exfiltration	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS enforce the Node.js 22 native permission model in execution manifests and npm run scripts via the `--permission` CLI flag.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.