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

package/common/managed/routes.js

@@ -0,0 +1,359 @@
+// Managed client pages only. API paths and E2E share hashes are not routes.
+import { BUNDLE_TABS } from '../bundle-tabs.js'
+import { MAX_FINDING_ID_LENGTH, isLinkableFindingId } from '../finding-id.js'
+import { isNpmPackageName, isNpmPackageSpec, isPatchHash, isPatchPath } from './npm-packages.js'
+
+// How Compare reviews the changes, past its Overview: `code`, beside the
+// tree of changed files. A link names the mode after the bundle or version
+// compared with; an older one's `diff`, a mode since folded into Code,
+// opens Code.
+const COMPARE_MODES = new Set(['code', 'diff'])
+export const compareModeOf = mode => COMPARE_MODES.has(mode) ? 'code' : 'overview'
+// A route's `compareMode` field, where `mode` is one; none for the Overview.
+export const compareModeField = mode => COMPARE_MODES.has(mode) ? { compareMode: 'code' } : {}
+const compareModeSuffix = mode => COMPARE_MODES.has(mode) ? '/code' : ''
+
+export const MANAGED_PAGES = Object.freeze({
+  manage: '/manage',
+  'manage-bundles': '/manage/bundle',
+  'manage-scans': '/manage/scans',
+  'manage-reports': '/manage/report',
+  'manage-repos': '/manage/repositories',
+  'manage-repo-risk': '/manage/repositories/risk',
+  'admin-users': '/manage/users',
+  'manage-teams': '/manage/team',
+  'manage-import': '/manage/import',
+  'manage-links': '/manage/links',
+  'manage-deduplication': '/manage/deduplication',
+  'manage-history': '/manage/history',
+})
+
+// A team's lists, each at /team/<slug>/<what it lists>; its dependencies'
+// sub-tabs past the first at /team/<slug>/dependencies/<tab>.
+const WORKSPACE_CONTENT_VIEWS = new Set(['workspace-reports', 'workspace-bundles', 'workspace-repositories', 'workspace-dependencies'])
+export const DEPENDENCY_TABS = new Set(['pulls', 'versions', 'branch', 'reviews'])
+// A route's `dependencyTab` field, where it names one.
+const dependencyTabField = route => route.view === 'workspace-dependencies' && route.dependencyTab != null ? { dependencyTab: route.dependencyTab } : {}
+
+// Dot-only path components are normalised away by URL parsers, even escaped.
+function findingPath(id) {
+  if (!isLinkableFindingId(id) || id === '.' || id === '..') return null
+  try { return `/finding/${encodeURIComponent(id)}` } catch { return null }
+}
+
+export function managedRoutePath(route) {
+  if (!route) return null
+  if (route.view === 'home') return '/'
+  if (route.view === 'reviews') return '/my/reviews'
+  if (route.view === 'profile') return '/my/profile'
+  if (route.view === 'npm') return npmPackagePath(route)
+  if (route.view === 'repository-code') return repositoryCodePath(route)
+  if (WORKSPACE_CONTENT_VIEWS.has(route.view)) {
+    const tab = dependencyTabField(route).dependencyTab ?? 'pulls'
+    if (!/^[A-Za-z0-9_-]+$/u.test(route.teamSlug ?? '') || !DEPENDENCY_TABS.has(tab)) return null
+    return `/team/${route.teamSlug}/${route.view.slice(10)}${tab === 'pulls' ? '' : `/${tab}`}`
+  }
+  if (route.view === 'bundles') {
+    if (!/^[A-Za-z0-9_-]+$/u.test(route.bundleSlug ?? '')
+        || [route.teamSlug, route.compareSlug].some(slug => slug != null && !/^[A-Za-z0-9_-]+$/u.test(slug))) return null
+    const tab = route.bundleTab ?? 'overview'
+    if (!BUNDLE_TABS.has(tab)) return null
+    const parent = route.teamSlug ? `/team/${route.teamSlug}` : '/manage'
+    // Code names its open file by number: 1-based in the bundle's sorted
+    // sources, which its content hash fixes. Never by path from the bundle.
+    // Its marked lines follow in the fragment, as #L42 or #L42-L69.
+    const file = tab === 'code' && isLineNumber(route.file) ? `/${route.file}` : ''
+    const lines = file && isLineNumber(route.line)
+      ? `#L${route.line}${isLineNumber(route.endLine) && route.endLine > route.line ? `-L${route.endLine}` : ''}` : ''
+    // Compare names the bundle compared with by its slug, then its mode
+    // (COMPARE_MODES) past the Overview.
+    const compare = tab === 'compare' && route.compareSlug != null
+      ? `/${route.compareSlug}${compareModeSuffix(route.compareMode)}` : ''
+    return `${parent}/bundle/${route.bundleSlug}${tab === 'overview' ? '' : `/${tab}`}${file}${compare}${lines}`
+  }
+  if (Object.hasOwn(MANAGED_PAGES, route.view)) {
+    const path = MANAGED_PAGES[route.view]
+    if (route.view === 'manage-deduplication' && route.linkId) return `${path}?report=${encodeURIComponent(route.linkId)}`
+    if (route.view === 'manage-bundles' && Number.isSafeInteger(route.createRepoId) && route.createRepoId > 0) return `${path}?createRepo=${route.createRepoId}`
+    if (route.view === 'manage-scans' && route.scanMode === 'link') return `${path}?mode=link`
+    if (route.view === 'manage-scans' && route.bundleId) {
+      return `${path}?bundle=${encodeURIComponent(route.bundleId)}${route.scanMode === 'dependencies' ? '&mode=dependencies' : ''}`
+    }
+    return route.view === 'manage-history' && route.actor ? `${path}?actor=${encodeURIComponent(route.actor)}` : path
+  }
+  if (!['findings', 'files'].includes(route.view) || !route.teamSlug
+      || [route.teamSlug, route.reportSlug].some(id => id != null && !/^[A-Za-z0-9_-]+$/u.test(id))) return null
+  const team = `/team/${encodeURIComponent(route.teamSlug)}`
+  const report = route.reportSlug ? `/report/${encodeURIComponent(route.reportSlug)}` : ''
+  if (route.finding) {
+    const suffix = findingPath(route.finding.id)
+    return route.view === 'findings' && suffix ? `${team}${report}${suffix}` : null
+  }
+  return `${team}${report}${route.view === 'files' ? '/files' : ''}`
+}
+
+// The npm viewer: its lookup page, or a package version's Overview, Code,
+// Search, Compare or Treemap tab, `/npm/<name>[@<version or dist-tag>][/<tab>…]`. Code names
+// its file by number and its lines in the fragment, as a bundle's Code
+// does: `/code/<file>#L4`. Compare names the version compared with, then
+// its mode past the Overview: `/compare/<version>/code` or `/diff`. Review
+// names the version reviewed against, and, of a version as a pnpm patch
+// changes it, the patch (`patch`): its hash, and where it is read, a
+// repository by its id, a commit and its file's path there,
+// `?patch=<hash>&repo=<repo id>&commit=<commit>&path=<path>`.
+export const NPM_TABS = new Set(['overview', 'code', 'search', 'compare', 'review', 'treemap'])
+// A patch as the server reads one (server-managed/npm-patch.ts requestedPatch).
+const isPatch = patch => isPatchHash(patch?.hash) && isRepoId(patch.repoId) && COMMIT.test(patch.commit ?? '') && isPatchPath(patch.path)
+function npmPackagePath(route) {
+  if (route.packageName == null) return '/npm'
+  const tab = route.bundleTab ?? 'overview'
+  if (!isNpmPackageName(route.packageName) || (route.packageSpec != null && !isNpmPackageSpec(route.packageSpec)) || !NPM_TABS.has(tab)
+      || (route.compareSpec != null && !isNpmPackageSpec(route.compareSpec))) return null
+  if (tab === 'review') {
+    if (route.reviewPackage != null && !isNpmPackageName(route.reviewPackage) || route.reviewSpec != null && !isNpmPackageSpec(route.reviewSpec)
+      || route.patch != null && !isPatch(route.patch)) return null
+    const base = route.reviewPackage == null ? '' : `/${route.reviewPackage}${route.reviewSpec == null ? '' : `@${route.reviewSpec}`}`
+    const patch = route.patch == null ? ''
+      : `?patch=${route.patch.hash}&repo=${route.patch.repoId}&commit=${route.patch.commit}&path=${route.patch.path.split('/').map(encodeURIComponent).join('/')}`
+    return `/npm/${route.packageName}${route.packageSpec == null ? '' : `@${route.packageSpec}`}/review${base}${patch}`
+  }
+  const file = tab === 'code' && isLineNumber(route.file) ? `/${route.file}` : ''
+  const lines = file && isLineNumber(route.line)
+    ? `#L${route.line}${isLineNumber(route.endLine) && route.endLine > route.line ? `-L${route.endLine}` : ''}` : ''
+  const compare = tab === 'compare' && route.compareSpec != null ? `/${route.compareSpec}${compareModeSuffix(route.compareMode)}` : ''
+  return `/npm/${route.packageName}${route.packageSpec == null ? '' : `@${route.packageSpec}`}${tab === 'overview' ? '' : `/${tab}`}${file}${compare}${lines}`
+}
+
+function parseNpmRoute(path, hash, search) {
+  const review = /^\/npm\/((?:@[^/@]+\/)?[^/@]+)(?:@([^/]+))?\/review(?:\/((?:@[^/@]+\/)?[^/@]+)(?:@([^/]+))?)?$/u.exec(path)
+  if (review) {
+    if (!isNpmPackageName(review[1]) || review[2] != null && !isNpmPackageSpec(review[2])
+      || review[3] != null && !isNpmPackageName(review[3]) || review[4] != null && !isNpmPackageSpec(review[4])) return null
+    // The full dependency form is canonical; a bare version is a shortcut.
+    const versionOnly = review[3] && /^\d+\.\d+\.\d+(?:[-+].*)?$/u.test(review[3]) && review[4] == null
+    const patch = search.has('patch')
+      ? { hash: search.get('patch'), repoId: /^[1-9]\d*$/u.test(search.get('repo') ?? '') ? Number(search.get('repo')) : null, commit: search.get('commit'), path: search.get('path') } : null
+    if (patch && !isPatch(patch)) return null
+    return { view: 'npm', packageName: review[1], packageSpec: review[2] ?? null, bundleTab: 'review',
+      ...(review[3] ? { reviewPackage: versionOnly ? review[1] : review[3], reviewSpec: versionOnly ? review[3] : review[4] ?? null } : {}), ...(patch ? { patch } : {}) }
+  }
+  const match = /^\/npm(?:\/((?:@[^/@]+\/)?[^/@]+)(?:@([^/]+))?(?:\/(code|search|compare|treemap)(?:\/([^/]+)(?:\/([a-z]+))?)?)?)?$/u.exec(path)
+  if (!match) return undefined
+  if (match[1] == null) return { view: 'npm' }
+  if (!isNpmPackageName(match[1]) || (match[2] != null && !isNpmPackageSpec(match[2]))) return null
+  const route = { view: 'npm', packageName: match[1], packageSpec: match[2] ?? null, bundleTab: match[3] ?? 'overview' }
+  if (match[4] == null) return route
+  if (route.bundleTab === 'compare') {
+    return isNpmPackageSpec(match[4]) && (match[5] == null || COMPARE_MODES.has(match[5])) ? { ...route, compareSpec: match[4], ...compareModeField(match[5]) } : null
+  }
+  if (route.bundleTab !== 'code') return null
+  const file = Number(match[4])
+  return !match[5] && /^[1-9]\d*$/u.test(match[4]) && Number.isSafeInteger(file) ? { ...route, file, ...codeLines(hash) } : null
+}
+
+// The code viewer: a directory of a repository at a commit, on its Code,
+// Search, Treemap, Compare, Commits, Issues, Pull requests, Agents, Pulse
+// or Replay tab, `/repo/<repo id>/<commit>[/<tab>…][?path=<directory>]`,
+// the repository's root where it names no directory. Code, the tab a bare
+// link opens, names its file by number and its lines in the fragment, as a
+// bundle's Code does: `/code/<file>#L4`. Compare names the commit compared
+// with, then its mode past the Overview, as an npm version's does:
+// `/compare/<commit>/code`. An Activity view names its sub-tab past the
+// first (isActivitySubtab): `/pulse/year`. Without a commit,
+// `/repo/<repo id>[?path=<directory>]`, it opens on the default
+// branch's head, or on the revision a route held in memory names (`ref`),
+// and its route then names the commit it opened. Links from before it moved
+// name it under `/manage/code/`, and open the same.
+export const REPOSITORY_CODE_TABS = new Set(['code', 'search', 'treemap', 'compare', 'commits', 'issues', 'pulls', 'agents', 'pulse', 'replay'])
+// The tabs reading none of the directory's files, which a directory at a
+// commit shows alone.
+export const REPOSITORY_FILELESS_TABS = new Set(['commits', 'issues', 'pulls', 'agents', 'pulse', 'replay'])
+// The Activity views' sub-tabs past their first: Issues' and Pull requests'
+// closed ones (open, the first), Pulse's periods (a month, the first),
+// Replay's commits played (the last 300, the first), and one agent's
+// sessions, by its id (every agent's, `all`, the first).
+const ACTIVITY_SUBTABS = new Map([['issues', new Set(['closed'])], ['pulls', new Set(['closed'])],
+  ['pulse', new Set(['week', 'quarter', 'year'])], ['replay', new Set(['100', '1000'])]])
+const AGENT_ID = /^[a-z][a-z\d-]{0,31}$/u
+export const isActivitySubtab = (tab, subtab) => tab === 'agents' ? typeof subtab === 'string' && AGENT_ID.test(subtab) && subtab !== 'all'
+  : ACTIVITY_SUBTABS.get(tab)?.has(subtab) === true
+const COMMIT = /^[a-f\d]{40}$/u
+const MAX_DIRECTORY = 500
+const isRepoId = value => Number.isSafeInteger(value) && value > 0
+
+// A directory as the server takes one (server-managed/repo-path.ts), in its
+// canonical form: `''` the root, else names with no empty, `.` or `..` one
+// among them, nor control characters, backslashes or spaces around one.
+export function isRepositoryDirectory(path) {
+  return typeof path === 'string' && (path === '' || path.length <= MAX_DIRECTORY && !/[\p{Cc}\\]/u.test(path)
+    && path.split('/').every(part => part !== '' && part !== '.' && part !== '..' && part === part.trim()))
+}
+
+function repositoryCodePath(route) {
+  const tab = route.bundleTab ?? 'code'
+  const path = route.path ?? ''
+  if (!isRepoId(route.repoId) || (route.commit != null && !COMMIT.test(route.commit)) || !isRepositoryDirectory(path) || !REPOSITORY_CODE_TABS.has(tab)
+      || (route.compareCommit != null && !COMMIT.test(route.compareCommit))) return null
+  const directory = path ? `?path=${path.split('/').map(encodeURIComponent).join('/')}` : ''
+  if (route.commit == null) return `/repo/${route.repoId}${directory}`
+  const file = tab === 'code' && isLineNumber(route.file) ? `/code/${route.file}` : tab === 'code' ? '' : `/${tab}`
+  const compare = tab === 'compare' && route.compareCommit != null ? `/${route.compareCommit}${compareModeSuffix(route.compareMode)}` : ''
+  const subtab = isActivitySubtab(tab, route.subtab) ? `/${route.subtab}` : ''
+  const lines = tab === 'code' && isLineNumber(route.file) && isLineNumber(route.line)
+    ? `#L${route.line}${isLineNumber(route.endLine) && route.endLine > route.line ? `-L${route.endLine}` : ''}` : ''
+  return `/repo/${route.repoId}/${route.commit}${file}${compare}${subtab}${directory}${lines}`
+}
+
+function parseRepositoryCodeRoute(url) {
+  const match = /^\/(?:repo|manage\/code)\/([1-9]\d*)(?:\/([a-f\d]{40})(?:\/(code|search|treemap|compare|commits|history|issues|pulls|agents|pulse|replay)(?:\/([^/]+)(?:\/([a-z]+))?)?)?)?$/u
+    .exec(url.pathname.replace(/\/$/u, ''))
+  if (!match) return undefined
+  const repoId = Number(match[1])
+  const path = url.searchParams.get('path') ?? ''
+  // Commits' tab was History's, `/history`, which links still name.
+  const tab = match[3] === 'history' ? 'commits' : match[3] ?? 'code'
+  if (!isRepoId(repoId) || !isRepositoryDirectory(path)) return null
+  const route = { view: 'repository-code', repoId, commit: match[2] ?? null, path, bundleTab: tab }
+  if (match[4] == null) return route
+  if (tab === 'compare') {
+    return COMMIT.test(match[4]) && (match[5] == null || COMPARE_MODES.has(match[5])) ? { ...route, compareCommit: match[4], ...compareModeField(match[5]) } : null
+  }
+  if (REPOSITORY_FILELESS_TABS.has(tab)) return match[5] == null && isActivitySubtab(tab, match[4]) ? { ...route, subtab: match[4] } : null
+  const file = Number(match[4])
+  return tab === 'code' && match[5] == null && /^[1-9]\d*$/u.test(match[4]) && Number.isSafeInteger(file) ? { ...route, file, ...codeLines(url.hash) } : null
+}
+
+function isLineNumber(value) {
+  return Number.isSafeInteger(value) && value > 0
+}
+
+// `#L42` or `#L42-L69`, in either order; anything else marks no lines.
+function codeLines(hash) {
+  const match = /^#L([1-9]\d*)(?:-L([1-9]\d*))?$/u.exec(hash)
+  const [first, last] = match ? [Number(match[1]), Number(match[2] ?? match[1])] : []
+  if (!isLineNumber(first) || !isLineNumber(last)) return {}
+  return first === last ? { line: first } : { line: Math.min(first, last), endLine: Math.max(first, last) }
+}
+
+export function parseManagedRoute(url) {
+  const path = url.pathname.replace(/\/$/u, '') || '/'
+  if (path === '/' || path === '/index.html') return { view: 'home' }
+  if (path === '/my/reviews') return { view: 'reviews' }
+  // Linking an account lands here, naming why GitHub's answer was refused,
+  // which the page shows once: the address it settles on drops it.
+  if (path === '/my/profile') {
+    const linkError = url.searchParams.get('link-error')
+    return { view: 'profile', ...(linkError && /^[a-z-]{1,64}$/u.test(linkError) ? { linkError } : {}) }
+  }
+  const view = Object.keys(MANAGED_PAGES).find(key => MANAGED_PAGES[key] === path)
+  if (view) {
+    const createRepoId = Number(url.searchParams.get('createRepo'))
+    return { view,
+      ...(view === 'manage-deduplication' && url.searchParams.get('report') ? { linkId: url.searchParams.get('report') } : {}),
+      ...(view === 'manage-bundles' && Number.isSafeInteger(createRepoId) && createRepoId > 0 ? { createRepoId } : {}),
+      ...(view === 'manage-history' && url.searchParams.get('actor') ? { actor: url.searchParams.get('actor') } : {}),
+      ...(view === 'manage-scans' ? url.searchParams.get('mode') === 'link' ? { scanMode: 'link' }
+        : url.searchParams.get('bundle') ? { bundleId: url.searchParams.get('bundle'),
+          ...(url.searchParams.get('mode') === 'dependencies' ? { scanMode: 'dependencies' } : {}) } : {} : {}),
+    }
+  }
+  const bundle = /^(?:\/team\/([A-Za-z0-9_-]+)|\/manage)\/bundle\/([A-Za-z0-9_-]+)(?:\/([a-z]+)(?:\/([A-Za-z0-9_-]+)(?:\/([a-z]+))?)?)?$/u.exec(path)
+  if (bundle) {
+    const bundleTab = bundle[3] ?? 'overview'
+    if (!BUNDLE_TABS.has(bundleTab)) return null
+    const route = { view: 'bundles', teamSlug: bundle[1] ?? null, bundleSlug: bundle[2], bundleTab }
+    if (bundle[4] == null) return route
+    if (bundleTab === 'compare') return bundle[5] == null || COMPARE_MODES.has(bundle[5]) ? { ...route, compareSlug: bundle[4], ...compareModeField(bundle[5]) } : null
+    const file = Number(bundle[4])
+    if (bundleTab !== 'code' || bundle[5] || !/^[1-9]\d*$/u.test(bundle[4]) || !Number.isSafeInteger(file)) return null
+    return { ...route, file, ...codeLines(url.hash) }
+  }
+  const npm = parseNpmRoute(path, url.hash, url.searchParams)
+  if (npm !== undefined) return npm
+  const code = parseRepositoryCodeRoute(url)
+  if (code !== undefined) return code
+  const contentList = /^\/team\/([A-Za-z0-9_-]+)\/(reports|bundles|repositories|dependencies)$/u.exec(path)
+  if (contentList) return { view: `workspace-${contentList[2]}`, teamSlug: contentList[1] }
+  const dependencies = /^\/team\/([A-Za-z0-9_-]+)\/dependencies\/([a-z]+)$/u.exec(path)
+  if (dependencies) return DEPENDENCY_TABS.has(dependencies[2]) ? { view: 'workspace-dependencies', teamSlug: dependencies[1], dependencyTab: dependencies[2] } : null
+  const match = /^\/team\/([^/]+)(?:\/report\/([^/]+))?(?:\/(files)|\/finding\/([^/]+))?$/u.exec(path)
+  if (!match) return null
+  try {
+    const teamSlug = decodeURIComponent(match[1])
+    const reportSlug = match[2] ? decodeURIComponent(match[2]) : null
+    if ([teamSlug, reportSlug].some(id => id != null && !/^[A-Za-z0-9_-]+$/u.test(id))) return null
+    if (match[4]?.length > MAX_FINDING_ID_LENGTH * 9) return null
+    const id = match[4] ? decodeURIComponent(match[4]) : null
+    if (id != null && !findingPath(id)) return null
+    return { view: match[3] ? 'files' : 'findings', teamSlug, reportSlug, ...(id == null ? {} : { finding: { id } }) }
+  } catch { return null }
+}
+
+// URL tokens are exact server-assigned slugs. Application state and API calls
+// continue to use UUIDs; never guess IDs from suffixes or accept ID aliases.
+export function resolveManagedRoute(route, teams, adminBundles = []) {
+  if (WORKSPACE_CONTENT_VIEWS.has(route.view)) {
+    const matches = teams.filter(team => team.slug === route.teamSlug)
+    return matches.length === 1 ? { view: route.view, teamId: matches[0].id, ...dependencyTabField(route) } : null
+  }
+  if (route.view === 'bundles') {
+    const { teamSlug, bundleSlug, compareSlug, compareMode, ...rest } = route
+    const matches = teamSlug == null ? [] : teams.filter(team => team.slug === teamSlug)
+    if (teamSlug != null && matches.length !== 1) return null
+    const team = matches[0]
+    const candidates = teamSlug == null ? adminBundles : teams.flatMap(entry => entry.bundles ?? [])
+    const idsOf = slug => new Set(candidates.filter(bundle => bundle.slug === slug).map(bundle => bundle.id))
+    const ids = idsOf(bundleSlug)
+    const bundle = (team?.bundles ?? adminBundles).find(entry => entry.slug === bundleSlug)
+    if (!bundleSlug || !bundle || ids.size !== 1) return null
+    // The bundle compared with, by the same rule; one no longer listed drops
+    // out, leaving Compare to pick again.
+    const compared = compareSlug == null ? null : idsOf(compareSlug)
+    const compare = compared?.size === 1 ? { compareId: [...compared][0], ...compareModeField(compareMode) } : {}
+    return { ...rest, teamId: team?.id ?? null, bundleId: bundle.id, ...compare }
+  }
+  if (!['findings', 'files'].includes(route.view)) return route
+  const { teamSlug, reportSlug, ...rest } = route
+  const matches = teams.filter(team => team.slug === teamSlug)
+  if (!teamSlug || matches.length !== 1) return null
+  const team = matches[0]
+  if (reportSlug == null) return { ...rest, teamId: team.id, reportId: null }
+  const reports = teams.flatMap(entry => entry.reports ?? []).filter(report => report.slug === reportSlug)
+  const ids = new Set(reports.map(report => report.id))
+  const report = (team.reports ?? []).find(entry => entry.slug === reportSlug)
+  return report && ids.size === 1 ? { ...rest, teamId: team.id, reportId: report.id } : null
+}
+
+export function managedRouteForIds(route, teams, adminBundles = []) {
+  if (WORKSPACE_CONTENT_VIEWS.has(route.view)) {
+    const team = teams.find(entry => entry.id === route.teamId)
+    const result = { view: route.view, teamSlug: team?.slug, ...dependencyTabField(route) }
+    return team?.slug && resolveManagedRoute(result, teams) ? result : null
+  }
+  if (route.view === 'bundles') {
+    const { teamId, bundleId, compareId, compareMode, ...rest } = route
+    const team = teams.find(entry => entry.id === teamId)
+    if (teamId != null && !team?.slug) return null
+    const bundle = (team?.bundles ?? adminBundles).find(entry => entry.id === bundleId)
+    if (!bundle?.slug) return null
+    const compared = compareId == null ? null
+      : (teamId == null ? adminBundles : teams.flatMap(entry => entry.bundles ?? [])).find(entry => entry.id === compareId)
+    const result = { ...rest, teamSlug: team?.slug ?? null, bundleSlug: bundle.slug,
+      ...(compared?.slug ? { compareSlug: compared.slug, ...compareModeField(compareMode) } : {}) }
+    const resolved = resolveManagedRoute(result, teams, adminBundles)
+    if (!resolved) return null
+    // A compared bundle whose slug doesn't name it alone leaves the route.
+    if (result.compareSlug != null && resolved.compareId !== compareId) {
+      const { compareSlug: _slug, compareMode: _mode, ...bare } = result
+      return bare
+    }
+    return result
+  }
+  if (!['findings', 'files'].includes(route.view)) return route
+  const { teamId, reportId, ...rest } = route
+  const team = teams.find(entry => entry.id === teamId)
+  const report = reportId == null ? null : team?.reports?.find(entry => entry.id === reportId)
+  if (!team?.slug || (reportId != null && !report?.slug)) return null
+  const result = { ...rest, teamSlug: team.slug, reportSlug: report?.slug ?? null }
+  return resolveManagedRoute(result, teams) ? result : null
+}

package/common/managed/scan-models.ts

@@ -0,0 +1,6 @@
+import { defaultScanModels } from '../default-scan-models.ts'
+
+// Use the same starting catalogue as the UI until managed scan discovery is wired.
+const catalogue = defaultScanModels()
+export const MANAGED_SCAN_MODELS = Object.freeze(catalogue.models)
+export const DEFAULT_MANAGED_SCAN_MODEL = catalogue.defaultModel

package/common/managed/team-app.d.ts

@@ -0,0 +1,6 @@
+// Set for a team that is not App: `findings`, its rows (with `countFindings`),
+// and `appReports`, set by the managed catalog: how many reports open in App mode alone.
+export type TeamAppMetadata = { appMode: true; appFindings: number } | { appMode: false; appReports?: number; findings?: number }
+export function managedTeamAppMetadata(workspace: readonly { filename: string; data: unknown }[] & { links?: readonly (readonly string[])[] },
+  options?: { countFindings?: boolean }): TeamAppMetadata
+export function managedTeamRevalidationConflicted(workspace: readonly { filename: string; data: unknown }[] & { links?: readonly (readonly string[])[] }): boolean

package/common/managed/team-app.js

@@ -0,0 +1,47 @@
+import { inheritReportMeta, isAppFinding, reportEntries } from '@preventive/report'
+import { collectDuplicates } from '../../client/linked-findings.js'
+import { hasRevalidateStamp } from '../finding-filters.js'
+import { workspaceAppMetadata } from '../workspace-app.js'
+import { mergeReportGroups } from '../workspace-groups.js'
+
+// The same classification as local workspaces, using only the complete,
+// server-filtered published workspace: the reports of one team response and
+// its `links`. The managed server classifies each team before sending its
+// catalog, so the sidebar opens a team collapsed to its App findings at once.
+// The server backfills finding IDs before building these envelopes.
+export function managedTeamAppMetadata(workspace, options = {}) {
+  const { reports, duplicates } = viewReports(workspace)
+  return workspaceAppMetadata(reports, id => [...duplicates.get(id) ?? []], options)
+}
+
+// Whether copies of one finding in the workspace disagree on what the
+// revalidation pass said, which takes the App lens off a view of it
+// (ui/view/render.js configureReportRevalidation). Asked of all its rows, so
+// that a view of any of its reports holds none either.
+export function managedTeamRevalidationConflicted(workspace) {
+  return mergeReportGroups(viewReports(workspace).reports).conflicts.size > 0
+}
+
+// The workspace's reports as a view holds them (ui/view/ingest.js), with the
+// duplicates its links name.
+function viewReports(workspace) {
+  const duplicates = new Map(), reports = []
+  collectDuplicates(workspace.links ?? [], duplicates)
+  for (const { filename, data } of workspace) {
+    if (data.source === 'links' && Array.isArray(data.links)) {
+      collectDuplicates(data.links, duplicates)
+      continue
+    }
+    const entries = (reportEntries(data) ?? []).map(entry => Array.isArray(entry) ? entry : [entry])
+    const judged = new Set(entries.flat().filter(hasRevalidateStamp).map(f => f.source ?? data.source ?? null))
+    const groups = entries.map(group => group.map(f => {
+      const finding = { ...f, _source: f.source ?? data.source ?? null }
+      inheritReportMeta(finding, data)
+      if (!('isApp' in finding)) finding.isApp = isAppFinding(finding, finding._source)
+      finding._sourcePass = judged.has(finding._source)
+      return finding
+    }))
+    reports.push({ fileName: filename, groups })
+  }
+  return { reports, duplicates }
+}

