@simonesiega/codex-limits 0.1.3 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/.env.example +10 -13
  2. package/CHANGELOG.md +60 -13
  3. package/LICENSE +21 -21
  4. package/README.md +136 -49
  5. package/SECURITY.md +96 -0
  6. package/dist/cli.js +173 -42823
  7. package/dist/index.js +3 -1078
  8. package/docs/photos/terminal/final_result_small.png +0 -0
  9. package/package.json +12 -8
  10. package/scripts/postinstall.cjs +15 -6
  11. package/types/index.d.ts +2 -3
  12. /package/docs/photos/terminal/{final_result.png → final_result_large.png} +0 -0
package/.env.example CHANGED
@@ -1,21 +1,18 @@
1
1
  # Optional: override the local Codex data directory inspected by codex-limits.
2
- # Leave unset to use the default platform-specific candidate paths.
2
+ # Leave unset to use CODEX_HOME and then the default platform-specific candidates.
3
3
  CODEX_LIMITS_HOME=
4
4
 
5
- # Optional fallback: codex-limits reads ~/.codex/auth.json automatically when available.
6
- # The tool calls the live Codex reset-credit endpoint at chatgpt.com only when credentials are found.
5
+ # Optional: Codex's native home override. CODEX_LIMITS_HOME takes precedence.
6
+ CODEX_HOME=
7
7
 
8
- # MacOS/Linux:
9
- # jq -r '.tokens.account_id // empty' ~/.codex/auth.json
10
- # Windows PowerShell:
11
- # (Get-Content "$env:USERPROFILE\.codex\auth.json" -Raw | ConvertFrom-Json).tokens.account_id
8
+ # Optional credential fallback. Prefer automatic auth.json discovery when available.
9
+ # Never commit real values or paste them into issue reports, logs, or screenshots.
12
10
  CODEX_LIMITS_ACCOUNT_ID=
13
-
14
- # MacOS/Linux:
15
- # jq -r '.tokens.access_token // empty' ~/.codex/auth.json
16
- # Windows PowerShell:
17
- # (Get-Content "$env:USERPROFILE\.codex\auth.json" -Raw | ConvertFrom-Json).tokens.access_token
18
11
  CODEX_LIMITS_ACCESS_TOKEN=
19
12
 
20
- # Optional: override the live usage endpoint if ChatGPT changes the Codex usage API path.
13
+ # Optional: override the live usage endpoint for advanced setups or local testing.
14
+ # HTTPS is required except for loopback HTTP (localhost, 127.0.0.1, or ::1).
21
15
  CODEX_LIMITS_USAGE_ENDPOINT=
