feat(proxy): Add wildcard subdomain support with PSL integration (#137)

* feat(proxy): add wildcard subdomain support with PSL integration

- Add cross-platform wildcard credential resolution using _wildcard. prefix
- Integrate Public Suffix List (PSL) for security boundaries
- Implement domain normalization with IDN support (punycode)
- Add TTL-based caching with size limits (10K entries max)
- Add feature flag CNP_WILDCARD_CREDENTIALS with shadow mode
- Fix critical path traversal vulnerability in credential resolution
- Add comprehensive unit tests and security tests
- Create ADR-023 documenting the implementation
- Update environment variables documentation

This allows organizations to use a single credential file for multiple
subdomains while maintaining security through PSL boundaries and proper
path validation.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* chore: remove temporary planning files

Remove IMPORTANT_FILES.yaml and PLAN.md that were used for
implementation planning but should not be part of the codebase.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

* docs: update documentation for wildcard credentials

- Add wildcard credential environment variables to .env.example
- Update main README with wildcard credentials section
- Add wildcard support details to proxy README
- Update credentials README with wildcard file naming

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

---------

Co-authored-by: Claude <[email protected]>

Author: crystalin

.env.example

@@ -23,6 +23,19 @@ DASHBOARD_API_KEY=your-secure-dashboard-key-here
 # Directory for domain credential files (default: ./credentials)
 CREDENTIALS_DIR=./credentials
 
+# Wildcard credential support (default: false)
+# true = Enable wildcard matching, false = Disable, shadow = Log only (no behavior change)
+# When enabled, _wildcard.example.com.credentials.json matches all subdomains of example.com
+CNP_WILDCARD_CREDENTIALS=false
+
+# TTL for credential resolution cache in milliseconds (default: 300000 = 5 minutes)
+# Caches both successful and failed credential lookups for performance
+CNP_RESOLUTION_CACHE_TTL=300000
+
+# Enable debug logging for credential resolution (default: false)
+# Logs detailed information about domain matching and wildcard resolution
+CNP_DEBUG_RESOLUTION=false
+
 # ===================
 # Service Configuration
 # ===================

README.md

@@ -318,6 +318,27 @@ EOF
 
 (_Use `credentials/localhost\:3000.credentials.json` for using it locally_)
 
+#### Wildcard Credentials
+
+You can use wildcard credentials to match multiple subdomains with a single credential file:
+
+```bash
+# Matches all subdomains of example.com (api.example.com, staging.example.com, etc.)
+cat > credentials/_wildcard.example.com.credentials.json << EOF
+{
+  "type": "api_key",
+  "accountId": "acc_name_to_display",
+  "api_key": "sk-ant-...",
+  "client_api_key": "cnp_live_..."
+}
+EOF
+
+# Enable wildcard support
+export CNP_WILDCARD_CREDENTIALS=true
+```
+
+Note: Exact matches take precedence over wildcards. See [ADR-023](docs/04-Architecture/ADRs/adr-023-wildcard-subdomain-support.md) for details.
+
 Authenticate your credential with Claude MAX Plan:
 
 ```bash

bun.lock

@@ -80,6 +80,7 @@
         "nanoid": "^5.0.8",
         "node-cache": "^5.1.2",
         "p-limit": "^6.1.0",
+        "psl": "^1.15.0",
         "rate-limiter-flexible": "^5.0.3",
         "redact-pii": "^3.4.0",
         "zod": "^3.24.1",
@@ -88,6 +89,7 @@
         "@types/bun": "^1.2.17",
         "@types/js-yaml": "^4.0.9",
         "@types/node": "^24.0.10",
+        "@types/psl": "^1.11.0",
       },
     },
   },
@@ -238,6 +240,8 @@
 
     "@types/pino": ["@types/[email protected]", "", { "dependencies": { "pino": "*" } }, "sha512-wKoab31pknvILkxAF8ss+v9iNyhw5Iu/0jLtRkUD74cNfOOLJNnqfFKAv0r7wVaTQxRZtWrMpGfShwwBjOcgcg=="],
 
+    "@types/psl": ["@types/[email protected]", "", { "dependencies": { "psl": "*" } }, "sha512-OeASqmnreaSJyxwljqCZjRIf7jpbwswaqbSPahE99PZrizNAOXEl9HRWhXvCt3fkAc/WuF8wcZ6zkDHXaE7X4g=="],
+
     "@types/react": ["@types/[email protected]", "", { "dependencies": { "csstype": "^3.0.2" } }, "sha512-AwAfQ2Wa5bCx9WP8nZL2uMZWod7J7/JSplxbTmBQ5ms6QpqNYm672H0Vu9ZVKVngQ+ii4R/byguVEUZQyeg44g=="],
 
     "@types/rimraf": ["@types/[email protected]", "", { "dependencies": { "@types/glob": "*", "@types/node": "*" } }, "sha512-F3OznnSLAUxFrCEu/L5PY8+ny8DtcFRjx7fZZ9bycvXRi3KPTRS9HOitGZwvPg0juRhXFWIeKX58cnX5YqLohQ=="],
@@ -784,6 +788,8 @@
 
     "proxy-from-env": ["[email protected]", "", {}, "sha512-D+zkORCbA9f1tdWRK0RaCR3GPv50cMxcrz4X8k5LTSUD1Dkw47mKJEZQNunItRTkWwgtaUSo1RVFRIG9ZXiFYg=="],
 
+    "psl": ["[email protected]", "", { "dependencies": { "punycode": "^2.3.1" } }, "sha512-JZd3gMVBAVQkSs6HdNZo9Sdo0LNcQeMNP3CozBJb3JYC/QUYZTnKxP+f8oWRX4rHP5EurWxqAHTSwUCjlNKa1w=="],
+
     "punycode": ["[email protected]", "", {}, "sha512-vYt7UD1U9Wg6138shLtLOvdAu+8DsC/ilFtEVHcH+wydcSpNE20AfSOduf6MkRFahL5FY7X1oU7nKVZFtfq8Fg=="],
 
     "punycode.js": ["[email protected]", "", {}, "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA=="],

credentials/README.md

@@ -8,6 +8,15 @@ Each domain should have its own credential file named `<domain>.credentials.json
 
 Example: `example.com.credentials.json`
 
+### Wildcard Credentials
+
+You can create wildcard credential files to match multiple subdomains:
+
+- `_wildcard.example.com.credentials.json` - Matches all subdomains of example.com
+- `_wildcard.staging.example.com.credentials.json` - Matches all subdomains of staging.example.com
+
+**Note**: Exact matches always take precedence over wildcards. Enable with `CNP_WILDCARD_CREDENTIALS=true`.
+
 ## Credential Structure
 
 ```json

docs/04-Architecture/ADRs/adr-023-wildcard-subdomain-support.md

@@ -0,0 +1,126 @@
+# ADR-023: Wildcard Subdomain Support
+
+## Status
+
+Accepted
+
+## Context
+
+The Claude Nexus Proxy needs to support organizations with many subdomains (e.g., `api.staging.example.com`, `api.prod.example.com`, `api.dev.example.com`) without requiring separate credential files for each subdomain. This is particularly important for:
+
+1. Large organizations with environment-based subdomains
+2. Multi-tenant SaaS applications with customer-specific subdomains
+3. Development teams using feature branch deployments
+
+Currently, each subdomain requires its own credential file, leading to:
+
+- Credential proliferation and management overhead
+- Increased risk of configuration drift
+- Difficulty in rotating API keys across environments
+
+## Decision
+
+We will implement wildcard subdomain support using a prefix-based approach that is cross-platform compatible:
+
+### 1. Wildcard Credential Files
+
+- Use `_wildcard.` prefix for wildcard credential files
+- Example: `_wildcard.example.com.credentials.json` matches `*.example.com`
+- This avoids filesystem issues with `*` character on Windows
+
+### 2. Resolution Order
+
+Credentials are resolved in order of specificity:
+
+1. Exact match: `api.staging.example.com.credentials.json`
+2. Most specific wildcard: `_wildcard.staging.example.com.credentials.json`
+3. Less specific wildcard: `_wildcard.example.com.credentials.json`
+4. No match: fallback to default behavior
+
+### 3. Security Boundaries
+
+- Integrate Public Suffix List (PSL) to prevent privilege escalation
+- Wildcard matching stops at registrable domain boundaries
+- Example: `_wildcard.co.uk.credentials.json` will NOT match `example.co.uk`
+
+### 4. Feature Flag Control
+
+- Environment variable: `CNP_WILDCARD_CREDENTIALS`
+- Values:
+  - `true`: Enable wildcard support
+  - `false`: Disable (default)
+  - `shadow`: Log matches without changing behavior
+
+### 5. Performance Optimization
+
+- TTL-based caching for credential resolution
+- Cache both positive and negative results
+- Environment variable: `CNP_RESOLUTION_CACHE_TTL` (default: 5 minutes)
+- Maximum cache size: 10,000 entries with LRU eviction
+
+### 6. Domain Normalization
+
+- Convert to lowercase
+- Remove ports
+- Handle Internationalized Domain Names (IDN) with punycode
+- Remove trailing dots
+- Collapse consecutive dots
+
+## Consequences
+
+### Positive
+
+- **Simplified credential management**: One file can serve multiple subdomains
+- **Reduced configuration drift**: Centralized credential updates
+- **Better security**: PSL integration prevents unauthorized access
+- **Cross-platform compatibility**: Works on all operating systems
+- **Performance**: Caching reduces filesystem operations
+- **Backward compatible**: Existing configurations continue to work
+- **Safe rollout**: Shadow mode allows testing without risk
+
+### Negative
+
+- **Added complexity**: More code paths to maintain
+- **Memory usage**: Cache requires memory (bounded at 10K entries)
+- **PSL dependency**: Requires maintaining PSL library
+- **Learning curve**: Administrators need to understand wildcard behavior
+
+### Neutral
+
+- **Explicit wildcards**: Requires `_wildcard.` prefix (not automatic)
+- **Cache invalidation**: Manual cache clear may be needed for immediate updates
+
+## Implementation Details
+
+### Key Components
+
+1. **AuthenticationService**: Enhanced with wildcard resolution logic
+2. **Domain normalization**: Handles IDN, ports, and edge cases
+3. **PSL integration**: Prevents privilege escalation attacks
+4. **Resolution cache**: Map with TTL-based expiration
+5. **Feature flags**: Safe rollout with shadow mode
+
+### Configuration Examples
+
+```
+# Wildcard for all staging subdomains
+_wildcard.staging.example.com.credentials.json
+
+# Wildcard for all subdomains of example.com
+_wildcard.example.com.credentials.json
+
+# Exact match (takes precedence)
+api.staging.example.com.credentials.json
+```
+
+### Environment Variables
+
+- `CNP_WILDCARD_CREDENTIALS`: Enable/disable feature
+- `CNP_RESOLUTION_CACHE_TTL`: Cache TTL in milliseconds
+- `CNP_DEBUG_RESOLUTION`: Enable debug logging
+
+## References
+
+- [Public Suffix List](https://publicsuffix.org/)
+- [RFC 3490: Internationalizing Domain Names in Applications (IDNA)](https://tools.ietf.org/html/rfc3490)
+- Original implementation plan: `/PLAN.md`

docs/06-Reference/environment-vars.md

@@ -47,6 +47,14 @@ DATABASE_URL=postgresql://user:password@localhost:5432/claude_nexus
 | --------------------- | ----------------------------- | ------- |
 | `DASHBOARD_CACHE_TTL` | Dashboard cache TTL (seconds) | `30`    |
 
+### Wildcard Credentials
+
+| Variable                   | Description                                           | Default  |
+| -------------------------- | ----------------------------------------------------- | -------- |
+| `CNP_WILDCARD_CREDENTIALS` | Enable wildcard subdomain support (true/false/shadow) | `false`  |
+| `CNP_RESOLUTION_CACHE_TTL` | TTL for credential resolution cache (ms)              | `300000` |
+| `CNP_DEBUG_RESOLUTION`     | Enable debug logging for credential resolution        | `false`  |
+
 ## Service Configuration
 
 ### Proxy Service
@@ -236,6 +244,11 @@ GEMINI_MODEL_NAME=gemini-2.0-flash-exp
 CREDENTIALS_DIR=./credentials
 TEST_SAMPLES_DIR=./test-samples
 
+# Wildcard Credentials (optional)
+# CNP_WILDCARD_CREDENTIALS=true
+# CNP_RESOLUTION_CACHE_TTL=300000
+# CNP_DEBUG_RESOLUTION=false
+
 # Production (uncomment for production)
 # NODE_ENV=production
 # LOG_LEVEL=warn

services/proxy/README.md

@@ -45,6 +45,9 @@ See `.env.example` in the root directory for all available environment variables
 - `DATABASE_URL` - PostgreSQL connection
 - `STORAGE_ENABLED` - Enable storage (default: false)
 - `SLACK_WEBHOOK_URL` - Slack notifications
+- `CNP_WILDCARD_CREDENTIALS` - Enable wildcard credential support (true/false/shadow)
+- `CNP_RESOLUTION_CACHE_TTL` - TTL for credential resolution cache in ms (default: 300000)
+- `CNP_DEBUG_RESOLUTION` - Enable debug logging for credential resolution
 
 ## API Endpoints
 

services/proxy/package.json

@@ -32,14 +32,16 @@
     "nanoid": "^5.0.8",
     "node-cache": "^5.1.2",
     "p-limit": "^6.1.0",
-    "zod": "^3.24.1",
+    "psl": "^1.15.0",
+    "rate-limiter-flexible": "^5.0.3",
     "redact-pii": "^3.4.0",
-    "rate-limiter-flexible": "^5.0.3"
+    "zod": "^3.24.1"
   },
   "devDependencies": {
     "@types/bun": "^1.2.17",
+    "@types/js-yaml": "^4.0.9",
     "@types/node": "^24.0.10",
-    "@types/js-yaml": "^4.0.9"
+    "@types/psl": "^1.11.0"
   },
   "engines": {
     "node": ">=20.0.0"