@solarpunkltd/swarm-id 0.0.0-stage → 0.8.0

package/dist/proxy/act/act.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Single ACT entry: lookup key + encrypted access key
+ */
+export interface ActEntry {
+    lookupKey: Uint8Array;
+    encryptedAccessKey: Uint8Array;
+}
+/**
+ * Serialize ACT entries to JSON bytes (Bee-compatible Simple Manifest format)
+ *
+ * @param entries - Array of ACT entries
+ * @returns JSON-encoded bytes
+ */
+export declare function serializeAct(entries: ActEntry[]): Uint8Array;
+/**
+ * Deserialize ACT entries from JSON bytes (Bee-compatible Simple Manifest format)
+ *
+ * @param data - JSON-encoded bytes
+ * @returns Array of ACT entries
+ */
+export declare function deserializeAct(data: Uint8Array): ActEntry[];
+/**
+ * Find an ACT entry by lookup key
+ *
+ * @param entries - Array of ACT entries
+ * @param lookupKey - 32-byte lookup key
+ * @returns The entry if found, undefined otherwise
+ */
+export declare function findEntryByLookupKey(entries: ActEntry[], lookupKey: Uint8Array): ActEntry | undefined;
+/**
+ * Check if two public keys are equal
+ */
+export declare function publicKeysEqual(a: {
+    x: Uint8Array;
+    y: Uint8Array;
+}, b: {
+    x: Uint8Array;
+    y: Uint8Array;
+}): boolean;
+/**
+ * Helper to collect all ACT entries from JSON-encoded ACT data
+ *
+ * This is a convenience function for working with JSON ACT data directly from storage.
+ *
+ * @param actData - JSON-encoded ACT data from storage
+ * @returns Array of ACT entries
+ */
+export declare function collectActEntriesFromJson(actData: Uint8Array): ActEntry[];
+/**
+ * Helper to find an ACT entry by lookup key from JSON-encoded ACT data
+ *
+ * This is a convenience function for working with JSON ACT data directly from storage.
+ *
+ * @param actData - JSON-encoded ACT data from storage
+ * @param lookupKey - 32-byte lookup key to search for
+ * @returns The encrypted access key if found, undefined otherwise
+ */
+export declare function findActEntryByKey(actData: Uint8Array, lookupKey: Uint8Array): Uint8Array | undefined;

package/dist/proxy/act/crypto.d.ts

@@ -0,0 +1,46 @@
+import { generateRandomKey } from "../../chunk";
+export { generateRandomKey };
+/**
+ * Derive public key from private key
+ */
+export declare function publicKeyFromPrivate(privKey: Uint8Array): {
+    x: Uint8Array;
+    y: Uint8Array;
+};
+/**
+ * Compute ECDH shared secret (x-coordinate of shared point)
+ *
+ * The public key point is validated to be on secp256k1 (rejects off-curve
+ * points and the point at infinity) before multiplying — feeding an
+ * unvalidated point to scalar multiplication would enable an invalid-curve
+ * attack on the private key.
+ */
+export declare function ecdhSharedSecret(privKey: Uint8Array, pubX: Uint8Array, pubY: Uint8Array): Uint8Array;
+/**
+ * Derive lookup key and access key decryption key from ECDH shared secret
+ */
+export declare function deriveKeys(privKey: Uint8Array, pubX: Uint8Array, pubY: Uint8Array): {
+    lookupKey: Uint8Array;
+    accessKeyDecryptionKey: Uint8Array;
+};
+/**
+ * Counter-mode encryption/decryption
+ * Matches Bee's Go implementation (bee/pkg/encryption/encryption.go:134-168)
+ * For each 32-byte block i: data[i] XOR keccak256(keccak256(key || uint32LE(i)))
+ */
+export declare function counterModeEncrypt(data: Uint8Array, key: Uint8Array): Uint8Array;
+/**
+ * Counter-mode decryption (symmetric with encryption)
+ */
+export declare const counterModeDecrypt: typeof counterModeEncrypt;
+/**
+ * Parse compressed public key (33 bytes) to uncompressed coordinates
+ */
+export declare function publicKeyFromCompressed(compressed: Uint8Array): {
+    x: Uint8Array;
+    y: Uint8Array;
+};
+/**
+ * Compress public key to 33 bytes
+ */
+export declare function compressPublicKey(x: Uint8Array, y: Uint8Array): Uint8Array;

package/dist/proxy/act/grantee-list.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Public key in uncompressed format
+ */
+export interface UncompressedPublicKey {
+    x: Uint8Array;
+    y: Uint8Array;
+}
+/**
+ * Derive the encryption key for the grantee list
+ *
+ * This is different from the legacy format key derivation.
+ * The grantee list is encrypted with a key derived from the publisher's private key.
+ */
+export declare function deriveGranteeListEncryptionKey(publisherPrivKey: Uint8Array): Uint8Array;
+/**
+ * Serialize grantee list to Bee-compatible format
+ *
+ * Bee stores grantees as concatenated 65-byte uncompressed secp256k1 public keys.
+ * Format: [0x04 || X (32 bytes) || Y (32 bytes)] for each key
+ *
+ * @param grantees - Array of public keys with x and y coordinates
+ * @returns Serialized grantee list
+ */
+export declare function serializeGranteeList(grantees: UncompressedPublicKey[]): Uint8Array;
+/**
+ * Deserialize grantee list from Bee-compatible format
+ *
+ * @param data - Serialized grantee list (concatenated 65-byte uncompressed keys)
+ * @returns Array of public keys with x and y coordinates
+ */
+export declare function deserializeGranteeList(data: Uint8Array): UncompressedPublicKey[];
+/**
+ * Encrypt a serialized grantee list for storage
+ *
+ * @param granteeList - Serialized grantee list
+ * @param publisherPrivKey - Publisher's private key for key derivation
+ * @returns Encrypted grantee list
+ */
+export declare function encryptGranteeList(granteeList: Uint8Array, publisherPrivKey: Uint8Array): Uint8Array;
+/**
+ * Decrypt an encrypted grantee list
+ *
+ * @param encryptedList - Encrypted grantee list
+ * @param publisherPrivKey - Publisher's private key for key derivation
+ * @returns Decrypted serialized grantee list
+ */
+export declare function decryptGranteeList(encryptedList: Uint8Array, publisherPrivKey: Uint8Array): Uint8Array;
+/**
+ * Serialize and encrypt grantee list in one step
+ *
+ * @param grantees - Array of public keys
+ * @param publisherPrivKey - Publisher's private key
+ * @returns Encrypted serialized grantee list ready for upload
+ */
+export declare function serializeAndEncryptGranteeList(grantees: UncompressedPublicKey[], publisherPrivKey: Uint8Array): Uint8Array;
+/**
+ * Decrypt and deserialize grantee list in one step
+ *
+ * @param encryptedList - Encrypted serialized grantee list
+ * @param publisherPrivKey - Publisher's private key
+ * @returns Array of public keys
+ */
+export declare function decryptAndDeserializeGranteeList(encryptedList: Uint8Array, publisherPrivKey: Uint8Array): UncompressedPublicKey[];
+/**
+ * Add grantees to an existing encrypted grantee list
+ *
+ * @param encryptedList - Existing encrypted grantee list
+ * @param newGrantees - New grantees to add
+ * @param publisherPrivKey - Publisher's private key
+ * @returns New encrypted grantee list with added grantees
+ */
+export declare function addToGranteeList(encryptedList: Uint8Array, newGrantees: UncompressedPublicKey[], publisherPrivKey: Uint8Array): Uint8Array;
+/**
+ * Remove grantees from an existing encrypted grantee list
+ *
+ * @param encryptedList - Existing encrypted grantee list
+ * @param revokeGrantees - Grantees to remove
+ * @param publisherPrivKey - Publisher's private key
+ * @returns New encrypted grantee list with removed grantees
+ */
+export declare function removeFromGranteeList(encryptedList: Uint8Array, revokeGrantees: UncompressedPublicKey[], publisherPrivKey: Uint8Array): Uint8Array;

