@evolu/common 6.0.1-preview.3 → 6.0.1-preview.30

package/src/Evolu/Owner.ts

@@ -1,302 +1,443 @@
-/**
- * TODO:
- *
- * @module
- */
-
-import { assert } from "../Assert.js";
+import * as bip39 from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english.js";
+import { NonEmptyReadonlyArray } from "../Array.js";
 import {
-  createEncryptionKey,
-  CreateMnemonicDep,
-  CreateRandomBytesDep,
   createSlip21,
-  createSlip21Id,
   EncryptionKey,
-  MnemonicSeed,
-  mnemonicToMnemonicSeed,
+  Entropy16,
+  Entropy32,
+  RandomBytesDep,
 } from "../Crypto.js";
-import { NanoIdLibDep } from "../NanoId.js";
-import { TimeDep } from "../Time.js";
+import { getOrNull } from "../Result.js";
 import {
-  Base64Url,
   brand,
-  DateIso,
-  DateIsoString,
   Id,
-  length,
+  IdBytes,
+  idBytesToId,
+  idToIdBytes,
   Mnemonic,
   NonNegativeInt,
-  Uint8Array,
 } from "../Type.js";
-import {
-  createInitialTimestamp,
-  TimestampString,
-  timestampToTimestampString,
-} from "./Timestamp.js";
-
-// TODO: Clean API
-// - createOwner should be createAppOwner
-// - Docs mention WriteKey is optional but it's required in Owner.
-// - For Protocol, we need only ownerId, encryptionKey, and writeKey.
-// - Not sure whether we need JSDoc for this module, and we don't
-//   use modules for Evolu internal API yet.
-// It's not single responsibility API.
+import type { Storage, EncryptedDbChange } from "./Storage.js";
 
 /**
- * `Owner` is an entity in Evolu that owns data, meaning it is locally stored on
- * a device under the user’s control. Data can be personal private, peer-to-peer
- * shared, or aggregated from multiple owners.
- *
- * An owner has a {@link Mnemonic} from which {@link OwnerId} and
- * {@link EncryptionKey} are deterministically derived using SLIP-21, and an
- * optional {@link WriteKey} that, when present, enables writing to the Evolu
- * Relay or peers. The {@link WriteKey} can be rotated.
- *
- * Variants include {@link AppOwner}, {@link ShardOwner}, {@link SharedOwner}, and
- * {@link SharedReadonlyOwner}, each with specific roles and properties detailed
- * in their respective definitions.
- *
- * Public-key cryptography isn’t included here as it belongs to app and varies
- * by use case. An Evolu app without collaboration doesn’t need it, while a
- * Nostr-like app can leverage Nostr NIPs, or a super-safe app can use
- * post-quantum cryptography.
+ * The Owner represents ownership of data in Evolu. Every database change is
+ * assigned to an owner, enabling sync functionality and access control.
+ *
+ * Owners enable **partial sync** - applications can choose which owners to
+ * sync, allowing selective data synchronization based on specific needs.
+ *
+ * Owners also provide **real data deletion** - while individual changes in
+ * local-first/distributed systems can only be marked as deleted, entire owners
+ * can be completely deleted from both relays and devices (except for
+ * {@link AppOwner}, which must be preserved for sync coordination).
+ *
+ * Evolu provides different owner types depending on their use case:
+ *
+ * - **Coordination**: {@link AppOwner} for sync coordination and long-term
+ *   persistence
+ * - **Data partitioning**: {@link ShardOwner} for partitioning application data
+ * - **Collaboration**: {@link SharedOwner} for collaborative write access
+ * - **Data sharing**: {@link SharedReadonlyOwner} for read-only access to shared
+ *   data
+ *
+ * Owners are cryptographically derived from an {@link OwnerSecret} using
+ * SLIP-21, ensuring secure and deterministic key generation:
+ *
+ * - {@link OwnerId}: Globally unique public identifier
+ * - {@link EncryptionKey}: Symmetric encryption key for data protection
+ * - {@link OwnerWriteKey}: Authentication token for write operations (rotatable)
+ *
+ * @see {@link createOwner}
  */
 export interface Owner {
-  readonly mnemonic: Mnemonic;
-  readonly createdAt: DateIsoString;
   readonly id: OwnerId;
-  readonly encryptionKey: EncryptionKey;
-  readonly writeKey: WriteKey;
-}
-
-export interface OwnerWithWriteAccess {
-  readonly id: OwnerId;
-  readonly encryptionKey: EncryptionKey;
-  readonly writeKey: WriteKey;
+  readonly encryptionKey: OwnerEncryptionKey;
+  readonly writeKey: OwnerWriteKey;
 }
 
 /**
- * The unique identifier of {@link Owner} derived from the {@link Mnemonic}.
- *
- * This branded {@link Id} type, generated by {@link createSlip21Id}, is a
- * 21-character {@link Base64Url} string (126 bits of entropy), providing a
- * compact, shareable, and secure identifier for UI use, tied to the owner's
- * mnemonic and derivation path.
+ * OwnerId is a branded {@link Id} that uniquely identifies an {@link Owner}.
+ * Branded from {@link Id} to leverage existing helpers like {@link idToIdBytes}.
  */
 export const OwnerId = brand("OwnerId", Id);
 export type OwnerId = typeof OwnerId.Type;
 
