@preventive/triage 1.0.0-alpha.5 → 1.0.0-alpha.50

package/server-managed/request-timing.ts

@@ -0,0 +1,63 @@
+// Where a request's time goes, told back in its Server-Timing header, which
+// DevTools shows beside the request: the database's statements and the time
+// spent in its operations (sql.ts), new pooled connections and their
+// handshakes (db-neon.ts), GitHub's calls (github-app.ts githubJson), and
+// the whole, from the handler's start to its answer's head; an instance's
+// first request marked cold. Counts and durations alone, nothing of what was
+// asked; a streamed answer's head tells what was known as it was written.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import { ServerResponse } from 'node:http'
+
+interface Timing {
+  started: number
+  cold: boolean
+  statements: number
+  db: number; dbMs: number
+  conn: number; connMs: number
+  gh: number; ghMs: number
+}
+const requests = new AsyncLocalStorage<Timing>()
+let served = false
+
+// `work` timed, its response's head carrying what it spent where; a test's
+// stand-in for a response, not a ServerResponse, is left as it is.
+export function runTimed<T>(res: ServerResponse, work: () => T): T {
+  const timing: Timing = { started: performance.now(), cold: !served, statements: 0, db: 0, dbMs: 0, conn: 0, connMs: 0, gh: 0, ghMs: 0 }
+  served = true
+  if (res instanceof ServerResponse) {
+    const writeHead = res.writeHead
+    res.writeHead = function (this: ServerResponse, ...args: Parameters<ServerResponse['writeHead']>) {
+      if (!this.headersSent) this.setHeader('server-timing', header(timing))
+      return writeHead.apply(this, args)
+    } as ServerResponse['writeHead']
+  }
+  return requests.run(timing, work)
+}
+
+// `work`, its time counted as `kind`'s where a request is timed.
+export async function timed<T>(kind: 'db' | 'conn' | 'gh', work: () => Promise<T>): Promise<T> {
+  const timing = requests.getStore()
+  if (!timing) return work()
+  const start = performance.now()
+  try { return await work() } finally {
+    timing[kind]++
+    timing[`${kind}Ms`] += performance.now() - start
+  }
+}
+
+// A statement sent to the database, where a request is timed.
+export function countStatement(): void {
+  const timing = requests.getStore()
+  if (timing) timing.statements++
+}
+
+function header(timing: Timing): string {
+  const ms = (value: number) => value.toFixed(1)
+  return [
+    ...timing.db > 0 || timing.statements > 0 ? [`db;dur=${ms(timing.dbMs)};desc="${timing.statements} statements"`] : [],
+    ...timing.conn > 0 ? [`conn;dur=${ms(timing.connMs)}`] : [],
+    ...timing.gh > 0 ? [`gh;dur=${ms(timing.ghMs)};desc="${timing.gh} calls"`] : [],
+    ...timing.cold ? ['cold;desc="first request of this instance"'] : [],
+    `app;dur=${ms(performance.now() - timing.started)}`,
+  ].join(', ')
+}

package/server-managed/reviewed-dependencies.ts

