rfc: npm audit fix provides overrides

accepted/0000-audit-overrides.md

@@ -0,0 +1,104 @@
+# npm audit fix can apply overrides
+
+## Summary
+
+Allow npm audit fix to, in addition to updating versions in the dependency
+tree, add overrides to a project's package.json to allow for non-semver
+compatible security fixes.
+
+## Motivation
+
+Currently security updates are limited to patches provided by the original
+authors. This means automatic fixes are impossible if the package is no
+longer maintained or patches include other changes that are undesirable.
+
+## Rationale and Alternatives
+
+Being able to apply hotfix patches allows for security updates to be
+deployed faster and sometimes, at all. Without this, advice when a
+package is unmaintained and has a security vulnerability is to switch to a
+fork, but that's time consuming and difficult, particularly when the package
+is a transitive dependency. This means that even conscientious teams may take
+an extended period of time to apply updates.
+
+This sort of feature exists in some third party tools (eg Synk) but they
+have to subvert npm's own integrity protections to make that possible.
+
+For the purposes of transparency, to be clear the original motivation for this RFC
+is to provide large enterprises (eg Microsoft) with a facility in the tool
+to allow them to provide their employees with internally patched or rebuilt
+versions of dependencies. (Current tooling, like Synk, subverts npm's
+expectations in ways that are potentially fragile.)
+
+## Scenario
+
+### "Hot fixes"
+
+A critical security flaw is found in a dependency of one of your
+dependencies.  The author of the transitive dependency is unavailable to
+provide updates. The package is widely used in your organization, usually
+as a transitive dependency. The ecosystem will eventually switch to another
+module. In the meantime you need some remediation.
+
+You instruct your private registry to provide audit results for the affected
+versions of the module that indicate that a custom patched version is
+available, something like:
+
+```
+{
+    "example": [
+        {
+            "id": 99999,
+            "severity": "high",
+            "title": "Remote Code Execution",
+            "url": "https://npmjs.com/advisories/99999",
+            "vulnerable_versions": "<=3.0.1",
+            "overrides": {
+                "3.0.0": "npm:@company/[email protected]"
+            }
+        }
+    ]
+}
+```
+
+This instructs `npm audit fix` to add an overrides section to your `package.json` like:
+
+```
+"overrides": {
+    "[email protected]": "npm:@company/[email protected]"
+}
+```
+
+## Implementation
+
+This obviously can't be a thing until overrides lands in npm itself.
+
+Updating the npm audit report library may be required.
+
+Updating the `npm audit fix` subcommand will be necessary.
+
+Out of scope: Updating the npm audit end point to start giving this advice. 
+It may or may not be desirable for the team that provides security advice
+for that end point, but that's ultimately up to them.
+
+## Unresolved Questions and Bikeshedding
+
+Immediate plans: I (@iarna) intends to implement a proof-of-concept as a
+stand alone tool using yarn and pnpm overrides.
+
+1. Details of the changes to audit API endpoint result need to be nailed
+down. There are some requirements and nice-to-haves:
+
+  1. Older clients must not fail when receiving the new advice.
+
+  2. Older clients should if possible report the new advice when they can't
+  apply it.
+
+  3. Long term compatibility may not be at issue as all three major npm
+  clients use the same reporting library.  At the same time, it's not clear
+  how easy it will be for other package managers to support npm-audit-report
+  version 2, given that the official documentation is "use arborist" which
+  will be a non-starter for them.
+
+2. ~~Would it be desirable to apply ALL audit fix results as overrides?~~ NO.
+