build(deps): bump actions/checkout from 4 to 6

.env.example

@@ -454,34 +454,30 @@ CLAUDE_OAUTH_CLIENT_ID=9d1c250a-e61b-44d9-88ed-5944d1962f5e
 # ── Codex / OpenAI ──
 CODEX_OAUTH_CLIENT_ID=app_EMoamEEZ73f0CkXaXp7hrann
 
-# ── Gemini (Google) ──
-GEMINI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
-GEMINI_OAUTH_CLIENT_SECRET=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
-
-# ── Gemini CLI (Google) ──
-GEMINI_CLI_OAUTH_CLIENT_ID=681255809395-oo8ft2oprdrnp9e3aqf6av3hmdib135j.apps.googleusercontent.com
-GEMINI_CLI_OAUTH_CLIENT_SECRET=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
+# ── Gemini / Gemini CLI / Antigravity / Windsurf (all Google-based) ──
+# These providers ship public OAuth client_id/secret values (or Firebase Web
+# keys) embedded in their public CLIs/binaries. Defaults are baked into the
+# code via open-sse/utils/publicCreds.ts — leave the env vars unset to use
+# them. Only set these if you registered your own OAuth app and want to use
+# your own credentials instead. See docs/security/PUBLIC_CREDS.md for context.
+#
+# GEMINI_OAUTH_CLIENT_ID=
+# GEMINI_OAUTH_CLIENT_SECRET=
+# GEMINI_CLI_OAUTH_CLIENT_ID=
+# GEMINI_CLI_OAUTH_CLIENT_SECRET=
+# ANTIGRAVITY_OAUTH_CLIENT_ID=
+# ANTIGRAVITY_OAUTH_CLIENT_SECRET=
+# WINDSURF_FIREBASE_API_KEY=
 
 # ── Qwen (Alibaba) ──
 QWEN_OAUTH_CLIENT_ID=f0304373b74a44d2b584a3fb70ca9e56
 
 # ── Kimi Coding (Moonshot) ──
 KIMI_CODING_OAUTH_CLIENT_ID=17e5f671-d194-4dfb-9706-5516cb48c098
 
-# ── Antigravity (Google Cloud Code) ──
-ANTIGRAVITY_OAUTH_CLIENT_ID=1071006060591-tmhssin2h21lcre235vtolojh4g403ep.apps.googleusercontent.com
-ANTIGRAVITY_OAUTH_CLIENT_SECRET=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
-
 # ── GitHub Copilot ──
 GITHUB_OAUTH_CLIENT_ID=Iv1.b507a08c87ecfe98
 
-# ── Windsurf / Devin CLI ──
-# Public Firebase Web API key used by Windsurf's Secure Token Service to refresh
-# short-lived browser-flow tokens. This is a client-side credential embedded in
-# the Windsurf app itself (not a secret). Long-lived import tokens skip this entirely.
-# Source: extracted from Devin CLI binary (devin.exe / model_configs_v2.bin).
-WINDSURF_FIREBASE_API_KEY=AIzaSyBpLTEGSt59AUPKxBb7lIWjSE2ZXQH7mgU
-
 # ── GitLab Duo ──
 # Register an OAuth app at: https://gitlab.com/-/profile/applications
 # Set redirect URI to: http://localhost:20128/callback (or your NEXT_PUBLIC_BASE_URL + /callback)
@@ -498,7 +494,11 @@ WINDSURF_FIREBASE_API_KEY=AIzaSyBpLTEGSt59AUPKxBb7lIWjSE2ZXQH7mgU
 #GITLAB_OAUTH_CLIENT_SECRET=
 
 # ── Qoder ──
-QODER_OAUTH_CLIENT_SECRET=4Z3YjXycVsQvyGF1etiNlIBB4RsqSDtW
+# Public OAuth client secret embedded in the Qoder CLI binary. Required only
+# when QODER_OAUTH_AUTHORIZE_URL / TOKEN_URL / USERINFO_URL / CLIENT_ID are
+# also set (see QODER_CONFIG.enabled in src/lib/oauth/constants/oauth.ts).
+# Extract the value from the public Qoder CLI binary if you intend to use it.
+# QODER_OAUTH_CLIENT_SECRET=
 
 # ── Qoder Browser OAuth (experimental) ──
 # OmniRoute only enables the browser OAuth flow when ALL 5 variables below are set:

.github/workflows/claude-code-review.yml

@@ -27,7 +27,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 

.github/workflows/claude.yml

@@ -26,7 +26,7 @@ jobs:
       actions: read # Required for Claude to read CI results on PRs
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 1
 

AGENTS.md

@@ -120,6 +120,10 @@ Always run `prettier --write` on changed files.
 - Auth middleware required on all API routes
 - Never log SQLite encryption keys
 - Sanitize user content (dompurify for HTML)
+- **Public upstream OAuth identifiers** (Gemini / Antigravity / Windsurf-style client_id/secret + Firebase Web keys extracted from public CLIs): use `resolvePublicCred()` from `open-sse/utils/publicCreds.ts`, **never** as string literals. Full pattern in `docs/security/PUBLIC_CREDS.md`.
+- **Error responses** (HTTP / SSE / executor / MCP): use `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts`, **never** put raw `err.stack` / `err.message` in a Response body. Full pattern in `docs/security/ERROR_SANITIZATION.md`.
+- **`exec()` / `spawn()` with runtime values**: pass via the `env` option, **never** string-interpolate paths/values into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
+- Prefer secure-by-default libraries when available — see [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) for the curated list (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink, etc.).
 
 ---
 

CLAUDE.md

@@ -244,6 +244,10 @@ connection continue serving other models.
 - Validate all inputs with Zod schemas
 - Encrypt credentials at rest (AES-256-GCM)
 - Upstream header denylist: `src/shared/constants/upstreamHeaders.ts` — keep sanitize, Zod schemas, and unit tests aligned when editing
+- **Public upstream credentials** (Gemini/Antigravity/Windsurf-style OAuth client_id/secret + Firebase Web keys extracted from public CLIs): **MUST** be embedded via `resolvePublicCred()` from `open-sse/utils/publicCreds.ts` — **never** as string literals. See `docs/security/PUBLIC_CREDS.md` for the mandatory pattern.
+- **Error responses** (HTTP / SSE / executor / MCP handler): **MUST** route through `buildErrorBody()` or `sanitizeErrorMessage()` from `open-sse/utils/error.ts` — **never** put raw `err.stack` or `err.message` in a response body. See `docs/security/ERROR_SANITIZATION.md`.
+- **Shell commands built from variables**: when calling `exec()`/`spawn()` with a script that needs runtime values, pass them via the `env` option (shell-escaped automatically) — **never** string-interpolate untrusted/external paths into the script body. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
+- **Secure-by-default libraries** ([tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults)): prefer Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink over custom implementations whenever adding new security-sensitive surfaces.
 
 ---
 
@@ -254,17 +258,18 @@ connection continue serving other models.
 1. Register in `src/shared/constants/providers.ts` (Zod-validated at load)
 2. Add executor in `open-sse/executors/` if custom logic needed (extend `BaseExecutor`)
 3. Add translator in `open-sse/translator/` if non-OpenAI format
-4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based
+4. Add OAuth config in `src/lib/oauth/constants/oauth.ts` if OAuth-based — if the upstream CLI ships a public client_id/secret, embed via `resolvePublicCred()` (see `docs/security/PUBLIC_CREDS.md`), **never** as a literal
 5. Register models in `open-sse/config/providerRegistry.ts`
-6. Write tests in `tests/unit/`
+6. Write tests in `tests/unit/` (include the publicCreds shape assertion if you added a new embedded default)
 
 ### Adding a New API Route
 
 1. Create directory under `src/app/api/v1/your-route/`
 2. Create `route.ts` with `GET`/`POST` handlers
 3. Follow pattern: CORS → Zod body validation → optional auth → handler delegation
 4. Handler goes in `open-sse/handlers/` (import from there, not inline)
-5. Add tests
+5. Error responses use `buildErrorBody()` / `errorResponse()` from `open-sse/utils/error.ts` (auto-sanitized — never put `err.stack` or `err.message` raw in the body). See `docs/security/ERROR_SANITIZATION.md`.
+6. Add tests — including at least one assertion that error responses do not leak stack traces (`!body.error.message.includes("at /")`)
 
 ### Adding a New DB Module
 
