feat: patch-package for SES-compat patches; root patches/ as single source of truth (#874)

## Summary

`@MetaMask/ocap-kernel` and `@metamask/kernel-utils` depend on
`@chainsafe/libp2p-yamux@7.0.4`, which requires a patch for SES/lockdown
compatibility. Previously the patch was applied via Yarn's `patch:`
protocol from a root `.yarn/patches/` file — invisible to and
unreproducible by consumers.

This PR switches to `patch-package` and exposes the patch in published
npm tarballs so consumers can apply it. Root `patches/` is the single
source of truth; per-package copies are generated at publish time by a
script that uses dependency graph analysis to determine which packages
need to ship the patch.

## Changes

**patch-package setup**
- Replace the Yarn `patch:` URL for `@chainsafe/libp2p-yamux` with a
plain `7.0.4` version specifier across all dependent packages
- Add `patch-package` as a root `devDependency`; add it to the root
`postinstall` so the patch is applied after every `yarn install`
- Add `patches/@ChainSafe+libp2p-yamux+7.0.4.patch` at the repo root and
remove the old `.yarn/patches/` file

**Graph-based sink analysis**
- Add `scripts/copy-patches.cjs`: for each root patch file, computes
which published packages are "sinks" — packages whose consumers may not
install any sibling that already handles the patch — and copies patch
files to their `patches/` dirs before packaging
- A sink is any package that directly depends on the patched dep and has
no other package in that set as a transitive dependency. Currently
`@metamask/kernel-utils` is the only sink (`@MetaMask/ocap-kernel`
depends on it, so its consumers always get `kernel-utils`'
`postinstall`)
- Add `node scripts/copy-patches.cjs` to `scripts/prepack.sh`; add
`packages/*/patches/` to `.gitignore`

**Sink package (`@metamask/kernel-utils`)**
- Add `"patches/"` to `files` and `"postinstall": "patch-package
--patch-dir patches"` so the patch is applied for consumers
- Add `"patch-package": "*"` to `peerDependencies` to signal the
requirement

**Non-sink package (`@MetaMask/ocap-kernel`)**
- Remove `"patches/"` from `files`; no `postinstall` needed
(kernel-utils handles it)

**`yarn constraints` enforcement**
- Replace `expectPatchedDependenciesAreDeclaredAndShipped` with
graph-aware rules: `expectPatchShippingIsCorrect` (sinks must have the
required fields; non-sinks must not — auto-fixable where possible) and
`expectNoPatchesForRemovedDependencies` (errors if a root patch targets
a package no longer depended on by any workspace)
- Keep `expectNoPatchProtocolProductionDependencies`

## Testing

- `yarn constraints` passes; `kernel-utils` is identified as a sink and
has all required fields; `ocap-kernel` is identified as a non-sink and
has none
- `node scripts/copy-patches.cjs` copies the patch to
`packages/kernel-utils/patches/` only; the generated dir does not appear
in `git status` (gitignored)
- The patch is applied on `yarn install` (verified via `grep
Object.defineProperty
node_modules/@chainsafe/libp2p-yamux/dist/src/decode.js`)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> **Medium Risk**
> Changes install and publish-time behavior by introducing
`patch-package`, root `patches/`, and new Yarn constraint enforcement,
which could break dependency installation or package publishing if
misconfigured. Runtime code changes are limited to applying an existing
third-party patch.
> 
> **Overview**
> Moves SES/lockdown dependency patching from Yarn’s `patch:` protocol
to `patch-package`, making the repo root `patches/` directory the single
source of truth and applying patches automatically on root
`postinstall`.
> 
> Adds publish-time patch shipping: `scripts/copy-patches.cjs` computes
“sink” packages from the workspace dependency graph and copies root
patches into each sink’s `patches/` directory during `prepack`
(generated dirs are gitignored). Yarn constraints are extended to forbid
`patch:` in production deps, enforce correct sink/non-sink patch
shipping config (e.g., `kernel-utils` ships `patches/`, declares
`patch-package` peer dep, and runs a guarded `postinstall`), and error
on orphaned root patches.
> 
> Also updates a few package dependencies (e.g.,
`@metamask/snaps-utils`, `@metamask/design-system-react`) and
regenerates `yarn.lock` accordingly.
> 
> <sup>Written by [Cursor
Bugbot](https://cursor.com/dashboard?tab=bugbot) for commit
0de6bb7. This will update automatically
on new commits. Configure
[here](https://cursor.com/dashboard?tab=bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: rekmarks

.gitignore

@@ -81,6 +81,9 @@ node_modules/
 # Bundle files
 *.bundle
 
+# Generated per-package patches dirs (populated by scripts/copy-patches.cjs at publish time)
+packages/*/patches/
+
 # Playwright reports
 playwright-report
 

.yarn/patches/@chainsafe-libp2p-yamux-npm-7.0.4-284c2f6812.patch

@@ -66,6 +66,30 @@ See [`packages/create-package/README.md`](packages/create-package/README.md).
 
 For information on creating releases, see the [MetaMask/core release documentation](https://github.com/MetaMask/core/blob/main/docs/contributing.md#releasing-changes).
 
+### Patches
+
+Some third-party dependencies require patches for SES/lockdown compatibility. The root
+`patches/` directory is the single source of truth for all patches, applied automatically
+on `yarn install` via `patch-package`.
+
+Published packages that ship patches to consumers are called "sinks". Sinks are determined
+by analyzing the dependency graph: a non-private package that directly depends on a patched
+dependency is a sink if none of its transitive internal dependencies also depend on that
+patched dependency. Only `dependencies` are considered for sink analysis (not
+`peerDependencies` or `devDependencies`).
+
+Sink packages include `patches/` in their `files` field, declare `patch-package` as a
+`peerDependency`, and have a `postinstall` script that runs `patch-package --patch-dir patches`.
+The `scripts/copy-patches.cjs` script copies root patches into each sink at publish time,
+and `yarn constraints` enforces the correct configuration.
+
+**Adding a patch:** Place the `.patch` file in the root `patches/` directory. Run
+`yarn constraints --fix` to update sink packages, and verify with
+`node scripts/copy-patches.cjs`.
+
+**Removing a patch:** Delete the `.patch` file from the root `patches/` directory and run
+`yarn constraints --fix` to clean up sink packages.
+
 ## References
 
 - [Glossary](./docs/glossary.md)

README.md

@@ -25,7 +25,7 @@
     "lint:eslint": "yarn eslint . --cache",
     "lint:fix": "yarn constraints --fix && yarn lint:eslint --fix && yarn lint:misc --write && yarn lint:dependencies:fix",
     "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html'  '**/*.yml' '!**/CHANGELOG.old.md' '!.yarnrc.yml' '!CLAUDE.md' '!merged-packages/**' --ignore-path .gitignore  --log-level error",
-    "postinstall": "simple-git-hooks && yarn rebuild:native",
+    "postinstall": "patch-package && simple-git-hooks && yarn rebuild:native",
     "prepack": "./scripts/prepack.sh",
     "rebuild:native": "./scripts/rebuild-native.sh",
     "test": "vitest run",
@@ -89,6 +89,7 @@
     "globals": "^16.0.0",
     "lint-staged": "^15.5.0",
     "lodash": "^4.17.21",
+    "patch-package": "^8.0.0",
     "playwright": "^1.58.2",
     "prettier": "^3.5.3",
     "prettier-plugin-packagejson": "^2.5.10",
@@ -126,7 +127,8 @@
       "@metamask/kernel-cli>@metamask/kernel-node-runtime>@libp2p/webrtc>@ipshipyard/node-datachannel": false,
       "@metamask/kernel-cli>@metamask/kernel-node-runtime>@metamask/kernel-store>better-sqlite3": false,
       "@metamask/kernel-cli>@metamask/kernel-node-runtime>@metamask/streams": false,
-      "@metamask/kernel-cli>@metamask/kernel-shims>@libp2p/webrtc>@ipshipyard/node-datachannel": false
+      "@metamask/kernel-cli>@metamask/kernel-shims>@libp2p/webrtc>@ipshipyard/node-datachannel": false,
+      "@metamask/kernel-cli>@metamask/kernel-utils": false
     }
   },
   "resolutions": {

package.json

@@ -30,7 +30,7 @@
   },
   "dependencies": {
     "@chainsafe/libp2p-noise": "^16.1.3",
-    "@chainsafe/libp2p-yamux": "patch:@chainsafe/libp2p-yamux@npm%3A7.0.4#~/.yarn/patches/@chainsafe-libp2p-yamux-npm-7.0.4-284c2f6812.patch",
+    "@chainsafe/libp2p-yamux": "7.0.4",
     "@libp2p/autonat": "2.0.38",
     "@libp2p/bootstrap": "11.0.47",
     "@libp2p/circuit-relay-v2": "3.2.24",

packages/brow-2-brow/package.json

@@ -73,7 +73,7 @@
     "@metamask/logger": "workspace:^",
     "@metamask/ocap-kernel": "workspace:^",
     "@metamask/rpc-errors": "^7.0.3",
-    "@metamask/snaps-utils": "^11.7.1",
+    "@metamask/snaps-utils": "^12.1.0",
     "@metamask/streams": "workspace:^",
     "@metamask/superstruct": "^3.2.1",
     "@metamask/utils": "^11.9.0",

packages/kernel-browser-runtime/package.json

@@ -60,7 +60,7 @@
     "test:dev:quiet": "yarn test:dev --reporter @ocap/repo-tools/vitest-reporters/silent"
   },
   "dependencies": {
-    "@metamask/design-system-react": "^0.6.0",
+    "@metamask/design-system-react": "^0.9.0",
     "@metamask/design-system-tailwind-preset": "^0.6.1",
     "@metamask/design-tokens": "^8.1.1",
     "@metamask/kernel-browser-runtime": "workspace:^",

packages/kernel-ui/package.json

@@ -10,6 +10,22 @@ or
 
 `npm install @metamask/kernel-utils`
 
+## SES/Lockdown Compatibility
+
+This package is designed to run under [SES](https://github.com/endojs/endo/tree/master/packages/ses) (Secure ECMAScript lockdown). Some of its dependencies require patches to work in a locked-down environment. The required patch files are included in the `patches/` directory of this package and are applied automatically via the `postinstall` script using [`patch-package`](https://github.com/ds300/patch-package).
+
+Add `patch-package` as a development dependency of your project:
+
+```sh
+yarn add --dev patch-package
+```
+
+or
+
+```sh
+npm install --save-dev patch-package
+```
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).

packages/kernel-utils/README.md

@@ -75,7 +75,8 @@
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.cts",
   "files": [
-    "dist/"
+    "dist/",
+    "patches/"
   ],
   "scripts": {
     "build": "ts-bridge --project tsconfig.build.json --no-references --clean",
@@ -88,6 +89,7 @@
     "lint:eslint": "eslint . --cache",
     "lint:fix": "yarn lint:eslint --fix && yarn lint:misc --write && yarn constraints --fix && yarn lint:dependencies",
     "lint:misc": "prettier --no-error-on-unmatched-pattern '**/*.json' '**/*.md' '**/*.html' '!**/CHANGELOG.old.md' '**/*.yml' '!.yarnrc.yml' '!merged-packages/**' --ignore-path ../../.gitignore --log-level error",
+    "postinstall": "[ ! -d patches ] || patch-package --patch-dir patches",
     "publish:preview": "yarn npm publish --tag preview",
     "test": "vitest run --config vitest.config.ts",
     "test:clean": "yarn test --no-cache --coverage.clean",
@@ -98,7 +100,7 @@
   },
   "dependencies": {
     "@chainsafe/libp2p-noise": "^16.1.3",
-    "@chainsafe/libp2p-yamux": "patch:@chainsafe/libp2p-yamux@npm%3A7.0.4#~/.yarn/patches/@chainsafe-libp2p-yamux-npm-7.0.4-284c2f6812.patch",
+    "@chainsafe/libp2p-yamux": "7.0.4",
     "@endo/captp": "^4.4.8",
     "@endo/errors": "^1.2.13",
     "@endo/exo": "^1.5.12",
@@ -153,6 +155,7 @@
   },
   "peerDependencies": {
     "acorn": "^8.15.0",
+    "patch-package": "^8.0.0",
     "vite": "^7.3.0"
   },
   "peerDependenciesMeta": {

packages/kernel-utils/package.json

@@ -10,6 +10,34 @@ or
 
 `npm install @metamask/ocap-kernel`
 
+## SES/Lockdown Compatibility
+
+This package is designed to run under [SES](https://github.com/endojs/endo/tree/master/packages/ses) (Secure ECMAScript lockdown). One of its dependencies, `@chainsafe/libp2p-yamux`, requires a patch to work in a locked-down environment. The required patches are listed in the `patchedDependencies` field of this package's `package.json`, and the patch files are included in the `patches/` directory of this package.
+
+Apply them using [`patch-package`](https://github.com/ds300/patch-package):
+
+1. Install `patch-package`:
+
+   ```sh
+   npm install --save-dev patch-package
+   ```
+
+2. Copy the patch file(s) to your project's `patches/` directory:
+
+   ```sh
+   cp node_modules/@metamask/ocap-kernel/patches/* patches/
+   ```
+
+3. Add a `postinstall` script to your `package.json`:
+
+   ```json
+   "scripts": {
+     "postinstall": "patch-package"
+   }
+   ```
+
+4. Run `npm install` (or your package manager's equivalent) to apply the patches.
+
 ## Contributing
 
 This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).