passkey-kit 0.18.2 → 0.19.0

package/dist/kit/legacy-ops.js

@@ -0,0 +1,237 @@
+/**
+ * Legacy (pre-1.0) wallet upgrade helpers.
+ *
+ * The kit cannot connect to a pre-1.0 wallet (`connectWallet` throws
+ * {@link LegacyWalletError}), but it can still craft the one transaction such
+ * a wallet needs: an in-place `update_contract_code` to the legacy-line build
+ * that reads both pre-1.0 storage layouts, followed for the bare-layout cohort
+ * by a `migrate_signers` call. This module builds those transactions from the
+ * wallet's actual on-chain state, so an application only has to sign and
+ * submit. See docs/legacy-wallet-upgrade.md for the full procedure.
+ *
+ * @packageDocumentation
+ */
+import { Address, xdr } from "@stellar/stellar-sdk";
+import { AssembledTransaction } from "@stellar/stellar-sdk/contract";
+import { KNOWN_VULNERABLE_WALLET_WASM_HASHES, LEGACY_UPGRADE_TARGET_WASM_HASH, LEGACY_WALLET_UPGRADE_GUIDE_URL, LEGACY_WALLET_WASM_HASHES, } from "../constants.js";
+import { PasskeyKitErrorCode, SigningError, ValidationError } from "../errors.js";
+import { signerKeyToScVal } from "./auth-payload.js";
+import { assertAdminRootMatchesHostFunction, signAuthEntry, } from "./tx-ops.js";
+import { toContractSignerKey } from "./wallet-ops.js";
+/**
+ * Pre-1.0 wallets that store signers in the pre-`6a27d48` (2024-12-13)
+ * layout. Every later build fails to decode them, which is why only the
+ * legacy-line target is a safe upgrade for them and why `migrate_signers`
+ * exists.
+ */
+export const BARE_LAYOUT_WALLET_WASM_HASHES = [
+    "0c0a264d4cc0b3e79b8533e2a2e1f0ed21501a5a3f9f2455d2f18c232940b865",
+    "19868df3653d427cafa1c30bdb6cec1ca5c8c815eeabab8a8bae6d83efb1fedd",
+];
+/** Classify a code hash without touching the network. */
+export function classifyWasmHash(wasmHash, acceptedWasmHashes) {
+    const hash = wasmHash.toLowerCase();
+    if (acceptedWasmHashes.includes(hash)) {
+        return { status: "current", cohort: null };
+    }
+    if (KNOWN_VULNERABLE_WALLET_WASM_HASHES.includes(hash)) {
+        return {
+            status: "vulnerable",
+            cohort: BARE_LAYOUT_WALLET_WASM_HASHES.includes(hash) ? "bare" : "wrapped",
+        };
+    }
+    if (LEGACY_WALLET_WASM_HASHES.includes(hash)) {
+        return { status: "legacy", cohort: "wrapped" };
+    }
+    return { status: "unknown", cohort: null };
+}
+function instanceLedgerKey(contractId) {
+    return xdr.LedgerKey.contractData(new xdr.LedgerKeyContractData({
+        contract: Address.fromString(contractId).toScAddress(),
+        key: xdr.ScVal.scvLedgerKeyContractInstance(),
+        durability: xdr.ContractDataDurability.persistent(),
+    }));
+}
+function codeLedgerKey(wasmHash) {
+    return xdr.LedgerKey.contractCode(new xdr.LedgerKeyContractCode({ hash: Buffer.from(wasmHash, "hex") }));
+}
+/**
+ * Read a wallet's code hash and the liveness of the entries an upgrade
+ * touches, and say what to do.
+ */
+export async function inspectLegacyWallet(deps, contractId) {
+    const wasmHash = (await deps.contractWasmHash(contractId)).toLowerCase();
+    const { status, cohort } = classifyWasmHash(wasmHash, deps.acceptedWasmHashes);
+    const upgradeTarget = LEGACY_UPGRADE_TARGET_WASM_HASH;
+    const keys = [instanceLedgerKey(contractId), codeLedgerKey(wasmHash), codeLedgerKey(upgradeTarget)];
+    const response = await deps.rpc.getLedgerEntries(...keys);
+    const latest = response.latestLedger;
+    const liveByKey = new Map();
+    for (const entry of response.entries) {
+        const liveUntil = entry.liveUntilLedgerSeq;
+        liveByKey.set(entry.key.toXDR("base64"), liveUntil !== undefined && liveUntil > latest);
+    }
+    const isLive = (key) => liveByKey.get(key.toXDR("base64")) === true;
+    const archived = {
+        instance: !isLive(keys[0]),
+        code: !isLive(keys[1]),
+        target: !isLive(keys[2]),
+    };
+    const upgradeRequired = status === "vulnerable";
+    const migrateRequired = cohort === "bare";
+    let recommendation;
+    switch (status) {
+        case "vulnerable":
+            recommendation =
+                `This wallet runs known-vulnerable code ${wasmHash.slice(0, 8)}…; anyone can overwrite ` +
+                    `its signers. Upgrade it in place now: ` +
+                    (archived.instance || archived.code || archived.target
+                        ? `restore the archived entries (${[
+                            archived.instance && "instance",
+                            archived.code && "current code",
+                            archived.target && "target code",
+                        ]
+                            .filter(Boolean)
+                            .join(", ")}), then `
+                        : "") +
+                    `call update_contract_code(${upgradeTarget.slice(0, 8)}…) authorized by an existing signer` +
+                    (migrateRequired
+                        ? `, then call migrate_signers with every signer key (this wallet stores the pre-6a27d48 layout)`
+                        : "") +
+                    `. Or move its funds out. Guide: ${LEGACY_WALLET_UPGRADE_GUIDE_URL}`;
+            break;
+        case "legacy":
+            recommendation =
+                `This wallet runs patched pre-1.0 code ${wasmHash.slice(0, 8)}…. It is not vulnerable; ` +
+                    `operate it with the passkey-kit 0.10.20–0.12.x line. Guide: ${LEGACY_WALLET_UPGRADE_GUIDE_URL}`;
+            break;
+        case "current":
+            recommendation = "This wallet runs accepted current code. No upgrade is needed.";
+            break;
+        default:
+            recommendation =
+                `This wallet runs code ${wasmHash.slice(0, 8)}… that this kit does not recognize. ` +
+                    `Verify its provenance before acting.`;
+    }
+    return {
+        contractId,
+        wasmHash,
+        status,
+        cohort,
+        upgradeTarget,
+        upgradeRequired,
+        migrateRequired,
+        archived,
+        guideUrl: LEGACY_WALLET_UPGRADE_GUIDE_URL,
+        recommendation,
+    };
+}
+/**
+ * Build `wallet.update_contract_code(target)` for a legacy wallet.
+ *
+ * The transaction's single auth entry is the wallet's own, to be signed by an
+ * existing signer through {@link signLegacyUpgradeTx}. The envelope source is
+ * the SDK's placeholder account, so submit through `PasskeyServer.send` (a
+ * relayer supplies the source and fees) or rebuild with your own funded source.
+ */
+export function buildLegacyUpgradeTx(deps, contractId, target = LEGACY_UPGRADE_TARGET_WASM_HASH) {
+    if (!/^[0-9a-f]{64}$/i.test(target)) {
+        throw new ValidationError("upgrade target must be a 32-byte hex WASM hash", PasskeyKitErrorCode.INVALID_INPUT, { target });
+    }
+    return AssembledTransaction.build({
+        method: "update_contract_code",
+        args: [xdr.ScVal.scvBytes(Buffer.from(target, "hex"))],
+        contractId,
+        rpcUrl: deps.rpcUrl,
+        networkPassphrase: deps.networkPassphrase,
+        timeoutInSeconds: deps.timeoutInSeconds,
+        parseResultXdr: () => null,
+    });
+}
+/**
+ * Build `wallet.migrate_signers(keys)` for a wallet already on the legacy-line
+ * target. The call needs no wallet authorization (it is a value-preserving
+ * re-encoding), so any funded source can submit it. Returns the number of
+ * entries rewritten when simulated or executed.
+ *
+ * Soroban has no storage iteration, so the caller supplies the keys: the
+ * hosted passkey indexer (`MercuryIndexer.getSigners` /
+ * `PasskeyServer.getSigners`) lists every signer a wallet has ever held.
+ */
+export function buildLegacyMigrateTx(deps, contractId, signerKeys) {
+    if (signerKeys.length === 0) {
+        throw new ValidationError("migrate_signers needs at least one signer key", PasskeyKitErrorCode.INVALID_INPUT, { contractId });
+    }
+    const keys = signerKeys.map((key) => signerKeyToScVal(deps.spec, toContractSignerKey(key)));
+    return AssembledTransaction.build({
+        method: "migrate_signers",
+        args: [xdr.ScVal.scvVec(keys)],
+        contractId,
+        rpcUrl: deps.rpcUrl,
+        networkPassphrase: deps.networkPassphrase,
+        timeoutInSeconds: deps.timeoutInSeconds,
+        parseResultXdr: (value) => value.u32(),
+    });
+}
+/**
+ * Sign a legacy wallet's `update_contract_code` auth entry with one of its
+ * existing signers, without a connected wallet.
+ *
+ * Passkey and Ed25519 signature entries encode identically on every pre-1.0
+ * build, and the signature covers the V2 address-bound payload the host
+ * presents to any custom account, so the kit's normal signers work here. The
+ * entry root is pinned to the transaction's own host function, as for every
+ * wallet-admin write.
+ */
+export async function signLegacyUpgradeTx(deps, tx, signer, options) {
+    const built = tx.built;
+    const topOp = built?.operations[0];
+    const topFunc = topOp?.type === "invokeHostFunction"
+        ? topOp.func
+        : undefined;
+    if (!topFunc) {
+        throw new ValidationError("the transaction has no invoke-host-function operation to sign", PasskeyKitErrorCode.INVALID_INPUT, { contractId: deps.contractId });
+    }
+    // Resolve the expiration once here (the kit's own ledger-based default) so
+    // the SDK does not fetch it, and pass the same value to every entry.
+    const expiration = options?.expiration ?? (await deps.calculateExpiration());
+    await tx.signAuthEntries({
+        address: deps.contractId,
+        expiration,
+        authorizeEntry: async (entry) => {
+            const clone = xdr.SorobanAuthorizationEntry.fromXDR(entry.toXDR());
+            assertRootIsExactlyThisCall(clone, deps.contractId, topFunc);
+            assertAdminRootMatchesHostFunction(clone, deps.contractId, topFunc);
+            return signAuthEntry(deps, clone, signer, {
+                ...options,
+                expiration,
+                allowWalletReentry: true,
+            });
+        },
+    });
+    return tx;
+}
+/**
+ * The legacy upgrade signs exactly one thing: this wallet's own
+ * `update_contract_code` (or `migrate_signers`) as the transaction's
+ * top-level call, with no sub-invocations. Anything else is refused before
+ * hashing, so a hostile transaction cannot borrow this signing path.
+ */
+function assertRootIsExactlyThisCall(entry, contractId, topFunc) {
+    const root = entry.rootInvocation();
+    const fn = root.function();
+    const expected = topFunc.switch().name === "hostFunctionTypeInvokeContract"
+        ? topFunc.invokeContract()
+        : undefined;
+    const actual = fn.switch().name === "sorobanAuthorizedFunctionTypeContractFn" ? fn.contractFn() : undefined;
+    const ok = expected !== undefined &&
+        actual !== undefined &&
+        root.subInvocations().length === 0 &&
+        Address.fromScAddress(actual.contractAddress()).toString() === contractId &&
+        actual.toXDR("base64") === expected.toXDR("base64");
+    if (!ok) {
+        throw new SigningError(`Refusing to sign: the auth entry must root at ${contractId}'s own top-level ` +
+            `update_contract_code / migrate_signers call with no sub-invocations`, PasskeyKitErrorCode.SIGNING_FAILED, { contractId });
+    }
+}
+//# sourceMappingURL=legacy-ops.js.map

