Implement policy system with comprehensive testing and configuration

- Introduced a new policy system for event processing, allowing fine-grained control over event storage and retrieval based on various criteria.
- Added support for policy configuration via JSON files, including whitelists, blacklists, and custom scripts.
- Implemented a test suite for the policy system, ensuring 100% test coverage of core functionality and edge cases.
- Created benchmark tests to evaluate policy performance under various conditions.
- Updated event handling to integrate policy checks for both read and write access.
- Enhanced documentation with examples and usage instructions for the policy system.
- Bumped version to v0.16.0.

docs/POLICY_README.md

@@ -0,0 +1,113 @@
+# ORLY Policy System
+
+The ORLY relay includes a comprehensive policy system that allows fine-grained control over event storage and retrieval based on various criteria including event kinds, pubkeys, content, and custom script logic.
+
+## Configuration
+
+Enable the policy system by setting the environment variable:
+```bash
+export ORLY_POLICY_ENABLED=true
+```
+
+## Policy Configuration File
+
+The policy configuration is loaded from `$HOME/.config/ORLY/policy.json`. See `example-policy.json` for a complete example.
+
+### Structure
+
+```json
+{
+  "kind": {
+    "whitelist": [1, 3, 5, 7, 9735],
+    "blacklist": []
+  },
+  "rules": {
+    "1": {
+      "description": "Text notes - allow all authenticated users",
+      "write_allow": [],
+      "write_deny": [],
+      "read_allow": [],
+      "read_deny": [],
+      "size_limit": 32000,
+      "content_limit": 10000
+    }
+  }
+}
+```
+
+### Kinds Filtering
+
+- `whitelist`: If present, only these event kinds are allowed. All others are denied.
+- `blacklist`: If present, these event kinds are denied. All others are allowed.
+- If both are empty, all kinds are allowed.
+
+### Rule Fields
+
+- `description`: Human-readable description of the rule
+- `script`: Path to a script for custom logic (overrides other criteria)
+- `write_allow`: List of pubkeys allowed to write this kind
+- `write_deny`: List of pubkeys denied from writing this kind
+- `read_allow`: List of pubkeys allowed to read this kind
+- `read_deny`: List of pubkeys denied from reading this kind
+- `max_expiry`: Maximum expiry time in seconds for events
+- `must_have_tags`: List of tag keys that must be present
+- `size_limit`: Maximum total event size in bytes
+- `content_limit`: Maximum content field size in bytes
+- `privileged`: If true, event must be authored by authenticated user or contain authenticated user in p tags
+- `rate_limit`: Rate limit in bytes per second (not yet implemented)
+
+## Policy Scripts
+
+For advanced policy logic, you can use custom scripts. The script should be placed at `$HOME/.config/ORLY/policy.sh` and made executable.
+
+### Script Interface
+
+The script receives JSON events via stdin and outputs JSON responses via stdout. Each event includes:
+
+- All original event fields
+- `logged_in_pubkey`: Hex-encoded authenticated user's pubkey (if any)
+- `ip_address`: Client's IP address
+
+### Response Format
+
+```json
+{"id": "event_id", "action": "accept|reject|shadowReject", "msg": "optional message"}
+```
+
+### Example Script
+
+See `example-policy.sh` for a complete example showing:
+- IP address blocking
+- Content filtering
+- Authentication requirements
+- User-specific permissions
+
+## Integration Points
+
+### EVENT Processing
+
+When policy is enabled, every EVENT envelope is checked using `CheckPolicy("write", event, loggedInPubkey, ipAddress)` before being stored.
+
+### REQ Processing
+
+When policy is enabled, every event returned in REQ responses is filtered using `CheckPolicy("read", event, loggedInPubkey, ipAddress)` before being sent to the client.
+
+## Error Handling
+
+- If policy script fails or times out, events are allowed by default
+- If policy configuration is invalid, default policy (allow all) is used
+- Policy script failures are logged but don't block relay operation
+
+## Monitoring
+
+Policy decisions are logged at debug level:
+- `policy allowed event <id>`
+- `policy rejected event <id>`
+- `policy filtered out event <id> for read access`
+
+## Security Considerations
+
+- Policy scripts run with the same privileges as the relay process
+- Scripts should be carefully reviewed and tested
+- Consider using read-only filesystems for policy scripts in production
+- Monitor script execution time to prevent DoS attacks