-export const writeKeyLength = 16 as NonNegativeInt;
+/** Bytes representation of {@link OwnerId}. */
+export const OwnerIdBytes = brand("OwnerIdBytes", IdBytes);
+export type OwnerIdBytes = typeof OwnerIdBytes.Type;
+
+export const ownerIdToOwnerIdBytes = (ownerId: OwnerId): OwnerIdBytes =>
+  idToIdBytes(ownerId) as OwnerIdBytes;
+
+export const ownerIdBytesToOwnerId = (ownerIdBytes: OwnerIdBytes): OwnerId =>
+  idBytesToId(ownerIdBytes as IdBytes) as OwnerId;
+
+export const ownerWriteKeyLength = NonNegativeInt.orThrow(16);
+
+export const OwnerEncryptionKey = brand("OwnerEncryptionKey", EncryptionKey);
+export type OwnerEncryptionKey = typeof OwnerEncryptionKey.Type;
 
 /**
- * A secure token proving the initiator can write changes. Derived from a
- * mnemonic or randomly generated. It's rotatable.
+ * A secure token for write operations. It's derived from {@link OwnerSecret} by
+ * default and can be rotated via {@link createOwnerWriteKey}.
  */
-export const WriteKey = brand("WriteKey", length(writeKeyLength)(Uint8Array));
-export type WriteKey = typeof WriteKey.Type;
+export const OwnerWriteKey = brand("OwnerWriteKey", Entropy16);
+export type OwnerWriteKey = typeof OwnerWriteKey.Type;
 
 /**
- * The root owner of an Evolu app, created from a mnemonic safely generated on a
- * device when the app is initialized or restored on another device using an
- * existing mnemonic. It manages the app's core data, including the storage of
- * other owners' mnemonics in an encrypted app table. Its `writeKey` is
- * deterministic and rotatable. Never share the AppOwner mnemonic with anyone.
+ * 32 bytes of cryptographic entropy used to derive {@link Owner} keys.
+ *
+ * Can be created using {@link createOwnerSecret} or converted from a
+ * {@link Mnemonic} using {@link mnemonicToOwnerSecret}.
  */
