@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/utils/postage-contract.d.ts

@@ -0,0 +1,143 @@
+/**
+ * PostageStamp contract address on Gnosis Chain. Lowercased — RPC nodes accept
+ * a non-checksummed `to`, and lowercasing sidesteps any checksum mistake.
+ */
+export declare const POSTAGE_STAMP_CONTRACT_ADDRESS = "0x45a1502382541cd610cc9068e88727426b696293";
+/**
+ * Picks the PostageStamp contract address that matches the chain `rpcUrl` points
+ * at. A dev-override address (bee-compose anvil) is only honoured against a local
+ * RPC; against any remote RPC (Gnosis mainnet) it would read a nonexistent
+ * contract — `eth_call` returns empty, the batch looks unknown, and callers
+ * silently fall back to a bogus price estimate. Tying the address to the RPC
+ * network stops the two from drifting apart, which is what produced wildly wrong
+ * estimated expiry dates when a dev build read a mainnet batch (#344).
+ */
+export declare function resolvePostageStampContractAddress(rpcUrl: string, localContractAddress?: string): string;
+/**
+ * Decoded `batches(bytes32)` tuple. Field names mirror the contract's `Batch`
+ * struct. `normalisedBalance` is a per-chunk value denominated in PLUR; it is
+ * the cumulative outpayment level at which this batch runs out.
+ */
+export interface OnChainPostageBatch {
+    owner: string;
+    depth: number;
+    bucketDepth: number;
+    immutableFlag: boolean;
+    normalisedBalance: bigint;
+    lastUpdatedBlockNumber: bigint;
+}
+/**
+ * A consistent snapshot of one batch plus the global accounting needed to turn
+ * its `normalisedBalance` into a remaining TTL.
+ */
+export interface OnChainBatchState {
+    batch: OnChainPostageBatch;
+    /** Per-chunk cumulative outpayment so far, in PLUR (`currentTotalOutPayment()`). */
+    currentTotalOutPayment: bigint;
+    /** Per-chunk per-block storage price, in PLUR (`lastPrice()`). */
+    lastPrice: bigint;
+}
+/**
+ * Decodes the ABI-encoded return of `batches(bytes32)` — a static tuple of
+ * `(address, uint8, uint8, bool, uint256, uint256)`, i.e. six 32-byte words.
+ * @throws if the payload is too short to hold the tuple.
+ */
+export declare function decodeBatches(hex: string): OnChainPostageBatch;
+/** Decodes a single-`uint256` return payload to a BigInt. */
+export declare function decodeUint(hex: string): bigint;
+/**
+ * Fetches a consistent on-chain snapshot of a postage batch from the
+ * PostageStamp contract: its `batches(batchId)` tuple plus the global
+ * `currentTotalOutPayment()` and `lastPrice()`.
+ *
+ * @param rpcUrl - Gnosis Chain JSON-RPC URL
+ * @param batchId - 32-byte hex batch ID, with or without `0x` prefix
+ * @param contractAddress - PostageStamp contract address to read from. Defaults
+ *          to the Gnosis mainnet deployment; override for a local dev chain
+ *          (bee-compose anvil deploys it at a different address).
+ * @returns The decoded state, or `undefined` if the batch is unknown to the
+ *          contract (zero owner) or the RPC request fails. Never throws — the
+ *          UI falls back to other expiry sources on `undefined`.
+ */
+/**
+ * Outcome of an on-chain batch read, keeping the two failure modes distinct:
+ *   - `found` — the contract knows the batch (non-zero owner).
+ *   - `not-found` — the contract returned an all-zero tuple; the batch
+ *     authoritatively does not exist on this chain.
+ *   - `error` — the RPC request failed or returned an undecodable payload, so
+ *     existence is *unknown* (not the same as "does not exist").
+ */
+export type OnChainBatchResult = {
+    status: "found";
+    state: OnChainBatchState;
+} | {
+    status: "not-found";
+} | {
+    status: "error";
+};
+/**
+ * Reads a batch's on-chain state, distinguishing "definitively absent" from
+ * "couldn't check". {@link fetchOnChainBatchState} is the simpler wrapper that
+ * collapses both into `undefined`.
+ */
+export declare function fetchOnChainBatchStateResult(rpcUrl: string, batchId: string, contractAddress?: string): Promise<OnChainBatchResult>;
+export declare function fetchOnChainBatchState(rpcUrl: string, batchId: string, contractAddress?: string): Promise<OnChainBatchState | undefined>;
+/**
+ * Computes a batch's remaining TTL in seconds from an on-chain snapshot, using
+ * the same integer math as the storage-incentives contract and Bee node.
+ *
+ * @returns Remaining seconds (`0` when expired), or `undefined` when the price
+ *          is zero — the batch then drains at no cost and has no finite expiry,
+ *          which we cannot render as a date. On mainnet the PriceOracle floor
+ *          keeps `lastPrice` well above zero, so this only guards dev chains.
+ */
+export declare function calculateContractTTLSeconds(state: OnChainBatchState): number | undefined;
+/**
+ * Convenience wrapper: fetches a batch's on-chain state and returns its
+ * remaining TTL in seconds. This is the contract-backed counterpart to
+ * {@link fetchBatchTTL} (which reads the Bee node), and unlike it works for any
+ * batch the contract knows about, regardless of whether the configured Bee node
+ * tracks it.
+ *
+ * @param contractAddress - PostageStamp contract address (defaults to mainnet;
+ *          override for a local dev chain).
+ * @returns Remaining TTL in seconds (`0` when expired), or `undefined` when the
+ *          batch is unknown, the RPC request fails, or the price is zero.
+ */
+export declare function fetchBatchTTLFromContract(rpcUrl: string, batchId: string, contractAddress?: string): Promise<number | undefined>;
+/**
+ * Resolves a batch's remaining TTL (seconds) from the most authoritative source
+ * available, in order:
+ *   1. The PostageStamp contract, read directly by batchId — ground truth that
+ *      works for any batch, even one the configured Bee node has never seen.
+ *   2. The Bee node's `batchTTL` — also live chain state, but only for batches
+ *      the node tracks.
+ *
+ * This is the single canonical "best remaining TTL" lookup; callers layer a
+ * price-based approximation ({@link calculateTTLSeconds}) on top when both
+ * sources return `undefined`.
+ *
+ * @param gnosisRpcUrl - Gnosis Chain JSON-RPC URL (for the contract read)
+ * @param beeUrl - Bee node URL (fallback)
+ * @param batchId - 32-byte hex batch ID, with or without `0x` prefix
+ * @param localContractAddress - PostageStamp address for a local dev chain. Only
+ *          honoured when `gnosisRpcUrl` targets a local node; against any remote
+ *          RPC the Gnosis mainnet deployment is used regardless (see
+ *          {@link resolvePostageStampContractAddress}).
+ * @returns Remaining TTL in seconds, or `undefined` if neither source can answer.
+ */
+export declare function fetchAuthoritativeBatchTTL(gnosisRpcUrl: string, beeUrl: string, batchId: string, localContractAddress?: string): Promise<number | undefined>;
+/**
+ * Resolves a batch's existence and remaining TTL, treating the on-chain contract
+ * as the source of truth. A contract `not-found` is authoritative — a Bee node
+ * that happens to track the batch cannot override the chain. The Bee node is
+ * consulted only when the contract read itself failed (RPC unreachable), as a
+ * best-effort second opinion.
+ *
+ * Unlike {@link fetchAuthoritativeBatchTTL} (best-effort TTL, falls back to Bee
+ * even on contract `not-found`), this is the stricter lookup for existence-aware
+ * UI.
+ *
+ * @param localContractAddress - PostageStamp address for a local dev chain; only
+ *          honoured against a local RPC (see {@link resolvePostageStampContractAddress}).
+ */

