@flayerlabs/gamemode-client 0.3.0 → 0.4.0

package/src/embed.ts

@@ -1,395 +1,226 @@
-import type { PlayerId } from '@flayerlabs/gamemode-spec';
+import type { Host, HostBuyProgress } from './live.js';
+import type { BuyResult } from './index.js';
 import {
-  EMBED_CHANNEL,
-  EMBED_PROTOCOL_VERSION,
-  isCanonicalSpendHookData,
-  isPlayerIdentities,
-  isSessionChallenge,
-  parseGameToHostMessage,
-  parseHostToGameMessage,
-  type EmbedFailure,
-  type EmbedRequest,
-  type EmbeddedContext,
-  type GameToHostMessage,
-  type HostToGameMessage,
-} from '@flayerlabs/gamemode-spec/embed';
-import type { MarketState, WireMarketState } from '@flayerlabs/gamemode-spec/live';
-import type { ClientPlatform, IdentityResolver, Readable } from './index.js';
-import { immutableLaunch, marketFrom, type Authorisation, type Host, type HostBuyProgress } from './live.js';
-import { Signal } from './signal.js';
-
-const DEFAULT_TIMEOUT_MS = 120_000;
-/** A room uses far fewer; refusing after the cap keeps lifetime replay memory strictly bounded. */
-const MAX_ACCEPTED_REQUEST_IDS = 1_024;
-
-export interface EmbedEventWindow {
-  addEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
-  removeEventListener(type: string, listener: EventListenerOrEventListenerObject | null): void;
+  FRAME_PROTOCOL_VERSION,
+  hostFrameFrom,
+  type BuyFailure,
+  type EmbedContext,
+  type GameToHostFrame,
+  type HostErrorCode,
+} from '@flayerlabs/gamemode-spec/frame';
+
+/**
+ * The game's end of the frame protocol: a {@link Host} reconstructed over `postMessage`.
+ *
+ * A game on flaunch.gg runs in a cross-origin iframe, so the page cannot hand it a Host object —
+ * the three Host calls travel as `gm:` frames instead (see `@flayerlabs/gamemode-spec/frame` for the
+ * shapes and the trust story). This file exists so a game never touches `postMessage` itself: it
+ * calls {@link connectHost} once and receives either a working Host plus the round to join, or
+ * `null` — which is an answer, not an error. Null means "not embedded", and the caller's right
+ * move is a mock room, so `pnpm dev` and the real page run the same entry file.
+ *
+ * Trust is decided once, before any message is read: the parent's origin comes from the one query
+ * parameter the page stamps on the iframe URL, and every frame is checked against both that origin
+ * and the parent window itself. A frame from anywhere else is silently ignored — this listener
+ * shares the window with whatever else the page runs.
+ */
+
+/** How often the game announces itself until the page answers. */
+const HELLO_INTERVAL_MS = 250;
+/** How long to wait for the page before concluding this is not an embed. */
+const DEFAULT_TIMEOUT_MS = 3_000;
+
+/**
+ * Where frames come from and go to. The default is the real window; tests inject a pair of these
+ * to run both ends of the protocol in one process with no DOM.
+ */
+export interface FrameEndpoint {
+  /** Deliver every incoming message with its origin and source; returns an unlisten. */
+  listen(handler: (data: unknown, origin: string, source: unknown) => void): () => void;
+  post(message: unknown, targetOrigin: string): void;
+  /** What a trusted message's source must equal. Null when there is no parent to talk to. */
+  parentSource(): unknown;
 }
 
