@tangle-network/blueprint-ui 0.1.2 → 0.3.0

package/src/wallet/detectParentOrigin.ts

@@ -0,0 +1,74 @@
+// Determine which origin to trust as the parent dapp.
+//
+// `document.referrer` is the *initial* embedder — it's set when the iframe is
+// first loaded and survives reloads (though it can be cleared by `referrerpolicy`
+// or by the embedder). The Tangle Cloud iframe wrapper deliberately omits
+// `referrerpolicy="no-referrer"` so we get the embedder's origin here.
+//
+// We compare it against an allowlist of known Tangle Cloud origins. If it
+// matches, that's the parent. Otherwise the iframe is being loaded directly
+// (standalone domain visit, dev server, untrusted embedder) and the bridge
+// stays disabled — the app falls back to its normal injected/WC wallet path.
+
+/**
+ * Default Tangle Cloud origins. Consumers (agent-sandbox UI,
+ * trading-arena, future iframe blueprints) pass app-specific additions
+ * via `extraOrigins` rather than mutating this list.
+ */
+export const TANGLE_CLOUD_ORIGINS_DEFAULT = Object.freeze([
+  'https://cloud.tangle.tools',
+  'https://develop.cloud.tangle.tools',
+  // Local dev (Vite default port for tangle-cloud + Netlify dev preview).
+  'http://localhost:4300',
+  'http://localhost:8888',
+] as const);
+
+function originFromReferrer(): string | null {
+  if (typeof document === 'undefined') return null;
+  const ref = document.referrer;
+  if (!ref) return null;
+  try {
+    return new URL(ref).origin;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Returns the parent origin to bridge to, or null when no trusted parent is
+ * detected. Caller should skip installing the bridge connector when this
+ * returns null.
+ *
+ * `extraOrigins` is the application's escape hatch for staging or dev
+ * deploys not covered by the default list. The library deliberately does
+ * not read environment variables itself (consumers may bundle for non-Vite
+ * runtimes); the consuming app threads `import.meta.env.VITE_*` or
+ * `process.env.*` in itself.
+ *
+ * Falls back to a `?parent=<origin>` query parameter when no referrer is
+ * present (some browsers strip referrer from cross-origin loads). Useful
+ * for dev embedding flows.
+ */
+export function detectTangleCloudParentOrigin(
+  options: { extraOrigins?: readonly string[] } = {},
+): string | null {
+  if (typeof window === 'undefined' || window.parent === window) {
+    return null;
+  }
+  const allowlist = new Set<string>([
+    ...TANGLE_CLOUD_ORIGINS_DEFAULT,
+    ...(options.extraOrigins ?? []),
+  ]);
+  const referrerOrigin = originFromReferrer();
+  if (referrerOrigin && allowlist.has(referrerOrigin)) {
+    return referrerOrigin;
+  }
+  try {
+    const url = new URL(window.location.href);
+    const explicit = url.searchParams.get('parent');
+    if (explicit && allowlist.has(explicit)) return explicit;
+  } catch {
+    // ignore
+  }
+  return null;
+}

package/src/wallet/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Tangle Cloud parent-bridge wallet adapter.
+ *
+ * iframe blueprints embedded by the Tangle Cloud dapp can't use the usual
+ * `window.ethereum` connector — browser wallet extensions don't inject into
+ * sandboxed iframes. This module ships a wagmi connector that proxies wallet
+ * operations to the parent dapp through the existing `tangle.app.*`
+ * postMessage protocol, so the iframe inherits the parent's wallet without
+ * its own picker.
+ *
+ * Usage in an iframe app's wagmi config:
+ *
+ *   import {
+ *     detectTangleCloudParentOrigin,
+ *     parentBridgeConnector,
+ *   } from '@tangle-network/blueprint-ui/wallet';
+ *
+ *   const parent = detectTangleCloudParentOrigin();
+ *   const config = createConfig(
+ *     parent !== null
+ *       ? { ...getDefaultConfig({...}), connectors: [
+ *           parentBridgeConnector({ parentOrigin: parent, appId: 'my-app' }),
+ *         ] }
+ *       : getDefaultConfig({...}),
+ *   );
+ *
+ * The bridge is intentionally the ONLY connector when running inside the
+ * dapp — surfacing injected / WalletConnect / Coinbase inside a sandboxed
+ * iframe doesn't work (no popup, no extension injection) and would just
+ * confuse operators.
+ */
+
+export {
+  detectTangleCloudParentOrigin,
+  TANGLE_CLOUD_ORIGINS_DEFAULT,
+} from './detectParentOrigin';
+
+export {
+  parentBridgeConnector,
+  type ParentBridgeConnectorOptions,
+} from './parentBridgeConnector';
+
+export {
+  ParentBridgeProvider,
+  isRunningInIframe,
+  type ParentBridgeOptions,
+} from './parentBridgeProvider';
+
+export {
+  TANGLE_IFRAME_PROTOCOL_PREFIX,
+  TANGLE_IFRAME_PROTOCOL_VERSION,
+  NO_WALLET_ADDRESS,
+  makeCorrelationId,
+  type AccountChanged,
+  type ChainChanged,
+  type HandshakeAck,
+  type HandshakeRequest,
+  type ParentMessage,
+  type ReadAccountRequest,
+  type ReadAccountResult,
+  type SignMessageRequest,
+  type SignMessageResult,
+  type SignTransactionRequest,
+  type SignTransactionResult,
+  type SwitchChainRequest,
+  type SwitchChainResult,
+} from './parentBridgeProtocol';

package/src/wallet/parentBridgeConnector.ts

@@ -0,0 +1,156 @@
+// Wagmi connector that proxies wallet operations to the Tangle Cloud parent
+// dapp via the iframe postMessage bridge. Becomes the autoConnect target
+// when this app is loaded inside an iframe sandbox without a window.ethereum
+// — i.e. always, when embedded by cloud.tangle.tools.
+//
+// Architecture: the connector owns one `ParentBridgeProvider` (singleton),
+// forwards every wagmi method to it, and reflects the provider's EIP-1193
+// events back to wagmi's emitter so the rest of the dapp (ConnectKit's
+// account chip, hooks like useAccount/useChainId) reacts to parent-state
+// changes without polling.
+
+import type { Address, Chain } from 'viem';
+import { createConnector } from 'wagmi';
+
+import { ParentBridgeProvider, type ParentBridgeOptions } from './parentBridgeProvider';
+
+export type ParentBridgeConnectorOptions = ParentBridgeOptions;
+
+export function parentBridgeConnector(options: ParentBridgeConnectorOptions) {
+  let provider: ParentBridgeProvider | undefined;
+  let installed = false;
+
+  return createConnector<ParentBridgeProvider>((config) => {
+    const ensureProvider = (): ParentBridgeProvider => {
+      if (!provider) provider = new ParentBridgeProvider(options);
+      if (!installed) {
+        provider.install();
+        installed = true;
+        // Wire the provider's EIP-1193 events to wagmi's emitter so
+        // ConnectKit and useAccount/useChainId reflect parent-state changes
+        // without polling.
+        provider.on('accountsChanged', (accounts) => {
+          config.emitter.emit('change', {
+            accounts: Array.isArray(accounts)
+              ? (accounts as readonly Address[])
+              : ([] as readonly Address[]),
+          });
+        });
+        provider.on('chainChanged', (chainIdHex) => {
+          const chainId =
+            typeof chainIdHex === 'string'
+              ? Number.parseInt(chainIdHex, 16)
+              : Number(chainIdHex);
+          if (Number.isFinite(chainId)) {
+            config.emitter.emit('change', { chainId });
+          }
+        });
+        provider.on('disconnect', () => {
+          config.emitter.emit('disconnect');
+        });
+      }
+      return provider;
+    };
+
+    return {
+      id: 'tangleParentBridge',
+      name: 'Tangle Cloud',
+      type: 'parentBridge',
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      async connect(): Promise<any> {
+        // wagmi v3's connect() return type is a conditional based on
+        // `withCapabilities`. We always return plain addresses; cast through
+        // `any` rather than re-implementing the type predicate.
+        const p = ensureProvider();
+        const accountsResult = (await p.request({
+          method: 'eth_requestAccounts',
+        })) as readonly Address[];
+        const chainIdHex = (await p.request({ method: 'eth_chainId' })) as string;
+        const chainId = Number.parseInt(chainIdHex, 16);
+        return {
+          accounts: accountsResult,
+          chainId: Number.isFinite(chainId) ? chainId : 0,
+        };
+      },
+
+      async disconnect() {
+        // Disconnect from the iframe's perspective is a local-only state
+        // reset — we can't ask the parent dapp to disconnect its wallet on
+        // our behalf, and a real disconnect should be initiated from the
+        // parent's UI. Tear down listeners + the message bridge so a future
+        // reconnect re-handshakes cleanly.
+        if (provider) provider.uninstall();
+        installed = false;
+        provider = undefined;
+      },
+
+      async getAccounts() {
+        const p = ensureProvider();
+        const cached = p.getCachedAccount();
+        if (cached) return [cached];
+        const accounts = (await p.request({
+          method: 'eth_accounts',
+        })) as readonly Address[];
+        return accounts;
+      },
+
+      async getChainId() {
+        const p = ensureProvider();
+        const cached = p.getCachedChainId();
+        if (cached !== null) return cached;
+        const chainIdHex = (await p.request({ method: 'eth_chainId' })) as string;
+        const chainId = Number.parseInt(chainIdHex, 16);
+        return Number.isFinite(chainId) ? chainId : 0;
+      },
+
+      async getProvider() {
+        return ensureProvider();
+      },
+
+      async isAuthorized() {
+        // Always authorized when in iframe mode — the parent dapp has
+        // already gated access by being the embedder. Returning `true`
+        // makes wagmi auto-reconnect on every page load, which is the
+        // right UX (iframe → parent wallet is always-on).
+        try {
+          const p = ensureProvider();
+          const accounts = (await p.request({
+            method: 'eth_accounts',
+          })) as readonly Address[];
+          return accounts.length > 0;
+        } catch {
+          return false;
+        }
+      },
+
+      async switchChain({ chainId }): Promise<Chain> {
+        const p = ensureProvider();
+        await p.request({
+          method: 'wallet_switchEthereumChain',
+          params: [{ chainId: `0x${chainId.toString(16)}` }],
+        });
+        const chain = config.chains.find((c) => c.id === chainId);
+        if (!chain) {
+          throw new Error(`Chain ${chainId} not configured for this app`);
+        }
+        return chain;
+      },
+
+      onAccountsChanged(accounts) {
+        config.emitter.emit('change', {
+          accounts: accounts as readonly Address[],
+        });
+      },
+      onChainChanged(chainIdHex) {
+        const chainId = Number.parseInt(chainIdHex, 16);
+        if (Number.isFinite(chainId)) {
+          config.emitter.emit('change', { chainId });
+        }
+      },
+      onDisconnect() {
+        config.emitter.emit('disconnect');
+      },
+    };
+  });
+}

package/src/wallet/parentBridgeProtocol.ts

@@ -0,0 +1,109 @@
+// Tangle Cloud iframe ↔ parent dapp protocol — must mirror the parent's
+// spec at `apps/tangle-cloud/src/blueprintApps/iframe/protocol.ts`. Bump the
+// version constant in lockstep when either side adds a request kind.
+
+import type { Address, Hex } from 'viem';
+
+export const TANGLE_IFRAME_PROTOCOL_VERSION = '1' as const;
+export const TANGLE_IFRAME_PROTOCOL_PREFIX = 'tangle.app.';
+
+// ─── Iframe → Parent requests ────────────────────────────────────────────────
+
+export type HandshakeRequest = {
+  kind: 'tangle.app.handshake';
+  appId: string;
+  version: typeof TANGLE_IFRAME_PROTOCOL_VERSION;
+};
+
+export type ReadAccountRequest = {
+  kind: 'tangle.app.readAccount';
+  correlationId: string;
+};
+
+export type SwitchChainRequest = {
+  kind: 'tangle.app.switchChain';
+  correlationId: string;
+  chainId: number;
+};
+
+export type SignMessageRequest = {
+  kind: 'tangle.app.signMessage';
+  correlationId: string;
+  chainId: number;
+  message: string;
+};
+
+export type SignTransactionRequest = {
+  kind: 'tangle.app.signTransaction';
+  correlationId: string;
+  chainId: number;
+  to: Address;
+  data: Hex;
+  value?: string;
+};
+
+// ─── Parent → Iframe messages ────────────────────────────────────────────────
+
+export type HandshakeAck = {
+  kind: 'tangle.app.handshakeAck';
+  appId: string;
+  protocolVersion: typeof TANGLE_IFRAME_PROTOCOL_VERSION;
+};
+
+export type ResultEnvelope<T> = { correlationId: string } & (
+  | { ok: true; data: T }
+  | { ok: false; error: string }
+);
+
+export type ReadAccountResult = {
+  kind: 'tangle.app.readAccountResult';
+} & ResultEnvelope<{ account: Address; chainId: number }>;
+
+export type SwitchChainResult = {
+  kind: 'tangle.app.switchChainResult';
+} & ResultEnvelope<{ chainId: number }>;
+
+export type SignMessageResult = {
+  kind: 'tangle.app.signMessageResult';
+} & ResultEnvelope<{ signature: Hex }>;
+
+export type SignTransactionResult = {
+  kind: 'tangle.app.signTransactionResult';
+} & ResultEnvelope<{ txHash: Hex }>;
+
+export type AccountChanged = {
+  kind: 'tangle.app.accountChanged';
+  account: Address | null;
+};
+
+export type ChainChanged = {
+  kind: 'tangle.app.chainChanged';
+  chainId: number;
+};
+
+export type ParentMessage =
+  | HandshakeAck
+  | ReadAccountResult
+  | SwitchChainResult
+  | SignMessageResult
+  | SignTransactionResult
+  | AccountChanged
+  | ChainChanged;
+
+// The zero address used by the parent when no wallet is connected. The parent
+// always responds to readAccount with an address; this sentinel means "no
+// wallet" without making the response type a union of result shapes.
+export const NO_WALLET_ADDRESS = '0x0000000000000000000000000000000000000000';
+
+/**
+ * Cryptographically-random ASCII correlation id matching the parent's
+ * validator regex (`/^[\w.\-:]+$/`, max length 128). The connector keeps a
+ * Map<correlationId, Resolver> so each request resolves independently.
+ */
+export function makeCorrelationId(prefix: string): string {
+  const random =
+    typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function'
+      ? crypto.randomUUID()
+      : Math.random().toString(36).slice(2) + Date.now().toString(36);
+  return `${prefix}.${random}`;
+}

package/src/wallet/parentBridgeProvider.test.ts

@@ -0,0 +1,209 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { ParentBridgeProvider } from './parentBridgeProvider';
+import {
+  NO_WALLET_ADDRESS,
+  TANGLE_IFRAME_PROTOCOL_VERSION,
+} from './parentBridgeProtocol';
+
+const PARENT_ORIGIN = 'https://cloud.tangle.tools';
+
+/**
+ * Drive the provider against a fake parent: capture every message the
+ * provider posts, route a scripted response (or broadcast) back, and assert
+ * the provider's observable behavior.
+ *
+ * The fake parent runs in the same JS context as the provider (jsdom's
+ * `window.parent === window`), so we monkey-patch `window.parent.postMessage`
+ * to intercept; for inbound messages we synthesize `MessageEvent`s with the
+ * trusted origin and dispatch them onto `window`.
+ */
+type Captured = { message: unknown; origin: string };
+
+function setupFakeParent() {
+  const captured: Captured[] = [];
+  const originalParent = window.parent;
+  Object.defineProperty(window, 'parent', {
+    configurable: true,
+    get() {
+      return {
+        postMessage: (message: unknown, targetOrigin: string) => {
+          captured.push({ message, origin: targetOrigin });
+        },
+      };
+    },
+  });
+  const restore = () => {
+    Object.defineProperty(window, 'parent', {
+      configurable: true,
+      value: originalParent,
+    });
+  };
+  const inbound = (data: object) =>
+    window.dispatchEvent(new MessageEvent('message', { data, origin: PARENT_ORIGIN }));
+  return { captured, inbound, restore };
+}
+
+describe('ParentBridgeProvider', () => {
+  let fake: ReturnType<typeof setupFakeParent>;
+  let provider: ParentBridgeProvider;
+
+  beforeEach(() => {
+    fake = setupFakeParent();
+    provider = new ParentBridgeProvider({
+      parentOrigin: PARENT_ORIGIN,
+      appId: 'agent-sandbox',
+      requestTimeoutMs: 1_000,
+    });
+  });
+
+  afterEach(() => {
+    provider.uninstall();
+    fake.restore();
+  });
+
+  it('sends a handshake on install + pins targetOrigin to the parent', () => {
+    provider.install();
+    expect(fake.captured).toHaveLength(1);
+    expect(fake.captured[0].origin).toBe(PARENT_ORIGIN);
+    expect(fake.captured[0].message).toEqual({
+      kind: 'tangle.app.handshake',
+      appId: 'agent-sandbox',
+      version: TANGLE_IFRAME_PROTOCOL_VERSION,
+    });
+  });
+
+  it('rejects messages from origins that are not the configured parent', () => {
+    provider.install();
+    // Manually dispatch a message from a different origin claiming to be a
+    // handshake ack. The provider must ignore it — verified by inspecting
+    // `getCachedAccount` (which gets set on a successful readAccountResult).
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: {
+          kind: 'tangle.app.accountChanged',
+          account: '0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef',
+        },
+        origin: 'https://evil.example.com',
+      }),
+    );
+    expect(provider.getCachedAccount()).toBeNull();
+  });
+
+  it('resolves eth_accounts to [] when parent reports zero-address', async () => {
+    provider.install();
+    fake.inbound({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'agent-sandbox',
+      protocolVersion: TANGLE_IFRAME_PROTOCOL_VERSION,
+    });
+    // Provider auto-fires a readAccount after handshakeAck. Wait for it,
+    // then reply with the zero-address sentinel.
+    const readAccountMsg = await vi.waitFor(() => {
+      const m = fake.captured.find(
+        (c) =>
+          typeof c.message === 'object' &&
+          c.message !== null &&
+          (c.message as { kind?: string }).kind === 'tangle.app.readAccount',
+      );
+      if (!m) throw new Error('readAccount not posted yet');
+      return m;
+    });
+    const correlationId = (readAccountMsg.message as { correlationId: string })
+      .correlationId;
+    fake.inbound({
+      kind: 'tangle.app.readAccountResult',
+      correlationId,
+      ok: true,
+      data: { account: NO_WALLET_ADDRESS, chainId: 84532 },
+    });
+    const accounts = await provider.request({ method: 'eth_accounts' });
+    expect(accounts).toEqual([]);
+  });
+
+  it('emits accountsChanged when the parent broadcasts a new account', () => {
+    provider.install();
+    fake.inbound({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'agent-sandbox',
+      protocolVersion: TANGLE_IFRAME_PROTOCOL_VERSION,
+    });
+    const seen: unknown[] = [];
+    provider.on('accountsChanged', (accounts) => seen.push(accounts));
+    fake.inbound({
+      kind: 'tangle.app.accountChanged',
+      account: '0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc',
+    });
+    expect(seen).toEqual([['0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc']]);
+  });
+
+  it('forwards personal_sign through the bridge and resolves on signMessageResult', async () => {
+    provider.install();
+    fake.inbound({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'agent-sandbox',
+      protocolVersion: TANGLE_IFRAME_PROTOCOL_VERSION,
+    });
+    // Establish chain context — the bridge needs `cachedChainId` to sign.
+    fake.inbound({ kind: 'tangle.app.chainChanged', chainId: 84532 });
+
+    const signed = provider.request({
+      method: 'personal_sign',
+      params: ['hello', '0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc'],
+    });
+    // Find the outbound signMessage request.
+    const outbound = await vi.waitFor(() => {
+      const msg = fake.captured.find(
+        (c) =>
+          typeof c.message === 'object' &&
+          c.message !== null &&
+          (c.message as { kind?: string }).kind === 'tangle.app.signMessage',
+      );
+      if (!msg) throw new Error('signMessage not posted yet');
+      return msg;
+    });
+    const correlationId = (outbound.message as { correlationId: string })
+      .correlationId;
+    expect((outbound.message as { message: string }).message).toBe('hello');
+    fake.inbound({
+      kind: 'tangle.app.signMessageResult',
+      correlationId,
+      ok: true,
+      data: { signature: '0xdeadbeef' },
+    });
+    await expect(signed).resolves.toBe('0xdeadbeef');
+  });
+
+  it('rejects on parent error response with the parent-provided error message', async () => {
+    provider.install();
+    fake.inbound({
+      kind: 'tangle.app.handshakeAck',
+      appId: 'agent-sandbox',
+      protocolVersion: TANGLE_IFRAME_PROTOCOL_VERSION,
+    });
+    fake.inbound({ kind: 'tangle.app.chainChanged', chainId: 84532 });
+
+    const signed = provider.request({
+      method: 'personal_sign',
+      params: ['hello', '0x9965507d1a55bcc2695c58ba16fb37d819b0a4dc'],
+    });
+    const outbound = await vi.waitFor(() => {
+      const msg = fake.captured.find(
+        (c) =>
+          typeof c.message === 'object' &&
+          c.message !== null &&
+          (c.message as { kind?: string }).kind === 'tangle.app.signMessage',
+      );
+      if (!msg) throw new Error('not posted yet');
+      return msg;
+    });
+    const correlationId = (outbound.message as { correlationId: string })
+      .correlationId;
+    fake.inbound({
+      kind: 'tangle.app.signMessageResult',
+      correlationId,
+      ok: false,
+      error: 'user-rejected',
+    });
+    await expect(signed).rejects.toThrow('user-rejected');
+  });
+});