Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

9.3 KB
Raw Blame
/**
 * The sandbox vocabulary a plugin compiles against — types only.
 *
 * It lives in core, alongside the rest of the plugin contract, because a backend is
 * written against these names and nothing else: a package implementing {@link
 * SandboxProvider} needs the policy it is handed and the argv it must return, not the
 * harness that routes them. The routing itself (which policy goes to which backend, and
 * the settings behind it) is the embedder's, and stays there.
 *
 * Confinement is argv rewriting and nothing else: a provider returns the argv the caller
 * should spawn instead of its own, and never executes anything itself.
 *
 * Nothing here emits runtime code. The helpers that read these shapes
 * (`SANDBOX_DIMENSIONS`, `providerDimensions`, `requestedDimensions`) are the embedder's
 * and live in the server package, so a plugin carries no runtime dependency on core.
 * A backend reaches the harness by contributing to the `sandbox.providers` slot (see
 * the sandbox module's iface.ts in the server package).
 */

/**
 * File-effect mode. `read-only` permits only required sinks (e.g. /dev/null);
 * `workspace-write` also permits the workspace and a backend-defined temp area;
 * `danger-full-access` means confinement is off and no provider is consulted.
 */
export type SandboxMode = "read-only" | "workspace-write" | "danger-full-access";

/** A mode that actually confines — the modes a {@link SandboxPolicy} can carry. */
export type ConfinedSandboxMode = Exclude<SandboxMode, "danger-full-access">;

/**
 * The isolation dimensions of this interface. A provider declares the subset it
 * implements; `fs-write` is the floor every confining backend covers, while `network`
 * and `mask-paths` are optional implementations (see {@link SandboxProvider.dimensions}).
 * `network-local` is the local network level: only the host's localhost is reachable. It is
 * its own dimension because a backend that can cut the network cannot necessarily keep the
 * host's loopback while cutting the rest. `closed-temp` is withholding the temporary directory
 * when a policy does not grant it ({@link SandboxPolicy.writableTemp}): a backend whose temp
 * area is always writable (the DSH adaptor, which grants the host's /tmp under
 * `workspace-write`) does not declare it, and a policy closing temp is never routed to it.
 */
export type SandboxDimension =
  "fs-write" | "network" | "network-local" | "mask-paths" | "closed-temp";

/**
 * The network levels, narrowest first: `none` = no network at all, `local` = only the host's
 * localhost, absent = unrestricted.
 */
export type SandboxNetwork = "none" | "local";

/**
 * What one confined execution is allowed to touch — carried PER CALL, not fixed on the
 * provider. The optional members are the optional dimensions: present means the policy
 * REQUIRES that dimension, and the service only routes such a policy to a provider that
 * implements it (never silently dropped).
 */
export interface SandboxPolicy {
  /**
   * The file-effect mode this execution runs under (`fs-write`). A provider is normally
   * consulted only for a confining mode; it is handed `danger-full-access` ONLY when the
   * policy still requires another dimension (a network cut, a masked path). Then it must
   * leave the filesystem unrestricted while enforcing that other dimension — "everything
   * writable, but no network" is a real, expressible policy.
   */
  mode: SandboxMode;
  /** Absolute root directory `workspace-write` may write under. */
  workspaceRoot: string;
  /**
   * Further absolute directories `workspace-write` may write under, beside the workspace:
   * the Session's scratchpad, where the plan file, a goal's state file and the
   * attachments live. The service sets it only under `workspace-write`. A backend that
   * does not implement the field confines more narrowly than asked, never more widely, so
   * no dimension guards it.
   *
   * Each root EXISTS on the host by the time a backend is handed the policy: the service
   * creates it first (the scratchpad is made lazily, and can be removed mid-Session), and
   * refuses the spawn when it cannot. A backend neither creates a root nor skips a missing
   * one. `workspaceRoot` is not covered: a missing Workspace is a different error, and
   * surfaces as such.
   */
  writableRoots?: readonly string[];
  /**
   * `network`: "none" = the confined process gets no network at all (dimension `network`);
   * "local" = it reaches the host's localhost and nothing else (dimension `network-local`).
   */
  network?: SandboxNetwork;
  /** `mask-paths`: absolute paths hidden from the confined process, reads included. */
  maskPaths?: readonly string[];
  /**
   * The system temporary directory is writable, in either confining mode: shells and most
   * tools need somewhere to write before they run anything. Absent = not granted — which the
   * service hands only to a backend declaring `closed-temp`.
   */
  writableTemp?: boolean;
}

