@solarpunkltd/swarm-id 0.0.0-stage → 0.8.1

package/dist/utils/batch-write-lock.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Run `op` under an exclusive, cross-tab Web Lock keyed on the postage batch.
+ *
+ * All writers to a given batch — every same-origin context: dApp proxy iframes
+ * and the SwarmID UI — request the same lock name, so only one write runs at a
+ * time across tabs. This is the single definition of the `swarm-write-<batchId>`
+ * convention (the proxy and the account-sync path both use it).
+ *
+ * Falls back to running `op` directly when the Web Locks API is unavailable
+ * (Node / test environments).
+ */
+export declare function withBatchWriteLock<T>(batchIdHex: string | undefined, op: () => Promise<T>): Promise<T>;

package/dist/utils/bee-error.d.ts

@@ -0,0 +1,11 @@
+/**
+ * True only for a definitive "chunk absent" — an HTTP 404, as Bee's `/soc`
+ * endpoint returns for a missing single-owner chunk (`BeeResponseError.status`).
+ * A timeout / 5xx / network error is INCONCLUSIVE, not a confirmed miss.
+ *
+ * NOTE: Bee's `/chunks` endpoint returns **500** ("read chunk failed") for an
+ * absent chunk, so this predicate is usable for the roster `/soc` existence read
+ * but NOT for the `/chunks`-based feed finders — there, absence and a transient
+ * server error are indistinguishable by status.
+ */
+export declare function isNotFoundError(error: unknown): boolean;

package/dist/utils/chat-binding.d.ts

