# How Apache Maka Manages Credentials and API Keys Securely: A Deep Dive into the Pure-Node Architecture

> Learn how Apache Maka securely manages credentials and API keys with its pure-Node architecture. Discover OS-level encryption and masked placeholders for enhanced security.

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

---

**Maka isolates sensitive data in a pure-Node credential store that encrypts secrets at the OS level, exposing only masked placeholders to the UI and short-lived references to the runtime sandbox.**

Apache Maka treats API keys and OAuth tokens as high-risk assets, implementing a defense-in-depth strategy that keeps raw secrets out of renderer processes, profile files, and command-line arguments. The system consolidates all sensitive data into a dedicated encrypted store accessed exclusively through the `@maka/storage` package, ensuring that credentials and API keys remain securely managed throughout their lifecycle.

## Centralized Credential Storage in @maka/storage

Maka implements a **pure-Node credential store** that serves as the single source of truth for all secrets. Located in [`packages/storage/src/credential-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/credential-store.ts), this module manages an encrypted JSON file that resides next to the desktop profile, ensuring that API keys and access tokens never touch unprotected disk space or application memory outside the main process.

The store enforces strict boundaries: it is **never exposed to renderer processes**, command-line arguments, or profile JSON files. All write operations flow through the storage package, which implements the logic described in the source as a "Pure-Node credential store. Shared by the desktop app and any…" components requiring secret access. This centralization prevents credential sprawl and eliminates the risk of accidental serialization into logs or configuration exports.

## Securing the UI Layer with Masked Placeholders

To prevent secret leakage through the interface, Maka enforces **read-only access via a safe IPC bridge**. UI components query the store indirectly and receive only confirmation that a credential exists, never the raw secret itself. When displaying connection status or configuration details, the interface renders a masked placeholder: "stored only in the local credential store; never written to profiles, arguments, or chat".

This guarantee is hardcoded in [`packages/cli/src/tui-copy-catalog.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-copy-catalog.ts) at line 143, where the TUI explicitly substitutes actual key values with security warnings. By enforcing this separation, Maka ensures that screen captures, chat logs, or UI debug states cannot inadvertently reveal sensitive material.

## Short-Lived Credentials and Lifecycle Management

For temporary access scenarios such as remote host connections, Maka generates **short-lived access credentials** that minimize exposure windows. When a user creates a new connection, the CLI emits a one-time credential ID that is immediately stored in the credential store and expires after a configurable period—typically 15 minutes.

The lifecycle is documented in [`docs/runtime-host-remote-access.md`](https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md) (lines 40-270), which specifies that these tokens can be explicitly revoked using:

```bash
maka runtime-host access revoke --root /srv/maka --credential <credentialId>

```

This approach ensures that even if a temporary token is intercepted, its utility is strictly time-bound and revocable without rotating the primary API key.

## Runtime Host Isolation and Reference-Based Injection

The **Runtime Host**—Maka's sandboxed execution environment—never receives raw credentials. Instead, it receives **environment variable references** that it resolves at execution time through the credential store. As documented in [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md) at line 43, the security guideline explicitly states: "Keep provider credentials and Electron IPC outside this package. The product shell resolves credentials and passes only the dependencies required for execution."

This reference-based injection limits the blast radius if a sandbox is compromised. An attacker gaining control of the Runtime Host would only obtain variable names, not the actual secrets, as the resolution occurs outside the sandbox boundary.

## OS-Level Encryption and Failure Handling

