docs(repo): safeguard against supply chain attacks

Author: mandarini

README.md

@@ -145,7 +145,8 @@ Testing varies per package. See the top-level [TESTING.md](docs/TESTING.md) for
 - **[Contributing](./CONTRIBUTING.md)** - Development guidelines
 - **[Release Workflows](./docs/RELEASE.md)** - Release and publishing process
 - **[Migration Guide](./docs/MIGRATION.md)** - Migrating to the monorepo structure
-- **[Security Policy](./docs/SECURITY.md)** - Security guidelines and reporting
+- **[Security Policy](./docs/SECURITY.md)** - Vulnerability reporting and disclosure policy
+- **[Securing your npm installs](./docs/NPM_PACKAGE_SECURITY.md)** - Consumer-side guide to defending your install against npm supply-chain attacks
 
 ## 🔐 Verifying provenance attestations
 
@@ -172,6 +173,8 @@ audited 1 package in 0s
 
 Because provenance attestations are a new capability, security features may evolve over time. Ensure you are using the latest npm CLI to verify attestation signatures reliably. This may require updating npm beyond the version bundled with Node.js.
 
+For a broader checklist — minimum release age, lockfile hygiene, blocking exotic transitive deps, lifecycle script controls, and what to do if you suspect a compromise — see [Securing your npm installs](./docs/NPM_PACKAGE_SECURITY.md).
+
 ## 📄 License
 
 This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.

docs/NPM_PACKAGE_SECURITY.md

