From 58f7fc69ff3da8afbb1e63546c6a7f0dace361f0 Mon Sep 17 00:00:00 2001 From: Teffen Ellis <592134+GirlBossRush@users.noreply.github.com> Date: Tue, 19 May 2026 13:32:16 +0200 Subject: [PATCH 1/3] website/docs: document npm install-script blocking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The repo's `.npmrc` sets `ignore-scripts=true` to neutralize the dominant npm supply-chain attack pattern (preinstall/postinstall payloads, as used by the recent "Shai-Hulud" and "Mini Shai-Hulud" incidents). The trade-off is that a handful of packages that ship native binaries — esbuild, chromedriver, tree-sitter — need to be rebuilt explicitly when their install step is required. Today this is implicit; a new contributor whose build fails because esbuild's binary didn't unpack has no obvious next step except to disable the protection. Documenting it in both setup guides points them at `npm rebuild --foreground-scripts ` and makes the "don't flip `ignore-scripts` off" guidance explicit. No code or config changes — docs only. Co-authored-by: Agent <279763771+playpen-agent@users.noreply.github.com> --- .../setup/frontend-dev-environment.md | 14 ++++++++++++++ .../developer-docs/setup/full-dev-environment.mdx | 14 ++++++++++++++ 2 files changed, 28 insertions(+) diff --git a/website/docs/developer-docs/setup/frontend-dev-environment.md b/website/docs/developer-docs/setup/frontend-dev-environment.md index 03bcb0256ce1..95b17d31e49b 100644 --- a/website/docs/developer-docs/setup/frontend-dev-environment.md +++ b/website/docs/developer-docs/setup/frontend-dev-environment.md @@ -55,6 +55,20 @@ If you're focusing solely on frontend development, you can create a minimal deve make web-watch ``` + :::info npm install scripts are disabled by default + + The repository's `.npmrc` sets `ignore-scripts=true` so `preinstall`/`install`/`postinstall` lifecycle scripts do not run during `npm ci`. This is intentional: it neutralizes the dominant npm supply-chain attack pattern (recent examples: "Shai-Hulud" and "Mini Shai-Hulud") at the cost of skipping a few legitimate native-binary unpacks. + + If the watch build fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild only that package: + + ```shell + npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json + ``` + + **Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repo-wide. + + ::: + 5. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose. ```shell diff --git a/website/docs/developer-docs/setup/full-dev-environment.mdx b/website/docs/developer-docs/setup/full-dev-environment.mdx index ca9d5bb5dff4..86e0c9117157 100644 --- a/website/docs/developer-docs/setup/full-dev-environment.mdx +++ b/website/docs/developer-docs/setup/full-dev-environment.mdx @@ -126,6 +126,20 @@ Install all required JavaScript and Python dependencies and create an isolated P make install ``` +:::info npm install scripts are disabled by default + +The repository's `.npmrc` sets `ignore-scripts=true`, which prevents `preinstall`/`install`/`postinstall` lifecycle scripts from running during `npm ci`. This neutralizes the most common npm supply-chain attack pattern (recent examples: "Shai-Hulud" and "Mini Shai-Hulud") at the cost of skipping legitimate native-binary unpacking for a few packages. + +If a build step fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild it explicitly: + +```shell +npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json +``` + +**Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repo-wide. + +::: + ### Generate development configuration Create a local configuration file that uses the local databases for development: From 3715aaa4ecfd9b8dc612a13ed43b3e34c96f44fe Mon Sep 17 00:00:00 2001 From: Teffen Ellis <592134+GirlBossRush@users.noreply.github.com> Date: Wed, 20 May 2026 02:50:57 +0200 Subject: [PATCH 2/3] Use separate file. --- website/docs/developer-docs/contributing.md | 2 +- .../setup/_npm-install-scripts-admonition.mdx | 13 +++++++++++++ ...vironment.md => frontend-dev-environment.mdx} | 16 +++------------- .../setup/full-dev-environment.mdx | 15 ++------------- 4 files changed, 19 insertions(+), 27 deletions(-) create mode 100644 website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx rename website/docs/developer-docs/setup/{frontend-dev-environment.md => frontend-dev-environment.mdx} (78%) diff --git a/website/docs/developer-docs/contributing.md b/website/docs/developer-docs/contributing.md index 1706be12adac..e600077f3bda 100644 --- a/website/docs/developer-docs/contributing.md +++ b/website/docs/developer-docs/contributing.md @@ -120,7 +120,7 @@ When you are creating an enhancement suggestion, please fill in [the template](h authentik can be run locally, although depending on which part you want to work on, different prerequisites are required. -This is documented in the [developer docs](./setup/frontend-dev-environment.md). +This is documented in the [developer docs](./setup/frontend-dev-environment.mdx). ### Help with the docs diff --git a/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx new file mode 100644 index 000000000000..b8cda2ce1f69 --- /dev/null +++ b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx @@ -0,0 +1,13 @@ +:::info NPM install scripts are disabled by default + +The repository's `.npmrc` sets `ignore-scripts=true` so `preinstall`/`install`/`postinstall` lifecycle scripts do not run during `npm ci`. This neutralizes a dominant NPM supply-chain attack pattern at the cost of skipping a few legitimate native-binary unpacks. + +If the watch build fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild only that package: + +```shell +npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json +``` + +**Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repo-wide. + +::: diff --git a/website/docs/developer-docs/setup/frontend-dev-environment.md b/website/docs/developer-docs/setup/frontend-dev-environment.mdx similarity index 78% rename from website/docs/developer-docs/setup/frontend-dev-environment.md rename to website/docs/developer-docs/setup/frontend-dev-environment.mdx index 95b17d31e49b..1f31a59b5b2e 100644 --- a/website/docs/developer-docs/setup/frontend-dev-environment.md +++ b/website/docs/developer-docs/setup/frontend-dev-environment.mdx @@ -8,6 +8,8 @@ tags: - docker --- +import NPMInstallScriptsAdmonition from "./\_npm-install-scripts-admonition.mdx"; + If you're focusing solely on frontend development, you can create a minimal development environment using Docker and Node.js. This setup allows you to make and preview changes to the frontend in real-time, without needing to interact with the backend. ### Prerequisites @@ -55,19 +57,7 @@ If you're focusing solely on frontend development, you can create a minimal deve make web-watch ``` - :::info npm install scripts are disabled by default - - The repository's `.npmrc` sets `ignore-scripts=true` so `preinstall`/`install`/`postinstall` lifecycle scripts do not run during `npm ci`. This is intentional: it neutralizes the dominant npm supply-chain attack pattern (recent examples: "Shai-Hulud" and "Mini Shai-Hulud") at the cost of skipping a few legitimate native-binary unpacks. - - If the watch build fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild only that package: - - ```shell - npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json - ``` - - **Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repo-wide. - - ::: + 5. In a new terminal, navigate to the cloned repository root and start the backend containers with Docker Compose. diff --git a/website/docs/developer-docs/setup/full-dev-environment.mdx b/website/docs/developer-docs/setup/full-dev-environment.mdx index 86e0c9117157..88c474641459 100644 --- a/website/docs/developer-docs/setup/full-dev-environment.mdx +++ b/website/docs/developer-docs/setup/full-dev-environment.mdx @@ -11,6 +11,7 @@ tags: import TabItem from "@theme/TabItem"; import Tabs from "@theme/Tabs"; +import NPMInstallScriptsAdmonition from "./\_npm-install-scripts-admonition.mdx"; ## Prerequisites @@ -126,19 +127,7 @@ Install all required JavaScript and Python dependencies and create an isolated P make install ``` -:::info npm install scripts are disabled by default - -The repository's `.npmrc` sets `ignore-scripts=true`, which prevents `preinstall`/`install`/`postinstall` lifecycle scripts from running during `npm ci`. This neutralizes the most common npm supply-chain attack pattern (recent examples: "Shai-Hulud" and "Mini Shai-Hulud") at the cost of skipping legitimate native-binary unpacking for a few packages. - -If a build step fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild it explicitly: - -```shell -npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json -``` - -**Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repo-wide. - -::: + ### Generate development configuration From 10ba6de2e5d071a85839df50cdf1d0a3b6fdff9e Mon Sep 17 00:00:00 2001 From: Dewi Roberts Date: Thu, 21 May 2026 13:07:59 +0100 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Dewi Roberts Signed-off-by: Dewi Roberts --- .../setup/_npm-install-scripts-admonition.mdx | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx index b8cda2ce1f69..23c5d6a2a178 100644 --- a/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx +++ b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx @@ -1,13 +1,11 @@ :::info NPM install scripts are disabled by default +The repository's NPM runtime configuration file (`.npmrc`) sets `ignore-scripts=true`. This means that `preinstall`/`install`/`postinstall` lifecycle scripts do not run during `npm ci`. This neutralizes a dominant NPM supply-chain attack pattern at the cost of skipping a few legitimate native-binary unpacks. -The repository's `.npmrc` sets `ignore-scripts=true` so `preinstall`/`install`/`postinstall` lifecycle scripts do not run during `npm ci`. This neutralizes a dominant NPM supply-chain attack pattern at the cost of skipping a few legitimate native-binary unpacks. - -If the watch build fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild only that package: +If the watch build fails because a package needs its install script (commonly `esbuild`, `chromedriver`, `tree-sitter`, or `tree-sitter-json`), rebuild only that package, for example: ```shell npm rebuild --foreground-scripts esbuild chromedriver tree-sitter tree-sitter-json ``` -**Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repo-wide. - +**Do not** edit `.npmrc` to flip `ignore-scripts` off — that re-introduces the risk repository-wide. :::