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

package/common/managed/github-agents.ts

@@ -0,0 +1,114 @@
+// Agents by their own GitHub accounts, where a repository's activity names
+// them: each its name, and how the app draws it, by its mark, as the Agents
+// tab does (ui/view/provider-icons.js), or by its avatar, which
+// /api/avatar/<avatar> serves; its accounts, each by the logins GitHub's REST and GraphQL APIs
+// name it by and its numeric id where known, which GitHub never gives
+// another; and the names its commits carry where GitHub names no account for
+// them. Claude Code's commits are authored as Claude <noreply@anthropic.com>,
+// which GitHub names `claude`; the Claude GitHub App's as `claude[bot]`.
+// Codex's GitHub connector's are its own; Codex otherwise commits as whoever
+// ran it, and those commits are theirs, with a
+// `Co-authored-by: Codex <codex@openai.com>` trailer, an address GitHub
+// names someone else's account for, so Codex is known by the address, not
+// that account. Copilot's coding agent authors its commits as its account,
+// Copilot; Copilot's code review reviews as another, its bot, which GitHub
+// names Copilot as well where it is asked to review and in its threads, and
+// `copilot-pull-request-reviewer` (`[bot]` to GitHub's REST API) on its
+// reviews, the accounts' ids telling the two apart: a login may so be more
+// than one account's. Dependabot, its GitHub App, as its bot,
+// `dependabot` to GitHub's GraphQL API, `dependabot[bot]` to its REST API and
+// in its address. GitHub's Agentic Workflows (gh-aw) post, and approve or
+// review pull requests, as GitHub Actions' bot, `github-actions` (41898282,
+// `[bot]` to the REST API), its mark the GitHub Actions App's avatar; other
+// workflows the bot runs are as much its own, and the commits workflows make
+// as the names they are commonly given, `github-actions` and `GitHub Action`,
+// GitHub naming no account for their addresses. Neo, its GitHub App (3115942),
+// as its account (274065190) and its App's bot (268952163), each known by
+// its id alone, whatever GitHub names it, and drawn by its App's avatar,
+// wherever either or its fingerprint names it. Cursor's agents commit as whoever ran them, with a
+// `Co-authored-by: Cursor Agent <cursoragent@cursor.com>` trailer; the app
+// has no mark of Cursor's, and draws it by its name's letter. Each by the
+// addresses (`emails`) its commits name it by, as author or co-author.
+//
+// Those the Agents tab tells beside Claude and Codex (whose sessions and
+// tasks it tells them by, common/managed/agent-tasks.ts), the server's app
+// agents (server-managed/app-agents.ts APP_AGENTS), by their branches'
+// prefix (`prefix`), the accounts their work is authored by, and the
+// fingerprint (`fingerprint`) they leave as a line of their pull
+// requests' bodies and their commits' messages, where they leave one:
+// Neo's, on `neo/` branches; Copilot's coding agent's, on `copilot/`;
+// Dependabot's, on `dependabot/<ecosystem>/…`. Their work may carry
+// Claude's or Codex's marks too, those its tools.
+export interface GithubAgentAccount { id?: number; logins: readonly string[] }
+export interface GithubAgent { name: string; mark?: 'anthropic' | 'openai' | 'github-copilot'; avatar?: string; accounts: readonly GithubAgentAccount[]; names: readonly string[]
+  emails?: readonly string[]; prefix?: string; fingerprint?: string }
+
+export const GITHUB_AGENTS = {
+  claude: { name: 'Claude', mark: 'anthropic', accounts: [{ id: 81847, logins: ['claude'] }, { logins: ['claude[bot]'] }], names: ['Claude'], emails: ['noreply@anthropic.com'] },
+  codex: { name: 'Codex', mark: 'openai', accounts: [{ id: 199175422, logins: ['chatgpt-codex-connector', 'chatgpt-codex-connector[bot]'] }], names: ['Codex'],
+    emails: ['codex@openai.com'] },
+  neo: { name: 'Neo', avatar: 'app-3115942', accounts: [{ id: 274065190, logins: [] }, { id: 268952163, logins: [] }], names: [], prefix: 'neo/',
+    fingerprint: '🤖 Generated with [Neo](' },
+  copilot: { name: 'Copilot', mark: 'github-copilot', accounts: [{ id: 198982749, logins: ['Copilot', 'copilot-swe-agent'] },
+    { id: 175728472, logins: ['Copilot', 'copilot-pull-request-reviewer', 'copilot-pull-request-reviewer[bot]'] }], names: ['Copilot'], prefix: 'copilot/' },
+  dependabot: { name: 'Dependabot', avatar: 'app-29110', accounts: [{ id: 49699333, logins: ['dependabot', 'dependabot[bot]'] }], names: ['dependabot[bot]'],
+    prefix: 'dependabot/' },
+  actions: { name: 'GitHub Actions', avatar: 'app-15368', accounts: [{ id: 41898282, logins: ['github-actions', 'github-actions[bot]'] }],
+    names: ['github-actions[bot]', 'github-actions', 'GitHub Action'] },
+  cursor: { name: 'Cursor', accounts: [], names: ['Cursor Agent'], emails: ['cursoragent@cursor.com'] },
+} as const satisfies Record<string, GithubAgent>
+export type GithubAgentId = keyof typeof GITHUB_AGENTS
+
+const agents = Object.entries(GITHUB_AGENTS) as [GithubAgentId, GithubAgent][]
+// Each login's agent, and the ids of the accounts it names, undefined for
+// one whose id the app doesn't know.
+const byLogin = new Map<string, { agent: GithubAgentId; ids: (number | undefined)[] }>()
+for (const [agent, { accounts }] of agents) {
+  for (const { id, logins } of accounts) {
+    for (const login of logins) byLogin.set(login.toLowerCase(), { agent, ids: [...byLogin.get(login.toLowerCase())?.ids ?? [], id] })
+  }
+}
+// The accounts known by their ids alone, no login of theirs: each its agent.
+const byId = new Map(agents.flatMap(([agent, { accounts }]) => accounts.flatMap(({ id, logins }) => id !== undefined && logins.length === 0 ? [[id, agent] as const] : [])))
+const byName = new Map(agents.flatMap(([agent, { names }]) => names.map(name => [name.toLowerCase(), agent] as const)))
+const byEmail = new Map(agents.flatMap(([agent, { emails = [] }]) => emails.map(email => [email, agent] as const)))
+
+// The agent whose address `email` is, GitHub matching addresses regardless of
+// case; null for anyone else's.
+export const emailAgent = (email: unknown): GithubAgentId | null => typeof email === 'string' ? byEmail.get(email.trim().toLowerCase()) ?? null : null
+
+// The agent an author is: by their login, GitHub matching logins regardless
+// of case, their account's id the agent's where both are known, so another
+// account GitHub names by the same login (a user's, the bot's GraphQL login
+// may be) is not; an account known by its id alone, by that, whatever its
+// login; for an author GitHub names no account for, by the name they carry.
+// Null for anyone else: a human's account is theirs, whatever their commits
+// name them.
+export function githubAgent(login: string | null, account: number | null = null, name: string | null = null): GithubAgentId | null {
+  if (typeof login !== 'string') return typeof name === 'string' ? byName.get(name.trim().toLowerCase()) ?? null : null
+  const known = byLogin.get(login.toLowerCase())
+  if (known && (account === null || known.ids.includes(undefined) || known.ids.includes(account))) return known.agent
+  return account === null ? null : byId.get(account) ?? null
+}
+
+// Whether the accounts `ids` a login is named by are all one agent's, as
+// Copilot's coding agent's and its code review's, both named Copilot, are:
+// the login is that agent's whichever it is, rather than no one's.
+export function oneAgent(login: string, ids: Iterable<number>): boolean {
+  const theirs = new Set([...ids].map(id => githubAgent(login, id)))
+  return theirs.size === 1 && !theirs.has(null)
+}
+
+// The accounts agents work as, a person's to GitHub, as the app is told of
+// them, each by its id and logins: the pull requests they open and the
+// commits they push to a branch directly are agents' (the Pulse's,
+// server-managed/repository-pulls.ts readPulls, repository-pulse.ts
+// commitStats), whatever their branches and labels, the rest of what they do
+// theirs. Christopher Turing's.
+export const AGENT_OPERATED = [{ id: 188797125, logins: ['ChristopherTuring'] }] as const satisfies readonly GithubAgentAccount[]
+
+// Whether an author is an account agents work as (AGENT_OPERATED): by its id
+// where GitHub gives it, whatever it is renamed to, else by its login,
+// regardless of case.
+export const agentOperated = (login: string | null, id: number | null = null): boolean => AGENT_OPERATED.some(account => id === null
+  ? typeof login === 'string' && account.logins.some(name => name.toLowerCase() === login.toLowerCase()) : account.id === id)

package/common/managed/github-logins.ts

@@ -0,0 +1,49 @@
+// The GitHub accounts an answer about a repository's activity names (its
+// commits', issues', pull requests', agents' and pulse's): as an author, one
+// who merged or a contributor, by login, and by the account's numeric id
+// where the answer names it beside the login. The server resolves them to the
+// app's users and agents (server-managed/github-users.ts), and the client
+// keeps those it answered with in place of what it held for them
+// (ui/view/github-users.js).
+import { oneAgent } from './github-agents.ts'
+
+// Where answers name a login, each with where the account's id is named
+// beside it.
+const LOGIN_KEYS = new Map([['author', 'authorId'], ['authorLogin', 'authorId'], ['mergedBy', 'mergedById'], ['login', 'id']])
+const LOGIN = /^[A-Za-z\d][A-Za-z\d-]{0,38}(?:\[bot\])?$/u
+const MAX_DEPTH = 8
+const accountId = (value: unknown) => Number.isSafeInteger(value) && (value as number) > 0 ? value as number : null
+
+// The logins `answer` names, each once, with the numeric id of the account
+// named beside them (null where none is, or where those named are all one
+// agent's, oneAgent); `ambiguous` where a login, GitHub matching logins
+// regardless of case, is named beside more than one: by an account GitHub
+// named by it once, as what was kept of the history says, and one it names by
+// it now, which is no telling whose each is.
+export function namedAccounts(answer: unknown): Map<string, number | 'ambiguous' | null> {
+  const named = new Map<string, Set<number>>()
+  collect(answer, named, 0)
+  const ids = new Map<string, Set<number>>()
+  for (const [login, theirs] of named) ids.set(login.toLowerCase(), new Set([...ids.get(login.toLowerCase()) ?? [], ...theirs]))
+  return new Map([...named.keys()].map((login): [string, number | 'ambiguous' | null] => {
+    const theirs = ids.get(login.toLowerCase())!
+    if (theirs.size <= 1) return [login, [...theirs][0] ?? null]
+    return [login, oneAgent(login, theirs) ? null : 'ambiguous']
+  }))
+}
+
+function collect(answer: unknown, named: Map<string, Set<number>>, depth: number): void {
+  if (depth > MAX_DEPTH || answer === null || typeof answer !== 'object') return
+  if (Array.isArray(answer)) {
+    for (const value of answer) collect(value, named, depth + 1)
+    return
+  }
+  const fields = answer as Record<string, unknown>
+  for (const [key, value] of Object.entries(fields)) {
+    const idKey = LOGIN_KEYS.get(key)
+    if (idKey && typeof value === 'string' && LOGIN.test(value)) {
+      const id = accountId(fields[idKey])
+      named.set(value, new Set([...named.get(value) ?? [], ...id === null ? [] : [id]]))
+    } else collect(value, named, depth + 1)
+  }
+}

