Security

Touba security starts with observable contracts: .tb source, AIR, manifest, scopes, opaque secrets, budgets, locks, and traces.

Available Controls

Control	What it does
AIR	carries compiled requirements
explicit manifest	grants handler, capabilities, secrets, limits, and memories
secret handles	keep sensitive values out of .tb, AIR, manifest, and traces
agent secret scopes	limit handles usable by the active agent
secret lifecycle	refuses a revoked or expired handle before handler
callable_by	refuses unauthorized agent invocations
agent uses	bounds resources selectable by an agentic decision
structured model input	separates instructions, user data, resources, and observations
maxAgentSteps	limits the sequential loop of a provider-driven agent
memory scopes	refuse memory access outside scope
tool payload validation	refuses invalid input/output before or after handler
controlled stop	traces cancel, global timeout, and kill switch in touba run
autonomy budgets	refuse excess duration, steps, tool calls, agent invocations, and provider calls
required handler isolation	wraps the process with the platform sandbox mechanism, without direct fallback
handler supply chain	verifies coherence between AIR, manifest, handlers, SDK metadata, handler_package, package files, dependency artifacts, provenance, and declared review through an explicit lock
traces	make authorizations, pauses, and refusals observable

Touba distinguishes structured model input for agentic decisions: developer instruction, user data, available resources, and runtime observations. This separation is a structural security boundary; prompt-injection detection remains a separate analysis layer.

Another available hardening point is controlled stop: distinguish pause, requested cancellation, effective cancellation, failure, and success. Touba exposes cooperative cancel, global timeout, and kill switch through touba run.

Autonomy budgets cover max_run_ms, max_steps, max_tool_calls, max_agent_invocations, max_provider_calls, and trigger quotas. They refuse execution outside these limits and produce budget traces.

Memory provenance and integrity are defined as observable metadata: origin, writer, run, reported digest, and integrity evidence. This framework helps audit memory access; truth and trust of content remain governed by the surrounding backend and review process.

Trace audit connects trace, AIR, source, artifact digests, declarative retention, and redaction policy. It makes a run explainable and verifiable through artifacts.

See also: Trace Audit.

Handler supply chain (SC-1 / SC-2 / SC-3) covers: sha256 digests for handlers, manifest, and AIR; command metadata; descriptive SDK metadata; declared handler_package identity; handler package files; declared dependency artifacts; provenance; declared review; explicit CLI validation; and lock/report inspection.

See also: Handler Supply Chain.

When sandbox.required: true, macOS uses sandbox-exec; Linux x64 combines bubblewrap, seccomp and Landlock. These backends deny out-of-scope data, writes, child processes and network access by default. A missing backend or unsupported policy prevents execution, with no direct-execution fallback. See the hardened execution profile for platform requirements and qualification status. Without a required sandbox, handlers remain trusted host code. See Manifest reference.

What Touba Refuses Before the Handler

• missing binding;
• missing grant;
• ungranted or unresolved secret;
• revoked or expired secret;
• secret not granted to the active agent;
• missing memory scope;
• invalid input payload;
• unauthorized agent caller;
• agentic capability outside uses;
• sub-agent not authorized by callable_by;
• agentic loop exceeding the configured step limit;
• autonomy budget exceeded or manifest attempting to broaden an AIR limit.

Security Boundaries

• Touba grants are declared contract boundaries. Handler sandboxing is a separate platform control explicitly required per binding.
• Traces and audit exports are engineering evidence; regulatory certification is a separate process.
• Supply-chain locks make handler drift observable; handler safety still requires host-code review.
• Data/instruction separation reduces a structural confusion; prompt-injection detection is a separate security analysis layer.
• Verified / Unverified is reserved for a complete guaranteed chain.

Recommended Posture

• Use low-privilege keys for live tests.
• Never commit secret values.
• Read traces after refusals.
• Keep handlers small and testable.
• Treat a handler as host code to audit.
• Use distinct types for external content and instructions sent to a model.