Supply-Chain Hardening for TypeScript Libraries: Everything We Did and Why

# .npmrc — DaloyJS root npm/pnpm config (supply-chain hardening)

# ---------------------------------------------------------------------------
# Lifecycle scripts
# ---------------------------------------------------------------------------
# Reject preinstall/install/postinstall/prepare hooks from transitive deps.
# This is the primary execution channel in chalk/debug, node-ipc, and the
# Shai-Hulud worm campaigns. Anything that legitimately needs to build (esbuild)
# is on an explicit allowlist via pnpm-workspace.yaml allowBuilds.
ignore-scripts=true

# ---------------------------------------------------------------------------
# Install integrity
# ---------------------------------------------------------------------------
frozen-lockfile=true
verify-store-integrity=true
prefer-frozen-lockfile=true
strict-peer-dependencies=true
auto-install-peers=false

# ---------------------------------------------------------------------------
# Release-age cooldown
# ---------------------------------------------------------------------------
# Wait 24h (1440 minutes) before installing a freshly published version.
# Most worm campaigns are detected and unpublished within hours.
minimum-release-age=1440

# ---------------------------------------------------------------------------
# Registry posture
# ---------------------------------------------------------------------------
registry=https://registry.npmjs.org/
provenance=true

audit-level=moderate
fund=false

# pnpm-workspace.yaml — pnpm 11 supply-chain keys
packages:
  - "packages/*"

# Wait 24h before resolving a freshly published version. Mirrors .npmrc.
minimumReleaseAge: 1440

# Only direct dependencies may use exotic sources (git, tarball URLs).
# Transitive deps MUST resolve from the configured registry. This blocks
# the "transitive dep pulled from a hijacked git fork" attack class.
blockExoticSubdeps: true

# Refuse to install any dependency with an unreviewed lifecycle script.
# Packages that genuinely need a build go through allowBuilds, below.
strictDepBuilds: true

# Re-check dependency state before `pnpm run` / `pnpm exec` so scripts
# never run against a stale node_modules — which is how cache-poisoning
# chains achieve persistence on CI.
verifyDepsBeforeRun: install

# Explicit allowlist of packages permitted to run install scripts. New
# entries require a PR that explains *why* the package needs to build.
allowBuilds:
  esbuild: true

# .github/workflows/release.yml — npm publish with OIDC + provenance
name: release

on:
  push:
    tags: ["v*"]

# Top-level permissions: deny everything by default. Each job opts in.
# This is the single most important line in this file.
permissions: {}

jobs:
  verify:
    name: verify
    runs-on: ubuntu-latest
    timeout-minutes: 15
    permissions:
      contents: read
    steps:
      - name: Checkout
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v5
        with:
          persist-credentials: false
      - name: Setup pnpm
        uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
      - name: Setup Node
        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 20
          # NOTE: deliberately no `cache: pnpm` — the GHA cache is a known
          # exfiltration channel and a known persistence channel.
      - run: pnpm install --frozen-lockfile --ignore-scripts
      - run: pnpm typecheck
      - run: pnpm test
      - run: pnpm coverage

  publish:
    name: publish
    needs: verify
    runs-on: ubuntu-latest
    timeout-minutes: 15
    environment: npm-publish # manual approval gate
    permissions:
      contents: read
      # id-token: write is required by npm trusted publishing (OIDC).
      # It is granted on THIS job only — never to verify, never globally,
      # and never on a workflow that a fork PR could run.
      id-token: write
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v5
        with:
          persist-credentials: false
      - uses: pnpm/action-setup@a7487c7e89a18df4991f7f222e4898a00d66ddda # v4
      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6
        with:
          node-version: 20
          registry-url: https://registry.npmjs.org
      - run: pnpm install --frozen-lockfile --ignore-scripts
      - name: Publish to npm with provenance
        run: pnpm publish --access public --no-git-checks --provenance
        env:
          NPM_CONFIG_PROVENANCE: "true"
          # NOTE: no NODE_AUTH_TOKEN. Trusted publishing gets the credential
          # from the OIDC exchange. Long-lived npm tokens have been retired.

# .github/workflows/zizmor.yml — static analysis on the workflows themselves
name: zizmor
on:
  push: { branches: [main] }
  pull_request: { branches: [main] }
