sandbox grants are ignored inside a std.spec describe block

[paul-hammant]

The same helper function, called from main, sees its sandbox grant honoured; called from inside a spec.describe block, the identical grant is denied.

Repro (~35 lines, no external deps)

import std.spec
import std.audit
import std.list
import std.os

fn add_perm(t: ptr, c: string, p: string) {
    list.add(t, c)
    list.add(t, p)
}

fn run_sandboxed(perms: ptr, code: fn) {
    sandbox_push(perms)
    sandbox_install()
    call(code, perms)
    sandbox_uninstall()
    sandbox_pop()
}

fn check(label: string) {
    audit.clear()
    perms = list.new()
    add_perm(perms, "env", "HOME")        // grant env:HOME
    w = | _ctx: ptr | { os_getenv("HOME") }
    run_sandboxed(perms, w)
    c, r, a = audit.entry(0)
    println("  ${label}: ${r} allowed=${a}")
}

main() {
    fw = spec.init()
    check("outside describe")
    spec.describe(fw, "d") {
        check("inside describe, not in it")
        spec.it("t") callback {
            check("inside it")
        }
    }
    spec.run_summary(fw)
}

  outside describe:            HOME allowed=1     <- grant honoured
  inside describe, not in it:  HOME allowed=0     <- same grant, denied
  inside it:                   HOME allowed=0

Measured on main @ 984236e, Linux x86_64.

What is and isn't the trigger

Bisected down from a failing test suite:

shape	result
helper called from main	allowed ✅
helper called from a plain fn	allowed ✅
inside one plain trailing block (outer() callback { … })	allowed ✅
inside two nested plain trailing blocks	allowed ✅
after spec.init() but outside describe	allowed ✅
inside spec.describe(fw, "d") { … }	denied ❌
inside spec.it(...) callback { … } within a describe	denied ❌

So it is not trailing blocks as such, not closure nesting depth, and not spec.init. It is specifically the describe block — and it inherits it by being nested inside one. Note the third row shows the failure occurs in the describe body directly, before any it runs.

One structural difference worth pointing a debugger at: describe is declared -> ptr and returns a suite handle, so its trailing block is a value-producing closure, unlike the -> void wrappers in the passing rows. It also runs println and a ref_set on the framework's depth cell before the body executes.

Why it matters beyond tests

The failure mode is the dangerous direction: a grant that is silently ignored. Code that runs correctly at top level starts denying its own permitted operations when moved inside a describe, with no diagnostic — the audit trail records allowed=0 and the program takes its denial path.

That makes std.spec unable to test sandboxed behaviour at all, which is how this was found: writing the co-located std.audit suite for #1584. Any future suite covering std.audit, containment, or a sandboxed integration will hit the same wall.

Workaround

None found that keeps the assertions inside describe. A suite can drive the sandbox from main and assert on the recorded trail afterwards, but that gives up per-case isolation and the it reporting.

I have parked the std.audit suite rather than write it against behaviour I know to be wrong — std.audit is currently the only std module with no coverage anywhere, and this is why.

Environment

• main @ 984236e, ae 0.567.0, Linux x86_64, gcc
• Not yet checked on macOS or Windows

🤖 Generated with Claude Code

[paul-hammant]

Root-caused, and the title is too narrow: this is not about std.spec. Any builder-style trailing block that returns a handle breaks sandbox grants, because the builder DSL and the sandbox share one global stack.

The mechanism

codegen.c:4855 declares a single stack:

static void* _aether_ctx_stack[64];
static int _aether_ctx_depth = 0;

Two unrelated features push onto it:

1. The sandbox — sandbox_push(perms) puts a permission list there.
2. The builder DSL — a trailing block on a value-returning function puts its handle there, so the block body can reach _ctx.

The emitted permission check then walks the whole stack (codegen.c:4899):

for (int level = 0; level < _aether_ctx_depth; level++) {
    if (!_aether_perms_allow(_aether_ctx_stack[level], category, resource)) { _allowed = 0; break; }
}

So inside a describe, level 0 is a spec suite, not a permission list. _aether_perms_allow does list_size(ctx) on it, gets no matching pairs, hits if (n == 0) return 0 — and denies.

Here is the emitted C for the repro, which makes it plain:

check("outside describe");
_aether_ctx_push((void*)(intptr_t)spec_describe(fw, "d"));   // <- suite handle
{
    check("inside describe");                                 // <- now denied
}
_aether_ctx_pop();

It is not spec-specific

A 20-line program with no std.spec at all reproduces it — any fn f(_ctx: ptr, ...) -> ptr with a trailing block will do:

fn returns_a_handle(_ctx: ptr, name: string) -> ptr {
    return list.new()
}

main() {
    check("outside any block")                     // allowed=1
    returns_a_handle("cfg") {
        check("inside a value-returning block")     // allowed=0
    }
}

  outside any block: allowed=1
  inside a value-returning trailing block: allowed=0

That widens the blast radius considerably: std.schema's record/field, std.clapae's command/arg, and any user-written builder are all this shape. Sandboxed code that calls into one silently loses its grants.

It also explains the bisection in the original report — plain -> void trailing blocks passed because nothing was pushed; describe is -> ptr and pushed.

Reproduces on Linux

Worth stating since the sandbox has BSD-specific pieces: this is the portable in-process layer, not Capsicum. It is compiler-emitted C and reproduces on stock Linux, so a fix and its test need no BSD box. std.capsicum and std.casper are unrelated to this.

Fix options

(a) Separate the stacks. The builder DSL gets _aether_block_ctx_stack, the sandbox keeps _aether_ctx_stack. Cleanest — they are unrelated concerns that were never meant to share — but it touches every _ctx emission site.

(b) Tag the entries. Push {kind, ptr} and have the permission walk skip non-permission frames. Smaller diff, but leaves one stack doing two jobs.

(c) Have the permission walk only consider frames pushed by sandbox_push. Effectively (b) with the tag held in a parallel array.

I lean to (a): the current coupling is invisible at every call site and will bite again the next time someone adds a stack consumer. (b) is the smaller change if the _ctx sites are more tangled than they look.

Happy to take whichever shape you prefer.

[paul-hammant]

@nicolas-maman — this needs your call before anyone writes code. It is an architectural decision about a compiler-level mechanism, not a bug fix with an obvious shape.

The question in one line

The builder-DSL context stack and the sandbox permission stack are the same global array. Should they be separated, or should the permission walk learn to skip frames that are not permission lists?

How it got this way (not accidental)

fd88dc30  2026-03-30  groovy/ruby/smalltalk inspired dsl with scope     <- introduced _aether_ctx_stack
2f47e04d  2026-04-04  add runtime containment sandbox                    <- reused it

The DSL stack came first. The sandbox commit added _aether_perms_allow walking that existing array — a deliberate reuse, not an oversight. It works perfectly as long as the two features never meet, which held until a builder block wrapped sandboxed code.

What it costs today

Any builder-style trailing block on a value-returning function silently voids sandbox grants inside it. Not std.spec-specific — that was just where I found it. std.schema's record/field, std.clapae's command/arg, and any user-written builder are the same shape.

The failure direction is the bad one: a grant is ignored, with no diagnostic. Code that runs correctly at top level starts taking its denial path when moved inside a builder block, and the audit trail records allowed=0 as though the policy said so.

Options, with the trade I see

(a) Separate the stacks. _aether_block_ctx_stack for the DSL, _aether_ctx_stack stays the sandbox's. Two unrelated concerns stop sharing state. Larger diff — touches every _ctx emission site in codegen_stmt.c and codegen_expr.c.

(b) Tag the frames. Push {kind, ptr}; the permission walk skips non-permission kinds. Small diff, one stack keeps doing two jobs, and the next feature that wants a context stack faces the same decision again.

(c) Have the permission walk consult a parallel "is this a permission frame" array. Effectively (b) with the tag stored separately.

I lean to (a) because the coupling is invisible at every call site and this will recur, but I have no view on how tangled the _ctx sites are — you will know whether that is a morning or a week.

There is also a prior question worth answering first: should a builder block inherit the sandbox context at all? If a builder is meant to run under the same grants as its caller, (a) is right. If it is meant to be a boundary, the answer is different and neither option above is it.

Repro, root cause and the emitted C are in the comment above. It reproduces on stock Linux — this is the portable in-process layer, not Capsicum, so no BSD box is needed.