@@ -0,0 +1,150 @@
+// The reviewed dependencies a host keeps beyond the app, as it registers
+// them before the server is assembled (server.ts registerReviewedDependencies):
+// an async method telling whether a dependency, as a lockfile locks it, is
+// reviewed there (`lookup`), and, optionally, one reading the reviews of
+// dependencies an open pull request's comments make (`parseComments`,
+// pull-comment-reviews.ts), and one formatting one's own dependency reviews
+// as a comment, for a copy button to give (`formatDependencyReviews`,
+// dependency-review-comments.ts). Registered, they replace the commit a repository
+// is reviewed since (pull-dependency-reviews.ts): a version passes by the
+// reviews its teams publish, and those its pull request's comments make, as
+// many as the repository requires, or by `lookup`'s saying so, and is
+// otherwise unreviewed. A patched version (pnpm's patchedDependencies)
+// passes by `lookup`, or reviews its comments make of its patch, alone, the
+// app reviewing no patch yet. Those comments' reviews count for the pull
+// request alone, as it is open: the host's to keep, as it is merged, among
+// those `lookup` tells of.
+//
+// Each version is asked of `lookup` once a request, as many at once as
+// ASK_AT_ONCE, its answer kept in this instance KEPT_MS; one it fails to
+// answer is unreviewed, and counted so (`unasked`).
+import { type Lru, lru } from './lru.ts'
+
+export type ReviewedLockfile = 'npm' | 'pnpm' | 'yarn1'
+// A dependency as a lockfile locks it: npm's always with its integrity (one
+// with none is never reviewed, nor asked of), its shasum where the lockfile
+// has one (Yarn 1's, after a tarball's `#`), and the hash of its patch where
+// it is patched (pnpm's).
+export interface ReviewedDependency {
+  ecosystem: 'npm'
+  lockfile: ReviewedLockfile
+  name: string
+  version: string
+  integrity?: string
+  shasum?: string
+  patchHash?: string
+}
+export type ReviewVerdict = 'accept' | 'accept-with-nits' | 'request-changes' | 'reject'
+// A comment of an open pull request's, as `parseComments` is given it: one
+// on the pull request (`comment`), a review's own (`review`, whatever its
+// state, a comment's alone too), or one on a line of its diff
+// (`review-comment`); by its author's GitHub login; when it was written, and
+// last edited (`editedAt`) where it was.
+export interface ReviewComment {
+  kind: 'comment' | 'review' | 'review-comment'
+  id: string
+  author: string | null
+  body: string
+  state?: string
+  createdAt: string
+  editedAt?: string
+  url: string
+}
+// What `parseComments` reads: the pull request, its comments, and the
+// dependencies: every one the lockfiles its review holds to add that can be
+// reviewed and `lookup` doesn't pass, and the others still wanting reviews.
+export interface ParseCommentsInput { repository: string; number: number; comments: ReviewComment[]; dependencies: ReviewedDependency[] }
+// A review its comments make, by `user` (a GitHub login, one of their
+// authors'), of each of `dependencies`, with its verdict, as of `time` (when
+// it was made, an ISO date or milliseconds; that user's latest comment's
+// where none is told).
+export interface CommentReview {
+  user: string
+  time?: string | number
+  dependencies: { ecosystem?: 'npm'; name: string; version: string; integrity: string; patchHash?: string; status: ReviewVerdict }[]
+}
+// A version a dependency review is of, or compared it with: its package's
+// name, its version, the integrity and, where npm tells one, the shasum of
+// its tarball, each held to the tarball reviewed, and its patch's hash where
+// it is known (pnpm's patched dependencies').
+export interface ReviewedVersion { name: string; version: string; integrity: string; shasum?: string; patchHash?: string }
+// One of one's own published dependency reviews, as `formatDependencyReviews`
+// is given it: the version it is of (`new`) and the one it compared it with
+// (`old`, none where it read its package whole); its verdict (`status`);
+// whether it read every file (`coverage`, `full`, else `partial`); its final
+// comment; each file's verdict and comment (`files`, of those with either);
+// by whom (`reviewer`, their GitHub login), and when it was published.
+export interface DependencyReviewEntry {
+  ecosystem: 'npm'
+  old: ReviewedVersion | null
+  new: ReviewedVersion
+  status: ReviewVerdict
+  coverage: 'full' | 'partial'
+  comment: string
+  files: { path: string; status: ReviewVerdict | null; comment: string }[]
+  reviewer: string
+  publishedAt: number
+}
+// What `formatDependencyReviews` formats: one's own reviews, never another's,
+// and the pull request whose versions they are of, where its copy asks.
+export interface FormatDependencyReviewsInput { reviews: DependencyReviewEntry[]; pullRequest?: { repository: string; number: number } }
+export interface ReviewedDependencies {
+  lookup(dependency: ReviewedDependency): Promise<boolean>
+  parseComments?(input: ParseCommentsInput): Promise<CommentReview[]>
+  // The comment to copy, none where it is empty, null or undefined.
+  formatDependencyReviews?(input: FormatDependencyReviewsInput): Promise<string | null | undefined>
+}
+
+const ASK_AT_ONCE = 16
+const KEPT_MS = 60_000
+
+let registered: ReviewedDependencies | null = null
+let assembled = false
+// Each lookup's answers, apart.
+const answers = new WeakMap<ReviewedDependencies['lookup'], Lru<{ at: number; reviewed: boolean }>>()
+
+// Registers the host's reviewed dependencies, once, before the server is
+// assembled (init()): a server already assembled keeps what it was given.
+export function registerReviewedDependencies(reviewed: ReviewedDependencies): void {
+  const optional = (method: unknown) => method === undefined || typeof method === 'function'
+  if (typeof reviewed?.lookup !== 'function' || !optional(reviewed.parseComments) || !optional(reviewed.formatDependencyReviews)) {
+    throw new TypeError('registerReviewedDependencies: expected { lookup, parseComments?, formatDependencyReviews? }, async methods')
+  }
+  if (assembled) throw new Error('registerReviewedDependencies: call it before init(), as the server takes them as it is assembled')
+  if (registered) throw new Error('registerReviewedDependencies: reviewed dependencies are registered already')
+  registered = { lookup: reviewed.lookup.bind(reviewed), ...reviewed.parseComments ? { parseComments: reviewed.parseComments.bind(reviewed) } : {},
+    ...reviewed.formatDependencyReviews ? { formatDependencyReviews: reviewed.formatDependencyReviews.bind(reviewed) } : {} }
+}
+
+// The reviewed dependencies registered, as a server takes them once it is
+// assembled; none registers after.
+export function assembledReviewedDependencies(): ReviewedDependencies | null {
+  assembled = true
+  return registered
+}
+
+// Which of `dependencies`, by their keys, `lookup` passes, and how many it
+// failed to answer.
+export async function askReviewed(lookup: ReviewedDependencies['lookup'], dependencies: Map<string, ReviewedDependency>): Promise<{ passed: Set<string>; unasked: number }> {
+  const passed = new Set<string>()
+  let unasked = 0
+  const pending = [...dependencies]
+  const kept = answers.get(lookup) ?? answers.set(lookup, lru(100_000)).get(lookup)!
+  await Promise.all(Array.from({ length: Math.min(ASK_AT_ONCE, pending.length) }, async () => {
+    for (let next = pending.pop(); next; next = pending.pop()) {
+      const [key, dependency] = next
+      const known = kept.get(key)
+      let answer = known && Date.now() - known.at < KEPT_MS ? known.reviewed : null
+      if (answer === null) {
+        try { answer = await lookup({ ...dependency }) === true } catch (error) {
+          unasked++
+          console.warn('reviewed dependencies: failed to answer', `${dependency.name}@${dependency.version}`, error instanceof Error ? error.message : error)
+          continue
+        }
+        kept.set(key, { at: Date.now(), reviewed: answer })
+      }
+      if (answer) passed.add(key)
+    }
+  }))
+  return { passed, unasked }
+}

package/server-managed/revisions.ts

@@ -0,0 +1,35 @@
+// Internal invalidation counters. Never expose these global values to clients:
+// feeds still publish only the existing user/visibility-scoped revisions.
+const catalogTables = ['managed_link_report', 'managed_team', 'managed_team_user', 'managed_team_repo', 'managed_report', 'managed_bundle', 'managed_selected_repo']
+const annotationTables = ['managed_finding_triage', 'managed_finding_triage_event', 'managed_finding_comment', 'managed_finding_issue']
+export function revisionSchema(postgres = false): string {
+  let sql = `CREATE TABLE IF NOT EXISTS managed_maintenance_lease (
+    id INTEGER PRIMARY KEY, owner TEXT NOT NULL, expires_at INTEGER NOT NULL
+  ); CREATE TABLE IF NOT EXISTS managed_change_revision (
+    id INTEGER PRIMARY KEY, catalog INTEGER NOT NULL, annotations INTEGER NOT NULL
+  ); INSERT INTO managed_change_revision VALUES (1, 0, 0) ON CONFLICT(id) DO NOTHING;`
+  for (const [column, tables] of [['catalog', catalogTables], ['annotations', annotationTables]] as const) {
+    const update = `UPDATE managed_change_revision SET ${column} = ${column} + 1 WHERE id = 1;`
+    if (postgres) {
+      sql += `CREATE OR REPLACE FUNCTION managed_${column}_changed() RETURNS trigger LANGUAGE plpgsql AS $$
+        BEGIN IF EXISTS (SELECT 1 FROM managed_revision_rows) THEN ${update} END IF; RETURN NULL; END $$;`
+    }
+    for (const table of tables) {
+      if (postgres) {
+        sql += `DROP TRIGGER IF EXISTS ${table}_revision ON ${table};`
+        for (const event of ['INSERT', 'UPDATE', 'DELETE']) {
+          sql += `DROP TRIGGER IF EXISTS ${table}_revision_${event} ON ${table};
+            CREATE TRIGGER ${table}_revision_${event} AFTER ${event} ON ${table}
+            REFERENCING ${event === 'DELETE' ? 'OLD' : 'NEW'} TABLE AS managed_revision_rows
+            FOR EACH STATEMENT EXECUTE FUNCTION managed_${column}_changed();`
+        }
+      } else {
+        for (const event of ['INSERT', 'UPDATE', 'DELETE']) {
+          sql += `CREATE TRIGGER IF NOT EXISTS ${table}_revision_${event}
+            AFTER ${event} ON ${table} BEGIN ${update} END;`
+        }
+      }
+    }
+  }
+  return sql
+}

