Stash Supply Chain Security

Supply Chain Security

Controls applied in this repo to limit blast radius from compromised npm packages, lockfile injection, dependency confusion, and rushed dependency upgrades. Sourced from lirantal/npm-security-best-practices and adapted for our pnpm workspace.

When to Use This Skill

• Modifying any file under .github/workflows/
• Editing pnpm-workspace.yaml, package.json pnpm block, or .npmrc
• Updating .github/dependabot.yml or .github/CODEOWNERS
• Adding a dependency that needs a build script (i.e. node-gyp, node-pty, prebuilt binaries)
• Bypassing the install cooldown for a security fix
• Publishing a package to npm under a name that has never been published before
• Reviewing a PR that touches any of the above

What's Enforced (Config + Test Gate)

Each control below is validated by e2e/tests/supply-chain.e2e.test.ts — the test suite fails CI if a control regresses, so silent removal isn't possible.

1. Post-install scripts disabled by default — practice #1

pnpm 10+ disables lifecycle scripts globally and only runs them for packages on the onlyBuiltDependencies allowlist.

• Where: package.json pnpm.onlyBuiltDependencies
• Current allowlist: ["node-pty"] (PTY tests need the native module built)
• Test asserts: allowlist length ≤ 3 — adding a fourth entry forces explicit review

2. Install cooldown — practice #2

New package versions wait 7 days before they're eligible for install. Mirrors the Dependabot cooldown so manual + automated updates have the same community-discovery window.

• Where: pnpm-workspace.yaml minimumReleaseAge: 10080 (minutes)
• Test asserts: ≥ 4320 minutes (3 days)

3. Lockfile injection prevented — practices #4, #16

Two layers:

• pnpm-workspace.yaml blockExoticSubdeps: true — pnpm refuses to install transitive deps that come from git or direct tarballs (pnpm ≥ 10.26)
• A test parses pnpm-lock.yaml and asserts every resolved tarball URL starts with https://registry.npmjs.org/

(Why not lockfile-lint? It only supports npm/yarn lockfiles. The pnpm-native test gives us the same protection.)

4. Frozen lockfile in CI — practice #5

CI uses pnpm install --frozen-lockfile. If pnpm-lock.yaml and any package.json drift, the install aborts — no silent registry fetches that bypass the locked versions.

• Where: every workflow under .github/workflows/, and every local composite action under .github/actions/
• Test asserts: no pnpm install step anywhere in that graph is missing --frozen-lockfile

The check used to read tests.yml alone, and release.yml — the one workflow that publishes to npm — ran a bare pnpm install the whole time. The single install allowed to resolve outside the lockfile was the one whose output goes to the registry.

5. Cooldown'd auto-updates — practice #6

Dependabot opens grouped, cooldown'd PRs (7 days minor/patch) for npm, cargo, gomod, github-actions and docker (the digest of the Alpine image the musl binaries are built in). Major bumps are not proposed at all — every entry ignores version-update:semver-major, so majors are reviewed and applied by hand.

There is deliberately no semver-major-days cooldown on any entry. It would delay major version update PRs, which the ignore above means Dependabot never opens, and cooldown does not reach the security path either ("the cooldown option is only available for version updates, not security updates"). Don't add one back as a safety net for the day the ignore is dropped — dead config reads as policy, and the test below fails on the pair.

cargo covers the in-tree Rust workspace at languages/typescript/packages/protect-ffi (not the repo root — that is where Cargo.toml/Cargo.lock live). It runs monthly rather than weekly because each bump costs a native rebuild to validate, and it ignores the exact-pinned CipherStash crates (cipherstash-client, cts-common, stack-auth, stack-profile, eql-bindings, vitaminc) — they share a release train with the @cipherstash/auth catalog and must be bumped together, manually.

• Where: .github/dependabot.yml
• Test asserts: cooldown ≥ 3 days on every entry; the sentence above names every monitored ecosystem; every entry ignores version-update:semver-major for * and sets no semver-major-days (both ends, so neither half can drift alone); every lockfile present in the repo maps to a monitored package-ecosystem; every entry's directory actually contains the manifest its ecosystem reads

The ecosystem-coverage assertion is derived from the filesystem, so adding a lockfile for a new language fails the suite until dependabot.yml covers it. Two lockfiles are exempt because Dependabot has no ecosystem for them (e2e/wasm/deno.lock, .flox/env/manifest.lock); both are named with their reason in the test.

Note that ignore conditions suppress Dependabot security PRs too, not just version updates. The compensating control is OSV: .github/workflows/osv-scanner.yml scans --recursive ./, which reaches every lockfile in the tree (including Cargo.lock) and reports to code scanning.

6. Registry pinning — practice #16

.npmrc pins both the default registry and the @cipherstash scope to https://registry.npmjs.org/. Auth tokens stay in user-level ~/.npmrc or env vars — never committed.

• Test asserts: .npmrc contains both pin lines and no _authToken / NPM_TOKEN

7. Governance (CODEOWNERS)

.github/CODEOWNERS requires @cipherstash/developers review for every supply-chain critical file. Combined with branch protection (configured in repo settings, not in this repo), this prevents single-actor changes to the chain.

• Test asserts: CODEOWNERS lists each critical path

