@snaha/swarm-id 0.0.1

package/dist/utils/batch-utilization.d.ts

@@ -0,0 +1,432 @@
+/**
+ * Batch Utilization Tracking for Swarm Storage
+ *
+ * This module implements utilization tracking for mutable postage batches.
+ * It manages two counter arrays:
+ * - Utilization counters (local, uint8): Track slots 0-255 per bucket for utilization chunks
+ * - Data counters (on-chain, uint32): Track slots 256+ per bucket for data chunks
+ *
+ * The system uses pre-calculation to handle the circular dependency of storing
+ * utilization data that tracks the storage of itself.
+ */
+import { Stamper, BatchId, Topic, Identifier, type Bee, EthAddress, type EnvelopeWithBatchId } from "@ethersphere/bee-js";
+import { type ContentAddressedChunk } from "../chunk";
+import { type Chunk as CafeChunk } from "cafe-utility";
+import type { UtilizationStoreDB } from "../storage/utilization-store";
+/** Number of buckets in a postage batch (2^16) */
+export declare const NUM_BUCKETS = 65536;
+/** Bucket depth parameter (determines bucket count) */
+export declare const BUCKET_DEPTH = 16;
+/** Number of slots reserved per bucket for utilization chunks (0-3) */
+export declare const UTILIZATION_SLOTS_PER_BUCKET = 4;
+/** Starting slot index for data chunks */
+export declare const DATA_COUNTER_START = 4;
+/** Size of each chunk in bytes */
+export declare const CHUNK_SIZE = 4096;
+/** Batch depth for N=256 slots per bucket with 65536 buckets */
+export declare const DEFAULT_BATCH_DEPTH = 24;
+/**
+ * Metadata for a single utilization chunk
+ */
+export interface ChunkMetadata {
+    /** Chunk index (0-63) */
+    index: number;
+    /**
+     * Content hash / CAC reference (same thing for content-addressed chunks)
+     * Empty string means never uploaded
+     */
+    contentHash: string;
+    /** Last upload timestamp */
+    lastUpload: number;
+    /** Whether this chunk needs uploading */
+    dirty: boolean;
+}
+/**
+ * Utilization state for a postage batch
+ *
+ * This new version stores utilization data as 64 chunks on Swarm
+ * with IndexedDB caching for performance.
+ */
+export interface BatchUtilizationState {
+    /** Batch ID this state belongs to */
+    batchId: BatchId;
+    /** Data counters (65,536 uint32 values) */
+    dataCounters: Uint32Array;
+    /** Metadata for each of the 64 utilization chunks */
+    chunks: ChunkMetadata[];
+    /** Topic for SOC storage */
+    topic: Topic;
+    /** Last sync timestamp */
+    lastSync: number;
+}
+/**
+ * Chunk with bucket assignment
+ */
+export interface ChunkWithBucket {
+    chunk: ContentAddressedChunk;
+    bucket: number;
+    slot: number;
+}
+/**
+ * Result of calculating utilization update
+ */
+export interface UtilizationUpdate {
+    /** Updated data counters */
+    dataCounters: Uint32Array;
+    /** Utilization chunks to upload */
+    utilizationChunks: ChunkWithBucket[];
+}
+/**
+ * Calculate which bucket a chunk belongs to based on its address.
+ * Uses the first 2 bytes of the chunk address as a big-endian uint16.
+ *
+ * This matches bee-js Stamper implementation.
+ *
+ * @param chunkAddress - The chunk's content address (32 bytes)
+ * @returns Bucket index (0-65535)
+ */
+export declare function toBucket(chunkAddress: Uint8Array): number;
+/**
+ * Calculate bucket assignments for multiple chunks
+ */
+export declare function assignChunksToBuckets(chunks: ContentAddressedChunk[]): ChunkWithBucket[];
+/**
+ * Number of utilization chunks (64 chunks of 4KB each = 262KB total)
+ * Each chunk contains 1,024 buckets (1,024 × 4 bytes = 4,096 bytes)
+ */
+export declare const NUM_UTILIZATION_CHUNKS = 64;
+export declare const BUCKETS_PER_CHUNK = 1024;
+/**
+ * Calculate which utilization chunk a bucket belongs to
+ * @param bucketIndex - Bucket index (0-65535)
+ * @returns Chunk index (0-63)
+ */
+export declare function getChunkIndexForBucket(bucketIndex: number): number;
+/**
+ * Calculate the offset of a bucket within its chunk
+ * @param bucketIndex - Bucket index (0-65535)
+ * @returns Offset within chunk (0-1023)
+ */
+export declare function getBucketOffsetInChunk(bucketIndex: number): number;
+/**
+ * Extract a 4KB chunk from the dataCounters array
+ * @param dataCounters - Full array of 65,536 counters
+ * @param chunkIndex - Index of chunk to extract (0-63)
+ * @returns 4KB Uint8Array containing serialized counters for this chunk
+ */
+export declare function extractChunk(dataCounters: Uint32Array, chunkIndex: number): Uint8Array;
+/**
+ * Merge a 4KB chunk back into the dataCounters array
+ * @param dataCounters - Full array of 65,536 counters (modified in place)
+ * @param chunkIndex - Index of chunk to merge (0-63)
+ * @param chunkData - 4KB Uint8Array containing serialized counters
+ */
+export declare function mergeChunk(dataCounters: Uint32Array, chunkIndex: number, chunkData: Uint8Array): void;
+/**
+ * Tracks which utilization chunks have been modified and need uploading
+ */
+export declare class DirtyChunkTracker {
+    private dirtyChunks;
+    constructor();
+    /**
+     * Mark a bucket as dirty (marks its containing chunk)
+     * @param bucketIndex - Bucket index (0-65535)
+     */
+    markDirty(bucketIndex: number): void;
+    /**
+     * Mark a chunk as clean (uploaded successfully)
+     * @param chunkIndex - Chunk index (0-63)
+     */
+    markClean(chunkIndex: number): void;
+    /**
+     * Get array of dirty chunk indices
+     * @returns Sorted array of chunk indices that need uploading
+     */
+    getDirtyChunks(): number[];
+    /**
+     * Check if there are any dirty chunks
+     * @returns true if there are chunks waiting to be uploaded
+     */
+    hasDirtyChunks(): boolean;
+    /**
+     * Clear all dirty markers
+     */
+    clear(): void;
+    /**
+     * Get number of dirty chunks
+     * @returns Count of chunks waiting to be uploaded
+     */
+    get count(): number;
+}
+/**
+ * Create a topic for batch utilization storage
+ * Topic format: `batch-utilization:{batchId}`
+ *
+ * @param batchId - Batch ID
+ * @returns Topic for this batch's utilization data
+ */
+export declare function makeBatchUtilizationTopic(batchId: BatchId): Topic;
+/**
+ * Create an identifier for a specific utilization chunk
+ * Identifier: Keccak256(topic || chunkIndex)
+ *
+ * @param topic - Batch utilization topic
+ * @param chunkIndex - Chunk index (0-63)
+ * @returns Identifier for this chunk
+ */
+export declare function makeChunkIdentifier(topic: Topic, chunkIndex: number): Identifier;
+/**
+ * Upload an encrypted utilization chunk to Swarm as CAC
+ *
+ * Architecture: Just upload encrypted chunk data as CAC (immutable)
+ *
+ * @param bee - Bee client instance
+ * @param batchId - Batch ID (for logging)
+ * @param postageBatchId - Postage stamp batch ID
+ * @param chunkIndex - Chunk index (0-63)
+ * @param data - Chunk data to upload (4KB)
+ * @param encryptionKey - Encryption key (32 bytes)
+ * @returns CAC reference
+ */
+export declare function uploadUtilizationChunk(bee: Bee, stamper: Stamper, chunkIndex: number, data: Uint8Array, encryptionKey: Uint8Array): Promise<Uint8Array>;
+/**
+ * Download and decrypt a utilization chunk from Swarm by CAC reference
+ *
+ * @param bee - Bee client instance
+ * @param cacReference - CAC reference (32 bytes)
+ * @param chunkIndex - Chunk index (for logging)
+ * @param encryptionKey - Encryption key (32 bytes)
+ * @returns Decrypted chunk data (4KB) or undefined if not found
+ */
+export declare function downloadUtilizationChunk(bee: Bee, cacReference: Uint8Array, chunkIndex: number, encryptionKey: Uint8Array): Promise<Uint8Array | undefined>;
+/**
+ * Serialize Uint32Array to bytes (little-endian)
+ */
+export declare function serializeUint32Array(arr: Uint32Array): Uint8Array;
+/**
+ * Deserialize bytes to Uint32Array (little-endian)
+ */
+export declare function deserializeUint32Array(bytes: Uint8Array): Uint32Array;
+/**
+ * Split data into 4KB chunks
+ */
+export declare function splitIntoChunks(data: Uint8Array): ContentAddressedChunk[];
+/**
+ * Reconstruct data from chunks
+ */
+export declare function reconstructFromChunks(chunks: ContentAddressedChunk[], originalLength: number): Uint8Array;
+/**
+ * Initialize a new batch utilization state
+ *
+ * Reserves slots 0-3 per bucket for utilization metadata chunks,
+ * and starts data chunks at slot 4 (DATA_COUNTER_START).
+ *
+ * With 65,536 buckets and ~64 utilization chunks, the probability
+ * of any bucket getting 4+ utilization chunks is negligible (< 0.0000001%).
+ */
+export declare function initializeBatchUtilization(batchId: BatchId): BatchUtilizationState;
+/**
+ * Calculate max slots per bucket based on batch depth
+ */
+export declare function calculateMaxSlotsPerBucket(batchDepth: number): number;
+/**
+ * Check if a bucket has capacity for more chunks
+ */
+export declare function hasBucketCapacity(dataCounter: number, batchDepth: number): boolean;
+/**
+ * Pre-calculate utilization update after writing data chunks.
+ *
+ * This solves the circular dependency problem:
+ * 1. Assign buckets/slots to data chunks
+ * 2. Update data counters
+ * 3. Serialize data counters into utilization chunks
+ * 4. Calculate where utilization chunks will land
+ * 5. Assign slots 0-N to utilization chunks per bucket
+ *
+ * Note: Utilization chunks always start from slot 0 since mutable stamps
+ * allow overwriting. No need to track previous positions.
+ *
+ * @param state - Current utilization state
+ * @param dataChunks - Data chunks to be written
+ * @param batchDepth - Batch depth parameter
+ * @returns Updated state and utilization chunks to upload
+ */
+export declare function calculateUtilizationUpdate(state: BatchUtilizationState, dataChunks: ContentAddressedChunk[], batchDepth: number): UtilizationUpdate;
+/**
+ * Create a Stamper with custom bucket state for mutable stamping
+ *
+ * @param privateKey - Private key for signing
+ * @param batchId - Batch ID
+ * @param bucketState - Custom bucket heights (for resuming or mutable overwrites)
+ * @param batchDepth - Batch depth parameter
+ */
+export declare function createStamper(privateKey: Uint8Array | string, batchId: BatchId, bucketState: Uint32Array, batchDepth: number): Stamper;
+/**
+ * Prepare bucket state for stamping chunks with specific slots
+ *
+ * @param chunksWithBuckets - Chunks with assigned buckets and slots
+ * @returns Bucket state array for Stamper
+ */
+export declare function prepareBucketState(chunksWithBuckets: ChunkWithBucket[]): Uint32Array;
+/**
+ * Convert utilization data counters to Stamper bucket state
+ *
+ * Each dataCounter[bucket] represents the number of slots used in that bucket.
+ * The Stamper's bucket state should start at the next available slot.
+ *
+ * @param dataCounters - Current utilization counters (65536 buckets)
+ * @returns Bucket state array for Stamper (65536 entries)
+ */
+export declare function utilizationToBucketState(dataCounters: Uint32Array): Uint32Array;
+/**
+ * Load utilization state with cache hierarchy
+ *
+ * Load order:
+ * 1. Try IndexedDB cache (all 64 chunks)
+ * 2. If incomplete, download missing chunks from Swarm
+ * 3. If not found, initialize new state
+ * 4. Cache downloaded chunks in IndexedDB
+ *
+ * @param batchId - Batch ID
+ * @param options - Load options with bee, owner, encryption key, and cache
+ * @returns Utilization state
+ */
+export declare function loadUtilizationState(batchId: BatchId, options: {
+    bee: Bee;
+    owner: EthAddress;
+    encryptionKey: Uint8Array;
+    cache: UtilizationStoreDB;
+}): Promise<BatchUtilizationState>;
+/**
+ * Save utilization state with incremental upload
+ *
+ * Only uploads dirty chunks to minimize network traffic.
+ * Updates IndexedDB cache with new chunk data.
+ *
+ * @param state - Current utilization state (modified in place)
+ * @param options - Save options
+ */
+export declare function saveUtilizationState(state: BatchUtilizationState, options: {
+    bee: Bee;
+    stamper: Stamper;
+    encryptionKey: Uint8Array;
+    cache: UtilizationStoreDB;
+    tracker: DirtyChunkTracker;
+}): Promise<void>;
+/**
+ * Update utilization state after writing data chunks
+ *
+ * This function:
+ * 1. Loads current state (from cache or Swarm)
+ * 2. Updates bucket counters for new data chunks
+ * 3. Marks affected utilization chunks as dirty
+ * 4. Returns state and tracker for later upload
+ *
+ * @param batchId - Batch ID
+ * @param dataChunks - Data chunks that were written
+ * @param batchDepth - Batch depth parameter
+ * @param options - Load options for state retrieval
+ * @returns Updated state and dirty chunk tracker
+ */
+export declare function updateAfterWrite(batchId: BatchId, dataChunks: ContentAddressedChunk[], batchDepth: number, options: {
+    bee: Bee;
+    owner: EthAddress;
+    encryptionKey: Uint8Array;
+    cache: UtilizationStoreDB;
+}): Promise<{
+    state: BatchUtilizationState;
+    tracker: DirtyChunkTracker;
+}>;
+/**
+ * Calculate current utilization fraction for a batch
+ *
+ * @param state - Current utilization state
+ * @param batchDepth - Batch depth parameter
+ * @returns Utilization as decimal fraction (0-1)
+ */
+export declare function calculateUtilization(state: BatchUtilizationState, batchDepth: number): number;
+/**
+ * Stamper wrapper that maintains bucket state from utilization data
+ *
+ * This class wraps the cafe-utility Stamper and:
+ * - Loads bucket state from cached utilization data on creation
+ * - Tracks which buckets/slots are used during stamping
+ * - Provides a flush() method to persist updates back to cache
+ *
+ * This ensures the Stamper always has accurate knowledge of which
+ * buckets/slots are already used, preventing overwrites.
+ */
+export declare class UtilizationAwareStamper implements Stamper {
+    private stamper;
+    private utilizationState;
+    private cache;
+    private dirty;
+    private dirtyBuckets;
+    readonly batchId: BatchId;
+    readonly depth: number;
+    get signer(): import("@ethersphere/bee-js").PrivateKey;
+    get buckets(): Uint32Array<ArrayBufferLike>;
+    get maxSlot(): number;
+    private constructor();
+    /**
+     * Create a UtilizationAwareStamper with bucket state from cache
+     *
+     * @param privateKey - Signer private key
+     * @param batchId - Postage batch ID
+     * @param depth - Batch depth
+     * @param cache - Utilization cache database
+     * @param _owner - Owner address (required for validation, reserved for future Swarm upload)
+     * @param _encryptionKey - Encryption key (required for validation, reserved for future Swarm upload)
+     * @returns New UtilizationAwareStamper instance
+     */
+    static create(privateKey: Uint8Array | string, batchId: BatchId, depth: number, cache: UtilizationStoreDB, _owner: EthAddress, _encryptionKey: Uint8Array): Promise<UtilizationAwareStamper>;
+    /**
+     * Stamp a chunk (implements Stamper interface)
+     *
+     * Delegates to underlying stamper and tracks which buckets are used.
+     *
+     * @param chunk - Chunk to stamp
+     * @returns Envelope with batch ID and signature
+     */
+    stamp(chunk: CafeChunk): EnvelopeWithBatchId;
+    /**
+     * Get bucket state (implements Stamper interface)
+     */
+    getState(): Uint32Array;
+    /**
+     * Flush dirty utilization chunks to cache
+     *
+     * This persists any bucket state changes made during stamping.
+     * Should be called after all stamping operations are complete.
+     */
+    flush(): Promise<void>;
+    /**
+     * Get current utilization state
+     *
+     * @returns Current utilization state
+     */
+    getUtilizationState(): BatchUtilizationState;
+    /**
+     * Apply utilization update from another tab.
+     * Updates local bucket counters to match leader's state.
+     *
+     * @param buckets Array of bucket indices and their new counter values
+     */
+    applyUtilizationUpdate(buckets: Array<{
+        index: number;
+        value: number;
+    }>): void;
+    /**
+     * Get bucket counter values for broadcasting to other tabs.
+     * Returns only the dirty buckets with their current values.
+     *
+     * IMPORTANT: Call this BEFORE flush() as flush() clears dirtyBuckets.
+     *
+     * @returns Array of bucket index/value pairs for broadcasting
+     */
+    getBucketUpdatesForBroadcast(): Array<{
+        index: number;
+        value: number;
+    }>;
+}
+//# sourceMappingURL=batch-utilization.d.ts.map