package/dist/utils/postage-stamp-association.d.ts

@@ -0,0 +1,39 @@
+import type { ConnectedApp, PostageStamp, SignedInAccount } from "../schemas";
+/**
+ * Resolve which postage stamp an app should upload with.
+ *
+ * An app may carry its own batch override (`postageStampBatchID`); otherwise it
+ * falls back to the account's default stamp. The account owns the stamp set, so
+ * these pointers are the single source of truth.
+ *
+ * The lookup is existence-checked: a pointer whose stamp is missing (e.g. a
+ * removed or replaced batch) is skipped so resolution falls through to the next
+ * candidate instead of failing.
+ *
+ * Paired with `stampsReachableByApp` below, which decides what a partitioned
+ * session may HOLD while this decides what it SPENDS — over the same two
+ * pointers, and deliberately differing on tombstones: this one skips them (a
+ * deleted stamp cannot be spent), that one keeps them (a session learns its
+ * stamp is deleted no other way). Change the pointer rule in one and the other
+ * has to follow, or a session holds a stamp it cannot resolve, or resolves one
+ * it was never handed.
+ */
+export declare function resolveStampForApp(app: Pick<ConnectedApp, "postageStampBatchID">, account: Pick<SignedInAccount, "defaultPostageStampBatchID">, stamps: PostageStamp[]): PostageStamp | undefined;
+/**
+ * The stamps a connected app's session can ever reach: the ones its pointers
+ * name — its own batch override, and the account default it falls through to.
+ *
+ * This is what a PARTITIONED session is handed and allowed to keep (#578). It
+ * holds its account view in memory, in a context embedded by an arbitrary dApp
+ * page, and it can only ever spend the stamp `resolveStampForApp` picks — so
+ * the rest of the collection is signer keys it has no use for. Least privilege
+ * rather than a broken boundary: an unpartitioned proxy reads the same material
+ * out of shared storage, but it does not have to be handed it.
+ *
+ * BOTH pointers, not just the winner: the default is the fallthrough
+ * `resolveStampForApp` takes when the override's stamp is gone, so shipping
+ * only the override would turn a recoverable stale pointer into a session that
+ * cannot upload at all. Tombstones its pointers still name are kept too — a
+ * tombstone is how the session learns the stamp it was spending is deleted.
+ */
+export declare function stampsReachableByApp(app: Pick<ConnectedApp, "postageStampBatchID">, account: Pick<SignedInAccount, "defaultPostageStampBatchID">, stamps: PostageStamp[]): PostageStamp[];

