@safekb/mcp 0.5.0 → 0.7.0

package/README.md

@@ -107,12 +107,14 @@ every tool that keeps a key this way; see [Where secrets are kept](#where-secret
 | `--rotate-key <ref>` | | Replace a seal root's secret with a new generated key; takes `--store`. |
 | `--move-key <ref>` | | Move a seal root's current key to `--store system\|file`. |
 | `--delete-key <ref>` | | Remove a seal root's keys from this machine, after a typed confirmation. |
+| `--export <file>` | | Write what this token reaches to a new passphrase-protected file. Takes `--space`, `--doc`, `--compress`, `--skip-locked`. See [Export and import](#export-and-import). |
+| `--import <file>` | | Create what such a file holds in this token's account, as new things. Takes `--into-space`, `--store`, `--keys`. |
 | | `SAFEKB_SEALED_IDLE_TTL` | Seconds an unlocked seal root may stay idle. Default 900. `unlock_sealed` can set it per root with `idle_ttl_seconds` (60 to 3600). |
 | | `SAFEKB_HOSTED_TIMEOUT` | Seconds a hosted tool call may take. Default 300. |
 | | `SAFEKB_MCP_NO_BROWSER` | Set to anything: never start a browser, only show the authorize link. |
 
-Exactly one mode is given: `--mcp`, `--setup`, `--authorize`, `--configure`, `--sidecar`, or one of the
-key modes. A flag that only modifies a mode (`--sealed-only`, `--keyring`, …) without one is an error;
+Exactly one mode is given: `--mcp`, `--setup`, `--authorize`, `--configure`, `--sidecar`, `--export`,
+`--import`, or one of the key modes. A flag that only modifies a mode (`--sealed-only`, `--keyring`, …) without one is an error;
 it never starts the server by itself. A flag the given mode does not take is an error too, as is a
 mode without the value or the modifier it needs, and any flag given an empty value.
 
@@ -310,6 +312,75 @@ irreversible per credential: the server drops its own encrypted secrets and that
 
 Old database and storage backups keep the server-encrypted copies until they age out.
 
+## Export and import
+
+```sh
+npx -y @safekb/mcp --export all.safekb --compress        # everything this token reaches
+npx -y @safekb/mcp --export work.safekb --space <space id> --doc <document id>
+npx -y @safekb/mcp --import all.safekb                   # into the account of this token
+npx -y @safekb/mcp --import work.safekb --into-space <space id>
+npx -y @safekb/mcp --import all.safekb --keys pc-a.keys --keys pc-b.keys   # keys of locked roots
+```
+
+Both need a terminal: the passphrase of the file is typed there (twice for an export) and is never an
+argument. The file is encrypted with AES-256-GCM under a key derived from the passphrase with Argon2id,
+in parts that cannot be dropped, swapped or cut off unnoticed; `--compress` gzips before encrypting.
+Attachments are streamed, so the file may be large. **The file holds every secret in plaintext under
+that one passphrase**: passwords, TOTP seeds and the content of sealed documents.
+
+What an export holds:
+
+- Spaces, folders, documents (Markdown, rich text and canvas blocks) with their tags, external
+  references, workflow status and due date, and their attachments.
+- Databases with columns, indexes, views, rows, row pages and the rows' files.
+- Credentials with every secret field. Each secret of a server-encrypted credential is one audited
+  reveal on the server.
+- Sealed folders, documents, attachments and credentials of every seal root that opens with a secret
+  this machine keeps or its sidecar holds (`safekb-mcp --sidecar`, then `add <name or id>` for a
+  passphrase root), decrypted on this machine.
+- Every other seal root as the server stores it, still sealed: the machine that makes the backup needs
+  none of their keys. The export names these roots before it writes. Pending deposits in them are left
+  out. `--skip-locked` leaves such roots out entirely instead.
+- Projects, tasks, decisions, and the links between exported things.
+
+What is selected:
+
+- No `--space` and no `--doc`: everything the token reaches.
+- `--space <id>` (repeatable): that space with its documents, credentials, projects and tasks.
+- `--doc <id>` (repeatable): that document, or that folder with everything in it and the credentials
+  filed in it. Its parent is not exported, so on import it is at the top of its space.
+- A link to something outside the selection is left out and counted.
+
+What an import does:
+
+- It creates new things with new ids and changes nothing that exists, so it works for a restore, for
+  another account or server, and twice in a row. References between imported things (links, relations,
+  ids in text, attachments shown in a page, the task of a checklist item) follow the new ids.
+- Every exported space becomes a new space, also where one of that name exists. `--into-space` puts
+  everything into one existing space instead. A token limited to some spaces is given the spaces it
+  creates (this needs a SafeKB server of October 2026 or newer).
+- A seal root the file holds still sealed is opened with its key: from a key export given with
+  `--keys <file>` (repeatable; made with `--export-keys` on any machine that keeps the key; its
+  passphrase is asked and its keys are used for this import only), or from a store of this machine.
+  A key of another account, or one replaced since by a key or passphrase change, does not open it.
+  Without a key everything in that root is left out, and the root is named with the reason; import
+  the file again with its key to restore it (that creates everything else again too).
+- Every seal root becomes a new seal root with a newly generated key, kept in the default key store
+  or the one named by `--store`; a passphrase root therefore becomes a key root. A seal root whose
+  name is taken on this machine gets ` (imported)` appended. **Back the new keys up**
+  (`--export-keys`).
+- A project whose slug is taken gets a numbered one. A task keeps its assignee only in the account
+  the export came from.
+- When a step fails the import stops, says at which record, and leaves what it had created; nothing
+  is rolled back.
+
+A file written by 0.7.0 or newer is not read by 0.6.0; 0.7.0 reads files of 0.6.0.
+
+Not in an export: version history, creation and change times and authors, shares, public links, space
+members, and the account's settings. A vault document (encrypted in the browser to its owner's vault)
+is exported as ciphertext and can only go back into the account it came from, while its id is free
+there. Merged tasks are left out.
+
 ## What sealing does not protect
 
 - Whatever a tool returns enters the local conversation transcript and is sent to the model provider.
@@ -317,6 +388,8 @@ Old database and storage backups keep the server-encrypted copies until they age
 - A program running as your user can read a key file, ask the system keyring or the sidecar for a
   secret, and read the memory of this client while a root is unlocked.
 - A session that has unlocked a root can be tricked by content it reads into copying it elsewhere.
+- An export file: it holds the sealed content of every root that opened under the passphrase of the
+  file, not under its seal roots.
 - A compromised local machine, or a malicious server serving stale data.
 - Metadata: existence, sizes, timestamps, tree position.