package/common/managed/npm-packages.d.ts

@@ -0,0 +1,5 @@
+export const MAX_TEAM_NPM_SCOPES: number
+export function isNpmPackageName(value: unknown): value is string
+export function isNpmPackageSpec(value: unknown): value is string
+export function npmPackageScope(name: string): string | null
+export function normalizeNpmScope(value: unknown): string | null

package/common/managed/npm-packages.js

@@ -0,0 +1,34 @@
+// npm package names, versions and scopes as the managed npm viewer takes
+// them, shared by its routes, the server and the Teams page.
+
+// Upstream's rule (@preventive/upstream src/args.js): a scope, then a name
+// starting with none of `.`, `_` and `-`, 214 characters in all.
+const PACKAGE_NAME = /^(?=.{1,214}$)(?:@[\w.-]+\/[\w-]|[\dA-Za-z])[\w.-]*$/u
+// An exact version or a dist-tag, as the registry resolves `/<name>/<spec>`.
+const PACKAGE_SPEC = /^(?=.{1,256}$)[\dA-Za-z][\w.+-]*$/u
+// npm's rule for a scope: lowercase, and not starting with `.` or `_`.
+const SCOPE = /^@[\da-z~-][\w.~-]*$/u
+export const MAX_TEAM_NPM_SCOPES = 100
+
+export function isNpmPackageName(value) {
+  return typeof value === 'string' && PACKAGE_NAME.test(value)
+}
+
+export function isNpmPackageSpec(value) {
+  return typeof value === 'string' && PACKAGE_SPEC.test(value)
+}
+
+// `@scope` of a scoped name, lowercased as scopes are compared; null for an
+// unscoped one.
+export function npmPackageScope(name) {
+  return name.startsWith('@') && name.includes('/') ? name.slice(0, name.indexOf('/')).toLowerCase() : null
+}
+
+// A scope as typed: `scope` or `@scope`, either case, surrounding space
+// ignored. Null when it is not one npm could publish under.
+export function normalizeNpmScope(value) {
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim().toLowerCase()
+  const scope = trimmed.startsWith('@') ? trimmed : `@${trimmed}`
+  return scope.length <= 214 && SCOPE.test(scope) ? scope : null
+}

