@landstrip/landstrip-api 0.19.12 → 0.19.13

package/README.md

@@ -40,6 +40,15 @@ Descriptor lifetimes and the reply protocol are covered in the manual.
 Integration helpers are exported through [`/shared`](lib/shared.d.ts) and
 [`/proxy`](lib/proxy.d.ts).
 
+`decodeLandstripTrap(value)` and `parseTrapLine(line)` from `/shared` return a
+validated `LandstripTrap`, or `null` for malformed input. Extra fields are
+preserved. Missing or unknown denial states are normalized to `info`, never
+queries; query IDs must be decimal `u64` strings and nonzero for queries.
+`isQueryTrap(trap)` narrows validated events to `LandstripQueryTrap` with
+`state: 'query'`. The declarations include all five native mechanisms and the
+current Windows error codes; the previously declared `POLICY_TCP_BIND_UNSUPPORTED`
+code remains accepted alongside `POLICY_LOCAL_BINDING_UNSUPPORTED`.
+
 `writeLandstripPolicyFile(policy, prefix = 'landstrip-')` from `/shared` writes
 `policy.json` and returns `{ dir, path }`. The caller owns `dir` and must remove it
 with `rmSync(dir, { recursive: true, force: true })` after use. Serialization

package/lib/index.d.ts

@@ -5,7 +5,8 @@ export type LandstripMechanism =
   | 'landlock'
   | 'seccomp'
   | 'seatbelt'