package/server-managed/scan-downloads.ts

@@ -0,0 +1,87 @@
+// A scan's packages' downloads, as risk asks them, readied before the
+// packages are assessed (repository-risk.ts), so that no assessment waits on
+// npm's downloads API, which answers some 40 lookups a minute: a package is
+// given to the assessors once its downloads are kept (npm-risk.ts
+// npmReadyScanDownloads), those that can be readied at once (kept already,
+// and unscoped ones, asked in bulk) first, each lockfile's as it is read, and
+// the rest (scoped ones, which npm answers only one by one) one at a time,
+// at the pace npm allows, while the assessors go on with the others.
+import { setTimeout as delay } from 'node:timers/promises'
+import { type Queue, queue } from './queue.ts'
+
+export interface DownloadsSource {
+  // Readies those of `names` that can be at once, `ready` told each.
+  atOnce(names: string[], ready: (name: string) => void, signal: AbortSignal): Promise<void>
+  // Readies one on its own.
+  one(name: string, signal: AbortSignal): Promise<void>
+}
+
+// How npm asking to be asked later is told (`busy`), and waited on: asked
+// again after a wait, up to `retries` times running.
+export interface DownloadsPacing { busy(error: unknown): boolean; retries: number; waitMs: number }
+
+export interface ReadyingDownloads<T> {
+  // Packages to give once their downloads are ready.
+  add(items: T[]): void
+  // Once all added are given, or the scan stops.
+  close(): Promise<void>
+}
+
+// Readies the downloads of the packages added, each given (`give`) once its
+// name's are, or once readying them fails otherwise than npm asking to wait,
+// or npm keeps asking past `retries`: its assessment then asks its own.
+export function readyingDownloads<T extends { name: string }>(source: DownloadsSource, signal: AbortSignal, give: (item: T) => void,
+  { busy, retries, waitMs }: DownloadsPacing): ReadyingDownloads<T> {
+  const waiting = new Map<string, T[]>()
+  const atOnce: Queue<string[]> = queue(signal), oneByOne: Queue<string> = queue(signal)
+  const release = (name: string) => { for (const item of waiting.get(name) ?? []) give(item); waiting.delete(name) }
+  const wait = async (attempt: number) => { try { await delay(waitMs * Math.min(attempt + 1, 5), undefined, { signal }); return true } catch { return false } }
+
+  // A lockfile's names, those that can be readied at once, again after a wait
+  // where npm asks: false once the scan stops.
+  const readyNow = async (names: string[]) => {
+    for (let attempt = 0; attempt <= retries; attempt++) {
+      const left = names.filter(name => waiting.has(name))
+      try { await source.atOnce(left, release, signal); return true } catch (error) {
+        if (signal.aborted) return false
+        if (!busy(error)) { for (const name of left) release(name); return true }
+        if (!await wait(attempt)) return false
+      }
+    }
+    return true
+  }
+  // Each lockfile's, the rest left to oneByOne.
+  const readyAtOnce = async () => {
+    for (let names = await atOnce.take(); names !== undefined; names = await atOnce.take()) {
+      if (!await readyNow(names)) return
+      for (const name of names) if (waiting.has(name)) oneByOne.add(name)
+    }
+  }
+  const readyOneByOne = async () => {
+    for (let name = await oneByOne.take(); name !== undefined; name = await oneByOne.take()) {
+      for (let attempt = 0; attempt <= retries; attempt++) {
+        try { await source.one(name, signal); break } catch (error) {
+          if (signal.aborted) return
+          if (!busy(error) || !await wait(attempt)) break
+        }
+      }
+      release(name)
+    }
+  }
+  const lanes = [readyAtOnce().finally(() => { oneByOne.close() }), readyOneByOne()]
+  return {
+    add(items) {
+      const names: string[] = []
+      for (const item of items) {
+        const kept = waiting.get(item.name)
+        if (kept) kept.push(item)
+        else { waiting.set(item.name, [item]); names.push(item.name) }
+      }
+      if (names.length > 0) atOnce.add(names)
+    },
+    async close() {
+      atOnce.close()
+      await Promise.all(lanes)
+    },
+  }
+}