package/dist/utils/promise.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Rejection type for {@link withTimeout}. Callers classify a timed-out read
+ * (INCONCLUSIVE — the target may exist behind a slow gateway) apart from a
+ * clean miss / other failure with `error instanceof TimeoutError` — never by
+ * matching the message text, which is display-only.
+ */
+export declare class TimeoutError extends Error {
+    constructor(message: string);
+}
+/**
+ * Time-bound `work`: resolve/reject with `work` if it settles within `ms`, else
+ * reject with a {@link TimeoutError}. Unlike a hand-rolled
+ * `Promise.race([work, rejectionTimer])`, the timer is cleared once the race
+ * settles, so a fast read leaves no stray timer to fire later (matters in
+ * tight read loops).
+ */
+export declare function withTimeout<T>(work: Promise<T>, ms: number, message: string): Promise<T>;
+/**
+ * Resolve after `ms` milliseconds — the default delay behind a poll or backoff.
+ *
+ * A caller whose timing a test needs to drive should keep taking an injectable
+ * wait and pass this as its default (as `acquirePartitionLock` does with
+ * `opts.wait`) rather than calling it directly, which would pin real time into
+ * the test path.
+ */
+export declare function sleep(ms: number): Promise<void>;
+/**
+ * Like {@link withTimeout}, but the deadline is `ms` from the last
+ * `keepAlive()` the work reported (or from the start, if it reported nothing) —
+ * so it bounds silence, not total elapsed time. For work of unbounded duration
+ * whose progress is observable: a payment signed in a wallet, a long upload.
+ *
+ * `work` is a function so it can be handed the `keepAlive` callback. A
+ * synchronous throw from it becomes a rejection, and a `keepAlive` after the
+ * work settles is ignored — both so the timer is always cleared.
+ */
+export declare function withIdleTimeout<T>(work: (keepAlive: () => void) => Promise<T>, ms: number, message: string): Promise<T>;

