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

package/server-managed/uploads.ts

@@ -0,0 +1,106 @@
+// Staging is shared storage, never process memory. Each part is bound to the
+// 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, 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
+// 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'
+
+function partId(session: string, kind: UploadKind, id: string, index: number): string {
+  const hash = createHash('sha256').update(JSON.stringify([session, kind, id, index])).digest('hex').slice(0, 32)
+  return `${hash.slice(0, 8)}-${hash.slice(8, 12)}-${hash.slice(12, 16)}-${hash.slice(16, 20)}-${hash.slice(20)}`
+}
+
+export function validUploadPart(id: string, index: number, maxBytes: number): boolean {
+  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 {
+  return UUID.test(id) && Number.isSafeInteger(count) && count > 0
+}
+
+// Limit cleanup to indices that any configured server could have accepted,
+// even if the request advertises an enormous count or the limit was lowered.
+export async function deleteUpload(store: BlobStore, session: string, kind: UploadKind, id: string, count: number): Promise<void> {
+  if (!validUpload(id, count)) throw new Error('bad-upload')
+  const end = Math.min(count, MAX_UPLOAD_PARTS), errors = []
+  for (let start = 0; start < end; start += 8) {
+    const results = await Promise.allSettled(Array.from({ length: Math.min(8, end - start) },
+      (_, index) => store.delete(partId(session, kind, id, start + index))))
+    for (const result of results) if (result.status === 'rejected') errors.push(result.reason)
+  }
+  if (errors.length > 0) throw new AggregateError(errors, 'Upload cleanup failed')
+}
+
+export async function putUploadPart(store: BlobStore, session: string, kind: UploadKind, id: string, index: number, bytes: Buffer): Promise<void> {
+  await store.put(partId(session, kind, id, index), bytes)
+}
+
+// Parts read at once while an upload is put together.
+const PARTS_READ_AT_ONCE = 6
+
+// The staged upload `req` names, its parts read a few at a time into the one
+// buffer it fills, each as long as its place in it. Its parts are deleted
+// once read, or once it fails: awaited, unless `behind` takes that cleanup to
+// go on past the response (http.ts), which staging maintenance backs up.
+export async function readUpload(store: BlobStore, req: IncomingMessage, session: string, kind: UploadKind, maxBytes: number,
+  behind?: (cleanup: Promise<void>) => void): Promise<Buffer> {
+  const id = req.headers['x-upload-id']
+  const count = Number(req.headers['x-upload-parts']), size = Number(req.headers['x-upload-size'])
+  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_STAGED_BYTES) throw new Error('too-large')
+    // Every byte of it is written below before it is returned: each part
+    // must fill its place exactly, or the upload fails.
+    const body = Buffer.allocUnsafe(size)
+    let failed = false, next = 0
+    const readParts = async () => {
+      while (!failed && next < count) {
+        const index = next++
+        const bytes = await store.get(partId(session, kind, id, index))
+        const expected = Math.min(UPLOAD_CHUNK_BYTES, size - index * UPLOAD_CHUNK_BYTES)
+        if (!bytes || bytes.length !== expected) { failed = true; throw new Error('bad-upload') }
+        bytes.copy(body, index * UPLOAD_CHUNK_BYTES)
+      }
+    }
+    // Each read settled before its parts are deleted.
+    const results = await Promise.allSettled(Array.from({ length: Math.min(PARTS_READ_AT_ONCE, count) }, readParts))
+    const rejected = results.find(result => result.status === 'rejected')
+    if (rejected) throw rejected.reason
+    return body
+  } finally {
+    // These bytes can no longer be finalized. Failed/abandoned chunk uploads
+    // are also covered by automatic staging maintenance.
+    const cleanup = deleteUpload(store, session, kind, id, count).catch(err => console.warn('managed: upload cleanup failed:', err))
+    if (behind) behind(cleanup)
+    else await cleanup
+  }
+}
+
+// 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

