How rules work in Suprbox

Suprbox sits between the documents you own and the AI agents you let read them. Every read goes through a rules engine before any bytes leave the vault. This post explains what the engine actually does, what each kind of rule is for, and how the same pipeline applies to direct document reads and to Suprbox Vault answers.

What a rule is

A rule is a row in the database with five things that matter at evaluation time.

A vault scope, which restricts the rule to one vault. A null vault means the rule applies across every vault the owner has.

A condition, expressed as a field, an operator, and a value. The most common condition is "document sensitivity is one of Restricted, Confidential". Conditions are evaluated against the document being read, against the operation being performed, or against time.

An action, which is the verb the rule wants to apply. The five actions today are deny, require approval, throttle, session lease, and redact. A sixth one, scope clamp, is a shorthand for "limit the response capability to metadata only" and behaves like a degraded form of allow.

A severity, which the dashboard surfaces but the engine does not act on.

A config blob, which carries action-specific settings: how many requests per hour for a throttle, how many seconds for a session lease, which entity types to redact, whether an approval bypass lasts a fixed time or forever.

What happens on every request

When an agent calls one of the read endpoints, the same five-step process runs.

Step one: identify the request. The agent key is verified against the database. The vault is checked for ownership by the same user the key belongs to. The scope on the key (read, write, delete) is checked against the operation. The vault binding on the key is checked against the vault id in the URL. Any failure here returns before any rule even loads.

Step two: load matching rules. A single SQL query pulls every active rule that applies to the (user, vault) pair. Rules with a null vault id apply to every vault. Rules pinned to a different vault are excluded.

Step three: evaluate each rule against the request. Each rule's condition is checked. The condition can reference the document's sensitivity classification, its tags, the operation being requested, the count of recent reads in the same vault, and the wall-clock time. Rules whose condition does not match the request are dropped.

Step four: merge the matching rules into a single decision. The merge step is where Suprbox decides what actually happens, because a request can match more than one rule. The merge always favors the most restrictive outcome and the most restrictive capability. A deny rule wins over an approval rule. An approval rule wins over a throttle. A redaction rule contributes its entity types to the response without changing the outcome.

Step five: act on the decision. If the outcome is deny, the response is a 403 with policy headers explaining which rules contributed. If require approval, an approval row is created in the database and the response is a 202 with the approval id. If throttle, a 429. If the outcome is allow, the response goes out with whatever shaping the merge produced: redactions applied to the body, capability clamps applied to which response shape is allowed, watermarks inserted, raw bytes blocked.

Every one of these branches writes an audit log entry before responding. The log records the key, the document, the vault, the operation, and which rules contributed to the decision.

The five actions in detail

Deny. The simplest action. Match the condition, deny the request. Useful for hard restrictions ("no agent may ever read the salary file") and for staged rollouts where you want to block one vault entirely before turning on writes.

Require approval. A human has to click yes before the read goes through. The first request creates an approval row in the pending state and the agent receives a 202 with the approval id. The agent can poll the approval status or wait for a webhook. Once approved, that same approval can grant a bypass on subsequent requests from the same key for the same document and operation, either for a configurable number of seconds or forever. The bypass is keyed on the document id, not on vault membership. Removing a document from a vault and re-adding it does not revoke an existing approval, because the document id has not changed.

Throttle. Counts recent reads on the vault and refuses anything past the cap per hour. Throttle differs from a session lease in that it operates at the vault level and across keys, while a session lease is per-session.

Session lease. Forces the agent to open a session for the vault and operate within a time window. Without a valid session id on the request, a leased vault returns 401 lease_expired. The agent has to call the session endpoint, get a session id, then attach it to subsequent requests. The lease can also be capped on the rule itself so a session cannot outlive the rule's intended window.

Redact. Runs PII detectors on the response body and masks any types listed in the rule's config. The detectors are the same ones that classify documents at ingest. If a rule says to redact social-security numbers and the body contains a string that matches the social-security detector, the response body has that span replaced with masked characters before it leaves the server.

Capabilities the merge can clamp

The merged decision exposes a capability object that the response layer reads to shape the body. Five capabilities matter today.

The read capability is a level: metadata, excerpt, or content. A rule that clamps the read to metadata returns just the document card with no body, even if the agent asked for the full text.

The maxPages capability caps how many pages an excerpt can return. The agent can ask for ten, but if a rule says three, three is what comes back.

The noDownload capability blocks the raw-bytes endpoint while still allowing extracted text. Useful when you want an agent to be able to summarize a file but not download the original.

The watermark capability injects an agent-identifying watermark into the response body. Combined with audit, this gives you a forensic trail.

The leaseSeconds and rateLimitPerHour capabilities are reported in policy headers so the agent knows what the limits are without trial and error.

How rules apply to Suprbox Vault

Suprbox Vault is the natural-language question-answering pipeline. When an agent calls it, the same rules engine runs at two layers.

The first layer runs before retrieval starts, with no document id. Vault-level rules fire here: deny, approval, throttle, session lease. If the outcome at this layer is not allow, the request never reaches retrieval. The agent sees the same response shape it would see on a direct read.

