Reference
Document security and handling
Securing a generated document is not the same problem as securing an endpoint, because the artefact leaves. An API response is read once by a client you control. A document is downloaded, saved, forwarded, printed, attached to an email and kept on somebody's laptop for six years, and every control you had over it stops at the moment it is delivered.
Two things follow. Access control decides who can obtain a copy and has no opinion at all about what happens to the copy, which is why so much of this is about what goes into the file rather than who can fetch it. And a document is a complete, portable, quotable record rather than the slice of data a page shows, so the same mistake costs more.
The single highest-value page, if you read one: a black rectangle over text does not redact it. That one misunderstanding produces public disclosures every year or two, and it keeps happening because the result on screen is completely convincing.
Nothing here states what any law requires of you. Retention periods, erasure obligations and residency rules vary by jurisdiction, by industry and by the kind of document. These pages describe the shape of each problem and the mechanisms a system needs to implement whatever answer your own advisers give.
Who can reach the document
Everything up to the moment of delivery. These are the controls that still work, and the reason to get them right is that they are the last ones you have: once a copy is on somebody's laptop, nothing on this page applies to it any more.
- Serving behind access control
Making sure the person downloading a document is entitled to it, which fails most often because the document lives somewhere the check does not.
- Signed URLs and expiry
Giving out a URL that carries its own authorisation for a limited time, which moves the access check to the moment the link is minted rather than the moment it is used.
- What belongs in a filename
The name the recipient sees, which travels further than the document's contents and is visible in places the contents are not.
- Content disposition and sniffing
The headers that decide whether a file downloads, opens in a viewer, or is interpreted as something else entirely by a browser guessing at its type.
- Access control on stored documents
The authorisation model for documents that persist somewhere after generation, which is a longer-lived and larger surface than the render call itself.
- Tenant isolation
The controls that stop a multi-tenant document system delivering one organisation's document to another, which is the worst failure available to it.
- Sharing by link or attachment
Two delivery models with different security properties, where the convenient one is usually the less controlled one.
- Expiring and revoking access
The difference between a link that stops working and a document that cannot be reached, which people conflate until they need one of them urgently.
- User supplied HTML and URLs
What a renderer can be made to do when the thing it renders is chosen by somebody else, which is a server-side request forgery problem before it is a rendering problem.
- Secrets in templates
The ways a credential ends up inside markup that is sent to a renderer, and why anything in that markup should be assumed to reach the document.
- Document passwords
Password protection on a document, which is genuinely useful for one purpose and routinely presented as something much stronger.
- Watermarking for traceability
Putting a per-recipient mark on a document so a copy found elsewhere can be attributed, which is a deterrent and an investigation aid rather than a control.
- Credential rotation
Replacing the key your pipeline authenticates with, without an outage, which is easy to plan and routinely never practised.
What is inside it
A document is a portable, complete, quotable record, which makes what goes into it a decision rather than an accident. These pages are about the things that end up in a file without anybody choosing to put them there.
- Personal data in an emailed document
What a document discloses once it is attached to a message, which is more than the recipient asked for and travels further than the message.
- Redaction is not a black rectangle
The most consequential misunderstanding in document handling: covering text with a shape hides it visually and leaves it entirely intact in the file.
- Metadata in a PDF
The fields a document format carries alongside its visible content, which are invisible on the page and present in the file.
- What not to print on a document
The values that reach a customer-facing document because they were available, which are usually internal identifiers, judgements and debugging aids.
- Attachments and embedded files
A PDF can contain other files inside it, which is useful for machine-readable payloads and is a way for content to travel without being visible.
- Classifying a generated document
Attaching a sensitivity level to each kind of document, which is what makes every other rule in this cluster applicable rather than aspirational.
How long it lives, and what happens after
Retention, deletion, erasure, legal hold and the record of who received what. The tensions here are real rather than technical: an immutable record and a right to erasure genuinely conflict, and the resolution is a policy rather than a library.
- Retention and deletion
The period a document remains available and the mechanism that removes it afterwards, where the second half is the one that is usually missing.
- Erasure against immutable records
A genuine conflict between a person's right to have their data removed and a business's obligation to retain records, which is resolved by policy rather than by a library.
- Legal hold
The ability to stop deleting a defined set of documents indefinitely, which overrides every retention rule and has to be built before it is needed.
- Audit trails for documents
The record of what happened to a document and who did it, which is asked for after an incident and cannot be reconstructed then.
- When the wrong document is sent
The response to the most common document incident, where the technical options are limited and the decisions are mostly about scope and disclosure.
- Data residency for documents
The question of which jurisdictions a document passes through, which has to be answered from your providers rather than assumed.
- Processors and third party access
The list of external systems that handle document content, which is longer than most teams expect and is asked about specifically in reviews.