Files & storage

Your matter files are some of the most sensitive things Opbox holds: a passport scan, a signed engagement letter, a draft government form with a client’s PII on it. This page explains, in plain terms, where those files physically live, what protects them, and what is changing. No code is required to follow it.

The one idea to hold on to: a file’s protections are properties of the single place it lives. The bytes are locked, fenced, graded, and logged together, as one thing. You do not get a file that is encrypted over here but unprotected over there. That is the whole point of the design, and everything below is a consequence of it.

How a file is stored today (live)

When you attach a file to a matter, Opbox does not drop it into a folder on a disk somewhere and hope for the best. It records the file as a row in the database - one record that carries every protection around the bytes - and seals the bytes before they ever leave the kernel. On a default box the sealed bytes then sit in the in-stack MinIO object store as ciphertext; on the bytea backend they sit in the database row itself. Either way the protections and the bytes are bound together as one locked thing.

Concretely, that single record holds:

• The bytes, encrypted before they are written. The file is sealed with AES-256-GCM (a strong, standard lock) the moment it arrives — before it is ever written down. There is no “plaintext” copy of the file sitting anywhere in the store; only the locked version exists at rest. The database schema even forbids a plaintext column, so there is no back door to leave one by accident.
• A seal bound to this exact matter and workspace. The lock is not generic. It is mathematically tied to which workspace and which file record this is. Think of it as a safe whose key only turns in this one safe, in this one office. If someone stole the locked blob and tried to drop it into another matter, another workspace, or another firm’s box, the lock would refuse to open — the bytes would fail to authenticate. A stolen file cannot be moved and read elsewhere. That binding is what the engineers call AAD: the file’s identity is baked into the lock itself.
• A workspace fence (row-level security). The database itself refuses to return a file row to anyone outside its workspace. This is enforced at the data layer, not just in application code, so even a query that “forgot” to filter by workspace still sees nothing across the fence. One firm’s files are structurally unreachable from another’s.
• A sensitivity grade. Every file carries a grade — NORMAL, SENSITIVE, CONFIDENTIAL, or RESTRICTED. The grade controls who is allowed to read the actual bytes: a more sensitive file requires a more senior role to open. (Anyone permitted can still see the file’s name and details; the grade gates the contents.) A passport or a filled government form, which carries real PII, sits high on this ladder by default.
• A record of who created it. Whether a human or an agent put the file there is recorded on the row, so the provenance is legible without detective work.
• One audit entry. Storing the file writes exactly one tamper-evident entry to the append-only audit log. Nothing happens to a file silently.

So when we say “the file’s protections are properties of the one place it lives,” this is what we mean: the encryption, the workspace fence, the grade, the ownership, and the audit are all attributes of that single row. You can never end up with the bytes in one place and the protections in another, because there is only one place.

The same store holds files that Opbox generates — a compiled exhibit bundle, or a filled-in PDF form — under the exact same rules. A generated document is just another row, sealed and fenced and graded like any upload, and a derived file even records which source files it came from.

The blob-size guard (just shipped)

Putting raw file bytes inside the database is clean and safe for the kinds of files most matters hold. But it would be a mistake to let anything in — a careless 4 GB upload could bloat the database and degrade everyone’s experience.

So file.put (the verb that stores a file) now rejects an over-large upload, fail-closed. There is a fixed 50 MiB cap on a single inline upload. Over that, the upload is refused outright with a clear error — it is never silently truncated, never partially accepted, never quietly swallowed. “Fail-closed” means: when in doubt, refuse, rather than let something through that we cannot safely handle.

This guard is small, but it is the deliberate trigger for the bigger change below. The cap is the line in the sand that says “files past this size need a different home.” That different home is the pluggable storage backend — and the rules for it have already been decided.

(For now the cap is a fixed value baked into the build. A future adjustable cap - set per deployment - is a separate question deliberately left open, because loosening a safety limit is itself a sensitive act.)

Where files will live next: the storage decision (planned)

The most important question about your documents is: as the firm grows, where do the actual bytes get to live — and do we lose any protection by moving them? A firm may eventually want its files in SharePoint, or in Box, or simply on a large disk rather than inside the database. That is a reasonable thing to want.

Opbox did not answer this casually. The question was worked through deliberately and the design settled firmly before any of it was built. The product now builds to that design. In plain terms, the decision - call it the “C-strict” decision - draws a sharp line between what is allowed to change and what is not.

What is not allowed to change

The kernel stays the single system of record and the single authority. Identity (who you are), isolation (the workspace fence), encryption (the lock), and audit (the log) all stay with the kernel — the trusted core of Opbox — and may never be handed off to anything less trusted. Not to a filesystem, not to per-user computer accounts, not to a third party’s own controls. Those four guarantees are non-negotiable, whatever the firm chooses for storage.

What is allowed to change

Only two things are severable — allowed to vary:

1. The byte-storage medium. The bytes may live somewhere other than the database. The in-stack MinIO object store is the realized default today; external backends like SharePoint or Box come later.
2. The folder presentation. Humans may see and arrange files as folders, rather than as database rows.

Everything else stays exactly where it is. Here is what that means in practice.

A pluggable storage backend may hold the bytes — but only as ciphertext it cannot read. When files move out to a backend (disk, SharePoint, Box), they leave the kernel already sealed. The backend receives the locked envelope and nothing else: no key, no plaintext, no way to read the contents. It is a dumb, opaque byte-vault. This is enforced at the type level in the code itself — the seam is built so that plaintext physically cannot be handed to a backend. So even if a firm puts files in SharePoint and SharePoint is misconfigured, or breached, or subpoenaed at the wrong moment, what is exposed is encrypted bytes the backend was never able to read.

The backend never decides who can see a file. The kernel always does. This is the heart of the design. The storage backend is not asked “may this person open this file?” — it is only ever asked “hand me these bytes.” Every access decision — the workspace fence, the role check, the sensitivity grade — happens in the kernel, before the backend is ever touched. SharePoint’s own sharing settings, or a disk’s file permissions, are disabled or treated as irrelevant; they are never read as authority. There is exactly one gate, and it is the kernel’s.

Humans get a per-matter folder view, but every change flows back through a kernel verb. People think in folders, so Opbox will show files as a folder you can browse, rename, and rearrange per matter — it will feel like real folders on a real drive. But the folder is a view, a presentation over the real records. Every action you take in it — attach a file, move it, delete it — is translated back into a proper kernel operation that enforces permissions and writes an audit entry. You cannot reach “behind” the folder and edit the authoritative bytes out of band. There is no sneaking around the audit trail by dragging a file in a window; the window is the front of a governed operation.

Deletion is never a silent destroy. When you delete a file, Opbox does not quietly erase it. It records a tombstone — a marker that says “this was removed” — and routes the removal for correction, while honoring the rule that a record that was properly entered may be corrected, but never silently erased. This matters enormously for regulated work, where “we deleted it and have no trace” is the opposite of what you want. Even if a firm later points storage at SharePoint, a SharePoint delete that the kernel cannot intercept is treated with suspicion: a backend that cannot guarantee this behavior is only allowed to hold routable copies, never the authoritative record.

Per-user operating-system accounts are not the security boundary. It is tempting to think “give each lawyer their own login on the machine and let the operating system protect the files.” Opbox explicitly rejects that as the security model. OS accounts are, at most, a convenience layer; the real protection is the database fence and the encryption, tied to your Opbox identity — not to which user is logged into a computer. Your files are not safe because of who is logged in; they are safe because of how they are locked and fenced.

Why this shape was chosen for regulated work

The reasoning is simple once the pieces are in place. Firms doing regulated work want two things that usually pull against each other:

• The convenience of real folders and the option of mainstream storage like SharePoint or Box.
• The guarantees of encryption, strict isolation between matters and firms, and a complete, tamper-evident audit trail.

The naive way to get the first is to give up the second — dump files into folders or a third-party drive and inherit its security, its sharing rules, its (lack of) audit. The C-strict decision refuses that trade. It says: you may have the folders, and you may have SharePoint or Box, without surrendering encryption, isolation, or audit — because those four things never leave the kernel in the first place. The storage medium and the folder view are allowed to change precisely because they were carefully separated from the parts that protect you. A file moving to SharePoint changes where the locked bytes sit; it changes nothing about who can open them or whether the move is logged.

That separation is also why this is a legitimate seam and not a risky split: no protection has to be re-implemented or re-derived out on the backend side. If it ever did - if any guarantee had to be rebuilt on the SharePoint side to make this work - the answer would be no, and the design would be reconsidered before shipping.

What you can do

Today, and in the near plan:

• Upload or attach a file to a matter (live). It is sealed, fenced, graded, owned, and logged the instant it lands.
• Generate a document against a matter (live). A compiled exhibit bundle or a filled PDF form lands as a protected file on the matter, under the same rules as an upload — recording the source files it came from.
• See a per-matter folder (planned). A browsable, rearrangeable folder view of a matter’s files, where every change is a governed, audited operation underneath.
• Point storage at SharePoint or Box (planned, deferred). Move the bytes to mainstream storage as opaque ciphertext, while the kernel keeps every access decision and the full audit trail. Local disk comes first and must be proven against the conditions above before any external backend is enabled.

In one line

The bytes can move and the folders can change — but identity, isolation, encryption, and audit never leave the kernel. That is what lets Opbox offer real folders and mainstream storage to a regulated firm without giving up the protections that make it safe to use.

Related reading

• The kernel - the trusted core that stays the system of record.
• Agents & MCP - why even an agent that touches your files gains no special powers.