package/server-managed/session.ts

@@ -0,0 +1,132 @@
+// Session + cookie plumbing for the managed auth server. The raw session
+// token lives ONLY in the cookie; the DB row id is its SHA-256 (see crypto.ts)
+// so a DB read can't reconstruct a live cookie. A double-submit CSRF token is
+// minted per session and returned to the client (echoed back on mutations).
+//
+// Async throughout — the store (db.ts) is async so a future non-SQLite
+// backend slots in without touching these helpers.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedSession, ManagedUser, StoredUser } from './db.ts'
+import { hashToken, randomToken } from './crypto.ts'
+
+// Base name for the short-lived OAuth-state cookie; `__Host-` is prefixed via
+// `cookieName` when cookies are Secure.
+export const STATE_COOKIE = 'dvstate'
+
+// Base names for GitHub issue authorization state (github-issue-oauth.ts),
+// linking another GitHub account (github-link-oauth.ts) and an
+// administrator's read-only view as another user (view-as.ts).
+export const ISSUE_STATE_COOKIE = 'dvissuestate'
+export const LINK_STATE_COOKIE = 'dvlinkstate'
+export const VIEW_COOKIE = 'dvview'
+// The session cookie cannot share a name with these, or one would overwrite
+// or be read as the other.
+export const RESERVED_COOKIES: readonly string[] = [STATE_COOKIE, ISSUE_STATE_COOKIE, LINK_STATE_COOKIE, VIEW_COOKIE]
+
+// `__Host-`-prefix the base name when cookies are Secure (the prefix mandates
+// Secure + Path=/ + no Domain, which `buildCookie` already emits).
+export function cookieName(config: ManagedConfig, base: string): string {
+  return config.cookieSecure ? `__Host-${base}` : base
+}
+
+export function buildCookie(
+  name: string, value: string,
+  opts: { maxAgeS: number; secure: boolean; sameSite?: 'Lax' | 'Strict' },
+): string {
+  const parts = [`${name}=${value}`, 'Path=/', 'HttpOnly', `SameSite=${opts.sameSite ?? 'Lax'}`, `Max-Age=${opts.maxAgeS}`]
+  if (opts.secure) parts.push('Secure')
+  return parts.join('; ')
+}
+
+// Expire a cookie now (Max-Age=0).
+export function clearCookie(name: string, secure: boolean): string {
+  return buildCookie(name, '', { maxAgeS: 0, secure })
+}
+
+export function parseCookies(header: string | undefined): Map<string, string> {
+  const out = new Map<string, string>()
+  if (!header) return out
+  for (const part of header.split(';')) {
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const k = part.slice(0, eq).trim()
+    if (k) out.set(k, part.slice(eq + 1).trim())
+  }
+  return out
+}
+
+// Mint a session for a freshly-authenticated user. Upserts the identity, then
+// stores the session keyed by the cookie token's hash. Returns the cookie to
+// set and the CSRF token (also persisted on the row), or null for an account
+// a user linked to theirs, which can neither sign in nor register.
+export async function createSession(
+  config: ManagedConfig, db: ManagedDb, user: ManagedUser, now: number,
+): Promise<{ setCookie: string; csrfToken: string; userId: string } | null> {
+  const token = randomToken()
+  const csrfToken = randomToken()
+  const userId = await db.upsertUser(user, now, config.initialAdminGithubId)
+  if (userId == null) return null
+  await db.createSession({ id: hashToken(token), userId, csrfToken, expiresAt: now + config.sessionTtlMs }, now)
+  const setCookie = buildCookie(config.sessionCookieName, token, {
+    maxAgeS: Math.floor(config.sessionTtlMs / 1000), secure: config.cookieSecure, sameSite: 'Lax',
+  })
+  return { setCookie, csrfToken, userId }
+}
+
+// A request's sign-in, whose presence its first read to find it records.
+// Every read after it in that request (the rechecks after its reads of
+// storage, GitHub or npm among them) only reads: last_seen_at was written a
+// moment before, by the read that let the request in. What the router's
+// gate read is handed to the read after it that says nothing was read
+// between them (`handed`), asking nothing again; once only, and to none
+// once another read came first.
+type SessionRead = { session: ManagedSession; user: StoredUser }
+const requests = new AsyncLocalStorage<{ seen: boolean; handed: { cookieHeader: string | undefined; read: SessionRead } | null }>()
+export function runRequestPresence<T>(work: () => T): T {
+  return requests.run({ seen: false, handed: null }, work)
+}
+export function handOverSession(cookieHeader: string | undefined, read: SessionRead): void {
+  const request = requests.getStore()
+  if (request) request.handed = { cookieHeader, read }
+}
+
+// Resolve the current session (+ user) from the request's cookies, or null.
+// A view cookie resolves only to that admin's view as another user: a view
+// that has ended never falls back to the admin's own session. `own` skips the
+// view and reads the signed-in session itself. `handed` takes the gate's
+// read, where it is this read's first since (handOverSession).
+export async function readSession(
+  config: ManagedConfig, db: ManagedDb, cookieHeader: string | undefined, now: number, { own = false, handed = false } = {},
+): Promise<SessionRead | null> {
+  const request = requests.getStore()
+  const given = request?.handed
+  if (request) request.handed = null
+  if (handed && !own && given && given.cookieHeader === cookieHeader) return given.read
+  const ids = sessionIds(config, cookieHeader, { own })
+  if (!ids) return null
+  const seen = request?.seen === true
+  const s = ids.viewer === null
+    ? await (seen ? db.getSessionWithUser : db.sessionWithUser)(ids.id, now)
+    : await (seen ? db.getViewSessionWithUser : db.viewSessionWithUser)(ids.id, ids.viewer, now)
+  if (s && request) request.seen = true
+  return s
+}
+
+// The sessions the request's cookies name, as readSession reads them: the
+// one acting (`id`), a view where an admin views as another user, with the
+// admin's own it is a view of (`viewer`); none signed out.
+export function sessionIds(config: ManagedConfig, cookieHeader: string | undefined, { own = false } = {}): { id: string; viewer: string | null } | null {
+  const cookies = parseCookies(cookieHeader)
+  const token = cookies.get(config.sessionCookieName)
+  if (token == null || token === '') return null
+  const view = own ? undefined : cookies.get(cookieName(config, VIEW_COOKIE))
+  return view != null && view !== '' ? { id: hashToken(view), viewer: hashToken(token) } : { id: hashToken(token), viewer: null }
+}
+
+// Drop the session named by the request's cookie (logout). The caller also
+// clears the cookie client-side.
+export async function endSession(config: ManagedConfig, db: ManagedDb, cookieHeader: string | undefined): Promise<void> {
+  const token = parseCookies(cookieHeader).get(config.sessionCookieName)
+  if (token != null && token !== '') await db.deleteSession(hashToken(token))
+}