package/dist/utils/sealed-values.d.ts

@@ -0,0 +1,23 @@
+/** Marks a stored string as sealed, and names the format. */
+export declare const SEALED_VALUE_PREFIX = "sealed:v1:";
+/**
+ * Whether this page seals with a key of its own in place of the browser's
+ * IndexedDB. What it seals now no later load can open.
+ */
+export declare function sealsWithPageKey(): Promise<boolean>;
+export declare function isSealedValue(value: unknown): value is string;
+/**
+ * Seal a value for storage. One value seals to one sealed form for the life of
+ * the page, so rewriting an unchanged record writes the same bytes.
+ */
+export declare function sealValue(plaintext: string): Promise<string>;
+/**
+ * Whether this page failed to reach the wrapping key for this value, as
+ * opposed to reaching it and finding the value will not open. Stays true for
+ * the rest of the page even if a later try opens it.
+ */
+export declare function isSealedValueUnavailable(sealed: string): boolean;
+/** Open these sealed values into memory, so `openedValue` can read them. */
+export declare function primeSealedValues(sealed: Iterable<string>): Promise<void>;
+/** The plain value, if this page has opened it. */
+export declare function openedValue(sealed: string): string | undefined;

package/dist/utils/seed-encryption.d.ts

@@ -0,0 +1,17 @@
+export declare function randomSalt(): Uint8Array;
+/** Encrypt bytes; returns hex of IV || ciphertext. */
+export declare function encryptSeed(data: Uint8Array, key: CryptoKey): Promise<string>;
+export declare function decryptSeed(payloadHex: string, key: CryptoKey): Promise<Uint8Array>;
+/**
+ * Derive an AES-GCM key from secret input keying material (HKDF-SHA256).
+ * The IKM must be secret — anything recoverable by a third party (addresses,
+ * public keys) gives no protection.
+ */
+export declare function deriveKeyFromSecret(ikm: Uint8Array, salt: Uint8Array, info: string): Promise<CryptoKey>;
+/** Derive the seed-encryption key from a passkey PRF output (HKDF). */
+export declare function deriveKeyFromPrf(prfOutput: Uint8Array): Promise<CryptoKey>;
+/** Derive the seed-encryption key from a wallet message signature + stored salt (HKDF). */
+export declare function deriveKeyFromSignature(signature: Uint8Array, salt: Uint8Array): Promise<CryptoKey>;
+/** Derive the seed-encryption key from a password + stored salt (PBKDF2). */
+export declare function deriveKeyFromPassword(password: string, salt: Uint8Array, iterations?: number): Promise<CryptoKey>;
+export declare const PASSWORD_KDF_ITERATIONS = 600000;

package/dist/utils/site-allow-list.d.ts

