Feature Proposal: Enterprise-grade API enhancements (Rate Limiting, Webhooks, Audit Logging)

Hi @jaredhendrickson13,

I've been using this excellent API package in production and found myself needing several enterprise features. Rather than maintaining a private fork, I'd love to contribute these back to the project if you're interested.

What I've Implemented

I've developed and tested the following features on pfSense 2.8.1:

1. Rate Limiting

Configurable request throttling to protect against abuse:

• Per-minute and per-hour limits (default: 60/min, 1000/hour)
• Burst allowance for traffic spikes
• Per-IP and per-API-key tracking
• Whitelist support for trusted IPs
• Standard headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

2. Webhook Events

Real-time notifications when resources change:

• Event patterns: firewall.*, *.created, *.updated, *.deleted
• HMAC-SHA256 signatures for verification
• Automatic retries (10s, 60s, 300s)
• Async delivery (non-blocking)

3. Audit Logging

Complete request/response logging for compliance:

• Full request details (method, endpoint, user, IP, duration)
• Automatic PII masking (passwords, secrets, tokens)
• Log rotation (10MB files, 10 files max)
• Syslog integration for SIEM systems
• Configurable retention (7-365 days)

4. Response Caching

Performance optimization with intelligent caching:

• APCu integration (with file fallback)
• ETag support with If-None-Match
• 304 Not Modified responses
• Configurable TTL (30-3600 seconds)

5. Cursor Pagination

Stable pagination for large datasets:

• Cursor-based navigation (stable during data changes)
• Forward/backward navigation
• HATEOAS prev/next links
• Backward compatible with limit/offset

6. New Endpoints

• GET /api/v2/system/health - System health checks (disk, memory, CPU, services, gateways)
• GET/POST /api/v2/system/backup - Backup management with optional encryption
• POST /api/v2/system/backup/restore - Restore with partial restore support
• GET/DELETE /api/v2/system/cache - Cache statistics and management
• GET /api/v2/audit/logs - Query audit logs
• POST /api/v2/diagnostics/ping - Run ping from pfSense
• POST /api/v2/diagnostics/traceroute - Run traceroute from pfSense
• POST /api/v2/diagnostics/dns_lookup - DNS lookups from pfSense
• Full webhook CRUD endpoints

7. Bug Fixes

• Fixed FirewallRule.gateway ForeignModelField including RoutingGatewayStatus (non-unique name field)
• Fixed PortForward.associated_rule_id using ForeignModelField for non-unique field
• Fixed memory exhaustion when reading large log files
• Fixed unsafe $_SERVER access (16 instances)
• Fixed unsafe array access after explode() (8 instances)
• Fixed CURLOPT_SSL_VERIFYHOST value (was 1, should be 2)
• Fixed PHP 8.1+ DateTime::getLastErrors() compatibility

Technical Details

• All features disabled by default - Zero impact on existing installations
• Backward compatible - No breaking changes
• New settings in RESTAPISettings model for configuration
• 43 new/modified files across Core, Models, Endpoints, and Responses

Questions

1. Are you interested in PRs for any/all of these features?
2. Would you prefer one large PR or separate PRs per feature?
3. Any architectural concerns or coding standards I should follow?

I'm happy to split this into smaller, focused PRs if that's easier to review. I can also add tests and documentation as needed.

Thanks for building such a solid foundation!