@landstrip/landstrip-api 0.19.20 → 0.20.0

package/README.md

@@ -18,7 +18,7 @@ See the [quick start](../../README.md#quick-start) for a policy and CLI example;
 const { execFileSync } = require("node:child_process");
 const { binaryPath } = require("@landstrip/landstrip-api");
 
-execFileSync(binaryPath(), ["-p", "policy.json", "--", "cargo", "test"], {
+execFileSync(binaryPath(), ["run", "-p", "policy.json", "--", "cargo", "test"], {
   stdio: "inherit",
 });
 ```
@@ -39,6 +39,37 @@ Proxy helpers: [`/proxy`](lib/proxy.d.ts). [`/shared`](lib/shared.d.ts) provides
   Failed writes clean up; failed cleanup reports both errors and the directory
   path in an `AggregateError`.
 
+## macOS log correlation
+
+Both `LandstripDarwinPolicy` and `SandboxDarwinConfig` accept optional
+`logTag?: string`, under the JSON key `macos` (not `darwin`):
+
+```js
+const { buildLandstripPolicy } = require("@landstrip/landstrip-api/shared");
+const policy = buildLandstripPolicy({ macos: { logTag: "agent-session-42" } });
+```
+
+`macos.logTag` tags Seatbelt denial logs for correlation. It must be nonempty
+and contain no double quote, backslash, ASCII control character (0x00–0x1f),
+or DEL (0x7f). `null` is invalid. `buildLandstripPolicy` and `parseSandboxConfig`
+validate and forward it; `deepMergeSandboxConfig` uses the override tag when
+provided, otherwise preserving the base tag.
+
+## Trap transport and reporting
+
+On Unix, `--trap FD|PATH` accepts either an inherited open FD ≥3 or an absolute
+Unix domain stream socket path. Start the socket listener before launching
+Landstrip: the host Landstrip process connects before sandbox setup, and the
+sandboxed child never inherits the trap transport.
+
+On Linux, the stream is bidirectional and uses the existing broker query
+protocol, not merely passive monitoring. For `state: "query"` events, reply on
+the same socket with `controlResponseLine(trap.query_id, "allow")` (or `"deny"`);
+the syscall waits for an answer. Completed events have `state: "info"`.
+Explicit read denials (`DenyMatch`, JSON `reason: "deny_match"`) are reported
+even when the command exits 0. macOS reports setup/launch failures on the trap
+transport and closes it on successful exec; use Seatbelt logs for runtime denials.
+
 ## Development
 
 Run `make ci` from the repository root.

package/lib/index.d.ts

@@ -93,6 +93,7 @@ export type LandstripPolicyErrorCode =
   | 'POLICY_DENY_WRITE_SYMLINK_ANCESTOR'
   | 'POLICY_INVALID_PORT'
   | 'POLICY_EMPTY_PATH'
+  | 'POLICY_INVALID_LOG_TAG'
   | 'POLICY_HOME_UNAVAILABLE'
   | 'POLICY_TRAVERSAL_DEPTH';
 
@@ -145,24 +146,38 @@ export interface LandstripControlResponse {
   action: 'allow' | 'deny';
 }
 
+export type LandstripPathSelector =
+  | string
+  | { literal: string }
+  | { glob: string };
+
 export interface LandstripFilesystemPolicy {
-  denyRead?: string[];
-  denyReadAlways?: string[];
-  allowRead?: string[];
-  allowWrite?: string[];
-  denyWrite?: string[];
-  denyWriteAlways?: string[];
+  denyRead?: LandstripPathSelector[];
+  denyReadAlways?: LandstripPathSelector[];
+  allowRead?: LandstripPathSelector[];
+  allowWrite?: LandstripPathSelector[];
+  denyWrite?: LandstripPathSelector[];
+  denyWriteAlways?: LandstripPathSelector[];
 }
 
 export interface LandstripNetworkPolicy {
   allowNetwork?: boolean;
   allowLocalBinding?: boolean;
   allowAllUnixSockets?: boolean;
-  allowUnixSockets?: string[];
+  allowUnixSockets?: LandstripPathSelector[];
   httpProxyPort?: number;
   socksProxyPort?: number;
 }
 
+export interface LandstripDarwinPolicy {
+  /** Seatbelt log correlation tag: nonempty, without double quotes, backslashes, ASCII controls or DEL; not null. */
+  logTag?: string;
+  allowTrustd?: boolean;
+  allowMachLookup?: string[];
+  allowAppleEvents?: boolean;
+  allowPty?: boolean;
+}
+
 export type LandstripWindowsAppContainerMode = 'lpac' | 'standard';
 
 export interface LandstripWindowsPolicy {
@@ -173,9 +188,32 @@ export interface LandstripWindowsPolicy {
 export interface LandstripPolicy {
   filesystem?: LandstripFilesystemPolicy;
   network?: LandstripNetworkPolicy;
+  macos?: LandstripDarwinPolicy;
   windows?: LandstripWindowsPolicy;
 }
 
+export type SandboxImplementation =
+  | 'landlock+seccomp'
+  | 'seatbelt'
+  | 'appContainer'
+  | 'restrictedUser';
+
+export interface FeatureCapabilities {
+  filesystemTiers: string[];
+  networkMediation: boolean;
+  unixSocketFiltering: boolean;
+  processIsolation: boolean;
+}
+
+export interface DoctorReport {
+  ok: boolean;
+  platform: string;
+  implementation: SandboxImplementation;
+  supported: FeatureCapabilities;
+  available: FeatureCapabilities;
+  error?: string;
+}
+
 export interface SandboxFilesystemConfig {
   denyRead: string[];
   denyReadAlways: string[];
@@ -200,6 +238,15 @@ export interface SandboxNetworkConfig {
   deniedDomains: string[];
 }
 
+export interface SandboxDarwinConfig {
+  /** Optional Seatbelt log correlation tag; same restrictions as LandstripDarwinPolicy.logTag. */
+  logTag?: string;
+  allowTrustd: boolean;
+  allowMachLookup: string[];
+  allowAppleEvents: boolean;
+  allowPty: boolean;
+}
+
 export interface SandboxWindowsConfig {
   appContainerMode: LandstripWindowsAppContainerMode;
   allowLoopback: boolean;
@@ -210,12 +257,14 @@ export interface SandboxConfig {
   shell?: SandboxShellConfig;
   network: SandboxNetworkConfig;
   filesystem: SandboxFilesystemConfig;
+  macos?: SandboxDarwinConfig;
   windows?: SandboxWindowsConfig;
 }
 
 export type SandboxFilesystemConfigFile = Partial<SandboxFilesystemConfig>;
 export type SandboxShellConfigFile = Partial<SandboxShellConfig>;
 export type SandboxNetworkConfigFile = Partial<SandboxNetworkConfig>;
+export type SandboxDarwinConfigFile = Partial<SandboxDarwinConfig>;
 export type SandboxWindowsConfigFile = Partial<SandboxWindowsConfig>;
 
 export interface SandboxConfigFile {
@@ -223,12 +272,12 @@ export interface SandboxConfigFile {
   shell?: SandboxShellConfigFile;
   network?: SandboxNetworkConfigFile;
   filesystem?: SandboxFilesystemConfigFile;
+  macos?: SandboxDarwinConfigFile;
   windows?: SandboxWindowsConfigFile;
 }
 
 export type SandboxConfigOverrides = SandboxConfigFile;
 
-
 export type PathAccessDecision = 'allow' | 'ask' | 'deny' | 'denyAlways';
 
 export type DomainAccessDecision = 'allow' | 'ask' | 'deny';

package/lib/shared.d.ts

@@ -1,19 +1,26 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import type {
+  DoctorReport,
+  FeatureCapabilities,
   LandstripControlResponse,
+  LandstripDarwinPolicy,
   LandstripFilesystemPolicy,
   LandstripFilesystemTrap,
   LandstripNetworkPolicy,
   LandstripNetworkTrap,
+  LandstripPathSelector,
   LandstripPolicy,
   LandstripTrap,
   LandstripWindowsPolicy,
   SandboxConfig,
   SandboxConfigFile,
   SandboxConfigOverrides,
+  SandboxDarwinConfig,
+  SandboxDarwinConfigFile,
   SandboxFilesystemConfig,
   SandboxFilesystemConfigFile,
+  SandboxImplementation,
   SandboxNetworkConfig,
   SandboxNetworkConfigFile,
   SandboxShellConfig,
@@ -27,11 +34,18 @@ export type LandstripDenialTrap = LandstripFilesystemTrap | LandstripNetworkTrap
 export type LandstripQueryTrap = LandstripDenialTrap & { state: 'query' };
 
 export type {
+  DoctorReport,
+  FeatureCapabilities,
+  LandstripDarwinPolicy,
+  LandstripPathSelector,
   SandboxConfig,
   SandboxConfigFile,
   SandboxConfigOverrides,
+  SandboxDarwinConfig,
+  SandboxDarwinConfigFile,
   SandboxFilesystemConfig,
   SandboxFilesystemConfigFile,
+  SandboxImplementation,
   SandboxNetworkConfig,
   SandboxNetworkConfigFile,
   SandboxShellConfig,
@@ -92,24 +106,25 @@ export function controlResponseLine(
 
 
 export interface BuildLandstripPolicyOptions {
-  filesystem?: LandstripFilesystemPolicy;
-  network?: LandstripNetworkPolicy;
-  windows?: LandstripWindowsPolicy;
-  baseDirectory?: string;
-  httpProxyPort?: number | null;
-  socksProxyPort?: number | null;
+  filesystem?: LandstripFilesystemPolicy | undefined;
+  network?: LandstripNetworkPolicy | undefined;
+  macos?: LandstripDarwinPolicy | undefined;
+  windows?: LandstripWindowsPolicy | undefined;
+  baseDirectory?: string | undefined;
+  httpProxyPort?: number | null | undefined;
+  socksProxyPort?: number | null | undefined;
 }
 
 export function resolveFilesystemPatterns(
-  patterns: string[] | undefined,
+  patterns: LandstripPathSelector[] | undefined,
   baseDirectory?: string,
-): string[];
-
+): LandstripPathSelector[];
 export function resolveFilesystemPolicy(
   filesystem?: LandstripFilesystemPolicy,
   baseDirectory?: string,
 ): LandstripFilesystemPolicy;
 
+/** Forwards macos.logTag; throws if it is empty, non-string, or contains a double quote, backslash, ASCII control or DEL. */
 export function buildLandstripPolicy(
   options: BuildLandstripPolicyOptions,
 ): LandstripPolicy;
@@ -122,10 +137,11 @@ export function writeLandstripPolicyFile(
 ): { dir: string; path: string };
 
 
-export function mergeArray(base: string[], override?: string[]): string[];
-
+export function mergeArray<T = string>(base: T[], override?: T[]): T[];
+/** Parses sandbox settings, validating macos.logTag with the same rules as buildLandstripPolicy (null is invalid). */
 export function parseSandboxConfig(value: unknown): SandboxConfigFile;
 
+/** Merges arrays and applies override scalar precedence, including macos.logTag. */
 export function deepMergeSandboxConfig<T extends SandboxConfig = SandboxConfig>(
   base: T,
   overrides?: SandboxConfigFile,
@@ -153,36 +169,35 @@ export interface EvaluateDomainOptions {
 
 export function matchesPathPattern(
   filePath: string,
-  patterns: string[],
+  patterns: LandstripPathSelector[],
   baseDirectory?: string,
 ): boolean;
 
 export function matchPathSpecificity(
   filePath: string,
-  patterns: string[],
+  patterns: LandstripPathSelector[],
   baseDirectory?: string,
 ): number;
 
 export function isPathReadAllowed(
   filePath: string,
-  allowRead: string[],
-  denyRead: string[],
+  allowRead: LandstripPathSelector[],
+  denyRead: LandstripPathSelector[],
   baseDirectory?: string,
   options?: { requireAllowMatch?: boolean },
 ): boolean;
 
 export function isPathWriteAllowed(
   filePath: string,
-  allowWrite: string[],
+  allowWrite: LandstripPathSelector[],
   baseDirectory?: string,
 ): boolean;
 
 export function shouldPromptForWrite(
   filePath: string,
-  allowWrite: string[],
+  allowWrite: LandstripPathSelector[],
   baseDirectory?: string,
 ): boolean;
-
 export function evaluateReadAccess(
   filePath: string,
   filesystem: SandboxFilesystemConfig | SandboxFilesystemConfigFile | SandboxConfig | SandboxConfigFile,

package/lib/shared.js

@@ -142,6 +142,7 @@ const LANDSTRIP_INTERNAL_CODES = new Set([
   'POLICY_DENY_WRITE_SYMLINK_ANCESTOR',
   'POLICY_INVALID_PORT',
   'POLICY_EMPTY_PATH',
+  'POLICY_INVALID_LOG_TAG',
   'POLICY_HOME_UNAVAILABLE',
   'POLICY_TRAVERSAL_DEPTH',
   'SUPERVISE_FAILED',
@@ -418,14 +419,27 @@ function controlResponseLine(queryId, action) {
   return JSON.stringify({ query_id: queryId, action }) + '\n';
 }
 
+function resolvePathSelector(entry, baseDirectory) {
+  if (typeof entry === 'string') {
+    return /[*?[\]]/.test(entry)
+      ? canonicalizeGlobPattern(entry, baseDirectory)
+      : canonicalizePath(entry, baseDirectory);
+  }
+  if (isRecord(entry)) {
+    if (typeof entry.literal === 'string') {
+      return { literal: canonicalizePath(entry.literal, baseDirectory) };
+    }
+    if (typeof entry.glob === 'string') {
+      return { glob: canonicalizeGlobPattern(entry.glob, baseDirectory) };
+    }
+  }
+  return entry;
+}
+
 function resolveFilesystemPatterns(patterns, baseDirectory) {
   if (!patterns || !Array.isArray(patterns)) return [];
   if (!baseDirectory) return [...patterns];
-  return patterns.map((pattern) =>
-    /[*?[\]]/.test(pattern)
-      ? canonicalizeGlobPattern(pattern, baseDirectory)
-      : canonicalizePath(pattern, baseDirectory),
-  );
+  return patterns.map((pattern) => resolvePathSelector(pattern, baseDirectory));
 }
 
 function resolveFilesystemPolicy(filesystem, baseDirectory) {
@@ -452,6 +466,14 @@ function resolveFilesystemPolicy(filesystem, baseDirectory) {
   return resolved;
 }
 
+function validateDarwinLogTag(value) {
+  if (typeof value !== 'string' || value.length === 0 || /["\\\x00-\x1f\x7f]/.test(value)) {
+    throw new Error(
+      'macos.logTag must be a nonempty string without double quotes, backslashes, ASCII control characters or DEL',
+    );
+  }
+}
+
 function buildLandstripPolicy(options) {
   const policy = {};
   if (options.network) {
@@ -485,6 +507,20 @@ function buildLandstripPolicy(options) {
       options.baseDirectory,
     );
   }
+  if (options.macos) {
+    policy.macos = {
+      allowTrustd: Boolean(options.macos.allowTrustd),
+      allowMachLookup: Array.isArray(options.macos.allowMachLookup)
+        ? [...options.macos.allowMachLookup]
+        : [],
+      allowAppleEvents: Boolean(options.macos.allowAppleEvents),
+      allowPty: Boolean(options.macos.allowPty),
+    };
+    if (options.macos.logTag !== undefined) {
+      validateDarwinLogTag(options.macos.logTag);
+      policy.macos.logTag = options.macos.logTag;
+    }
+  }
   if (options.windows) {
     policy.windows = {
       appContainerMode: options.windows.appContainerMode ?? 'lpac',
@@ -552,12 +588,28 @@ function validateStringArrayFields(value, fields, prefix = '') {
 
 function mergeArray(base, override) {
   if (!override) return base;
-  return [...new Set([...(base ?? []), ...override])];
+  const result = [];
+  const seen = new Set();
+  for (const item of [...(base ?? []), ...override]) {
+    const key = typeof item === 'string' ? `s:${item}` : `o:${JSON.stringify(item)}`;
+    if (!seen.has(key)) {
+      seen.add(key);
+      result.push(item);
+    }
+  }
+  return result;
 }
 
 function parseSandboxConfig(value) {
   requireSandboxObject(value, 'sandbox config');
-  rejectUnknownSandboxFields(value, ['enabled', 'shell', 'network', 'filesystem', 'windows']);
+  rejectUnknownSandboxFields(value, [
+    'enabled',
+    'shell',
+    'network',
+    'filesystem',
+    'macos',
+    'windows',
+  ]);
   validateBooleanFields(value, ['enabled']);
 
   const config = {};
@@ -656,6 +708,38 @@ function parseSandboxConfig(value) {
     }
   }
 
+  if (value.macos !== undefined) {
+    requireSandboxObject(value.macos, 'macos');
+    rejectUnknownSandboxFields(
+      value.macos,
+      ['allowTrustd', 'allowMachLookup', 'allowAppleEvents', 'allowPty', 'logTag'],
+      'macos.',
+    );
+    validateBooleanFields(
+      value.macos,
+      ['allowTrustd', 'allowAppleEvents', 'allowPty'],
+      'macos.',
+    );
+    validateStringArrayFields(value.macos, ['allowMachLookup'], 'macos.');
+    config.macos = {};
+    if (value.macos.allowTrustd !== undefined) {
+      config.macos.allowTrustd = value.macos.allowTrustd;
+    }
+    if (value.macos.allowMachLookup !== undefined) {
+      config.macos.allowMachLookup = [...value.macos.allowMachLookup];
+    }
+    if (value.macos.allowAppleEvents !== undefined) {
+      config.macos.allowAppleEvents = value.macos.allowAppleEvents;
+    }
+    if (value.macos.allowPty !== undefined) {
+      config.macos.allowPty = value.macos.allowPty;
+    }
+    if (value.macos.logTag !== undefined) {
+      validateDarwinLogTag(value.macos.logTag);
+      config.macos.logTag = value.macos.logTag;
+    }
+  }
+
   if (value.windows !== undefined) {
     requireSandboxObject(value.windows, 'windows');
     rejectUnknownSandboxFields(value.windows, ['appContainerMode', 'allowLoopback'], 'windows.');
@@ -685,6 +769,7 @@ function deepMergeSandboxConfig(base, overrides) {
   const shell = overrides.shell;
   const network = overrides.network;
   const filesystem = overrides.filesystem;
+  const macos = overrides.macos;
   const windows = overrides.windows;
 
   const result = {
@@ -713,6 +798,19 @@ function deepMergeSandboxConfig(base, overrides) {
     };
   }
 
+  if (base.macos !== undefined || macos !== undefined) {
+    result.macos = {
+      allowTrustd: macos?.allowTrustd ?? base.macos?.allowTrustd ?? false,
+      allowMachLookup: mergeArray(base.macos?.allowMachLookup ?? [], macos?.allowMachLookup),
+      allowAppleEvents: macos?.allowAppleEvents ?? base.macos?.allowAppleEvents ?? false,
+      allowPty: macos?.allowPty ?? base.macos?.allowPty ?? false,
+    };
+    const logTag = macos?.logTag ?? base.macos?.logTag;
+    if (logTag !== undefined) {
+      result.macos.logTag = logTag;
+    }
+  }
+
   if (base.windows !== undefined || windows !== undefined) {
     result.windows = {
       appContainerMode: windows?.appContainerMode ?? base.windows?.appContainerMode ?? 'standard',
@@ -729,14 +827,43 @@ function normalizePathForComparison(filePath) {
   return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
 }
 
+function resolveSelectorForMatch(pattern, baseDirectory) {
+  if (isRecord(pattern)) {
+    if (typeof pattern.literal === 'string') {
+      return {
+        canonical: canonicalizePath(pattern.literal, baseDirectory),
+        isGlob: false,
+      };
+    }
+    if (typeof pattern.glob === 'string') {
+      const isGlob = /[*?[\]]/.test(pattern.glob);
+      return {
+        canonical: isGlob
+          ? canonicalizeGlobPattern(pattern.glob, baseDirectory)
+          : canonicalizePath(pattern.glob, baseDirectory),
+        isGlob,
+      };
+    }
+  }
+  const raw = String(pattern);
+  const isGlob = /[*?[\]]/.test(raw);
+  return {
+    canonical: isGlob
+      ? canonicalizeGlobPattern(raw, baseDirectory)
+      : canonicalizePath(raw, baseDirectory),
+    isGlob,
+  };
+}
+
 function matchesPathPattern(filePath, patterns, baseDirectory = process.cwd()) {
   if (!Array.isArray(patterns) || patterns.length === 0) return false;
   const abs = normalizePathForComparison(canonicalizePath(filePath, baseDirectory));
 
   return patterns.some((pattern) => {
-    const absPattern = normalizePathForComparison(canonicalizeGlobPattern(pattern, baseDirectory));
+    const { canonical, isGlob } = resolveSelectorForMatch(pattern, baseDirectory);
+    const absPattern = normalizePathForComparison(canonical);
 
-    if (/[*?[\]]/.test(pattern)) {
+    if (isGlob) {
       const matcher = globToRegExp(absPattern);
       for (let candidate = abs; ;) {
         if (matcher.test(candidate)) return true;
@@ -757,7 +884,7 @@ function matchPathSpecificity(filePath, patterns, baseDirectory = process.cwd())
   let best = -1;
   for (const pattern of patterns) {
     if (!matchesPathPattern(filePath, [pattern], baseDirectory)) continue;
-    const canonical = canonicalizeGlobPattern(pattern, baseDirectory);
+    const { canonical } = resolveSelectorForMatch(pattern, baseDirectory);
     if (canonical.length > best) {
       best = canonical.length;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@landstrip/landstrip-api",
-  "version": "0.19.20",
+  "version": "0.20.0",
   "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.20",
-    "@landstrip/landstrip-darwin-x64": "0.19.20",
-    "@landstrip/landstrip-linux-x64": "0.19.20",
-    "@landstrip/landstrip-linux-arm64": "0.19.20",
-    "@landstrip/landstrip-win32-x64": "0.19.20",
-    "@landstrip/landstrip-win32-arm64": "0.19.20"
+    "@landstrip/landstrip-darwin-arm64": "0.20.0",
+    "@landstrip/landstrip-darwin-x64": "0.20.0",
+    "@landstrip/landstrip-linux-x64": "0.20.0",
+    "@landstrip/landstrip-linux-arm64": "0.20.0",
+    "@landstrip/landstrip-win32-x64": "0.20.0",
+    "@landstrip/landstrip-win32-arm64": "0.20.0"
   },
   "publishConfig": {
     "access": "public"