@meshconnect/uwc-ton-connector 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { NamespacedStorage, type TonConnectStorage } from './namespaced-storage';
+export { isValidBase64 } from './validation';
+export { buildTonTransactionRequest, buildSignDataPayload, executeSignData, unwrapBoc, bocToHash, toFriendlyAddress } from './ton-transaction-utils';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,KAAK,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,SAAS,EACT,iBAAiB,EAClB,MAAM,yBAAyB,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { NamespacedStorage } from './namespaced-storage';
+export { isValidBase64 } from './validation';
+export { buildTonTransactionRequest, buildSignDataPayload, executeSignData, unwrapBoc, bocToHash, toFriendlyAddress } from './ton-transaction-utils';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA0B,MAAM,sBAAsB,CAAA;AAChF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAC5C,OAAO,EACL,0BAA0B,EAC1B,oBAAoB,EACpB,eAAe,EACf,SAAS,EACT,SAAS,EACT,iBAAiB,EAClB,MAAM,yBAAyB,CAAA"}

package/dist/namespaced-storage.d.ts

@@ -0,0 +1,22 @@
+/** Mirrors @tonconnect/sdk IStorage — avoids leaking SDK types in published .d.ts. */
+export interface TonConnectStorage {
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+}
+/**
+ * Prefixed localStorage wrapper required by @tonconnect/sdk.
+ * The SDK requires the dApp to provide storage for persisting connection state across reloads.
+ * Keys are prefixed per wallet (e.g. "tonkeeper:session") to avoid collisions.
+ * Falls back to in-memory Map when localStorage is blocked (Safari ITP in iframes).
+ */
+export declare class NamespacedStorage implements TonConnectStorage {
+    private prefix;
+    private memoryFallback;
+    constructor(prefix: string);
+    setItem(key: string, value: string): Promise<void>;
+    getItem(key: string): Promise<string | null>;
+    removeItem(key: string): Promise<void>;
+    private prefixed;
+}
+//# sourceMappingURL=namespaced-storage.d.ts.map

package/dist/namespaced-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaced-storage.d.ts","sourceRoot":"","sources":["../src/namespaced-storage.ts"],"names":[],"mappings":"AAAA,sFAAsF;AACtF,MAAM,WAAW,iBAAiB;IAChC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC5C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACvC;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,iBAAiB;IAG7C,OAAO,CAAC,MAAM;IAF1B,OAAO,CAAC,cAAc,CAA4B;gBAE9B,MAAM,EAAE,MAAM;IAE5B,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAW5C,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAY5C,OAAO,CAAC,QAAQ;CAGjB"}

package/dist/namespaced-storage.js

@@ -0,0 +1,52 @@
+/**
+ * Prefixed localStorage wrapper required by @tonconnect/sdk.
+ * The SDK requires the dApp to provide storage for persisting connection state across reloads.
+ * Keys are prefixed per wallet (e.g. "tonkeeper:session") to avoid collisions.
+ * Falls back to in-memory Map when localStorage is blocked (Safari ITP in iframes).
+ */
+export class NamespacedStorage {
+    prefix;
+    memoryFallback = new Map();
+    constructor(prefix) {
+        this.prefix = prefix;
+    }
+    async setItem(key, value) {
+        if (typeof localStorage === 'undefined') {
+            this.memoryFallback.set(this.prefixed(key), value);
+            return;
+        }
+        try {
+            localStorage.setItem(this.prefixed(key), value);
+        }
+        catch {
+            this.memoryFallback.set(this.prefixed(key), value);
+        }
+    }
+    async getItem(key) {
+        if (typeof localStorage === 'undefined') {
+            return this.memoryFallback.get(this.prefixed(key)) ?? null;
+        }
+        try {
+            return localStorage.getItem(this.prefixed(key));
+        }
+        catch {
+            return this.memoryFallback.get(this.prefixed(key)) ?? null;
+        }
+    }
+    async removeItem(key) {
+        if (typeof localStorage === 'undefined') {
+            this.memoryFallback.delete(this.prefixed(key));
+            return;
+        }
+        try {
+            localStorage.removeItem(this.prefixed(key));
+        }
+        catch {
+            this.memoryFallback.delete(this.prefixed(key));
+        }
+    }
+    prefixed(key) {
+        return `${this.prefix}:${key}`;
+    }
+}
+//# sourceMappingURL=namespaced-storage.js.map

package/dist/namespaced-storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"namespaced-storage.js","sourceRoot":"","sources":["../src/namespaced-storage.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,OAAO,iBAAiB;IAGR;IAFZ,cAAc,GAAG,IAAI,GAAG,EAAkB,CAAA;IAElD,YAAoB,MAAc;QAAd,WAAM,GAAN,MAAM,CAAQ;IAAG,CAAC;IAEtC,KAAK,CAAC,OAAO,CAAC,GAAW,EAAE,KAAa;QACtC,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;YACxC,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAA;YAClD,OAAM;QACR,CAAC;QACD,IAAI,CAAC;YACH,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAA;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,CAAA;QACpD,CAAC;IACH,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,GAAW;QACvB,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;YACxC,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAA;QAC5D,CAAC;QACD,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAA;QAC5D,CAAC;IACH,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAW;QAC1B,IAAI,OAAO,YAAY,KAAK,WAAW,EAAE,CAAC;YACxC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;YAC9C,OAAM;QACR,CAAC;QACD,IAAI,CAAC;YACH,YAAY,CAAC,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QAC7C,CAAC;QAAC,MAAM,CAAC;YACP,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QAChD,CAAC;IACH,CAAC;IAEO,QAAQ,CAAC,GAAW;QAC1B,OAAO,GAAG,IAAI,CAAC,MAAM,IAAI,GAAG,EAAE,CAAA;IAChC,CAAC;CACF"}