package/dist/proxy/act/history.d.ts

@@ -0,0 +1,182 @@
+/**
+ * ACT History Management
+ *
+ * This module provides timestamped versioning of ACT entries, matching Bee's
+ * approach to tracking ACT versions over time.
+ *
+ * Key concepts:
+ * - Each ACT update creates a new history entry
+ * - Entries are keyed by reversed timestamp (MaxInt64 - timestamp)
+ * - History enables looking up ACT state at any point in time
+ * - Encrypted grantee list reference is stored in metadata
+ *
+ * This implementation uses the MantarayNode class from bee-js to produce
+ * Bee-compatible binary manifests with the proper version hash header.
+ *
+ * IMPORTANT: Mantaray manifests are hierarchical - each child node must be
+ * uploaded separately to Swarm. The root node references children by their
+ * content addresses (selfAddress). To read entries, all child nodes must be
+ * loaded recursively.
+ */
+import { MantarayNode } from "@ethersphere/core-sdk";
+/**
+ * Single history entry metadata
+ */
+export interface HistoryEntryMetadata {
+    actReference: string;
+    encryptedGranteeListRef?: string;
+}
+/**
+ * History entry with timestamp
+ */
+export interface HistoryEntry {
+    timestamp: number;
+    metadata: HistoryEntryMetadata;
+}
+/**
+ * Result of serializing a history tree
+ */
+export interface SerializedHistoryTree {
+    blobs: Map<string, Uint8Array>;
+    rootReference: string;
+}
+/**
+ * Result of saving a history tree
+ */
+export interface SaveHistoryTreeResult {
+    rootReference: string;
+    tagUid?: number;
+}
+/**
+ * Calculate reversed timestamp key for history lookup
+ *
+ * Bee uses reversed timestamps so that the latest entry sorts first.
+ * Key = MaxInt64 - timestamp
+ *
+ * @param timestamp - Unix timestamp in seconds
+ * @returns Reversed timestamp as string (for use as path)
+ */
+export declare function calculateReversedTimestamp(timestamp: number): string;
+/**
+ * Calculate original timestamp from reversed key
+ *
+ * @param reversedKey - Reversed timestamp string
+ * @returns Original Unix timestamp in seconds
+ */
+export declare function calculateOriginalTimestamp(reversedKey: string): number;
+/**
+ * Create a new empty history manifest using MantarayNode
+ */
+export declare function createHistoryManifest(): MantarayNode;
+/**
+ * Add an entry to the history manifest
+ *
+ * This mutates the manifest in place by adding a fork.
+ *
+ * @param manifest - Existing history manifest (MantarayNode)
+ * @param timestamp - Unix timestamp for this entry
+ * @param actReference - Reference to the ACT manifest (hex string)
+ * @param encryptedGranteeListRef - Optional reference to encrypted grantee list (hex string)
+ */
+export declare function addHistoryEntry(manifest: MantarayNode, timestamp: number, actReference: string, encryptedGranteeListRef?: string): void;
+/**
+ * Get the latest history entry (most recent timestamp)
+ *
+ * Since keys are reversed timestamps, the smallest key is the latest entry.
+ * NOTE: This requires the manifest to have been loaded with loadRecursively()
+ * or to have been populated locally with addHistoryEntry().
+ *
+ * @param manifest - History manifest (MantarayNode)
+ * @returns Latest entry with its timestamp, or undefined if empty
+ */
+export declare function getLatestEntry(manifest: MantarayNode): HistoryEntry | undefined;
+/**
+ * Get entry at or before a specific timestamp
+ *
+ * This finds the ACT state that was valid at the given timestamp.
+ * NOTE: This requires the manifest to have been loaded with loadRecursively().
+ *
+ * @param manifest - History manifest (MantarayNode)
+ * @param timestamp - Target timestamp
+ * @returns Entry at or before timestamp, or undefined if none exists
+ */
+export declare function getEntryAtTimestamp(manifest: MantarayNode, timestamp: number): HistoryEntry | undefined;
+/**
+ * Get all history entries sorted by timestamp (newest first)
+ *
+ * @param manifest - History manifest (MantarayNode)
+ * @returns Array of entries sorted newest first
+ */
+export declare function getAllEntries(manifest: MantarayNode): HistoryEntry[];
+/**
+ * Serialize the entire history manifest tree to individual blobs
+ *
+ * Mantaray manifests are hierarchical - each node is stored at its content
+ * address. This function returns all blobs that need to be uploaded, keyed
+ * by their content addresses.
+ *
+ * @deprecated Use saveHistoryTreeRecursively instead which uploads bottom-up
+ * and uses Bee's actual returned references to avoid address mismatches.
+ *
+ * @param manifest - History manifest (MantarayNode)
+ * @returns Map of content address -> serialized data, plus root reference
+ */
+export declare function serializeHistoryTree(manifest: MantarayNode): Promise<SerializedHistoryTree>;
+/**
+ * Upload callback type for saveHistoryTreeRecursively
+ */
+export type UploadCallback = (data: Uint8Array, isRoot: boolean) => Promise<{
+    reference: string;
+    tagUid?: number;
+}>;
+/**
+ * Save the entire history manifest tree by uploading bottom-up
+ *
+ * This function uploads nodes in the correct order (children before parents)
+ * and uses Bee's actual returned references to update selfAddress before
+ * marshaling parents. This avoids address mismatches between local hash
+ * computation and Bee's storage.
+ *
+ * The flow mirrors MantarayNode.saveRecursively() from bee-js:
+ * 1. Recursively save all child forks first
+ * 2. Marshal this node (which uses children's updated selfAddress)
+ * 3. Upload and set selfAddress from Bee's response
+ *
+ * @param manifest - History manifest (MantarayNode)
+ * @param uploadFn - Callback to upload data, returns reference from Bee
+ * @returns Root reference from Bee and optional tag UID
+ */
+export declare function saveHistoryTreeRecursively(manifest: MantarayNode, uploadFn: UploadCallback): Promise<SaveHistoryTreeResult>;
+/**
+ * Serialize history manifest root to Mantaray binary format
+ *
+ * @deprecated Use serializeHistoryTree for proper Mantaray serialization
+ * @param manifest - History manifest (MantarayNode)
+ * @returns Serialized root manifest as Uint8Array
+ */
+export declare function serializeHistory(manifest: MantarayNode): Promise<Uint8Array>;
+/**
+ * Deserialize history manifest from Mantaray binary format
+ *
+ * NOTE: After deserialization, call loadRecursively() or manually load
+ * child nodes to populate targetAddress for entries.
+ *
+ * @param data - Serialized manifest
+ * @param selfAddress - The reference/address of the manifest (32 bytes as Uint8Array)
+ * @returns Parsed history manifest (MantarayNode)
+ */
+export declare function deserializeHistory(data: Uint8Array, selfAddress: Uint8Array): MantarayNode;
+/**
+ * Load child node data into a deserialized manifest
+ *
+ * After deserializing the root node, this function loads all child node data
+ * so that targetAddress is available for each entry.
+ *
+ * @param manifest - Deserialized root manifest
+ * @param loadData - Callback to load data for a given reference
+ */
+export declare function loadHistoryEntries(manifest: MantarayNode, loadData: (reference: string) => Promise<Uint8Array>): Promise<void>;
+/**
+ * Get current Unix timestamp in seconds
+ */
+export declare function getCurrentTimestamp(): number;