package/common/managed/permissions.ts

@@ -0,0 +1,31 @@
+// Per-membership visibility permissions for a team's users — shared by the
+// managed server (which stores + validates them) and the admin client (the
+// team-member checkboxes). Each is an independent opt-in, BOTH DEFAULT OFF:
+//   dependencies — scan findings in dependencies' own code; App impact stays visible
+//   security     — security findings and published bundle advisories
+// The managed server filters report responses and authorizes advisory lookups
+// using these independent permissions.
+export type VisibilityPermission = 'dependencies' | 'security'
+
+export const VISIBILITY_PERMISSIONS: readonly VisibilityPermission[] = ['dependencies', 'security']
+
+// Human labels for the admin checkboxes (keyed by permission).
+export const VISIBILITY_PERMISSION_LABELS: Record<VisibilityPermission, string> = {
+  dependencies: 'Dependencies',
+  security: 'Security',
+}
+
+// A membership's resolved permission set; every key present (false = off).
+export type TeamUserPermissions = Record<VisibilityPermission, boolean>
+
+// All-off — the default for a fresh membership.
+const DEFAULT_TEAM_USER_PERMISSIONS: TeamUserPermissions = { dependencies: false, security: false }
+
+// Coerce arbitrary input (a request body) into a full permission set: a key is
+// granted only when explicitly `true`; anything else (absent, non-bool) is off.
+export function parseTeamUserPermissions(x: unknown): TeamUserPermissions {
+  const o = (x == null || typeof x !== 'object') ? {} : x as Record<string, unknown>
+  const out = { ...DEFAULT_TEAM_USER_PERMISSIONS }
+  for (const p of VISIBILITY_PERMISSIONS) out[p] = o[p] === true
+  return out
+}

package/common/managed/report-content.ts