package/dist/ton-transaction-utils.d.ts

@@ -0,0 +1,81 @@
+import type { TonNativeTransferRequest, TonSignDataPayload, SignatureType } from '@meshconnect/uwc-types';
+/** Mirrors @tonconnect/sdk SendTransactionRequest. */
+interface TonConnectTransactionRequest {
+    validUntil: number;
+    network?: string;
+    from?: string;
+    messages: {
+        address: string;
+        amount: string;
+        stateInit?: string;
+        payload?: string;
+    }[];
+}
+/** Mirrors @tonconnect/sdk SignDataResponse. Not all wallets support SignData (e.g. OKX). */
+interface SignDataResult {
+    signature: string;
+    address: string;
+    timestamp: number;
+    domain: string;
+    payload: string;
+}
+/**
+ * Convert raw TON address to user-friendly format.
+ * TON has two formats:
+ *   Raw:           "0:6e7ee4a1b2c3d4..."   (workchain:hex, used by the SDK)
+ *   User-friendly: "UQBx7kobs..."           (base64url, used in UIs and explorers)
+ */
+export declare function toFriendlyAddress(rawAddress: string, converter: (rawWorkchainAddress: string) => string): string;
+/**
+ * Build a single TON message from a transfer request.
+ * Example: { address: "UQCy9m...", amount: "500000000", payload: "te6cckEBAQ..." }
+ *
+ * - `amount` is in nanotons as a decimal string (1 TON = 1_000_000_000)
+ * - `payload` is a base64-encoded BOC (Bag of Cells) — for Jetton transfers, on-chain comments, etc.
+ * - `stateInit` is a base64 BOC that deploys a smart contract alongside the transfer
+ */
+export declare function buildTonTransactionMessage(request: TonNativeTransferRequest): {
+    stateInit?: string;
+    payload?: string;
+    address: string;
+    amount: string;
+};
+/**
+ * Transform a UWC transfer request into @tonconnect/sdk's SendTransactionRequest.
+ *
+ * @param senderRawAddress - Raw 0:hex address from sdk.account.address.
+ *   The SDK expects `from` in raw format; the UI's user-friendly address (UQ...) is a fallback only.
+ *
+ * `validUntil` defaults to now + 5 min (TX_EXPIRY_SECONDS). TON transactions require an expiry.
+ * `sendMode` — bit flags for message handling (e.g. 128 = send entire balance).
+ * See: https://docs.ton.org/v3/documentation/smart-contracts/message-management/message-modes-cookbook
+ */
+export declare function buildTonTransactionRequest(request: TonNativeTransferRequest, senderRawAddress?: string): TonConnectTransactionRequest & {
+    sendMode?: number;
+};
+export declare function buildSignDataPayload(message: string, override?: TonSignDataPayload): TonSignDataPayload;
+/**
+ * Execute signData on the SDK, normalizing errors for wallets that don't support it.
+ * OKX and some other wallets do not implement SignData — this gives a clear error message.
+ */
+export declare function executeSignData(sdk: {
+    signData?: (payload: TonSignDataPayload) => Promise<SignDataResult>;
+}, payload: TonSignDataPayload): Promise<SignatureType>;
+/**
+ * Extract BOC (Bag of Cells) string from wallet response.
+ * TON wallets return the serialized signed transaction as base64, not a tx hash.
+ * Some wallets return a plain string, others wrap it in { boc: "..." } — handle both.
+ */
+export declare function unwrapBoc(result: string | {
+    boc: string;
+} | null | undefined): string;
+/**
+ * Convert a base64 BOC to a hex transaction hash for use in explorers.
+ *
+ * @ton/core (268 KB JS, CJS — no tree-shaking) is lazy-loaded via dynamic import.
+ * Impact: 0 KB for non-TON users, ~22ms cold load + <1ms hash on first TON transaction.
+ * Subsequent calls: <0.1ms (module cached by runtime).
+ */
+export declare function bocToHash(boc: string): Promise<string>;
+export {};
+//# sourceMappingURL=ton-transaction-utils.d.ts.map

package/dist/ton-transaction-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ton-transaction-utils.d.ts","sourceRoot":"","sources":["../src/ton-transaction-utils.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,wBAAwB,EACxB,kBAAkB,EAClB,aAAa,EACd,MAAM,wBAAwB,CAAA;AAa/B,sDAAsD;AACtD,UAAU,4BAA4B;IACpC,UAAU,EAAE,MAAM,CAAA;IAClB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE;QACR,OAAO,EAAE,MAAM,CAAA;QACf,MAAM,EAAE,MAAM,CAAA;QACd,SAAS,CAAC,EAAE,MAAM,CAAA;QAClB,OAAO,CAAC,EAAE,MAAM,CAAA;KACjB,EAAE,CAAA;CACJ;AAED,6FAA6F;AAC7F,UAAU,cAAc;IACtB,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,CAAC,mBAAmB,EAAE,MAAM,KAAK,MAAM,GACjD,MAAM,CAKR;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,wBAAwB;;;;;EAkB3E;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,wBAAwB,EACjC,gBAAgB,CAAC,EAAE,MAAM,GACxB,4BAA4B,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAatD;AAED,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,MAAM,EACf,QAAQ,CAAC,EAAE,kBAAkB,GAC5B,kBAAkB,CAEpB;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE;IAAE,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,cAAc,CAAC,CAAA;CAAE,EAC5E,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,aAAa,CAAC,CA4BxB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,GAAG;IAAE,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,GAClD,MAAM,CASR;AAED;;;;;;GAMG;AACH,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAI5D"}

