@zenera/sandbox 1.1.58 → 1.2.0

package/README.md

@@ -10,8 +10,7 @@ import { podmanSandbox } from '@zenera/sandbox';
 
 const sandbox = podmanSandbox({ root: '/path/to/workspace', key: 'session-1' });
 await sandbox.exec('python -V');
-const view = sandbox.files({ root: '/path/to/workspace', mount: '/workspace' });
-await view.fs!.writeFile(`${view.root}/notes.md`, 'hello');
+await sandbox.fs.writeFile('/workspace/notes.md', 'hello'); // what `cat notes.md` sees
 await sandbox.close();
 ```
 
@@ -19,14 +18,18 @@ await sandbox.close();
 
 - **`Sandbox`** - `prepare` (pull the image, or build it from `build:`),
   `exec`, background jobs (`startJob`, `readJob`, `stopJob`),
-  `close` at the end of a turn, and the files: `fs` (an `FsDriver`) and
-  `files(view)`, which maps the host's workspace and mounts to the paths `fs`
-  finds them at. The invariant: **a file written through `fs` is the file
-  `exec` sees under the same name, and the reverse.**
+  `close` at the end of a turn, and the files: `fs`, an `FsDriver` in the
+  agent's own paths (`/workspace/a.py`) and contained to the sandbox's trees.
+  The invariant: **a file written through `fs` is the file `exec` sees under
+  the same name, and the reverse.**
 - **`SandboxFactory`** - `(opts: SandboxOptions) => Sandbox`, how a host picks
   where sandboxes run.
-- **`FsDriver`** - the filesystem seam, usable without a sandbox. `localFs` is
-  this machine's disk; `InMemoryFs` keeps a tree in memory.
+- **`FsDriver`** - the filesystem seam, usable without a sandbox. `RootedFs`
+  serves named trees from directories on this machine - `/workspace` from the
+  session's folder, `/assets` read-only - and is the one place a path is
+  contained: it must name a tree, its symlinks must resolve into one, and a
+  read-only tree refuses every change. `localFs` is this machine's disk as it
+  is; `InMemoryFs` keeps a tree in memory.
 
 ## The image
 
@@ -43,10 +46,26 @@ by name, across copies of this package).
 ## Implementations
 
 - **`PodmanSandbox`** / `podmanSandbox` - a podman container on this machine,
-  binding host directories, with `fs = localFs`. `ensurePodmanImage` is its
-  image step on its own.
+  binding host directories, with `fs` a `RootedFs` over them under the names
+  they are bound at. `ensurePodmanImage` is its image step on its own.
+- **`BwrapSandbox`** / `bwrapSandbox` - for a host that is itself the
+  container, such as the agent image: each command runs under bubblewrap
+  (`/opt/zenera/bin/bwrap`, else `bwrap` on PATH) in its own user, pid, ipc and
+  uts namespaces, on a read-only view of the image, with the session's
+  directories bound in and the server's own paths (`/state`, `/run/secrets`)
+  hidden. bwrap is started with exactly the command's environment, never this
+  process's: the image's `ENV` (`/opt/zenera/etc/image-env.json`, written when
+  the agent image is built; else `PATH`, `LANG`, `LC_*`, `TZ`) plus the run's.
+  `/proc` is the command's own where the container lets one be
+  mounted, else the container's bound read-only (`probeBwrap()` says which, or
+  why bwrap cannot isolate anything; nothing falls back to running unisolated).
+  `prepare()` builds nothing: it checks that the container was built from the
+  project's Dockerfile (`ZEN_IMAGE_BUILD`) or image (`ZEN_IMAGE_BASE`), when
+  it says what it was built from.
+  `cpus`, `memory` and `persist` belong to the container and are ignored;
+  commands get `oom_score_adj` 1000, so they go before the server.
 - A sandbox that keeps its files with the container (a sandbox service) serves
-  `fs` itself and returns `inSandboxPaths(view, fs)` from `files()`.
+  `fs` itself, under the same names.
 
 ## Testing an implementation
 

package/dist/bwrap.d.ts

@@ -0,0 +1,143 @@
+import { type Mount } from './mounts.ts';
+import { type Runner } from './process.ts';
+import { RootedFs } from './rooted-fs.ts';
+import { type BuildSpec, type ExecOptions, type ExecResult, type JobOutput, type JobStopped, type PrepareOptions, type Sandbox, type SandboxFactory, type SandboxHardening, type SandboxNetwork, type SandboxOptions } from './contract.ts';
+/** Where the agent image keeps its bwrap: a static build, so any base runs it. */
+export declare const ZENERA_BWRAP = "/opt/zenera/bin/bwrap";
+/**
+ * The project image's own environment (its Dockerfile's `ENV` lines), written by the agent
+ * image's build as a JSON object: what a command gets to start from, as it would in that image.
+ */
+export declare const IMAGE_ENV_FILE = "/opt/zenera/etc/image-env.json";
+/** Set by `zen image build`: what the image was built from. */
+export declare const IMAGE_BUILD_ENV = "ZEN_IMAGE_BUILD";
+export declare const IMAGE_BASE_ENV = "ZEN_IMAGE_BASE";
+/** `--proc`: a `/proc` of the command's own, or the container's, bound read-only. */
+export type ProcMode = 'fresh' | 'bind';
+export interface BwrapProbe {
+    ok: boolean;
+    /** the binary probed */
+    bwrap: string;
+    /** how `/proc` is given to commands, when `ok` */
+    proc?: ProcMode;
+    /** why not, when not `ok` */
+    error?: string;
+    hint?: string;
+}
+/** What a host can tell the sandbox about where it runs; the defaults are the agent image's. */
+export interface BwrapHost {
+    /** the bwrap binary; `/opt/zenera/bin/bwrap`, else `bwrap` on PATH */
+    bwrap?: string;
+    /** where the base environment and secrets are read from; `process.env` */
+    env?: NodeJS.ProcessEnv;
+    /** more paths no command sees, besides `/state` and `/run/secrets` (always hidden) */
+    hidden?: readonly string[];
+    /**
+     * What this image was built from, which `prepare` checks the spec against;
+     * from `ZEN_IMAGE_BUILD` / `ZEN_IMAGE_BASE` when unset. Neither known, or
+     * `false`: no check — the container is whatever its host made it.
+     */
+    image?: false | {
+        build?: string;
+        base?: string;
+    };
+    /**
+     * What a command's environment starts from: the image's own `ENV` (IMAGE_ENV_FILE, when the
+     * container has it), else PATH, LANG, LC_* and TZ of this process. Never the rest of it.
+     */
+    imageEnv?: Record<string, string>;
+    /** how processes are spawned — the seam tests replace */
+    exec?: Runner;
+    /** the host's filesystem as the root is built from it — the seam tests replace */
+    tree?: HostTree;
+}
+/** The host's filesystem, as far as building a command's root needs it. */
+export interface HostTree {
+    kind(path: string): 'dir' | 'file' | 'symlink' | 'missing';
+    list(path: string): string[];
+    link(path: string): string;
+}
+export declare const hostTree: HostTree;
+interface Resolved {
+    root: string;
+    key: string;
+    image: string;
+    build?: BuildSpec;
+    network: SandboxNetwork;
+    workdir: string;
+    timeout: number;
+    hardening: SandboxHardening;
+    user?: {
+        uid: string;
+        gid?: string;
+    };
+    env: Record<string, string>;
+    secrets: readonly string[];
+    readOnly: boolean;
+    mounts: readonly Mount[];
+    execEnv: Record<string, string>;
+    execPaths: Record<string, readonly string[]>;
+}
+export declare class BwrapSandbox implements Sandbox {
+    #private;
+    readonly name: string;
+    readonly fs: RootedFs;
+    readonly spec: Resolved;
+    constructor(opts: SandboxOptions, host?: BwrapHost);
+    get started(): boolean;
+    /** Checks that this container is the image the project describes; builds nothing. */
+    prepare(opts?: PrepareOptions): Promise<void>;
+    start(): Promise<void>;
+    exec(command: string, opts?: ExecOptions): Promise<ExecResult>;
+    /**
+     * Starts a command and returns. Its log is a file of this process's, outside
+     * the command's view; its exit code is the one bwrap reports.
+     */
+    startJob(command: string, opts?: ExecOptions): Promise<string>;
+    readJob(id: string, from?: number): Promise<JobOutput>;
+    /**
+     * Ends bwrap, and with it everything the job started: the command is the
+     * first process of a pid namespace, and a namespace whose first process
+     * dies takes the rest with it.
+     */
+    stopJob(id: string): Promise<JobStopped>;
+    /** Ends every command and job; the files stay where the mounts keep them. */
+    close(): Promise<void>;
+    /** A path inside the sandbox, contained to the working directory. */
+    inside(path?: string): string;
+}
+export declare const bwrapSandbox: SandboxFactory;
+export interface BwrapArgs {
+    tree: HostTree;
+    hidden: readonly string[];
+    /** shallowest first */
+    binds: readonly {
+        at: string;
+        host: string;
+        readOnly: boolean;
+    }[];
+    proc: ProcMode;
+    network: SandboxNetwork;
+    strict: boolean;
+    user?: {
+        uid: string;
+        gid?: string;
+    };
+    cwd: string;
+    /** more mounts, after `/tmp` exists */
+    extra?: readonly string[];
+    command: readonly string[];
+}
+export declare function bwrapArgs(a: BwrapArgs): string[];
+/**
+ * The host's root, bound piece by piece: `targets` are mounted later, `omit`
+ * is never shown. A directory is opened only for a mount point it lacks;
+ * whatever it holds is then bound entry by entry, so this stays rare — under
+ * SELinux a bind of something the runtime itself mounted can be refused.
+ */
+export declare function rootArgs(tree: HostTree, targets: readonly string[], omit: readonly string[]): string[];
+/** What is hidden inside a bound directory is covered: an empty tmpfs, or /dev/null. */
+export declare function hiddenArgs(tree: HostTree, hidden: readonly string[]): string[];
+export declare function probeBwrap(bwrap?: string, run?: Runner): Promise<BwrapProbe>;
+export {};
+//# sourceMappingURL=bwrap.d.ts.map