| name | tls-certificate-troubleshooter |
| description | Diagnose TLS and certificate problems in KKTerm, including HTTPS URL Connection errors, expired certificates, untrusted roots, hostname mismatch, SNI, chain issues, corporate inspection, and TLS handshake failures. |
TLS Certificate Troubleshooter
Use this skill when HTTPS, API, URL Connection, proxy, or secure service access fails with certificate, trust, hostname, or TLS handshake errors.
Workflow
- Identify the failing client and target: WebView2 URL Connection, terminal command, SSH remote host, dashboard widget network request, or another tool.
- Capture the exact error class: expired certificate, hostname mismatch, unknown issuer, incomplete chain, revoked certificate, protocol version, cipher, or handshake timeout.
- Separate TLS certificate trust from SSH host key trust. They are different trust systems and should not share remediation steps.
- Check the hostname used by the client. Certificate validation follows the requested DNS name, not a convenient alias or raw IP address.
- For corporate inspection or proxy environments, ask whether the issuing CA is expected and managed before suggesting trust changes.
- Treat clock skew as a first-class cause when certificates appear not-yet-valid or unexpectedly expired.
- Avoid telling users to disable certificate validation. If a temporary bypass is discussed, label it unsafe and keep it out of saved app settings.
- For internal services, prefer fixing the certificate chain, SANs, and server configuration over pinning brittle workarounds.
Command Guidance
- Windows certificate/date context:
Get-Date, browser/WebView2 error text, and certificate viewer details when available.
- PowerShell HTTPS check:
Invoke-WebRequest https://<host> -Method Head for a simple client-side error, without adding validation bypasses.
- OpenSSL check when installed:
openssl s_client -connect <host>:443 -servername <host> -showcerts.
- POSIX remote check:
curl -Iv https://<host> to view TLS and certificate errors without downloading a body.
- For non-443 services, use the service port and correct SNI/server name when the tool supports it.
KKTerm Boundaries
- URL Connections use WebView2, which follows Windows trust and proxy behavior.
- Dashboard AI Created Widgets may make network requests only when their permissions allow it and Settings permits widget network tools.
- Secrets and private keys must not be pasted into chat.
- SSH host key warnings belong to SSH troubleshooting, not TLS certificate repair.
