docs(db): guardrail listInstallations/listRepositories against tenant-facing misuse

[JSONbored]

Summary

Closes #4797. Audited every query touching installations, repositories, and repository_settings — the shared tables Rent-a-Loop's architecture (#4783) reuses — for tenant-scoping at the query layer, not just application logic.

Single-row lookups are correctly scoped: getRepositorySettings, getRepository, getInstallation, listInstalledRepoFullNamesForInstallation all take their scoping key as an explicit function parameter, so the query itself can't return another tenant's row regardless of caller behavior.

Bulk queries have a real gap, now guardrailed: listInstallations/listRepositories have no WHERE clause — every row, every call. Traced all 30+ call sites (src/queue/**, src/review/**, src/github/backfill.ts, src/api/routes.ts, src/services/**): every one is internal cross-repo maintenance machinery or an admin/maintainer/owner-role-gated dashboard route (verified via canSessionAccessPath/requireAppRole at each API call site — e.g. /v1/repos, /v1/installations all require an authorized admin session). No live leak exists today, but the isolation only holds because every current caller happens to be admin-gated, not because the query itself enforces it — exactly the risk class the issue's problem statement calls out. Added doc-comment guardrails on both functions pointing at the correctly-scoped alternatives, so a future customer-facing endpoint doesn't reach for them by habit.

Full audit findings posted on #4797.

Test plan

• npx tsc --noEmit clean
• npm run test:ci (full local gate incl. drift checks, coverage, engine parity, MCP/miner packs, UI build): green, verified via literal captured exit code
• Confirmed no other stale nested node_modules/@loopover/* copies exist in this checkout that could mask a real failure
• Rebased onto latest origin/main, no conflicts

[superagent-security]

Superagent didn't find any vulnerabilities or security issues in this PR.

[loopover-orb]

Tip

✅ LoopOver review result - approve/merge recommended

_{Review updated: 2026-07-16 02:14:26 UTC}

1 file · 1 AI reviewer · no blockers · readiness 86/100 · CI green · clean

✅ Suggested Action - Approve/Merge

• safe to merge

Review summary
This PR adds doc-comment-only guardrails to `listInstallations` and `listRepositories` in src/db/repositories.ts, warning future callers not to use these unscoped bulk queries in tenant-facing paths and pointing to the correctly-scoped alternatives. The change is purely additive (comments only, no logic touched) and matches its stated intent — no functional risk, but it also does not add any actual enforcement (e.g. a lint rule, runtime assertion, or type-level restriction) to prevent misuse, relying entirely on future contributors reading the doc comment.

Nits — 6 non-blocking

• This is a documentation-only guardrail with no enforcement mechanism — a future contributor could still call `listInstallations`/`listRepositories` from a tenant-facing route without ever seeing the comment; consider whether a lint rule or a differently-named/wrapped function (e.g. `listInstallationsUnscoped_INTERNAL`) would provide a stronger guardrail than a JSDoc comment alone.
• No test changes accompany this PR, but since the diff only adds comments and doesn't alter behavior, that's expected and not a gap.
• Consider renaming the functions or adding a lightweight runtime guard (e.g. requiring an explicit `{ internal: true }` marker) to make misuse fail loudly rather than rely on doc-comment discipline, per src/db/repositories.ts:304 and :546.
• If the audit findings referenced in the PR description (30+ call sites) aren't already written up in issue Cross-tenant data-isolation audit #4797, link the specific commit/comment there for future auditors.
• PR author also opened the linked issue — Link an issue that was opened by a different contributor, or provide a rationale for why this self-authored issue represents genuine discovery work.
• Code changes lack test evidence — Add focused regression tests or explain why existing coverage is sufficient.

Decision drivers

• ✅ Code review — No blockers (1 reviewer)
• ✅ Gate result — Passing (No configured blocker found.)

Context & advisory signals — never blocks the verdict

Signal	Result	Evidence
Linked issue	✅ Linked	#4797
Related work	✅ No active overlap found	No same-issue or scoped active PR overlap found.
Change scope	❌ 8/20	High review scope from cached public metadata (1 linked issue).
Validation posture	✅ 25/25	PR body includes validation/test evidence.
Contributor workload	✅ 10/10	Author activity: 42 registered-repo PR(s), 34 merged, 443 issue(s).
Contributor context	✅ Confirmed Gittensor contributor	JSONbored; Gittensor profile; 42 PR(s), 443 issue(s).
Improvement	ℹ️ None detected	risk: low · value: none · LLM: minor

Linked issue satisfaction

Partially addressed
The PR performs a real query-layer audit and adds guardrail comments, but the acceptance criterion demands every gap be fixed before closing, whereas listInstallations/listRepositories remain unscoped at the query layer and rely on doc comments plus current caller admin-gating rather than an actual query-layer fix.

Review context

• Author: JSONbored
• Role context: owner (maintainer lane)
• Public audience mode: oss maintainer
• Lane context: Repository is configured for direct PR review.
• Public profile languages: not available
• Official Gittensor activity: 42 PR(s), 443 issue(s).
• PR-specific overlap: none found.

Contributor next steps

• Start here: Treat this as maintainer-lane context rather than normal contributor-lane activity.
• Then work through the remaining 2 steps in the Signals table above.

Signal definitions

• Related work = same linked issue, overlapping active PRs, or title/path similarity.
• Change scope = cached public metadata such as size labels, draft state, and review-burden hints.
• Validation posture = whether the PR provides enough public validation/test evidence for maintainer review.
• Contributor workload = public contributor activity and cleanup pressure, not a repo-wide quality failure.
• Contributor context = public GitHub/Gittensor identity context; non-Gittensor status is not a blocker.

🧪 Chat with LoopOver

Ask LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.

• @loopover ask <question> answers contribution-quality Q&A with source citations and freshness.
• @loopover chat <question> answers in natural prose from cached decision-pack facts via local inference (maintainer/collaborator; read-only).
• A plain-language @loopover mention with a real question is routed to the closest matching read-only command automatically — no exact syntax required.

Full command reference: https://gittensory.aethereal.dev/docs/loopover-commands

🧪 Experimental — new and may change.

_{🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed}

---

💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →.

Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.

• Re-run LoopOver review

[loopover-orb]

LoopOver approves — the gate is satisfied and CI is green.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 95.60%. Comparing base (44570d0) to head (4a96d42).
⚠️ Report is 42 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #6328   +/-   ##
=======================================
  Coverage   95.60%   95.60%           
=======================================
  Files         596      596           
  Lines       47121    47121           
  Branches    14999    14999           
=======================================
  Hits        45049    45049           
  Misses       1290     1290           
  Partials      782      782           

Flag	Coverage Δ
shard-1	43.95% <ø> (-0.18%)	⬇️
shard-2	36.80% <ø> (+0.29%)	⬆️
shard-3	32.35% <ø> (-0.05%)	⬇️
shard-4	33.60% <ø> (-0.81%)	⬇️
shard-5	31.84% <ø> (-0.05%)	⬇️
shard-6	45.19% <ø> (+0.41%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/db/repositories.ts	96.80% <ø> (ø)