@@ -0,0 +1,54 @@
+/** The name whose text record holds the list. */
+export declare const DEFAULT_SITE_ALLOW_LIST_ENS_NAME = "solarpunkid.eth";
+/** The text record key, in the reverse-domain form ENSIP-5 asks of a vendor key. */
+export declare const DEFAULT_SITE_ALLOW_LIST_RECORD_KEY = "buzz.solarpunk.sites";
+/**
+ * How long a list read from the chain is trusted before it is read again. A
+ * site removed from the record keeps working at most this long on a device
+ * that read it before.
+ */
+export declare const SITE_ALLOW_LIST_CACHE_MS: number;
+/** The ENS registry, at the same address on every chain ENS is deployed to. */
+export declare const ENS_REGISTRY_ADDRESS = "0x00000000000C2E074eC69A0dFb2997BA6C7d2e1e";
+/** Why a site was refused, so a caller can word its own screen. */
+export type SiteRefusal = "not-clean" | "not-listed" | "list-unavailable";
+export type SiteCheck = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: SiteRefusal;
+    message: string;
+};
+export interface SiteAllowList {
+    /** Whether `origin`, exactly as the browser reports it, may be served. */
+    check(origin: string): Promise<SiteCheck>;
+}
+export interface SiteAllowListSettings {
+    /** An Ethereum mainnet JSON-RPC endpoint. Unset, every site is refused. */
+    rpcUrl: string | undefined;
+    ensName: string;
+    recordKey: string;
+    /**
+     * Origins allowed without the chain, for local work. Local http is accepted
+     * here. Only a development build passes any.
+     */
+    devOrigins?: readonly string[];
+    /** Where the read list is kept between loads. Unset, it is kept in memory. */
+    storage?: Pick<Storage, "getItem" | "setItem">;
+    now?: () => number;
+}
+/** The EIP-137 namehash of a name already in its normalized form. */
+export declare function ensNamehash(name: string): string;
+/**
+ * The origins a record names. Entries are separated by white space or commas.
+ * An entry that is not a clean https origin is ignored and logged, so one bad
+ * entry cannot take the whole list down, and no entry is ever read as a
+ * pattern.
+ */
+export declare function parseSiteAllowList(record: string): string[];
+/**
+ * The allow list for one setting of name, record key and endpoint. One
+ * instance per page: it shares a read in flight between the checks that wait
+ * on it.
+ */
+export declare function createSiteAllowList(settings: SiteAllowListSettings): SiteAllowList;

package/dist/utils/stamp-lifespan.d.ts

@@ -0,0 +1,37 @@
+/** The subset of a stamp record the readiness rule is derived from. */
+export interface StampLifetimeFields {
+    batchTTL?: number;
+    createdAt: number;
+    updatedAt?: number;
+    /** What the node last said: absent on a record that predates the fields */
+    usable?: boolean;
+    exists?: boolean;
+}
+/** Why the session refuses to stamp with the record, or `undefined` if it will. */
+export type StampRefusal = "stamp-expired" | "stamp-not-usable";
+/**
+ * The readiness rule. Expiry first, because it is the older and the more
+ * specific answer; then what the record says about the batch (#765): one the
+ * node does not have (`exists: false`) or cannot use (`usable: false`) has its
+ * first stamped write refused, which a dApp gating on `canUpload` alone met
+ * 30 s later as a timeout. The fields are what the writer last stored — the
+ * chain reconcile on drive open refreshes them — not a live reading.
+ */
+export declare function stampRefusal(stamp: StampLifetimeFields, now?: number): StampRefusal | undefined;
+/**
+ * Remaining lifespan in seconds at `now`: negative once expired, `undefined`
+ * when the TTL was never measured.
+ */
+export declare function remainingLifespanSeconds(stamp: StampLifetimeFields, now?: number): number | undefined;
+/**
+ * Whether the stored lifetime has run out. An unknown lifetime is not
+ * expired: refusing to stamp on missing data would turn every legacy record
+ * read-only.
+ */
+export declare function isStampExpired(stamp: StampLifetimeFields, now?: number): boolean;
+/**
+ * Whether two records would age to the same lifetime and refuse the same way
+ * — the check a refresh needs to notice a renewal of the SAME batch, which
+ * moves only `batchTTL` and `updatedAt`, or a node that has since accepted it.
+ */
+export declare function sameStampLifetime(a: StampLifetimeFields | undefined, b: StampLifetimeFields | undefined): boolean;

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

