@snaha/swarm-id 0.0.1

package/dist/utils/ttl.d.ts

@@ -0,0 +1,49 @@
+/**
+ * TTL (Time To Live) calculation and formatting utilities for postage stamps
+ */
+/**
+ * Gnosis Chain block time in seconds
+ */
+export declare const GNOSIS_BLOCK_TIME = 5;
+/**
+ * Swarmscan API URL for price data
+ */
+export declare const SWARMSCAN_STATS_URL = "https://api.swarmscan.io/v1/postage-stamps/stats";
+/**
+ * Fetches current price from Swarmscan.
+ * @returns pricePerGBPerMonth in BZZ
+ */
+export declare function fetchSwarmPrice(): Promise<number>;
+/**
+ * Calculates TTL in seconds from stamp amount and Swarmscan price.
+ *
+ * @param amount - Stamp amount in PLUR (smallest BZZ unit)
+ * @param pricePerGBPerMonth - Price from Swarmscan (in BZZ)
+ * @returns TTL in seconds
+ */
+export declare function calculateTTLSeconds(amount: bigint | number | string, pricePerGBPerMonth: number): number;
+/**
+ * Formats a TTL value (in seconds) to a human-readable string.
+ * Returns "Xd Yh" format (e.g., "30d 14h").
+ *
+ * @param ttlSeconds - TTL in seconds
+ * @returns Human-readable TTL string, or "N/A" if undefined/invalid
+ */
+export declare function formatTTL(ttlSeconds: number | undefined): string;
+/**
+ * Fetches block timestamp from Gnosis RPC.
+ *
+ * @param rpcUrl - Gnosis RPC URL
+ * @param blockNumber - Block number to get timestamp for
+ * @returns Block timestamp in seconds (Unix timestamp)
+ */
+export declare function getBlockTimestamp(rpcUrl: string, blockNumber: number): Promise<number>;
+/**
+ * Calculates expiry timestamp for a postage stamp.
+ *
+ * @param blockTimestamp - Timestamp when stamp was created (from blockNumber)
+ * @param ttlSeconds - TTL in seconds
+ * @returns Expiry timestamp in seconds (Unix timestamp)
+ */
+export declare function calculateExpiryTimestamp(blockTimestamp: number, ttlSeconds: number): number;
+//# sourceMappingURL=ttl.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ttl.d.ts","sourceRoot":"","sources":["../../src/utils/ttl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAkBlC;;GAEG;AACH,eAAO,MAAM,mBAAmB,qDACoB,CAAA;AAEpD;;;GAGG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,MAAM,CAAC,CAOvD;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAChC,kBAAkB,EAAE,MAAM,GACzB,MAAM,CASR;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAShE;AAED;;;;;;GAMG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAqBjB;AAED;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER"}

package/dist/utils/url.d.ts

@@ -0,0 +1,41 @@
+import type { AppMetadata } from "../types";
+/**
+ * Configuration options for building the authentication URL.
+ */
+export interface BuildAuthUrlOptions {
+    /**
+     * When true, shows the agent sign-up option on the connect page.
+     * Agents are automated services that can perform operations on behalf of users.
+     */
+    agent?: boolean;
+    /**
+     * Challenge string for storage partitioning detection. When present, the popup checks
+     * if it can read this challenge from localStorage to determine whether
+     * storage is partitioned.
+     */
+    challenge?: string;
+}
+/**
+ * Build the authentication URL for connecting to Swarm ID
+ *
+ * This function creates the same URL format as used by SwarmIdProxy.openAuthPopup()
+ * to ensure consistency across the library.
+ *
+ * @param baseUrl - The base URL where the authentication page is hosted
+ * @param origin - The origin of the parent application requesting authentication
+ * @param metadata - Optional application metadata to display during authentication
+ * @param options - Optional configuration for the auth URL
+ * @returns The complete authentication URL with hash parameters
+ *
+ * @example
+ * ```typescript
+ * const url = buildAuthUrl(
+ *   "https://swarm-id.example.com",
+ *   "https://myapp.example.com",
+ *   { name: "My App", description: "A decentralized application" }
+ * )
+ * // Returns: "https://swarm-id.example.com/connect#origin=https%3A%2F%2Fmyapp.example.com&appName=My+App&appDescription=A+decentralized+application"
+ * ```
+ */
+export declare function buildAuthUrl(baseUrl: string, origin: string, metadata?: AppMetadata, options?: BuildAuthUrlOptions): string;
+//# sourceMappingURL=url.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"url.d.ts","sourceRoot":"","sources":["../../src/utils/url.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAA;AAE3C;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,MAAM,EACd,QAAQ,CAAC,EAAE,WAAW,EACtB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,MAAM,CAwBR"}

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

