Appearance
Workspaces
One deployment can hold many workspaces. Each has its own pages, history, search, attachments and admins — and the boundary between them is the database's, not a WHERE clause anybody has to remember writing.
One account, one sign-in, a role per workspace, and a switcher when you belong to more than one.
Addressing a workspace
Set NOTESFLOW_BASE_HOST to the deployment's own host and acme.<host> names a workspace. Workspaces are also reachable by path, at /w/<slug>.
How the boundary is enforced
Every table is one of two things, and which one is a decision made when the table is added:
- Control plane — accounts, sessions, workspaces, memberships, invitations. Facts about the deployment.
- Tenant data — pages, blocks, ops, comments, files, groups, roles, views. Facts about one workspace.
Tenant tables carry row-level security policies. Inside a request, the handle used for queries is scoped to one workspace, so a query written there is confined by construction rather than by the author remembering.
The naming follows the failure modes, which are not symmetric: a control-plane query that runs scoped is harmless, because those tables carry no policy. A tenant query that runs unscoped is a cross-workspace leak — and it is invisible until the day there are two workspaces.
Two checks stand behind it:
bash
pnpm check:tenancy # no control-plane query may read a tenant table
pnpm check:postgres # the store suite against a real server, including a role that owns nothingAnd one configuration completes it: running the store as a role that owns nothing, without which a superuser connection is exempt from the policies it is relying on.
What the boundary does not cover
Stated because a security boundary you misunderstand is worse than one you know the edges of. It confines queries. It does not confine the process: anything that legitimately spans workspaces — sessions, the account list, the operator console — runs on the unscoped handle by design, and is covered by the tenancy check instead. The full accounting is in ADR 0003.
Two functions that cross it, narrowly
An operator has legitimate questions the boundary would otherwise refuse, so two functions answer them, each cut as narrowly as its question:
workspace_sizes()returns cardinality only — a workspace has 412 pages, and nothing about any of them.shared_with(account)returns the pages explicitly granted to one account in workspaces it does not belong to, which is exactly what that account may already open. It cannot browse, because a grant is what puts a row in it. The account id comes from the session and never from a request: it is the authorisation.
Starting a workspace
Who may make one is the deployment's policy, set by an operator in the platform console under Who may create workspaces:
| Policy | Somebody who is not an operator… |
|---|---|
| Only operators | may not make one. The default. |
| Anyone may ask; an owner approves | may ask for one; an owner approves or declines it. |
| Anyone may create one | may make one directly. |
An operator can make one account an exception either way — "operators only, except the person who runs research" — and can cap how many workspaces one person may start. An operator always creates directly.
The switcher offers New workspace… or Ask for a new workspace… only to somebody the server would let do it. A request holds its address while it waits, and the person who asked is told the outcome in the sidebar — "ready, open it" or the reason it was declined.
Whoever started a workspace is its admin, including one an operator approved. Approving grants the operator nothing inside it. A workspace somebody other than an operator starts begins with the deployment's default quotas.
The operator can also give a workspace of their own to everybody who signs in belonging nowhere — see authentication.
Its own settings
A workspace's icon, who may join it without an invitation and as what, and the time zone of its daily digest are its admin's, in Settings. Its name and address are the operator's.
Two are about removing writing (ADR 0048; see purging and redacting):
- Keep everything written: turn purging off (a legal hold). Nothing can be purged from the trash, and nobody can redact somebody else's writing. People can still redact their own — the password pasted by mistake — but what they remove is kept out of sight in the database, not erased. Each change is in the audit log as
workspace.settings. - Tell people when their writing is purged or redacted — on by default. Each person can also turn the two kinds off for themselves in Settings.
So are its short references (PROJ- and where a PROJ-123 goes), set in the console and kept as the workspace's own data, for anyone who holds manage_workspace. An address must be http or https and say <num> where the number goes; at most 50 are kept, and each change is in the audit log as workspace.autolinks. Anyone who can read a page in the workspace can read the list, because their editor draws it; someone who can read nothing there gets an empty one. See Links.
Renaming and moving
An operator can rename a workspace freely; a name is a label. Changing its address is different, because a slug is in every bookmark, every link pasted into chat and every mirror's configuration. So the old address:
- keeps working — it leads to the same workspace, over HTTP and over the live socket;
- is reserved for that workspace for good, and never given to another. A bookmark to your team's pages must never open a stranger's;
- can be taken back by the same workspace, which simply undoes the move.
The default workspace keeps its address, because the bare path means it. Every rename or move is written into the workspace's own audit log, so its admins know why links changed.
Deleting a workspace
Deleting is scheduled, then carried out. An owner types the workspace's address to confirm and chooses a grace period, 1 to 365 days (30 by default). From that moment:
- the workspace is read-only. Every page opens without a caret and a notice says when it will be deleted. Reading still works, so
pnpm export:gitcan take a copy during the window; - an owner can take it back, and nothing has been lost;
- the schedule and any cancellation are written into the workspace's own log, where its admins can see it while there is still time to object.
When the period is over, the server removes everything in the workspace — pages, history, comments, attachments, memberships, keys, webhooks — and records the deletion in the deployment's log. Every address the workspace ever had stays reserved. The default workspace cannot be deleted.
To close a workspace completely during the window, suspend it as well.
The platform console
/admin is for an operator (platform_role of owner or support): which workspaces exist, how big they are, their quotas, suspension, renaming and deletion, workspace requests, the creation and sign-in policies, accounts and operators. support can read all of it and change nothing. It offers no way to open a page.
That absence is the feature. A console that quietly listed page titles would break the promise the boundary makes without anybody choosing to break it. When an operator genuinely needs to look inside, there is break-glass — which says why, expires on its own, and is written into that workspace's own log where its admins see it.
Operators and accounts
An owner appoints other owners and support staff in the console. The last owner cannot step down — a deployment nobody may operate cannot be repaired from inside — and an address named in NOTESFLOW_ADMIN_EMAILS cannot be demoted there, since the environment would promote it again.
An owner can also disable an account: its sessions end, its keys stop working, every sign-in road refuses it, and its open pages close. Its memberships, grants and everything it wrote are kept, so enabling it again restores all of it. An owner must be stepped down before being disabled, and nobody can disable themselves. An owner can also reset an account's sign-in.
Sharing across the boundary
A page can be shared with somebody in another workspace, or with a whole other workspace. It is modelled as visiting: they open it at the owning workspace's address and hold no membership there, so no new concept and no exception in the policy is needed. See sharing a page.