@jerryan/just-bash 3.5.0

package/dist/security/blocked-globals.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Blocked Globals for Defense-in-Depth Box
+ *
+ * This module defines which JavaScript globals should be blocked during
+ * bash script execution to prevent code execution escape vectors.
+ *
+ * IMPORTANT: This is a SECONDARY defense layer. The primary security comes
+ * from proper sandboxing and architectural constraints.
+ *
+ * NOTE: Dynamic import() is handled separately in defense-in-depth-box.ts via
+ * ESM loader hooks. This module only defines global/property patching.
+ */
+import type { SecurityViolationType } from "./types.js";
+/**
+ * Strategy for handling a blocked global.
+ * - "throw": Replace with a proxy that throws on access/call
+ * - "freeze": Freeze the object to prevent modification
+ */
+export type BlockStrategy = "throw" | "freeze";
+/**
+ * Configuration for a blocked global.
+ */
+export interface BlockedGlobal {
+    /**
+     * The property name on the target object (e.g., "Function", "eval").
+     */
+    prop: string;
+    /**
+     * The target object containing the property.
+     * Usually globalThis, but can be other objects like Object.prototype.
+     */
+    target: object;
+    /**
+     * Type of violation to record when this global is accessed.
+     */
+    violationType: SecurityViolationType;
+    /**
+     * Strategy for blocking this global.
+     */
+    strategy: BlockStrategy;
+    /**
+     * Human-readable description of why this is blocked.
+     */
+    reason: string;
+    /**
+     * For object proxies (strategy: "throw" on objects): allow reads of these
+     * specific property names even inside the sandbox context. Node.js internals
+     * read certain properties (e.g., process.env keys) during module loading
+     * within the AsyncLocalStorage context, so they must be allowed through.
+     */
+    allowedKeys?: Set<string>;
+}
+export declare function getBlockedGlobalViolationTypes(): ReadonlySet<SecurityViolationType>;
+/**
+ * Get the list of globals to block during script execution.
+ *
+ * Note: This function must be called at runtime (not module load time)
+ * because some globals may not exist in all environments.
+ */
+export declare function getBlockedGlobals(): BlockedGlobal[];

package/dist/security/defense-context.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Fail closed when execution is expected to run inside defense async context.
+ */
+export declare function assertDefenseContext(requireDefenseContext: boolean | undefined, component: string, phase: string): void;
+/**
+ * Guard an async boundary by checking context both before and after await.
+ */
+export declare function awaitWithDefenseContext<T>(requireDefenseContext: boolean | undefined, component: string, phase: string, op: () => Promise<T>): Promise<T>;
+/**
+ * Bind a callback to the current defense async context and assert defense
+ * invariants on callback entry.
+ */
+export declare function bindDefenseContextCallback<TArgs extends unknown[], TResult>(requireDefenseContext: boolean | undefined, component: string, phase: string, callback: (...args: TArgs) => TResult): (...args: TArgs) => TResult;

package/dist/security/defense-in-depth-box.d.ts

