OKF Explorer OKF Explorer documentation

Maintaining Explorer dependencies

Deepmerge removal — 11 November 2026

Alert #92 (GHSA-gcqx-w48m-w2h4) concerns prototype poisoning in deepmerge 4.3.1. Its only consumer here was the development-only Svelte Vite plugin, which merges repository configuration; this does not establish a remotely exploitable path in the static Site. Neither package has a released upstream fix.

The pinned plugin 7.3.1 carries a pnpm patch backported from upstream PR #1415, revision 3fb6096650ede5b0d7f8ea9a82edd8849e3e4b76. It replaces both configuration merge calls with the proposed internal merge. A scoped dependency override removes the unused deepmerge edge. This is a maintained local backport, not a claim that the upstream proposal has been released.

Patch context retains upstream whitespace through a scoped Git attribute. The lockfile binds the patch hash; the SBOM records its path and SHA-256 alongside the original registry package integrity. Tests exercise poisoned nested and null-prototype inputs, constructor keys, configuration precedence, array replacement, source isolation and preprocessor behaviour against the installed patched plugin. The dependency policy rejects any returning copy or reference to deepmerge. Arrays and non-plain values retain their references, as in the upstream proposal; plain objects are copied recursively.

Run frozen installation from apps/okf-explorer so relative patch paths resolve consistently, as CI does. Replace this backport with a compatible upstream release only after checking that the dependency is absent and these tests pass.

Playwright update deferred — 11 November 2026

PR #195 remains open because Playwright 1.65.0's Firefox 159 build crashes in three existing accessibility checks. The failures reproduce locally, including a direct native ARIA reflection read after a role or label locator. They match Playwright issue #43967 and Mozilla bug 2090055. The latest stable npm version was still 1.65.0 when checked on 11 November.

The independent PDF.js and framework updates retain Playwright 1.64.1 from main. Resume the browser update when a stable package contains the upstream fix, then run the complete Chrome, Firefox and WebKit acceptance gate. Keep all accessibility rules, tests and browser engines enabled. This deferral does not establish that the older toolchain has no other known defects.

Node type definitions — 11 November 2026

PR #190 updates the application's development-only @types/node resolution from 24.19.2 to 26.6.6, with undici-types 8.9.0. These packages describe Node APIs to TypeScript; they do not install a Node runtime or raise the application's declared minimum. CI retains its existing Node 24 and Node 26 runtime checks. No application code begins using a newer Node API in this update.

Review the resolved lockfile and regenerated SBOM together. The dependency policy, Svelte type check and application tests pass locally. The deterministic application tree and build-manifest digests remain identical to the preceding main build, so its existing Heritage browser evidence still identifies those application bytes. Protected CI and deployed identity remain separate checks.

Ask OKF HTTP adapter reconciliation — 11 November 2026

The earlier PR #191 candidate proposed @modelcontextprotocol/node 2.1.0. The v0.8.0 integration subsequently adopted adapter 2.1.2, server and client 2.4.0, legacy comparison SDK 1.32.2 and patched transitive HTTP dependencies. Reconciliation preserves the newer manifest and lockfile from main byte for byte, including its security overrides; the earlier candidate must not downgrade them. The remaining change records that history and links this maintenance guidance from the repository introduction.

The service rejects oversized bodies and all JSON-RPC batches before invoking the handler. Preserve those stricter application controls, host/origin admission and read-only evidence tools. Service tests cover streamed and declared body limits, single-message admission, both supported SDKs and ordinary evidence requests. A repository merge does not redeploy the hosted service or change a published source/engine archive.

Reviewed integration on 23 October 2026

The reading-help candidate combines the overlapping Explorer updates from PRs #160, #165, #168, #169, #170, #171 and #173. The reviewed versions are Svelte 5.57.1, the Svelte Vite plugin 7.3.1, Vite 8.3.3, PDF.js 6.4.299, Playwright 1.64.1, axe 4.14.0, devalue 5.9.4 and source-map-js 1.2.2. Vitest and its matching coverage package move together to 4.1.12, which addresses the follow-up manual mock registration and Windows path validation advisories. The dependency guard rejects the earlier 4.1.11 floor. The newer axe check also exposed label/name mismatches in the learning-hub link, graph zoom, authority counts and relationship drawer. Their accessible names now include the visible wording and counts. Graph stack counts already included in the complete node name are decorative duplicates. The changed direct dependencies are pinned to those versions. Keep pnpm 10, the cookie and nanoid controls and the reviewed Rolldown pin. The conditional devalue override now selects 5.9.4 for older copies.

