Skip to content

Encrypted spaces

Covered Not covered
The adversary has A copy of the database (dump, volume, WAL, a backup archive), the files volume, the container logs and writable layers, or the whole server taken away powered off, including its swap device (swap is enforced). A running, unlocked server: root on the host, a debugger in a process, a memory snapshot of a live VM, or a hibernated host or suspended VM whose memory image was written to disk while unlocked. Such an attacker can read RAM, where the unlocked key and plaintext live. This is accepted by founder answer 1.
Guarantee Without an unlock password or the recovery code, no workspace content can be read from what is on disk. Ciphertext moved between rows, columns, tables or workspaces fails to decrypt. Tampering by someone who can write to the database: a field rolled back to an older ciphertext of the same row and column is not detected. Theft only reads data; tampering is outside the founder’s threat.
Visible The metadata listed below: ids, structure, people, times, task status, owner and due date, and value lengths. No digest of content is stored in the clear. —
Former holders Removing or demoting an owner or admin rotates the key (founder direction 2026-10-23). Once the rotation has finished, that person’s unlock password, together with any copy of the data taken after it finished, opens nothing. Rotation closes only the later-copies part. A copy the person already holds from before (an old backup or dump) still opens with their old password: old ciphertext and old wraps in it cannot be changed. During the rotation, a copy can still hold old-key values. A raw image of the disk can hold old-key ciphertext in freed blocks after the rotation (limits).
Weak passwords The password rule The weakest unlock password protects the whole workspace: each holder’s key is an independent target for an offline guess.

Account data (names, e-mail addresses, sessions, passwords managed by Better Auth) is not workspace content and is unchanged. Live audio and video are not stored (live media).

  • Sealed workspace. A workspace with workspaces.encrypted = true. “Encrypted workspace” in the UI and “sealed” in code mean the same thing.
  • DEK. A workspace data key: 32 random bytes with a key version (1, 2, …). A new version is made at creation and at every rotation. A DEK never reaches PostgreSQL or a disk unwrapped.
  • Live versions. The key versions that may still have ciphertext: just the current one, except during a rotation.
  • Holder. An owner or admin with an unlock password, or the recovery code. Each holder has an X25519 key pair. Its private key is encrypted under a key derived from the password or code, and every live DEK is sealed to its public key.
  • Keyring. A new process that holds one random boot key in RAM only (see unlock lifecycle).
  • Unlock rows. The live DEKs sealed under the boot key, stored in workspace_unlocks, one row per version. While current rows exist for every live version, the workspace is unlocked.
  • Seal / open. To encrypt or decrypt one value. Envelope is the stored ciphertext format.