@@ -0,0 +1,62 @@
+import { VersionedStorageManager } from "./versioned-storage";
+import type { Account, SyncedAccount, ConnectedApp, PostageStamp } from "../types";
+import { type NetworkSettings } from "../schemas";
+/**
+ * Serialize the portable projection of an account (`SyncedAccount`) — what
+ * backup files and the sync feed carry off the device. Beyond the schema-level
+ * absence of the seed vault, it strips the live per-app session material:
+ * `appSecret` (the secret the dApp proxy authenticates from, re-derivable from
+ * the master key on the next connect) and `connectedUntil` (meaningless without
+ * the secret — keeping it would show a "Connected" app that can no longer
+ * authenticate).
+ */
+export declare function serializeSyncedAccount(data: SyncedAccount): Record<string, unknown>;
+/**
+ * Serialize Account for storage (nested: includes its connected apps and
+ * postage stamps inline). A signed-out account persists only its minimal
+ * remnant — display fields, the encrypted vault, and the encrypted state
+ * snapshot — so no synced data (in particular the plaintext `derivationKey`)
+ * stays on disk in the clear while signed out.
+ */
+export declare function serializeAccount(account: Account): Record<string, unknown>;
+/**
+ * Serialize ConnectedApp for storage
+ */
+export declare function serializeConnectedApp(app: ConnectedApp): Record<string, unknown>;
+/**
+ * A serialized connected app without its per-context session material.
+ *
+ * `appSecret` is the app's own credential and `connectedUntil` is the deadline
+ * of the session that established it — both belong to one context, and neither
+ * survives leaving it. Every channel that carries an account to another
+ * context strips them here: the popup handshake (`serializeSyncedAccount`)
+ * and the account bus (`accountDeltaSnapshot`). The bus receive schema
+ * (`BusConnectedAppSchema` in `bus/messages.ts`) omits the same two fields
+ * again, so a publisher that forgets this strip is still caught on receive.
+ */
+export declare function portableConnectedApp(app: Record<string, unknown>): 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>;
+/**
+ * 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;

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

@@ -0,0 +1,40 @@
+/**
+ * Whether the proxy iframe can read the trusted domain's first-party store —
+ * asked BEFORE authentication, because it decides which transport the auth
+ * popup has to take (#613).
+ *
+ * The mirror image of the probe the connect popup already runs: there, the
+ * iframe writes a challenge and the popup checks whether it can read it back
+ * first-party (`ui/src/lib/stores/connect.svelte.ts`). That answer arrives far
+ * too late to choose a transport, so the same question is asked the other way
+ * round — the first-party app leaves a marker, and the iframe reads it back.
+ *
+ * Deliberately NOT any of these:
+ *
+ * - **`document.hasStorageAccess()`** — measured 2026-08-31 in the
+ *   `chromium-partitioned` rig: it returns `true` inside a genuinely
+ *   partitioned frame. It is cookie-scoped, and Chrome partitions storage
+ *   separately from cookies, so it answers a different question.
+ * - **The accounts key.** The proxy writes `swarm-id-accounts` from inside the
+ *   iframe (`clearAuthData`), and the versioned storage manager can materialise
+ *   state in a fresh partitioned bucket, so its presence conflates "first-party
+ *   storage is visible" with "this partition has its own copy".
+ * - **The user agent**, which is what this replaces.
+ *
+ * The marker only ever answers YES with certainty. Absent means "not proven
+ * shared" — a partitioned iframe, or a browser that has never had the SwarmID
+ * site open at the top level — and the caller treats that as partitioned,
+ * which is the safe direction: the delegated transport works in both modes.
+ */
+export declare const STORAGE_SHARED_KEY = "swarm-id-first-party";
+/**
+ * Leave the marker. Called by the trusted domain's own pages.
+ *
+ * The framed guard is load-bearing: the proxy route runs the same app shell
+ * inside the iframe, and a marker written there would land in the partitioned
+ * bucket and make the iframe report itself shared — the one wrong answer this
+ * must never give.
+ */
+export declare function markFirstPartyStorage(): void;
+/** Whether this context can see the marker a first-party page left. */
+export declare function isStorageShared(): boolean;

