@snaha/swarm-id 0.0.1

package/src/sync/index.ts

@@ -0,0 +1,28 @@
+// Public API
+export {
+  // Account-level key derivation
+  deriveAccountBackupKey,
+  deriveAccountSwarmEncryptionKey,
+  backupKeyToPrivateKey,
+} from "../utils/key-derivation"
+export { serializeAccountState, deserializeAccountState } from "./serialization"
+
+// Sync account
+export { createSyncAccount, ACCOUNT_SYNC_TOPIC_PREFIX } from "./sync-account"
+export type { SyncAccountOptions, SyncAccountFunction } from "./sync-account"
+
+// Restore account from Swarm
+export { restoreAccountFromSwarm } from "./restore-account"
+export type { RestoreAccountResult } from "./restore-account"
+
+// Store interfaces
+export type {
+  AccountsStoreInterface,
+  IdentitiesStoreInterface,
+  ConnectedAppsStoreInterface,
+  PostageStampsStoreInterface,
+  StamperOptions,
+  FlushableStamper,
+} from "./store-interfaces"
+
+export type { SyncResult } from "./types"

package/src/sync/restore-account.ts

@@ -0,0 +1,90 @@
+/**
+ * Restore Account from Swarm
+ *
+ * When a passkey auth succeeds but no local account exists (e.g. new device),
+ * this utility derives the keys needed to find and decrypt the account
+ * snapshot stored in Swarm and returns the restored state.
+ */
+
+import {
+  Bee,
+  PrivateKey,
+  EthAddress,
+  Topic,
+  Reference,
+  type Bytes,
+} from "@ethersphere/bee-js"
+import {
+  deriveAccountSwarmEncryptionKey,
+  deriveSecret,
+} from "../utils/key-derivation"
+import { ACCOUNT_SYNC_TOPIC_PREFIX } from "./sync-account"
+import { AsyncEpochFinder } from "../proxy/feeds/epochs/async-finder"
+import { downloadDataWithChunkAPI } from "../proxy/download-data"
+import { deserializeAccountState } from "./serialization"
+import type { AccountStateSnapshot } from "../utils/account-state-snapshot"
+
+/**
+ * Result of a successful account restore from Swarm
+ */
+export interface RestoreAccountResult {
+  snapshot: AccountStateSnapshot
+  swarmEncryptionKey: string
+  credentialId: string
+}
+
+/**
+ * Restore account state from Swarm using passkey authentication result
+ *
+ * @param bee - Bee client instance
+ * @param masterKey - Master key from passkey authentication
+ * @param ethereumAddress - Account ID (EthAddress) from passkey authentication
+ * @param credentialId - Credential ID from passkey authentication
+ * @returns Restored account state, or undefined if no backup found in Swarm
+ */
+export async function restoreAccountFromSwarm(
+  bee: Bee,
+  masterKey: Bytes,
+  ethereumAddress: EthAddress,
+  credentialId: string,
+): Promise<RestoreAccountResult | undefined> {
+  const accountId = ethereumAddress.toHex()
+
+  // 1. Derive the swarm encryption key from the master key
+  const swarmEncryptionKey = await deriveAccountSwarmEncryptionKey(
+    masterKey.toHex(),
+  )
+
+  // 2. Derive the backup key (used as feed owner)
+  const backupKeyHex = await deriveSecret(swarmEncryptionKey, "backup-key")
+  const backupKey = new PrivateKey(backupKeyHex)
+  const owner = backupKey.publicKey().address()
+
+  // 3. Build the feed topic
+  const topic = Topic.fromString(`${ACCOUNT_SYNC_TOPIC_PREFIX}:${accountId}`)
+
+  // 4. Look up the latest epoch feed entry
+  // Note: feed SOCs are uploaded unencrypted (sync-account.ts doesn't pass
+  // encryptionKey to updater.update()), so the finder must NOT use one either.
+  const finder = new AsyncEpochFinder(bee, topic, owner)
+  const now = BigInt(Math.floor(Date.now() / 1000))
+
+  const refBytes = await finder.findAt(now)
+
+  if (!refBytes) {
+    return undefined
+  }
+
+  // 5. Download and decrypt the account snapshot
+  const reference = new Reference(refBytes)
+  const data = await downloadDataWithChunkAPI(bee, reference.toHex())
+
+  // 6. Deserialize the snapshot
+  const snapshot = deserializeAccountState(data)
+
+  return {
+    snapshot,
+    swarmEncryptionKey,
+    credentialId,
+  }
+}