@@ -0,0 +1,354 @@
+/**
+ * Defense-in-Depth Box
+ *
+ * A security layer that monkey-patches dangerous JavaScript globals during
+ * bash script execution. Uses AsyncLocalStorage to track execution context,
+ * so blocks only apply to code running within bash.exec() - not to concurrent
+ * operations in the same process.
+ *
+ * IMPORTANT: This is a SECONDARY defense layer. It should never be relied upon
+ * as the primary security mechanism. The primary security comes from proper
+ * sandboxing, input validation, and architectural constraints.
+ *
+ * Key design decisions:
+ * - AsyncLocalStorage for context tracking (blocks only affect sandboxed code)
+ * - Reference counting for nested exec() calls
+ * - Patches are process-wide but checks are context-aware
+ * - Violations are recorded even in audit mode
+ *
+ * Dynamic import() mitigation (three layers):
+ * 1. ESM loader hooks (module.register/registerHooks):
+ *    - block data:/blob: URLs only in the untrusted async context
+ *    - block Node.js builtin specifiers in untrusted sandbox context
+ * 2. Module._resolveFilename blocked — catches file-based specifiers
+ * 3. Filesystem restrictions — OverlayFs writes to memory only
+ *
+ * Runtimes with only module.register() (no registerHooks) resolve auto mode as
+ * unsupported and reject explicitly enabled activation. Their separate loader
+ * thread cannot observe AsyncLocalStorage, so installing a partial or
+ * process-global fallback would either be misleading or break unrelated host
+ * imports.
+ */
+import type { DefenseInDepthConfig, DefenseInDepthHandle, DefenseInDepthStats, DefenseInDepthStatus, SecurityViolation } from "./types.js";
+/**
+ * Error thrown when a security violation is detected and blocking is enabled.
+ */
+export declare class SecurityViolationError extends Error {
+    readonly violation: SecurityViolation;
+    constructor(message: string, violation: SecurityViolation);
+}
+/**
+ * Defense-in-Depth Box
+ *
+ * Singleton class that manages security patches during bash execution.
+ * Use getInstance() to get or create the instance.
+ */
+export declare class DefenseInDepthBox {
+    private static instance;
+    private static importHooksRegistered;
+    /**
+     * Tracks active trusted scopes per executionId.
+     * Needed for async machinery that may not preserve `store.trusted` all the
+     * way into Node.js internals (e.g. dynamic import resolution hooks).
+     */
+    private static trustedExecutionDepth;
+    private config;
+    private refCount;
+    private patchFailures;
+    private activeExecutionIds;
+    /** Reusable DefenseContext objects keyed by executionId (avoids per-.then() allocation). */
+    private contextCache;
+    private originalDescriptors;
+    /**
+     * Descriptors made temporarily read-only while the shared host realm is
+     * protected. Unlike process-lifetime hardening, every entry remains
+     * configurable and is restored exactly when the last handle deactivates.
+     */
+    private temporaryIntrinsicDescriptors;
+    private violations;
+    private activationTime;
+    private totalActiveTimeMs;
+    private constructor();
+    /**
+     * Get or create the singleton instance.
+     *
+     * @param config - Configuration for the defense box.
+     * @throws Error if called with a config that conflicts with the existing instance's
+     *         security-relevant settings (enabled, auditMode). This prevents a weaker
+     *         first caller from silently downgrading protection for later callers.
+     */
+    static getInstance(config?: DefenseInDepthConfig | boolean): DefenseInDepthBox;
+    /**
+     * Reset the singleton instance. Only use in tests.
+     */
+    static resetInstance(): void;
+    /**
+     * Check if the current async context is within sandboxed execution.
+     */
+    static isInSandboxedContext(): boolean;
+    /**
+     * Get the current execution ID if in a sandboxed context.
+     */
+    static getCurrentExecutionId(): string | undefined;
+    private static enterTrustedScope;
+    private static leaveTrustedScope;
+    private static isTrustedScopeActive;
+    private static isTrustedContext;
+    /**
+     * Check if a defense execution ID is still live (its handle is not deactivated).
+     */
+    private isExecutionIdActive;
+    /**
+     * Get or create a cached DefenseContext for an executionId.
+     * Avoids allocating a new {sandboxActive, executionId} object on every
+     * Promise.then / timer call.
+     */
+    private getCachedContext;
+    /**
+     * Bind a callback to the current defense AsyncLocalStorage context.
+     *
+     * Useful for infrastructure callbacks that may execute later via pre-captured
+     * timer references, while still needing executionId/trace continuity.
+     *
+     * Note: this intentionally does NOT preserve `trusted` mode. Trusted execution
+     * is meant to stay tightly scoped to the immediate infrastructure operation.
+     */
+    static bindCurrentContext<TArgs extends unknown[], TResult>(fn: (...args: TArgs) => TResult): (...args: TArgs) => TResult;
+    /**
+     * Check if defense-in-depth is enabled and functional.
+     * Returns false if AsyncLocalStorage is unavailable or config.enabled is false.
+     */
+    isEnabled(): boolean;
+    /** Return the resolved runtime capability without activating protection. */
+    getStatus(): DefenseInDepthStatus;
+    /**
+     * Update configuration. Only affects future activations.
+     */
+    updateConfig(config: Partial<DefenseInDepthConfig>): void;
+    /**
+     * Activate the defense box. Returns a handle for scoped execution.
+     *
+     * Usage:
+     * ```
+     * const { run, deactivate } = box.activate();
+     * try {
+     *   await run(async () => {
+     *     // Code here is protected
+     *   });
+     * } finally {
+     *   deactivate();
+     * }
+     * ```
+     */
+    activate(): DefenseInDepthHandle;
+    /**
+     * Force deactivation, restoring all patches regardless of ref count.
+     * Use for error recovery only.
+     */
+    forceDeactivate(): void;
+    /**
+     * Check if patches are currently applied.
+     */
+    isActive(): boolean;
+    /**
+     * Get statistics about the defense box.
+     */
+    getStats(): DefenseInDepthStats;
+    /**
+     * Get the list of patch paths that failed during the last activation.
+     */
+    getPatchFailures(): string[];
+    /**
+     * Clear stored violations. Useful for testing.
+     */
+    clearViolations(): void;
+    /**
+     * Get a human-readable path for a target object and property.
+     */
+    private getPathForTarget;
+    /**
+     * Run a function as trusted infrastructure code.
+     * Blocking is suspended for the current async context only — other
+     * concurrent exec() calls remain protected.
+     *
+     * Uses AsyncLocalStorage to scope the trust, so async operations
+     * spawned inside the callback inherit the trusted state.
+     */
+    static runTrusted<T>(fn: () => T): T;
+    /**
+     * Async version of runTrusted.
+     */
+    static runTrustedAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Restore blocking for an untrusted operation nested inside trusted host code.
+     */
+    static runUntrustedAsync<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Check if current context should be blocked.
+     * Returns false in audit mode, browser environment, outside sandboxed context,
+     * inside runTrusted(), or when the immediate caller is a Node.js bundled dep.
+     */
+    private shouldBlock;
+    /** Record audit events only for untrusted sandbox work. */
+    private shouldAudit;
+    /**
+     * Record a violation and optionally invoke the callback.
+     */
+    private recordViolation;
+    /**
+     * Create a blocking proxy for a function.
+     */
+    private createBlockingProxy;
+    /**
+     * Create a blocking proxy for an object (blocks all property access).
+     */
+    private createBlockingObjectProxy;
+    /** Preserve read access while denying mutation only in sandbox context. */
+    private createReadonlyObjectProxy;
+    /**
+     * Apply security patches to dangerous globals.
+     */
+    private applyPatches;
+    /**
+     * Close the cached-reference assignment path without permanently freezing
+     * host globals. The global proxies protect references obtained after
+     * activation; these temporary descriptor changes protect references cached
+     * before activation. Configurability is deliberately retained so teardown
+     * can restore the host realm byte-for-byte.
+     */
+    private protectReversibleIntrinsics;
+    /**
+     * Protect against .constructor.constructor escape vector.
+     *
+     * The pattern `{}.constructor.constructor` accesses Function via:
+     * - {}.constructor → Object (via Object.prototype.constructor)
+     * - Object.constructor → Function (via Function.prototype.constructor)
+     *
+     * By patching Function.prototype.constructor to return our blocked proxy,
+     * we block the escape vector without breaking normal .constructor access.
+     */
+    private protectConstructorChain;
+    /**
+     * Protect Error.prepareStackTrace from being set in sandbox context.
+     *
+     * The attack vector is:
+     * ```
+     * Error.prepareStackTrace = (err, stack) => {
+     *   return stack[0].getFunction().constructor; // Gets Function
+     * };
+     * const F = new Error().stack;
+     * F("return process")();
+     * ```
+     *
+     * We only block SETTING, not reading, because V8 reads it internally
+     * when creating error stack traces.
+     */
+    private protectErrorPrepareStackTrace;
+    /**
+     * Protect Promise.then callback lifetime across deactivate boundaries.
+     *
+     * Callbacks registered in sandbox context are wrapped with an execution-id
+     * liveness check. If they run after the originating handle is deactivated,
+     * they are blocked even if global patches have already been restored.
+     */
+    private protectPromiseThen;
+    /**
+     * Patch a prototype's constructor property to block access in sandbox context.
+     */
+    private patchPrototypeConstructor;
+    /**
+     * Protect process.mainModule from being accessed or set in sandbox context.
+     *
+     * The attack vector is:
+     * ```
+     * process.mainModule.require('child_process').execSync('whoami')
+     * process.mainModule.constructor._load('vm')
+     * ```
+     *
+     * process.mainModule may be undefined in ESM contexts but could exist in
+     * CommonJS workers. We block both reading and setting.
+     */
+    private protectProcessMainModule;
+    /**
+     * Protect process.execPath from being read or set in sandbox context.
+     *
+     * process.execPath is a string primitive (not an object), so it cannot be
+     * proxied via the normal blocked globals mechanism. We use Object.defineProperty
+     * with getter/setter (same pattern as protectProcessMainModule).
+     */
+    private protectProcessExecPath;
+    /**
+     * Lock well-known Symbol properties on built-in constructors/prototypes.
+     *
+     * Instead of freezing entire prototypes (which breaks Node.js internals),
+     * we make specific Symbol properties non-configurable so they can't be
+     * replaced. This prevents:
+     * - Symbol.species hijacking (controls .map/.filter/.slice return types)
+     * - Symbol.iterator hijacking (controls for...of and spread)
+     * - Symbol.toPrimitive hijacking (controls type coercion)
+     */
+    private lockWellKnownSymbols;
+    /**
+     * Block Proxy.revocable to prevent bypassing Proxy constructor blocking.
+     *
+     * Proxy.revocable internally uses the real Proxy constructor, so it bypasses
+     * our blocking proxy on globalThis.Proxy. We replace it with a wrapper that
+     * checks the sandbox context before delegating to the original.
+     */
+    private protectProxyRevocable;
+    /**
+     * Block dynamic import() escape vectors via ESM loader hooks.
+     *
+     * Uses Node.js module.registerHooks() (23.5+, synchronous) to install ESM
+     * loader hooks that reject dangerous specifiers.
+     *
+     * registerHooks() runs in-thread and can read AsyncLocalStorage. We use it
+     * to block Node.js builtin specifiers (node:* and bare builtins) only in
+     * untrusted sandbox context while still allowing trusted infrastructure
+     * imports (runTrusted/runTrustedAsync).
+     *
+     * module.register() is deliberately not used as a fallback: those hooks run
+     * in a separate loader thread and cannot read AsyncLocalStorage.
+     *
+     * This is process-wide and permanent (hooks cannot be unregistered).
+     * Only applied once per process regardless of how many DefenseInDepthBox
+     * instances are created.
+     *
+     * Combined with Module._resolveFilename blocking (file-based specifiers),
+     * this closes the import() escape vector except for specifiers that bypass
+     * both the ESM loader and CJS resolution (none known).
+     */
+    private protectDynamicImport;
+    /**
+     * Protect Module._load from being called in sandbox context.
+     *
+     * The attack vector is:
+     * ```
+     * module.constructor._load('child_process')
+     * require.main.constructor._load('vm')
+     * ```
+     *
+     * We access the Module class and replace _load with a blocking proxy.
+     */
+    private protectModuleLoad;
+    /**
+     * Protect Module._resolveFilename from being called in sandbox context.
+     *
+     * Module._resolveFilename is called for both require() and import() resolution.
+     * Blocking it catches file-based import() specifiers:
+     *   import('./malicious.js')  // _resolveFilename is called to resolve the path
+     *
+     * data: and blob: URLs are handled separately by protectDynamicImport()
+     * via ESM loader hooks.
+     */
+    private protectModuleResolveFilename;
+    private protectModuleMethod;
+    /**
+     * Apply a single patch to a blocked global.
+     */
+    private applyPatch;
+    /**
+     * Restore all original values.
+     */
+    private restorePatches;
+}