@@ -0,0 +1,72 @@
+import { parseLinkedFindings } from '../../client/linked-findings.js'
+import { dependencyDirectory, isDependencyFile } from '../../client/dependency-paths.js'
+import { detectFormat, loadFindings, parseCodexCsvToScans, readReport, reportEntries, reportRepoGithub } from '@preventive/report'
+import { commonFileDirectory } from './repository-alias.ts'
+
+// A managed blob retains one server identity even when a CSV contains several
+// scans. Keep all their findings (and upstream ids) under that identity. CSV
+// repository columns describe findings, not an embedded report-level location.
+export function readManagedReport(content: string, filename: string): ReturnType<typeof readReport> {
+  const links = content.trimStart().startsWith('[') ? parseLinkedFindings(content) : null
+  if (links) return { data: { source: 'links', findings: [], links: links.groups }, format: 'links', reason: null }
+  const parsed = readReport(content)
+  // Permission-filtered responses can be JSON under the original CSV filename.
+  if (parsed.data != null || detectFormat(content, filename) !== 'codex') return parsed
+  try {
+    const scans = parseCodexCsvToScans(content)
+    return {
+      data: { type: 'security', source: 'codex-security', findings: scans.flatMap((scan) => scan.data.findings) },
+      format: 'codex', reason: null,
+    }
+  } catch (err) {
+    return { data: null, format: null, reason: err instanceof Error ? err.message : 'Invalid Codex CSV' }
+  }
+}
+
+export function loadManagedFindings(content: string, filename: string): ReturnType<typeof loadFindings> {
+  const parsed = readManagedReport(content, filename)
+  return parsed.data == null ? Promise.resolve(null) : loadFindings(JSON.stringify(parsed.data))
+}
+
+// Source access follows individual visible members, not their shared finding
+// IDs: another member with the same ID can cite files the viewer cannot see.
+export function managedFindingSourcePaths(findings: unknown[]): Set<string> {
+  const paths = new Set<string>()
+  for (const finding of findings) {
+    if (!finding || typeof finding !== 'object') continue
+    const f = finding as { file?: unknown; evidence?: { file?: unknown }[] }
+    if (typeof f.file === 'string' && f.file) paths.add(f.file)
+    for (const evidence of Array.isArray(f.evidence) ? f.evidence : []) {
+      if (typeof evidence?.file === 'string' && evidence.file) paths.add(evidence.file)
+    }
+  }
+  return paths
+}
+
+// The report's own findings, in either entry shape, outside the dependency
+// directory the local report view would choose: node_modules, else vendor,
+// else dependencies.
+function ownFindings(data: unknown) {
+  const objects = (reportEntries(data) ?? []).flat().filter((finding): finding is { file?: unknown } => finding != null && typeof finding === 'object')
+  const directory = dependencyDirectory([{ groups: [objects], tree: (data as { tree?: unknown } | null)?.tree }])
+  return { directory, own: objects.filter(finding => !isDependencyFile(finding.file, directory)) }
+}
+
+// Findings name the repository of their own file. Like the local report view,
+// a report without its own repository belongs to the one repository named by
+// its own findings (Claude Security and Codex exports name one on every finding).
+export function findingsRepository(data: unknown): string | null {
+  const repos = new Map<string, string>()
+  for (const finding of ownFindings(data).own) {
+    const github = reportRepoGithub(finding)
+    if (github) repos.set(github.toLowerCase(), github)
+  }
+  return repos.size === 1 ? [...repos.values()][0]! : null
+}
+
+// The directory shared by the files the report's own findings cite, for alias
+// matching. Dependency paths, including cited evidence, cannot hide it.
+export function ownFileDirectory(data: unknown): string {
+  const { directory, own } = ownFindings(data)
+  return commonFileDirectory([...managedFindingSourcePaths(own)].filter(path => !isDependencyFile(path, directory)))
+}

package/common/managed/report-filter.ts

