@preventive/triage 1.0.0-alpha.3 → 1.0.0-alpha.30

package/common/code-language.js

@@ -0,0 +1,51 @@
+const EXT_TO_LANG = {
+  __proto__: null,
+  js: 'javascript', mjs: 'javascript', cjs: 'javascript',
+  jsx: 'jsx',
+  ts: 'typescript', mts: 'typescript', cts: 'typescript',
+  tsx: 'tsx',
+  json: 'json',
+  css: 'css',
+  html: 'markup', htm: 'markup', xml: 'markup', svg: 'markup',
+  yml: 'yaml', yaml: 'yaml',
+  sh: 'bash', bash: 'bash',
+  md: 'markdown', markdown: 'markdown',
+  sol: 'solidity',
+  php: 'php', phtml: 'php',
+  rs: 'rust',
+  rb: 'ruby',
+  py: 'python', pyw: 'python', pyi: 'python',
+  java: 'java',
+  // .h is claimed by C, C++ and Objective-C alike. The C++ grammar
+  // extends the C one, so it is the superset that colours a header
+  // from any of the three; the C grammar would leave a C++ header's
+  // class/template/namespace keywords plain.
+  cpp: 'cpp', cc: 'cpp', cxx: 'cpp', 'c++': 'cpp',
+  hpp: 'cpp', hh: 'cpp', hxx: 'cpp', 'h++': 'cpp', h: 'cpp',
+  c: 'c',
+  m: 'objectivec', mm: 'objectivec',
+}
+
+// Stasis records loader formats as well as language names. Resolve those to
+// the grammars we ship before consulting the filename.
+const FORMAT_TO_LANG = {
+  __proto__: null,
+  module: 'javascript', commonjs: 'javascript',
+  'module-typescript': 'typescript', 'commonjs-typescript': 'typescript',
+  json: 'json', solidity: 'solidity', php: 'php', shell: 'bash', rust: 'rust',
+  java: 'java', objc: 'objectivec', objcpp: 'objectivec',
+  c: 'c', 'c-header': 'c', cpp: 'cpp', 'cpp-header': 'cpp',
+  ruby: 'ruby', podspec: 'ruby', podfile: 'ruby', fastlane: 'ruby',
+  'podfile-lock': 'yaml', xml: 'markup',
+}
+
+export function langForPath(path, format) {
+  if (typeof format === 'string' && FORMAT_TO_LANG[format]) return FORMAT_TO_LANG[format]
+  if (typeof path !== 'string') return null
+  // Only the filename can contribute an extension. A dotted directory such
+  // as `.abc/edf` is a path segment, not an extension on `edf`.
+  const basename = path.slice(path.lastIndexOf('/') + 1)
+  const dot = basename.lastIndexOf('.')
+  if (dot <= 0) return null
+  return EXT_TO_LANG[basename.slice(dot + 1).toLowerCase()] ?? null
+}

package/common/default-scan-models.ts

@@ -0,0 +1,30 @@
+// Shared starting catalogue for the UI and managed server until scan-service
+// discovery supplies supported models and effort limits. Use undated aliases.
+export function defaultScanModels(provider: string | null = null) {
+  const ids = [
+    'anthropic/claude-opus-5.5',
+    'anthropic/claude-fable-5.1',
+    'anthropic/claude-sonnet-5.5',
+    'anthropic/claude-haiku-4.5',
+    'openai/gpt-6-astra',
+    'openai/gpt-6-astra-pro',
+    'openai/gpt-6.1-sol',
+    'openai/gpt-6.1-sol-pro',
+    'openai/gpt-6-luna',
+    'openai/gpt-6-luna-pro',
+    'moonshotai/kimi-k3',
+    'google/gemini-3.8-flash',
+    'google/gemma-4-31b-it',
+    'x-ai/grok-4.7',
+    'z-ai/glm-5.3',
+    'qwen/qwen3.8-max',
+    'deepseek/deepseek-v4.1-flash',
+    'deepseek/deepseek-v4-pro',
+  ]
+  // OpenRouter routes all listed providers. Direct-provider credentials only
+  // expose that provider's models; no selection leaves the catalogue intact.
+  const prefix = provider === 'moonshot' ? 'moonshotai' : provider
+  const models = ids.filter(id => !['anthropic', 'openai', 'moonshot'].includes(provider ?? '') || id.startsWith(`${prefix}/`))
+    .map(id => ({ id, efforts: ['low', 'medium', 'high', 'xhigh', 'max'] }))
+  return { models, defaultModel: models[0]!.id }
+}