-export interface AppOwner extends Owner {
-  readonly type: "AppOwner";
-}
+export const OwnerSecret = brand("OwnerSecret", Entropy32);
+export type OwnerSecret = typeof OwnerSecret.Type;
+
+/** Creates a {@link OwnerSecret}. */
+export const createOwnerSecret = (deps: RandomBytesDep): OwnerSecret =>
+  deps.randomBytes.create(32) as OwnerSecret;
+
+/** Converts an {@link OwnerSecret} to a {@link Mnemonic}. */
+export const ownerSecretToMnemonic = (secret: OwnerSecret): Mnemonic =>
+  bip39.entropyToMnemonic(secret, wordlist) as Mnemonic;
+
+/** Converts a {@link Mnemonic} to an {@link OwnerSecret}. */
+export const mnemonicToOwnerSecret = (mnemonic: Mnemonic): OwnerSecret =>
+  bip39.mnemonicToEntropy(mnemonic, wordlist) as OwnerSecret;
+
+/** Creates a randomly generated {@link OwnerWriteKey}. */
+export const createOwnerWriteKey = (deps: RandomBytesDep): OwnerWriteKey =>
+  deps.randomBytes.create(16) as OwnerWriteKey;
 
 /**
- * Used to shard data within an app for partial or deferred sync. Created in the
- * Evolu `initialData` function or dynamically as needed. Its mnemonic is stored
- * in an app table (encrypted by `AppOwner`) and synced between devices. Its
- * `writeKey` is deterministic and rotatable, enabling selective syncing of data
- * subsets. Not intended for sharing outside the app.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * Creates an {@link Owner} from a {@link OwnerSecret} using SLIP-21 key
+ * derivation.
+ *
+ * This is an internal helper function, use:
+ *
+ * - {@link createAppOwner}
+ * - {@link createShardOwner}
+ * - {@link createSharedOwner}
+ * - {@link createSharedReadonlyOwner}
  */
-export interface ShardOwner {
-  readonly type: "ShardOwner";
-  readonly mnemonic: Mnemonic;
-  readonly writeKey: WriteKey;
-}
+export const createOwner = (secret: OwnerSecret): Owner => ({
+  id: ownerIdBytesToOwnerId(
+    OwnerIdBytes.orThrow(
+      createSlip21(secret, ["Evolu", "OwnerIdBytes"]).slice(0, 16),
+    ),
+  ),
+
+  encryptionKey: OwnerEncryptionKey.orThrow(
+    createSlip21(secret, ["Evolu", "OwnerEncryptionKey"]),
+  ),
+
+  writeKey: OwnerWriteKey.orThrow(
+    createSlip21(secret, ["Evolu", "OwnerWriteKey"]).slice(0, 16),
+  ),
+});
 
 /**
- * Used to share data among one or more users, enabling collaboration or
- * controlled access. Its `writeKey` is random (not derived from the mnemonic,
- * stored alongside it in the app table) and rotatable, ensuring it cannot be
- * regenerated by others if shared. Share the `mnemonic` alone for read-only
- * access (as `SharedReadonlyOwner`) or share SharedOwner itself for write
- * access.
- *
- * This type omits `id`, `encryptionKey`, and `createdAt` as they are derived by
- * Evolu from the `mnemonic`, reducing storage overhead.
+ * The AppOwner represents the application owner. It's created using a
+ * cryptographically secure random generator or derived from an external source,
+ * e.g., mnemonic stored securely in a hardware device.
+ *
+ * While it's possible to store all application data in AppOwner, the better
+ * approach is to use it only for sync coordination. Storing all app data in
+ * AppOwner means that data will be stored/synced forever. And that's a problem
+ * if we want to provide real data deletion or in-app data migration without
+ * data duplication. In local-first apps/distributed systems, we can't delete
+ * individual changes, we only mark them as deleted, otherwise sync could not
+ * work.
+ *
+ * If we really want to delete data or at least avoid syncing it, we must store
+ * it using a different owner than AppOwner, e.g. {@link ShardOwner} or
+ * {@link SharedOwner}, and delete that owner. The AppOwner itself must be
+ * preserved because it coordinates deletion information across devices. Other
+ * devices need to sync the information that an owner was deleted so they can
+ * delete their local data as well.
+ *
+ * ### Privacy Considerations
+ *
+ * AppOwner must never be shared with anyone, except for its {@link OwnerId},
+ * which can be used for authorization with
+ * {@link createOwnerWebSocketTransport}. It's safe because OwnerId is
+ * pseudonymous (it can't be assigned to a specific person).
+ *
+ * For data sharing scenarios, use {@link SharedOwner} and
+ * {@link SharedReadonlyOwner} instead, which are designed specifically for
+ * collaborative access.
  */