package/dist/utils/batch-utilization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"batch-utilization.d.ts","sourceRoot":"","sources":["../../src/utils/batch-utilization.ts"],"names":[],"mappings":"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"}

package/dist/utils/constants.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Time and Session Constants
+ *
+ * Centralized constants for time units and default session durations.
+ */
+export declare const SECOND = 1000;
+export declare const MINUTE: number;
+export declare const HOUR: number;
+export declare const DAY: number;
+export declare const DEFAULT_SESSION_DURATION: number;
+//# sourceMappingURL=constants.d.ts.map

package/dist/utils/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/utils/constants.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,eAAO,MAAM,MAAM,OAAQ,CAAA;AAC3B,eAAO,MAAM,MAAM,QAAc,CAAA;AACjC,eAAO,MAAM,IAAI,QAAc,CAAA;AAC/B,eAAO,MAAM,GAAG,QAAY,CAAA;AAM5B,eAAO,MAAM,wBAAwB,QAAW,CAAA"}

package/dist/utils/hex.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare function hexAddress(input: string): Address;
+//# sourceMappingURL=hex.d.ts.map

package/dist/utils/hex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hex.d.ts","sourceRoot":"","sources":["../../src/utils/hex.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEzC,OAAO,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAA;AAEnE;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAQjD"}

