@jerryan/just-bash 3.5.0

package/dist/security/types.d.ts

@@ -0,0 +1,151 @@
+/**
+ * Security Types for Defense-in-Depth Box
+ *
+ * These types define the configuration and behavior of the defense-in-depth
+ * security layer that protects against code execution escape vectors.
+ *
+ * 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.
+ */
+/**
+ * Configuration for the defense-in-depth box.
+ */
+export interface DefenseInDepthConfig {
+    /**
+     * Enable, disable, or capability-detect the defense layer.
+     *
+     * `true` (the default used by `Bash`) and `"auto"` both enable the strongest
+     * protection supported by the current runtime. Inspect `getStatus()` when a
+     * host requires the full contextual dynamic-import boundary.
+     */
+    enabled?: boolean | "auto";
+    /**
+     * Permanently freeze selected host intrinsics and lock well-known Symbol
+     * descriptors. This cannot be undone by `deactivate()` and is therefore
+     * disabled by default. Only use in a dedicated, process-lifetime realm.
+     */
+    processLifetimeIntrinsicHardening?: boolean;
+    /**
+     * Audit mode: log violations but don't block them.
+     * Useful for debugging and testing without breaking execution.
+     * Default: false
+     */
+    auditMode?: boolean;
+    /**
+     * Callback invoked when a security violation is detected.
+     * Called regardless of auditMode setting.
+     */
+    onViolation?: (violation: SecurityViolation) => void;
+    /**
+     * Violation types to exclude from blocking.
+     * Use this when certain globals are required for legitimate purposes
+     * (e.g., WebAssembly for sql.js in sqlite3 worker).
+     * Constructor-execution protections are non-excludable.
+     */
+    excludeViolationTypes?: SecurityViolationType[];
+}
+export interface DefenseInDepthStatus {
+    requested: "auto" | "enabled" | "disabled";
+    state: "enabled" | "unsupported" | "disabled";
+    /**
+     * Overall effective enforcement strength without changing the legacy
+     * `state` contract. Audit mode always reports `"none"` because it records
+     * violations without blocking them.
+     */
+    level: "full" | "best-effort" | "none";
+    contextualDynamicImportProtection: boolean;
+    processLifetimeIntrinsicHardening: boolean;
+    /**
+     * Scoped gates are reversible but cannot revoke mutation functions or
+     * intrinsic references cached before activation. Complete protection
+     * requires the explicitly irreversible process-lifetime mode or isolation.
+     */
+    intrinsicProtection: "scoped-best-effort" | "process-lifetime";
+    reason?: string;
+}
+/**
+ * Types of security violations that can be detected.
+ */
+/**
+ * Types of security violations that can be detected.
+ *
+ * Note: We focus on code execution vectors. We don't block:
+ * - process: Needed for Node.js operation (process.nextTick, etc.)
+ * - require: May not exist in ESM, and import() can't be blocked this way
+ */
+export type SecurityViolationType = "function_constructor" | "eval" | "setTimeout" | "setInterval" | "setImmediate" | "async_function_constructor" | "generator_function_constructor" | "async_generator_function_constructor" | "weak_ref" | "finalization_registry" | "reflect" | "proxy" | "process_env" | "process_binding" | "process_dlopen" | "process_main_module" | "process_exit" | "process_kill" | "process_setuid" | "process_umask" | "process_argv" | "process_exec_path" | "process_chdir" | "process_connected" | "process_send" | "process_channel" | "process_timing" | "module_load" | "webassembly" | "shared_array_buffer" | "atomics" | "process_get_builtin_module" | "error_prepare_stack_trace" | "performance_timing" | "process_stdout" | "process_stderr" | "module_resolve_filename" | "dynamic_import_builtin" | "missing_defense_context" | "promise_then_after_deactivate" | "bound_callback_after_deactivate" | "prototype_mutation" | "json_mutation" | "math_mutation" | "process_report" | "process_exception_handler";
+/**
+ * Information about a detected security violation.
+ */
+export interface SecurityViolation {
+    /**
+     * Timestamp when the violation occurred (milliseconds since epoch).
+     */
+    timestamp: number;
+    /**
+     * Type of violation detected.
+     */
+    type: SecurityViolationType;
+    /**
+     * Human-readable message describing the violation.
+     */
+    message: string;
+    /**
+     * Path to the blocked global (e.g., "globalThis.Function").
+     */
+    path: string;
+    /**
+     * Stack trace at the point of violation, if available.
+     */
+    stack?: string;
+    /**
+     * Execution ID from AsyncLocalStorage context, for correlation.
+     */
+    executionId?: string;
+}
+/**
+ * Statistics about defense-in-depth box activity.
+ */
+export interface DefenseInDepthStats {
+    /**
+     * Total number of violations blocked.
+     */
+    violationsBlocked: number;
+    /**
+     * List of all violations detected (capped to prevent memory issues).
+     */
+    violations: SecurityViolation[];
+    /**
+     * Total time the defense layer has been active in milliseconds.
+     */
+    activeTimeMs: number;
+    /**
+     * Current reference count (number of nested activations).
+     */
+    refCount: number;
+}
+/**
+ * Handle returned by activate() for scoped execution.
+ * Use the run() method to execute code within the protected context.
+ */
+export interface DefenseInDepthHandle {
+    /**
+     * Run code within the protected AsyncLocalStorage context.
+     * All async descendants of the provided function will be tracked.
+     *
+     * @param fn - Async function to execute in the protected context
+     * @returns Promise resolving to the function's return value
+     */
+    run: <T>(fn: () => Promise<T>) => Promise<T>;
+    /**
+     * Deactivate the defense layer. Must be called in a finally block.
+     * Decrements ref count; patches are restored when count hits 0.
+     */
+    deactivate: () => void;
+    /**
+     * Unique identifier for this execution context.
+     * Useful for correlating violations with specific exec() calls.
+     */
+    executionId: string;
+}