package/dist/ton-transaction-utils.js

@@ -0,0 +1,120 @@
+import { TON_MAINNET_CHAIN_ID } from '@meshconnect/uwc-constants';
+import { isValidBase64 } from './validation';
+/** Default transaction expiry window in seconds. TON transactions must include an expiry timestamp. */
+const TX_EXPIRY_SECONDS = 300;
+/**
+ * Convert raw TON address to user-friendly format.
+ * TON has two formats:
+ *   Raw:           "0:6e7ee4a1b2c3d4..."   (workchain:hex, used by the SDK)
+ *   User-friendly: "UQBx7kobs..."           (base64url, used in UIs and explorers)
+ */
+export function toFriendlyAddress(rawAddress, converter) {
+    if (rawAddress.includes(':')) {
+        return converter(rawAddress);
+    }
+    return rawAddress;
+}
+/**
+ * Build a single TON message from a transfer request.
+ * Example: { address: "UQCy9m...", amount: "500000000", payload: "te6cckEBAQ..." }
+ *
+ * - `amount` is in nanotons as a decimal string (1 TON = 1_000_000_000)
+ * - `payload` is a base64-encoded BOC (Bag of Cells) — for Jetton transfers, on-chain comments, etc.
+ * - `stateInit` is a base64 BOC that deploys a smart contract alongside the transfer
+ */
+export function buildTonTransactionMessage(request) {
+    if (request.payload && !isValidBase64(request.payload)) {
+        throw new Error('payload must be a base64-encoded BOC. If you want to include a text comment, ' +
+            'encode it as a Cell first using @ton/core.');
+    }
+    if (request.stateInit && !isValidBase64(request.stateInit)) {
+        throw new Error('stateInit must be a base64-encoded BOC.');
+    }
+    return {
+        address: request.to,
+        amount: request.amount,
+        ...(request.payload && { payload: request.payload }),
+        ...(request.stateInit && { stateInit: request.stateInit })
+    };
+}
+/**
+ * Transform a UWC transfer request into @tonconnect/sdk's SendTransactionRequest.
+ *
+ * @param senderRawAddress - Raw 0:hex address from sdk.account.address.
+ *   The SDK expects `from` in raw format; the UI's user-friendly address (UQ...) is a fallback only.
+ *
+ * `validUntil` defaults to now + 5 min (TX_EXPIRY_SECONDS). TON transactions require an expiry.
+ * `sendMode` — bit flags for message handling (e.g. 128 = send entire balance).
+ * See: https://docs.ton.org/v3/documentation/smart-contracts/message-management/message-modes-cookbook
+ */
+export function buildTonTransactionRequest(request, senderRawAddress) {
+    const message = buildTonTransactionMessage(request);
+    const txRequest = {
+        validUntil: request.validUntil ?? Math.floor(Date.now() / 1000) + TX_EXPIRY_SECONDS,
+        network: TON_MAINNET_CHAIN_ID,
+        from: senderRawAddress ?? request.from,
+        messages: [message]
+    };
+    if (request.sendMode !== undefined)
+        txRequest.sendMode = request.sendMode;
+    return txRequest;
+}
+export function buildSignDataPayload(message, override) {
+    return override ?? { type: 'text', text: message };
+}
+/**
+ * Execute signData on the SDK, normalizing errors for wallets that don't support it.
+ * OKX and some other wallets do not implement SignData — this gives a clear error message.
+ */
+export async function executeSignData(sdk, payload) {
+    if (typeof sdk.signData !== 'function') {
+        throw new Error('This wallet does not support message signing via TON Connect.');
+    }
+    let result;
+    try {
+        result = await sdk.signData(payload);
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        if (msg.includes('SignData') || msg.includes('not support')) {
+            throw new Error(`This wallet does not support message signing via TON Connect. ` +
+                `Not all TON wallets implement the SignData feature.`);
+        }
+        throw error;
+    }
+    return {
+        type: 'tvm',
+        signature: result.signature,
+        timestamp: result.timestamp,
+        domain: result.domain,
+        payload
+    };
+}
+/**
+ * Extract BOC (Bag of Cells) string from wallet response.
+ * TON wallets return the serialized signed transaction as base64, not a tx hash.
+ * Some wallets return a plain string, others wrap it in { boc: "..." } — handle both.
+ */
+export function unwrapBoc(result) {
+    if (!result) {
+        throw new Error('Empty transaction result from TON wallet');
+    }
+    const boc = typeof result === 'string' ? result : result.boc;
+    if (!boc) {
+        throw new Error('No BOC in transaction result');
+    }
+    return boc;
+}
+/**
+ * Convert a base64 BOC to a hex transaction hash for use in explorers.
+ *
+ * @ton/core (268 KB JS, CJS — no tree-shaking) is lazy-loaded via dynamic import.
+ * Impact: 0 KB for non-TON users, ~22ms cold load + <1ms hash on first TON transaction.
+ * Subsequent calls: <0.1ms (module cached by runtime).
+ */
+export async function bocToHash(boc) {
+    const { Cell } = await import('@ton/core');
+    const cell = Cell.fromBase64(boc);
+    return cell.hash().toString('hex');
+}
+//# sourceMappingURL=ton-transaction-utils.js.map