What's Documented but Not Enforced

These controls depend on developer environment or org-level configuration — we describe them here but don't gate CI on them.

Harden installs locally — practice #3

For local installs of new packages, consider running them through one of:

• npq — security checks, package age, typosquatting, provenance: npq install <pkg>
• Socket Firewall (sfw) — real-time blocker for known-malicious packages: sfw pnpm add <pkg>

Neither is required, but they're cheap insurance when adding a new direct dependency.

2FA on npm accounts — practice #10

Every maintainer with publish access to @cipherstash/* should have:

npm profile enable-2fa auth-and-writes

Releases no longer depend on this — release.yml publishes via OIDC and holds no long-lived token (see "Publishing" below). 2FA still matters for the manual publishes that OIDC can't cover: claiming a new package name, npm deprecate, and npm dist-tag changes.

Reduce dependency tree — practice #13

Before adding a new direct dep, ask:

• Does Node ≥ 22 (our minimum) already provide this?
• Is the package actively maintained? Check Snyk's database (security.snyk.io) — practice #14
• What does npm pack <pkg> show in the actual tarball? (npmjs.org's web view can lie — practice #15)

Secrets in CI

tests.yml writes .env files at CI time from GitHub Secrets. This is acceptable: secrets are never committed, scoped to the runner, and rotate via the GitHub UI. The .env files exist only for the lifetime of the job.

Do not commit any .env file to the repo.

Treat OIDC as a transport, not as a synonym for publishing. A non-publishing workload-identity exchange still needs job-level id-token: write, but it must be classified separately from registry publishers in scripts/__tests__/workflow-publish-permissions.test.mjs, with the audience and reason recorded there. Keep its static credential inputs absent and grant only the repository permissions the job actually needs.

A job's permissions: block limits only that job's GITHUB_TOKEN. Some actions use the OIDC token to obtain a different GitHub token instead — anthropics/claude-code-action, given no github_token input, exchanges it for a Claude GitHub App installation token with write access to contents, pull requests and issues. Check which token an action actually uses, and pass github_token: ${{ secrets.GITHUB_TOKEN }} where the action accepts one, so the grants you reviewed are the grants that apply.

Publishing — OIDC trusted publishing + provenance (practices #11, #12)

.github/workflows/release.yml publishes to npm with no NPM_TOKEN. It authenticates via npm OIDC trusted publishing, and provenance attestations are generated automatically as a side effect. Verify any published version with:

npm view <pkg>@<version> --json | grep -A3 attestations

Constraints baked into that workflow — don't undo them:

• permissions: id-token: write is what mints the OIDC token. Without it every publish fails — but it belongs on the publishing jobs, never at the workflow level. A trusted publisher is registered against a repository and a workflow filename, so once release.yml is the registered publisher, npm accepts a token minted by any job in that file: the registry cannot tell the cheap every-push gate apart from the publish job. Declared at the top, it reaches every job that does not override it, including the one added next month by someone who never read this page. release.yml therefore grants contents: read at the workflow level and escalates per job, so a new job has to ask for the credential in its own diff. Enforced by scripts/__tests__/workflow-publish-permissions.test.mjs, which also holds the list of jobs allowed to hold it.

• runs-on: ubuntu-latest, not a self-hosted/Blacksmith runner. npm rejects provenance from non-GitHub-hosted runners with E422.

• Never set NPM_TOKEN. changesets/action writes a token .npmrc when it sees one, which shadows OIDC and fails every publish with E404 (npm/cli#8976).

• npm ≥ 11.5.1 and Node ≥ 22.14. Node 22 ships npm 10.x, so the workflow installs npm@^11.5.1 explicitly before publishing.

• No Actions cache in this workflow (no cache:, package-manager-cache: false, pnpm/action-setup with cache: false). A poisoned cache entry would execute in a credential-bearing job. Enforced by scripts/lint-no-workflow-caching.mjs, which also follows any local composite action or reusable workflow the job reaches — the rule is about the whole call tree, not the one file.

• Every published uses: must be in that script's AUDITED_ACTIONS allowlist. The gate cannot open a published action to check whether it caches, and the ones that do are not all named "cache" — a setup-<tool> action that caches by default has no cache: input and no telling name. So the list is what is permitted, and an action it has never met fails by default. Adding a step to release.yml, _build-ffi-artifacts.yml or tests-supply-chain.yml means auditing the action and adding it there with the reason, in the same PR.

• Three actions must disable caching explicitly, and the input differs for each. Allowlisting an action is not the same as it being safe by default:

  Action	Input	Its default	Required
  pnpm/action-setup	cache	false	cache: false
  actions/setup-node	package-manager-cache	true	package-manager-cache: false
  jdx/mise-action	cache	true	cache: false

  - uses: jdx/mise-action@<sha> # v3.6.3
    with:
      install: true
      working_directory: languages/typescript/packages/protect-ffi
      cache: false # defaults to TRUE — omitting this restores the Actions cache

  Omitting the key is not "no caching" for the bottom two, it is caching spelled invisibly. The gate's generic rule only fires on a truthy cache: value, so a missing key is invisible to it — which is exactly how a mise-action step with no cache: passed until each action got its own explicit-false assertion.