@@ -0,0 +1,109 @@
+// Apply report permissions before serving findings, triage, or source files.
+// Security uses the same complete-row classification as the UI. Dependency
+// access is per finding: App, own source, and the own-source organizations stay.
+import { inheritReportMeta, isAppFinding, reportRepoGithub, stampSecurityGroups } from '@preventive/report'
+import { readManagedReport } from './report-content.ts'
+import { revalidationLinks, securityLinks } from '../security-links.js'
+
+export interface ViewerPermissions {
+  dependencies: boolean
+  security: boolean
+}
+
+type Finding = Record<string, unknown>
+function object(value: unknown): Finding | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Finding : null
+}
+function pathOf(finding: Finding): string {
+  return typeof finding['file'] === 'string' ? finding['file'].replaceAll('\\', '/') : ''
+}
+function isDependency(finding: Finding): boolean {
+  return /(?:^|\/)(?:node_modules|vendor|dependencies)(?:\/|$)/u.test(pathOf(finding))
+}
+function githubOrg(value: unknown): string | null {
+  return reportRepoGithub(value)?.split('/')[0]?.toLowerCase() ?? null
+}
+function npmScope(finding: Finding, fromPath = false): string | null {
+  let name = object(object(finding['package'])?.['npm'])?.['name']
+  if (typeof name !== 'string' && fromPath) {
+    const parts = pathOf(finding).split('/')
+    for (let i = parts.length - 3; i >= 0; i--) {
+      if (['node_modules', 'vendor', 'dependencies'].includes(parts[i]!)) {
+        name = `${parts[i + 1]}/${parts[i + 2]}`
+        break
+      }
+    }
+  }
+  return typeof name === 'string' ? /^(@[^/\s]+)\/[^/\s]+$/u.exec(name)?.[1] ?? null : null
+}
+
+// Parsed projections keep run inheritance and derived flags out of cached
+// reports. A known positive security stamp may include linked findings outside
+// this report; a negative stamp never overrides the intrinsic classifier.
+export function projectFinding(value: unknown, report: Finding): Finding | null {
+  const original = object(value)
+  if (!original) return null
+  const finding = { ...original }
+  inheritReportMeta(finding, report)
+  finding['_source'] = finding['source'] ?? report['source'] ?? null
+  if (!('isApp' in finding)) finding['isApp'] = isAppFinding(finding, finding['_source'])
+  if (finding['isSecurity'] === true) finding['security'] = true
+  return finding
+}
+
+// Native JSON and supported text imports obey the same permission rules.
+// A filtered text import is returned as JSON under its original filename, which
+// readManagedReport already accepts. Unchanged inputs keep their original bytes.
+export function filterReportContent(content: string, perms: ViewerPermissions, filename = '', repo?: unknown): string {
+  if (perms.dependencies && perms.security) return content
+  let data: unknown
+  try { data = JSON.parse(content) } catch {
+    const parsed = readManagedReport(content, filename)
+    if (parsed.data == null) {
+      if (/\.csv$/iu.test(filename)) throw new Error('Cannot filter unreadable CSV report')
+      return content
+    }
+    data = parsed.data
+  }
+  const filtered = filterReportData(data, perms, repo)
+  return filtered === data ? content : JSON.stringify(filtered)
+}
+
+// repo, when supplied, is the server's authoritative assignment (including an
+// explicit unassigned value). Finding-specific repos still describe their source.
+export function filterReportData(data: unknown, perms: ViewerPermissions, repo?: unknown, securityIds?: Set<string>): unknown {
+  if (perms.dependencies && perms.security) return data
+  const report = object(data)
+  if (!report) return data
+  const key = Array.isArray(report['findings']) ? 'findings' : Array.isArray(report['groups']) ? 'groups' : null
+  if (!key) return data
+  const entries = (report[key] as unknown[]).map(entry => ({
+    entry, members: (Array.isArray(entry) ? entry : [entry]).map(original => ({ original, finding: projectFinding(original, report) })),
+  }))
+  const groups = entries.map(({ members }) => members.flatMap(({ finding }) => finding ? [finding] : []))
+  if (!perms.security) stampSecurityGroups(groups, { linkedIds: securityLinks(revalidationLinks(groups.flat())).linkedIds })
+  const githubOrgs = new Set<string>(), npmScopes = new Set<string>()
+  const addOrgs = (finding: Finding) => {
+    const github = githubOrg(finding), npm = npmScope(finding)
+    if (github) githubOrgs.add(github)
+    if (npm) npmScopes.add(npm)
+  }
+  addOrgs({ ...report, repo: repo === undefined ? report['repo'] : repo })
+  for (const finding of groups.flat()) {
+    if (finding['isApp'] !== true && !isDependency(finding)) addOrgs(finding)
+  }
+  const kept: unknown[] = []
+  let changed = false
+  for (const { entry, members } of entries) {
+    // Classify the complete row before hiding dependency components.
+    if (!perms.security && members.some(({ finding }) => finding?.['isSecurity'] === true || securityIds?.has(String(finding?.['id'])))) { changed = true; continue }
+    const visible = members.filter(({ finding }) => !finding || perms.dependencies || finding['isApp'] === true || !isDependency(finding)
+      || githubOrgs.has(githubOrg(finding) ?? '') || npmScopes.has(npmScope(finding, true) ?? ''))
+    if (visible.length === members.length) kept.push(entry)
+    else {
+      changed = true
+      if (visible.length > 0) kept.push(Array.isArray(entry) ? visible.map(({ original }) => original) : visible[0]!.original)
+    }
+  }
+  return changed ? { ...report, [key]: kept } : data
+}

package/common/managed/repository-alias.ts

