mirror of
https://github.com/tiennm99/ccs.git
synced 2026-10-03 20:13:02 +00:00
74 lines
3.2 KiB
Markdown
74 lines
3.2 KiB
Markdown
# Codex Auth Developer Contract
|
|
|
|
The canonical [Codex Adapter guide](https://docs.ccs.kaitran.ca/features/workflow/codex-adapter)
|
|
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`](../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`](../src/codex-auth/commands/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
|
|
|
|
```text
|
|
~/.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`](../src/codex-auth/codex-config-symlink.ts),
|
|
[`codex-profile-resources.ts`](../src/codex-auth/codex-profile-resources.ts),
|
|
and
|
|
[`codex-profile-plugin-cache.ts`](../src/codex-auth/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/`.
|