Architecture

How Ownfold composes portable cryptography, backend coordination, browser E2EE, storage, and framework adapters across different trust models.

Ownfold has portable layers that can be assembled into two supported security profiles.

Browser E2EE profile

Browser                                      Application infrastructure
┌────────────────────────────┐               ┌─────────────────────────────┐
│ Vault client + crypto      │──metadata────▶│ Ownfold coordination routes│
│ Root key + record plaintext│               │ Vault/device/rotation rows  │
│ IndexedDB device material  │──ciphertext──▶│ App-owned private records   │
└────────────────────────────┘               └─────────────────────────────┘

The browser plane creates keys, encrypts and decrypts records, wraps data keys, verifies Recovery Kits, and manages lock state. The server plane authenticates users, validates ownership and revisions, stores encrypted device envelopes, and coordinates pairing and rotation. It has no application-data decryption API.

Trusted backend encryption profile

API / job / CLI process
┌───────────────────────────────────────────┐
│ @ownfold/crypto                           │
│ Root-key handle + temporary plaintext     │
│ Encrypt/decrypt + authenticated context   │
└───────────────────┬───────────────────────┘
                    │ encrypted envelope
                    ▼
            Application storage

This profile imports @ownfold/core and @ownfold/crypto directly. It requires no browser, frontend framework, HTTP adapter, or Ownfold database adapter. The service intentionally owns the keys, so it provides encryption at rest rather than protection from the application backend.

The backend encryption guide documents key lifetime, Recovery Kit storage, authenticated context, and the changed threat boundary.

Package layers

@ownfold/core defines formats, parsers, errors, state types, and contracts.
@ownfold/crypto implements approved primitives behind a replaceable engine interface.
@ownfold/server owns authenticated coordination and ciphertext-write validation.
@ownfold/browser optionally owns local persistence, workers, recovery, tabs, and browser vault lifecycle.
React, transports, frameworks, authentication resolvers, and databases are optional leaf adapters.

Core and crypto never import a framework, ORM, browser storage API, or authentication provider. Server never imports React or the browser client. Framework handlers converge on one Web Request boundary, so validation and error semantics remain identical.

Record storage is application-owned

In the browser E2EE profile, Ownfold database adapters do not store journal entries or documents. The host creates a table with its normal ownership columns and an encrypted_payload JSON/blob column. The server can observe record count, timestamps, approximate sizes, access timing, device labels, and key versions. It cannot decrypt the payload without compromising the browser runtime or changing served JavaScript.

In trusted backend encryption, the application still owns record storage, but the service can decrypt by design. Authorization and secret-manager controls replace the browser as the key-access boundary.

Network independence

No package contains an Ownfold API origin. All network calls go through the supplied VaultTransport or the host application’s record API. The project remains operational if its maintainers, website, or package registry disappear after dependencies are vendored.