@droplinked_inc/wallet-connection 0.1.1

package/dist/connectors/evm.d.ts

@@ -0,0 +1,144 @@
+/**
+ * EVM connector — replaces the v1.0.1 EVMProvider class.
+ *
+ * Hardening deltas:
+ *   1. No remote fetch of contract address (was a single point of supply-chain
+ *      compromise via apiv3dev.droplinked.com). Caller supplies the address.
+ *   2. Wallet selection is strict: MetaMask must self-identify as MetaMask
+ *      and Coinbase must self-identify as Coinbase. No fallthrough to the
+ *      umbrella `window.ethereum`.
+ *   3. All RPC responses are zod-validated.
+ *   4. Login is EIP-712 typed, not personal_sign of a static string.
+ *   5. No recursive self-call in `handleWallet` (the original had an
+ *      uncontrolled recursion that could spin a wallet-permissions popup
+ *      loop).
+ *   6. Bigints throughout — no `any` for `totalPrice`.
+ */
+import { Chain, ChainWallet, Network, type ChainProvider, type EvmAddress, type IChainPayment } from '../types.js';
+import { type Eip1193Provider } from '../provider.js';
+import type { Hex } from 'viem';
+/** Minimal ABI fragments — kept inline rather than fetched remotely. */
+declare const ERC20_TRANSFER_ABI: readonly [{
+    readonly constant: false;
+    readonly inputs: readonly [{
+        readonly name: "_to";
+        readonly type: "address";
+    }, {
+        readonly name: "_value";
+        readonly type: "uint256";
+    }];
+    readonly name: "transfer";
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "bool";
+    }];
+    readonly stateMutability: "nonpayable";
+    readonly type: "function";
+}];
+export interface EvmConnectorOptions {
+    readonly chain: Chain;
+    readonly network: Network;
+    readonly wallet?: ChainWallet;
+    /** Required for `payment()` — the droplinked checkout contract address. */
+    readonly checkoutContractAddress?: EvmAddress;
+    /** Required for typed-data signing. Defaults to globalThis.location.origin. */
+    readonly origin?: string;
+}
+export declare class EvmConnector implements ChainProvider {
+    readonly chain: Chain;
+    readonly network: Network;
+    address: EvmAddress;
+    wallet: ChainWallet;
+    private readonly checkoutContractAddress;
+    private readonly origin;
+    constructor(opts: EvmConnectorOptions);
+    setAddress(address: string): this;
+    setWallet(wallet: ChainWallet): this;
+    /** Resolve the EIP-1193 provider for the configured wallet. */
+    getWalletProvider(): Eip1193Provider;
+    /**
+     * Ensure the wallet is connected to the expected address and chain.
+     * Unlike v1.0.1 this is iterative (max 3 retries) — there is no
+     * recursive self-call that can spin a popup loop.
+     */
+    handleWallet(expectedAddress: string): Promise<void>;
+    /**
+     * Connect + EIP-712 typed login. Returns the signature; the caller is
+     * expected to submit it to the droplinked auth API.
+     */
+    walletLogin(): Promise<{
+        address: EvmAddress;
+        signature: string;
+    }>;
+    /**
+     * ERC-20 token transfer.
+     *
+     * NOTE: This issues a direct `transfer` call. We intentionally do *not*
+     * issue an `approve` against an unbounded spender — the drainer-style
+     * "approve max uint256 to a router" pattern is rejected at the API
+     * boundary. Callers wanting allowance flows must use a different
+     * specialized package.
+     */
+    paymentWithToken(receiver: string, amount: bigint, tokenAddress: string): Promise<string>;
+    /**
+     * Droplinked checkout contract call. Requires
+     * `checkoutContractAddress` to be supplied at construction time —
+     * we will never fetch it from a remote endpoint.
+     */
+    payment(data: IChainPayment): Promise<{
+        deploy_hash: string;
+        cryptoAmount: bigint;
+    }>;
+    /**
+     * Submit pre-built calldata produced server-side. The calldata is
+     * NOT trusted blindly — we enforce two boundary checks before
+     * surfacing the transaction to the wallet:
+     *
+     *   1. `to` MUST equal the connector's configured
+     *      `checkoutContractAddress`. Sending arbitrary calldata to an
+     *      arbitrary destination would resurrect the drainer pathway
+     *      that motivated removing the v1.0.1 remote-ABI fetch.
+     *   2. The first 4 bytes of `data` (the function selector) MUST be
+     *      on the explicit allowlist below. Notably the selectors for
+     *      `approve(address,uint256)`, `setApprovalForAll(...)`, NFT
+     *      `safeTransferFrom(...)`, and ERC-20 `permit(...)` are
+     *      rejected — these are the canonical "drainer" entry points
+     *      that a compromised checkout API or consumer-side XSS would
+     *      try to coerce the user into signing.
+     *
+     * Both checks throw `InvalidTransactionError` BEFORE any wallet
+     * prompt appears, so the user is never shown a malicious payload.
+     */
+    submitRawTransaction(args: {
+        readonly to: EvmAddress;
+        readonly data: Hex;
+        readonly value: bigint;
+        readonly gasLimit?: bigint;
+    }): Promise<Hex>;
+}
+/**
+ * 4-byte function selectors that the droplinked checkout flow is known
+ * to call. Anything else is rejected at the boundary.
+ *
+ *  - `0xa9059cbb` — ERC-20 `transfer(address,uint256)`
+ *      The standard token payment path used by `paymentWithToken`.
+ *  - `0x6a627842` — droplinked legacy checkout `droplinkedPurchase(...)`
+ *      Selector matches the calldata blob produced by the droplinked
+ *      checkout API. Replace if the API rotates to a new function.
+ *  - `0x` (empty data) — native-currency transfer to the checkout
+ *      contract. Allowed because there is no selector to spoof; the
+ *      destination is already pinned by the `to === checkoutContract`
+ *      check.
+ */
+export declare const SUBMIT_RAW_TX_SELECTOR_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Drainer selectors callers will sometimes ask the wallet to sign.
+ * Listed explicitly so the rejection message names them — when one of
+ * these appears in calldata, that is *strong* evidence that the
+ * checkout API or the consumer page is compromised.
+ */
+export declare const KNOWN_DRAINER_SELECTORS: Readonly<Record<string, string>>;
+/** Returns the calldata blob for `transfer(address,uint256)`. */
+export declare function encodeErc20Transfer(to: EvmAddress, amount: bigint): Hex;
+export { ERC20_TRANSFER_ABI };
+//# sourceMappingURL=evm.d.ts.map

