ccs/docs/codex-auth.md

Codex Auth Developer Contract

The canonical Codex Adapter guide owns user setup. This local contract documents active ccsx auth invariants that contributors and operators must preserve.

Command Surface

ccsx auth owns create, login, switch, use, show, remove, and import-default. Keep syntax and option changes sourced from src/codex-auth/codex-auth-help.ts rather than copying a long command reference here.

• create <name> is idempotent and starts native codex login for new profiles. --force repairs shared resources without replacing auth.json.
• switch <name> changes the persistent registry default.
• use <name> emits only shell-evaluable CODEX_HOME and CCS_CODEX_PROFILE assignments to stdout. It affects the current shell after eval/source; diagnostics stay on stderr.
• ccsx <name> launches a named profile directly without changing the persistent default.

Import Safety

import-default <name> imports native ~/.codex/auth.json without deleting the source. The implementation in import-default-command.ts must continue to:

• refuse import while a current-user Codex process may be refreshing tokens, unless the operator explicitly accepts the race with --force-while-running;
• retry and validate JSON/JWT shape, reject CLIProxy auth-file formats, and fail without registering a profile when a torn write persists;
• write the destination atomically with private permissions;
• omit history and sessions unless --with-history is requested;
• refuse an existing profile unless --force is used, and preserve its current auth.json as auth.json.bak-<timestamp> before overwrite.

Storage And Cross-Platform Fallback

~/.ccs/
├── codex-profiles.yaml
└── codex-instances/<name>/
    ├── auth.json, history.jsonl, sessions/   # profile-local
    ├── config.toml -> ~/.codex/config.toml
    ├── agents/ -> ~/.codex/agents/
    ├── skills/ -> ~/.codex/skills/
    └── plugins/
        └── cache/ -> ~/.codex/plugins/cache/

The plugins/ parent stays profile-local. Shared config, resources, and plugin cache repair must preserve existing profile-local content. On Windows or other systems where symlinks are unavailable, CCS copies missing shared content into the profile and warns that later upstream edits will not propagate automatically. See codex-config-symlink.ts, codex-profile-resources.ts, and codex-profile-plugin-cache.ts.

ccsx And ccsxp Isolation

ccsx auth applies only to native Codex profiles. ccsxp ignores CCS_CODEX_PROFILE, uses native ~/.codex history by default, and routes through its separate CLIProxy Codex pool. CCSXP_CODEX_HOME is its explicit home override. Never make a ccsx auth switch silently redirect ccsxp, merge their auth stores, or consume ccsx import backups as pool credentials.

Behavior locks live under tests/unit/codex-auth/ and tests/integration/codex-auth/.