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

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, 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, coordinates concurrent access to durable policy stores including runtime-policy.json and 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) 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:

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.

Atomic Policy Mutation

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

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:

// 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 – Implements the activation gate that serializes reads and mutations.
• 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 – Defines the persisted runtime-policy schema and mutation helpers.
• packages/core/src/runtime-policy.ts – Core type definitions for RuntimePolicy, RuntimePolicyMutation, and related utilities.
• 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 and credential-vault.json, defined in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}