Skip to content

Latest commit

 

History

History
70 lines (49 loc) · 10.3 KB

data-model.md

File metadata and controls

70 lines (49 loc) · 10.3 KB

Data and trust model

The application server stores encrypted identities, per-user public encryption/signing keys, vault metadata ciphertext, memberships, recipient key envelopes, invitations, documents, immutable file versions, ciphertext chunks and metadata-only audit events. Exact field/API definitions are in docs/api-contract.md.

Hosted IdentityContext and explicit Google fallback authenticate default PocketBase users; it does not unlock a vault. Direct signup remains blocked. Verified Workspace JIT admits only ordinary identities. Disable an application identity to revoke sessions; Google suspension alone does not revoke existing application tokens. Operators do not gain decryption keys through application authority.

The client's passphrase-derived key protects its private-key bundle. X25519 recipient encryption and Ed25519 signatures protect distribution of independent vault keys. A versioned AEAD format binds ciphertext to its context. Authenticated encryption does not by itself detect server rollback to a previously valid snapshot; server revision checks address ordinary concurrent changes, not malicious history replay.

Initial public keys are immutable. The client automatically pins public keys on first use, preserves existing pins and rejects changed known keys during sharing, acceptance, file verification and rotation. Independent verification remains available through verify-user --fingerprint and optional --fingerprint on share and accept. First-use pinning trusts the authenticated server’s initial account-to-key mapping: Google verifies the account identity, not the encryption key. A compromised server can substitute a key on first contact; a fresh client without pins has the same exposure. Never resolve a changed-key error by silently replacing the pin. Email recipient lookup is exact and case-insensitive, while invitations, memberships and pins use stable account IDs. Email reassignment cannot transfer an existing grant. Members are owner/editor/reader; only the owner manages grants. New members receive every retained epoch needed for vault history. Invitations convey no ordinary vault access until acceptance. A reader can still copy plaintext or keys; roles constrain application writes, not redistribution.

Revocation immediately removes authorization and freezes publication. An unlocked owner rotates the current vault key and publishes envelopes for exactly the remaining authorized recipients. Rotation must account for outstanding invitations and stale clients. Previously disclosed secrets remain disclosed.

The local host and an unlocked agent are trusted. File contents are untrusted input, never instructions. Session keys are memory-only; Python/runtime copies, privileged processes and host swap can defeat perfect memory erasure. Limit session lifetimes and disable core dumps where supported. Avoid returning plaintext or decrypted names beyond the requested task.

The local memory session starts a fresh interpreter rather than continuing after a Python fork. The foreground client verifies the identity before transferring only that identity, account and request configuration over a private inherited socket. Passphrases and encrypted identity bundles do not cross this startup channel. Both processes disable core dumps; standard streams are detached in the worker. A bounded readiness handshake precedes unlock success. The process uses the current interpreter without resolving virtual-environment symlinks.

A persistent, empty, mode-0600 lifecycle lock serializes unlock, lock and logout per server/account. Session sockets are mode 0600 in an owned mode-0700 directory, and both sides check native peer credentials. Recovery removes only an unchanged, owned socket after connection refusal; timeouts and unsafe paths fail closed. An exiting worker removes only its own socket inode. Abrupt termination may leave a stale socket, but never a key-bearing file.

Original file bytes are encrypted into immutable protected-file chunks. SQL exports ciphertext storage filenames and ciphertext checksums, never materializing large file payloads into filtered snapshots. Server recovery combines a consistent database replica with retained primary S3 objects and verifies ciphertext checksums before serving restored state. Other actual file fields, including avatars, are checked for complete readable responses but have no authoritative stored checksum. Such backups are server-state copies, not client private-key caches. An ordinary data export excludes the identity bundle and uses a separate archive passphrase. There are no recovery keys; preserving backup bytes cannot replace a lost decryption passphrase. An optionally enrolled macOS Keychain credential is a retained copy of that passphrase, so an enrolled Mac may still unlock after the user forgets it.

