# How Maka Handles Secrets and Tool Execution Across Sandbox Boundaries

> Discover how Maka safely handles secrets and tool execution across sandbox boundaries using approved expansions and a secretMaterial structure for enhanced security.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: internals
- Published: 2026-09-12

---

**Maka isolates sessions inside sandbox boundaries and manages cross-boundary execution through explicit user-approved expansions, keeping secrets segregated in a secretMaterial structure that is only accessible to built-in tools.**

The Apache Maka project implements a defense-in-depth security model where each session operates within a constrained **ExecutionBoundary** that governs filesystem and network access. When tools require elevated privileges or sensitive credentials, the runtime orchestrates boundary expansions and secret injection without ever exposing sensitive data to user-supplied code.

## Secret Handling Architecture

Maka’s secret management is tightly coupled with its runtime policy system to ensure credentials never leak into untrusted execution contexts.

### Runtime Policy and Secret Material Structure

According to the `apache/maka` source code, secrets are stored in a **secretMaterial** structure defined in [[`packages/storage/src/runtime-policy/operations.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts)](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts). This object attaches to runtime-policy operations and supports three distinct credential types:

- **`secretMaterial.connection.secret`** – Credentials for network connections (e.g., API keys).
- **`secretMaterial.networkProxy.secret`** – Authentication for proxy servers.
- **`secretMaterial.requestHeaders.secret`** – Secret-based HTTP headers injected into requests.

This design ensures that secrets are **never exposed to user-supplied code**; they are only passed to built-in tool implementations that know how to consume them.

### Secret Validation and Constraints

Before any secret is utilized, the runtime validates the operation through functions in [[`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts)](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). The `validateSandboxBoundaryExpansion` and `applySandboxBoundaryExpansion` functions enforce strict size caps and prevent cross-target leakage. Additionally, secret material is automatically stripped when a boundary is downgraded or when the session terminates, ensuring no residual credentials persist in memory.

## Cross-Boundary Tool Execution Workflow

When a session requires capabilities that exceed its current **ExecutionBoundary**—such as network access or broader filesystem rights—it must explicitly request an expansion.

### Requesting Boundary Expansion with request_sandbox_boundary

Sessions initiate cross-boundary execution by invoking the **`request_sandbox_boundary`** tool. This tool creates a **SandboxBoundaryRequest** object (see lines 76-95 in [[`sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/sandbox-boundary.ts)](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts)), which captures the requested expansion and justification. The request is stored and presented to the user or host for review.

```typescript
// Request network access for external API calls
await tools.request_sandbox_boundary({
  expansion: { network: { enabled: true } },
  justification: "Need to call an external API"
});

```

### The Approval and Expansion Process

If the user **approves** the request, the host expands the session’s boundary through a controlled pipeline:

1. **`assessSandboxBoundaryExpansion`** – Evaluates the requested changes against existing policies.
2. **`applySandboxBoundaryExpansion`** – Applies the validated changes to the session context.
3. **`createManagedExecutionBoundary`** – Generates a new boundary object with the granted permissions.

If the user **denies** the request, the operation is marked *denied* and any pending tool execution aborts with a `SandboxCommandError`.

The system actively prevents privilege escalation through **`expansionConflictsWithExplicitDeny`**, which checks the expansion against explicit deny rules and protected metadata before approval.

## Safety Guarantees and Capacity Limits

Maka enforces hard constraints to prevent abuse of boundary expansions:

- **Maximum 32 filesystem entries** per expansion request.
- **4 KB path length limit** for filesystem entries.
- **64 KB serialized payload limit** for boundary requests.
- **Conflict checks** ensure that a boundary request cannot silently override an existing deny rule.

Once approved, the tool executes with the newly granted permissions, and any required secrets are supplied from the associated `secretMaterial` structure.

## Practical Implementation Examples

The following patterns demonstrate how to work with secrets and boundary expansions in Maka:

```typescript
// Example 1: Using secretMaterial with the web-fetch tool
const result = await tools.web_fetch({
  url: "https://api.example.com/data",
  // The API key is injected via secretMaterial, not inline
  secretMaterial: { connection: { secret: process.env.MY_API_KEY } }
});

```

```typescript
// Example 2: Requesting filesystem write access
await tools.request_sandbox_boundary({
  expansion: {
    filesystem: {
      entries: [{ path: "/workspace/tmp", access: "write", scope: "subtree" }]
    }
  },
  justification: "Write temporary files for processing"
});

```

## Summary

- Maka uses an **ExecutionBoundary** object to isolate sessions, controlling filesystem and network access.
- Secrets are encapsulated in **secretMaterial** structures attached to runtime-policy operations, ensuring they remain inaccessible to user code.
- Cross-boundary tool execution requires explicit user approval via **`request_sandbox_boundary`**, which creates a **SandboxBoundaryRequest** processed through `assessSandboxBoundaryExpansion` and `applySandboxBoundaryExpansion`.
- Hard capacity limits (32 filesystem entries, 4 KB paths, 64 KB payloads) and conflict checks prevent privilege escalation and resource exhaustion.
- Once approved, tools receive secrets only through the `secretMaterial` interface defined in [`packages/storage/src/runtime-policy/operations.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts).

## Frequently Asked Questions

### How does Maka prevent secrets from leaking to user-supplied code?

Maka stores all credentials in a **secretMaterial** structure that is attached to runtime-policy operations in [`packages/storage/src/runtime-policy/operations.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/operations.ts). This structure is only accessible to built-in tool implementations that consume the secrets, while user-supplied code receives no access to the raw credential values. The runtime strips secret material when boundaries are downgraded or sessions end.

### What happens when a sandbox boundary request is denied?

If a user or host denies a **SandboxBoundaryRequest**, the request is marked as denied in the system state. Any pending tool execution that depends on the expanded boundary aborts immediately with a **SandboxCommandError**, preventing the session from proceeding with operations that exceed its current permissions.

### What are the capacity limits for sandbox boundary expansions?

According to the implementation in [`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts), boundary expansions are capped at **32 filesystem entries**, **4 KB maximum path length** per entry, and **64 KB for the serialized payload**. These limits are enforced by `validateSandboxBoundaryExpansion` to prevent resource exhaustion and denial-of-service attacks.

### Where is the ExecutionBoundary defined in the codebase?

The **ExecutionBoundary** object and its associated validation logic are defined in [[`packages/core/src/sandbox-boundary.ts`](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts)](https://github.com/apache/maka/blob/main/packages/core/src/sandbox-boundary.ts). The actual tool implementation that creates boundary requests resides in [[`packages/runtime/src/sandbox-boundary-tool.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts)](https://github.com/apache/maka/blob/main/packages/runtime/src/sandbox-boundary-tool.ts), while the host-side authority that consumes secrets is located in [[`packages/runtime-host/src/server/execution-model-authority.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-model-authority.ts)](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/execution-model-authority.ts).