Agent Skills: Node.js Certificate Trust Expert

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

| Action | What It Does | |--------|--------------| | Diagnose | Full connectivity check (VPN, DNS, SSL, env vars, CA file, Node.js test) | | Extract cert | Get corporate root CA from live TLS chain using openssl | | Verify config | Check env vars and CA file are correctly configured | | Smoke test | Test actual Node.js HTTPS connectivity | | Cert info | Display certificate details (subject, issuer, expiry) | | Proxy env | Output export statements for shell configuration | | Toggle setup | Generate proxy-on/off/status functions for rc file | | Check inspection | Detect if SSL inspection is currently active | | Cert bundle | Combine system certs + corporate CA into one bundle | | Export fix | Generate portable script for teammates |

Reference Documentation

| Topic | Reference | |-------|-----------| | Why Node.js fails (deep dive) | root-cause.md | | Certificate extraction procedure | cert-extraction.md | | Proxy environment variables | proxy-env-vars.md | | Tool-specific fixes | tool-specific-fixes.md | | macOS/Linux/Windows specifics | platform-guide.md | | Error messages and decision tree | troubleshooting.md | | Certificate rotation and bundling | ca-bundle-management.md |

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:

| Script | Purpose | |--------|---------| | diagnose.sh | Full diagnostic sweep | | extract-cert.sh | Extract corporate root CA | | smoke-test.sh | Test Node.js HTTPS connectivity | | cert-info.sh | Display certificate details |

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