package/server-managed/slugs.ts

@@ -0,0 +1,38 @@
+import type { DatabaseSync } from 'node:sqlite'
+
+// Legacy non-UUID IDs stay intact. Production IDs are UUIDs; only their final
+// component is proposed as a slug, never an arbitrary prefix or abbreviation.
+export function preferredSlug(id: string): string {
+  return /^[a-f\d]{8}(?:-[a-f\d]{4}){3}-([a-f\d]{12})$/iu.exec(id)?.[1] ?? id
+}
+
+export function allocateMissingSlugs(rows: { id: string; slug: string | null }[]): { id: string; slug: string }[] {
+  // Reserve legacy IDs before UUID suffixes can claim them.
+  const used = new Set(rows.flatMap(row => row.slug == null ? [row.id] : [row.id, row.slug]))
+  const allocated = []
+  for (const row of rows) {
+    if (row.slug != null) continue
+    const candidate = preferredSlug(row.id)
+    const slug = used.has(candidate) ? row.id : candidate
+    allocated.push({ id: row.id, slug })
+    used.add(slug)
+  }
+  return allocated
+}
+
+// Allocate once, across the entire namespace rather than a viewer's teams.
+// Keep existing slugs stable when names, memberships, or collisions change.
+export function migrateSlugs(db: DatabaseSync): void {
+  db.exec('BEGIN IMMEDIATE')
+  try {
+    for (const table of ['managed_team', 'managed_report', 'managed_bundle']) {
+      const columns = db.prepare(`PRAGMA table_info(${table})`).all() as { name: string }[]
+      if (!columns.some(column => column.name === 'slug')) db.exec(`ALTER TABLE ${table} ADD COLUMN slug TEXT`)
+      const rows = db.prepare(`SELECT id, slug FROM ${table} ORDER BY id`).all() as { id: string; slug: string | null }[]
+      const update = db.prepare(`UPDATE ${table} SET slug = ? WHERE id = ?`)
+      for (const row of allocateMissingSlugs(rows)) update.run(row.slug, row.id)
+      db.exec(`CREATE UNIQUE INDEX IF NOT EXISTS ${table}_slug_idx ON ${table}(slug)`)
+    }
+    db.exec('COMMIT')
+  } catch (err) { db.exec('ROLLBACK'); throw err }
+}

