Systems

vcapability

File, network and process access, only for code handed the token.

Released v1.0.0 · 2026-09-28

Import

use "stdlib/capability.ven"

Capability based access to files, the network and other processes: a program is handed an explicit token for what it may touch, and every call through the module's wrappers is checked against it and denied unless it matches. Path checks resolve dots and relative segments but not symlinks, and code that calls a builtin directly, instead of a wrapper, sits outside the check.

vcapability.ven

Reference (39 functions)

Matching helpers (exposed, so a caller can build their own checks)
Capability-gated file/network/process access
Functions
Sandbox entry point
Ambient-authority revocation (manual, one-shot, irreversible)
Functions

API reference

Matching helpers (exposed, so a caller can build their own checks)

`path_within(path, prefix)`

True when path, once resolved to an absolute, '..'-collapsed form, is prefix itself or a real descendant of it.

print(path_within("/tmp/sandbox/a.txt", "/tmp/sandbox"))
print(path_within("/tmp/sandbox-evil/a.txt", "/tmp/sandbox"))

`host_matches(host, pattern)`

True when host matches pattern, where pattern is either an exact host name or a leading-wildcard suffix pattern.

print(host_matches("api.example.com", "*.example.com"))
print(host_matches("example.com", "*.example.com"))
print(host_matches("evil.com", "*.example.com"))

`allows_file_read(capabilities, path)`

True when some FileReadCapability in capabilities covers path.

caps = [FileReadCapability("/tmp/in")]
print(allows_file_read(caps, "/tmp/in/data.csv"))

`allows_file_write(capabilities, path)`

True when some FileWriteCapability in capabilities covers path.

caps = [FileWriteCapability("/tmp/out")]
print(allows_file_write(caps, "/tmp/out/report.txt"))

`allows_network(capabilities, host)`

True when some NetworkCapability in capabilities covers host.

caps = [NetworkCapability("*.example.com")]
print(allows_network(caps, "api.example.com"))

`allows_process(capabilities, command_text)`

True when some ProcessCapability in capabilities covers command_text, the already space-joined full command line.

caps = [ProcessCapability("git ")]
print(allows_process(caps, "git status"))

`allows_environment(capabilities, name)`

True when some EnvironmentCapability in capabilities covers the environment variable named name.

caps = [EnvironmentCapability("AWS_")]
print(allows_environment(caps, "AWS_SECRET_KEY"))

Capability-gated file/network/process access

`cap_read_file(capabilities, path)`

Reads the file at path as Text, after checking a granted FileReadCapability covers it.

caps = [FileReadCapability("/tmp/sandbox")]
print(cap_read_file(caps, "/tmp/sandbox/notes.txt"))

`cap_write_file(capabilities, path, text)`

Writes text to the file at path, replacing its contents, after checking a granted FileWriteCapability covers it.

caps = [FileWriteCapability("/tmp/sandbox")]
cap_write_file(caps, "/tmp/sandbox/out.txt", "hello")

`cap_append_file(capabilities, path, text)`

Appends text to the file at path, after checking a granted FileWriteCapability covers it.

caps = [FileWriteCapability("/tmp/sandbox")]
cap_append_file(caps, "/tmp/sandbox/log.txt", "one more line\n")

`cap_delete_file(capabilities, path)`

Deletes the file at path, after checking a granted FileWriteCapability covers it.

caps = [FileWriteCapability("/tmp/sandbox")]
cap_delete_file(caps, "/tmp/sandbox/scratch.txt")

`cap_file_exists(capabilities, path)`

Checks whether the file at path exists, after checking a granted FileReadCapability covers it.

caps = [FileReadCapability("/tmp/sandbox")]
print(cap_file_exists(caps, "/tmp/sandbox/notes.txt"))

`cap_copy_file(capabilities, src, dst)`

Copies the file at src to dst, after checking a granted FileReadCapability covers the source and a granted FileWriteCapability covers the destination.

caps = [FileReadCapability("/tmp/in"), FileWriteCapability("/tmp/out")]
cap_copy_file(caps, "/tmp/in/a.txt", "/tmp/out/a.txt")

`cap_http_get(capabilities, url)`

Issues an HTTP GET to url, after checking a granted NetworkCapability covers the URL's host.

caps = [NetworkCapability("*.example.com")]
response = cap_http_get(caps, "https://api.example.com/status")
print(response)

`cap_http_post(capabilities, url, body)`

Issues an HTTP POST of body to url, after checking a granted NetworkCapability covers the URL's host.

caps = [NetworkCapability("*.example.com")]
response = cap_http_post(caps, "https://api.example.com/events", "{\"ok\":true}")

`cap_tcp_connect(capabilities, host, port)`

Opens a raw TCP connection to host on port, after checking a granted NetworkCapability covers host.

caps = [NetworkCapability("api.example.com")]
conn = cap_tcp_connect(caps, "api.example.com", 443)

`cap_run_command(capabilities, command, timeout_ms = nothing)`

Runs command (a List of program and argument Text values), after checking a granted ProcessCapability covers its full, space-joined command line.

caps = [ProcessCapability("git ")]
result = cap_run_command(caps, ["git", "status"])
print(result)

`cap_remove_directory(capabilities, path, recursive = nothing)`

Removes the directory at path, after checking a granted FileWriteCapability covers it.

