Scoped capabilities: bounded observation and restricted authority mode

[alexanderradahl]

Why

The poisoned-repository harness in #2 / #4 now makes the current boundary measurable: while the global unlock is armed, model-visible untrusted content and the bridge's full registered shell/filesystem authority coexist. The latch is a revocation control, not a per-action authorization boundary.

Product Hunt launch feedback sharpened the next design problem in two useful ways:

1. A useful approval must bind authority to the specific action, not merely say that broad authority is currently armed.
2. "Read current state" is not automatically safe. Revalidation can itself disclose secrets, acquire locks, hit side-effecting endpoints, or broaden model-visible context. The trusted primitive is closer to a bounded observation capability than generic read access.

A command-name denylist is not meaningful while arbitrary shell_exec remains available: the shell can invoke the same capability under another spelling. Any restricted mode has to remove or constrain the underlying authority.

Design target

Explore an optional authority model with these properties:

• capability scope is explicit over actor/trigger, tool/effect, target/provider, and expiry;
• a model may only narrow a granted scope, never widen it;
• expiry fails closed;
• resuming after expiry revalidates only through a bounded observation path, rather than silently refreshing broad authority;
• changed preconditions invalidate the old plan;
• when bounded revalidation cannot be expressed, abort rather than recursively asking for another broad grant.

Bounded observation cases

Do not classify something as safe just because it is named read or uses HTTP GET. Test the observable effect and target instead.

Useful low-authority preconditions may include:

• Git HEAD / tree object ids;
• file hashes captured when the action was proposed;
• row/version tokens;
• ETags or exact-resource versions;
• provider-specific metadata endpoints whose effects and returned fields are bounded.

A revalidation capability must not be able to widen actor, target, provider, fields, path scope, or network destination relative to the action it is validating.

Architecture constraint to resolve

The current HTTP transport re-keys requests onto one shared bridge.mjs child. As documented in SECURITY.md, that means the stdio side cannot distinguish OAuth session/conversation identity today. A true per-conversation capability lease therefore requires an architectural or protocol change; do not paper over that limitation with an in-process map keyed on data the bridge never receives.

Possible directions to evaluate, without committing to one yet:

• one bridge worker / capability context per authenticated remote session;
• explicit signed capability material propagated through the transport;
• a deliberately smaller restricted bridge process that exposes only workspace-scoped operations and no arbitrary shell/network authority.

Acceptance criteria

• Threat model distinguishes global unlock/revocation from action-scoped authorization.
• Proposed capability representation is monotonic: downstream/model-controlled code can only narrow it.
• Observation/revalidation authority is separately bounded and never treated as inherently safe by verb/tool name.
• Expiry + changed-precondition behavior is deterministic and fail-closed.
• Design explains how caller/conversation identity reaches the enforcement point, or explicitly chooses a process-level boundary instead.
• Restricted mode removes underlying authority rather than special-casing command names.
• Reuse tests/fixtures/poisoned-repository.* as an adversarial acceptance fixture where applicable.
• SECURITY.md states remaining escape hatches/ambient-authority limits without stronger claims than the implementation earns.

This is a design/hardening issue, not a claim that the current unrestricted mode is vulnerable beyond its documented security model.