@@ -0,0 +1,113 @@
+/** The first line, which also versions the format. */
+export declare const CHAT_BINDING_TITLE = "Swarm ID chat binding v1";
+export interface SiteOriginOptions {
+    /**
+     * Also accept `http://localhost`, `http://127.0.0.1` and `http://[::1]`
+     * with any port. Only a development build passes this.
+     */
+    allowLocalHttp?: boolean;
+}
+/** A signed binding as it travels: the message and its signature. */
+export interface ChatBinding {
+    message: string;
+    /** `0x` + r ‖ s ‖ v, 65 bytes, v 27 or 28. */
+    signature: string;
+}
+/** The three fields a binding message carries, as the message spells them. */
+export interface ChatBindingFields {
+    site: string;
+    /** `0x` + 40 lower-case hex characters. */
+    chatAddress: string;
+    /** ISO 8601 UTC, as `Date.prototype.toISOString` writes it. */
+    date: string;
+}
+export interface VerifiedChatBinding extends ChatBindingFields {
+    /** The recovered signer, `0x` + 40 lower-case hex characters. */
+    signer: string;
+}
+/** What a binding has to name for a reader to accept it. */
+export interface ExpectedChatBinding {
+    site: string;
+    chatAddress: string;
+    signer: string;
+}
+/**
+ * Whether `value` is a bare https origin in the exact form the browser
+ * reports one: a host and nothing else, no path, query, fragment or user
+ * info, lower case, punycode, no default port. Anything a URL parser would
+ * have to normalize is refused rather than normalized, so one site has one
+ * spelling.
+ */
+export declare function isCleanSiteOrigin(value: string, options?: SiteOriginOptions): boolean;
+/** Build the exact four-line message for these fields. */
+export declare function buildChatBindingMessage(fields: {
+    site: string;
+    chatAddress: string;
+    date: Date;
+}, options?: SiteOriginOptions): string;
+/**
+ * Read the fields out of a binding message, refusing every shape but the one
+ * `buildChatBindingMessage` writes: another first line, a missing or extra
+ * line, a trailing newline, a site that is not a clean origin, an address in
+ * another spelling, a date in another form.
+ */
+export declare function parseChatBindingMessage(message: string, options?: SiteOriginOptions): ChatBindingFields;
+/**
+ * The chat address a site's binding names: the address of the site's chat key
+ * (`deriveChatKey`), bare lower-case hex. The one place that says which key a
+ * binding is about, for the window that signs one and the frame that checks a
+ * handed-over one.
+ *
+ * @param appSecret - the site's app secret (bare hex)
+ */
+export declare function siteChatAddress(appSecret: string): string;
+/**
+ * Sign the binding for `site` with the account's own key. The chat address is
+ * the address of the site's chat key, derived from that same key here, so no
+ * caller can bind an address the account does not hold for that site.
+ *
+ * @param accountKey - the account's private key (bare hex), whose address is
+ *   the account's `id`
+ */
+export declare function createChatBinding(accountKey: string, site: string, date: Date, options?: SiteOriginOptions): ChatBinding;
+/**
+ * Check a binding's shape and recover who signed it. Throws on a message of
+ * any other shape and on a signature that is not 65 bytes with v 27 or 28 and
+ * a low s. A valid signature over a changed message recovers SOME address,
+ * which is why a reader compares `signer` with the account it expects
+ * (`acceptedChatBinding` does).
+ */
+export declare function verifyChatBinding(binding: ChatBinding, options?: SiteOriginOptions): VerifiedChatBinding;
+/**
+ * The binding, if it verifies and names exactly this site, this chat address
+ * and this signer, otherwise undefined. Addresses compare in any case and
+ * with or without `0x`.
+ */
+export declare function acceptedChatBinding(binding: ChatBinding | undefined, expected: ExpectedChatBinding, options?: SiteOriginOptions): ChatBinding | undefined;
+/**
+ * The connected apps with every chat binding removed except `site`'s own.
+ *
+ * Each site's binding publicly links the account to its chat on that site, and
+ * a proxy frame runs inside one site's page, where that page's scripts can
+ * reach what the frame holds. So everything handed to a frame keeps only the
+ * binding of the site it runs for. The account's own synced copy keeps all of
+ * them.
+ */
+export declare function onlySiteChatBinding<App extends {
+    appUrl: string;
+    chatBinding?: ChatBinding;
+}>(apps: readonly App[], site: string): App[];
+/**
+ * Of two bindings for the connection to `site` in `account`'s state, the one
+ * `account` signed for `site` over one it did not, then the later date, the
+ * first on a tie, and whichever is there when only one is. The date is the
+ * signer's own claim, and any message with a valid signature recovers SOME
+ * signer, so a binding whose date was edited, or that another key signed, must
+ * never outrank the account's own by claiming a later one. A binding is never
+ * withdrawn, only replaced by a newer one (docs/Chat-Binding.md), so this is
+ * the whole of how two copies of a connection merge theirs.
+ *
+ * @param account - the account's address, its `id`, in any case and with or
+ *   without `0x`
+ */
+export declare function newerChatBinding(first: ChatBinding | undefined, second: ChatBinding | undefined, site: string, account: string): ChatBinding | undefined;

package/dist/utils/coalesced-task.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Run `task` at most once per `cooldownMs` across all same-origin browser tabs.
+ *
+ * An exclusive Web Lock (`navigator.locks`, keyed on `lockName`) serialises
+ * concurrent callers so two tabs can't run `task` at the same instant; a shared
+ * `localStorage` timestamp (`cooldownKey`) then lets the second caller skip when
+ * another tab already ran within the window. `force` bypasses the cooldown (e.g.
+ * a page load / manual refresh) but still honours the optional short `graceMs`
+ * window, so a burst of forced runs (N tabs on load, or two back-to-back forced
+ * triggers) still collapses to one.
+ *
+ * Effect: with several tabs each scheduling the same task, only ONE actually runs
+ * per window — the rest observe the fresh timestamp and return. Whatever the task
+ * persists (e.g. the account document) then propagates to the other tabs via their
+ * own `storage` listeners, so they never need to fetch themselves.
+ *
+ * Falls back to running `task` directly when the Web Locks API is unavailable
+ * (Node / test), still honouring the cooldown when `localStorage` is present.
+ */
+export declare function runCoalescedAcrossTabs(opts: {
+    lockName: string;
+    cooldownKey: string;
+    cooldownMs: number;
+    force?: boolean;
+    /** Short window honoured even under `force` — collapses back-to-back forced runs. */
+    graceMs?: number;
+    task: () => Promise<void>;
+}): Promise<void>;