16
+
17
+ # Optional: suppress global-install guidance from the non-interactive postinstall script.
18
+ CODEX_LIMITS_SKIP_INIT=
package/CHANGELOG.md CHANGED
@@ -1,13 +1,60 @@
1
- # Changelog
2
-
3
- All notable changes to codex-limits are documented in this file.
4
-
5
- ## [0.1.0] - 2026-07-05
6
-
7
- ### Added
8
-
9
- - Added the shared core API for Codex usage limits and reset-credit coupons.
10
- - Added the read-only Ink terminal dashboard with usage limit cards and reset coupon panels.
11
- - Added non-interactive `status`, `coupons`, and JSON command output.
12
- - Added an opencode plugin that registers `/codex-limits` without sending a prompt to the LLM.
13
- - Added `codex-limits init` and npm postinstall setup for optional agent integrations.
1
+ # Changelog
2
+
3
+ All notable changes to codex-limits are documented in this file.
4
+
5
+ ## [Unreleased]
6
+
7
+ ### Breaking Changes
8
+
9
+ ### Added
10
+
11
+ ### Changed
12
+
13
+ ### Fixed
14
+
15
+ ### Removed
16
+
17
+ ### Security
18
+
19
+ ## [0.1.4] - 2026-07-13
20
+
21
+ ### Added
22
+
23
+ - Added responsive dashboard layouts for wide, compact, short, and very small terminals.
24
+ - Added GitHub Actions checks and npm Trusted Publishing workflows.
25
+ - Added consistent Prettier formatting and package-artifact smoke validation.
26
+
27
+ ### Changed
28
+
29
+ - Changed npm artifacts to use self-contained runtime bundles and TypeScript-generated root plugin declarations, reducing installation dependencies while preserving the default and named `tui` exports.
30
+ - Changed `bun run check` to verify formatting, types, tests, production builds, package metadata, and isolated packed artifacts.
31
+ - Changed malformed, duplicate, conflicting, and extra CLI arguments to fail deterministically on stderr.
32
+
33
+ ### Fixed
34
+
35
+ - Fixed partial live usage windows being discarded when local usage data was unavailable.
36
+ - Fixed malformed, oversized, timed-out, aborted, and non-successful live responses to produce stable warnings and safe local fallback behavior.
37
+ - Fixed OpenCode registration and disposal to remain idempotent while supporting both command APIs.
38
+
39
+ ### Security
40
+
41
+ - Bounded local traversal, file sizes, JSONL line sizes, credential files, and live response bodies while skipping nested symbolic links.
42
+ - Prevented authenticated redirects, rejected unsafe endpoint protocols, and removed raw exception details from CLI and OpenCode errors.
43
+ - Strengthened warning and JSON redaction so credentials, private paths, authenticated headers, and internal source metadata do not reach public output.
44
+
45
+ ## [0.1.3] - 2026-07-09
46
+
47
+ ### Fixed
48
+
49
+ - Fixed `codex-limits init --opencode` to install the scoped OpenCode plugin package.
50
+ - Fixed OpenCode command registration to keep `/codex-limits` available with both legacy and current TUI plugin APIs.
51
+
52
+ ## [0.1.0] - 2026-07-05
53
+
54
+ ### Added
55
+
56
+ - Added the shared core API for Codex usage limits and reset-credit coupons.
57
+ - Added the read-only Ink terminal dashboard with usage limit cards and reset coupon panels.
58
+ - Added non-interactive `status`, `coupons`, and JSON command output.
59
+ - Added an opencode plugin that registers `/codex-limits` without sending a prompt to the LLM.
60
+ - Added `codex-limits init` and npm postinstall setup for optional agent integrations.
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Simone Siega
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Simone Siega
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -19,16 +19,73 @@
19
19
  <p align="center">
20
20
  <img src="https://img.shields.io/npm/v/@simonesiega/codex-limits?label=npm" alt="npm version" />
21
21
  <img src="https://img.shields.io/badge/TypeScript-5-blue?logo=typescript" alt="TypeScript" />
22
- <img src="https://img.shields.io/badge/Bun-runtime-black?logo=bun" alt="Bun" />
22
+ <img src="https://img.shields.io/badge/Bun-toolchain-black?logo=bun" alt="Bun toolchain" />
23
23
  </p>
24
24
 
25
- ## Final result 🚀
25
+ ## Preview 🚀
26
26
 
27
27
  <p align="center">
28
- <img src="docs/photos/terminal/final_result.png" alt="Final codex-limits terminal dashboard" width="740" />
28
+ <img src="docs/photos/terminal/final_result_large.png" alt="Final codex-limits larger terminal dashboard" width="400" />
29
+ <img src="docs/photos/terminal/final_result_small.png" alt="Final codex-limits smaller terminal dashboard" width="400" />
29
30
  </p>
30
31
 