@@ -0,0 +1,65 @@
+export interface RepositoryAliasInput {
+  oldRepo: string
+  oldPath: string
+  repoId: number
+  newPath: string
+}
+
+function containsPath(parent: string, path: string) {
+  return !parent || path === parent || path.startsWith(`${parent}/`)
+}
+
+function aliasLocation(alias: RepositoryAliasInput, directory: string) {
+  if (containsPath(alias.oldPath, directory)) {
+    const suffix = directory.slice(alias.oldPath.length).replace(/^\//u, '')
+    return { directory: [alias.newPath, suffix].filter(Boolean).join('/'), filePrefix: '' }
+  }
+  if (!containsPath(directory, alias.oldPath)) return null
+  const filePrefix = alias.oldPath.slice(directory.length).replace(/^\//u, '')
+  // This suffix is already in every file path. The destination must preserve
+  // it, so mapping needs only a new directory, never a file-path rewrite.
+  if (alias.newPath === filePrefix) return { directory: '', filePrefix }
+  if (!alias.newPath.endsWith(`/${filePrefix}`)) return null
+  return { directory: alias.newPath.slice(0, -filePrefix.length - 1), filePrefix }
+}
+
+// Match directory boundaries, keeping any subdirectory below the alias. A
+// shared file prefix can prove a more specific alias applies without changing
+// those files. The most specific applicable source wins, once, never chained.
+export function matchRepositoryAlias(github: string, directory: string, aliases: readonly RepositoryAliasInput[], filePrefix = '') {
+  let match: { repoId: number; directory: string } | null = null, specificity = -1
+  for (const alias of aliases) {
+    if (alias.oldRepo.toLowerCase() !== github.toLowerCase()) continue
+    const location = aliasLocation(alias, directory)
+    if (!location || !containsPath(location.filePrefix, filePrefix) || alias.oldPath.length <= specificity) continue
+    match = { repoId: alias.repoId, directory: location.directory }
+    specificity = alias.oldPath.length
+  }
+  return match
+}
+
+// Run before decoding a bundle's inventory: unrelated repos/directories and
+// mappings without the required common suffix cannot benefit from its paths.
+export function repositoryAliasNeedsFilePrefix(github: string, directory: string, aliases: readonly RepositoryAliasInput[]) {
+  return aliases.some(alias => alias.oldRepo.toLowerCase() === github.toLowerCase()
+    && Boolean(aliasLocation(alias, directory)?.filePrefix))
+}
+
+// Whole directory segments only; no source bodies, hashing, or path rewriting.
+// A single file still proves its parent prefix. Stop as soon as none is shared.
+export function commonFileDirectory(paths: Iterable<string>): string {
+  let prefix: string[] | undefined
+  for (const path of paths) {
+    const parts = path.split('/')
+    if (parts.some(part => !part || part === '.' || part === '..') || path.includes('\\')) return ''
+    parts.pop()
+    if (prefix === undefined) prefix = parts
+    else {
+      let length = 0
+      while (length < prefix.length && length < parts.length && prefix[length] === parts[length]) length++
+      prefix.length = length
+    }
+    if (prefix.length === 0) return ''
+  }
+  return prefix?.join('/') ?? ''
+}

package/common/managed/roles.ts

@@ -0,0 +1,35 @@
+// Managed-mode user roles, shared by the managed server (which stores +
+// validates them) and the admin client (the role picker). A linear privilege
+// ladder, highest first:
+//   admin  — full access incl. managing other users' roles
+//   manage — owned/team content management
+//   triage — can triage findings
+//   view   — read-only
+//   none   — no access
+// Admins manage workspace access. Managers handle owned uploads and content
+// in their teams; repository changes also require repository/path access. View
+// is the floor for reading content, triage for annotating accessible reports.
+// None cannot read or mutate managed data, regardless of ownership or teams.
+export type Role = 'admin' | 'manage' | 'triage' | 'view' | 'none'
+
+export const ROLES: readonly Role[] = ['admin', 'manage', 'triage', 'view', 'none']
+
+export function isRole(x: unknown): x is Role {
+  return typeof x === 'string' && (ROLES as readonly string[]).includes(x)
+}
+
+// True iff `role` sits at or above `min` in the privilege ladder. ROLES is
+// ordered highest-first, so a lower index is more privileged; an unknown role
+// (index -1) is never "at least" anything. e.g. roleAtLeast(role, 'view') is
+// "has at least read access" (everything except 'none').
+export function roleAtLeast(role: Role, min: Role): boolean {
+  const r = ROLES.indexOf(role)
+  return r !== -1 && r <= ROLES.indexOf(min)
+}
+
+// Who reads connected repositories' code (the code viewer): a team member,
+// view or above, the server reading only what their team grants reach and
+// their own GitHub account may read. A public link reads none.
+export function canReadRepositoryCode(session: { role: Role; publicShare?: boolean } | null | undefined): boolean {
+  return session != null && !session.publicShare && roleAtLeast(session.role, 'view')
+}

package/common/managed/routes.d.ts

@@ -0,0 +1,2 @@
+// The static server only needs to recognise managed pages, not resolve them.
+export function parseManagedRoute(url: URL): { view: string } | null