Capability Grants

A constructor executes inside a WASI sandbox that can reach nothing by default — no filesystem, no network, no environment. The consumer (not the author) widens it, per instance, with grants. The same constructor code can therefore be run wide-open by one workflow and fully sealed by another.

The grammar is identical on every consumer surface — Rust constructor!, Rust #[reactor(constructor = ...)], and Python cloaca.constructor(...):

grants = {
    fs   = ["ro:/data", "rw:/scratch"],
    env  = ["API_REGION"],
    http = ["api.example.com", "*.internal:8443"],
    tcp  = ["db.internal:5432"],
}

grants={"fs": ["ro:/data"], "env": ["API_REGION"]}

The five kinds

Kind	Pattern	Effect
`fs`	`ro:<path>` / `rw:<path>`	Pre-opens the directory read-only / read-write. Everything outside stays invisible. A bare path with no `ro:`/`rw:` prefix is a hard error — the load fails closed.
`env`	`<NAME>`	Passes the host’s value of that variable through by name (skipped silently if unset). Literal values are not supported.
`http`	`<host>[:port][/path-glob]`, `*` globs	Grants the http capability plus a per-request egress policy matching host/port/path.
`tcp`	`<host>:<port>`, `:<port>`, ``	Grants raw sockets plus a per-connection policy. A DNS host is resolved once at load and matched by `(ip, port)`.
`secrets`	`<name>`	Allow-lists the named secrets the member may resolve through the secret store; anything not listed is denied (`NotGranted`, distinct from `NotFound`).

Semantics worth knowing

Default-closed, fail-closed. No grant → deny. A malformed grant aborts the load rather than silently widening access.
Symlinks cannot escape. A path inside a granted tree that symlinks outside it is refused by the sandbox (Operation not permitted). Grant the real target, or point at a regular file — e.g. prefer /etc/hostname over /etc/os-release, which is a symlink into /usr/lib on Debian images.
Denial surfaces at the operation, not at load: an ungranted read fails inside the member (a task node fails, a trigger simply never fires) with the WASI error naming the path.
Load-time lint. If the provider package declares a capability intent the consumer didn’t grant, the loader logs a warning at load — the mismatch will deny at runtime, so it’s surfaced early rather than as a mystery failure.

Native providers bypass enforcement

Grant enforcement applies only to WASM providers. A provider packaged with runtime = native runs trusted and unsandboxed, in-process — no WASI sandbox, no capability allow-list, no egress policy (ProviderRuntime::grants_enforced() returns true only for Wasm; the native load path takes no grants at all). Any grants you write at a native constructor’s instantiation site are advisory documentation, not a security boundary. Treat installing a native provider like adding a normal Rust dependency: review it, pin it, and trust it — or use a WASM provider instead. cloacinactl constructor package --native prints this trust tier at packaging time.

You cannot reach unenforced grants by accident

Because runtime is an emission target, a provider can ship as WASM in one version and native in the next — which would quietly turn your grants from a control into decoration. Two rules make that impossible:

Declaring grants against a provider that resolves NATIVE is a load error, unless you acknowledge the trust tier explicitly. The message names all three ways out:

grants are not enforced on native providers; either pin runtime = "wasm", acknowledge with runtime = "native", or remove grants
You can pin the tier with an optional runtime on the consumption site. If the resolved provider disagrees, the load fails and names both runtimes:
```
constructor!(
    id = "read_config",
    from = "cloacina-provider-fs@0.1",
    constructor = "read_file",
    config = { path = "/etc/app.toml" },
    grants = { fs = ["ro:/etc"] },
    runtime = "wasm",          // fail the load if this provider ever goes native
);
```
#[reactor(.., runtime = "..")] takes the same pin. Writing runtime = "native" is the explicit acknowledgement: the node loads, the grants stay advisory, and the loader logs a warning saying so.

Grants-free native loads are unaffected — no error, no new requirement. On the producer side, changing a provider’s runtime is a MAJOR/breaking change, checked against providers/COMPAT.toml by the provider wave guard.

The runnable examples/constructor-contract/fs-grant-demo demonstrates all three outcomes side by side: a granted read, the same read denied without the grant, and a granted write through a second suite member.