Add WhitelistRegistry and enhance documentation

- Add WhitelistRegistry (pkg/registry/static/whitelist.go)
  - Simple URL-based whitelist for trusted issuers and verifiers
  - YAML/JSON configuration file support
  - Automatic file watching and config reload via fsnotify
  - Wildcard matching (prefix match and global wildcard)
  - Role-based lists: issuers, verifiers, trusted_subjects
  - Runtime management: AddIssuer(), RemoveIssuer(), etc.
  - 87% test coverage

- Update example/config.yaml with comprehensive registry documentation
  - ETSI TSL, OpenID Federation, DID Web, DID Web VH
  - mDOC IACA, Whitelist, and static test registries
  - All configuration options documented

- Add mDOC IACA Registry documentation to README.md
  - Dynamic IACA certificate validation for mDOC/mDL
  - Architecture and usage examples

- Fix static registry examples in README.md to match actual API
- Add example/whitelist.yaml configuration template
- Update CHANGELOG.md with new features

Author: leifj

CHANGELOG.md

@@ -9,6 +9,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- WhitelistRegistry (`pkg/registry/static/whitelist.go`)
+  - Simple URL-based whitelist for trusted issuers and verifiers
+  - YAML/JSON configuration file support
+  - Automatic file watching and config reload via fsnotify
+  - Wildcard matching: `https://example.com/*` for prefix match, `*` for all
+  - Role-based lists: `issuers`, `verifiers`, `trusted_subjects`
+  - Runtime management: `AddIssuer()`, `RemoveIssuer()`, `AddVerifier()`, `RemoveVerifier()`
+  - 87% test coverage
+
 - Standalone AuthZEN client library (`pkg/authzenclient/`)
   - HTTP client for AuthZEN PDPs with discovery support
   - Methods: `Discover()`, `Evaluate()`, `Resolve()`, `EvaluateX5C()`, `EvaluateJWK()`
@@ -35,6 +44,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Enhanced README.md with:
   - ETSI TSL Registry section documenting both standalone and server modes
+  - mDOC IACA Registry section documenting dynamic IACA certificate validation
   - Updated package structure diagram
   - Configuration options table for TSLConfig
 

README.md

@@ -220,6 +220,41 @@ Resolves and validates DID Web VH (Verifiable History) identifiers with cryptogr
 
 **Supported resource types:** `did_document`, `jwk`, `verification_method`
 
+#### mDOC IACA Registry
+
+Dynamically validates mDOC/mDL X.509 certificate chains against IACA (Issuing Authority Certificate Authority) certificates fetched from OpenID4VCI issuers.
+
+**Architecture:**
+1. Receives trust evaluation with issuer URL (`subject.id`) and X5C chain (`resource.key`)
+2. Fetches issuer's OpenID4VCI metadata (discovers `mdoc_iacas_uri` endpoint)
+3. Fetches IACA certificates from `mdoc_iacas_uri`
+4. Validates X5C chain against fetched IACAs
+5. Optionally enforces issuer allowlist
+
+**Supported resource types:** `x5c`
+
+```go
+import "github.com/sirosfoundation/go-trust/pkg/registry/mdociaca"
+
+reg, err := mdociaca.New(&mdociaca.Config{
+    Name:            "mdoc-iaca",
+    IssuerAllowlist: []string{"https://issuer.example.com"},  // Optional
+    CacheTTL:        time.Hour,
+})
+
+// Evaluate trust for an mDOC issuer
+req := &authzen.EvaluationRequest{
+    Subject:  authzen.Subject{Type: "key", ID: "https://issuer.example.com"},
+    Resource: authzen.Resource{Type: "x5c", Key: []interface{}{dsB64, iacaB64}},
+}
+resp, err := reg.Evaluate(ctx, req)
+```
+
+**Use cases:**
+- Mobile driving license (mDL) issuer validation
+- EUDI wallet mDOC credential issuance
+- Any OpenID4VCI issuer publishing IACA certificates
+
 ### Static Trust Registries
 
 The `pkg/registry/static` package provides simple TrustRegistry implementations for testing, development, and basic use cases:
@@ -229,20 +264,61 @@ The `pkg/registry/static` package provides simple TrustRegistry implementations
 | `AlwaysTrustedRegistry` | Always returns `decision=true` | Testing, development, trust-all scenarios |
 | `NeverTrustedRegistry` | Always returns `decision=false` | Testing trust rejection, deny-all scenarios |
 | `SystemCertPoolRegistry` | Validates X509 against OS CA bundle | Simple TLS trust without ETSI TSL |
+| `WhitelistRegistry` | URL-based whitelist with file watching | Simple issuer/verifier allowlisting |
 
 ```go
 import "github.com/sirosfoundation/go-trust/pkg/registry/static"
 
-// Accept all trust requests
-registry := static.NewAlwaysTrustedRegistry()
+// Accept all trust requests (testing only!)
+registry := static.NewAlwaysTrustedRegistry("test-always-trusted")
 
-// Reject all trust requests  
-registry := static.NewNeverTrustedRegistry()
+// Reject all trust requests (testing only!)
+registry := static.NewNeverTrustedRegistry("test-never-trusted")
 
 // Validate against system CA bundle
-registry := static.NewSystemCertPoolRegistry()
+registry, _ := static.NewSystemCertPoolRegistry(static.SystemCertPoolConfig{
+    Name:        "system-ca",
+    Description: "System root CA certificates",
+})
+
+// URL whitelist from config file (with auto-reload)
+registry, _ := static.NewWhitelistRegistryFromFile("/etc/go-trust/whitelist.yaml", true)
+defer registry.Close()
+
+// URL whitelist configured programmatically
+registry := static.NewWhitelistRegistry()
+registry.AddIssuer("https://pid-issuer.example.com")
+registry.AddVerifier("https://verifier.example.com")
 ```
 
+#### WhitelistRegistry Configuration
+
+The whitelist registry supports YAML or JSON configuration files:
+
+```yaml
+# whitelist.yaml
+issuers:
+  - https://pid-issuer.example.com
+  - https://issuer.example.org
+  - https://trusted-domain.com/*  # Wildcard prefix match
+
+verifiers:
+  - https://verifier.example.com
+  - https://rp.example.org
+
+trusted_subjects:
+  - https://any-role.example.com  # Matches any role
+```
+
+**Features:**
+- Role-based matching: `issuers` for credential issuers, `verifiers` for relying parties
+- Wildcard support: `https://example.com/*` matches any path under that domain
+- Global wildcard: `*` matches all subjects (use with caution)
+- File watching: Automatically reloads config when file changes (when `watch=true`)
+- Runtime updates: `AddIssuer()`, `RemoveIssuer()`, `AddVerifier()`, `RemoveVerifier()`
+
+**Security Note:** WhitelistRegistry provides URL-based trust only. Signature verification must be performed at the application layer. For cryptographic trust verification, use ETSI TSL, OpenID Federation, or other advanced registries.
+
 ## Deployment
 
 ### Docker
@@ -397,6 +473,11 @@ srv := testserver.New(testserver.WithRegistry(static.NewNeverTrustedRegistry()))
 
 // Test with system CA validation
 srv := testserver.New(testserver.WithRegistry(static.NewSystemCertPoolRegistry()))
