How Credentials Are Stored and Protected in Apache Maka

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 located within the runtime-policy directory. According to the source code in 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:

• 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 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 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, 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, 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:

// 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)
});

// 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 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.
• 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 within the runtime-policy directory, as defined in 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.

How does Maka prevent credential leaks in error messages?

As implemented in 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, ensures that each credential source (e.g., a specific environment variable) maps to exactly one entry, preventing ambiguity during credential resolution.

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