# Policy Structure

## Overview

This document defines the structure and configuration options for the Autheona Policy Engine rules. Policies are JSON-based rule sets evaluated by the AST-based engine to determine actions (allow, block, ignore) based on email, domain, and IP intelligence data.

## Policy Structure

A Policy is the root container for all rules. It defines the schema version, the top-level rule set, and execution behavior.

```json
{
  "version": "1.0",
  "stop_on_block": true,
  "parent_rules": [
    {
      "field": "domain_disposable",
      "operator": "==",
      "target": {
        "bool": true
      },
      "action": "block"
    }
  ]
}
```

### Policy Fields

| Field           | Type    | Required | Description                                                                                            |
| --------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------ |
| `version`       | String  | Yes      | Schema version identifier for the policy.                                                              |
| `stop_on_block` | Boolean | No       | If `true`, evaluation stops immediately when any rule with `block` action matches. Default is `false`. |
| `parent_rules`  | Array   | Yes      | Array of top-level rules executed concurrently. Each rule is evaluated in a separate worker thread.    |

## Rule Structure

A Rule is a single evaluation unit within the policy tree. Every rule acts as either a **Logical Branch** (grouping other rules) or a **Leaf Condition** (performing a comparison).

### Leaf Condition Structure

```json
{
  "field": "email_deliverable",
  "operator": "==",
  "target": {
    "bool": false
  },
  "action": "block"
}
```

### Logical Branch Structures

**AND Branch** (all children must match):

```json
{
  "and_rules": [
    {
      "field": "domain_valid_tld",
      "operator": "==",
      "target": {
        "bool": true
      },
      "action": "allow"
    },
    {
      "field": "email_deliverable",
      "operator": "==",
      "target": {
        "bool": true
      },
      "action": "allow"
    }
  ]
}
```

**OR Branch** (any child must match):

```json
{
  "or_rules": [
    {
      "field": "domain_disposable",
      "operator": "==",
      "target": {
        "bool": true
      },
      "action": "block"
    },
    {
      "field": "domain_typo",
      "operator": "==",
      "target": {
        "bool": true
      },
      "action": "block"
    }
  ]
}
```

**NOT Branch** (negates the child rule):

```json
{
  "not_rule": {
    "field": "domain_valid_tld",
    "operator": "==",
    "target": {
      "bool": true
    },
    "action": "block"
  }
}
```

### Rule Fields