package/dist/utils/collection.d.ts

@@ -0,0 +1,6 @@
+/**
+ * A file's path inside the folder it was picked with. `webkitdirectory` and a
+ * dropped directory prefix every path with the folder's own name; that segment
+ * goes, so `index.html` sits at the manifest root — the rule bee-js applies.
+ */
+export declare function collectionPath(file: Pick<File, "name" | "webkitRelativePath">): string;

package/dist/utils/connection-info.d.ts

@@ -0,0 +1,11 @@
+import type { ConnectionInfo } from "../types";
+/**
+ * Structural equality for {@link ConnectionInfo} snapshots, scoped to the
+ * fields the proxy emits to dApps. Used by the proxy to suppress redundant
+ * `connectionInfoChanged` events.
+ *
+ * `storagePartitioned` is compared via boolean coercion so a writer that
+ * sends `false` and one that omits the field (effectively `undefined`)
+ * are treated as equal — they mean the same thing to the dApp.
+ */
+export declare function connectionInfoEqual(a: ConnectionInfo | undefined, b: ConnectionInfo): boolean;

package/dist/utils/constants.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Time and Session Constants
+ *
+ * Centralized constants for time units and default session durations.
+ */
+export declare const SECOND = 1000;
+export declare const MINUTE: number;
+export declare const HOUR: number;
+export declare const DAY: number;
+/**
+ * A saved session lets a site keep writing until its next load notices a
+ * revoke, so it is kept short. An account can set its own.
+ */
+export declare const DEFAULT_SESSION_DURATION: number;
+/**
+ * How long a connection to a dApp lasts, in ms: the account's own setting, or
+ * the default above.
+ *
+ * One rule with two callers on opposite sides of the handover — the popup
+ * writes `connectedUntil` from it when it saves the connection
+ * (`ui/src/lib/connect-handshake.ts`), and a partitioned proxy recomputes the
+ * same deadline when it hydrates (`hydratePartitionAccount`). Two copies of
+ * `?? DEFAULT_SESSION_DURATION` is one copy that goes stale when the rule
+ * gains a clamp or a floor (#590).
+ */
+export declare function appSessionDuration(settings?: {
+    appSessionDuration?: number;
+}): number;

