Audit fixes: revive the API, close the token leak, make self-hosting the default

[Bogzx]

Addresses the LearnLoop findings from repo-audit.html. Every claim below was verified by running the thing, not by reading it.

Verification (all run on this branch at final commit):

Check	Result
npm ci	clean, 315 packages
npm run typecheck	exit 0, 0 errors, 7 workspaces
npm test	exit 0 — 139 tests, 139 pass, 0 fail (baseline was 89)
npm run build --workspace=apps/dashboard	exit 0, ✓ Generating static pages (7/7)

---

Blocker fixes

tracedGenerate called itself — apps/api/src/gemini.ts:57 invoked tracedGenerate(params) instead of ai.models.generateContent(params). Every LLM call unwound into RangeError: Maximum call stack size exceeded before any network I/O, so all ten exported functions were dead and /score, /coach, /diff, /improve with them. The recursion was type-valid, which is why tsc and CI stayed green.

apps/api had no test script and zero tests — precisely why this shipped. Added apps/api/src/gemini.test.ts: seven tests that stub globalThis.fetch and assert a request actually reaches the transport, which is what infinite recursion prevents. Verified as a real regression guard: reintroducing the self-call turns the suite red with RangeError, not merely a failed assertion.

Two defects in the pre-existing uncommitted work were found and fixed before building on it: the test asserted five dimension names that do not exist (constraints/output_shape/verification vs the real specificity/constraint_articulation/output_specification), so 3 of 7 tests failed; and apps/api/package.json pointed test at two files that did not exist. It had never been run.

/coach failed open silently — apps/api/src/index.ts:471-483 answered a scoring failure with { proceed: true, text: '', overall: 0 }. The MCP tool (apps/mcp-server/src/tools.ts:339) renders an empty text on a proceed: true score-mode response as (coach overall: 0/10 — no coaching needed) — byte-identical to a flawless prompt. Whenever Gemini was down the tool ran forever: never coaching, never erroring, reporting success.

proceed stays true (a coaching sidecar outage must not block real work), but the response now carries degraded/error and a non-empty text naming the failure, and the MCP tool renders that instead of the success string. Helper extracted to apps/api/src/coach-degraded.ts so it is testable without booting an HTTP listener and a Postgres pool; 8 tests pin the contract.

No LICENSE, no license field in any of nine manifests — also hard-blocks vsce package. Added MIT LICENSE (Copyright (c) 2026 Bogdan Truta) and license: "MIT" to all nine manifests, plus repository on the two publishable ones.

The dead production host — trailheadapi-production.up.railway.app returns 404 and was the hardcoded default in ten source files. Rather than re-point at another host that can die, self-hosting is now the default: every surface defaults to http://localhost:3000 (the port apps/api actually listens on) and names the exact env var / setting when it cannot reach it. Changed: apps/browser-ext/src/config.ts:3, apps/vscode-ext/package.json:44, apps/vscode-ext/src/extension.ts:19, apps/dashboard/src/lib/api.ts:20, apps/mcp-server/bin/cli.mjs:56, apps/mcp-server/src/reset-cli.ts:67, apps/mcp-server/src/bootstrap-cli.ts:164, apps/mcp-server/src/smoke-test.mjs:28, apps/mcp-server/src/verify-all-tools.mjs:14, apps/browser-ext/manifest.json:10, apps/browser-ext/scripts/smoke.sh:8.

The browser popup gains an API server row that shows, edits and probes the URL. The dashboard fails at request time (never at module scope) so next build still produces its 7 routes.

Security

GET /teams returned every tenant's token, unauthenticated, with CORS * (apps/api/src/index.ts:127, 1557-1567). That token is the only credential in the system — read on the wiki (which summarises private source code) and write on everything — so one GET from any web page compromised every tenant at once.

It now requires X-Team-Token and returns only the caller's own team, as { name, id } where id is a truncated SHA-256 of the token: opaque, stable, safe to render, not replayable. TeamSummary no longer carries token, so the type system enforces this at every call site.

