# Gateway Governance

Provon applies two independent controls before or during a model call:

- **Usage limits** decide whether the project API key may consume more requests, tokens, or cost.
- **Guardrails** inspect the request or response and monitor, adjust, or block supported conditions.

Both controls produce structured project evidence: usage-policy events or guardrail trace events.
Neither replaces application authorization or provider-side safety controls.

Provon Cloud managed targets also use an organization credit ledger. Credits pay for managed model
execution; they are not a third project policy layer.

## Usage Limits

Usage limits are attached to the Provon project API key used by the application. They can apply to
all Gateway requests on that key or to a specific model ID.

Supported metrics:

| Metric   | Modes                | Typical use                                         |
| -------- | -------------------- | --------------------------------------------------- |
| Requests | Rate limit           | Bound request throughput                            |
| Tokens   | Rate limit or budget | Bound short-window throughput or total token volume |
| Cost     | Budget               | Bound estimated and actual USD spend                |

Supported windows are minute, hour, day, week, month, quarter, year, custom, and lifetime.

### Configure A Limit

In the Workbench:

1. Open **API keys**.
2. Expand the project key used by the workload.
3. Under **Limits**, select **Add limit**.
4. Choose metric, type, limit, period, and scope.
5. For a model-specific scope, enter the exact request model ID.
6. Save the limit and monitor used, reserved, remaining, and reset values.

Provon reserves estimated usage before routing, then settles successful requests against actual
usage when the provider reports it. Failed requests release their reservation.

### Rejection Contract

When admission would exceed a policy, Gateway returns `429`:

```json
{
  "error": {
    "code": "gateway_budget_exceeded",
    "message": "Gateway budget exceeded",
    "reason": "cost_budget_exceeded",
    "policyId": "policy_123",
    "resetAt": "2026-08-02T00:00:00.000Z"
  }
}
```

Rate-limit rejections use `rate_limit_exceeded`. Responses include:

```text
Retry-After
RateLimit-Limit
RateLimit-Remaining
RateLimit-Reset
```

Do not implement automatic retries for a cost or lifetime budget rejection. Retry only when the
policy has a reset time and the workload can wait.

## Cloud AI Gateway Credits

Provon Cloud managed model targets use the organization's prepaid **Cloud AI Gateway credits**.
This ledger is separate from project API-key usage limits:

- credits pay for managed provider execution;
- API-key limits bound one workload's requests, tokens, or cost;
- BYOK requests use the upstream provider account instead of the Provon Cloud credit balance.

Provon reserves an estimated amount before a managed request and settles against actual model usage
afterward. Insufficient balance returns `402`:

```json
{
  "error": {
    "code": "INSUFFICIENT_GATEWAY_CREDITS",
    "message": "organization does not have enough Cloud AI Gateway credits"
  }
}
```

Add credit under organization **Billing**. Do not retry until the balance changes or the request is
moved intentionally to a BYOK target.

## Guardrail Modes And Actions

Guardrails are configured under **Guardrails** and run in priority order.

Workbench actions:

| Action      | Behavior                                                             |
| ----------- | -------------------------------------------------------------------- |
| **Monitor** | Record the match and allow the exchange                              |
| **Adjust**  | Redact supported sensitive content or lower supported request limits |
| **Block**   | Reject the exchange with `409`                                       |

Start new rules with **Monitor** against representative traffic. Review the captured match evidence
before switching to **Adjust** or **Block**.

## Built-In Guardrails

### Data Protection

| Rule             | Direction        | Purpose                                              |
| ---------------- | ---------------- | ---------------------------------------------------- |
| Personal data    | Input and output | Detect email addresses and payment card numbers      |
| Secrets and keys | Input and output | Detect API keys, access keys, JWTs, and private keys |

These rules support monitoring, redaction through **Adjust**, and blocking. Match evidence stores
categories and hashes rather than the matched secret value.

### Tool Governance

| Rule                  | Purpose                                                        |
| --------------------- | -------------------------------------------------------------- |
| Tool argument policy  | Match risky tool names and argument conditions                 |
| Duplicate tool calls  | Detect the same tool call repeated in a bounded message window |
| Duplicate tool output | Detect repeated consumption of the same tool result            |
| Repeated tool errors  | Detect repeated failures on the same tool path                 |

Tool argument policies support wildcard tool names and optional argument-path predicates. Use them
to enforce explicit application policy, not to infer business authorization from prompt text.

### Context Budget

| Rule                   | Purpose                                                 |
| ---------------------- | ------------------------------------------------------- |
| Conversation footprint | Cap message count, tool calls, and tool-definition size |
| Prompt token budget    | Block requests over an estimated input-token limit      |
| Response token budget  | Monitor, cap, or block requested completion tokens      |

Input token checks are estimates. API-key token policies perform their own admission reservation and
settle against provider-reported usage when available.

## Guardrail Block Contract

An enforced block returns `409`:

```json
{
  "error": {
    "message": "Provon Gateway blocked this exchange because a guardrail was triggered.",
    "type": "provon_gateway_guard",
    "code": "PROVON_GATEWAY_GUARD_TRIGGERED",
    "param": null,
    "retryable": false,
    "details": {
      "pluginId": "provon.guard.secret-leak",
      "action": "block",
      "direction": "input",
      "category": "openai_api_key"
    }
  }
}
```

The response includes:

```text
x-provon-guard-triggered: true
x-provon-guard-plugin-id
x-provon-guard-action
x-provon-request-id
```

Do not retry the same blocked payload. Change the request or the project policy.

## Tool Argument Policies

Each Tool argument policy rule matches:

- a tool-name pattern;
- an optional argument field path;
- an operator;
- an optional comparison value;
- an optional reason and category.

Supported operators include existence, equality, numeric comparison, string containment,
prefix/suffix matching, and allow/deny list membership.

Example intent:

```text
tool pattern: shell_*
field:        command
operator:     contains
value:        rm -rf
action:       Block
```

Keep tool authorization in the application. A Gateway guardrail is an additional policy boundary,
not the source of user permissions.

## Layering Controls

Apply controls in this order:

1. Use application authentication and authorization for user actions.
2. Restrict project API-key capabilities and rotate keys independently.
3. Add API-key usage limits for hard resource boundaries.
4. Add guardrails for request, response, and tool-shape policy.
5. Restrict Provider Keys and model mappings to approved upstream targets.
6. Use Trace Capture to retain the evidence needed to audit decisions.

A request may be admitted by usage policy and still be blocked by a guardrail. A request may pass
both and still fail provider authentication, capability checks, or upstream execution.

## Security Guidance

- Give workloads Provon project keys, never upstream provider keys.
- Use a separate project key per environment or application boundary.
- Avoid raw secrets and unnecessary personal data in prompts and context headers.
- Use **Specific** model mappings when a Provider Key must expose a strict allowlist.
- Treat header overrides and custom upstream URLs as privileged configuration.
- Review Provider Key, guardrail, and API-key changes as production policy changes.
- Apply project telemetry retention to captured prompts, responses, and tool arguments.

## Related Docs

- [Gateway API](./gateway-api.md)
- [Model providers](./model-providers.md)
- [Routing and reliability](./gateway-routing.md)
- [Gateway evidence](./gateway-observability.md)
- [Production guide](./gateway-production.md)
- [Gateway troubleshooting](./gateway-troubleshooting.md)