@preventive/triage 1.0.0-alpha.19 → 1.0.0-alpha.20

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 '../../report/index.js'
+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,121 @@
+// 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-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) {
+    return { view,
+      ...(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

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'
+
+export const TRIAGE_BUCKETS: readonly TriageBucket[] = ['inprogress', 'fixed', 'invalid', 'deleted']
+
+// 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/out/index.html

@@ -110,6 +110,10 @@
         <span class="drop-local-copy">Review locally in your browser. Sync across devices when you need it.</span>
       </p>
     </div>
+    <a class="landing-github-link" href="https://github.com/PreventiveMeasures/triage" target="_blank" rel="noopener noreferrer">
+      <span class="drop-supported-icon" data-icon="github" aria-hidden="true"></span>
+      <span>GitHub</span>
+    </a>
   </div>
   <div id="report"></div>
 </main>