package/dist/security/violation-error-message.d.ts

@@ -0,0 +1,3 @@
+import type { SecurityViolationType } from "./types.js";
+export declare function assertExcludableViolationTypes(violationTypes: readonly SecurityViolationType[] | undefined): void;
+export declare function formatViolationErrorMessage(message: string, violationType: SecurityViolationType, canExclude: boolean): string;

package/dist/security/wasm-callback.d.ts

@@ -0,0 +1,6 @@
+export declare function sanitizeUnknownError(error: unknown): string;
+/**
+ * Wrap WASM-to-JS callbacks so callback failures are surfaced as sanitized
+ * internal errors without leaking host/internal paths.
+ */
+export declare function wrapWasmCallback<TArgs extends unknown[], TResult>(component: string, phase: string, callback: (...args: TArgs) => TResult): (...args: TArgs) => TResult;

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

@@ -0,0 +1,228 @@
+/**
+ * Worker Defense-in-Depth
+ *
+ * A simplified version of DefenseInDepthBox designed for use in Worker threads.
+ * Since workers have their own isolated V8 context, we don't need AsyncLocalStorage
+ * to track execution context - the entire worker IS the sandboxed context.
+ *
+ * Key differences from DefenseInDepthBox:
+ * - No AsyncLocalStorage (always blocks, no context tracking needed)
+ * - Single activation model (apply patches once at worker startup)
+ * - Violations reported via callback (typically postMessage to parent)
+ *
+ * Usage in a worker:
+ * ```typescript
+ * import { parentPort } from 'node:worker_threads';
+ * import { WorkerDefenseInDepth } from '../security/worker-defense-in-depth.js';
+ *
+ * // Apply patches at worker startup
+ * const defense = new WorkerDefenseInDepth({
+ *   onViolation: (v) => parentPort?.postMessage({ type: 'security-violation', violation: v }),
+ * });
+ *
+ * // All code in the worker is now protected
+ * // Attempting Function, eval, etc. will throw SecurityViolationError
+ * ```
+ *
+ * Constructor Protection:
+ * Function.prototype.constructor returns a proxy that allows property reads
+ * (e.g., `.constructor.name` for type introspection) but blocks invocation
+ * (e.g., `.constructor("code")` for dynamic code 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.
+ *
+ * Dynamic import() mitigation (three layers):
+ * 1. Module._resolveFilename blocked — catches file-based specifiers
+ * 2. Main-thread ESM loader hooks block data:/blob: URLs (not in workers)
+ * 3. Filesystem restrictions — OverlayFs writes to memory only
+ *
+ * Note: ESM loader hooks are registered by DefenseInDepthBox in the main
+ * thread. Workers inherit the hooks automatically. Worker-level registration
+ * is not needed (and would require require('node:module') which is blocked).
+ */
+import type { DefenseInDepthConfig, SecurityViolation } from "./types.js";
+/**
+ * Error thrown when a security violation is detected.
+ */
+export declare class WorkerSecurityViolationError extends Error {
+    readonly violation: SecurityViolation;
+    constructor(message: string, violation: SecurityViolation);
+}
+/**
+ * Statistics about the worker defense layer.
+ */
+export interface WorkerDefenseStats {
+    /** Total number of violations detected */
+    violationsBlocked: number;
+    /** List of all violations detected (capped to prevent memory issues) */
+    violations: SecurityViolation[];
+    /** Whether patches are currently active */
+    isActive: boolean;
+}
+/**
+ * Worker Defense-in-Depth
+ *
+ * Applies security patches to dangerous JavaScript globals in a worker context.
+ * Unlike DefenseInDepthBox, this is designed for workers where the entire
+ * execution context is sandboxed.
+ */
+export declare class WorkerDefenseInDepth {
+    private config;
+    private isActivated;
+    private originalDescriptors;
+    private patchFailures;
+    private violations;
+    private executionId;
+    /**
+     * Original Proxy constructor, captured before patching.
+     * This is captured at instance creation time to ensure we get the unpatched version.
+     */
+    private originalProxy;
+    /**
+     * Recursion guard to prevent infinite loops when proxy traps trigger
+     * code that accesses the same proxied object (e.g., process.env).
+     */
+    private inTrap;
+    /**
+     * Create and activate the worker defense layer.
+     *
+     * @param config - Configuration for the defense layer
+     */
+    constructor(config: DefenseInDepthConfig);
+    /**
+     * Get statistics about the defense layer.
+     */
+    getStats(): WorkerDefenseStats;
+    /**
+     * Clear stored violations. Useful for testing.
+     */
+    clearViolations(): void;
+    /**
+     * Get the execution ID for this worker.
+     */
+    getExecutionId(): string;
+    /**
+     * Deactivate the defense layer and restore original globals.
+     * Typically only needed for testing.
+     */
+    deactivate(): void;
+    /**
+     * Activate the defense layer by applying patches.
+     */
+    private activate;
+    /**
+     * Get a human-readable path for a target object and property.
+     */
+    private getPathForTarget;
+    /**
+     * Record a violation and invoke the callback.
+     * In worker context, blocking always happens (no audit mode context check).
+     */
+    private recordViolation;
+    /**
+     * Create a blocking proxy for a function.
+     * In worker context, always blocks (no context check needed).
+     */
+    private createBlockingProxy;
+    /**
+     * Create a blocking proxy for an object (blocks all property access).
+     */
+    private createBlockingObjectProxy;
+    private createReadonlyObjectProxy;
+    /**
+     * Apply security patches to dangerous globals.
+     */
+    private applyPatches;
+    /**
+     * Lock well-known Symbol properties on built-in constructors/prototypes.
+     */
+    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
+     * always blocks in worker context.
+     */
+    private protectProxyRevocable;
+    /**
+     * Protect against .constructor.constructor escape vector.
+     * @param excludeTypes - Set of violation types to skip
+     */
+    private protectConstructorChain;
+    /**
+     * Protect Error.prepareStackTrace from being set.
+     */
+    private protectErrorPrepareStackTrace;
+    /**
+     * Patch a prototype's constructor property.
+     *
+     * Returns a proxy that allows reading properties (like .name) but blocks
+     * calling the constructor as a function (which would allow code execution).
+     */
+    private patchPrototypeConstructor;
+    /**
+     * Protect process.mainModule from being accessed or set.
+     *
+     * 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 worker 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;
+    /**
+     * Protect process.connected from being read or set in worker context.
+     *
+     * process.connected is a boolean 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 protectProcessExecPath).
+     *
+     * Only protects if process.connected exists (IPC contexts).
+     */
+    private protectProcessConnected;
+    /**
+     * Protect Module._load from being called.
+     *
+     * 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 worker context.
+     *
+     * Module._resolveFilename is called for both require() and import() resolution.
+     * Blocking it catches file-based import() specifiers.
+     *
+     * data: and blob: URLs are handled by ESM loader hooks registered
+     * in the main thread (DefenseInDepthBox.protectDynamicImport).
+     */
+    private protectModuleResolveFilename;
+    private protectModuleMethod;
+    /**
+     * Apply a single patch to a blocked global.
+     */
+    private applyPatch;
+    /**
+     * Restore all original values.
+     */
+    private restorePatches;
+}

