Enterprise hardening baseline: security, reliability, CI gates, and runbooks

.github/settings.yml

@@ -0,0 +1,23 @@
+branches:
+  - name: main
+    protection:
+      required_pull_request_reviews:
+        required_approving_review_count: 1
+        require_code_owner_reviews: false
+        dismiss_stale_reviews: true
+      required_status_checks:
+        strict: true
+        checks:
+          - context: "CI / Test on Node.js 20.x"
+          - context: "CI / Test on Node.js 22.x"
+          - context: "CI / Coverage Gate"
+          - context: "CI / Lint"
+          - context: "CI / Codex Compatibility Smoke"
+          - context: "CI / Cross-Platform Smoke (windows-latest)"
+          - context: "CI / Cross-Platform Smoke (macos-latest)"
+          - context: "CodeQL / Analyze"
+          - context: "Secret Scan / Gitleaks"
+          - context: "Supply Chain / Dependency Review"
+          - context: "Supply Chain / SCA and License Gate"
+      enforce_admins: true
+      restrictions: null

.github/workflows/ci.yml

@@ -6,12 +6,17 @@ on:
   pull_request:
     branches: [main]
 
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   test:
     name: Test on Node.js ${{ matrix.node-version }}
     runs-on: ubuntu-latest
 
     strategy:
+      fail-fast: false
       matrix:
         node-version: [20.x, 22.x]
 
@@ -23,7 +28,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
-          cache: 'npm'
+          cache: npm
 
       - name: Install dependencies
         run: npm ci
@@ -44,15 +49,34 @@ jobs:
       - name: Run type check
         run: npm run typecheck
 
-      - name: Run tests with coverage
-        run: npm run coverage
-
       - name: Build
         run: npm run build
 
+      - name: Run tests
+        run: npm test
+
+  coverage-gate:
+    name: Coverage Gate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage threshold gate
+        run: npm run coverage
+
   lint:
     name: Lint
-
     runs-on: ubuntu-latest
 
     steps:
@@ -63,7 +87,7 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
-          cache: 'npm'
+          cache: npm
 
       - name: Install dependencies
         run: npm ci
@@ -83,10 +107,41 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 20.x
-          cache: 'npm'
+          cache: npm
 
       - name: Install dependencies
         run: npm ci
 
       - name: Run Codex compatibility tests
         run: npm run test -- test/codex.test.ts test/host-codex-prompt.test.ts test/request-transformer.test.ts test/fetch-helpers.test.ts