package/dist/utils/device-id.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Device ID Utilities
+ *
+ * Manages a per-browser device identifier stored in localStorage and
+ * provides helpers for merging device lists across sync/restore.
+ */
+import type { Device } from "../schemas";
+/**
+ * Get the current device ID, creating one if it doesn't exist.
+ */
+export declare function getOrCreateDeviceId(): string;
+/**
+ * Merge a device list with the current device.
+ *
+ * Upserts the current device: creates the entry if absent, otherwise leaves it
+ * as it is apart from the name. A `deviceName` we are given REPLACES the stored
+ * one, so a caller that learns a better label — the partition naming of #570 —
+ * corrects the row already in the registry instead of only the next one
+ * created. A caller with nothing to say passes nothing and the stored label
+ * stands: the name must not be blanked by a context that does not know it.
+ *
+ * A replacement carries `nameUpdatedAt`, the name's own merge clock, without
+ * which the correction never left this device: `mergeDevicesList` ranks records
+ * on sign-in recency, a rename moves none of it, and a tie favours the local
+ * copy — so every other context kept its stale label forever (#663). Only an
+ * ACTUAL change stamps it. Both callers are polls, and a clock that moved every
+ * time a caller passed the name it already stored would make every quiet round
+ * a byte change to persist, which is the churn #652 removed.
+ *
+ * Touches neither `removedAt` nor `lastSignedInAt` on an existing entry. Both
+ * callers are refresh paths — the proxy's throttled roster poll and the UI's
+ * periodic fold — and a poll is not a sign-in: clearing our own tombstone here
+ * undid every removal on the next round (#611), and stamping `lastSignedInAt`
+ * here (#652) made every fold a byte change to persist, which a proxy holding
+ * a partition answered with a bus delta and a stamped feed write. #337's "a
+ * genuine sign-in re-activates a device removed elsewhere" still holds; it
+ * lives at the sign-in seam instead (`reactivateThisDevice`, the only one there
+ * is), which is the only place that can tell a user unlocking their account
+ * from a timer firing.
+ * Liveness is not this field's job either — the bus carries it.
+ */
+export declare function mergeDevices(existing: Device[], currentDeviceId: string, deviceName?: string): Device[];
+/**
+ * Detect a human-readable name for the current device and browser.
+ * Returns a string like "Chrome on Linux Desktop" or "Safari on iPhone".
+ */
+export declare function detectDeviceName(): string;
+/**
+ * The device name a STORAGE-PARTITIONED proxy iframe announces itself under.
+ *
+ * A partitioned iframe keeps its own `swarm-id-device-id` in the partition, and
+ * a partition is one (top-level site, iframe origin) pair — so two tabs of one
+ * dApp are one device, while two different dApps on the same browser are two.
+ * `detectDeviceName()` alone therefore hands a Safari user with three connected
+ * dApps three indistinguishable "Safari on Mac" rows (#570). The dApp host is
+ * what tells them apart, and the port comes with it: locally the dApps differ
+ * by port alone.
+ *
+ * Only for the partitioned case. An UNPARTITIONED proxy reads the trusted
+ * domain's first-party store, so it shares `swarm-id-device-id` with the
+ * identity UI — it is the same device, and naming that after whichever dApp
+ * happened to load it would be wrong.
+ *
+ * The host is finer-grained than the partition key, which is schemeful site
+ * (eTLD+1) and may drop the port. Two same-site dApps — `app1.foo.com` and
+ * `app2.foo.com`, or two localhost ports — therefore share ONE partition and
+ * one device row, and each announces that row under its own host, so the
+ * stored name alternates between them on their polls.
+ *
+ * The label is per-origin and the thing it labels is per-site, and both are
+ * right for their own job. The name is per-origin because the origin is what a
+ * user recognises. The row is per-site because it stands for a WRITER, not for
+ * a security boundary: nothing reads the device registry to decide whether a
+ * write is allowed (`knownDeviceIds` only feeds the lease rival set), and two
+ * contexts in one partition cannot write at the same time anyway — they share
+ * `withBatchWriteLock`, a Web Lock scoped to the store they share. Giving them
+ * a row each would spend two of a finite `partitionCount` on writers that are
+ * already serialised. Where per-origin state really is per-origin, the storage
+ * key says so: the stored session (#671), and the stamper's.
+ *
+ * What the alternation costs: nothing on the refresh itself. A partitioned
+ * proxy keeps the merged registry in memory, and the refresh that produces it
+ * is a pre-acquire hook rather than a publish, so a flip writes nothing and
+ * sends nothing. It does not stay in memory, though — the next bus-delta fold
+ * persists it, since `refreshStoredPartitionAccount` serialises the whole
+ * in-memory account, merged devices included, into the session record. And a
+ * flipped row that travels for any other reason (a delta, a feed publish)
+ * carries a newer name clock, so it wins the name wherever it lands rather
+ * than tying and losing: the alternation reaches the account, not just the two
+ * iframes.
+ */
+export declare function partitionDeviceName(appOrigin: string): string;
+/**
+ * Whether a merged device registry is worth persisting over the stored one.
+ *
+ * The old test was "did the list get LONGER", which threw away every merge that
+ * only refreshed a peer's `lastSignedInAt` or set a `removedAt` tombstone — and
+ * those are exactly the fields `activeDeviceIds` prunes the rival set on. A peer
+ * the roster shows as live could therefore age out of the stored copy, drop out
+ * of the rival set, and never get an intent read: the dual-acquire the registry
+ * refresh exists to prevent (#586).
+ *
+ * Every field counts, our own included. `mergeDevices` no longer stamps our
+ * `lastSignedInAt` on a poll (#652), so when it moves it is a genuine sign-in
+ * (a reactivation) and worth a save. Until then this excluded it, because
+ * counting a stamp that moved on every call meant a save and a storage event in
+ * every other tab, every poll round.
+ */
+export declare function deviceRegistryChanged(stored: Device[], merged: Device[], selfDeviceId: string): boolean;

