'pnpm' | 'yarn'; allowScripts: string[]; }

export function enforceSafeInstallation(config: InstallGuardConfig): void { const npmrcPath = '.npmrc'; const pnpmrcPath = '.npmrc';

const baseConfig = 'ignore-scripts=true\n'; const auditConfig = config.allowScripts.length > 0 ? allowed-scripts=${config.allowScripts.join(',')}\n : '';

writeFileSync(pnpmrcPath, baseConfig + auditConfig, 'utf-8');

const managerFlag = config.packageManager === 'npm' ? '--ignore-scripts' : config.packageManager === 'pnpm' ? '--ignore-scripts' : '--ignore-scripts';

try { execSync(${config.packageManager} install ${managerFlag}, { stdio: 'inherit' }); console.log([Security] Dependencies installed with lifecycle scripts disabled.); } catch (error) { console.error([Security] Installation failed. Review dependency scripts before enabling.); process.exit(1); } }

### Architecture Rationale
Each choice follows the principle of least privilege and defense in depth. Cache key entropy prevents cross-PR contamination. OIDC scoping limits token exposure to specific jobs. Lifecycle script neutralization removes the primary execution vector for supply chain payloads. The architecture assumes that any external contribution could contain malicious logic, and therefore isolates it from secrets, caches, and publishing credentials until explicit approval.

## Pitfall Guide

### 1. `pull_request_target` Trust Misconfiguration
**Explanation:** This trigger runs fork code with the base repository's permissions, secrets, and cache access. Teams often use it for labeling or commenting workflows without realizing it grants full repository context.
**Fix:** Replace with `pull_request` for untrusted code. If base context is required, use a two-step workflow: first validate in a restricted runner, then merge to a protected branch that triggers the privileged workflow.

### 2. Predictable Cache Key Generation
**Explanation:** Keys based solely on `pnpm-lock.yaml` or `package-lock.json` hashes allow attackers to pre-populate cache storage with modified binaries. The cache persists across workflow runs and is restored by legitimate builds.
**Fix:** Introduce cryptographic entropy, workflow run IDs, and branch scoping. Never cache compiled binaries or native modules from external contributions.

### 3. Assuming SLSA Provenance Equals Malware Detection
**Explanation:** SLSA Level 3 proves that an artifact was built by the claimed pipeline and hasn't been tampered with post-build. It does not verify that the pipeline itself was uncompromised or that the source code is safe.
**Fix:** Treat provenance as a chain-of-custody verification, not a security scanner. Combine it with static analysis, dependency auditing, and runtime behavior monitoring.

### 4. Over-Provisioned OIDC Permissions
**Explanation:** Granting `id-token: write` at the workflow level instead of the job level exposes tokens to all steps, including those running untrusted code. Tokens can be extracted from memory before the publishing step executes.
**Fix:** Scope OIDC permissions to specific jobs. Use short expiration windows. Rotate tokens immediately after publishing. Never run dependency installation or test suites in the same job that requests OIDC credentials.

### 5. Blind Token Rotation Without Environment Sanitization
**Explanation:** Revoking compromised tokens without first cleaning the infected environment can trigger destructive payloads. Some malware monitors token validity and executes wiper routines upon revocation.
**Fix:** Isolate affected runners, snapshot memory/disk state for forensics, disable automated cleanup scripts, then rotate credentials. Maintain an incident response playbook that sequences containment before revocation.

### 6. Ignoring Optional/Transitive Lifecycle Scripts
**Explanation:** Packages can declare `optionalDependencies` or `peerDependencies` that execute `postinstall` scripts even when not explicitly required. Attackers use this to bypass direct dependency audits.
**Fix:** Set `ignore-scripts=true` globally. Use `npm ls --json` or `pnpm why` to audit transitive dependencies. Only enable scripts for packages that require native compilation, and verify their build scripts manually.