package/dist/proxy/act/index.d.ts

@@ -0,0 +1,114 @@
+/**
+ * ACT (Access Control Tries) - Bee-Compatible Implementation
+ *
+ * This module provides client-side ACT operations with Bee-compatible
+ * Simple Manifest (JSON) format:
+ * - ACT manifest (JSON with lookup key -> encrypted access key mappings)
+ * - Encrypted grantee list (stored separately)
+ * - History manifest (tracks ACT versions over time)
+ */
+import type { Bee, BeeRequestOptions, UploadOptions } from "@ethersphere/bee-js";
+import type { UploadProgress } from "../types";
+import { type UploadTarget } from "../upload";
+type ActUploadOptions = UploadOptions & {
+    beeCompatible?: boolean;
+};
+/**
+ * The private keys one session may read or publish with. A proxy holds two —
+ * the origin-bound app key and the account-wide sharing key (#519) — and does
+ * not know which one a share was made out to, so every reader/publisher entry
+ * point takes candidates and uses the one the ACT names.
+ */
+export type ActKeyCandidates = Uint8Array | Uint8Array[];
+/**
+ * Result of ACT upload operation
+ */
+export interface ActUploadResult {
+    encryptedReference: string;
+    historyReference: string;
+    granteeListReference: string;
+    publisherPubKey: string;
+    actReference: string;
+    tagUid?: number;
+}
+/**
+ * Result of ACT grantee modification
+ */
+export interface ActGranteeModifyResult {
+    historyReference: string;
+    granteeListReference: string;
+    actReference: string;
+    tagUid?: number;
+}
+/**
+ * Result of ACT revocation. `encryptedReference` is returned unchanged (#496):
+ * revocation drops the revoked entries but must not re-encrypt the reference.
+ */
+export interface ActRevocationResult extends ActGranteeModifyResult {
+    encryptedReference: string;
+}
+/**
+ * Create an ACT-protected upload
+ *
+ * This creates:
+ * 1. ACT manifest (JSON Simple Manifest with lookup key -> encrypted access key mappings)
+ * 2. Encrypted grantee list (for publisher management)
+ * 3. History manifest (tracks ACT versions over time)
+ *
+ * @param config - Upload configuration (stamper or subsidised gateway)
+ * @param contentReference - The reference to protect (32 or 64 bytes)
+ * @param publisherPrivateKey - Publisher's private key (32 bytes)
+ * @param granteePublicKeys - Array of grantee public keys
+ * @param options - Upload options
+ * @param requestOptions - Bee request options
+ * @param onProgress - Progress callback
+ * @returns Multiple references for ACT
+ */
+export declare function createActForContent(target: UploadTarget, contentReference: Uint8Array, publisherPrivateKey: Uint8Array, granteePublicKeys: Array<{
+    x: Uint8Array;
+    y: Uint8Array;
+}>, options?: ActUploadOptions, requestOptions?: BeeRequestOptions, onProgress?: (progress: UploadProgress) => void): Promise<ActUploadResult>;
+/**
+ * Decrypt an ACT-protected reference
+ *
+ * @param bee - Bee instance
+ * @param encryptedReference - The encrypted reference (hex string)
+ * @param historyReference - History manifest reference
+ * @param publisherPubKeyHex - Publisher's compressed public key (hex)
+ * @param readerPrivateKeys - Reader's private key(s), 32 bytes each; the first
+ *   one the ACT names (as a grantee, or as the publisher itself) decrypts
+ * @param timestamp - Optional timestamp to look up specific ACT version
+ * @param requestOptions - Bee request options
+ * @returns Decrypted content reference (hex string)
+ */
+export declare function decryptActReference(bee: Bee, encryptedReference: string, historyReference: string, publisherPubKeyHex: string, readerPrivateKeys: ActKeyCandidates, timestamp?: number, requestOptions?: BeeRequestOptions): Promise<string>;
+/**
+ * Add grantees to an existing ACT
+ */
+export declare function addGranteesToAct(target: UploadTarget, bee: Bee, historyReference: string, publisherCandidates: ActKeyCandidates, newGranteePublicKeys: Array<{
+    x: Uint8Array;
+    y: Uint8Array;
+}>, options?: ActUploadOptions, requestOptions?: BeeRequestOptions, onProgress?: (progress: UploadProgress) => void): Promise<ActGranteeModifyResult>;
+/**
+ * Revoke grantees from an ACT by dropping their entries. The content reference is
+ * returned unchanged — revocation must not re-encrypt it (#496).
+ */
+export declare function revokeGranteesFromAct(target: UploadTarget, bee: Bee, historyReference: string, encryptedReference: string, publisherCandidates: ActKeyCandidates, revokePublicKeys: Array<{
+    x: Uint8Array;
+    y: Uint8Array;
+}>, options?: ActUploadOptions, requestOptions?: BeeRequestOptions, onProgress?: (progress: UploadProgress) => void): Promise<ActRevocationResult>;
+/**
+ * Get grantees from an ACT
+ */
+export declare function getGranteesFromAct(bee: Bee, historyReference: string, publisherCandidates: ActKeyCandidates, requestOptions?: BeeRequestOptions): Promise<string[]>;
+/**
+ * Parse a compressed public key from hex string
+ */
+export declare function parseCompressedPublicKey(hex: string): {
+    x: Uint8Array;
+    y: Uint8Array;
+};
+export { type ActEntry } from "./act";
+export { type UncompressedPublicKey } from "./grantee-list";
+export { type HistoryEntry, type HistoryEntryMetadata } from "./history";
+export { publicKeyFromPrivate, compressPublicKey, publicKeyFromCompressed, } from "./crypto";