package/dist/ton-transaction-utils.js.map

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

package/dist/validation.d.ts

@@ -0,0 +1,2 @@
+export declare function isValidBase64(value: string): boolean;
+//# sourceMappingURL=validation.d.ts.map

package/dist/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AACA,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAEpD"}

package/dist/validation.js

@@ -0,0 +1,5 @@
+const BASE64_REGEX = /^[A-Za-z0-9+/\-_]+={0,2}$/;
+export function isValidBase64(value) {
+    return value.length > 0 && value.length % 4 !== 1 && BASE64_REGEX.test(value);
+}
+//# sourceMappingURL=validation.js.map

package/dist/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAAA,MAAM,YAAY,GAAG,2BAA2B,CAAA;AAChD,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,KAAK,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AAC/E,CAAC"}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@meshconnect/uwc-ton-connector",
+  "version": "0.2.0",
+  "description": "TON Connect connector for Universal Wallet Connector — mobile QR/URI wallet connections",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "dependencies": {
+    "@ton/core": "^0.63.1",
+    "@meshconnect/uwc-constants": "0.5.0",
+    "@meshconnect/uwc-types": "0.7.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "type-check": "tsc --noEmit"
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { NamespacedStorage, type TonConnectStorage } from './namespaced-storage'
+export { isValidBase64 } from './validation'
+export {
+  buildTonTransactionRequest,
+  buildSignDataPayload,
+  executeSignData,
+  unwrapBoc,
+  bocToHash,
+  toFriendlyAddress
+} from './ton-transaction-utils'

package/src/namespaced-storage.test.ts

@@ -0,0 +1,135 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import { NamespacedStorage } from './namespaced-storage'
+
+describe('NamespacedStorage', () => {
+  describe('key prefixing', () => {
+    it('isolates namespaces from each other', async () => {
+      const injected = new NamespacedStorage('uwc-ton-injected')
+      const remote = new NamespacedStorage('uwc-ton-remote')
+
+      await injected.setItem('session', 'injected-data')
+      await remote.setItem('session', 'remote-data')
+
+      expect(await injected.getItem('session')).toBe('injected-data')
+      expect(await remote.getItem('session')).toBe('remote-data')
+    })
+  })
+
+  describe('CRUD operations', () => {
+    it('setItem and getItem round-trip', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'value')
+      expect(await storage.getItem('key')).toBe('value')
+    })
+
+    it('getItem returns null for missing keys', async () => {
+      const storage = new NamespacedStorage('test')
+      expect(await storage.getItem('nonexistent')).toBeNull()
+    })
+
+    it('removeItem deletes the key', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'value')
+      await storage.removeItem('key')
+      expect(await storage.getItem('key')).toBeNull()
+    })
+
+    it('setItem overwrites existing values', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'old')
+      await storage.setItem('key', 'new')
+      expect(await storage.getItem('key')).toBe('new')
+    })
+  })
+
+  describe('localStorage throws (Safari ITP / iframe)', () => {
+    let originalLocalStorage: Storage
+
+    beforeEach(() => {
+      originalLocalStorage = globalThis.localStorage
+      Object.defineProperty(globalThis, 'localStorage', {
+        value: {
+          getItem: () => {
+            throw new DOMException('access denied')
+          },
+          setItem: () => {
+            throw new DOMException('access denied')
+          },
+          removeItem: () => {
+            throw new DOMException('access denied')
+          }
+        },
+        writable: true,
+        configurable: true
+      })
+    })
+
+    afterEach(() => {
+      Object.defineProperty(globalThis, 'localStorage', {
+        value: originalLocalStorage,
+        writable: true,
+        configurable: true
+      })
+    })
+
+    it('falls back to memory on setItem/getItem', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'value')
+      expect(await storage.getItem('key')).toBe('value')
+    })
+
+    it('falls back to memory on removeItem', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'value')
+      await storage.removeItem('key')
+      expect(await storage.getItem('key')).toBeNull()
+    })
+  })
+
+  describe('localStorage undefined (non-browser env)', () => {
+    let originalLocalStorage: Storage
+
+    beforeEach(() => {
+      originalLocalStorage = globalThis.localStorage
+      // @ts-expect-error -- simulating non-browser environment
+      delete globalThis.localStorage
+    })
+
+    afterEach(() => {
+      Object.defineProperty(globalThis, 'localStorage', {
+        value: originalLocalStorage,
+        writable: true,
+        configurable: true
+      })
+    })
+
+    it('setItem and getItem use memory fallback', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'value')
+      expect(await storage.getItem('key')).toBe('value')
+    })
+
+    it('getItem returns null for missing keys', async () => {
+      const storage = new NamespacedStorage('test')
+      expect(await storage.getItem('nope')).toBeNull()
+    })
+
+    it('removeItem deletes from memory', async () => {
+      const storage = new NamespacedStorage('test')
+      await storage.setItem('key', 'value')
+      await storage.removeItem('key')
+      expect(await storage.getItem('key')).toBeNull()
+    })
+
+    it('memory fallback is per-instance (not shared)', async () => {
+      const a = new NamespacedStorage('a')
+      const b = new NamespacedStorage('b')
+
+      await a.setItem('key', 'from-a')
+      await b.setItem('key', 'from-b')
+
+      expect(await a.getItem('key')).toBe('from-a')
+      expect(await b.getItem('key')).toBe('from-b')
+    })
+  })
+})