package/dist/shell-metadata.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Shell Metadata
+ *
+ * Shared source of truth for shell version and process information.
+ * Used by both variable expansion ($BASH_VERSION, $PPID, etc.)
+ * and /proc filesystem initialization.
+ */
+/**
+ * Simulated bash version string
+ */
+export declare const BASH_VERSION = "5.1.0(1)-release";
+/**
+ * Simulated kernel version for /proc/version
+ */
+export declare const KERNEL_VERSION = "Linux version 5.15.0-generic (just-bash) #1 SMP PREEMPT";
+/**
+ * Format /proc/self/status content using virtual process info.
+ * Never exposes real host process information.
+ */
+export declare function formatProcStatus(info: {
+    pid: number;
+    ppid: number;
+    uid: number;
+    gid: number;
+}): string;

package/dist/source-limit.d.ts

@@ -0,0 +1,2 @@
+/** Reject source before normalization or parsing can duplicate it. */
+export declare function assertSourceWithinLimit(source: string, maxSourceBytes: number): void;

package/dist/timers.d.ts

@@ -0,0 +1,16 @@
+export declare const _setTimeout: typeof globalThis.setTimeout;
+export declare const _clearTimeout: typeof globalThis.clearTimeout;
+export interface FiniteTimeoutHandle {
+    cleared: boolean;
+    remainingMs: number;
+    timer: ReturnType<typeof globalThis.setTimeout> | undefined;
+}
+/**
+ * Schedule a configured deadline without overflowing the host timer. Positive
+ * Infinity means no deadline; longer finite delays are advanced in native-safe
+ * chunks so they retain their actual duration.
+ */
+export declare function _setTimeoutIfFinite(callback: Parameters<typeof globalThis.setTimeout>[0], delay: number): FiniteTimeoutHandle | undefined;
+export declare function _clearFiniteTimeout(handle: FiniteTimeoutHandle | undefined): void;
+export declare const _setInterval: typeof globalThis.setInterval;
+export declare const _clearInterval: typeof globalThis.clearInterval;

