@landstrip/landstrip-api 0.19.6 → 0.19.7

package/lib/index.d.ts

@@ -84,6 +84,7 @@ export type LandstripPolicyErrorCode =
   | 'POLICY_IO_FAILED'
   | 'POLICY_UNRESTRICTED_READ'
   | 'POLICY_DENY_READ_ALWAYS_UNSUPPORTED'
+  | 'POLICY_DENY_WRITE_ALWAYS_UNSUPPORTED'
   | 'POLICY_TCP_BIND_UNSUPPORTED'
   | 'POLICY_UNIX_SOCKET_UNSUPPORTED'
   | 'POLICY_UNIX_SOCKET_PATH'
@@ -141,6 +142,114 @@ export interface LandstripControlResponse {
   action: 'allow' | 'deny';
 }
 
+export interface LandstripFilesystemPolicy {
+  denyRead?: string[];
+  denyReadAlways?: string[];
+  allowRead?: string[];
+  allowWrite?: string[];
+  denyWrite?: string[];
+  denyWriteAlways?: string[];
+}
+
+export interface LandstripNetworkPolicy {
+  allowNetwork?: boolean;
+  allowLocalBinding?: boolean;
+  allowAllUnixSockets?: boolean;
+  allowUnixSockets?: string[];
+  httpProxyPort?: number;
+  socksProxyPort?: number;
+}
+
+export type LandstripWindowsAppContainerMode = 'lpac' | 'standard';
+
+export interface LandstripWindowsPolicy {
+  appContainerMode?: LandstripWindowsAppContainerMode;
+  allowLoopback?: boolean;
+}
+
+export interface LandstripPolicy {
+  filesystem?: LandstripFilesystemPolicy;
+  network?: LandstripNetworkPolicy;
+  windows?: LandstripWindowsPolicy;
+}
+
+export interface SandboxFilesystemConfig {
+  denyRead: string[];
+  denyReadAlways: string[];
+  allowRead: string[];
+  allowWrite: string[];
+  denyWrite: string[];
+  denyWriteAlways: string[];
+}
+
+export type ShellReadAccess = 'host' | 'policy';
+
+export interface SandboxShellConfig {
+  readAccess: ShellReadAccess;
+}
+
+export interface SandboxNetworkConfig {
+  allowNetwork: boolean;
+  allowLocalBinding: boolean;
+  allowAllUnixSockets: boolean;
+  allowUnixSockets: string[];
+  allowedDomains: string[];
+  deniedDomains: string[];
+}
+
+export interface SandboxWindowsConfig {
+  appContainerMode: LandstripWindowsAppContainerMode;
+  allowLoopback: boolean;
+}
+
+export interface SandboxConfig {
+  enabled: boolean;
+  shell?: SandboxShellConfig;
+  network: SandboxNetworkConfig;
+  filesystem: SandboxFilesystemConfig;
+  windows?: SandboxWindowsConfig;
+}
+
+export type SandboxFilesystemConfigFile = Partial<SandboxFilesystemConfig>;
+export type SandboxShellConfigFile = Partial<SandboxShellConfig>;
+export type SandboxNetworkConfigFile = Partial<SandboxNetworkConfig>;
+export type SandboxWindowsConfigFile = Partial<SandboxWindowsConfig>;
+
+export interface SandboxConfigFile {
+  enabled?: boolean;
+  shell?: SandboxShellConfigFile;
+  network?: SandboxNetworkConfigFile;
+  filesystem?: SandboxFilesystemConfigFile;
+  windows?: SandboxWindowsConfigFile;
+}
+
+export type SandboxConfigOverrides = SandboxConfigFile;
+
+
+export type PathAccessDecision = 'allow' | 'ask' | 'deny' | 'denyAlways';
+
+export type DomainAccessDecision = 'allow' | 'ask' | 'deny';
+
+export interface EvaluateReadOptions {
+  baseDirectory?: string;
+  allowReadOverrides?: string[];
+  requireAllowMatch?: boolean;
+}
+
+export interface EvaluateWriteOptions {
+  baseDirectory?: string;
+  allowWriteOverrides?: string[];
+}
+
+export interface EvaluateDomainOptions {
+  allowedDomainsOverrides?: string[];
+}
+
+
+export interface ExtractDeniedPathOptions {
+  cwd?: string;
+  command?: string;
+}
 /**
  * Path to the native landstrip binary for the running platform.
  *
@@ -150,3 +259,13 @@ export function binaryPath(platform?: string, arch?: string): string;
 
 /** Name of the binary package for the given platform. */
 export function packageName(platform?: string, arch?: string): string;
+
+
+export type {
+  ProxyPortRange,
+  FilterProxyOptions,
+  FilterProxyHandle,
+  ProxyEnvironmentVariable,
+  ProxyCredentials,
+  CreateProxyEnvironmentOptions,
+} from './proxy';

package/lib/proxy.d.ts

@@ -20,3 +20,35 @@ export interface FilterProxyHandle {
 }
 
 export function startFilterProxy(options: FilterProxyOptions): Promise<FilterProxyHandle>;
