Security

Onprest is designed on the assumption that any component, including the public gateway, may be compromised. This page explains what each part protects and what remains your responsibility. How it works lists what the gateway and the agent each hold.

If the gateway is compromised

The gateway holds the agent public key, bcrypt hashes of API keys, and the public contract of each capability. If the gateway is compromised, an attacker can see the public contract and send calls to the agent, but only to capabilities that exist in capability.yaml, with input that passes validation, within the capability’s policy, and receiving only its declared output. They learn no SQL or credentials. The agent’s per-capability rate limits also hold without the gateway’s cooperation.

The gateway alone checks which API key made a call. A compromised gateway can therefore call any capability as any caller; keep each capability’s reach narrow enough that this is acceptable.

API keys

Each key lists the capabilities it may call; an empty list allows nothing and "*" must be set explicitly to allow everything. The same check applies to REST, MCP, OpenAPI, and file downloads. The gateway stores only bcrypt hashes and logs only key names. See API Keys.

What the agent may touch

The agent’s configuration and its operating-system permissions decide what a capability can reach. Keep both narrow:

• Databases: use a read-only user for read capabilities, and grant mutations only the operations and tables they need. policy.readonly checks the statement type but cannot see what a function does; database permissions are the real boundary. See Databases.
• Folders: point folder sources at dedicated directories, use access: read unless the capability saves files, and give the agent’s user only those permissions.
• HTTP APIs: callers can only fill in the arguments you bind; they cannot change the URL, method, or credentials. Restrict each source’s methods and, where possible, its addresses with allowed_cidrs. See HTTP APIs.
• Code: with the sandbox off (the default), a module has the agent user’s full file, network, and environment access. Turn the sandbox on and grant only what the module needs. Review the code and how it uses its input, especially input that selects a path or destination. Output selection controls the API response, not what code sends over a network grant. See Code (Wasm).

Side effects

Mutations, file saves, HTTP calls, and code can change things that are not automatically undone. Onprest never retries them. When a call fails after it started, the error’s outcome tells you whether the change was rolled back or is unknown; see Uncertain outcomes. Annotations and effects: none describe a capability; they do not make a retry safe.

Returned files

A download link works only with the API key that made the call, only while that key may still call the capability, only until it expires, and only while the same agent connection is up. Knowing the URL is not enough. The gateway streams files without storing them, and builds links only from the configured ONPREST_PUBLIC_BASE_URL. See Files.

Agent connection

The agent connects outbound, so the on-prem network needs no inbound port. Each connection is authenticated with an Ed25519 signature over a one-time challenge from the gateway, which cannot be replayed. Use wss:// for any gateway that is not on the same host as the agent. The gateway accepts one agent connection at a time and rejects a second one while the first is alive.

If the agent private key may have leaked, rotate it.

Errors and logs

Responses and gateway logs contain only fixed error codes and safe messages. Database errors, upstream responses, paths, credentials, and submitted values stay in the agent’s local log, with secrets removed. Treat that log as sensitive and keep it on the on-prem side.