### 7. Shared Runner Cache Across Trust Boundaries
**Explanation:** GitHub Actions caches are shared across workflows in the same repository. A malicious PR can write to the cache, and a subsequent main branch push can restore it, executing attacker-controlled binaries.
**Fix:** Implement cache partitioning by trust level. Use separate cache namespaces for PRs, main, and release workflows. Set explicit cache retention policies and disable cache sharing for untrusted branches.

## Production Bundle

### Action Checklist
- [ ] Audit all GitHub Actions workflows for `pull_request_target` usage and replace with isolated validation steps
- [ ] Implement cryptographic cache key generation with entropy and branch scoping
- [ ] Restrict `id-token: write` permissions to specific publishing jobs only
- [ ] Configure package managers to disable lifecycle scripts by default (`ignore-scripts=true`)
- [ ] Deploy dependency auditing automation that scans lockfiles for known compromised versions
- [ ] Establish an incident response playbook that sequences environment isolation before token revocation
- [ ] Enable runner memory protection and restrict `/proc` access in CI environments
- [ ] Conduct quarterly pipeline security reviews focusing on cache, OIDC, and script execution boundaries

### Decision Matrix

| Scenario | Recommended Approach | Why | Cost Impact |
|----------|---------------------|-----|-------------|
| Open-source repository with external contributions | Isolated PR validation + cache entropy + script neutralization | Prevents fork code from accessing secrets or poisoning caches | Low (workflow restructuring) |
| Enterprise private repository with strict compliance | Dedicated runners per trust level + OIDC job scoping + memory scraping detection | Ensures cryptographic provenance aligns with actual build integrity | Medium (infrastructure isolation) |
| High-velocity microservices with frequent releases | Automated lockfile auditing + short-lived OIDC + cached dependency verification | Balances deployment speed with supply chain verification | Low-Medium (CI optimization) |
| Legacy monolith with transitive dependency sprawl | Global script disable + explicit allowed-scripts list + dependency consolidation | Reduces attack surface from hidden lifecycle execution | Medium (refactoring effort) |

### Configuration Template

```yaml
# .github/workflows/release.yml
name: Secure Release Pipeline
on:
  push:
    branches: [main]

permissions:
  contents: read
  id-token: write

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Install dependencies safely
        run: |
          echo "ignore-scripts=true" > .npmrc
          npm ci --ignore-scripts
      - name: Run security audit
        run: npm audit --production

  publish:
    needs: validate
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read
    steps:
      - uses: actions/checkout@v4
      - name: Generate secure cache key
        id: cache-key
        run: |
          KEY=$(node -e "
            const { generateSecureCacheKey } = require('./scripts/cache-key.js');
            console.log(generateSecureCacheKey({
              lockfilePath: 'pnpm-lock.yaml',
              workflowRunId: '${{ github.run_id }}',
              environment: 'release'
            }));
          ")
          echo "key=$KEY" >> $GITHUB_OUTPUT
      - uses: actions/cache@v4
        with:
          path: ~/.pnpm-store
          key: ${{ steps.cache-key.outputs.key }}
          restore-keys: |
            ci-cache-release-
      - name: Publish to registry
        run: npm publish --provenance
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

// .npmrc
ignore-scripts=true
engine-strict=true
audit-level=high

Quick Start Guide

1. Audit your workflows: Search your repository for pull_request_target and id-token: write. Document which jobs request these permissions and verify they are strictly scoped.
2. Deploy cache key hardening: Add the TypeScript cache key generator to your repository. Update your GitHub Actions workflows to use the generated key instead of static lockfile hashes.
3. Neutralize lifecycle scripts: Create a .npmrc file with ignore-scripts=true. Run npm install --dry-run to identify packages that require scripts, then explicitly allow only those using allowed-scripts.
4. Validate OIDC boundaries: Restrict id-token: write to the exact job that publishes artifacts. Set token expiration to 15 minutes or less. Verify that no test or build steps run in the same job context.
5. Monitor and iterate: Enable dependency auditing automation. Review cache hit/miss rates and adjust entropy parameters if performance degrades. Conduct quarterly pipeline security reviews to adapt to emerging supply chain tactics.