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

package/LICENSE-APACHE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/api/reap.ts

@@ -0,0 +1,17 @@
+// E2e-only Vercel deployment: no persistent relay is running in this function.
+// The managed deployment routes /api/reap through its top-level app instead.
+import { createReapHandler } from '../server-common/reap.ts'
+import { databaseUrls } from '../server-common/database-config.ts'
+import { reapOrphans } from '../server-e2e/objstore/reaper.ts'
+import { openNeonObjstore } from '../server-e2e/objstore/store-neon.ts'
+import { openVercelBlobBackend } from '../server-e2e/objstore/blob-vercel.ts'
+
+const handler = createReapHandler({ e2e: async () => {
+  const url = databaseUrls().e2e
+  const token = process.env['BLOB_READ_WRITE_TOKEN']
+  if (!url || !token) throw new Error('E2e cron requires DATABASE_URL or E2E_DATABASE_URL, plus BLOB_READ_WRITE_TOKEN')
+  const blob = await openVercelBlobBackend({ token })
+  // Stateless Neon HTTP handle: nothing to close, no relay listener or timer.
+  await reapOrphans(await openNeonObjstore(url, blob))
+} })
+export default handler

package/cli.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import './strip-types-loader.js'
+
+// Load TypeScript only after the stripping hook is registered.
+const { start } = await import('./server.ts')
+await start()

package/client/finding-link.js