@@ -0,0 +1,131 @@
+/**
+ * Generic Versioned Storage Utility
+ *
+ * Provides a framework-agnostic way to store and retrieve versioned data
+ * with automatic migration support.
+ */
+import { z } from "zod";
+/**
+ * Versioned storage wrapper schema
+ * Used to check if data is in versioned format
+ */
+export declare const VersionedStorageSchema: z.ZodObject<{
+    version: z.ZodNumber;
+    data: z.ZodUnknown;
+}, z.core.$strip>;
+export type VersionedStorage = z.infer<typeof VersionedStorageSchema>;
+/**
+ * Storage adapter interface - allows different storage backends
+ */
+export interface StorageAdapter {
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * Version parser function - handles migration from one version to another
+ */
+export type VersionParser<T> = (data: unknown, version: number) => T[];
+/**
+ * Serializer function - converts data to JSON-serializable format
+ */
+export type Serializer<T> = (data: T) => Record<string, unknown>;
+/**
+ * Listener function for storage change events
+ */
+export type StorageChangeListener<T> = (data: T[]) => void;
+/**
+ * Options for versioned storage
+ */
+export interface VersionedStorageOptions<T> {
+    /** Storage key */
+    key: string;
+    /** Current version number */
+    currentVersion: number;
+    /** Storage adapter (e.g., localStorage) */
+    storage: StorageAdapter;
+    /** Version parsers - map of version to parser function */
+    parsers: Record<number, VersionParser<T>>;
+    /** Optional serializer for complex types */
+    serializer?: Serializer<T>;
+    /** Logger name for error messages */
+    loggerName?: string;
+}
+/**
+ * LocalStorage adapter for browser environments
+ */
+export declare class LocalStorageAdapter implements StorageAdapter {
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+}
+/**
+ * In-memory storage adapter (for testing or non-browser environments)
+ */
+export declare class MemoryStorageAdapter implements StorageAdapter {
+    private storage;
+    getItem(key: string): string | undefined;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+}
+/**
+ * Generic versioned storage manager
+ */
+export declare class VersionedStorageManager<T> {
+    private options;
+    private listeners;
+    private boundStorageHandler;
+    constructor(options: VersionedStorageOptions<T>);
+    /**
+     * Subscribe to storage change events from other windows/tabs
+     * The browser's storage event fires when localStorage changes in OTHER windows,
+     * making this useful for cross-window synchronization.
+     *
+     * @param listener - Callback function that receives the updated data
+     * @returns Unsubscribe function to remove the listener
+     */
+    subscribe(listener: StorageChangeListener<T>): () => void;
+    /**
+     * Set up the browser storage event listener
+     * Only listens for changes to this manager's specific key
+     */
+    private setupStorageEventListener;
+    /**
+     * Clean up the storage event listener when no more subscribers
+     */
+    private cleanupStorageEventListener;
+    /**
+     * Notify all listeners of data changes
+     */
+    private notifyListeners;
+    /**
+     * Load data from storage
+     */
+    load(): T[];
+    /**
+     * Parse versioned data and migrate if needed
+     */
+    private parse;
+    /**
+     * Save data to storage
+     */
+    save(data: T[]): void;
+    /**
+     * Clear data from storage
+     */
+    clear(): void;
+}
+/**
+ * Create a versioned storage manager with localStorage
+ */
+export declare function createLocalStorageManager<T>(options: Omit<VersionedStorageOptions<T>, "storage">): VersionedStorageManager<T>;
+/**
+ * Create a versioned storage manager with memory storage
+ */
+export declare function createMemoryStorageManager<T>(options: Omit<VersionedStorageOptions<T>, "storage">): VersionedStorageManager<T>;
+/**
+ * Create a simple Zod-based parser for a single version
+ */
+export declare function createZodParser<T>(schema: z.ZodType<T[]>): VersionParser<T>;
+//# sourceMappingURL=versioned-storage.d.ts.map

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

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

package/package.json

@@ -0,0 +1,78 @@
+{
+  "name": "@snaha/swarm-id",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Swarm ID library for authentication and Bee API operations",
+  "main": "dist/swarm-id.esm.js",
+  "module": "dist/swarm-id.esm.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/swarm-id.esm.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "build:watch": "rollup -c -w",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "lint": "eslint src/**/*.ts",
+    "lint:fix": "eslint src/**/*.ts --fix",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "format:check": "prettier --check \"src/**/*.ts\"",
+    "typecheck": "tsc --noEmit",
+    "check:all": "pnpm format:check && pnpm lint && pnpm typecheck && pnpm test"
+  },
+  "keywords": [
+    "swarm",
+    "identity",
+    "authentication",
+    "bee",
+    "web3"
+  ],
+  "author": "snaha",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/snaha/swarm-id"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@ethersphere/bee-js": "^11.1.1",
+    "cafe-utility": "33.3.2",
+    "zod": "4.1.13"
+  },
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "29.0.0",
+    "@rollup/plugin-json": "6.1.0",
+    "@rollup/plugin-node-resolve": "16.0.3",
+    "@rollup/plugin-replace": "6.0.3",
+    "@rollup/plugin-terser": "0.4.4",
+    "@rollup/plugin-typescript": "12.3.0",
+    "@types/node": "24.10.1",
+    "@typescript-eslint/eslint-plugin": "8.48.1",
+    "@typescript-eslint/parser": "8.48.1",
+    "@vitest/ui": "^4.0.16",
+    "eslint": "9.39.1",
+    "prettier": "3.7.3",
+    "rollup": "4.53.3",
+    "tslib": "2.8.1",
+    "typescript": "5.8.3",
+    "vitest": "4.0.14"
+  },
+  "engines": {
+    "node": ">=22",
+    "pnpm": "10.x"
+  }
+}

