# How Credentials Are Stored and Protected in Apache Maka

> Discover how Apache Maka secures user credentials in a dedicated JSON vault. Learn about its size limits, atomic operations, and API access for robust protection against exposure.

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

---

**Apache Maka stores user secrets in a dedicated JSON-based credential vault with strict 64 KB size limits, atomic file operations, and API-mediated access that prevents credential exposure in logs or UI leaks.**

Apache Maka implements a defense-in-depth strategy for sensitive data by persisting API keys and OAuth tokens in a bounded, validated credential vault rather than environment variables or plain text configuration files. Understanding how credentials are stored and protected in Maka requires examining the architectural safeguards in the storage layer, the atomic persistence mechanisms, and the runtime privacy controls that collectively prevent unauthorized access and accidental leakage.

## Credential Vault Architecture

### File Location and Data Model

Maka persists credentials in a dedicated file named [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) located within the runtime-policy directory. According to the source code in [`packages/storage/src/runtime-policy/credential-vault-document.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/credential-vault-document.ts), this file serves as the single source of truth for all user-provided secrets including API keys and OAuth tokens.

Each entry in the vault implements the `CredentialVaultEntry` interface, which stores:

- A `secret` string containing the actual credential material
- A `locator` object describing the credential's origin (environment variable, saved settings, etc.)
- A unique `credentialId` for referencing specific entries
- A revision number for optimistic concurrency control
- An `updatedAt` timestamp for audit purposes

### Strict Size Limits and Validation

The vault enforces hard boundaries to prevent abuse and ensure predictable performance. As defined in [`credential-vault-document.ts`](https://github.com/apache/maka/blob/main/credential-vault-document.ts):

- **Maximum secret size**: 64 KB (`MAX_SECRET_LENGTH`)
- **Maximum entries**: 2,048 credentials (`MAX_VAULT_ENTRIES`)
- **Document size limit**: Enforced by `VAULT_DOCUMENT_MAX_BYTES` during read/write operations

Before storage, all incoming secrets pass through `normalizeCredentialSecret` and `normalizeSetCredentialInput` functions that enforce these length limits and sanitize values. This validation occurs at the API boundary, ensuring only normalized data reaches the persistence layer.

## Secure Persistence Mechanisms

### Atomic Read/Write Operations

The `CredentialVaultDocumentOwner` class provides the exclusive interface for vault operations, guaranteeing data integrity through atomic file operations. When reading, the `read()` method uses `readBoundedJsonDocument` to safely load the vault while validating the schema version and entry structure. This function ensures unique locators and IDs before returning data to callers.

For writes, the implementation in [`packages/storage/src/runtime-policy/document-io.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/document-io.ts) uses a write-to-temp-then-rename pattern via `writeJsonDocument`. This approach prevents partial writes or corruption if the process crashes during persistence. The write operation first validates that the serialized document does not exceed `VAULT_DOCUMENT_MAX_BYTES`, rejecting oversized payloads before they touch the filesystem.

### Controlled Access API

Access to the vault is strictly mediated through the `CredentialVaultDocumentOwner` API. The storage layer isolates the [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) file within the runtime-policy directory, and callers cannot interact with the file directly. Instead, they must use the defined methods—`read()`, `set()`, and `delete()`—which perform comprehensive validation of size limits, schema compliance, and uniqueness constraints before persisting any changes.

## Runtime Privacy Protections

### Preventing Credential Leaks in Logs

Maka deliberately prevents credential exposure in logs and error streams. As noted in comments within [`packages/ui/src/tool-output-stream.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-output-stream.ts), the codebase explicitly avoids echoing credentials in provider error bodies that might be logged to the console. Secrets remain in-memory only during active use and are never serialized to logging facilities, ensuring that debug output or crash reports cannot leak sensitive material.

### UI Transparency Without Exposure

The user interface provides visibility into credential provenance without revealing secret values. In [`packages/ui/src/tool-activity/copy.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-activity/copy.ts), the UI displays the origin of each credential—whether sourced from environment variables, saved keys, or marked as missing—using the `locator.scope` property. This transparency helps users understand protection levels while ensuring the actual `secret` strings remain masked in the interface.

## Programmatic Vault Operations

The following examples demonstrate how to interact with the credential vault through the supported API:

```typescript
// Load the current vault
const vault = new CredentialVaultDocumentOwner();
const doc = await vault.read('/path/to/runtime-policy');

// Add or update a credential (validation guarantees secret ≤ 64 KB)
await vault.set('/path/to/runtime-policy', {
  locator: { scope: 'environment', name: 'MAKA_TAVILY_API_KEY' },
  secret: 'my-super-secret-key',
  expected: null,  // no prior version expected (create new)
});

```

```typescript
// Delete a credential (must provide expected version to prevent races)
await vault.delete('/path/to/runtime-policy', {
  expected: {
    locator: { scope: 'environment', name: 'MAKA_TAVILY_API_KEY' },
    credentialId: '123e4567-e89b-12d3-a456-426614174000',
    revision: 3,
  },
});

```

## Summary

- **Dedicated vault file**: Credentials reside in [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) managed exclusively through the `CredentialVaultDocumentOwner` class.
- **Hard size limits**: Secrets cannot exceed 64 KB, and the vault cannot hold more than 2,048 entries, enforced by `MAX_SECRET_LENGTH` and `MAX_VAULT_ENTRIES`.
- **Atomic persistence**: Write operations use temporary files and atomic renames to prevent corruption, implemented in [`packages/storage/src/runtime-policy/document-io.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/document-io.ts).
- **API-mediated access**: Direct file access is prohibited; all interactions route through validated methods that check schema versions, uniqueness, and bounds.
- **Runtime protection**: Secrets are excluded from logs and UI error messages, with source tracking visible only through the `locator` metadata.

## Frequently Asked Questions

### Where does Maka store credential files locally?

Maka stores credentials in a file named [`credential-vault.json`](https://github.com/apache/maka/blob/main/credential-vault.json) within the runtime-policy directory, as defined in [`packages/storage/src/runtime-policy/credential-vault-document.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/credential-vault-document.ts). This location is isolated from user configuration files and accessed exclusively through the storage layer's `CredentialVaultDocumentOwner` API.

### What is the maximum size limit for secrets in Maka?

Individual secrets are limited to 64 KB (`MAX_SECRET_LENGTH`), and the entire vault cannot exceed 2,048 entries (`MAX_VAULT_ENTRIES`). Additionally, the serialized JSON document must remain under `VAULT_DOCUMENT_MAX_BYTES` as enforced during read and write operations in [`document-io.ts`](https://github.com/apache/maka/blob/main/document-io.ts).

### How does Maka prevent credential leaks in error messages?

As implemented in [`packages/ui/src/tool-output-stream.ts`](https://github.com/apache/maka/blob/main/packages/ui/src/tool-output-stream.ts), Maka deliberately avoids echoing credential values in provider error bodies that might propagate to logs. The UI and logging layers treat the `secret` property of `CredentialVaultEntry` as sensitive, displaying only the `locator` metadata (source information) while masking the actual values.

### Can multiple credentials share the same locator in the vault?

No. The `CredentialVaultDocumentOwner.read()` method explicitly validates that all locators within the vault are unique. This constraint, enforced in [`packages/storage/src/runtime-policy/credential-vault-document.ts`](https://github.com/apache/maka/blob/main/packages/storage/src/runtime-policy/credential-vault-document.ts), ensures that each credential source (e.g., a specific environment variable) maps to exactly one entry, preventing ambiguity during credential resolution.