Merge pull request #171 from sensiblebit/feat/trust-anchor-source-tracking

feat: track trust anchor sources

Author: danielewood

.claude/docs/architecture.md

@@ -7,8 +7,8 @@ Stateless utility functions. No database, no file I/O. This is the public librar
 - `certkit.go` — PEM parsing, key generation, fingerprints, SKI computation. `DeduplicatePasswords()`, `ParseCertificatesAny()` (DER/PEM/PKCS#7). `MarshalEncryptedPrivateKeyToPEM()` encrypts a private key to PKCS#8 v2 PEM (PBES2/AES-256-CBC). `decryptPKCS8PrivateKey()` (unexported) decrypts PKCS#8 v2 encrypted keys; wired into `ParsePEMPrivateKeyWithPasswords()`. PBKDF2 key derivation is delegated to platform-specific `derivePBKDF2Key()`.
 - `pbkdf2.go` — Native PBKDF2-HMAC-SHA-256 implementation (`//go:build !js`) using Go stdlib `crypto/pbkdf2`.
 - `pbkdf2_js.go` — WASM PBKDF2 implementation (`//go:build js`) using the browser's Web Crypto `SubtleCrypto.deriveBits()` API. Runs key derivation off the main thread so CSS animations continue during export.
-- `bundle.go` — Certificate chain resolution via AIA, trust store verification. `BundleResult`/`BundleOptions` types, `DefaultOptions()`, `FetchLeafFromURL()`, `FetchAIACertificates()`, `Bundle()`. `MozillaRootPool()` (`sync.Once`-cached), `MozillaRootPEM()`.
-- `connect.go` — Transport connection probing and chain diagnostics. `ConnectTLS()` handles implicit TLS plus opportunistic mail-protocol STARTTLS/STLS upgrades for SMTP, IMAP, and POP3, plus LDAP `StartTLS` on port `389`; surfaces useful non-TLS diagnostics for SSH/HTTP/plaintext services; and returns negotiated protocol, cipher suite, peer chain, mTLS info, and verification result with automatic AIA walking for missing intermediates. `ScanCipherSuites()` enumerates supported TLS suites and key exchange groups, including STARTTLS-aware scans and optional QUIC probing. `DiagnoseConnectChain()` detects root-in-chain (RFC 8446 §4.4.2), duplicate certs, and missing intermediates. `FormatConnectResult()` renders the shared text summary, while the CLI verbose formatter appends a PEM copy of the server-sent chain with metadata headers. Types: `ConnectTLSInput`, `ConnectResult`, `ClientAuthInfo`, `ChainDiagnostic`, `ScanCipherSuitesInput`, `CipherScanResult`.
+- `bundle.go` — Certificate chain resolution via AIA, trust store verification, and cross-store trust probing. `BundleResult`/`BundleOptions` types, `DefaultOptions()`, `FetchLeafFromURL()`, `FetchAIACertificates()`, `Bundle()`, `CheckTrustAnchors()`, `FormatTrustAnchors()`. `MozillaRootPool()` and `SystemCertPoolCached()` are `sync.Once`-cached; `MozillaRootPEM()` exposes the embedded root bundle.
+- `connect.go` — Transport connection probing and chain diagnostics. `ConnectTLS()` handles implicit TLS plus opportunistic mail-protocol STARTTLS/STLS upgrades for SMTP, IMAP, and POP3, plus LDAP `StartTLS` on port `389`; surfaces useful non-TLS diagnostics for SSH/HTTP/plaintext services; and returns negotiated protocol, cipher suite, peer chain, mTLS info, and verification result with automatic AIA walking for missing intermediates. `ScanCipherSuites()` enumerates supported TLS suites and key exchange groups, including STARTTLS-aware scans and optional QUIC probing. `DiagnoseConnectChain()` detects root-in-chain (RFC 8446 §4.4.2), duplicate certs, and misordered chains; `ConnectTLS()` appends the `missing-intermediate` diagnostic during AIA recovery when applicable. `FormatConnectResult()` renders the shared text summary, while the CLI verbose formatter appends a PEM copy of the server-sent chain with metadata headers. Types: `ConnectTLSInput`, `ConnectResult`, `ClientAuthInfo`, `ChainDiagnostic`, `ScanCipherSuitesInput`, `CipherScanResult`.
 - `connect_policy.go` — Conservative policy heuristics for negotiated and scanned TLS results. Flags protocol versions, cipher suites, and leaf certificate key/signature algorithms that are likely not authorized by the selected policy profile.
 - `security_policy.go` — Shared policy type definitions. `SecurityPolicy` currently exposes `fips-140-2` and `fips-140-3` heuristic modes used by both TLS and SSH probing.
 - `probe_tls13.go` — Byte-level TLS 1.3 ClientHello construction and response parsing used by `ScanCipherSuites()` for TLS 1.3 cipher and key-exchange-group probing.
@@ -31,7 +31,7 @@ Certificate/key processing, in-memory storage, and persistence. Used by both CLI
 - `certstore.go` — `CertHandler` interface (`HandleCertificate`, `HandleKey`), `ProcessInput` struct.
 - `process.go` — `ProcessData()`: format detection and parsing pipeline (PEM → DER → PKCS#7 → PKCS#8 → SEC1 → Ed25519 → JKS → PKCS#12). Calls `CertHandler` for each parsed item.
 - `memstore.go` — `MemStore`: in-memory `CertHandler` implementation and primary runtime store. `CertRecord`/`KeyRecord` types. Stores multiple certs per SKI via composite key (serial + AKI). Provides `ScanSummary()`, `AllCertsFlat()`, `AllKeysFlat()`, `CertsByBundleName()`, `BundleNames()`, `DumpDebug()`.
-- `summary.go` — `ScanSummary` struct (roots, intermediates, leaves, keys, matched pairs).
+- `summary.go` — `ScanSummary` struct for aggregate scan counts, including roots/intermediates/leaves/keys/matches plus expired, Mozilla-trusted, system-trusted, and untrusted certificate totals.
 - `export.go` — `GenerateBundleFiles()`: creates all output files for a bundle (PEM variants, key, P12, K8s YAML, JSON, YAML, CSR). All key output is normalized to PKCS#8 format. `BundleExportInput` and `ExportMatchedBundleInput` support an `EncryptKey` option for PKCS#8 v2 password-protecting exported `.key` files. `GenerateJSON`, `GenerateYAML`, `GenerateCSR` also exported individually. `BundleWriter` interface and `ExportMatchedBundles()` provide shared export orchestration for both CLI and WASM.
 - `validate.go` — Certificate validation checks. `RunValidation()` orchestrates all checks for a certificate. `CheckExpiration()`, `CheckKeyStrength()`, `CheckSignature()`, `CheckTrustChain()` for individual validation steps. Types: `RunValidationInput`, `ValidationResult`, `ValidationCheck`, `CheckTrustChainInput`.
 - `aia.go` — Store-aware AIA resolution. `ResolveAIA()` fetches missing intermediates via AIA URLs using an `AIAFetcher` callback. `HasUnresolvedIssuers()` checks if any certs need issuer resolution. Type: `ResolveAIAInput`.
@@ -66,7 +66,7 @@ Thin CLI layer. Each file is one Cobra command. Flag variables are package-level
 - `scan.go` — Main scanning command with `--dump-keys`, `--dump-certs`, `--max-file-size`, `--bundle-path` flags.
 - `bundle.go` — Build verified certificate chains from leaf certs; resolves intermediates via AIA; outputs PEM, chain, fullchain, PKCS#12, or JKS with `--key`, `--force`, `--trust-store` flags.
 - `inspect.go` — Display detailed certificate, key, or CSR information with text or JSON output (`--format`); filters expired items unless `--allow-expired`.
-- `verify.go` — Verify certificate chains, key matches, expiry windows, and optional OCSP/CRL status; returns exit code 2 on validation failures; `--key`, `--expiry`, `--trust-store`, `--diagnose`, `--ocsp`, `--crl`, `--format` flags.
+- `verify.go` — Verify certificate chains, key matches, expiry windows, and optional OCSP/CRL status; returns exit code 2 on validation failures; always checks Mozilla + system trust and accepts `--roots` for additional file-backed trust anchors. Flags: `--key`, `--roots`, `--expiry`, `--diagnose`, `--ocsp`, `--crl`, `--format`.
 - `connect.go` — Test TLS connections and display certificate chain details; supports implicit TLS plus STARTTLS/STLS upgrades, optional cipher enumeration, OCSP/CRL checks, and FIPS-style policy diagnostics. In verbose text mode it also appends the server-sent certificate chain in PEM with metadata headers for direct reuse. Flags: `--servername`, `--ciphers`, `--no-ocsp`, `--crl`, `--fips-140-2`, `--fips-140-3`, `--format`.
 - `probe.go` — Parent `probe` command for transport-oriented inspection commands.
 - `probe_ssh.go` — `probe ssh` subcommand. Connects without authenticating, prints banner/algorithm details, and supports `--fips-140-2` / `--fips-140-3` policy heuristics for SSH transport algorithms.

CHANGELOG.md

@@ -12,12 +12,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Add `tree` subcommand to display the full CLI command, subcommand, and flag surface in a tree layout ([#169])
 - Encrypt PEM private key output (`.key`) using PKCS#8 v2 (AES-256-CBC) when an explicit export password is supplied ([#167])
 - Support decryption of PKCS#8 v2 encrypted private keys (`ENCRYPTED PRIVATE KEY` PEM blocks) with all PBES2 cipher (AES-128/192/256-CBC, 3DES-CBC) and PRF (HMAC-SHA-1/256/384/512) combinations ([#167])
+- Add `trust_anchors` reporting across `inspect`, `verify`, and `connect` JSON output so certificates show which trust sources validate them (`mozilla`/`system` everywhere, plus optional `file` roots in `verify`) ([`0ee41ad`])
+- Add per-store Mozilla/system trust counts to `scan` JSON summaries alongside the existing aggregate `untrusted_*` counts ([`0ee41ad`])
+- Add `verify --roots <file>` to include PEM/DER/PKCS#7/PKCS#12/JKS certificates as an additional file-backed trust source ([`0ee41ad`])
+- Add `CheckTrustAnchorsResult` so library callers can inspect `trust_anchors` plus trust-source load warnings from `CheckTrustAnchors` ([#171])
 
 ### Changed
 
 - Normalize all exported private key PEM output (`.key`, K8s `tls.key`, YAML `key`) to PKCS#8 (`PRIVATE KEY`) regardless of input format ([#167])
 - Bundle export warns when Kubernetes TLS secret contains an unencrypted private key alongside encrypted outputs ([#167])
 - Use browser Web Crypto API for PBKDF2 key derivation in WASM builds to avoid blocking the main thread during encrypted key export ([#167])
+- `verify` now checks both Mozilla and system trust stores by default and treats a certificate as trusted when any available anchor source succeeds ([`0ee41ad`])
+- `scan` now counts `untrusted_*` certificates as trusted by neither Mozilla nor system, and exposes per-store trust counts in JSON output ([`0ee41ad`])
+- Surface trust-source load warnings in `inspect`, `verify`, and `connect`, fail fast on invalid `verify` trust-store configuration, and stop reporting a synthetic `file` source when no file-backed roots were requested ([#171])
+
+### Removed
+
+- **Breaking:** Remove `verify --trust-store`; use the default Mozilla+system verification or `--roots` to add a file-backed trust source ([`0ee41ad`])
 
 ### Fixed
 
@@ -1097,6 +1108,7 @@ Initial release.
 [#158]: https://github.com/sensiblebit/certkit/pull/158
 [#167]: https://github.com/sensiblebit/certkit/issues/167
 [#169]: https://github.com/sensiblebit/certkit/pull/169
+[#171]: https://github.com/sensiblebit/certkit/pull/171
 [#73]: https://github.com/sensiblebit/certkit/pull/73
 [#64]: https://github.com/sensiblebit/certkit/pull/64
 [#63]: https://github.com/sensiblebit/certkit/pull/63
@@ -1115,3 +1127,4 @@ Initial release.
 [#27]: https://github.com/sensiblebit/certkit/pull/27
 [`6492fa5`]: https://github.com/sensiblebit/certkit/commit/6492fa5
 [`772742c`]: https://github.com/sensiblebit/certkit/commit/772742c
+[`0ee41ad`]: https://github.com/sensiblebit/certkit/commit/0ee41ad

EXAMPLES.md

@@ -151,10 +151,10 @@ Chain verification happens automatically -- certkit always checks that a cert ch
 certkit verify cert.pem
 ```
 
-By default this checks against the Mozilla root store (embedded, works everywhere). To check against your OS trust store instead:
+By default this checks against both the embedded Mozilla roots and your OS trust store. To add a private root file as another trust source:
 
 ```sh
-certkit verify cert.pem --trust-store system
+certkit verify cert.pem --roots private-ca.pem
 ```
 
 Combine all checks at once:

README.md

@@ -151,19 +151,19 @@ Common passwords (`""`, `"password"`, `"changeit"`, `"keypassword"`) are always
 ### Verify Flags
 
 <!-- certkit:flags:verify -->
-| Flag                      | Default   | Description                                              |
-| ------------------------- | --------- | -------------------------------------------------------- |
-| `--allow-private-network` | `false`   | Allow AIA/OCSP/CRL fetches to private/internal endpoints |
-| `--crl`                   | `false`   | Check CRL distribution points for revocation             |
-| `--diagnose`              | `false`   | Show diagnostics when chain verification fails           |
-| `--expiry`, `-e`          |           | Check if cert expires within duration (e.g., 30d, 720h)  |
-| `--format`                | `text`    | Output format: text, json                                |
-| `--key`                   |           | Private key file to check against the certificate        |
-| `--ocsp`                  | `false`   | Check OCSP revocation status                             |
-| `--trust-store`           | `mozilla` | Trust store: system, mozilla                             |
+| Flag                      | Default | Description                                                           |
+| ------------------------- | ------- | --------------------------------------------------------------------- |
+| `--allow-private-network` | `false` | Allow AIA/OCSP/CRL fetches to private/internal endpoints              |
+| `--crl`                   | `false` | Check CRL distribution points for revocation                          |
+| `--diagnose`              | `false` | Show diagnostics when chain verification fails                        |
+| `--expiry`, `-e`          |         | Check if cert expires within duration (e.g., 30d, 720h)               |
+| `--format`                | `text`  | Output format: text, json                                             |
+| `--key`                   |         | Private key file to check against the certificate                     |
+| `--ocsp`                  | `false` | Check OCSP revocation status                                          |
+| `--roots`                 |         | Additional root certificates file (PEM, DER, PKCS#7, PKCS#12, or JKS) |
 <!-- /certkit:flags -->
 
-Chain verification is always performed. When the input contains an embedded private key (PKCS#12, JKS), key match is checked automatically. Use `--ocsp` and/or `--crl` to check revocation status (requires network access and a valid chain).
+Chain verification is always performed against both the embedded Mozilla roots and the host system trust store. Use `--roots` to add a file-backed trust source for private PKI. When the input contains an embedded private key (PKCS#12, JKS), key match is checked automatically. Use `--ocsp` and/or `--crl` to check revocation status (requires network access and a valid chain).
 
 ### Connect Flags
 

bundle.go

@@ -14,6 +14,7 @@ import (
 	"net/http"
 	"net/url"
 	"slices"
+	"strings"
 	"sync"
 	"time"
 
@@ -24,6 +25,9 @@ var (
 	mozillaPoolOnce     sync.Once
 	mozillaPool         *x509.CertPool
 	errMozillaPool      error
+	systemPoolOnce      sync.Once
+	systemPool          *x509.CertPool
+	errSystemPool       error
 	mozillaSubjectsOnce sync.Once
 	mozillaSubjects     map[string]bool
 	mozillaRootKeysOnce sync.Once
@@ -47,6 +51,8 @@ var (
 	errBundleLeafNil            = errors.New("leaf certificate is nil")
 	errBundleMaxChainExceeded   = errors.New("certificate chain exceeded maximum intermediate limit")
 	errBundleUnknownTrustStore  = errors.New("unknown trust_store")
+	errVerifyChainCertNil       = errors.New("certificate is nil")
+	errVerifyChainRootsNil      = errors.New("root pool is nil")
 )
 
 // privateNetworks contains CIDR ranges for private, reserved, and shared
@@ -97,6 +103,19 @@ func MozillaRootPool() (*x509.CertPool, error) {
 	return mozillaPool, errMozillaPool
 }
 
+// SystemCertPoolCached returns a shared x509.CertPool containing the host
+// system roots. The pool is initialized once and cached for the lifetime of
+// the process.
+func SystemCertPoolCached() (*x509.CertPool, error) {
+	systemPoolOnce.Do(func() {
+		systemPool, errSystemPool = x509.SystemCertPool()
+		if errSystemPool != nil {
+			errSystemPool = fmt.Errorf("loading system cert pool: %w", errSystemPool)
+		}
+	})
+	return systemPool, errSystemPool
+}
+
 // MozillaRootSubjects returns a set of raw ASN.1 subject byte strings from all
 // Mozilla root certificates. The result is initialized once and cached for the
 // lifetime of the process.
@@ -293,6 +312,20 @@ type VerifyChainTrustInput struct {
 	Intermediates *x509.CertPool
 }
 
+// CheckTrustAnchorsInput holds parameters for CheckTrustAnchors.
+type CheckTrustAnchorsInput struct {
+	Cert          *x509.Certificate
+	Intermediates *x509.CertPool
+	FileRoots     *x509.CertPool
+}
+
+// CheckTrustAnchorsResult reports which trust sources validated a certificate
+// and any source-load warnings encountered while probing.
+type CheckTrustAnchorsResult struct {
+	Anchors  []string
+	Warnings []string
+}
+
 // VerifyChainTrust reports whether the given certificate chains to a trusted
 // root. Cross-signed roots (same Subject and public key as a Mozilla root)
 // are trusted directly. For expired certificates, verification is performed
@@ -306,11 +339,19 @@ type VerifyChainTrustInput struct {
 // invalid at the leaf's issuance time. This is an uncommon edge case in
 // practice (intermediates outlive the leaves they sign).
 func VerifyChainTrust(input VerifyChainTrustInput) bool {
+	chains, err := verifyChainTrustChains(input)
+	return err == nil && len(chains) > 0
+}
+
+func verifyChainTrustChains(input VerifyChainTrustInput) ([][]*x509.Certificate, error) {
+	if input.Cert == nil {
+		return nil, errVerifyChainCertNil
+	}
 	if input.Roots == nil {
-		return false
+		return nil, errVerifyChainRootsNil
 	}
 	if IsMozillaRoot(input.Cert) {
-		return true
+		return [][]*x509.Certificate{{input.Cert}}, nil
 	}
 	opts := x509.VerifyOptions{
 		Roots:         input.Roots,
@@ -321,8 +362,58 @@ func VerifyChainTrust(input VerifyChainTrustInput) bool {
 		// Use NotBefore + 1s: the issuing chain was necessarily valid at issuance.
 		opts.CurrentTime = input.Cert.NotBefore.Add(time.Second)
 	}
-	_, err := input.Cert.Verify(opts)
-	return err == nil
+	chains, err := input.Cert.Verify(opts)
+	if err != nil {
+		return nil, fmt.Errorf("verifying certificate against roots: %w", err)
+	}
+	return chains, nil
+}
+
+// CheckTrustAnchors reports which trust sources validate the certificate.
+// Results are returned in stable order: mozilla, system, file.
+func CheckTrustAnchors(input CheckTrustAnchorsInput) CheckTrustAnchorsResult {
+	if input.Cert == nil {
+		return CheckTrustAnchorsResult{Anchors: []string{}, Warnings: []string{}}
+	}
+
+	result := CheckTrustAnchorsResult{
+		Anchors:  make([]string, 0, 3),
+		Warnings: make([]string, 0, 2),
+	}
+	if mozillaPool, err := MozillaRootPool(); err != nil {
+		result.Warnings = append(result.Warnings, fmt.Sprintf("mozilla trust source unavailable: %v", err))
+	} else if VerifyChainTrust(VerifyChainTrustInput{
+		Cert:          input.Cert,
+		Roots:         mozillaPool,
+		Intermediates: input.Intermediates,
+	}) {
+		result.Anchors = append(result.Anchors, "mozilla")
+	}
+	if systemPool, err := SystemCertPoolCached(); err != nil {
+		result.Warnings = append(result.Warnings, fmt.Sprintf("system trust source unavailable: %v", err))
+	} else if VerifyChainTrust(VerifyChainTrustInput{
+		Cert:          input.Cert,
+		Roots:         systemPool,
+		Intermediates: input.Intermediates,
+	}) {
+		result.Anchors = append(result.Anchors, "system")
+	}
+	if input.FileRoots != nil && VerifyChainTrust(VerifyChainTrustInput{
+		Cert:          input.Cert,
+		Roots:         input.FileRoots,
+		Intermediates: input.Intermediates,
+	}) {
+		result.Anchors = append(result.Anchors, "file")
+	}
+	return result
+}
+
+// FormatTrustAnchors renders trust anchor labels for display.
+func FormatTrustAnchors(anchors []string) string {
+	if len(anchors) == 0 {
+		return "none"
+	}
+	return strings.Join(anchors, ", ")
 }
 
 // BundleResult holds the resolved chain and metadata.