Error codes

(no submodules)

Purpose

This module owns the stable SAND_VM.* error-code registry used by every public failure path inside the @suaveplan/api-sandbox-vm package. The registry is built once via defineCodes("SAND_VM", […]) so the namespace prefix and per-code suffix are co-derived — that guarantee lets the host's lifecycle driver, the audit sink, and the conformance harness branch on literal code strings without ever decoding free-form error messages.

Side-effect-importing this module from src/index.ts ensures every consumer that imports the package barrel (or any subpath export) participates in the same code registration, which is what scripts/conformance.ts validates.

Features

Five stable codes (EVAL_REJECTED, INDIRECT_EVAL_REJECTED, MODULE_IMPORT_FORBIDDEN, SOURCE_TEXT_MODULE_FAILED, PERMISSION_DENIED) — every failure surface in the package maps to exactly one.
A typed SandboxVmError subclass of SuaveplanError so consumers may discriminate via instanceof or by code string.
Wire-stable code string: the namespaced form (e.g. "SAND_VM.EVAL_REJECTED") is the value used in OTel attributes, audit logs, and IPC envelopes back to the host.

Usage: Basic

import {
    SAND_VM_CODES,
    SandboxVmError,
} from "@suaveplan/api-sandbox-vm/error-codes/error-codes";

throw new SandboxVmError(
    SAND_VM_CODES.EVAL_REJECTED,
    "dynamic code evaluation is disabled in the vm sandbox"
);

Usage: Advanced

Use the context option to attach a redaction-safe payload that flows through to OTel span attributes and the lifecycle driver's crash report:

import {
    SAND_VM_CODES,
    SandboxVmError,
} from "@suaveplan/api-sandbox-vm/error-codes/error-codes";

function denyOutboundFetch(host: string, reason: string): never {
    throw new SandboxVmError(
        SAND_VM_CODES.PERMISSION_DENIED,
        `outbound HTTP to ${host} denied by policy`,
        {
            context: { capability: "fetch", host, reason },
        }
    );
}

API Reference

SAND_VM_CODES — frozen record mapping enum key (e.g. EVAL_REJECTED) to the namespaced string code ("SAND_VM.EVAL_REJECTED").
type SandboxVmCode — the literal union of every value in SAND_VM_CODES.
class SandboxVmError extends SuaveplanError<SandboxVmCode> — constructor takes (code, message, options?). options.context is forwarded through the base class redaction pipeline.

Implementation Notes

The registry is declared as const so the compiler retains literal types (essential for exhaustive switch narrowing in consumers). The class sets this.name = "SandboxVmError" so heap snapshots, sourcemaps and uncaught-exception handlers attribute failures to this package rather than the generic SuaveplanError super-class. Registry ordering reflects severity in roughly increasing order — the first two entries reflect deliberate plugin policy violations, the next two reflect host-environment misconfiguration, and the last reflects permission-policy denials that fan in from api-sandbox-permissions.

3.1 KiB Raw Blame History