@@ -323,6 +328,8 @@ For any non-trivial change, read the matching deep-dive first:
 | Memory system (FTS5 + Qdrant)                | `docs/frameworks/MEMORY.md`                                       |
 | Cloud agents                                 | `docs/frameworks/CLOUD_AGENT.md`                                  |
 | Guardrails (PII / injection / vision)        | `docs/security/GUARDRAILS.md`                                     |
+| Public upstream credentials (Gemini/etc.)    | `docs/security/PUBLIC_CREDS.md`                                   |
+| Error message sanitization                   | `docs/security/ERROR_SANITIZATION.md`                             |
 | Evals                                        | `docs/frameworks/EVALS.md`                                        |
 | Compliance / audit                           | `docs/security/COMPLIANCE.md`                                     |
 | Webhooks                                     | `docs/frameworks/WEBHOOKS.md`                                     |
@@ -402,3 +409,7 @@ git push -u origin feat/your-feature
 8. Always include tests when changing production code
 9. Coverage must stay ≥75% (statements, lines, functions) / ≥70% (branches). Current measured: ~82%.
 10. Never bypass Husky hooks (`--no-verify`, `--no-gpg-sign`) without explicit operator approval.
+11. Never embed public upstream OAuth client_id/secret or Firebase Web keys as string literals — always go through `resolvePublicCred()` (`open-sse/utils/publicCreds.ts`). See `docs/security/PUBLIC_CREDS.md`.
+12. Never return raw `err.stack` / `err.message` in HTTP / SSE / executor responses — always route through `buildErrorBody()` or `sanitizeErrorMessage()` (`open-sse/utils/error.ts`). See `docs/security/ERROR_SANITIZATION.md`.
+13. Never string-interpolate external paths or runtime values into shell scripts passed to `exec()`/`spawn()` — pass via the `env` option instead. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
+14. Never dismiss a CodeQL / Secret-Scanning alert without (a) first checking the pattern docs above to see if the helper applies, and (b) recording the technical justification in the dismissal comment. Precedent: `js/stack-trace-exposure` raised on callsites that already route through `sanitizeErrorMessage()` is a known CodeQL limitation (custom sanitizers not recognized) — dismiss as `false positive` referencing `docs/security/ERROR_SANITIZATION.md`.

CONTRIBUTING.md

@@ -266,6 +266,10 @@ Create request/response translators in `open-sse/translator/`.
 
 Add OAuth credentials in `src/lib/oauth/constants/oauth.ts` and service in `src/lib/oauth/services/`.
 
+If the upstream provider distributes a public OAuth client_id/secret or Firebase Web API key inside its public CLI / browser bundle, **do not** embed it as a string literal. Use `resolvePublicCred()` from `open-sse/utils/publicCreds.ts` and add a masked byte entry to `EMBEDDED_DEFAULTS`. The full mandatory workflow is documented in [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md).
+
+Inside handlers/executors, error messages reaching the client must go through `buildErrorBody()` / `sanitizeErrorMessage()` from `open-sse/utils/error.ts` — never put raw `err.stack` or `err.message` in a Response body. See [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md).
+
 ### Step 5: Register Models
 
 Add model definitions in `open-sse/config/providerRegistry.ts`.
@@ -287,9 +291,13 @@ Write unit tests in `tests/unit/` covering at minimum:
 - [ ] Build succeeds (`npm run build`)
 - [ ] TypeScript types added for new public functions and interfaces
 - [ ] No hardcoded secrets or fallback values
+- [ ] Public upstream credentials embedded via `resolvePublicCred()` (see [`docs/security/PUBLIC_CREDS.md`](./docs/security/PUBLIC_CREDS.md)), never as literals
+- [ ] Error responses route through `buildErrorBody()` / `sanitizeErrorMessage()` — no raw stack traces in response bodies (see [`docs/security/ERROR_SANITIZATION.md`](./docs/security/ERROR_SANITIZATION.md))
+- [ ] Shell commands (`exec` / `spawn`) pass runtime values via `env`, not via string interpolation
 - [ ] All inputs validated with Zod schemas
 - [ ] CHANGELOG updated (if user-facing change)
 - [ ] Documentation updated (if applicable)