package/src/sync/serialization.ts

@@ -0,0 +1,39 @@
+import {
+  serializeAccountStateSnapshot,
+  deserializeAccountStateSnapshot,
+} from "../utils/account-state-snapshot"
+import type { AccountStateSnapshot } from "../utils/account-state-snapshot"
+
+/**
+ * Serialize account state to JSON bytes
+ *
+ * @param state - Account payload to serialize
+ * @returns JSON encoded as Uint8Array
+ */
+export function serializeAccountState(state: AccountStateSnapshot): Uint8Array {
+  const json = JSON.stringify(serializeAccountStateSnapshot(state))
+
+  return new TextEncoder().encode(json)
+}
+
+/**
+ * Deserialize JSON bytes to account payload
+ *
+ * @param data - JSON bytes to deserialize
+ * @returns Account payload
+ */
+export function deserializeAccountState(
+  data: Uint8Array,
+): AccountStateSnapshot {
+  const json = new TextDecoder().decode(data)
+  const parsed = JSON.parse(json)
+  const result = deserializeAccountStateSnapshot(parsed)
+
+  if (!result.success) {
+    throw new Error(
+      `Failed to deserialize account state: ${result.error.message}`,
+    )
+  }
+
+  return result.data
+}

package/src/sync/store-interfaces.ts

@@ -0,0 +1,62 @@
+/**
+ * Store Interfaces for Sync Coordinator
+ *
+ * These interfaces define the minimal contract that stores must implement
+ * to be used with the sync coordinator. This allows the coordinator to be
+ * used with different store implementations (Svelte stores, plain objects, etc.)
+ */
+
+import type { EthAddress, BatchId, Stamper } from "@ethersphere/bee-js"
+import type { Account, Identity, ConnectedApp, PostageStamp } from "../schemas"
+
+/**
+ * Options for creating a stamper with utilization tracking
+ */
+export interface StamperOptions {
+  owner: EthAddress
+  encryptionKey: Uint8Array
+}
+
+/**
+ * Extended stamper interface with optional flush capability
+ *
+ * Some stampers (like UtilizationAwareStamper) support flushing
+ * dirty bucket state to cache.
+ */
+export interface FlushableStamper extends Stamper {
+  flush?(): Promise<void>
+}
+
+/**
+ * Interface for accessing account data
+ */
+export interface AccountsStoreInterface {
+  getAccount(id: EthAddress): Account | undefined
+}
+
+/**
+ * Interface for accessing identity data
+ */
+export interface IdentitiesStoreInterface {
+  getIdentitiesByAccount(accountId: EthAddress): Identity[]
+}
+
+/**
+ * Interface for accessing connected app data
+ */
+export interface ConnectedAppsStoreInterface {
+  getAppsByIdentityId(identityId: string): ConnectedApp[]
+}
+
+/**
+ * Interface for accessing and managing postage stamp data
+ */
+export interface PostageStampsStoreInterface {
+  getStamp(batchID: BatchId): PostageStamp | undefined
+  getStampsByAccount(accountId: string): PostageStamp[]
+  getStamper(
+    batchID: BatchId,
+    options?: StamperOptions,
+  ): Promise<FlushableStamper | undefined>
+  updateStampUtilization(batchID: BatchId, utilization: number): void
+}