| Field       | Type   | Required         | Description                                                                     |
| ----------- | ------ | ---------------- | ------------------------------------------------------------------------------- |
| `field`     | String | Yes (for leaf)   | The data point to inspect. See [Available Fields](#available-fields).           |
| `operator`  | String | Yes (for leaf)   | Comparison operator. See [Operators](#operators).                               |
| `target`    | Object | Yes (for leaf)   | Expected value for comparison. Contains `bool`, `number`, or `string` property. |
| `action`    | String | Yes (for leaf)   | Action to take if the condition matches: `allow`, `block`, or `ignore`.         |
| `params`    | Object | No               | Additional parameters for specific field evaluations.                           |
| `and_rules` | Array  | Yes (for branch) | Array of rules where ALL must match.                                            |
| `or_rules`  | Array  | Yes (for branch) | Array of rules where ANY must match.                                            |
| `not_rule`  | Object | Yes (for branch) | Single rule to negate.                                                          |

## Actions

Actions define the verdict applied when a rule condition matches.

| Action   | Behavior                                                                 |
| -------- | ------------------------------------------------------------------------ |
| `allow`  | Permits the request. Lowest priority; overridden by `block`.             |
| `block`  | Blocks the request. Highest priority in the security hierarchy.          |
| `ignore` | Evaluates the rule but produces no action. Used for shadow mode testing. |

### Action Resolution Hierarchy

The engine uses a Fail-Closed security posture. When multiple actions are triggered:

1. `block` (highest priority)
2. `allow` (lowest priority)

If any rule triggers a block, it overrides all permissive rules.

## Operators

Operators define how the field value is compared against the target.

### Boolean Operators

|  Operator | Description  |
| --------- | ------------ |
| `==`      | Equal to     |
| `!=`      | Not equal to |

### Numeric Operators

| Operator | Description              |
| -------- | ------------------------ |
| `==`     | Equal to                 |
| `!=`     | Not equal to             |
| `<`      | Less than                |
| `>`      | Greater than             |
| `<=`     | Less than or equal to    |
| `>=`     | Greater than or equal to |

### List Operator

| Operator | Description                                                      |
| -------- | ---------------------------------------------------------------- |
| `list`   | Checks if the field value exists within a referenced named list. |

## Available Fields

Fields are categorized by their target value type and the supported operators.

### Boolean Fields

These fields evaluate to `true` or `false`. Supported operators: `==`, `!=`.

#### Email Boolean Fields

| Field                    | Description                                          |
| ------------------------ | ---------------------------------------------------- |
| `domain_business`        | Domain is classified as business type.               |
| `domain_disposable`      | Domain is a known disposable email provider.         |
| `domain_educational`     | Domain is an educational institution.                |
| `domain_free`            | Domain is a free email provider (e.g., gmail.com).   |
| `domain_government`      | Domain is a government entity.                       |
| `domain_ipv4_address`    | Domain resolves to an IPv4 address.                  |
| `domain_ipv6_address`    | Domain resolves to an IPv6 address.                  |
| `domain_numeric_only`    | Domain consists of numeric characters only.          |
| `domain_punycode`        | Email uses punycode encoding.                        |
| `domain_single_label`    | Domain has only one label (no dots).                 |
| `domain_typo`            | Domain is a common typo of a legitimate domain.      |
| `domain_valid_tld`       | Domain has a valid Top-Level Domain.                 |
| `domain_website`         | Domain is a registered website.                      |
| `email_deliverable`      | Email address is deliverable (MX record exists).     |
| `local_dot_variations`   | Local part has dot variations (e.g., j.doe vs jdoe). |
| `local_fraud_pattern`    | Local part matches known fraud patterns.             |
| `local_hyphen`           | Local part contains hyphens.                         |
| `local_mixed_script`     | Email contains mixed Unicode scripts.                |
| `local_numeric`          | Local part contains numeric characters.              |
| `local_plus_addressing`  | Local part uses plus addressing (e.g., +tag).        |
| `local_quoted`           | Local part is quoted.                                |
| `local_role_based`       | Local part is a role address (e.g., admin@).         |
| `local_special_chars`    | Local part contains special characters.              |
| `local_underscore`       | Local part contains underscores.                     |
| `subdomain_hyphenated`   | Subdomain contains hyphens.                          |
| `subdomain_numeric_only` | Subdomain is numeric only.                           |
| `subdomain_uuid_hash`    | Subdomain resembles a UUID or hash.                  |
| `subdomain_wildcard`     | Subdomain is a wildcard record.                      |

### Numeric Fields

These fields evaluate to a number. Supported operators: `==`, `!=`, `<`, `>`, `<=`, `>=`.

#### Email Numeric Fields

| Field             | Description                                   | Minimum Value | Maximum Value |
| ----------------- | --------------------------------------------- | ------------- | ------------- |
| `domain_age_days` | Age of the domain registration in days.       | `1`           | `1024`        |
| `email_velocity`  | Frequency/volume of emails from this address. | `1`           | `1024`        |
| `subdomain_count` | Number of subdomains for the domain.          | `1`           | `32`          |

### String List Fields

These fields check if a value exists within a user-defined list. Supported operator: `list`.

#### Email String List Fields

| Field                   | Description                                         | Target Format    |
| ----------------------- | --------------------------------------------------- | ---------------- |
| `domain_custom_domains` | Checks against a custom domain list.                | List UUID string |
| `domain_custom_tlds`    | Checks against a custom TLD list.                   | List UUID string |
| `local_custom_roles`    | Checks against a custom role-based local part list. | List UUID string |

## Target Configuration

The `target` object specifies the expected value for comparison. Only include the field matching the rule's data type.

### Boolean Target

```json
{
  "target": {
    "bool": true
  }
}

{
  "target": {
    "bool": false
  }
}
```

### Numeric Target

```json
{
  "target": {
    "number": 30
  }
}

{
  "target": {
    "number": 5.5
  }
}
```

### String Target (for List Operator)

```json
{
  "target": {
    "string": "reference-key"
  }
}
```

## Example Policies

### Block Disposable Emails

Blocks any email from a disposable email provider.

```json
{
  "version": "1.0",
  "stop_on_block": true,
  "parent_rules": [
    {
      "field": "domain_disposable",
      "operator": "==",
      "target": {
        "bool": true
      },
      "action": "block"
    }
  ]
}
```

### Block Undeliverable and Fraudulent Emails

Uses an OR branch to check multiple conditions.

```json
{
  "version": "1.0",
  "stop_on_block": false,
  "parent_rules": [
    {
      "or_rules": [
        {
          "field": "email_deliverable",
          "operator": "==",
          "target": {
            "bool": false
          },
          "action": "block"
        },
        {
          "field": "local_fraud_pattern",
          "operator": "==",
          "target": {
            "bool": true
          },
          "action": "block"
        }
      ]
    }
  ]
}
```

### Allow Only Corporate Domains

Uses the `list` operator to check against a custom domain whitelist.

```json
{
  "version": "1.0",
  "stop_on_block": true,
  "parent_rules": [
    {
      "field": "domain_custom_domains",
      "operator": "list",
      "target": {
        "string": "reference-key"
      },
      "action": "allow"
    },
    {
      "field": "domain_custom_domains",
      "operator": "list",
      "target": {
        "string": "reference-key"
      },
      "action": "block"
    }
  ]
}
```

### Complex Multi-Condition Policy

Combines AND and OR logic with short-circuit evaluation.

```json
{
  "version": "1.0",
  "stop_on_block": true,
  "parent_rules": [
    {
      "and_rules": [
        {
          "field": "domain_valid_tld",
          "operator": "==",
          "target": {
            "bool": true
          },
          "action": "ignore"
        },
        {
          "or_rules": [
            {
              "field": "domain_age_days",
              "operator": "<",
              "target": {
                "number": 30
              },
              "action": "block"
            },
            {
              "field": "subdomain_count",
              "operator": ">",
              "target": {
                "number": 10
              },
              "action": "allow"
            }
          ]
        }
      ]
    }
  ]
}
```