Architecture of the Credential Vault in Apache Maka: Bounded JSON Storage for Workspace Secrets

The Apache Maka credential vault is a bounded JSON document that stores API keys and passwords with optimistic concurrency control, protected by strict size limits and revision-based versioning.

Apache Maka manages sensitive workspace secrets through a centralized Credential Vault implemented as a single JSON file. Unlike external secret managers, Maka embeds the vault directly in workspace storage, using a prepare → commit pattern to ensure atomic updates and detect concurrent modifications. Understanding the architecture of the credential vault in Apache Maka is essential for developers integrating custom providers or maintaining the storage layer.

Core Document Structure

The vault persists as credential-vault.json and is modeled by the CredentialVaultDocument interface defined in packages/storage/src/runtime-policy/credential-vault-document.ts. This schema balances flexibility with strict resource constraints.

Schema Definition

Each document contains a fixed schemaVersion, a monotonically increasing revision number, and an array of CredentialVaultEntry objects. Individual entries include:

• locator: A CredentialLocator identifying the credential's purpose
• credentialId: A UUID generated for each secret
• secret: The encrypted or plaintext value (subject to length limits)
• updatedAt: ISO timestamp tracking last modification

The schema is enforced at lines 49‑63 of credential-vault-document.ts, where TypeScript interfaces define the contract between storage and runtime policy.

Hard Limits and Resource Bounds

To prevent uncontrolled growth, the implementation enforces three critical constants at lines 37‑38, lines 51‑53, and lines 84‑86:

• Max secret length: 64 KB per entry (MAX_SECRET_LENGTH)
• Max entries: 2,048 credentials per workspace (MAX_VAULT_ENTRIES)
• Document size cap: Enforced by VAULT_DOCUMENT_MAX_BYTES during I/O operations

These bounds ensure that the vault remains performant and portable across different Maka deployments, from CLI tools to desktop applications.

Credential Identification and Scoping

Secrets are not stored by arbitrary keys. Instead, the vault uses CredentialLocator objects defined in packages/core/runtime-policy.ts to determine where a credential applies.

Locator Scopes and Deduplication

Each locator specifies one of three scopes: connection, web_search, or network_proxy. The locatorKey function (implemented at lines 67‑76 of the vault document module) generates a unique string key from the locator fields, enabling deduplication. The sameLocator utility compares locators to prevent duplicate entries for identical resources.

This design allows bulk operations such as deleteConnectionCredentials to filter entries by connectionId without scanning unrelated secrets.

Concurrency Control and Versioning

The vault implements an optimistic concurrency model rather than file locking. Every mutation requires the caller to supply an expected revision; mismatches signal stale data.

Revision Tracking

Both the document and individual entries carry revision numbers. When CredentialVaultDocumentOwner.set() or delete() is invoked, the prepareSet or prepareDelete helper validates the provided expected version against the stored entry via matchesExpectation (lines 89‑99). If the check fails, the operation returns a credential_stale result instead of modifying the vault.

This pattern allows CLI tools and desktop UIs to implement conflict resolution workflows without blocking the filesystem.

Immutable Snapshots

Read operations return a CredentialVaultSnapshot via vaultSnapshot (lines 46‑51), containing the current document revision and an array of credential statuses computed by credentialStatusFromEntry (lines 53‑56). Snapshots are frozen views; mutations always operate on the underlying document before atomically persisting changes.

Persistence and I/O Architecture

The CredentialVaultDocumentOwner class delegates filesystem operations to bounded I/O helpers in packages/storage/src/runtime-policy/document-io.ts.

Bounded JSON Operations

The readBoundedJsonDocument function validates file size against VAULT_DOCUMENT_MAX_BYTES before parsing, while writeJsonDocument serializes and atomically writes the vault. At lines 31‑34 and lines 36‑38, the owner class wraps these helpers to ensure every write path re-validates document size before committing to disk.

This architecture prevents disk saturation attacks and guarantees that partially written files never corrupt the vault state.

High-Level API Reference

The CredentialVaultDocumentOwner class exposed in packages/storage/src/runtime-policy/credential-vault-document.ts provides the primary interface for credential management.

Reading the Vault

The read(root) method loads credential-vault.json from the specified workspace root. If the file is absent, it initializes an empty vault with schemaVersion 1 and revision 0.

import { CredentialVaultDocumentOwner } from '@maka/storage/runtime-policy/credential-vault-document';

