Appearance
Packages, quotas and the audit log
Packages
A package is what a workspace or an account has paid for: a name, a price as it is shown, a set of features and eight limits — people, pages, storage, sites, the largest single upload, API requests a day, days of page history, and how many workspaces an owner may start. An owner of the deployment writes them under Packages in /admin, and nothing is redeployed. Nothing is charged here either: payments are a later step that will write the same assignment.
Which package governs a workspace, in order: its own; else its owner's account package (the owner is whoever started it, unless you name somebody under the workspace's Package); else the default package; else none, which is every feature and no limits. So a deployment that defines nothing is unchanged. Give a workspace's package an end date and it is a trial: the day after, the workspace falls back to whatever is under it, with nobody doing anything.
Exceptions, per workspace. Under a workspace's Package you can grant one feature its package lacks or withhold one it has. Under its Limits, a number replaces the package's limit for that dimension and a blank follows the package.
The features are a fixed list: single sign-on, directory sync (SCIM), sign-in rules, API keys, webhooks, published sites, custom roles, the audit log and git sync. A package is a ceiling over a person's role, never a grant: somebody still needs the capability, and the workspace needs the feature. A request the package refuses is answered 402, naming the feature and saying that whoever runs the deployment can change the package.
When a package lapses or shrinks, nothing anybody wrote is deleted and every setting is kept, so renewing brings it back as it was. The editor shows what each feature does when it lapses, beside its checkbox. Two rules decide the hard cases: a downgrade never makes a workspace less safe (sign-in rules already on stay on), and it never locks anybody out (require SSO stops applying when SSO is off). Downloading everything as a zip is never gated.
Archive a package to stop assigning it while everybody on it stays. A package something is on, or the default, cannot be deleted. Every change is in the audit log.
The measured limits. An upload over the largest upload is refused before it is read. API requests a day counts requests made with an API key, per workspace per UTC day, and answers 429 until midnight UTC once used up; people in a browser are never counted. Page history is how many days back a page's versions can be opened and restored. Nothing older is deleted, and the timeline is never limited.
Customers asking for a package. Tick Offered in the app on a package and it is shown to whoever runs a workspace, in its console, and to everybody for their own account, in Settings. Choosing one asks for it; the request appears under Package requests in /admin, where an owner approves it (optionally until a date, for a trial) or declines it with a reason. The person who asked is told either way, through the link webhook (package-decided). Nothing changes until it is approved.
Before a package ends, the workspace's admins and the package's owner — or the person, for an account's own package — get a package-ending notice a week ahead, once per end date (NOTESFLOW_PACKAGE_NOTICE_DAYS changes the week). The workspace console warns too.
Quotas
Limits per workspace — people, pages, stored bytes, sites, and the measured three above — which come from its package, with any number you set for that workspace replacing the package's. With no package anywhere, all of them default to no limit.
NULL is the spelling for "no limit" rather than a very large number: "unlimited" and "a billion" are different promises, and a number eventually gets compared against.
Who sets them
They live on the workspace record, which is control plane, and that is the decision rather than where there happened to be room: a limit is a statement the deployment makes about a workspace, not a fact the workspace owns.
The platform console sets them. The workspace's own console reports them, and has no route that writes one. A ceiling somebody can raise for themselves is not a ceiling.
Where they are enforced
Where the thing is made — page creation, upload, invitation — because a limit discovered afterwards is a limit somebody has already crossed. Three details follow:
- The permission check comes first. Somebody who may not create a page here is told that, not that the workspace is full.
- An upload is answered from its declared length before a byte is read, and then again against what actually arrived. The declared length is the client's claim; the second number is the one that gets stored.
- The member limit stops the invitation, not the arrival. Refusing a redemption would turn a full workspace into a failed sign-in, which is the wrong place to learn about it — and the invitation was authorised when there was room. Break-glass is exempt: an operator's access must not be blocked by the operator's own quota.
A refusal names what was exceeded and who can raise it. "Quota exceeded" sends the reader to their workspace admin, who cannot raise it either — an error that routes somebody to the wrong person has wasted two people's time instead of one's.
How they are counted
Deliberately two ways. Pages and bytes are tenant data, counted on the scoped handle — no exception, no privileged function, the policy does the filtering. Members are control plane, counted by workspace id.
A quota that needed a hole in the tenant boundary to be enforced would not be worth enforcing.
The audit log
Each workspace has its own, readable with the read_audit capability.
Two kinds of entry are the reason it exists, and are written so they are never buried:
- Break-glass — an operator letting themselves in, and why.
- Outward sharing — a grant that leaves the workspace, naming the page and the recipient, and a matching entry when it is withdrawn. Both sides log it: the granting workspace's says what it opened, and the receiving workspace's says what was opened to it, because an admin whose workspace was just handed somebody else's document has no other way to learn that.
Internal sharing is not logged. It happens constantly, and recording it would bury the entries the log exists to make visible.
Break-glass
An operator who genuinely needs to look inside a workspace says why, in a sentence somebody else will read.
The grant is an ordinary membership with an expiry, so the permission rule needs to know nothing about it — a mechanism the rule has to be taught about is one that will drift from it. It expires on its own, it can be ended early, and it is written into that workspace's own log, where its admins see it.
Access a workspace cannot see is not access it agreed to.
Edits that were only reading
Before the fix for this, a page whose live document had been unloaded and later reopened could record an edit to every block on it. The timeline then credited whoever opened the page with rewriting it. The page's history gained a revision for each visit, and the reader started watching the page. Newer versions stop this from happening, but edits recorded before the upgrade are still in the log.
# Postgres
NOTESFLOW_DATABASE_URL=postgres://… pnpm repair:read-edits
# PGlite: stop the server first; two processes on one data directory corrupt it
pnpm repair:read-edits --data apps/server/.notesflow-dataThis lists, per workspace and page, the updates that repeat exactly what the block already said. It changes nothing until you run it again with --apply. Applying sets those updates aside. The timeline, a page's revisions, a block's provenance, and the choice of who hears about a suggestion all stop counting them. Applying also removes any automatic "wrote this" watch that only those updates had started. Watches that somebody chose, or that a comment started, stay.
The log is not edited. Every op stays in it, and replaying a page still reads them all. Repeating a block's own state changes nothing when replayed. An update counts as unchanged only when every field it carries equals that field's previous value. Anything uncertain stays attributed. Running the command twice does nothing the second time.
Suspending and deleting a workspace
The platform console can suspend one: nobody can open it, and the people already in it are disconnected at once. Deleting one is scheduled with a grace period during which it is read-only and can be taken back — see deleting a workspace. Both are an operator's actions, visible as such, and live in platform_role rather than in any role a workspace can grant itself.
Purging
When somebody purges a page or redacts writing, it is gone from every reader. Purging in the platform console decides what else happens to it:
- Erase it from the database — the rows are deleted, and an attachment's bytes with them.
- Keep it out of sight, not erased — every row is moved, as it was, into
purge_vault, a table no route reads. Whoever runs the deployment can still produce it from the database, for a regulator or a court; it goes when the workspace is deleted, and with nothing else.
Unset follows NOTESFLOW_PURGE_MODE (erase or retain), else erase. Each change is in the platform's audit log as platform.purging; each purge and redaction is in the workspace's, as page.purged and page.redacted, with ids and counts and never a title. Backups taken before a purge still hold what it removed until they age out, in either mode.
Trials
Trials in the platform console let a visitor try Notesflow without an account (ADR 0049). Try it without an account on the sign-in page makes them a workspace of their own, held by a cookie in their browser and closed to everybody else — other browsers, every account, and operators, who reach it only by break-glass like any workspace. It is not an account: no address, so nothing is ever sent to it.
- The package is a trial's ceiling, chosen here. The seeded Free (trial) has none of the package features and 200 pages, 50 MB, 10 MB uploads and 30 days of page history; change it under Packages like any other. With no package chosen, nobody can start a trial — a workspace with no package would have every feature.
- A recovery key (
NFTR-…) shown in the trial's Settings brings it back to any browser, and takes it from whichever browser held it before. Nothing a trial shares, invites or publishes: Sign up to share this workspace. - Signing up keeps it. Signed in in the browser that holds the trial, the person is asked once whether to keep it in their account; yes makes it an ordinary workspace with them as its admin, under whatever package governs their workspaces, and counted against their limit.
- Housekeeping. A trial nobody opens for the days set here (30) is scheduled for deletion with its own grace (14), read-only meanwhile, and purged after. Coming back, by its cookie or its key, takes the schedule back. Revoke shuts a trial's identity out and schedules it at once.
- The cap on live trials (10,000) refuses Try it once reached; Try it and recovery are limited per network as well.
Unset follows NOTESFLOW_TRIAL_WORKSPACES (on), else off. Turning trials off stops new ones; existing trials stay reachable, claimable and swept. Trials need sign-in to be required and the web app and the API on one site, or the cookie is a third-party cookie Safari and Firefox drop; the console says so when either is missing.
Default quotas for new workspaces
Beside the creation policy, the platform console sets the quotas a workspace starts with when somebody other than an operator starts it, directly or through an approved request. An operator changes them per workspace afterwards as before; an operator's own workspaces start unlimited.
What else is written down
Besides break-glass and outward sharing, a workspace's log records the administrative acts done to it: members added, removed, re-roled or leaving; invitations, groups, roles and SSO connections made or changed; keys and service identities made, rotated or revoked; webhooks; sites created, published, re-addressed or unpublished; its own settings; a whole-workspace download; a rename or a change of address; and a deletion scheduled or cancelled. Edits to pages are not in it — that is what the op log, the timeline and history are for.
The deployment's own log records what has no workspace to belong to: requests for workspaces and their outcome, operators appointed, the sign-in policy changed, accounts disabled, enabled or their sign-in reset, and workspaces purged.