fyn 3.0.4 → 3.1.0

package/README.md

@@ -138,33 +138,123 @@ TypeScript paths, or equivalent tool settings to use it.
 ### Lifecycle script allow list (`fyn.allowScripts`)
 
 As a security hardening measure, `fyn` does **not** run a package's npm lifecycle
-scripts (`preinstall`, `install`, `postinstall`) during install unless the package
-came from a configured registry (the primary `registry` or a `@scope:registry`) or
-is a local `file:`/`link:`/symlink dependency.
+scripts (`preinstall`, `install`, `postinstall`) during install unless someone has
+approved that package. Installing a package otherwise runs its author's code before
+you have read a line of it, and a compromised release reaches every machine that
+installs it.
 
-Packages pulled from other sources — `github:`, git URLs (`git+https`, `git+ssh`,
-…), and `http(s)` tarball URLs — have their lifecycle scripts **skipped by default**,
-and `fyn` prints a warning showing how to allow them.
+Approval is per package, in `fyn.allowScripts`. The only packages exempt are your
+own — `file:`/`link:` dependencies and fynpo siblings, which the pull request that
+changed them already reviewed.
+
+When an install finds scripts nobody has approved it **stops and asks**, on a
+terminal. In CI — or anywhere else there is no terminal to ask on — it **fails**,
+rather than quietly handing you a tree whose native packages were never built. See
+[`fyn.scriptPolicy`](#choosing-a-trust-model-fynscriptpolicy) for the opt-out back to
+trusting a package because of where it came from.
 
 To allow specific scripts for such a package, add a `fyn.allowScripts` map to your
-`package.json`. Each key is `name@<spec-or-version>` and the value is the list of
-allowed script names:
+`package.json`. Each key is a package name and each value says which versions and
+which scripts are approved:
+
+```json
+{
+  "fyn": {
+    "allowScripts": {
+      "sharp": { "semver": "^0.34.4", "scripts": ["install"] },
+      "esbuild": { "semver": "^0.28.2 || ^0.29.0" },
+      "canvas": { "scripts": ["install"] },
+      "zlib-sync": { "scripts": ["*", "!postinstall"] },
+      "lodash": {},
+      "malware": false
+    }
+  }
+}
+```
+
+- **`semver`** — approved only for versions matching this range. Omit it to approve
+  every version. A union works: `"^0.28.2 || ^0.29.0"`.
+- **`scripts`** — approved only for these lifecycle scripts. Omit it to approve all
+  of them. Script names are matched case-insensitively.
+- So `esbuild` above is "those two release lines, any script", `canvas` is "any version,
+  `install` only", `zlib-sync` is "any script except `postinstall`", and `lodash` is "any
+  version, any script".
+- Inside `scripts`, **`!name` denies that one script** and `+name` allows it, same as a bare
+  name. So `["*", "!postinstall"]` is "every install script except postinstall", and
+  `["+install", "!preinstall"]` spells both halves out. `!*` denies them all. A `!` beats a
+  bare or `+` name for the same script, whichever order they appear in.
+- **`false`** denies a package outright. A denial wins over everything: any other
+  entry matching the same package, `allowTopLevelScripts`, an `approve --all`, and
+  an approval in a wider scope. Removing the `false` is the only way to undo it.
+  [`fyn.denyScripts`](#blacklisting-packages-fyndenyscripts) says the same thing in its own
+  map, can also scope by version and script, and is what `install-scripts deny` writes.
+
+This is the form `fyn install-scripts approve` writes. Several older and shorter
+forms are still read, so a hand-written or npm-written allowlist keeps working:
+
+| entry | means |
+|---|---|
+| `"sharp": true` / `"sharp": "*"` | any version, any script |
+| `"sharp": ["install"]` / `"sharp": "install"` | any version, those scripts |
+| `"sharp": "0.34.4"` / `"sharp": "^0.34.0"` | matching versions, any script — npm's form |
+| `"sharp@^0.34.0": ["install"]` | the range in the key, those scripts |
+| `"foo@github:user/foo#v1": ["install"]` | matched against the requested spec |
+
+A range in the key is matched against the **resolved version**, so `sharp@^0.34.0`
+covers `0.34.4`. A key whose spec is not a semver range — a `github:`/git/URL spec —
+is matched literally against what the dependency asked for, since there is no
+version to range over. When a key and its value both carry a version constraint,
+both have to be satisfied.
+
+#### Blacklisting packages (`fyn.denyScripts`)
+
+`fyn.denyScripts` is the allowlist's opposite, and it takes **the same map shape** — it answers
+the same two questions, which versions and which scripts. The only difference is that a match
+denies:
 
 ```json
 {
   "fyn": {
     "allowScripts": {
-      "foo@github:user/foo#v1": ["install", "postinstall"],
-      "bar@2.3.0": ["preinstall"]
+      "sharp": { "semver": "^0.34.4", "scripts": ["install"] }
+    },
+    "denyScripts": {
+      "malware": {},
+      "sketchy": { "semver": "^2.0.0" },
+      "esbuild": { "scripts": ["postinstall"] }
     }
   }
 }
 ```
 
-- The key matches **either** the original dependency spec (e.g. `foo@github:user/foo#v1`)
-  **or** the resolved version (e.g. `bar@2.3.0`).
-- Script names are matched case-insensitively.
-- Use `["*"]` (or `true`) as the value to allow all lifecycle scripts for that package.
+As on the allow side, an absent `semver` means every version and an absent `scripts` means
+every install script. So `malware` is denied outright, `sketchy` only at 2.x, and `esbuild`
+keeps every script but `postinstall`.
+
+Setting both is the point: `allowScripts` says what you reviewed, `denyScripts` says what you
+refuse, and **deny wins** — over a matching `allowScripts` entry, over `allowTopLevelScripts`,
+over an `install-scripts approve --all`, over `scriptPolicy: "all"`, and over an approval
+recorded in a wider scope. Removing the entry is the only way to undo it.
+
+- Entries need no `!` markers. Every entry in this map is already a denial, so `scripts` there
+  lists what to deny.
+- It applies at **every scope** — `fynpo.json` `fyn.options`, the package's own
+  `package.json`, and `--deny-scripts` on the command line — and the three **union**. No scope
+  can drop what a wider one denied, so a monorepo-wide denial is not something an individual
+  package can talk its way out of.
+- `fyn install-scripts deny <pkg>` writes an empty entry — `{}`, every version, every script.
+  In a fynpo repo it writes the root `fynpo.json`; `--local` writes the package's own
+  `package.json`. Narrowing an entry is a hand edit.
+- For one run: `fyn install --deny-scripts=malware,sketchy`. A bare name there means the same
+  as `{}`.
+- A denied package is **skipped, not queued for review**. The install reports it in the
+  end-of-install summary and carries on — it is never offered to the approval prompt, because
+  approving it could not take effect.
+- `install-scripts prune` never touches it. It drops stale *approvals* — measured against what
+  is actually installed, hoisted packages included — and a denial for a package you no longer
+  install is still the answer if it ever comes back.
+- The older `"allowScripts": { "malware": false }` form is still read and denies the whole
+  package; `denyScripts` is the form that can also scope by version and script.
 
 #### Trusting direct dependencies (`fyn.allowTopLevelScripts`)
 
@@ -182,6 +272,10 @@ any non-registry package that is declared **directly** in your top-level
 }
 ```
 
+- **`"source"` mode only.** Under `"review"` (the default) it is ignored: the question there
+  is whether someone read the code, and "I typed this name into my `package.json`" does not
+  answer it. A blanket exemption for every direct dependency would be the widest hole in the
+  policy, and a stale `true` would open it silently.
 - This is **off by default**; the deny-by-default policy above is unchanged.
 - It only applies to dependencies you declared directly in the top-level
   `package.json`. Non-registry packages pulled in **transitively** stay blocked
@@ -196,6 +290,129 @@ any non-registry package that is declared **directly** in your top-level
 > has been pushed there. Declaring it in your `package.json` is an explicit trust
 > decision — pin to a commit/tarball you've reviewed when that matters.
 
+#### Choosing a trust model (`fyn.scriptPolicy`)
+
+`fyn.scriptPolicy` picks which question decides whether a package may run its scripts:
+
+| mode | registry packages | git/URL packages | workspace-local packages |
+|---|---|---|---|
+| `"review"` *(default)* | need an allowlist entry | need an allowlist entry | run their scripts |
+| `"source"` | run their scripts | need an allowlist entry | run their scripts |
+| `"all"` | run their scripts | run their scripts | run their scripts |
+| `"off"` | nothing runs | nothing runs | nothing runs |
+
+`"review"` asks whether someone approved *this code* — npm 12's model, and the only one that
+covers a compromised release of an ordinary dependency. `"source"` asks only where the package
+*came from*, so anything off a configured registry runs; it is the opt-out for a project that
+would rather not maintain an allowlist. `"off"` is npm's `ignore-scripts`, and like npm's it
+wins over the allowlist rather than being overridden by it.
+
+```json
+{
+  "fyn": {
+    "scriptPolicy": "source"
+  }
+}
+```
+
+Or for one run: `fyn install --script-policy=source`.
+
+`"all"` asks nothing: every package runs its scripts whatever its source, including the
+`github:`/git/URL ones every other mode blocks. Reach for it when you have decided the tree is
+already trusted — a vendored or internally mirrored dependency set, or a throwaway sandbox — and
+maintaining approvals buys you nothing. It is the loosest mode fyn has, looser than the
+behavior fyn had before the allowlist existed.
+
+A denial is still honored under `"all"`: `fyn.denyScripts` and an `allowScripts` `false` are
+checked *before* the mode is. That makes `"all"` plus denials a blacklist — everything runs
+except what you name — instead of a switch that discards the denials you already recorded.
+
+```json
+{
+  "fyn": {
+    "scriptPolicy": "all",
+    "denyScripts": { "malware": {} }
+  }
+}
+```
+
+Workspace-local packages — `file:`/`link:` deps and fynpo siblings — are exempt in **every**
+mode, including `"review"`: an allowlist is a review gate on code you did not write, and
+monorepo source is reviewed by the pull request that changed it. Set
+`fyn.reviewLocalPackages: true` if you want them reviewed like anything else. A local path
+declared *by* a git package is not workspace-local and stays blocked.
+
+##### What an unapproved package looks like
+
+Under `"review"`, an install that finds unapproved install scripts stops before running
+anything:
+
+```
+2 packages want to run install scripts that have not been approved:
+  sharp@0.34.4     install
+  esbuild@0.28.2   postinstall
+Approve? [a]ll / [s]elect / [n]one (default)
+```
+
+`a` approves them all, `s` walks them one at a time, `n` continues with those scripts skipped.
+An approval is written to your `package.json` — or the monorepo's `fynpo.json` — so the next
+install does not ask again.
+
+Where there is no terminal to ask on — CI, a pipe, a git hook — the install **fails** with the
+same list and a non-zero exit, instead of producing a tree whose native packages silently never
+built. Record the approvals in `package.json` and commit them, the way you would a lockfile.
+
+To see what a project would need to approve without changing what an install runs:
+
+```
+fyn install --script-policy=source --allow-scripts-pending
+```
+
+#### One allowlist for a fynpo monorepo
+
+In a fynpo repo the allowlist belongs at the root, in `fynpo.json` under `fyn.options` — one
+approval per dependency, reviewed once, rather than a copy in each of twenty packages:
+
+```json
+{
+  "fyn": {
+    "options": {
+      "scriptPolicy": "review",
+      "allowScripts": { "sharp": true, "esbuild@0.28.2": ["postinstall"] }
+    }
+  },
+  "packages": ["packages/*"]
+}
+```
+
+Scopes combine as: **fynpo config → package.json → CLI**. Approvals accumulate across them; a
+package may add its own but a denial at any scope is final — a `denyScripts` entry or an
+`allowScripts` `false`, either way no tighter scope can lift it. For `scriptPolicy` a package may
+only *tighten* what the repo asked for (`"review"` → `"off"`, never back to `"source"`); a CLI
+flag is a one-off and overrides outright.
+
+#### Reviewing with `fyn install-scripts`
+
+```
+fyn install-scripts ls                 # what is awaiting review (--json for data)
+fyn install-scripts approve <pkg>...   # allow those packages (--all for everything pending)
+fyn install-scripts deny <pkg>...      # blacklist those packages (fyn.denyScripts)
+fyn install-scripts prune              # drop entries for packages no longer installed
+```
+
+`ls` reads what the last install recorded, so run `fyn install` (optionally with
+`--allow-scripts-pending`) first.
+
+`approve` scopes what it writes to the release line it reviewed —
+`"sharp": { "semver": "^0.34.4", "scripts": ["install"] }` — and to the scripts the package
+actually has, so a jump past that range, or a release that later adds a `preinstall`, comes
+back for review. Approving a second version widens that one entry's `semver` into a union
+rather than adding a near-duplicate. `--no-allow-scripts-pin` omits `semver`, approving every
+version. In a fynpo repo it writes to the root `fynpo.json`; `--local` writes to the package's
+own `package.json`.
+
+Approving does not run anything retroactively — run `fyn install` afterwards.
+
 ### Registry-only transitive dependencies (`fyn.enforceRegistryDeps`)
 
 By default, `fyn` requires that **transitive** (non-top-level) dependencies

package/bin/check-node.mjs

@@ -0,0 +1,24 @@
+//
+// Refuse to run on a node older than package.json engines, with a message rather than whatever
+// syntax error the bundle would produce.
+//
+// This is its own module, imported before the bundle, because node parses an entire static
+// import graph before evaluating any of it - a check sitting above a static import of the
+// bundle would never get to run on the versions it exists for.
+//
+const MIN_NODE = "22.12.0";
+
+const parts = version => version.split("-")[0].split(".").map(n => parseInt(n, 10));
+
+const older = (a, b) => {
+  const [pa, pb] = [parts(a), parts(b)];
+  for (let i = 0; i < 3; i++) {
+    if (pa[i] !== pb[i]) return pa[i] < pb[i];
+  }
+  return false;
+};
+
+if (older(process.versions.node, MIN_NODE)) {
+  console.error(`fyn requires node >= ${MIN_NODE}, and this is ${process.versions.node}.`);
+  process.exit(1);
+}

package/bin/fun.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import "./check-node.mjs";
+
+// dynamic so the version check above runs first - see check-node.mjs
+const { fun } = await import("./index.mjs");
+
+try {
+  await fun();
+  process.exit(0);
+} catch (err) {
+  console.error(err);
+  process.exit(1);
+}

package/bin/fyn.mjs

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+
+import "./check-node.mjs";
+
+// dynamic so the version check above runs first - see check-node.mjs
+const { run } = await import("./index.mjs");
+
+try {
+  await run();
+  process.exit(0);
+} catch (err) {
+  console.log(err);
+  process.exit(1);
+}

package/bin/index.mjs

@@ -0,0 +1,43 @@
+//
+// Programmatic entry point. The release bundle is ESM (dist/fyn.mjs) because chalker uses
+// top-level await to optionally load ESM-only chalk, and no CJS output format can represent
+// module-scope await.
+//
+// The bundle is reached through a URL built at runtime rather than a literal specifier, and
+// that is load-bearing rather than stylistic: a literal is statically analyzable, so a consumer
+// that bundles this module - fynpo does - inlines the whole ~3.7MB fyn bundle into its own and
+// ships a frozen second copy of a package it already depends on. A computed URL keeps fyn a
+// runtime dependency of its consumers, which is what it should be.
+//
+// Loading is deferred to the first call for the same reason it always was: this is the whole
+// CLI, and a consumer holding a reference to `run` should not pay to evaluate it.
+//
+import { fileURLToPath, pathToFileURL } from "node:url";
+import Path from "node:path";
+
+const bundleUrl = pathToFileURL(
+  Path.join(Path.dirname(fileURLToPath(import.meta.url)), "..", "dist", "fyn.mjs")
+).href;
+
+let bundle;
+
+const load = async () => {
+  if (!bundle) {
+    bundle = await import(bundleUrl);
+  }
+  return bundle;
+};
+
+/**
+ * @param {...unknown} args forwarded to the CLI's run
+ * @returns {Promise<unknown>} what the CLI's run resolves to
+ */
+export const run = async (...args) => (await load()).run(...args);
+
+/**
+ * @param {...unknown} args forwarded to the CLI's fun
+ * @returns {Promise<unknown>} what the CLI's fun resolves to
+ */
+export const fun = async (...args) => (await load()).fun(...args);
+
+export default { run, fun };