package/dist/utils/key-derivation.d.ts

@@ -0,0 +1,92 @@
+/**
+ * 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 declare function deriveSecret(masterKey: string, appOrigin: string): Promise<string>;
+/**
+ * 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 declare function generateMasterKey(): Promise<string>;
+/**
+ * Convert a hex string to Uint8Array
+ *
+ * @param hexString - Hex string (e.g., "deadbeef")
+ * @returns Uint8Array
+ */
+export declare function hexToUint8Array(hexString: string): Uint8Array;
+/**
+ * Convert a Uint8Array to hex string
+ *
+ * @param bytes - Uint8Array to convert
+ * @returns Hex string (e.g., "deadbeef")
+ */
+export declare function uint8ArrayToHex(bytes: Uint8Array): string;
+/**
+ * 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 declare function verifySecret(masterKey: string, appOrigin: string, expectedSecret: string): Promise<boolean>;
+/**
+ * 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 declare function deriveIdentityKey(accountMasterKey: string, identityId: string): Promise<string>;
+/**
+ * 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 declare function deriveAccountBackupKey(accountMasterKey: string, accountId: string): Promise<string>;
+/**
+ * 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 declare function deriveAccountSwarmEncryptionKey(accountMasterKey: string): Promise<string>;
+/**
+ * Convert backup key to PrivateKey for feed signing
+ */
+export declare function backupKeyToPrivateKey(backupKeyHex: string): PrivateKey;
+export declare const utils: {
+    hexToUint8Array: typeof hexToUint8Array;
+    uint8ArrayToHex: typeof uint8ArrayToHex;
+};
+//# sourceMappingURL=key-derivation.d.ts.map

