@snaha/swarm-id 0.0.1

package/src/index.ts

@@ -0,0 +1,430 @@
+/**
+ * Swarm ID Library
+ *
+ * A TypeScript library for integrating Swarm ID authentication
+ * and Bee API operations into dApps.
+ */
+
+// Main client for parent windows
+export { SwarmIdClient } from "./swarm-id-client"
+
+// Proxy for iframe
+export { SwarmIdProxy, initProxy } from "./swarm-id-proxy"
+
+// Key derivation utilities
+export {
+  deriveSecret,
+  deriveIdentityKey,
+  generateMasterKey,
+  hexToUint8Array,
+  uint8ArrayToHex,
+  verifySecret,
+  utils,
+} from "./utils/key-derivation"
+
+// Hex address utility
+export { hexAddress } from "./utils/hex"
+
+// Batch utilization tracking
+export {
+  initializeBatchUtilization,
+  calculateUtilizationUpdate,
+  updateAfterWrite,
+  saveUtilizationState,
+  loadUtilizationState,
+  calculateUtilization,
+  toBucket,
+  assignChunksToBuckets,
+  serializeUint32Array,
+  deserializeUint32Array,
+  splitIntoChunks,
+  reconstructFromChunks,
+  calculateMaxSlotsPerBucket,
+  hasBucketCapacity,
+  createStamper,
+  prepareBucketState,
+  UtilizationAwareStamper,
+  NUM_BUCKETS,
+  BUCKET_DEPTH,
+  UTILIZATION_SLOTS_PER_BUCKET,
+  DATA_COUNTER_START,
+  CHUNK_SIZE,
+  DEFAULT_BATCH_DEPTH,
+} from "./utils/batch-utilization"
+
+// Utilization storage (IndexedDB cache)
+export {
+  UtilizationStoreDB,
+  evictOldEntries,
+  calculateContentHash,
+} from "./storage/utilization-store"
+
+export type {
+  ChunkCacheEntry,
+  BatchMetadata,
+  CacheEvictionPolicy,
+} from "./storage/utilization-store"
+
+// Debounced utilization uploader
+export { DebouncedUtilizationUploader } from "./storage/debounced-uploader"
+
+// Versioned storage utilities
+export {
+  VersionedStorageManager,
+  LocalStorageAdapter,
+  MemoryStorageAdapter,
+  createLocalStorageManager,
+  createMemoryStorageManager,
+  createZodParser,
+  VersionedStorageSchema,
+} from "./utils/versioned-storage"
+
+// Storage managers for entities
+export {
+  createAccountsStorageManager,
+  createIdentitiesStorageManager,
+  createConnectedAppsStorageManager,
+  createPostageStampsStorageManager,
+  createNetworkSettingsStorageManager,
+  serializeAccount,
+  serializeIdentity,
+  serializeConnectedApp,
+  serializePostageStamp,
+  serializeNetworkSettings,
+  disconnectApp,
+} from "./utils/storage-managers"
+
+// Storage manager types
+export type { NetworkSettingsStorageManager } from "./utils/storage-managers"
+
+// Account state snapshot (shared by file export and Swarm sync)
+export {
+  serializeAccountStateSnapshot,
+  deserializeAccountStateSnapshot,
+  AccountStateSnapshotSchemaV1,
+} from "./utils/account-state-snapshot"
+
+export type {
+  AccountStateSnapshot,
+  AccountStateSnapshotResult,
+} from "./utils/account-state-snapshot"
+
+// Encrypted backup (.swarmid) support
+export {
+  deriveBackupEncryptionKey,
+  encryptBackupPayload,
+  decryptBackupPayload,
+  buildBackupHeader,
+  createEncryptedExport,
+  decryptEncryptedExport,
+  parseEncryptedExportHeader,
+  PasskeyBackupHeaderSchemaV1,
+  EthereumBackupHeaderSchemaV1,
+  AgentBackupHeaderSchemaV1,
+  EncryptedSwarmIdExportSchemaV1,
+} from "./utils/backup-encryption"
+
+export type {
+  PasskeyBackupHeader,
+  EthereumBackupHeader,
+  AgentBackupHeader,
+  EncryptedSwarmIdExport,
+  BackupHeaderWithoutCiphertext,
+  ParseHeaderResult,
+} from "./utils/backup-encryption"
+
+// Epoch-based feeds - implementations
+export {
+  EpochIndex,
+  SyncEpochFinder,
+  AsyncEpochFinder,
+  BasicEpochUpdater,
+  lca,
+  next,
+  createSyncEpochFinder,
+  createAsyncEpochFinder,
+  createEpochUpdater,
+  createEpochFinder, // deprecated alias for createSyncEpochFinder
+  MAX_LEVEL,
+} from "./proxy/feeds/epochs"
+
+// State sync to Swarm
+export {
+  // Account-level key derivation
+  deriveAccountBackupKey,
+  deriveAccountSwarmEncryptionKey,
+  backupKeyToPrivateKey,
+  serializeAccountState,
+  deserializeAccountState,
+  // Sync account
+  createSyncAccount,
+  ACCOUNT_SYNC_TOPIC_PREFIX,
+  // Restore account from Swarm
+  restoreAccountFromSwarm,
+} from "./sync"
+
+// State sync types
+export type {
+  SyncResult,
+  // Sync account types
+  SyncAccountOptions,
+  SyncAccountFunction,
+  // Store interfaces
+  AccountsStoreInterface,
+  IdentitiesStoreInterface,
+  ConnectedAppsStoreInterface,
+  PostageStampsStoreInterface,
+  StamperOptions,
+  FlushableStamper,
+  // Restore account types
+  RestoreAccountResult,
+} from "./sync"
+
+// Type exports
+export type {
+  ClientOptions,
+  AuthStatus,
+  ButtonStyles,
+  UploadResult,
+  FileData,
+  PostageBatch,
+  UploadOptions,
+  ActUploadOptions,
+  SOCReader,
+  SOCWriter,
+  SingleOwnerChunk,
+  SocUploadResult,
+  SocRawUploadResult,
+  FeedReaderOptions,
+  FeedWriterOptions,
+  FeedReader,
+  FeedWriter,
+  SequentialFeedReaderOptions,
+  SequentialFeedWriterOptions,
+  SequentialFeedUpdateOptions,
+  SequentialFeedUploadOptions,
+  SequentialFeedPayloadResult,
+  SequentialFeedReferenceResult,
+  SequentialFeedUploadResult,
+  SequentialFeedReader,
+  SequentialFeedWriter,
+  UploadProgress,
+  RequestOptions,
+  DownloadOptions,
+  ParentToIframeMessage,
+  IframeToParentMessage,
+  PopupToIframeMessage,
+  SetSecretMessage,
+  AuthData,
+  AppMetadata,
+  ButtonConfig,
+  ConnectionInfo,
+  // ACT message types
+  ActUploadDataMessage,
+  ActDownloadDataMessage,
+  ActAddGranteesMessage,
+  ActRevokeGranteesMessage,
+  ActGetGranteesMessage,
+  ActUploadDataResponseMessage,
+  ActDownloadDataResponseMessage,
+  ActAddGranteesResponseMessage,
+  ActRevokeGranteesResponseMessage,
+  ActGetGranteesResponseMessage,
+  SocUploadMessage,
+  SocRawUploadMessage,
+  SocDownloadMessage,
+  SocRawDownloadMessage,
+  SocGetOwnerMessage,
+  EpochFeedDownloadReferenceMessage,
+  EpochFeedUploadReferenceMessage,
+  FeedGetOwnerMessage,
+  SequentialFeedGetOwnerMessage,
+  SequentialFeedDownloadPayloadMessage,
+  SequentialFeedDownloadRawPayloadMessage,
+  SequentialFeedDownloadReferenceMessage,
+  SequentialFeedUploadPayloadMessage,
+  SequentialFeedUploadRawPayloadMessage,
+  SequentialFeedUploadReferenceMessage,
+  SocUploadResponseMessage,
+  SocRawUploadResponseMessage,
+  SocDownloadResponseMessage,
+  SocRawDownloadResponseMessage,
+  SocGetOwnerResponseMessage,
+  EpochFeedDownloadReferenceResponseMessage,
+  EpochFeedUploadReferenceResponseMessage,
+  FeedGetOwnerResponseMessage,
+  SequentialFeedGetOwnerResponseMessage,
+  SequentialFeedDownloadPayloadResponseMessage,
+  SequentialFeedDownloadRawPayloadResponseMessage,
+  SequentialFeedDownloadReferenceResponseMessage,
+  SequentialFeedUploadPayloadResponseMessage,
+  SequentialFeedUploadRawPayloadResponseMessage,
+  SequentialFeedUploadReferenceResponseMessage,
+} from "./types"
+
+// Entity types from schemas
+export type {
+  Account,
+  PasskeyAccount,
+  EthereumAccount,
+  AgentAccount,
+  Identity,
+  ConnectedApp,
+  PostageStamp,
+  AccountMetadata,
+  NetworkSettings,
+} from "./schemas"
+
+// Network settings constants and schema
+export {
+  DEFAULT_BEE_NODE_URL,
+  DEFAULT_GNOSIS_RPC_URL,
+  NetworkSettingsSchemaV1,
+} from "./schemas"
+
+// Base validation schemas and types
+export {
+  ReferenceSchema,
+  BatchIdSchema,
+  AddressSchema,
+  PrivateKeySchema,
+  EncryptionKeySchema,
+  IdentifierSchema,
+  SignatureSchema,
+  TimestampSchema,
+  FeedIndexSchema,
+} from "./schemas"
+export type {
+  Reference,
+  BatchId,
+  Address,
+  PrivateKey,
+  Identifier,
+  Signature,
+  Timestamp,
+  FeedIndex,
+} from "./schemas"
+
+// Batch utilization types
+export type {
+  BatchUtilizationState,
+  ChunkWithBucket,
+  UtilizationUpdate,
+} from "./utils/batch-utilization"
+
+// Versioned storage types
+export type {
+  VersionedStorage,
+  StorageAdapter,
+  VersionParser,
+  Serializer,
+  VersionedStorageOptions,
+} from "./utils/versioned-storage"
+
+// Epoch feed types
+export type {
+  Epoch,
+  EpochFinder,
+  EpochUpdater,
+  EpochFeedOptions,
+  EpochFeedWriterOptions,
+  EpochLookupResult,
+} from "./proxy/feeds/epochs"
+
+// Schema exports (for validation)
+export {
+  UploadOptionsSchema,
+  ActUploadOptionsSchema,
+  RequestOptionsSchema,
+  DownloadOptionsSchema,
+  UploadResultSchema,
+  FileDataSchema,
+  PostageBatchSchema,
+  AuthStatusSchema,
+  ButtonStylesSchema,
+  ParentToIframeMessageSchema,
+  IframeToParentMessageSchema,
+  PopupToIframeMessageSchema,
+  SetSecretMessageSchema,
+  AuthDataSchema,
+  // ACT message schemas
+  ActUploadDataMessageSchema,
+  ActDownloadDataMessageSchema,
+  ActAddGranteesMessageSchema,
+  ActRevokeGranteesMessageSchema,
+  ActGetGranteesMessageSchema,
+  ActUploadDataResponseMessageSchema,
+  ActDownloadDataResponseMessageSchema,
+  ActAddGranteesResponseMessageSchema,
+  ActRevokeGranteesResponseMessageSchema,
+  ActGetGranteesResponseMessageSchema,
+} from "./types"
+
+// Download data utility
+export { downloadDataWithChunkAPI } from "./proxy/download-data"
+
+// ACT (Access Control Tries) exports
+export {
+  createActForContent,
+  decryptActReference,
+  addGranteesToAct,
+  revokeGranteesFromAct,
+  getGranteesFromAct,
+  parseCompressedPublicKey,
+  publicKeyFromPrivate,
+  compressPublicKey,
+  publicKeyFromCompressed,
+} from "./proxy/act"
+
+export type { ActEntry } from "./proxy/act"
+
+// Constant exports
+export { SWARM_SECRET_PREFIX, STORAGE_CHALLENGE_KEY } from "./types"
+
+// URL building utilities
+export { buildAuthUrl } from "./utils/url"
+
+// Manifest builder utilities for /bzz/ feed compatibility
+export {
+  buildBzzCompatibleManifest,
+  buildBzzManifestNode,
+  buildMinimalManifest,
+  extractReferenceFromManifest,
+  extractEntryFromManifest,
+  extractContentFromFlatManifest,
+  padPayloadForSOCDetection,
+  MAX_PADDED_PAYLOAD_SIZE,
+} from "./proxy/manifest-builder"
+
+export type {
+  BzzCompatibleManifestResult,
+  BzzManifestNodeResult,
+} from "./proxy/manifest-builder"
+
+// Mantaray tree utilities for recursive upload/download
+export {
+  saveMantarayTreeRecursively,
+  loadMantarayTreeWithChunkAPI,
+} from "./proxy/mantaray"
+
+export type { UploadCallback } from "./proxy/mantaray"
+
+// Time and session constants
+export {
+  SECOND,
+  MINUTE,
+  HOUR,
+  DAY,
+  DEFAULT_SESSION_DURATION,
+} from "./utils/constants"
+
+// TTL calculation and formatting utilities
+export {
+  calculateTTLSeconds,
+  formatTTL,
+  getBlockTimestamp,
+  calculateExpiryTimestamp,
+  fetchSwarmPrice,
+  SWARMSCAN_STATS_URL,
+  GNOSIS_BLOCK_TIME,
+} from "./utils/ttl"