Maka delegates the final encryption boundary to the operating system. On Windows, the credential store integrates with the **OS credential manager and DPAPI**, ensuring that the JSON file is encrypted and accessible only by the user's account. The project's security policy in [`SECURITY.md`](https://github.com/apache/maka/blob/main/SECURITY.md) (lines 85-90) clarifies that the **only enforcement boundary** is the operating system itself, leveraging native protections rather than custom cryptography.

When the store is unavailable—whether locked, missing, or corrupted—all code paths propagate clear errors such as `credential store unavailable`. This allows the UI to surface problems without attempting fallback storage that might leak secrets. Test suites including [`host-profile.test.ts`](https://github.com/apache/maka/blob/main/host-profile.test.ts) and [`oauth.test.ts`](https://github.com/apache/maka/blob/main/oauth.test.ts) explicitly assert this failure behavior to prevent regression.

## Practical Implementation Examples

The following patterns demonstrate how to interact with Maka's secure credential management:

Storing a new API key permanently:

```typescript
import { CredentialStore } from '@maka/storage';
await CredentialStore.set('anthropic', { apiKey: '<secret>' });
// The secret is written to the encrypted JSON file and never appears in logs.

```

Creating a short-lived Runtime Host access credential:

```bash
maka runtime-host access create --principal my-client

# → prints a one-time credential ID, which the CLI stores in the credential store.

```

Revoking access programmatically:

```typescript
import { RuntimeHost } from '@maka/cli';
await RuntimeHost.access.revoke({
  root: '/srv/maka',
  credential: '<credentialId>'
});

```

## Summary

- **Centralized storage**: All secrets live in [`packages/storage/src/credential-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/credential-store.ts), a pure-Node module that encrypts data using OS-level protections like Windows DPAPI.
- **UI isolation**: The renderer receives only masked placeholders via IPC, ensuring raw keys never appear in [`packages/cli/src/tui-copy-catalog.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-copy-catalog.ts) or chat logs.
- **Ephemeral access**: Runtime Host connections use short-lived tokens (default 15 minutes) documented in [`docs/runtime-host-remote-access.md`](https://github.com/apache/maka/blob/main/docs/runtime-host-remote-access.md), revocable via CLI commands.
- **Sandbox safety**: The Runtime Host ([`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md)) resolves credentials by reference only, keeping raw secrets outside the execution boundary.
- **Explicit failures**: The system returns `credential store unavailable` errors rather than falling back to insecure storage, with behavior enforced by tests in [`host-profile.test.ts`](https://github.com/apache/maka/blob/main/host-profile.test.ts) and [`oauth.test.ts`](https://github.com/apache/maka/blob/main/oauth.test.ts).

## Frequently Asked Questions

### Where does Maka physically store API keys and credentials?

Maka writes all secrets to a single encrypted JSON file located adjacent to the desktop profile, implemented in [`packages/storage/src/credential-store.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/credential-store.ts). On Windows, this file is protected by the OS credential manager and DPAPI, ensuring it is accessible only to the current user account.

### How does Maka prevent credentials from leaking into UI logs or chat history?

The TUI and renderer processes query credentials through a safe IPC bridge that returns only confirmation of existence, not the secret value. As implemented in [`packages/cli/src/tui-copy-catalog.ts`](https://github.com/apache/maka/blob/main/packages/cli/src/tui-copy-catalog.ts) at line 143, the UI displays the string "stored only in the local credential store; never written to profiles, arguments, or chat" instead of the actual key material.

### What happens if the credential store is locked or corrupted?

All code paths that interact with the store propagate a `credential store unavailable` error when the store cannot be accessed. This prevents the application from falling back to insecure storage mechanisms or exposing secrets in error messages. Test suites including [`host-profile.test.ts`](https://github.com/apache/maka/blob/main/host-profile.test.ts) and [`oauth.test.ts`](https://github.com/apache/maka/blob/main/oauth.test.ts) verify this behavior.

### How are credentials passed to the sandboxed Runtime Host without exposing raw secrets?

The Runtime Host receives only environment variable **references** (names), not the actual values. According to [`packages/runtime/README.md`](https://github.com/apache/maka/blob/main/packages/runtime/README.md), the product shell resolves these references against the credential store at execution time, ensuring that raw credentials never cross into the sandboxed environment where they could be extracted by malicious code.