package/common/finding-id.js

@@ -0,0 +1,47 @@
+// Session-local finding ids (see `client/triage.js`'s SESSION_ID_RE:
+// purely numeric `_id` fallbacks, handed out by an in-memory counter
+// for findings whose id couldn't be derived) are re-assigned on every
+// load, so a link built on one would point at an arbitrary other
+// finding after a reload — including in the SENDER's own tab. Those are
+// refused up front rather than silently mis-resolving. Everything else
+// the app treats as persistent — the analyzer's uuids, the deterministic
+// uuids `@preventive/report/src/finding-id.js` derives, and the codex importer's
+// finding-URL ids — is linkable, which is why this is a
+// "not session-local" test rather than a uuid-shape test.
+const SESSION_ID_RE = /^\d+$/u
+
+// Control characters can't appear in a uuid, a URL, or an OPFS filename
+// the app will hand out, so their presence means a mangled / hand-crafted
+// fragment. Rejecting them keeps a stray `\n` out of an `alert()` and out
+// of the `[data-gid]` selector the reveal path builds. A scan rather than
+// a character-class regex: matching control characters in a literal is a
+// lint error (`no-control-regex`), and spelling the range out in code is
+// clearer than the escaped equivalent anyway.
+function hasControlChar(value) {
+  for (let i = 0; i < value.length; i++) {
+    const code = value.codePointAt(i)
+    if (code < 0x20 || code === 0x7f) return true
+  }
+  return false
+}
+
+// Per-component cap. The longest legitimate value is a codex finding-URL
+// id; report names and workspace ids no longer travel in the fragment at
+// all. The cap exists so a hostile fragment can't push a megabyte of
+// text through `decodeURIComponent` + the "couldn't find it" alert.
+export const MAX_FINDING_ID_LENGTH = 512
+
+function isUsablePart(value) {
+  return typeof value === 'string'
+    && value.length > 0
+    && value.length <= MAX_FINDING_ID_LENGTH
+    && !hasControlChar(value)
+}
+
+// Whether a finding id survives a reload, i.e. whether a link built on
+// it means anything tomorrow. Callers use this to decide whether to
+// OFFER a link at all (the per-finding Link button hides itself for a
+// session-local id) rather than handing out one that silently rots.
+export function isLinkableFindingId(id) {
+  return isUsablePart(id) && !SESSION_ID_RE.test(id)
+}

package/common/github-issue-labels.d.ts

@@ -0,0 +1 @@
+export function newIssueLabels(isSecurity?: boolean, configured?: string): string[]

package/common/github-issue-labels.js

@@ -0,0 +1,11 @@
+// Shared by GitHub's prefilled form and managed API issue creation.
+export function newIssueLabels(isSecurity = false, configured = '') {
+  const seen = new Set()
+  return ['deepview', ...(isSecurity ? ['security'] : []), ...configured.split(',')]
+    .map(label => label.trim()).filter(label => {
+      const key = label.toLowerCase()
+      if (!label || seen.has(key)) return false
+      seen.add(key)
+      return true
+    })
+}

package/common/github-pr.ts