package/dist/utils/hex.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Hex utilities
+ *
+ * Canonical location for hex conversion functions
+ */
+import type { Address } from "../schemas";
+/**
+ * Convert a hex string (optional 0x prefix) to Uint8Array
+ *
+ * @param hexString - Hex string (e.g., "deadbeef" or "0xdeadbeef")
+ * @returns Uint8Array
+ * @throws {Error} If the input has odd length or non-hex characters — a
+ *   malformed value must fail loudly, not silently decode to zero bytes
+ */
+export declare function hexToUint8Array(hexString: string): Uint8Array;
+/**
+ * Convert a Uint8Array to hex string
+ *
+ * @param bytes - Uint8Array to convert
+ * @returns Hex string (e.g., "deadbeef")
+ */
+export declare function uint8ArrayToHex(bytes: Uint8Array): string;
+/**
+ * Create a validated hex address string (40 lowercase hex chars).
+ * Accepts optional 0x prefix and any case.
+ *
+ * @param input - Ethereum address string (with or without 0x prefix)
+ * @returns Normalized 40-character lowercase hex string
+ * @throws {Error} If the input is not a valid 40-char hex address
+ */
+export declare function hexAddress(input: string): Address;

package/dist/utils/json-rpc.d.ts

@@ -0,0 +1,34 @@
+/** A workable deadline for a chain read over a public RPC. */
+export declare const CHAIN_READ_TIMEOUT_MS = 10000;
+export interface JsonRpcOptions {
+    /** Deadline for the whole request, including the response body. */
+    timeoutMs: number;
+    /**
+     * How the endpoint is named in error messages, e.g. "The configured Gnosis
+     * RPC". Defaults to the endpoint's origin.
+     */
+    label?: string;
+}
+/** One call in a batch. Ids are assigned by {@link jsonRpcBatch}. */
+export interface JsonRpcRequest {
+    method: string;
+    params: unknown[];
+}
+/**
+ * One checked JSON-RPC call. `T` is a cast, not a validation — a caller that
+ * reads a field off the result should check that field's type itself.
+ *
+ * @throws if the transport fails, the endpoint answers non-2xx, or the response
+ *   carries an `error` or no usable `result`; a {@link TimeoutError} once the
+ *   deadline passes.
+ */
+export declare function jsonRpcCall<T>(rpcUrl: string, method: string, params: unknown[], options: JsonRpcOptions): Promise<T>;
+/**
+ * A batch of checked calls, returned in the same order as `requests`. Responses
+ * are matched back by id, since JSON-RPC does not promise batch ordering.
+ *
+ * @throws if the transport fails, the batch comes back the wrong shape or with
+ *   ids that do not match the requests, or ANY member fails the contract —
+ *   a partial batch is not an answer.
+ */
+export declare function jsonRpcBatch(rpcUrl: string, requests: JsonRpcRequest[], options: JsonRpcOptions): Promise<unknown[]>;

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

