Security & permissions

This page explains, in plain terms, how Opbox decides every act of seeing and doing. It is written for the person who has to sign off on putting regulated client data into the system: a partner, a compliance lead, a founder. There is almost no code here. The aim is for you to finish this page understanding why a leak is hard, not just being told that it is.

The one idea to hold onto: a bank vault with many locks

Picture a bank vault. To open any single deposit box, several different locks all have to turn at once: the building has to let you in the door, your own key has to fit, the box has to be one your key is cut for, and the most valuable boxes need a second person and a second factor. No single key opens everything. If any one lock fails to turn, the box stays shut.

Opbox works the same way. Every request to read or change something passes through a stack of independent checks. Each check can only ever narrow what you are allowed to do, never widen it. For data to leak, every lock would have to fail at the same time, and several of them are enforced by different systems (the database, the application, the cryptography) so that a single bug or a single stolen credential is not enough.

The rest of this page walks the locks one at a time, then ties them back together.

Lock 1: Workspace isolation — the outer fence

One client lives in one workspace. A workspace is the wall around a single client’s matters, documents, files, bills, and parties. Nothing inside one workspace can be seen from another.

What makes this trustworthy is where the wall is built. It is not built only in the application code (the part that could, in principle, contain a forgotten check). It is built into the database itself, using a Postgres feature called row-level security.

Here is what that means for you. When a request comes in, the system tells the database, in effect, “everything you do for the next moment is on behalf of workspace A — and nothing else.” From that point on, the database physically refuses to return any row that belongs to a different workspace.

What this means for you: even a direct query against the raw database — the kind of thing a careless script, a future bug, or a curious operator might run — cannot reach across the fence. The database hands back nothing for any other client. The application’s own checks are the fast path; the database wall is the backstop, and it holds even when the application is wrong.

And it fails closed. If a request somehow arrives without a workspace stamped on it, the database treats that as “belongs to no workspace,” which matches no rows at all. The accident is no data, never all data.

Organisation vs workspace — two different memberships

There is a layer above the workspace: an organisation can hold several workspaces (for example, a firm that runs more than one practice area, each walled off). Membership in the organisation is a separate thing from membership in a workspace. An organisation role of OVERSEER lets a person review and read the audit trail across the organisation’s workspaces; it does not dissolve the walls, it is a deliberate, recorded oversight power. The point to take away: being in the organisation and being able to work inside a particular client’s workspace are two distinct grants, not one.

Lock 2: Tiers — who you are

Inside a workspace, not everyone is the same. Each person (or automated agent) holds one of four tiers, arranged as a ladder from least to most powerful:

Every action in the system carries a required tier. The rule is simple: your tier must be at least the tier the action requires, or the action is refused. A client on the portal cannot reach a staff-only action; a junior cannot reach an owner-only one.

The two ends are worth dwelling on. EXTERNAL is the client’s tier — it is the narrowest, a strictly fenced view of their own affairs. OWNER is the widest, reserved for the principal and for the small set of trusted automation that runs the firm’s own setup.

Money and destruction need a second factor

The actions that move money — recording a payment, issuing a refund, raising a charge — and the actions that tear things down are the ones you most want protected. These require a senior tier and a fresh second-factor (MFA) step-up: even an already-signed-in senior user must re-prove themselves with their authenticator within a short, fixed window before the system will let the money move. A stale session is not enough. If an owner uses an emergency override, that override is itself written into the permanent audit log, so it can never be quiet.

What this means for you: a stolen everyday session does not get an attacker to the money. The bank-teller-grade actions are behind a separate, time-limited factor, and every exception is on the record.

Lock 3: Autonomy — how much the AI may do on its own

Opbox is agent-first: an AI assistant can act on your behalf. That power is deliberately metered by an autonomy level, a dial from 0 to 3:

• Level 0 — read only. Look, summarise, answer. Change nothing.
• Level 1 — ordinary changes. Draft, update, the normal everyday writes.
• Level 2 — sensitive actions. The more consequential, carefully-scoped acts.
• Level 3 — owner-equivalent. The full set, including the money and destructive class.

Two things set the level the agent actually gets, and this is the key safety idea:

1. The agent’s own standing level — the ceiling its operator gave it.
2. The credential’s ceiling — a limit carried on the specific key it is using for this task.

The effective level is the lower of the two — the “lowest lock wins” rule. Hand an agent a key that is capped at level 1, and even a level-3 agent can only do level-1 work while holding that key. You can therefore dial down what an agent may do for a single task simply by giving it a more restricted key, without changing the agent itself. Power can only ever shrink as it passes down the chain, never grow.

Lock 4: Token scopes — a key cut for one door

When something acts in the system, it presents a token — a bearer credential, like a key card. A token is not an all-areas pass. It can be cut narrowly:

• Limited to specific actions — a token may be allowed to perform only a named list of actions and nothing else.
• Bound to a specific resource — a token can be tied to one particular thing. The clearest example is a client’s portal link: the token behind that link is bound to that client’s portal. It cannot be pointed at a different portal to go fishing for someone else’s matter.