@@ -0,0 +1,243 @@
+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
+// by every instance: each repository's published advisory listing, written by
+// dependency audits that ask repositories, keyed `github/advisories/owner/name`.
+// Upstream stamps, validates and expires each value (90 minutes for a listing);
+// a refresh replaces the row, and there is one row per repository, so rows are
+// not evicted. Only public repositories publish advisories: rows are shared
+// across viewers.
+export const UPSTREAM_CACHE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_upstream_cache (
+  cache_key TEXT PRIMARY KEY,
+  value     TEXT NOT NULL,
+  cached_at INTEGER NOT NULL
+) STRICT;
+`
+
+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>>
+  // Those of `first` that are kept; where none is, those of `then`, in the
+  // same statement (`first` whether they are `first`'s).
+  getFirstUpstreamCacheEntries(first: string[], then: string[]): Promise<{ first: boolean; entries: Map<string, string> }>
+  setUpstreamCacheEntry(key: string, value: string, cachedAt: number): Promise<void>
+  // Each of `entries` (key, value), as setUpstreamCacheEntry keeps one, in one
+  // statement: the last of a key given twice.
+  setUpstreamCacheEntries(entries: [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(?))')
+  const getFirst = db.prepare(`WITH found AS (SELECT cache_key, value FROM managed_upstream_cache WHERE cache_key IN (SELECT value FROM json_each(?)))
+    SELECT cache_key, value, 1 AS in_first FROM found
+    UNION ALL SELECT cache_key, value, 0 AS in_first FROM managed_upstream_cache
+      WHERE cache_key IN (SELECT value FROM json_each(?)) AND NOT EXISTS (SELECT 1 FROM found)`)
+  // 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 < ?')
+  // setUpstreamCacheEntries's, by how many it keeps at once.
+  const setMany = new Map<number, ReturnType<ManagedSql['prepare']>>()
+  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 getFirstUpstreamCacheEntries(first, then) {
+      if (first.length === 0 && then.length === 0) return { first: false, entries: new Map() }
+      const rows = await getFirst.all(JSON.stringify(first), JSON.stringify(then)) as { cache_key: string; value: string; in_first: number }[]
+      return { first: rows.some(row => Number(row.in_first) === 1), entries: new Map(rows.map(row => [row.cache_key, row.value])) }
+    },
+    async setUpstreamCacheEntry(key, value, cachedAt) {
+      await set.run(key, value, cachedAt)
+    },
+    async setUpstreamCacheEntries(entries, cachedAt) {
+      const rows = [...new Map(entries)]
+      if (rows.length === 0) return
+      let many = setMany.get(rows.length)
+      if (!many) {
+        setMany.set(rows.length, many = db.prepare(`INSERT INTO managed_upstream_cache (cache_key, value, cached_at) VALUES ${rows.map(() => '(?, ?, ?)').join(', ')}
+          ON CONFLICT (cache_key) DO UPDATE SET value = excluded.value, cached_at = excluded.cached_at
+          WHERE managed_upstream_cache.cached_at <= excluded.cached_at`))
+      }
+      await many.run(...rows.flatMap(([key, value]) => [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, 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,
+// registries' repository lookups) read as misses and are not written.
+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.
+// 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 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)
+        return null
+      }
+    },
+    async write(type, key, value) {
+      if (type !== CACHED_TYPE || signal.aborted) return
+      try { await db.setUpstreamCacheEntry(`${type}/${key}`, JSON.stringify(value), Date.now()) } catch (error) {
+        if (debug) console.warn('managed: upstream cache write failed:', error)
+      }
+    },
+  }
+}
+
+// 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
+}

package/server-managed/workspace-shares.ts

@@ -0,0 +1,169 @@
+import { linkRevision } from './link-reports.ts'
+import type { ManagedSql } from './sql.ts'
+import type { BundleBuildConditions, ManagedBundle, TeamReportAccessSnapshot, UserTeam } from './db.ts'
+import { type TeamUserPermissions, parseTeamUserPermissions } from '../common/managed/permissions.ts'
+
+export const WORKSPACE_SHARE_SCHEMA = `
+CREATE TABLE IF NOT EXISTS managed_workspace_share (
+  token_hash TEXT PRIMARY KEY,
+  team_id TEXT NOT NULL REFERENCES managed_team(id) ON DELETE CASCADE,
+  created_by TEXT NOT NULL REFERENCES managed_user(id) ON DELETE CASCADE,
+  created_at INTEGER NOT NULL,
+  dependencies INTEGER NOT NULL DEFAULT 0,
+  security INTEGER NOT NULL DEFAULT 0
+) STRICT;
+CREATE INDEX IF NOT EXISTS managed_workspace_share_team_idx ON managed_workspace_share(team_id);
+`
+
+export interface WorkspaceShareSnapshot extends TeamReportAccessSnapshot {
+  team: UserTeam
+  permissions: TeamUserPermissions
+  repositories: { repoId: number; github: string; path: string }[]
+  bundles: ManagedBundle[]
+}
+export interface WorkspaceShareInfo {
+  id: string
+  createdAt: number
+  createdBy: string
+  permissions: TeamUserPermissions
+}
+export interface ManagedWorkspaceShare extends WorkspaceShareInfo {
+  teamId: string
+  teamName: string
+  teamSlug: string
+}
+export type WorkspaceShareFeedState = { grant: string; catalog: number; annotations: number }
+export interface WorkspaceShareStore {
+  createWorkspaceShare(sessionId: string, now: number, teamId: string, tokenHash: string, permissions?: TeamUserPermissions): Promise<boolean>
+  listWorkspaceShares(sessionId: string, now: number, teamId: string): Promise<WorkspaceShareInfo[] | null>
+  listManagedWorkspaceShares(sessionId: string, now: number): Promise<ManagedWorkspaceShare[] | null>
+  updateWorkspaceShare(sessionId: string, now: number, teamId: string, id: string, permissions: TeamUserPermissions): Promise<boolean>
+  revokeWorkspaceShares(sessionId: string, now: number, teamId: string, id?: string): Promise<boolean>
+  getWorkspaceShare(tokenHash: string): Promise<WorkspaceShareSnapshot | null>
+  getWorkspaceShareFeedState(tokenHash: string): Promise<WorkspaceShareFeedState | null>
+}
+
+// A share is a capability, never a user session. Its issuer must still manage
+// this team on every read. No union of the issuer's other memberships applies.
+function shareQueries(db: ManagedSql) {
+  const manager = db.prepare(`SELECT 1 FROM managed_session s
+    JOIN managed_user u ON u.id = s.user_id
+    JOIN managed_team t ON t.id = ? AND t.hidden = 0
+    WHERE s.id = ? AND s.expires_at > ? AND (u.role = 'admin' OR (u.role = 'manage'
+      AND EXISTS (SELECT 1 FROM managed_team_user tu WHERE tu.user_id = u.id AND tu.team_id = t.id)))`)
+  const insert = db.prepare(`INSERT INTO managed_workspace_share (token_hash, team_id, created_by, created_at, dependencies, security)
+    SELECT ?, ?, user_id, ?, ?, ? FROM managed_session WHERE id = ?`)
+  const remove = db.prepare('DELETE FROM managed_workspace_share WHERE team_id = ? AND (CAST(? AS TEXT) IS NULL OR token_hash = ?)')
+  const update = db.prepare('UPDATE managed_workspace_share SET dependencies = ?, security = ? WHERE team_id = ? AND token_hash = ?')
+  // The management ID is a hash, never a bearer token. Existing URLs remain
+  // unchanged when their permissions are edited; plaintext tokens aren't kept.
+  const list = db.prepare(`SELECT s.token_hash AS id, s.created_at AS createdAt, u.login AS createdBy, s.dependencies, s.security
+    FROM managed_workspace_share s JOIN managed_user u ON u.id = s.created_by WHERE s.team_id = ? ORDER BY s.created_at DESC, s.token_hash`)
+  const session = db.prepare(`SELECT u.id, u.role FROM managed_session s JOIN managed_user u ON u.id = s.user_id
+    WHERE s.id = ? AND s.expires_at > ? AND u.role IN ('manage', 'admin')`)
+  const all = db.prepare(`SELECT s.token_hash AS id, s.created_at AS createdAt, u.login AS createdBy, s.dependencies, s.security,
+    t.id AS teamId, t.slug AS teamSlug, t.name AS teamName FROM managed_workspace_share s
+    JOIN managed_user u ON u.id = s.created_by JOIN managed_team t ON t.id = s.team_id AND t.hidden = 0
+    WHERE ? = 'admin' OR EXISTS (SELECT 1 FROM managed_team_user tu WHERE tu.user_id = ? AND tu.team_id = s.team_id)
+    ORDER BY t.name, t.id, s.created_at DESC, s.token_hash`)
+  const shareGrant = `FROM managed_workspace_share s
+    JOIN managed_user u ON u.id = s.created_by
+    JOIN managed_team t ON t.id = s.team_id AND t.hidden = 0
+    WHERE s.token_hash = ? AND (u.role = 'admin' OR (u.role = 'manage'
+      AND EXISTS (SELECT 1 FROM managed_team_user tu WHERE tu.user_id = u.id AND tu.team_id = s.team_id)))`
+  const share = db.prepare(`SELECT t.id, t.slug, t.name, s.dependencies, s.security ${shareGrant}`)
+  // Validate the capability and its issuer every poll; global counters are
+  // internal hints that let unchanged feeds skip rebuilding the full catalog.
+  const feed = db.prepare(`SELECT t.id, s.dependencies, s.security,
+    (SELECT catalog FROM managed_change_revision WHERE id = 1) AS catalog,
+    (SELECT annotations FROM managed_change_revision WHERE id = 1) AS annotations ${shareGrant}`)
+  const repositories = db.prepare(`SELECT tr.repo_id AS repoId, sr.full_name AS github, tr.path
+    FROM managed_team_repo tr JOIN managed_selected_repo sr ON sr.repo_id = tr.repo_id
+    WHERE tr.team_id = ? ORDER BY tr.repo_id, tr.path`)
+  const reports = db.prepare(`SELECT DISTINCT r.id, r.slug, r.filename, r.analyzer, r.byte_size AS byteSize,
+    r.sha256, r.repo_directory AS directory, sr.full_name AS github
+    FROM managed_team_repo tr JOIN managed_report r ON r.repo_id = tr.repo_id
+    JOIN managed_selected_repo sr ON sr.repo_id = r.repo_id
+    WHERE tr.team_id = ? AND r.visible = 1 AND (tr.path = '' OR r.repo_directory = tr.path
+      OR substr(r.repo_directory, 1, length(tr.path) + 1) = tr.path || '/') ORDER BY r.id`)
+  // A raw bundle is visible only when its declared root is inside the team scope.
+  // Root bundles remain hidden from directory-only grants.
+  const bundles = db.prepare(`SELECT DISTINCT b.id, b.slug, b.integrity, b.filename, b.kind, b.byte_size AS byteSize,
+    b.uploaded_by AS uploadedBy, b.repo_id AS repoId, b.repo_directory AS repoDirectory, b.uploaded_at AS uploadedAt, b.provenance, b.build_conditions AS buildConditions, sr.full_name AS repoFullName
+    FROM managed_team_repo tr JOIN managed_bundle b ON b.repo_id = tr.repo_id
+    JOIN managed_selected_repo sr ON sr.repo_id = b.repo_id
+    WHERE tr.team_id = ? AND b.visible = 1 AND (tr.path = '' OR b.repo_directory = tr.path
+      OR substr(b.repo_directory, 1, length(tr.path) + 1) = tr.path || '/') ORDER BY b.id`)
+  return { manager, insert, remove, update, list, session, all, share, feed, repositories, reports, bundles }
+}
+
+function shareInfo<T extends { dependencies: number; security: number }>(row: T) {
+  const { dependencies, security, ...rest } = row
+  return { ...rest, permissions: { dependencies: dependencies === 1, security: security === 1 } }
+}
+
+export function workspaceShareMethods(db: ManagedSql): WorkspaceShareStore {
+  const q = shareQueries(db)
+  return {
+    async createWorkspaceShare(sessionId, now, teamId, tokenHash, permissions) {
+      if (!await q.manager.get(teamId, sessionId, now)) return false
+      const p = parseTeamUserPermissions(permissions)
+      await q.insert.run(tokenHash, teamId, now, +p.dependencies, +p.security, sessionId)
+      return true
+    },
+    async listWorkspaceShares(sessionId, now, teamId) {
+      if (!await q.manager.get(teamId, sessionId, now)) return null
+      const rows = await q.list.all(teamId) as { id: string; createdAt: number; createdBy: string; dependencies: number; security: number }[]
+      return rows.map(shareInfo)
+    },
+    async listManagedWorkspaceShares(sessionId, now) {
+      const viewer = await q.session.get(sessionId, now) as { id: string; role: string } | undefined
+      if (!viewer) return null
+      const rows = await q.all.all(viewer.role, viewer.id) as (Omit<ManagedWorkspaceShare, 'permissions'> & { dependencies: number; security: number })[]
+      return rows.map(shareInfo)
+    },
+    async updateWorkspaceShare(sessionId, now, teamId, id, permissions) {
+      if (!await q.manager.get(teamId, sessionId, now)) return false
+      const p = parseTeamUserPermissions(permissions)
+      return (await q.update.run(+p.dependencies, +p.security, teamId, id)).changes > 0
+    },
+    async revokeWorkspaceShares(sessionId, now, teamId, id) {
+      if (!await q.manager.get(teamId, sessionId, now)) return false
+      const result = await q.remove.run(teamId, id ?? null, id ?? null)
+      return id === undefined || result.changes > 0
+    },
+    async getWorkspaceShareFeedState(tokenHash) {
+      const row = await q.feed.get(tokenHash) as { id: string; dependencies: number; security: number; catalog: number; annotations: number } | undefined
+      return row ? { grant: JSON.stringify([row.id, row.dependencies, row.security]), catalog: row.catalog, annotations: row.annotations } : null
+    },
+    async getWorkspaceShare(tokenHash) {
+      const grant = await q.share.get(tokenHash) as { id: string; slug: string; name: string; dependencies: number; security: number } | undefined
+      if (!grant) return null
+      const { dependencies, security, ...team } = grant
+      const permissions = { dependencies: dependencies === 1, security: security === 1 }
+      const rows = await q.reports.all(team.id) as { id: string; slug: string; filename: string; analyzer: string | null; byteSize: number; sha256: string; directory: string; github: string }[]
+      const links = await linkRevision(db)
+      const bundleRows = (await q.bundles.all(team.id) as (Omit<ManagedBundle, 'buildConditions'> & { buildConditions: string | null; repoFullName: string })[])
+        .map(row => ({ ...row, buildConditions: row.buildConditions == null ? null : JSON.parse(row.buildConditions) as BundleBuildConditions }))
+      const repositories = await q.repositories.all(team.id) as WorkspaceShareSnapshot['repositories']
+      return {
+        user: { id: `share:${tokenHash}`, login: 'public', name: 'Public workspace', avatarUrl: null, role: 'view' },
+        teamId: team.id,
+        linkRevision: links,
+        permissions,
+        repositories,
+        reports: rows.map(row => ({ id: row.id, filename: row.filename, byteSize: row.byteSize, sha256: row.sha256,
+          repo: { github: row.github, directory: row.directory }, permissions })),
+        team: { ...team, permissions, cacheKey: links,
+          repos: repositories.map(repo => ({ repoId: repo.repoId, fullName: repo.github, path: repo.path || null }))
+            .toSorted((a, b) => a.fullName.localeCompare(b.fullName) || (a.path ?? '').localeCompare(b.path ?? '')),
+          reports: rows.map(row => ({ id: row.id, slug: row.slug, filename: row.filename, visible: true, analyzer: row.analyzer, repoFullName: row.github, repoDirectory: row.directory,
+            cacheKey: JSON.stringify([row.sha256, row.github, row.directory, row.filename, permissions, links]) })),
+          bundles: bundleRows.map(row => ({ id: row.id, slug: row.slug, integrity: row.integrity,
+            filename: row.filename, visible: true, kind: row.kind, byteSize: row.byteSize, repoId: row.repoId!, repoDirectory: row.repoDirectory, repoFullName: row.repoFullName, provenance: row.provenance })),
+        },
+        bundles: bundleRows.map(row => ({ ...row, visible: true })),
+      }
+    },
+  }
+}

package/server.ts

@@ -0,0 +1,70 @@
+import { parseArgs } from 'node:util'
+import type { Server } from 'node:http'
+import { startServer } from './server-common/standalone.ts'
+
+// The reviewed dependencies a host keeps beyond the app, registered before
+// init() (server-managed/reviewed-dependencies.ts): an async method telling
+// whether a dependency, as a lockfile locks it, is reviewed there
+// (`lookup`), and optionally one reading the reviews an open pull request's
+// comments make (`parseComments`), and one formatting one's own dependency
+// reviews as a comment to copy (`formatDependencyReviews`). They replace a
+// repository's commit its dependencies are reviewed since.
+export { registerReviewedDependencies } from './server-managed/reviewed-dependencies.ts'
+export type { CommentReview, DependencyReviewEntry, FormatDependencyReviewsInput, ParseCommentsInput, ReviewComment, ReviewedDependencies, ReviewedDependency,
+  ReviewedLockfile, ReviewedVersion, ReviewVerdict } from './server-managed/reviewed-dependencies.ts'
+
+const modes = ['e2e', 'managed', 'managed-e2e', 'e2e-managed'] as const
+export type ServerMode = typeof modes[number]
+
+function parseMode(mode: string): ServerMode {
+  for (const candidate of modes) if (mode === candidate) return candidate
+  throw new Error(`Unknown mode: ${mode}. Expected ${modes.join(', ')}.`)
+}
+
+export type InitOptions = {
+  mode?: ServerMode
+  // False serves only the API: `out/` is never read, nor its UI served, for
+  // hosts that serve the UI themselves.
+  ui?: boolean
+}
+
+// Assemble the selected server without binding a port. Hosts can reuse its
+// request/upgrade listeners or call listen() themselves. `init(mode)` is
+// `init({ mode })`.
+export async function init(options: ServerMode | InitOptions = {}): Promise<Server> {
+  const { mode = 'e2e', ui = true }: InitOptions = typeof options === 'string' ? { mode: options } : options
+  const selected = parseMode(mode)
+  if (selected === 'e2e') {
+    const { createE2eApp } = await import('./server-e2e/app.ts')
+    return (await createE2eApp(undefined, { ui })).httpServer
+  }
+  if (selected === 'managed') {
+    const managed = await import('./server-managed/index.ts')
+    return managed.init(undefined, { ui })
+  }
+  const combined = await import('./server-managed/combined.ts')
+  return combined.init(selected === 'managed-e2e' ? 'managed+e2e' : 'e2e+managed', { ui })
+}
+
+export async function start(): Promise<void> {
+  const { values } = parseArgs({ options: {
+    mode: { type: 'string', default: 'e2e' },
+    help: { type: 'boolean', short: 'h' },
+  } })
+  const mode = parseMode(values.mode)
+  if (values.help) {
+    console.log(`Usage: node cli.js --mode <${modes.join('|')}>
+Defaults to e2e. Combined modes share HOST/PORT; the first mode is the client default.
+Managed modes require GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET and OAUTH_CALLBACK_URL.
+Combined storage: DATABASE_URL for a shared Neon DB, or E2E_DATABASE_URL and
+MANAGED_DATABASE_URL for separate Neon DBs. Do not mix shared and per-mode URLs.
+Without URLs: SQLite at DB_PATH for e2e and MANAGED_DB_PATH for managed.
+Combined mode does not support mixing Neon and SQLite.`)
+  } else {
+    const config = mode === 'managed'
+      ? (await import('./server-managed/config.ts')).loadManagedConfig()
+      : (await import('./server-e2e/config.ts')).loadConfig()
+    const server = await init(mode)
+    startServer(server, config)
+  }
+}