@@ -0,0 +1,305 @@
+// Deep links to a single finding — pure logic side. Encodes the
+// finding's id plus a "where does it live" hint into the URL hash
+// (`#finding=<id>&v=<hints>`) and parses the same back on the receiving
+// side, so "look at THIS issue" is a link you can paste into a chat
+// instead of a screenshot plus directions.
+//
+// Sibling of `workspace-share-link.js`, and deliberately unlike it in
+// one respect: the id here is NOT a secret. A share link carries the
+// workspace's private key and is therefore encrypted; a finding id is
+// meaningless without the report the recipient must already have, so it
+// rides in the clear and the link stays legible in a chat client.
+//
+// The two LOCATION hints are a different matter. A report filename
+// ("acme-corp-pentest-2024.json") and a workspace id are the sender's
+// own metadata, and a URL is the most-forwarded, most-logged, most-
+// screenshotted string there is — so they ship as 3-byte digests
+// (4 base64url chars) rather than plaintext. That is a fingerprint, not
+// a sealed box: 24 bits only narrows the field, and anyone holding a
+// candidate name can confirm it by hashing. What it does buy is that
+// the name itself never appears in the URL, and a recipient who does
+// NOT hold the report learns nothing from the link but its length.
+//
+// Cheap on the receiving side too: matching a hint means hashing the
+// names already on disk, not reading a single file (see
+// `finding-locate.js`).
+//
+// The hint is a HINT, not an address. The receiver tries the named report
+// or workspace, then a scan of everything stored locally (see
+// `ui/view/finding-link-nav.js`) — so a link built in a workspace still
+// lands for a recipient who only has the single report, and a stale
+// hint costs a scan rather than the finding.
+//
+// Param names live in the same `&`-joined fragment namespace as
+// `share=`, and the parser has the same shape as `extractShareEncoded`
+// — a fragment can therefore only ever be one kind of link, and adding
+// a fourth param later doesn't disturb either.
+
+import { encodeUtf8 } from '../common/utf8.js'
+import { managedRoutePath, parseManagedRoute } from '../common/managed/routes.js'
+import { MAX_FINDING_ID_LENGTH, isLinkableFindingId } from '../common/finding-id.js'
+export { isLinkableFindingId } from '../common/finding-id.js'
+
+// ── location hints ───────────────────────────────────────────────────
+
+// 3 bytes → exactly 4 base64url characters, no padding. Sized to keep
+// the fragment short while still being selective enough that a hint
+// usually names one report out of a user's collection: with 16.7M
+// values, a library of 100 reports has a ~0.03% chance of any collision
+// at all, and a collision costs only a wrong first guess (the receiver
+// re-checks that the finding is actually there, then scans).
+const HINT_BYTES = 3
+const HINT_CHARS = 4
+const HINT_RE = /^[\w-]{4}$/u
+
+// Both hints travel as ONE `v=` parameter: 6 bytes, 8 base64url
+// characters, report half first. Workspace-only links use `w` followed
+// by their 3-byte / 4-character hint. Purely a length decision — two named
+// params spend 20 characters (`&report=aB3-&ws=x_9Z`) to carry 8
+// characters of payload, and a link is something people paste into
+// chat, tickets and commit messages.
+//
+// Concatenating the two 4-character tokens IS the base64 of the 6-byte
+// buffer: 3 bytes is exactly one base64 group, so nothing carries
+// across the halves and either framing produces identical text. That's
+// what lets the packing be a string join and the unpacking a slice,
+// with no encode / decode round trip.
+//
+// `AAAA` (3 zero bytes) marks a half that isn't known — a single-file
+// view has no workspace, and a report whose hint hasn't been hashed yet
+// omits its own. A genuine digest of `AAAA` therefore reads as absent,
+// once per 16.7M values per half; the cost is that the receiver skips
+// straight to the scan, which is where an unmatched hint lands anyway.
+const COMBINED_RE = /^[\w-]{8}$/u
+const NO_HINT = 'AAAA'
+
+// Domain-separated per kind so the same string can't produce a hint
+// that matches in the other namespace — a workspace whose id happened
+// to equal a report's filename would otherwise cross-resolve. Same
+// convention as `workspace-id.js`'s derivation domain.
+const HINT_DOMAINS = {
+  report: 'deepview/finding-link/report/v1\n',
+  workspace: 'deepview/finding-link/workspace/v1\n',
+}
+
+// `${kind}\0${value}` → token. Memoised because the LINK BUILDER must
+// be synchronous: the Link button writes to the clipboard inside the
+// click handler, and Safari drops the clipboard grant if the write
+// happens after an await. Ingest primes this cache for every report it
+// loads (and `switchToWorkspace` for the workspace), so by the time a
+// card is on screen its hint is already here. A cold entry is not a
+// failure — the link is simply built without that hint, and the
+// receiver falls back to the scan.
+const hintCache = new Map()
+
+function hintKey(kind, value) { return `${kind}\0${value}` }
+
+// Whether a value is a well-formed hint token, i.e. something
+// `computeLinkHint` could have produced.
+export function isLinkHint(value) {
+  return typeof value === 'string' && HINT_RE.test(value)
+}
+
+// Derive (and memoise) the hint token for a report filename or a
+// workspace id. Resolves to null — never throws — when the kind is
+// unknown, the value is empty, or `crypto.subtle` is unavailable (some
+// `file://` setups): a missing hint degrades the link, it doesn't break
+// it, so the caller shouldn't have to guard.
+export async function computeLinkHint(kind, value) {
+  const domain = HINT_DOMAINS[kind]
+  if (!domain || typeof value !== 'string' || !value) return null
+  const key = hintKey(kind, value)
+  const cached = hintCache.get(key)
+  if (cached !== undefined) return cached
+  let token
+  try {
+    const digest = await crypto.subtle.digest('SHA-256', encodeUtf8(domain + value))
+    token = new Uint8Array(digest).slice(0, HINT_BYTES)
+      .toBase64({ alphabet: 'base64url', omitPadding: true })
+  } catch {
+    // Not cached: an environment without crypto.subtle stays broken,
+    // but a one-off failure (a lone surrogate in a filename tripping
+    // encodeUtf8) shouldn't poison the entry forever.
+    return null
+  }
+  hintCache.set(key, token)
+  return token
+}
+
+// Synchronous companion — the memoised token, or null if it hasn't been
+// computed yet. The link builder uses this; see `hintCache` above for
+// why it can't just await.
+export function knownLinkHint(kind, value) {
+  if (typeof value !== 'string' || !value) return null
+  return hintCache.get(hintKey(kind, value)) ?? null
+}
+
+// Pack both hints into the `v=` value, or null when neither is known
+// (in which case the param is omitted entirely rather than shipping
+// eight characters of "nothing"). Throws on a non-empty value that
+// isn't a token, so a caller passing a raw filename finds out
+// immediately instead of shipping a hint-less link.
+function packLinkHints(report, workspace) {
+  const halves = []
+  for (const [what, hint] of [['report', report], ['workspace', workspace]]) {
+    if (hint === null || hint === undefined || hint === '') { halves.push(NO_HINT); continue }
+    if (!isLinkHint(hint)) {
+      throw new TypeError(`encodeFindingRef: ${what} must be a link hint token, not a name`)
+    }
+    halves.push(hint)
+  }
+  if (halves.every((h) => h === NO_HINT)) return null
+  // Workspace → finding needs only the workspace half. Report links
+  // retain their original six-byte / eight-character encoding.
+  if (halves[0] === NO_HINT) return `w${halves[1]}`
+  return halves.join('')
+}
+
+// Split a validated `v=` value back into its two halves, mapping the
+// `AAAA` filler to null.
+function unpackLinkHints(value) {
+  const halves = [value.slice(0, HINT_CHARS), value.slice(HINT_CHARS)]
+    .map((h) => (h === NO_HINT ? null : h))
+  return { report: halves[0], workspace: halves[1] }
+}
+
+// ── fragment codec ───────────────────────────────────────────────────
+
+// Build the fragment body (no leading '#') for a finding reference.
+// `report` / `workspace` are hint TOKENS (from `computeLinkHint` /
+// `knownLinkHint`), not names; they leave as the single packed `v=`
+// param: `w` + four characters for a workspace, eight for a report with its
+// optional workspace. Omitted when neither is known.
+//
+// The id is percent-encoded: usually a uuid with nothing to escape, but
+// the codex importer's finding-URL ids carry `/`, `:`, `?` and —
+// decisively — `&` and `=`, which would otherwise split into phantom
+// params on the way back. The packed hints need no encoding (base64url
+// is already fragment-safe) and are emitted verbatim.
+export function encodeFindingRef({ id, report, workspace } = {}) {
+  if (!isLinkableFindingId(id)) {
+    throw new TypeError('encodeFindingRef: a persistent finding id is required')
+  }
+  const parts = [`finding=${encodeURIComponent(id)}`]
+  const packed = packLinkHints(report, workspace)
+  if (packed) parts.push(`v=${packed}`)
+  return parts.join('&')
+}
+
+// Full shareable URL for the current page origin + pathname, mirroring
+// `buildShareUrl`. `location.search` is dropped for the same reason it
+// is there: the target page takes no query params, so dragging the
+// sender's current `?foo=bar` into the recipient's URL would be a
+// surprising leak.
+export function buildFindingUrl(ref, pathname) {
+  const encoded = encodeFindingRef(ref)
+  if (typeof location === 'undefined') return `${pathname ?? ''}#${encoded}`
+  return `${location.origin}${pathname ?? location.pathname}#${encoded}`
+}
+
+// Extract `{ id, report, workspace }` from a hash string (or
+// `location.hash` when called with no argument), unpacking `v=` back
+// into the two hint tokens. Returns null when the fragment carries no
+// usable `finding=` param — a share link, an in-page anchor, an empty
+// hash, or a payload that fails validation.
+//
+// HASH ONLY, matching `extractShareEncoded`. The id isn't secret, so the
+// Referer-leak argument that motivates it there doesn't apply; the
+// reason is uniformity — one place in the app reads deep links, and a
+// caller that reached for `?finding=` would quietly bypass it.
+//
+// A malformed `v=` drops both hints rather than the whole ref: the id is
+// what identifies the finding, and the receiver's scan can still land
+// it. That also covers a link from an older build, whose separate
+// `report=` / `ws=` params simply go unread. An un-decodable ID, on the
+// other hand, fails the whole parse — there is nothing left to look up.
+export function extractFindingRef(hash) {
+  const raw = typeof hash === 'string' ? hash : (typeof location === 'undefined' ? '' : location.hash)
+  if (!raw) return null
+  const stripped = raw.replace(/^#/u, '')
+  if (!stripped) return null
+  const found = { id: null, report: null, workspace: null }
+  for (const part of stripped.split('&')) {
+    const eq = part.indexOf('=')
+    if (eq < 0) continue
+    const key = part.slice(0, eq)
+    const rawValue = part.slice(eq + 1)
+    if (!rawValue) continue
+    // The packed hints are one workspace token or a token pair — validated
+    // verbatim rather than decoded, since base64url has nothing
+    // `encodeURIComponent` would have touched. Anything else is a link
+    // from another era or a mangled paste; drop it and let the scan
+    // take over.
+    if (key === 'v') {
+      if (rawValue.length === 5 && rawValue[0] === 'w' && isLinkHint(rawValue.slice(1))) {
+        const workspace = rawValue.slice(1)
+        Object.assign(found, { report: null, workspace: workspace === NO_HINT ? null : workspace })
+        continue
+      }
+      if (!COMBINED_RE.test(rawValue)) continue
+      Object.assign(found, unpackLinkHints(rawValue))
+      continue
+    }
+    if (key !== 'finding') continue
+    // Cheap length bound BEFORE decoding: percent-encoding expands at
+    // most 3:1, so nothing under this cap can decode to something over
+    // MAX_FINDING_ID_LENGTH, and a megabyte fragment never reaches
+    // decodeURIComponent. `isLinkableFindingId` re-checks the decoded
+    // length, so this is a guard, not the rule.
+    if (rawValue.length > MAX_FINDING_ID_LENGTH * 3) continue
+    let value
+    // decodeURIComponent throws URIError on a truncated / invalid escape
+    // (`%`, `%zz`) — common when a chat client mangles a pasted link.
+    try { value = decodeURIComponent(rawValue) } catch { continue }
+    if (isLinkableFindingId(value)) found.id = value
+  }
+  if (!found.id) return null
+  return found
+}
+
+// Recognise a finding deep link pasted into free text — the reverse of
+// `buildFindingUrl`, used to linkify comments (see `parseCommentRefs` in
+// `ui/view/format.js`). Returns `{ id, fragment, path }` with the E2E fragment
+// re-emitted canonically and a managed destination URL, or null
+// for anything that isn't one of OUR links.
+//
+// "Ours" means the CURRENT host, scheme included. A finding id resolves
+// only against the reader's available reports, so a link to some other
+// deployment couldn't be followed usefully even if it were offered — and
+// a same-name look-alike on another host is exactly what a linkifier
+// must not present as the real thing. Credentials are refused for the
+// same reason (`https://user@triage.space/…` reads as ours but isn't
+// something the app ever emits).
+//
+// Managed team/report paths are preserved to identify the intended copy.
+// E2E entry links resolve from `/` in managed mode, without inheriting
+// the current report. E2E consumers use just the fragment to stay on their
+// current deployment, including `/index.html` and subpaths.
+//
+// The anti-mutation guard is the one from `githubRefToken`: `new URL`
+// silently rewrites its input (resolving `..`, lower-casing, punycoding
+// IDN homographs, dropping a default port), any of which can let a
+// look-alike round up into a passing link. A candidate that isn't
+// already canonical is refused rather than linkified. Every link this
+// app emits round-trips unchanged, since `buildFindingUrl` builds from
+// `location` itself.
+export function parseFindingUrl(candidate, { managed = false } = {}) {
+  if (typeof location === 'undefined') return null
+  let u
+  try { u = new URL(candidate) } catch { return null }
+  if (u.href !== candidate) return null
+  if (u.protocol !== location.protocol) return null
+  if (u.host !== location.host) return null
+  if (u.username || u.password) return null
+  const route = parseManagedRoute(u)
+  if (route?.finding) {
+    return { id: route.finding.id, fragment: encodeFindingRef(route.finding), path: managedRoutePath(route) }
+  }
+  // Only E2E entry pages carry finding hashes. Unknown managed page URLs
+  // must not turn into a search for another accessible copy of the finding.
+  if (managed && route?.view !== 'home' && !/\/(?:index|view)\.html$/u.test(u.pathname)) return null
+  const ref = extractFindingRef(u.hash)
+  if (!ref) return null
+  const fragment = encodeFindingRef(ref)
+  return { id: ref.id, fragment, path: `/#${fragment}` }
+}

package/client/linked-findings.d.ts

@@ -0,0 +1 @@
+export function parseLinkedFindings(content: string): { groups: string[][]; skipped: number } | null

package/client/linked-findings.js

@@ -0,0 +1,111 @@
+// The "links" file — a small JSON document that says which findings
+// are the SAME finding, reported twice:
+//
+//   [[{"id":"a"},{"id":"b"}], [{"id":"c"},{"id":"d"},{"id":"e"}]]
+//
+// One inner array per link. Every finding named in it is a duplicate
+// of every other one in that array, and the file says nothing else:
+// no severity, no title, no file, no prose. That is the whole format.
+//
+// It is NOT a report, and this module deliberately sits outside
+// `@preventive/report` because of it. A report carries findings; a links file
+// carries only ids of findings that must already live in reports the
+// reader holds. So it never reaches `ingestReport` / `state.reports`,
+// it has its own view (`ui/view/render-links.js`) that points at the
+// findings. It also supplies the "Duplicates:" row on finding cards
+// and groups explicitly linked rows in workspace App view.
+//
+// Pure — no storage, no DOM, no app state. `linked-findings-index.js`
+// beside this file is the OPFS-wide store built on top; everything
+// here is text in, data out, so the recognition rules are testable on
+// their own.
+
+import { isLinkableFindingId } from './finding-link.js'
+
+// The `source` marker a links file is filed under — the same slot a
+// report's producer ('deepsec', 'piolium', …) occupies in the counts
+// cache, so `getKind(name)` answers "what kind of file is this" for
+// links and reports alike and the sidebar can bucket both from one
+// lookup. No report format can collide with it: this value comes from
+// here, never from a document's own content.
+export const LINKS_KIND = 'links'
+
+// Is this one entry of an inner array — `{"id": "…"}` — as the format
+// spells it? Extra fields are allowed and ignored: an exporter that
+// writes the title or the report alongside the id is writing a
+// superset of this format, not a different one.
+function entryId(entry) {
+  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null
+  const { id } = entry
+  return typeof id === 'string' && id.length > 0 ? id : null
+}
+
+// Recognise `content` as a links file and normalise it.
+//
+// Returns `{ groups, skipped }` — `groups` is one `string[]` of finding
+// ids per link, and `skipped` counts ids the app could never follow (a
+// session-local numeric id, a control character, something absurdly
+// long — `isLinkableFindingId` draws the same line the per-finding Link
+// button draws). Returns null when the text isn't this format at all.
+//
+// Recognition is on SHAPE, and it is strict, because this parser runs
+// against every dropped file before the report readers get their turn:
+// a top-level array, holding only arrays, holding only objects with a
+// string `id`. Nothing else this app reads is a bare JSON array, so
+// nothing else can be mistaken for one — and an empty top-level array
+// is refused rather than claimed, since `[]` is every empty JSON list
+// in the world, not distinctively a links file.
+//
+// Normalisation drops what carries no information: ids repeated inside
+// one link, ids that can't be linked, and then any link left naming
+// fewer than two findings — a "link" to a single finding links nothing.
+// A file whose every link normalises away is still a links file; it
+// just has no links, which its view says plainly.
+export function parseLinkedFindings(content) {
+  let data
+  try { data = JSON.parse(content) } catch { return null }
+  if (!Array.isArray(data) || data.length === 0) return null
+  const groups = []
+  let skipped = 0
+  for (const raw of data) {
+    if (!Array.isArray(raw)) return null
+    const ids = new Set()
+    for (const entry of raw) {
+      const id = entryId(entry)
+      if (id === null) return null
+      if (isLinkableFindingId(id)) ids.add(id)
+      else skipped++
+    }
+    if (ids.size > 1) groups.push([...ids])
+  }
+  return { groups, skipped }
+}
+
+// How many findings the links in `groups` name, counted once each — a
+// finding named by two links is one linked finding. What the sidebar
+// badge and the view's header report alongside the link count.
+export function countLinkedIds(groups) {
+  const ids = new Set()
+  for (const group of groups) for (const id of group) ids.add(id)
+  return ids.size
+}
+
+// Fold links into `index` (a `Map<id, Set<id>>`): every id in a link
+// gains every OTHER id in it as a duplicate. Called once per links
+// file, so an id linked by two files ends up with the union of what
+// both said about it.
+//
+// Union, NOT transitive closure. If one file links a↔b and another
+// links b↔c, then b has two duplicates and a has one — a and c were
+// never said to be the same finding, and inferring it would put a
+// claim in the reader's card that no file they dropped ever made.
+export function collectDuplicates(groups, index) {
+  for (const group of groups) {
+    for (const id of group) {
+      let set = index.get(id)
+      if (!set) index.set(id, set = new Set())
+      for (const other of group) if (other !== id) set.add(other)
+    }
+  }
+  return index
+}

package/common/bundle-commit.d.ts

@@ -0,0 +1 @@
+export function bundleCommitHash(value: unknown): string | null

package/common/bundle-commit.js

@@ -0,0 +1,4 @@
+// Match the full Git object IDs used by bundle origin links.
+export function bundleCommitHash(value) {
+  return typeof value === 'string' && /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/u.test(value) ? value : null
+}