package/dist/proxy/app-stamp-limits.d.ts

@@ -0,0 +1,62 @@
+/**
+ * What one app may stamp with the account's stamp through `stampChunk`. A
+ * hacked or greedy app could otherwise fill the person's stamp, so each app
+ * origin gets a count per stamp, a rate, and a share of any one bucket. The
+ * frame keeps the usage per app origin and per stamp in its own storage, so a
+ * reload of the app does not reset it. A new stamp starts a new count.
+ */
+import { z } from "zod";
+import { SwarmIdError } from "../errors";
+/** Slots one app may spend from one of the account's stamps, ever. A stamp again at a slot already held spends none */
+export declare const APP_STAMP_COUNT_LIMIT = 10000;
+/** Stamps one app may take within one {@link APP_STAMP_RATE_WINDOW_MS} */
+export declare const APP_STAMP_RATE_LIMIT = 60;
+/** The rate limit's window. A window starts at the first stamp after the last one ended */
+export declare const APP_STAMP_RATE_WINDOW_MS: number;
+/**
+ * Share of a bucket's data lane one app may use. Rounded down, so at the
+ * smallest usable depth (lane of 7) an app gets 2 slots in any one bucket.
+ */
+export declare const APP_BUCKET_SHARE: number;
+declare const AppStampUsageSchema: z.ZodObject<{
+    count: z.ZodNumber;
+    windowStart: z.ZodNumber;
+    windowCount: z.ZodNumber;
+    buckets: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>;
+/** What one app has stamped with one of the account's stamps */
+export type AppStampUsage = z.infer<typeof AppStampUsageSchema>;
+export declare function emptyAppStampUsage(): AppStampUsage;
+/**
+ * The stored usage, or an empty one when there is none. Only the frame writes
+ * the record, so a malformed one is a bug of ours and starts over rather than
+ * locking the app out for good.
+ */
+export declare function parseAppStampUsage(raw: string | null): AppStampUsage;
+/** Slots one app may use in one bucket of a lane this size */
+export declare function appBucketCap(laneCapacity: number): number;
+/**
+ * Why stamping a single-owner chunk again at the slot it already holds is
+ * refused for this app, or undefined when it is allowed. No slot is spent, so
+ * only the count and the rate apply, not the bucket share.
+ */
+export declare function appRestampRefusal(usage: AppStampUsage, now: number): SwarmIdError | undefined;
+/**
+ * Why the next stamp for this app is refused, or undefined when it is allowed.
+ *
+ * @param target.bucket - The bucket the chunk's address lands in
+ * @param target.laneCapacity - Data chunks the stamper's lane holds per bucket
+ */
+export declare function appStampRefusal(usage: AppStampUsage, target: {
+    bucket: number;
+    laneCapacity: number;
+    now: number;
+}): SwarmIdError | undefined;
+/**
+ * The usage once one more stamp at a slot already held is counted. It spends
+ * no slot, and the count bounds slots spent, so only the rate counts it.
+ */
+export declare function recordAppRestamp(usage: AppStampUsage, now: number): AppStampUsage;
+/** The usage once one more stamp in `bucket` is counted */
+export declare function recordAppStamp(usage: AppStampUsage, bucket: number, now: number): AppStampUsage;
+export {};

package/dist/proxy/chunk-upload-stream.d.ts

@@ -0,0 +1,37 @@
+export interface ChunkUploadStreamOptions {
+    tag?: number;
+    concurrency?: number;
+}
+export declare class ChunkUploadStream {
+    private beeUrl;
+    private options?;
+    private ws;
+    private pendingAcks;
+    private concurrency;
+    private closed;
+    private errorMessage;
+    constructor(beeUrl: string, options?: ChunkUploadStreamOptions | undefined);
+    getConcurrency(): number;
+    /**
+     * Open the WebSocket connection to Bee's chunk stream endpoint.
+     * Resolves when the connection is established.
+     */
+    open(): Promise<void>;
+    /**
+     * Send a stamped chunk over the WebSocket.
+     * The data should already have the 113-byte stamp prepended.
+     *
+     * Respects concurrency limits — will wait if too many chunks are in-flight.
+     */
+    uploadChunk(stampedData: Uint8Array): Promise<void>;
+    /**
+     * Wait for all pending acks to resolve, then close the WebSocket.
+     */
+    close(): Promise<void>;
+    private buildWsUrl;
+    /**
+     * Wait for the next ack to arrive (used for concurrency back-pressure).
+     */
+    private waitForAck;
+    private rejectAllPending;
+}

package/dist/proxy/chunking.d.ts

@@ -0,0 +1,15 @@
+import { Reference } from "@ethersphere/bee-js";
+import { type ContentAddressedChunk } from "../chunk";
+import type { ChunkReference } from "./types";
+export declare const CHUNK_SIZE = 4096;
+export declare const PLAIN_REFS_PER_CHUNK = 128;
+export declare const ENCRYPTED_REFS_PER_CHUNK = 64;
+/**
+ * Split data into 4096-byte chunks
+ */
+export declare function splitDataIntoChunks(data: Uint8Array): Uint8Array[];
+/**
+ * Build merkle tree from chunk references
+ * Returns root reference (32 bytes)
+ */
+export declare function buildMerkleTree(chunkRefs: ChunkReference[], onIntermediateChunk: (chunk: ContentAddressedChunk) => Promise<void>): Promise<Reference>;

package/dist/proxy/collection.d.ts

@@ -0,0 +1,38 @@
+import type { Bee, BeeRequestOptions } from "@ethersphere/bee-js";
+import { type UploadTarget } from "./upload";
+import type { UploadProgress, CollectionFile, CollectionEntry } from "../types";
+export interface UploadCollectionOptions {
+    /** Encrypt file content (default true). `false` also leaves the manifest plain */
+    encrypt?: boolean;
+    /** Encrypt the manifest too, so the root reference carries a key (default true) */
+    encryptManifest?: boolean;
+    pin?: boolean;
+    deferred?: boolean;
+    tag?: number;
+    /** Served for the bare `/bzz/<reference>/` (`website-index-document`) */
+    indexDocument?: string;
+    /** Served for a path that is not in the folder (`website-error-document`) */
+    errorDocument?: string;
+    /** Called once per file */
+    onProgress?: (progress: UploadProgress) => void;
+    requestOptions?: BeeRequestOptions;
+}
+/**
+ * What `uploadFile` and `uploadFiles` encrypt: everything by default, so the
+ * root reference carries a key. `encryptManifest: false` bares the manifest
+ * over encrypted content; `encrypt: false` bares everything — a plain manifest
+ * over plain content is the only shape a bare-manifest reader can use.
+ */
+export declare function manifestEncryption(options: {
+    encrypt?: boolean;
+    encryptManifest?: boolean;
+} | undefined): {
+    content: boolean;
+    manifest: boolean;
+};
+export declare function uploadCollection(target: UploadTarget, files: CollectionFile[], options?: UploadCollectionOptions): Promise<{
+    reference: string;
+    tagUid?: number;
+}>;
+/** The files of a manifest: every node with content, the docs fork excluded. */
+export declare function listCollection(bee: Bee, reference: string, requestOptions?: BeeRequestOptions): Promise<CollectionEntry[]>;

package/dist/proxy/download-data.d.ts

@@ -0,0 +1,27 @@
+import { EthAddress, Identifier } from "@ethersphere/bee-js";
+import type { Bee, BeeRequestOptions, DownloadOptions } from "@ethersphere/bee-js";
+import type { UploadProgress } from "./types";
+import type { SingleOwnerChunk } from "../types";
+/**
+ * The slice of a Bee client that reading chunks needs.
+ *
+ * Everything that only downloads — the feed finders and the chunk readers
+ * here — takes this rather than a whole `Bee`, so a test can hand in a
+ * store-backed mock without casting, and the signature says which of the
+ * client's surface the caller actually depends on. `url` is there for the
+ * log lines only.
+ */
+export type ChunkDownloader = Pick<Bee, "url"> & {
+    chunk: Pick<Bee["chunk"], "download">;
+};
+/**
+ * Download data using only the chunk API
+ * This ensures encrypted data remains encrypted during transmission and avoids metadata leakage
+ *
+ * Supports both:
+ * - Regular references (64 hex chars = 32 bytes)
+ * - Encrypted references (128 hex chars = 64 bytes: 32-byte address + 32-byte encryption key)
+ */
+export declare function downloadDataWithChunkAPI(bee: ChunkDownloader, reference: string, _options?: DownloadOptions, onProgress?: (progress: UploadProgress) => void, requestOptions?: BeeRequestOptions): Promise<Uint8Array>;
+export declare function downloadSOC(bee: ChunkDownloader, owner: string | Uint8Array | EthAddress, identifier: string | Uint8Array | Identifier, requestOptions?: BeeRequestOptions): Promise<SingleOwnerChunk>;
+export declare function downloadEncryptedSOC(bee: ChunkDownloader, owner: string | Uint8Array | EthAddress, identifier: string | Uint8Array | Identifier, encryptionKey: string | Uint8Array, requestOptions?: BeeRequestOptions): Promise<SingleOwnerChunk>;

package/dist/proxy/errors.d.ts

@@ -0,0 +1,8 @@
+import type { WireError } from "../types";
+/**
+ * The endpoint that refused, without its host: bee-js joins the node's base
+ * URL in, and the user's node — a LAN address, an internal hostname — is
+ * theirs, not the dApp's to learn from an error.
+ */
+export declare function refusedPath(url: string): string | undefined;
+export declare function toWireError(error: unknown, fallback: string): WireError;