@snaha/swarm-id 0.0.1

package/src/utils/constants.ts

@@ -0,0 +1,20 @@
+/**
+ * Time and Session Constants
+ *
+ * Centralized constants for time units and default session durations.
+ */
+
+// ============================================================================
+// Time Units (in milliseconds)
+// ============================================================================
+
+export const SECOND = 1_000
+export const MINUTE = 60 * SECOND
+export const HOUR = 60 * MINUTE
+export const DAY = 24 * HOUR
+
+// ============================================================================
+// Session Defaults
+// ============================================================================
+
+export const DEFAULT_SESSION_DURATION = 30 * DAY

package/src/utils/hex.ts

@@ -0,0 +1,27 @@
+/**
+ * Hex utilities
+ *
+ * Re-exports hex conversion functions from key-derivation
+ */
+
+import type { Address } from "../schemas"
+
+export { hexToUint8Array, uint8ArrayToHex } from "./key-derivation"
+
+/**
+ * Create a validated hex address string (40 lowercase hex chars).
+ * Accepts optional 0x prefix and any case.
+ *
+ * @param input - Ethereum address string (with or without 0x prefix)
+ * @returns Normalized 40-character lowercase hex string
+ * @throws {Error} If the input is not a valid 40-char hex address
+ */
+export function hexAddress(input: string): Address {
+  const clean = input.replace(/^0x/i, "").toLowerCase()
+  if (!/^[0-9a-f]{40}$/.test(clean)) {
+    throw new Error(
+      `Invalid hex address: expected 40 hex characters (with optional 0x prefix), got "${input}"`,
+    )
+  }
+  return clean
+}

package/src/utils/key-derivation.ts

@@ -0,0 +1,197 @@
+/**
+ * Swarm Identity - Key Derivation Utilities
+ *
+ * Provides cryptographic functions for deriving app-specific secrets
+ * from a master identity key.
+ */
+
+import { PrivateKey } from "@ethersphere/bee-js"
+
+/**
+ * Derive an app-specific secret from a master key and app origin
+ *
+ * Uses HMAC-SHA256 to create a deterministic, unique secret for each app.
+ * The same master key + app origin will always produce the same secret.
+ *
+ * @param masterKey - The master identity key (hex string)
+ * @param appOrigin - The app's origin (e.g., "https://swarm-app.local:8080")
+ * @returns The derived secret as a hex string
+ */
+export async function deriveSecret(
+  masterKey: string,
+  appOrigin: string,
+): Promise<string> {
+  const encoder = new TextEncoder()
+
+  // Convert master key from hex string to Uint8Array
+  const keyData = hexToUint8Array(masterKey)
+  const message = encoder.encode(appOrigin)
+
+  // Import the master key for HMAC
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  )
+
+  // Sign the app origin with the master key
+  const signature = await crypto.subtle.sign("HMAC", cryptoKey, message)
+
+  // Convert to hex string
+  const secretHex = uint8ArrayToHex(new Uint8Array(signature))
+
+  return secretHex
+}
+
+/**
+ * Generate a random master key for testing/demo purposes
+ *
+ * In production, this would be derived from a user's mnemonic or
+ * imported from an existing identity.
+ *
+ * @returns A random 32-byte key as a hex string
+ */
+export async function generateMasterKey(): Promise<string> {
+  const randomBytes = new Uint8Array(32)
+  crypto.getRandomValues(randomBytes)
+
+  const masterKey = uint8ArrayToHex(randomBytes)
+
+  return masterKey
+}
+
+/**
+ * Convert a hex string to Uint8Array
+ *
+ * @param hexString - Hex string (e.g., "deadbeef")
+ * @returns Uint8Array
+ */
+export function hexToUint8Array(hexString: string): Uint8Array {
+  // Remove any whitespace and ensure even length
+  const hex = hexString.replace(/\s/g, "")
+  if (hex.length % 2 !== 0) {
+    throw new Error("Invalid hex string: length must be even")
+  }
+
+  const bytes = new Uint8Array(hex.length / 2)
+  for (let i = 0; i < hex.length; i += 2) {
+    bytes[i / 2] = parseInt(hex.substring(i, i + 2), 16)
+  }
+
+  return bytes
+}
+
+/**
+ * Convert a Uint8Array to hex string
+ *
+ * @param bytes - Uint8Array to convert
+ * @returns Hex string (e.g., "deadbeef")
+ */
+export function uint8ArrayToHex(bytes: Uint8Array): string {
+  return Array.from(bytes)
+    .map((b) => b.toString(16).padStart(2, "0"))
+    .join("")
+}
+
+/**
+ * Verify that a derived secret matches the expected value
+ *
+ * Useful for testing.
+ *
+ * @param masterKey - Master key hex string
+ * @param appOrigin - App origin
+ * @param expectedSecret - Expected secret hex string
+ * @returns true if the derived secret matches the expected secret
+ */
+export async function verifySecret(
+  masterKey: string,
+  appOrigin: string,
+  expectedSecret: string,
+): Promise<boolean> {
+  const derived = await deriveSecret(masterKey, appOrigin)
+  return derived === expectedSecret
+}
+
+/**
+ * Derive an identity-specific master key from account master key and identity ID
+ *
+ * Uses HMAC-SHA256 to create a deterministic, unique key for each identity.
+ * This enables hierarchical key derivation: Account → Identity → App.
+ * The same account master key + identity ID will always produce the same identity key.
+ *
+ * @param accountMasterKey - The account's master key (hex string)
+ * @param identityId - The identity's unique identifier
+ * @returns The derived identity master key as a hex string
+ */
+export async function deriveIdentityKey(
+  accountMasterKey: string,
+  identityId: string,
+): Promise<string> {
+  const encoder = new TextEncoder()
+
+  // Convert account master key to Uint8Array
+  const keyData = hexToUint8Array(accountMasterKey)
+  const message = encoder.encode(identityId)
+
+  // Import the account master key for HMAC
+  const cryptoKey = await crypto.subtle.importKey(
+    "raw",
+    keyData,
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  )
+
+  // Sign the identity ID with the account master key
+  const signature = await crypto.subtle.sign("HMAC", cryptoKey, message)
+
+  // Convert to hex string
+  const identityKeyHex = uint8ArrayToHex(new Uint8Array(signature))
+
+  return identityKeyHex
+}
+
+/**
+ * Derive account backup key from account master key
+ *
+ * Used for signing account feed updates
+ *
+ * @param accountMasterKey - Account master key (hex string)
+ * @param accountId - Account ID (EthAddress hex string)
+ * @returns 32-byte account backup key (as hex string)
+ */
+export async function deriveAccountBackupKey(
+  accountMasterKey: string,
+  accountId: string,
+): Promise<string> {
+  return deriveSecret(accountMasterKey, `account:${accountId}`)
+}
+
+/**
+ * Derive account Swarm encryption key from account master key
+ *
+ * Used for encrypting account snapshot data before upload to Swarm
+ *
+ * @param accountMasterKey - Account master key (hex string)
+ * @returns 32-byte encryption key (as hex string)
+ */
+export async function deriveAccountSwarmEncryptionKey(
+  accountMasterKey: string,
+): Promise<string> {
+  return deriveSecret(accountMasterKey, `swarm-encryption`)
+}
+
+/**
+ * Convert backup key to PrivateKey for feed signing
+ */
+export function backupKeyToPrivateKey(backupKeyHex: string): PrivateKey {
+  return new PrivateKey(backupKeyHex)
+}
+
+// Export utility functions for testing
+export const utils = {
+  hexToUint8Array,
+  uint8ArrayToHex,
+}