package/server-managed/solidity-entry-points.ts

@@ -0,0 +1,71 @@
+import { normalizeTeamPath } from './repo-path.ts'
+
+const MAX_SUGGESTIONS = 100
+const EXCLUDED_DIRECTORIES = new Set(['test', 'tests', 'script', 'scripts', 'mock', 'mocks', 'node_modules', 'vendor', 'out', 'artifacts', 'cache', 'build', 'dist', 'broadcast'])
+
+function sourcePath(value: unknown): value is string {
+  if (typeof value !== 'string' || !value.endsWith('.sol') || /\.(?:t|s|test|spec)\.sol$/iu.test(value)) return false
+  const normalized = normalizeTeamPath(value)
+  const directories = value.split('/').slice(0, -1).map(part => part.toLowerCase())
+  const sourceRoot = directories.findIndex(part => part === 'src' || part === 'contracts')
+  return normalized.ok && normalized.path === value && !directories.some((part, index) =>
+    EXCLUDED_DIRECTORIES.has(part) || (part === 'lib' && (sourceRoot < 0 || index < sourceRoot)))
+}
+
+type ListingEntry = { name?: unknown; path?: unknown; type?: unknown; sha?: unknown; submodule_git_url?: unknown }
+
+// Maintain the alphabetically first 100 unique candidates even when GitHub's
+// input is unordered. Return whether a unique candidate exceeds the capacity.
+export function addSoliditySuggestion(paths: string[], path: string): boolean {
+  let start = 0
+  let end = paths.length
+  while (start < end) {
+    const middle = Math.floor((start + end) / 2)
+    if (paths[middle]! < path) start = middle + 1
+    else end = middle
+  }
+  if (paths[start] === path) return false
+  const full = paths.length === MAX_SUGGESTIONS
+  if (start < MAX_SUGGESTIONS) {
+    // Evict before inserting, so retained candidates never exceed the cap.
+    if (full) paths.pop()
+    paths.splice(start, 0, path)
+  }
+  return full
+}
+
+// Suggestions from filenames, not deployability or import analysis. Read at
+// most two source trees, using SHAs from the authorized pinned directory.
+export async function readSolidityEntryPoints(directory: string, listing: unknown[], read: (suffix: string) => Promise<unknown>) {
+  const prefix = directory ? directory + '/' : ''
+  const entries = listing.filter((entry): entry is ListingEntry => !!entry && typeof entry === 'object').filter(entry =>
+    typeof entry.name === 'string' && !entry.name.includes('/') && entry.path === prefix + entry.name && !entry.submodule_git_url)
+  const hasFramework = entries.some(entry => entry.type === 'file' && typeof entry.name === 'string'
+    && (entry.name === 'foundry.toml' || /^hardhat\.config\.(?:[cm]?js|ts)$/u.test(entry.name)))
+  const roots = entries.filter(entry => entry.type === 'dir' && (entry.name === 'contracts' || (hasFramework && entry.name === 'src'))
+    && typeof entry.sha === 'string' && /^[a-f\d]{40}$/iu.test(entry.sha)).slice(0, 2)
+  const paths: string[] = []
+  let limited = false
+  for (const entry of entries) {
+    if (entry.type === 'file' && sourcePath(entry.path) && addSoliditySuggestion(paths, entry.path)) limited = true
+  }
+  // Both roots' listings asked together, then read in order.
+  const listings = roots.map(root => Promise.resolve().then(() => (sourcePath(`${root.path}/Contract.sol`) ? read(`/git/trees/${root.sha}?recursive=1`) : null)))
+  for (const listed of listings) listed.catch(() => {})
+  for (const [i, root] of roots.entries()) {
+    try {
+      const data = await listings[i] as { tree?: unknown; truncated?: unknown } | null
+      if (!Array.isArray(data?.tree)) continue
+      limited ||= data.truncated === true
+      for (const entry of data.tree) {
+        if (entry?.type !== 'blob' || !['100644', '100755'].includes(entry.mode) || typeof entry.path !== 'string') continue
+        const path = `${root.path}/${entry.path}`
+        if (sourcePath(path) && addSoliditySuggestion(paths, path)) limited = true
+      }
+    } catch {
+      // Optional suggestions must not block browsing. The request handler
+      // rechecks GitHub access and local path grants after all reads.
+    }
+  }
+  return { paths, limited }
+}