package/dist/security/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Security Module - Defense-in-Depth Box
+ *
+ * This module provides a secondary defense layer that monkey-patches
+ * dangerous JavaScript globals during bash script execution.
+ *
+ * IMPORTANT: This is a SECONDARY defense layer. It should never be relied upon
+ * as the primary security mechanism. The primary security comes from proper
+ * sandboxing, input validation, and architectural constraints.
+ *
+ * Usage:
+ * ```typescript
+ * import { Bash } from 'just-bash';
+ *
+ * // Capability-detect defense-in-depth (the Bash default)
+ * const bash = new Bash({
+ *   defenseInDepth: { enabled: "auto" },
+ * });
+ *
+ * // Or with custom configuration
+ * const bash = new Bash({
+ *   defenseInDepth: {
+ *     enabled: true,
+ *     auditMode: false,
+ *     onViolation: (v) => console.warn('Violation:', v),
+ *   },
+ * });
+ * ```
+ */
+export { DefenseInDepthBox, SecurityViolationError, } from "./defense-in-depth-box.js";
+export { createConsoleViolationCallback, SecurityViolationLogger, type SecurityViolationLoggerOptions, type ViolationSummary, } from "./security-violation-logger.js";
+export type { DefenseInDepthConfig, DefenseInDepthHandle, DefenseInDepthStats, DefenseInDepthStatus, SecurityViolation, SecurityViolationType, } from "./types.js";
+export { WorkerDefenseInDepth, type WorkerDefenseStats, } from "./worker-defense-in-depth.js";