package/src/proxy/act/act.test.ts

@@ -0,0 +1,278 @@
+/**
+ * Unit tests for ACT data structure and serialization (Bee-compatible Simple Manifest JSON format)
+ */
+
+import { describe, it, expect } from "vitest"
+import {
+  serializeAct,
+  deserializeAct,
+  findEntryByLookupKey,
+  publicKeysEqual,
+  type ActEntry,
+} from "./act"
+import { publicKeyFromPrivate } from "./crypto"
+
+// Helper to create a random 32-byte array
+function randomBytes(length: number): Uint8Array {
+  const bytes = new Uint8Array(length)
+  crypto.getRandomValues(bytes)
+  return bytes
+}
+
+// Helper to create a test public key
+function createTestPublicKey(seed: number): { x: Uint8Array; y: Uint8Array } {
+  const privKey = new Uint8Array(32)
+  privKey[31] = seed
+  return publicKeyFromPrivate(privKey)
+}
+
+// Helper to convert bytes to hex
+function toHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+}
+
+describe("serializeAct/deserializeAct (Bee-compatible Simple Manifest JSON format)", () => {
+  it("should serialize and deserialize single entry", () => {
+    const lookupKey = randomBytes(32)
+    const encryptedAccessKey = randomBytes(32)
+
+    const entries: ActEntry[] = [{ lookupKey, encryptedAccessKey }]
+
+    const serialized = serializeAct(entries)
+    const deserialized = deserializeAct(serialized)
+
+    expect(deserialized.length).toBe(1)
+    expect(deserialized[0].lookupKey).toEqual(lookupKey)
+    expect(deserialized[0].encryptedAccessKey).toEqual(encryptedAccessKey)
+  })
+
+  it("should handle multiple entries", () => {
+    const entries: ActEntry[] = []
+
+    for (let i = 0; i < 5; i++) {
+      entries.push({
+        lookupKey: randomBytes(32),
+        encryptedAccessKey: randomBytes(32),
+      })
+    }
+
+    const serialized = serializeAct(entries)
+    const deserialized = deserializeAct(serialized)
+
+    expect(deserialized.length).toBe(5)
+  })
+
+  it("should handle zero entries", () => {
+    const entries: ActEntry[] = []
+
+    const serialized = serializeAct(entries)
+    const deserialized = deserializeAct(serialized)
+
+    expect(deserialized.length).toBe(0)
+  })
+
+  it("should produce valid JSON format", () => {
+    const lookupKey = randomBytes(32)
+    const encryptedAccessKey = randomBytes(32)
+
+    const entries: ActEntry[] = [{ lookupKey, encryptedAccessKey }]
+
+    const serialized = serializeAct(entries)
+
+    // Should be valid JSON
+    const json = new TextDecoder().decode(serialized)
+    const parsed = JSON.parse(json)
+
+    // Should have entries object
+    expect(parsed).toHaveProperty("entries")
+    expect(typeof parsed.entries).toBe("object")
+
+    // Entry key should be hex-encoded lookup key
+    const lookupKeyHex = toHex(lookupKey)
+    expect(parsed.entries).toHaveProperty(lookupKeyHex)
+
+    // Entry value should have reference (hex-encoded encrypted access key)
+    expect(parsed.entries[lookupKeyHex]).toHaveProperty("reference")
+    expect(parsed.entries[lookupKeyHex].reference).toBe(
+      toHex(encryptedAccessKey),
+    )
+  })
+
+  it("should handle entries with same lookup key (last wins)", () => {
+    const lookupKey = randomBytes(32)
+    const encryptedAccessKey1 = randomBytes(32)
+    const encryptedAccessKey2 = randomBytes(32)
+
+    // Two entries with same lookup key
+    const entries: ActEntry[] = [
+      { lookupKey, encryptedAccessKey: encryptedAccessKey1 },
+      { lookupKey, encryptedAccessKey: encryptedAccessKey2 },
+    ]
+
+    const serialized = serializeAct(entries)
+    const deserialized = deserializeAct(serialized)
+
+    // Should only have one entry (second overwrites first)
+    expect(deserialized.length).toBe(1)
+    expect(deserialized[0].encryptedAccessKey).toEqual(encryptedAccessKey2)
+  })
+
+  it("should produce Bee-compatible Simple Manifest structure", () => {
+    const lookupKey = new Uint8Array(32)
+    lookupKey.fill(0xaa)
+    const encryptedAccessKey = new Uint8Array(32)
+    encryptedAccessKey.fill(0xbb)
+
+    const entries: ActEntry[] = [{ lookupKey, encryptedAccessKey }]
+
+    const serialized = serializeAct(entries)
+
+    // Parse and check structure matches Bee's Simple Manifest
+    const json = new TextDecoder().decode(serialized)
+    const manifest = JSON.parse(json)
+
+    // Bee Simple Manifest format:
+    // { "entries": { "<path>": { "reference": "<hex>", "metadata": {} } } }
+    expect(manifest).toHaveProperty("entries")
+
+    const lookupKeyHex = "aa".repeat(32)
+    expect(manifest.entries).toHaveProperty(lookupKeyHex)
+    expect(manifest.entries[lookupKeyHex]).toHaveProperty("reference")
+    expect(manifest.entries[lookupKeyHex].reference).toBe("bb".repeat(32))
+    expect(manifest.entries[lookupKeyHex]).toHaveProperty("metadata")
+  })
+
+  it("should handle large number of entries", () => {
+    const numEntries = 100
+    const entries: ActEntry[] = []
+    for (let i = 0; i < numEntries; i++) {
+      entries.push({
+        lookupKey: randomBytes(32),
+        encryptedAccessKey: randomBytes(32),
+      })
+    }
+
+    const serialized = serializeAct(entries)
+    const deserialized = deserializeAct(serialized)
+
+    expect(deserialized.length).toBe(numEntries)
+  })
+
+  it("should preserve all data through serialize/deserialize cycle", () => {
+    const entries: ActEntry[] = []
+    for (let i = 0; i < 10; i++) {
+      entries.push({
+        lookupKey: randomBytes(32),
+        encryptedAccessKey: randomBytes(32),
+      })
+    }
+
+    const serialized = serializeAct(entries)
+    const deserialized = deserializeAct(serialized)
+
+    expect(deserialized.length).toBe(entries.length)
+
+    // Each entry should be found
+    for (const entry of entries) {
+      const found = findEntryByLookupKey(deserialized, entry.lookupKey)
+      expect(found).toBeDefined()
+      expect(found?.encryptedAccessKey).toEqual(entry.encryptedAccessKey)
+    }
+  })
+})
+
+describe("findEntryByLookupKey", () => {
+  it("should find matching entry", () => {
+    const lookupKey1 = randomBytes(32)
+    const lookupKey2 = randomBytes(32)
+    const lookupKey3 = randomBytes(32)
+
+    const entries: ActEntry[] = [
+      { lookupKey: lookupKey1, encryptedAccessKey: randomBytes(32) },
+      { lookupKey: lookupKey2, encryptedAccessKey: randomBytes(32) },
+      { lookupKey: lookupKey3, encryptedAccessKey: randomBytes(32) },
+    ]
+
+    const found = findEntryByLookupKey(entries, lookupKey2)
+    expect(found).toBeDefined()
+    expect(found?.lookupKey).toEqual(lookupKey2)
+  })
+
+  it("should return undefined for non-matching key", () => {
+    const entries: ActEntry[] = [
+      { lookupKey: randomBytes(32), encryptedAccessKey: randomBytes(32) },
+      { lookupKey: randomBytes(32), encryptedAccessKey: randomBytes(32) },
+    ]
+
+    const notFound = findEntryByLookupKey(entries, randomBytes(32))
+    expect(notFound).toBeUndefined()
+  })
+
+  it("should return undefined for empty entries", () => {
+    const notFound = findEntryByLookupKey([], randomBytes(32))
+    expect(notFound).toBeUndefined()
+  })
+
+  it("should match exact bytes only", () => {
+    const lookupKey = new Uint8Array(32)
+    lookupKey[0] = 0x01
+    lookupKey[31] = 0xff
+
+    const entries: ActEntry[] = [
+      { lookupKey, encryptedAccessKey: randomBytes(32) },
+    ]
+
+    // Same content should match
+    const sameContent = new Uint8Array(32)
+    sameContent[0] = 0x01
+    sameContent[31] = 0xff
+    expect(findEntryByLookupKey(entries, sameContent)).toBeDefined()
+
+    // Different content should not match
+    const different = new Uint8Array(32)
+    different[0] = 0x01
+    different[31] = 0xfe // Different!
+    expect(findEntryByLookupKey(entries, different)).toBeUndefined()
+  })
+})
+
+describe("publicKeysEqual", () => {
+  it("should return true for equal public keys", () => {
+    const key1 = createTestPublicKey(30)
+    const key2 = {
+      x: new Uint8Array(key1.x),
+      y: new Uint8Array(key1.y),
+    }
+
+    expect(publicKeysEqual(key1, key2)).toBe(true)
+  })
+
+  it("should return false for different x coordinates", () => {
+    const key1 = createTestPublicKey(31)
+    const key2 = createTestPublicKey(32)
+
+    expect(publicKeysEqual(key1, key2)).toBe(false)
+  })
+
+  it("should return false for different y coordinates", () => {
+    const key1 = createTestPublicKey(33)
+    const key2 = {
+      x: new Uint8Array(key1.x), // Same x
+      y: randomBytes(32), // Different y
+    }
+
+    expect(publicKeysEqual(key1, key2)).toBe(false)
+  })
+
+  it("should return false for different lengths", () => {
+    const key1 = createTestPublicKey(34)
+    const key2 = {
+      x: new Uint8Array(16), // Wrong length
+      y: key1.y,
+    }
+
+    expect(publicKeysEqual(key1, key2)).toBe(false)
+  })
+})