The second layer runs after retrieval but before synthesis. For every document that the retrieval pipeline surfaced as a candidate, the engine re-evaluates with that document id in hand. Per-document rules fire here: sensitivity-based denies, approval requirements, metadata clamps. Any document whose decision is not allow has its chunks dropped from the candidate set before they reach the language model. The agent never sees content from a document it could not have read directly.

The synthesized answer then passes through the same content-shaping step as a direct read. If a redaction rule fires on any of the contributing documents, the answer text is run through the detectors and the same masking applies. The policy headers on the response report the union of all rules that contributed across all cited documents.

This design avoids the shadow-path problem common to AI features that bolt on after a permission system is built. The retrieval pipeline does not have its own authorization. It uses the existing rules engine, by calling it twice with different inputs.

How merges decide ties

When two rules of the same action match the same request, ties are broken deterministically.

For deny and approval, the rule with the lowest id wins for the purposes of which rule id appears first in the policy headers. The outcome is the same either way.

For redact, both rules contribute their entity-type lists. The union is what gets masked.

For throttle, both rules' rate caps are evaluated. The lower cap wins. The policy headers report which rule actually drove the throttle.

For session leases, both rules' durations are evaluated. The shorter lease wins. Lease enforcement on the response runs against the shortest one.

For metadata clamps, any clamp wins. If any matching rule says metadata, the response is metadata regardless of what other matching rules said.

Audit and the activity log

Every evaluated request produces an audit log entry. The entry records the agent key, the vault, the document if one was named, the operation, the outcome, the contributing rule ids, and a one-line label that surfaces in the dashboard activity feed.

For Suprbox Vault answers, an entry is written for every cited document. This means a single question that pulls from three sources writes three entries, each tagged with the document that contributed. If the answer cited nothing, a single entry is written for the question itself.

The audit log is the record of truth for "what did this agent see, and why." It is also the input to a future feature that will let you replay a request: feed an audit entry back through the engine and see whether the outcome would change under your current rule set.

A worked example

Consider a vault called Acme Deal Room. Two rules are attached.

The first is an approval rule with condition "document sensitivity is Confidential" and action "require approval, bypass forever". The second is a redaction rule with condition "document sensitivity is Restricted" and action "redact: SSN, credit-card".

An agent key bound to this vault calls the endpoint that reads the full text of a Confidential PDF. The merge step sees one matching rule, the approval rule. The outcome is require approval. The response is 202 with an approval id. The audit log records the request with outcome pending.

A human approves in the dashboard. The agent retries. The merge step sees the approval rule match again, but the bypass query finds a previously-approved row for the same key and document, so the outcome promotes to allow. The body returns with no redaction. Audit logs the allow with rule id of the approval, plus a synthetic id marking the bypass.

Now the agent asks Suprbox Vault: "what is the social-security number of the registered agent on the term sheet?" The first layer evaluates with no document id. No vault-level rules deny. Retrieval runs. The reranker surfaces three chunks, two from the Confidential PDF and one from a Restricted memo. The second layer re-evaluates each cited document. The Confidential PDF's approval bypass is still active, so its chunks survive. The Restricted memo's redaction rule fires, so its chunks survive but the entity types SSN and credit-card are queued for masking. The answer is synthesized from all three chunks. The detectors run on the answer text. Any SSN that the model included literally is masked. The response goes out with policy headers listing both rule ids and the redacted entity types. Audit writes three entries, one per cited document.

Where the engine does not run

A small list of read paths intentionally bypass the engine, all of them owner-facing.

The dashboard's own document viewer reads documents through the owner's logged-in session, not through an agent key. The owner can already see everything they uploaded.

The chat surface inside the dashboard for Suprbox Vault runs against an owner-only endpoint that calls the retrieval and synthesis pipeline without the rule layer. The owner is asking questions of their own data, and rules exist to mediate agent access, not the owner's own access.

Backfill and re-index endpoints run as the owner and modify the index, not the documents. They are not subject to rules because they cannot return content to an external caller in the first place.

Every other read path runs through the engine.

Practical guidance

A few patterns we have seen work well.

Start with one rule per vault: approval required on Confidential, deny on Restricted, redact on the PII types you care about across the org. Iterate from there.

Use the audit log as the source of truth when debating whether a rule is too strict or too loose. Look at outcomes over a week and adjust based on real activity, not based on what you imagined the agent would do.

Treat the approval bypass-forever flag with care. It is keyed on the document id, not on vault membership, so a document that moves between vaults keeps its bypass. If you want approvals scoped to the current vault membership, set a finite bypass duration and re-approve when the document is added to a new vault.

Throttle and session lease compose well together. A 60-per-hour cap on a vault with a 10-minute lease lets you give an agent a working window for a known task while keeping a circuit breaker on runaway behavior.

Summary

The rules engine in Suprbox is one piece of code that runs on every agent read. It supports five actions, merges deterministically when multiple rules match, and reports its decision in policy headers and the audit log. The same engine runs for direct document reads and for Suprbox Vault answers, with the latter calling it once at the vault level and again per cited document. Nothing an agent sees through any read path has bypassed the engine that you, the vault owner, configured.