orb(chat): session→installation→repo authz and hosted-tenant readiness for the chat surface

[JSONbored]

Context

Part of the ORB maintainer chat platform epic; do not start before the epic's spec sub-issue closes (it fixes the authz matrix and tenant model). The chat surface lives in apps/loopover-ui's authenticated app area and must resolve, per session, which repos this maintainer may see and act on — correctly for self-host today and for hosted multi-tenancy tomorrow (#4877 Phase B).

Requirements

1. Session → identity → repo-set resolution using the existing authz helpers and tiers (verified-admin vs affiliation), per the spec's matrix; the chat UI only offers repos the session may ground on, and dispatch affordances only where the dispatch tier is met.
2. Alignment with Decouple "admin of a GitHub install" from "has a running container" #4927 (admin-of-install ≠ has-a-running-deployment): a maintainer whose repo has no live deployment gets a defined, useful state (the spec decides what), not an error.
3. Hosted-tenancy readiness: no global-singleton state introduced by the chat session layer (the Phase B multi-tenancy sweep must not have to undo this feature); session context flows explicitly.
4. Session expiry/revocation mid-conversation degrades cleanly: in-flight stream terminates with the explicit auth-terminal event; the transcript stays readable; re-auth resumes without data loss.
5. Operator tier (ADMIN_GITHUB_LOGINS) behavior per the spec — likely cross-repo grounding; whatever is decided is tested.

Deliverables

• Session/repo-resolution wiring for the chat surfaces + the degraded-state UI.
• Tests: per-tier repo-set resolution, cross-tenant denial, mid-stream expiry behavior, no-new-global-singletons check (structural/lint-level where feasible).

Expected outcome

The chat surface's answer to "who are you and what may you touch" is inherited entirely from the existing authz model, provably tenant-safe.

[linear-code]

JSO-6352

[JSONbored]

Correcting a reference before implementation starts, per this epic's "re-check the sub-issues against the decisions" deliverable.

Two of the three authz helpers named in #9187's requirement 3 do not exist: requireRepoMaintainer and requireSessionRepoAccess are not in the tree. What exists is:

• authenticateSessionToken — src/auth/security.ts
• verifyInstallationAdmin — src/orb/oauth.ts

The second is the one that matters for dispatch gating: it binds to the immutable account_id rather than the renameable/re-registerable login, which is the property that makes it safe to gate writes on.

Per the draft decision record on #9187: reads gate on authenticateSessionToken plus repo scope from the session's installation; dispatches additionally require verifyInstallationAdmin; affiliation-tier maintainers get read-only chat with no dispatch.

Flagging here so this issue is not implemented against an API that was never built.

[JSONbored]

Correction — I was wrong about the authz helpers

I claimed earlier in this thread that requireRepoMaintainer and requireSessionRepoAccess do not exist. That is false, and I am retracting it before it misdirects any implementation.

Both exist and are the live guards:

• requireSessionRepoAccess — src/api/routes.ts:6232, 16 call sites
• requireRepoMaintainer — src/api/routes.ts:6250, 26 call sites

My error was a too-narrow search: I grepped src/auth/ for exported require* functions. Both are module-local to src/api/routes.ts and therefore unexported, so nothing matched and I read absence-of-match as absence. Asserting non-existence from one failed grep was the mistake — the same class of error I flagged on #8639 earlier today.

The authorization model is documented in src/api/routes.ts above canSessionAccessPath, and it is more precise than what I wrote. Two independent axes, identity per-login and authority per-repo, with two maintainer tiers:

• Affiliation tier — owns/installed the repo, or authored a PR there with a maintainer association. Gates maintainer-data reads. This is requireSessionRepoAccess.
• Verified write/admin/maintain, resolved live via the installation. Additionally gates repo-visible settings writes and secret BYOK writes. This is requireRepoWriteAccess.
• requireRepoMaintainer is the per-repo maintainer guard used by the protected routes.
• Operators (ADMIN_GITHUB_LOGINS) and server-to-server tokens bypass per-repo scope by design.

What this changes in the recorded decision

The substance of item 3 stands — reads gate on repo-scoped session access, dispatches additionally require verified admin authority, affiliation tier stays read-only. But it should be implemented against the real helpers rather than the ones I named:

Purpose	Use
Grounding-tool reads	requireSessionRepoAccess / requireRepoMaintainer
Action dispatch (#9190)	requireRepoWriteAccess — the tier that already gates writes

verifyInstallationAdmin remains the live installation-admin check underneath, but the route-level guard to call is requireRepoWriteAccess, which is what every other write path here already uses. Inventing a parallel authz path for chat would be exactly the drift the authorization doc-comment exists to prevent.

Also worth noting for whoever implements: canSessionAccessPath is a coarse path allowlist that runs in global middleware before the handler. A new chat path must be added there and scoped by a per-route guard — the comment states plainly that a path added to the allowlist MUST be scoped by a guard in its handler.

[JSONbored]

Gardening pass note (Pass 3, strategic epic health check): this issue's blocker, #9187 (the maintainer/owner conversational-surface spec), has now formally closed. This thread already has substantive authz-mapping work in progress against the draft decision — confirming the tracking-level dependency has cleared too, nothing new about scope.