permissions: {}
jobs:
  zizmor:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v5
        with: { persist-credentials: false }
      - name: Run zizmor
        uses: woodruffw/zizmor-action@0c4ee94d3ea53cd6fd34a05dd07a4ba14e1f9b4c # v0.4.1
        with: { upload-sarif: true }

# .github/workflows/scorecard.yml — OpenSSF Scorecard weekly
name: scorecard
on:
  branch_protection_rule:
  schedule: [{ cron: "30 5 * * 0" }]
  push: { branches: [main] }
permissions: {}
jobs:
  analysis:
    runs-on: ubuntu-latest
    permissions:
      security-events: write
      id-token: write   # only for publishing the result
      contents: read
    steps:
      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
        with: { persist-credentials: false }
      - uses: ossf/scorecard-action@62b2cac7ed8198b15735ed49ab1e5cf35480ba46 # v2.4.0
        with: { results_file: results.sarif, results_format: sarif, publish_results: true }
      - uses: github/codeql-action/upload-sarif@4f3212b61783c3c68e8309a0f18a699764811cda
        with: { sarif_file: results.sarif }

// scripts/verify-lockfile-sources.mjs — run in CI before install
// Catches "registry override sneaks into pnpm-lock.yaml" attacks.

import { readFileSync } from "node:fs";

const lock = readFileSync("pnpm-lock.yaml", "utf8");
const FORBIDDEN = [
  /resolution:\s*\{\s*tarball:/, // direct tarball URL in a transitive resolution
  /resolution:\s*\{\s*git:/,     // git resolution in a transitive dep
  /registry:\s*['"]?(?!https:\/\/registry\.npmjs\.org\/)/, // any non-npm registry
];

const offenders = FORBIDDEN.flatMap((re) => {
  const matches = lock.match(new RegExp(re, "g")) ?? [];
  return matches.map((m) => ({ re: re.source, snippet: m }));
});

if (offenders.length > 0) {
  console.error("Forbidden resolutions in pnpm-lock.yaml:");
  for (const o of offenders) console.error(" ", o.re, "→", o.snippet);
  process.exit(1);
}
console.log("Lockfile sources OK.");

# Scaffold a new app with the app-safe posture baked in.
pnpm create daloy@latest my-api \
  --template node-basic \
  --with-ci \
  --code-owner @acme/security

# What this drops into the new repo:
#   .github/workflows/ci.yml         — pinned actions, no cache, --ignore-scripts
#   .github/workflows/codeql.yml     — TS/JS static analysis
#   .github/workflows/deploy.yml     — manual-only app deployment starter
#   .github/workflows/container-scan.yml — runs Trivy scans on your dockerfile
#   .github/workflows/scorecard.yml  — weekly OpenSSF Scorecard
#   .github/workflows/vuln-scan.yml  — checks for known vulnerabilities
#   .github/workflows/zizmor.yml     — workflow lint on every push
#   .github/dependabot.yml           — weekly bumps, grouped by ecosystem
#   .github/CODEOWNERS               — @acme/security on workflow files
#   SECURITY.md                      — disclosure policy + supported versions
#   scripts/verify-lockfile-sources.mjs — the script above, runnable as
#                                        pnpm verify:lockfile

# A short, opinionated map of the attack paths the above shuts down:

attack path                                 → blocked by
------------------------------------------- -----------------------------------
Malicious postinstall in a transitive dep   → ignore-scripts + strictDepBuilds
Hijacked package published as a new patch   → minimum-release-age=1440
Transitive dep swapped for a git/tarball    → blockExoticSubdeps
Stale node_modules survives an attack PR    → verifyDepsBeforeRun
GitHub Actions @v1 silently rolls to evil   → SHA-pinned actions (every step)
GHA cache contains an attacker's payload    → no `cache: pnpm` on install
Workflow accidentally gets contents: write  → top-level permissions: {}
Workflow exfiltrates secrets to an attacker → zizmor checks for it, blocks PR
Long-lived npm token leaks from a runner    → trusted publishing (OIDC) only
Build artifacts can't be traced to a commit → --provenance attaches a Sigstore
                                              attestation to every publish
Lockfile silently picks a wrong registry    → verify-lockfile-sources.mjs in CI