Encrypted opaque storage: a general primitive for private off-chain account data

[BrianSeong99]

Motivation

Guardian already coordinates per-account state and authenticates the account's cosigners. What it doesn't offer is a place to durably store arbitrary private data that has no on-chain representation and can't be rebuilt from chain — and that the operator must not be able to read.

Many integrations need this. A wallet needs to persist contacts, trusted dApps, settings, and portfolio history. A dApp or bridge integration may need to stash per-account preferences, session metadata, or app-specific state. Today each of these has to stand up its own backend, even though Guardian is already the per-account, authenticated service they talk to.

Rather than solve this once per integration, add a general storage primitive to Guardian: encrypted, opaque, per-account. Wallet metadata is the first concrete consumer, not the scope.

Proposal

A small opaque, namespaced blob store scoped per account. Clients store named, versioned blobs; Guardian only ever sees ciphertext. The client encrypts before PUT and decrypts after GET with a key it derives and holds locally — Guardian never receives it and never interprets the bytes.

This is the same architectural move as #266: after that change Guardian treats proposals as opaque blobs with no server-side parsing. Storage is opaque by design — Guardian never indexes, validates, or type-checks contents. It's a dumb, encrypted, per-account key-value store. (Related: #255 META - Privacy.)

Example use case — Bread Wallet private metadata. The wallet writes namespaces like contacts, trusted_apps, settings, portfolio_history, encrypted under a key derived from the user's recovery phrase, so a new device restores and decrypts them during recovery. Guardian sees only opaque blobs.

Proposed API

Reuses the existing auth headers (x-pubkey / x-signature / x-timestamp), validated against the account's authorized cosigner list — no new auth.

GET    /storage            -> [{ key, version }]       # cheap sync check
GET    /storage/:key       -> { version, value }       # value = opaque ciphertext
PUT    /storage/:key       -> body { value }, header If-Match: <version>
                             # 201 on write, 409 on version mismatch (CAS)
DELETE /storage/:key       -> tombstone

Data model

One additive table, opaque to the server (mirrors states / deltas):

CREATE TABLE account_storage (
    account_id  VARCHAR(64) NOT NULL,
    key         VARCHAR(64) NOT NULL,   -- caller-defined namespace
    version     BIGINT      NOT NULL,   -- monotonic per (account_id, key)
    value       BYTEA       NOT NULL,   -- opaque bytes; never read server-side
    updated_at  TIMESTAMPTZ NOT NULL,
    PRIMARY KEY (account_id, key)
);

• Conflicts: optimistic concurrency via If-Match: <version> — consistent with the nonce "higher wins" rule already used for deltas.
• Encryption is the client's responsibility and out of scope for the server; Guardian stores whatever bytes it's handed. Documenting only that the server must remain content-agnostic.

What this needs from Guardian

1. The account_storage table + the endpoints above, kept fully opaque (no parsing/validation of contents). Small extension to the existing storage backend.
2. SDK client methods to get / put / list / delete entries (analogous to the client-API work already discussed for delta application).

Deliberately low-lift: no policy engine, no server-side crypto — opaque storage plus CRUD.

Open questions

1. Per-account quota / value-size cap, and whether storage shares the delta rate-limit / body-size budgets?
2. On switch_guardian, is copying entries to the new Guardian sufficient, or should the SDK orchestrate migration?
3. Latest-only, or keep a short version history for multi-device conflict forensics?
4. Naming: is account_storage / /storage the right primitive name, or something more specific (e.g. /kv)?

[haseebrabbani]

TL;DR: Mostly sounds good. A few details that need to be nailed down before implementing are how this client-side encryption sits on top of the at-rest storage encryption we already have server-side, and the concurrency contract (the shared per-account replay counter will collide with multi-device sync, and the schema as drawn can't represent its own tombstone). Per-account quotas and hashing the plaintext key names are also probably required.

1. Encryption model

We already encrypt sensitive columns at rest via the StorageDecorator (AES-256-GCM, server-held key through GUARDIAN_STORAGE_ENCRYPTION_KEY or KMS, routing columns plaintext) — but Guardian holds that key, so the operator can still decrypt. This proposal's client-held key is a different trust boundary: the two stack as defense in depth (the existing layer covers DB/disk theft, the new one hides the bytes from Guardian itself). Provided the client key is client-derived and never server-recoverable, a few things follow:

• Decide how value flows through the decorator. It arrives already client-encrypted, so a second server-side wrap adds little (DB theft is already covered) — we can mark it opaque and bypass, or double-wrap for uniformity. Either is fine; let's just make it intentional.
• Reuse the envelope. Its record-identity binding (ciphertext tied to account_id/nonce against cross-record swaps) is exactly what the client layer needs — bind (account_id, key, version) as associated data — so we mirror it rather than write new crypto. The same plaintext-routing-columns pattern is why key ends up operator-visible (point 6).
• Fit the key model to multisig. "Derived from the user's recovery phrase" is single-user; for a multi-cosigner account we'd decouple write-authorization (the existing cosigner-list check — any cosigner can PUT) from decryption (an end-user key, domain-separated from the signing seed), so cosigners and Guardian relay and authorize but never read. The SDK should probably own that scheme + derivation rather than each integrator rolling their own.

2. Confidentiality isn't integrity — let's cover reads

Because Guardian holds the bytes, it can roll back to an older blob, omit a key, or hand different devices different values — and no request signature prevents that on reads. Writes are already tamper-evident (the auth layer signs a digest of the request payload) as long as the spec requires the ciphertext + version to sit inside that signed payload. For reads, we'd want the SDK to bind (account_id, key, version) as associated data (so a returned blob can't be swapped for another key/account/version) and track expected versions, so a rollback is at least detectable.

