@snaha/swarm-id 0.0.1

package/src/schemas.ts

@@ -0,0 +1,299 @@
+/**
+ * Entity Schemas with Zod
+ *
+ * Defines Zod schemas for storage entities with transforms to convert
+ * serialized primitives to bee-js runtime types. Types are derived using
+ * z.infer to guarantee schema/type consistency.
+ */
+
+import { z } from "zod"
+import {
+  EthAddress,
+  BatchId as BeeBatchId,
+  Bytes,
+  PrivateKey as BeePrivateKey,
+} from "@ethersphere/bee-js"
+
+// ============================================================================
+// Network Settings Constants
+// ============================================================================
+
+export const DEFAULT_BEE_NODE_URL = "https://api.gateway.ethswarm.org/"
+export const DEFAULT_GNOSIS_RPC_URL = "https://xdai.fairdatasociety.org/"
+
+// ============================================================================
+// Base Validation Schemas (hex strings, no transforms)
+// ============================================================================
+
+const hexString = (length: number) =>
+  z.string().regex(new RegExp(`^[0-9a-fA-F]{${length}}$`), {
+    message: `Must be a ${length}-character hex string`,
+  })
+
+// Support both regular (32-byte = 64 hex chars) and encrypted (64-byte = 128 hex chars) references
+export const ReferenceSchema = z
+  .string()
+  .regex(/^[0-9a-fA-F]{64}$|^[0-9a-fA-F]{128}$/, {
+    message:
+      "Reference must be 64 hex chars (32 bytes) or 128 hex chars (64 bytes for encrypted)",
+  })
+export const BatchIdSchema = hexString(64) // 32 bytes
+export const AddressSchema = hexString(40) // 20 bytes
+export const PrivateKeySchema = hexString(64) // 32 bytes
+export const EncryptionKeySchema = hexString(64) // 32 bytes symmetric key
+export const IdentifierSchema = hexString(64) // 32 bytes
+export const SignatureSchema = hexString(130) // 65 bytes
+export const TimestampSchema = z.preprocess(
+  (val) => (typeof val === "bigint" ? val.toString() : val),
+  z.union([z.number(), z.string()]),
+)
+export const FeedIndexSchema = z.preprocess(
+  (val) => (typeof val === "bigint" ? val.toString() : val),
+  z.union([z.number(), z.string()]),
+)
+
+export type Reference = z.infer<typeof ReferenceSchema>
+export type BatchId = z.infer<typeof BatchIdSchema>
+export type Address = z.infer<typeof AddressSchema>
+export type PrivateKey = z.infer<typeof PrivateKeySchema>
+export type Identifier = z.infer<typeof IdentifierSchema>
+export type Signature = z.infer<typeof SignatureSchema>
+export type Timestamp = z.infer<typeof TimestampSchema>
+export type FeedIndex = z.infer<typeof FeedIndexSchema>
+
+// ============================================================================
+// Primitive → bee-js Type Transforms (internal, for entity schemas)
+// ============================================================================
+
+/**
+ * Schema for EthAddress - validates 40-char hex string, transforms to EthAddress
+ */
+const StoredEthAddress = z
+  .string()
+  .length(40)
+  .transform((s) => new EthAddress(s))
+
+/**
+ * Schema for BatchId - validates 64-char hex string, transforms to BatchId
+ */
+const StoredBatchId = z
+  .string()
+  .length(64)
+  .transform((s) => new BeeBatchId(s))
+
+/**
+ * Schema for PrivateKey - validates 64-char hex string, transforms to PrivateKey
+ */
+const StoredPrivateKey = z
+  .string()
+  .length(64)
+  .transform((s) => new BeePrivateKey(s))
+
+/**
+ * Schema for Bytes - validates number array, transforms to Bytes
+ */
+const StoredBytes = z
+  .array(z.number())
+  .transform((arr) => new Bytes(new Uint8Array(arr)))
+
+// ============================================================================
+// Account Schemas
+// ============================================================================
+
+/**
+ * Passkey Account Schema V1
+ */
+export const PasskeyAccountSchemaV1 = z.object({
+  id: StoredEthAddress,
+  name: z.string(),
+  createdAt: z.number(),
+  type: z.literal("passkey"),
+  credentialId: z.string(),
+  swarmEncryptionKey: z.string().length(64), // NEW: derived encryption key for Swarm data (64-char hex)
+  defaultPostageStampBatchID: StoredBatchId.optional(), // NEW: account default stamp
+})
+
+/**
+ * Ethereum Account Schema V1
+ */
+export const EthereumAccountSchemaV1 = z.object({
+  id: StoredEthAddress,
+  name: z.string(),
+  createdAt: z.number(),
+  type: z.literal("ethereum"),
+  ethereumAddress: StoredEthAddress,
+  encryptedMasterKey: StoredBytes,
+  encryptionSalt: StoredBytes,
+  encryptedSecretSeed: StoredBytes, // Encrypted secret seed for later retrieval
+  swarmEncryptionKey: z.string().length(64), // NEW: derived encryption key for Swarm data (64-char hex)
+  defaultPostageStampBatchID: StoredBatchId.optional(), // NEW: account default stamp
+})
+
+/**
+ * Agent Account Schema V1
+ * For automated testing and programmatic use with BIP39 seed phrases
+ * Seed phrase is NOT stored - must be re-entered on each authentication (like passkey)
+ */
+export const AgentAccountSchemaV1 = z.object({
+  id: StoredEthAddress,
+  name: z.string(),
+  createdAt: z.number(),
+  type: z.literal("agent"),
+  swarmEncryptionKey: z.string().length(64), // derived encryption key for Swarm data (64-char hex)
+  defaultPostageStampBatchID: StoredBatchId.optional(),
+})
+
+/**
+ * Account Schema V1 (discriminated union)
+ */
+export const AccountSchemaV1 = z.discriminatedUnion("type", [
+  PasskeyAccountSchemaV1,
+  EthereumAccountSchemaV1,
+  AgentAccountSchemaV1,
+])
+
+// ============================================================================
+// Identity Schema
+// ============================================================================
+
+/**
+ * Identity Schema V1
+ */
+export const IdentitySchemaV1 = z.object({
+  id: AddressSchema,
+  accountId: StoredEthAddress,
+  name: z.string(),
+  defaultPostageStampBatchID: StoredBatchId.optional(),
+  createdAt: z.number(),
+  settings: z
+    .object({
+      appSessionDuration: z.number().optional(),
+    })
+    .optional(),
+})
+
+// ============================================================================
+// Connected App Schema
+// ============================================================================
+
+/**
+ * Connected App Schema V1 (no transforms needed - all primitives)
+ */
+export const ConnectedAppSchemaV1 = z.object({
+  appUrl: z.string(),
+  appName: z.string(),
+  lastConnectedAt: z.number(),
+  identityId: z.string(),
+  appIcon: z.string().optional(),
+  appDescription: z.string().optional(),
+  connectedUntil: z.number().optional(),
+  appSecret: z.string().optional(),
+})
+
+// ============================================================================
+// Postage Stamp Schema
+// ============================================================================
+
+/**
+ * Postage Stamp Schema V1
+ */
+export const PostageStampSchemaV1 = z.object({
+  accountId: z.string().length(40), // CHANGED: was identityId
+  batchID: StoredBatchId,
+  signerKey: StoredPrivateKey,
+  utilization: z.number(),
+  usable: z.boolean(),
+  depth: z.number(),
+  amount: z.string().transform((val) => BigInt(val)),
+  bucketDepth: z.number(),
+  blockNumber: z.number(),
+  immutableFlag: z.boolean(),
+  exists: z.boolean(),
+  batchTTL: z.number().optional(),
+  createdAt: z.number(),
+})
+
+// ============================================================================
+// Sync State Snapshot Schemas
+// ============================================================================
+
+/**
+ * Account Metadata Schema V1
+ */
+export const AccountMetadataSchemaV1 = z.object({
+  accountName: z.string(),
+  defaultPostageStampBatchID: z.string().length(64).optional(), // BatchId hex string
+  createdAt: z.number(),
+  lastModified: z.number(),
+})
+
+const ACCOUNT_STATE_SNAPSHOT_VERSION = 1
+
+/**
+ * Unified account state snapshot schema used by both file export and Swarm sync.
+ * Contains minimal metadata instead of the full Account object.
+ */
+export const AccountStateSnapshotSchemaV1 = z.object({
+  version: z.literal(ACCOUNT_STATE_SNAPSHOT_VERSION),
+  timestamp: z.number(),
+  accountId: z.string().length(40),
+  metadata: AccountMetadataSchemaV1,
+  identities: z.array(IdentitySchemaV1),
+  connectedApps: z.array(ConnectedAppSchemaV1),
+  postageStamps: z.array(PostageStampSchemaV1),
+})
+
+// ============================================================================
+// Derived Types (guaranteed to match current schema version)
+// ============================================================================
+
+export type PasskeyAccount = z.infer<typeof PasskeyAccountSchemaV1>
+export type EthereumAccount = z.infer<typeof EthereumAccountSchemaV1>
+export type AgentAccount = z.infer<typeof AgentAccountSchemaV1>
+export type Account = z.infer<typeof AccountSchemaV1>
+export type Identity = z.infer<typeof IdentitySchemaV1>
+export type ConnectedApp = z.infer<typeof ConnectedAppSchemaV1>
+export type PostageStamp = z.infer<typeof PostageStampSchemaV1>
+export type AccountMetadata = z.infer<typeof AccountMetadataSchemaV1>
+export type AccountStateSnapshot = z.infer<typeof AccountStateSnapshotSchemaV1>
+
+// ============================================================================
+// Network Settings Schema
+// ============================================================================
+
+/**
+ * Network Settings Schema V1
+ * Stores user-configurable network endpoints (Bee node and Gnosis RPC)
+ */
+export const NetworkSettingsSchemaV1 = z.object({
+  beeNodeUrl: z.string().url(),
+  gnosisRpcUrl: z.string().url(),
+})
+
+export type NetworkSettings = z.infer<typeof NetworkSettingsSchemaV1>
+
+// ============================================================================
+// BroadcastChannel Message Schemas
+// ============================================================================
+
+/**
+ * Bucket update entry for cross-tab synchronization
+ */
+export const BucketUpdateSchema = z.object({
+  index: z.number().int().min(0).max(65535),
+  value: z.number().int().min(0),
+})
+
+/**
+ * Utilization update message sent via BroadcastChannel
+ */
+export const UtilizationUpdateMessageSchema = z.object({
+  type: z.literal("utilization-updated"),
+  batchId: z.string().length(64),
+  buckets: z.array(BucketUpdateSchema),
+})
+
+export type BucketUpdate = z.infer<typeof BucketUpdateSchema>
+export type UtilizationUpdateMessage = z.infer<
+  typeof UtilizationUpdateMessageSchema
+>