caps = [FileWriteCapability("/tmp/sandbox")]
cap_remove_directory(caps, "/tmp/sandbox/scratch", yes)

`cap_move_path(capabilities, src, dst)`

Moves the path at src to dst, after checking a granted FileWriteCapability covers both src and dst.

caps = [FileWriteCapability("/tmp/sandbox")]
cap_move_path(caps, "/tmp/sandbox/old.txt", "/tmp/sandbox/new.txt")

`cap_environment_variable(capabilities, name)`

Reads the environment variable named name, after checking a granted EnvironmentCapability covers it.

caps = [EnvironmentCapability("AWS_")]
key = cap_environment_variable(caps, "AWS_SECRET_KEY")

`capabilities_for_role(registry, role_name)`

Looks up role_name in registry (a List of RoleCapabilities) and gives back the capabilities that role grants.

registry = [RoleCapabilities("auditor", [FileReadCapability("/var/log")])]
caps = capabilities_for_role(registry, "auditor")
missing = capabilities_for_role(registry, "typo-role")
print(length(missing))

Sandbox entry point

`run_sandboxed(fn, capabilities)`

Runs fn(capabilities) and nothing more.

make my_step(caps)
    give cap_read_file(caps, "/tmp/in/data.csv")

result = run_sandboxed(my_step, [FileReadCapability("/tmp/in")])

Ambient-authority revocation (manual, one-shot, irreversible)

`revoked_read_file(*args)`

A one-shot kill switch for read_file: assign this to the name read_file at your own script's top level to make every later call to read_file raise, for the rest of the process.

read_file = revoked_read_file

`revoked_write_file(*args)`

A one-shot kill switch for write_file: assign this to the name write_file at your own script's top level to make every later call to write_file raise, for the rest of the process.

write_file = revoked_write_file

`revoked_append_file(*args)`

A one-shot kill switch for append_file: assign this to the name append_file at your own script's top level to make every later call to append_file raise, for the rest of the process.

append_file = revoked_append_file

`revoked_delete_file(*args)`

A one-shot kill switch for delete_file: assign this to the name delete_file at your own script's top level to make every later call to delete_file raise, for the rest of the process.

delete_file = revoked_delete_file

`revoked_copy_file(*args)`

A one-shot kill switch for copy_file: assign this to the name copy_file at your own script's top level to make every later call to copy_file raise, for the rest of the process.

copy_file = revoked_copy_file

`revoked_file_exists(*args)`

A one-shot kill switch for file_exists: assign this to the name file_exists at your own script's top level to make every later call to file_exists raise, for the rest of the process.

file_exists = revoked_file_exists

`revoked_tcp_connect(*args)`

A one-shot kill switch for tcp_connect: assign this to the name tcp_connect at your own script's top level to make every later call to tcp_connect raise, for the rest of the process.

tcp_connect = revoked_tcp_connect

`revoked_http_get(*args)`

A one-shot kill switch for http_get: assign this to the name http_get at your own script's top level to make every later call to http_get raise, for the rest of the process.

http_get = revoked_http_get

`revoked_http_post(*args)`

A one-shot kill switch for http_post: assign this to the name http_post at your own script's top level to make every later call to http_post raise, for the rest of the process.

http_post = revoked_http_post

`revoked_open_in_browser(*args)`

A one-shot kill switch for open_in_browser: assign this to the name open_in_browser at your own script's top level to make every later call to open_in_browser raise, for the rest of the process.

open_in_browser = revoked_open_in_browser

`revoked_run_command(*args)`

A one-shot kill switch for run_command: assign this to the name run_command at your own script's top level to make every later call to run_command raise, for the rest of the process.

run_command = revoked_run_command

`revoked_remove_directory(*args)`

A one-shot kill switch for remove_directory: assign this to the name remove_directory at your own script's top level to make every later call to remove_directory raise, for the rest of the process.

remove_directory = revoked_remove_directory

`revoked_move_path(*args)`

A one-shot kill switch for move_path: assign this to the name move_path at your own script's top level to make every later call to move_path raise, for the rest of the process.

move_path = revoked_move_path

`revoked_environment_variable(*args)`

A one-shot kill switch for environment_variable: assign this to the name environment_variable at your own script's top level to make every later call to environment_variable raise, for the rest of the process.

environment_variable = revoked_environment_variable

`effect_capability_kinds(effect_name)`

The capability shape KIND names (as kind(cap) returns them) that can satisfy effect_name.

print(effect_capability_kinds("FileIO"))
print(effect_capability_kinds("Concurrency"))

`unenforced_effects(declared_effects)`

An honest, non-raising status report: the subset of declared_effects that this module has NO capability kind for at all.

print(unenforced_effects(["FileIO", "Concurrency"]))

`check_effects_capabilities(declared_effects, capabilities)`

Real runtime enforcement of a function's own declared uses clause: raises unless every effect in declared_effects is both checkable and actually backed by a granted capability in capabilities.

caps = [FileReadCapability("/tmp/in"), NetworkCapability("*.example.com")]
print(check_effects_capabilities(["FileIO", "NetworkIO"], caps))

API reference

Matching helpers (exposed, so a caller can build their own checks)

Capability-gated file/network/process access

Sandbox entry point

Ambient-authority revocation (manual, one-shot, irreversible)

Get notified when vcapability changes