@@ -0,0 +1,124 @@
+import { hexToUint8Array, uint8ArrayToHex } from "./hex";
+/** Master key → the stored derivation key */
+export declare const DERIVATION_KEY_LABEL = "derivation-key";
+/** Derivation key → the Swarm encryption key */
+export declare const SWARM_ENCRYPTION_LABEL = "swarm-encryption";
+/** Derivation key → the postage signer that stamps the account's uploads */
+export declare const POSTAGE_SIGNER_LABEL = "postage-signer";
+/** Swarm encryption key → the backup signer that owns every feed */
+export declare const BACKUP_KEY_LABEL = "backup-key";
+/** Derivation key → the account-wide ACT sharing key (#519) */
+export declare const ACT_SHARING_LABEL = "act-sharing";
+/**
+ * App secret → the site's chat key, the key a site's chat signs with and whose
+ * address the site's chat binding names (docs/Chat-Binding.md).
+ *
+ * The version in the label is how a leaked chat key is replaced: a new label
+ * gives every account a new chat key on every site, the identity UI then signs
+ * a fresh binding at the next connect because the kept one names the old
+ * address, and readers stop accepting the old key because no binding names it.
+ */
+export declare const CHAT_KEY_LABEL = "swarm-id chat key v1";
+/**
+ * Derive a secret from a parent key under a label, with Web Crypto.
+ *
+ * HMAC-SHA256: deterministic, so the same parent key and label always give
+ * the same secret. `deriveSecretSync` is the same function without the
+ * `await`, for a caller that cannot have one; the test pins the two equal.
+ *
+ * @param parentKey - The key to derive from (hex string)
+ * @param label - What the derived key is for: one of the labels above, or the
+ *   app's origin (e.g. "https://swarm-app.local:8080") for a per-app secret
+ * @returns The derived secret as a hex string
+ */
+export declare function deriveSecret(parentKey: string, label: string): Promise<string>;
+/**
+ * `deriveSecret` without the `await`: the same HMAC-SHA256 computed with
+ * `@noble/hashes`, for a caller that cannot await — `buildConnectionInfo` in
+ * the proxy builds ConnectionInfo synchronously (#692). Byte-identical to the
+ * Web Crypto path, which the test pins.
+ */
+export declare function deriveSecretSync(parentKey: string, label: string): string;
+/**
+ * Derive an AES-GCM-256 key from `secretHex` under `label`.
+ *
+ * The three steps — HMAC to a fresh secret, hex to bytes, import as AES-GCM —
+ * are one pipeline. Non-extractable and encrypt/decrypt only, which is the
+ * part worth stating once (#590). The bus envelope (`deriveBusContext`) is the
+ * live caller; the `.swarmid` file key is the identity UI's, derived by HKDF
+ * from the recovery-phrase entropy, and never comes through here.
+ */
+export declare function deriveAesGcmKey(secretHex: string, label: string): Promise<CryptoKey>;
+/**
+ * Derive account derivation key from account master key
+ *
+ * A generic 32-byte root key stored on the account, used for deterministically
+ * deriving further keys (e.g. swarmEncryptionKey) without re-authentication.
+ *
+ * @param accountMasterKey - Account master key (hex string)
+ * @returns 32-byte derivation key (as hex string)
+ */
+export declare function deriveAccountDerivationKey(accountMasterKey: string): Promise<string>;
+/**
+ * Derive Swarm encryption key from account derivation key
+ *
+ * Used for encrypting account snapshot data before upload to Swarm.
+ * Derived from the stored derivationKey rather than the master key directly.
+ *
+ * @param derivationKey - Account derivation key (hex string)
+ * @returns 32-byte encryption key (as hex string)
+ */
+export declare function deriveSwarmEncryptionKey(derivationKey: string): Promise<string>;
+/**
+ * Derive the account-level postage batch signer key from the account derivation
+ * key. Used as the PrivateKey for signing chunks uploaded with a postage batch.
+ *
+ * @param derivationKey - Account derivation key (hex string)
+ * @returns 32-byte signer key (as hex string)
+ */
+export declare function derivePostageSignerKey(derivationKey: string): Promise<string>;
+/**
+ * `derivePostageSignerKey` without the `await`, for the proxy's ConnectionInfo
+ * (#815): the signer's address is what an app buys a batch for.
+ */
+export declare function derivePostageSignerKeySync(derivationKey: string): string;
+/**
+ * The account-wide ACT key (#519): what other people grant access to when they
+ * mean the person rather than one of their apps. Derived from the derivation
+ * key, so every app origin and every device of the account arrives at the same
+ * key — and the master key still never leaves the identity UI. Its public half
+ * is `identity.sharingPublicKey`. Synchronous because ConnectionInfo is built
+ * without awaiting.
+ */
+export declare function deriveSharingKey(derivationKey: string): {
+    secret: Uint8Array;
+    publicKey: string;
+};
+/**
+ * The first output of `derive` that is a valid secp256k1 private key, a
+ * number from 1 to n - 1 where n is the curve order. It asks under `label`
+ * first, then under `label/1`, `label/2` and so on. An HMAC-SHA256 output
+ * misses that range with a chance of about 2^-128, so in practice the first
+ * answer is the key, but the rule is fixed so every device agrees even then.
+ *
+ * @throws if no candidate within the attempt bound is a key, which only a
+ *   broken `derive` can cause
+ */
+export declare function firstValidPrivateKey(derive: (label: string) => Uint8Array, label: string): Uint8Array;
+/**
+ * The site's chat key, from the site's app secret
+ * (`deriveSecret(masterKey, origin)`): `HMAC(appSecret, CHAT_KEY_LABEL)`, the
+ * same derivation `deriveAppSecret` runs for an app's own label, held to a
+ * valid secp256k1 key by `firstValidPrivateKey`. It depends on the account and
+ * the site alone, so every device of the account derives the same key.
+ * Synchronous because ConnectionInfo and the binding are built without
+ * awaiting.
+ *
+ * @param appSecret - the site's app secret (bare hex)
+ * @returns the 32-byte chat private key
+ */
+export declare function deriveChatKey(appSecret: string): Uint8Array;
+export declare const utils: {
+    hexToUint8Array: typeof hexToUint8Array;
+    uint8ArrayToHex: typeof uint8ArrayToHex;
+};