The bot lockfiles lost the override declarations and omitted the regenerated SBOM and required documentation. Regenerate their combined lockfile with pnpm, check the full resolved inventory and rebuild the SBOM. Preserve the preceding main and reading-help browser receipts under validation/dependency-updates/2026-10-23/ before refreshing the current 100-question suite and three local journeys. Browser results remain bound to their exact application; GitHub CI and deployed identity are separate gates.

A dependency is a library or tool that Explorer uses. package.json declares which versions are permitted; pnpm-lock.yaml records the exact versions and package integrity values selected for a build. Both files matter when reviewing an automated Dependabot pull request.

Preserve the security controls

The stable component review records the final P0 selections, including Kit 3.1.0, Svelte 5.57.2, Vite 8.3.5 and svelte-check 4.7.7. Use pnpm 10.34.7, as declared by packageManager and the workflows. CI keeps its existing Node 24 LTS and Node 26 Current lines, pinned to security releases 24.22.1 and 26.12.1 respectively. The comparison also states why larger or explicitly governed changes remain proposed.

Use the repository's pnpm 10 toolchain. Run pnpm install --frozen-lockfile for validation: it fails when the manifest and lockfile disagree. During an authorised update, regenerate the lockfile with pnpm, review every changed package, then return to frozen installation. Never hand-edit integrity values or remove a security override to bypass a failing install.

The conditional cookie@<0.7.2: 0.7.2 override preserves the reviewed fix for GHSA-pxg6-pf52-xh8x. Some older bot updates removed this override from the lockfile and selected cookie 0.6.0. @types/cookie is a separate type-definition package and must not be confused with the affected runtime package. The P0 follow-up replaces the earlier broad override: Kit 3 requires cookie 2.0.1, which must never be downgraded to 0.7.2. The dependency guard checks both the shared security floor and the framework's required API version.

Vitest and its coverage package must resolve to the same version. The September baseline used 4.1.11, including the transitive @vitest/mocker fix for GHSA-82fw-gwwq-j7x9. That advisory concerns development-server file access; a dependency alert is not evidence that the static Pages site has been exploited. Keep development servers local and review any change that exposes them to a network.

The September audit also found older transitive copies of devalue and nanoid. It introduced conditional overrides selecting devalue 5.9.2 for GHSA-9rgm-9g3h-6x36 and nanoid 3.3.18 for GHSA-2v37-7h3g-55p8. These address denial-of-service conditions involving malformed input or a zero-sized custom ID request; the audit does not demonstrate an exploitable Explorer path. The guard checks resolved versions, allowing the temporary overrides to be removed when reviewed upstream dependencies select safe copies.

pnpm deps:check enforces these recorded dependency invariants against the manifest, package inventory and resolved snapshots. Its regression tests retain examples of lost overrides, vulnerable duplicate packages and mismatched coverage. It is a targeted guard, not a replacement for vulnerability alerts or reviewing upstream changes. Pre-release replacements need an explicit policy review rather than silently passing the stable-version checks.

Framework and bundler baseline

The September framework baseline used SvelteKit 2.70.3, the Svelte Vite plugin 7.3.0, Svelte 5.57.0, svelte-check 4.7.6 and Vite 8.3.0. The reviewed October versions are listed above. The P0 advisory follow-up adopts SvelteKit 3.1.0 and static adapter 4.0.0, moves framework settings into Vite and extends the Kit 3 type configuration. Existing $lib imports use explicit Vite and TypeScript aliases. Deployment polling remains disabled; routes, prerender exceptions and deterministic versioning are preserved. Node 24 and the existing Svelte, Vite and TypeScript versions satisfy the new framework's requirements.

Vite uses Rolldown to produce the static application. The rolldown: 1.2.9 override keeps its native bindings on the reviewed version while Vite's permitted range also admits later releases. Remove or change that pin only after reviewing the new Rolldown release and testing the resulting build. The conditional nanoid override remains in place; the current lockfile selects the newer safe copy, 3.3.19.

Framework updates can change generated HTML, CSS and JavaScript even when no application source changes. Review the exact lockfile and regenerated SBOM, then run the deterministic build, Site checks and the full Chrome, Firefox and WebKit browser contract before accepting a candidate. Local checks do not establish the identity of a later Pages deployment.

For the 25 September update, the 100-question Heritage suite and three local journeys were run against the rebuilt application. The preceding receipt and results are retained under validation/dependency-updates/2026-09-25/pre-framework/. The final receipt also binds those browser results to the assembled Site after the security documentation commit was included; that documentation change did not change the application or Heritage corpus evaluated in the browser.