@@ -0,0 +1,295 @@
+# Securing your npm installs
+
+A practical guide for consumers of `@supabase/supabase-js` (and any other npm package) to defend against npm supply-chain attacks.
+
+> Looking to **report** a vulnerability in Supabase itself? See [SECURITY.md](./SECURITY.md) instead. This guide is about hardening your install of Supabase (and other) packages on your machines and in your CI.
+
+## Why this guide exists
+
+The same attack pattern keeps recurring: a popular npm package is compromised, the new version executes attacker code on `npm install` via a lifecycle script or transitive dependency, the malware harvests credentials from the install host, and then self-propagates by republishing other packages the victim maintains.
+
+The good news: most of the impact is preventable from the consumer side, regardless of what any one publisher does. This guide is the set of settings and habits we recommend you adopt.
+
+## TL;DR — what to do today
+
+1. **Commit your lockfile** and install with `--frozen-lockfile` (pnpm/yarn) or `npm ci` (npm) in CI.
+2. **Quarantine new versions.** Set a minimum release age (≥ 7 days) so installs won't pick up a brand-new version while attackers are still in their detection window. npm, pnpm, yarn, and bun all support this natively now.
+3. **Block exotic transitive deps.** Refuse `github:`, `git+`, and `file:` refs that didn't come from the npm registry.
+4. **Verify provenance.** Run `npm audit signatures` after install. Supabase packages publish with sigstore attestations.
+5. **Constrain lifecycle scripts.** Default-deny `postinstall` / `preinstall` / `prepare`; allow per-package.
+6. **Pin a single source of truth for your package manager** (`packageManager` field in `package.json` with a sha512 hash).
+7. **Have a rollback plan.** Know which packages, which versions, and which credentials to rotate if a compromise is announced upstream.
+
+The rest of this document expands on each of these and covers the Edge Functions / Deno case separately.
+
+## Pin your dependency versions
+
+A committed lockfile is the floor, not the ceiling.
+
+**Application repos**:
+
+- Commit `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, or `bun.lock`.
+- In CI, install with `npm ci` / `pnpm install --frozen-lockfile` / `yarn install --immutable` / `bun install --frozen-lockfile`. These fail if `package.json` and the lockfile disagree, which is what you want.
+- Caret ranges (`^1.2.3`) in `package.json` are fine **if** you also have a lockfile and the rest of the guidance below — the lockfile is what actually gets installed.
+
+**Pin transitive risk with overrides.** If you don't trust a particular transitive dep version, force a known-good version via:
+
+```jsonc
+// npm and pnpm
+"overrides": {
+  "some-dep": "1.2.3"
+}
+
+// yarn
+"resolutions": {
+  "some-dep": "1.2.3"
+}
+```
+
+This is the lever to reach for when you see a CVE on a transitive you don't directly depend on.
+
+## Quarantine new versions (minimum release age)
+
+Most npm compromises are detected and remediated within hours. A short quarantine on freshly-published versions is the single highest-leverage setting.
+
+### pnpm (recommended)
+
+pnpm v11 turns this on by default (1440 minutes = 1 day). You can raise it. In `pnpm-workspace.yaml` at the repo root (pnpm 10+ reads config from this file with or without workspaces):
+
+```yaml
+minimumReleaseAge: 10080 # 7 days, in minutes
+minimumReleaseAgeExclude:
+  - '@your-org/*' # bypass for your own internal packages
+```
+
+Set `minimumReleaseAge: 0` only if you have a specific reason to opt out of the default.
+
+#### `trustPolicy` (pnpm)
+
+Independent of the age gate, pnpm's `trustPolicy: no-downgrade` refuses to install a version whose trust level (trusted publisher → provenance → none) has dropped relative to previous releases of the same package. That catches the case where an attacker can publish but can't replicate the original maintainer's OIDC binding:
+
+```yaml
+trustPolicy: no-downgrade
+trustPolicyExclude:
+  - 'some-package' # opt specific packages out if needed
+trustPolicyIgnoreAfter: '180d' # ignore checks for packages older than 180 days
+```
+
+### yarn (Berry / v4+)
+
+In `.yarnrc.yml`:
+
+```yaml
+npmMinimalAgeGate: '7d'
+npmPreapprovedPackages: # opt specific packages out of all package gates
+  - '@your-org/*'
+```
+
+Versions newer than the gate are excluded from resolution. Yarn's docs also note this guards against the npm registry's 72-hour unpublish window — a package you just installed could vanish, breaking your build, if you don't wait it out.
+
+Two related yarn settings worth knowing about while you're in `.yarnrc.yml`:
+
+- **`enableScripts: false`** is the default in yarn — postinstall scripts from third-party packages don't run. Workspaces still run their own.
+- **`enableHardenedMode: true`** makes yarn re-query remote registries to confirm that the lockfile content matches what the registry currently serves. Auto-on for GitHub PRs from public repos; worth turning on permanently if your threat model warrants slower installs.
+
+### npm
+
+Use the [`min-release-age`](https://docs.npmjs.com/cli/configuring-npm/config#min-release-age) config (relative, in days) or [`before`](https://docs.npmjs.com/cli/configuring-npm/config#before) (absolute date). Set in `.npmrc`:
+
+```ini
+min-release-age=7
+```
+
+Or per-command:
+
+```bash
+npm install --min-release-age=7
+```
+
+If `min-release-age` isn't available in your npm version yet, fall back to a private mirror or to a CI gate that calls `npm view <pkg>@<version> time.<version>` and rejects installs whose newest version was published in the last N days.
+
+### Bun
+
+Use the `--minimum-release-age` flag (seconds), or set it once in `bunfig.toml`:
+
+```toml
+[install]
+minimumReleaseAge = 604800 # 7 days, in seconds
+minimumReleaseAgeExcludes = ["@types/node", "typescript"] # trusted bypass
+```
+
+Or per-command:
+
+```bash
+bun add @supabase/supabase-js --minimum-release-age 604800
+```
+
+Bun's age gate only affects new resolutions — existing entries in `bun.lock` are unchanged. It also runs a stability check: if multiple versions were published close together just outside your gate, Bun extends the filter to skip those (likely unstable) versions and picks an older, more mature one. Exact-version requests (`pkg@1.1.1`) respect the gate but bypass the stability extension.
+
+### Deno / Edge Functions
+
+Deno has an unstable `--minimum-dependency-age` flag that accepts minutes, an ISO-8601 duration, or an absolute RFC3339 cutoff:
+
+```bash
+deno install --minimum-dependency-age=P7D    # 7-day quarantine
+deno install --minimum-dependency-age=10080  # 7 days, in minutes
+deno install --minimum-dependency-age=2026-04-01  # cut off at a fixed date
+deno install --minimum-dependency-age=0      # disable
+```
+
+Track Deno's release notes for when this stabilises. See the [Edge Functions](#edge-functions-specifics) section below for the Supabase-runtime-specific picture.
+
+## Use a private registry or mirror
+
+A proxy in front of `registry.npmjs.org` is the strongest layer of defense your org can add. It lets you enforce quarantine, audit, block, and roll back independently of what npmjs.org does.
+
+Common options (we don't endorse any one): [Verdaccio](https://verdaccio.org/), JFrog Artifactory, Sonatype Nexus, AWS CodeArtifact, GitHub Packages.
+
+A minimal `.npmrc` pointing to a private registry:
+
+```ini
+registry=https://npm.your-org.example/
+@supabase:registry=https://npm.your-org.example/
+//npm.your-org.example/:_authToken=${NPM_TOKEN}
+always-auth=true
+```
+
+Notes:
+
+- Never commit the token. Use `${NPM_TOKEN}` from your CI environment (npm 7+ expands env vars in `.npmrc`).
+- Scoped registry lines let you point specific scopes at a different upstream.
+- For a per-project `.npmrc`, put it next to `package.json`. For a per-user one, `~/.npmrc`.
+
+## Verify package provenance
+
+`@supabase/supabase-js`, `@supabase/auth-js`, `@supabase/postgrest-js`, `@supabase/realtime-js`, `@supabase/storage-js`, and `@supabase/functions-js` publish with [sigstore provenance attestations](https://docs.npmjs.com/generating-provenance-statements) via npm OIDC trusted publishing. The attestations cryptographically tie each published tarball to the workflow run, commit, and repository it was built from.
+
+To verify after install:
+
+```bash
+npm audit signatures
+```
+
+Sample output:
+
+```text
+audited 1 package in 0s
+1 package has a verified registry signature
+```
+
+A failure here is a strong signal that either your registry mirror is tampered with or the tarball was modified after publish. Use a recent npm CLI (the version bundled with Node.js can lag); install the latest with `npm install -g npm@latest`.
+
+See the existing [README — Verifying provenance attestations](../README.md#-verifying-provenance-attestations) section for additional examples.
+
+## Control lifecycle scripts
+
+`preinstall`, `postinstall`, and `prepare` scripts are the single most common code-execution entry point in a compromised dep.
+
+**pnpm**: declare an allowlist in `pnpm-workspace.yaml`:
+
+```yaml
+allowBuilds:
+  esbuild: false
+  simple-git-hooks: true
+```
+
+Default-deny is the goal. Add packages only when you genuinely need their build to run.
+
+**yarn**: `enableScripts: false` is the default — postinstall scripts from third-party packages don't run unless you opt in per package via `dependenciesMeta` in `package.json`. Workspaces still run their own scripts.
+
+**npm / bun**: install with `--ignore-scripts` and only enable scripts for the packages that truly need them.
+
+**The `@supabase/*` core packages run no install/postinstall scripts.** You can safely keep them on the deny list.
+
+## Block exotic dependency references
+
+The TanStack/router attack used `optionalDependencies: { "@tanstack/setup": "github:tanstack/router#<sha>" }` to pull payload code from a fork's git object store, bypassing the npm registry entirely. Block this class of ref:
+
+**pnpm**: in `pnpm-workspace.yaml`:
+
+```yaml
+blockExoticSubdeps: true
+```
+
+**npm**: the `allow-git`, `allow-remote`, `allow-file`, and `allow-directory` settings each take `"all"` (default), `"none"`, or `"root"`. `"root"` means "only allow this kind of reference if it's declared in your own `package.json`, never as a transitive dep" — which is exactly the trust boundary you want:
+
+```ini
+allow-git=root
+allow-remote=root
+allow-file=root
+allow-directory=root
+```
+
+**yarn**: use `approvedGitRepositories` to allowlist specific git sources. Anything not matching is rejected:
+
+```yaml
+approvedGitRepositories:
+  - 'https://github.com/yarnpkg/*'
+  - 'ssh://git@github.com/yarnpkg/*'
+```
+
+**bun**: no native equivalent today — inspect your `bun.lock` for non-registry refs.
+
+## Pin your package manager
+
+Drift between local dev and CI is a quiet source of risk. Pin the package manager itself with a sha512 hash:
+
+```jsonc
+// package.json
+"packageManager": "pnpm@10.0.0+sha512.<hash>"
+```
+
+Corepack (bundled with modern Node) and `pnpm/action-setup@v6+` both read this field automatically. A compromised npm mirror serving a tampered pnpm binary fails the hash check instead of running.
+
+## CI / lockfile hygiene
+
+- Run `--frozen-lockfile` / `npm ci` in every CI job. Never let CI silently regenerate the lockfile.
+- Review lockfile diffs in PRs the same way you review code diffs. Unexpected new transitives or version jumps deserve a question.
+- Configure Dependabot or Renovate to batch updates and respect the same min-age you set locally. Renovate's `minimumReleaseAge` option is the direct equivalent.
+- Run `npm audit signatures` as a non-blocking CI step so a tampered tarball is caught early.
+
+## Edge Functions specifics
+
+If you're using `@supabase/supabase-js` (or any `npm:` specifier) from Deno in a Supabase Edge Function, the picture is slightly different.
+
+Deno's `--minimum-dependency-age` (see above) is currently behind an unstable flag, and the Supabase Edge Runtime upgrade path for Deno is being worked on separately. Until your runtime supports it, the practical defenses are:
+
+- **Pin to exact versions** in your import map / `deno.json` — avoid floating tags like `latest`.
+- **Vendor critical dependencies** (`deno vendor`) and commit the vendored output. This freezes the dep at a known-good snapshot and removes the runtime fetch entirely.
+- **Use `--lock` and `--lock-write`** in CI to fail any build that pulls in unexpected content.
+- **Stay current on Deno** — newer versions are landing more supply-chain features (lockfile integrity, `npm:` provenance verification, min-age stabilisation). Track the [Deno release notes](https://github.com/denoland/deno/releases).
+
+Talk to the Supabase Functions team if your security posture depends on a feature only in a newer Deno.
+
+## If you suspect you installed a compromised version
+
+Move quickly. Order of operations:
+
+1. **Treat the install host as potentially compromised.** Anything readable by the user that ran the install — env vars, files, secrets in memory — should be assumed exfiltrated.
+2. **Rotate credentials reachable from that host**: cloud provider keys (AWS, GCP, Azure), Kubernetes / Vault tokens, GitHub tokens, npm tokens, SSH keys, and any Supabase service-role keys or anon keys that touched the box.
+3. **Wipe `node_modules`** and your package manager cache (`npm cache clean --force`, `pnpm store prune`, `yarn cache clean`).
+4. **Pin to a known-good version** in `package.json` and reinstall against a fresh cache.
+5. **Check `npm audit` and the [GitHub Advisory Database](https://github.com/advisories)** for the package.
+6. **Report it**: file a GitHub Security Advisory on the upstream repo, and email `security@npmjs.com` if the version is still installable.
+
+## What Supabase does on its side
+
+You shouldn't have to trust us — that's the whole point of this guide — but for completeness:
+
+- **OIDC trusted publishing.** No long-lived `NPM_TOKEN` secret. Each publish is authenticated against npm using a short-lived OIDC token bound to the release workflow.
+- **Provenance attestations.** Every release of `@supabase/supabase-js` and its sibling packages ships with a sigstore attestation tying the tarball to its source commit and workflow run. Verify with `npm audit signatures`.
+- **No `postinstall` / `preinstall` scripts** in any of the six core packages (`auth-js`, `postgrest-js`, `realtime-js`, `storage-js`, `functions-js`, `supabase-js`). You can safely install with `--ignore-scripts`.
+- **Fixed-version monorepo releases.** All packages release together with identical versions, so when you pin one, you pin them all.
+
+If something looks wrong with a published `@supabase/*` package, report it via the channels in [SECURITY.md](./SECURITY.md).
+
+## References
+
+- TanStack/router compromise postmortem: [TanStack/router#7383](https://github.com/TanStack/router/issues/7383), [GHSA-g7cv-rxg3-hmpx](https://github.com/TanStack/router/security/advisories/GHSA-g7cv-rxg3-hmpx).
+- Adnan Khan, ["The Monsters in Your Build Cache — GitHub Actions Cache Poisoning"](https://adnanthekhan.com/2024/05/06/the-monsters-in-your-build-cache-github-actions-cache-poisoning/) (May 2024).
+- GitHub Security Lab, ["Keeping your GitHub Actions and workflows secure: Preventing pwn requests"](https://securitylab.github.com/resources/github-actions-preventing-pwn-requests/) (Part 1 of a 4-part series, 2021–2025).
+- npm trusted publishing: <https://docs.npmjs.com/trusted-publishers>.
+- npm provenance: <https://docs.npmjs.com/generating-provenance-statements>.
+- pnpm `minimumReleaseAge`, `blockExoticSubdeps`, `allowBuilds`: <https://pnpm.io/settings>.
+- Renovate `minimumReleaseAge`: <https://docs.renovatebot.com/configuration-options/#minimumreleaseage>.
+- GitHub Advisory Database: <https://github.com/advisories>.

docs/SECURITY.md

@@ -1,6 +1,8 @@
 Contact: https://hackerone.com/supabase
 Canonical: https://supabase.com/.well-known/security.txt
 
+> Looking to **harden your install** of Supabase npm packages against supply-chain attacks (version pinning, minimum release age, private registries, provenance verification)? See [Securing your npm installs](./NPM_PACKAGE_SECURITY.md). The rest of this page is about reporting vulnerabilities in Supabase itself.
+
 At Supabase, we consider the security of our systems a top priority. But no matter how much effort we put into system security, there can still be vulnerabilities present.
 
 If you discover a vulnerability, we would like to know about it so we can take steps to address it as quickly as possible. We would like to ask you to help us better protect our clients and our systems.