package/common/managed/triage.ts

@@ -0,0 +1,83 @@
+// Per-finding triage annotations on a managed server — shared by the server
+// (which stores one row per finding id, validates the wire shape, and decides
+// per report which ids a viewer may read or write) and the managed client
+// (which mirrors entries into its local triage map). Keyed by finding id
+// alone, like that map: reports mostly repeat one another (a re-scan of the
+// same code carries the same finding ids), and a finding's triage is shared by
+// every report that carries it. A wire entry carries the four server-persisted
+// fields below, or is null for a cleared entry (the server's tombstone); the
+// client's `ignoredReports` deliberately does NOT ride this wire — the
+// per-report ignore is a client-local concept keyed by report name.
+export type TriageBucket = 'inprogress' | 'fixed' | 'invalid' | 'deleted' | 'ignored'
+
+const TRIAGE_BUCKETS: readonly TriageBucket[] = ['inprogress', 'fixed', 'invalid', 'deleted', 'ignored']
+
+// One finding's server-side triage entry (also the write shape — writes
+// replace the whole entry). Absent fields are unset; `flagged` is tri-state:
+// absent = never set, `true` = flagged, `false` = an explicit un-flag
+// tombstone that must round-trip (see client/state.ts TriageEntry).
+export type TriageEntryPatch = {
+  color?: string
+  triage?: TriageBucket
+  // Legacy triage history/migration only. New comments use separate records;
+  // the managed triage write endpoint rejects this field.
+  comment?: string
+  fix?: string
+  flagged?: boolean
+}
+
+// Length caps enforced at the write endpoint so one entry can't balloon a row.
+export const MAX_TRIAGE_TEXT = 10_000
+export const MAX_TRIAGE_COLOR = 50
+
+// Caps on one write request as a whole — shared with the client, which batches
+// within them: entries per request, the finding-id length (real ids are 36-char
+// uuids), and the JSON body (the server's small default is too small for entry
+// batches, which carry free text).
+export const MAX_TRIAGE_ENTRIES = 200
+export const MAX_FINDING_ID = 100
+export const MAX_TRIAGE_BODY_BYTES = 262_144
+
+// The most trail events one history read returns (newest first). Retention is
+// the server's: everything is kept unless its TRIAGE_HISTORY_LIMIT says
+// otherwise.
+export const MAX_TRIAGE_HISTORY = 200
+
+export function isTriageBucket(x: unknown): x is TriageBucket {
+  return typeof x === 'string' && (TRIAGE_BUCKETS as readonly string[]).includes(x)
+}
+
+// Coerce one wire entry (a request-body value) into a clean patch. `null`
+// means "clear the entry"; a malformed value (wrong type, unknown bucket,
+// over-cap string, non-boolean flagged) is 'invalid' so the endpoint 400s
+// rather than store garbage. Null/empty-string fields count as absent (an
+// absent field is cleared anyway under whole-entry replace); unknown keys are
+// ignored.
+export function parseTriageEntryPatch(x: unknown): TriageEntryPatch | null | 'invalid' {
+  if (x === null) return null
+  if (typeof x !== 'object' || Array.isArray(x)) return 'invalid'
+  const o = x as Record<string, unknown>
+  const out: TriageEntryPatch = {}
+  const color = o['color']
+  if (color != null) {
+    if (typeof color !== 'string' || color.length > MAX_TRIAGE_COLOR) return 'invalid'
+    if (color !== '') out.color = color
+  }
+  const triage = o['triage']
+  if (triage != null) {
+    if (!isTriageBucket(triage)) return 'invalid'
+    out.triage = triage
+  }
+  for (const key of ['comment', 'fix'] as const) {
+    const v = o[key]
+    if (v == null) continue
+    if (typeof v !== 'string' || v.length > MAX_TRIAGE_TEXT) return 'invalid'
+    if (v !== '') out[key] = v
+  }
+  const flagged = o['flagged']
+  if (flagged != null) {
+    if (typeof flagged !== 'boolean') return 'invalid'
+    out.flagged = flagged
+  }
+  return out
+}

