Skip to content

privacy-and-data-flow.md

Latest commit

 

History

History
117 lines (89 loc) · 5.03 KB

privacy-and-data-flow.md

File metadata and controls

117 lines (89 loc) · 5.03 KB
Raw

Privacy and Data Flow

This document describes what the current source reads, holds temporarily, and persists. It does not treat operating-system permissions or the selected Codex executable's behavior as privacy guarantees of this app.

Codex Home and Authentication File

CODEX_HOME is resolved in this order: the override in Settings, a non-empty CODEX_HOME in the launch environment, then ~/.codex under the current user's home directory. The result must be an existing directory.

The app opens auth.json under the effective Home. The reader rejects symbolic links and non-regular files and limits the file size to 1 MiB. Up to 1 MiB of the complete auth.json bytes briefly enters app process memory; the decoded model reads only tokens.account_id. Other fields do not enter the model or get written to app state, but they were still present in the original in-memory file bytes.

The reader compares device, inode, size, modification time, and status-change time before and after reading and rechecks the current path. The code does not promise reliable zeroing of these original bytes or the account ID.

Account Identity

A non-empty account ID is immediately processed with HMAC-SHA256. The key is a 32-byte random salt generated in Keychain. The output is encoded as 64 lowercase hexadecimal characters (256 bits). The state file uses this digest as the account key and does not store the original account ID.

The production Keychain tuple is:

  • service: org.codexquota.monitor.identity-salt
  • account: account-hash-salt-v1

The development build uses org.codexquota.monitor.dev.identity-salt with the same account name. The Keychain item is non-synchronizable and uses AfterFirstUnlockThisDeviceOnly.

State File

The production state path is ~/Library/Application Support/CodexQuota/state.json; the development build uses ~/Library/Application Support/CodexQuota-Dev/state.json. Directory permissions are restricted to the current user, and the state file is written with mode 0600.

The current persistence schema is 3. It stores:

  • custom Codex executable and CODEX_HOME override paths;
  • Launch at Login, notification, and interface preferences;
  • user-entered custom markers, preset symbols, and colors;
  • canonical path, device, inode, size, modification/status-change times, and SHA-256 from the trust receipt;
  • account HMACs, two logical slots, and last confirmed quota snapshots;
  • notification deduplication state, screen identifier, panel edge, and vertical position.

Custom paths may contain the local user name, and custom markers are stored in plain text. Never use a token, password, or other credential as a marker. The persisted marker shape is accountMarkers → delta/epsilon → content(kind,value)+rgb; delta and epsilon are internal logical slots, not real account IDs.

The app does not automatically write original account IDs, access tokens, refresh tokens, cookies, Authorization headers, or complete protocol payloads from auth.json or app-server responses to the state file. User-entered custom markers are the exception: marker text is persisted as entered, so never use a credential as a marker.

app-server Data Flow

The app launches the selected Codex executable with app-server --listen stdio:// and exchanges line-delimited JSON over stdin/stdout. The current methods and notifications are:

  • initialize / initialized;
  • account/read with refreshToken: false;
  • account/rateLimits/read;
  • account/updated;
  • account/rateLimits/updated.

Account details returned by account/read are used only to verify the current connection and are not written directly to the state file. Quota responses are converted to confirmed, per-window snapshots containing usage percentage, reset time, window duration, and confirmation time.

Network and Subprocess Environment

Codex Quota itself has no telemetry, cloud sync, or project-operated remote service. It communicates with the Codex subprocess over local stdio, but that does not make the complete runtime offline: the Codex subprocess may access the network.

The subprocess inherits only these non-empty launch-environment values:

  • language and time zone: LANG, LANGUAGE, LC_ALL, LC_CTYPE, LC_MESSAGES, TZ;
  • proxy: HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, NO_PROXY, and their lowercase forms;
  • certificates: SSL_CERT_FILE, SSL_CERT_DIR.

The app also sets CODEX_HOME, HOME, a fixed PATH, and TMPDIR. The fixed PATH is /opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin. The environment allowlist does not reduce the subprocess's existing current-user file permissions.

Notifications and Deletion

Quota alerts are disabled by default. The app requests system notification permission only after the user enables alerts. Notification titles use the visible account marker; deduplication records use an internal identifier.

Removing the app does not automatically delete state or the Keychain salt. Delete only this product's Application Support directory and corresponding Keychain tuple. Do not delete CODEX_HOME, ~/.codex, or auth.json.