+
+export const PROXY_ENVIRONMENT_VARIABLES: readonly [
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'ALL_PROXY',
+  'http_proxy',
+  'https_proxy',
+  'all_proxy',
+];
+
+export type ProxyEnvironmentVariable = (typeof PROXY_ENVIRONMENT_VARIABLES)[number];
+
+export interface ProxyCredentials {
+  token: string;
+  authorization: string;
+}
+
+export function createProxyCredentials(token?: string): ProxyCredentials;
+
+export function createProxyUrl(port: number, token?: string | null, host?: string): string;
+
+export interface CreateProxyEnvironmentOptions {
+  token?: string | null;
+  host?: string;
+  baseEnv?: NodeJS.ProcessEnv;
+}
+
+export function createProxyEnvironment(
+  port?: number | null,
+  options?: CreateProxyEnvironmentOptions | string | null,
+  baseEnv?: NodeJS.ProcessEnv,
+): NodeJS.ProcessEnv;

package/lib/proxy.js

@@ -1,6 +1,8 @@
 // SPDX-License-Identifier: Apache-2.0
 'use strict';
 
+const { randomBytes } = require('node:crypto');
+
 const { lookup } = require('node:dns/promises');
 const { Agent, createServer: createHttpServer, request: requestHttp } = require('node:http');
 const { connect, isIP } = require('node:net');
@@ -342,6 +344,60 @@ function startFilterProxy(options) {
   });
 }
 
+const PROXY_ENVIRONMENT_VARIABLES = [
+  'HTTP_PROXY',
+  'HTTPS_PROXY',
+  'ALL_PROXY',
+  'http_proxy',
+  'https_proxy',
+  'all_proxy',
+];
+
+function createProxyCredentials(tokenArg) {
+  const token =
+    typeof tokenArg === 'string' && tokenArg.length > 0
+      ? tokenArg
+      : randomBytes(32).toString('base64url');
+  const authorization = `Basic ${Buffer.from(`landstrip:${token}`).toString('base64')}`;
+  return { token, authorization };
+}
+
+function createProxyUrl(port, token, host = '127.0.0.1') {
+  const credentials = typeof token === 'string' && token.length > 0 ? `landstrip:${token}@` : '';
+  return `http://${credentials}${host}:${port}`;
+}
+
+function createProxyEnvironment(port, options, baseEnvArg) {
+  let token = null;
+  let host = '127.0.0.1';
+  let baseEnv = baseEnvArg;
+
+  if (typeof options === 'string') {
+    token = options;
+  } else if (options && typeof options === 'object') {
+    if (typeof options.token === 'string') token = options.token;
+    if (typeof options.host === 'string') host = options.host;
+    if (options.baseEnv && typeof options.baseEnv === 'object') baseEnv = options.baseEnv;
+  }
+
+  const result = baseEnv ? { ...baseEnv } : {};
+  if (!port || typeof port !== 'number' || port <= 0) {
+    return result;
+  }
+
+  const url = createProxyUrl(port, token, host);
+  for (const name of PROXY_ENVIRONMENT_VARIABLES) {
+    result[name] = url;
+  }
+  result.NO_PROXY = '';
+  result.no_proxy = '';
+  return result;
+}
+
 module.exports = {
   startFilterProxy,
+  PROXY_ENVIRONMENT_VARIABLES,
+  createProxyCredentials,
+  createProxyUrl,
+  createProxyEnvironment,
 };

package/lib/shared.d.ts

@@ -2,13 +2,44 @@
 
 import type {
   LandstripControlResponse,
+  LandstripFilesystemPolicy,
   LandstripFilesystemTrap,
+  LandstripNetworkPolicy,
   LandstripNetworkTrap,
+  LandstripPolicy,
   LandstripTrap,
+  LandstripWindowsPolicy,
+  SandboxConfig,
+  SandboxConfigFile,
+  SandboxConfigOverrides,
+  SandboxFilesystemConfig,
+  SandboxFilesystemConfigFile,
+  SandboxNetworkConfig,
+  SandboxNetworkConfigFile,
+  SandboxShellConfig,
+  SandboxShellConfigFile,
+  SandboxWindowsConfig,
+  SandboxWindowsConfigFile,
+  ShellReadAccess,
 } from './index.js';
 
 export type LandstripDenialTrap = LandstripFilesystemTrap | LandstripNetworkTrap;
 
+export type {
+  SandboxConfig,
+  SandboxConfigFile,
+  SandboxConfigOverrides,
+  SandboxFilesystemConfig,
+  SandboxFilesystemConfigFile,
+  SandboxNetworkConfig,
+  SandboxNetworkConfigFile,
+  SandboxShellConfig,
+  SandboxShellConfigFile,
+  SandboxWindowsConfig,
+  SandboxWindowsConfigFile,
+  ShellReadAccess,
+};
+
 export function isRecord(value: unknown): value is Record<string, unknown>;
 
 export function expandHomePath(path: string): string;
@@ -57,3 +88,144 @@ export function controlResponseLine(
   queryId: string,
   action: LandstripControlResponse['action'],
 ): string;