-export interface EmbedTargetWindow {
-  postMessage(message: unknown, targetOrigin: string): void;
+export interface ConnectHostOptions {
+  /** Default: the `parentOrigin` query parameter of the page's own URL. */
+  parentOrigin?: string;
+  timeoutMs?: number;
+  endpoint?: FrameEndpoint;
 }
 
-export interface EmbeddedGameConnection {
-  context: EmbeddedContext;
+export interface EmbeddedHost {
   host: Host;
-  platform: ClientPlatform;
+  context: EmbedContext;
   dispose(): void;
 }
 
-interface Pending {
-  method: EmbedRequest['method'];
-  resolve(value: unknown): void;
-  reject(error: Error): void;
-  progress?: (event: HostBuyProgress) => void;
-  timer: ReturnType<typeof setTimeout>;
+function windowEndpoint(): FrameEndpoint | null {
+  if (typeof window === 'undefined') return null;
+  return {
+    listen(handler) {
+      const onMessage = (event: MessageEvent) => handler(event.data, event.origin, event.source);
+      window.addEventListener('message', onMessage);
+      return () => window.removeEventListener('message', onMessage);
+    },
+    post(message, targetOrigin) {
+      window.parent.postMessage(message, targetOrigin);
+    },
+    parentSource() {
+      return window.parent === window ? null : window.parent;
+    },
+  };
 }
 
-export interface ConnectEmbeddedGameOptions {
-  /** Fixed in trusted game code, never taken from a query string supplied by the parent. */
-  parentOrigin: string;
-  timeoutMs?: number;
-  currentWindow?: EmbedEventWindow;
-  parentWindow?: EmbedTargetWindow;
+function parentOriginFromLocation(): string | null {
+  if (typeof window === 'undefined') return null;
+  const origin = new URLSearchParams(window.location.search).get('parentOrigin');
+  return origin && origin.length > 0 ? origin : null;
 }
 
-/** Connect an untrusted game frame to the semantic services of its trusted parent. */
-export function connectEmbeddedGame(options: ConnectEmbeddedGameOptions): Promise<EmbeddedGameConnection> {
-  const current = options.currentWindow ?? window;
-  const parent = options.parentWindow ?? window.parent;
-  const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
-  const market = new Signal<MarketState>({ status: 'unavailable', prices: [], trades: [], marketCapUsd: null });
-  const pending = new Map<string, Pending>();
-  let disposed = false;
-  let context: EmbeddedContext | null = null;
-  let resolveContext!: (value: EmbeddedContext) => void;
-  let rejectContext!: (error: Error) => void;
-  const ready = new Promise<EmbeddedContext>((resolve, reject) => {
-    resolveContext = resolve;
-    rejectContext = reject;
-  });
-
-  const post = (message: GameToHostMessage): void => parent.postMessage(message, options.parentOrigin);
-  const request = (value: EmbedRequest, progress?: (event: HostBuyProgress) => void): Promise<unknown> => {
-    if (disposed) return Promise.reject(new Error('the embedded connection is closed'));
-    const id = globalThis.crypto.randomUUID();
-    return new Promise((resolve, reject) => {
-      const timer = setTimeout(() => {
-        pending.delete(id);
-        reject(new Error('the trusted parent did not answer in time'));
-      }, timeoutMs);
-      pending.set(id, { method: value.method, resolve, reject, timer, ...(progress ? { progress } : {}) });
-      post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'request', id, request: value });
-    });
-  };
-
-  const onMessage: EventListener = (rawEvent): void => {
-    const event = rawEvent as MessageEvent;
-    if (event.origin !== options.parentOrigin || event.source !== parent) return;
-    const message = parseHostToGameMessage(event.data);
-    if (!message) return;
-    if (message.type === 'context') {
-      if (context === null) {
-        context = Object.freeze({ ...message.context, launch: immutableLaunch(message.context.launch) });
-        resolveContext(context);
-      }
-      return;
-    }
-    if (message.type === 'market') {
-      const parsed = marketFrom(message.market);
-      if (parsed) market.set(parsed);
-      return;
-    }
-    const waiting = pending.get(message.id);
-    if (!waiting) return;
-    if (message.type === 'buy-progress') {
-      waiting.progress?.(
-        message.transactionHash
-          ? { state: 'pending', transactionHash: message.transactionHash }
-          : { state: 'pending' },
-      );
-      return;
-    }
-    pending.delete(message.id);
-    clearTimeout(waiting.timer);
-    if (!message.ok) {
-      if (waiting.method === 'buy') {
-        const reason = message.error === 'no-wallet' ? 'try-again' : message.error;
-        waiting.resolve({ failed: { bought: false, reason } });
-      } else {
-        waiting.reject(new Error(message.error));
-      }
-      return;
-    }
-    waiting.resolve(message.value);
-  };
-  current.addEventListener('message', onMessage);
-
-  const contextTimer = setTimeout(() => {
-    disposed = true;
-    current.removeEventListener('message', onMessage);
-    rejectContext(new Error('the trusted parent did not provide game context'));
-  }, timeoutMs);
-  post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'ready' });
+/** What the game is told when the page refuses a call outright rather than failing a buy. */
+const failureFor = (code: HostErrorCode): BuyFailure => (code === 'declined' ? 'declined' : 'try-again');
 
-  return ready.then((trustedContext) => {
-    clearTimeout(contextTimer);
-    const host: Host = {
-      address: async () => {
-        const value = await request({ method: 'address' });
-        return typeof value === 'string' || value === null ? value : null;
-      },
-      signIn: async (message) => {
-        const value = await request({ method: 'sign-in', message });
-        if (typeof value !== 'string' || !/^0x[0-9a-fA-F]+$/.test(value)) throw new Error('invalid signature response');
-        return value as `0x${string}`;
-      },
-      sessionEvidence: () => request({ method: 'session-evidence' }),
-      buy: async (authorisation, progress) => {
-        const value = await request({ method: 'buy', authorisation }, progress);
-        if (typeof value !== 'object' || value === null) return { failed: { bought: false, reason: 'try-again' } };
-        const spent = (value as { spentWei?: unknown }).spentWei;
-        try {
-          const spentWei = BigInt(String(spent));
-          return spentWei >= 0n ? { spentWei } : { failed: { bought: false, reason: 'try-again' } };
-        } catch {
-          return { failed: { bought: false, reason: 'try-again' } };
-        }
-      },
-    };
-    const identity: IdentityResolver = {
-      resolve: async (players) => {
-        const value = await request({ method: 'identity', players });
-        return isPlayerIdentities(value) ? value : [];
-      },
+type Pending =
+  | { kind: 'address'; resolve: (address: string | null) => void; reject: (error: Error) => void }
+  | { kind: 'signIn'; resolve: (signature: `0x${string}`) => void; reject: (error: Error) => void }
+  | {
+      kind: 'buy';
+      resolve: (outcome: { spentWei: bigint } | { failed: BuyResult }) => void;
+      progress: ((event: HostBuyProgress) => void) | undefined;
     };
-    const marketReadable: Readable<MarketState> = {
-      current: () => market.current(),
-      subscribe: (listener) => market.subscribe(listener),
-    };
-    return {
-      context: trustedContext,
-      host,
-      platform: { identity, market: marketReadable },
-      dispose: () => {
-        if (disposed) return;
-        disposed = true;
-        current.removeEventListener('message', onMessage);
-        for (const waiting of pending.values()) {
-          clearTimeout(waiting.timer);
-          waiting.reject(new Error('the embedded connection is closed'));
-        }
-        pending.clear();
-        market.clear();
-      },
-    };
-  });
-}
 
-export interface ServeEmbeddedGameOptions {
-  currentWindow?: EmbedEventWindow;
-  frameWindow: EmbedTargetWindow;
-  gameOrigin: string;
-  context: EmbeddedContext;
-  host: Host;
-  /**
-   * Verify the gate signature and signer for the canonical spend fields.
-   *
-   * The bridge itself checks the complete ABI encoding, including the required zero referrer,
-   * before calling this seam. A false result fails closed before any wallet UI can open.
-   */
-  validateAuthorisation(
-    authorisation: Authorisation,
-    context: EmbeddedContext,
-    signal?: AbortSignal,
-  ): boolean | Promise<boolean>;
-  platform?: ClientPlatform;
-  /** Display domain used by the gate's canonical wallet challenge. */
-  signInDomain?: string;
-}
+/**
+ * Connect to the embedding page, or learn that there is none.
+ *
+ * Resolves null when the game is not in an iframe, when no `parentOrigin` was provided, or when
+ * the page does not answer within the timeout — a page that answers late was never going to
+ * service a buy either. After it resolves, individual Host calls have no timeout of their own:
+ * sign-in and buy legitimately wait on a human, and the page always answers, refusals included.
+ */
+export async function connectHost(options: ConnectHostOptions = {}): Promise<EmbeddedHost | null> {
+  const endpoint = options.endpoint ?? windowEndpoint();
+  if (!endpoint) return null;
+  const parentOrigin = options.parentOrigin ?? parentOriginFromLocation();
+  if (!parentOrigin) return null;
+  const parent = endpoint.parentSource();
+  if (parent === null) return null;
 
-function wireMarket(state: MarketState): WireMarketState {
-  return { ...state, trades: state.trades.map((trade) => ({ ...trade, spendWei: trade.spendWei.toString() })) };
-}
+  const pending = new Map<string, Pending>();
+  let unlisten: () => void = () => {};
+  let disposed = false;
 
-function failure(reason: string): EmbedFailure {
-  return ['nothing-to-spend', 'declined', 'not-enough-for-fees', 'window-closed'].includes(reason)
-    ? (reason as EmbedFailure)
-    : 'try-again';
-}
+  const send = (frame: GameToHostFrame): void => endpoint.post(frame, parentOrigin);
+
+  const context = await new Promise<EmbedContext | null>((resolveContext) => {
+    let settled = false;
+    const hello = setInterval(() => send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:hello' }), HELLO_INTERVAL_MS);
+    const deadline = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      clearInterval(hello);
+      unlisten();
+      resolveContext(null);
+    }, options.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+
+    unlisten = endpoint.listen((data, origin, source) => {
+      // Both checks, always: the origin says who wrote the frame, the source says which window
+      // sent it, and either alone can be satisfied by a page we never agreed to trust.
+      if (origin !== parentOrigin || source !== parent) return;
+      const frame = hostFrameFrom(data);
+      if (!frame) return;
+
+      if (frame.type === 'gm:context') {
+        // First context wins; the page re-sends it for every hello and nothing may move the game
+        // to a different round mid-flight.
+        if (settled) return;
+        settled = true;
+        clearInterval(hello);
+        clearTimeout(deadline);
+        resolveContext(frame.context);
+        return;
+      }
 
-/** Serve one known iframe. Both its origin and WindowProxy are required for every request. */
-export function serveEmbeddedGame(options: ServeEmbeddedGameOptions): () => void {
-  const current = options.currentWindow ?? window;
-  const active = new Set<string>();
-  const acceptedRequestIds = new Set<string>();
-  const usedAuthorisations = new Set<string>();
-  const requestTimes: number[] = [];
-  let buyActive = false;
-  let signInActive = false;
-  let evidenceActive = false;
-  let childReady = false;
-  let stopped = false;
-  const lifetime = new AbortController();
-  let latestMarket: MarketState | null = options.platform?.market?.current() ?? null;
-  const post = (message: HostToGameMessage): void => {
-    if (!stopped) options.frameWindow.postMessage(message, options.gameOrigin);
-  };
-  const answer = (id: string, value: unknown): void =>
-    post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'response', id, ok: true, value });
-  const refuse = (id: string, error: EmbedFailure): void =>
-    post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'response', id, ok: false, error });
+      if (frame.type === 'gm:progress') {
+        const request = pending.get(frame.id);
+        if (request?.kind === 'buy') {
+          request.progress?.(
+            frame.progress.transactionHash !== undefined
+              ? { state: 'pending', transactionHash: frame.progress.transactionHash }
+              : { state: 'pending' },
+          );
+        }
+        return;
+      }
 
-  const run = async (id: string, request: EmbedRequest): Promise<void> => {
-    if (stopped || acceptedRequestIds.has(id) || acceptedRequestIds.size >= MAX_ACCEPTED_REQUEST_IDS) return;
-    const now = Date.now();
-    while (requestTimes[0] !== undefined && requestTimes[0] <= now - 1_000) requestTimes.shift();
-    if (active.size >= 16 || requestTimes.length >= 64) return;
-    requestTimes.push(now);
-    acceptedRequestIds.add(id);
-    active.add(id);
-    try {
-      switch (request.method) {
-        case 'address':
-          answer(id, await options.host.address(lifetime.signal));
-          break;
-        case 'sign-in':
-          if (signInActive) {
-            refuse(id, 'try-again');
-            break;
-          }
-          signInActive = true;
-          try {
-            const address = await options.host.address(lifetime.signal);
-            if (stopped) break;
-            if (
-              !address ||
-              !isSessionChallenge(request.message, address, options.context.gateUrl, options.signInDomain)
-            ) {
-              refuse(id, address ? 'try-again' : 'no-wallet');
-              break;
-            }
-            const signature = await options.host.signIn(request.message, lifetime.signal);
-            if (stopped) break;
-            answer(id, signature);
-          } finally {
-            signInActive = false;
-          }
-          break;
-        case 'session-evidence':
-          if (evidenceActive) {
-            refuse(id, 'try-again');
-            break;
-          }
-          evidenceActive = true;
-          try {
-            const evidence = await options.host.sessionEvidence?.(lifetime.signal);
-            if (!stopped) answer(id, evidence);
-          } finally {
-            evidenceActive = false;
-          }
-          break;
-        case 'identity':
-          answer(id, (await options.platform?.identity?.resolve(request.players)) ?? []);
-          break;
-        case 'buy': {
-          if (buyActive) {
-            refuse(id, 'try-again');
-            break;
-          }
-          buyActive = true;
-          try {
-            const address = await options.host.address(lifetime.signal);
-            if (stopped) break;
-            if (
-              !address ||
-              address.toLowerCase() !== request.authorisation.buyer.toLowerCase() ||
-              request.authorisation.poolId.toLowerCase() !== options.context.launch.poolId.toLowerCase()
-            ) {
-              refuse(id, address ? 'try-again' : 'no-wallet');
-              break;
-            }
-            if (
-              !isCanonicalSpendHookData(request.authorisation) ||
-              !(await options.validateAuthorisation(request.authorisation, options.context, lifetime.signal))
-            ) {
-              refuse(id, 'try-again');
-              break;
-            }
-            if (stopped) break;
-            const authorisationId = [
-              request.authorisation.buyer.toLowerCase(),
-              request.authorisation.poolId.toLowerCase(),
-              request.authorisation.nonce,
-            ].join(':');
-            if (usedAuthorisations.has(authorisationId) || usedAuthorisations.size >= 256) {
-              refuse(id, 'try-again');
-              break;
-            }
-            usedAuthorisations.add(authorisationId);
-            const result = await options.host.buy(
-              request.authorisation,
-              (event) => {
-                post({
-                  channel: EMBED_CHANNEL,
-                  v: EMBED_PROTOCOL_VERSION,
-                  type: 'buy-progress',
-                  id,
-                  ...(event.transactionHash ? { transactionHash: event.transactionHash } : {}),
-                });
-              },
-              lifetime.signal,
-            );
-            if (stopped) break;
-            if ('failed' in result) {
-              refuse(id, result.failed.bought ? 'try-again' : failure(result.failed.reason));
-            } else {
-              answer(id, { spentWei: result.spentWei.toString() });
-            }
-          } finally {
-            buyActive = false;
-          }
-          break;
+      // gm:res — terminal, exactly once per id. A late or repeated answer finds nothing here.
+      const request = pending.get(frame.id);
+      if (!request) return;
+      pending.delete(frame.id);
+
+      if (request.kind === 'buy') {
+        if (!frame.ok) {
+          request.resolve({ failed: { bought: false, reason: failureFor(frame.error.code) } });
+        } else if (frame.result.method !== 'buy') {
+          request.resolve({ failed: { bought: false, reason: 'try-again' } });
+        } else if ('spentWei' in frame.result.outcome) {
+          request.resolve({ spentWei: BigInt(frame.result.outcome.spentWei) });
+        } else {
+          request.resolve({ failed: frame.result.outcome.failed });
         }
+        return;
       }
-    } catch {
-      refuse(id, 'try-again');
-    } finally {
-      active.delete(id);
-    }
-  };
 
-  const onMessage: EventListener = (rawEvent): void => {
-    const event = rawEvent as MessageEvent;
-    if (event.origin !== options.gameOrigin || event.source !== options.frameWindow) return;
-    const message = parseGameToHostMessage(event.data);
-    if (!message) return;
-    if (message.type === 'ready') {
-      if (childReady) return;
-      childReady = true;
-      post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'context', context: options.context });
-      if (latestMarket) {
-        post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'market', market: wireMarket(latestMarket) });
+      if (request.kind === 'address') {
+        if (frame.ok && frame.result.method === 'address') request.resolve(frame.result.address);
+        else request.reject(new Error(frame.ok ? 'the page answered the wrong call' : frame.error.message));
+        return;
       }
-      return;
-    }
-    void run(message.id, message.request);
+
+      if (frame.ok && frame.result.method === 'signIn') request.resolve(frame.result.signature);
+      else request.reject(new Error(frame.ok ? 'the page answered the wrong call' : frame.error.message));
+    });
+  });
+
+  if (!context) return null;
+
+  const requestId = (): string => globalThis.crypto.randomUUID();
+
+  const host: Host = {
+    address: () =>
+      new Promise<string | null>((resolve, reject) => {
+        if (disposed) return resolve(null);
+        const id = requestId();
+        pending.set(id, { kind: 'address', resolve, reject });
+        send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:req', id, call: { method: 'address' } });
+      }),
+
+    signIn: (message: string) =>
+      new Promise<`0x${string}`>((resolve, reject) => {
+        if (disposed) return reject(new Error('this embed has been disposed'));
+        const id = requestId();
+        pending.set(id, { kind: 'signIn', resolve, reject });
+        send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:req', id, call: { method: 'signIn', message } });
+      }),
+
+    buy: (authorisation, progress) =>
+      new Promise<{ spentWei: bigint } | { failed: BuyResult }>((resolve) => {
+        if (disposed) return resolve({ failed: { bought: false, reason: 'try-again' } });
+        const id = requestId();
+        pending.set(id, { kind: 'buy', resolve, progress });
+        // The client's Authorisation is already all strings plus optional hookData, which is
+        // exactly the wire shape — nothing to convert, nothing to get wrong.
+        send({ v: FRAME_PROTOCOL_VERSION, type: 'gm:req', id, call: { method: 'buy', authorisation } });
+      }),
   };
-  current.addEventListener('message', onMessage);
-  const stopMarket =
-    options.platform?.market?.subscribe((state) => {
-      latestMarket = state;
-      if (childReady) {
-        post({ channel: EMBED_CHANNEL, v: EMBED_PROTOCOL_VERSION, type: 'market', market: wireMarket(state) });
-      }
-    }) ?? (() => {});
 
-  return () => {
-    if (stopped) return;
-    stopped = true;
-    lifetime.abort();
-    current.removeEventListener('message', onMessage);
-    stopMarket();
+  return {
+    host,
+    context,
+    dispose() {
+      disposed = true;
+      unlisten();
+      pending.clear();
+    },
   };
 }