package/dist/utils/key-derivation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-derivation.d.ts","sourceRoot":"","sources":["../../src/utils/key-derivation.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAEhD;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,CAAC,CAOzD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAa7D;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,UAAU,GAAG,MAAM,CAIzD;AAED;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,OAAO,CAAC,CAGlB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,iBAAiB,CACrC,gBAAgB,EAAE,MAAM,EACxB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,MAAM,CAAC,CAuBjB;AAED;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,gBAAgB,EAAE,MAAM,EACxB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;;;;;;GAOG;AACH,wBAAsB,+BAA+B,CACnD,gBAAgB,EAAE,MAAM,GACvB,OAAO,CAAC,MAAM,CAAC,CAEjB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,GAAG,UAAU,CAEtE;AAGD,eAAO,MAAM,KAAK;;;CAGjB,CAAA"}

package/dist/utils/storage-managers.d.ts

@@ -0,0 +1,65 @@
+/**
+ * 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 { VersionedStorageManager } from "./versioned-storage";
+import type { Account, Identity, ConnectedApp, PostageStamp } from "../types";
+import { type NetworkSettings } from "../schemas";
+/**
+ * Serialize Account for storage
+ */
+export declare function serializeAccount(account: Account): Record<string, unknown>;
+/**
+ * Serialize Identity for storage
+ */
+export declare function serializeIdentity(identity: Identity): Record<string, unknown>;
+/**
+ * Serialize ConnectedApp for storage
+ */
+export declare function serializeConnectedApp(app: ConnectedApp): Record<string, unknown>;
+/**
+ * Serialize PostageStamp for storage
+ */
+export declare function serializePostageStamp(stamp: PostageStamp): Record<string, unknown>;
+/**
+ * Create storage manager for accounts
+ */
+export declare function createAccountsStorageManager(): VersionedStorageManager<Account>;
+/**
+ * Create storage manager for identities
+ */
+export declare function createIdentitiesStorageManager(): VersionedStorageManager<Identity>;
+/**
+ * Create storage manager for connected apps
+ */
+export declare function createConnectedAppsStorageManager(): VersionedStorageManager<ConnectedApp>;
+/**
+ * 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 declare function disconnectApp(appUrl: string): void;
+/**
+ * Create storage manager for postage stamps
+ */
+export declare function createPostageStampsStorageManager(): VersionedStorageManager<PostageStamp>;
+/**
+ * Serialize NetworkSettings for storage
+ */
+export declare function serializeNetworkSettings(settings: NetworkSettings): Record<string, unknown>;
+/**
+ * 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 declare function createNetworkSettingsStorageManager(): NetworkSettingsStorageManager;
+//# sourceMappingURL=storage-managers.d.ts.map

package/dist/utils/storage-managers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-managers.d.ts","sourceRoot":"","sources":["../../src/utils/storage-managers.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EACL,uBAAuB,EAGxB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAQ7E,OAAO,EAML,KAAK,eAAe,EACrB,MAAM,YAAY,CAAA;AAkEnB;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAuC1E;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAS7E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,GAAG,EAAE,YAAY,GAChB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAWzB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,YAAY,GAClB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAgBzB;AAMD;;GAEG;AACH,wBAAgB,4BAA4B,IAAI,uBAAuB,CAAC,OAAO,CAAC,CAU/E;AAED;;GAEG;AACH,wBAAgB,8BAA8B,IAAI,uBAAuB,CAAC,QAAQ,CAAC,CAUlF;AAED;;GAEG;AACH,wBAAgB,iCAAiC,IAAI,uBAAuB,CAAC,YAAY,CAAC,CAUzF;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CASlD;AAED;;GAEG;AACH,wBAAgB,iCAAiC,IAAI,uBAAuB,CAAC,YAAY,CAAC,CAUzF;AAuBD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,eAAe,GACxB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAKzB;AAED;;GAEG;AACH,MAAM,WAAW,6BAA6B;IAC5C,IAAI,IAAI,eAAe,GAAG,SAAS,CAAA;IACnC,IAAI,CAAC,QAAQ,EAAE,eAAe,GAAG,IAAI,CAAA;IACrC,KAAK,IAAI,IAAI,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,mCAAmC,IAAI,6BAA6B,CA6CnF"}

package/dist/utils/swarm-id-export.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Swarm ID Export/Import Module
+ *
+ * Provides serialization and deserialization for the .swarmid export format.
+ * Delegates to account-payload for the unified payload schema.
+ */
+import type { Account, Identity, ConnectedApp, PostageStamp } from "../schemas";
+import type { AccountPayload, AccountPayloadResult } from "./account-payload";
+export type { ExportedConnectedApp } from "./account-payload";
+export { AccountPayloadSchemaV1 as SwarmIdExportSchemaV1 } from "./account-payload";
+export type SwarmIdExport = AccountPayload;
+export type SwarmIdImportResult = AccountPayloadResult;
+/**
+ * Serialize account data into a plain object suitable for JSON export.
+ * Extracts accountId + metadata from the Account, then delegates to
+ * the shared account-payload serializer.
+ */
+export declare function serializeSwarmIdExport(account: Account, identities: Identity[], connectedApps: ConnectedApp[], postageStamps: PostageStamp[]): Record<string, unknown>;
+/**
+ * Deserialize and validate a .swarmid export file.
+ * Delegates to the shared account-payload deserializer.
+ */
+export declare function deserializeSwarmIdExport(data: unknown): SwarmIdImportResult;
+//# sourceMappingURL=swarm-id-export.d.ts.map

package/dist/utils/swarm-id-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swarm-id-export.d.ts","sourceRoot":"","sources":["../../src/utils/swarm-id-export.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAK/E,OAAO,KAAK,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAG7E,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAA;AAC7D,OAAO,EAAE,sBAAsB,IAAI,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAMnF,MAAM,MAAM,aAAa,GAAG,cAAc,CAAA;AAE1C,MAAM,MAAM,mBAAmB,GAAG,oBAAoB,CAAA;AAMtD;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,OAAO,EAAE,OAAO,EAChB,UAAU,EAAE,QAAQ,EAAE,EACtB,aAAa,EAAE,YAAY,EAAE,EAC7B,aAAa,EAAE,YAAY,EAAE,GAC5B,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAczB;AAMD;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,GAAG,mBAAmB,CAE3E"}