+
+
+export interface BuildLandstripPolicyOptions {
+  filesystem?: LandstripFilesystemPolicy;
+  network?: LandstripNetworkPolicy;
+  windows?: LandstripWindowsPolicy;
+  baseDirectory?: string;
+  httpProxyPort?: number | null;
+  socksProxyPort?: number | null;
+}
+
+export function resolveFilesystemPatterns(
+  patterns: string[] | undefined,
+  baseDirectory?: string,
+): string[];
+
+export function resolveFilesystemPolicy(
+  filesystem?: LandstripFilesystemPolicy,
+  baseDirectory?: string,
+): LandstripFilesystemPolicy;
+
+export function buildLandstripPolicy(
+  options: BuildLandstripPolicyOptions,
+): LandstripPolicy;
+
+export function serializeLandstripPolicy(policy: LandstripPolicy): string;
+
+
+export function mergeArray(base: string[], override?: string[]): string[];
+
+export function parseSandboxConfig(value: unknown): SandboxConfigFile;
+
+export function deepMergeSandboxConfig<T extends SandboxConfig = SandboxConfig>(
+  base: T,
+  overrides?: SandboxConfigFile,
+): T;
+
+
+export type PathAccessDecision = 'allow' | 'ask' | 'deny' | 'denyAlways';
+
+export type DomainAccessDecision = 'allow' | 'ask' | 'deny';
+
+export interface EvaluateReadOptions {
+  baseDirectory?: string;
+  allowReadOverrides?: string[];
+  requireAllowMatch?: boolean;
+}
+
+export interface EvaluateWriteOptions {
+  baseDirectory?: string;
+  allowWriteOverrides?: string[];
+}
+
+export interface EvaluateDomainOptions {
+  allowedDomainsOverrides?: string[];
+}
+
+export function matchesPathPattern(
+  filePath: string,
+  patterns: string[],
+  baseDirectory?: string,
+): boolean;
+
+export function matchPathSpecificity(
+  filePath: string,
+  patterns: string[],
+  baseDirectory?: string,
+): number;
+
+export function isPathReadAllowed(
+  filePath: string,
+  allowRead: string[],
+  denyRead: string[],
+  baseDirectory?: string,
+  options?: { requireAllowMatch?: boolean },
+): boolean;
+
+export function isPathWriteAllowed(
+  filePath: string,
+  allowWrite: string[],
+  baseDirectory?: string,
+): boolean;
+
+export function shouldPromptForWrite(
+  filePath: string,
+  allowWrite: string[],
+  baseDirectory?: string,
+): boolean;
+
+export function evaluateReadAccess(
+  filePath: string,
+  filesystem: SandboxFilesystemConfig | SandboxFilesystemConfigFile | SandboxConfig | SandboxConfigFile,
+  options?: EvaluateReadOptions | string,
+  allowReadOverrides?: string[],
+): 'allow' | 'ask' | 'deny';
+
+export function evaluateWriteAccess(
+  filePath: string,
+  filesystem: SandboxFilesystemConfig | SandboxFilesystemConfigFile | SandboxConfig | SandboxConfigFile,
+  options?: EvaluateWriteOptions | string,
+  allowWriteOverrides?: string[],
+): PathAccessDecision;
+
+export function isDomainAllowed(
+  domain: string,
+  network: SandboxNetworkConfig | SandboxNetworkConfigFile | SandboxConfig | SandboxConfigFile,
+  allowedDomainsOverrides?: string[],
+): boolean;
+
+export function evaluateDomainAccess(
+  domain: string,
+  network: SandboxNetworkConfig | SandboxNetworkConfigFile | SandboxConfig | SandboxConfigFile,
+  options?: EvaluateDomainOptions | string[],
+): DomainAccessDecision;
+
+
+export function normalizeBlockedPath(filePath: string, cwd?: string): string;
+
+export function extractTrapBlockedPath(
+  trapOutput: string,
+  cwd?: string,
+  operation?: 'read' | 'write',
+): string | null;
+export function extractDomainsFromCommand(command: string): string[];
+
+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 interface ExtractDeniedPathOptions {
+  cwd?: string;
+  command?: string;
+}
+
+export function extractDeniedPath(
+  output: string,
+  options?: ExtractDeniedPathOptions | string,
+  command?: string,
+): string | null;

package/lib/shared.js

@@ -347,6 +347,635 @@ function controlResponseLine(queryId, action) {
   return JSON.stringify({ query_id: queryId, action }) + '\n';
 }
 