That resource binding is the anti-enumeration fence. A common attack is to take a working link and simply change the identifier in it — ...portal/1001 becomes ...portal/1002 — to walk through other people’s records. Because the token is cut for one specific portal, swapping the identifier does not work: the key does not fit the other door.

What this means for you: the magic link you email a client is genuinely theirs. It opens one box and only that box, even in the hands of someone who tries to tamper with it.

Lock 5: File sensitivity grades

Not every file deserves the same handling. Each file carries a sensitivity grade:

• NORMAL
• SENSITIVE
• CONFIDENTIAL
• RESTRICTED

The higher the grade, the higher the tier required to read the actual bytes of the file. By default, ordinary staff can open NORMAL files; SENSITIVE files require a senior (ADMIN) tier; and the two highest grades, CONFIDENTIAL and RESTRICTED, require OWNER. A firm can author its own grade-to-tier policy on top of these defaults.

A subtle but important detail: someone may be allowed to know a file exists — to see its name in a list — without being allowed to open it. The metadata and the contents are gated separately, so the most sensitive material does not even reveal its contents to a member of staff who is below its grade.

Lock 6: Encryption at rest

The locks above govern who may ask. Encryption governs what is worth stealing if someone gets past the asking entirely — say, by walking off with a backup disk.

• Files and personal data are encrypted with AES-256-GCM, a standard, strong, authenticated cipher. On disk, the material is unreadable ciphertext.
• Each encrypted blob is bound to its own row — to the specific record and workspace it belongs to. This binding is not cosmetic. If an attacker lifted an encrypted blob and tried to paste it into a different record or a different workspace to read it there, the decryption simply fails. The lock and the box are cut for each other; a stolen blob in the wrong place is gibberish.
• Tokens and passwords are never stored in a form anyone can read back. A token is kept only as a one-way hash; the real value is shown once when it is created and is unrecoverable thereafter. Passwords are stored with a strong one-way password hash (Argon2id). A copy of the database yields no usable keys, tokens, or passwords.

What this means for you: a stolen backup is not a breach of your clients’ contents. The data is encrypted, the keys are not in the backup, and the encrypted pieces cannot even be reshuffled into a readable form.

Lock 7: The audit log — tamper-evident by design

Every action that changes the system writes exactly one record to an append-only audit log: who, what, when, in which workspace. One action, one line, no gaps and no double-counting.

What makes the log trustworthy is that it is hash-chained. Each new record carries a cryptographic fingerprint that is computed from the record before it, so the entries are linked into a chain, like a wax seal that spans the gap between every two pages. The records are also append-only at the database level: the system’s own working account is not permitted to edit or delete a past entry at all.

If someone with deep access were to reach underneath the application and alter or remove a past row directly in the database, the fingerprints stop matching at that point — the chain breaks, and the break is detectable. There is a built-in check (an ADMIN-only verification action) that re-walks the chain and reports whether it is intact.

What this means for you: you do not have to take “nothing was tampered with” on trust. You can have the chain verified, and silent after-the-fact editing of the history is detectable rather than invisible.

The principle underneath all of it: fail closed

The thread running through every lock above is the same: when the system is unsure, it denies.

• An action the system does not recognise is refused, not guessed at.
• A request with no clear identity is refused, not run as a default user.
• A connection with no workspace stamped on it sees nothing, not everything.
• A decryption that does not perfectly check out returns an error, not a “best effort” plaintext.

Opbox never silently succeeds and never quietly widens access. The default answer to any ambiguity is “no,” and a human has to take a positive step to turn that into a “yes.” This is the opposite of the failure mode that causes most real-world leaks, where a forgotten check defaults to open.

Tying the locks together

Now put the vault back together. For a client’s confidential document to be read, all of these must line up at once:

1. The request is inside the right workspace (the database wall) — Lock 1.
2. The caller’s tier is high enough for the action — Lock 2.
3. If an AI is acting, its autonomy (the lower of agent and key) permits it — Lock 3.
4. The token is allowed this action and is cut for this resource — Lock 4.
5. The caller’s tier clears the file’s sensitivity grade to read the bytes — Lock 5.
6. The stored bytes decrypt in their own row and workspace — Lock 6.

Miss any one and the request stops. And whatever happens, one audit line is written (Lock 7), so the attempt is on the record either way.

What this means for a regulated practice

If you are responsible for client confidentiality, professional-conduct rules, or data-protection obligations, here is the short version to carry into a sign-off:

• Client separation is enforced by the database, not just trusted to the code. Cross-client leakage is structurally hard, and it stays hard even when the application has a bug.
• Least privilege is the default. Clients see only their own matter; staff get the everyday surface; money and destruction sit at the top with a second factor. AI assistants are metered by an autonomy dial that can only shrink as keys are handed down.
• The most sensitive material is gated all the way down to the file bytes, and is unreadable at rest even to someone holding the disk.
• The record is tamper-evident. You can demonstrate, not merely assert, that the audit history has not been quietly rewritten.
• The system fails closed. Ambiguity resolves to denial, which is the safe direction for a regulated practice.

For how the firm’s people and AI agents are structured on top of these locks, see agents. For the engine that enforces every one of these rules, see the kernel.