package/dist/transform/pipeline.d.ts

@@ -0,0 +1,8 @@
+import type { BashTransformResult, TransformPlugin } from "./types.js";
+export declare class BashTransformPipeline<TMetadata extends object = Record<string, never>> {
+    private readonly maxSourceBytes;
+    private plugins;
+    constructor(maxSourceBytes?: number);
+    use<M extends object>(plugin: TransformPlugin<M>): BashTransformPipeline<TMetadata & M>;
+    transform(script: string): BashTransformResult<TMetadata>;
+}

package/dist/transform/plugins/command-collector.d.ts

@@ -0,0 +1,8 @@
+import type { TransformContext, TransformPlugin, TransformResult } from "../types.js";
+export interface CommandCollectorMetadata {
+    commands: string[];
+}
+export declare class CommandCollectorPlugin implements TransformPlugin<CommandCollectorMetadata> {
+    readonly name = "command-collector";
+    transform(context: TransformContext): TransformResult<CommandCollectorMetadata>;
+}

package/dist/transform/plugins/tee-plugin.d.ts

@@ -0,0 +1,40 @@
+import type { TransformContext, TransformPlugin, TransformResult } from "../types.js";
+export interface TeePluginOptions {
+    outputDir: string;
+    targetCommandPattern?: {
+        test(input: string): boolean;
+    };
+    timestamp?: Date;
+}
+export interface TeeFileInfo {
+    commandIndex: number;
+    commandName: string;
+    /** The full command string (name + arguments) before tee wrapping */
+    command: string;
+    stdoutFile: string;
+}
+export interface TeePluginMetadata {
+    teeFiles: TeeFileInfo[];
+}
+export declare class TeePlugin implements TransformPlugin<TeePluginMetadata> {
+    readonly name = "tee";
+    private options;
+    private counter;
+    constructor(options: TeePluginOptions);
+    transform(context: TransformContext): TransformResult<TeePluginMetadata>;
+    private formatTimestamp;
+    private generateStdoutPath;
+    private encodeCommandName;
+    private transformScript;
+    private transformStatement;
+    private transformPipeline;
+    /**
+     * Restore PIPESTATUS and exit code without user-visible variables.
+     * Produces: `builtin __just_bash_tee_restore ${PIPESTATUS[i]} ...`
+     */
+    private makePipestatusRestore;
+    private shouldTarget;
+    private getCommandName;
+    private serializeCommand;
+    private makeTeeCommand;
+}

package/dist/transform/serialize.d.ts

@@ -0,0 +1,4 @@
+import type { ScriptNode, WordNode } from "../ast/types.js";
+export declare function serialize(node: ScriptNode): string;
+export { serializeWord };
+declare function serializeWord(node: WordNode): string;

package/dist/transform/types.d.ts

@@ -0,0 +1,18 @@
+import type { ScriptNode } from "../ast/types.js";
+export interface TransformPlugin<TMetadata extends object = Record<string, unknown>> {
+    name: string;
+    transform(context: TransformContext): TransformResult<TMetadata>;
+}
+export interface TransformContext {
+    ast: ScriptNode;
+    metadata: Record<string, unknown>;
+}
+export interface TransformResult<TMetadata extends object = Record<string, unknown>> {
+    ast: ScriptNode;
+    metadata?: TMetadata;
+}
+export interface BashTransformResult<TMetadata extends object = Record<string, unknown>> {
+    script: string;
+    ast: ScriptNode;
+    metadata: TMetadata;
+}