+- [ ] No new CodeQL / Secret-Scanning alerts opened, or each one dismissed with technical justification referencing the relevant `docs/security/` doc
 
 ---
 

SECURITY.md

@@ -194,19 +194,26 @@ docker run -d \
 
 These rules are enforced by tooling and reviewers:
 
-1. **Never commit secrets** — `.env` is gitignored; `.env.example` is the template
+1. **Never commit secrets** — `.env` is gitignored; `.env.example` is the template (no literals, comments only — see PUBLIC_CREDS.md below)
 2. **Never use `eval()`, `new Function()`, or implied eval** — ESLint enforces
 3. **Never bypass Husky hooks** (`--no-verify`, `--no-gpg-sign`) without explicit operator approval
 4. **Never write raw SQL in routes** — always go through `src/lib/db/` (parameterized)
 5. **Always validate inputs with Zod** — `src/shared/validation/schemas.ts`
 6. **Always sanitize upstream headers** — denylist in `src/shared/constants/upstreamHeaders.ts`
 7. **Encrypt credentials at rest** — AES-256-GCM via `src/lib/db/encryption.ts`
+8. **Public upstream OAuth identifiers via `resolvePublicCred()`** — never embed `AIza…` / `GOCSPX-…` / `…apps.googleusercontent.com` literals in source. See [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md).
+9. **Error responses through `buildErrorBody()` / `sanitizeErrorMessage()`** — never put raw `err.stack` / `err.message` in HTTP / SSE / executor / MCP response bodies. See [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md).
+10. **`exec()` / `spawn()` runtime values via the `env` option** — never string-interpolate external paths or untrusted values into shell-passed scripts. Reference: `src/mitm/cert/install.ts::updateNssDatabases`.
+11. **Prefer secure-by-default libraries** — see [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) (Helmet.js, DOMPurify, ssrf-req-filter, safe-regex, Google Tink). Reach for them before rolling your own.
 
 ## References
 
 - [`docs/architecture/AUTHZ_GUIDE.md`](docs/architecture/AUTHZ_GUIDE.md) — authorization pipeline
 - [`docs/security/GUARDRAILS.md`](docs/security/GUARDRAILS.md) — guardrails framework
 - [`docs/security/COMPLIANCE.md`](docs/security/COMPLIANCE.md) — audit log and retention
+- [`docs/security/PUBLIC_CREDS.md`](docs/security/PUBLIC_CREDS.md) — **mandatory** pattern for public upstream credentials
+- [`docs/security/ERROR_SANITIZATION.md`](docs/security/ERROR_SANITIZATION.md) — **mandatory** pattern for error responses
 - [`docs/architecture/RESILIENCE_GUIDE.md`](docs/architecture/RESILIENCE_GUIDE.md) — circuit breaker + cooldown + lockout
 - [`docs/security/STEALTH_GUIDE.md`](docs/security/STEALTH_GUIDE.md) — TLS fingerprinting (legal/ethical notice)
 - [`CLAUDE.md`](CLAUDE.md) — hard rules for AI agents
+- [tldrsec/awesome-secure-defaults](https://github.com/tldrsec/awesome-secure-defaults) — curated secure-by-default libraries

docs/README.md

@@ -70,11 +70,13 @@ Combo routing, scoring, and replay.
 
 ## security/
 
-Guardrails, compliance, and stealth.
+Guardrails, compliance, stealth, and the mandatory patterns for handling public credentials and error messages.
 
 - [GUARDRAILS.md](security/GUARDRAILS.md) — PII, prompt injection, vision guardrails.
 - [COMPLIANCE.md](security/COMPLIANCE.md) — audit trails and compliance.
 - [STEALTH_GUIDE.md](security/STEALTH_GUIDE.md) — TLS / fingerprint stealth.
+- [PUBLIC_CREDS.md](security/PUBLIC_CREDS.md) — **mandatory** pattern for embedding public upstream OAuth client_id/secret + Firebase Web keys without tripping secret scanners.
+- [ERROR_SANITIZATION.md](security/ERROR_SANITIZATION.md) — **mandatory** pattern for routing every error response through `sanitizeErrorMessage` to prevent stack-trace exposure.
 
 ## compression/