Data Storage & Secrets
Relevant source files
The following files were used as context for generating this wiki page:
The Data Storage and Secrets system in CCS manages the persistence, protection, and retrieval of configuration files, authentication tokens, and profile-specific resources. It provides a unified interface for handling sensitive data across multiple runtimes, including Claude Code, Codex, and various API providers.
The system ensures that sensitive credentials like API keys are never exposed in plaintext during diagnostic summaries or logs, utilizing redaction and masking techniques. Configuration is primarily stored in YAML and TOML formats, with localized storage in a dedicated directory structure (usually ~/.ccs).
Configuration Architecture
CCS uses a hierarchical configuration structure that prioritizes per-variant or per-profile settings over global defaults. The primary configuration file is config.yaml, which is generated with descriptive comments and structured sections.
Primary Storage Components
| Component | File/Path | Description |
|---|---|---|
| Unified Config | config.yaml | The main CCS configuration file containing accounts, profiles, and preferences. |
| Codex Config | config.toml | Upstream-owned configuration file for Codex CLI integration. |
| Profile Settings | *.settings.json | Environment variables and specific settings for individual API profiles. |
| Shared Resources | .ccs/shared/ | Symlinked or copied directories for agents, skills, and plugins. |
| Auth Registry | codex-profiles.yaml | Registry for managing multiple Codex authentication instances. |
Sources: src/config/loader/yaml-serializer.ts:16-18, tests/unit/web-server/codex-dashboard-service.test.ts:98-102, tests/integration/web-server/codex-profiles-endpoint.test.ts:100-104
Configuration Serialization Flow
When saving the unified configuration, the system generates a commented YAML file to maintain readability for manual edits.
The serializer includes specific sections for accounts, profiles, CLIProxy variants, and global environment variables.
Sources: src/config/loader/yaml-serializer.ts:25-300
Secret Management & Redaction
Secrets are managed through an inheritance chain and are protected by masking and redaction filters before being surfaced in the UI or diagnostics.
Token Inheritance Logic
The system resolves API keys based on the following priority:
- Per-variant override: Specific key defined for a CLIProxy variant (e.g.,
gemini). - Global CLIProxy Auth: A general key defined in the
cliproxy.authsection. - Internal Default: The hardcoded
ccs-internal-managedconstant.
Sources: src/cliproxy/auth/tests/auth-token-manager.test.js:150-170
Security Filters and Redaction
Diagnostic summaries automatically redact sensitive URLs and environment variable values. URLs are shortened to their protocol (e.g., [redacted:https]), and set environment variables are marked as [set].
The masking function specifically shows the first four and last four characters of a token if it is longer than 8 characters; otherwise, it returns ****.
Sources: tests/unit/web-server/codex-dashboard-service.test.ts:114-122, src/cliproxy/auth/tests/auth-token-manager.test.js:108-115
Resource Storage & Symlinking
To avoid "config thrash," CCS manages resources like agents, skills, and settings through a shared directory structure, often utilizing symbolic links to bridge data between CCS and native CLI home directories (e.g., ~/.claude or ~/.codex).
Shared Resource Layout
| Type | Source Path | Target/Link Path |
|---|---|---|
| Skills | ~/.claude/skills/ | .ccs/shared/skills/ |
| Agents | ~/.claude/agents/ | .ccs/shared/agents/ |
| Settings | ~/.claude/settings.json | .ccs/shared/settings.json |
Sources: tests/unit/web-server/shared-routes.test.ts:150-170, tests/unit/codex-auth/codex-profile-resources.test.ts:34-40
Resource Linking Sequence
When initializing a profile, the system ensures that shared resources are correctly linked or copied to the profile-specific directory.
The system includes fallback logic to copy files if symbolic link creation is restricted by the operating system (e.g., EPERM or EACCES errors).
Sources: tests/unit/codex-auth/codex-profile-resources.test.ts:70-85, tests/unit/web-server/shared-routes.test.ts:15-30
Data Access & Security Guards
The web server implements specific guards to protect configuration data from unauthorized access, particularly when the dashboard is running.
Localhost Access Guard
To prevent remote exploitation when dashboard authentication is disabled, certain endpoints (like /api/codex/profiles) verify that the request originates from the loopback address (127.0.0.1). If the Host or Origin headers indicate a non-local origin even with a loopback IP, the request is rejected with a 403 Forbidden status.
Sources: tests/integration/web-server/codex-profiles-endpoint.test.ts:165-185
Conflict Detection
To prevent accidental data loss during concurrent edits, the system uses modification times (mtime) as a locking mechanism.
expectedMtime: When saving a raw configuration or patching a setting, the client must provide themtimeit last read.- Conflict Error: If the file's current
mtimeon disk differs from theexpectedMtime, the system rejects the write with aCodexRawConfigConflictError.
Sources: tests/unit/web-server/codex-dashboard-service.test.ts:285-295, ui/src/pages/codex.tsx:112-120
Summary
The CCS Data Storage & Secrets system provides a robust framework for managing diverse configuration formats while maintaining strict security boundaries. By combining hierarchical settings resolution with automatic redaction and filesystem-level resource sharing, it enables seamless switching between AI providers without exposing sensitive credentials or duplicating configuration logic.