Client consequences, all deliberate: the popup's pick-a-team list is gone (switching teams means entering that team's token, which the popup resolves to a display name); the popup's reachability probe moved to GET /, the genuine unauthenticated endpoint; the dashboard shows the team its own NEXT_PUBLIC_TEAM_TOKEN resolves to and no longer prints the token into the page.

TRAILHEAD_AUTO_CREATE_TEAMS defaulted on (apps/api/src/index.ts:81) — any string any stranger sent silently provisioned a tenant row. Now defaults off; opt in with =true.

A live tenant token was committed in scripts/list-team-prompts.mjs:18 and scripts/delete-prompt.mjs:18. All three scripts/*.mjs were unreferenced one-offs and are deleted. See Not done below — the token still needs rotating by hand.

Compose ports bind to 127.0.0.1. docker-compose.yml sets TRAILHEAD_AUTO_CREATE_TEAMS=true so trailhead-mcp init's derived per-repo token is accepted; that combination must not be reachable from the network, so neither published port listens on 0.0.0.0.

Honesty pass

Every claim checked against code, not against the spec:

• README.md:99,108,320-323 — the debounced 250 ms scoring, the 5-second nudge and auto-send-on-timeout were all deliberately removed; apps/browser-ext/src/send-intercept.ts:17-21 lists them as gone. The extension scores on send and never auto-fires.
• README.md:84-85,288,371 — claimed Gemini 2.5 Flash / 2.5 Pro. packages/scoring/src/models.mjs uses gemini-3-flash-preview and gemma-4-31b-it. Nothing uses 2.5 Pro.
• README.md:123 — "Four hero tools"; apps/mcp-server/src/tools.ts registers five. Added the missing wiki_proven_prompts row, plus a note that npx trailhead-mcp does not work (private: true, neither name on npm).
• apps/vscode-ext/README.md:12 — Cmd+Shift+K articulation scaffold. The manifest contributes no keybindings at all and one command (trailhead.refresh). Moved to an explicit "specced but never built" section.
• apps/dashboard/README.md:47 — "All four routes prerender as static". There are five app routes and none prerender: / is force-dynamic, the other four read searchParams. Only the framework's /_not-found is static, which is why the build reports 7. (My own first correction here said "four are static" — caught it by reading the build output instead of trusting the audit.)
• apps/browser-ext/README.md:47 — pointed at a PINNED_CHROME.txt that was never created.
• packages/db/schema.sql:2 — "Six tables"; there are eight (wiki_jobs and wiki_job_paths landed with rich bootstrap).

New features

Self-host docker-compose — docker-compose.yml + apps/api/Dockerfile + .dockerignore + SELFHOSTING.md + rewritten .env.example. Postgres 16 with a named volume and pg_isready healthcheck, schema auto-applied on first boot via docker-entrypoint-initdb.d, API gated on service_healthy. A stranger needs only a Gemini key.

Wiki export to markdown — GET /wiki/export returns the whole team wiki as one markdown document (?drafts=true, ?format=json). The renderer is pure, so 14 tests cover the output contract. The case worth calling out: prompt templates routinely contain their own triple-backtick fences, so fence width is computed from the longest backtick run in the body — a hardcoded three-backtick fence closes early and silently truncates the export, the kind of corruption nobody notices until they need the backup. The tree query moved to apps/api/src/wiki-tree.ts so /wiki/tree and /wiki/export share one query instead of two copies that drift.

Remaining MEDIUM/LOW

• Bubble classifier over-matching (apps/browser-ext/src/selectors.ts:133-141, content.ts:78-91) — classifyBubble matched the node or any descendant, and the walker went outermost-first and let the outermost win, so one wrapper div swallowed the whole thread and every per-message widget mounted on the wrong element. Now matches the element itself only. The walker also stopped testing every div, article, li (thousands of elements per streaming token) in favour of querying the hint selectors directly. 9 tests.
• Duplicated types (apps/mcp-server/src/api-client.ts:19-43, apps/vscode-ext/src/api.ts:9-26) — four shared types re-declared locally while their neighbours in the same import block came from @trailhead/shared. Both now import and re-export. Also added SearchItem/SearchResponse to shared and applied them to GET /search, which returned c.json({ items: rows }) with no declared contract at all.
• Unverified .d.mts declarations (packages/scoring/tsconfig.json) — include was ["src/**/*.ts"], matching neither .mts nor .mjs, so nothing typechecked the implementations. Enabled allowJs/checkJs and widened the include (it immediately caught real implicit-any). More importantly, nothing compared a declaration to its implementation: declarations-match.test.mjs parses each .d.mts's value-level exports, imports the .mjs, and asserts both sets match in both directions. All ten pairs are in sync. Verified it fails: a phantom export declare const PHANTOM_MODEL turns it red naming the file and the symbol.
• Missing indexes (packages/db/schema.sql:71-81,96) — captures had nothing beyond its PK yet /team/metrics filters it on (team_token, created_at) and the dashboard polls every 30s per viewer. The /score dedup probe filters skill_observations on (team_token, user_id, dimension, prompt_hash, ts) but the only index led with (team_token, dimension) and carried neither user_id nor prompt_hash — and that probe runs once per dimension, five times per /score. Dropped idx_nodes_team_token_path, which duplicated the UNIQUE (team_token, path) constraint. Migration: packages/db/migrations/2026-08-17-hot-path-indexes.sql.
• Packaging — contributes.viewsContainers used the $(rocket) codicon where VS Code requires a file path, which fails vsce package. Added a real SVG at apps/vscode-ext/media/trailhead.svg.
• Clutter — deleted c.txt (five space characters, unreferenced), moved pitch-before-after.html into archive/, switched the landing page from react.development.js to the production builds.
• Naming split — left as-is. README.md:9-10 already explains that Trailhead is the internal codename and LearnLoop the product name; renaming nine packages is a large, risky change for little gain.