@@ -0,0 +1,56 @@
+export const MAX_PULL_REQUEST_URL = 2048
+
+export interface PullRequestRef { repo: string; number: number }
+export type GithubFixRef = PullRequestRef & { kind: 'pull' | 'issue' }
+export type GithubFixStatus = 'open' | 'draft' | 'closed' | 'merged'
+export type GithubIssueClosedReason = 'completed' | 'not_planned' | 'duplicate' | 'unknown'
+export type GithubFixResult = { url: string } & (
+  { title: string; description: string | null; status: GithubFixStatus; stateReason: GithubIssueClosedReason | null } | { error: 'unavailable' }
+)
+
+// Unknown closure reasons must never imply that an issue was completed.
+export function githubIssueClosedReason(value: unknown): GithubIssueClosedReason {
+  return value === 'completed' || value === 'not_planned' || value === 'duplicate' ? value : 'unknown'
+}
+
+export function isGithubRepoName(value: string): boolean {
+  const [owner, repo, extra] = value.split('/')
+  return extra === undefined && owner !== undefined && repo !== undefined
+    && owner.length <= 39 && /^[a-zA-Z\d](?:-?[a-zA-Z\d])*$/u.test(owner)
+    && repo.length <= 100 && repo !== '.' && repo !== '..' && /^[a-zA-Z\d._-]+$/u.test(repo)
+}
+
+// Only identify the repository and PR number. This never supplies an API URL:
+// the server must match a team repository and use its stored full name.
+function parseGithubNumberedUrl(value: unknown, path: RegExp): PullRequestRef | null {
+  if (typeof value !== 'string' || value.length > MAX_PULL_REQUEST_URL) return null
+  let url: URL
+  try { url = new URL(value) } catch { return null }
+  if (url.href !== value || url.origin !== 'https://github.com' || url.username || url.password) return null
+  const match = path.exec(url.pathname)
+  if (!match) return null
+  const repo = `${match[1]}/${match[2]}`
+  const number = Number(match[3])
+  if (!isGithubRepoName(repo) || !Number.isSafeInteger(number) || number <= 0) return null
+  return { repo, number }
+}
+
+export function parseGithubPrUrl(value: unknown): PullRequestRef | null {
+  return parseGithubNumberedUrl(value, /^\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:\/(?:files|commits|checks))?\/?$/u)
+}
+
+export function parseGithubIssueUrl(value: unknown): PullRequestRef | null {
+  return parseGithubNumberedUrl(value, /^\/([^/]+)\/([^/]+)\/issues\/(\d+)\/?$/u)
+}
+
+export function parseGithubFixUrl(value: unknown): GithubFixRef | null {
+  const pr = parseGithubPrUrl(value)
+  if (pr) return { ...pr, kind: 'pull' }
+  const issue = parseGithubIssueUrl(value)
+  return issue ? { ...issue, kind: 'issue' } : null
+}
+
+// Browser-only deduplication key; never used to construct a server API call.
+export function githubFixKey(ref: GithubFixRef): string {
+  return `${ref.repo.toLowerCase()}#${ref.kind}:${ref.number}`
+}

package/common/managed/comments.ts

@@ -0,0 +1,34 @@
+// Managed comments are independent records, shared by reports containing the
+// same finding. Imported and legacy comments may lack attribution or dates.
+export interface ManagedComment {
+  id: string
+  findingId: string
+  body: string
+  authorId: string | null
+  authorLogin: string | null
+  createdAt: number | null
+  updatedAt: number | null
+  version: number
+}
+
+export const MAX_COMMENT_TEXT = 10_000
+
+// Callers also enforce write access to the report containing the finding.
+// Admins can remove comments with no linked user, but cannot claim authorship.
+export function canDeleteComment(comment: Pick<ManagedComment, 'authorId'>, actor: { id: string; role: string } | null | undefined): boolean {
+  return actor != null && (comment.authorId === actor.id || (comment.authorId == null && actor.role === 'admin'))
+}
+
+export function compareManagedComments(a: ManagedComment, b: ManagedComment): number {
+  if (a.createdAt == null && b.createdAt != null) return -1
+  if (a.createdAt != null && b.createdAt == null) return 1
+  const byDate = (a.createdAt ?? 0) - (b.createdAt ?? 0)
+  if (byDate !== 0) return byDate
+  if (a.id === b.id) return 0
+  return a.id < b.id ? -1 : 1
+}
+
+export function parseCommentBody(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length > MAX_COMMENT_TEXT) return null
+  return value.trim() || null
+}

