# PermissionProfileCompiler in Apache Maka: How It Compiles Permission Profiles for Secure Execution

> Discover how the PermissionProfileCompiler in Apache Maka compiles permission profiles. Learn how it transforms modes like explore ask or bypass into a fully-qualified PermissionProfile for secure tool execution.

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

---

**The PermissionProfileCompiler transforms a permission mode (`explore`, `ask`, or `bypass`) and working directory into a fully-qualified PermissionProfile that the runtime enforces during tool execution.**

In Apache Maka, the **PermissionProfileCompiler** serves as the bridge between high-level user preferences and concrete sandbox security policies. Located in [`packages/core/src/permission-profile-compiler.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile-compiler.ts), this core component ensures that every tool invocation runs with precisely defined filesystem and network permissions.

## What PermissionProfileCompiler Does

The compiler's primary export, **`compilePermissionProfile`**, executes a four-step pipeline to derive sandbox configurations from simple mode strings.

### Step 1: Collect Workspace Roots

The compiler first determines which directories constitute the trusted workspace. It uses explicitly provided `workspaceRoots` or falls back to the current working directory (`cwd`):

```typescript
const workspaceRoots = input.workspaceRoots ?? [input.cwd];

```

### Step 2: Select a Base Profile

Based on the requested `mode`, the compiler selects one of three **built-in managed profiles**:

| Mode | Profile Selected | Permission Level |
|------|------------------|------------------|
| `explore` | `read-only` | Read access to workspace only |
| `ask` | `workspace-write` | Read/write to workspace, tmp directories |
| `bypass` | `danger-full-access` | Unrestricted filesystem and network access |

This selection occurs via a `switch (input.mode)` statement in the compiler source.

### Step 3: Wrap via compileManaged

The chosen profile passes through **`compileManaged`**, which attaches metadata including the standardized `profileName` and bundles the **network sandbox policy**.

```typescript
return compileManaged(input.mode, /* ... */, workspaceRoots);

```

### Step 4: Return CompiledDescription

The final **`CompiledPermissionProfile`** object contains:

- `mode`: The original permission mode
- `profileName`: Human-readable identifier (`read-only`, `workspace-write`, `danger-full-access`)
- `profile`: The full `PermissionProfile` with filesystem entries
- `workspaceRoots`: Normalized list of trusted paths
- `network`: Network policy configuration (`restricted` or `enabled`)

## Where PermissionProfileCompiler Is Used

According to the Apache Maka source code, two primary systems consume the compiler's output.

### Built-in Tool Runtime

In [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) (lines 33-37), the runtime obtains a profile when a tool lacks an explicit profile definition. The compiler derives the effective security context from the session's `permissionMode`.

### Filesystem Worker Client

In [`packages/runtime/src/filesystem-worker/client.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/filesystem-worker/client.ts) (lines 296-301), each remote request triggers profile compilation to enforce **filesystem permissions on the worker side**. This ensures that even distributed operations respect the originating session's constraints.

## Practical Usage Examples

### Read-Only Exploration Mode

```typescript
import { compilePermissionProfile } from '@maka/core/permission-profile-compiler';

const compiled = compilePermissionProfile({
  mode: 'explore',
  cwd: '/home/user/project',
});
// compiled.profileName === 'read-only'
// compiled.network.kind === 'restricted'

```

### Workspace Write Mode with Multiple Roots

```typescript
const compiled = compilePermissionProfile({
  mode: 'ask',
  cwd: '/home/user/project',
  workspaceRoots: ['/home/user/project', '/home/user/other'],
});
// compiled.profileName === 'workspace-write'
// Profile grants write access to :workspace_roots, :tmpdir, :slash_tmp

```

### Bypass Mode (Full Access)

```typescript
const compiled = compilePermissionProfile({
  mode: 'bypass',
  cwd: '/home/user/project',
});
// compiled.profileName === 'danger-full-access'
// compiled.profile.fileSystem.kind === 'unrestricted'
// compiled.network.kind === 'enabled'

```

### Feeding Profiles to SandboxManager

```typescript
import { SandboxManager } from '@maka/runtime/sandbox';

const { profile, workspaceRoots } = compilePermissionProfile({
  mode: 'ask',
  cwd: '/repo',
});

SandboxManager.createSandbox({ profile, workspaceRoots });

```

## Key Source Files

| File | Purpose |
|------|---------|
| [`packages/core/src/permission-profile-compiler.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile-compiler.ts) | Core `compilePermissionProfile` implementation |
| [`packages/core/src/permission-profile.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile.ts) | Profile definitions and helper creators |
| [`packages/runtime/src/builtin-tools.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/builtin-tools.ts) | Runtime usage for built-in tools |
| [`packages/runtime/src/filesystem-worker/client.ts`](https://github.com/apache/maka/blob/main/packages/runtime/src/filesystem-worker/client.ts) | Remote filesystem enforcement |
| `packages/runtime/src/sandbox/*` | Platform-specific sandbox implementations (macOS Seatbelt, Linux seccomp) |

## Summary

- **PermissionProfileCompiler** converts permission modes into enforceable sandbox policies through `compilePermissionProfile`.
- Three modes map to three profiles: `explore` → read-only, `ask` → workspace-write, `bypass` → danger-full-access.
- The compiler normalizes workspace roots and bundles network policies into a `CompiledPermissionProfile` structure.
- Runtime systems in [`builtin-tools.ts`](https://github.com/apache/maka/blob/main/builtin-tools.ts) and [`filesystem-worker/client.ts`](https://github.com/apache/maka/blob/main/filesystem-worker/client.ts) consume these profiles to enforce security boundaries.
- Platform-specific sandbox managers translate the abstract profile into concrete OS restrictions.

## Frequently Asked Questions

### What permission modes does PermissionProfileCompiler support?

The compiler supports three modes defined in the Apache Maka source: **`explore`** (read-only workspace access), **`ask`** (read/write to workspace and temporary directories), and **`bypass`** (unrestricted filesystem and network access). Each mode maps to a predefined managed profile with specific `canReadPath` and `canWritePath` entries.

### How does PermissionProfileCompiler determine which directories are trusted?

The compiler checks `input.workspaceRoots` first; if undefined, it defaults to `[input.cwd]`. This logic appears in [`packages/core/src/permission-profile-compiler.ts`](https://github.com/apache/maka/blob/main/packages/core/src/permission-profile-compiler.ts). Callers can explicitly pass multiple roots to extend the trusted boundary beyond the current working directory.

### Can I use PermissionProfileCompiler directly in my own tools?

Yes. Import `compilePermissionProfile` from `@maka/core/permission-profile-compiler` and pass a configuration object with `mode` and `cwd`. The function returns a `CompiledPermissionProfile` suitable for `SandboxManager.createSandbox()` or custom enforcement logic.

### What happens to the network policy in each mode?

The compiler sets `network.kind` to `restricted` for `explore` and `ask` modes, blocking external connections. Only `bypass` mode yields `network.kind === 'enabled'`. This policy is bundled by `compileManaged` and enforced by platform-specific sandbox implementations in `packages/runtime/src/sandbox/`.