package/dist/utils/tag.d.ts

@@ -0,0 +1,11 @@
+import type { Bee } from "@ethersphere/bee-js";
+/**
+ * Attempt to create a tag for upload progress tracking.
+ * Returns the tag UID on success, or undefined if the node
+ * does not support tags (e.g., gateway nodes return 404).
+ *
+ * Only a definitive 404 (the endpoint is unsupported) is cached per `Bee`; a
+ * transient failure (5xx / network / timeout) is NOT cached, so a later upload
+ * re-probes the node instead of being permanently tag-less after one blip.
+ */
+export declare function tryCreateTag(bee: Bee): Promise<number | undefined>;

package/dist/utils/ttl.d.ts

@@ -0,0 +1,120 @@
+/**
+ * TTL (Time To Live) calculation and formatting utilities for postage stamps
+ */
+/**
+ * Gnosis Chain block time in seconds
+ */
+export declare const GNOSIS_BLOCK_TIME = 5;
+/**
+ * Blocks per day on Gnosis Chain (24h / 5s block time = 17280). BigInt so it
+ * composes with the PLUR-denominated price math in
+ * {@link calculateStampAmountForDays} without precision loss.
+ */
+export declare const BLOCKS_PER_DAY: bigint;
+/**
+ * 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>;
+/**
+ * Approximates the lifetime of a postage stamp deposit in seconds, assuming
+ * the chain's per-block price stays constant at `pricePerGBPerMonth` for the
+ * full lifetime. This is the answer to "how long would a stamp with this
+ * deposit last at the current price" — not the remaining TTL of an existing
+ * stamp (for that, prefer {@link fetchBatchTTL}, which uses live chain state).
+ *
+ * Uses BigInt math throughout. `pricePerGBPerMonth * 1e16` (PLUR conversion)
+ * silently loses precision in Number, since `1e16 > Number.MAX_SAFE_INTEGER`.
+ *
+ * @param amount - Stamp amount in PLUR (per-chunk)
+ * @param pricePerGBPerMonth - Price in BZZ per GiB per month (from Swarmscan)
+ * @returns Lifetime in seconds. Returns `0` if the amount or price is
+ *          non-positive or the price is not finite — a 0-price chain
+ *          technically never expires stamps, but returning 0 keeps callers
+ *          inside safe Number range and is the conservative display choice.
+ */
+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;
+/**
+ * Snapshot of Bee's view of the chain, from `GET /chainstate`.
+ *
+ * `currentPrice` is PLUR per chunk per block — the per-block storage rent rate
+ * Bee charges against a stamp's deposit. Bee returns it as a decimal string
+ * because Gnosis prices can exceed `Number.MAX_SAFE_INTEGER` on high-traffic
+ * chains, so we keep it BigInt all the way through to the stamp-amount math.
+ */
+export interface ChainState {
+    block: number;
+    currentPrice: bigint;
+}
+/**
+ * Fetches the current chain state (block + per-chunk-per-block price) from a
+ * Bee node. Used to size new stamp amounts: Bee rejects `POST /stamps` calls
+ * whose amount does not cover at least 24h of storage at `currentPrice`.
+ *
+ * @param beeUrl - Bee node URL
+ * @returns Parsed chain state with `currentPrice` as BigInt
+ * @throws if the request fails, returns non-OK, or omits required fields.
+ *         Callers (e.g. the dev page) surface this directly to the user.
+ */
+export declare function fetchChainState(beeUrl: string): Promise<ChainState>;
+/**
+ * Minimum stamp amount (PLUR per chunk) that covers `days` days of validity
+ * at the given per-block price. Bee enforces a 24h floor on `POST /stamps`, so
+ * passing `days = 1` returns the exact minimum that will be accepted.
+ *
+ * @param currentPrice - Per-chunk-per-block price in PLUR (from {@link fetchChainState})
+ * @param days - Positive integer number of days of validity to fund
+ * @returns Amount in PLUR per chunk, or `0n` for non-positive / non-integer inputs
+ */
+export declare function calculateStampAmountForDays(currentPrice: bigint, days: number): bigint;
+/**
+ * Live details for a batch from a Bee node's `/stamps/{batchId}` endpoint.
+ * Fields are individually optional: each is present only when the response
+ * carries it with the expected type.
+ */
+export interface BatchDetails {
+    /** Remaining TTL in seconds; negative API values are normalised to `0`. */
+    batchTTL?: number;
+    /** Whether the batch is usable (started and not expired). */
+    usable?: boolean;
+    /** Whether the batch exists on chain. */
+    exists?: boolean;
+}
+/**
+ * Fetches live batch details directly from a Bee node's `/stamps/{batchId}`
+ * endpoint. The Bee node computes these from current chain state, so they are
+ * authoritative — unlike the snapshot stored at stamp-assignment time, which
+ * can go stale (e.g. a freshly bought batch reports `usable: false` for ~30s).
+ *
+ * @param beeUrl - Bee node URL
+ * @param batchId - Hex-encoded batch ID (without `0x` prefix)
+ * @returns Batch details, or `undefined` if the Bee node does not know about
+ *          this batch or the request fails.
+ */
+export declare function fetchBatchDetails(beeUrl: string, batchId: string): Promise<BatchDetails | undefined>;
+/**
+ * Fetches the remaining batchTTL (in seconds) for a stamp directly from a Bee
+ * node's `/stamps/{batchId}` endpoint, via {@link fetchBatchDetails}. The Bee
+ * node computes this from current chain state (per-block price and cumulative
+ * outpayment), so it is more accurate than the constant-price approximation
+ * in {@link calculateTTLSeconds}.
+ *
+ * @param beeUrl - Bee node URL
+ * @param batchId - Hex-encoded batch ID (without `0x` prefix)
+ * @returns Remaining TTL in seconds, or `undefined` if the Bee node does not
+ *          know about this batch or the request fails. Negative values from
+ *          the Bee API are normalised to `0` (expired).
+ */
+export declare function fetchBatchTTL(beeUrl: string, batchId: string): Promise<number | undefined>;

package/dist/utils/url.d.ts

@@ -0,0 +1,55 @@
+import type { AppMetadata } from "../types";
+/**
+ * Normalize a URL by removing trailing slash.
+ */
+export declare function normalizeUrl(url: string): string;
+/**
+ * True only for a well-formed `http:`/`https:` URL. Unlike a bare
+ * `new URL(value)` / zod `.url()` check, this rejects a scheme-less paste like
+ * `localhost:1633` (which `new URL` happily parses with protocol `localhost:`)
+ * — the single validator shared by the network-settings schema and its editor
+ * dialog so a broken Bee/RPC endpoint can't be saved or persisted.
+ */
+export declare function isHttpUrl(value: string): boolean;
+/**
+ * True for an address a site may name as its Bee node: an `http:` or
+ * `https:` URL, optionally with a path, the way a gateway in front of Bee is
+ * often mounted. Refused besides what `isHttpUrl` refuses: credentials, which
+ * `fetch` will not send from a URL and throws on, and a query or fragment,
+ * which bee-js would put in the middle of every request path it appends.
+ */
+export declare function isBeeApiUrl(value: string): boolean;
+/**
+ * Configuration options for building the authentication URL.
+ */
+export interface BuildAuthUrlOptions {
+    /**
+     * 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;