package/dist/utils/lock-soc.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Address derivation for the per-partition lock SOC. Lives in `utils/` (not
+ * `sync/`) so it can be imported by both `sync/partition-lock.ts` (the lock
+ * SOC reader/writer) and `utils/batch-utilization.ts` (the stamper that
+ * routes lock-SOC overstamps to the reserved slot) without a circular
+ * dependency through `toBucket`.
+ */
+import { Identifier, type BatchId, type EthAddress } from "@ethersphere/bee-js";
+/**
+ * Build the lock-SOC identifier for one partition of one batch. Universal
+ * across accounts — the per-account `owner` carries that separation — so the
+ * identifier encodes what remains: which batch, and which of its lanes.
+ *
+ * The batch is in here because it is in everything the lock protects. A lane's
+ * slot space is computed WITHIN a batch (`dataSlot`), and the state riding it
+ * is published under `makePartitionStateTopic(batchId, partition)`. Keying the
+ * lock on the partition alone made lane p of batch X and lane p of batch Y one
+ * chunk address, so two coordinators that share no slot took turns anyway —
+ * and per-app stamp overrides put two live coordinators on two batches without
+ * any multi-batch feature (#589).
+ */
+export declare function makePartitionLockIdentifier(batchId: BatchId, partition: number): Identifier;
+/**
+ * 32-byte SOC chunk address for the (batch, partition, owner) lock SOC. Used
+ * by the stamper to detect "this stamp is the lock SOC's overstamp" and route
+ * it to the reserved slot.
+ */
+export declare function lockSocAddress(batchId: BatchId, partition: number, owner: EthAddress): Uint8Array;
+/**
+ * Bucket index that the partition-lock SOC for (batch, partition, owner) lands
+ * in. Lock-SOC writes overstamp this single fixed bucket; the partition stamper
+ * reserves the bucket from data uploads so the tight heartbeat cadence
+ * doesn't exhaust the bucket's slot budget.
+ */
+export declare function lockSocBucket(batchId: BatchId, partition: number, owner: EthAddress): number;