@landstrip/landstrip 0.18.33 → 0.18.35

package/README.md

@@ -1,13 +1,9 @@
-<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
-<!-- Copyright (C) Jarkko Sakkinen 2026 -->
-
 # landstrip
 
 `landstrip` runs commands in an OS-level sandbox using Landlock on Linux,
-Seatbelt on macOS, and AppContainer or restricted users on Windows. Policies use
-the supported subset of the Anthropic Sandbox Runtime format.
+Seatbelt on macOS, and AppContainer or restricted users on Windows.
 
-## Installation
+## Install
 
 ```sh
 npm install --save-dev @landstrip/landstrip
@@ -17,7 +13,7 @@ npx landstrip run -p policy.json -- cargo test
 The npm package installs a Node.js wrapper and a native binary for the current
 platform.
 
-## Quick start
+## Usage
 
 ```sh
 landstrip run -p policy.json -- cargo test
@@ -26,21 +22,17 @@ landstrip policy resolve -p policy.json
 landstrip doctor
 ```
 
-Windows builds also provide `windows install`, `windows status`, and
-`windows uninstall`. Full command reference: `landstrip --help` and the
-[manual page](man/man1/landstrip.1).
-
-### Agent extensions
+Run `landstrip --help` or see [landstrip(1)](man/man1/landstrip.1) for the full
+command reference.
 
-```sh
-pi install npm:pi-landstrip
-opencode plugin install opencode-landstrip
-```
+## Agent extensions
 
-See [pi-landstrip](packages/pi-landstrip/README.md) and
-[opencode-landstrip](packages/opencode-landstrip/README.md).
+| Integration | Package                | Documentation                                                        |
+| ----------- | ---------------------- | -------------------------------------------------------------------- |
+| OpenCode    | `opencode-landstrip`   | [OpenCode](packages/opencode-landstrip/README.md)                    |
+| Pi          | `pi-landstrip`         | [Pi](packages/pi-landstrip/README.md)                                |
 
-## Policy sketch
+## Policy
 
 ```json
 {
@@ -52,49 +44,23 @@ See [pi-landstrip](packages/pi-landstrip/README.md) and
   },
   "network": {
     "allowNetwork": false,
-    "httpProxyPort": 8080,
-    "allowLocalBinding": false,
-    "allowUnixSockets": []
+    "allowLocalBinding": false
   }
 }
 ```
 
-Pass policies with `-p, --policy <FILE>` (repeatable). Semantics, platform
-limits, traps, and exit status are in the manual page.
+Pass policies with `-p, --policy <FILE>`. Later policies merge over earlier
+ones. Platform behavior and limits are documented in the manual.
 
 ## Development
 
-### Package
-
-Artifacts land in `npm/*/bin` and `artifacts/`. Staging writes platform tarballs
-and matching `<file>.sha256` sidecars under `artifacts/`.
-
-Non-host targets use [`cargo-zigbuild`](https://github.com/rust-cross/cargo-zigbuild)
-(Zig as linker). Requires `cargo-zigbuild`, `zig`, and the matching `rustup`
-targets (`x86_64-unknown-linux-musl`, `aarch64-unknown-linux-musl`,
-`x86_64-pc-windows-gnu`, `aarch64-pc-windows-gnullvm`, `aarch64-apple-darwin`,
-`x86_64-apple-darwin`). Host-native triples use plain `cargo`. Darwin links
-`libsandbox`; from Linux set `SDKROOT` to a macOS SDK (Apple SDK; not
-redistributed).
-
-```sh
-make package
-make package PLATFORMS='linux-x64 win32-x64'
-PACKAGE_STRICT=1 make package
-```
-
-`make publish` uploads each GitHub release tarball with its `<file>.sha256`
-sidecar. Verify a download with:
-
 ```sh
-sha256sum -c landstrip-<version>-<platform>.tar.gz.sha256
+make ci
 ```
 
-## License
+## Licensing
 
-`landstrip` is free software under the GNU Lesser General Public License
-version 2.1 or later (LGPL-2.1+). See [LICENSE-LGPL-2.1](LICENSE-LGPL-2.1).
+`landstrip` uses [LGPL-2.1+](LICENSE-LGPL-2.1).
 
-The JavaScript npm wrapper is under the Apache License 2.0. See
-[LICENSE-APACHE-2.0](LICENSE-APACHE-2.0). Corresponding source for each native
-package is available from the matching repository tag.
+The JavaScript wrapper and agent extensions use
+[Apache 2.0](LICENSE-APACHE-2.0).

package/lib/shared.d.ts

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+  LandstripControlResponse,
+  LandstripFilesystemTrap,
+  LandstripNetworkTrap,
+  LandstripTrap,
+} from './index.js';
+
+export type LandstripDenialTrap = LandstripFilesystemTrap | LandstripNetworkTrap;
+
+export function isRecord(value: unknown): value is Record<string, unknown>;
+
+export function expandHomePath(path: string): string;
+
+export function pathUnderDirectory(filePath: string, dir: string): boolean;
+
+export function sessionAllows(prefixes: Set<string>, filePath: string): boolean;
+
+export function sessionScopeFor(filePath: string, baseDirectory: string): string;
+
+export function domainMatchesPattern(domain: string, pattern: string): boolean;
+
+export function domainMatchesAny(domain: string, patterns: string[]): boolean;
+
+export function allowsAllDomains(allowedDomains: string[]): boolean;
+
+export function decodeLandstripTrap(value: unknown): LandstripTrap | null;
+
+export function parseTrapLine(line: string): LandstripTrap | null;
+
+export function parseLandstripTraps(output: string): LandstripTrap[];
+
+export function isFilesystemTrap(trap: LandstripTrap): trap is LandstripFilesystemTrap;
+
+export function isDenialTrap(trap: LandstripTrap): trap is LandstripDenialTrap;
+
+export function isQueryTrap(trap: LandstripTrap): trap is LandstripDenialTrap;
+
+export function formatLandstripTrap(trap: LandstripTrap): string;
+
+export function formatLandstripTraps(traps: LandstripTrap[]): string;
+
+export function controlResponseLine(
+  queryId: string,
+  action: LandstripControlResponse['action'],
+): string;

package/lib/shared.js

@@ -0,0 +1,219 @@
+// SPDX-License-Identifier: Apache-2.0
+'use strict';
+
+const { realpathSync } = require('node:fs');
+const { homedir } = require('node:os');
+const { dirname, isAbsolute, join, relative, sep } = require('node:path');
+
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function expandHomePath(value) {
+  if (value === '~' || value === '$HOME') return homedir();
+  if (value.startsWith('~/')) return join(homedir(), value.slice(2));
+  if (value.startsWith('$HOME/')) return join(homedir(), value.slice(6));
+  return value;
+}
+
+function pathUnderDirectory(filePath, dir) {
+  const child = relative(dir, filePath);
+  return child === '' || (!isAbsolute(child) && child !== '..' && !child.startsWith(`..${sep}`));
+}
+
+function sessionAllows(prefixes, filePath) {
+  for (const prefix of prefixes) {
+    if (pathUnderDirectory(filePath, prefix)) return true;
+  }
+  return false;
+}
+
+// The broadest ancestor worth approving in one action: the immediate child of
+// `$HOME` (e.g. `~/.cargo`) for paths under the user's home, the project root
+// for paths under it, otherwise the containing directory. A file sitting
+// directly on a boundary falls back to the exact file so nothing widens
+// silently.
+function sessionScopeFor(filePath, baseDirectory) {
+  const dir = dirname(filePath);
+  const homeBoundaries = new Set([homedir()]);
+  try {
+    homeBoundaries.add(realpathSync.native(homedir()));
+  } catch {
+    // $HOME not resolvable — fall back to the raw value only.
+  }
+
+  for (const boundary of homeBoundaries) {
+    if (pathUnderDirectory(dir, boundary)) {
+      const first = relative(boundary, dir).split(sep)[0];
+      if (!first) return filePath;
+      return join(boundary, first);
+    }
+  }
+
+  const projectBoundaries = new Set([baseDirectory]);
+  try {
+    projectBoundaries.add(realpathSync.native(baseDirectory));
+  } catch {
+    // Project directory not resolvable — fall back to the raw value only.
+  }
+
+  for (const boundary of projectBoundaries) {
+    if (pathUnderDirectory(dir, boundary)) return boundary;
+  }
+
+  return dir;
+}
+
+function domainMatchesPattern(domain, pattern) {
+  // A trailing dot ("pastebin.com.") is the same host to DNS but would slip
+  // past a literal deny entry; strip it from both sides before matching.
+  const normalizedDomain = domain.toLowerCase().replace(/\.+$/, '');
+  const normalizedPattern = pattern.toLowerCase().replace(/\.+$/, '');
+
+  if (normalizedPattern === '*') return true;
+  if (normalizedPattern.startsWith('*.')) {
+    const base = normalizedPattern.slice(2);
+    return normalizedDomain === base || normalizedDomain.endsWith(`.${base}`);
+  }
+
+  return normalizedDomain === normalizedPattern;
+}
+
+function domainMatchesAny(domain, patterns) {
+  return patterns.some((pattern) => domainMatchesPattern(domain, pattern));
+}
+
+function allowsAllDomains(allowedDomains) {
+  return allowedDomains.includes('*');
+}
+
+// landstrip emits each trap as a flat JSON record tagged by a `kind`
+// discriminant (`filesystem`, `network`, `launch`, `usage`, `internal`)
+// alongside a stable `code` and variant-specific fields. The declarations it
+// ships are erased at compile time, so validate the fields callers read
+// before trusting a decoded line. `state` is deliberately not validated: a
+// missing or unknown state degrades to "informational", the safe direction.
+// `query_id` must be a string — landstrip < 0.17 sent a number, and a
+// numeric id fails its own deserializer when echoed back.
+const LANDSTRIP_OPERATIONS = new Set(['read', 'write']);
+
+function isLandstripTrap(value) {
+  if (!isRecord(value)) return false;
+
+  switch (value.kind) {
+    case 'filesystem':
+      return (
+        LANDSTRIP_OPERATIONS.has(value.operation) &&
+        typeof value.path === 'string' &&
+        typeof value.query_id === 'string'
+      );
+    case 'network':
+      return (
+        typeof value.operation === 'string' &&
+        typeof value.target === 'string' &&
+        typeof value.query_id === 'string'
+      );
+    case 'launch':
+      return typeof value.program === 'string' && typeof value.message === 'string';
+    case 'usage':
+      return typeof value.message === 'string';
+    case 'internal':
+      return typeof value.code === 'string' && typeof value.message === 'string';
+    default:
+      return false;
+  }
+}
+
+function decodeLandstripTrap(value) {
+  return isLandstripTrap(value) ? value : null;
+}
+
+function parseTrapLine(line) {
+  try {
+    const parsed = JSON.parse(line);
+    return isLandstripTrap(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseLandstripTraps(output) {
+  const traps = [];
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0 || trimmed[0] !== '{') continue;
+    const trap = parseTrapLine(trimmed);
+    if (trap) traps.push(trap);
+  }
+
+  return traps;
+}
+
+function isFilesystemTrap(trap) {
+  return trap.kind === 'filesystem';
+}
+
+// filesystem and network traps report an access the policy denied; launch,
+// usage and internal traps report that landstrip itself failed.
+function isDenialTrap(trap) {
+  return trap.kind === 'filesystem' || trap.kind === 'network';
+}
+
+// A `state: "query"` trap suspends the child's syscall until the host answers
+// it on the trap socket. An `info` trap is terminal.
+function isQueryTrap(trap) {
+  return isDenialTrap(trap) && trap.state === 'query';
+}
+
+function formatLandstripTrap(trap) {
+  switch (trap.kind) {
+    case 'filesystem':
+      return `landstrip: filesystem ${trap.operation} denied (${trap.path})${
+        trap.mechanism ? ` [${trap.mechanism}]` : ''
+      }`;
+    case 'network':
+      return `landstrip: network ${trap.operation} denied (${trap.target})${
+        trap.mechanism ? ` [${trap.mechanism}]` : ''
+      }`;
+    case 'launch':
+      return `landstrip: launch failed (${trap.program})${trap.message ? `: ${trap.message}` : ''}`;
+    case 'usage':
+      return `landstrip: usage error: ${trap.message}`;
+    case 'internal': {
+      const mechanism = trap.mechanism ? ` [${trap.mechanism}]` : '';
+      return `landstrip: ${trap.code}${mechanism}: ${trap.message}`;
+    }
+  }
+}
+
+function formatLandstripTraps(traps) {
+  return traps.map(formatLandstripTrap).join('\n');
+}
+
+// The broker matches an answer to its query by the exact decimal `query_id`
+// string the trap carried. A numeric id fails its deserializer, the line is
+// dropped, and the child's syscall stays suspended.
+function controlResponseLine(queryId, action) {
+  return JSON.stringify({ query_id: queryId, action }) + '\n';
+}
+
+module.exports = {
+  isRecord,
+  expandHomePath,
+  pathUnderDirectory,
+  sessionAllows,
+  sessionScopeFor,
+  domainMatchesPattern,
+  domainMatchesAny,
+  allowsAllDomains,
+  decodeLandstripTrap,
+  parseTrapLine,
+  parseLandstripTraps,
+  isFilesystemTrap,
+  isDenialTrap,
+  isQueryTrap,
+  formatLandstripTrap,
+  formatLandstripTraps,
+  controlResponseLine,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@landstrip/landstrip",
-  "version": "0.18.33",
+  "version": "0.18.35",
   "description": "Sandbox runner using Landlock, Seatbelt, and AppContainer",
   "license": "Apache-2.0 AND LGPL-2.1-or-later",
   "homepage": "https://github.com/landstrip/landstrip#readme",
@@ -17,6 +17,10 @@
     ".": {
       "types": "./lib/index.d.ts",
       "default": "./lib/index.js"
+    },
+    "./shared": {
+      "types": "./lib/shared.d.ts",
+      "default": "./lib/shared.js"
     }
   },
   "bin": {
@@ -30,12 +34,12 @@
     "LICENSE-LGPL-2.1"
   ],
   "optionalDependencies": {
-    "@landstrip/landstrip-darwin-arm64": "0.18.33",
-    "@landstrip/landstrip-darwin-x64": "0.18.33",
-    "@landstrip/landstrip-linux-x64": "0.18.33",
-    "@landstrip/landstrip-linux-arm64": "0.18.33",
-    "@landstrip/landstrip-win32-x64": "0.18.33",
-    "@landstrip/landstrip-win32-arm64": "0.18.33"
+    "@landstrip/landstrip-darwin-arm64": "0.18.35",
+    "@landstrip/landstrip-darwin-x64": "0.18.35",
+    "@landstrip/landstrip-linux-x64": "0.18.35",
+    "@landstrip/landstrip-linux-arm64": "0.18.35",
+    "@landstrip/landstrip-win32-x64": "0.18.35",
+    "@landstrip/landstrip-win32-arm64": "0.18.35"
   },
   "publishConfig": {
     "access": "public"