Rules, amounts and currencies

A policy version is one JSON document in the kblock.cloud/policy@1 format. It holds a list of rules and a default. For every tool call, the Gateway evaluates the agent's active version: the rules that match the call compete, the most restrictive one wins, and when no rule matches, the default decides.

This page is the reference for writing that document. To create and save one, see Create a policy.

A complete example

This document is valid (it was checked with K-Block's own validator) and is a simplified version of the Support refunds template. It assumes tools whose actions are orders.read, orders.search, refund.issue, payouts.send and customers.export, and a refund tool whose amount is mapped in USD.

{
  "schema": "kblock.cloud/policy@1",
  "default": "deny",
  "rules": [
    { "id": "read-orders", "actions": ["orders.read", "orders.search"], "effect": "allow" },
    {
      "id": "refund-over-limit",
      "actions": ["refund.issue"],
      "amount": { "currency": "USD", "gt": "1000" },
      "effect": "deny"
    },
    {
      "id": "refund-approval",
      "actions": ["refund.issue"],
      "amount": { "currency": "USD", "gt": "100", "lte": "1000" },
      "effect": "require_approval",
      "approvers": { "roles": ["owner", "admin", "approver"] },
      "approval_ttl_seconds": 14400
    },
    {
      "id": "refund-auto",
      "actions": ["refund.issue"],
      "amount": { "currency": "USD", "lte": "100" },
      "effect": "allow"
    },
    { "id": "never", "actions": ["payouts.*", "customers.export"], "effect": "deny" }
  ]
}

How it decides some calls:

Document structure

Validation is strict: any member not listed on this page, at any level, is refused with UNKNOWN_MEMBER.

Rule members

How rules match a call

The Gateway knows four things about a call when it evaluates the policy: the tool's action (set when the tool was exposed, for example refund.issue), the exposed tool name (for example issue_refund), the call's amount, if the tool has an amount mapping, and the call's arguments, which only rules with argument conditions look at.

A rule is a candidate for a call when all of these hold:

1. One of its actions patterns matches the tool's action.
2. If it has tools, the exposed tool name is in the list.
3. If it has an amount condition, the amount satisfies it (see Amount conditions).
4. If it has a when list, its argument conditions hold (see Argument conditions).

Action patterns

A pattern is dot-separated segments of lowercase letters, digits, _ and -, with an optional final * segment, or * alone, at most 128 characters. Patterns in the reserved kblock. namespace are refused, because no tool action can use it.

Effects and the winner

Among the candidates, the most restrictive effect wins: deny beats require_approval, which beats allow. When several candidates have the winning effect, the first one in document order decides (so its approvers and TTL apply).

Rule order therefore matters only between rules with the same effect. A broad allow rule can never override a matching deny rule, wherever it is placed.

The default

When no rule is a candidate, the document's default decides:

• "deny": the call is refused.
• "require_approval": the call waits for approval by any member whose role is owner, admin or approver (the default has no approver list of its own).

A permissive default is not possible: anything you want to allow must be allowed by a rule.

Amount conditions and thresholds

An amount condition compares the call's amount with up to four thresholds, using exact decimal arithmetic (never floating point):

Write the thresholds as decimal strings, for example "100" or "99.50", with up to 18 digits before and 18 after the decimal point. A condition whose bounds admit no value (for example gt "10" and lt "5") is refused with CONTRADICTORY_BOUNDS.

The rule matches only when the call has an amount in the condition's currency that satisfies every bound you set. To cover a range without gaps, pair an exclusive bound with an inclusive one at the same threshold, as the example does with lte "100" and gt "100".

Missing amounts fail closed

When a call has no amount, or an amount in another currency than the condition's, K-Block cannot compare it. It then fails closed:

• deny and require_approval rules with an amount condition match;
• allow rules with an amount condition do not match.

In the example, a refund without a readable amount matches both refund-over-limit and refund-approval, and the deny wins. The decision's explanation records which rules matched only because of the missing amount. The validator's advisory warning FAIL_CLOSED_ROUTING tells you which tools are routed this way.

How amounts are read

A policy never reads tool arguments itself. The amount comes from the tool's amount mapping, which you set when you expose or edit the tool (see Expose and map tools):

Only a signed-in owner or admin can change the amount mapping of an enabled tool. The amount mapping is part of the tool's authorized binding: after any change, the Gateway does not run the tool's calls until an owner or admin authorizes the tool again.

Accepted amount values

The value at the amount pointer must be one of:

• a non-negative decimal string: digits, optionally a . and 1 to 18 fraction digits, no sign, no exponent, no leading zeros ("12.50", "0.5", "1000");
• a non-negative integer JSON number that is a safe integer (12).

There are no currency-specific decimal rules: "12.345" is accepted for USD. The string is used exactly as given.

INVALID_AMOUNT is decided before the policy is evaluated, so no rule can allow such a call, and observe windows never relax it. An amount mapping that is itself invalid denies calls with INVALID_TOOL_CONFIGURATION.

Tools without an amount mapping

A tool without an amount mapping has no amounts: every call is treated as having no amount (it is priced 0 with the placeholder currency XXX in the signed task). Amount conditions in the policy never allow such calls, and a delegation with a spending limit refuses them.

Currencies

Three currencies can be involved: the tool's Currency, an optional currency the call names, and the currency of each rule's amount condition.

Fixed currency (no currency pointer)

Without a currency pointer, every amount of the tool is in the tool's currency. A currency argument the agent passes is not read: a call with {"amount": "5", "currency": "EUR"} on a USD tool is evaluated as 5 USD. Use this only when the upstream tool always works in that currency.

Currency pointer

With a currency pointer, the call must name exactly the tool's currency at that pointer. A different code, a lowercase code, or a missing value denies the call with INVALID_AMOUNT, and the upstream is never called. This prevents an upstream that honours the call's currency from executing an amount the policy priced in another currency.

Rule currency and tool currency differ

If a rule's amount condition names another currency than the tool's (for example the rule says EUR, the tool is mapped in USD), the comparison is impossible and the rule fails closed: deny and require_approval rules match, allow rules do not. Keep the currencies of your amount rules equal to the currencies of the tools they target.

Approvers in rules

A require_approval rule must say who may approve:

{ "roles": ["owner", "admin"], "users": ["<user-id>"] }

• roles: one to three of owner, admin, approver.
• users: 1 to 32 member user IDs (lowercase UUIDs). The Reference card in the editor lists the members who can approve, with their IDs.

A person is eligible when their current role is owner, admin or approver and either their role is listed or their user ID is listed. A listed user who later becomes a developer or viewer is no longer eligible. Validation refuses users who are not members (UNKNOWN_APPROVER) or whose role cannot approve (APPROVER_ROLE_NOT_CAPABLE).

When the rule decides a call, K-Block resolves the eligible people at that moment. Only members with an active K-Block signing identity count, because approving means signing. Two outcomes deny the call instead of creating a request:

Role-wide approvers count every member with that role and an active identity. The templates use only role approvers, and a require_approval default always admits every owner, admin and approver, so in an organization with more than 32 such members those calls are denied with TOO_MANY_APPROVERS until you list fewer roles or explicit users in the rule. A default cannot be narrowed: add a require_approval rule for the calls instead. Observe windows never relax either code.

The approval request stays open for the rule's approval_ttl_seconds, or the organization's default approval lifetime when the rule sets none, but never longer than the agent's delegation remains valid. See How approvals work.

Argument conditions

A rule can also decide on the call's arguments: the exact JSON object the agent (or your code, for a decision-only tool) sends, which the signed TASK binds. Add a when list to the rule: every condition in it must hold for the rule to apply.

{
  "schema": "kblock.cloud/policy@1",
  "default": "deny",
  "rules": [
    {
      "id": "non-prod-deploys",
      "actions": ["deploy.run"],
      "when": [{ "path": "/environment", "in": ["dev", "staging"] }],
      "effect": "allow"
    },
    {
      "id": "prod-deploys",
      "actions": ["deploy.run"],
      "when": [{ "path": "/environment", "eq": "production" }],
      "effect": "require_approval",
      "approvers": { "roles": ["owner", "admin"] }
    },
    {
      "id": "stock-adjustments",
      "actions": ["inventory.adjust"],
      "when": [
        { "path": "/lines/*/sku", "for": "all", "starts_with": ["SKU-"] },
        { "path": "/lines/*/qty", "for": "all", "gt": "0", "lte": "500" }
      ],
      "effect": "allow"
    }
  ]
}

Paths and wildcards

path is a JSON Pointer into the arguments object (RFC 6901): /environment, /customer/country, /lines/0/qty. A member name containing / or ~ is written ~1 and ~0. Array indexes are written in decimal without leading zeros.

A * token selects every element of an array: /lines/*/qty is the qty of each line. A condition whose path has a * needs "for": "all" (every selected element must satisfy it) or "for": "any" (at least one must); a path without * must not have for. Applied to an object instead of an array, * names the member "*", as JSON Pointer says.

Operators

Each condition has exactly one operator family:

There are no regular expressions, no arithmetic between arguments and no code: every condition is decided deterministically from the arguments alone.

Missing or malformed values fail closed

A condition can be true, false or indeterminate: the value it needs is missing, has another type (a number where a string is expected), is not a well-formed decimal, or a * path selects no element. K-Block never guesses:

• an allow rule applies only when every condition is true, so a missing or malformed value can never gain an allow;
• a deny or require_approval rule applies unless one condition is definitely false, so a missing value can never escape a deny or an approval.

In the example, a deploy without environment matches prod-deploys and waits for a person. for: "all" is false when any element is false, else indeterminate when any element is; for: "any" is true when any element is true, else indeterminate when any element is.

What agents and people see

Explanations name the rule and its conditions (path, operator and the policy's own operand), never the call's argument values. At the Rule and thresholds disclosure level, agents see the conditions of the deciding rule; see What agents are told. The action's page shows the arguments as signed in its evidence.

Language revision 3 and simulation

A document with any when list is language revision 3. Like revision 2, it can decide calls only once every Gateway supports it; until then its activation is refused with GATEWAYS_NOT_UPGRADED (see the language gate).

Policy tests and simulations evaluate argument conditions on the example's arguments (a JSON object of at most 8 KiB). A recorded call whose arguments are no longer available, because its operational data passed the retention period and it has no signed arguments, cannot be replayed against conditions: it is reported as not evaluable (ARGUMENTS_REQUIRED) instead of guessed. Decision maps and impact previews skip tools whose decision depends on arguments, and say so.

Descriptions and guards

Two optional rule members never change how a call is evaluated:

• description is a human reason, shown in explanations to people and, at the disclosure levels Rule and approval details (rule, the default) and Rule and thresholds (conditions), to agents in refusals. Never put secrets in it. See What agents are told.
• guard: true marks a require_approval rule that an observe window must never relax, even a window started to relax approvals. Without an observe window it has no effect.

Using either member makes the document language revision 2. Such a document can decide calls only once K-Block has enabled these newer policy features on every Gateway; until then, its activation is refused with GATEWAYS_NOT_UPGRADED. In that case, try again later, or contact K-Block support with the error code and the time of your attempt. See the language gate. Documents without them are revision 1 and are never held back.

Validation errors

Validation lists every problem with a JSON Pointer path. The most common codes:

Templates and their parameters

A template is a ready-made document for a common kind of agent. Creating a policy from a template produces a draft built from your parameter values, plus saved example calls; it never activates anything (see Create a policy).

Parameter rules:

• A currency parameter is an ISO 4217 code of three uppercase letters.
• An amount parameter is a non-negative decimal string up to 1000000000000000 (10^15). It is normalized, so "100.00" and "100" produce the same document and digest.
• Where a template has two amount limits, the lower must be strictly below the upper (for example the automatic refund limit below the approval limit), else the parameter is refused with PARAMETER_ORDER.
• Unknown parameters are refused; omitted parameters take their defaults.

Every template document has a deny default, uses only role approvers (no user IDs), uses only revision-1 members, and lists the strictest amount rule for an action first. Each template also comes with example calls and their expected outcome, one-line notes per rule, and a delegation hint: the permissions (and, for amount templates, the maximum amount) to grant the agent's delegation, which stays the hard limit whatever the policy says.

Templates assume action names. Before you activate a draft from a template, compare its actions with your tools' actions and edit the document.

Next steps