+
+// Test with specific whitelist
+reg := static.NewWhitelistRegistry()
+reg.AddIssuer("https://test-issuer.example.com")
+srv := testserver.New(testserver.WithRegistry(reg))
 ```
 
 ## Development
@@ -430,7 +511,7 @@ go-trust/
 │   │   ├── oidfed/   # OpenID Federation registry
 │   │   ├── didweb/   # DID Web registry
 │   │   ├── didwebvh/ # DID Web VH registry
-│   │   └── static/   # Static registries (always/never/system)
+│   │   └── static/   # Static registries (always/never/system/whitelist)
 │   ├── logging/    # Structured logging
 │   └── testserver/ # Embedded test server
 ├── example/        # Example configurations

example/README.md

@@ -6,11 +6,24 @@ This directory contains configuration examples for running go-trust as an AuthZE
 
 | File | Description |
 |------|-------------|
-| `config.yaml` | Server configuration file example |
+| `config.yaml` | Comprehensive server configuration with all registry types documented |
 | `docker-compose.yaml` | Docker Compose deployment |
 | `kubernetes.yaml` | Kubernetes deployment with Ingress and ServiceMonitor |
 | `prometheus.yml` | Prometheus scrape configuration |
 
+## Registry Examples
+
+The `config.yaml` documents all supported registry types:
+
+| Registry | Resource Types | Resolution-Only | Description |
+|----------|---------------|-----------------|-------------|
+| ETSI TSL | `x5c` | No | X.509 trust via ETSI TS 119612 Trust Status Lists |
+| OpenID Federation | `entity_configuration`, `jwk` | Yes | Entity trust chain validation |
+| DID Web | `did_document`, `jwk`, `verification_method` | Yes | W3C did:web method |
+| DID Web VH | `did_document`, `jwk`, `verification_method` | Yes | did:webvh with verifiable history |
+| mDOC IACA | `x5c` | No | Dynamic IACA validation for mDOC/mDL |
+| Whitelist | URL-based | No | Simple URL-based trust (testing only) |
+
 ## Testing Examples
 
 The `testing/` subdirectory contains Go code examples for integration testing:
@@ -25,11 +38,39 @@ The `testing/` subdirectory contains Go code examples for integration testing:
 # Build the binary
 make build
 
-# Run with certificate bundle
+# Run with ETSI certificate bundle
 ./gt --etsi-cert-bundle /path/to/trusted-certs.pem
 
-# Run with config file
-./gt --config example/config.yaml
+# Run with multiple TSL files
+./gt --etsi-tsl-files /path/to/eu-lotl.xml,/path/to/se-tsl.xml
+
+# Run with logging configuration
+./gt --etsi-cert-bundle certs.pem --log-level debug --log-format json
+
+# Run with external URL (for .well-known discovery)
+./gt --etsi-cert-bundle certs.pem --external-url https://pdp.example.com
+```
+
+### CLI Options Reference
+
+```
+Server options:
+  --host string          API server hostname (default: 127.0.0.1)
+  --port string          API server port (default: 6001)
+  --external-url string  External URL for PDP discovery
+
+ETSI TSL options:
+  --etsi-cert-bundle string  Path to PEM file with trusted CA certificates
+  --etsi-tsl-files string    Comma-separated list of local TSL XML files
+
+Logging options:
+  --log-level string   debug, info, warn, error (default: info)
+  --log-format string  text or json (default: text)
+
+Other:
+  --config string  Configuration file path (YAML format) - partial support
+  --help           Show help message
+  --version        Show version information
 ```
 
 ### Running with Docker
@@ -64,4 +105,47 @@ tsl-tool --output trusted-certs.pem pipeline.yaml
 ./gt --etsi-cert-bundle trusted-certs.pem
 ```
 
+## Programmatic Registry Usage
+
+See the testing examples or the main [README](../README.md) for examples of using each registry type programmatically:
+
+```go
+// ETSI TSL
+reg, _ := etsi.NewTSLRegistry(etsi.TSLConfig{
+    Name:       "ETSI-TSL",
+    CertBundle: "/path/to/certs.pem",
+})
+
+// OpenID Federation
+reg, _ := oidfed.NewOIDFedRegistry(oidfed.Config{
+    Description: "OIDF Registry",
+    TrustAnchors: []oidfed.TrustAnchorConfig{
+        {EntityID: "https://federation.example.com"},
+    },
+})
+
+// DID Web
+reg, _ := didweb.NewDIDWebRegistry(didweb.Config{
+    Timeout:     30 * time.Second,
+    Description: "DID Web Registry",
+})
+
+// DID Web VH
+reg, _ := didwebvh.NewDIDWebVHRegistry(didwebvh.Config{
+    Timeout:     30 * time.Second,
+    Description: "DID Web VH Registry",
+})
+
+// mDOC IACA
+reg, _ := mdociaca.New(&mdociaca.Config{
+    Name:            "mDOC-IACA",
+    IssuerAllowlist: []string{"https://issuer.example.com"},
+    CacheTTL:        time.Hour,
+})
+
+// Whitelist
+reg, _ := static.NewWhitelistRegistryFromFile("/etc/go-trust/whitelist.yaml", true)
+defer reg.Close()
+```
+
 See the main [README](../README.md) for complete documentation.