+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),
+  );
+}
+
+function resolveFilesystemPolicy(filesystem, baseDirectory) {
+  if (!filesystem) return {};
+  const resolved = {};
+  if (filesystem.denyRead !== undefined) {
+    resolved.denyRead = resolveFilesystemPatterns(filesystem.denyRead, baseDirectory);
+  }
+  if (filesystem.denyReadAlways !== undefined) {
+    resolved.denyReadAlways = resolveFilesystemPatterns(filesystem.denyReadAlways, baseDirectory);
+  }
+  if (filesystem.allowRead !== undefined) {
+    resolved.allowRead = resolveFilesystemPatterns(filesystem.allowRead, baseDirectory);
+  }
+  if (filesystem.allowWrite !== undefined) {
+    resolved.allowWrite = resolveFilesystemPatterns(filesystem.allowWrite, baseDirectory);
+  }
+  if (filesystem.denyWrite !== undefined) {
+    resolved.denyWrite = resolveFilesystemPatterns(filesystem.denyWrite, baseDirectory);
+  }
+  if (filesystem.denyWriteAlways !== undefined) {
+    resolved.denyWriteAlways = resolveFilesystemPatterns(filesystem.denyWriteAlways, baseDirectory);
+  }
+  return resolved;
+}
+
+function buildLandstripPolicy(options) {
+  const policy = {};
+  if (options.network) {
+    const net = {
+      allowNetwork: Boolean(options.network.allowNetwork),
+      allowLocalBinding: Boolean(options.network.allowLocalBinding),
+      allowAllUnixSockets: Boolean(options.network.allowAllUnixSockets),
+      allowUnixSockets: Array.isArray(options.network.allowUnixSockets)
+        ? [...options.network.allowUnixSockets]
+        : [],
+    };
+    const httpProxyPort =
+      options.httpProxyPort !== undefined
+        ? options.httpProxyPort
+        : options.network.httpProxyPort;
+    if (httpProxyPort !== null && httpProxyPort !== undefined) {
+      net.httpProxyPort = httpProxyPort;
+    }
+    const socksProxyPort =
+      options.socksProxyPort !== undefined
+        ? options.socksProxyPort
+        : options.network.socksProxyPort;
+    if (socksProxyPort !== null && socksProxyPort !== undefined) {
+      net.socksProxyPort = socksProxyPort;
+    }
+    policy.network = net;
+  }
+  if (options.filesystem) {
+    policy.filesystem = resolveFilesystemPolicy(
+      options.filesystem,
+      options.baseDirectory,
+    );
+  }
+  if (options.windows) {
+    policy.windows = {
+      appContainerMode: options.windows.appContainerMode ?? 'lpac',
+      allowLoopback: Boolean(options.windows.allowLoopback),
+    };
+  }
+  return policy;
+}
+
+function serializeLandstripPolicy(policy) {
+  return JSON.stringify(policy, null, 2) + '\n';
+}
+
+function requireSandboxObject(value, label) {
+  if (!isRecord(value)) {
+    throw new Error(`${label} must be an object`);
+  }
+}
+
+function rejectUnknownSandboxFields(value, allowed, prefix = '') {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) {
+      throw new Error(`unknown sandbox field ${prefix}${key}`);
+    }
+  }
+}
+
+function validateBooleanFields(value, fields, prefix = '') {
+  for (const field of fields) {
+    if (value[field] !== undefined && typeof value[field] !== 'boolean') {
+      throw new Error(`${prefix}${field} must be a boolean`);
+    }
+  }
+}
+
+function validateStringArrayFields(value, fields, prefix = '') {
+  for (const field of fields) {
+    const entry = value[field];
+    if (entry === undefined) continue;
+    if (!Array.isArray(entry) || entry.some((item) => typeof item !== 'string')) {
+      throw new Error(`${prefix}${field} must be an array of strings`);
+    }
+  }
+}
+
+function mergeArray(base, override) {
+  if (!override) return base;
+  return [...new Set([...(base ?? []), ...override])];
+}
+
+function parseSandboxConfig(value) {
+  requireSandboxObject(value, 'sandbox config');
+  rejectUnknownSandboxFields(value, ['enabled', 'shell', 'network', 'filesystem', 'windows']);
+  validateBooleanFields(value, ['enabled']);
+
+  const config = {};
+  if (value.enabled !== undefined) {
+    config.enabled = value.enabled;
+  }
+
+  if (value.shell !== undefined) {
+    requireSandboxObject(value.shell, 'shell');
+    rejectUnknownSandboxFields(value.shell, ['readAccess'], 'shell.');
+    if (
+      value.shell.readAccess !== undefined &&
+      value.shell.readAccess !== 'host' &&
+      value.shell.readAccess !== 'policy'
+    ) {
+      throw new Error('shell.readAccess must be host or policy');
+    }
+    config.shell = { ...value.shell };
+  }
+
+  if (value.network !== undefined) {
+    requireSandboxObject(value.network, 'network');
+    rejectUnknownSandboxFields(
+      value.network,
+      [
+        'allowNetwork',
+        'allowLocalBinding',
+        'allowAllUnixSockets',
+        'allowUnixSockets',
+        'allowedDomains',
+        'deniedDomains',
+      ],
+      'network.',
+    );
+    validateBooleanFields(
+      value.network,
+      ['allowNetwork', 'allowLocalBinding', 'allowAllUnixSockets'],
+      'network.',
+    );
+    validateStringArrayFields(
+      value.network,
+      ['allowUnixSockets', 'allowedDomains', 'deniedDomains'],
+      'network.',
+    );
+    config.network = {};
+    if (value.network.allowNetwork !== undefined) {
+      config.network.allowNetwork = value.network.allowNetwork;
+    }
+    if (value.network.allowLocalBinding !== undefined) {
+      config.network.allowLocalBinding = value.network.allowLocalBinding;
+    }
+    if (value.network.allowAllUnixSockets !== undefined) {
+      config.network.allowAllUnixSockets = value.network.allowAllUnixSockets;
+    }
+    if (value.network.allowUnixSockets !== undefined) {
+      config.network.allowUnixSockets = [...value.network.allowUnixSockets];
+    }
+    if (value.network.allowedDomains !== undefined) {
+      config.network.allowedDomains = [...value.network.allowedDomains];
+    }
+    if (value.network.deniedDomains !== undefined) {
+      config.network.deniedDomains = [...value.network.deniedDomains];
+    }
+  }
+
+  if (value.filesystem !== undefined) {
+    requireSandboxObject(value.filesystem, 'filesystem');
+    rejectUnknownSandboxFields(
+      value.filesystem,
+      ['denyRead', 'denyReadAlways', 'allowRead', 'allowWrite', 'denyWrite', 'denyWriteAlways'],
+      'filesystem.',
+    );
+    validateStringArrayFields(
+      value.filesystem,
+      ['denyRead', 'denyReadAlways', 'allowRead', 'allowWrite', 'denyWrite', 'denyWriteAlways'],
+      'filesystem.',
+    );
+    config.filesystem = {};
+    if (value.filesystem.denyRead !== undefined) {
+      config.filesystem.denyRead = [...value.filesystem.denyRead];
+    }
+    if (value.filesystem.denyReadAlways !== undefined) {
+      config.filesystem.denyReadAlways = [...value.filesystem.denyReadAlways];
+    }
+    if (value.filesystem.allowRead !== undefined) {
+      config.filesystem.allowRead = [...value.filesystem.allowRead];
+    }
+    if (value.filesystem.allowWrite !== undefined) {
+      config.filesystem.allowWrite = [...value.filesystem.allowWrite];
+    }
+    if (value.filesystem.denyWrite !== undefined) {
+      config.filesystem.denyWrite = [...value.filesystem.denyWrite];
+    }
+    if (value.filesystem.denyWriteAlways !== undefined) {
+      config.filesystem.denyWriteAlways = [...value.filesystem.denyWriteAlways];
+    }
+  }
+
+  if (value.windows !== undefined) {
+    requireSandboxObject(value.windows, 'windows');
+    rejectUnknownSandboxFields(value.windows, ['appContainerMode', 'allowLoopback'], 'windows.');
+    if (
+      value.windows.appContainerMode !== undefined &&
+      value.windows.appContainerMode !== 'standard' &&
+      value.windows.appContainerMode !== 'lpac'
+    ) {
+      throw new Error('windows.appContainerMode must be lpac or standard');
+    }
+    validateBooleanFields(value.windows, ['allowLoopback'], 'windows.');
+    config.windows = {};
+    if (value.windows.appContainerMode !== undefined) {
+      config.windows.appContainerMode = value.windows.appContainerMode;
+    }
+    if (value.windows.allowLoopback !== undefined) {
+      config.windows.allowLoopback = value.windows.allowLoopback;
+    }
+  }
+
+  return config;
+}
+
+function deepMergeSandboxConfig(base, overrides) {
+  if (!overrides) return { ...base };
+
+  const shell = overrides.shell;
+  const network = overrides.network;
+  const filesystem = overrides.filesystem;
+  const windows = overrides.windows;
+
+  const result = {
+    enabled: overrides.enabled ?? base.enabled,
+    network: {
+      allowNetwork: network?.allowNetwork ?? base.network?.allowNetwork ?? false,
+      allowLocalBinding: network?.allowLocalBinding ?? base.network?.allowLocalBinding ?? false,
+      allowAllUnixSockets: network?.allowAllUnixSockets ?? base.network?.allowAllUnixSockets ?? false,
+      allowUnixSockets: mergeArray(base.network?.allowUnixSockets, network?.allowUnixSockets),
+      allowedDomains: mergeArray(base.network?.allowedDomains, network?.allowedDomains),
+      deniedDomains: mergeArray(base.network?.deniedDomains, network?.deniedDomains),
+    },
+    filesystem: {
+      denyRead: mergeArray(base.filesystem?.denyRead, filesystem?.denyRead),
+      denyReadAlways: mergeArray(base.filesystem?.denyReadAlways, filesystem?.denyReadAlways),
+      allowRead: mergeArray(base.filesystem?.allowRead, filesystem?.allowRead),
+      allowWrite: mergeArray(base.filesystem?.allowWrite, filesystem?.allowWrite),
+      denyWrite: mergeArray(base.filesystem?.denyWrite, filesystem?.denyWrite),
+      denyWriteAlways: mergeArray(base.filesystem?.denyWriteAlways, filesystem?.denyWriteAlways),
+    },
+  };
+
+  if (base.shell !== undefined || shell !== undefined) {
+    result.shell = {
+      readAccess: shell?.readAccess ?? base.shell?.readAccess ?? 'host',
+    };
+  }
+
+  if (base.windows !== undefined || windows !== undefined) {
+    result.windows = {
+      appContainerMode: windows?.appContainerMode ?? base.windows?.appContainerMode ?? 'standard',
+      allowLoopback: windows?.allowLoopback ?? base.windows?.allowLoopback ?? false,
+    };
+  }
+
+  return result;
+}
+
+
+function normalizePathForComparison(filePath) {
+  const normalized = normalizePathSeparators(filePath);
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+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));
+
+    if (/[*?[\]]/.test(pattern)) {
+      const matcher = globToRegExp(absPattern);
+      for (let candidate = abs; ;) {
+        if (matcher.test(candidate)) return true;
+        const parent = normalizePathSeparators(dirname(candidate));
+        if (parent === candidate) break;
+        candidate = process.platform === 'win32' ? parent.toLowerCase() : parent;
+      }
+      return false;
+    }
+
+    const sepChar = absPattern.endsWith('/') ? '' : '/';
+    return abs === absPattern || abs.startsWith(absPattern + sepChar);
+  });
+}
+
+function matchPathSpecificity(filePath, patterns, baseDirectory = process.cwd()) {
+  if (!Array.isArray(patterns) || patterns.length === 0) return -1;
+  let best = -1;
+  for (const pattern of patterns) {
+    if (!matchesPathPattern(filePath, [pattern], baseDirectory)) continue;
+    const canonical = canonicalizeGlobPattern(pattern, baseDirectory);
+    if (canonical.length > best) {
+      best = canonical.length;
+    }
+  }
+  return best;
+}
+
+function isPathReadAllowed(
+  filePath,
+  allowRead,
+  denyRead,
+  baseDirectory = process.cwd(),
+  options,
+) {
+  const allowPatterns = Array.isArray(allowRead) ? allowRead : [];
+  const denyPatterns = Array.isArray(denyRead) ? denyRead : [];
+  const allow = matchPathSpecificity(filePath, allowPatterns, baseDirectory);
+  const deny = matchPathSpecificity(filePath, denyPatterns, baseDirectory);
+
+  if (options && options.requireAllowMatch) {
+    return allow >= 0 && allow >= deny;
+  }
+  if (deny < 0) return true;
+  return allow >= deny;
+}
+
+function isPathWriteAllowed(filePath, allowWrite, baseDirectory = process.cwd()) {
+  const allowPatterns = Array.isArray(allowWrite) ? allowWrite : [];
+  return allowPatterns.length > 0 && matchesPathPattern(filePath, allowPatterns, baseDirectory);
+}
+
+function shouldPromptForWrite(filePath, allowWrite, baseDirectory = process.cwd()) {
+  return !isPathWriteAllowed(filePath, allowWrite, baseDirectory);
+}
+
+function normalizeReadOptions(options, allowReadOverrides) {
+  if (typeof options === 'string') {
+    return {
+      baseDirectory: options,
+      allowReadOverrides: Array.isArray(allowReadOverrides) ? allowReadOverrides : [],
+      requireAllowMatch: false,
+    };
+  }
+  return {
+    baseDirectory: options?.baseDirectory,
+    allowReadOverrides: options?.allowReadOverrides ?? (Array.isArray(allowReadOverrides) ? allowReadOverrides : []),
+    requireAllowMatch: options?.requireAllowMatch ?? false,
+  };
+}
+
+function evaluateReadAccess(filePath, filesystemOrConfig, options, allowReadOverrides) {
+  const filesystem = filesystemOrConfig && 'filesystem' in filesystemOrConfig ? filesystemOrConfig.filesystem : (filesystemOrConfig ?? {});
+  const opts = normalizeReadOptions(options, allowReadOverrides);
+  const baseDirectory = opts.baseDirectory;
+
+  if (filesystem.denyReadAlways && matchesPathPattern(filePath, filesystem.denyReadAlways, baseDirectory)) {
+    return 'deny';
+  }
+
+  const effectiveAllowRead = opts.allowReadOverrides.length > 0
+    ? mergeArray(filesystem.allowRead ?? [], opts.allowReadOverrides)
+    : (filesystem.allowRead ?? []);
+
+  if (isPathReadAllowed(filePath, effectiveAllowRead, filesystem.denyRead ?? [], baseDirectory, { requireAllowMatch: opts.requireAllowMatch })) {
+    return 'allow';
+  }
+
+  return 'ask';
+}
+
+function normalizeWriteOptions(options, allowWriteOverrides) {
+  if (typeof options === 'string') {
+    return {
+      baseDirectory: options,
+      allowWriteOverrides: Array.isArray(allowWriteOverrides) ? allowWriteOverrides : [],
+    };
+  }
+  return {
+    baseDirectory: options?.baseDirectory,
+    allowWriteOverrides: options?.allowWriteOverrides ?? (Array.isArray(allowWriteOverrides) ? allowWriteOverrides : []),
+  };
+}
+
+function evaluateWriteAccess(filePath, filesystemOrConfig, options, allowWriteOverrides) {
+  const filesystem = filesystemOrConfig && 'filesystem' in filesystemOrConfig ? filesystemOrConfig.filesystem : (filesystemOrConfig ?? {});
+  const opts = normalizeWriteOptions(options, allowWriteOverrides);
+  const baseDirectory = opts.baseDirectory;
+
+  if (filesystem.denyWriteAlways && matchesPathPattern(filePath, filesystem.denyWriteAlways, baseDirectory)) {
+    return 'denyAlways';
+  }
+
+  if (filesystem.denyWrite && matchesPathPattern(filePath, filesystem.denyWrite, baseDirectory)) {
+    return 'deny';
+  }
+
+  const effectiveAllowWrite = opts.allowWriteOverrides.length > 0
+    ? mergeArray(filesystem.allowWrite ?? [], opts.allowWriteOverrides)
+    : (filesystem.allowWrite ?? []);
+
+  if (effectiveAllowWrite.length > 0 && matchesPathPattern(filePath, effectiveAllowWrite, baseDirectory)) {
+    return 'allow';
+  }
+
+  return 'ask';
+}
+
+function isDomainAllowed(domain, networkOrConfig, allowedDomainsOverrides) {
+  const network = networkOrConfig && 'network' in networkOrConfig ? networkOrConfig.network : (networkOrConfig ?? {});
+  if (network.allowNetwork) return true;
+  const denied = network.deniedDomains ?? [];
+  if (domainMatchesAny(domain, denied)) return false;
+  const effectiveAllowed = Array.isArray(allowedDomainsOverrides) && allowedDomainsOverrides.length > 0
+    ? mergeArray(network.allowedDomains ?? [], allowedDomainsOverrides)
+    : (network.allowedDomains ?? []);
+  return domainMatchesAny(domain, effectiveAllowed);
+}
+
+function evaluateDomainAccess(domain, networkOrConfig, options) {
+  const network = networkOrConfig && 'network' in networkOrConfig ? networkOrConfig.network : (networkOrConfig ?? {});
+  if (network.allowNetwork) return 'allow';
+  const overrides = Array.isArray(options) ? options : options?.allowedDomainsOverrides;
+  const denied = network.deniedDomains ?? [];
+  if (domainMatchesAny(domain, denied)) return 'deny';
+  const effectiveAllowed = Array.isArray(overrides) && overrides.length > 0
+    ? mergeArray(network.allowedDomains ?? [], overrides)
+    : (network.allowedDomains ?? []);
+  if (domainMatchesAny(domain, effectiveAllowed)) return 'allow';
+  return 'ask';
+}
+
+
+function isPathLike(value) {
+  if (typeof value !== 'string') return false;
+  const trimmed = value.trim();
+  return (
+    trimmed === '~' ||
+    trimmed.startsWith('/') ||
+    trimmed.startsWith('\\\\') ||
+    /^[a-zA-Z]:[\\/]/.test(trimmed) ||
+    trimmed.startsWith('~/') ||
+    trimmed.startsWith('~\\') ||
+    trimmed.startsWith('./') ||
+    trimmed.startsWith('.\\') ||
+    trimmed.startsWith('../') ||
+    trimmed.startsWith('..\\') ||
+    trimmed.startsWith('.') ||
+    trimmed.includes('/') ||
+    trimmed.includes('\\')
+  );
+}
+
+function normalizeBlockedPath(filePath, cwd = process.cwd()) {
+  const nativePath =
+    process.platform === 'win32' && /^\/[a-zA-Z](?:\/|$)/.test(filePath)
+      ? `${filePath[1]}:${filePath.slice(2)}`
+      : filePath;
+  return canonicalizePath(isAbsolute(nativePath) ? nativePath : join(cwd, nativePath), cwd);
+}
+
+function normalizePathMatch(value, cwd) {
+  return isPathLike(value) ? normalizeBlockedPath(value, cwd) : null;
+}
+
+function extractDomainsFromCommand(command) {
+  if (typeof command !== 'string') return [];
+  const domains = [];
+  const urlRegex = /https?:\/\/([^\s/:?#'"]+)(?::\d+)?(?:[/?#]|\s|$)/g;
+  let match;
+  while ((match = urlRegex.exec(command)) !== null) {
+    const domain = match[1].toLowerCase();
+    if (!domains.includes(domain)) {
+      domains.push(domain);
+    }
+  }
+  return domains;
+}
+
+function extractCandidatePaths(command) {
+  if (typeof command !== 'string') return [];
+  const paths = [];
+  const tokens = command.match(/(?:[^\s"']+|"[^"]*"|'[^']*')+/g) ?? [];
+  for (const rawToken of tokens) {
+    const token = rawToken.replace(/^["']|["']$/g, '');
+    const clean = token.replace(/^[<>&|;]+|[<>&|;]+$/g, '');
+    if (
+      clean.length > 0 &&
+      !clean.startsWith('-') &&
+      (clean.startsWith('/') ||
+        clean.startsWith('./') ||
+        clean.startsWith('../') ||
+        clean.startsWith('~/') ||
+        clean.startsWith('\\\\') ||
+        clean.startsWith('~\\') ||
+        clean.startsWith('.\\') ||
+        clean.startsWith('..\\') ||
+        /^[a-zA-Z]:[\\/]/.test(clean))
+    ) {
+      if (!paths.includes(clean)) {
+        paths.push(clean);
+      }
+    }
+  }
+  return paths;
+}
+
+function extractNativeDeniedPath(output, cwd = process.cwd()) {
+  if (typeof output !== 'string') return null;
+  const denial = String.raw`(?:Access is denied\.?|Operation not permitted|Permission denied)`;
+  let match = output.match(new RegExp(String.raw`['"]([^'"\n]+)['"][^\r\n]{0,120}${denial}`, 'i'));
+  if (match) return normalizePathMatch(match[1], cwd);
+
+  // bash/sh and native Windows tools: line X: /path: Permission denied,
+  // or cmd: C:\path: Access is denied.
+  match = output.match(
+    new RegExp(
+      String.raw`(?:^|:\s+)((?:[a-zA-Z]:[\\/]|\\\\|/|\.{1,2}[\\/])[^:\r\n]*?):\s+${denial}$`,
+      'im',
+    ),
+  );
+  if (match) return normalizePathMatch(match[1], cwd);
+
+  // ls/cat/cp: cannot open/access/stat '/path': Permission denied
+  match = output.match(
+    new RegExp(
+      String.raw`^[a-zA-Z0-9_-]+: cannot (?:open|access|stat|create)(?: directory)? '?([^'\n]+?)'?(?: for (?:reading|writing))?: ${denial}$`,
+      'im',
+    ),
+  );
+  if (match) return normalizePathMatch(match[1], cwd);
+
+  return null;
+}
+
+function extractNativeWriteDeniedPath(output, cwd = process.cwd()) {
+  if (typeof output !== 'string') return null;
+  const denial = String.raw`(?:Access is denied\.?|Operation not permitted|Permission denied)`;
+  let match = output.match(
+    new RegExp(
+      String.raw`(?:[Uu]nable to create|failed to create(?: directory)?|cannot (?:create|touch|mkdir|remove|unlink|rename)|for writing)[^'"\x60\r\n]*['"\x60]([^'"\x60\r\n]+)['"\x60](?:[^\r\n]*\r?\n){0,3}[^\r\n]{0,120}${denial}`,
+      'im',
+    ),
+  );
+  if (match) return normalizePathMatch(match[1], cwd);
+
+  match = output.match(
+    new RegExp(
+      String.raw`^[a-zA-Z0-9_-]+: cannot create(?: directory)? '?([^'\n]+?)'?(?: for writing)?: ${denial}$`,
+      'im',
+    ),
+  );
+  if (match) return normalizePathMatch(match[1], cwd);
+
+
+  match = output.match(
+    new RegExp(
+      String.raw`^[a-zA-Z0-9_-]+: couldn't open temporary file ((?:[a-zA-Z]:[\\/]|\\\\|/)[^:\r\n]*?): ${denial}$`,
+      'im',
+    ),
+  );
+  if (match) return normalizePathMatch(match[1], cwd);
+
+  return null;
+}
+
+function extractTrapBlockedPath(trapOutput, cwd = process.cwd(), operation) {
+  if (typeof trapOutput !== 'string') return null;
+  const traps = parseLandstripTraps(trapOutput);
+  for (const trap of traps) {
+    if (isFilesystemTrap(trap) && (!operation || trap.operation === operation)) {
+      return normalizeBlockedPath(trap.path, cwd);
+    }
+  }
+  return null;
+}
+
+function extractDeniedPath(output, options, commandArg) {
+  if (typeof output !== 'string') return null;
+  let cwd = process.cwd();
+  let command = commandArg;
+  if (typeof options === 'string') {
+    cwd = options;
+  } else if (options && typeof options === 'object') {
+    if (typeof options.cwd === 'string') cwd = options.cwd;
+    if (typeof options.command === 'string') command = options.command;
+  }
+
+  // 1. Structured traps
+  const landstripTraps = parseLandstripTraps(output);
+  const trapped = extractTrapBlockedPath(output, cwd);
+  if (trapped) return trapped;
+
+  // 2. Native shell/tool error messages
+  const nativeMatch = extractNativeDeniedPath(output, cwd);
+  if (nativeMatch) return nativeMatch;
+
+  // 3. Fallback: if landstrip trapped but path wasn't specified, inspect command candidates
+  if (
+    command &&
+    landstripTraps.some((trap) => trap.kind === 'filesystem' || trap.kind === 'internal')
+  ) {
+    for (const candidate of extractCandidatePaths(command)) {
+      return normalizeBlockedPath(candidate, cwd);
+    }
+  }
+
+  return null;
+}
+
 module.exports = {
   isRecord,
   expandHomePath,
@@ -371,4 +1000,30 @@ module.exports = {
   formatLandstripTrap,
   formatLandstripTraps,
   controlResponseLine,
+  resolveFilesystemPatterns,
+  resolveFilesystemPolicy,
+  buildLandstripPolicy,
+  serializeLandstripPolicy,
+  mergeArray,
+  parseSandboxConfig,
+  deepMergeSandboxConfig,
+
+  normalizePathForComparison,
+  matchesPathPattern,
+  matchPathSpecificity,
+  isPathReadAllowed,
+  isPathWriteAllowed,
+  shouldPromptForWrite,
+  evaluateReadAccess,
+  evaluateWriteAccess,
+  isDomainAllowed,
+  evaluateDomainAccess,
+
+  normalizeBlockedPath,
+  extractTrapBlockedPath,
+  extractDomainsFromCommand,
+  extractCandidatePaths,
+  extractNativeDeniedPath,
+  extractNativeWriteDeniedPath,
+  extractDeniedPath,
 };

package/package.json

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