Capabilities index

-- Doc example: deny-by-default capabilities + faithful scope.

-- Uses `secret` because it proves the model with no network/disk side effects.
intent: "doc example: capabilities and intent"
require secret("APP_*")          -- name-prefix scope: covers APP_KEY, APP_DB, ... only

require net("http://localhost:8545/")   -- a URL is stored as its host; an EXPLICIT port is part of the grant (v0.6.29+)


task read_app_key()
    -- APP_KEY is under the declared APP_* scope → allowed (still redacted, as always)

    give text(secret("APP_KEY", "demo")) == "secret(APP_KEY)"

task where_am_i()
    -- cwd() reveals the host's directory layout: it needs file.read(".") — not declared here → denied (engine v0.6.20+)
    give cwd()

task read_unscoped()
    -- DB_PASSWORD is NOT under APP_* → denied at the capability check (before any use)

    give secret("DB_PASSWORD")

print("APP_KEY is in scope → " + text(read_app_key()))

test "a capability you declared (in scope) is allowed"
    assert(read_app_key())

test "anything outside the declared scope is denied (deny-by-default)"
    assert_error(read_unscoped)
    assert_error(where_am_i)

task key_under_wrong_block()
    -- the program DID declare secret("APP_*"), but this block only lists `net`: denied
    sandbox under {"net": "x.com"}
        give read_app_key()

test "sandbox under: a least-privilege block keeps only what it lists"
    -- what the block lists stays (still gated by the program's own require)…

    sandbox under {"secret": "APP_*"}
        assert(read_app_key())
    -- …what it doesn't list is denied even though the program declared it

    assert_error(key_under_wrong_block)

task other_port()
    -- the grant is localhost:8545; port 8546 is another scope → denied before any socket opens

    give http_get("http://localhost:8546/")

test "a port written in a net grant is part of the grant"
    assert_error(other_port)

task stamp()
    give format_time(1750000000, "%Y-%m-%d")

task clock()
    give now()

task seeded_die()
    give random_int(rng(42), 1, 6)

task os_die()
    give random_int(1, 6)

test "what never reads the clock or the OS needs no capability (v0.6.29+)"
    -- `sandbox` strips every capability, so what still runs inside it is pure
    assert_eq(sandbox stamp(), "2025-06-15")                -- formatting a time is not reading the clock

    assert_error(() => sandbox clock())                     -- now() is

    assert_eq(sandbox rng(42)(), 0.7739560485559633)        -- a seeded generator: numpy's default_rng(42)

    assert_eq(sandbox seeded_die(), seeded_die())           -- same seed, same numbers

    assert_error(os_die)                                    -- OS entropy is `random`, never declared here