/**
 * Enforcement completeness for this host. `partial` means the backend or an older
 * kernel ABI cannot govern every promised effect; a caller requiring an absolute
 * boundary must not treat it as `full`. Reported as fact, never requested.
 */
export type SandboxEnforcement = "full" | "partial";

/**
 * Evidence identifying a runner that failed BEFORE executing the wrapped command.
 * A consumer applies `allowedExitCodes` when present, drops `informationalLines` by
 * exact line equality, then matches `fatalSignatures` case-insensitively per remaining
 * stderr line. Exit status alone never proves runner failure.
 */
export interface RunnerFailureRule {
  allowedExitCodes?: readonly number[];
  fatalSignatures: readonly string[];
  informationalLines?: readonly string[];
}

/** The result of confining one argv. */
export interface ConfinedArgv {
  /** The wrapped argv (runner, profile, separator, then the caller's argv). */
  argv: string[];
  /** How completely the backend enforces this policy here. */
  enforcement: SandboxEnforcement;
  /**
   * The backend's denial DIALECT: the case-insensitive stderr substrings a denied
   * effect produces under THIS backend. A consumer inferring denials matches these
   * rather than a cross-backend union, which would claim denials a backend never emits.
   */
  denialSignatures: readonly string[];
  /** Structured runner-failure evidence (see {@link RunnerFailureRule}). */
  runnerFailureRules: readonly RunnerFailureRule[];
  /**
   * Environment entries the RUNNER needs, laid over the command's own environment at
   * spawn. A runner that is a script has to tell its interpreter how to behave — the
   * desktop app's own binary runs a script only under `ELECTRON_RUN_AS_NODE`, and
   * nothing in an argv can say so. These describe the runner, not the command: a runner
   * that hands the environment on keeps them from the command it confines.
   */
  env?: Readonly<Record<string, string>>;
}

/**
 * A sandbox backend. `confine` must return enforcing argv or THROW — returning the
 * original argv unconfined is forbidden, which is what makes the whole capability
 * fail-closed.
 */
export interface SandboxProvider {
  /**
   * The dimensions this backend implements. Absent = `["fs-write"]`: a backend that
   * says nothing governs file writes only, which is the honest default and exactly
   * what a stock DSH backend is. The service routes by this declaration, so an
   * unimplemented dimension can never be silently ignored.
   */
  readonly dimensions?: readonly SandboxDimension[];
  /**
   * What enforces the confinement on this host, as an administrator would name it
   * ("bubblewrap", "Landlock"). The settings card says what this machine enforces and by
   * what; absent, it names the backend instead.
   */
  readonly mechanism?: string;
  /**
   * What this backend leaves open on this host beyond the dimensions it does not declare —
   * a policy field it cannot honour in full, a kernel that enforces only part of it — in an
   * administrator's words. The settings card discloses them under what this machine enforces.
   */
  readonly limits?: readonly SandboxLimit[];
  confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv;
}

/** One limit of a backend on this host (see {@link SandboxProvider.limits}). */
export interface SandboxLimit {
  text: string;
  textZh?: string;
}

/** A provider, or a promise of one: backends load asynchronously (dynamic imports, probes). */
export type SandboxProviderLoad = SandboxProvider | PromiseLike<SandboxProvider | null> | null;

/**
 * What a backend binds: a load, or a loader that produces one. A loader is called at boot and
 * again after its failure whenever the sandbox's settings are saved — so a backend whose check
 * failed on a setting (a wrong program path) recovers once that setting is fixed, no restart.
 */
export type SandboxProviderSource = SandboxProviderLoad | (() => SandboxProviderLoad);

/**
 * The active confinement settings, resolved per spawn. A type literal with plain
 * arrays because it parks as Json in the platform context (see PlatformCtx.sandbox).
 */
export type SandboxSettings = {
  /** `danger-full-access` = confinement off; commands spawn exactly as before. */
  mode: SandboxMode;
  network?: SandboxNetwork;
  maskPaths?: string[];
  /** Grant the system temp directory writable (SandboxPolicy.writableTemp). Absent = granted. */
  writableTemp?: boolean;
};