Not done and why

• 🔑 The leaked tenant token must be rotated by the repo owner, by hand. repo_dbab62ba8d72ca37 is removed from the working tree but remains in git history, and history was not rewritten (out of scope, and it would break every existing clone). Until it is rotated it remains a valid credential for that team. This needs the owner's account — it cannot be done from here.
• The Docker stack has never actually been run. Docker CLI 28.0.4 and Compose v2.34.0 are installed on this machine but the daemon is not running. docker compose config validates (exit 0 with GEMINI_API_KEY set, exit 1 with a readable message without it), so schema, interpolation, volumes and healthcheck wiring are checked — but docker compose up was never executed. Unproven at runtime: that the image builds, that npm ci succeeds in-container, that the API connects to Postgres, and that the schema auto-applies. These are reasoned from source, not observed. Please run it once before advertising it.
• npx trailhead-mcp still does not work. The package remains private: true and unpublished; renaming, unprivating, building to dist/ and bundling the workspace deps is a publishing decision for the owner, not a code fix. The README now says so plainly instead of advertising it.
• No browser-extension icons, no zip/crx step, no store listing. The vsce blocker is fixed, but producing icon art and store listings is a design/publishing task.
• The landing page still compiles JSX in-browser via @babel/standalone, and still uses the cdn.tailwindcss.com dev CDN. Both need a real build step, which also turns the Vercel deploy from "serve static files" into "run a build" — a bigger change than this pass, and documented inline in index.html.
• apps/landing-page/assets/logo-full.png is 488 KB and could be an order of magnitude smaller. Re-encoding a brand asset without the owner eyeballing the result is not a call to make from a script.
• The audit's "two files committed as UTF-16" could not be reproduced — a scan of every tracked file found no BOM-prefixed or null-heavy UTF-16 content. Either already fixed, or the finding was inaccurate.
• apps/landing-page is not actually a workspace (it has no package.json) despite the root workspaces: ["apps/*"] implying it. Left alone; changing it affects the deploy.
• Not attempted from the audit's feature list: local/Ollama model support, weekly Slack/Discord digest, score trend over time, PR description scoring, prompt diff replay.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
learnloop	Ready	Preview	Aug 17, 2026 4:53pm
polihackwinners-dashboard	Ready	Preview	Aug 17, 2026 4:53pm