This is stated plainly for the review and for the operations guide. Someone with the disk can see:

  • the workspace’s name, that it is encrypted, its members and their roles, invitations, who has an unlock password, and when and by whom it was unlocked or locked;
  • how many projects, conversations, messages, tasks, docs, versions, maps, thoughts, links and files exist, with their ids, authors, times, sizes and value lengths;
  • the structure: which message is in which conversation and task, reply order, attachment counts, DM participants, task dependencies and links between objects;
  • tasks: number, status, owner, waiting-for person and due date; decisions’ status; doc contributors;
  • maps: thought positions, sizes, shapes and link endpoints (not their text or labels);
  • which thought a message cites (message_references, #469: a kind and a target id, never the cited title or text, which are opened per reader through the seal); and for a file the numbers read from its bytes at upload, its page count (PDF), data-row count (CSV, TSV) and duration (audio) (project_files.page_count, row_count, duration_ms). They are counts like the file’s size, never its content;
  • that an activity of a kind happened (“title changed”, “due changed”), but not the values;
  • notifications: who did what, of which kind, for whom, in which workspace;
  • the client-chosen keys described above.

Nothing listed is text that a person wrote, a name of a thing, or file bytes.

Fail closed everywhere. Nothing falls back to plaintext.

Surface While locked
Any route that reads or writes a sealed column of that workspace 423 WORKSPACE_LOCKED { code, message: "Garden club is waiting to be unlocked.", details: { workspaceId } }. No partial body.
Workspace list and read, members, roles, invitations, People, leave, the encryption status, unlock Work (metadata). encryption.state = 'locked'.
Cross-workspace lists (Home, Inbox, ⌘K, search, the morning summary) Omit the workspace’s items and return it in lockedWorkspaces.
The event stream Delivers id-only events as today. Fetching the object answers 423.
Live Wiki and maps No room opens (WebSocket refusal workspace_locked). Open rooms close on lock. Unsaved typing stays in the browser’s visit copy (#651) and is offered again after unlock.
Files Upload and download answer 423.
Notification generation (worker) An event of a locked sealed workspace is recorded in sealed_job_waits (notifications.generate, { eventId }) and the cursor moves on, so other workspaces never wait.
draft.summarize.v1 The handler records a wait and completes the job.
Push and e-mail sends Go out. Their text is content-free and never needs the key.
idempotency.cleanup.v1, space-ai.sweep.v1 Run. They read no sealed column.
AI jobs Never exist (F-029).
After unlock workspace-encryption.resume.v1 replays that workspace’s waits in creation order and deletes each once handled. Notifications are unique per (user_id, event_id), so a replay never duplicates.

The API test enumerates every registered route (Fastify onRoute), resolves its parameters to objects of a locked sealed workspace, and expects either 423 or membership in LOCKED_ALLOWED_ROUTES (packages/contracts/src/encryption.ts), the metadata routes above, each with a reason. A new route must be classified.

Everything except AI works as in any workspace: conversations, DMs, tasks and task discussions, decisions, goals, drafts, maps, the live Wiki, files, search, live sessions and export.

Today’s search runs entirely in PostgreSQL: SQL triggers write plaintext title and body into search_documents, and tsv/keys are generated from them (search). PostgreSQL cannot index ciphertext. A blind index of keyed tokens in the same GIN index was considered and rejected: its deterministic tokens reveal term frequency and co-occurrence to anyone with the dump, and the one-character prefix keys are nearly as guessable as letters. The choice is an encrypted index at rest, decrypted into RAM:

  • At rest. search_documents.sealed boolean. For a sealed workspace the existing triggers branch on workspace_sealed(NEW.workspace_id) and write a placeholder row: kind, audience_key, project, object, version, status, author and time, with title = '' and body = ''. The generated tsv and keys are empty when sealed. Each trigger also appends (workspace_id, doc_key) to search_changes (seq bigserial) on insert, update and delete. The content stays only in the source tables, sealed. Person rows (account names) keep the SQL path.
  • In RAM. Each API process keeps a SealedSearchIndex per unlocked workspace (packages/db/src/sealed-search.ts, used by the server’s search adapter and by the chooser), partitioned by audience_key. It is built on the first search after unlock. It reads the placeholder rows and each kind’s content through a sealedContent loader added to SEARCH_SOURCES (packages/core/src/search/sources.ts), which opens the source columns and composes title and body as the triggers do today (a task’s body is #number, outcome and blocker). Before every search the process applies the search_changes it has not seen (one indexed query), so a committed edit is searchable at once on every replica. A change is read by the transaction that wrote it, not by its seq: a bigserial is assigned at insert, so a lower number can commit after a higher one was read (S2b, migration 0127 adds search_changes.xid). The index remembers the first transaction id it has not applied and reads the changes of the transactions below the snapshot’s xmin, which have all finished, so no change is skipped. Changes older than 24 hours are pruned by the hourly search-changes.cleanup.v1 job; an index idle for 23 hours is rebuilt instead of caught up. The index is never written to disk. It is dropped on lock (ProcessKeys.onForget, which sealFor also calls when any process finds the workspace locked, so a lock on another replica drops it at the next search) and when the process drops its keys.
  • Query. It accepts the same grammar and the same refusals (QUERY_NEEDS_WORD, QUERY_UNSUPPORTED, checked before either source), simple-style lowercasing without stemming, a prefix match on the last word, title similarity, and websearch quotes (adjacent words), or and -word. Plain words match any of the words (F-042, #1293, founder decision 2026-11-12), as in a plain space: the last word also as a prefix, a title with a typo in a word of four letters or more (per word), and a document ranks by the words it holds, a word weighing its idf among the documents of the audience’s own partition (rarer weighs more) and a title word more than a body word; there are no stems and no accent folding in the in-RAM index. Quotes, or and -word stay exact (every word). The title match is the operator the SQL path uses (title %> query, word_similarity at pg_trgm.word_similarity_threshold, 0.6; the earlier text said 0.3, which is the threshold of the other operator). It is the best share of the query’s trigrams in a continuous extent of the title’s trigrams, found through a trigram posting list so only titles that share enough trigrams are compared. A task reverted at creation (#238) is not findable, as in SQL.
  • Access before ranking. The visible audience keys come from policySearchAccess on every request, as today. The in-RAM lookup reads only the partitions of those keys, so hidden rows never become candidates. The EXPLAIN (BUFFERS) saturation property applies to the SQL part. For the in-RAM part the test asserts that the work counter (postings read) does not change with hidden matches.
  • Merge. Plain and sealed results are merged by (score, at, id), where id is the placeholder row’s search_documents.id, so the one sealed cursor (already the position of the last visible result) serves both sources: each applies it, returns its best limit + 1 rows, and the use case merges them. The in-RAM score approximates ts_rank (title weight 1.0, body 0.4) plus half the title similarity, so ordering between the two sources is approximate (the sets of results are the same). Highlighting marks the title whole and a long body as a window around the first match (ts_headline’s shape).
  • Bound. The index is bounded by its estimated heap, not by the text: each distinct term of a document costs a map entry, a string and an array, so the heap measured 16 to 112 times the text on the test corpora (many short titles are the worst case). docHeapCost and the per-posting and per-term costs in sealed-search.ts come from measurements after a full GC, rounded up, and tests/app/sealed-search-heap.test.ts fails when the estimate falls below the measured heap or exceeds 2.5 times it. Two bounds: FLUX_SEALED_SEARCH_MAX_BYTES per workspace (default 256 MiB estimated heap) and FLUX_SEALED_SEARCH_PROCESS_MAX_BYTES across every workspace of the API process. The process default is a quarter of the container’s memory limit (cgroup memory.max, which is FLUX_API_MEMORY, 1536m by default), at most 512 MiB and at least 64 MiB, and 512 MiB when there is no limit; the workspace default is 256 MiB or the process bound if that is smaller. An out-of-memory kill drops every key the process holds and locks all its encrypted workspaces, which is why the total is bounded and not only each workspace. A build or catch-up that grows past either stops at once and the workspace answers with sealedUnavailable: [workspaceId] (S3 draws “Search isn’t available in Garden club: it is too large to search in memory”); a chooser search there finds nothing and says searchUnavailable: true. A workspace over its own bound is retried after 10 minutes; one that only lacked room in the process after 1 minute. Before a build, indexes nobody searched for 5 minutes (FLUX_SEALED_SEARCH_IDLE_MS) are evicted (oldest first) to make room; an evicted workspace rebuilds at its next search. Stale postings of replaced documents count until their partition is rebuilt (once they pass 64 KiB and outweigh the live ones). A build yields to the event loop between chunks of 500 documents. A row that does not decrypt (tampering, a restored backup of another key) fails the search with a generic error, and that failure is remembered for 15 seconds so a single bad row does not cost a decryption pass of the workspace per request; a Lock or an unlock clears it.
  • Freshness and replicas. A change is searchable once every transaction that started before it has finished: the catch-up reads the transactions below the snapshot’s xmin, so one long open write transaction in the database delays what newer commits changed (nothing is lost; it is found at the next search after that transaction ends). Another API replica learns of a Lock the first time it handles a request or frame for that workspace (every operation checks the unlock rows, and sealFor drops the keys, the index and the rooms there); until then it keeps the plaintext index in its memory, as it keeps the cached keys (S1).
  • Files are found by name only (C-63, #1382; #1424 B). The text inside the files people send (PDF, DOCX, Markdown, plain text, CSV/TSV) is searched in plain spaces only. The choice was a sealed index or none, and it is none for the text: a file of an encrypted space gets no extraction job (the triggers of migrations 0072 and 0088 skip workspace_sealed workspaces), and the worker never opens its object. Its name is searchable like any sealed title (migration 0088): the file’s row is a placeholder (sealed, empty title and body, written by search_put), and the in-memory index of the unlocked space opens project_files.name for it (contentOf, kind file); the name is never in a visible column. A sealed index would need the extracted text stored sealed beside the sealed object and held in the API’s memory, where the bound counts estimated heap at 16 to 112 times the text; one PDF of 200,000 characters would use as much of the 256 MiB as thousands of messages. A file is also reached through the message it is attached to, which this index holds.
  • The chooser. A chooser search with text (a task or decision of one project) uses the same index for its case-insensitive title filter. It replaces the S2a-2a scan of the newest 2000 objects and its searchLimited marker, and its test switch.
  • Test support. The explain route of a test deployment adds sealed: { postings, terms, documents } (what the index read), the workspaces with an index in the process with the estimated heap of each, and the number of full builds, so the tests prove that matches a reader cannot see change neither the answer nor the postings read, that the bounds hold, and that a bad row does not rebuild per search.

Rooms run in the API as today (apps/server/src/editing). Every persisted update, ledger, head, archive, snapshot hash, receipt and map journal change is sealed by the repositories (packages/db/src/repositories/doc-live.ts, live-editing.ts, live-map.ts, S2b) inside the same transaction, which reads the unlock rows FOR SHARE: doc_live_heads and doc_live_archives (body, codec state, hash), doc_live_updates (the update bytes, the ledger, the fingerprint), doc_live_snapshots (hash), live_editing_intents (receipt, fingerprint; the map’s native results too) and map_live_journal (change, fingerprint). A catch-up rebuilds a room from the sealed snapshot and log; the decoded rooms of a process are a cache and are cleared when it drops keys. The database size limits of the journal and the codec state (8 MiB) see the envelope, which is about a third larger than the value, and the undo preparation measures a sealed journal opened (journalCharge) because the SQL walk cannot see into an envelope. Presence (cursors, selections, slots) stays visible in its 5 to 30 second lease and carries no text.

Locking closes the rooms. Every live connection records its workspace when it is admitted. When a process drops a workspace’s keys (a lock anywhere, a keyring restart, unsafe swap) its gate closes that workspace’s live connections with close code 4423 and clears the decoded rooms; a new upgrade or live route while locked answers 423. Another replica’s connections close at the next frame or change it handles, because every operation checks the unlock rows. The ordinary routes (save, undo, native map commands) seal as the rest of the repositories do. The “hide empty maps” test compares the opened default title in the application for an encrypted workspace (the maps without a thought are opened and the empty ones excluded before the page and the total). The two-API arrangement (live-editing-two-api) works because each API gets the DEK through the keyring. The synchronous_commit = off transient writes carry no sealed values except presence, which stays visible.

Upload and download use the file format above. Export bundles decrypt in the API while streaming. The size and digest checks run on plaintext.

In a sealed workspace the generator (packages/core/src/notifications/generate.ts) opens the message, task or decision only in RAM, to decide the reason (a mention or question in the body, an assignment). It then writes a content-free row: title is “who and why”, body = '', and url holds ids. The Inbox, push (packages/core/src/push/delivery.ts) and e-mail (notifications/email.ts) therefore never carry content.

Reason Title in a sealed workspace
mention “Ada mentioned you in Garden club”
question “Ada asked you in Garden club”
reply “Ada replied in Garden club”
dm “Ada sent you a message in Garden club”
assigned “Ada assigned you a task in Garden club”
review “Ada asked for your review in Garden club”
invitation “Ada invited you to a call in Garden club”
security “Ben now has an unlock password for Garden club”
security “Garden club’s encryption keys were changed outside Flux. It stays locked.”

The workspace name is visible metadata, and the project name is not used. Opening the item rechecks access and, while locked, shows the locked state.

  • API export (GET /api/v1/projects/:id/export) works while unlocked and streams the plaintext bundle to the person who asked (with project.manage). That is a deliberate copy leaving Flux. The API never writes it to disk.
  • ./flux export writes the bundle into exports/ on the server, which would put plaintext on disk. For a sealed workspace it refuses: “Garden club is encrypted. Export it from the app.” The command exits non-zero.
  • ./flux backup copies the database and the files volume as they are, so sealed content stays sealed, together with the wraps and flux.env. That file holds FLUX_KEYRING_TOKEN, which opens nothing without the running keyring.
  • ./flux restore truncates workspace_unlocks, so a restored sealed workspace is locked. A backup taken during a rotation restores with its progress row, and the rotation continues after the first unlock. It opens with any owner’s or admin’s unlock password as it was when the backup was taken, or the recovery code valid then. The backup guide says so. A backup without its passwords and code cannot be read by anyone.
  • At creation the policy row is blocked (trigger above) and stays so. PUT /api/v1/projects/:id/ai-policy answers 409 WORKSPACE_ENCRYPTED_AI_OFF before any other check that could pass. The database trigger refuses allowed as a backstop. Every F-029 enforcement point then applies unchanged: no agent, assistant, MCP client, run, schedule, reaction, comparison or event audience for an agent.
  • Workspace.ai gains fixed: 'encrypted' | null. While it is 'encrypted', the client shows no switch.
  • The People panel’s AI row (WorkspacePeople.tsx, the section AI in Garden club) keeps its place and shows, to everyone including members: “Off · Garden club is encrypted, so AI can never be turned on here.” There is no button.
  • <AiSurface> already renders nothing while blocked, so the human-only interface comes for free.

Superseded by C-24 to C-27 (#874, #848). The window is now the New space window, from every New space entry point: an Encrypted switch (off by default, “Can’t be turned off later”), no AI row, Your unlock password and Repeat (with Suggest six random words), and Download recovery code, which Create waits for; the browser makes the code. People and keys are managed from the space’s settings (People and encryption) and, while it is locked, from its locked panel. The text below is the earlier design of the Details panel and stays for its reasoning.

Today the only workspace creation in the interface is the first space in project setup (project/newProject.ts, project/ProjectSetup.tsx). S3 adds New space as the last row of Home → Details → People (app/Details.tsx, PeopleEntries). It opens a small form in the Details panel (the Details sheet on a phone):

  • Name (as today).
  • A checkbox row, Encrypt this space, with the line: “Everything inside is encrypted on the server. Only people work here: no agents, no assistant, no AI. This can’t be changed later.”
  • When checked, Unlock password appears in place below it, already filled with a generated six-word passphrase that is shown in full, with a quiet Other words that draws new ones and Use my own, which empties the field and adds Repeat password. The hint reads: “Each owner and admin has their own. It’s needed after every server restart. Every owner’s and admin’s password protects the whole space, and the weakest one counts. Your own needs at least 20 characters.” Then one line: “If every unlock password and the recovery code are lost, everything in this space is gone for good. Nobody can recover it, not even whoever runs this server.” The six words are offered to a password manager (a password field with autocomplete="new-password" and the account e-mail as its username) and the form says: “Write these six words down or save them in your password manager. You type them after every server restart.” (UI audit RC-2.) Then a quiet link, What encryption protects, which opens the threat model in plain words. It explains that it protects a copy of the data or a server taken away switched off, and not a running server, a hibernated host or a VM memory snapshot.
  • The button reads Create space, or Create encrypted space when the box is checked.

The next step, in the same panel, is Your recovery code. The code is shown in monospace groups with the text “This code unlocks Garden club if every password is lost. It’s shown only now. Print it or write it down and keep it somewhere safe.” A Print button sits above a checkbox “I’ve kept the recovery code”, and Done is enabled only after it is checked. There is no Copy button: a copied code can stay in clipboard history and sync between devices. A person who selects the text and copies it themselves takes that choice. Nothing about the code is stored in the browser. The code is two lines of four groups in reading order (“20C6-E0PC-3VP2-GMT2” / “42B5-GDE4-CQNF-6STJ”) on every width, so it cannot be read by columns (RC-3), with the line “Keep this code apart from your unlock password.” The step cannot be skipped by closing it (RC-1). While the box is unchecked, Esc, ×, Back or leaving the page asks in place: “Close without keeping the recovery code? You can make a new one in People.” with Keep it open and Close anyway. Closing anyway records, in this browser only and with the space’s id alone, that the code was not kept, and People → Encryption then says to owners “Nobody confirmed keeping Garden club’s recovery code. Make a new one.” until a new code is kept. The same applies to a new code made in People. If the answer to the create call was lost, a retry with the same creationId returns the space without the code. The panel then says “The recovery code was shown once and can’t be shown again. Make a new one in People.” and offers New recovery code.

Project setup’s first space keeps its form and is never encrypted. The new space appears in the project picker and in Create like any other space. After Done the person lands in the new space.

  • E2EE or client-side keys (#615, set aside).
  • Encrypting an existing workspace, or turning encryption off. Encryption is chosen only at creation. Moving content into a new encrypted space is a later import feature.
  • Rotation on a schedule or on request without a removal (the mechanism allows it later), hardware security modules, a highly available keyring, and a keyring across hosts (single host only until TLS is added).
  • GitHub bindings and ./flux export for encrypted spaces.
  • Protecting a running server’s memory beyond the measures listed.