next.orly.dev/docs/POLICY_README.md

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:

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

{
  "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

{"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