- providers.ts: close the unterminated `dify` APIKEY_PROVIDERS entry (Wave-1b #2488
merge artifact) that broke the entire build (esbuild 'Expected }').
- CHANGELOG.md: restore the `# Changelog` header and an empty `[Unreleased]` section
(docs-sync requires the first section to be Unreleased); remove the duplicated
`[3.8.1]` block.
- Bump package.json / electron / open-sse / openapi.yaml to 3.8.2 to match the
CHANGELOG release header.
- Mirror the `[3.8.2]` section into all 41 i18n CHANGELOGs so docs-sync passes.
Unblocks all commits on release/v3.8.2-based branches.
A corrupted or mis-typed credential (non-string apiKey, or a non-string
modelsUrl from providerSpecificData/registry) could throw
'TypeError: ... is not a function' when validation called .startsWith()/.trim()
during a provider connection test. Adds typeof guards in validateOpenAILikeProvider,
validateGeminiLikeProvider and validateSnowflakeProvider so validation returns a
clean { valid } result instead of crashing. Does not pinpoint the NVIDIA NIM
e.startsWith report (needs a stack trace), but hardens the whole class.
New perplexityTlsClient.ts (Firefox-148 TLS profile, mirrors chatgptTlsClient)
routes perplexity-web requests so Cloudflare stops 403-challenging datacenter
IPs. Executor and connection validator now distinguish a Cloudflare block from
an invalid session cookie. Adds OMNIROUTE_PPLX_TLS_TIMEOUT_MS /
OMNIROUTE_PPLX_TLS_GRACE_MS. Co-authored analysis by havockdev.
The cliproxyapi sidecar (service + named volume + DOCKER_GUIDE.md docs)
was accidentally dropped in 3ff3e3dd1, a commit whose message only
mentioned a ChatPlayground guard. Restore the pre-removal version of
docker-compose.yml and docs/guides/DOCKER_GUIDE.md from 49fe356b9 —
re-adds the `cliproxyapi` profile on port 8317 and the cliproxyapi-data
volume while preserving the docs YAML frontmatter.
* fix(cli-tools): guard modelId type before calling indexOf
E2E shakedown v3.8.0: cli-tools quebrava com TypeError quando dynamicModels
continha entradas sem .id (objeto retornado diretamente em vez de string).
* fix(offline): avoid SSR/CSR hydration mismatch on navigator.onLine
Replace useState+lazy-initializer with useSyncExternalStore so the server
snapshot (() => false) and client snapshot (() => navigator.onLine) are
declared separately. React hydrates with the server value and switches to
the real online status client-side without a mismatch.
* chore(i18n): add missing en.json keys for translator, cli-tools, memory, onboarding
Adds 58 missing keys identified by the new dashboard audit script:
- cliTools: 18 custom CLI builder keys (CustomCliCard)
- translator: 24 keys covering stream transformer, live monitor, test bench
- memory: 12 health/pagination/dialog keys
- onboarding.tier: 8 keys for the tier tour walkthrough
Also adds scripts/i18n/audit-dashboard-pages.mjs which scans all dashboard
pages, reports t() calls referencing missing en.json keys, and flags
candidate hardcoded JSX/attribute strings.
* chore(i18n): replace hardcoded UI text with t() calls across dashboard (round 1)
Subagents refactored 8 high-impact dashboard pages, replacing 81 of the
407 hardcoded English/PT strings flagged by the audit with proper
useTranslations() lookups. Added 73 corresponding keys to en.json across
the home, apiManager, providers, settings, and usage namespaces.
Pages affected:
- BudgetTab (27 → 0)
- HomePageClient (2 → 0)
- RoutingTab (25 → 7)
- ResilienceTab (38 → 18)
- SystemStorageTab (42 → 21)
- providers/[id] (17 → 15)
- ApiManagerPageClient (14 → 13)
- OneproxyTab (13 → 10)
Also adds two helper scripts:
- scripts/i18n/extract-keys-from-diff.mjs — extracts new keys from git diff
- scripts/i18n/merge-keys.mjs — merges a pending-keys JSON into en.json
Remaining hardcoded strings will be addressed in follow-up rounds.
* chore(i18n): replace hardcoded UI text with t() calls across dashboard (round 2)
Continues round 1 (commit 8d34f4c65). Round-2 subagents refactored
additional dashboard pages, replacing 77 more hardcoded strings with
useTranslations() lookups. Added 79 corresponding keys to en.json
across the a2aDashboard, agents, analytics, apiManager, cliTools,
common, and settings namespaces.
Pages affected:
- a2a/page (new useTranslations + 6 keys)
- agent-skills/page (new useTranslations + 9 keys)
- AutoRoutingAnalyticsTab (new useTranslations + 6 keys)
- AppearanceTab (8 → 6 remaining)
- OneproxyTab (10 → 0)
- ResilienceTab (18 → 0 missing key)
- RoutingTab (7 → 0 missing key)
- VisionBridgeSettingsTab (new useTranslations + 6 keys)
- CopilotToolCard (7 → 0 missing key)
- ApiManagerPageClient (13 → 0 missing key)
- gamification/admin (new useTranslations + 7 keys)
Hardcoded total: 326 → 249. Real missing keys: 0 (the 6 still flagged
are false positives in exampleTemplates.tsx where t is passed as a
parameter — keys exist at translator.templatePayloads.*).
* chore(i18n): replace hardcoded UI text with t() calls across dashboard (round 3)
Round-3 subagents and manual edits refactored 9 more dashboard pages
(plus 2 small extras), replacing ~80 hardcoded strings with
useTranslations() lookups. Added 79 corresponding keys to en.json
across analytics, cloudAgents, combos, common, health, settings, and
usage namespaces.
Pages affected:
- analytics/ComboHealthTab (new useTranslations + 15 keys)
- analytics/CompressionAnalyticsTab (new useTranslations + 11 keys)
- settings/SystemStorageTab (21 → 0 missing key)
- tokens/page (new useTranslations + 13 keys)
- usage/BudgetTab (9 missing fixed)
- health/page (manual: 6 keys)
- cloud-agents/page (manual: 3 keys)
- combos/page (manual: 1 key)
Hardcoded total: 249 → 164. Real missing keys: 0 (6 remaining are
exampleTemplates.tsx false positives).
Also adds scripts/i18n/build-pending-from-missing.mjs which reads
_audit.json and locates English values from HEAD to rebuild
_pending-keys.json after race-condition resets between subagent edits.
* chore(i18n): localize remaining dashboard settings labels
Replace hardcoded labels in compression and resilience settings with
translation lookups to continue the dashboard i18n cleanup.
Add the v3.8.0 dashboard shakedown runbook to document the manual
smoke-test process and known dev environment pitfalls.
* chore(i18n): replace hardcoded UI text with t() calls across dashboard (round 4)
Round-4 subagent + manual key-resolution refactored remaining strings in
3 high-traffic settings/API tabs, plus extracted English values for
keys that were already added as t() calls but lost during the previous
en.json race-condition resets.
Pages affected:
- api-manager/ApiManagerPageClient (7 → 0 missing key)
- settings/CompressionSettingsTab (8 → 0 missing key)
- settings/MemorySkillsTab (8 → 0 missing key)
- settings/ResilienceTab (4 more keys recovered)
Hardcoded total: 164 → 140. Real missing keys: 0 (6 remaining are the
exampleTemplates.tsx false positives — t passed as parameter).
* chore(i18n): replace hardcoded UI text with t() calls across dashboard (round 5)
Round-5 agent began processing the remaining smaller dashboard files.
Added 5 more keys to en.json for providers/[id]/page.tsx OAuth flow
labels and the cross-OS auto-detection hint.
Pages affected:
- providers/[id]/page.tsx (5 keys)
Hardcoded total: 140 → 136. Real missing keys: 0.
* chore(i18n): resolve last 2 missing providers/[id] keys
Adds providerDetailMyClaudeAccountPlaceholder and
providerDetailPathAutoDetected — the final user-visible labels in the
providers/[id] page that the round-5 subagent rewrote to t() calls
without yet adding to en.json.
Real missing keys: 0 (6 remaining are exampleTemplates.tsx false
positives — t is passed as a parameter so the audit cannot resolve the
namespace; keys do exist at translator.templatePayloads.*).
* chore(i18n): replace hardcoded UI text with t() calls across dashboard (round 6 — 10 parallel agents)
Round-6 dispatched 10 parallel subagents covering all 57 remaining
dashboard files. Each agent worked on a disjoint file set to avoid
en.json race conditions. Added ~60 new i18n keys across 9 namespaces
covering small UI labels, table headers, search placeholders, and
empty-state messages.
Major changes:
- analytics: SearchAnalyticsTab, ProviderUtilizationTab, DiversityScoreCard, CompressionAnalyticsTab (new useTranslations + keys)
- batch: BatchDetailModal, BatchListTab, FileDetailModal, FilesListTab (new useTranslations + keys)
- settings: CliproxyapiSettingsTab, PayloadRulesTab, ModelCooldownsCard, AppearanceTab, PricingTab (mostly new useTranslations)
- endpoint: TokenSaverCard, ApiEndpointsTab, EndpointPageClient
- cache: CachePerformance, IdempotencyLayer, ReasoningCacheTab, MediaPageClient, page
- combos: IntelligentComboPanel, page
- playground: ChatPlayground, SearchPlayground
- providers: ProviderCard
- onboarding: TierFlowDiagram
- changelog: ChangelogViewer
- home: ProviderTopology, TierCoverageWidget, BootstrapBanner, BadgeToast
- usage: BudgetTab, BudgetTelemetryCards, QuotaTable
- quotaShare: QuotaSharePageClient
- profile: page
- leaderboard: page
- skills: page
Hardcoded total: 131 → 60. Real missing keys: 0 plus 1 false-positive
for combos.modePack (lookup via prop-passed t).
* chore(i18n): finalize round-6 keys for batch/cache/endpoint/usage
Adds the remaining keys produced by parallel agents A4, A6, A8, A9:
- common: batch-related labels (BatchDetailModal, BatchListTab,
FileDetailModal, FilesListTab, page) + profile/leaderboard
- cache: hit rate, latency, retry, avg chars
- endpoint: token saver, API endpoints, copy URL, cloud/local labels
- usage: noSpend, activeSessions, quotaAlerts, budget timing
- skills: install/marketplace/filter
- proxyRegistry/quotaShare/mcpDashboard: misc labels
Hardcoded total: 60 → 48. Real missing keys: 0 (modePack remaining is a
false positive — combos.modePack exists but the audit can't resolve it
since IntelligentComboPanel receives t as a prop).
* fix(playground): dedupe filteredModels to avoid duplicate React key warning
The /v1/models endpoint can return the same model id twice (e.g., when a
model is listed by both an alias and its canonical provider), which made
the <Select> emit two <option> elements with the same key — triggering
"Encountered two children with the same key, codex/gpt-5.5".
Replace the chained filter + map with a single pass that skips ids
already added.
* fix(playground): guard against non-string model ids before .split/.startsWith
The /v1/models endpoint can include synthetic entries (combos, locals,
in-progress imports) with a null/undefined id. The playground used to
call m.id.split("/") in the provider-discovery loop, which threw on the
first non-string entry; the surrounding .catch(() => {}) silently
swallowed the error, so the provider/model/account dropdowns ended up
empty even though /v1/models returned thousands of valid entries.
- Skip entries without a string id before split/startsWith.
- Log the rejection in the .catch handler so future regressions are
visible in DevTools instead of silently emptying the UI.
* fix(playground): guard ChatPlayground filteredModels for non-string ids
Same root cause as commit 49fe356b9: ChatPlayground filtered models
with m.id.startsWith(...) which crashed on null/undefined ids returned
by /v1/models (synthetic combo entries). Apply the same defensive guard
and dedupe used in the parent page.
* fix(claude): drop orphan tool_result after fixToolAdjacency strip (discussion #2410)
Discussion #2410 reports Claude returning 400 for sequences like:
assistant: tool_use(id=X)
user: <plain text> ← breaks adjacency
user: tool_result(id=X)
The previous round added `fixToolAdjacency` (commit 44d9abac9) which
correctly strips the orphan tool_use from the assistant message. But
that left the now-unmatched tool_result intact, so the upstream
rejected the request with:
messages.N.content.M: unexpected `tool_use_id` found in `tool_result`
blocks: X. Each tool_result block must have a corresponding tool_use
block in the previous message.
Fix: after running `fixToolAdjacency`, re-run `fixToolPairs` to drop
the orphaned tool_result blocks. All three call sites updated:
- contextManager.purifyHistory (both inside the binary-search loop
and the final pass)
- BaseExecutor message-prep (Claude path)
- claudeCodeCompatible request signer
Also tightens an unrelated dynamic-key access in
readNestedString (claudeCodeCompatible) to satisfy the prototype-
pollution scanner triggered by the post-tool semgrep hook.
* fix(mitm): point runtime manager re-export to js entrypoint
Use the emitted `.js` path for the runtime manager re-export so dynamic
runtime loading resolves correctly outside the Turbopack alias handling.
* docs: add AgentRouter setup guide (#2422)
Integrated into release/v3.8.0 — AgentRouter setup guide docs.
* feat: add new feature on combos - falloverBeforeRetry (#2417)
Integrated into release/v3.8.0 — falloverBeforeRetry for per-model quota skipping in combos.
* feat(batch): implement 10 feature requests harvested (#2414)
Integrated into release/v3.8.0 — batch of 10 feature requests: llama.cpp local provider, upstream error exposure, Termux detection, providers rotate CLI, t3.chat web skeleton, Zed Docker integration, Kiro multi-account OAuth isolation, auto-combo cost blending, auto-combo context filter, combo provider-level exhaustion tracking (#1731). Conflicts with #2417 (falloverBeforeRetry) resolved.
* fix(gamification): resolve SQL bug, auth gap, pagination, and anomaly scoring (#2421)
Integrated into release/v3.8.0 — 6 critical gamification bug fixes: SQL SELECT in checkActionCountBadges, federation auth enforcement, leaderboard pagination offset, real z-score computation, addXp level calculation, and barrel index.ts
* docs(changelog): add post-release entries for #2414#2417#2421#2422
- feat(batch): T3-Chat-Web executor, exhaustedProviders set (#1731), Zed Docker
- feat(combos): falloverBeforeRetry + setTry loop (#2417 — @hartmark)
- fix(gamification): SQL SELECT bug, federation auth, pagination, z-score (#2421 — @oyi77)
- docs: AgentRouter setup guide (#2422 — @leninejunior)
* fix(security): resolve CodeQL random/password-hash alerts and sync docs & tests
---------
Co-authored-by: diegosouzapw <diego.souza.pw@gmail.com>
Co-authored-by: Lenine Júnior <lenine@engrene.com.br>
Co-authored-by: Markus Hartung <mail@hartmark.se>
Co-authored-by: Paijo <14921983+oyi77@users.noreply.github.com>
Adds `.safeParse()` to cli-tools/apply and cli-tools/config POST handlers to
satisfy the check:route-validation:t06 CI gate. Regenerates all 41 locale
translations of CLAUDE.md to clear the i18n strict-drift check failure.
feat(cli): suporte i18n completo — 42 locales, --lang flag, config lang get/set/list
- 42 locale files in bin/cli/locales/ (en + pt-BR fully translated, 29 with common/program, 11 scaffolds)
- --lang <code> global flag for per-execution override
- config lang get/set/list subcommands
- Locale persistence via ~/.omniroute/.env
- Path traversal protection via regex validation in normalize()
- Script generate-locales.mjs for scaffolding new locales
- Unit tests for lang commands + normalization security
Integrated into release/v3.8.0
Adiciona testes de isLoopback (aceita loopback, rejeita IPs públicos), verificação
de hash por máquina e DISABLE flag; testes de detectRestrictedEnvironment para
Codespaces/WSL/CI/Gitpod; e docs/security/CLI_TOKEN_AUTH.md com threat model.
Remove every reference to the competing open-source project from docs,
comparisons, i18n mirrors, comments, and source files so the branch
history does not expose competitive intelligence.
- management.ts: replace === with timingSafeEqual for CLI token comparison
- machineToken.ts: salt upgraded to omniroute-cli-auth-v1; OMNIROUTE_CLI_SALT env
var honoured for rotation; full 64-char SHA-256 hex token
- tray.ps1: accept .png via GDI+ Bitmap->Icon handle; Windows tray works without .ico
- tray.ts: getIconPath() tries icon.ico then icon.png on Windows
- compression/types.ts: DEFAULT_CAVEMAN_CONFIG.preservePatterns filled with
six defaults (fenced code, inline code, URLs, paths, error lines, stack traces)
- CLAUDE.md: Hard Rule #15 — spawn-capable routes must use isLocalOnlyPath()
- .env.example + docs/reference/ENVIRONMENT.md: document OMNIROUTE_CLI_SALT
- docs/security/CLI_TOKEN.md: new (was referenced in changelog but missing)
- docs/security/ROUTE_GUARD_TIERS.md: new (was referenced in changelog but missing)
- tests/unit/lib/machineToken.test.ts: updated for 64-char token; added
OMNIROUTE_CLI_SALT env-var rotation test
- Add az locale to config/i18n.json (source of truth, 42 locales total)
- Create src/i18n/messages/az.json (UI strings from en.json base)
- Create docs/i18n/az/ directory with full documentation set
- Add 🇦🇿 Azərbaycan dili to README.md language bar
- Add az entry to docs/i18n/README.md index (40 doc languages)
- Add az to generate-multilang.mjs LOCALE_SPECS (Google TL: az)
- Add az to i18n_autotranslate.py lang_map
- Update CHANGELOG.md with feat(i18n) entry
Adiciona ServerSupervisor (bin/cli/runtime/processSupervisor.mjs) que reinicia o
servidor com backoff exponencial (1s, 2s, 4s... cap 10s) em caso de crash.
Após maxRestarts falhas em 30s exibe crash log e encerra. Detecta MITM como
causa do crash via heurística e desabilita automaticamente.
PID management agora é granular por subprocesso (~/.omniroute/{service}/.pid)
suportando server, mitm e tunnel/cloudflared|tailscale. `stop` e
`killAllSubprocesses` encerram todos os serviços registrados.
Novas opções em `serve`: --log (passa stdout/stderr inline), --no-recovery
(comportamento legado sem supervisor), --max-restarts <n> (padrão 2).
Remove o monolito bin/cli-commands.mjs (2853 linhas) e helpers redundantes
(bin/cli/args.mjs, tests/unit/cli-args.test.ts). Todos os subcomandos já foram
migrados individualmente para bin/cli/commands/ nas Fases 1.1–1.7. Atualiza
pack-artifact-policy para referenciar bin/cli/program.mjs no lugar de
bin/cli-commands.mjs e bin/cli/index.mjs. Atualiza docs e CHANGELOG.
Adds bin/cli/runtime/sqliteRuntime.mjs that resolves better-sqlite3 from:
(1) bundled optionalDependency, (2) ~/.omniroute/runtime/ install,
(3) lazy npm install into runtime dir, (4) node:sqlite stdlib (Node >=22.5),
(5) bundled sql.js WASM. Each native binary is validated against expected
platform magic bytes (ELF/Mach-O/PE) before load.
Adds bin/cli/runtime/magicBytes.mjs with validateBinaryMagic() helper
(9 tests). Adds bin/cli/runtime/index.mjs as warmUpRuntimes() orchestrator.
Adds scripts/postinstall.mjs warm-up hook (non-fatal, skipped in CI).
Integrates it as the last step of scripts/build/postinstall.mjs.
Extends src/lib/db/core.ts with ensureDbInitialized() (async, idempotent)
and getDriverInfo() so the startup orchestrator can await the resolver
before any DB access, enabling graceful degradation without crashing the
process on missing better-sqlite3.
Solves Windows EBUSY error on 'npm install -g omniroute@latest' while the
previous version is still running, and works in environments without C++
build tools or with unreachable npm registry.
Documents OMNIROUTE_SKIP_POSTINSTALL in .env.example and ENVIRONMENT.md.
Ref: 9router/cli/hooks/sqliteRuntime.js (pattern origin).
When users configured `visionBridgeModel: "gemini/gemini-2.0-flash"` (or
any non-Anthropic prefix like `openrouter/...`, `google/...`), every
request failed with `Vision API error 401: You didn't provide an API
key` from OpenAI. The helper hardcoded `https://api.openai.com/v1` as
the base URL and `OPENAI_API_KEY` as the auth header for any model
that wasn't `anthropic/*`, so users without an OpenAI key (or who
wanted to use Gemini/OpenRouter/OmniRoute self-loop) had no path that
worked.
This change adds two env vars:
- VISION_BRIDGE_BASE_URL — alternate OpenAI-compatible base URL.
Priority: VISION_BRIDGE_BASE_URL → legacy OpenAI URL env →
api.openai.com (default).
- VISION_BRIDGE_API_KEY — alternate API key for that endpoint.
Priority: explicit caller arg → VISION_BRIDGE_API_KEY →
per-provider env (Anthropic/Google/OpenAI) → OpenAI fallback.
Anthropic models (anthropic/*) keep their dedicated `x-api-key` path
with the Anthropic env key unchanged — the override only affects the
OpenAI-compat branch, since the wire format differs.
Operators now have stable paths to:
- Route through OmniRoute itself (any registered model works):
VISION_BRIDGE_BASE_URL=http://localhost:20128/v1
VISION_BRIDGE_API_KEY=sk-<omniroute-key>
- Use Google's Gemini OpenAI-compat endpoint directly:
VISION_BRIDGE_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
- Use OpenRouter directly:
VISION_BRIDGE_BASE_URL=https://openrouter.ai/api/v1
Reported by @kapustacool-lgtm. Documented in `.env.example` and
`docs/reference/ENVIRONMENT.md`. 11 unit tests cover env precedence
and the Anthropic-bypass guarantee.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Phase 0.1 — single source of truth for CLI Tools documentation.
`docs/CLI-TOOLS.md` was a 492-line copy frozen at v3.0.0-rc.16 (13 tools,
outdated provider tables). The current source of truth is
`docs/reference/CLI-TOOLS.md` (v3.8.0, 17 tools, referenced by CLAUDE.md
and every cross-doc link in docs/).
Changes:
- delete docs/CLI-TOOLS.md (no remaining references; all docs already
pointed at docs/reference/CLI-TOOLS.md)
- scripts/check/check-docs-sync.mjs: add anti-regression check that
fails if a legacy superseded doc reappears
Verified: \`npm run check:docs-sync\` passes; rg shows zero remaining
references to the legacy path outside _references/ and _tasks/.
Refs: _tasks/features-v3.8.0/cli/fase-0-preparacao/0.1-limpar-docs-duplicada.md
The 1.0.0 release of the package was broken end-to-end:
1. index.js re-exported from "./index.ts" — Node can't import .ts at runtime,
so any consumer who `npm install`ed the package got ERR_UNKNOWN_FILE_EXTENSION.
2. The emitted provider shape did not match the OpenCode schema
(https://opencode.ai/config.json). It used a custom `{id, name, npm, options, auth}`
instead of the schema's `{npm: "@ai-sdk/openai-compatible", name, options, models}`.
3. README told users to pass `baseURL: "http://localhost:20128/v1"` but the code
appended `/v1` again — every request would 404 at `/v1/v1/...`.
4. No build step, no LICENSE file, no repository/author/engines fields, no tests.
This rewrite:
- Moves source under `src/`, adds a tsup build emitting CJS + ESM + .d.ts.
- `createOmniRouteProvider` now returns a schema-valid entry with
`npm: "@ai-sdk/openai-compatible"` + `models: Record<string, { name }>`.
- Adds `buildOmniRouteOpenCodeConfig` for full-document scaffolding.
- `normalizeBaseURL` deduplicates trailing `/` and `/v1`, accepts both forms,
and rejects malformed URLs and empty inputs.
- 13 unit tests covering URL normalisation, input validation, default model
catalog, custom models + labels, dedup/trim behaviour, and JSON round-trip.
- Adds LICENSE, full package.json (repository, engines, scripts, exports),
.gitignore, .npmignore, tsconfig.json, and a comprehensive README.
- Resets version to 0.1.0 to signal the pre-1.0 reset (1.0.0 was never on npm).
Documentation:
- New `docs/frameworks/OPENCODE.md` covering both integration paths (CLI vs npm),
URL normalisation, auth modes, troubleshooting, and runtime flow.
- README.md links the package and points to the new doc.
- CHANGELOG entry under Unreleased > Changed.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CodeQL js/stack-trace-exposure does not recognize sanitizers reached
through a custom helper indirection — flagging callsites like
open-sse/utils/error.ts::errorResponse and
open-sse/executors/cursor.ts::buildErrorResponse even though both route
through sanitizeErrorMessage().
Record the dismissal precedent (alerts #224 and #231, May 2026):
- Add a "Known CodeQL limitation" section in
docs/security/ERROR_SANITIZATION.md documenting how to handle future
occurrences (verify callchain → verify test coverage → dismiss with
reference, do NOT duplicate the pattern inline).
- Extend CLAUDE.md Hard Rule #14 with the precedent so the next
engineer doesn't try to "fix" the false positive by weakening the
shared sanitizer.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Blackbox's `/api/chat` now rejects requests whose `validated` field
doesn't match the frontend `tk` token (exported from app.blackbox.ai's
Next.js bundle), returning HTTP 403 even when the session cookie is
valid and the subscription is active. The previous executor sent a
random UUID, which works only until Blackbox enforces the check.
This change:
- Adds `resolveBlackboxValidatedToken()` that returns
`BLACKBOX_WEB_VALIDATED_TOKEN` when set, otherwise falls back to the
legacy random UUID (no regression for users who already work).
- Detects 403 responses whose body indicates a token-specific failure
("invalid validated token", "validation token", etc.) and replaces
the generic "cookie expired" message with explicit guidance to set
BLACKBOX_WEB_VALIDATED_TOKEN. The cookie-expired path is preserved
for non-token 401/403.
- Documents the env var in `.env.example` and
`docs/reference/ENVIRONMENT.md` (env-doc-sync check passes).
Deliberately NOT included: runtime scraping of Blackbox's Next.js
chunks to auto-extract `tk`. That coupling to their bundle hash would
silently break on every frontend deploy — the env override is the
stable path for operators who have already resolved the token.
Reported by @kazimshah39 with detailed root-cause analysis.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Fixes the 4 fixable alerts opened in the recent scan and adds enforceable
guardrails so future development follows the same pattern.
Code fixes:
- src/mitm/cert/install.ts: pass certPath/certName/action via exec()'s env
option instead of string-interpolating them into the bash script
(CodeQL js/shell-command-injection-from-environment #225)
- scripts/docs/{gen-provider-reference,add-frontmatter,fix-internal-links}:
escape backslash before other regex/markdown metacharacters
(CodeQL js/incomplete-sanitization #227, #228, #229)
Documentation (mandatory patterns):
- docs/security/PUBLIC_CREDS.md — embedding public upstream OAuth/Firebase
identifiers via resolvePublicCred(); never as string literals
- docs/security/ERROR_SANITIZATION.md — routing every error response through
sanitizeErrorMessage()/buildErrorBody(); never raw err.stack/err.message
- CLAUDE.md: 4 new Hard Rules (#11-#14) + Security section + scenario notes
- AGENTS.md, CONTRIBUTING.md: cross-reference the two new docs
- SECURITY.md: extended Hard Security Rules with the new mandatory patterns
- docs/README.md: index entries pointing to the two new docs
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Wires the new platform-overhaul gates into the Detailed Checklist used by
the release-cut workflow:
Documentation block:
npm run check:docs-all (umbrella over sync, counts, env-doc, deprecated, doc-links)
npm run check:env-doc-sync (code ↔ .env.example ↔ ENVIRONMENT.md parity)
npm run check:doc-links (no broken internal markdown refs)
i18n block (replaces stale `scripts/i18n-check.mjs` mention):
npm run i18n:check (drift between source docs and .i18n-state.json)
npm run i18n:check-ui-coverage (every locale ≥ 80% UI key coverage)
npm run i18n:sync-ui:dry (0 missing keys across 40 locales)
Note about running npm run i18n:run when source English docs change.
These are the same checks newly enforced by the docs-sync-strict and
i18n-ui-coverage CI jobs added in commit acf6b93d.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
The FASE 7 frontmatter sync touched docs/architecture/ARCHITECTURE.md but
.i18n-state.json was not refreshed, so npm run i18n:check reported
source-changed drift on every subsequent run.
Resolution: re-ran the hash-based translator end-to-end (npm run i18n:run
-- --locale=pt-BR --files=docs/architecture/ARCHITECTURE.md) which:
- retranslated the source through the production backend (14 chunks,
75 KB pt-BR output);
- persisted the new source/target SHA-256 pair in .i18n-state.json
(target_hash now matches the regenerated translation);
- left every other source/locale pair untouched.
After the run:
npm run i18n:check → PASS - all sources and targets match recorded hashes.
The pre-commit i18n drift advisory will no longer warn for this file.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