const vaultOwner = new CredentialVaultDocumentOwner();
const vault = await vaultOwner.read('/path/to/maka/profile');
console.log('Current revision:', vault.revision);

Writing Credentials

The set(root, input) method accepts a SetCredentialInput containing a locator, secret value, and optional expected version. It uses the prepare → commit pattern to validate size constraints before persisting.

import { CredentialVaultDocumentOwner } from '@maka/storage/runtime-policy/credential-vault-document';
import type { SetCredentialInput } from '@maka/core/runtime-policy';

const vaultOwner = new CredentialVaultDocumentOwner();

const input: SetCredentialInput = {
  locator: { scope: 'connection', kind: 'api_key', connectionId: 'github' },
  secret: 'ghp_XXXXXXXXXXXXXXXXXXXX',
  expected: null, // No version check for initial write
};

const result = await vaultOwner.set('/path/to/maka/profile', input);
if (result.kind === 'committed') {
  console.log('Stored at revision:', result.snapshot.revision);
}

Deletion and Bulk Cleanup

Individual deletion uses delete(root, input) with a DeleteCredentialInput containing the credential ID and expected revision. For maintenance, deleteConnectionCredentials and deleteOrphanedConnectionCredentials filter the entry array by connection scope and persist the reduced document atomically.

import { CredentialVaultDocumentOwner } from '@maka/storage/runtime-policy/credential-vault-document';
import type { DeleteCredentialInput } from '@maka/core/runtime-policy';

const vaultOwner = new CredentialVaultDocumentOwner();

const deleteInput: DeleteCredentialInput = {
  expected: {
    locator: { scope: 'connection', kind: 'api_key', connectionId: 'github' },
    credentialId: 'c1a2b3d4-5678-90ab-cdef-1234567890ab',
    revision: 3,
  },
};

const result = await vaultOwner.delete('/path/to/maka/profile', deleteInput);
if (result.kind === 'credential_stale') {
  console.warn('Concurrent modification detected — refetch and retry.');
}

Summary

• The Credential Vault is a single JSON file (credential-vault.json) governed by CredentialVaultDocumentOwner in packages/storage/src/runtime-policy/credential-vault-document.ts.
• Strict limits enforce 64 KB maximum secret size, 2,048 entries per workspace, and bounded document size to prevent resource exhaustion.
• Optimistic concurrency via revision numbers ensures thread-safe updates without file locks, returning credential_stale when versions mismatch.
• Scoped locators (connection, web_search, network_proxy) enable precise deduplication and bulk deletion of orphaned credentials.
• Bounded I/O helpers in document-io.ts validate size constraints during read and write operations, ensuring atomic persistence.

Frequently Asked Questions

Where is the credential vault physically stored in an Apache Maka workspace?

The vault persists as credential-vault.json in the Maka workspace profile directory. The CredentialVaultDocumentOwner class uses readBoundedJsonDocument and writeJsonDocument from packages/storage/src/runtime-policy/document-io.ts to perform bounded I/O operations against this file, ensuring that document size never exceeds VAULT_DOCUMENT_MAX_BYTES during persistence.

How does Apache Maka prevent concurrent writes from corrupting the credential vault?

Maka implements optimistic concurrency control through revision numbering. Every entry and the vault document itself maintain a revision counter; when calling set() or delete(), callers provide an expected version. The matchesExpectation function (lines 89‑99 of credential-vault-document.ts) validates this version, and if the stored data has changed, the operation returns a credential_stale result without writing, allowing the caller to retry with fresh data.

What are the hard limits enforced on secrets stored in Apache Maka?

According to the constants defined at lines 37‑38, lines 51‑53, and lines 84‑86 of the vault document implementation, secrets are constrained by MAX_SECRET_LENGTH (64 KB per credential), MAX_VAULT_ENTRIES (2,048 total entries per workspace), and VAULT_DOCUMENT_MAX_BYTES (total document size). These limits are validated during the prepareSet phase before any write operation commits to disk.

Can credentials be grouped or bulk-deleted by connection in Apache Maka?

Yes. The deleteConnectionCredentials and deleteOrphanedConnectionCredentials methods filter the CredentialVaultEntry array by connection ID scope. These bulk helpers replace the entire document atomically after filtering, making them efficient for cleanup operations when removing deprecated provider configurations without iterating through individual delete() calls.

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