package/dist/connectors/evm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evm.d.ts","sourceRoot":"","sources":["../../src/connectors/evm.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,EACL,KAAK,EAEL,WAAW,EAEX,OAAO,EACP,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,aAAa,EACnB,MAAM,aAAa,CAAC;AAQrB,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AAKxB,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAEhC,wEAAwE;AACxE,QAAA,MAAM,kBAAkB;;;;;;;;;;;;;;;;EAYd,CAAC;AAEX,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,2EAA2E;IAC3E,QAAQ,CAAC,uBAAuB,CAAC,EAAE,UAAU,CAAC;IAC9C,+EAA+E;IAC/E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,YAAa,YAAW,aAAa;IAChD,SAAgB,KAAK,EAAE,KAAK,CAAC;IAC7B,SAAgB,OAAO,EAAE,OAAO,CAAC;IAC1B,OAAO,EAAE,UAAU,CAAgD;IACnE,MAAM,EAAE,WAAW,CAAC;IAC3B,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAyB;IACjE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,IAAI,EAAE,mBAAmB;IAQrC,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAKjC,SAAS,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAUpC,+DAA+D;IAC/D,iBAAiB,IAAI,eAAe;IAUpC;;;;OAIG;IACG,YAAY,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoD1D;;;OAGG;IACG,WAAW,IAAI,OAAO,CAAC;QAAE,OAAO,EAAE,UAAU,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;IA8BxE;;;;;;;;OAQG;IACG,gBAAgB,CACpB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,MAAM,CAAC;IA0BlB;;;;OAIG;IACG,OAAO,CACX,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC;IAoBzD;;;;;;;;;;;;;;;;;;;OAmBG;IACG,oBAAoB,CAAC,IAAI,EAAE;QAC/B,QAAQ,CAAC,EAAE,EAAE,UAAU,CAAC;QACxB,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC;QACnB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;KAC5B,GAAG,OAAO,CAAC,GAAG,CAAC;CAkCjB;AAMD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,gCAAgC,EAAE,WAAW,CAAC,MAAM,CAG/D,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAOpE,CAAC;AAyCF,iEAAiE;AACjE,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,GAAG,CASvE;AAGD,OAAO,EAAE,kBAAkB,EAAE,CAAC"}

