Node.js Certificate Trust Expert

Fix certificate errors when Node.js tools run behind corporate SSL-inspecting proxies (Zscaler, Palo Alto, Cisco Umbrella, etc.).

The Core Problem

Corporate proxies perform SSL/TLS inspection by:

1. Intercepting HTTPS connections
2. Decrypting traffic with their own CA
3. Re-encrypting with a corporate certificate
4. Forwarding to the destination

Node.js uses its own bundled CA store, not the system trust store. When a corporate proxy re-signs certificates, Node.js sees an untrusted issuer and fails with errors like:

• UNABLE_TO_VERIFY_LEAF_SIGNATURE
• SELF_SIGNED_CERT_IN_CHAIN
• unable to get local issuer certificate
• certificate has expired (even for valid certs)

The fix: Extract the corporate root CA and tell Node.js to trust it via NODE_EXTRA_CA_CERTS.

Capabilities

Reference Documentation

Workflow

1. Diagnose the Problem

When a user reports certificate errors:

1. Confirm they're on VPN/corporate network - "Are you connected to your company VPN?"
2. Check for SSL inspection - "Let me check if your traffic is being inspected"
3. Run diagnostics - Use /node-cert:diagnose or the diagnose script

2. Extract the Certificate

If SSL inspection is detected:

1. Read cert-extraction.md
2. Run extraction - /node-cert:extract-cert or scripts/extract-cert.sh
3. Verify the cert - Check it's the root CA, not intermediate

3. Configure Environment

Set up the environment variables:

1. Read proxy-env-vars.md
2. Generate shell functions - /node-cert:proxy-toggle-setup
3. Add to shell rc file - .zshrc, .bashrc, or .bash_profile

4. Test the Fix

Verify everything works:

1. Run smoke test - /node-cert:smoke-test
2. Test specific tools - Claude Code, npm, git, etc.

Scripts

Portable scripts in scripts/ that work without the plugin:

Run with: bash scripts/<script>.sh

Response Guidelines

• Always check references first before answering questions
• Show commands - users should see exactly what will run
• Explain the why - not just the command, but why it works
• Platform-aware - macOS, Linux, and Windows have differences
• No company-specific values - use placeholders user can customize
• Cite sources - reference file or external URL

Examples

Example 1: User Reports Certificate Error

User: I'm getting "UNABLE_TO_VERIFY_LEAF_SIGNATURE" when running Claude Code on my corporate VPN

Skill: This error means Node.js doesn't trust the certificate it received. Corporate proxies
often re-sign TLS traffic with their own CA, which Node.js doesn't know about.

Let me check if SSL inspection is active and extract your corporate certificate.

[Runs /node-cert:diagnose]

I can see Zscaler is intercepting your traffic. The certificate chain shows:
- api.anthropic.com
- YourCompany Forward Trust CA (intermediate)
- YourCompany Root CA (root - this is what we need)

I'll extract the root CA now...

[Runs /node-cert:extract-cert]

Done! The certificate was saved to ~/CAFile.pem. Now configure your environment:

export NODE_EXTRA_CA_CERTS=~/CAFile.pem

To make this permanent and toggleable, I can generate shell functions for your rc file.
Want me to run /node-cert:proxy-toggle-setup?

Example 2: Help Teammate

User: My colleague is having the same VPN cert issues. Can I give them a script?

Skill: Yes! I'll generate a portable fix script they can run.

[Runs /node-cert:export-fix]

Created: ~/fix-corporate-cert.sh

This script:
1. Extracts the corporate root CA from the live TLS chain
2. Saves it to ~/CAFile.pem
3. Outputs the export statement to add to their shell

They can run it with: bash fix-corporate-cert.sh

No dependencies required beyond openssl (comes with macOS/Linux).

Example 3: Debug Why Fix Stopped Working

User: The VPN cert fix was working yesterday, but now Claude Code is failing again

Skill: This often happens when the corporate CA rotates. Let me check...

[Runs /node-cert:cert-info ~/CAFile.pem]

Your current CA file shows:
- Subject: YourCompany Root CA
- Expires: 2024-03-15 (EXPIRED!)

The corporate CA has rotated. I'll extract the new one:

[Runs /node-cert:extract-cert]

New certificate saved. It expires 2026-01-15. Claude Code should work now.

Tip: Some companies rotate certs quarterly. If this happens often, consider
adding a weekly cron job to re-extract the cert.

Allowed Tools

This skill can use:

• Read - to read reference files
• Bash - to run diagnostic and extraction scripts
• Write - to generate shell config and export scripts
• WebSearch - to research tool-specific certificate configurations