package/common/managed/permissions.ts

@@ -0,0 +1,35 @@
+// 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.
+export const DEFAULT_TEAM_USER_PERMISSIONS: TeamUserPermissions = { dependencies: false, security: false }
+
+export function isVisibilityPermission(x: unknown): x is VisibilityPermission {
+  return typeof x === 'string' && (VISIBILITY_PERMISSIONS as readonly string[]).includes(x)
+}
+
+// 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,42 @@
+import { parseLinkedFindings } from '../../client/linked-findings.js'
+import { detectFormat, loadFindings, parseCodexCsvToScans, readReport } from '@preventive/report'
+
+// 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
+}

package/common/managed/report-filter.ts

@@ -0,0 +1,108 @@
+// 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'
+
+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)
+  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/roles.ts

@@ -0,0 +1,28 @@
+// 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)
+}

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

package/common/managed/routes.js

@@ -0,0 +1,124 @@
+// 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'
+
+export const MANAGED_PAGES = Object.freeze({
+  manage: '/manage',
+  'manage-bundles': '/manage/bundle',
+  'manage-scans': '/manage/scans',
+  'manage-reports': '/manage/report',
+  'manage-repos': '/manage/repositories',
+  'admin-users': '/manage/users',
+  'manage-teams': '/manage/team',
+  'manage-import': '/manage/import',
+  'manage-links': '/manage/links',
+  'manage-history': '/manage/history',
+})
+
+// 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 === 'bundles') {
+    if (!/^[A-Za-z0-9_-]+$/u.test(route.bundleSlug ?? '')
+        || (route.teamSlug != null && !/^[A-Za-z0-9_-]+$/u.test(route.teamSlug))) return null
+    const tab = route.bundleTab ?? 'overview'
+    if (!BUNDLE_TABS.has(tab)) return null
+    const parent = route.teamSlug ? `/team/${route.teamSlug}` : '/manage'
+    return `${parent}/bundle/${route.bundleSlug}${tab === 'overview' ? '' : `/${tab}`}`
+  }
+  if (Object.hasOwn(MANAGED_PAGES, route.view)) {
+    const path = MANAGED_PAGES[route.view]
+    if (route.view === 'manage-bundles' && Number.isSafeInteger(route.createRepoId) && route.createRepoId > 0) return `${path}?createRepo=${route.createRepoId}`
+    if (route.view === 'manage-scans' && route.bundleId) return `${path}?bundle=${encodeURIComponent(route.bundleId)}`
+    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' : ''}`
+}
+
+export function parseManagedRoute(url) {
+  const path = url.pathname.replace(/\/$/u, '') || '/'
+  if (path === '/' || path === '/index.html') return { view: 'home' }
+  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-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('bundle') ? { bundleId: url.searchParams.get('bundle') } : {}),
+    }
+  }
+  const bundle = /^(?:\/team\/([A-Za-z0-9_-]+)|\/manage)\/bundle\/([A-Za-z0-9_-]+)(?:\/([a-z]+))?$/u.exec(path)
+  if (bundle) {
+    const bundleTab = bundle[3] ?? 'overview'
+    return BUNDLE_TABS.has(bundleTab) ? { view: 'bundles', teamSlug: bundle[1] ?? null, bundleSlug: bundle[2], bundleTab } : 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 (route.view === 'bundles') {
+    const { teamSlug, bundleSlug, ...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 ids = new Set(candidates.filter(bundle => bundle.slug === bundleSlug).map(bundle => bundle.id))
+    const bundle = (team?.bundles ?? adminBundles).find(entry => entry.slug === bundleSlug)
+    return bundleSlug && bundle && ids.size === 1 ? { ...rest, teamId: team?.id ?? null, bundleId: bundle.id } : null
+  }
+  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 (route.view === 'bundles') {
+    const { teamId, bundleId, ...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 result = { ...rest, teamSlug: team?.slug ?? null, bundleSlug: bundle.slug }
+    return resolveManagedRoute(result, teams, adminBundles) ? result : null
+  }
+  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