package/dist/connectors/evm.js

@@ -0,0 +1,330 @@
+/**
+ * EVM connector — replaces the v1.0.1 EVMProvider class.
+ *
+ * Hardening deltas:
+ *   1. No remote fetch of contract address (was a single point of supply-chain
+ *      compromise via apiv3dev.droplinked.com). Caller supplies the address.
+ *   2. Wallet selection is strict: MetaMask must self-identify as MetaMask
+ *      and Coinbase must self-identify as Coinbase. No fallthrough to the
+ *      umbrella `window.ethereum`.
+ *   3. All RPC responses are zod-validated.
+ *   4. Login is EIP-712 typed, not personal_sign of a static string.
+ *   5. No recursive self-call in `handleWallet` (the original had an
+ *      uncontrolled recursion that could spin a wallet-permissions popup
+ *      loop).
+ *   6. Bigints throughout — no `any` for `totalPrice`.
+ */
+import { ChainPaymentSchema, ChainWallet, EvmAddressSchema, } from '../types.js';
+import { AccountChangedException, ChainMismatchError, InvalidTransactionError, WalletNotFoundException, } from '../errors.js';
+import { getChainMetadata } from '../chains.js';
+import { getAccounts, getChainId, isWalletConnected, requestAccounts, selectCoinbaseProvider, selectMetaMaskProvider, } from '../provider.js';
+import { buildLoginPayload, signLoginPayload, } from '../signing.js';
+/** Minimal ABI fragments — kept inline rather than fetched remotely. */
+const ERC20_TRANSFER_ABI = [
+    {
+        constant: false,
+        inputs: [
+            { name: '_to', type: 'address' },
+            { name: '_value', type: 'uint256' },
+        ],
+        name: 'transfer',
+        outputs: [{ name: '', type: 'bool' }],
+        stateMutability: 'nonpayable',
+        type: 'function',
+    },
+];
+export class EvmConnector {
+    chain;
+    network;
+    address = '0x0000000000000000000000000000000000000000';
+    wallet;
+    checkoutContractAddress;
+    origin;
+    constructor(opts) {
+        this.chain = opts.chain;
+        this.network = opts.network;
+        this.wallet = opts.wallet ?? ChainWallet.Metamask;
+        this.checkoutContractAddress = opts.checkoutContractAddress;
+        this.origin = opts.origin ?? resolveOrigin();
+    }
+    setAddress(address) {
+        this.address = EvmAddressSchema.parse(address);
+        return this;
+    }
+    setWallet(wallet) {
+        if (wallet !== ChainWallet.Metamask && wallet !== ChainWallet.CoinBase) {
+            throw new WalletNotFoundException(`wallet ${wallet} not supported on EVM connector`);
+        }
+        this.wallet = wallet;
+        return this;
+    }
+    /** Resolve the EIP-1193 provider for the configured wallet. */
+    getWalletProvider() {
+        if (this.wallet === ChainWallet.Metamask) {
+            return selectMetaMaskProvider();
+        }
+        if (this.wallet === ChainWallet.CoinBase) {
+            return selectCoinbaseProvider();
+        }
+        throw new WalletNotFoundException(`wallet ${this.wallet} not implemented`);
+    }
+    /**
+     * Ensure the wallet is connected to the expected address and chain.
+     * Unlike v1.0.1 this is iterative (max 3 retries) — there is no
+     * recursive self-call that can spin a popup loop.
+     */
+    async handleWallet(expectedAddress) {
+        const expected = EvmAddressSchema.parse(expectedAddress);
+        const provider = this.getWalletProvider();
+        const meta = getChainMetadata(this.chain, this.network);
+        for (let attempt = 0; attempt < 3; attempt++) {
+            let accounts = await getAccounts(provider);
+            if (!(await isWalletConnected(provider)) || accounts.length === 0) {
+                accounts = await requestAccounts(provider);
+            }
+            const first = accounts[0];
+            if (first === undefined) {
+                throw new WalletNotFoundException('wallet returned no accounts');
+            }
+            if (first.toLowerCase() !== expected) {
+                // Ask for permissions once; do NOT recurse forever.
+                await provider.request({
+                    method: 'wallet_requestPermissions',
+                    params: [{ eth_accounts: {} }],
+                });
+                continue;
+            }
+            const currentChainId = await getChainId(provider);
+            if (currentChainId.toLowerCase() !== meta.chainIdHex.toLowerCase()) {
+                try {
+                    await provider.request({
+                        method: 'wallet_switchEthereumChain',
+                        params: [{ chainId: meta.chainIdHex }],
+                    });
+                }
+                catch {
+                    await provider.request({
+                        method: 'wallet_addEthereumChain',
+                        params: [
+                            {
+                                chainId: meta.chainIdHex,
+                                chainName: meta.chainName,
+                                nativeCurrency: meta.nativeCurrency,
+                                rpcUrls: meta.rpcUrls,
+                            },
+                        ],
+                    });
+                }
+                continue;
+            }
+            return;
+        }
+        throw new AccountChangedException(`wallet did not converge to ${expected} on ${this.chain}/${this.network}`);
+    }
+    /**
+     * Connect + EIP-712 typed login. Returns the signature; the caller is
+     * expected to submit it to the droplinked auth API.
+     */
+    async walletLogin() {
+        const provider = this.getWalletProvider();
+        const accountsBefore = await getAccounts(provider);
+        const accounts = accountsBefore.length > 0 ? accountsBefore : await requestAccounts(provider);
+        const first = accounts[0];
+        if (first === undefined) {
+            throw new WalletNotFoundException('wallet returned no accounts');
+        }
+        const address = EvmAddressSchema.parse(first);
+        const meta = getChainMetadata(this.chain, this.network);
+        const currentChainId = await getChainId(provider);
+        if (currentChainId.toLowerCase() !== meta.chainIdHex.toLowerCase()) {
+            throw new ChainMismatchError(`wallet on chain ${currentChainId} but ${meta.chainIdHex} expected`);
+        }
+        const payload = buildLoginPayload({
+            address,
+            chainId: meta.chainIdNumber,
+            origin: this.origin,
+            expiresInSeconds: 60 * 10, // 10 minutes
+        });
+        const signature = await signLoginPayload(provider, payload);
+        this.address = address;
+        return { address, signature };
+    }
+    /**
+     * ERC-20 token transfer.
+     *
+     * NOTE: This issues a direct `transfer` call. We intentionally do *not*
+     * issue an `approve` against an unbounded spender — the drainer-style
+     * "approve max uint256 to a router" pattern is rejected at the API
+     * boundary. Callers wanting allowance flows must use a different
+     * specialized package.
+     */
+    async paymentWithToken(receiver, amount, tokenAddress) {
+        const recv = EvmAddressSchema.parse(receiver);
+        const token = EvmAddressSchema.parse(tokenAddress);
+        if (typeof amount !== 'bigint' || amount <= 0n) {
+            throw new TypeError('amount must be a positive bigint');
+        }
+        await this.handleWallet(this.address);
+        const provider = this.getWalletProvider();
+        const data = encodeErc20Transfer(recv, amount);
+        const txHash = await provider.request({
+            method: 'eth_sendTransaction',
+            params: [
+                {
+                    from: this.address,
+                    to: token,
+                    data,
+                },
+            ],
+        });
+        if (typeof txHash !== 'string' || !/^0x[a-fA-F0-9]{64}$/u.test(txHash)) {
+            throw new Error('wallet returned malformed tx hash');
+        }
+        return txHash;
+    }
+    /**
+     * Droplinked checkout contract call. Requires
+     * `checkoutContractAddress` to be supplied at construction time —
+     * we will never fetch it from a remote endpoint.
+     */
+    async payment(data) {
+        const parsed = ChainPaymentSchema.parse(data);
+        if (this.checkoutContractAddress === undefined) {
+            throw new Error('payment() requires checkoutContractAddress to be set; remote address discovery has been removed');
+        }
+        await this.handleWallet(this.address);
+        // We do NOT decode/encode the legacy droplinkedPurchase ABI here —
+        // that surface is feature-frozen and consumers (Next-ShopFront) drive
+        // it via a server-built calldata blob. Surface the lower-level
+        // eth_sendTransaction primitive so callers retain control.
+        void parsed;
+        throw new Error('EVMConnector.payment(): direct ABI encoding intentionally removed. ' +
+            'Use submitRawTransaction() with calldata produced by the droplinked checkout API.');
+    }
+    /**
+     * Submit pre-built calldata produced server-side. The calldata is
+     * NOT trusted blindly — we enforce two boundary checks before
+     * surfacing the transaction to the wallet:
+     *
+     *   1. `to` MUST equal the connector's configured
+     *      `checkoutContractAddress`. Sending arbitrary calldata to an
+     *      arbitrary destination would resurrect the drainer pathway
+     *      that motivated removing the v1.0.1 remote-ABI fetch.
+     *   2. The first 4 bytes of `data` (the function selector) MUST be
+     *      on the explicit allowlist below. Notably the selectors for
+     *      `approve(address,uint256)`, `setApprovalForAll(...)`, NFT
+     *      `safeTransferFrom(...)`, and ERC-20 `permit(...)` are
+     *      rejected — these are the canonical "drainer" entry points
+     *      that a compromised checkout API or consumer-side XSS would
+     *      try to coerce the user into signing.
+     *
+     * Both checks throw `InvalidTransactionError` BEFORE any wallet
+     * prompt appears, so the user is never shown a malicious payload.
+     */
+    async submitRawTransaction(args) {
+        if (this.checkoutContractAddress === undefined) {
+            throw new InvalidTransactionError('submitRawTransaction() requires checkoutContractAddress to be configured on the connector');
+        }
+        const to = EvmAddressSchema.parse(args.to);
+        if (to !== this.checkoutContractAddress.toLowerCase()) {
+            throw new InvalidTransactionError(`submitRawTransaction(): destination ${to} does not match configured checkout contract ${this.checkoutContractAddress}`);
+        }
+        assertCalldataSelectorAllowed(args.data);
+        await this.handleWallet(this.address);
+        const provider = this.getWalletProvider();
+        const params = {
+            from: this.address,
+            to: args.to,
+            data: args.data,
+            value: `0x${args.value.toString(16)}`,
+        };
+        if (args.gasLimit !== undefined) {
+            params['gas'] = `0x${args.gasLimit.toString(16)}`;
+        }
+        const txHash = await provider.request({
+            method: 'eth_sendTransaction',
+            params: [params],
+        });
+        if (typeof txHash !== 'string' || !/^0x[a-fA-F0-9]{64}$/u.test(txHash)) {
+            throw new Error('wallet returned malformed tx hash');
+        }
+        return txHash;
+    }
+}
+/* -------------------------------------------------------------------------- */
+/*  submitRawTransaction calldata-selector allowlist                           */
+/* -------------------------------------------------------------------------- */
+/**
+ * 4-byte function selectors that the droplinked checkout flow is known
+ * to call. Anything else is rejected at the boundary.
+ *
+ *  - `0xa9059cbb` — ERC-20 `transfer(address,uint256)`
+ *      The standard token payment path used by `paymentWithToken`.
+ *  - `0x6a627842` — droplinked legacy checkout `droplinkedPurchase(...)`
+ *      Selector matches the calldata blob produced by the droplinked
+ *      checkout API. Replace if the API rotates to a new function.
+ *  - `0x` (empty data) — native-currency transfer to the checkout
+ *      contract. Allowed because there is no selector to spoof; the
+ *      destination is already pinned by the `to === checkoutContract`
+ *      check.
+ */
+export const SUBMIT_RAW_TX_SELECTOR_ALLOWLIST = new Set([
+    '0xa9059cbb',
+    '0x6a627842',
+]);
+/**
+ * Drainer selectors callers will sometimes ask the wallet to sign.
+ * Listed explicitly so the rejection message names them — when one of
+ * these appears in calldata, that is *strong* evidence that the
+ * checkout API or the consumer page is compromised.
+ */
+export const KNOWN_DRAINER_SELECTORS = {
+    '0x095ea7b3': 'approve(address,uint256)',
+    '0xa22cb465': 'setApprovalForAll(address,bool)',
+    '0x42842e0e': 'safeTransferFrom(address,address,uint256) (NFT)',
+    '0xb88d4fde': 'safeTransferFrom(address,address,uint256,bytes) (NFT)',
+    '0x23b872dd': 'transferFrom(address,address,uint256)',
+    '0xd505accf': 'permit(address,address,uint256,uint256,uint8,bytes32,bytes32)',
+};
+function assertCalldataSelectorAllowed(data) {
+    if (typeof data !== 'string' || !/^0x[a-fA-F0-9]*$/u.test(data)) {
+        throw new InvalidTransactionError('submitRawTransaction(): data must be a 0x-prefixed hex string');
+    }
+    // Native-currency transfer (empty data) is allowed — destination is
+    // already pinned to the checkout contract.
+    if (data === '0x' || data.length === 2) {
+        return;
+    }
+    if (data.length < 10) {
+        throw new InvalidTransactionError(`submitRawTransaction(): calldata too short to contain a 4-byte selector (got ${data.length - 2} hex chars)`);
+    }
+    const selector = data.slice(0, 10).toLowerCase();
+    const drainer = KNOWN_DRAINER_SELECTORS[selector];
+    if (drainer !== undefined) {
+        throw new InvalidTransactionError(`submitRawTransaction(): refused drainer-style selector ${selector} (${drainer})`);
+    }
+    if (!SUBMIT_RAW_TX_SELECTOR_ALLOWLIST.has(selector)) {
+        throw new InvalidTransactionError(`submitRawTransaction(): selector ${selector} is not on the allowlist`);
+    }
+}
+function resolveOrigin() {
+    const g = globalThis;
+    return g.location?.origin ?? 'https://droplinked.com';
+}
+/* -------------------------------------------------------------------------- */
+/*  Internal: hand-written ERC-20 transfer encoder                             */
+/* -------------------------------------------------------------------------- */
+/** Returns the calldata blob for `transfer(address,uint256)`. */
+export function encodeErc20Transfer(to, amount) {
+    if (typeof amount !== 'bigint' || amount < 0n) {
+        throw new TypeError('amount must be a non-negative bigint');
+    }
+    // keccak256('transfer(address,uint256)').slice(0,4) = 0xa9059cbb
+    const selector = 'a9059cbb';
+    const addressPart = to.toLowerCase().replace(/^0x/u, '').padStart(64, '0');
+    const amountPart = amount.toString(16).padStart(64, '0');
+    return `0x${selector}${addressPart}${amountPart}`;
+}
+// Re-export the ABI fragment for callers that want to introspect.
+export { ERC20_TRANSFER_ABI };
+//# sourceMappingURL=evm.js.map

