@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/bus/messages.d.ts

@@ -0,0 +1,241 @@
+/**
+ * Account-bus message schemas.
+ *
+ * Wire format is JSON-serializable (plain objects, hex strings) so the same
+ * messages can later travel transports that leave the browser (WebRTC,
+ * SWIP-60). Receivers parse with `BusMessageSchema`, which revives typed
+ * values (BatchId, PrivateKey, bigint) exactly like the device-state feed
+ * payloads do — see `docs/Account-Bus.md`.
+ */
+import { z } from "zod";
+/**
+ * A full account-state snapshot from another live context. Merged with the
+ * same LWW primitives as a device-state feed payload, minus the session
+ * material above.
+ */
+export declare const AccountDeltaMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"account-delta">;
+    snapshot: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        timestamp: z.ZodNumber;
+        accountId: z.ZodString;
+        metadata: z.ZodObject<{
+            accountName: z.ZodString;
+            defaultPostageStampBatchID: z.ZodOptional<z.ZodString>;
+            publicKey: z.ZodString;
+            settings: z.ZodOptional<z.ZodObject<{
+                appSessionDuration: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            accountNameAt: z.ZodOptional<z.ZodNumber>;
+            defaultStampAt: z.ZodOptional<z.ZodNumber>;
+            settingsAt: z.ZodOptional<z.ZodNumber>;
+            createdAt: z.ZodNumber;
+            lastModified: z.ZodNumber;
+            devices: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodString;
+                createdAt: z.ZodNumber;
+                lastSignedInAt: z.ZodNumber;
+                name: z.ZodOptional<z.ZodString>;
+                nameUpdatedAt: z.ZodOptional<z.ZodNumber>;
+                removedAt: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>>;
+            partitionCount: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>;
+        postageStamps: z.ZodArray<z.ZodObject<{
+            batchID: z.ZodPipe<z.ZodString, z.ZodTransform<import("@ethersphere/core-sdk").BatchId, string>>;
+            signerKey: z.ZodPipe<z.ZodString, z.ZodTransform<import("@ethersphere/core-sdk").PrivateKey, string>>;
+            name: z.ZodOptional<z.ZodString>;
+            nameUpdatedAt: z.ZodOptional<z.ZodNumber>;
+            utilization: z.ZodNumber;
+            usable: z.ZodBoolean;
+            depth: z.ZodNumber;
+            amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+            bucketDepth: z.ZodNumber;
+            blockNumber: z.ZodNumber;
+            immutableFlag: z.ZodBoolean;
+            exists: z.ZodBoolean;
+            batchTTL: z.ZodOptional<z.ZodNumber>;
+            createdAt: z.ZodNumber;
+            updatedAt: z.ZodOptional<z.ZodNumber>;
+            deletedAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        connectedApps: z.ZodArray<z.ZodObject<{
+            appName: z.ZodString;
+            appDescription: z.ZodOptional<z.ZodString>;
+            appIcon: z.ZodOptional<z.ZodString>;
+            appUrl: z.ZodString;
+            lastConnectedAt: z.ZodNumber;
+            postageStampBatchID: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@ethersphere/core-sdk").BatchId, string>>>;
+            postageStampBatchIDAt: z.ZodOptional<z.ZodNumber>;
+            revokedAt: z.ZodOptional<z.ZodNumber>;
+            disconnectedAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * A context waiting for a batch-write partition (all slots held by live
+ * peers) asks live holders to yield. An idle holder releases via the normal
+ * Swarm lease protocol and answers with `lease-released`; holders mid-write
+ * ignore it. Repeats are harmless (yield-if-idle is a guarded no-op).
+ *
+ * `batchId` scopes the ask, because the lock it is a fast path for is scoped
+ * that way: lanes are per (batch, partition) since #589, so a holder on batch X
+ * and a waiter on batch Y contend for nothing. Answering across batches would
+ * drop a lease for a waiter it cannot help — the bus must not be broader than
+ * the lock it front-runs, any more than it may be narrower.
+ *
+ * `requestId` is 8 hex chars, fresh per poll round, and exists so exactly one
+ * holder answers: each derives the same permutation of the partitions from it
+ * and yields at its own rank (`swarm-id-proxy.ts`, `yieldRankDelayMs`). It is
+ * format-checked: the rank is `parseInt(requestId, 16)`, so an unconstrained
+ * string reintroduces the very bug this fixes (`NaN` or a negative collapses
+ * every holder onto the same rank), silently and with nothing to diagnose.
+ */
+export declare const LeaseRequestMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"lease-request">;
+    accountId: z.ZodString;
+    batchId: z.ZodString;
+    fromDeviceId: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * The holder that drew the lowest rank for `requestId` is answering it. Sent
+ * BEFORE the release starts, because the release itself is two stamped Swarm
+ * writes — an order of magnitude longer than the rank step — so a signal sent
+ * after it would reach the other holders only once they had all begun yielding
+ * too, which is #576 again. Holders further down the order stand down on this;
+ * the waiter ignores it (no slot is free yet).
+ */
+export declare const LeaseClaimMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"lease-claim">;
+    accountId: z.ZodString;
+    batchId: z.ZodString;
+    fromDeviceId: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strip>;
+/**
+ * A holder released its partition (on request or teardown) — waiting peers
+ * wake their slot poll immediately instead of sleeping out the interval. The
+ * lock SOCs on Swarm remain the authority; this is purely a wake-up.
+ *
+ * `requestId` echoes the `lease-request` this answers, so holders further down
+ * the rank order can stand down. Absent on a teardown release, which answers
+ * no request.
+ */
+export declare const LeaseReleasedMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"lease-released">;
+    accountId: z.ZodString;
+    batchId: z.ZodString;
+    partition: z.ZodNumber;
+    fromDeviceId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * "This device is live." Published on joining the room and every
+ * `PRESENCE_INTERVAL_MS` (`presence.ts`); a receiver stamps its own clock, so
+ * there is no timestamp to skew and a replay (#604) only refreshes a device it
+ * has already heard. A peer on an older bundle drops it at the schema — a new
+ * kind, not an envelope change, so nothing to deploy in step.
+ */
+export declare const PresenceMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"presence">;
+    accountId: z.ZodString;
+    fromDeviceId: z.ZodString;
+}, z.core.$strip>;
+export declare const BusMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"utilization-updated">;
+    batchId: z.ZodString;
+    partition: z.ZodNumber;
+    partitionCount: z.ZodNumber;
+    buckets: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        value: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"account-delta">;
+    snapshot: z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        timestamp: z.ZodNumber;
+        accountId: z.ZodString;
+        metadata: z.ZodObject<{
+            accountName: z.ZodString;
+            defaultPostageStampBatchID: z.ZodOptional<z.ZodString>;
+            publicKey: z.ZodString;
+            settings: z.ZodOptional<z.ZodObject<{
+                appSessionDuration: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
+            accountNameAt: z.ZodOptional<z.ZodNumber>;
+            defaultStampAt: z.ZodOptional<z.ZodNumber>;
+            settingsAt: z.ZodOptional<z.ZodNumber>;
+            createdAt: z.ZodNumber;
+            lastModified: z.ZodNumber;
+            devices: z.ZodDefault<z.ZodArray<z.ZodObject<{
+                deviceId: z.ZodString;
+                createdAt: z.ZodNumber;
+                lastSignedInAt: z.ZodNumber;
+                name: z.ZodOptional<z.ZodString>;
+                nameUpdatedAt: z.ZodOptional<z.ZodNumber>;
+                removedAt: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>>;
+            partitionCount: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>;
+        postageStamps: z.ZodArray<z.ZodObject<{
+            batchID: z.ZodPipe<z.ZodString, z.ZodTransform<import("@ethersphere/core-sdk").BatchId, string>>;
+            signerKey: z.ZodPipe<z.ZodString, z.ZodTransform<import("@ethersphere/core-sdk").PrivateKey, string>>;
+            name: z.ZodOptional<z.ZodString>;
+            nameUpdatedAt: z.ZodOptional<z.ZodNumber>;
+            utilization: z.ZodNumber;
+            usable: z.ZodBoolean;
+            depth: z.ZodNumber;
+            amount: z.ZodPipe<z.ZodString, z.ZodTransform<bigint, string>>;
+            bucketDepth: z.ZodNumber;
+            blockNumber: z.ZodNumber;
+            immutableFlag: z.ZodBoolean;
+            exists: z.ZodBoolean;
+            batchTTL: z.ZodOptional<z.ZodNumber>;
+            createdAt: z.ZodNumber;
+            updatedAt: z.ZodOptional<z.ZodNumber>;
+            deletedAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+        connectedApps: z.ZodArray<z.ZodObject<{
+            appName: z.ZodString;
+            appDescription: z.ZodOptional<z.ZodString>;
+            appIcon: z.ZodOptional<z.ZodString>;
+            appUrl: z.ZodString;
+            lastConnectedAt: z.ZodNumber;
+            postageStampBatchID: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@ethersphere/core-sdk").BatchId, string>>>;
+            postageStampBatchIDAt: z.ZodOptional<z.ZodNumber>;
+            revokedAt: z.ZodOptional<z.ZodNumber>;
+            disconnectedAt: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"lease-request">;
+    accountId: z.ZodString;
+    batchId: z.ZodString;
+    fromDeviceId: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"lease-claim">;
+    accountId: z.ZodString;
+    batchId: z.ZodString;
+    fromDeviceId: z.ZodString;
+    requestId: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"lease-released">;
+    accountId: z.ZodString;
+    batchId: z.ZodString;
+    partition: z.ZodNumber;
+    fromDeviceId: z.ZodString;
+    requestId: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"presence">;
+    accountId: z.ZodString;
+    fromDeviceId: z.ZodString;
+}, z.core.$strip>], "type">;
+export type AccountDeltaMessage = z.infer<typeof AccountDeltaMessageSchema>;
+/** The wire form of a delta: hex strings, not revived `BatchId`/`PrivateKey`. */
+export type AccountDeltaInput = z.input<typeof AccountDeltaMessageSchema>;
+export type BusMessage = z.infer<typeof BusMessageSchema>;
+/** What publishers hand to the bus: the JSON-serializable wire form. */
+export type BusMessageInput = z.input<typeof BusMessageSchema>;

package/dist/bus/presence.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Who is live on the account bus, as seen from one context.
+ *
+ * Every context in the room publishes a `presence` on join and every
+ * `PRESENCE_INTERVAL_MS`; a receiver notes the time it heard each device. A
+ * device unheard for `PRESENCE_MAX_AGE_MS` is no longer live. That is the whole
+ * mechanism: the bus already knows who is in the room, this only ties room
+ * membership to a `deviceId`.
+ *
+ * A clean departure does not wait for the window. The signaling server sends
+ * `peer-left` when a socket closes — including one its own reaper terminated,
+ * so a crash and a dropped network count too — and `forgetPeer` drops the
+ * device that socket carried (#572). Ageing is the backstop for what that
+ * cannot see: a peer the server has not yet reaped, and a device heard only
+ * over the local transport. A leave message of our own is not an option — a
+ * publish encrypts before it sends, and a page being torn down never gets
+ * back to the send.
+ *
+ * In memory only, and deliberately never persisted or published as state. A
+ * `lastSeenAt` that rode the account snapshot would make every publish a byte
+ * change to fold and re-persist, and the unpartitioned proxy answers every
+ * storage event with a bus delta and a stamped feed write — a loop that never
+ * settles, even on one device. Durable truth (`lastSignedInAt`) keeps meaning
+ * "signed in"; liveness lives here and is rebuilt from scratch on every load.
+ */
+export declare const PRESENCE_INTERVAL_MS = 20000;
+/**
+ * Three missed beats — of the THROTTLED interval, not ours. A window of three
+ * of our own beats sits exactly at a hidden tab's clamped cadence, so a
+ * backgrounded-but-live device would flap in and out of its peers' live sets:
+ * a blinking badge, and a coordinator repeatedly re-including the same peer in
+ * an idle-yield round. Being slow to drop a device that really left costs only
+ * an absent intent read, which is why the window errs long. Still well past
+ * `LEASE_TTL_MS` and far inside `KNOWN_DEVICE_MAX_AGE_MS`.
+ */
+export declare const PRESENCE_MAX_AGE_MS: number;
+export declare class PresenceTracker {
+    private seen;
+    /**
+     * Note a beat. `peerId` is the transport's own name for whoever sent it —
+     * present on the signaling transport, absent on the local one, which has no
+     * peers. It is what lets a departure be attributed to a device (#572).
+     */
+    observe(deviceId: string, nowMs: number, peerId?: string): void;
+    /**
+     * A socket left the room, so whatever it carried is gone with it.
+     *
+     * Only when it was the device's LAST socket: two tabs of one dApp share a
+     * partition, and therefore a `deviceId`, while holding a socket each — one
+     * of them closing is not the device leaving. A device heard only over the
+     * local transport has no socket to lose and is left to age out.
+     *
+     * Every entry is checked rather than stopping at the first match. Nothing
+     * here enforces that one socket only ever beats under one `deviceId`, and a
+     * device left holding a dead socket id could only age out — the three-minute
+     * wait this exists to remove. The loop is over a handful of entries.
+     */
+    forgetPeer(peerId: string): void;
+    /** Devices heard within `PRESENCE_MAX_AGE_MS` of `nowMs`. */
+    liveDeviceIds(nowMs: number): string[];
+    clear(): void;
+}

package/dist/bus/signaling-transport.d.ts

@@ -0,0 +1,79 @@
+import type { BusTransport } from "./account-bus";
+import type { BusMessageInput } from "./messages";
+export interface SignalingTransportOptions {
+    /** Signaling server URL, e.g. `wss://bus.example.com/bus`. */
+    url: string;
+    /** Account-derived room topic (`deriveBusContext`). */
+    topic: string;
+    /** Account-derived AES-GCM envelope key (`deriveBusContext`). */
+    encryptionKey: CryptoKey;
+    /**
+     * Factory for the WebRTC upgrade; omit to stay relay-only (e.g. in
+     * environments without RTCPeerConnection). No STUN/TURN is configured by
+     * default: same-device loopback and LAN peers connect via host candidates,
+     * everything else falls back to the relay.
+     */
+    createPeerConnection?: () => RTCPeerConnection;
+}
+export declare class SignalingTransport implements BusTransport {
+    readonly local = false;
+    private options;
+    private socket;
+    private peers;
+    private handlers;
+    private peerLeftHandlers;
+    private closed;
+    private reconnectDelayMs;
+    private reconnectTimer;
+    /** In-flight `deliver` calls, awaited by `close()` so a teardown
+     *  announcement published in the closing tick still reaches the wire. */
+    private pendingDeliveries;
+    constructor(options: SignalingTransportOptions);
+    /** Live peers currently visible in the room (test/debug aid). */
+    get peerCount(): number;
+    publish(message: BusMessageInput): void;
+    subscribe(handler: (raw: unknown, from?: string) => void): () => void;
+    onPeerLeft(handler: (peerId: string) => void): () => void;
+    /**
+     * Stops reconnecting at once, but lets in-flight publishes reach the wire
+     * first: `deliver` awaits envelope encryption, and callers announce a
+     * teardown (`lease-released`) and close the bus in the same tick, so tearing
+     * the socket down synchronously would drop exactly the message a waiting
+     * peer is owed. Each pending delivery is a single encrypt plus synchronous
+     * sends, so this settles promptly — it is not a flush of a send queue.
+     */
+    close(): void;
+    private shutdown;
+    private connect;
+    private scheduleReconnect;
+    private deliver;
+    private sendToServer;
+    private handleServerMessage;
+    private receiveEnvelope;
+    private initiatePeerConnection;
+    private handleSignal;
+    /**
+     * Install a freshly created connection on a peer, closing whatever was there.
+     * A duplicate or renegotiated offer used to overwrite the field and leak the
+     * previous `RTCPeerConnection`, which keeps its ICE agent and sockets alive.
+     * The candidate queue resets with it: the new connection has no remote
+     * description, and candidates gathered for the old one are meaningless.
+     */
+    private adoptConnection;
+    /**
+     * Replay the candidates that arrived before the remote description. One bad
+     * candidate must not strand the rest, so each is applied on its own.
+     *
+     * Takes the connection whose description just landed, and does nothing if the
+     * peer has moved on to another: signals are handled concurrently, so a second
+     * offer can be adopted while this one is still awaiting
+     * `setRemoteDescription`, and marking the flag then would describe a
+     * connection that has no remote description — re-opening the drop window this
+     * queue exists to close, for candidates that arrive before the new
+     * negotiation finishes.
+     */
+    private flushPendingCandidates;
+    private adoptDataChannel;
+    private forwardIceCandidates;
+    private sendSignal;
+}

package/dist/chunk/bmt.d.ts

@@ -0,0 +1,16 @@
+import { Reference } from "@ethersphere/bee-js";
+/**
+ * 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 declare function calculateChunkAddress(chunkContent: Uint8Array): Reference;

package/dist/chunk/cac.d.ts

@@ -0,0 +1,17 @@
+import { Bytes, Reference, Span } from "@ethersphere/bee-js";
+/**
+ * Content addressed chunk interface
+ */
+export interface ContentAddressedChunk {
+    readonly data: Uint8Array;
+    readonly span: Span;
+    readonly payload: Bytes;
+    readonly address: Reference;
+}
+/**
+ * Creates a content addressed chunk from payload data
+ *
+ * @param payloadBytes the data to be stored in the chunk (1-4096 bytes)
+ * @param spanOverride optional span value to use instead of payload length
+ */
+export declare function makeContentAddressedChunk(payloadBytes: Uint8Array | string, spanOverride?: Span | bigint): ContentAddressedChunk;

package/dist/chunk/constants.d.ts

@@ -0,0 +1,10 @@
+export declare const MIN_PAYLOAD_SIZE = 0;
+export declare const MAX_PAYLOAD_SIZE = 4096;
+export declare const SPAN_SIZE = 8;
+export declare const UNENCRYPTED_REF_SIZE = 32;
+export declare const ENCRYPTED_REF_SIZE = 64;
+export declare const IDENTIFIER_SIZE = 32;
+export declare const SIGNATURE_SIZE = 65;
+export declare const SOC_HEADER_SIZE: number;
+export declare const DEFAULT_DOWNLOAD_CONCURRENCY = 64;
+export declare const DEFAULT_UPLOAD_CONCURRENCY = 8;

package/dist/chunk/encrypted-cac.d.ts

@@ -0,0 +1,47 @@
+import { Bytes, Reference, Span } from "@ethersphere/bee-js";
+import { type Key } from "./encryption";
+/**
+ * Encrypted chunk interface
+ *
+ * The reference includes both the chunk address and the encryption key (64 bytes total)
+ */
+export interface EncryptedChunk {
+    readonly data: Uint8Array;
+    readonly encryptionKey: Key;
+    readonly span: Span;
+    readonly payload: Bytes;
+    readonly address: Reference;
+    readonly reference: Reference;
+}
+/**
+ * Creates an encrypted content addressed chunk
+ *
+ * Process:
+ * 1. Create chunk with span + payload
+ * 2. Encrypt the chunk data
+ * 3. Calculate BMT hash on encrypted data
+ * 4. Return reference = address + encryption key (64 bytes)
+ *
+ * @param payloadBytes the data to be stored in the chunk
+ * @param encryptionKey optional encryption key (if not provided, a random key will be generated)
+ */
+export declare function makeEncryptedContentAddressedChunk(payloadBytes: Uint8Array | string, encryptionKey?: Key): EncryptedChunk;
+/**
+ * Decrypts an encrypted chunk given the encryption key
+ *
+ * @param encryptedChunkData The encrypted chunk data (span + payload)
+ * @param encryptionKey The 32-byte encryption key
+ */
+export declare function decryptEncryptedChunk(encryptedChunkData: Uint8Array, encryptionKey: Key): Uint8Array;
+/**
+ * Extracts encryption key from a 64-byte encrypted reference
+ *
+ * @param reference 64-byte reference (address + key)
+ */
+export declare function extractEncryptionKey(reference: Reference): Key;
+/**
+ * Extracts the chunk address from a 64-byte encrypted reference
+ *
+ * @param reference 64-byte reference (address + key)
+ */
+export declare function extractChunkAddress(reference: Reference): Reference;

package/dist/chunk/encryption.d.ts

@@ -0,0 +1,85 @@
+export declare const KEY_LENGTH = 32;
+export declare const REFERENCE_SIZE = 64;
+export type Key = Uint8Array;
+export interface Encrypter {
+    key(): Key;
+    encrypt(data: Uint8Array): Uint8Array;
+}
+export interface Decrypter {
+    key(): Key;
+    decrypt(data: Uint8Array): Uint8Array;
+}
+export interface EncryptionInterface extends Encrypter, Decrypter {
+    reset(): void;
+}
+/**
+ * Core encryption class implementing CTR-mode encryption with Keccak256
+ * This matches the Go implementation in bee/pkg/encryption/encryption.go
+ */
+export declare class Encryption implements EncryptionInterface {
+    private readonly encryptionKey;
+    private readonly keyLen;
+    private readonly padding;
+    private index;
+    private readonly initCtr;
+    constructor(key: Key, padding: number, initCtr: number);
+    key(): Key;
+    /**
+     * Encrypts data with optional padding
+     */
+    encrypt(data: Uint8Array): Uint8Array;
+    /**
+     * Decrypts data (caller must know original length if padding was used)
+     */
+    decrypt(data: Uint8Array): Uint8Array;
+    /**
+     * Resets the counter - only safe to call after encryption/decryption is completed
+     */
+    reset(): void;
+    /**
+     * Transforms data by splitting into key-length segments and encrypting sequentially
+     */
+    private transform;
+    /**
+     * Segment-wise transformation using XOR with Keccak256-derived keys
+     * Matches the Go implementation's Transcrypt function
+     */
+    private transcrypt;
+}
+/**
+ * Generates a cryptographically secure random key
+ */
+export declare function generateRandomKey(length?: number): Key;
+/**
+ * Creates encryption interface for chunk span (first 8 bytes)
+ */
+export declare function newSpanEncryption(key: Key): EncryptionInterface;
+/**
+ * Creates encryption interface for chunk data
+ */
+export declare function newDataEncryption(key: Key): EncryptionInterface;
+export interface ChunkEncrypter {
+    encryptChunk(chunkData: Uint8Array, key?: Key): {
+        key: Key;
+        encryptedSpan: Uint8Array;
+        encryptedData: Uint8Array;
+    };
+}
+/**
+ * Default chunk encrypter implementation
+ */
+export declare class DefaultChunkEncrypter implements ChunkEncrypter {
+    encryptChunk(chunkData: Uint8Array, key?: Key): {
+        key: Key;
+        encryptedSpan: Uint8Array;
+        encryptedData: Uint8Array;
+    };
+}
+/**
+ * Creates a new chunk encrypter
+ */
+export declare function newChunkEncrypter(): ChunkEncrypter;
+/**
+ * Decrypts encrypted chunk data using the provided encryption key
+ */
+export declare function decryptChunkData(key: Key, encryptedChunkData: Uint8Array): Uint8Array;

package/dist/chunk/index.d.ts

@@ -0,0 +1,5 @@
+export { MIN_PAYLOAD_SIZE, MAX_PAYLOAD_SIZE, SPAN_SIZE, UNENCRYPTED_REF_SIZE, ENCRYPTED_REF_SIZE, IDENTIFIER_SIZE, SIGNATURE_SIZE, SOC_HEADER_SIZE, DEFAULT_DOWNLOAD_CONCURRENCY, DEFAULT_UPLOAD_CONCURRENCY, } from "./constants";
+export { type Key, type ChunkEncrypter, type Encrypter, type Decrypter, type EncryptionInterface, KEY_LENGTH, REFERENCE_SIZE, newChunkEncrypter, decryptChunkData, generateRandomKey, newSpanEncryption, newDataEncryption, Encryption, DefaultChunkEncrypter, } from "./encryption";
+export { calculateChunkAddress } from "./bmt";
+export { type ContentAddressedChunk, makeContentAddressedChunk } from "./cac";
+export { type EncryptedChunk, makeEncryptedContentAddressedChunk, decryptEncryptedChunk, extractEncryptionKey, extractChunkAddress, } from "./encrypted-cac";