package/dist/security/safe-timestamp.d.ts

@@ -0,0 +1 @@
+export declare function getSafeTimestamp(): number;

package/dist/security/security-violation-logger.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Security Violation Logger
+ *
+ * Utility for tracking and reporting security violations from the
+ * defense-in-depth box. Useful for monitoring, alerting, and debugging.
+ *
+ * IMPORTANT: This is for monitoring a SECONDARY defense layer.
+ * Violations indicate potential escape attempts but the primary
+ * security should prevent these from being exploitable.
+ */
+import type { SecurityViolation, SecurityViolationType } from "./types.js";
+/**
+ * Options for the security violation logger.
+ */
+export interface SecurityViolationLoggerOptions {
+    /**
+     * Maximum number of violations to store per type.
+     * Default: 100
+     */
+    maxViolationsPerType?: number;
+    /**
+     * Maximum total violations to retain across all types.
+     * Oldest violations are dropped when this limit is reached.
+     * Default: 1000
+     */
+    maxViolationsTotal?: number;
+    /**
+     * Whether to include stack traces in logged violations.
+     * Default: true
+     */
+    includeStackTraces?: boolean;
+    /**
+     * Custom handler called for each violation.
+     */
+    onViolation?: (violation: SecurityViolation) => void;
+    /**
+     * Whether to log violations to console (for debugging).
+     * Default: false
+     */
+    logToConsole?: boolean;
+}
+/**
+ * Summary of violations by type.
+ */
+export interface ViolationSummary {
+    type: SecurityViolationType;
+    count: number;
+    firstSeen: number;
+    lastSeen: number;
+    paths: string[];
+}
+/**
+ * Security Violation Logger
+ *
+ * Collects and summarizes security violations for analysis.
+ */
+export declare class SecurityViolationLogger {
+    private violations;
+    private violationsByType;
+    private options;
+    constructor(options?: SecurityViolationLoggerOptions);
+    /**
+     * Record a security violation.
+     * This method is designed to be passed as the onViolation callback.
+     */
+    record(violation: SecurityViolation): void;
+    /**
+     * Get all recorded violations.
+     */
+    getViolations(): SecurityViolation[];
+    /**
+     * Get violations of a specific type.
+     */
+    getViolationsByType(type: SecurityViolationType): SecurityViolation[];
+    /**
+     * Get a summary of all violations by type.
+     */
+    getSummary(): ViolationSummary[];
+    /**
+     * Get total violation count.
+     */
+    getTotalCount(): number;
+    /**
+     * Check if any violations have been recorded.
+     */
+    hasViolations(): boolean;
+    /**
+     * Clear all recorded violations.
+     */
+    clear(): void;
+    /**
+     * Create a callback function suitable for DefenseInDepthConfig.onViolation.
+     */
+    createCallback(): (violation: SecurityViolation) => void;
+}
+/**
+ * Create a simple violation callback that logs to console.
+ */
+export declare function createConsoleViolationCallback(): (violation: SecurityViolation) => void;

package/dist/security/trusted-globals.d.ts

@@ -0,0 +1,17 @@
+/**
+ * SECURITY: Pre-captured references to dangerous globals.
+ *
+ * These are captured at module load time (before defense-in-depth patches)
+ * so that just-bash infrastructure can use them. They bypass all defense
+ * protections.
+ *
+ * DO NOT import these from command implementations unless absolutely
+ * necessary (e.g., Python WASM worker IPC). Any import from this module
+ * should be reviewed for security implications.
+ */
+export declare const _SharedArrayBuffer: typeof globalThis.SharedArrayBuffer;
+export declare const _Atomics: typeof globalThis.Atomics;
+export declare const _performanceNow: () => number;
+export declare const _Headers: typeof globalThis.Headers;
+/** Internal capability revocation; never expose this constructor to commands. */
+export declare const _Proxy: ProxyConstructor;