package/src/namespaced-storage.ts

@@ -0,0 +1,57 @@
+/** Mirrors @tonconnect/sdk IStorage — avoids leaking SDK types in published .d.ts. */
+export interface TonConnectStorage {
+  setItem(key: string, value: string): Promise<void>
+  getItem(key: string): Promise<string | null>
+  removeItem(key: string): Promise<void>
+}
+
+/**
+ * Prefixed localStorage wrapper required by @tonconnect/sdk.
+ * The SDK requires the dApp to provide storage for persisting connection state across reloads.
+ * Keys are prefixed per wallet (e.g. "tonkeeper:session") to avoid collisions.
+ * Falls back to in-memory Map when localStorage is blocked (Safari ITP in iframes).
+ */
+export class NamespacedStorage implements TonConnectStorage {
+  private memoryFallback = new Map<string, string>()
+
+  constructor(private prefix: string) {}
+
+  async setItem(key: string, value: string): Promise<void> {
+    if (typeof localStorage === 'undefined') {
+      this.memoryFallback.set(this.prefixed(key), value)
+      return
+    }
+    try {
+      localStorage.setItem(this.prefixed(key), value)
+    } catch {
+      this.memoryFallback.set(this.prefixed(key), value)
+    }
+  }
+
+  async getItem(key: string): Promise<string | null> {
+    if (typeof localStorage === 'undefined') {
+      return this.memoryFallback.get(this.prefixed(key)) ?? null
+    }
+    try {
+      return localStorage.getItem(this.prefixed(key))
+    } catch {
+      return this.memoryFallback.get(this.prefixed(key)) ?? null
+    }
+  }
+
+  async removeItem(key: string): Promise<void> {
+    if (typeof localStorage === 'undefined') {
+      this.memoryFallback.delete(this.prefixed(key))
+      return
+    }
+    try {
+      localStorage.removeItem(this.prefixed(key))
+    } catch {
+      this.memoryFallback.delete(this.prefixed(key))
+    }
+  }
+
+  private prefixed(key: string): string {
+    return `${this.prefix}:${key}`
+  }
+}

package/src/ton-transaction-utils.test.ts

