← Documentation

Policy Engine

Policy Engine

Imara enforces capability bounds through a TOML-based policy file. Every classified action is checked against these rules before execution. The engine is fail-closed — no matching rule means the action is blocked and logged.

Fail-closed by default

If an intent is classified to an action type that has no matching allow rule, the request is blocked with status BLOCKED_POLICY. The block is written to the ledger and included in the hash chain. There is no fallback, override flag, or admin bypass — policy is enforced structurally.

ⓘ

Blocked actions still produce a ledger entry and chain link. Regulators can see exactly what was attempted and why it was stopped.

policy.toml structure

The policy file lives at policy.toml in your working directory. It contains one or more [[rules]] sections.

# policy.toml

[[rules]]
action  = "ACTION_PAYMENT_INITIATE"
effect  = "allow"
limit   = 10_000          # maximum amount in base units
currency = "USD"

[[rules]]
action  = "ACTION_PAYMENT_APPROVE"
effect  = "allow"

[[rules]]
action  = "ACTION_PAYMENT_QUERY"
effect  = "allow"

# Anything not listed above is implicitly denied.

Rule fields

action*

string

The classified action type this rule applies to. Must match the dispatcher's output exactly.

effect*

allow | deny

Whether to permit or explicitly block this action. Omitting is equivalent to deny.

limit

number

For payment actions: the maximum amount in base currency units.

currency

string

ISO 4217 currency code. Enforced alongside limit.

tenant

string

Scope this rule to a specific tenant ID. Omit to apply to all tenants.

* required

Example: multi-tenant policy

Scope rules to individual fintech tenants to enforce different limits per institution.

[[rules]]
action   = "ACTION_PAYMENT_INITIATE"
effect   = "allow"
tenant   = "acme-bank"
limit    = 50_000
currency = "USD"

[[rules]]
action   = "ACTION_PAYMENT_INITIATE"
effect   = "allow"
tenant   = "nova-pay"
limit    = 5_000
currency = "USD"

[[rules]]
action   = "ACTION_PAYMENT_QUERY"
effect   = "allow"   # all tenants can query

Reloading policy at runtime

Send a SIGHUP to reload policy without restarting the process. The new rules take effect for all subsequent requests; in-flight requests complete under the previous policy.

kill -HUP $(pgrep stratusos)
ⓘ

Policy reloads are logged to the system ledger with a special entry type so auditors can see exactly when rules changed.

Next: S3 Replication