package/server-managed/sql-postgres.ts

@@ -0,0 +1,34 @@
+// The small SQL dialect used by the shared store. Parameter values never pass
+// through these rewrites; only our own SQL does. Keep aliases case-sensitive.
+export function postgresSql(source: string): { sql: string; names: string[] } {
+  const names: string[] = []
+  let position = 0
+  let sql = source.replaceAll('json_each(:contexts)', 'jsonb_array_elements(:contexts::jsonb)')
+    .replaceAll("CAST(unixepoch('subsec') * 1000 AS INTEGER)", 'CAST(EXTRACT(EPOCH FROM clock_timestamp()) * 1000 AS BIGINT)')
+    .replaceAll(/json_extract\((\w+\.value), '\$\.(\w+)'\)/gu, "($1->>'$2')")
+    .replaceAll('json_each(?)', 'jsonb_array_elements_text(?::jsonb)')
+    .replaceAll('INSERT OR IGNORE INTO', 'INSERT INTO')
+    .replaceAll('CROSS JOIN', 'JOIN')
+    .replaceAll(/\binstr\(/gu, 'strpos(')
+    // Rows gathered as one JSON array value, NULL (not '[]') where none are.
+    .replaceAll(/\bjson_group_array\(/gu, 'json_agg(')
+    .replaceAll(/\bjson_object\(/gu, 'json_build_object(')
+  // Quoted literals (including ':') are never placeholders or identifiers.
+  sql = sql.split(/('(?:''|[^'])*')/u).map((part, i) => i % 2 ? part : part
+    .replaceAll(/\?|(?<!:):([a-zA-Z]\w*)/gu, (_match, name: string | undefined) => {
+      if (!name) return `$${++position}`
+      let index = names.indexOf(name)
+      if (index < 0) { index = names.length; names.push(name) }
+      return `$${index + 1}`
+    })
+    .replaceAll(/\b[a-z]+[A-Z]\w*\b/gu, name => `"${name}"`)
+  ).join('')
+  sql = sql.replaceAll(/(\$\d+) IS NULL/gu, '$1::text IS NULL')
+  if (source.includes('INSERT OR IGNORE')) sql += ' ON CONFLICT DO NOTHING'
+  return { sql, names }
+}
+
+export function postgresSchema(sql: string): string {
+  return sql.replaceAll(') STRICT;', ');').replaceAll(/\bINTEGER\b/gu, 'BIGINT')
+    .replaceAll(/seq\s+BIGINT PRIMARY KEY/gu, 'seq BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY')
+}