@@ -0,0 +1,300 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import {
+  buildTonTransactionRequest,
+  buildSignDataPayload,
+  unwrapBoc,
+  bocToHash,
+  executeSignData,
+  toFriendlyAddress
+} from './ton-transaction-utils'
+import { TON_MAINNET_CHAIN_ID } from '@meshconnect/uwc-constants'
+import type {
+  TonNativeTransferRequest,
+  TonSignDataPayload
+} from '@meshconnect/uwc-types'
+
+describe('buildTonTransactionRequest', () => {
+  const baseRequest: TonNativeTransferRequest = {
+    to: 'UQBExample123',
+    amount: '1000000000',
+    from: 'UQBSender456'
+  } as TonNativeTransferRequest
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    vi.setSystemTime(new Date('2026-01-15T12:00:00Z'))
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  it('builds correct transaction structure', () => {
+    const result = buildTonTransactionRequest(baseRequest)
+
+    expect(result.network).toBe(TON_MAINNET_CHAIN_ID)
+    expect(result.from).toBe('UQBSender456')
+    expect(result.messages).toHaveLength(1)
+    expect(result.messages[0].address).toBe('UQBExample123')
+    expect(result.messages[0].amount).toBe('1000000000')
+  })
+
+  it('sets validUntil to now + 300s when not provided', () => {
+    const result = buildTonTransactionRequest(baseRequest)
+    const expectedTs = Math.floor(Date.now() / 1000) + 300
+
+    expect(result.validUntil).toBe(expectedTs)
+  })
+
+  it('uses provided validUntil when specified', () => {
+    const result = buildTonTransactionRequest({
+      ...baseRequest,
+      validUntil: 9999999
+    } as TonNativeTransferRequest)
+
+    expect(result.validUntil).toBe(9999999)
+  })
+
+  it('includes sendMode when provided', () => {
+    const result = buildTonTransactionRequest({
+      ...baseRequest,
+      sendMode: 3
+    } as TonNativeTransferRequest)
+
+    expect(result.sendMode).toBe(3)
+  })
+
+  it('omits sendMode when not provided', () => {
+    const result = buildTonTransactionRequest(baseRequest)
+
+    expect(result).not.toHaveProperty('sendMode')
+  })
+
+  it('overrides from with senderRawAddress when provided', () => {
+    const result = buildTonTransactionRequest(baseRequest, '0:abc123')
+
+    expect(result.from).toBe('0:abc123')
+  })
+
+  it('uses request.from when senderRawAddress is undefined', () => {
+    const result = buildTonTransactionRequest(baseRequest)
+
+    expect(result.from).toBe('UQBSender456')
+  })
+
+  it('includes payload and stateInit in message when valid base64', () => {
+    const result = buildTonTransactionRequest({
+      ...baseRequest,
+      payload: 'dGVzdA==',
+      stateInit: 'AQIDBA=='
+    } as TonNativeTransferRequest)
+
+    expect(result.messages[0].payload).toBe('dGVzdA==')
+    expect(result.messages[0].stateInit).toBe('AQIDBA==')
+  })
+
+  it('throws when payload is not valid base64', () => {
+    expect(() =>
+      buildTonTransactionRequest({
+        ...baseRequest,
+        payload: 'not valid base64!!'
+      } as TonNativeTransferRequest)
+    ).toThrow('payload must be a base64-encoded BOC')
+  })
+
+  it('throws when stateInit is not valid base64', () => {
+    expect(() =>
+      buildTonTransactionRequest({
+        ...baseRequest,
+        stateInit: 'bad data ##'
+      } as TonNativeTransferRequest)
+    ).toThrow('stateInit must be a base64-encoded BOC')
+  })
+})
+
+describe('buildSignDataPayload', () => {
+  it('returns override payload when provided', () => {
+    const override: TonSignDataPayload = { type: 'binary', bytes: 'AQID' }
+    const result = buildSignDataPayload('ignored message', override)
+
+    expect(result).toBe(override)
+  })
+
+  it('builds text payload when no override provided', () => {
+    const result = buildSignDataPayload('Please sign this')
+
+    expect(result).toEqual({ type: 'text', text: 'Please sign this' })
+  })
+
+  it('returns cell override as-is', () => {
+    const override: TonSignDataPayload = {
+      type: 'cell',
+      schema: 'some-schema',
+      cell: 'AQID'
+    }
+    const result = buildSignDataPayload('msg', override)
+
+    expect(result).toBe(override)
+  })
+})
+
+describe('unwrapBoc', () => {
+  it('returns string directly when result is a string', () => {
+    expect(unwrapBoc('te6cckEBAQ==')).toBe('te6cckEBAQ==')
+  })
+
+  it('extracts boc property when result is an object', () => {
+    expect(unwrapBoc({ boc: 'te6cckEBAQ==' })).toBe('te6cckEBAQ==')
+  })
+
+  it('throws on null result', () => {
+    expect(() => unwrapBoc(null)).toThrow(
+      'Empty transaction result from TON wallet'
+    )
+  })
+
+  it('throws on undefined result', () => {
+    expect(() => unwrapBoc(undefined)).toThrow(
+      'Empty transaction result from TON wallet'
+    )
+  })
+
+  it('throws on object without boc property', () => {
+    expect(() => unwrapBoc({ hash: 'abc' })).toThrow(
+      'No BOC in transaction result'
+    )
+  })
+
+  it('throws on empty string', () => {
+    expect(() => unwrapBoc('')).toThrow(
+      'Empty transaction result from TON wallet'
+    )
+  })
+})
+
+describe('bocToHash', () => {
+  // BOC for: beginCell().storeUint(0, 32).storeStringTail('test').endCell()
+  const testBoc = 'te6cckEBAQEACgAAEAAAAAB0ZXN0cbBecQ=='
+  const expectedHash =
+    'f9b941877628a233a719e129140e93df1eeb5a65aeea5fbd16fb0b9af4004c94'
+
+  it('computes deterministic hash from a valid BOC', async () => {
+    expect(await bocToHash(testBoc)).toBe(expectedHash)
+  })
+
+  it('returns the same hash for the same BOC', async () => {
+    expect(await bocToHash(testBoc)).toBe(await bocToHash(testBoc))
+  })
+
+  it('throws on invalid base64', async () => {
+    await expect(bocToHash('not-valid-boc')).rejects.toThrow()
+  })
+})
+
+describe('toFriendlyAddress', () => {
+  const mockConverter = (hex: string) => 'UQ' + hex.replace('0:', '')
+
+  it('converts raw 0:hex address using converter', () => {
+    expect(toFriendlyAddress('0:abc123', mockConverter)).toBe('UQabc123')
+  })
+
+  it('returns already-friendly address as-is', () => {
+    expect(toFriendlyAddress('UQBExample123', mockConverter)).toBe(
+      'UQBExample123'
+    )
+  })
+
+  it('returns EQ addresses as-is', () => {
+    expect(toFriendlyAddress('EQBExample456', mockConverter)).toBe(
+      'EQBExample456'
+    )
+  })
+
+  it('returns empty string as-is (no colon)', () => {
+    expect(toFriendlyAddress('', mockConverter)).toBe('')
+  })
+
+  it('converts address with 0: prefix but no hex body', () => {
+    expect(toFriendlyAddress('0:', mockConverter)).toBe('UQ')
+  })
+
+  it('handles -1: workchain prefix', () => {
+    const converter = (raw: string) => 'EQ' + raw.split(':')[1]
+    expect(toFriendlyAddress('-1:abcdef', converter)).toBe('EQabcdef')
+  })
+})
+
+describe('executeSignData', () => {
+  it('throws early when signData is not a function', async () => {
+    const sdk = {} as { signData?: undefined }
+    const payload: TonSignDataPayload = { type: 'text', text: 'hello' }
+
+    await expect(executeSignData(sdk, payload)).rejects.toThrow(
+      'This wallet does not support message signing via TON Connect'
+    )
+  })
+
+  it('returns signature result on success', async () => {
+    const mockResult = {
+      signature: 'abc123',
+      timestamp: 1700000000,
+      domain: 'example.com'
+    }
+    const sdk = { signData: vi.fn().mockResolvedValue(mockResult) }
+    const payload: TonSignDataPayload = { type: 'text', text: 'hello' }
+
+    const result = await executeSignData(sdk, payload)
+
+    expect(result.type).toBe('tvm')
+    expect(result.signature).toBe('abc123')
+    expect(result.timestamp).toBe(1700000000)
+    expect(result.domain).toBe('example.com')
+    expect(result.payload).toBe(payload)
+  })
+
+  it('wraps error with user-friendly message when wallet does not support SignData', async () => {
+    const sdk = {
+      signData: vi
+        .fn()
+        .mockRejectedValue(new Error('SignData method not available'))
+    }
+    const payload: TonSignDataPayload = { type: 'text', text: 'hello' }
+
+    await expect(executeSignData(sdk, payload)).rejects.toThrow(
+      'This wallet does not support message signing via TON Connect'
+    )
+  })
+
+  it('wraps error when message contains "not support"', async () => {
+    const sdk = {
+      signData: vi.fn().mockRejectedValue(new Error('Feature not supported'))
+    }
+    const payload: TonSignDataPayload = { type: 'text', text: 'hello' }
+
+    await expect(executeSignData(sdk, payload)).rejects.toThrow(
+      'This wallet does not support message signing via TON Connect'
+    )
+  })
+
+  it('re-throws unrelated errors unchanged', async () => {
+    const sdk = {
+      signData: vi.fn().mockRejectedValue(new Error('Network timeout'))
+    }
+    const payload: TonSignDataPayload = { type: 'text', text: 'hello' }
+
+    await expect(executeSignData(sdk, payload)).rejects.toThrow(
+      'Network timeout'
+    )
+  })
+
+  it('handles non-Error thrown values in the SignData path', async () => {
+    const sdk = {
+      signData: vi.fn().mockRejectedValue('not support this')
+    }
+    const payload: TonSignDataPayload = { type: 'text', text: 'hello' }
+
+    await expect(executeSignData(sdk, payload)).rejects.toThrow(
+      'This wallet does not support message signing via TON Connect'
+    )
+  })
+})