31
- The screenshot shows the final **`codex-limits`** terminal dashboard: a clean, read-only TUI that summarizes Codex usage limits and reset-credit coupons in one place. The top section displays the current 5-hour and weekly usage windows with remaining percentages, visual progress bars, and reset times, while the lower section shows available reset coupons, their expiration dates, and the next coupon deadline.
32
+ The screenshots show the **`codex-limits`** terminal dashboards: clean, read-only TUIs that summarize Codex usage limits and reset-credit coupons in one place. The top section displays the current 5-hour and weekly usage windows with remaining percentages, visual progress bars, and reset times, while the lower section shows available reset coupons, their expiration dates, and the next coupon deadline.
33
+
34
+ ## Contents
35
+
36
+ - [Quick start](#quick-start)
37
+ - [Requirements](#requirements)
38
+ - [Overview](#overview)
39
+ - [Agent integrations](#agent-integrations)
40
+ - [How it works](#how-it-works)
41
+ - [Environment](#environment)
42
+ - [Usage](#usage)
43
+ - [Troubleshooting](#troubleshooting)
44
+ - [Local development](#local-development)
45
+ - [Security](#security)
46
+ - [License](#license)
47
+ - [Contributors](#contributors)
48
+
49
+ ## Quick start
50
+
51
+ The package is available on npm as [`@simonesiega/codex-limits`](https://www.npmjs.com/package/@simonesiega/codex-limits) and supports Node.js 20 or newer.
52
+
53
+ Install **`codex-limits`** globally from npm:
54
+
55
+ ```bash
56
+ npm install -g @simonesiega/codex-limits@latest
57
+ ```
58
+
59
+ The `@latest` tag ensures you install the latest published version.
60
+
61
+ Then run it from any terminal:
62
+
63
+ ```bash
64
+ codex-limits
65
+ ```
66
+
67
+ The list of available commands is shown when you run `codex-limits --help` or in the [Usage](#usage) section.
68
+
69
+ Install optional agent integrations with their named flag:
70
+
71
+ ```bash
72
+ codex-limits init --<agent-name>
73
+ ```
74
+
75
+ For example, install the OpenCode integration:
76
+
77
+ ```bash
78
+ codex-limits init --opencode
79
+ ```
80
+
81
+ ## Requirements
82
+
83
+ | Requirement | Details |
84
+ | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
85
+ | Node.js | Node.js 20 or newer is required to run the published CLI. Bun is only required for local development. |
86
+ | Codex | For normal use, Codex should already be installed and authenticated so `codex-limits` can discover its local data and credentials. Advanced setups can provide supported environment overrides instead. |
87
+ | Operating systems | Windows, macOS, and Linux are supported through their standard Codex data locations. Use `CODEX_LIMITS_HOME` or `CODEX_HOME` if your data is stored elsewhere. |
88
+ | Internet connection | Local usage fallback can work offline. An internet connection is required for current live usage and reset-credit coupon information; unavailable network data is reported safely without breaking the dashboard. |
32
89
 
33
90
  ## Overview
34
91
 
@@ -42,15 +99,16 @@ It also includes plain-text commands for quick checks, JSON output for scripts a
42
99
 
43
100
  ### Supported agents
44
101
 
45
- | Agent | Status | Agent command | Init Command | Description |
46
- | --- | --- | --- | --- | --- |
102
+ | Agent | Status | Agent command | Init command | Description |
103
+ | -------- | --------- | --------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------- |
47
104
  | OpenCode | Supported | `/codex-limits` | `codex-limits init --opencode` | Opens a fast, read-only Codex limits dashboard directly inside OpenCode without sending the request to the LLM. |
48
105
 
49
- Agent integrations are not enabled during package installation. The package import export is reserved for the agent plugin entry that supported agents load after you run the matching `codex-limits init` command.
106
+ Agent integrations are not enabled automatically during package installation. They must be installed with `codex-limits init` and are only available in the agent terminal after a restart. See [Adding new agents](#adding-new-agents) if you want to add support for another agent.
50
107
 
51
108
  ### Selected agent integration screenshots
52
109
 
53
110
  #### OpenCode
111
+
54
112
  The OpenCode integration adds a `/codex-limits` command that opens a compact modal inside the agent interface. It gives a quick read-only summary of the current 5-hour limit, weekly limit, and reset-credit coupons, then lets you close the view and return immediately to the conversation.
55
113
 
56
114
  <p align="center">
@@ -61,20 +119,20 @@ The OpenCode integration adds a `/codex-limits` command that opens a compact mod
61
119
 
62
120
  New agents can be added by creating a dedicated adapter under `src/agents/<agent-name>` and registering it in `src/agents/index.ts`. Each integration should keep the same goal: show Codex limit information quickly, safely, and without exposing tokens, account IDs, cookies, auth headers, or raw local files.
63
121
 
64
- See the [Contributing](./CONTRIBUTING.md) section if you want to add support for another agent.
122
+ See the [Contributing](./CONTRIBUTING.md) guide if you want to add support for another agent.
65
123
 
66
124
  ## How it works
67
125
 
68
126
  **`codex-limits`** is built around a shared core with different output surfaces on top of it.
69
127
 
70
- | Area | Path | Purpose |
71
- | --- | --- | --- |
72
- | CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and routes to the dashboard, plain-text commands, JSON output, and `init`. |
73
- | Core logic | `src/package/core` | Detects Codex data, reads local usage, fetches optional live information, normalizes usage windows, and keeps sensitive values out of the output. |
74
- | CLI commands | `src/package/commands` | Handles the dashboard, `status`, `coupons`, `--json`, and `init` commands. |
75
- | Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
76
- | Agent integrations | `src/agents` | Contains optional coding-agent adapters that users install with `codex-limits init`. |
77
- | Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
128
+ | Area | Path | Purpose |
129
+ | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
130
+ | CLI entry | `src/package/cli.ts` | Starts the `codex-limits` command and routes to the dashboard, plain-text commands, JSON output, and `init`. |
131
+ | Core logic | `src/package/core` | Detects Codex data, reads local usage, fetches optional live information, normalizes usage windows, and keeps sensitive values out of the output. |
132
+ | CLI commands | `src/package/commands` | Handles the dashboard, `status`, `coupons`, `--json`, and `init` commands. |
133
+ | Terminal UI | `src/package/tui` | Renders the clean Ink-based dashboard from normalized usage data. |
134
+ | Agent integrations | `src/agents` | Contains optional coding-agent adapters that users install with `codex-limits init`. |
135
+ | Tests | `tests` | Contains the test suite used to validate core behavior, CLI output, safety rules, and integration logic. |
78
136
 
79
137
  This structure keeps the project easy to extend: the core decides what the data means, while the CLI, TUI, and agents only decide how that information is shown.
80
138
 
@@ -84,64 +142,93 @@ This structure keeps the project easy to extend: the core decides what the data
84
142
 
85
143
  Environment variables are only used as a fallback when automatic discovery is not enough, or when you want to override the default behavior.
86
144
 
87
- | Variable | Purpose |
88
- | --- | --- |
89
- | `CODEX_LIMITS_HOME` | Manually sets the local Codex data directory when it cannot be detected automatically. |
90
- | `CODEX_LIMITS_ACCESS_TOKEN` | Manually provides an access token for live reset-credit coupon data. |
91
- | `CODEX_LIMITS_ACCOUNT_ID` | Manually provides the account ID used for live reset-credit coupon data. |
92
- | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint, mainly for testing or advanced setups. |
145
+ | Variable | Purpose |
146
+ | ----------------------------- | ---------------------------------------------------------------------------------------- |
147
+ | `CODEX_LIMITS_HOME` | Overrides the local Codex data directory before all other candidates. |
148
+ | `CODEX_HOME` | Uses Codex's native home override when `CODEX_LIMITS_HOME` is not set. |
149
+ | `CODEX_LIMITS_ACCESS_TOKEN` | Provides an access token for authenticated live usage and reset-credit requests. |
150
+ | `CODEX_LIMITS_ACCOUNT_ID` | Provides the account ID paired with `CODEX_LIMITS_ACCESS_TOKEN`. |
151
+ | `CODEX_LIMITS_USAGE_ENDPOINT` | Overrides the live usage endpoint with HTTPS or loopback HTTP for advanced setups/tests. |
152
+ | `CODEX_LIMITS_SKIP_INIT` | Suppresses optional global-install setup guidance from the non-interactive postinstall. |
93
153
 
94
- ## Installation
154
+ ### Data access and safety
95
155
 
96
- Install **`codex-limits`** globally from npm:
156
+ Local Codex data is inspected read-only with bounded file, directory, JSONL, and response limits. Credentials, raw files, and private paths are excluded from public output. Live requests require HTTPS, except for loopback HTTP during local testing. See [`SECURITY.md`](./SECURITY.md#local-data-and-network-behavior) for the complete data-access and network-safety model.
97
157
 
98
- ```bash
99
- npm install -g @simonesiega/codex-limits
100
- ```
158
+ ## Usage
101
159
 
102
- Then run it from any terminal:
160
+ | Command | Description |
161
+ | ----------------------------- | -------------------------------------------------------------- |
162
+ | `codex-limits` | Opens the interactive terminal dashboard. |
163
+ | `codex-limits status` | Prints a plain usage summary. |
164
+ | `codex-limits coupons` | Prints reset-credit coupon information. |
165
+ | `codex-limits coupons --json` | Prints machine-readable reset-credit coupon data only. |
166
+ | `codex-limits --json` | Prints machine-readable usage and coupon data. |
167
+ | `codex-limits init` | Prompts for optional agent integrations in an interactive TTY. |
103
168
 
104
- ```bash
105
- codex-limits
106
- ```
169
+ ### `init` options
107
170
 
108
- ## Usage
171
+ Use `codex-limits init` to install optional agent integrations. Installation only updates the selected agent configuration; it does not send a prompt to an LLM or modify Codex data.
172
+
173
+ | Command | What it does |
174
+ | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
175
+ | `codex-limits init` | Prompts for every supported integration when stdin and stdout are interactive terminals. If no integration is selected, nothing is installed. |
176
+ | `codex-limits init --help` or `codex-limits init -h` | Prints the `init` command help without changing any configuration. |
177
+ | `codex-limits init --all` | Installs every supported integration without prompting. |
178
+ | `codex-limits init --opencode` | Installs only the OpenCode integration, which adds `/codex-limits` to OpenCode. |
179
+ | `codex-limits init --<agent-name>` | Installs only the named supported integration. Replace `<agent-name>` with an integration listed in [Supported agents](#supported-agents). |
180
+
181
+ `--all` cannot be combined with a named integration flag. Duplicate, unknown, and positional arguments are rejected. In a non-interactive terminal, use `--all` or a named integration flag instead of running `codex-limits init` without options.
182
+
183
+ ## Troubleshooting
184
+
185
+ ### No Codex data found
186
+
187
+ Make sure Codex has been run and authenticated at least once. If its data is stored outside the standard location, set `CODEX_LIMITS_HOME` or `CODEX_HOME` to the Codex data directory, then run `codex-limits status` again.
109
188
 
110
- | Command | Description |
111
- | --- | --- |
112
- | `codex-limits` | Opens the interactive terminal dashboard. |
113
- | `codex-limits status` | Prints a plain usage summary. |
114
- | `codex-limits coupons` | Prints reset-credit coupon information. |
115
- | `codex-limits --json` | Prints machine-readable usage data for scripts and automation. |
116
- | `codex-limits init` | Installs optional agent integrations. |
117
- | `codex-limits init --opencode` | Installs the OpenCode integration directly. |
118
- | `codex-limits --help` | Prints the help text. |
119
- | `codex-limits --version` | Prints the installed package version. |
189
+ ### Usage information unavailable
190
+
191
+ Run `codex-limits status` to view the safe warning summary. Confirm that Codex authentication is current and that the machine can reach the ChatGPT Codex service. Local session data may still provide a fallback when live usage is unavailable; coupon information requires an internet connection.
192
+
193
+ ### Permission errors
194
+
195
+ Confirm that your user can read the selected Codex directory and its session files. Do not run the CLI with elevated privileges unless your Codex installation explicitly requires it. Prefer correcting the directory permissions or selecting the correct directory with `CODEX_LIMITS_HOME`.
196
+
197
+ ### Agent command not appearing after initialization
198
+
199
+ Run the named initializer again, for example `codex-limits init --opencode`, and confirm that it reports the integration as installed or already installed. Restart the target agent terminal so it reloads its configuration. If the command is still missing, verify that the displayed configuration paths belong to the agent installation you are using.
120
200
 
121
201
  ## Local development
122
202
 
123
203
  Clone the repository, install dependencies, and run the CLI locally:
124
204
 
125
205
  ```bash
206
+ git clone https://github.com/simonesiega/codex-limits.git
207
+ cd codex-limits
126
208
  bun install
127
209
  bun run dev
128
210
  ```
129
211
 
130
212
  Useful development commands:
131
213
 
132
- | Command | Description |
133
- | --- | --- |
134
- | `bun run dev` | Runs the CLI in development mode. |
135
- | `bun run check` | Runs type checking, tests, and build validation. |
136
- | `bun test` | Runs the test suite. |
137
- | `bun run build` | Builds the package. |
214
+ | Command | Description |
215
+ | ---------------------- | ---------------------------------------------------------------- |
216
+ | `bun run dev` | Runs the CLI in development mode. |
217
+ | `bun run check` | Runs formatting, types, tests, builds, and package smoke checks. |
218
+ | `bun test` | Runs the test suite. |
219
+ | `bun run build` | Builds the package. |
220
+ | `bun run format` | Formats the repository with Prettier. |
221
+ | `bun run format:check` | Checks formatting without changing files. |
222
+
223
+ ## Security
138
224
 
225
+ For vulnerability reports and local data safety details, see [`SECURITY.md`](./SECURITY.md).
139
226
 
140
227
  ## License
141
228
 
142
229
  This project is licensed under the MIT License. See [`LICENSE`](LICENSE).
143
230
 
144
- ## Contributors 🧑‍💻
231
+ ## Contributors
145
232
 
146
233
  <p align="center">
147
234
  <a href="https://github.com/simonesiega/codex-limits/graphs/contributors">
package/SECURITY.md ADDED
@@ -0,0 +1,96 @@
1
+ <h1 align="center">
2
+ Security Policy
3
+ </h1>
4
+
5
+ <p align="center">
6
+ Responsible disclosure guidelines for <strong>codex-limits</strong>.
7
+ </p>
8
+
9
+ <p align="center">
10
+ <img src="https://img.shields.io/badge/Security-private%20reporting-red" alt="Private security reporting" />
11
+ <img src="https://img.shields.io/badge/Data%20access-read--only-blue" alt="Read-only data access" />
12
+ <img src="https://img.shields.io/badge/Supported-latest%20release%20%7C%20main-brightgreen" alt="Supported versions: latest release and main" />
13
+ <img src="https://img.shields.io/github/license/simonesiega/codex-limits" alt="License" />
14
+ </p>
15
+
16
+ ## Supported versions
17
+
18
+ Security fixes are handled for the latest published version of `@simonesiega/codex-limits` and for the current `main` branch.
19
+
20
+ | Version | Support |
21
+ | ------------------ | ------------------------------ |
22
+ | Latest npm release | Supported |
23
+ | `main` branch | Supported for unreleased fixes |
24
+ | Older releases | Best effort only |
25
+
26
+ ## Reporting a vulnerability
27
+
28
+ If you discover a vulnerability, a way to expose private Codex data, or a behavior that could leak sensitive information, do not open a public issue.
29
+
30
+ Report it privately using one of the following methods:
31
+
32
+ | Contact | Value |
33
+ | ----------------------------------- | ------------------------------------------------------------------------------------------ |
34
+ | GitHub private vulnerability report | [Submit a private report](https://github.com/simonesiega/codex-limits/security/advisories) |
35
+ | Email | [simonesiega1@gmail.com](mailto:simonesiega1@gmail.com) |
36
+
37
+ Do not include real access tokens, credentials, or unredacted private Codex files in the report. Use redacted examples whenever possible.
38
+
39
+ Please include:
40
+
41
+ | Field | Why it matters |
42
+ | -------------------- | ------------------------------------------------------------------------- |
43
+ | Short description | Explains what the issue is. |
44
+ | Impact | Explains what data, command, output, or integration is affected. |
45
+ | Reproduction steps | Makes the issue easier to verify and fix. |
46
+ | Environment | Helps isolate OS, Bun, Node, Codex, terminal, or agent-specific behavior. |
47
+ | Suggested mitigation | Optional, but useful if you already found a safe fix. |
48
+
49
+ ## What to expect
50
+
51
+ After receiving a report, the maintainer will:
52
+
53
+ 1. Confirm receipt of the report.
54
+ 2. Investigate and reproduce the issue.
55
+ 3. Share relevant progress when possible.
56
+ 4. Coordinate a fix and disclosure before publishing details.
57
+
58
+ Please do not publicly disclose the vulnerability until a fix is available or disclosure has been coordinated. No specific response time is promised, but reports will be handled as promptly as reasonably possible.
59
+
60
+ ## Local data and network behavior
61
+
62
+ `codex-limits` is designed to keep Codex data on your machine.
63
+
64
+ The CLI performs bounded, read-only inspection of recognized Codex home candidates. It reads small non-sensitive JSON state files, bounded `sessions/**/rollout-*.jsonl` logs, and `auth.json` only for credential resolution. Traversal depth, directory entries, file counts, file sizes, JSONL line sizes, and response sizes are limited; nested symbolic links are skipped. Raw local files and credentials are never returned by the public CLI or JSON contracts.
65
+
66
+ For live usage and coupon information, the project contacts the default ChatGPT Codex endpoints. The only endpoint override is `CODEX_LIMITS_USAGE_ENDPOINT`, mainly for testing or advanced setups. Overrides must use HTTPS, except for loopback HTTP during local testing. Authenticated requests reject redirects, use bounded timeouts and responses, and never include credential headers in diagnostics.
67
+
68
+ Agent integrations follow the same safety model: they should display a read-only summary by reusing the shared core, not send private Codex data to the agent, and not expose sensitive values inside the agent UI.
69
+
70
+ ## What to report
71
+
72
+ Please report any issue that could expose private data or break the read-only safety model of the project.
73
+
74
+ Relevant examples include:
75
+
76
+ - access tokens printed in terminal output, JSON output, logs, tests, or screenshots;
77
+ - account IDs exposed without redaction;
78
+ - auth headers, cookies, or private environment values reaching user-visible output;
79
+ - raw local Codex files being printed, logged, snapshotted, or committed;
80
+ - agent integrations exposing private Codex data inside the agent UI;
81
+ - unexpected writes to local Codex data;
82
+ - unexpected network behavior related to usage or coupon discovery;
83
+ - unsafe handling of `CODEX_LIMITS_HOME`, `CODEX_LIMITS_ACCESS_TOKEN`, `CODEX_LIMITS_ACCOUNT_ID`, or `CODEX_LIMITS_USAGE_ENDPOINT`.
84
+
85
+ ## Safety expectations
86
+
87
+ `codex-limits` is intended to be safe by default.
88
+
89
+ The project should:
90
+
91
+ - remain read-only for local Codex data;
92
+ - keep sensitive values out of CLI output, TUI output, JSON output, tests, logs, and screenshots;
93
+ - centralize data discovery, parsing, normalization, warnings, and redaction in the shared core;
94
+ - keep agent integrations thin and reuse the shared core instead of reimplementing security-sensitive parsing;
95
+ - use placeholders or redacted values in documentation, examples, and test fixtures;
96
+ - convert network, payload, authentication, and filesystem failures into deterministic safe warnings rather than raw exception messages.