Capabilities & security

Entelechy has two layers of permission:

1. Kernel capabilities (requires { … }): what a Kernel may do with Fields, input and time. Checked by the compiler, granted by the session.
2. Host permissions (--allow …): the files and clipboard a scene may touch. Decided by the person running the scene, never widened over the protocol.

Kernel capabilities

Capability	Grants
field.read	read input Fields (sample, value, size…)
field.write	create and write output Fields, images included
input.read	read the pointer, keys, typed text, pads…
time.read	read the scene clock (time(), clock())

kernel demo.tint@1 {
    requires { field.read; field.write; }
    ...
}

A missing one is named by the compiler, with the fix (real output):

{"error":{"column":102,"line":1,"message":"writing an output needs `field.write`; add it to `requires`"},"id":1}

Narrowing with --grant

The person running a scene may limit what a session grants (all by default):

entelechy serve scene.esn --grant field.read,time.read

A Kernel requiring one not granted is refused when prepared, and what ran before keeps running (real output):

rejected /tmp/fk/kernels/rings.ent: demo.rings@1 requires field.write, which this session does not grant

render, serve, bench and the Player take --grant; the protocol’s status answers grants.

Host permissions: --allow

Form	Allows
--allow file.write=<dir>	outputs written to a file land in that directory and under it, once the evaluation that changed them commits; nothing is written without it
--allow file.delete=<dir>	an output to files removes and renames files there
--allow file.read=<dir>	a served scene’s inputs read files there
--allow clipboard.read, --allow clipboard.write	the Player’s scene reads and writes the system clipboard (elsewhere a scene’s clipboard is the session’s own)
--allow-origin <origin>	a web page from that origin may open the WebSocket

render, serve and the Player take all three file permissions. A replay says allow file.write <dir>; what it writes is kept for the run and never reaches the disk.

What a served scene reaches

When an agent drives a scene through serve:

• Reads stay beside the scene as it first loaded (the scene, its placed graphs, what it uses, the files its inputs read), in package directories, and in directories given by --allow file.read — judged where a path lands after its links and ... A composed document does not widen this.
• Writes take --allow file.write. compose writes only the scene’s own .ent, .esn and .replay files, under its directory and not in a package directory.
• Sockets: a WebSocket upgrade is accepted only from a page served by this machine (localhost, 127.0.0.1, [::1]), a non-browser client, or an origin named by --allow-origin; otherwise 403. A page opened from a file says null and needs --allow-origin null.
• Budgets: what an agent sends is charged against the Host’s budget (--memory, --work) before it costs anything; a socket request is at most 256 MiB; a connection with 64 unread answers is read no further, so a peer that does not read holds back only itself.

What a served scene reaches is what the person running it gave. Why: a file an agent can read it can send away, and any page the person visits can reach a socket on their machine. (docs/DECISIONS.md)

Other protections

• Loop budgets: a loop counted at run time runs whole, bounded by --work; a manifest’s budget gives the iterations one element may run.
• No recursion: a function never reaches itself; a cycle is refused, naming it.
• Effects are data: a Kernel’s effects (writing files…) are data the Host carries out after a commit, not side effects the Kernel performs.
• crates/interface/entelechy/tests/hostile.rs tests hostile input.