Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS
Dependency Audit (DEPS.md)
Living reference of every third-party dependency in PortOS, why it's kept, and what the current verdict is. Updated by /do:depfree runs.
That "every dependency" claim is enforced by docs/deps-doc.test.js (run by cd server && npm test): adding a dependency to any workspace manifest without a row here fails the suite, and a Quick Reference row naming a package no manifest declares fails too unless its verdict records the removal (REMOVED / REPLACED).
Last audited: 2026-09-21 (routine sweep: 0 open Dependabot alerts, 0 vulnerabilities across root/server/client/autofixer, react/react-dom 19.3.0 held back by r3f peer cap #7370); prior 2026-09-12 (scoped: remove the redundant direct google-auth-library, issue #7013); prior 2026-09-11 (scoped: drop @scalar/api-reference-react, issue #7012); prior 2026-09-02 (scoped: pdf-lib → @cantoo/pdf-lib, issue #5672; parity sweep that added the missing playwright-core row and put this document under test — docs/deps-doc.test.js, issue #5708); prior 2026-08-04 (scoped audit of the keyv/cacheable supply-chain compromise); prior follow-up 2026-07-14 (issue #2547), prior full audit 2026-04-28 (default mode), tables corrected 2026-07-01 during a docs audit.
Verdict: All remaining dependencies justified. The 2026-09-21 routine sweep verified that all direct dependencies are current, with 0 open Dependabot alerts on GitHub, clean audits across all workspaces, and react/react-dom 19.3.0 held back by @react-three/fiber's peer constraint (issue #7370). The 2026-09-12 follow-up removed the direct [email protected] pin (issue #7013); Google OAuth now uses the copy already pulled transitively by the scoped Calendar SDK, so this is a manifest/lockfile cleanup rather than a reduction of the transitive tree. The 2026-09-11 follow-up removed @scalar/api-reference-react (issue #7012) — the heaviest client dependency, ~half the lockfile and 3.24 MB of dist assets, including Vue 3 and the Vercel AI SDK advisory GHSA-866g-f22w-33x8. The REST Reference tab now lists OpenAPI operations natively. The 2026-08-04 audit replaced the entire eslint stack with @biomejs/biome, dropping 110 net client packages including the file-entry-cache → flat-cache → keyv chain named in the August 2026 Shai-Hulud npm compromise (PortOS held safe versions throughout — see the detailed finding below). The same pass closed a latent hole where ignore-scripts=true was only active for repo-root installs, not for any workspace install or CI. Since the last full audit: sax was removed (replaced with an owned parser, issue #1824), portos-ai-toolkit was vendored in-tree (server/lib/aiToolkit/), and monolithic googleapis was replaced with scoped @googleapis/* packages. The 2026-07-14 follow-up bumped kokoro-js to its latest patch 1.2.1 (still on maintenance watch — no publish since 2025-05) and aligned the dual pm2 pins (root + server both 7.0.4). The 2026-09-02 follow-up replaced abandoned pdf-lib (no publish since 2022-05) with the maintained MIT fork @cantoo/[email protected] — a same-public-API swap across the four export paths, done while npm audit was still clean rather than under advisory pressure.
Audit Methodology
Each dependency is classified into one of three tiers:
- Tier 1 (ACCEPTABLE) — large, widely-audited, foundational libraries. Kept without question.
- Tier 2 (SUSPECT) — smaller libraries that may be replaceable. Audited for actual usage.
- Tier 3 (REMOVABLE) — clear candidates for owned-code replacement.
Before removing a Tier 3 candidate, run a transitive-dep check (npm ls <pkg>). If a kept package already pulls the same major version, the candidate is downgraded to KEEP (transitive) — direct removal saves no supply chain attack surface.
Quick Reference Table
| Package | Tier | Verdict | Where Used | Notes |
|---|---|---|---|---|
| Root deps | ||||
pm2 |
1 | KEEP | top-level scripts | Process manager, foundational. Declared in root dependencies (the root manifest has no devDependencies). Pinned 7.1.0 (aligned with server pin) |
| Server deps | ||||
@cantoo/pdf-lib |
2 | KEEP | PDF generation for the volume / comic / prose / legacy-archive exports | Maintained MIT fork of pdf-lib, which has had no publish since 2022-05. Same public API (PDFDocument/rgb/StandardFonts); the swap was 4 import lines. On maintenance watch — see the detailed finding |
pdf-lib |
— | REPLACED | PDF generation | 2026-09-02 → @cantoo/pdf-lib (issue #5672). Abandoned upstream: 1.17.1 is simultaneously the pinned and the latest published version, unchanged since 2022-05-12. Not deprecated and never flagged by npm audit — replaced ahead of an advisory, not in response to one |
@novnc/novnc |
1 | KEEP | PortDeck remote desktop viewer | Mature RFB/VNC protocol implementation; replacing it would require owning multiple security types and framebuffer encodings |
@googleapis/calendar |
1 | KEEP | Calendar integration | Scoped official Google SDK (replaced monolithic googleapis) |
@googleapis/gmail |
— | REPLACED | Messages/Gmail integration | Issue #12219 → server/services/gmailApi.js, a six-operation adapter over the @googleapis/calendar OAuth client's request() (fixed Gmail v1 origin; auth, refresh and transport stay upstream). Calendar still retains googleapis-common, Google auth and their transport dependencies, so this trims a direct dependency and its update churn, not that transitive supply chain |
better-sqlite3-multiple-ciphers |
2 | KEEP | server/services/signalSnapshot.js — read-only SQLCipher snapshot of the local Signal Desktop database |
MIT build of better-sqlite3 with SQLCipher 4 compatibility. Ships prebuilds and sets gypfile false, so install does not compile it. node:sqlite cannot open SQLCipher, and a main-file copy misses committed WAL frames (#11149). A missing prebuild fails that sync closed |
chokidar |
1 | KEEP | server file watching | Mature cross-platform file-system watcher used by server services |
compression |
1 | KEEP | server HTTP responses | Express-maintained Brotli and gzip negotiation for API and built client responses; preserves streaming and backpressure |
express |
1 | KEEP | server/index.js + routes |
Framework |
google-auth-library |
— | REMOVED (direct) | Google OAuth | Consolidated under @googleapis/calendar's transitive googleapis-common dependency |
kokoro-js |
2 | REMOVED | Former in-process TTS | Replaced by the in-tree Piper backend; existing settings migrate |
node-pty |
1 | KEEP | shell/terminal services | Native PTY binding (N-API) |
pg |
1 | KEEP | Postgres access | Official pg driver |
playwright-core |
1 | KEEP | server/services/fableLoom/falVideoAutomation.js — fal.ai scene video automation |
Drives the PortOS-managed browser over CDP (chromium.connectOverCDP). -core rather than the full playwright package deliberately: the browser is provisioned separately by npm run setup:browser, so the bundled browser download would be dead weight |
pm2 |
1 | KEEP | app lifecycle | Process manager. Pinned 7.1.0 (aligned with root pin) |
sharp |
1 | KEEP | image processing | Native, widely-audited |
socket.io |
1 | KEEP | realtime | Foundational |
socket.io-client |
1 | KEEP | server-to-client | Paired with socket.io |
trash |
— | REPLACED | Recoverable image/video history deletion (server/lib/trashFiles.js) |
Issue #12246 → PortOS-owned adapters in server/lib/nativeTrash.js / nativeTrashXdg.js (ADR docs/decisions/2026-10-18-native-trash-without-dependency.md): osascript + NSFileManager.trashItemAtURL per file on macOS, Windows PowerShell 5.1 + shell32 SHFileOperationW with a fixed-drive pre-flight, freedesktop Trash 1.0 on node:fs for Linux. Removed the package's 57 lockfile entries, its ad-hoc-signed macOS binary and unsigned Windows executable |
undici |
1 | KEEP | HTTP client | Node core team project |
ws |
1 | KEEP | remote desktop + browser WebSockets | Foundational WebSocket transport; also used transitively by Socket.IO |
zod |
1 | KEEP | input validation | Widely-audited |
| Server devDeps | ||||
@babel/parser |
1 | KEEP | scripts/generate-prompt-stage-call-sites.js — parses server/ sources to index prompt-stage call sites |
Already present transitively (via vitest); promoted to an explicit devDep in #6624 so the generator can't break on a hoist change. Declared on server rather than root because CI never installs root node_modules |
vitest |
1 | KEEP | test runner | |
@vitest/coverage-v8 |
1 | KEEP | coverage | Paired with vitest |
| Client deps | ||||
@dnd-kit/core |
1 | KEEP | drag/drop | |
@dnd-kit/sortable |
1 | KEEP | drag/drop | |
@react-three/drei |
1 | KEEP | CyberCity 3D | Three.js helpers |
@react-three/fiber |
1 | KEEP | CyberCity 3D | React renderer for Three |
@scalar/api-reference-react |
— | REMOVED | Dev Tools → API Explorer | 2026-09-11 → native REST Reference tab (issue #7012). Was the heaviest client dep (~half the lockfile, 3.24 MB dist, Vue 3 + Vercel AI SDK). See detailed finding |
@xterm/xterm |
1 | KEEP | browser terminal | |
@xterm/addon-fit |
— | REMOVED | xterm sizing | 2026-09-12 → in-tree terminal sizing helper (issue #7014) |
@xterm/addon-web-links |
1 | KEEP | xterm links | |
lucide-react |
1 | KEEP | icons | Widely-used |
react |
1 | KEEP | UI | |
react-dom |
1 | KEEP | UI | |
react-router |
1 | KEEP | routing | v8 dropped the react-router-dom alias package |
recharts |
1 | KEEP | charts | |
socket.io-client |
1 | KEEP | realtime client | |
three |
1 | KEEP | 3D | |
three-stdlib |
— | REMOVED (direct) | 3D avatars | 2026-09-02 → three/examples/jsm/utils/SkeletonUtils.js (issue #5683). The sole direct import was SkeletonUtils.clone, which three itself ships. Still in the tree transitively via @react-three/drei, so this is a manifest cleanup, not a supply-chain reduction — the win is one fewer pin to Dependabot-bump and the removal of a pinned-vs-^ drift surface against drei's own request |
| Client devDeps | ||||
@biomejs/biome |
1 | KEEP | linting | Replaced the whole eslint stack 2026-08-04; native binary, 0 regular deps + 8 platform optionals (1 installed) |
eslint |
— | REMOVED | linting | 2026-08-04 → @biomejs/biome. 53 packages were reachable only via eslint itself (incl. the file-entry-cache → flat-cache → keyv chain); 110 net once the plugin subtrees and orphaned typescript go too. minimatch and brace-expansion left the tree with it (both now 0 occurrences in every lockfile), so neither needs an override pin — do not re-add one |
@eslint/js |
— | REMOVED | linting | Removed with eslint |
@eslint-react/eslint-plugin |
— | REMOVED | linting | Removed with eslint; its 8 enabled rules map to Biome rules + one GritQL plugin |
eslint-plugin-react-hooks |
— | REMOVED | linting | Removed with eslint; rules-of-hooks → Biome useHookAtTopLevel |
typescript |
— | REMOVED | (none) | 2026-08-04. Was only here for @eslint-react's peer dep; client has no tsconfig / .ts sources / tsc script |
@tailwindcss/postcss |
1 | KEEP | styling | |
tailwindcss |
1 | KEEP | styling | |
@vitejs/plugin-react |
1 | KEEP | build | |
vite |
1 | KEEP | build | |
vitest |
1 | KEEP | client test runner | happy-dom environment |
happy-dom |
1 | KEEP | test DOM | Paired with vitest. Replaced jsdom in #6144 — same suite, ~65% less time in environment |
@testing-library/jest-dom |
1 | KEEP | test matchers | |
@testing-library/dom |
— | REMOVED (direct) | DOM test utilities | 2026-09-12 → imported through @testing-library/react; remains in the tree transitively, so this removes only the redundant direct pin |
@testing-library/react |
1 | KEEP | component tests | |
@testing-library/user-event |
1 | KEEP | interaction tests | |
rollup-plugin-visualizer |
2 | KEEP | bundle-size analysis | Dev-only, opt-in |
| Autofixer deps | ||||
express |
1 | KEEP | autofixer/ui.js |
Same framework and pin (5.2.1) as the server workspace, but a separate install prefix with its own lockfile — so it needs its own overrides block to inherit the server's express-tree pins |
| Browser workspace | ||||
| (none) | — | — | browser/server.js |
Zero dependencies — Node built-ins only, plus in-repo imports from server/lib/ and scripts/lib/. No Dependabot entry, and its lockfile is gitignored |
Detailed Findings — Tier 2/3 Audits
@cantoo/pdf-lib — KEEP (Tier 2), replaced pdf-lib 2026-09-02 (issue #5672)
- Usage: 4 import sites, all the same named import —
server/services/pipeline/volumePdf.js,comicPdf.js,proseExport.js, andserver/services/legacyExport.js(import { PDFDocument, rgb, StandardFonts }). ~40 call sites across them, all in the narrow high-level core:PDFDocument.create,addPage,embedFont,drawText,drawImage,widthOfTextAtSize,save, plusrgb()and 9StandardFontsconstants. No low-levelPDFDict/PDFRefwork, no form filling, no encryption, no incremental update. - Why the swap:
[email protected]has had no npm publish since 2022-05-12 — the pinned version and the latest published version are the same release. It is not deprecated andnpm auditwas clean, but it is a parser/serializer for a hostile binary format sitting on the export path for four user-facing pipelines. When a PDF advisory lands there is no upstream release to take. Migrating while audit is green is a planned change; migrating after an advisory is an emergency. - The fork:
@cantoo/pdf-lib(github.com/cantoo-scribe/pdf-lib), same MIT license, pinned2.9.1, published 2026-08. It preserves thePDFDocument/rgb/StandardFontspublic API, so the migration was 4 import lines + 1 manifest line + the lockfile — no output, layout, font, or page-geometry change. - Transitive cost:
server/package-lock.jsongoes 380 → 385 packages (+5 net). In: the fork pluscolor,color-string,is-arrayish,simple-swizzle,html-entities,node-html-better-parser, and a top-levelpako. Out:pdf-liband its nestedpako/tslibcopies.@pdf-lib/standard-fontsand@pdf-lib/upngstay — the fork depends on them too — and so does the top-leveltslib, which other packages pull.npm auditstays at 0 vulnerabilities. - Replacement complexity if owned in-tree instead: Infeasible (300+ lines of font metrics, xref tables, and content-stream encoding) — which is why a maintained fork, not a rewrite, was the decision.
- Regression cover: two boundary tests assert real output bytes rather than helper behaviour, because a same-API fork can only regress below the helper layer —
proseExport.test.js(buildProsePdfreturns aUint8Arraystarting%PDF-and ending%%EOF) andcomicPdf.test.js(image XObject count scales with the number of embedded pages, catching a silently-droppeddrawImagepayload). - Grep caveat for the next audit:
server/services/legacyExport.jscontains a byte sequence that makesfile(1)classify it asdata, so plaingrep -rsilently skips it — a repo-wide dependency sweep must usegrep -ra. That is exactly how the fourth import site was missed when this migration was first scoped; it surfaced only as anERR_MODULE_NOT_FOUNDin the suite. - Re-audit trigger: revisit if
@cantoo/pdf-libitself goes >12 months without a publish, or on any CVE against it. The fallback is the same shape as the swap in: another maintained fork, or upstreampdf-libif it ever resumes releases.
@scalar/api-reference-react — REMOVED 2026-09-11 (issue #7012)
- Usage (was): 1 import, in
client/src/components/api-explorer/ScalarReference.jsx, whichclient/src/pages/ApiExplorer.jsxreached through alazy()dynamic import on one route (Dev Tools → API Explorer, the REST Reference tab). - Measured footprint at removal (2026-09-02, fresh
npm run build --prefix client):- Packages: 261 of the client's 599 installed packages (44%) were reachable ONLY via Scalar. Scalar's own subtree was 282. The exclusive set included an entire second UI framework (
vue,radix-vue,@headlessui/vue,@floating-ui/vue,vue-sonner,@unhead/vue) and the Vercel AI SDK (ai,@ai-sdk/gateway,@ai-sdk/provider,@ai-sdk/provider-utils,@ai-sdk/vue). - Bundle: 3.24 MB of dist assets against ~13.0 MB of built JS —
OperationBlock.vue-*.js(2.21 MB),ScalarReference-*.js(608 KB),AgentScalarChatInterface.vue-*.js(197 KB),ScalarReference-*.css(250 KB).
- Packages: 261 of the client's 599 installed packages (44%) were reachable ONLY via Scalar. Scalar's own subtree was 282. The exclusive set included an entire second UI framework (
- Why it left:
agent: { disabled: true }was a runtime config value, so Rollup could not tree-shake the agent chat / AI SDK. An isolated Scalar/Swagger static page would have kept the same lockfile and advisory surface. The native catalog already listed HTTP operations; the REST tab now does the same for the Internal vs Exposed OpenAPI documents. - Replacement:
RestReferenceViewinclient/src/pages/ApiExplorer.jsxfetches/api/api-docs/internal/openapi.jsonor/api/api-docs/openapi.jsonand lists operations. No second UI framework. - Regression cover:
client/src/pages/ApiExplorer.bundle.test.jsasserts the client manifest no longer declares@scalar/api-reference-react, and afternpm run build --prefix clientasserts no Scalar/Vue-named chunks remain inclient/dist/assets. The chunk assertion skips whendist/is absent; CI runs it as its own step right after the client build. - Re-audit trigger: none — do not reintroduce Scalar or another OpenAPI SPA (rapidoc, Stoplight Elements) without a new depfree issue. The native list plus the raw JSON links is the reference UI.
kokoro-js — REMOVED 2026-09-11
- Decision: retire the in-process backend in favor of the existing Piper CLI backend (#7011).
- Dependencies: removed kokoro-js and its exclusive tar/protobufjs overrides. Sharp remains a direct dependency used by image processing.
- Upgrade: migration 376 switches saved Kokoro settings to Piper, preserving the old settings and any customized Piper voice. Reads and saves also normalize restored legacy settings. Settings → Voice explains the change; choose a voice and use Save & Reconcile to install the binary/model. No models download during migration.
- Character profiles: historical Kokoro profiles and audio remain intact. Synthesis reports an actionable retirement error; select/promote a Piper preset to replace the binding rather than silently changing a character's voice.
google-auth-library — REMOVED (direct) 2026-09-12 (issue #7013)
- Usage (was):
server/services/googleAuth.jsimportedOAuth2Clientdirectly for the shared Calendar/Messages OAuth flow. - Resolution: the service now uses
auth.OAuth2from the existing@googleapis/calendarSDK. That export is the sameOAuth2Clientclass supplied throughgoogleapis-common, so authorization URLs, token exchange, credentials, and refresh-token persistence keep the existing behavior. - Transitive cost: the lockfile retains
[email protected]undergoogleapis-common(shared by the Calendar and Gmail SDKs) and removes the direct11.0.2copy plus its exclusive nested dependencies. This removes a redundant direct pin, not the transitive package itself. - Regression cover:
docs/deps-doc.test.jsand the Calendar route/account/sync suites pass; a direct module-load smoke check confirms thatauth.OAuth2is constructible.
eslint (and the keyv / flat-cache / file-entry-cache chain) — REMOVED 2026-08-04
- Trigger: the August 2026 Shai-Hulud npm compromise hit
keyv,flat-cache, andfile-entry-cache(among ~430 packages). PortOS was never exposed — it held[email protected],[email protected],[email protected], while the malicious releases were the next major in each line (6.0.0/6.1.24/11.1.6), unreachable from the^4/^4.0.0/^8.0.0ranges. npm has since unpublished all three, and no install hook ever existed in the tree. - Why they were here at all: not direct dependencies. A single chain under one root —
eslint → file-entry-cache → flat-cache → keyv— client workspace, devDependencies only.[email protected](latest) hard-requiresfile-entry-cache@^8.0.0; no eslint release drops it. So the only way to shed them was to stop using eslint. - Semver headroom was already zero: the highest published
[email protected]is8.0.0,[email protected]is4.0.1,[email protected]is4.5.4. Anoverridespin would have been a no-op — there was nowhere to float. Removal was therefore a maintenance win, not a security fix. - Resolution: replaced eslint with
@biomejs/biome(the Quick Reference row andclient/package.jsonare the version's home — naming a pin here only drifts). Client lockfile 447 → 337 packages (−110; the eslint tree out, 9 Biome entries in, only 1 platform binary installed). All four eslint-chain packages now report 0 occurrences inclient/package-lock.json. typescriptwent with it. It was a client devDependency solely to satisfy@eslint-react/eslint-plugin's peer dep — the client has notsconfig, zero.ts/.tsxsources, notscscript, and nothing peer-depends on it. Removing it also retires the.github/dependabot.ymlignore rule that pinned it below TS7 (and issue #3351, which tracked waiting on typescript-eslint for TS7 support — now moot).- Rule parity was proven with fixtures, not inferred from a clean run — a linter with no rules also reports "0 problems". Every rule the old config enforced fires under Biome;
npm run lintcovers the same 1859 files with 0 problems.exhaustive-depswas alreadyoff(documented, deliberate), which is what made this a half-day swap instead of a risky one. - The
crypto.randomUUIDban survives as a GritQL plugin (client/lint-no-random-uuid.grit). This rule is load-bearing:crypto.randomUUIDis undefined on insecure origins, and PortOS is routinely reached over plain HTTP via Tailscale. It matches on the CST node kind rather than code snippets, so it catchescrypto.,globalThis.crypto.,window.,self., optional chaining, baretypeofreferences, and assignment targets — and, matching the old ESLint rule exactly, notcrypto['randomUUID']. Exemptions forsrc/lib/uuid.jsandsrc/**/*.test.{js,jsx}are expressed as negated globs, because a Biome override'spluginslist is additive:plugins: []does NOT disable an inherited plugin. Do not "simplify" that back. - Deliberately scoped: Biome's formatter and
assistare disabled (enabling them would rewrite all 1859 files in one unreviewable diff), and the rule set usespreset: "none"with an explicit list rather than Biome's broaderrecommended— keeping this a tooling swap, not a smuggled lint-policy change. Adopting more Biome rules is a separate decision. - Config is
biome.jsonc, notbiome.json— the latter rejects comments, failing with a misleading "expected an object, received an array", and the rationale comments inherited fromeslint.config.jsare worth keeping.
sax — REMOVED (issue #1824)
- History: was used by
server/services/claudeChangelog.jsand the Apple Health XML import; originally kept as "transitive via pm2→needle" (the 2026-04 audit above). - Resolution: replaced with an owned streaming parser (
server/services/appleHealthXmlParser.js) in issue #1824, and pm2 7.x no longer pulls it. No longer inserver/package.json.
Heavy-Mode Notes
If /do:depfree --heavy is run, the following Tier 1 entries would drop to Tier 2/3 and become replacement candidates regardless of popularity:
@googleapis/calendar— narrow surface used; could be replaced with direct REST calls + owned auth (Gmail already is, viagmailApi.js).- Many of the
@dnd-kit/*,@xterm/*,lucide-react,rechartsdeps would be re-evaluated. pm2would NOT be replaced (foundational process manager).
This is intentionally NOT done in default mode — current dependency footprint is reasonable for the project's deployment context (single-user, Tailscale-private).
Extreme-Mode Notes
/do:depfree --extreme (and the better-dependency-freedom scheduled audit with its removal bar set to Extreme) aims at zero dependencies: it forces the strongest model tier at maximum reasoning effort, drops the line ceiling in favor of a parity-test gate, and keeps only what cannot be owned responsibly — the Node runtime and npm, security-sensitive protocol implementations (the pg wire protocol and its authentication, TLS), native bindings (node-pty, better-sqlite3-multiple-ciphers, sharp), and the CI-required test runner. Under that bar the following Tier 1 entries become candidates, each needing a written replacement design and a parity suite before any call site switches:
expressandcompression— the used surface is routing, middleware chaining, static files, body parsing, and Brotli/gzip negotiation overnode:httpandnode:zlib.socket.io— the used surface is rooms, acks, and reconnection over WebSocket; a design must cover the client half too.react/react-dom— a product-level rewrite rather than a dependency swap; expected to be recordedSKIPPED_INFEASIBLEwith a design sketch and a filed issue, which is the mode's required output for a package it cannot remove.@googleapis/*— direct REST calls plus owned OAuth signing.chokidar,@dnd-kit/*,@xterm/*,lucide-react,recharts,three— re-evaluated by used surface, not size.
An extreme run re-tests every SKIPPED_INFEASIBLE row here rather than honoring it, so this section is a forecast, not a decision log; the decision log is the tables above, which record the mode each row was reached under.
Override Pins (overrides)
Defined in package.json (root + server + client + autofixer) — kept current to dodge known upstream advisories:
[email protected](root + server + client)[email protected],[email protected],[email protected](root + server)[email protected],[email protected](server + client)[email protected],[email protected],[email protected](server + autofixer — the express-reachable subset;autofixer/mirrors only these three because a pin for a package absent from the tree reads as protection that does not exist)[email protected](server only)[email protected](server + client)[email protected](server only)[email protected](client only, keeps drei/fiber on one three copy)
The retired Kokoro dependency tree no longer needs the tar or protobufjs override pins.
These exist purely to force-bump transitive deps; revisit if npm audit flags new advisories.
Keep this list in sync with the manifests — a stale entry here reads as a pin that exists when it doesn't. server/dependency-overrides.test.js guards the pins themselves (cross-manifest version parity, a MINIMUM_SAFE floor per remediated advisory, that every workspace shipping a tracked lockfile is in the governed manifest list, that each tracked lockfile actually resolves the pinned version, and that every pin names a package its own workspace lockfile still contains — so a pin outliving its consumer fails rather than lingering as imaginary protection), but it does not read this document. When a floor moves because a new advisory covers the version already pinned — as [email protected] did under GHSA-5p4m-2wfm-xmqj — bump the pin, the MINIMUM_SAFE row, and this list together.
Not every compromised package warrants a pin. A pin only helps when the installed version is below the top of its permitted range — otherwise there is nothing to force. The August 2026 keyv / flat-cache / file-entry-cache compromise deliberately got no pin: each range was already at its ceiling (highest published [email protected] is 4.5.4, etc.), so a pin would have been a no-op, and the packages were removed outright instead. Check headroom (npm view <pkg>@<major> version) before adding an entry here.
Direct Dependency Pinning
Every direct dependency and devDependency, in every manifest, is an exact version — no ^, ~, >=, or *. A caret range lets a fresh npm install (or any tree re-resolution: a Dependabot bump to a sibling package, npm run setup's npm install --no-save --prefix server, scripts/ensure-deps.js's clean-reinstall path) float past a version nobody reviewed — the same argument that already makes an override pin exact, applied to the packages this repo depends on directly. Upgrades arrive as reviewable Dependabot PRs instead.
server/dependency-overrides.test.js enforces this across all four manifests, so a dependency added with a caret fails the suite rather than shipping.
Install-Script Policy
ignore-scripts=true is pinned in every workspace's own .npmrc (root, client/, server/, autofixer/, browser/) — not just the repo root. The list is not maintained by hand: discoverWorkspaces() in scripts/trusted-rebuilds.js globs every top-level directory carrying a package.json, and the test asserts each discovered one has the setting — so a workspace added later is caught rather than silently unguarded. npm resolves the project .npmrc from the local prefix and never walks up the directory tree, so a root-only setting does not cover cd client && npm install or npm ci --prefix server (what CI runs). Deleting any workspace .npmrc silently re-grants every dependency in that workspace an install-time code-execution slot — the vector the Shai-Hulud worm used.
Packages that legitimately need an install script are named explicitly in the allowlist in scripts/trusted-rebuilds.js, the single source consumed by npm run setup, scripts/ensure-deps.js, setup.ps1, update.sh / update.ps1, and CI. scripts/trusted-rebuilds.test.js fails if a workspace .npmrc loses the setting, or if a dependency appears with an install hook that nobody has explicitly decided about. Because CI caches server/node_modules between jobs, scripts/trusted-rebuild-stamp.js writes a mark into the tree in the same step that rebuilds it and checks that mark after a cache restore — a tree cached before the rebuild is otherwise indistinguishable from a good one, since the allowlisted packages all ship prebuilt bindings and import fine either way.
Install-time dependency patches
None at present. PortOS carried two from 2026-09/10 to 2026-10-21, both against packages that only PM2 pulled in through proxy-agent: an FTP LIST-date fallback for get-uri (#9444, #9462, with basic-ftp and ip-address overrides) and a recursion bound for braces (#9906, below). PM2 7.1.0 dropped proxy-agent and vendored chokidar, so none of those packages resolve in any lockfile and the patches, their overrides, their tests and the patches field of the trusted-rebuild stamp were removed with that bump. A tree stamped before the removal reads as stale and is rebuilt. If a patch is ever needed again, the hook point is rebuildTrusted in scripts/trusted-rebuilds.js, which every managed install path already calls after npm install because ignore-scripts=true rules out a postinstall hook.
PM2 brace recursion advisory (#9906)
The upstream braces advisory GHSA-vfj7-8cjw-p6xm never got a patched braces release. PM2 7.1.0 (2026-10-21) vendors chokidar with a bounded brace expansion and drops the braces dependency, so no lockfile resolves braces any more; the local depth patch PortOS carried from 2026-10-03 (scripts/lib/bracesDepthPatch.js) went with it. If a future dependency reintroduces braces 3.x, check first whether the dependency can be moved off it before restoring the patch from history.
Inline Audit Policy
audit=false is pinned in the same five .npmrc files, enforced by the same discovered-workspace test. This turns off only the advisory lookup npm install performs after it has already resolved and written node_modules — it does not change what gets installed.
It is off because it is a hang risk on the path that matters least. The lookup only prints a summary, but npm blocks on it, and a request that stalls costs fetch-timeout (300s by default) times fetch-retries (2) before npm gives up. On 2026-09-03 the endpoint began completing the TLS handshake and then never sending a byte; a warm root install that takes 0.15s took 153.88s, of which 0.22s was CPU and the rest was a socket wait. Every managed install path runs four workspace installs in sequence (update.sh, update.ps1, setup.ps1, npm run setup, scripts/ensure-deps.js), so a self-update stalled for roughly ten minutes on a report written to data/update.log. PortOS is distributed software that self-updates on machines nobody is watching, so a third-party endpoint must not be able to wedge the update path for something advisory.
Nothing is lost. Dependency safety here is enforced statically rather than by a live network call: direct dependencies are pinned to exact versions and the overrides blocks are pinned too, both asserted by server/dependency-overrides.test.js — which deliberately replaced an npm audit shell-out because "audit needs the network and its output drifts". CI never ran npm audit either. Run npm audit directly when you want the report; the periodic dependency audits recorded in this document are where it belongs.