Review and validate a candidate

  1. Start from current main on a feature branch. Inspect the complete diff, upstream release notes, security advisories and changes in indirectly used packages. Do not infer safety from the bot's authorship or a patch-version label.
  2. Update only the reviewed versions. Keep coupled packages together: Vitest with coverage, and Playwright with its core/browser versions. Recheck the combined lockfile after integrating overlapping updates.
  3. Run the checks below. The software bill of materials (SBOM) is the generated inventory of exact package versions and integrity values. Regenerate it only after reviewing the lockfile; preserve historical release receipts.
  4. Update this documentation and CHANGELOG.md when behaviour or the supported toolchain changes. Required checks do not exempt dependency updates.
  5. Review the exact candidate, pass protected-branch CI, then verify the exact merged Pages deployment. Earlier release receipts do not attest to a new manifest, lockfile or application build.
cd apps/okf-explorer
pnpm install --frozen-lockfile
pnpm deps:check
pnpm audit --audit-level=moderate
pnpm sbom
pnpm sbom:check
pnpm check
pnpm test
pnpm test:coverage

Run the affected browser journeys too. Changes to Playwright or the application compiler require the supported Chrome, Firefox and WebKit checks. A failed inventory check is different from a functional test failure; a skipped browser check is still missing validation.

Local browser checks own their server and fail if its port is already occupied. This prevents a different worktree's older application from satisfying the tests. For parallel work, choose a free port explicitly, for example PLAYWRIGHT_PORT=4183 pnpm test:e2e. Do not stop another task's server or use its results as evidence for this candidate. The full browser command uses that port for the application and then the generated Site in sequence. Set PLAYWRIGHT_FOUNDRY_PORT if the Site needs a different free port.

An application rebuild also invalidates the current Heritage browser receipt's application identity. Follow the receipt refresh procedure to run its 100 questions and three local journeys, then materialise a new receipt from those results. Preserve the previous receipt and result files; do not change identity hashes by hand or weaken the receipt tests. The 25 September security repair retains its preceding evidence under validation/dependency-updates/2026-09-25/pre-security/.

Build and deployment actions

GitHub Actions updates can affect code running during builds or deployment. Keep actions pinned to complete commit hashes and verify those hashes against the upstream release. Preserve the existing workflow triggers, pnpm 10 setting and separate Pages deployment permissions. The reviewed maintenance update uses pnpm/action-setup 6.1.1 and actions/deploy-pages 5.0.1; it does not grant additional permissions. On 11 November 2026, the upstream annotated v6.1.1 tag was checked against the pinned commit 73e46992e05b19abd31f2f3c20e0e7370d762115. The update changes the setup action in CI, shadow evaluation and Pages while preserving pnpm 10.34.7 and existing triggers and permissions. The action's upstream changes concern bootstrap and cache handling; protected CI and the exact Pages deployment verify its use in this repository.

Framework maintenance — 11 November 2026

The maintenance candidate selects static adapter 4.0.1, SvelteKit 3.1.1, Svelte 5.57.3, svelte-check 4.7.8 and Vite 8.3.6. These versions retain the existing Node requirements. Their locked indirect dependencies include cookie 2.0.2, PostCSS 8.5.32 and magic-string 1.4.5. The conditional security overrides and the reviewed Rolldown 1.2.9 pin remain in place.

The upstream fixes cover framework routing and server imports, Svelte state and accessibility handling, and Vite asset hashing, CSS imports and workers. Explorer's application source and route contracts remain unchanged. Those upstream descriptions do not establish Explorer compatibility: the candidate must pass the app contracts, generated Site checks and Chrome, Firefox and WebKit journeys against its exact locked build.

The framework changes generated application bytes. The refreshed Heritage 100-question and three-journey observations cover the combined application, including PDF.js 6.5.438. The preceding PDF.js receipt and compressed results are retained under validation/dependency-updates/2026-11-11/pre-framework/. Local observations and protected-branch CI do not establish a later Pages deployment.

PDF renderer maintenance — 11 November 2026

The PDF.js update selects pdfjs-dist 6.5.438 and its optional canvas dependency @napi-rs/canvas 1.1.0. The renderer and worker remain from the same locked package; the update changes the generated application bytes. The SBOM records the resolved packages without changing the existing security overrides.

The existing source-boundary browser test verifies the frozen DWP PDF checksum, renders a populated page, changes page and returns to it. It also loads all 28 source cases. This local check uses the separately retained producer fixture; no PDF is copied into Explorer's Git history or Site inputs by the update. The 100-question Heritage suite and three local journeys supply fresh runtime evidence for the rebuilt application. The previous receipt and compressed results are retained under validation/dependency-updates/2026-11-11/pre-pdfjs/.

Protected-branch CI and exact-commit Pages verification remain separate from these local observations.