package/src/ton-transaction-utils.ts

@@ -0,0 +1,185 @@
+import type {
+  TonNativeTransferRequest,
+  TonSignDataPayload,
+  SignatureType
+} from '@meshconnect/uwc-types'
+import { TON_MAINNET_CHAIN_ID } from '@meshconnect/uwc-constants'
+import { isValidBase64 } from './validation'
+
+/** Default transaction expiry window in seconds. TON transactions must include an expiry timestamp. */
+const TX_EXPIRY_SECONDS = 300
+
+/*
+ * Local mirrors of @tonconnect/sdk types.
+ * Defined here so ton-connector has zero runtime dependency on @tonconnect/sdk,
+ * avoiding type leaks in the published .d.ts files.
+ */
+
+/** Mirrors @tonconnect/sdk SendTransactionRequest. */
+interface TonConnectTransactionRequest {
+  validUntil: number
+  network?: string
+  from?: string
+  messages: {
+    address: string
+    amount: string
+    stateInit?: string
+    payload?: string
+  }[]
+}
+
+/** Mirrors @tonconnect/sdk SignDataResponse. Not all wallets support SignData (e.g. OKX). */
+interface SignDataResult {
+  signature: string
+  address: string
+  timestamp: number
+  domain: string
+  payload: string
+}
+
+/**
+ * Convert raw TON address to user-friendly format.
+ * TON has two formats:
+ *   Raw:           "0:6e7ee4a1b2c3d4..."   (workchain:hex, used by the SDK)
+ *   User-friendly: "UQBx7kobs..."           (base64url, used in UIs and explorers)
+ */
+export function toFriendlyAddress(
+  rawAddress: string,
+  converter: (rawWorkchainAddress: string) => string
+): string {
+  if (rawAddress.includes(':')) {
+    return converter(rawAddress)
+  }
+  return rawAddress
+}
+
+/**
+ * Build a single TON message from a transfer request.
+ * Example: { address: "UQCy9m...", amount: "500000000", payload: "te6cckEBAQ..." }
+ *
+ * - `amount` is in nanotons as a decimal string (1 TON = 1_000_000_000)
+ * - `payload` is a base64-encoded BOC (Bag of Cells) — for Jetton transfers, on-chain comments, etc.
+ * - `stateInit` is a base64 BOC that deploys a smart contract alongside the transfer
+ */
+export function buildTonTransactionMessage(request: TonNativeTransferRequest) {
+  if (request.payload && !isValidBase64(request.payload)) {
+    throw new Error(
+      'payload must be a base64-encoded BOC. If you want to include a text comment, ' +
+        'encode it as a Cell first using @ton/core.'
+    )
+  }
+
+  if (request.stateInit && !isValidBase64(request.stateInit)) {
+    throw new Error('stateInit must be a base64-encoded BOC.')
+  }
+
+  return {
+    address: request.to,
+    amount: request.amount,
+    ...(request.payload && { payload: request.payload }),
+    ...(request.stateInit && { stateInit: request.stateInit })
+  }
+}
+
+/**
+ * Transform a UWC transfer request into @tonconnect/sdk's SendTransactionRequest.
+ *
+ * @param senderRawAddress - Raw 0:hex address from sdk.account.address.
+ *   The SDK expects `from` in raw format; the UI's user-friendly address (UQ...) is a fallback only.
+ *
+ * `validUntil` defaults to now + 5 min (TX_EXPIRY_SECONDS). TON transactions require an expiry.
+ * `sendMode` — bit flags for message handling (e.g. 128 = send entire balance).
+ * See: https://docs.ton.org/v3/documentation/smart-contracts/message-management/message-modes-cookbook
+ */
+export function buildTonTransactionRequest(
+  request: TonNativeTransferRequest,
+  senderRawAddress?: string
+): TonConnectTransactionRequest & { sendMode?: number } {
+  const message = buildTonTransactionMessage(request)
+
+  const txRequest: TonConnectTransactionRequest & { sendMode?: number } = {
+    validUntil:
+      request.validUntil ?? Math.floor(Date.now() / 1000) + TX_EXPIRY_SECONDS,
+    network: TON_MAINNET_CHAIN_ID,
+    from: senderRawAddress ?? request.from,
+    messages: [message]
+  }
+  if (request.sendMode !== undefined) txRequest.sendMode = request.sendMode
+
+  return txRequest
+}
+
+export function buildSignDataPayload(
+  message: string,
+  override?: TonSignDataPayload
+): TonSignDataPayload {
+  return override ?? { type: 'text', text: message }
+}
+
+/**
+ * Execute signData on the SDK, normalizing errors for wallets that don't support it.
+ * OKX and some other wallets do not implement SignData — this gives a clear error message.
+ */
+export async function executeSignData(
+  sdk: { signData?: (payload: TonSignDataPayload) => Promise<SignDataResult> },
+  payload: TonSignDataPayload
+): Promise<SignatureType> {
+  if (typeof sdk.signData !== 'function') {
+    throw new Error(
+      'This wallet does not support message signing via TON Connect.'
+    )
+  }
+
+  let result: SignDataResult
+  try {
+    result = await sdk.signData(payload)
+  } catch (error) {
+    const msg = error instanceof Error ? error.message : String(error)
+    if (msg.includes('SignData') || msg.includes('not support')) {
+      throw new Error(
+        `This wallet does not support message signing via TON Connect. ` +
+          `Not all TON wallets implement the SignData feature.`
+      )
+    }
+    throw error
+  }
+
+  return {
+    type: 'tvm',
+    signature: result.signature,
+    timestamp: result.timestamp,
+    domain: result.domain,
+    payload
+  }
+}
+
+/**
+ * Extract BOC (Bag of Cells) string from wallet response.
+ * TON wallets return the serialized signed transaction as base64, not a tx hash.
+ * Some wallets return a plain string, others wrap it in { boc: "..." } — handle both.
+ */
+export function unwrapBoc(
+  result: string | { boc: string } | null | undefined
+): string {
+  if (!result) {
+    throw new Error('Empty transaction result from TON wallet')
+  }
+  const boc = typeof result === 'string' ? result : result.boc
+  if (!boc) {
+    throw new Error('No BOC in transaction result')
+  }
+  return boc
+}
+
+/**
+ * Convert a base64 BOC to a hex transaction hash for use in explorers.
+ *
+ * @ton/core (268 KB JS, CJS — no tree-shaking) is lazy-loaded via dynamic import.
+ * Impact: 0 KB for non-TON users, ~22ms cold load + <1ms hash on first TON transaction.
+ * Subsequent calls: <0.1ms (module cached by runtime).
+ */
+export async function bocToHash(boc: string): Promise<string> {
+  const { Cell } = await import('@ton/core')
+  const cell = Cell.fromBase64(boc)
+  return cell.hash().toString('hex')
+}

