From 3537ea544dd087e9f94b20438642d50f07dbc1d3 Mon Sep 17 00:00:00 2001 From: Teffen Ellis <592134+GirlBossRush@users.noreply.github.com> Date: Thu, 21 May 2026 14:47:49 +0200 Subject: [PATCH] website/docs: document npm install-script blocking (#22461) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * website/docs: document npm install-script blocking 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> * Use separate file. * Apply suggestions from code review Co-authored-by: Dewi Roberts Signed-off-by: Dewi Roberts --------- Signed-off-by: Dewi Roberts Co-authored-by: Agent <279763771+playpen-agent@users.noreply.github.com> Co-authored-by: Dewi Roberts --- website/docs/developer-docs/contributing.md | 2 +- .../setup/_npm-install-scripts-admonition.mdx | 11 +++++++++++ ...ev-environment.md => frontend-dev-environment.mdx} | 4 ++++ .../developer-docs/setup/full-dev-environment.mdx | 3 +++ 4 files changed, 19 insertions(+), 1 deletion(-) 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} (95%) diff --git a/website/docs/developer-docs/contributing.md b/website/docs/developer-docs/contributing.md index 1706be12ad..e600077f3b 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 0000000000..23c5d6a2a1 --- /dev/null +++ b/website/docs/developer-docs/setup/_npm-install-scripts-admonition.mdx @@ -0,0 +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. + +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 repository-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 95% rename from website/docs/developer-docs/setup/frontend-dev-environment.md rename to website/docs/developer-docs/setup/frontend-dev-environment.mdx index 03bcb0256c..1f31a59b5b 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,6 +57,8 @@ If you're focusing solely on frontend development, you can create a minimal deve make web-watch ``` + + 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 ca9d5bb5df..88c4746414 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,6 +127,8 @@ Install all required JavaScript and Python dependencies and create an isolated P make install ``` + + ### Generate development configuration Create a local configuration file that uses the local databases for development: