@preventive/triage 1.0.0-alpha.37 → 1.0.0-alpha.38

package/server-managed/team-feed.ts

@@ -7,7 +7,7 @@ import type { WorkspaceShareFeedState } from './workspace-shares.ts'
 
 // Short database reads work across instances without pinning a Neon connection.
 // All polling belongs to the awaited request; nothing runs after it completes.
-export const TEAM_FEED_POLL_MS = 3_000
+const TEAM_FEED_POLL_MS = 3_000
 export const TEAM_FEED_LIFETIME_MS = 240_000 // below the configured Vercel 300s
 const HEARTBEAT_MS = 15_000
 

package/server-managed/team-npm-scopes.ts

@@ -0,0 +1,77 @@
+// npm scopes a team lists: its members, whatever their role, may read that
+// scope's private packages in the npm viewer (npm-packages.ts), as admins and
+// managers may read any. Hidden teams grant nothing, as for their content.
+import { MAX_TEAM_NPM_SCOPES, normalizeNpmScope } from '../common/managed/npm-packages.js'
+import { ManagedMutationError } from './management.ts'
+import type { ManagedSql } from './sql.ts'
+
+export const TEAM_NPM_SCOPE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_team_npm_scope (
+  team_id TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+  scope   TEXT NOT NULL,
+  PRIMARY KEY (team_id, scope)
+) STRICT;
+`
+
+export interface TeamNpmScopeStore {
+  // Every team's scopes, sorted, keyed by team id; teams without any are absent.
+  listTeamNpmScopes(): Promise<Record<string, string[]>>
+  // Replaces a team's scopes; admin only. Answers what changed, or null for no team.
+  setTeamNpmScopes(sessionId: string, teamId: string, scopes: unknown): Promise<{ added: string[]; removed: string[] } | null>
+  // The scopes a user's visible teams list.
+  listUserNpmScopes(userId: string): Promise<string[]>
+  // Whether any visible team lists the scope: whoever reads its packages,
+  // they are the instance's own, whose new releases aren't flagged (http.ts).
+  hasTeamNpmScope(scope: string): Promise<boolean>
+}
+
+// Each distinct scope, normalized; a list with one npm could not publish
+// under, or too many, is refused whole.
+export function parseTeamNpmScopes(input: unknown): string[] {
+  if (!Array.isArray(input)) throw new ManagedMutationError(400, 'bad-scopes')
+  const scopes = new Set<string>()
+  for (const value of input) {
+    const scope = normalizeNpmScope(value)
+    if (scope === null) throw new ManagedMutationError(400, 'bad-scope')
+    scopes.add(scope)
+  }
+  if (scopes.size > MAX_TEAM_NPM_SCOPES) throw new ManagedMutationError(400, 'too-many-scopes')
+  return [...scopes].toSorted()
+}
+
+export function teamNpmScopeMethods(db: ManagedSql): TeamNpmScopeStore {
+  return {
+    async listTeamNpmScopes() {
+      const rows = await db.prepare('SELECT team_id AS teamId, scope FROM managed_team_npm_scope ORDER BY team_id, scope').all() as { teamId: string; scope: string }[]
+      const result: Record<string, string[]> = {}
+      for (const { teamId, scope } of rows) (result[teamId] ??= []).push(scope)
+      return result
+    },
+    async setTeamNpmScopes(sessionId, teamId, input) {
+      const user = await db.prepare(`SELECT u.role FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+        WHERE s.id = ? AND s.expires_at > ?`).get(sessionId, Date.now()) as { role: string } | undefined
+      if (!user) throw new ManagedMutationError(401, 'unauthenticated')
+      if (user.role !== 'admin') throw new ManagedMutationError(403, 'forbidden')
+      const scopes = parseTeamNpmScopes(input)
+      if (!await db.prepare('SELECT id FROM managed_team WHERE id = ?').get(teamId)) return null
+      const current = (await db.prepare('SELECT scope FROM managed_team_npm_scope WHERE team_id = ?').all(teamId) as { scope: string }[]).map(row => row.scope)
+      const removed = current.filter(scope => !scopes.includes(scope)).toSorted()
+      const added = scopes.filter(scope => !current.includes(scope))
+      for (const scope of removed) await db.prepare('DELETE FROM managed_team_npm_scope WHERE team_id = ? AND scope = ?').run(teamId, scope)
+      for (const scope of added) await db.prepare('INSERT INTO managed_team_npm_scope (team_id, scope) VALUES (?, ?)').run(teamId, scope)
+      return { added, removed }
+    },
+    async listUserNpmScopes(userId) {
+      const rows = await db.prepare(`SELECT DISTINCT ns.scope FROM managed_team_user tu
+        JOIN managed_team t ON t.id = tu.team_id AND t.hidden = 0
+        JOIN managed_team_npm_scope ns ON ns.team_id = tu.team_id
+        WHERE tu.user_id = ? ORDER BY ns.scope`).all(userId) as { scope: string }[]
+      return rows.map(row => row.scope)
+    },
+    async hasTeamNpmScope(scope) {
+      return !!await db.prepare(`SELECT 1 AS listed FROM managed_team_npm_scope ns
+        JOIN managed_team t ON t.id = ns.team_id AND t.hidden = 0
+        WHERE ns.scope = ? LIMIT 1`).get(scope)
+    },
+  }
+}

package/server-managed/type-only-worker.js

@@ -0,0 +1,19 @@
+// Which of a comparison's pairs of files changed in types alone (type-only.ts),
+// as @preventive/compare's compareTrees stamps a change `typeOnly`, off the
+// server's event loop: each pair a tree of a file a side, a side not there
+// none, its paths as they are, which say what a file is. Two paths pair as one
+// change wherever compareTrees takes them for a rename at all; where it
+// doesn't, the pair is types only where each of its two changes is, as each
+// side holds types alone and neither keeps an `export {}`, which is what it
+// would stamp of them paired. `[true, false, ...]` by pair.
+import { parentPort, workerData } from 'node:worker_threads'
+import { compareTrees } from '@preventive/compare'
+
+const tree = file => (file ? [{ name: file.path, data: file.text }] : [])
+const answer = workerData.pairs.map(([from, to]) => {
+  const changes = compareTrees(tree(from), tree(to), { paths: 'keys', lines: false, renames: Number.MIN_VALUE })
+  return changes.length > 0 && changes.every(change => change.typeOnly === true)
+})
+// Node worker messages have no browser target origin.
+// oxlint-disable-next-line unicorn/require-post-message-target-origin
+parentPort.postMessage(answer)

package/server-managed/type-only.ts

@@ -0,0 +1,103 @@
+// Compare's changes to TypeScript declaration files in types alone (GET
+// /api/bundles/:id/type-only?other=, GET /api/npm/type-only): every file
+// that changed between a comparison's two sides, added and removed ones too,
+// paired as its viewer pairs them (rename-diff.ts comparedFiles), whose
+// change @preventive/compare's compareTrees stamps
+// `typeOnly` -- each side there a file named as a declaration file and
+// proven to hold types alone, so that it runs nothing (proveTypeOnly) --
+// and nothing else. Proven in a worker, off the event loop, a comparison at a
+// time per process, for at most a minute; told a line each, `{ path, hash,
+// otherPath, otherHash }`, a side not there null, which the viewer checks
+// name the files it shows. Access is the caller's to check.
+import { Worker } from 'node:worker_threads'
+import { type ComparedSide, PrettyError, type PrettyRequest } from './pretty-print.ts'
+import { comparedFiles } from './rename-diff.ts'
+
+// TypeScript files, by extension as the pretty-print cache reads them: none
+// other is asked about.
+const TYPESCRIPT = new Set(['ts', 'mts', 'cts'])
+// Comparisons proven at once per process, and those waiting their turn past
+// them, any more refused; the longest one may take, its wait included.
+const MAX_ACTIVE_PROOFS = 1
+const MAX_WAITING_PROOFS = 16
+const PROOF_TIMEOUT_MS = 60_000
+
+type File = PrettyRequest & { text: string }
+export interface TypeOnlyLine { path: string | null; hash: string | null; otherPath: string | null; otherHash: string | null }
+
+let active = 0
+const waiting: Array<() => void> = []
+
+async function turn(deadline: number): Promise<void> {
+  if (active < MAX_ACTIVE_PROOFS) { active++; return }
+  if (waiting.length >= MAX_WAITING_PROOFS) throw new PrettyError(429, 'proof-busy')
+  await new Promise<void>((resolve, reject) => {
+    const next = () => { clearTimeout(timer); resolve() }
+    const timer = setTimeout(() => {
+      waiting.splice(waiting.indexOf(next), 1)
+      reject(new PrettyError(504, 'proof-timeout'))
+    }, deadline - Date.now())
+    waiting.push(next)
+  })
+}
+function done() {
+  const next = waiting.shift()
+  if (next) next()
+  else active--
+}
+
+// Which of `pairs` compareTrees stamps types only, by index, in a worker
+// settled once it is gone; none where it fails, as no proof should.
+function proven(pairs: Array<[File | null, File | null]>, deadline: number): Promise<boolean[]> {
+  let worker: Worker
+  try {
+    worker = new Worker(new URL('./type-only-worker.js', import.meta.url), {
+      workerData: { pairs: pairs.map(sides => sides.map(file => file && { path: file.path, text: file.text })) },
+      // Node's type stripping, which the proof holds oxc's tree to, warns it is experimental.
+      execArgv: ['--disable-warning=ExperimentalWarning'], resourceLimits: { maxOldGenerationSizeMb: 1024 },
+    })
+  } catch (err) {
+    console.warn('managed: a type-only proof could not start:', err)
+    throw new PrettyError(503, 'unavailable')
+  }
+  return new Promise((resolve, reject) => {
+    let answer: boolean[] | null = null, failure = new PrettyError(422, 'unproven')
+    const timer = setTimeout(() => { failure = new PrettyError(504, 'proof-timeout'); void worker.terminate() }, deadline - Date.now())
+    worker.once('message', (told: unknown) => {
+      if (Array.isArray(told) && told.length === pairs.length && told.every(one => typeof one === 'boolean')) answer = told
+      void worker.terminate()
+    })
+    worker.once('error', err => { console.warn('managed: a type-only proof failed:', err) })
+    worker.once('exit', () => {
+      clearTimeout(timer)
+      if (answer) resolve(answer)
+      else reject(failure)
+    })
+  })
+}
+
+// The files that changed between a comparison's two sides in types alone,
+// as the viewer pairs them, a line each once all are proven, in path order.
+export function typeOnlyFiles([base, other]: readonly [ComparedSide, ComparedSide]): AsyncGenerator<TypeOnlyLine> {
+  const typescript = ({ files }: ComparedSide) => new Map(files.filter(file => TYPESCRIPT.has(file.extension)).map(file => [file.path, file]))
+  const [olds, news] = [typescript(base), typescript(other)]
+  const { changed, onlyBase, onlyOther } = comparedFiles([base, other])
+  // A side there not a TypeScript file this reads leaves its pair out; one not there is null.
+  const pairs = [...changed.map(({ path, basePath = path }) => [olds.get(basePath), news.get(path)]),
+    ...onlyBase.map(({ path, basePath = path }) => [olds.get(basePath), null]), ...onlyOther.map(({ path }) => [null, news.get(path)])]
+    .filter((sides): sides is [File | null, File | null] => sides.every(file => file !== undefined) && sides.some(file => file !== null) && sides[0]?.hash !== sides[1]?.hash)
+    .toSorted(([a, b], [c, d]) => {
+      const [x, y] = [(b ?? a)!.path, (d ?? c)!.path]
+      return x < y ? -1 : x > y ? 1 : 0
+    })
+  return (async function* () {
+    if (pairs.length === 0) return
+    const deadline = Date.now() + PROOF_TIMEOUT_MS
+    await turn(deadline)
+    let stamped
+    try { stamped = await proven(pairs, deadline) } finally { done() }
+    for (const [i, [from, to]] of pairs.entries()) {
+      if (stamped[i]) yield { path: from?.path ?? null, hash: from?.hash ?? null, otherPath: to?.path ?? null, otherHash: to?.hash ?? null }
+    }
+  })()
+}

package/server-managed/uploads.ts

@@ -2,13 +2,16 @@
 // authenticated session, destination and random upload ID. No bearer URL is
 // exposed; all reads/writes still pass the managed role/origin/CSRF gates.
 import { Buffer } from 'node:buffer'
-import { createHash } from 'node:crypto'
+import { createHash, generateKeyPairSync } from 'node:crypto'
 import type { IncomingMessage } from 'node:http'
 import type { BlobStore } from './blob-store.ts'
+import { maxSealedBytes, openUpload } from '../common/managed/upload-seal.ts'
 
 export const UPLOAD_CHUNK_BYTES = 3 * 1024 * 1024
 export const MAX_UPLOAD_BYTES = 1024 * 1024 * 1024
-const MAX_UPLOAD_PARTS = Math.ceil(MAX_UPLOAD_BYTES / UPLOAD_CHUNK_BYTES)
+// Staged parts may carry a sealed body, slightly larger than its content.
+const MAX_STAGED_BYTES = maxSealedBytes(MAX_UPLOAD_BYTES)
+const MAX_UPLOAD_PARTS = Math.ceil(MAX_STAGED_BYTES / UPLOAD_CHUNK_BYTES)
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/u
 export type UploadKind = 'reports' | 'bundles'
 
@@ -18,7 +21,7 @@ function partId(session: string, kind: UploadKind, id: string, index: number): s
 }
 
 export function validUploadPart(id: string, index: number, maxBytes: number): boolean {
-  return UUID.test(id) && Number.isSafeInteger(index) && index >= 0 && index < Math.ceil(Math.min(maxBytes, MAX_UPLOAD_BYTES) / UPLOAD_CHUNK_BYTES)
+  return UUID.test(id) && Number.isSafeInteger(index) && index >= 0 && index < Math.ceil(Math.min(maxSealedBytes(maxBytes), MAX_STAGED_BYTES) / UPLOAD_CHUNK_BYTES)
 }
 
 export function validUpload(id: string, count: number): boolean {
@@ -48,7 +51,7 @@ export async function readUpload(store: BlobStore, req: IncomingMessage, session
   if (typeof id !== 'string' || !validUpload(id, count)) throw new Error('bad-upload')
   try {
     if (!Number.isSafeInteger(size) || size <= 0 || count !== Math.ceil(size / UPLOAD_CHUNK_BYTES)) throw new Error('bad-upload')
-    if (size > maxBytes || size > MAX_UPLOAD_BYTES) throw new Error('too-large')
+    if (size > maxBytes || size > MAX_STAGED_BYTES) throw new Error('too-large')
     const parts: Buffer[] = []
     for (let index = 0; index < count; index++) {
       const bytes = await store.get(partId(session, kind, id, index))
@@ -63,3 +66,21 @@ export async function readUpload(store: BlobStore, req: IncomingMessage, session
     await deleteUpload(store, session, kind, id, count).catch(err => console.warn('managed: upload cleanup failed:', err))
   }
 }
+
+// A session's upload key pair, stored as its private JWK.
+export function newUploadKey(): string {
+  const { privateKey } = generateKeyPairSync('x25519')
+  const { kty, crv, x, d } = privateKey.export({ format: 'jwk' })
+  return JSON.stringify({ kty, crv, x, d })
+}
+
+// The raw public key (base64url) browsers seal this session's uploads to.
+export function uploadPublicKey(key: string): string {
+  return (JSON.parse(key) as { x: string }).x
+}
+
+export async function openSessionUpload(key: string | null | undefined, sealed: Buffer, maxBytes: number): Promise<Buffer> {
+  if (!key) throw new Error('bad-upload')
+  const bytes = await openUpload(new Uint8Array(sealed.buffer as ArrayBuffer, sealed.byteOffset, sealed.byteLength), JSON.parse(key) as JsonWebKey, maxBytes)
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength)
+}

package/server-managed/upstream-cache.ts

@@ -1,4 +1,10 @@
-import type { CacheStore } from '@preventive/upstream/advisories.js'
+import { Buffer } from 'node:buffer'
+import { constants } from 'node:fs'
+import { mkdir, open, rename, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { promisify } from 'node:util'
+import { gunzip, gzip } from 'node:zlib'
+import type { CacheStore, Package } from '@preventive/upstream/advisories.js'
 import type { ManagedSql } from './sql.ts'
 
 // Records @preventive/upstream would otherwise keep in its disk cache, shared
@@ -18,30 +24,55 @@ CREATE TABLE IF NOT EXISTS managed_upstream_cache (
 
 export interface UpstreamCacheStore {
   getUpstreamCacheEntry(key: string): Promise<string | null>
+  // Key → value for those of `keys` that are kept.
+  getUpstreamCacheEntries(keys: string[]): Promise<Map<string, string>>
   setUpstreamCacheEntry(key: string, value: string, cachedAt: number): Promise<void>
+  // Removes those under `prefix` (no LIKE wildcard in it) kept before `before`;
+  // how many.
+  deleteUpstreamCacheEntries(prefix: string, before: number): Promise<number>
 }
 
 export function upstreamCacheMethods(db: ManagedSql): UpstreamCacheStore {
   const get = db.prepare('SELECT value FROM managed_upstream_cache WHERE cache_key = ?')
+  const getMany = db.prepare('SELECT cache_key, value FROM managed_upstream_cache WHERE cache_key IN (SELECT value FROM json_each(?))')
   // A slower concurrent audit cannot replace a newer listing with an older one.
   const set = db.prepare(`INSERT INTO managed_upstream_cache (cache_key, value, cached_at) VALUES (?, ?, ?)
     ON CONFLICT (cache_key) DO UPDATE SET value = excluded.value, cached_at = excluded.cached_at
     WHERE managed_upstream_cache.cached_at <= excluded.cached_at`)
+  const remove = db.prepare('DELETE FROM managed_upstream_cache WHERE cache_key LIKE ? AND cached_at < ?')
   return {
     async getUpstreamCacheEntry(key) {
       const row = await get.get(key) as { value: string } | undefined
       return row?.value ?? null
     },
+    async getUpstreamCacheEntries(keys) {
+      if (keys.length === 0) return new Map()
+      const rows = await getMany.all(JSON.stringify(keys)) as { cache_key: string; value: string }[]
+      return new Map(rows.map(row => [row.cache_key, row.value]))
+    },
     async setUpstreamCacheEntry(key, value, cachedAt) {
       await set.run(key, value, cachedAt)
     },
+    async deleteUpstreamCacheEntries(prefix, before) {
+      return Number((await remove.run(`${prefix}%`, before)).changes)
+    },
   }
 }
 
 // An audit's `cache`: where the server has an upstream disk cache (off Vercel,
 // set at startup), that keeps everything; else this store keeps listings.
-export function auditCache(cacheDir: string | null | undefined, db: UpstreamCacheStore, signal: AbortSignal, debug = false): CacheStore | undefined {
-  return cacheDir ? undefined : upstreamCache(db, signal, debug)
+export function auditCache(cacheDir: string | null | undefined, db: UpstreamCacheStore, signal: AbortSignal, debug = false, repos: Iterable<string> = []): CacheStore | undefined {
+  return cacheDir ? undefined : upstreamCache(db, signal, debug, repos)
+}
+
+// The repositories whose listings an audit of `packages` asks for, where they
+// are already known: each `github` package, each `soldeer` package's given
+// repository, and with `repoAdvisories`, every other package's. Upstream looks
+// up the rest itself.
+export function auditedRepos(packages: Iterable<Package>, repoAdvisories: boolean): string[] {
+  const repos = [...packages].map(pkg => (pkg.ecosystem === 'github' ? pkg.name
+    : pkg.ecosystem === 'soldeer' || repoAdvisories ? pkg.github : undefined))
+  return [...new Set(repos.filter(repo => repo !== undefined))]
 }
 
 // Only listings are kept: upstream's other records (npm version documents,
@@ -51,12 +82,25 @@ const CACHED_TYPE = 'github/advisories'
 // The cache is an optimization: a database failure is a miss, never a failed
 // audit. Upstream keeps listing after an abandoned audit; once `signal` aborts,
 // the request's database work is over and the store is left alone.
-export function upstreamCache(db: UpstreamCacheStore, signal: AbortSignal, debug = false): CacheStore {
+// Upstream reads one listing at a time per repository, and a request's queries
+// share one connection (Neon), so a recheck of hundreds of packages would wait
+// on as many round trips: the first read asks for every listing of `repos`
+// at once. Any other key, or all of them if that read fails, is read alone.
+export function upstreamCache(db: UpstreamCacheStore, signal: AbortSignal, debug = false, repos: Iterable<string> = []): CacheStore {
+  // Upstream asks for a listing by its repository's lowercased name.
+  const batched = new Set([...repos].map(repo => `${CACHED_TYPE}/${repo.toLowerCase()}`))
+  let batch: Promise<Map<string, string> | null> | undefined
+  const readBatch = () => batch ??= db.getUpstreamCacheEntries([...batched]).catch((error: unknown) => {
+    if (debug) console.warn('managed: upstream cache read failed:', error)
+    return null
+  })
   return {
     async read(type, key) {
       if (type !== CACHED_TYPE || signal.aborted) return null
+      const cacheKey = `${type}/${key}`
       try {
-        const value = await db.getUpstreamCacheEntry(`${type}/${key}`)
+        const found = batched.has(cacheKey) ? await readBatch() : null
+        const value = found ? found.get(cacheKey) ?? null : await db.getUpstreamCacheEntry(cacheKey)
         return value === null ? null : JSON.parse(value) as unknown
       } catch (error) {
         if (debug) console.warn('managed: upstream cache read failed:', error)
@@ -71,3 +115,101 @@ export function upstreamCache(db: UpstreamCacheStore, signal: AbortSignal, debug
     },
   }
 }
+
+// The file upstream keeps `file` in, under `dir` of its disk cache
+// (setCacheDir), as its cachePath names it: `@babel+core@7.29.7.tgz`, a
+// capital written `!` and the letter, and a Windows device name's first
+// letter escaped.
+export function upstreamCachePath(root: string, dir: string, file: string): string {
+  const name = encodeURIComponent(file.replaceAll(/[!A-Z]/gu, char => `!${char.toLowerCase()}`))
+    .replaceAll('%40', '@').replaceAll('%2F', '+')
+    .replace(/^(?=(?:con|prn|aux|nul|com\d|lpt\d)(?:\.|$))./u, char => `%${char.codePointAt(0)!.toString(16).toUpperCase()}`)
+  return join(root, dir, name)
+}
+
+// A kept file, where it is a regular file of at most `max` bytes, checked on
+// the file as opened (a FIFO or device would block or never end), and read
+// to the size it had then.
+export async function readKeptFile(path: string, max: number): Promise<Uint8Array | null> {
+  const handle = await open(path, constants.O_RDONLY | constants.O_NONBLOCK).catch(() => null)
+  if (!handle) return null
+  try {
+    const stats = await handle.stat()
+    if (!stats.isFile() || stats.size > max) return null
+    const bytes = Buffer.allocUnsafe(stats.size)
+    for (let at = 0; at < bytes.length;) {
+      const { bytesRead } = await handle.read(bytes, at, bytes.length - at, at)
+      if (bytesRead === 0) return null
+      at += bytesRead
+    }
+    return bytes
+  } catch { return null }
+  finally { await handle.close() }
+}
+
+// `bytes` kept at `path`, written whole beside it first and then moved in, so a
+// reader finds the old file or the new one, never part of one; a failure
+// keeps nothing.
+let tmpSeq = 0
+export async function keepFile(path: string, bytes: Uint8Array) {
+  const tmp = `${path}.${process.pid}.${++tmpSeq}.tmp`
+  try {
+    await mkdir(dirname(path), { recursive: true })
+    await writeFile(tmp, bytes)
+    await rename(tmp, path)
+  } catch { await rm(tmp, { force: true }).catch(() => {}) }
+}
+
+const gunzipAsync = promisify(gunzip)
+const gzipAsync = promisify(gzip)
+
+// An upstream's JSON object kept with its ETag, gzipped, as keepJson keeps it:
+// `{ etag, json }`, or null where none is kept, or what is can't be read
+// within `limit` bytes.
+export async function readKeptJson(path: string, limit: number): Promise<{ etag: string; json: Record<string, unknown> } | null> {
+  const bytes = await readKeptFile(path, limit)
+  if (!bytes) return null
+  const object = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+  try {
+    const kept: unknown = JSON.parse((await gunzipAsync(bytes, { maxOutputLength: limit + 1024 })).toString('utf8'))
+    return object(kept) && typeof kept['etag'] === 'string' && object(kept['json']) ? { etag: kept['etag'], json: kept['json'] } : null
+  } catch { return null }
+}
+
+// `body`, an upstream's JSON object as it wrote it, kept with its `etag`.
+export async function keepJson(path: string, etag: string, body: Buffer) {
+  await keepFile(path, await gzipAsync(Buffer.concat([Buffer.from(`{"etag":${JSON.stringify(etag)},"json":`), body, Buffer.from('}')])))
+}
+
+// A kept listing is read to no more than this, gzipped or not: one runs to
+// some hundreds of KiB.
+const LISTING_BYTES = 64 * 1024 * 1024
+
+// A repository's listing as last kept where audits keep them (auditCache),
+// however old, for when GitHub can't be reached to refresh it: `at`, when it
+// was kept, and `cache`, a store answering it to upstream as kept just now,
+// so that upstream takes it rather than ask GitHub, and keeping nothing.
+// Upstream checks it as it checks its own. Null where none is kept, or it
+// can't be read.
+export async function lastListing(cacheDir: string | null | undefined, db: UpstreamCacheStore, repo: string, debug = false): Promise<{ at: number; cache: CacheStore } | null> {
+  const key = repo.toLowerCase()
+  let kept: { at?: unknown } | null
+  try {
+    if (cacheDir) {
+      const bytes = await readKeptFile(upstreamCachePath(cacheDir, CACHED_TYPE, `${key}.json.gz`), LISTING_BYTES)
+      kept = bytes && JSON.parse((await gunzipAsync(bytes, { maxOutputLength: LISTING_BYTES })).toString('utf8'))
+    } else {
+      const value = await db.getUpstreamCacheEntry(`${CACHED_TYPE}/${key}`)
+      kept = value === null ? null : JSON.parse(value)
+    }
+  } catch (error) {
+    if (debug) console.warn('managed: kept listing read failed:', error)
+    return null
+  }
+  const at = kept?.at
+  if (typeof at !== 'number') return null
+  return { at, cache: {
+    read: (type, name) => Promise.resolve(type === CACHED_TYPE && name === key ? { ...kept, at: Date.now() } : null),
+    write: () => Promise.resolve(),
+  } }
+}

package/server-managed/view-as.ts

@@ -0,0 +1,58 @@
+// An administrator's read-only view as another user, for checking what that
+// account can access. The view is a session row for the viewed user (so every
+// access check applies that user's role, teams and permissions unchanged) tied
+// to the admin's own session, carried in its own cookie beside the session
+// cookie. Ending the admin session, or the admin role, ends the view.
+//
+// The router refuses writes for any request that carries the view cookie, and
+// such requests never act with the viewed user's GitHub credentials: GitHub
+// data that needs them is left out instead.
+import { AsyncLocalStorage } from 'node:async_hooks'
+import type { ManagedConfig } from './config.ts'
+import type { ManagedDb, ManagedSession } from './db.ts'
+import { hashToken, randomToken } from './crypto.ts'
+import { VIEW_COOKIE, buildCookie, clearCookie, cookieName, parseCookies } from './session.ts'
+
+export const VIEW_AS_PATH = '/api/auth/view-as'
+export const VIEW_ONLY_ERROR = 'view-only'
+
+function viewCookieName(config: ManagedConfig): string {
+  return cookieName(config, VIEW_COOKIE)
+}
+
+// The raw view token, or null when the request carries no view.
+export function viewToken(config: ManagedConfig, cookieHeader: string | undefined): string | null {
+  const token = parseCookies(cookieHeader).get(viewCookieName(config))
+  return token == null || token === '' ? null : token
+}
+
+export function clearViewCookie(config: ManagedConfig): string {
+  return clearCookie(viewCookieName(config), config.cookieSecure)
+}
+
+// Open a view as `userId` from the admin's `session`, replacing any earlier
+// view of that session. Null when the database refuses it (see createViewSession).
+export async function startViewSession(config: ManagedConfig, db: ManagedDb, session: ManagedSession, userId: string, now: number): Promise<string | null> {
+  const token = randomToken()
+  const ok = await db.createViewSession({ id: hashToken(token), viewerSessionId: session.id, userId, csrfToken: randomToken() }, now)
+  if (!ok) return null
+  return buildCookie(viewCookieName(config), token, {
+    maxAgeS: Math.max(0, Math.floor((session.expiresAt - now) / 1000)), secure: config.cookieSecure, sameSite: 'Lax',
+  })
+}
+
+export async function endViewSession(config: ManagedConfig, db: ManagedDb, cookieHeader: string | undefined): Promise<void> {
+  const token = viewToken(config, cookieHeader)
+  if (token != null) await db.deleteSession(hashToken(token))
+}
+
+const viewing = new AsyncLocalStorage<boolean>()
+
+export function runViewing<T>(active: boolean, work: () => T): T {
+  return active ? viewing.run(true, work) : work()
+}
+
+// Whether the current request is an admin's view as another user.
+export function isViewing(): boolean {
+  return viewing.getStore() === true
+}