package/dist/kit/legacy-ops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"legacy-ops.js","sourceRoot":"","sources":["../../src/kit/legacy-ops.ts"],"names":[],"mappings":"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"}

package/dist/kit.d.ts

@@ -22,6 +22,7 @@ import { type Signer } from "./signers.js";
 import type { WebAuthnClient } from "./kit/webauthn-ops.js";
 import type { CreatedPasskey } from "./kit/webauthn-ops.js";
 import type { SignOptions } from "./kit/tx-ops.js";
+import { type LegacyWalletInspection } from "./kit/legacy-ops.js";
 import { type PolicySignerTxOptions, type WalletTx } from "./kit/wallet-ops.js";
 import type { WalletCandidateLookup } from "./indexer/types.js";
 import { type VerifiedWalletBirth } from "./kit/birth-verification.js";
@@ -97,6 +98,8 @@ export declare class PasskeyKit {
     readonly acceptedWasmHashes: readonly string[];
     /** Accepted immutable birth code identities, lowercase hex. Never empty. */
     readonly acceptedBirthWasmHashes: readonly string[];
+    /** Funded key used only for footprint restores, when configured. */
+    private readonly restoreKeypair?;
     /** Full-history source for immutable wallet-birth verification. */
     readonly history?: Horizon.Server;
     readonly rpId?: string;
@@ -143,6 +146,13 @@ export declare class PasskeyKit {
      * @throws {WalletOwnershipError} If the keyId is not a signer on the wallet.
      */
     connectWallet(options?: ConnectOptions): Promise<ConnectWalletResult>;
+    /**
+     * Reject a wallet whose current code is a pre-1.0 build, with guidance.
+     * Known-vulnerable builds get the upgrade instructions; patched legacy
+     * builds get the "use the 0.10.20–0.12.x kit" instruction. Accepted hashes
+     * are never legacy, so an integrator cannot opt into a vulnerable build.
+     */
+    private assertNotLegacyWallet;
     private assertWalletWasmHash;
     private contractWasmHash;
     /** Create the address-bound proof required for a Secp256r1 signer write. */
@@ -154,6 +164,47 @@ export declare class PasskeyKit {
     private assertWebAuthnVerificationConfig;
     /** Disconnect the current wallet. */
     disconnect(): void;
+    /**
+     * Inspect a wallet this kit cannot connect to and say what it needs:
+     * its code status (vulnerable / legacy / current / unknown), its storage
+     * cohort, which ledger entries are archived, and a plain recommendation.
+     * Read-only.
+     */
+    inspectLegacyWallet(contractId: string): Promise<LegacyWalletInspection>;
+    private legacyTxDeps;
+    /**
+     * Restore archived entries a simulated transaction needs, using the
+     * configured `restoreSource`, and rebuild. Throws with guidance when no
+     * restore source is configured.
+     */
+    private withRestore;
+    /**
+     * Build the in-place upgrade for a pre-1.0 wallet:
+     * `update_contract_code(<legacy-line target>)`, authorized by the wallet.
+     * Refuses wallets that are not on a known pre-1.0 build. Restores archived
+     * entries first when `restoreSource` is configured.
+     *
+     * Sign it with {@link signLegacyUpgradeTx} and submit through
+     * `PasskeyServer.send` (or your own funded source).
+     */
+    buildLegacyUpgradeTx(contractId: string): Promise<{
+        inspection: LegacyWalletInspection;
+        tx: AssembledTransaction<null>;
+    }>;
+    /**
+     * Build `migrate_signers(keys)` for a wallet already upgraded to the
+     * legacy-line target. Needs no wallet authorization; any funded source can
+     * submit it. Get the keys from `PasskeyServer.getSigners` /
+     * `MercuryIndexer.getSigners`.
+     */
+    buildLegacyMigrateTx(contractId: string, signerKeys: readonly SignerKey[]): Promise<AssembledTransaction<number>>;
+    /**
+     * Sign a legacy wallet's upgrade transaction with one of its existing
+     * signers, without connecting. Defaults to a discoverable passkey prompt;
+     * pass `new PasskeySigner(keyId)` to require a specific credential, or an
+     * `Ed25519Signer`.
+     */
+    signLegacyUpgradeTx<T>(tx: AssembledTransaction<T>, contractId: string, signer?: Signer, options?: Omit<SignOptions, "allowWalletReentry">): Promise<AssembledTransaction<T>>;
     /** Sign a single auth entry (defaults to the connected passkey signer). */
     signAuthEntry(entry: xdr.SorobanAuthorizationEntry, signer?: Signer, options?: SignOptions): Promise<xdr.SorobanAuthorizationEntry>;
     /** Sign an assembled transaction's wallet auth entries. */

package/dist/kit.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../src/kit.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../src/kit.ts"],"names":[],"mappings":"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"}

package/dist/kit.js

@@ -17,14 +17,16 @@ import { startAuthentication, startRegistration, } from "@simplewebauthn/browser
 import { Client as PasskeyClient, } from "passkey-kit-sdk";
 import base64url from "./base64url.js";
 import { SignerKey, SignerStore, } from "./types.js";
-import { ConfigurationError, PasskeyKitError, PasskeyKitErrorCode, WalletNotConnectedError, WalletOwnershipError, WalletAmbiguousError, } from "./errors.js";
+import { ConfigurationError, PasskeyKitError, ValidationError, PasskeyKitErrorCode, WalletNotConnectedError, WalletOwnershipError, WalletAmbiguousError, LegacyWalletError, } from "./errors.js";
 import { PasskeyEventEmitter } from "./events.js";
 import { isDefaultDeployer } from "./utils.js";
-import { DEFAULT_TIMEOUT_SECONDS } from "./constants.js";
+import { DEFAULT_TIMEOUT_SECONDS, KNOWN_VULNERABLE_WALLET_WASM_HASHES, LEGACY_UPGRADE_TARGET_WASM_HASH, LEGACY_WALLET_UPGRADE_GUIDE_URL, LEGACY_WALLET_WASM_HASHES, } from "./constants.js";
 import { PasskeySigner } from "./signers.js";
 import { calculateExpiration } from "./kit/tx-ops.js";
 import { CredentialManager, SignerManager, SubmissionManager, } from "./managers/index.js";
 import { resolveDeployer } from "./kit/deploy-ops.js";
+import { buildLegacyMigrateTx, buildLegacyUpgradeTx, inspectLegacyWallet, signLegacyUpgradeTx, } from "./kit/legacy-ops.js";
+import { restoreFootprint } from "./kit/tx-ops.js";
 import { buildSecp256r1Signer, } from "./kit/wallet-ops.js";
 import { verifyWalletBirth, } from "./kit/birth-verification.js";
 import { bindingChallenge, verifyBindingRecord, verifyFreshAssertion, verifyStoredProof, } from "./kit/webauthn-verify.js";
@@ -44,6 +46,8 @@ export class PasskeyKit {
     acceptedWasmHashes;
     /** Accepted immutable birth code identities, lowercase hex. Never empty. */
     acceptedBirthWasmHashes;
+    /** Funded key used only for footprint restores, when configured. */
+    restoreKeypair;
     /** Full-history source for immutable wallet-birth verification. */
     history;
     rpId;
@@ -70,6 +74,18 @@ export class PasskeyKit {
         if (!config.walletWasmHash) {
             throw new ConfigurationError("walletWasmHash is required", PasskeyKitErrorCode.MISSING_CONFIG);
         }
+        for (const configured of [
+            config.walletWasmHash,
+            ...(config.acceptedWasmHashes ?? []),
+            ...(config.acceptedBirthWasmHashes ?? []),
+        ]) {
+            if (KNOWN_VULNERABLE_WALLET_WASM_HASHES.includes(configured.toLowerCase())) {
+                throw new ConfigurationError(`walletWasmHash ${configured.slice(0, 8)}… is a known-vulnerable legacy build ` +
+                    `(update_signer has no authorization check). Do not deploy from it or accept it. ` +
+                    `Existing wallets on it must upgrade to ${LEGACY_UPGRADE_TARGET_WASM_HASH}; ` +
+                    `see ${LEGACY_WALLET_UPGRADE_GUIDE_URL}`, PasskeyKitErrorCode.INVALID_CONFIG, { wasmHash: configured.toLowerCase() });
+            }
+        }
         this.rpc = new Server(config.rpcUrl);
         this.rpcUrl = config.rpcUrl;
         this.networkPassphrase = config.networkPassphrase;
@@ -130,6 +146,7 @@ export class PasskeyKit {
             getSignerContext: () => this.signerContext(),
             calculateExpiration: () => calculateExpiration({ rpc: this.rpc, timeoutInSeconds: this.timeoutInSeconds }),
         });
+        this.restoreKeypair = restoreKeypair;
         this.submissionManager = new SubmissionManager({
             rpc: this.rpc,
             rpcUrl: config.rpcUrl,
@@ -299,6 +316,9 @@ export class PasskeyKit {
         // The last definitive rejection, rethrown verbatim when nothing verifies so
         // its context (e.g. the rejected wasm hash) is not replaced by a summary.
         let lastMismatch;
+        // A candidate on pre-1.0 code is a definitive answer with its own guidance.
+        // It is reported in preference to any generic mismatch when nothing verifies.
+        let legacyMismatch;
         for (const candidate of candidates) {
             const wallet = new PasskeyClient({
                 contractId: candidate.contractId,
@@ -308,6 +328,10 @@ export class PasskeyKit {
             this.wallet = wallet;
             this.keyId = keyIdBase64;
             try {
+                // Before birth verification: a legacy wallet fails that check for
+                // reasons that would hide the real problem (no constructor birth, an
+                // unaccepted hash). Name the legacy code and the upgrade path instead.
+                await this.assertNotLegacyWallet(candidate.contractId);
                 const birth = await verifyWalletBirth({
                     rpc: this.rpc,
                     history: this.history,
@@ -358,6 +382,10 @@ export class PasskeyKit {
             catch (err) {
                 this.wallet = undefined;
                 this.keyId = undefined;
+                if (err instanceof LegacyWalletError) {
+                    legacyMismatch = err;
+                    continue;
+                }
                 if (err instanceof WalletOwnershipError) {
                     lastMismatch = err;
                     continue;
@@ -368,7 +396,8 @@ export class PasskeyKit {
         this.wallet = undefined;
         this.keyId = undefined;
         if (verified.size === 0) {
-            throw (lastMismatch ??
+            throw (legacyMismatch ??
+                lastMismatch ??
                 new WalletOwnershipError("The passkey is not a signer on any resolved wallet", {
                     candidates: candidates.map(({ contractId }) => contractId),
                     keyId: keyIdBase64,
@@ -392,6 +421,26 @@ export class PasskeyKit {
         this.events.emit("walletConnected", { contractId, keyId: keyIdBase64 });
         return { rawResponse, keyId: keyIdBuffer, keyIdBase64, contractId };
     }
+    /**
+     * Reject a wallet whose current code is a pre-1.0 build, with guidance.
+     * Known-vulnerable builds get the upgrade instructions; patched legacy
+     * builds get the "use the 0.10.20–0.12.x kit" instruction. Accepted hashes
+     * are never legacy, so an integrator cannot opt into a vulnerable build.
+     */
+    async assertNotLegacyWallet(contractId) {
+        const wasmHash = await this.contractWasmHash(contractId);
+        const vulnerable = KNOWN_VULNERABLE_WALLET_WASM_HASHES.includes(wasmHash);
+        if (!vulnerable && !LEGACY_WALLET_WASM_HASHES.includes(wasmHash)) {
+            return;
+        }
+        throw new LegacyWalletError({
+            contractId,
+            wasmHash,
+            vulnerable,
+            upgradeTarget: LEGACY_UPGRADE_TARGET_WASM_HASH,
+            guideUrl: LEGACY_WALLET_UPGRADE_GUIDE_URL,
+        });
+    }
     async assertWalletWasmHash(contractId) {
         const wasmHash = await this.contractWasmHash(contractId);
         if (!this.acceptedWasmHashes.includes(wasmHash)) {
@@ -512,6 +561,98 @@ export class PasskeyKit {
             this.events.emit("walletDisconnected", { contractId });
         }
     }
+    // -- Legacy (pre-1.0) wallet upgrade ------------------------------------------
+    /**
+     * Inspect a wallet this kit cannot connect to and say what it needs:
+     * its code status (vulnerable / legacy / current / unknown), its storage
+     * cohort, which ledger entries are archived, and a plain recommendation.
+     * Read-only.
+     */
+    inspectLegacyWallet(contractId) {
+        return inspectLegacyWallet({
+            rpc: this.rpc,
+            acceptedWasmHashes: this.acceptedWasmHashes,
+            contractWasmHash: (id) => this.contractWasmHash(id),
+        }, contractId);
+    }
+    legacyTxDeps(contractId) {
+        return {
+            rpcUrl: this.rpcUrl,
+            networkPassphrase: this.networkPassphrase,
+            timeoutInSeconds: this.timeoutInSeconds,
+            spec: new PasskeyClient({
+                contractId,
+                rpcUrl: this.rpcUrl,
+                networkPassphrase: this.networkPassphrase,
+            }).spec,
+        };
+    }
+    /**
+     * Restore archived entries a simulated transaction needs, using the
+     * configured `restoreSource`, and rebuild. Throws with guidance when no
+     * restore source is configured.
+     */
+    async withRestore(build, contractId) {
+        let tx = await build();
+        const simulation = tx.simulation;
+        if (simulation && Api.isSimulationRestore(simulation)) {
+            if (!this.restoreKeypair) {
+                throw new PasskeyKitError(`Wallet ${contractId} has archived ledger entries that must be restored before this ` +
+                    `call can run. Configure \`restoreSource\` (a funded key) on the kit, or submit a ` +
+                    `RestoreFootprint operation yourself, then retry.`, PasskeyKitErrorCode.RESTORE_REQUIRED, { context: { contractId } });
+            }
+            await restoreFootprint({
+                rpc: this.rpc,
+                networkPassphrase: this.networkPassphrase,
+                sourceKeypair: this.restoreKeypair,
+                timeoutInSeconds: this.timeoutInSeconds,
+            }, simulation.restorePreamble);
+            tx = await build();
+        }
+        return tx;
+    }
+    /**
+     * Build the in-place upgrade for a pre-1.0 wallet:
+     * `update_contract_code(<legacy-line target>)`, authorized by the wallet.
+     * Refuses wallets that are not on a known pre-1.0 build. Restores archived
+     * entries first when `restoreSource` is configured.
+     *
+     * Sign it with {@link signLegacyUpgradeTx} and submit through
+     * `PasskeyServer.send` (or your own funded source).
+     */
+    async buildLegacyUpgradeTx(contractId) {
+        const inspection = await this.inspectLegacyWallet(contractId);
+        if (inspection.status !== "vulnerable" && inspection.status !== "legacy") {
+            throw new ValidationError(`Wallet ${contractId} is not on a known pre-1.0 build (${inspection.status}); ` +
+                `there is no legacy upgrade to build. ${inspection.recommendation}`, PasskeyKitErrorCode.INVALID_INPUT, { contractId, wasmHash: inspection.wasmHash, status: inspection.status });
+        }
+        const tx = await this.withRestore(() => buildLegacyUpgradeTx(this.legacyTxDeps(contractId), contractId, inspection.upgradeTarget), contractId);
+        return { inspection, tx };
+    }
+    /**
+     * Build `migrate_signers(keys)` for a wallet already upgraded to the
+     * legacy-line target. Needs no wallet authorization; any funded source can
+     * submit it. Get the keys from `PasskeyServer.getSigners` /
+     * `MercuryIndexer.getSigners`.
+     */
+    buildLegacyMigrateTx(contractId, signerKeys) {
+        return this.withRestore(() => buildLegacyMigrateTx(this.legacyTxDeps(contractId), contractId, signerKeys), contractId);
+    }
+    /**
+     * Sign a legacy wallet's upgrade transaction with one of its existing
+     * signers, without connecting. Defaults to a discoverable passkey prompt;
+     * pass `new PasskeySigner(keyId)` to require a specific credential, or an
+     * `Ed25519Signer`.
+     */
+    signLegacyUpgradeTx(tx, contractId, signer = new PasskeySigner("any"), options) {
+        return signLegacyUpgradeTx({
+            networkPassphrase: this.networkPassphrase,
+            spec: this.legacyTxDeps(contractId).spec,
+            signerContext: this.signerContext(),
+            calculateExpiration: () => calculateExpiration({ rpc: this.rpc, timeoutInSeconds: this.timeoutInSeconds }),
+            contractId,
+        }, tx, signer, options);
+    }
     // -- Signing -----------------------------------------------------------------
     /** Sign a single auth entry (defaults to the connected passkey signer). */
     signAuthEntry(entry, signer, options) {