package/src/utils/storage-managers.ts

@@ -0,0 +1,365 @@
+/**
+ * Pre-configured Storage Managers for Entity Types
+ *
+ * Provides ready-to-use storage managers for accounts, identities,
+ * connected apps, and postage stamps with versioning support.
+ */
+
+import { z } from "zod"
+import {
+  VersionedStorageManager,
+  createLocalStorageManager,
+  type VersionParser,
+} from "./versioned-storage"
+import type { Account, Identity, ConnectedApp, PostageStamp } from "../types"
+import {
+  STORAGE_KEY_ACCOUNTS,
+  STORAGE_KEY_IDENTITIES,
+  STORAGE_KEY_CONNECTED_APPS,
+  STORAGE_KEY_POSTAGE_STAMPS,
+  STORAGE_KEY_NETWORK_SETTINGS,
+} from "../types"
+import {
+  AccountSchemaV1,
+  IdentitySchemaV1,
+  ConnectedAppSchemaV1,
+  PostageStampSchemaV1,
+  NetworkSettingsSchemaV1,
+  type NetworkSettings,
+} from "../schemas"
+
+// ============================================================================
+// Parsers (Zod transforms handle primitive → bee-js conversion)
+// ============================================================================
+
+/**
+ * Parse accounts - Zod transforms handle type conversion
+ */
+const parseAccountsV1: VersionParser<Account> = (data: unknown) => {
+  const result = z.array(AccountSchemaV1).safeParse(data)
+
+  if (!result.success) {
+    console.error("Parse failed:", result.error.format())
+    return []
+  }
+
+  return result.data
+}
+
+/**
+ * Parse identities - Zod transforms handle type conversion
+ */
+const parseIdentitiesV1: VersionParser<Identity> = (data: unknown) => {
+  const result = z.array(IdentitySchemaV1).safeParse(data)
+
+  if (!result.success) {
+    console.error("Parse failed:", result.error.format())
+    return []
+  }
+
+  return result.data
+}
+
+/**
+ * Parse connected apps
+ */
+const parseConnectedAppsV1: VersionParser<ConnectedApp> = (data: unknown) => {
+  const result = z.array(ConnectedAppSchemaV1).safeParse(data)
+
+  if (!result.success) {
+    console.error("Parse failed:", result.error.format())
+    return []
+  }
+
+  return result.data
+}
+
+/**
+ * Parse postage stamps - Zod transforms handle type conversion
+ */
+const parsePostageStampsV1: VersionParser<PostageStamp> = (data: unknown) => {
+  const result = z.array(PostageStampSchemaV1).safeParse(data)
+
+  if (!result.success) {
+    console.error("Parse failed:", result.error.format())
+    return []
+  }
+
+  return result.data
+}
+
+// ============================================================================
+// Serializers
+// ============================================================================
+
+/**
+ * Serialize Account for storage
+ */
+export function serializeAccount(account: Account): Record<string, unknown> {
+  if (account.type === "passkey") {
+    return {
+      id: account.id.toString(),
+      name: account.name,
+      createdAt: account.createdAt,
+      type: account.type,
+      credentialId: account.credentialId,
+      swarmEncryptionKey: account.swarmEncryptionKey,
+      defaultPostageStampBatchID:
+        account.defaultPostageStampBatchID?.toString(),
+    }
+  } else if (account.type === "agent") {
+    return {
+      id: account.id.toString(),
+      name: account.name,
+      createdAt: account.createdAt,
+      type: account.type,
+      swarmEncryptionKey: account.swarmEncryptionKey,
+      defaultPostageStampBatchID:
+        account.defaultPostageStampBatchID?.toString(),
+    }
+  } else {
+    return {
+      id: account.id.toString(),
+      name: account.name,
+      createdAt: account.createdAt,
+      type: account.type,
+      ethereumAddress: account.ethereumAddress.toString(),
+      encryptedMasterKey: Array.from(account.encryptedMasterKey.toUint8Array()),
+      encryptionSalt: Array.from(account.encryptionSalt.toUint8Array()),
+      encryptedSecretSeed: Array.from(
+        account.encryptedSecretSeed.toUint8Array(),
+      ),
+      swarmEncryptionKey: account.swarmEncryptionKey,
+      defaultPostageStampBatchID:
+        account.defaultPostageStampBatchID?.toString(),
+    }
+  }
+}
+
+/**
+ * Serialize Identity for storage
+ */
+export function serializeIdentity(identity: Identity): Record<string, unknown> {
+  return {
+    id: identity.id,
+    accountId: identity.accountId.toString(),
+    name: identity.name,
+    defaultPostageStampBatchID: identity.defaultPostageStampBatchID?.toString(),
+    createdAt: identity.createdAt,
+    settings: identity.settings,
+  }
+}
+
+/**
+ * Serialize ConnectedApp for storage
+ */
+export function serializeConnectedApp(
+  app: ConnectedApp,
+): Record<string, unknown> {
+  return {
+    appUrl: app.appUrl,
+    appName: app.appName,
+    lastConnectedAt: app.lastConnectedAt,
+    identityId: app.identityId,
+    appIcon: app.appIcon,
+    appDescription: app.appDescription,
+    connectedUntil: app.connectedUntil,
+    appSecret: app.appSecret,
+  }
+}
+
+/**
+ * Serialize PostageStamp for storage
+ */
+export function serializePostageStamp(
+  stamp: PostageStamp,
+): Record<string, unknown> {
+  return {
+    accountId: stamp.accountId,
+    batchID: stamp.batchID.toString(),
+    signerKey: stamp.signerKey.toString(),
+    utilization: stamp.utilization,
+    usable: stamp.usable,
+    depth: stamp.depth,
+    amount: stamp.amount.toString(), // Convert bigint to string for JSON
+    bucketDepth: stamp.bucketDepth,
+    blockNumber: stamp.blockNumber,
+    immutableFlag: stamp.immutableFlag,
+    exists: stamp.exists,
+    batchTTL: stamp.batchTTL,
+    createdAt: stamp.createdAt,
+  }
+}
+
+// ============================================================================
+// Storage Manager Factories
+// ============================================================================
+
+/**
+ * Create storage manager for accounts
+ */
+export function createAccountsStorageManager(): VersionedStorageManager<Account> {
+  return createLocalStorageManager<Account>({
+    key: STORAGE_KEY_ACCOUNTS,
+    currentVersion: 1,
+    parsers: {
+      1: parseAccountsV1,
+    },
+    serializer: serializeAccount,
+    loggerName: "AccountsStorage",
+  })
+}
+
+/**
+ * Create storage manager for identities
+ */
+export function createIdentitiesStorageManager(): VersionedStorageManager<Identity> {
+  return createLocalStorageManager<Identity>({
+    key: STORAGE_KEY_IDENTITIES,
+    currentVersion: 1,
+    parsers: {
+      1: parseIdentitiesV1,
+    },
+    serializer: serializeIdentity,
+    loggerName: "IdentitiesStorage",
+  })
+}
+
+/**
+ * Create storage manager for connected apps
+ */
+export function createConnectedAppsStorageManager(): VersionedStorageManager<ConnectedApp> {
+  return createLocalStorageManager<ConnectedApp>({
+    key: STORAGE_KEY_CONNECTED_APPS,
+    currentVersion: 1,
+    parsers: {
+      1: parseConnectedAppsV1,
+    },
+    serializer: serializeConnectedApp,
+    loggerName: "ConnectedAppsStorage",
+  })
+}
+
+/**
+ * Invalidate all connected app entries for a given app URL.
+ * Sets lastConnectedAt to 0 and connectedUntil to undefined so
+ * isConnectionValid() returns false and reconnect won't happen on refresh.
+ */
+export function disconnectApp(appUrl: string): void {
+  const manager = createConnectedAppsStorageManager()
+  const apps = manager.load()
+  const updated = apps.map((app) =>
+    app.appUrl === appUrl
+      ? { ...app, lastConnectedAt: 0, connectedUntil: undefined }
+      : app,
+  )
+  manager.save(updated)
+}
+
+/**
+ * Create storage manager for postage stamps
+ */
+export function createPostageStampsStorageManager(): VersionedStorageManager<PostageStamp> {
+  return createLocalStorageManager<PostageStamp>({
+    key: STORAGE_KEY_POSTAGE_STAMPS,
+    currentVersion: 1,
+    parsers: {
+      1: parsePostageStampsV1,
+    },
+    serializer: serializePostageStamp,
+    loggerName: "PostageStampsStorage",
+  })
+}
+
+// ============================================================================
+// Network Settings Storage (Singleton)
+// ============================================================================
+
+/**
+ * Parse network settings - Zod validates URL format
+ */
+function parseNetworkSettingsV1(data: unknown): NetworkSettings | undefined {
+  const result = NetworkSettingsSchemaV1.safeParse(data)
+
+  if (!result.success) {
+    console.error(
+      "[NetworkSettingsStorage] Parse failed:",
+      result.error.format(),
+    )
+    return undefined
+  }
+
+  return result.data
+}
+
+/**
+ * Serialize NetworkSettings for storage
+ */
+export function serializeNetworkSettings(
+  settings: NetworkSettings,
+): Record<string, unknown> {
+  return {
+    beeNodeUrl: settings.beeNodeUrl,
+    gnosisRpcUrl: settings.gnosisRpcUrl,
+  }
+}
+
+/**
+ * Singleton storage manager interface for network settings
+ */
+export interface NetworkSettingsStorageManager {
+  load(): NetworkSettings | undefined
+  save(settings: NetworkSettings): void
+  clear(): void
+}
+
+/**
+ * Create storage manager for network settings (singleton)
+ * Unlike other storage managers, this stores a single object, not an array
+ */
+export function createNetworkSettingsStorageManager(): NetworkSettingsStorageManager {
+  return {
+    load(): NetworkSettings | undefined {
+      if (typeof localStorage === "undefined") {
+        return undefined
+      }
+
+      const raw = localStorage.getItem(STORAGE_KEY_NETWORK_SETTINGS)
+      if (!raw) {
+        return undefined
+      }
+
+      try {
+        const parsed = JSON.parse(raw)
+        return parseNetworkSettingsV1(parsed)
+      } catch (e) {
+        console.error(
+          "[NetworkSettingsStorage] Failed to parse stored data:",
+          e,
+        )
+        return undefined
+      }
+    },
+
+    save(settings: NetworkSettings): void {
+      if (typeof localStorage === "undefined") {
+        console.warn("[NetworkSettingsStorage] localStorage not available")
+        return
+      }
+
+      const serialized = serializeNetworkSettings(settings)
+      localStorage.setItem(
+        STORAGE_KEY_NETWORK_SETTINGS,
+        JSON.stringify(serialized),
+      )
+    },
+
+    clear(): void {
+      if (typeof localStorage === "undefined") {
+        return
+      }
+
+      localStorage.removeItem(STORAGE_KEY_NETWORK_SETTINGS)
+    },
+  }
+}