-  | 'appcontainer';
+  | 'appcontainer'
+  | 'windowsuser';
 
 /**
  * `query` holds the syscall until the launcher answers with a
@@ -86,6 +87,7 @@ export type LandstripPolicyErrorCode =
   | 'POLICY_DENY_READ_ALWAYS_UNSUPPORTED'
   | 'POLICY_DENY_WRITE_ALWAYS_UNSUPPORTED'
   | 'POLICY_TCP_BIND_UNSUPPORTED'
+  | 'POLICY_LOCAL_BINDING_UNSUPPORTED'
   | 'POLICY_UNIX_SOCKET_UNSUPPORTED'
   | 'POLICY_UNIX_SOCKET_PATH'
   | 'POLICY_DENY_WRITE_SYMLINK_ANCESTOR'
@@ -99,6 +101,7 @@ export type LandstripInternalCode =
   | LandstripPolicyErrorCode
   | 'SANDBOX_SETUP_FAILED'
   | 'SUPERVISE_FAILED'
+  | 'HOST_JOB_INCOMPATIBLE'
   | 'PLATFORM_UNSUPPORTED'
   | 'INTEGER_TOO_LARGE'
   | 'INTERNAL_ERROR';

package/lib/shared.d.ts

@@ -24,6 +24,7 @@ import type {
 } from './index.js';
 
 export type LandstripDenialTrap = LandstripFilesystemTrap | LandstripNetworkTrap;
+export type LandstripQueryTrap = LandstripDenialTrap & { state: 'query' };
 
 export type {
   SandboxConfig,
@@ -78,7 +79,7 @@ export function isFilesystemTrap(trap: LandstripTrap): trap is LandstripFilesyst
 
 export function isDenialTrap(trap: LandstripTrap): trap is LandstripDenialTrap;
 
-export function isQueryTrap(trap: LandstripTrap): trap is LandstripDenialTrap;
+export function isQueryTrap(trap: LandstripTrap): trap is LandstripQueryTrap;
 
 export function formatLandstripTrap(trap: LandstripTrap): string;
 
@@ -222,7 +223,11 @@ export function extractCandidatePaths(command: string): string[];
 
 export function extractNativeDeniedPath(output: string, cwd?: string): string | null;
 
-export function extractNativeWriteDeniedPath(output: string, cwd?: string): string | null;
+export function extractNativeWriteDeniedPath(
+  output: string,
+  cwd?: string,
+  command?: string,
+): string | null;
 
 export interface ExtractDeniedPathOptions {
   cwd?: string;

package/lib/shared.js

@@ -122,51 +122,115 @@ 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']);
+const LANDSTRIP_MECHANISMS = new Set([
+  'landlock',
+  'seccomp',
+  'seatbelt',
+  'appcontainer',
+  'windowsuser',
+]);
+const LANDSTRIP_INTERNAL_CODES = new Set([
+  'POLICY_PARSE_FAILED',
+  'POLICY_IO_FAILED',
+  'POLICY_UNRESTRICTED_READ',
+  'POLICY_DENY_READ_ALWAYS_UNSUPPORTED',
+  'POLICY_DENY_WRITE_ALWAYS_UNSUPPORTED',
+  'POLICY_TCP_BIND_UNSUPPORTED',
+  'POLICY_LOCAL_BINDING_UNSUPPORTED',
+  'POLICY_UNIX_SOCKET_UNSUPPORTED',
+  'POLICY_UNIX_SOCKET_PATH',
+  'POLICY_DENY_WRITE_SYMLINK_ANCESTOR',
+  'POLICY_INVALID_PORT',
+  'POLICY_EMPTY_PATH',
+  'POLICY_HOME_UNAVAILABLE',
+  'POLICY_TRAVERSAL_DEPTH',
+  'SUPERVISE_FAILED',
+  'HOST_JOB_INCOMPATIBLE',
+  'PLATFORM_UNSUPPORTED',
+  'INTEGER_TOO_LARGE',
+  'INTERNAL_ERROR',
+]);
+
+function isDenialRecord(value) {
+  return (
+    typeof value.query_id === 'string' &&
+    /^(0|[1-9][0-9]{0,19})$/.test(value.query_id) &&
+    BigInt(value.query_id) <= 18446744073709551615n &&
+    (value.state !== 'query' || value.query_id !== '0') &&
+    typeof value.syscall === 'string' &&
+    typeof value.errno === 'string' &&
+    value.mechanism === 'seccomp' &&
+    isRecord(value.process) &&
+    Number.isInteger(value.process.pid) &&
+    value.process.pid >= 0 &&
+    value.process.pid <= 4294967295 &&
+    (value.process.exe === null || typeof value.process.exe === 'string') &&
+    (value.process.cwd === null || typeof value.process.cwd === 'string')
+  );
+}
 
 function isLandstripTrap(value) {
   if (!isRecord(value)) return false;
 
   switch (value.kind) {
-    case 'filesystem':
+    case 'filesystem': {
+      if (!Array.isArray(value.flags)) return false;
+      for (const flag of value.flags) {
+        if (typeof flag !== 'string') return false;
+      }
+      const grant = value.operation === 'read' ? 'allowRead' : 'allowWrite';
+      const otherGrant = value.operation === 'read' ? 'allowWrite' : 'allowRead';
       return (
-        LANDSTRIP_OPERATIONS.has(value.operation) &&
+        value.code === 'FILESYSTEM_DENIED' &&
+        (value.operation === 'read' || value.operation === 'write') &&
         typeof value.path === 'string' &&
-        typeof value.query_id === 'string'
+        typeof value.requested_path === 'string' &&
+        (value.reason === 'allow_miss' || value.reason === 'deny_match') &&
+        isRecord(value.suggested_grant) &&
+        typeof value.suggested_grant[grant] === 'string' &&
+        value.suggested_grant[otherGrant] === undefined &&
+        isDenialRecord(value)
       );
+    }
     case 'network':
       return (
-        typeof value.operation === 'string' &&
+        value.code === 'NETWORK_DENIED' &&
+        (value.operation === 'connect' || value.operation === 'bind') &&
         typeof value.target === 'string' &&
-        typeof value.query_id === 'string'
+        isDenialRecord(value)
       );
     case 'launch':
-      return typeof value.program === 'string' && typeof value.message === 'string';
+      return (
+        value.code === 'LAUNCH_FAILED' &&
+        typeof value.program === 'string' &&
+        typeof value.message === 'string' &&
+        (value.errno === undefined || typeof value.errno === 'string')
+      );
     case 'usage':
-      return typeof value.message === 'string';
+      return value.code === 'USAGE_ERROR' && typeof value.message === 'string';
     case 'internal':
-      return typeof value.code === 'string' && typeof value.message === 'string';
+      return (
+        typeof value.message === 'string' &&
+        (value.code === 'SANDBOX_SETUP_FAILED'
+          ? LANDSTRIP_MECHANISMS.has(value.mechanism)
+          : LANDSTRIP_INTERNAL_CODES.has(value.code) && value.mechanism === undefined)
+      );
     default:
       return false;
   }
 }
 
 function decodeLandstripTrap(value) {
-  return isLandstripTrap(value) ? value : null;
+  if (!isLandstripTrap(value)) return null;
+  if (isDenialTrap(value) && value.state !== 'query' && value.state !== 'info') {
+    return { ...value, state: 'info' };
+  }
+  return value;
 }
 
 function parseTrapLine(line) {
   try {
-    const parsed = JSON.parse(line);
-    return isLandstripTrap(parsed) ? parsed : null;
+    return decodeLandstripTrap(JSON.parse(line));
   } catch {
     return null;
   }
@@ -928,7 +992,37 @@ function extractNativeDeniedPath(output, cwd = process.cwd()) {
   return null;
 }
 
-function extractNativeWriteDeniedPath(output, cwd = process.cwd()) {
+const nativeWriteTools = new Set(['mkdir', 'rm', 'rmdir', 'tee', 'touch', 'truncate', 'unlink']);
+const nativeShellTools = new Set(['bash', 'dash', 'fish', 'ksh', 'sh', 'zsh']);
+const nativeWriteSyscalls = new Set([
+  'chmod',
+  'chown',
+  'copyfile',
+  'link',
+  'mkdir',
+  'mkdtemp',
+  'rename',
+  'rmdir',
+  'symlink',
+  'truncate',
+  'unlink',
+  'utimes',
+  'write',
+]);
+
+function commandRedirectsToPath(command, path, cwd) {
+  if (typeof command !== 'string') return false;
+  const redirects = command.matchAll(
+    /(?:[0-9]*>>?|&>>?|>\|)\s*(?:'([^'\r\n]+)'|"([^"\r\n]+)"|\x60([^\x60\r\n]+)\x60|([^\s'"\x60;&|<>]+))/g,
+  );
+  for (const redirect of redirects) {
+    const target = redirect[1] ?? redirect[2] ?? redirect[3] ?? redirect[4];
+    if (target !== undefined && normalizePathMatch(target, cwd) === path) return true;
+  }
+  return false;
+}
+
+function extractNativeWriteDeniedPath(output, cwd = process.cwd(), command) {
   if (typeof output !== 'string') return null;
   const denial = String.raw`(?:Access is denied\.?|Operation not permitted|Permission denied)`;
   let match = output.match(
@@ -956,6 +1050,29 @@ function extractNativeWriteDeniedPath(output, cwd = process.cwd()) {
   );
   if (match) return normalizePathMatch(match[1], cwd);
 
+  match = output.match(
+    new RegExp(
+      String.raw`^([^\s:]+):\s+((?:[a-zA-Z]:[\\/]|\\\\|\/|\.{1,2}[\\/])[^:\r\n]*?):\s+${denial}$`,
+      'im',
+    ),
+  );
+  if (match) {
+    const tool = basename(match[1]);
+    const path = normalizePathMatch(match[2], cwd);
+    if (path && nativeWriteTools.has(tool)) return path;
+    if (path && nativeShellTools.has(tool) && commandRedirectsToPath(command, path, cwd)) return path;
+  }
+
+  match = output.match(
+    new RegExp(
+      String.raw`(?:EPERM|EACCES):\s*(?:operation not permitted|permission denied),\s*([a-z]+)\s+['"\x60]([^'"\x60\r\n]+)['"\x60]`,
+      'i',
+    ),
+  );
+  if (match && nativeWriteSyscalls.has(match[1].toLowerCase())) {
+    return normalizePathMatch(match[2], cwd);
+  }
+
   return null;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@landstrip/landstrip-api",
-  "version": "0.19.12",
+  "version": "0.19.13",
   "description": "Sandbox runner using Landlock, Seatbelt, and AppContainer",
   "license": "Apache-2.0",
   "homepage": "https://github.com/landstrip/landstrip#readme",
@@ -40,12 +40,12 @@
     "ipaddr.js": "^2.5.0"
   },
   "optionalDependencies": {
-    "@landstrip/landstrip-darwin-arm64": "0.19.12",
-    "@landstrip/landstrip-darwin-x64": "0.19.12",
-    "@landstrip/landstrip-linux-x64": "0.19.12",
-    "@landstrip/landstrip-linux-arm64": "0.19.12",
-    "@landstrip/landstrip-win32-x64": "0.19.12",
-    "@landstrip/landstrip-win32-arm64": "0.19.12"
+    "@landstrip/landstrip-darwin-arm64": "0.19.13",
+    "@landstrip/landstrip-darwin-x64": "0.19.13",
+    "@landstrip/landstrip-linux-x64": "0.19.13",
+    "@landstrip/landstrip-linux-arm64": "0.19.13",
+    "@landstrip/landstrip-win32-x64": "0.19.13",
+    "@landstrip/landstrip-win32-arm64": "0.19.13"
   },
   "publishConfig": {
     "access": "public"