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

package/server-managed/repository-squashes.ts

@@ -0,0 +1,168 @@
+// The pull requests squashed into a repository's commits, as the code
+// viewer's Commits tab draws them (repository-history.ts), each looked up
+// with GraphQL once and kept by its commit.
+import { linkNoreplyUsers } from './github-accounts.ts'
+import { type GraphqlError, githubGraphql } from './github-graphql.ts'
+import { COMMIT_FRAGMENT, type GraphCommit, type HistoryCommit, commitActors, graphCommit, inBatches, variablesOf } from './repository-history.ts'
+
+const SHA = /^[a-f\d]{40}$/u
+
+// A pull request squashed into a commit of the default branch's history
+// (`merge`): its number, the commit its head was at when merged (`head`,
+// GitHub's own of it, which a branch reused or pushed over since never
+// moves), and its own commits, the latest MAX_SQUASHED of them, `more`
+// where it had more. Drawn as the merge it was, its commits on a lane of
+// their own (repository-history.js).
+export interface SquashedPull { merge: string; number: number; head: string; commits: HistoryCommit[]; more: boolean }
+// The pull requests squashed into commits, kept by each commit (a merged pull
+// request's commits never change); null for a commit none was.
+export interface Squashes {
+  read(shas: string[]): Promise<Map<string, SquashedPull | null>>
+  write(sha: string, pull: SquashedPull | null): Promise<void>
+}
+
+// The pull requests merged as another read told them (http.ts pulseMerges,
+// the Pulse's agent-merges.ts agentMerges): each's merge commit, its number
+// where told (null where not), every one merged from `from` till `to` among
+// them; a commit committed within, as a squash's or a rebase's is as it is
+// merged, the merge commit of the one it names, or of none.
+export interface KnownMerges { numbers: ReadonlyMap<string, number | null>; from: number; to: number }
+// How far within `from` and `to` a commit is told by them, for the clocks
+// of a merge and its commit.
+const KNOWN_SKEW_MS = 5 * 60_000
+
+const MAX_SQUASHED = 100
+// Looked up of an answer's commits not yet kept, at most, the newest first;
+// in queries of as many commits, or pull requests (their commits' lines
+// counted, as a history's are), as many at once.
+export const MAX_SQUASH_LOOKUPS = 500
+const SQUASH_COMMITS = 100
+const SQUASH_PULLS = 5
+const SQUASH_PARALLEL = 4
+
+// The merged pull request that brought each commit in, `c<n>` the `n`th's.
+const mergedPullsQuery = (count: number) => `query($owner: String!, $name: String!, ${variablesOf('o', count, 'GitObjectID!')}) {
+  repository(owner: $owner, name: $name) {
+    ${Array.from({ length: count }, (_, at) => `c${at}: object(oid: $o${at}) { ... on Commit { associatedPullRequests(first: 1) { nodes { number mergeCommit { oid } } } } }`).join('\n    ')}
+  }
+}`
+// Each pull request's head when merged and its latest commits, `p<n>` the `n`th's.
+const squashedQuery = (count: number) => `query($owner: String!, $name: String!, ${variablesOf('n', count, 'Int!')}) {
+  repository(owner: $owner, name: $name) {
+    ${Array.from({ length: count }, (_, at) => `p${at}: pullRequest(number: $n${at}) { headRefOid commits(last: ${MAX_SQUASHED}) { totalCount nodes { commit { ...historyCommit } } } }`).join('\n    ')}
+  }
+}
+${COMMIT_FRAGMENT}`
+
+type MergedPulls = { repository?: Record<string, { associatedPullRequests?: { nodes?: ({ number?: unknown; mergeCommit?: { oid?: unknown } | null } | null)[] } } | null> | null }
+type SquashedPage = { repository?: Record<string, { headRefOid?: unknown; commits?: { totalCount?: unknown; nodes?: ({ commit?: GraphCommit | null } | null)[] } } | null> | null }
+
+// A pull request or commit GitHub has none of, as one deleted: its field null.
+const notFound = (error: GraphqlError) => error?.type === 'NOT_FOUND'
+
+// Each repository's lookup of squashed pull requests going on, by its full
+// name: one at a time, those asking meanwhile waiting on it, and their
+// commits it doesn't look up looked up once it is done.
+const lookingUp = new Map<string, Promise<void>>()
+
+// Whether `promise` settles within `ms`, waited on that long at most.
+const within = (promise: Promise<unknown>, ms: number) => ms === Number.POSITIVE_INFINITY ? promise
+  : new Promise<void>(resolve => {
+    const timer = setTimeout(resolve, ms)
+    void promise.finally(() => { clearTimeout(timer); resolve() })
+  })
+
+// The pull requests squashed into `commits`, a merged pull request's merge
+// commit of one parent, not one rebased (its commits copied onto the branch,
+// told by their subjects), kept by each commit (`squashes`), those not yet
+// kept looked up with GraphQL, as many as MAX_SQUASH_LOOKUPS an answer, each
+// kept as it is found (lookUpSquashes), of those merges another read told
+// (`known`), the pull request each was merged by not looked up. Answered
+// with those kept once the
+// repository's lookup is done, or `waitMs` on, that lookup going on behind:
+// `behind`, one this started, for the caller to keep alive, and `pending`
+// while one does. Another's lookup done within it, but not of all of these,
+// those it left are looked up as this one's, within what is left of it.
+export async function squashedPulls(fullName: string, token: string, commits: HistoryCommit[], squashes: Squashes,
+  waitMs = Number.POSITIVE_INFINITY, fetchImpl: typeof fetch = globalThis.fetch, known: KnownMerges | null = null)
+  : Promise<{ pulls: SquashedPull[]; pending: boolean; behind: Promise<void> | null }> {
+  const single = commits.filter(commit => commit.parents.length === 1)
+  const kept = await squashes.read(single.map(commit => commit.sha))
+  let unknown = single.filter(commit => !kept.has(commit.sha))
+  if (unknown.length === 0) return { pulls: single.flatMap(commit => kept.get(commit.sha) ?? []), pending: false, behind: null }
+  const listed = new Map(commits.map(commit => [commit.sha, commit]))
+  const deadline = Date.now() + waitMs
+  const found = new Map<string, SquashedPull | null>()
+  // Waited on, as long as is left, and those of `unknown` it kept found.
+  const settle = async (looking: Promise<void>) => {
+    await within(looking, Math.max(0, deadline - Date.now()))
+    for (const [sha, pull] of await squashes.read(unknown.map(commit => commit.sha))) found.set(sha, pull)
+    unknown = unknown.filter(commit => !found.has(commit.sha))
+  }
+  const another = lookingUp.get(fullName)
+  if (another) await settle(another)
+  let behind: Promise<void> | null = null
+  if (!another || (unknown.length > 0 && !lookingUp.has(fullName))) {
+    const lookup = lookUpSquashes(fullName, token, unknown.slice(0, MAX_SQUASH_LOOKUPS), listed, squashes, fetchImpl, known)
+    const done: Promise<void> = lookup.catch(() => {}).finally(() => { if (lookingUp.get(fullName) === done) lookingUp.delete(fullName) })
+    lookingUp.set(fullName, done)
+    behind = lookup
+    await settle(done)
+  }
+  return { pulls: single.flatMap(commit => kept.get(commit.sha) ?? found.get(commit.sha) ?? []), pending: lookingUp.has(fullName), behind }
+}
+
+// The pull requests squashed into `unknown`, of the commits `listed`, looked
+// up, each kept as it is found (squashedPulls); those committed when
+// `known` tells every merge, by it: a merge commit's pull request, by its
+// number, the rest none's.
+async function lookUpSquashes(fullName: string, token: string, unknown: HistoryCommit[], listed: Map<string, HistoryCommit>, squashes: Squashes,
+  fetchImpl: typeof fetch, known: KnownMerges | null) {
+  const [owner, name] = fullName.split('/') as [string, string]
+  const merged: { commit: HistoryCommit; number: number }[] = []
+  const asked: HistoryCommit[] = []
+  for (const commit of unknown) {
+    const told = known !== null && commit.committedAt !== null && commit.committedAt >= known.from + KNOWN_SKEW_MS && commit.committedAt <= known.to - KNOWN_SKEW_MS
+    const number = told ? known.numbers.get(commit.sha) : null
+    if (number === null) asked.push(commit)
+    else if (number === undefined) await squashes.write(commit.sha, null)
+    else merged.push({ commit, number })
+  }
+  await inBatches(asked, SQUASH_COMMITS, SQUASH_PARALLEL, async batch => {
+    const data = await githubGraphql(mergedPullsQuery(batch.length), { owner, name, ...Object.fromEntries(batch.map((commit, at) => [`o${at}`, commit.sha])) },
+      token, fetchImpl, notFound) as MergedPulls
+    for (const [at, commit] of batch.entries()) {
+      const node = data?.repository?.[`c${at}`]
+      if (!node) continue
+      const pull = node.associatedPullRequests?.nodes?.[0]
+      const number = pull?.mergeCommit?.oid === commit.sha && Number.isSafeInteger(pull.number) && (pull.number as number) > 0 ? pull.number as number : null
+      if (number === null) await squashes.write(commit.sha, null)
+      else merged.push({ commit, number })
+    }
+  })
+  await inBatches(merged, SQUASH_PULLS, SQUASH_PARALLEL, async batch => {
+    const data = await githubGraphql(squashedQuery(batch.length), { owner, name, ...Object.fromEntries(batch.map(({ number }, at) => [`n${at}`, number])) },
+      token, fetchImpl, notFound) as SquashedPage
+    await linkNoreplyUsers(Object.values(data?.repository ?? {}).flatMap(pull => (pull?.commits?.nodes ?? []).flatMap(item => commitActors(item?.commit))), token, fetchImpl)
+    for (const [at, { commit, number }] of batch.entries()) {
+      const node = data?.repository?.[`p${at}`]
+      if (!node) continue
+      const own = (node.commits?.nodes ?? []).flatMap(item => graphCommit(item?.commit) ?? [])
+      const head = typeof node.headRefOid === 'string' && SHA.test(node.headRefOid) ? node.headRefOid : own.at(-1)?.sha
+      // Fast-forwarded, its last commit the merge's own; or rebased, its
+      // commits, more than one, copied onto the branch: the merge and those
+      // below it on their first parents, by their subjects, its commits'
+      // (one squashed is told by its commit's title too, by default, and
+      // drawn as it was either way).
+      const below = [commit]
+      for (let next = listed.get(commit.parents[0] ?? ''); next && below.length < own.length; next = listed.get(next.parents[0] ?? '')) below.push(next)
+      const copies = own.toReversed().slice(0, below.length).every((item, step) => below[step]!.subject === item.subject)
+      // Its commits' copies as far as those listed go, but not all of them
+      // listed: told, and kept, once they are.
+      if (own.length > 1 && copies && below.length < own.length) continue
+      const rebased = own.length > 1 && copies
+      const squashed = head !== undefined && head !== commit.sha && own.length > 0 && !own.some(item => item.sha === commit.sha) && !rebased
+      await squashes.write(commit.sha, squashed ? { merge: commit.sha, number, head, commits: own, more: Number(node.commits?.totalCount) > own.length } : null)
+    }
+  })
+}

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,149 @@
+// 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's (pnpm's patchedDependencies)
+// reviews are of its patch, its teams' and its comments' alike. 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))
+}