local-ssl-cert

name	local-ssl-cert
description	Set up trusted local HTTPS/SSL/TLS development certificates with mkcert or equivalent tooling. Use when Codex needs to help developers create, install, trust, generate, configure, or troubleshoot local certificates for localhost, 127.0.0.1, LAN IPs, mobile testing, Vite, Node, Next.js, webpack, nginx, Docker, OAuth callbacks, secure cookies, service workers, or browser secure-context errors.

Local SSL Cert

Use this skill to help developers create and wire trusted local HTTPS certificates for development only.

Prefer mkcert for local development unless the user explicitly asks for manual OpenSSL, production certificates, or organization-managed PKI.

Safety Rules

• Treat "SSL certificate" as common shorthand; explain that modern HTTPS uses TLS when useful.
• Never recommend local mkcert certificates for production or end-user machines.
• Never commit, expose, print, or share private keys. Call out rootCA-key.pem as highly sensitive.
• Do not place certificate private keys under public/static asset folders.
• Do not use NODE_TLS_REJECT_UNAUTHORIZED=0 as a normal fix. Mention it only as a risky temporary diagnostic escape hatch.
• If generating commands, include every hostname/IP the user will type in the browser address bar.

Workflow

1. Identify the target environment:

   • OS/shell: Windows PowerShell, macOS/Linux bash, or unknown.
   • Framework/server: Vite, Node HTTPS, Next.js, webpack, nginx, Docker, or other.
   • Access targets: localhost, 127.0.0.1, ::1, custom local domains, LAN IPs, mobile devices.

2. Decide whether to read a reference:

   • Read references/mkcert.md for install/generation/trust steps.
   • Read references/frameworks.md when writing project config snippets.
   • Read references/troubleshooting.md when diagnosing browser, Node, mobile, or LAN failures.

3. Produce a concrete local plan:

   • Install mkcert and any platform prerequisite.
   • Run mkcert -install.
   • Generate cert/key files into a non-public folder such as certs/.
   • Configure the dev server to load the files.
   • Add private-key patterns to .gitignore.
   • Verify with the exact HTTPS URL the developer will use.

4. If useful, run the helper:

python <skill-dir>/scripts/mkcert_plan.py --shell powershell --framework vite --hosts localhost 127.0.0.1 ::1 --lan-ip 192.168.1.23

Use the helper output as a draft, then adapt paths and framework config to the user's project.

Standard Outputs

For setup requests, include:

• the mkcert install command for the user's OS,
• the mkcert -install step,
• the certificate generation command,
• the dev server config snippet,
• .gitignore entries for private keys,
• one verification URL,
• one short security warning about rootCA-key.pem.

For troubleshooting requests, identify which trust condition failed:

• CA not trusted,
• hostname/IP not included in the certificate,
• wrong cert/key path,
• server not listening on the right host,
• client runtime does not trust the CA,
• mobile device has not installed/trusted the root CA.

Default Certificate Layout

Use this layout unless the project already has a convention:

certs/
  local.pem
  local-key.pem

Add or recommend:

certs/*-key.pem
*.key
rootCA-key.pem

Never suggest copying rootCA-key.pem into the project.