package/common/managed/upload-seal.ts

@@ -0,0 +1,126 @@
+// Managed uploads cross TLS-terminating proxies (Cloudflare, corporate
+// gateways) that would otherwise read report and bundle bytes in plaintext.
+// The server sends each session an X25519 public key; the browser seals every
+// upload to it with a fresh ephemeral key (X25519 → HKDF-SHA-256 →
+// AES-256-GCM), so the content key itself never crosses the proxy. Text is
+// gzipped before sealing; binary content is sealed as is.
+//
+// Sealed body: version(1) | flags(1) | ephemeral public key(32), then the
+// payload in 1 MiB segments, each sealed under nonce = big-endian segment
+// index with the last byte marking the final segment. The header is the HKDF
+// salt, so altering it changes the key. Segments bound browser memory for
+// large bundles, and their nonces reject reordered, truncated or extended
+// bodies. Every upload derives its own key, so counter nonces never repeat.
+
+import { gunzipBytes } from '../gzip.js'
+import { encodeUtf8 } from '../utf8.js'
+
+// Set (to the format version) on a request whose body is sealed.
+export const UPLOAD_SEAL_HEADER = 'x-upload-encryption'
+const VERSION = 1
+const FLAG_GZIP = 1
+const CURVE = { name: 'X25519' }
+const HEADER_BYTES = 2 + 32
+const TAG_BYTES = 16
+const SEGMENT_BYTES = 1024 * 1024
+const SNIFF_BYTES = 64 * 1024
+const KEY_INFO = 'deepview-managed-upload.v1.content-key'
+
+// The largest sealed body for `maxBytes` of content. Deflate can grow
+// incompressible text slightly (its worst case is about 0.03%).
+export function maxSealedBytes(maxBytes: number): number {
+  const payload = maxBytes + Math.ceil(maxBytes / 1024) + 64
+  return HEADER_BYTES + payload + TAG_BYTES * (Math.floor(payload / SEGMENT_BYTES) + 1)
+}
+
+function nonce(index: number, final: boolean): Uint8Array<ArrayBuffer> {
+  const iv = new Uint8Array(12)
+  new DataView(iv.buffer).setUint32(7, index)
+  iv[11] = final ? 1 : 0
+  return iv
+}
+
+async function contentKey(secret: ArrayBuffer, header: Uint8Array<ArrayBuffer>, usage: KeyUsage): Promise<CryptoKey> {
+  const ikm = await crypto.subtle.importKey('raw', secret, 'HKDF', false, ['deriveKey'])
+  return await crypto.subtle.deriveKey({ name: 'HKDF', hash: 'SHA-256', salt: header, info: encodeUtf8(KEY_INFO) },
+    ikm, { name: 'AES-GCM', length: 256 }, false, [usage])
+}
+
+// Archives and other binary content would only grow under gzip. A NUL byte or
+// invalid UTF-8 in the first 64 KiB marks content as binary.
+async function isText(blob: Blob): Promise<boolean> {
+  const head = new Uint8Array(await blob.slice(0, SNIFF_BYTES).arrayBuffer())
+  if (head.includes(0)) return false
+  try { new TextDecoder('utf-8', { fatal: true }).decode(head, { stream: true }); return true }
+  catch { return false }
+}
+
+// Seal `blob` to the server's raw public key. Reads the input as a stream;
+// sealed segments are kept as Blobs, which browsers may page to disk. An abort
+// stops reading at the next chunk.
+export async function sealUpload(blob: Blob, publicKey: Uint8Array<ArrayBuffer>, signal?: AbortSignal): Promise<Blob> {
+  const gzip = await isText(blob)
+  const [server, ephemeral] = await Promise.all([
+    crypto.subtle.importKey('raw', publicKey, CURVE, false, []),
+    crypto.subtle.generateKey(CURVE, false, ['deriveBits']) as Promise<CryptoKeyPair>,
+  ])
+  const header = new Uint8Array(HEADER_BYTES)
+  header[0] = VERSION
+  header[1] = gzip ? FLAG_GZIP : 0
+  header.set(new Uint8Array(await crypto.subtle.exportKey('raw', ephemeral.publicKey)), 2)
+  const key = await contentKey(await crypto.subtle.deriveBits({ name: 'X25519', public: server }, ephemeral.privateKey, 256), header, 'encrypt')
+  const parts = [new Blob([header])], segment = new Uint8Array(SEGMENT_BYTES)
+  let filled = 0, index = 0
+  const seal = async (final: boolean) => {
+    parts.push(new Blob([await crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce(index++, final) }, key, segment.subarray(0, filled))]))
+    filled = 0
+  }
+  const stream: ReadableStream<Uint8Array> = gzip ? blob.stream().pipeThrough(new CompressionStream('gzip')) : blob.stream()
+  const reader = stream.getReader()
+  try {
+    for (let read = await reader.read(); !read.done; read = await reader.read()) {
+      signal?.throwIfAborted()
+      for (let offset = 0; offset < read.value.length;) {
+        // A full segment is final only if the input ends with it.
+        if (filled === SEGMENT_BYTES) await seal(false)
+        const length = Math.min(SEGMENT_BYTES - filled, read.value.length - offset)
+        segment.set(read.value.subarray(offset, offset + length), filled)
+        filled += length
+        offset += length
+      }
+    }
+  } catch (err) {
+    await reader.cancel(err).catch(() => {})
+    throw err
+  }
+  await seal(true)
+  return new Blob(parts)
+}
+
+// Open a sealed body with the session's private JWK. Throws 'too-large' when
+// the content exceeds `maxBytes`, else 'bad-upload' for any invalid body.
+export async function openUpload(sealed: Uint8Array<ArrayBuffer>, privateKey: JsonWebKey, maxBytes: number): Promise<Uint8Array<ArrayBuffer>> {
+  // Every segment but the last is full, so the layout follows from the length.
+  const rest = sealed.length - HEADER_BYTES
+  const count = Math.ceil(rest / (SEGMENT_BYTES + TAG_BYTES))
+  const last = rest - (count - 1) * (SEGMENT_BYTES + TAG_BYTES)
+  if (rest < TAG_BYTES || last < TAG_BYTES || sealed[0] !== VERSION || (sealed[1]! & ~FLAG_GZIP) !== 0) throw new Error('bad-upload')
+  const gzip = sealed[1] === FLAG_GZIP, plain = new Uint8Array(rest - count * TAG_BYTES)
+  if (!gzip && plain.length > maxBytes) throw new Error('too-large')
+  try {
+    const header = sealed.slice(0, HEADER_BYTES)
+    const [key, peer] = await Promise.all([
+      crypto.subtle.importKey('jwk', privateKey, CURVE, false, ['deriveBits']),
+      crypto.subtle.importKey('raw', header.slice(2), CURVE, false, []),
+    ])
+    const content = await contentKey(await crypto.subtle.deriveBits({ name: 'X25519', public: peer }, key, 256), header, 'decrypt')
+    for (let index = 0; index < count; index++) {
+      const start = HEADER_BYTES + index * (SEGMENT_BYTES + TAG_BYTES)
+      const segment = sealed.subarray(start, Math.min(start + SEGMENT_BYTES + TAG_BYTES, sealed.length))
+      plain.set(new Uint8Array(await crypto.subtle.decrypt({ name: 'AES-GCM', iv: nonce(index, index === count - 1) }, content, segment)), index * SEGMENT_BYTES)
+    }
+  } catch (err) { throw new Error('bad-upload', { cause: err }) }
+  if (!gzip) return plain
+  try { return await gunzipBytes(plain, { maxBytes }) }
+  catch (err) { throw new Error(err instanceof RangeError ? 'too-large' : 'bad-upload', { cause: err }) }
+}

package/common/pretty-print.d.ts

@@ -0,0 +1,5 @@
+// Type declarations for `common/pretty-print.js`, for `.ts` callers.
+
+export const MAX_PRETTY_BYTES: number
+export function prettyExtension(path: string): string | null
+export function needsPrettyPrint(path: string, text: string, read?: () => { category: string }): boolean