package/src/sync/sync-account.test.ts

@@ -0,0 +1,302 @@
+import { describe, it, expect, vi, beforeEach } from "vitest"
+import { EthAddress, BatchId } from "@ethersphere/bee-js"
+import { createSyncAccount } from "./sync-account"
+import { deserializeAccountState } from "./serialization"
+import type {
+  AccountsStoreInterface,
+  IdentitiesStoreInterface,
+  ConnectedAppsStoreInterface,
+  PostageStampsStoreInterface,
+} from "./store-interfaces"
+import type { UtilizationStoreDB } from "../storage/utilization-store"
+import type { DebouncedUtilizationUploader } from "../storage/debounced-uploader"
+import {
+  TEST_ETH_ADDRESS_HEX,
+  TEST_IDENTITY_ADDRESS_HEX,
+  TEST_BATCH_ID_HEX,
+  createPasskeyAccount,
+  createIdentity,
+  createConnectedApp,
+  createPostageStamp,
+} from "../test-fixtures"
+
+// ============================================================================
+// Mock Factories
+// ============================================================================
+
+function createMockStores() {
+  const account = createPasskeyAccount({
+    credentialId: "test-credential",
+    name: "Test Account",
+    defaultPostageStampBatchID: new BatchId(TEST_BATCH_ID_HEX),
+  })
+  const identity = createIdentity()
+  const connectedApp = createConnectedApp({ appSecret: undefined })
+  const stamp = createPostageStamp()
+
+  const accountsStore: AccountsStoreInterface = {
+    getAccount: vi.fn((id: EthAddress) =>
+      id.toHex() === TEST_ETH_ADDRESS_HEX ? account : undefined,
+    ),
+  }
+
+  const identitiesStore: IdentitiesStoreInterface = {
+    getIdentitiesByAccount: vi.fn((accountId: EthAddress) =>
+      accountId.toHex() === TEST_ETH_ADDRESS_HEX ? [identity] : [],
+    ),
+  }
+
+  const connectedAppsStore: ConnectedAppsStoreInterface = {
+    getAppsByIdentityId: vi.fn((identityId: string) =>
+      identityId === TEST_IDENTITY_ADDRESS_HEX ? [connectedApp] : [],
+    ),
+  }
+
+  const mockStamper = {
+    stamp: vi.fn().mockResolvedValue({
+      batchId: new Uint8Array(32),
+      index: new Uint8Array(8),
+      timestamp: new Uint8Array(8),
+      signature: new Uint8Array(65),
+    }),
+    flush: vi.fn().mockResolvedValue(undefined),
+  }
+
+  const postageStampsStore: PostageStampsStoreInterface = {
+    getStamp: vi.fn((batchID: BatchId) =>
+      batchID.toHex() === TEST_BATCH_ID_HEX ? stamp : undefined,
+    ),
+    getStampsByAccount: vi.fn((accountId: string) =>
+      accountId === TEST_ETH_ADDRESS_HEX ? [stamp] : [],
+    ),
+    getStamper: vi.fn().mockResolvedValue(mockStamper),
+    updateStampUtilization: vi.fn(),
+  }
+
+  return {
+    accountsStore,
+    identitiesStore,
+    connectedAppsStore,
+    postageStampsStore,
+    mockStamper,
+  }
+}
+
+// ============================================================================
+// Upload & Epoch Mock Setup
+// ============================================================================
+
+// Track what was uploaded
+let capturedUploadData: Uint8Array | undefined
+let capturedEncryptionKey: Uint8Array | undefined
+let uploadCallCount: number
+let epochUpdateCallCount: number
+let capturedEpochReference: Uint8Array | undefined
+
+const FAKE_UPLOAD_REFERENCE = "ab".repeat(32)
+const FAKE_SOC_ADDRESS = new Uint8Array(32).fill(0xee)
+
+vi.mock("../proxy/upload-encrypted-data", () => ({
+  uploadEncryptedDataWithSigning: vi.fn(
+    async (
+      _context: unknown,
+      data: Uint8Array,
+      encryptionKey: Uint8Array | undefined,
+    ) => {
+      capturedUploadData = data
+      capturedEncryptionKey = encryptionKey
+      uploadCallCount++
+      return {
+        reference: FAKE_UPLOAD_REFERENCE,
+        chunkAddresses: [new Uint8Array(32).fill(0xaa)],
+      }
+    },
+  ),
+}))
+
+// Use a real class for the mock so `new BasicEpochUpdater(...)` works
+const mockUpdate = vi.fn()
+
+vi.mock("../proxy/feeds/epochs", () => {
+  return {
+    BasicEpochUpdater: class MockBasicEpochUpdater {
+      update = mockUpdate
+      getOwner = vi.fn(() => new EthAddress("a".repeat(40)))
+    },
+  }
+})
+
+// Mock utilization to avoid complexity in these tests
+vi.mock("../utils/batch-utilization", () => ({
+  updateAfterWrite: vi.fn().mockResolvedValue({
+    state: { chunks: new Map() },
+    tracker: { hasDirtyChunks: () => false, getDirtyChunks: () => [] },
+  }),
+  saveUtilizationState: vi.fn().mockResolvedValue(undefined),
+  calculateUtilization: vi.fn().mockReturnValue(0.01),
+}))
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe("createSyncAccount", () => {
+  beforeEach(() => {
+    capturedUploadData = undefined
+    capturedEncryptionKey = undefined
+    capturedEpochReference = undefined
+    uploadCallCount = 0
+    epochUpdateCallCount = 0
+
+    mockUpdate.mockReset()
+    mockUpdate.mockImplementation(
+      async (_timestamp: bigint, reference: Uint8Array) => {
+        capturedEpochReference = reference
+        epochUpdateCallCount++
+        return {
+          socAddress: FAKE_SOC_ADDRESS,
+          epoch: { start: 0n, level: 0 },
+          timestamp: BigInt(Math.floor(Date.now() / 1000)),
+        }
+      },
+    )
+  })
+
+  it("should upload encrypted data and update epoch feed", async () => {
+    const stores = createMockStores()
+
+    const syncAccount = createSyncAccount({
+      bee: {} as never,
+      ...stores,
+      utilizationStore: {} as UtilizationStoreDB,
+      utilizationUploader: {
+        scheduleUpload: vi.fn().mockResolvedValue(undefined),
+      } as unknown as DebouncedUtilizationUploader,
+    })
+
+    const result = await syncAccount(TEST_ETH_ADDRESS_HEX)
+
+    expect(result).toBeDefined()
+    expect(result!.status).toBe("success")
+    if (result!.status !== "success") return
+
+    // Verify upload happened
+    expect(uploadCallCount).toBe(1)
+    expect(capturedUploadData).toBeDefined()
+    expect(capturedEncryptionKey).toBeDefined()
+
+    // Verify epoch feed was updated
+    expect(epochUpdateCallCount).toBe(1)
+    expect(capturedEpochReference).toBeDefined()
+
+    // Verify result contains reference and chunk addresses
+    expect(result.reference).toBe(FAKE_UPLOAD_REFERENCE)
+    expect(result.chunkAddresses.length).toBeGreaterThanOrEqual(2) // data chunks + SOC
+  })
+
+  it("should serialize account state with all fields including accountName", async () => {
+    const stores = createMockStores()
+
+    const syncAccount = createSyncAccount({
+      bee: {} as never,
+      ...stores,
+      utilizationStore: {} as UtilizationStoreDB,
+      utilizationUploader: {
+        scheduleUpload: vi.fn().mockResolvedValue(undefined),
+      } as unknown as DebouncedUtilizationUploader,
+    })
+
+    await syncAccount(TEST_ETH_ADDRESS_HEX)
+
+    // Deserialize the captured upload data to verify contents
+    expect(capturedUploadData).toBeDefined()
+    const deserialized = deserializeAccountState(capturedUploadData!)
+
+    expect(deserialized.version).toBe(1)
+    expect(deserialized.accountId).toBe(TEST_ETH_ADDRESS_HEX)
+    expect(deserialized.metadata.accountName).toBe("Test Account")
+    expect(deserialized.metadata.defaultPostageStampBatchID).toBe(
+      TEST_BATCH_ID_HEX,
+    )
+    expect(deserialized.metadata.createdAt).toBe(1700000000000)
+    expect(deserialized.identities).toHaveLength(1)
+    expect(deserialized.identities[0].name).toBe("Default Identity")
+    expect(deserialized.connectedApps).toHaveLength(1)
+    expect(deserialized.connectedApps[0].appName).toBe("Test App")
+    expect(deserialized.postageStamps).toHaveLength(1)
+    expect(deserialized.postageStamps[0].depth).toBe(20)
+  })
+
+  it("should return undefined when account not found", async () => {
+    const stores = createMockStores()
+    ;(
+      stores.accountsStore.getAccount as ReturnType<typeof vi.fn>
+    ).mockReturnValue(undefined)
+
+    const syncAccount = createSyncAccount({
+      bee: {} as never,
+      ...stores,
+      utilizationStore: {} as UtilizationStoreDB,
+      utilizationUploader: {
+        scheduleUpload: vi.fn().mockResolvedValue(undefined),
+      } as unknown as DebouncedUtilizationUploader,
+    })
+
+    const result = await syncAccount(TEST_ETH_ADDRESS_HEX)
+    expect(result).toBeUndefined()
+    expect(uploadCallCount).toBe(0)
+  })
+
+  it("should return undefined when no default stamp available", async () => {
+    const stores = createMockStores()
+    const account = createPasskeyAccount({
+      defaultPostageStampBatchID: new BatchId(TEST_BATCH_ID_HEX),
+    })
+    ;(
+      stores.accountsStore.getAccount as ReturnType<typeof vi.fn>
+    ).mockReturnValue({
+      ...account,
+      defaultPostageStampBatchID: undefined,
+    })
+    ;(
+      stores.identitiesStore.getIdentitiesByAccount as ReturnType<typeof vi.fn>
+    ).mockReturnValue([
+      { ...createIdentity(), defaultPostageStampBatchID: undefined },
+    ])
+
+    const syncAccount = createSyncAccount({
+      bee: {} as never,
+      ...stores,
+      utilizationStore: {} as UtilizationStoreDB,
+      utilizationUploader: {
+        scheduleUpload: vi.fn().mockResolvedValue(undefined),
+      } as unknown as DebouncedUtilizationUploader,
+    })
+
+    const result = await syncAccount(TEST_ETH_ADDRESS_HEX)
+    expect(result).toBeUndefined()
+    expect(uploadCallCount).toBe(0)
+  })
+
+  it("should include SOC address in returned chunk addresses", async () => {
+    const stores = createMockStores()
+
+    const syncAccount = createSyncAccount({
+      bee: {} as never,
+      ...stores,
+      utilizationStore: {} as UtilizationStoreDB,
+      utilizationUploader: {
+        scheduleUpload: vi.fn().mockResolvedValue(undefined),
+      } as unknown as DebouncedUtilizationUploader,
+    })
+
+    const result = await syncAccount(TEST_ETH_ADDRESS_HEX)
+    expect(result).toBeDefined()
+    expect(result!.status).toBe("success")
+    if (result!.status !== "success") return
+
+    // Last address should be the SOC address from epoch feed update
+    const lastAddress = result.chunkAddresses[result.chunkAddresses.length - 1]
+    expect(lastAddress).toEqual(FAKE_SOC_ADDRESS)
+  })
+})