+
+  cross-platform-smoke:
+    name: Cross-Platform Smoke (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [windows-latest, macos-latest]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run smoke typecheck
+        run: npm run typecheck
+
+      - name: Build
+        run: npm run build
+
+      - name: Run smoke tests
+        run: npm run test -- test/runtime-paths.test.ts test/codex-bin-wrapper.test.ts

.github/workflows/secret-scan.yml

@@ -0,0 +1,28 @@
+name: Secret Scan
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 5 * * 1"
+
+jobs:
+  gitleaks:
+    name: Gitleaks
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run gitleaks scanner
+        uses: gitleaks/gitleaks-action@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/supply-chain.yml

@@ -0,0 +1,78 @@
+name: Supply Chain
+
+on:
+  pull_request:
+    branches: [main]
+  push:
+    branches: [main]
+  schedule:
+    - cron: "0 4 * * 1"
+
+jobs:
+  dependency-review:
+    name: Dependency Review
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: read
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Dependency review
+        uses: actions/dependency-review-action@v4
+        with:
+          fail-on-severity: high
+          fail-on-scopes: runtime
+          deny-licenses: GPL-2.0, GPL-3.0, AGPL-3.0
+
+  sca-and-license:
+    name: SCA and License Gate
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run vulnerability policy gate
+        run: npm run audit:ci
+
+      - name: Run license policy gate
+        run: npm run license:check
+
+  sbom:
+    name: Generate SBOM
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Generate CycloneDX SBOM
+        run: npx --yes @cyclonedx/cyclonedx-npm --output-file sbom.cdx.json --omit dev
+
+      - name: Upload SBOM artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: sbom-cyclonedx
+          path: sbom.cdx.json

README.md

@@ -128,6 +128,7 @@ codex auth doctor --fix
 | `codex auth fix --dry-run` | Preview safe repairs |
 | `codex auth fix --live --model gpt-5-codex` | Run repairs with live probe model |
 | `codex auth doctor --fix` | Diagnose and apply safe fixes |
+| `codex auth rotate-secrets --json` | Re-encrypt stored secrets and return rotation summary |
 
 ---
 

docs/README.md

@@ -59,6 +59,7 @@ Canonical documentation map for `codex-multi-auth`.
 | [development/REPOSITORY_SCOPE.md](development/REPOSITORY_SCOPE.md) | Ownership map by repository path |
 | [development/TESTING.md](development/TESTING.md) | Validation gates and test matrix |
 | [development/TUI_PARITY_CHECKLIST.md](development/TUI_PARITY_CHECKLIST.md) | Dashboard UX parity checklist |
+| [runbooks/README.md](runbooks/README.md) | Operations and incident response playbooks |
 | [benchmarks/code-edit-format-benchmark.md](benchmarks/code-edit-format-benchmark.md) | Benchmark methodology and outputs |
 
 ---

docs/configuration.md

@@ -68,6 +68,12 @@ These are safe for most operators and frequently used in day-to-day workflows.
 | `CODEX_TUI_GLYPHS=ascii|unicode|auto` | Glyph mode selection |
 | `CODEX_AUTH_FETCH_TIMEOUT_MS=<ms>` | HTTP request timeout override |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS=<ms>` | Stream stall timeout override |
+| `CODEX_AUTH_ENCRYPTION_KEY=<32-byte-random-key>` | Enable at-rest encryption for stored account secrets (high-entropy key material only) |
+| `CODEX_AUTH_PREVIOUS_ENCRYPTION_KEY=<32-byte-random-key>` | Previous high-entropy key used during staged secret rotation |
+| `CODEX_AUTH_ROLE=admin|operator|viewer` | CLI authorization role baseline |
+
+For `CODEX_AUTH_ENCRYPTION_KEY` and `CODEX_AUTH_PREVIOUS_ENCRYPTION_KEY`, use 32-byte
+random key material from a secret manager. Do not use user-memorable passwords.
 
 ---
 
@@ -81,6 +87,14 @@ Use these only when debugging, controlled benchmarking, or maintainer workflows.
 - `CODEX_CLI_ACCOUNTS_PATH`
 - `CODEX_CLI_AUTH_PATH`
 - refresh lease tuning variables (`CODEX_AUTH_REFRESH_LEASE*`)
+- `CODEX_AUTH_BREAK_GLASS`
+- `CODEX_AUTH_ABAC_READ_ONLY`
+- `CODEX_AUTH_ABAC_DENY_ACTIONS`
+- `CODEX_AUTH_ABAC_DENY_COMMANDS`
+- `CODEX_AUTH_ABAC_REQUIRE_INTERACTIVE`
+- `CODEX_AUTH_ABAC_REQUIRE_IDEMPOTENCY_KEY`
+- `CODEX_AUTH_REDACT_JSON_OUTPUT`
+- retention tuning variables (`CODEX_AUTH_RETENTION_*`)
 
 Full inventory: [development/CONFIG_FIELDS.md](development/CONFIG_FIELDS.md)
 

docs/development/CONFIG_FIELDS.md

@@ -195,6 +195,21 @@ Used only for host plugin mode through the host runtime config file.
 | `CODEX_TUI_GLYPHS` | TUI glyph mode |
 | `CODEX_AUTH_FETCH_TIMEOUT_MS` | Request timeout override |
 | `CODEX_AUTH_STREAM_STALL_TIMEOUT_MS` | Stream stall timeout override |
+| `CODEX_AUTH_ENCRYPTION_KEY` | Primary high-entropy 32-byte key for at-rest secret encryption |
+| `CODEX_AUTH_PREVIOUS_ENCRYPTION_KEY` | Previous high-entropy 32-byte key for staged secret rotation |
+| `CODEX_AUTH_ROLE` | Authorization role baseline (`admin`, `operator`, `viewer`) |
+| `CODEX_AUTH_BREAK_GLASS` | Emergency authorization bypass toggle |
+| `CODEX_AUTH_ABAC_READ_ONLY` | Deny mutating actions while allowing read-only command paths |
+| `CODEX_AUTH_ABAC_DENY_ACTIONS` | Comma-separated action denies (`accounts:write`, etc.) |
+| `CODEX_AUTH_ABAC_DENY_COMMANDS` | Comma-separated command denies (`rotate-secrets`, etc.) |
+| `CODEX_AUTH_ABAC_REQUIRE_INTERACTIVE` | Comma-separated actions that require interactive terminal |
+| `CODEX_AUTH_ABAC_REQUIRE_IDEMPOTENCY_KEY` | Comma-separated actions that require idempotency key context |
+| `CODEX_AUTH_REDACT_JSON_OUTPUT` | Redact sensitive values in JSON command output |
+| `CODEX_AUTH_RETENTION_LOG_DAYS` | Log retention window |
+| `CODEX_AUTH_RETENTION_CACHE_DAYS` | Cache retention window |
+| `CODEX_AUTH_RETENTION_FLAGGED_DAYS` | Flagged-account file retention window |
+| `CODEX_AUTH_RETENTION_QUOTA_CACHE_DAYS` | Quota cache retention window |
+| `CODEX_AUTH_RETENTION_DLQ_DAYS` | Dead-letter queue retention window |
 | `CODEX_MULTI_AUTH_SYNC_CODEX_CLI` | Toggle Codex CLI state sync |
 | `CODEX_MULTI_AUTH_REAL_CODEX_BIN` | Force official Codex binary path |
 | `CODEX_MULTI_AUTH_BYPASS` | Bypass local auth handling |

docs/development/TESTING.md

@@ -24,6 +24,8 @@ npm run typecheck
 npm run lint
 npm test
 npm run build
+npm run audit:ci
+npm run license:check
 ```
 
 Optional:
@@ -42,8 +44,11 @@ npm run bench:edit-formats:smoke
 1. `npm run typecheck`
 2. `npm run lint`
 3. `npm test`
-4. `npm run build`
-5. run docs command checks for newly documented command paths
+4. `npm run coverage`
+5. `npm run build`
+6. `npm run audit:ci`
+7. `npm run license:check`
+8. run docs command checks for newly documented command paths
 
 * * *
 

docs/index.md

@@ -46,4 +46,5 @@ Legacy package/path guidance is documented in [upgrade.md](upgrade.md) and [refe
 - Command flags and hotkeys: [reference/commands.md](reference/commands.md)
 - Settings and overrides: [reference/settings.md](reference/settings.md)
 - Storage path matrix: [reference/storage-paths.md](reference/storage-paths.md)
-- Full docs portal: [README.md](README.md)
+- Operations runbooks: [runbooks/README.md](runbooks/README.md)
+- Full docs portal: [README.md](README.md)

docs/privacy.md

@@ -20,6 +20,7 @@
 | Accounts | `~/.codex/multi-auth/openai-codex-accounts.json` | Primary saved account pool |
 | Flagged accounts | `~/.codex/multi-auth/openai-codex-flagged-accounts.json` | Accounts with hard auth failures |
 | Quota cache | `~/.codex/multi-auth/quota-cache.json` | Cached quota snapshots |
+| Background DLQ | `~/.codex/multi-auth/background-job-dlq.jsonl` | Failed background jobs after retry exhaustion |
 | Logs | `~/.codex/multi-auth/logs/codex-plugin/` | Optional diagnostics |
 | Prompt/cache files | `~/.codex/multi-auth/cache/` | Cached prompt/template metadata |
 | Codex CLI state | `~/.codex/accounts.json`, `~/.codex/auth.json` | Official Codex CLI files |
@@ -48,6 +49,35 @@ Current external destinations:
 
 Raw body logs may contain sensitive payload text. Treat logs as sensitive data and rotate/delete as needed.
 
+`CODEX_AUTH_REDACT_JSON_OUTPUT=1` redacts sensitive values from JSON command output for automation logs.
+
+---
+
+## Secret Encryption and Rotation
+
+- Account refresh/access tokens can be encrypted at rest when `CODEX_AUTH_ENCRYPTION_KEY` is set.
+- Key rotation supports staged migration with `CODEX_AUTH_PREVIOUS_ENCRYPTION_KEY`.
+- Both key variables should be 32-byte high-entropy key material (not passwords).
+- Rotation command:
+
+```bash
+codex auth rotate-secrets --json
+```
+
+Store encryption keys in a secret manager or CI secret store, not in repository files.
+
+---
+
+## Retention
+
+Startup retention cleanup removes expired local artifacts based on:
+
+- `CODEX_AUTH_RETENTION_LOG_DAYS`
+- `CODEX_AUTH_RETENTION_CACHE_DAYS`
+- `CODEX_AUTH_RETENTION_FLAGGED_DAYS`
+- `CODEX_AUTH_RETENTION_QUOTA_CACHE_DAYS`
+- `CODEX_AUTH_RETENTION_DLQ_DAYS`
+
 ---
 
 ## Data Cleanup