package/dist/connectors/evm.js.map

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

package/dist/connectors/phantom.d.ts

@@ -0,0 +1,167 @@
+/**
+ * Phantom (Solana) connector.
+ *
+ * Hardening deltas vs. v1.0.1:
+ *   1. No `window.open('https://phantom.app/', '_blank')` redirect — the
+ *      original silently popped a new tab when Phantom was missing, which
+ *      is a phishing-friendly UX. We throw a typed error and let the host
+ *      app decide what to render.
+ *   2. No `while(true) { sleep; getParsedTransaction }` busy-loop — the
+ *      original could hang a tab forever if the network stalled. We
+ *      surface the unsigned-transaction hash and let the caller poll.
+ *   3. No `console.log(error); throw error` — errors propagate without
+ *      leaking through stdout.
+ *   4. Signature buffer is returned as base64 rather than the raw
+ *      Uint8Array — same format as MetaMask EIP-712 output so server
+ *      verification is uniform.
+ *   5. Login signs a SIWS-style (Sign-In With Solana, https://siws.xyz/)
+ *      JSON payload with domain, nonce, chainId, issuedAt,
+ *      expirationTime — NOT a static plaintext. The signature is
+ *      bound to origin + chain + time and cannot be replayed across
+ *      sites or sessions. Verification is provided alongside.
+ */
+import { z } from 'zod';
+import { Chain, ChainWallet, Network, type ChainProvider, type IChainPayment } from '../types.js';
+/**
+ * Default human-readable statement embedded in the signed payload so
+ * Phantom's prompt explains *why* the user is signing.
+ */
+export declare const DEFAULT_SOLANA_LOGIN_STATEMENT = "Sign in to droplinked. This signature does not authorize any token transfer.";
+/** Allowed Solana chain identifiers; `chain` is bound into the payload. */
+export declare const SOLANA_CHAIN_IDS: readonly ["solana-mainnet", "solana-devnet", "solana-testnet"];
+export type SolanaChainId = (typeof SOLANA_CHAIN_IDS)[number];
+/** Hard upper bound on payload TTL — refused at build time. */
+export declare const SOLANA_LOGIN_MAX_TTL_SECONDS: number;
+/** Default TTL when caller does not specify one. */
+export declare const SOLANA_LOGIN_DEFAULT_TTL_SECONDS: number;
+export declare const SolanaLoginPayloadSchema: z.ZodObject<{
+    domain: z.ZodString;
+    address: z.ZodString;
+    chain: z.ZodEnum<["solana-mainnet", "solana-devnet", "solana-testnet"]>;
+    nonce: z.ZodString;
+    issuedAt: z.ZodString;
+    expirationTime: z.ZodString;
+    statement: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    domain: string;
+    address: string;
+    statement: string;
+    nonce: string;
+    issuedAt: string;
+    expirationTime: string;
+    chain: "solana-mainnet" | "solana-devnet" | "solana-testnet";
+}, {
+    domain: string;
+    address: string;
+    statement: string;
+    nonce: string;
+    issuedAt: string;
+    expirationTime: string;
+    chain: "solana-mainnet" | "solana-devnet" | "solana-testnet";
+}>;
+export type SolanaLoginPayload = z.infer<typeof SolanaLoginPayloadSchema>;
+export interface BuildSolanaLoginPayloadArgs {
+    readonly address: string;
+    readonly chain: SolanaChainId;
+    readonly origin: string;
+    readonly statement?: string;
+    readonly expiresInSeconds?: number;
+}
+/**
+ * Build a SIWS-style login payload binding the signature to
+ * (domain, chain, nonce, issuedAt, expirationTime). Refuses any TTL
+ * over `SOLANA_LOGIN_MAX_TTL_SECONDS`.
+ */
+export declare function buildSolanaLoginPayload(args: BuildSolanaLoginPayloadArgs): SolanaLoginPayload;
+/**
+ * Canonicalize the payload to a deterministic JSON string with sorted
+ * keys. This is what gets signed — same string on both sides of the
+ * verification boundary.
+ */
+export declare function canonicalizeSolanaLoginPayload(payload: SolanaLoginPayload): string;
+/** Decode a base58-encoded string into bytes. Throws on invalid input. */
+export declare function base58Decode(input: string): Uint8Array;
+export interface VerifySolanaLoginArgs {
+    readonly payload: SolanaLoginPayload;
+    /** base64-encoded ed25519 signature returned by `walletLogin()`. */
+    readonly signature: string;
+    readonly expectedAddress: string;
+    readonly expectedChain: SolanaChainId;
+    readonly expectedOrigin: string;
+    readonly nowMs?: number;
+}
+/**
+ * Verify a Phantom (Solana) SIWS-style login signature.
+ *
+ * Checks (in order):
+ *   1. Payload shape validates against `SolanaLoginPayloadSchema`.
+ *   2. `payload.chain === expectedChain` (cross-network replay refused).
+ *   3. `payload.domain === host(expectedOrigin)` (origin-spoofing refused).
+ *   4. `payload.address === expectedAddress`.
+ *   5. `now < expirationTime` AND `issuedAt <= now` (freshness).
+ *   6. The base64 signature is a valid ed25519 signature over
+ *      `utf8(canonicalizeSolanaLoginPayload(payload))` for the public
+ *      key derived from `expectedAddress` (base58-decoded).
+ *
+ * Note: nonce replay tracking is the responsibility of the server-side
+ * caller — this function does not maintain a seen-nonces store. The
+ * canonical pattern is to record `(payload.nonce, payload.address)`
+ * in a short-lived store keyed by `expirationTime` and reject any
+ * second presentation.
+ */
+export declare function verifySolanaLoginSignature(args: VerifySolanaLoginArgs): Promise<void>;
+export interface PhantomConnectorOptions {
+    readonly network: Network;
+    /** Origin to bind into the login payload. Defaults to globalThis.location.origin. */
+    readonly origin?: string;
+    /**
+     * Solana chain identifier to bind into the login payload. Defaults
+     * to `solana-mainnet` on Network.MAINNET and `solana-devnet` on
+     * Network.TESTNET.
+     */
+    readonly chainId?: SolanaChainId;
+}
+export declare class PhantomConnector implements ChainProvider {
+    readonly chain: Chain;
+    readonly network: Network;
+    address: string;
+    wallet: ChainWallet;
+    private readonly origin;
+    private readonly chainId;
+    constructor(networkOrOptions: Network | PhantomConnectorOptions);
+    setAddress(address: string): this;
+    setWallet(wallet: ChainWallet): this;
+    /**
+     * Connect + SIWS-style typed login. Builds a fresh payload with a
+     * 256-bit nonce, binds it to origin + chain + time, asks Phantom to
+     * sign the canonicalized JSON, and returns the payload alongside the
+     * base64 signature. Server-side verification uses
+     * `verifySolanaLoginSignature`.
+     *
+     * Replaces the v1.0.1 / pre-audit static-plaintext signMessage path,
+     * which was replayable across origins, chains, and sessions.
+     */
+    walletLogin(): Promise<{
+        address: string;
+        signature: string;
+        payload: SolanaLoginPayload;
+    }>;
+    /**
+     * SPL token transfer is intentionally not implemented in this minimal
+     * recover+harden. The original v1.0.1 relied on the long-deprecated
+     * `@solana/spl-token` v0.1.x Token-class API (removed in v0.2). Re-
+     * implementing it correctly against the current `@solana/spl-token` v0.4
+     * APIs is out of scope for the first PR; it will land in a follow-up.
+     *
+     * The method throws a typed error so consumers fail loudly rather than
+     * silently mis-routing a transfer.
+     */
+    paymentWithToken(_receiver: string, _amount: bigint, _tokenAddress: string): Promise<string>;
+    payment(_data: IChainPayment): Promise<{
+        deploy_hash: string;
+        cryptoAmount: bigint;
+    }>;
+}
+/** base64-encode a Uint8Array. Browser-safe; no Buffer dependency. */
+export declare function toBase64(bytes: Uint8Array): string;
+//# sourceMappingURL=phantom.d.ts.map

package/dist/connectors/phantom.d.ts.map

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