package/src/chunk/bmt.test.ts

@@ -0,0 +1,217 @@
+/**
+ * Unit tests for BMT (Binary Merkle Tree) hashing
+ */
+
+import { describe, it, expect } from "vitest"
+import { Span } from "@ethersphere/bee-js"
+import { calculateChunkAddress } from "./bmt"
+
+// ============================================================================
+// calculateChunkAddress Tests
+// ============================================================================
+
+describe("calculateChunkAddress", () => {
+  describe("basic functionality", () => {
+    it("should return 32-byte Reference", () => {
+      const span = Span.fromBigInt(BigInt(4))
+      const payload = new Uint8Array([1, 2, 3, 4])
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+
+    it("should produce deterministic result (same content = same address)", () => {
+      const span = Span.fromBigInt(BigInt(5))
+      const payload = new Uint8Array([10, 20, 30, 40, 50])
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address1 = calculateChunkAddress(chunkContent)
+      const address2 = calculateChunkAddress(chunkContent)
+
+      expect(address1.toUint8Array()).toEqual(address2.toUint8Array())
+    })
+
+    it("should produce different address for different content", () => {
+      const span = Span.fromBigInt(BigInt(4))
+
+      const payload1 = new Uint8Array([1, 2, 3, 4])
+      const chunkContent1 = new Uint8Array(8 + payload1.length)
+      chunkContent1.set(span.toUint8Array())
+      chunkContent1.set(payload1, 8)
+
+      const payload2 = new Uint8Array([5, 6, 7, 8])
+      const chunkContent2 = new Uint8Array(8 + payload2.length)
+      chunkContent2.set(span.toUint8Array())
+      chunkContent2.set(payload2, 8)
+
+      const address1 = calculateChunkAddress(chunkContent1)
+      const address2 = calculateChunkAddress(chunkContent2)
+
+      expect(address1.toUint8Array()).not.toEqual(address2.toUint8Array())
+    })
+  })
+
+  describe("payload size handling", () => {
+    it("should handle minimum payload (1 byte)", () => {
+      const span = Span.fromBigInt(BigInt(1))
+      const payload = new Uint8Array([42])
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+
+    it("should handle maximum payload (4096 bytes)", () => {
+      const span = Span.fromBigInt(BigInt(4096))
+      const payload = new Uint8Array(4096)
+      for (let i = 0; i < 4096; i++) {
+        payload[i] = i % 256
+      }
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+
+    it("should throw error on payload larger than 4096 bytes", () => {
+      const span = Span.fromBigInt(BigInt(4097))
+      const payload = new Uint8Array(4097)
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      expect(() => calculateChunkAddress(chunkContent)).toThrow(
+        /payload size .* exceeds maximum chunk payload size/,
+      )
+    })
+  })
+
+  describe("zero-padding behavior", () => {
+    it("should produce consistent hash with short payloads (zero-padded internally)", () => {
+      // Two chunks with same payload should have same address
+      const span = Span.fromBigInt(BigInt(10))
+      const payload = new Uint8Array([1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address1 = calculateChunkAddress(chunkContent)
+      const address2 = calculateChunkAddress(chunkContent)
+
+      expect(address1.toUint8Array()).toEqual(address2.toUint8Array())
+    })
+
+    it("should produce different hash for different payload lengths with same prefix", () => {
+      // Payload of length 4 vs length 5 should have different addresses
+      const payload4 = new Uint8Array([1, 2, 3, 4])
+      const payload5 = new Uint8Array([1, 2, 3, 4, 0])
+
+      const span4 = Span.fromBigInt(BigInt(4))
+      const chunkContent4 = new Uint8Array(8 + payload4.length)
+      chunkContent4.set(span4.toUint8Array())
+      chunkContent4.set(payload4, 8)
+
+      const span5 = Span.fromBigInt(BigInt(5))
+      const chunkContent5 = new Uint8Array(8 + payload5.length)
+      chunkContent5.set(span5.toUint8Array())
+      chunkContent5.set(payload5, 8)
+
+      const address4 = calculateChunkAddress(chunkContent4)
+      const address5 = calculateChunkAddress(chunkContent5)
+
+      // Even though payload5 ends with 0 (like zero-padding), different spans mean different addresses
+      expect(address4.toUint8Array()).not.toEqual(address5.toUint8Array())
+    })
+  })
+
+  describe("span variations", () => {
+    it("should produce different addresses for same payload but different span", () => {
+      const payload = new Uint8Array([1, 2, 3, 4])
+
+      const span1 = Span.fromBigInt(BigInt(4))
+      const chunkContent1 = new Uint8Array(8 + payload.length)
+      chunkContent1.set(span1.toUint8Array())
+      chunkContent1.set(payload, 8)
+
+      // Same payload but span indicates different length
+      const span2 = Span.fromBigInt(BigInt(3))
+      const chunkContent2 = new Uint8Array(8 + payload.length)
+      chunkContent2.set(span2.toUint8Array())
+      chunkContent2.set(payload, 8)
+
+      const address1 = calculateChunkAddress(chunkContent1)
+      const address2 = calculateChunkAddress(chunkContent2)
+
+      expect(address1.toUint8Array()).not.toEqual(address2.toUint8Array())
+    })
+  })
+
+  describe("edge cases", () => {
+    it("should handle chunk with zero-filled payload", () => {
+      const span = Span.fromBigInt(BigInt(32))
+      const payload = new Uint8Array(32) // all zeros
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+
+    it("should handle chunk with all 0xFF payload", () => {
+      const span = Span.fromBigInt(BigInt(32))
+      const payload = new Uint8Array(32).fill(0xff)
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+
+    it("should handle exactly 32 bytes payload (one BMT segment)", () => {
+      const span = Span.fromBigInt(BigInt(32))
+      const payload = new Uint8Array(32)
+      for (let i = 0; i < 32; i++) {
+        payload[i] = i
+      }
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+
+    it("should handle exactly 64 bytes payload (two BMT segments)", () => {
+      const span = Span.fromBigInt(BigInt(64))
+      const payload = new Uint8Array(64)
+      for (let i = 0; i < 64; i++) {
+        payload[i] = i
+      }
+      const chunkContent = new Uint8Array(8 + payload.length)
+      chunkContent.set(span.toUint8Array())
+      chunkContent.set(payload, 8)
+
+      const address = calculateChunkAddress(chunkContent)
+
+      expect(address.toUint8Array().length).toBe(32)
+    })
+  })
+})

package/src/chunk/bmt.ts

@@ -0,0 +1,57 @@
+import { Binary } from "cafe-utility"
+import { Reference, Span } from "@ethersphere/bee-js"
+
+const MAX_CHUNK_PAYLOAD_SIZE = 4096
+const SEGMENT_SIZE = 32
+
+/**
+ * Calculate a Binary Merkle Tree hash for a chunk
+ *
+ * The BMT chunk address is the hash of the 8 byte span and the root
+ * hash of a binary Merkle tree (BMT) built on the 32-byte segments
+ * of the underlying data.
+ *
+ * If the chunk content is less than 4k, the hash is calculated as
+ * if the chunk was padded with all zeros up to 4096 bytes.
+ *
+ * @param chunkContent Chunk data including span and payload as well
+ *
+ * @returns the keccak256 hash in a byte array
+ */
+export function calculateChunkAddress(chunkContent: Uint8Array): Reference {
+  const span = chunkContent.slice(0, Span.LENGTH)
+  const payload = chunkContent.slice(Span.LENGTH)
+  const rootHash = calculateBmtRootHash(payload)
+  const chunkHash = Binary.keccak256(Binary.concatBytes(span, rootHash))
+
+  return new Reference(chunkHash)
+}
+
+function calculateBmtRootHash(payload: Uint8Array): Uint8Array {
+  if (payload.length > MAX_CHUNK_PAYLOAD_SIZE) {
+    throw new Error(
+      `payload size ${payload.length} exceeds maximum chunk payload size ${MAX_CHUNK_PAYLOAD_SIZE}`,
+    )
+  }
+  const input = new Uint8Array(MAX_CHUNK_PAYLOAD_SIZE)
+  input.set(payload)
+
+  // Build BMT by hashing pairs of segments level by level
+  let currentLevel = Binary.partition(input, SEGMENT_SIZE)
+
+  while (currentLevel.length > 1) {
+    const nextLevel: Uint8Array[] = []
+
+    for (let i = 0; i < currentLevel.length; i += 2) {
+      const left = currentLevel[i]
+      const right = currentLevel[i + 1]
+      const combined = Binary.concatBytes(left, right)
+      const hash = Binary.keccak256(combined)
+      nextLevel.push(hash)
+    }
+
+    currentLevel = nextLevel
+  }
+
+  return currentLevel[0]
+}