# Security Boundaries, Runtime Policies, and Access Authority Management in Apache Maka

> Understand Apache Maka's security boundaries, runtime policies, and access authority management. Discover its layered security model for robust access control.

- Repository: [The Apache Software Foundation/maka](https://github.com/apache/maka)
- Tags: security-guide
- Published: 2026-08-27

---

**Apache Maka enforces a layered security model that isolates state access through immutable connection permissions, atomic runtime-policy activation gates, and fine-grained capability checks enforced by the Host Kernel and Domain Modules.**

Apache Maka's Runtime Host architecture establishes strict security boundaries to protect sensitive operations from unauthorized access. The framework combines protocol-level validation with durable runtime policies stored in JSON documents, ensuring that every state mutation occurs atomically and every capability check consults the latest committed authority. This design guarantees that only designated principals can modify security-relevant state while maintaining consistency across concurrent operations.

## Protocol and Security Boundaries

Maka enforces its outermost security layer through **closed-schema protocol validation** and **immutable connection authentication**. According to the Runtime Host architecture documented in [`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md), all inbound messages must conform to strict schemas that reject unknown fields and enforce explicit size limits (lines 300-307).

### Connection Authentication and Immutable Permissions

Authentication occurs before a connection is fully admitted to the Runtime Host. The **Host Kernel** authenticates the connection once and creates an immutable permission set that fixes the principal's authorized operations for the entire session lifetime. As implemented in the protocol handling code (lines 303-306), this early binding prevents privilege escalation during the connection lifecycle.

### Local IPC Trust Boundaries

For local inter-process communication, Maka establishes additional **Local Owner** authority only after the OS endpoint verifies a same-user trust boundary (line 304). This ensures that elevated local privileges require both successful authentication and verifiable local process ownership.

## Runtime-Policy Activation

While protocol boundaries protect the perimeter, **Runtime-Policy Activation Gates** manage how internal policy changes propagate through the system. The `RuntimePolicyActivationGate` class, located in [`packages/runtime-host/src/server/runtime-policy-activation-gate.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-activation-gate.ts), coordinates concurrent access to durable policy stores including [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json) and [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json).

### Read and Mutation Serialization

The activation gate distinguishes between **read activations** and **mutations** to ensure consistency:

- **Read activations** (`runReadActivation`) wait for any pending mutation tails to complete before executing, guaranteeing that reads observe fully committed state.
- **Mutations** (`runMutation`) serialize after all preceding mutations and any in-flight read activations, ensuring atomic application of policy changes.

### Poisoning and Failure Handling

If a mutation's outcome remains ambiguous or a post-commit hook fails, the gate enters a **poisoned** state. Once poisoned, the gate rejects subsequent reads and mutations with a `poisonedError`, preventing the system from operating on potentially inconsistent policy state.

## Access Authority Management

**Access authority** in Maka combines the connection's authenticated principal, granted capabilities, and policy-derived permissions into a comprehensive permission object stored within the runtime-policy documents.

### HostRuntimePolicyCoordinator

The **HostRuntimePolicyCoordinator** ([`packages/runtime-host/src/server/runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts)) serves as the central authority for all policy-driven decisions. It exposes operations like `runtime.policy.query` and `runtime.policy.mutate`, using the activation gate to serialize access. Before persisting any change, the coordinator invokes `validateMutation` to ensure the requested transformation complies with schema and security constraints.

### Fine-Grained Capability Enforcement

Domain Modules consult the coordinator to enforce specific capabilities against the active policy snapshot:

- **Credential Vault Access**: The `credential.vault.query` operation verifies that the requesting connection's policy permits access to the specific `CredentialLocator` using `sameLocator` logic (lines 50-60).
- **Workspace Path Resolution**: The `WorkspaceTarget` resolver validates that clients may access host filesystem paths only when the `canUseHostPaths` policy flag is enabled (architecture section *Workspace resolution*, lines 30-41).
- **Client Capability Invocations**: Reverse calls from client-published capabilities remain size-limited and cannot exceed the authority granted during the original connection authentication (lines 4-7 of the *Protocol and security boundary* section).

## Runtime-Policy Code Examples

### Querying Policy State with Read Activation

When retrieving current policy settings, use `runReadActivation` to ensure the read observes a consistent snapshot:

```ts
const policy = await activation.runReadActivation(() =>
  policyCoordinator.queryPolicy()
);
console.log('Current policy revision:', policy.revision);

```

This pattern guarantees the query waits for any in-flight mutations to complete before returning data from [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json).

### Atomic Policy Mutation

To modify runtime behavior, such as disabling web search capabilities, wrap the operation in `runMutation`:

```ts
await activation.runMutation(async () => {
  const result = await policyCoordinator.mutatePolicy({
    kind: 'set',
    operation: { webSearch: { enabled: false } },
  });
  if (!result.ok) {
    throw new Error(`Mutation failed: ${result.error.message}`);
  }
  return result;
});

```

The activation gate serializes this mutation after previous writes and runs the post-commit hook only after successful persistence.

### Enforcing Host-Path Capability Checks

Domain Modules validate specific permissions before executing sensitive operations:

```ts
// In a Domain Module handling a workspace request
if (!policy.policy.canUseHostPaths) {
  throw new Error('Host-path access not permitted by runtime policy');
}

```

This check ensures compliance with the `canUseHostPaths` flag stored in the active policy document before allowing raw filesystem access.

## Key Implementation Files

The security model spans several critical source files:

- [`packages/runtime-host/src/server/runtime-policy-activation-gate.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-activation-gate.ts) – Implements the activation gate that serializes reads and mutations.
- [`packages/runtime-host/src/server/runtime-policy-coordinator.ts`](https://github.com/apache/maka/blob/main/packages/runtime-host/src/server/runtime-policy-coordinator.ts) – Central coordinator exposing query/mutate operations with validation.
- [`packages/storage/src/runtime-policy/policy-document.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/policy-document.ts) – Defines the persisted runtime-policy schema and mutation helpers.
- [`packages/core/src/runtime-policy.ts`](https://github.com/apache/maka/blob/main/packages/core/src/runtime-policy.ts) – Core type definitions for `RuntimePolicy`, `RuntimePolicyMutation`, and related utilities.
- [`docs/architecture/runtime-host-architecture.md`](https://github.com/apache/maka/blob/main/docs/architecture/runtime-host-architecture.md) – High-level description of the Host's security boundaries and authority model.

## Summary

- **Protocol boundaries** enforce closed-schema validation and immutable connection permissions before the Runtime Host admits any client connection.
- **Runtime-Policy Activation Gates** ensure atomic policy mutations and consistent reads, poisoning the gate if post-commit validation fails to prevent inconsistent state.
- **Access authority** combines connection principals with policy-derived capabilities, centralized through the `HostRuntimePolicyCoordinator`.
- **Domain Modules** enforce fine-grained checks for credentials, workspace paths, and client capabilities against the active policy snapshot.
- All security-relevant state mutations flow through the activation gate and coordinator, ensuring that only designated authority can modify runtime policies.

## Frequently Asked Questions

### How does Maka prevent partially applied runtime policies from affecting operations?

Maka prevents partial policy application through the **RuntimePolicyActivationGate**, which serializes all mutations using `runMutation`. Read operations executing through `runReadActivation` wait for any pending mutations to complete before accessing policy stores. If a mutation fails or its post-commit hook throws an error, the gate becomes poisoned and rejects all subsequent operations rather than risk inconsistent state.

### What establishes the initial security boundary when a client connects to Maka?

The **Host Kernel** establishes the security boundary during connection authentication, which occurs before admitting the client session. The kernel validates the connection against a closed-schema protocol, enforces size limits, and creates an immutable permission set that binds the connection principal to specific capabilities for the session lifetime, preventing runtime privilege escalation.

### Where are Maka's runtime policies stored and how are they structured?

Runtime policies reside in durable JSON documents including [`runtime-policy.json`](https://github.com/apache/maka/blob/main/runtime-policy.json) and [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json), defined in [`packages/storage/src/runtime-policy/policy-document.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/policy-document.ts). The `HostRuntimePolicyCoordinator` manages these stores, ensuring that mutations pass validation before persistence and that the activation gate coordinates concurrent access to maintain consistency.

### Can Domain Modules override security policies set by the Host Kernel?

No, Domain Modules cannot override Kernel-established security boundaries. While Domain Modules possess **business-level authority** to enforce policy checks (such as `canUseHostPaths` or credential access), they must route all policy mutations through the `HostRuntimePolicyCoordinator`, which validates changes against the schema and existing permissions. The Kernel retains exclusive rights to connection-level permission objects and protocol validation.