OS Keychain Management
Relevant source files
The following files were used as context for generating this wiki page:
The OS Keychain Management system in M31 Autonomous (M31A) provides a unified, cross-platform abstraction for securely storing sensitive information, specifically API keys for LLM providers like OpenRouter, Zen, and Nvidia. By leveraging native operating system secret stores, M31A ensures that sensitive credentials are never written to the filesystem in plaintext.
Sources: README.md:120-121, CONTRIBUTING.md:41-42
Architecture and Platform Support
M31A implements a "one code path, three backends" architecture. It abstracts the complexities of different OS credential managers into a single internal API used by the application's configuration and provider modules.
Platform Backends
| Operating System | Backend Mechanism | Implementation File |
|---|---|---|
| Linux | D-Bus / Secret Service API | pkg/keychain/keychain_linux.go |
| macOS | Apple Keychain | pkg/keychain/keychain_darwin.go |
| Windows | Windows Credential Manager | pkg/keychain/keychain_windows.go |
Sources: README.md:231-233, scripts/validate-release.sh:565-573, scripts/verify_v1.sh:111-114
The following diagram illustrates how the M31A application interacts with the platform-specific keychain implementations:
The diagram shows the modular structure where a single package provides platform-specific implementations for secret storage.
Sources: pkg/keychain/keychain_linux.go, pkg/keychain/keychain_darwin.go, pkg/keychain/keychain_windows.go
Security and Protection Mechanisms
The keychain system is a critical component of the M31A security model, designed to prevent credential exposure.
Resolution Order
M31A follows a strict priority when resolving API keys to ensure the most secure method is attempted first:
- Environment Variables: Checked first for transient or CI/CD usage.
- OS Keychain: Checked second to retrieve persistently stored encrypted secrets.
- Config File: Checked last as a fallback.
Sources: CONTRIBUTING.md:41-42
Path Traversal Protection
The system includes specialized hardening to prevent directory traversal attacks within the keychain service names. The sanitizeService function is utilized to block attempts to manipulate secret paths.
Sources: README.md:236-237, README.md:418
Security Validation
The release pipeline includes automated checks to ensure the integrity of the keychain system, verifying that API keys are never stored in plaintext and that no hardcoded keys exist in the source code.
This sequence shows the secure retrieval flow including path sanitization.
Sources: README.md:418, scripts/validate-release.sh:502-515
Implementation Details
The implementation relies on native system calls or standard library wrappers for each platform to maintain a zero-telemetry and static-binary profile (CGO_ENABLED=0).
Key Components
- Service Name Sanitization: Ensures that strings passed to the OS-level credential managers do not contain malicious path segments.
- Provider Registration: During the first launch or via CLI, M31A prompts for keys and stores them immediately in the detected OS backend.
Sources: README.md:120-121, README.md:236-237, scripts/validate-release.sh:51-54
Summary
The OS Keychain Management system is fundamental to M31A's "Security-First" approach. By abstracting Linux, macOS, and Windows secret stores, the project provides developers with a seamless way to handle sensitive LLM provider credentials without risking accidental plaintext exposure in configuration files or logs. This system, verified through rigorous release validation scripts, ensures that M31A remains a secure tool for professional software development.