fix: allow secure .npmrc files, validate for credentials

[wz-gsa]

Problem

Caulking currently blocks all .npmrc files from being committed, even legitimate project-level configuration files that contain security controls.

This is blocking developers who want to commit project .npmrc files with recommended security settings like:

• ignore-scripts=true (prevents arbitrary script execution during npm install)
• audit=true (enables vulnerability scanning)

Reported by: @AndrewBurnes (blocked on commit)

Current Behavior

$ git add .npmrc
$ git commit -m "Add npm security config"
ERROR: forbidden file staged: .npmrc
Caulking blocked a forbidden file from being committed.

Why This Is a Problem

Good .npmrc (should be allowed):

# Project-level security controls
ignore-scripts=true
audit=true
fund=false

Bad .npmrc (should be blocked):

# User-level auth tokens (credentials!)
_authToken=npm_abc123456789
//registry.npmjs.org/:_authToken=${NPM_TOKEN}

Caulking was treating both the same way — blocking everything.

---

Solution

Changes

1. Removed .npmrc from blanket deny list

   • No longer blocks all .npmrc files unconditionally

2. Added validate_npmrc() function

   • Content-aware validation
   • Checks for auth tokens and credentials
   • Validates security controls

3. Credential Detection

   • Blocks files containing:
     • _authToken
     • _auth
     • _password
     • Scoped registry tokens (:_authToken)

4. Security Controls Validation

   • Warns (but allows) if missing ignore-scripts=true
   • Provides actionable guidance

Validation Logic

validate_npmrc() {
  # Check for required security settings
  if grep -qE '^\s*ignore-scripts\s*=\s*true' "$file"; then
    has_ignore_scripts=1
  fi

  # Check for credentials
  if grep -qE '(_authToken|_auth|_password|:_authToken)' "$file"; then
    has_credentials=1
  fi

  # Fail if credentials present
  if [[ $has_credentials -eq 1 ]]; then
    say "ERROR: .npmrc contains auth tokens or credentials"
    print_npmrc_hint
    return 1
  fi

  # Warn if missing security controls (but allow commit)
  if [[ $has_ignore_scripts -eq 0 ]]; then
    say "WARNING: .npmrc missing 'ignore-scripts=true' (recommended)"
  fi
}

Helpful Error Messages

When credentials detected:

ERROR: .npmrc contains auth tokens or credentials

Caulking blocked .npmrc because it may contain auth tokens or lack security controls.

Safe .npmrc files must include these security settings:
  ignore-scripts=true
  audit=true

And must NOT contain:
  - Auth tokens (_authToken, _auth, _password)
  - Registry credentials
  - API keys

To fix:
  1. Add required security settings
  2. Remove auth tokens (use environment variables instead)
  3. Stage and commit again

---

Testing

✅ Test 1: Safe .npmrc (should pass)

$ cat .npmrc
ignore-scripts=true
audit=true

$ git add .npmrc && git commit -m "Add npm config"
✅ Commit succeeds

✅ Test 2: .npmrc with credentials (should block)

$ cat .npmrc
_authToken=npm_abc123456789

$ git add .npmrc && git commit -m "Add npm config"
❌ ERROR: .npmrc contains auth tokens or credentials

✅ Test 3: .npmrc missing security controls (should warn)

$ cat .npmrc
fund=false
audit=true

$ git add .npmrc && git commit -m "Add npm config"
⚠️  WARNING: .npmrc missing 'ignore-scripts=true' (recommended security control)
✅ Commit succeeds with warning

✅ Shellcheck passes
✅ All pre-commit hooks pass

---

Security Rationale

Why This Is Safe

1. Still blocks credentials — Auth tokens are detected and blocked
2. Encourages security controls — Warns when missing ignore-scripts=true
3. Content-aware — Inspects file contents, not just filename
4. Better developer experience — Clear guidance on what's wrong and how to fix it

Why This Is Important

Supply chain security best practice:

Projects should commit .npmrc with ignore-scripts=true to prevent arbitrary code execution during npm install.

Blocking all .npmrc files prevents teams from implementing this critical security control.

Threat Model

Scenario	Old Behavior	New Behavior	Result
Project config with security settings	❌ Blocked	✅ Allowed	Better security
User config with auth token	❌ Blocked	❌ Blocked	Same protection
Project config without security settings	❌ Blocked	⚠️ Warning + allowed	Guidance provided

---

Rollout

After merge:

1. All developers run make install (or pull and ./install.sh)
2. Test with a project .npmrc:

   echo 'ignore-scripts=true' > .npmrc
   git add .npmrc
   git commit -m "test: npm security config"

---

Related

• Addresses @AndrewBurnes blocking issue
• Aligns with npm security best practices: https://docs.npmjs.com/cli/v10/using-npm/config#ignore-scripts
• Complements existing supply chain security controls in caulking

Resolves blocking issue for project-level npm security configurations.

[apburnes]