@arkade-os/sdk 0.4.19 → 0.4.20

package/dist/esm/worker/messageBus.js

@@ -2,15 +2,22 @@
 import { getActiveServiceWorker, setupServiceWorkerOnce, } from './browser/service-worker-manager.js';
 import { RestArkProvider } from '../providers/ark.js';
 import { RestDelegatorProvider } from '../providers/delegator.js';
-import { ReadonlySingleKey, SingleKey } from '../identity/index.js';
+import { hydrateIdentity, isSigningSerialized, normalizeSerializedIdentity, } from '../identity/index.js';
 import { ReadonlyWallet, Wallet } from '../wallet/wallet.js';
-import { hex } from "@scure/base";
 import { MessageBusNotInitializedError, ServiceWorkerTimeoutError, } from './errors.js';
+/**
+ * Grace period after a handler times out during which late handler
+ * completion is still delivered to the client. Once this expires,
+ * the bus sends an "Operation abandoned" error so the message id
+ * never goes silent indefinitely.
+ */
+const LATE_DELIVERY_GRACE_MS = 5 * 60000;
 export class MessageBus {
     /** Create the service-worker message bus with repositories and handler configuration. */
-    constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, debug = false, buildServices, }) {
+    constructor(walletRepository, contractRepository, { messageHandlers, tickIntervalMs = 10000, messageTimeoutMs = 30000, messageTimeoutOverrides = {}, debug = false, buildServices, }) {
         this.walletRepository = walletRepository;
         this.contractRepository = contractRepository;
+        this.lateDeliveries = new Set();
         this.running = false;
         this.tickTimeout = null;
         this.tickInProgress = false;
@@ -20,6 +27,8 @@ export class MessageBus {
         this.handlers = new Map(messageHandlers.map((u) => [u.messageTag, u]));
         this.tickIntervalMs = tickIntervalMs;
         this.messageTimeoutMs = messageTimeoutMs;
+        this.constructorTimeoutOverrides = { ...messageTimeoutOverrides };
+        this.messageTimeoutOverrides = { ...this.constructorTimeoutOverrides };
         this.debug = debug;
         this.buildServicesFn = buildServices ?? this.buildServices.bind(this);
     }
@@ -55,6 +64,11 @@ export class MessageBus {
             self.clearTimeout(this.tickTimeout);
             this.tickTimeout = null;
         }
+        for (const record of this.lateDeliveries) {
+            record.settled = true;
+            self.clearTimeout(record.deadline);
+        }
+        this.lateDeliveries.clear();
         self.removeEventListener("message", this.boundOnMessage);
         await Promise.all(Array.from(this.handlers.values()).map((updater) => updater.stop()));
     }
@@ -81,7 +95,8 @@ export class MessageBus {
             const now = Date.now();
             for (const updater of this.handlers.values()) {
                 try {
-                    const response = await this.withTimeout(updater.tick(now), `${updater.messageTag}:tick`);
+                    const tickLabel = `${updater.messageTag}:tick`;
+                    const response = await this.withTimeout(updater.tick(now), this.resolveTimeoutMs(tickLabel, updater.messageTag), tickLabel);
                     if (this.debug)
                         console.log(`[${updater.messageTag}] outgoing tick response:`, response);
                     if (response && response.length > 0) {
@@ -124,6 +139,12 @@ export class MessageBus {
             this.initialized = false;
             await Promise.all(Array.from(this.handlers.values()).map((h) => h.stop().catch(() => { })));
         }
+        // Recompute the active timeout map from scratch so a prior init's
+        // keys cannot linger after re-init with a smaller map.
+        this.messageTimeoutOverrides = {
+            ...this.constructorTimeoutOverrides,
+            ...(config.messageTimeouts ?? {}),
+        };
         const services = await this.buildServicesFn(config);
         // Start all handlers
         for (const updater of this.handlers.values()) {
@@ -146,8 +167,9 @@ export class MessageBus {
         const delegatorProvider = config.delegatorUrl
             ? new RestDelegatorProvider(config.delegatorUrl)
             : undefined;
-        if ("privateKey" in config.wallet) {
-            const identity = SingleKey.fromHex(config.wallet.privateKey);
+        const serialized = normalizeSerializedIdentity(config.wallet);
+        if (isSigningSerialized(serialized)) {
+            const identity = hydrateIdentity(serialized);
             const wallet = await Wallet.create({
                 identity,
                 arkServerUrl: config.arkServer.url,
@@ -161,23 +183,18 @@ export class MessageBus {
             });
             return { wallet, arkProvider, readonlyWallet: wallet };
         }
-        else if ("publicKey" in config.wallet) {
-            const identity = ReadonlySingleKey.fromPublicKey(hex.decode(config.wallet.publicKey));
-            const readonlyWallet = await ReadonlyWallet.create({
-                identity,
-                arkServerUrl: config.arkServer.url,
-                arkServerPublicKey: config.arkServer.publicKey,
-                indexerUrl: config.indexerUrl,
-                esploraUrl: config.esploraUrl,
-                storage,
-                delegatorProvider,
-                watcherConfig: config.watcherConfig,
-            });
-            return { readonlyWallet, arkProvider };
-        }
-        else {
-            throw new Error("Missing privateKey or publicKey in configuration object");
-        }
+        const identity = hydrateIdentity(serialized);
+        const readonlyWallet = await ReadonlyWallet.create({
+            identity,
+            arkServerUrl: config.arkServer.url,
+            arkServerPublicKey: config.arkServer.publicKey,
+            indexerUrl: config.indexerUrl,
+            esploraUrl: config.esploraUrl,
+            storage,
+            delegatorProvider,
+            watcherConfig: config.watcherConfig,
+        });
+        return { readonlyWallet, arkProvider };
     }
     onMessage(event) {
         // Keep the service worker alive while async work is pending.
@@ -192,7 +209,7 @@ export class MessageBus {
     async processMessage(event) {
         const { id, tag, broadcast } = event.data;
         if (tag === "PING") {
-            event.source?.postMessage({ id, tag: "PONG" });
+            this.deliverResponse(event.source, { id, tag: "PONG" }, { id, tag: "PONG" });
             return;
         }
         if (tag === "INITIALIZE_MESSAGE_BUS") {
@@ -203,7 +220,7 @@ export class MessageBus {
             // performs network calls (buildServices) and handler startup
             // that may legitimately exceed the message timeout.
             await this.waitForInit(event.data.config);
-            event.source?.postMessage({ id, tag });
+            this.deliverResponse(event.source, { id, tag }, { id, tag });
             if (this.debug) {
                 console.log("MessageBus initialized");
             }
@@ -216,45 +233,60 @@ export class MessageBus {
             // hanging forever. This happens when the browser kills and restarts
             // the service worker — the new instance has initialized=false and
             // messages arrive before INITIALIZE_MESSAGE_BUS is re-sent.
-            event.source?.postMessage({
+            const fallbackTag = tag ?? "unknown";
+            this.deliverResponse(event.source, {
                 id,
-                tag: tag ?? "unknown",
+                tag: fallbackTag,
                 error: new MessageBusNotInitializedError(),
-            });
+            }, { id, tag: fallbackTag });
             return;
         }
         if (!id || !tag) {
             if (this.debug)
                 console.error("Invalid message received, missing required fields:", event.data);
-            event.source?.postMessage({
+            const fallbackTag = tag ?? "unknown";
+            this.deliverResponse(event.source, {
                 id,
-                tag: tag ?? "unknown",
+                tag: fallbackTag,
                 error: new TypeError("Invalid message received, missing required fields"),
-            });
+            }, { id, tag: fallbackTag });
             return;
         }
+        const messageType = this.extractMessageType(event.data);
         if (broadcast) {
             const updaters = Array.from(this.handlers.values());
-            const results = await Promise.allSettled(updaters.map((updater) => this.withTimeout(updater.handleMessage(event.data), updater.messageTag)));
+            const entries = updaters.map((updater) => {
+                const label = this.labelFor(messageType, updater.messageTag);
+                const timeoutMs = this.resolveTimeoutMs(messageType, updater.messageTag);
+                const handlerPromise = updater.handleMessage(event.data);
+                const raced = updater.isLongRunning?.(event.data)
+                    ? handlerPromise
+                    : this.withTimeout(handlerPromise, timeoutMs, label);
+                return { updater, handlerPromise, raced };
+            });
+            const results = await Promise.allSettled(entries.map((e) => e.raced));
             results.forEach((result, index) => {
-                const updater = updaters[index];
+                const { updater, handlerPromise } = entries[index];
+                const handlerTag = updater.messageTag;
+                const context = { id, tag: handlerTag, messageType };
                 if (result.status === "fulfilled") {
                     const response = result.value;
-                    if (response) {
-                        event.source?.postMessage(response);
-                    }
+                    // Always deliver a response so the caller's message id
+                    // never goes silent. Handlers returning null/undefined
+                    // get an explicit ack envelope.
+                    this.deliverResponse(event.source, response ?? { id, tag: handlerTag }, context);
                 }
                 else {
                     if (this.debug)
-                        console.error(`[${updater.messageTag}] handleMessage failed`, result.reason);
-                    const error = result.reason instanceof Error
-                        ? result.reason
-                        : new Error(String(result.reason));
-                    event.source?.postMessage({
-                        id,
-                        tag: updater.messageTag,
-                        error,
-                    });
+                        console.error(`[${handlerTag}] handleMessage failed`, result.reason);
+                    const error = toError(result.reason);
+                    this.deliverResponse(event.source, { id, tag: handlerTag, error }, context);
+                    // If the error was a timeout, keep watching the
+                    // underlying handler and surface its eventual result
+                    // under the same id.
+                    if (result.reason instanceof ServiceWorkerTimeoutError) {
+                        this.attachLateDelivery(handlerPromise, event.source, id, handlerTag, messageType);
+                    }
                 }
             });
             return;
@@ -263,35 +295,53 @@ export class MessageBus {
         if (!updater) {
             if (this.debug)
                 console.warn(`[${tag}] unknown message tag, ignoring message`);
+            this.deliverResponse(event.source, {
+                id,
+                tag,
+                error: new Error(`Unknown handler tag: ${tag}`),
+            }, { id, tag, messageType });
             return;
         }
+        const label = this.labelFor(messageType, tag);
+        const timeoutMs = this.resolveTimeoutMs(messageType, tag);
+        const handlerPromise = updater.handleMessage(event.data);
+        const context = { id, tag, messageType };
         try {
-            const response = await this.withTimeout(updater.handleMessage(event.data), tag);
+            const response = updater.isLongRunning?.(event.data)
+                ? await handlerPromise
+                : await this.withTimeout(handlerPromise, timeoutMs, label);
             if (this.debug)
                 console.log(`[${tag}] outgoing response:`, response);
-            if (response) {
-                event.source?.postMessage(response);
-            }
+            // Always deliver a response so the caller's message id never
+            // goes silent. A handler returning null/undefined yields an
+            // explicit ack envelope.
+            this.deliverResponse(event.source, response ?? { id, tag }, context);
         }
         catch (err) {
             if (this.debug)
                 console.error(`[${tag}] handleMessage failed`, err);
-            const error = err instanceof Error ? err : new Error(String(err));
-            event.source?.postMessage({ id, tag, error });
+            const error = toError(err);
+            this.deliverResponse(event.source, { id, tag, error }, context);
+            // When we abandoned the handler via timeout, keep watching it
+            // so the client's message id eventually gets a final response.
+            if (err instanceof ServiceWorkerTimeoutError) {
+                this.attachLateDelivery(handlerPromise, event.source, id, tag, messageType);
+            }
         }
     }
     /**
      * Race `promise` against a timeout. Note: this does NOT cancel the
-     * underlying work — the original promise keeps running. This is safe
-     * here because only the caller (not the handler) posts the response.
+     * underlying work — the original promise keeps running. Call
+     * `attachLateDelivery` after catching the timeout to surface the
+     * eventual result so the message id does not go silent.
      */
-    withTimeout(promise, label) {
-        if (this.messageTimeoutMs <= 0)
+    withTimeout(promise, timeoutMs, label) {
+        if (timeoutMs <= 0)
             return promise;
         return new Promise((resolve, reject) => {
             const timer = self.setTimeout(() => {
-                reject(new ServiceWorkerTimeoutError(`Message handler timed out after ${this.messageTimeoutMs}ms (${label})`));
-            }, this.messageTimeoutMs);
+                reject(new ServiceWorkerTimeoutError(`Message handler timed out after ${timeoutMs}ms (${label})`));
+            }, timeoutMs);
             promise.then((val) => {
                 self.clearTimeout(timer);
                 resolve(val);
@@ -301,6 +351,97 @@ export class MessageBus {
             });
         });
     }
+    /**
+     * Extract the declared `type` from a request envelope (e.g. "SETTLE").
+     * Not every envelope carries a type (PING/INIT are special cased
+     * earlier), so this returns undefined for envelopes that lack one.
+     */
+    extractMessageType(data) {
+        const maybeType = data.type;
+        return typeof maybeType === "string" ? maybeType : undefined;
+    }
+    /**
+     * Resolve the timeout for an operation. Message-type overrides take
+     * precedence over handler-tag overrides, with the bus-wide default
+     * (`messageTimeoutMs`) as the final fallback.
+     */
+    resolveTimeoutMs(messageType, handlerTag) {
+        if (messageType &&
+            Object.prototype.hasOwnProperty.call(this.messageTimeoutOverrides, messageType)) {
+            return this.messageTimeoutOverrides[messageType];
+        }
+        if (Object.prototype.hasOwnProperty.call(this.messageTimeoutOverrides, handlerTag)) {
+            return this.messageTimeoutOverrides[handlerTag];
+        }
+        return this.messageTimeoutMs;
+    }
+    /**
+     * Build a human-readable label for timeout errors. Format:
+     * `"<MESSAGE_TYPE> via <HANDLER_TAG>"` when both are known, else the
+     * handler tag alone. Used so timeout errors name the operation the
+     * client actually triggered (e.g. SETTLE) rather than just the
+     * handler that received it (e.g. WALLET_UPDATER).
+     */
+    labelFor(messageType, handlerTag) {
+        return messageType ? `${messageType} via ${handlerTag}` : handlerTag;
+    }
+    /**
+     * Post a response to the originating client. When `source` is null
+     * (client tab closed, detached frame, etc.) the response cannot be
+     * delivered; we log the drop in debug mode so it is not invisible.
+     */
+    deliverResponse(source, response, context) {
+        if (!source) {
+            if (this.debug)
+                console.warn(`[${context.tag}] cannot deliver response: event.source is null`, {
+                    id: context.id,
+                    messageType: context.messageType,
+                });
+            return;
+        }
+        source.postMessage(response);
+    }
+    /**
+     * After a handler times out the client has already received a timeout
+     * error, but the handler keeps running. Attach a follow-up so the
+     * handler's eventual result (or error) is delivered under the same
+     * message id, or — if the handler never completes within
+     * {@link LATE_DELIVERY_GRACE_MS} — an "Operation abandoned" error is
+     * sent so the client's listener (if still attached) does not hang.
+     */
+    attachLateDelivery(handlerPromise, source, id, tag, messageType) {
+        const context = { id, tag, messageType };
+        const record = {
+            settled: false,
+            deadline: self.setTimeout(() => {
+                if (record.settled)
+                    return;
+                record.settled = true;
+                this.lateDeliveries.delete(record);
+                this.deliverResponse(source, {
+                    id,
+                    tag,
+                    error: new Error(`Operation abandoned: handler did not complete within ${LATE_DELIVERY_GRACE_MS}ms after timeout (${this.labelFor(messageType, tag)})`),
+                }, context);
+            }, LATE_DELIVERY_GRACE_MS),
+        };
+        this.lateDeliveries.add(record);
+        handlerPromise.then((response) => {
+            if (record.settled)
+                return;
+            record.settled = true;
+            self.clearTimeout(record.deadline);
+            this.lateDeliveries.delete(record);
+            this.deliverResponse(source, response ?? { id, tag }, context);
+        }, (err) => {
+            if (record.settled)
+                return;
+            record.settled = true;
+            self.clearTimeout(record.deadline);
+            this.lateDeliveries.delete(record);
+            this.deliverResponse(source, { id, tag, error: toError(err) }, context);
+        });
+    }
     /**
      * Returns the registered SW for the path.
      * It uses the functions in `service-worker-manager.ts` module.
@@ -323,3 +464,6 @@ export class MessageBus {
         return getActiveServiceWorker(path);
     }
 }
+function toError(value) {
+    return value instanceof Error ? value : new Error(String(value));
+}

package/dist/types/contracts/handlers/default.d.ts

@@ -10,7 +10,7 @@ export interface DefaultContractParams {
     csvTimelock: RelativeTimelock;
 }
 /**
- * Handler for default wallet virtual outputs.
+ * Handler for default wallet VTXOs.
  *
  * Default contracts use the standard forfeit + exit tapscript:
  * - forfeit: (Alice + Server) multisig for collaborative spending

package/dist/types/contracts/handlers/helpers.d.ts

@@ -9,7 +9,7 @@ export declare function timelockToSequence(timelock: RelativeTimelock): number;
  */
 export declare function sequenceToTimelock(sequence: number): RelativeTimelock;
 /**
- * Resolve wallet's role from explicit role or by matching pubkey.
+ * Resolve wallet's role from explicit role or by matching descriptor/pubkey.
  */
 export declare function resolveRole(contract: Contract, context: PathContext): "sender" | "receiver" | undefined;
 /**

package/dist/types/contracts/types.d.ts

@@ -96,13 +96,21 @@ export interface PathContext {
     /** Current block height, when known. */
     blockHeight?: number;
     /**
-     * Wallet public key encoded as 32-byte x-only hex.
-     * Used by handlers to determine the wallet's role in multi-party contracts.
+     * Wallet's descriptor for signing.
+     * Format: tr(pubkey) for static keys, tr([fingerprint/path']xpub/0/{index}) for HD.
+     * Used by handlers to determine wallet's role in multi-party contracts.
+     */
+    walletDescriptor?: string;
+    /**
+     * Wallet's public key (x-only, 32 bytes hex).
+     * @deprecated Use walletDescriptor instead.
      */
     walletPubKey?: string;
     /**
      * Explicit role override for multi-party contracts such as VHTLC.
-     * If not provided, the handler may derive the role from `walletPubKey`.
+     * If not provided, the handler may derive the role by matching
+     * {@link walletDescriptor} (preferred) — or {@link walletPubKey} as a
+     * fallback — against the contract's sender/receiver params.
      */
     role?: string;
     /** The specific virtual output being evaluated. */

package/dist/types/identity/descriptor.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Check if a string is a descriptor of the shape `tr(...)`.
+ *
+ * This is a shape check only — it does not validate the inner key material.
+ * Use {@link expand} (via {@link extractPubKey} / {@link parseHDDescriptor})
+ * for full parsing. The guard rejects empty bodies and missing/trailing
+ * parentheses so callers can safely branch on descriptor vs. raw pubkey.
+ */
+export declare function isDescriptor(value: string): boolean;
+/**
+ * Normalize a value to descriptor format.
+ * If already a descriptor, return as-is. If hex pubkey, wrap as tr(pubkey).
+ * Throws when the value is empty or not a string so we never produce
+ * malformed descriptors like `tr()` that downstream parsers would reject.
+ */
+export declare function normalizeToDescriptor(value: string): string;
+/**
+ * Extract the public key from a simple descriptor.
+ * For simple descriptors (tr(pubkey)), extracts the pubkey using the library.
+ * For HD descriptors, throws — use DescriptorProvider to derive the key.
+ */
+export declare function extractPubKey(descriptor: string): string;
+/** Parsed HD descriptor components. */
+export interface ParsedHDDescriptor {
+    fingerprint: string;
+    basePath: string;
+    xpub: string;
+    derivationPath: string;
+}
+/**
+ * Parse an HD descriptor into its components.
+ * HD descriptors have the format: tr([fingerprint/path']xpub/derivation)
+ * Returns null if the descriptor is not in HD format.
+ */
+export declare function parseHDDescriptor(descriptor: string): ParsedHDDescriptor | null;

package/dist/types/identity/descriptorProvider.d.ts

@@ -0,0 +1,28 @@
+import { Transaction } from "../utils/transaction";
+/** A signing request that pairs a descriptor with a transaction. */
+export interface DescriptorSigningRequest {
+    /** Descriptor identifying which key to sign with */
+    descriptor: string;
+    /** Transaction to sign */
+    tx: Transaction;
+    /** Specific input indexes to sign (signs all if omitted) */
+    inputIndexes?: number[];
+}
+/**
+ * Provider interface for descriptor-based signing.
+ *
+ * Implementations include:
+ * - {@link StaticDescriptorProvider}: wraps a legacy {@link Identity} with a single key.
+ * - HD-wallet provider: signs with keys derived from an xpub-based descriptor
+ *   (planned — tracked separately from this interface).
+ */
+export interface DescriptorProvider {
+    /** Returns the current signing descriptor. */
+    getSigningDescriptor(): string;
+    /** Checks if a descriptor belongs to this provider. */
+    isOurs(descriptor: string): boolean;
+    /** Signs transactions, each with its own descriptor-derived key. */
+    signWithDescriptor(requests: DescriptorSigningRequest[]): Promise<Transaction[]>;
+    /** Signs a message using the key derived from the descriptor. */
+    signMessageWithDescriptor(descriptor: string, message: Uint8Array, type?: "schnorr" | "ecdsa"): Promise<Uint8Array>;
+}

package/dist/types/identity/index.d.ts

@@ -46,4 +46,10 @@ export interface BatchSignableIdentity extends Identity {
 /** Type guard for identities that support batch signing. */
 export declare function isBatchSignable(identity: Identity): identity is BatchSignableIdentity;
 export * from "./singleKey";
-export * from "./seedIdentity";
+export type { NetworkOptions, DescriptorOptions, SeedIdentityOptions, MnemonicOptions, } from "./seedIdentity";
+export { SeedIdentity, MnemonicIdentity, ReadonlyDescriptorIdentity, } from "./seedIdentity";
+export * from "./serialize";
+export { isDescriptor, normalizeToDescriptor, extractPubKey, parseHDDescriptor, } from "./descriptor";
+export type { ParsedHDDescriptor } from "./descriptor";
+export type { DescriptorProvider, DescriptorSigningRequest, } from "./descriptorProvider";
+export { StaticDescriptorProvider } from "./staticDescriptorProvider";

package/dist/types/identity/seedIdentity.d.ts

@@ -1,6 +1,7 @@
 import { Identity, ReadonlyIdentity } from ".";
 import { Transaction } from "../utils/transaction";
 import { SignerSession } from "../tree/signingSession";
+import type { SerializedSigningIdentity, SerializedReadonlyIdentity } from "./serialize";
 /** Used for default BIP86 derivation with network selection. */
 export interface NetworkOptions {
     /**
@@ -27,14 +28,14 @@ export type MnemonicOptions = SeedIdentityOptions & {
  *
  * This is the recommended identity type for most applications. It uses
  * standard BIP86 (Taproot) derivation by default and stores an output
- * descriptor for interoperability with other wallets. The descriptor
- * format is HD-ready, allowing future support for multiple addresses
- * and change derivation.
+ * descriptor for interoperability with other wallets.
  *
  * Prefer this (or @see MnemonicIdentity) over `SingleKey` for new
  * integrations — `SingleKey` exists for backward compatibility with
  * raw nsec-style keys.
  *
+ * For descriptor-based signing, wrap with {@link StaticDescriptorProvider}.
+ *
  * @example
  * ```typescript
  * const seed = mnemonicToSeedSync(mnemonic);
@@ -50,7 +51,6 @@ export type MnemonicOptions = SeedIdentityOptions & {
  * ```
  */
 export declare class SeedIdentity implements Identity {
-    protected readonly seed: Uint8Array;
     private readonly derivedKey;
     readonly descriptor: string;
     constructor(seed: Uint8Array, descriptor: string);
@@ -131,3 +131,40 @@ export declare class ReadonlyDescriptorIdentity implements ReadonlyIdentity {
     xOnlyPublicKey(): Promise<Uint8Array>;
     compressedPublicKey(): Promise<Uint8Array>;
 }
+/**
+ * Serialize a seed-backed signing identity into a
+ * {@link SerializedSigningIdentity} envelope without exposing the
+ * underlying secret material on the public instance surface.
+ *
+ * Called by {@link serializeSigningIdentity}; application code should
+ * prefer that public dispatcher instead of calling this directly. This
+ * helper is deliberately kept out of the `src/identity` barrel so it is
+ * not part of the package's public export surface.
+ *
+ * Secret-surface trade-off: the resulting envelope carries master-seed
+ * material — the BIP39 mnemonic (+ optional passphrase) for
+ * `MnemonicIdentity` or the raw 64-byte seed for `SeedIdentity`. A party
+ * that reads this envelope can derive any key under the HD tree, not
+ * just the key currently in use. The pre-change `SingleKey` flow only
+ * shipped one derived private key and therefore had a smaller blast
+ * radius. This is an intentional design trade to preserve class and
+ * descriptor identity across the page / service-worker boundary; the
+ * page already holds the same material so that it can re-initialize a
+ * killed worker. Transport is same-origin `postMessage` only. See the
+ * threat-model note in `src/worker/browser/README.md`.
+ *
+ * @internal
+ */
+export declare function serializeSeedOwnedSigningIdentity(identity: SeedIdentity): SerializedSigningIdentity;
+/**
+ * Downgrade a seed-backed or descriptor-backed identity into a readonly
+ * descriptor envelope. Always produces a descriptor-only shape — secret
+ * material never crosses this path, even if the input is a signing
+ * identity.
+ *
+ * Deliberately kept out of the `src/identity` barrel; consumers should go
+ * through {@link serializeReadonlyIdentity}.
+ *
+ * @internal
+ */
+export declare function serializeSeedOwnedReadonlyIdentity(identity: SeedIdentity | ReadonlyDescriptorIdentity): SerializedReadonlyIdentity;

package/dist/types/identity/serialize.d.ts

@@ -0,0 +1,84 @@
+import type { Identity, ReadonlyIdentity } from ".";
+/**
+ * Tagged envelope for a signing identity transported across the
+ * service-worker boundary. All variants are structured-clone safe
+ * (plain strings only — no functions or prototypes).
+ *
+ * Adding a new variant is a source change in every worker build; keep
+ * old variants around until all deployed workers handle them.
+ */
+export type SerializedSigningIdentity = {
+    type: "single-key";
+    privateKey: string;
+} | {
+    type: "seed";
+    seed: string;
+    descriptor: string;
+} | {
+    type: "mnemonic";
+    mnemonic: string;
+    descriptor: string;
+    passphrase?: string;
+};
+/**
+ * Tagged envelope for a readonly identity transported across the
+ * service-worker boundary. All variants are structured-clone safe.
+ */
+export type SerializedReadonlyIdentity = {
+    type: "readonly-single-key";
+    publicKey: string;
+} | {
+    type: "readonly-descriptor";
+    descriptor: string;
+};
+export type SerializedIdentity = SerializedSigningIdentity | SerializedReadonlyIdentity;
+/** Type guard — true for signing envelopes, false for readonly envelopes. */
+export declare function isSigningSerialized(s: SerializedIdentity): s is SerializedSigningIdentity;
+/**
+ * Serialize a signing identity into a structured-clone safe envelope for
+ * transport across the service-worker boundary.
+ *
+ * Supports SDK-owned signing identities directly. For custom identities, a
+ * duck-typed `toHex()` fallback preserves compatibility with existing
+ * `SingleKey`-like implementations.
+ */
+export declare function serializeSigningIdentity(identity: Identity): SerializedSigningIdentity;
+/**
+ * Serialize a readonly identity into a structured-clone safe envelope.
+ *
+ * Works for any `ReadonlyIdentity` via `compressedPublicKey()`. When called
+ * with a signing identity, produces a readonly envelope (never ships signing
+ * material) — callers that need to preserve signing capability across the
+ * boundary must use {@link serializeSigningIdentity}.
+ */
+export declare function serializeReadonlyIdentity(identity: ReadonlyIdentity): Promise<SerializedReadonlyIdentity>;
+/**
+ * Rehydrate a serialized identity envelope back into an identity instance.
+ * The return type is the union of signing and readonly; use
+ * {@link isSigningSerialized} on the envelope before hydration if the caller
+ * needs to know which side it ends up on.
+ */
+export declare function hydrateIdentity(s: SerializedIdentity): Identity | ReadonlyIdentity;
+/**
+ * Legacy untagged shape emitted by page builds prior to the tagged
+ * SerializedIdentity envelope. Retained so newer workers can still accept
+ * older pages during a rolling upgrade. Slated for removal in the next major.
+ *
+ * @deprecated Use {@link SerializedIdentity}.
+ */
+export type LegacySerializedIdentity = {
+    privateKey: string;
+} | {
+    publicKey: string;
+};
+/**
+ * Accept either a modern {@link SerializedIdentity} envelope or a legacy
+ * `{ privateKey }` / `{ publicKey }` shape and normalize to a
+ * {@link SerializedIdentity}. Emits a one-time deprecation warning when a
+ * legacy shape is seen.
+ *
+ * Intended for the worker-side boundary; new page builds always emit tagged
+ * envelopes via {@link serializeSigningIdentity} /
+ * {@link serializeReadonlyIdentity}.
+ */
+export declare function normalizeSerializedIdentity(shape: SerializedIdentity | LegacySerializedIdentity): SerializedIdentity;