-export interface SharedOwner {
-  readonly type: "SharedOwner";
-  readonly mnemonic: Mnemonic;
-  readonly writeKey: WriteKey;
+export interface AppOwner extends Owner {
+  readonly type: "AppOwner";
+
+  /**
+   * The mnemonic that was used to derive the AppOwner keys. Optional when the
+   * AppOwner is created from external keys to avoid sharing the mnemonic with
+   * the Evolu app.
+   */
+  readonly mnemonic?: Mnemonic | null;
 }
 
+/** Creates an {@link AppOwner} from an {@link OwnerSecret}. */
+export const createAppOwner = (secret: OwnerSecret): AppOwner => ({
+  type: "AppOwner",
+  mnemonic: ownerSecretToMnemonic(secret),
+  ...createOwner(secret),
+});
+
 /**
- * Used for sharing data that can only be read, such as with followers or peers
- * in a read-only sync scenario. It lacks a `writeKey`, containing only the
- * `mnemonic` from which `id` and `encryptionKey` are derived by Evolu.
- * Typically derived from a `SharedOwner` by sharing its `mnemonic` without the
- * `writeKey`.
+ * An {@link Owner} for sharding data.
+ *
+ * ShardOwners are the recommended storage location for most application data
+ * because they can be completely deleted (both on relays and devices) and
+ * conditionally synced.
+ *
+ * Can be created from {@link OwnerSecret} via {@link createShardOwner} or
+ * deterministically derived from {@link AppOwner} using
+ * {@link deriveShardOwner}.
  */
-export interface SharedReadonlyOwner {
-  readonly type: "SharedReadonlyOwner";
-  readonly mnemonic: Mnemonic;
+export interface ShardOwner extends Owner {
+  readonly type: "ShardOwner";
+  readonly transports?: ReadonlyArray<OwnerTransport>;
 }
 
-/**
- * Creates an {@link AppOwner}, optionally from an existing mnemonic to restore
- * it on another device; otherwise, generates a new mnemonic.
- */
-export const createAppOwner =
-  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) =>
-  (mnemonic = deps.createMnemonic()): AppOwner => {
-    const owner = createOwner(deps)(mnemonic);
-    return { type: "AppOwner", ...owner };
+/** Creates a {@link ShardOwner} from an {@link OwnerSecret}. */
+export const createShardOwner = (
+  secret: OwnerSecret,
+  transports?: ReadonlyArray<OwnerTransport>,
+): ShardOwner => {
+  return {
+    type: "ShardOwner",
+    ...createOwner(secret),
+    ...(transports && { transports }),
   };
+};
 
 /**
- * Creates a {@link ShardOwner} for sharding app data with a freshly generated
- * mnemonic. Unlike {@link createAppOwner}, it doesn’t accept an existing
- * mnemonic because ShardOwner mnemonics are always generated and restored
- * automatically via database sync.
+ * Derives a {@link ShardOwner} from an {@link AppOwner} using the specified path.
+ *
+ * **Advantages of derived owners:**
+ *
+ * - **Deterministic**: Same path always produces the same ShardOwner across all
+ *   devices
+ * - **Immediate availability**: Can be hardcoded and used before sync occurs
+ * - **Consistent setup**: All devices start with identical data structure
+ * - **Lifecycle management**: Can implement epoch patterns for clean data
+ *   deletion and recreation
+ *
+ * **Common patterns:**
+ *
+ * - Use paths like `["shard", 1]` for versioned data lifecycle
+ * - Use paths like `["project", "MyApp", 1]` for named partitions with versions
+ * - Each device can derive the same owners and set up initial structure
  */
-export const createShardOwner = (
-  deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep,
+export const deriveShardOwner = (
+  owner: AppOwner,
+  path: NonEmptyReadonlyArray<string | number>,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): ShardOwner => {
-  const owner = createOwner(deps)();
+  const secret = createSlip21(owner.encryptionKey, path) as OwnerSecret;
+
   return {
     type: "ShardOwner",
-    mnemonic: owner.mnemonic,
-    writeKey: owner.writeKey,
+    ...createOwner(secret),
+    ...(transports && { transports }),
   };
 };
 
+/** An {@link Owner} for collaborative data with write access. */
+export interface SharedOwner extends Owner {
+  readonly type: "SharedOwner";
+  readonly transports?: ReadonlyArray<OwnerTransport>;
+}
+
 /**
- * Creates a fresh {@link SharedOwner} for sharing data with write access. Takes
- * no arguments as both `mnemonic` and rotatable `writeKey` are newly generated;
- * when shared, recipients use the provided `mnemonic` and `writeKey` directly
- * as a {@link SharedOwner} without needing to recreate it.
+ * Creates a {@link SharedOwner} from an {@link OwnerSecret} for collaborative
+ * write access.
+ *
+ * Use {@link createSharedReadonlyOwner} to create a read-only version for
+ * sharing.
  */
 export const createSharedOwner = (
-  deps: CreateRandomBytesDep & CreateMnemonicDep,
+  secret: OwnerSecret,
+  transports?: ReadonlyArray<OwnerTransport>,
 ): SharedOwner => {
-  const mnemonic = deps.createMnemonic();
-  const writeKey = createWriteKey(deps)(); // Random, no seed
   return {
     type: "SharedOwner",
-    mnemonic,
-    writeKey,
+    ...createOwner(secret),
+    ...(transports && { transports }),
   };
 };
 
 /**
- * Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner} for read-only
- * data sharing. Extracts the `mnemonic` from the provided {@link SharedOwner},
- * omitting its `writeKey` to ensure read-only access.
+ * Read-only version of a {@link SharedOwner} for data sharing. Contains only the
+ * {@link OwnerId} and {@link EncryptionKey} needed for others to read the shared
+ * data without write access.
  */
+export interface SharedReadonlyOwner {
+  readonly type: "SharedReadonlyOwner";
+  readonly id: OwnerId;
+  readonly encryptionKey: EncryptionKey;
+  readonly transports?: ReadonlyArray<OwnerTransport>;
+}
+
+/** Creates a {@link SharedReadonlyOwner} from a {@link SharedOwner}. */
 export const createSharedReadonlyOwner = (
   sharedOwner: SharedOwner,
-): SharedReadonlyOwner => {
-  return {
-    type: "SharedReadonlyOwner",
-    mnemonic: sharedOwner.mnemonic,
-  };
-};
-
-/** Creates an {@link Owner} with optional `mnemonic` and `writeKey`. */
-export const createOwner =
-  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep) =>
-  (mnemonic = deps.createMnemonic(), writeKey?: WriteKey): Owner => {
-    const seed = mnemonicToMnemonicSeed(mnemonic);
-
-    const id = createSlip21Id(seed, ["Evolu", "Owner Id"]) as OwnerId;
-    const encryptionKey = createEncryptionKey(seed);
-
-    const createdAt = DateIso.fromParent(new Date(deps.time.now()));
-    assert(createdAt.ok, "Invalid DateIso: bad system clock");
-
-    return {
-      mnemonic,
-      createdAt: createdAt.value,
-      id,
-      encryptionKey,
-      writeKey: writeKey ?? createWriteKey(deps)(seed),
-    };
-  };
-
-export const createWriteKey =
-  (deps: CreateRandomBytesDep) =>
-  (seed?: MnemonicSeed): WriteKey => {
-    const key = seed
-      ? createSlip21(seed, ["Evolu", "Write Key"]).slice(0, 16)
-      : deps.createRandomBytes(16);
+): SharedReadonlyOwner => ({
+  type: "SharedReadonlyOwner",
+  id: sharedOwner.id,
+  encryptionKey: sharedOwner.encryptionKey,
+  ...(sharedOwner.transports && { transports: sharedOwner.transports }),
+});
 
-    const writeKey = WriteKey.from(key);
-    assert(writeKey.ok, "Ensure valid WriteKey");
+/**
+ * Transport configuration for connecting to relays.
+ *
+ * Currently only WebSocket, in the future Bluetooth, LocalNetwork, etc.
+ */
+export type OwnerTransport = OwnerWebSocketTransport;
 
-    return writeKey.value;
-  };
+/**
+ * WebSocket transport configuration.
+ *
+ * ### Authentication via URL
+ *
+ * The {@link OwnerId} is passed as a URL query parameter. While this approach is
+ * generally discouraged for authentication tokens (they get logged), it's safe
+ * here because OwnerId is pseudonymous and used only for access verification -
+ * it provides no ability to read encrypted data or write changes.
+ *
+ * See: [HTTP headers in Websockets client
+ * API](https://stackoverflow.com/questions/4361173/http-headers-in-websockets-client-api/74564827#74564827)
+ *
+ * ### Error Handling
+ *
+ * When a relay rejects a connection (invalid OwnerId, unauthorized owner, or
+ * server error), the browser WebSocket API does not expose the specific HTTP
+ * status code or reason - it only reports a generic connection failure. The
+ * client automatically retries with exponential backoff and jitter, eventually
+ * succeeding once the configuration or server issue is resolved.
+ *
+ * Legitimate clients will be properly configured with valid credentials, so
+ * automatic retry is OK.
+ *
+ * @see {@link createOwnerWebSocketTransport}
+ * @see {@link parseOwnerIdFromOwnerWebSocketTransportUrl}
+ */
+export interface OwnerWebSocketTransport {
+  readonly type: "WebSocket";
+  readonly url: string;
+}
 
 /**
- * An `OwnerRow` represents a row in the `evolu_owner` table, based on an
- * {@link Owner} with an added `timestamp` ({@link TimestampString}) for CRDT
- * sync. It supports all {@link Owner} variants with an optional `writeKey`; use
- * {@link createOwnerRow} to align it with a specific {@link Owner}.
+ * Creates an {@link OwnerWebSocketTransport} for the given relay URL and
+ * {@link OwnerId}.
+ *
+ * The URL must be a WebSocket base URL without query parameters or fragments
+ * (e.g., `wss://relay.evolu.dev`, not `wss://relay.evolu.dev?foo=bar`). The
+ * function appends the `ownerId` as a query parameter.
+ *
+ * ### Example
+ *
+ * ```ts
+ * // Create transport "wss://relay.evolu.dev?ownerId=..."
+ * const transport = createOwnerWebSocketTransport({
+ *   url: "wss://relay.evolu.dev",
+ *   ownerId: owner.id,
+ * });
+ *
+ * // Use with createEvolu
+ * const evolu = createEvolu(deps)(Schema, {
+ *   transports: [transport],
+ * });
+ * ```
  */
-export type OwnerRow = Omit<Owner, "writeKey"> & {
-  readonly writeKey: WriteKey | null;
-  readonly timestamp: TimestampString;
-};
+export const createOwnerWebSocketTransport = (config: {
+  readonly url: string;
+  readonly ownerId: OwnerId;
+}): OwnerWebSocketTransport => ({
+  type: "WebSocket",
+  url: `${config.url}?ownerId=${config.ownerId}`,
+});
 
 /**
- * Creates an {@link OwnerRow} from any {@link Owner} variant for the
- * `evolu_owner` table, adding a `timestamp` ({@link TimestampString}) for CRDT
- * sync.
+ * Extracts {@link OwnerId} from an {@link OwnerWebSocketTransport} URL query
+ * string.
+ *
+ * Parses the query string `?ownerId=...` and validates that the extracted value
+ * is a valid {@link OwnerId}.
+ *
+ * ### Example
+ *
+ * ```ts
+ * parseOwnerIdFromOwnerWebSocketTransportUrl(
+ *   "/sync?ownerId=_12345678abcdefgh",
+ * );
+ * // Returns: OwnerId or null
+ * ```
  */
-export const createOwnerRow =
-  (deps: TimeDep & CreateRandomBytesDep & CreateMnemonicDep & NanoIdLibDep) =>
-  (
-    owner: AppOwner | ShardOwner | SharedOwner | SharedReadonlyOwner,
-  ): OwnerRow => {
-    const timestamp = timestampToTimestampString(createInitialTimestamp(deps));
-    switch (owner.type) {
-      case "AppOwner": {
-        const { type, ...rest } = owner;
-        return { ...rest, timestamp };
-      }
-      case "ShardOwner":
-      case "SharedOwner":
-        return {
-          ...createOwner(deps)(owner.mnemonic, owner.writeKey),
-          timestamp,
-        };
-      case "SharedReadonlyOwner":
-        return {
-          ...createOwner(deps)(owner.mnemonic),
-          writeKey: null,
-          timestamp,
-        };
-    }
-  };
+export const parseOwnerIdFromOwnerWebSocketTransportUrl = (
+  url: string,
+): OwnerId | null => getOrNull(OwnerId.fromUnknown(url.split("=")[1]));
+
+/** Base interface for all owner errors. */
+export interface BaseOwnerError {
+  readonly ownerId: OwnerId;
+}
 
 /**
- * Rotates the {@link WriteKey} for an {@link AppOwner}, {@link ShardOwner}, or
- * {@link SharedOwner}, returning a new instance with the updated key.
+ * Usage data for an {@link OwnerId}.
+ *
+ * Tracks data consumption to monitor usage patterns and enforce quotas if
+ * needed. Used by both relays and clients.
+ *
+ * Relays and clients must handle rate limiting, connection limits, and request
+ * throttling separately with in-memory state.
  */
-export const rotateWriteKey = <T extends AppOwner | ShardOwner | SharedOwner>(
-  owner: T,
-  newWriteKey: WriteKey,
-): T => {
-  return {
-    ...owner,
-    writeKey: newWriteKey,
-  } as T;
-};
+export interface OwnerUsage {
+  /** The {@link Owner} this usage data belongs to. */
+  readonly ownerId: OwnerIdBytes;
+
+  /**
+   * Total logical data bytes stored.
+   *
+   * Measures the size of {@link EncryptedDbChange}s only, excluding
+   * {@link Storage} implementation overhead (with SqliteStorage: indexes,
+   * skiplist columns, etc.). This provides:
+   *
+   * - **Predictable measurement** - same data = same byte count across all
+   *   instances
+   * - **Quota enforcement** - consistent billing/limits independent of storage
+   *   implementation
+   * - **Overhead tracking** - actual Storage size can be compared against this to
+   *   monitor efficiency
+   */
+  readonly storedBytes: NonNegativeInt;
+
+  // TODO: Decide how to use receivedBytes and sentBytes.
+  // /** Total bytes received. */
+  // readonly receivedBytes: NonNegativeInt;
+
+  // TODO: Decide how to use sentBytes.
+  // /** Total bytes sent. */
+  // readonly sentBytes: NonNegativeInt;
+
+  // TODO: Decide how to use firstTimestamp.
+  // /**
+  //  * The minimum {@link Timestamp}.
+  //  *
+  //  * Helps {@link Storage} choose faster algorithms.
+  //  */
+  // readonly firstTimestamp: TimestampBytes | null;
+
+  // TODO: Decide how to use lastTimestamp.
+  // /**
+  //  * The maximum {@link Timestamp}.
+  //  *
+  //  * Helps {@link Storage} choose faster algorithms. Free relays can use it to
+  //  * identify inactive accounts for cleanup or archival.
+  //  */
+  // readonly lastTimestamp: TimestampBytes | null;
+}