3. Storage should get its own replay lane

Reusing the existing auth also inherits its replay rule: resolve_account rejects any request whose timestamp isn't strictly greater than the account's last-accepted one, via a per-account CAS on last_auth_timestamp that's shared across every cosigner and device. So two devices syncing concurrently would serialize — the loser gets a 401, not a 409 — and a background sync could bump the counter and cause a delta submission from another device to be rejected. For a store whose headline feature is multi-device sync, we'd probably want replay scoped per-key rather than on the shared account counter.

4. The schema can't represent its own tombstone

With value BYTEA NOT NULL and a latest-only PK (account_id, key), a DELETE has to drop the row, which loses the monotonic version — a recreated key restarts at v1 and the CAS silently breaks (resurrection/rollback). Keeping the row and making a tombstone a version bump (nullable value + a deleted flag) avoids that. Two consequences to spell out if we go that way: deletions have to surface in the GET /storage list (with the flag) so other devices know to drop the key locally, and tombstones need a compaction policy (e.g. after N newer versions or some TTL) so they don't accumulate against the quota in point 5 indefinitely.

While we're settling semantics: the compare-and-swap version should live in the request message rather than an If-Match header, since Guardian serves both HTTP and gRPC (axum + tonic); 201 on create / 200 on update reads better than 201 for every write; and we need a create-only path too — If-Match: <version> can't express "create if absent," so two devices creating the same key concurrently would both succeed and silently clobber each other unless there's an If-None-Match: * equivalent. (The CAS itself is genuinely new behavior, not reuse — the delta path uses a UNIQUE(account_id, nonce) constraint with ON CONFLICT DO UPDATE, not "higher wins.")

5. Quotas look like a launch requirement

An opaque store we can't inspect or deduplicate is an easy free-backend / DoS vector, and what's there today doesn't cover it: the 1 MB body limit (GUARDIAN_MAX_REQUEST_BYTES) caps a single PUT but not aggregate growth, and rate-limiting is per-IP/signer request-rate, not bytes stored. Per-account total-bytes, per-key value-size, and per-account key-count caps at the app layer — the same shape as the existing GUARDIAN_MAX_PENDING_PROPOSALS_PER_ACCOUNT (default 20), on a budget separate from delta traffic — would close it. One related guardrail while we're here: storage PUT/DELETE should honor the existing account pause (the same 409 deltas hit when an account is paused), with GET still allowed, so storage can't be used to keep writing to a halted account.

6. Key names leak metadata

Even with encrypted values, plaintext keys expose the namespaces (contacts, portfolio_history), their sizes, and write frequency to the operator — and per the routing-columns-stay-plaintext pattern above, that's the default outcome unless we do something about it. Deriving opaque keys client-side (HMAC(storage_key, namespace)), optionally padding value sizes into buckets, and documenting what stays observable would bring the key column up to the same bar as the values.

Thoughts on open questions

• Quotas — required, on a separate budget (above).
• switch_guardian — SDK-orchestrated copy, since the destination Guardian can't read the bytes and a client-held key makes the ciphertext portable as-is (no re-encryption). The same client-held-key caveat applies to key rotation and recovery in general: Guardian can't re-encrypt, so rotating the storage key means a full client-side download-decrypt-reencrypt-reupload, and a lost recovery phrase means the data is gone by design — worth stating so nobody expects server-side recovery.
• Version history — the single-row schema is latest-only, and opaque bytes can't be merged server-side, so client-side conflict resolution on a 409 (re-read, merge, retry) is probably the pragmatic call over a history table.
• Naming — either works; I think /storage is fine.