New file versions include plaintext_sha256 inside their encrypted metadata, covered by the writer's signed manifest. This plaintext checksum is never stored in clear server fields, returned by metadata listings or printed by comparison. It is distinct from public ciphertext checksums used to verify transport and backup integrity. Encrypting it prevents the server from using a plaintext checksum to recognize known files or test guesses about their contents.

An unlocked client can compare an explicit local path with a verified version's encrypted checksum without downloading its file chunks. The result identifies the document/version and exposes only equality and the comparison method. Older versions without this field fall back to verified in-memory content download; immutable versions are not migrated. Invalid present checksum fields fail closed. Normal content reads verify the plaintext checksum when present. A metadata-only equality check trusts the authenticated writer's checksum and does not validate availability or integrity of the stored file chunks; complete backup/restore checks remain necessary.

Document archive state is reversible operational metadata, separate from the signed content revision. Owners and editors archive/unarchive with both content and archive revision checks. Archived documents retain all versions and permissions but reject saves until unarchived. Archive transitions are audited; exports and complete backups retain archived documents.

Optional macOS Keychain unlock

Explicit enrollment validates the entered passphrase against the authenticated account's server bundle before saving it in a non-synchronizing Data Protection Keychain item. The item is scoped to the server origin and immutable account ID. It stores only the passphrase; the encrypted identity bundle remains server-only, and decrypted keys remain in memory. Linux and ordinary terminal unlock do not depend on Keychain.

A signed native helper retrieves the secret with Apple's userPresence access control. Touch ID or a macOS credential may satisfy this requirement; this is not a guarantee that no password prompt will appear. Authentication gates retrieval for a new session, not each file operation. The same-user CLI and agents retain the existing unlocked-session authority. The host, signing identity and installed helper are part of the trusted computing base. Secrets cross private process pipes in memory, never shell arguments, environment variables or files.

unlock --keychain fails on cancellation, unavailable credentials or helper errors without silently falling back to a terminal passphrase. lock, expiry and logout do not delete enrollment. keychain-forget removes the current server/account's saved credential; use lock separately to end any active memory session. Changing the vault passphrase does not update the enrolled credential; enroll again with the new passphrase or forget the stale credential. Keychain removal cannot recall a previously disclosed passphrase. See macOS setup for installation and on-device checks.

Encrypted identity-bundle replacement requires a signature from the immutable existing signing identity, binding the account, expected bundle revision and exact replacement bundle. An application token alone cannot replace the bundle. Successful replacement writes a metadata-only audit event visible only to that account through filtered SQL. Rejected replacement leaves the bundle and audit unchanged.

Vault owners can use vaultcontext archive-vault VAULT_ID and vaultcontext unarchive-vault VAULT_ID. Archiving applies to all members and hides the vault from default vaults; vaults --archived selects archived vaults and vaults --all selects both. Listings include archived. Existing files, history, protected downloads, comparisons and exports remain accessible by ID. Archived vaults reject saves, document archive changes, new invitations and invitation acceptance. Pending invitations remain pending and can be accepted after unarchiving. Revocation and key rotation remain available. Individual document archive states and any rotation freeze remain unchanged. Archiving neither revokes access nor deletes data or reclaims storage. Repeated requests with current revisions are harmless. Complete backups retain vault archive state; encrypted file exports retain their existing v2 format and do not recreate vault lifecycle.

Vault archive state is operational metadata. A separate monotonically increasing vault archive revision protects saves across archive/unarchive cycles; transitions also increment the existing vault revision used for ownership operations. State changes and their audit entries commit or roll back together.

Hosted sessions use the pinned shared identity library. Single-use, sixty-second assertions are bound to the exact VaultContext audience. Server-verified assertion context supplies Workspace sharing eligibility; request bodies and login claims never grant vault membership or decryption. App tokens expire within fifteen minutes and cannot be extended by auth-refresh. Central disable blocks new assertions; independent fallback accounts must also be disabled for complete offboarding.

Every memory-worker operation pins authentication to its unlocked account ID. A renewed or replaced token for another account, or deleted login state, fails before vault requests. Authentication renewal leaves the original monotonic unlock deadline unchanged. App logout stops the worker before removing its app token; shared identity logout revokes central renewal but cannot recall tokens or keys already held locally.