QueryContext

The QueryContext class allows you to query whether filesystem or network operations would be permitted by a given capability set. This is useful for:

Testing your sandbox configuration before applying it
Debugging permission issues
Building tools that preview sandbox effects

Constructor

constructor(caps: CapabilitySet)

Create a new query context from a capability set.

CapabilitySet

required

The capability set to query against.

import { CapabilitySet, QueryContext, AccessMode } from 'nono-ts';

const caps = new CapabilitySet();
caps.allowPath('/tmp', AccessMode.ReadWrite);
caps.blockNetwork();

const query = new QueryContext(caps);

Methods

queryPath

queryPath(path: string, mode: AccessMode): QueryResultInfo

Query whether a filesystem operation would be permitted.

string

required

The path to check access for.

AccessMode

required

The access mode to check: Read, Write, or ReadWrite.

QueryResultInfo

Result object describing whether access would be allowed or denied.

const result = query.queryPath('/tmp/test.txt', AccessMode.Write);

if (result.status === 'allowed') {
  console.log(`Access granted via: ${result.grantedPath}`);
  console.log(`Access level: ${result.access}`);
} else {
  console.log(`Access denied: ${result.reason}`);
}

queryNetwork

queryNetwork(): QueryResultInfo

Query whether network access would be permitted.

QueryResultInfo

Result object describing whether network access would be allowed or denied.

const result = query.queryNetwork();

if (result.status === 'allowed') {
  console.log('Network access is permitted');
} else {
  console.log('Network access is blocked');
}

QueryResultInfo

The result of a query operation.

Properties

string

required

Either "allowed" or "denied".

string

required

The reason for the result. Possible values:For allowed results:

"granted_path" — Access granted by a filesystem capability
"network_allowed" — Network access is not blocked

For denied results:

"path_not_granted" — No capability covers this path
"insufficient_access" — Path is covered but with insufficient permissions
"network_blocked" — Network access has been blocked

string | undefined

For granted_path results, the path of the capability that grants access.

string | undefined

For granted_path results, the access level of the granting capability.

string | undefined

For insufficient_access results, the access level that was granted.

string | undefined

For insufficient_access results, the access level that was requested.

Examples

Testing Filesystem Access

import { CapabilitySet, QueryContext, AccessMode } from 'nono-ts';

const caps = new CapabilitySet();
caps.allowPath('/var/data', AccessMode.Read);
caps.allowPath('/tmp', AccessMode.ReadWrite);

const query = new QueryContext(caps);

// Test various paths
const tests = [
  { path: '/var/data/file.json', mode: AccessMode.Read },
  { path: '/var/data/file.json', mode: AccessMode.Write },
  { path: '/tmp/cache.txt', mode: AccessMode.ReadWrite },
  { path: '/etc/passwd', mode: AccessMode.Read },
];

for (const test of tests) {
  const result = query.queryPath(test.path, test.mode);
  const modeStr = AccessMode[test.mode];
  console.log(`${test.path} (${modeStr}): ${result.status} - ${result.reason}`);
}

// Output:
// /var/data/file.json (Read): allowed - granted_path
// /var/data/file.json (Write): denied - insufficient_access
// /tmp/cache.txt (ReadWrite): allowed - granted_path
// /etc/passwd (Read): denied - path_not_granted

Insufficient Access Detection

const caps = new CapabilitySet();
caps.allowPath('/data', AccessMode.Read);

const query = new QueryContext(caps);
const result = query.queryPath('/data/output.txt', AccessMode.Write);

if (result.reason === 'insufficient_access') {
  console.log(`Permission denied: granted ${result.granted}, requested ${result.requested}`);
  // Output: Permission denied: granted read, requested write
}

Validating Configuration

function validateSandboxConfig(
  caps: CapabilitySet,
  requiredPaths: Array<{ path: string; mode: AccessMode }>
): string[] {
  const query = new QueryContext(caps);
  const errors: string[] = [];

  for (const { path, mode } of requiredPaths) {
    const result = query.queryPath(path, mode);
    if (result.status === 'denied') {
      errors.push(`Missing access: ${path} (${AccessMode[mode]}) - ${result.reason}`);
    }
  }

  return errors;
}

// Usage
const caps = new CapabilitySet();
caps.allowPath('/app', AccessMode.Read);

const required = [
  { path: '/app/config.json', mode: AccessMode.Read },
  { path: '/app/logs', mode: AccessMode.Write },
  { path: '/tmp', mode: AccessMode.ReadWrite },
];

const errors = validateSandboxConfig(caps, required);
if (errors.length > 0) {
  console.error('Sandbox configuration incomplete:');
  errors.forEach(e => console.error(`  - ${e}`));
}

Network Access Check

const caps = new CapabilitySet();
// Network is allowed by default

const query = new QueryContext(caps);
console.log(query.queryNetwork());
// { status: 'allowed', reason: 'network_allowed' }

caps.blockNetwork();
const queryBlocked = new QueryContext(caps);
console.log(queryBlocked.queryNetwork());
// { status: 'denied', reason: 'network_blocked' }

Getting Started

API Reference

Examples

Constructor

Methods

queryPath

queryNetwork

QueryResultInfo

Properties

Examples

Testing Filesystem Access

Insufficient Access Detection

Validating Configuration

Network Access Check

​Constructor

​Methods

​queryPath

​queryNetwork

​QueryResultInfo

​Properties

​Examples

​Testing Filesystem Access

​Insufficient Access Detection

​Validating Configuration

​Network Access Check

Constructor

Methods

queryPath

queryNetwork

QueryResultInfo

Properties

Examples

Testing Filesystem Access

Insufficient Access Detection

Validating Configuration

Network Access Check