@preventive/triage 1.0.0-alpha.21 → 1.0.0-alpha.23

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@preventive/triage",
-  "version": "1.0.0-alpha.21",
+  "version": "1.0.0-alpha.23",
   "description": "Client & relay server for triaging of automated reports",
   "license": "MIT",
   "author": {
@@ -109,12 +109,16 @@
     "server-managed/db-table-names.ts",
     "server-managed/db.ts",
     "server-managed/github-app.ts",
+    "server-managed/github-errors.ts",
     "server-managed/github-metadata.ts",
+    "server-managed/github-issue-oauth.ts",
+    "server-managed/github-issues.ts",
     "server-managed/github-oauth.ts",
     "server-managed/github-pulls.ts",
     "server-managed/http-response.ts",
     "server-managed/http.ts",
     "server-managed/import-triage.ts",
+    "server-managed/managed-issues.ts",
     "server-managed/index.ts",
     "server-managed/public-workspace.ts",
     "server-managed/repo-path.ts",
@@ -122,6 +126,7 @@
     "server-managed/report-query.ts",
     "server-managed/report-response.ts",
     "server-managed/report-sources.ts",
+    "server-managed/repository-browser.ts",
     "server-managed/repository-discovery.ts",
     "server-managed/repository-policy.ts",
     "server-managed/session.ts",
@@ -172,12 +177,16 @@
     "common/bundle-reasons.js",
     "common/bundle-sources.d.ts",
     "common/bundle-sources.js",
+    "common/bundle-source-links.d.ts",
+    "common/bundle-source-links.js",
     "common/bundle-stats.js",
     "common/bundle-tabs.js",
     "common/code-language.js",
     "common/default-scan-models.ts",
     "common/finding-id.js",
     "common/github-pr.ts",
+    "common/github-issue-labels.js",
+    "common/github-issue-labels.d.ts",
     "common/managed/comments.ts",
     "common/managed/permissions.ts",
     "common/managed/report-content.ts",
@@ -200,6 +209,8 @@
     "out/client-managed-import.js",
     "out/client-sync.js",
     "out/graph.js",
+    "out/github-issue-authorized.html",
+    "out/github-issue-authorized.js",
     "out/icon-maskable.svg",
     "out/icon.svg",
     "out/index.html",

package/server-e2e/app.ts

@@ -348,7 +348,8 @@ async function assembleE2eApp(config: Config, rollback: AsyncDisposableStack) {
   // The sync protocol this build advertises — emitted as a `server-info` frame
   // right after the challenge on every connection. This is the e2e boot, so it
   // always advertises e2e.
-  const SERVER_INFO: ServerInfo = { mode: 'e2e', managed: null, ...(config.deepviewScanServer ? { deepviewScanServer: config.deepviewScanServer } : {}) }
+  const SERVER_INFO: ServerInfo = { mode: 'e2e', managed: null, ...(config.deepviewScanServer ? { deepviewScanServer: config.deepviewScanServer } : {}),
+    ...(config.githubNewIssueLabels ? { githubNewIssueLabels: config.githubNewIssueLabels } : {}) }
 
   // Shared per-connection dispatch surface. Both the WS plane
   // (installWsServer below) and the SSE+POST fallback (installSseServer

package/server-e2e/config.ts

@@ -28,6 +28,7 @@ export type Config = {
   password: string | null
   trustProxyEnv: string | undefined
   deepviewScanServer: string | null
+  githubNewIssueLabels?: string
 }
 
 // Parse + range-validate an integer env var, throwing a clear
@@ -207,5 +208,6 @@ export function loadConfig(): Config {
     debug, neonUrl, blobToken, tokenSecret, password,
     trustProxyEnv: env['TRUST_PROXY'],
     deepviewScanServer: configuredScanServer(env['DEEPVIEW_SCAN_SERVER']),
+    githubNewIssueLabels: env['GITHUB_NEW_ISSUE_LABELS'] ?? '',
   }
 }

package/server-managed/config.ts

@@ -1,10 +1,6 @@
-// Managed-server boot config, parsed once at startup and
-// failing fast on a missing / invalid required value — the same discipline as
-// server-e2e/config.ts. Auth (GitHub identity + sessions) is required. An
-// optional, SEPARATE GitHub App (id + private key + slug) enables PRIVATE repo
-// listing via installation tokens — kept distinct from the login App so its
-// Contents permission never lands on the login consent. The sync protocol is
-// not parsed here yet.
+// Managed-server boot config. GitHub user authorization establishes identity;
+// optional App installation credentials enable repository access. A single
+// GitHub App can provide both flows, with repository grants at installation.
 import { env } from 'node:process'
 import { databaseUrls } from '../server-common/database-config.ts'
 
@@ -35,21 +31,17 @@ export interface ManagedConfig {
   cookieSecure: boolean
   sessionCookieName: string
   sessionTtlMs: number
-  // Optional SEPARATE GitHub App for PRIVATE repository access — distinct from
-  // the login App above. It carries the Contents: Read permission (so its
-  // consent never touches login) and is read via installation tokens: the id +
-  // PEM private key mint them; the slug builds the "Connect a repository"
-  // install URL. id/key absent → private repos are off (public-only listing);
-  // slug absent → no install link.
+  // Optional installation credentials for the same GitHub App as login.
+  // Repository permissions are approved when connecting repositories.
   githubAppId: string | null
   githubAppPrivateKey: string | null
   githubAppSlug: string | null
+  githubNewIssueLabels?: string
   // Max accepted size (bytes) for an uploaded report on the "Manage reports"
   // page. Reports are findings dumps (JSON / markdown / CSV), small to a few MB.
   maxReportBytes: number
   // Max accepted size (bytes) for an uploaded bundle (sourcemap / stasis
-  // archive). Bundles run larger than reports, so a higher cap (default 100 MiB,
-  // matching the e2e objstore per-upload cap).
+  // archive). Bundles run larger than reports, so a higher cap (default 200 MiB).
   maxBundleBytes: number
   // How many triage-trail events to keep per finding (managed_finding_triage_event):
   // 0, the default, keeps everything — the trail is the record. An operator
@@ -130,8 +122,9 @@ export function loadManagedConfig({ combined = false } = {}): ManagedConfig {
     githubAppId: env['GITHUB_APP_ID'] ?? null,
     githubAppPrivateKey: normalizePem(env['GITHUB_APP_PRIVATE_KEY']),
     githubAppSlug: env['GITHUB_APP_SLUG'] ?? null,
+    githubNewIssueLabels: env['GITHUB_NEW_ISSUE_LABELS'] ?? '',
     maxReportBytes: intEnv('MAX_REPORT_BYTES', 10_485_760, 1, 104_857_600),
-    maxBundleBytes: intEnv('MAX_BUNDLE_BYTES', 104_857_600, 1, 1_073_741_824),
+    maxBundleBytes: intEnv('MAX_BUNDLE_BYTES', 209_715_200, 1, 1_073_741_824),
     triageHistoryLimit: intEnv('TRIAGE_HISTORY_LIMIT', 0, 0, 1_000_000_000),
   }
 }

package/server-managed/db-methods.ts

@@ -7,6 +7,7 @@ import { preferredSlug } from './slugs.ts'
 import { type CommentStore, commentMethods } from './comments.ts'
 import { type ActivityStore, activityMethods } from './activity.ts'
 import { type GithubMetadataStore, githubMetadataMethods } from './github-metadata.ts'
+import { type ManagedIssueStore, managedIssueMethods } from './managed-issues.ts'
 import { type ImportTriageStore, importTriageMethods } from './import-triage.ts'
 import type { ManagedSql } from './sql.ts'
 import { type WorkspaceShareStore, workspaceShareMethods } from './workspace-shares.ts'
@@ -280,6 +281,7 @@ export interface UserTeamReport {
   id: string
   slug: string
   filename: string
+  analyzer: string | null
   repoFullName: string | null
   repoDirectory: string
   cacheKey: string
@@ -305,7 +307,7 @@ export interface UserTeam {
 }
 
 // Backend-agnostic store surface (SQLite + PostgreSQL implementations).
-export interface ManagedDb extends ActivityStore, CommentStore, GithubMetadataStore, WorkspaceShareStore, ImportTriageStore {
+export interface ManagedDb extends ActivityStore, CommentStore, GithubMetadataStore, ManagedIssueStore, WorkspaceShareStore, ImportTriageStore {
   // Upsert the identity; returns the user's opaque id (stable across logins).
   // Initial-admin approval comes only from trusted login configuration. It
   // promotes a matching No access identity only while it is the sole user.
@@ -325,6 +327,7 @@ export interface ManagedDb extends ActivityStore, CommentStore, GithubMetadataSt
   // mutable context while keeping the original added_by/added_at; deselectRepo
   // resolves true iff a row was removed.
   selectRepo(repo: SelectedRepoInput, now: number): Promise<void>
+  connectRepoInstallation(repo: SelectedRepo, installationId: number, sessionId: string, now: number): Promise<boolean>
   deselectRepo(repoId: number): Promise<boolean>
   listSelectedRepos(): Promise<SelectedRepo[]>
   listAllRepos(): Promise<ManagedRepo[]>
@@ -344,6 +347,10 @@ export interface ManagedDb extends ActivityStore, CommentStore, GithubMetadataSt
   // getReport reads one row (for download); deleteReport resolves true iff a row
   // was removed.
   insertReport(report: ReportRecordInput, now: number): Promise<void>
+  // Content reuse is atomic with insertion, including across server instances.
+  // Existing copies are kept; the oldest matching row is the stable identity.
+  insertOrReuseReport(report: ReportRecordInput, now: number): Promise<ReportRecord>
+  getReportByHash(sha256: string, analyzer: string | null): Promise<ReportRecord | null>
   listReports(userId?: string): Promise<AdminReport[]>
   getReport(id: string): Promise<ReportRecord | null>
   getTeamReportAccessSnapshot(sessionId: string, now: number, teamId: string): Promise<TeamReportAccessSnapshot | null>
@@ -504,6 +511,12 @@ function prepareStatements(db: ManagedSql) {
          installation_id = excluded.installation_id, default_branch = excluded.default_branch,
          html_url = excluded.html_url, updated_at = excluded.updated_at, active = 1`,
     ),
+    // Never reactivate or recreate a repo, overwrite another connection, or
+    // commit after the administrator's session/role was revoked during GitHub I/O.
+    connectRepoInstallationStmt: db.prepare(`UPDATE managed_selected_repo SET installation_id = ?, updated_at = ?
+      WHERE repo_id = ? AND full_name = ? AND added_at = ? AND installation_id IS NULL
+        AND EXISTS (SELECT 1 FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+          WHERE s.id = ? AND s.expires_at > ? AND u.role = 'admin')`),
     deleteRepoStmt: db.prepare(`DELETE FROM managed_selected_repo WHERE repo_id = ?`),
     deactivateRepoStmt: db.prepare(`UPDATE managed_selected_repo SET active = 0 WHERE repo_id = ? AND active = 1`),
     reactivateRepoStmt: db.prepare(`UPDATE managed_selected_repo SET active = 1 WHERE repo_id = ? AND active = 0`),
@@ -563,6 +576,10 @@ function prepareStatements(db: ManagedSql) {
               analyzer AS analyzer, visible AS visible, bundle_id AS bundleId
          FROM managed_report WHERE id = ?`,
     ),
+    selectReportByHashStmt: db.prepare(
+      `SELECT id FROM managed_report WHERE sha256 = ? AND COALESCE(analyzer, '') = COALESCE(?, '')
+       ORDER BY uploaded_at, id LIMIT 1`,
+    ),
     selectReportAccessStmt: db.prepare(
       `WITH requested AS (SELECT value AS id FROM json_each(?)), report_grants AS (
          SELECT r.id AS id, MAX(tu.view_dependencies) AS dependencies, MAX(tu.view_security) AS security
@@ -732,7 +749,7 @@ function prepareStatements(db: ManagedSql) {
     // Reports attached to the repos of the user's teams, tagged by team (a report
     // shows under every team whose repo it's attached to). Newest first.
     selectUserTeamReportsStmt: db.prepare(
-      `SELECT DISTINCT tr.team_id AS teamId, r.id AS id, r.slug AS slug, r.filename AS filename, r.uploaded_at,
+      `SELECT DISTINCT tr.team_id AS teamId, r.id AS id, r.slug AS slug, r.filename AS filename, r.analyzer, r.uploaded_at,
               r.sha256 AS sha256, r.bundle_id AS bundleId, r.repo_id AS repoId, r.repo_directory AS repoDirectory, sr.full_name AS repoFullName,
               tu.view_dependencies AS dependencies, tu.view_security AS security,
               (SELECT role FROM managed_user WHERE id = tu.user_id) AS role
@@ -837,6 +854,9 @@ function selectedRepoMethods(stmts: ReturnType<typeof prepareStatements>) {
     async deselectRepo(repoId: number): Promise<boolean> {
       return Number((await deleteRepoStmt.run(repoId)).changes) > 0
     },
+    async connectRepoInstallation(repo: SelectedRepo, installationId: number, sessionId: string, now: number): Promise<boolean> {
+      return Number((await stmts.connectRepoInstallationStmt.run(installationId, now, repo.repoId, repo.fullName, repo.addedAt, sessionId, now)).changes) > 0
+    },
     async listSelectedRepos(): Promise<SelectedRepo[]> {
       const rows = (await selectReposStmt.all()) as RepoRow[]
       return rows.map(readRepo)
@@ -888,14 +908,34 @@ type ReportRow = {
 // openSqliteManagedDb small. Closes over its prepared statements.
 function reportMethods(stmts: ReturnType<typeof prepareStatements>) {
   const { insertReportStmt, selectReportsStmt, selectReportStmt, deleteReportStmt, setReportRepoStmt, setReportVisibleStmt } = stmts
+  async function getReport(id: string): Promise<ReportRecord | null> {
+    const row = (await selectReportStmt.get(id)) as ReportRow | undefined
+    if (row == null) return null
+    return { ...row, repoEmbedded: row.repoEmbedded === 1, visible: row.visible === 1 }
+  }
+  async function getReportByHash(sha256: string, analyzer: string | null): Promise<ReportRecord | null> {
+    const row = await stmts.selectReportByHashStmt.get(sha256, analyzer) as { id: string } | undefined
+    return row ? getReport(row.id) : null
+  }
+  async function insertReport(report: ReportRecordInput, now: number): Promise<void> {
+    await insertReportStmt.run(
+      report.id, preferredSlug(report.id), report.filename, report.contentType, report.byteSize,
+      report.sha256, report.uploadedBy, report.uploadedByLogin ?? null, report.repoId,
+      report.repoDirectory ?? '', report.repoEmbedded ? 1 : 0, report.analyzer ?? null, report.visible == null ? 0 : report.visible ? 1 : 0, report.bundleId ?? null,
+      report.bundleIntegrity ?? null, now,
+    )
+  }
   return {
-    async insertReport(report: ReportRecordInput, now: number): Promise<void> {
-      await insertReportStmt.run(
-        report.id, preferredSlug(report.id), report.filename, report.contentType, report.byteSize,
-        report.sha256, report.uploadedBy, report.uploadedByLogin ?? null, report.repoId,
-        report.repoDirectory ?? '', report.repoEmbedded ? 1 : 0, report.analyzer ?? null, report.visible == null ? 0 : report.visible ? 1 : 0, report.bundleId ?? null,
-        report.bundleIntegrity ?? null, now,
-      )
+    insertReport,
+    getReport,
+    getReportByHash,
+    async insertOrReuseReport(report: ReportRecordInput, now: number): Promise<ReportRecord> {
+      // The driver holds its writer lock for this whole operation. Checking
+      // again here closes the race between the HTTP lookup and blob upload.
+      const existing = await getReportByHash(report.sha256, report.analyzer ?? null)
+      if (existing) return existing
+      await insertReport(report, now)
+      return (await getReport(report.id))!
     },
     async listReports(userId?: string): Promise<AdminReport[]> {
       const rows = (await selectReportsStmt.all(userId ?? null, userId ?? null, userId ?? null)) as ReportListRow[]
@@ -908,16 +948,6 @@ function reportMethods(stmts: ReturnType<typeof prepareStatements>) {
         uploadedAt: r.uploadedAt,
       }))
     },
-    async getReport(id: string): Promise<ReportRecord | null> {
-      const row = (await selectReportStmt.get(id)) as ReportRow | undefined
-      if (row == null) return null
-      return {
-        id: row.id, slug: row.slug, filename: row.filename, contentType: row.contentType, byteSize: row.byteSize,
-        sha256: row.sha256, uploadedBy: row.uploadedBy, uploadedAt: row.uploadedAt,
-        repoId: row.repoId, repoDirectory: row.repoDirectory, repoEmbedded: row.repoEmbedded === 1, analyzer: row.analyzer, visible: row.visible === 1,
-        bundleId: row.bundleId,
-      }
-    },
     async getTeamReportAccessSnapshot(sessionId: string, now: number, teamId: string): Promise<TeamReportAccessSnapshot | null> {
       const session = await stmts.selectSessionStmt.get(sessionId, now) as SessionRow | undefined
       if (!session) return null
@@ -1165,14 +1195,14 @@ function teamMethods( stmts: ReturnType<typeof prepareStatements>) {
       const scopes = await stmts.selectUserTeamScopesStmt.all(userId) as { teamId: string; repoId: number; path: string; fullName: string }[]
       const reportsByTeam = new Map<string, UserTeamReport[]>()
       for (const r of (await selectUserTeamReportsStmt.all(userId)) as {
-        teamId: string; id: string; slug: string; filename: string; sha256: string; bundleId: string | null; repoId: number
+        teamId: string; id: string; slug: string; filename: string; analyzer: string | null; sha256: string; bundleId: string | null; repoId: number
         repoDirectory: string; repoFullName: string | null; dependencies: number; security: number; role: string
       }[]) {
         const list = reportsByTeam.get(r.teamId) ?? []
         const cacheKey = createHash('sha256').update(JSON.stringify([
           r.sha256, r.bundleId, r.filename, r.repoId, r.repoDirectory, r.repoFullName, r.dependencies, r.security, r.role,
         ])).digest('base64url')
-        list.push({ id: r.id, slug: r.slug, filename: r.filename, repoFullName: r.repoFullName, repoDirectory: r.repoDirectory, cacheKey })
+        list.push({ id: r.id, slug: r.slug, filename: r.filename, analyzer: r.analyzer, repoFullName: r.repoFullName, repoDirectory: r.repoDirectory, cacheKey })
         reportsByTeam.set(r.teamId, list)
       }
       const bundlesByTeam = new Map<string, UserTeamBundle[]>()
@@ -1320,6 +1350,7 @@ export function createManagedMethods(db: ManagedSql, options: ManagedDbOptions =
       return row?.githubId ?? null
     },
     ...githubMetadataMethods(db),
+    ...managedIssueMethods(db),
     ...selectedRepoMethods(stmts),
     ...activity,
     ...comments,

package/server-managed/db-neon.ts

@@ -3,6 +3,7 @@ import { WebSocket } from 'ws'
 import { type ManagedDb, type ManagedDbOptions, createManagedMethods } from './db-methods.ts'
 import { MANAGED_SCHEMA } from './db-schema.ts'
 import { GITHUB_METADATA_SCHEMA, GITHUB_STATE_REASON_COLUMN } from './github-metadata.ts'
+import { MANAGED_ISSUE_SCHEMA } from './managed-issues.ts'
 import { COMMENT_SCHEMA } from './comments.ts'
 import { ACTIVITY_SCHEMA } from './activity.ts'
 import { type ManagedSqlDriver, scopeManagedMethods } from './sql.ts'
@@ -56,7 +57,7 @@ async function initialize(db: PgConnection): Promise<void> {
       await db.query(postgresSchema(WORKSPACE_SHARE_SCHEMA))
       await db.query('INSERT INTO managed_schema_version VALUES (4)')
     }
-    await db.query(postgresSchema(GITHUB_METADATA_SCHEMA))
+    await db.query(postgresSchema(GITHUB_METADATA_SCHEMA + MANAGED_ISSUE_SCHEMA))
     await db.query(`ALTER TABLE managed_github_metadata ADD COLUMN IF NOT EXISTS state_reason ${GITHUB_STATE_REASON_COLUMN}`)
     await db.query('ALTER TABLE managed_github_metadata ADD COLUMN IF NOT EXISTS attempted_at BIGINT')
     if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 5')).rows.length === 0) {
@@ -78,6 +79,10 @@ async function initialize(db: PgConnection): Promise<void> {
       await db.query("ALTER TABLE managed_bundle ADD COLUMN IF NOT EXISTS repo_directory TEXT NOT NULL DEFAULT ''")
       await db.query('INSERT INTO managed_schema_version VALUES (7)')
     }
+    if ((await db.query('SELECT version FROM managed_schema_version WHERE version = 8')).rows.length === 0) {
+      await db.query('CREATE INDEX IF NOT EXISTS managed_report_hash_idx ON managed_report(sha256, uploaded_at, id)')
+      await db.query('INSERT INTO managed_schema_version VALUES (8)')
+    }
     await db.query('COMMIT')
   } catch (err) {
     await db.query('ROLLBACK')

package/server-managed/db-schema.ts

@@ -108,6 +108,7 @@ CREATE TABLE IF NOT EXISTS managed_report (
 ) STRICT;
 
 CREATE INDEX IF NOT EXISTS managed_report_uploaded_at_idx ON managed_report(uploaded_at);
+CREATE INDEX IF NOT EXISTS managed_report_hash_idx ON managed_report(sha256, uploaded_at, id);
 CREATE INDEX IF NOT EXISTS managed_report_bundle_integrity_idx ON managed_report(bundle_integrity);
 CREATE INDEX IF NOT EXISTS managed_report_bundle_hash_idx ON managed_report(bundle_id, sha256);
 

package/server-managed/db.ts

@@ -8,6 +8,7 @@ import { initCommentMethods } from './comments.ts'
 import { initActivityMethods } from './activity.ts'
 import { MANAGED_SCHEMA } from './db-schema.ts'
 import { GITHUB_METADATA_SCHEMA, GITHUB_STATE_REASON_COLUMN } from './github-metadata.ts'
+import { MANAGED_ISSUE_SCHEMA } from './managed-issues.ts'
 import { managedTableRenames } from './db-table-names.ts'
 import { type ManagedDb, type ManagedDbOptions, createManagedMethods } from './db-methods.ts'
 import { createSqliteDriver, scopeManagedMethods } from './sql.ts'
@@ -64,7 +65,7 @@ export function openSqliteManagedDb(path: string, options: ManagedDbOptions = {}
     db.exec('PRAGMA synchronous = FULL;')
     db.exec('PRAGMA foreign_keys = ON;')
     migrateManagedTableNames(db)
-    db.exec(MANAGED_SCHEMA + GITHUB_METADATA_SCHEMA)
+    db.exec(MANAGED_SCHEMA + GITHUB_METADATA_SCHEMA + MANAGED_ISSUE_SCHEMA)
     ensureColumn(db, 'managed_github_metadata', 'state_reason', GITHUB_STATE_REASON_COLUMN)
     ensureColumn(db, 'managed_github_metadata', 'attempted_at', 'INTEGER')
     // Existing public links must opt in too; never preserve an implicit grant.

package/server-managed/github-app.ts

@@ -1,23 +1,32 @@
-// Repository listing for the "Manage repositories" page, READ-ONLY. Two sources,
-// merged + deduped by full name:
-//
-//   PUBLIC  — the logged-in user's own repos (GET /user/repos) read with their
-//             identity-only login token. No installation; the login App needs no
-//             repository permissions, so login never shows "Act on your behalf".
-//   PRIVATE — a SEPARATE GitHub App (Contents: Read) the user installs on the
-//             repos they want; read server-side via installation tokens. That
-//             App's Contents permission lives on IT, never on the login App, so
-//             login stays clean. "Connect a repository" installs it (installUrl).
-//
-// Archived repos are skipped. Nothing here writes.
+// Repository discovery uses the signed-in user token and App installation
+// tokens. Login and repository installation can use one GitHub App: user
+// authorization requests account permissions, installation grants repository
+// permissions. Discovery itself is read-only and skips archived repositories.
 import { Buffer } from 'node:buffer'
-import { createSign } from 'node:crypto'
+import { createHash, createSign } from 'node:crypto'
 import type { ManagedConfig } from './config.ts'
+import { GithubApiError, throwGithubResponseError } from './github-errors.ts'
+
+export { GithubApiError } from './github-errors.ts'
 
 const GITHUB_API = 'https://api.github.com'
 const API_VERSION = '2022-11-28'
 const USER_AGENT = 'deepview-triage'
 const PER_PAGE = 100
+const INSTALLATION_TOKEN_TTL_MS = 5 * 60_000
+const INSTALLATION_TOKEN_EXPIRY_MARGIN_MS = 60_000
+const MAX_INSTALLATION_TOKENS = 256
+interface InstallationTokenEntry { token: string | null; expiresAt: number; pending: Promise<string> | null }
+// Credentials only: visibility, user identities, and permissions are never
+// cached here. Bound memory per transport and separate App/key/install scopes.
+const installationTokens = new WeakMap<typeof fetch, Map<string, InstallationTokenEntry>>()
+
+function discardInstallationToken(token: string | null, fetchImpl: typeof fetch): void {
+  if (!token) return
+  const cache = installationTokens.get(fetchImpl)
+  if (!cache) return
+  for (const [key, entry] of cache) if (entry.token === token) cache.delete(key)
+}
 
 // One listed repository. Carries the context to read its contents later:
 // `installationId` mints an App installation token (Contents: Read) for a repo
@@ -33,18 +42,7 @@ export interface ConnectedRepo {
   installationId: number | null
 }
 
-// A failure carrying the HTTP status the router should surface. 401 passes
-// through so the user-token path can map it to "log in again".
-export class GithubApiError extends Error {
-  status: number
-  constructor(status: number, message: string) {
-    super(message)
-    this.name = 'GithubApiError'
-    this.status = status
-  }
-}
-
-// The separate repositories App is configured (id + private key present) →
+// App installation credentials are configured (id + private key present) →
 // private repos can be listed via its installation tokens.
 export function githubAppConfigured(config: ManagedConfig): boolean {
   return config.githubAppId != null && config.githubAppPrivateKey != null
@@ -70,7 +68,7 @@ export function mergeRepos(...lists: ConnectedRepo[][]): ConnectedRepo[] {
 // One GitHub API call returning parsed JSON, optionally Bearer-authed by a
 // user token, App JWT, or installation token. Network / non-2xx / malformed
 // fold into a GithubApiError (401 passes through for the caller to handle).
-async function githubJson(url: string, token: string | null, fetchImpl: typeof fetch, method: 'GET' | 'POST' = 'GET'): Promise<unknown> {
+export async function githubJson(url: string, token: string | null, fetchImpl: typeof fetch, method: 'GET' | 'POST' = 'GET'): Promise<unknown> {
   let res: Response
   try {
     res = await fetchImpl(url, {
@@ -83,9 +81,8 @@ async function githubJson(url: string, token: string | null, fetchImpl: typeof f
       },
     })
   } catch { throw new GithubApiError(502, 'github-unreachable') }
-  if (res.status === 401) throw new GithubApiError(401, 'github-unauthorized')
-  if (res.status === 404) throw new GithubApiError(404, 'github-not-found')
-  if (!res.ok) throw new GithubApiError(502, `github-status-${res.status}`)
+  if (res.status === 401) discardInstallationToken(token, fetchImpl)
+  if (!res.ok) await throwGithubResponseError(res)
   try { return await res.json() } catch { throw new GithubApiError(502, 'github-malformed') }
 }
 
@@ -156,7 +153,7 @@ export async function listUserRepos(accessToken: string, fetchImpl: typeof fetch
   return [...byName.values()].toSorted((a, b) => a.fullName.localeCompare(b.fullName))
 }
 
-// ── PRIVATE: the separate App's installations via installation tokens ──
+// ── PRIVATE: App installations via installation tokens ──
 
 function base64url(input: Buffer | string): string {
   return Buffer.from(input).toString('base64url')
@@ -188,13 +185,65 @@ async function listInstallationIds(jwt: string, fetchImpl: typeof fetch): Promis
   return ids
 }
 
-// Exchange the App JWT for a scoped installation access token (inherits the
-// App's Contents: Read).
-async function mintInstallationToken(jwt: string, installId: number, fetchImpl: typeof fetch): Promise<string> {
-  const body = await githubJson(`${GITHUB_API}/app/installations/${installId}/access_tokens`, jwt, fetchImpl, 'POST')
-  const token = (body as { token?: unknown }).token
-  if (typeof token !== 'string' || token === '') throw new GithubApiError(502, 'github-install-token-denied')
-  return token
+// Reuse installation credentials only in this process. Refresh well before
+// expiry and coalesce concurrent mints; failed or undated tokens are not cached.
+async function installationAccessToken(appId: string, privateKey: string, installId: number, fetchImpl: typeof fetch): Promise<string> {
+  let cache = installationTokens.get(fetchImpl)
+  if (!cache) { cache = new Map(); installationTokens.set(fetchImpl, cache) }
+  const now = Date.now()
+  for (const [key, entry] of cache) if (!entry.pending && entry.expiresAt <= now) cache.delete(key)
+  const key = JSON.stringify([appId, createHash('sha256').update(privateKey).digest('hex'), installId])
+  const cached = cache.get(key)
+  if (cached) {
+    cache.delete(key)
+    cache.set(key, cached)
+    if (cached.pending) return cached.pending
+    return cached.token!
+  }
+  const entry: InstallationTokenEntry = { token: null, expiresAt: 0, pending: null }
+  const pending = Promise.resolve().then(async () => {
+    try {
+      const jwt = appJwt(appId, privateKey)
+      const body = await githubJson(`${GITHUB_API}/app/installations/${installId}/access_tokens`, jwt, fetchImpl, 'POST') as { token?: unknown; expires_at?: unknown }
+      if (typeof body?.token !== 'string' || body.token === '') throw new GithubApiError(502, 'github-install-token-denied')
+      entry.token = body.token
+      const expiresAt = typeof body.expires_at === 'string' ? Date.parse(body.expires_at) : NaN
+      entry.expiresAt = Number.isFinite(expiresAt) ? Math.min(now + INSTALLATION_TOKEN_TTL_MS, expiresAt - INSTALLATION_TOKEN_EXPIRY_MARGIN_MS) : 0
+      if (entry.expiresAt <= Date.now() && cache.get(key) === entry) cache.delete(key)
+      return body.token
+    } catch (err) {
+      if (cache.get(key) === entry) cache.delete(key)
+      throw err
+    } finally { entry.pending = null }
+  })
+  entry.pending = pending
+  cache.set(key, entry)
+  if (cache.size > MAX_INSTALLATION_TOKENS) cache.delete(cache.keys().next().value!)
+  return await pending
+}
+
+// Resolve this exact repository with the App's identity, then confirm the
+// installation token reaches the same numeric repository. A missing grant is
+// actionable through installation; transport/auth/rate errors must stay errors.
+export async function repositoryInstallation(config: ManagedConfig, repoId: number, fullName: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<number | null> {
+  const { githubAppId, githubAppPrivateKey } = config
+  if (githubAppId == null || githubAppPrivateKey == null) throw new GithubApiError(503, 'github-app-not-configured')
+  if (publicRepositoryName(fullName) !== fullName) throw new GithubApiError(409, 'repo-identity-changed')
+  const path = fullName.split('/').map(encodeURIComponent).join('/')
+  const jwt = appJwt(githubAppId, githubAppPrivateKey)
+  let raw
+  try { raw = await githubJson(`${GITHUB_API}/repos/${path}/installation`, jwt, fetchImpl) } catch (err) {
+    if (err instanceof GithubApiError && err.status === 404) return null
+    throw err
+  }
+  const installation = raw as { id?: unknown; suspended_at?: unknown; permissions?: { contents?: unknown } } | null
+  const id = installation?.id
+  if (typeof id !== 'number' || !Number.isSafeInteger(id) || id <= 0) throw new GithubApiError(502, 'github-malformed')
+  if (installation?.suspended_at != null || !['read', 'write'].includes(String(installation?.permissions?.contents))) return null
+  const token = await installationAccessToken(githubAppId, githubAppPrivateKey, id, fetchImpl)
+  const repo = parseRepo(await githubJson(`${GITHUB_API}/repos/${path}`, token, fetchImpl), id)
+  if (repo == null || repo.id !== repoId || repo.fullName.toLowerCase() !== fullName.toLowerCase()) throw new GithubApiError(409, 'repo-identity-changed')
+  return id
 }
 
 // The `repositories` array of one /installation/repositories page → ConnectedRepo[],
@@ -232,7 +281,7 @@ export async function listInstalledRepos(config: ManagedConfig, fetchImpl: typeo
   if (githubAppId == null || githubAppPrivateKey == null) return []
   const jwt = appJwt(githubAppId, githubAppPrivateKey)
   const lists = await mapGithubRequests(await listInstallationIds(jwt, fetchImpl), async (id) => {
-    const token = await mintInstallationToken(jwt, id, fetchImpl)
+    const token = await installationAccessToken(githubAppId, githubAppPrivateKey, id, fetchImpl)
     return listInstallationRepos(token, id, fetchImpl)
   })
   return mergeRepos(...lists)
@@ -260,9 +309,25 @@ async function mapGithubRequests<T, U>(items: T[], work: (item: T) => Promise<U>
 // https://docs.github.com/en/rest/collaborators/collaborators#get-repository-permissions-for-a-user
 // Resolve the current login from /user so renamed handles cannot check someone
 // else's access. All repo paths come from GitHub's installation catalogue.
-export async function filterInstalledRepos(config: ManagedConfig, repositories: ConnectedRepo[], userToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo[]> {
+export async function githubUserIdentity(userToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<{ id: number; login: string }> {
   const identity = await githubJson(`${GITHUB_API}/user`, userToken, fetchImpl) as { id?: unknown; login?: unknown }
   if (typeof identity?.login !== 'string' || !identity.login || typeof identity.id !== 'number' || !Number.isSafeInteger(identity.id) || identity.id <= 0) throw new GithubApiError(502, 'github-malformed')
+  return { id: identity.id, login: identity.login }
+}
+
+export async function githubRepoReadPermission(fullName: string, token: string, identity: { id: number; login: string }, fetchImpl: typeof fetch = globalThis.fetch): Promise<boolean> {
+  const path = fullName.split('/').map(encodeURIComponent).join('/')
+  try {
+    const body = await githubJson(`${GITHUB_API}/repos/${path}/collaborators/${encodeURIComponent(identity.login)}/permission`, token, fetchImpl) as { permission?: unknown; user?: { id?: unknown } }
+    return body?.user?.id === identity.id && ['read', 'write', 'admin'].includes(String(body?.permission))
+  } catch (err) {
+    if (err instanceof GithubApiError && err.status === 404) return false
+    throw err // Never broaden access when GitHub cannot verify permission.
+  }
+}
+
+export async function filterInstalledRepos(config: ManagedConfig, repositories: ConnectedRepo[], userToken: string, fetchImpl: typeof fetch = globalThis.fetch): Promise<ConnectedRepo[]> {
+  const identity = await githubUserIdentity(userToken, fetchImpl)
   const tokens = new Map<number, Promise<string | null>>()
   const allowed = await mapGithubRequests(repositories, async (repo) => {
     // Internal repos may have private=false; missing visibility is not proof
@@ -276,26 +341,19 @@ export async function filterInstalledRepos(config: ManagedConfig, repositories:
     }
     const accessToken = await token
     if (!accessToken) return false
-    const path = repo.fullName.split('/').map(encodeURIComponent).join('/')
-    try {
-      const body = await githubJson(`${GITHUB_API}/repos/${path}/collaborators/${encodeURIComponent(identity.login as string)}/permission`, accessToken, fetchImpl) as { permission?: unknown; user?: { id?: unknown } }
-      return body?.user?.id === identity.id && ['read', 'write', 'admin'].includes(String(body?.permission))
-    } catch (err) {
-      if (err instanceof GithubApiError && err.status === 404) return false
-      throw err // Never broaden the list when GitHub cannot verify access.
-    }
+    return githubRepoReadPermission(repo.fullName, accessToken, identity, fetchImpl)
   })
   return repositories.filter((_, index) => allowed[index])
 }
 
-// Mint a token to READ a selected repo's contents: an installation token (the
+// Get a token to READ a selected repo's contents: an installation token (the
 // App's Contents: Read) when the repo was reached through an installation, or
 // null for a public repo readable unauthenticated. This is the whole point of
 // persisting `installationId` — the stored context is enough to read.
 export async function repoAccessToken(config: ManagedConfig, installationId: number | null, fetchImpl: typeof fetch = globalThis.fetch): Promise<string | null> {
   const { githubAppId, githubAppPrivateKey } = config
   if (installationId == null || githubAppId == null || githubAppPrivateKey == null) return null
-  return await mintInstallationToken(appJwt(githubAppId, githubAppPrivateKey), installationId, fetchImpl)
+  return await installationAccessToken(githubAppId, githubAppPrivateKey, installationId, fetchImpl)
 }
 
 // ── merged listing ──

package/server-managed/github-errors.ts

@@ -0,0 +1,28 @@
+// A failure carrying the HTTP status the router should surface. 401 passes
+// through so the user-token path can map it to "log in again".
+export class GithubApiError extends Error {
+  status: number
+  retryAfter: number | null
+  constructor(status: number, message: string, retryAfter: number | null = null) {
+    super(message)
+    this.name = 'GithubApiError'
+    this.status = status
+    this.retryAfter = retryAfter
+  }
+}
+
+export async function throwGithubResponseError(res: Response): Promise<never> {
+  if (res.status === 403 || res.status === 429) {
+    const body = await res.json().catch(() => null) as { message?: unknown } | null
+    if (res.status === 429 || res.headers.get('x-ratelimit-remaining') === '0' || res.headers.has('retry-after')
+      || (typeof body?.message === 'string' && /rate limit|abuse detection/iu.test(body.message))) {
+      const retry = Number(res.headers.get('retry-after'))
+      const reset = Number(res.headers.get('x-ratelimit-reset')) * 1000
+      const wait = Math.max(Number.isFinite(retry) ? retry : 0, Number.isFinite(reset) ? (reset - Date.now()) / 1000 : 0)
+      throw new GithubApiError(429, 'github-rate-limited', Math.max(60, Math.ceil(wait)))
+    }
+  }
+  if (res.status === 401) throw new GithubApiError(401, 'github-unauthorized')
+  if (res.status === 404) throw new GithubApiError(404, 'github-not-found')
+  throw new GithubApiError(502, `github-status-${res.status}`)
+}