@solarpunkltd/swarm-id 0.0.0-stage → 0.8.0

package/dist/swarm-id-proxy.d.ts

@@ -0,0 +1,1031 @@
+import type { SiteAllowList } from "./utils/site-allow-list";
+/**
+ * Debounce window for proxy-side account-state publishing. Coalesces a burst of
+ * triggers (lease acquisition + storage changes) into a single feed write.
+ */
+export declare const PUBLISH_DEBOUNCE_MS = 1500;
+/**
+ * Swarm ID Proxy - Runs inside the iframe
+ *
+ * Responsibilities:
+ * - Receive app-specific secrets from auth popup
+ * - Keep a partitioned session in this partition's own localStorage (#635)
+ * - Proxy Bee API calls from parent dApp
+ * - Augment requests with authentication
+ * - Return responses to parent dApp
+ */
+export declare class SwarmIdProxy {
+    private parentOrigin;
+    private parentIdentified;
+    /**
+     * Set by the first `parentIdentify`, before its allow-list check awaits, so a
+     * second one cannot start a check of its own. A refused parent leaves it set:
+     * the frame answers nothing more until the page loads it again.
+     */
+    private parentIdentifyReceived;
+    private siteAllowList;
+    private authenticated;
+    private authLoading;
+    private appSecret;
+    /**
+     * The chat binding the popup handed over with this session, already checked
+     * against it (`acceptHandedOverChatBinding`). Only a handover sets it: an
+     * unpartitioned session reads its connection out of shared storage and
+     * reports none.
+     */
+    private chatBinding;
+    private postageBatchId;
+    private signerKey;
+    private stamper;
+    /**
+     * Hash of `<owner>-<encryptionKey>` that the current `stamper` was built
+     * with. Account-level inputs are baked into `UtilizationAwareStamper` at
+     * construction, so when the underlying account changes (e.g. a local
+     * account migrates to a synced one) we need to detect that even if the
+     * postage stamp's batch/signer didn't change, and rebuild the stamper.
+     */
+    private stamperAccountFingerprint;
+    private stampWorkerPool;
+    private storagePartitioned;
+    private pendingChallenge;
+    /**
+     * Hydrated account view for the storage-partitioning fallback: the synced
+     * projection handed over by the connect popup (`AuthData.account`), held in
+     * memory only — the stored-account schema requires a vault. What survives a
+     * reload is the handover itself, under its own key (#635), which this view
+     * is then rebuilt from. When set, the proxy is a
+     * first-class writer despite the partition (docs/Account-Bus.md, phase 3).
+     */
+    private partitionAccount;
+    /** Account-derived topic the attached bus transports share; undefined when
+     *  none are attached. */
+    private busTopic;
+    private removeBusLocal;
+    private removeBusSignaling;
+    /** Derivation key of a join that attached everything it wanted. Lets the
+     *  synchronous `joinAccountBus` return without re-deriving, and — because it
+     *  stays unset when a transport failed to attach — makes the next join a
+     *  RETRY rather than a dedup'd no-op. */
+    private busJoinedKey;
+    /** Bumped by every bus join and by `clearAuthData`, so a join whose key
+     *  derivation is still in flight can tell it has been superseded. */
+    private busJoinGeneration;
+    /** Account whose room the attached transports currently speak into. A
+     *  transport encrypts with its construction-time key, so this — not whichever
+     *  connection resolves now — is who a publish actually reaches. */
+    private busBoundAccountId;
+    /** Scheduled answers to peers' `lease-request`s, by request id, so a peer
+     *  earlier in the rank order can call ours off (`yieldRankDelayMs`). */
+    private pendingYields;
+    /** Request ids somebody has claimed (us or a peer). Insertion-ordered and
+     *  capped at `ANSWERED_REQUEST_MEMORY`. Separate from `pendingYields`
+     *  because the cancel window has to outlive the rank timer: the timer only
+     *  starts the yield, whose first Swarm write is still ahead of it. */
+    private answeredRequests;
+    /**
+     * Utilization deltas that arrived while the stamper had no lane, held until
+     * a bind names one (`applyPendingLaneUpdate`). Keyed by lane so a delta for
+     * a lane we do not end up binding cannot displace the one we do — the point
+     * of buffering is that nothing is silently lost. Buckets merge per index
+     * with `max`, matching `applyUtilizationUpdate`'s own monotonic rule.
+     * Bounded by the account's partition count.
+     */
+    private pendingLaneUpdates;
+    /**
+     * The newest timestamp this frame gave a stamp again of a single-owner
+     * chunk, in milliseconds, by site, stamp and chunk address. Set under the
+     * write lock when the stamp is made, while the stored slot record is
+     * written only after the lock, so a second stamp of that address inside
+     * the lock still gets a newer timestamp than the first.
+     */
+    private lastRestampMs;
+    private utilizationStore;
+    private beeApiUrl;
+    private gnosisRpcUrl;
+    private postageStampContractAddress;
+    private signalingUrl;
+    private authButtonContainer;
+    private buttonConfig;
+    private popupMode;
+    private appMetadata;
+    /**
+     * The last Bee client built, with the URL it was asked for. Keyed on that
+     * input URL, not on the client's own `url`, which bee-js keeps without the
+     * trailing slash.
+     */
+    private beeClient;
+    private unsubscribeStorageListeners;
+    private storageWorkQueue;
+    private lastConnectionInfo;
+    private isConnecting;
+    private parentWindow;
+    private bus;
+    /** Who else is live in the account's room, from their `presence` beats. */
+    private presence;
+    private presenceTimer;
+    private subsidisedGatewayUrl;
+    /**
+     * The resolved stamp's stored lifetime fields (#745), set wherever the
+     * stamp is. Expiry is derived from them on every read, so a tab left open
+     * past the drive's lifetime refuses its own writes rather than letting Bee
+     * refuse the lease claim.
+     */
+    private stampLifetime;
+    /** Bumped by every `initializeStamper`; an older init sees it move and stops */
+    private stamperInitGeneration;
+    /** Why the session refuses to stamp with the resolved drive, if it does. */
+    private get stampRefusal();
+    /**
+     * The client for the node the current mode writes to: the dApp's gateway
+     * while the session is subsidised, the configured node otherwise. Reads have
+     * to come from where the uploads go, or a dApp reads back a 404 for the
+     * chunk it just wrote.
+     *
+     * Derived on every read rather than assigned, because a mode change is not
+     * always an event — a drive's expiry is read off the clock — and a client
+     * picked once keeps pointing wherever the session started: at the gateway
+     * for a session that connected after the page loaded, or at the node for
+     * one whose drive has since run out or been removed.
+     */
+    private get bee();
+    /**
+     * The client for the configured node, whatever the mode. The coordinator
+     * writes there, and only there: it runs in user-stamp mode alone, and a
+     * refused drive (expired, unusable) keeps one while `bee` points at the
+     * gateway. What it writes — the roster, this device's state — is read back
+     * through this client too.
+     */
+    private get nodeBee();
+    /** A client for `url`, rebuilt only when the URL differs from the last. */
+    private beeClientFor;
+    /**
+     * The write path (lock + partition lease + stamp flush) for the current
+     * account+batch. Assigned in `initializeStamper` together with the stamper it
+     * writes through, and dropped with it whenever the resolved stamp changes
+     * (`setResolvedStamp`); undefined before auth / after disconnect. The proxy
+     * delegates all writes to it via `withModeAwareWriteLock`.
+     */
+    private coordinator;
+    /**
+     * Debounce timer + in-flight guard for proxy-side account-state publishing.
+     * The proxy publishes the account snapshot to the shared sync feed when it
+     * first acquires a partition (so the device announces itself — see #336
+     * motivation #4) and when account state changes while a lease is held.
+     */
+    private publishTimer;
+    private publishInFlight;
+    /**
+     * Why the next debounced publish was scheduled. `"acquired"` (announce on
+     * lease acquisition) is gated on this device not yet being in the feed, so a
+     * plain reload doesn't republish. `"change"` (account-state delta) always
+     * publishes. `"change"` dominates a coalesced burst — a real delta must never
+     * be skipped just because an acquisition was also pending.
+     */
+    private publishReason;
+    /**
+     * This device's identity, captured ONCE at authentication and reused for
+     * every lease operation. Never re-read from `getOrCreateDeviceId()` mid-
+     * session, so acquire / refresh / validate always agree on one identity.
+     */
+    private deviceId;
+    /**
+     * A session this load restored from storage, rather than one the person
+     * connected in it, waits on this before its first write, so a session ended
+     * while no page of the site was open cannot write.
+     * Unset for a fresh connection. Kept through `clearAuthData`, so a write
+     * that was waiting when the check ended the session is told why.
+     */
+    private restoredSessionCheck;
+    constructor(config: ProxyConfig);
+    /**
+     * Subscribe to shared localStorage changes that can affect the dApp-visible
+     * ConnectionInfo (auth state, identity, postage stamps, account type).
+     *
+     * - `connectedApps` drives auth transitions (new connection / identity switch /
+     *   disconnect) and triggers `authSuccess` / `disconnectResponse` to the parent.
+     * - `identities`, `accounts`, `postageStamps` may change the derived
+     *   ConnectionInfo without flipping auth state (e.g. rename, default-stamp
+     *   change, local→synced migration). On change we re-derive ConnectionInfo
+     *   and emit `connectionInfoChanged` if it actually differs.
+     *
+     * Note: We always set up these listeners, even when storage might be partitioned.
+     * In some browsers/configurations (like localhost development), storage events
+     * work between same-origin windows even in iframes. If storage IS partitioned,
+     * the listeners simply won't fire, and we fall back to postMessage from the popup.
+     */
+    private setupStorageListeners;
+    /**
+     * Queue a reconcile behind whatever reconcile is already running.
+     *
+     * `refreshStampFromStorage` / `initializeStamper` mutate shared
+     * `stamper` / `postageBatchId` state across awaits, so two of them in flight
+     * at once emit inconsistent ConnectionInfo. ONE queue for every source: a
+     * storage event and an `account-delta` fold are the same work arriving two
+     * ways, and a queue each would serialize neither against the other.
+     *
+     * Rejections are caught and logged here — the chain must survive one failure,
+     * and nothing else catches them (the bus dispatch's try/catch only covers a
+     * synchronous throw).
+     */
+    private enqueueReconcile;
+    /**
+     * Re-read network settings. `beeApiUrl` / `gnosisRpcUrl` are read fresh per
+     * call — by the TTL/contract helpers, and by `bee`, which builds the client
+     * for a changed URL on its next read — so updating them is all it takes.
+     */
+    private applyNetworkSettings;
+    /**
+     * The body of `applyNetworkSettings`, taking the settings as a value: a
+     * partitioned session cannot read them from storage and is handed them by
+     * the connect popup instead (`hydratePartitionAccount`). One implementation,
+     * or the two paths drift — an RPC-only change is invisible to a `beeNodeUrl`
+     * guard, and the subsidised-gateway rules below are easy to forget.
+     */
+    private applyNetworkSettingsValues;
+    /**
+     * Handle changes to the nested account document. Covers auth transitions
+     * (connect / secret change / disconnect) AND derived-ConnectionInfo changes
+     * (default-stamp change, new stamp purchased, account rename) — all of which
+     * now live in one document.
+     *
+     * `"storage"`: a `storage` event from another window, or a same-window write
+     * the shell made on its own — this device's change, so it publishes.
+     * `"bus"`: a same-window write the shell marked `noRepublish` — a peer's
+     * delta it folded, a volatile field, a device-local sign-out. The shell
+     * sharing this window (the identity UI runs inside the proxy iframe too)
+     * makes those beside the proxy, and they reconcile the way a bus delta does,
+     * without a publish: republishing a fold stamped a fresh clock on every hop
+     * and kept two devices publishing at each other every few seconds (#707).
+     */
+    private handleAccountStorageChange;
+    /**
+     * Re-resolve this origin's connection and reconcile the session with it.
+     *
+     * `source` is where the news came from, and only the disconnect branch cares.
+     * A partitioned iframe cannot see connected apps in storage, so a storage
+     * event saying "no valid connection" means nothing there — but an
+     * `account-delta` from a peer is authoritative, and acting on it is the whole
+     * point of that message (docs/Account-Bus.md).
+     */
+    private reevaluateConnection;
+    /**
+     * Re-resolve postage stamp and account inputs for the current connection
+     * from shared storage. Reinitializes the stamper if the batch, signer
+     * key, or account-level inputs (owner / encryption key) changed — the
+     * last case handles e.g. local→synced account migration where the
+     * postage stamp is unchanged but the underlying account isn't.
+     */
+    private refreshStampFromStorage;
+    /**
+     * The only way the resolved stamp changes. The write path — the stamper and
+     * the coordinator that writes through it — belongs to the stamp it was built
+     * for, so it goes whenever the fields naming that stamp do, before anything
+     * is built for the next one. Otherwise the previous coordinator outlives its
+     * stamp: after the drive is removed, or the connection moves to another
+     * account, an upload still takes that coordinator's lease and spends the old
+     * batch while the dApp is told there is no stamp at all.
+     */
+    private setResolvedStamp;
+    /**
+     * Authenticate using data from connected apps storage
+     */
+    private authenticateFromStorage;
+    /**
+     * Handle messages from the auth popup (same-origin postMessage).
+     * Used as storage partitioning fallback when storage events don't fire due to partitioning.
+     */
+    private handlePopupMessage;
+    /**
+     * End the connect attempt a refused handover belonged to.
+     *
+     * The popup cannot be told it was refused — there is no channel back — so it
+     * shows "Connected!" while the button here spins on, and the only other
+     * thing that ever cleared the flag was the user closing that popup
+     * (`checkPopupClosed`), which nothing gave them a reason to do.
+     *
+     * `isConnecting` first: `showAuthButton` early-returns while it is set, so
+     * clearing the flag is what lets the button come back. `authLoading` is
+     * already false on every path that reaches here — belt-and-braces, not a
+     * second fix.
+     *
+     * The challenge is deliberately kept. The popup is still open and may yet
+     * send a payload this bundle can read; refusing one message ends the
+     * attempt's spinner, not the ceremony behind it.
+     */
+    private endRefusedConnect;
+    /**
+     * The handed-over chat binding, if it names exactly this parent origin, the
+     * address of the chat key of the secret it came with and the account it came
+     * with, so the dApp is never shown a statement about another site, key or
+     * account. A restored session runs through here again, so a stored binding
+     * naming any other address is dropped on reload as well.
+     *
+     * Local http is allowed in the parse because the comparison with
+     * `parentOrigin`, which the browser reported, is the check here. Which sites
+     * a binding may name at all is the popup's to decide, and a production popup
+     * refuses local http.
+     */
+    private acceptHandedOverChatBinding;
+    /**
+     * Write the handed-over session to this partition's own store, sealed so
+     * none of it is plain text on disk: it holds the app secret, the derivation
+     * key and the stamp's signer key.
+     *
+     * The wire form, not the parsed one: `AuthDataSchema` revives `BatchId` and
+     * `PrivateKey` instances, which do not survive `JSON.stringify`, so what goes
+     * in is what the popup sent and what comes back out is parsed the same way it
+     * was on arrival.
+     *
+     * The deadline is the one `hydratePartitionAccount` just computed, read back
+     * off the connection rather than recomputed, so the session at rest and the
+     * session in memory cannot disagree about when it ends.
+     */
+    private savePartitionSession;
+    /**
+     * Re-persist the stored session's account view after a live fold moved it.
+     *
+     * Without this the record is frozen at the handover: a rotated signer key or
+     * a moved default stamp arrives over the bus, updates `partitionAccount`, and
+     * then a reload resurrects the pre-fold copy and uploads with it until the
+     * next live overlap.
+     *
+     * Only the account. The deadline stays the one the handover recorded, because
+     * `hydratePartitionAccount` recomputes `connectedUntil` on every call — write
+     * the in-memory one back and a session extends itself for as long as deltas
+     * keep arriving. And the record is edited in the shape it was WRITTEN in
+     * (raw JSON), not the parsed one: `AuthDataSchema` revives byte classes that
+     * do not survive a second `JSON.stringify`.
+     *
+     * Never creates a record — a session that failed to persist stays unpersisted.
+     */
+    private refreshStoredPartitionAccount;
+    /** Forget the stored session. Every path that ends one calls this. */
+    private clearPartitionSession;
+    /**
+     * Writes to the stored session wait for sealing, so they run one after
+     * another in call order. Otherwise a save that started before a clear could
+     * land after it and bring an ended session back. `build` answers the record
+     * to write, `null` to remove it, or `undefined` to leave it as it is.
+     */
+    private writePartitionSession;
+    /**
+     * The stored record for this parent and its opened wire payload, or
+     * `"unavailable"` when this page could not read the wrapping key, so the
+     * record may still open on a later load.
+     */
+    private openStoredPartitionSession;
+    /**
+     * The stored session for THIS parent, if it is still within its deadline.
+     *
+     * The key is per dApp origin, because the partition is not: it is scoped to
+     * the top-level SITE, so same-site dApps share this store (#671). The
+     * `parentOrigin` check below is now the belt to that pair of braces rather
+     * than the only thing keeping two dApps apart. An expired, malformed or
+     * unopenable record is removed on the way past: it will never become valid
+     * again, and a record whose seal does not open is no session. So is a record
+     * carrying a chat binding that fails `acceptHandedOverChatBinding`, such as
+     * one naming the app secret's address from before sites had a chat key:
+     * restored without it, the session would hand out a chat key no binding
+     * names, so the person unlocks once and the window signs a fresh one. A record whose
+     * wrapping key this page could not read is no session for this page only,
+     * and stays stored for a later load to open.
+     */
+    private readPartitionSession;
+    /**
+     * Build the in-memory account view for a partitioned session and initialize
+     * the write path from it. The vault fields are inert placeholders — the
+     * record never touches storage and the seed never leaves first-party
+     * context; `SignedInAccount` merely requires their presence.
+     */
+    private hydratePartitionAccount;
+    /**
+     * Join the account bus for whatever connection is resolvable right now
+     * (idempotent per account). Called from every path that establishes or
+     * re-resolves a connection — the unpartitioned ones included, or the bus
+     * would never reach past this origin+partition outside Safari.
+     */
+    private joinAccountBus;
+    /**
+     * Attach the account's bus transports (docs/Account-Bus.md). Idempotent per
+     * account; same code path on every browser — Safari is not special.
+     *
+     * BOTH transports hang off the account-derived topic, so a context only ever
+     * shares a channel with other contexts of the same account. The local one is
+     * attached whether or not a signaling URL is configured: without it there is
+     * still same-device tab↔tab traffic to carry, and a build with no signaling
+     * URL must not lose cross-tab utilization.
+     *
+     * Because the topic is derived, both transports now attach a few ticks after
+     * an auth event rather than at construction, so a peer publishing inside
+     * that window loses that one message. Bounded by a single HMAC derivation,
+     * and no worse than a tab that has not finished loading — which has no
+     * listener either; durable counters reconcile on the next read. `busTopic`
+     * is set exactly when the local transport goes live, so it is the signal to
+     * wait on.
+     *
+     * The two attaches are INDEPENDENT. `SignalingTransport` connects in its
+     * constructor, where `new URL` / `new WebSocket` throw synchronously on a
+     * url that is set but unusable (`ws://` from an https page, a CSP that omits
+     * the bus host, a typo) — and that must cost the signaling transport only.
+     * Letting it take the local one down produces "no bus at all, for the whole
+     * session", silently and indistinguishably from a healthy build with no
+     * signaling url at all.
+     */
+    private ensureAccountBusTransports;
+    /**
+     * "This device is live", to the account's room. Reads the room and the
+     * device id at fire time — the same guard `publishAccountDelta` carries —
+     * so a beat scheduled for one account can never name it into another's
+     * room during a switch, and one that fires before auth finished says nothing.
+     */
+    private publishPresence;
+    /** Stop beating and forget who was live: the next room starts from nothing. */
+    private stopPresence;
+    /** Leave the account's bus room: both transports detached and closed, and
+     *  every latch cleared so the next join is a fresh one. */
+    private detachBusTransports;
+    /**
+     * Clean up resources when the proxy is destroyed.
+     * Call this method when the proxy iframe is being unloaded.
+     */
+    destroy(): void;
+    /**
+     * Tear the write coordinator down, announcing the partition it held so
+     * waiting peers wake now instead of sleeping out their poll interval
+     * (docs/Account-Bus.md, bus-accelerated leases). The announcement races the
+     * Swarm release it describes, which is harmless: the lock SOCs stay the
+     * authority, so a peer woken too early just spends one extra read round.
+     */
+    private teardownCoordinator;
+    private terminateStampWorkerPool;
+    private static laneKey;
+    /**
+     * Hold a lane-scoped delta that arrived with no lane bound to compare it
+     * against, merged into whatever that lane already has.
+     */
+    private bufferLaneUpdate;
+    /**
+     * Fold the buffered delta for the lane we just bound in, then drop every
+     * buffered lane — the ones we did not bind are another device's business.
+     * Called on every lease acquire: on the cold path the counters are already
+     * seeded from the durable partition-state feed, so this is a harmless
+     * monotonic no-op; on the adopt fast path they are not, and this is the
+     * whole point.
+     */
+    private applyPendingLaneUpdate;
+    /**
+     * Run this holder's answer to a peer's `lease-request`, announcing the
+     * partition it gave up so the waiter (and holders further down the rank
+     * order) hear about it.
+     *
+     * The `lease-claim` goes out FIRST. Releasing is two stamped Swarm writes
+     * (`yieldIdleLease` → `lease.release()`), which is orders of magnitude
+     * longer than a rank step, so announcing only on completion would reach the
+     * other holders long after every one of them had begun releasing too — #576
+     * with extra steps. A claim is cheap to send and is what the rank step
+     * actually budgets for.
+     */
+    private answerLeaseRequest;
+    /**
+     * How long this holder waits before answering `requestId`.
+     *
+     * A waiter needs exactly ONE slot, but the request names no partition, so
+     * every idle holder used to release at once: with `partitionCount = 4` all
+     * four dropped their lease, each then paid a cold acquire on its next
+     * upload, and whoever lost the re-race got "Uploads are unavailable". The
+     * waiter re-broadcasts every round, so it repeated.
+     *
+     * The request id gives every holder the same permutation of the partitions,
+     * and each waits its own rank in it. Exactly one draws rank 0 and answers
+     * immediately — so the ordinary one-holder handover is not slowed at all —
+     * while the rest stand down as soon as they see its `lease-claim`. Only
+     * holders that would presently yield take a rank at all (`canYieldForPeer`),
+     * so a holder mid-burst does not sit at the front of the order and decline
+     * in silence; the next eligible rank answers a step later, which still beats
+     * waiting out a poll interval.
+     *
+     * `scripts/bus-handover-latency.ts` reimplements this election (these
+     * handlers are private) to measure the handover against a real cluster.
+     * Change the formula here and change it there, or the script starts
+     * measuring a race the product does not have.
+     */
+    private yieldRankDelayMs;
+    /** Stop answering `requestId` — somebody else claimed it (or we just did).
+     *  Remembered as well as cancelled, because the rank timer may already have
+     *  fired: it hands off to `answerLeaseRequest`, which re-checks this. */
+    private standDownFromRequest;
+    private markRequestAnswered;
+    /** Drop every scheduled answer — nothing they would release is ours now. */
+    private cancelPendingYields;
+    /**
+     * Account-bus subscription: utilization deltas from other contexts, and the
+     * lease fast path (docs/Account-Bus.md, bus-accelerated leases). The Swarm
+     * lock-SOC protocol stays authoritative — these messages only shortcut its
+     * timers.
+     */
+    private setupBusListeners;
+    /**
+     * Fold a peer's account snapshot into this session's view and reconcile.
+     *
+     * This is the only push channel a partitioned iframe has: it cannot see
+     * shared storage, so without this a revoke reaches it only when the page
+     * closes — and since #547 that session is a full writer holding every stamp's
+     * signer key (docs/Account-Bus.md, `account-delta`).
+     *
+     * Durable truth is unchanged. An unpartitioned session still owns its state
+     * through storage; the delta only drives the reconcile, and `clearAuthData`
+     * invalidates the stored entry if the outcome is a disconnect.
+     */
+    private applyAccountDelta;
+    /**
+     * Create an onProgress callback for upload operations.
+     * Returns undefined if progress reporting is disabled.
+     */
+    private createProgressCallback;
+    /**
+     * Announce that proxy is ready to receive messages
+     * Broadcasts to parent with wildcard origin since we don't know parent origin yet
+     */
+    private announceReady;
+    /**
+     * Get the stored postage batch ID
+     */
+    getPostageBatchId(): string | undefined;
+    /**
+     * Get the stored signer key
+     */
+    getSignerKey(): string | undefined;
+    /**
+     * Initialize the Stamper for client-side signing
+     * Uses UtilizationAwareStamper to track bucket usage
+     */
+    private initializeStamper;
+    /**
+     * The eager lease claim is a write of its own, so a restored session makes
+     * it only once its check allows writes. A session whose check could not
+     * complete claims lazily instead, on the first write a later check allows.
+     */
+    private startLeaseOnceAllowed;
+    /**
+     * This device's identity, captured once. Lazily initialised here as a
+     * fallback; the auth entry points set it eagerly. Reused for every lease
+     * operation so acquire / refresh / validate never disagree about who we
+     * are (which previously caused false "reclaimed by another device").
+     */
+    private requireDeviceId;
+    private readLeaseCache;
+    private writeLeaseCache;
+    /**
+     * Get or create a StampWorkerPool for parallel signing.
+     * Lazy-initialized on first use and reused across uploads, for as long as
+     * it signs for the current stamper and has the requested size.
+     */
+    private getOrCreateWorkerPool;
+    /**
+     * Save stamper bucket state to IndexedDB, logging a failure rather than
+     * throwing. The upload path relies on this: the coordinator flushes in a
+     * `finally`, after the upload has already gone out.
+     */
+    private saveStamperState;
+    /**
+     * Save stamper bucket state to IndexedDB and tell local peers, throwing when
+     * the save fails.
+     */
+    private persistStamperState;
+    /**
+     * Execute an upload operation against the right target for the current mode.
+     * In subsidised mode (no usable user stamp) the gateway handles stamping, so
+     * there is no local stamp state to protect and we run unlocked. In user-stamp
+     * mode the write goes through the {@link BatchWriteCoordinator}, which takes
+     * the cross-tab write lock, ensures a held partition, and flushes stamper
+     * state — the proxy no longer owns any of that.
+     */
+    private withModeAwareWriteLock;
+    /**
+     * Save stamper state only in stamper mode.
+     * In subsidised mode, there's no local stamp state to persist.
+     */
+    private saveStamperStateIfNeeded;
+    /**
+     * Setup message listener for parent and popup messages
+     */
+    private setupMessageListener;
+    /**
+     * Handle parent identification
+     */
+    private handleParentIdentify;
+    /**
+     * Handle messages from parent window
+     */
+    private handleParentMessage;
+    /**
+     * Load authentication data from shared storage (ConnectedApp records).
+     */
+    private loadAuthData;
+    /**
+     * Bring a stored session back up, exactly as the popup handover does.
+     *
+     * Through the same `hydratePartitionAccount`, so there is one function that
+     * builds a partitioned session rather than two that drift.
+     *
+     * The deadline cannot see a revoke made while the tab was closed, so the
+     * session comes up for reads at once and checks the account's published
+     * state before its first write (`startRestoredSessionCheck`), as a session
+     * restored from shared storage does.
+     */
+    private restorePartitionSession;
+    /**
+     * Ask the account's published state whether this restored session was ended
+     * while no page of the site was open. Ended means what it means
+     * everywhere else: the entry is gone, `revokedAt` (Remove), or a
+     * `disconnectedAt` newer than the connection this session came from
+     * (Disconnect, #667), with the rules in `sync/session-check.ts`.
+     *
+     * Reads start at once. Writes wait on the answer (`ensureCanWrite`), and an
+     * answer that could not be read keeps them refused: an unreachable Swarm
+     * says nothing about a revoke, so it neither ends the session nor lets it
+     * write. The next write asks again.
+     */
+    private startRestoredSessionCheck;
+    /** Waits for the restored session's check, and refuses unless it allowed. */
+    private awaitRestoredSessionAllowed;
+    /**
+     * The gate every write handler passes. The session check comes first, and
+     * the refusal checks run after it because the session can change while it
+     * waits.
+     */
+    private ensureCanWrite;
+    /**
+     * Look up the postage stamp for the currently connected app's identity
+     * by reading from shared localStorage stores.
+     */
+    private lookupPostageStampForApp;
+    /**
+     * Look up the account for the currently connected app's identity
+     * by reading from shared localStorage stores.
+     *
+     * @returns Account info with owner address and encryption key, or undefined if not found
+     */
+    private lookupAccountForApp;
+    /**
+     * The partition rival set for `accountId`: every device heard live on the
+     * account bus, plus the recently signed-in devices of the stored registry
+     * (read fresh, so the intent round reflects a device that announced after
+     * the coordinator was built).
+     *
+     * The bus half is the liveness signal — a peer beating in the room is alive
+     * by construction, whether or not its roster append ever landed. The
+     * registry half is the bootstrap for contexts with no bus (no signaling
+     * server configured) and for a device that just signed in and has not
+     * beaten yet; it is bounded to `KNOWN_DEVICE_MAX_AGE_MS` because removed
+     * (tombstoned) devices won't write, and long-dead ghosts (the device list is
+     * append-only) would each add an absent intent read to every acquire — on a
+     * flaky gateway that can push a single acquire past its timeout, so a live
+     * device can't claim even a FREE partition. A genuinely-live holder this
+     * prune drops is still caught by the deviceId-independent occupancy beacon.
+     *
+     * On any storage error the bus half alone is returned — the lease then falls
+     * back to the guard+TTL acquire path against whoever is live.
+     */
+    private knownDeviceIdsForAccount;
+    private lastDeviceRegistryRefreshAt;
+    /**
+     * Pull the latest account snapshot from the shared feed and union its
+     * `metadata.devices` into the locally-stored account, so `knownDeviceIds`
+     * reflects a peer that signed in AFTER this device created the account (else
+     * the claimer never reads the peer's beacon and they dual-acquire). Throttled
+     * (the slot-wait loop re-acquires) and best-effort — on any failure the
+     * current registry is used as-is.
+     */
+    private refreshDeviceRegistryFromSwarm;
+    /**
+     * Assemble the current account-state snapshot for the connected app's
+     * account. Needs no feed signing key, so it stays separate from
+     * `buildAccountStateSnapshotForPublish` below — reusing that one would cost
+     * two key derivations to send a bus message.
+     *
+     * `requireDefaultStamp` is the FEED path's precondition, not the snapshot's:
+     * that write is paid for by the default stamp, while a bus message costs
+     * nothing to send and `metadata.defaultPostageStampBatchID` is optional on
+     * the wire. An account with no drives is a supported connected state, and
+     * gating the delta on a stamp is how such an account's revokes never reach
+     * its partitioned sessions at all.
+     */
+    private buildAccountStateSnapshot;
+    /**
+     * Announce this session's account state to the account's other live contexts
+     * (docs/Account-Bus.md, `account-delta`). Unlike the feed write below it
+     * needs no partition and no lock — it is a message, not a write — so a
+     * read-only session still relays what it can see to peers that cannot.
+     *
+     * `ofEndedConnection` reports a session that has just ENDED (the revoke a
+     * storage event revealed), where the entry the snapshot is resolved from is
+     * by definition no longer a valid connection.
+     */
+    private publishAccountDelta;
+    /**
+     * Assemble the current account-state snapshot for the connected app's account
+     * from shared localStorage (the same shape `sync-account` builds from its DI
+     * stores). Returns the snapshot plus the feed signing key + owner. Undefined
+     * when storage is partitioned or the account/stamp can't be resolved.
+     */
+    private buildAccountStateSnapshotForPublish;
+    /**
+     * Schedule a debounced account-state publish. Safe to call from inside the
+     * coordinator's lease callbacks: it only arms a timer, so the actual publish
+     * runs later, outside any held write lock.
+     *
+     * A coordinator is NOT a precondition — only the feed half of the publish
+     * needs one, and `runAccountStatePublish` checks for it there, after the bus
+     * delta has gone out.
+     */
+    private schedulePublish;
+    /**
+     * Publish the account snapshot: to the account's live peers over the bus,
+     * and to the shared feed via the coordinator (same write lock + held
+     * partition). The feed write needs a partition; the bus message does not, so
+     * it goes out first and a read-only session still relays to peers that
+     * cannot see storage at all. Single-device accounts' feeds are published by
+     * the SwarmID UI. Re-arms if a publish is already in flight so the latest
+     * state still lands.
+     */
+    private runAccountStatePublish;
+    /**
+     * Lift this device's own `removedAt` on a genuine sign-in — #337's rule, at
+     * the one seam that can tell a user unlocking their account from a timer.
+     *
+     * `mergeDevices` used to do this on every refresh, which meant no removal and
+     * no expiry ever stuck (#611). Here it happens once, on a fresh `setSecret`
+     * handover, and the next publish re-announces us with the tombstone gone —
+     * `ensureInRoster` appends when the removed-state differs, so the roster
+     * carries the reactivation to peers without any extra write of our own.
+     *
+     * Clearing `removedAt` is only half of it: `mergeDevicesList` ranks devices
+     * on `max(removedAt, lastSignedInAt)`, so a lift that left the old sign-in
+     * stamp in place would lose to the very tombstone it is undoing and the next
+     * fold would put it straight back. A handover IS a sign-in — the user
+     * clicked connect and unlocked in the popup — so it stamps one.
+     *
+     * Partitioned only: an unpartitioned proxy has no business editing the
+     * shared account document behind the identity UI's back. The identity UI has
+     * no reactivation seam of its own, and needs none — nothing writes a device
+     * tombstone today, and a device that stops beating on the bus is ignored at
+     * read rather than tombstoned (#655). If manual removal is ever built, its
+     * seam has to do what this one does, both halves included.
+     */
+    private reactivateThisDevice;
+    /**
+     * The name this context announces itself under in the device registry.
+     *
+     * A PARTITIONED proxy keeps its own `swarm-id-device-id` in the partition, so
+     * it is a per-dApp device and says which dApp (#570). An UNPARTITIONED one
+     * reads the trusted domain's first-party store and therefore shares the
+     * device id with the identity UI — it is the same device, and naming it after
+     * whichever dApp happened to embed it would be wrong.
+     */
+    private announcedDeviceName;
+    /**
+     * Check if a connection is still valid based on connectedUntil timestamp
+     */
+    private isConnectionValid;
+    /**
+     * Find the account + connected-app pair for the current parent origin, reading
+     * the nested account documents. Resolves ambiguity (the same app connected
+     * under multiple accounts) by sorting valid entries by `lastConnectedAt`
+     * descending and returning the most recent.
+     */
+    private findConnectionForParent;
+    /**
+     * Look up the app secret from shared storage for the current parent origin.
+     * Returns the secret if a valid connection is found.
+     */
+    private lookupAppSecretFromSharedStorage;
+    /**
+     * Clear authentication data
+     */
+    private clearAuthData;
+    /**
+     * Send error message to parent
+     */
+    /**
+     * Answer a request with what went wrong, as a dApp can branch on it (#761):
+     * the caught value is classified by `toWireError`; `fallback` is the
+     * message for a throw that was not an `Error`.
+     */
+    private sendErrorToParent;
+    private ensureCanUpload;
+    /**
+     * Whether uploads can be stamped with the account's own postage batch. Both
+     * what the dApp is told (`buildConnectionInfo`'s `uploadMode`) and where the
+     * bytes go (`isSubsidisedModeActive`) are decided by this one rule.
+     */
+    private hasUsableUserStamp;
+    /**
+     * Whether uploads go to the subsidised gateway: one is configured, and there
+     * is no usable user stamp to write with instead.
+     */
+    private isSubsidisedModeActive;
+    /**
+     * Send message to parent
+     */
+    private sendToParent;
+    /**
+     * Send message to the event source (parent window that sent the request)
+     */
+    private postMessage;
+    private handleCheckAuth;
+    /**
+     * The two public keys the identity carries, memoised on the derivation key
+     * they come from: `buildConnectionInfo` runs from eight sites, and the key
+     * changes only when the account does. Public halves only, never a secret.
+     */
+    private identityKeys?;
+    private identityKeysFor;
+    /**
+     * Build the current ConnectionInfo snapshot from in-memory auth state and
+     * shared localStorage. Pure — does not send anything.
+     */
+    private buildConnectionInfo;
+    /**
+     * Which of the two ways to be upload-less this session hit. Ordered by how
+     * early the path gives up, so the answer names the first thing that stopped
+     * it rather than the last symptom.
+     *
+     * Only meaningful once authenticated — an unconnected session has no reason
+     * to report beyond not being connected.
+     */
+    private uploadUnavailableReason;
+    /**
+     * Recompute ConnectionInfo and send `connectionInfoChanged` to the parent
+     * if it actually differs from the last value we sent. Used both on auth
+     * transitions and on storage events that affect derived fields.
+     */
+    private emitConnectionInfoIfChanged;
+    private handleIsConnected;
+    private handleGetNodeInfo;
+    private handleDisconnect;
+    /**
+     * Show authentication button in the UI
+     */
+    private showAuthButton;
+    private handleConnect;
+    /**
+     * Open the authentication popup window.
+     * Returns true if popup was opened, false if parent origin is not set.
+     */
+    private openAuthPopup;
+    /**
+     * Handle login button click
+     */
+    private handleLoginClick;
+    /**
+     * Handle disconnect button click
+     */
+    private handleDisconnectClick;
+    /**
+     * Set container element for auth button
+     */
+    setAuthButtonContainer(container: HTMLElement): void;
+    private handleUploadData;
+    private handleDownloadData;
+    private handleUploadFile;
+    private handleDownloadFile;
+    /** A folder as one manifest (#750); the Swarm-specific part is `uploadCollection`. */
+    private handleUploadFiles;
+    private handleListFiles;
+    private handleUploadChunk;
+    private handleDownloadChunk;
+    private handleGsocMine;
+    private handleGsocSend;
+    private handleSocUpload;
+    private handleSocRawUpload;
+    private handleSocDownload;
+    private handleSocRawDownload;
+    private handleSocGetOwner;
+    /**
+     * Derive a stable, app-scoped secret HMAC(appSecret, label) for the connected
+     * app. `appSecret` is genuinely secret (unlike the recoverable appKey public
+     * key) and never leaves the iframe — only the derived bytes are returned, so
+     * the app can seed an unguessable feed topic without exposing metadata (#520).
+     */
+    private handleDeriveAppSecret;
+    /**
+     * Hand the authenticated page its site's chat key, the key whose address the
+     * site's chat binding names (docs/Chat-Binding.md), so the site's chat can
+     * sign with it. Same authentication rule as `handleDeriveAppSecret`, and like
+     * it the app secret itself never leaves the frame.
+     */
+    private handleGetChatKey;
+    /**
+     * Stamp a chunk with the account's own stamp and hand the stamp back, for
+     * the app to send through its own Swarm access. The stamp takes the same
+     * write path as an upload, so it is returned only after the coordinator has
+     * published the partition counter, the guarantee an upload's ack carries.
+     * It also needs the stamper state saved, and refuses when that save fails.
+     * A restored session stamps only once its session check allows writes, as
+     * every write does (`ensureCanWrite`).
+     * The account's own lock and counter chunks never
+     * come through here, they stay inside the frame and go through its node.
+     */
+    private handleStampChunk;
+    /**
+     * Save the counter a stamp spent before the stamp is returned. The write
+     * path's own flush only logs a failure, which an upload can afford and a
+     * stamp cannot: an account on one device keeps its counter nowhere else, so
+     * after a reload the slot would be handed out a second time.
+     */
+    private persistStamperStateForStamp;
+    /**
+     * Stamp for this app if its limits allow, and count the stamp. Synchronous
+     * from the read of the usage to its write, so two requests can never both
+     * take the last stamp an app is allowed. The usage is written before the
+     * stamp is returned, so a stamp that could not be counted is never handed
+     * out.
+     *
+     * A single-owner chunk this app had stamped before in this device's lane is
+     * stamped again at the same slot with a newer timestamp, which a mutable
+     * batch takes as a replacement. That spends no slot, so only the count and
+     * the rate apply. A content chunk always takes a new slot.
+     *
+     * The slot a single-owner chunk went to is not written here. The caller
+     * runs `recordSlot` only once the counter that spent it is saved and
+     * published: a record left by a stamp that failed to commit would outlive
+     * the counter, the slot would go to another chunk after a reload, and the
+     * next stamp of this address would replace that chunk on Bee.
+     */
+    private stampWithinAppLimits;
+    /** Stamp at a new slot within the app's limits, and the usage that counts it */
+    private stampNewSlot;
+    /**
+     * The owner addresses of the account's own chunks and keys, for refusing a
+     * single-owner chunk an app asks to have signed as one of them.
+     */
+    private accountInternalOwners;
+    private parseFeedTimestamp;
+    private parseFeedIndex;
+    private makeSequentialFeedIdentifier;
+    private findLatestSequentialIndex;
+    private sequentialNextIndex;
+    private handleFeedGetOwner;
+    private handleEpochFeedDownloadReference;
+    private handleEpochFeedUploadReference;
+    private handleSequentialFeedGetOwner;
+    private resolveSequentialOwner;
+    private parseSequentialPayload;
+    private resolveSequentialIndex;
+    private handleSequentialFeedDownloadPayload;
+    private handleSequentialFeedDownloadRawPayload;
+    private handleSequentialFeedDownloadReference;
+    private buildSequentialPayload;
+    private handleSequentialFeedUploadPayload;
+    private handleSequentialFeedUploadRawPayload;
+    private handleSequentialFeedUploadReference;
+    /**
+     * The account-wide ACT key (#519), or undefined when the session carries no
+     * account to derive it from.
+     */
+    private sharingSecret;
+    /**
+     * The keys this session may read or manage ACT data with: the origin-bound
+     * app key, then the account-wide sharing key. The ACT module picks the one
+     * a share names.
+     */
+    private actKeys;
+    private handleActUploadData;
+    private handleActDownloadData;
+    private handleActAddGrantees;
+    private handleActRevokeGrantees;
+    private handleActGetGrantees;
+    private handleGetPostageBatch;
+    /**
+     * Handle createFeedManifest request
+     * Creates a feed manifest for accessing feed content via URL
+     */
+    private handleCreateFeedManifest;
+}
+/**
+ * Optional configuration for the proxy, supplied by the host trusted-domain app.
+ */
+export interface ProxyConfig {
+    /**
+     * The sites this frame serves (docs/Site-Allow-List.md). A parent whose
+     * origin it refuses gets an `initError` and nothing else.
+     */
+    siteAllowList: SiteAllowList;
+    /**
+     * PostageStamp contract address for on-chain stamp-TTL reads. Defaults to the
+     * Gnosis mainnet deployment; set this (from a build-time env) to the local
+     * bee-compose anvil address when developing against a local chain.
+     */
+    postageStampContractAddress?: string;
+    /**
+     * Account-bus signaling server URL (e.g. `wss://bus.example.com/bus`,
+     * `ws://localhost:5520` in dev). Unset disables the cross-partition/
+     * cross-device bus transport (docs/Account-Bus.md).
+     */
+    signalingUrl?: string;
+}
+/**
+ * Initialize the proxy (called from HTML page)
+ */
+export declare function initProxy(config: ProxyConfig): SwarmIdProxy;