package/src/storage/debounced-uploader.ts

@@ -0,0 +1,192 @@
+/**
+ * Debounced Utilization Uploader
+ *
+ * Batches multiple utilization updates together to minimize upload frequency.
+ * Uses a per-batch debounce mechanism with configurable delay.
+ */
+
+import type { DirtyChunkTracker } from "../utils/batch-utilization"
+
+/**
+ * Default debounce delay in milliseconds
+ */
+const DEFAULT_DEBOUNCE_DELAY_MS = 1000
+
+/**
+ * Pending upload task for a batch
+ */
+interface PendingUpload {
+  /** Dirty chunk tracker accumulating changes */
+  tracker: DirtyChunkTracker
+
+  /** Timer ID for debounce */
+  timerId: ReturnType<typeof setTimeout> | undefined
+
+  /** Upload function to execute */
+  uploadFn: () => Promise<void>
+
+  /** Promise resolvers for awaiting completion */
+  promise: { resolve: () => void; reject: (error: Error) => void }
+}
+
+/**
+ * Debounced uploader for batch utilization data
+ *
+ * Batches multiple updates within a time window and uploads only once.
+ * Each batch has its own independent debounce timer.
+ */
+export class DebouncedUtilizationUploader {
+  private pendingUploads = new Map<string, PendingUpload>()
+  private defaultDelay: number
+
+  /**
+   * Create a new debounced uploader
+   * @param delay - Debounce delay in milliseconds (default: 1000ms = 1s)
+   */
+  constructor(delay = DEFAULT_DEBOUNCE_DELAY_MS) {
+    this.defaultDelay = delay
+  }
+
+  /**
+   * Schedule an upload for a batch (debounced)
+   *
+   * If multiple updates occur within the debounce window, they are merged
+   * and only one upload is performed.
+   *
+   * @param batchId - Batch ID (hex string)
+   * @param tracker - Dirty chunk tracker with current changes
+   * @param uploadFn - Function to execute upload
+   * @param delay - Optional custom delay for this upload
+   * @returns Promise that resolves when upload completes
+   */
+  scheduleUpload(
+    batchId: string,
+    tracker: DirtyChunkTracker,
+    uploadFn: () => Promise<void>,
+    delay?: number,
+  ): Promise<void> {
+    const actualDelay = delay ?? this.defaultDelay
+
+    // Cancel existing timer if present
+    const existing = this.pendingUploads.get(batchId)
+    if (existing?.timerId) {
+      clearTimeout(existing.timerId)
+      // Reject old promise
+      existing.promise.reject(new Error("Upload cancelled by new request"))
+    }
+
+    // Merge with existing tracker or create new
+    const mergedTracker = existing?.tracker ?? tracker
+
+    // If we're merging with an existing tracker, copy dirty chunks
+    if (existing && existing.tracker !== tracker) {
+      for (const chunkIndex of tracker.getDirtyChunks()) {
+        mergedTracker.markDirty(chunkIndex * 1024) // Mark any bucket in the chunk
+      }
+    }
+
+    // Create new promise
+    return new Promise<void>((resolve, reject) => {
+      // Schedule new upload
+      const timerId = setTimeout(async () => {
+        try {
+          await uploadFn()
+          resolve()
+        } catch (error) {
+          console.error(
+            `[DebouncedUploader] Upload failed for batch ${batchId}:`,
+            error,
+          )
+          reject(error instanceof Error ? error : new Error(String(error)))
+        } finally {
+          // Remove from pending
+          this.pendingUploads.delete(batchId)
+        }
+      }, actualDelay)
+
+      // Store pending upload
+      this.pendingUploads.set(batchId, {
+        tracker: mergedTracker,
+        timerId,
+        uploadFn,
+        promise: { resolve, reject },
+      })
+    })
+  }
+
+  /**
+   * Flush pending upload for a batch immediately (cancel debounce)
+   * @param batchId - Batch ID to flush
+   */
+  async flush(batchId: string): Promise<void> {
+    const pending = this.pendingUploads.get(batchId)
+    if (!pending) {
+      return
+    }
+
+    // Cancel timer
+    if (pending.timerId) {
+      clearTimeout(pending.timerId)
+    }
+
+    // Execute immediately
+    try {
+      await pending.uploadFn()
+    } finally {
+      this.pendingUploads.delete(batchId)
+    }
+  }
+
+  /**
+   * Flush all pending uploads immediately
+   */
+  async flushAll(): Promise<void> {
+    const batchIds = Array.from(this.pendingUploads.keys())
+
+    await Promise.all(batchIds.map((batchId) => this.flush(batchId)))
+  }
+
+  /**
+   * Cancel pending upload for a batch (discard changes)
+   * @param batchId - Batch ID to cancel
+   */
+  cancel(batchId: string): void {
+    const pending = this.pendingUploads.get(batchId)
+    if (!pending) {
+      return
+    }
+
+    if (pending.timerId) {
+      clearTimeout(pending.timerId)
+    }
+
+    this.pendingUploads.delete(batchId)
+  }
+
+  /**
+   * Cancel all pending uploads (discard all changes)
+   */
+  cancelAll(): void {
+    for (const pending of this.pendingUploads.values()) {
+      if (pending.timerId) {
+        clearTimeout(pending.timerId)
+      }
+    }
+
+    this.pendingUploads.clear()
+  }
+
+  /**
+   * Get count of pending uploads
+   */
+  getPendingCount(): number {
+    return this.pendingUploads.size
+  }
+
+  /**
+   * Check if a batch has a pending upload
+   */
+  hasPending(batchId: string): boolean {
+    return this.pendingUploads.has(batchId)
+  }
+}