package/src/validation.test.ts

@@ -0,0 +1,51 @@
+import { describe, it, expect } from 'vitest'
+import { isValidBase64 } from './validation'
+
+describe('isValidBase64', () => {
+  it('accepts standard base64 strings', () => {
+    expect(isValidBase64('SGVsbG8gV29ybGQ=')).toBe(true)
+    expect(isValidBase64('dGVzdA==')).toBe(true)
+    expect(isValidBase64('AQIDBA==')).toBe(true)
+  })
+
+  it('accepts URL-safe base64 strings (- and _ chars)', () => {
+    expect(isValidBase64('abc-def_ghi')).toBe(true)
+    expect(isValidBase64('A-B_CD')).toBe(true)
+  })
+
+  it('accepts base64 without padding', () => {
+    expect(isValidBase64('SGVsbG8')).toBe(true)
+    expect(isValidBase64('YQ')).toBe(true)
+  })
+
+  it('accepts base64 with single pad character', () => {
+    expect(isValidBase64('YWI=')).toBe(true)
+  })
+
+  it('accepts base64 with double pad characters', () => {
+    expect(isValidBase64('YQ==')).toBe(true)
+  })
+
+  it('returns false for empty string', () => {
+    expect(isValidBase64('')).toBe(false)
+  })
+
+  it('returns false for strings with invalid characters', () => {
+    expect(isValidBase64('hello world')).toBe(false) // space
+    expect(isValidBase64('abc!def')).toBe(false) // exclamation
+    expect(isValidBase64('test@#$')).toBe(false) // special chars
+    expect(isValidBase64('data:image/png;base64,abc')).toBe(false) // colon, semicolon, comma
+  })
+
+  it('returns false for strings with padding in wrong position', () => {
+    expect(isValidBase64('=abc')).toBe(false)
+    expect(isValidBase64('a=bc')).toBe(false)
+    expect(isValidBase64('===abc')).toBe(false)
+  })
+
+  it('rejects strings where length % 4 === 1 (undecodable)', () => {
+    expect(isValidBase64('A')).toBe(false)
+    expect(isValidBase64('0')).toBe(false)
+    expect(isValidBase64('ABCDE')).toBe(false)
+  })
+})

package/src/validation.ts

@@ -0,0 +1,4 @@
+const BASE64_REGEX = /^[A-Za-z0-9+/\-_]+={0,2}$/
+export function isValidBase64(value: string): boolean {
+  return value.length > 0 && value.length % 4 !== 1 && BASE64_REGEX.test(value)
+}