@me.jango/signa 0.0.0-stage → 0.4.0

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# @me.jango/signa
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Sign in to your app with a Signa passkey account or an external wallet, then request exact payment
+reviews. This is the browser-only slice of the Signa client. Bot access and the CLI ship separately as
+the full client archive linked from https://api.signa.center/api/docs/client.
+
+```sh
+npm install @me.jango/signa
+```
+
+| Import | What it is | Needs |
+| --- | --- | --- |
+| `@me.jango/signa` | The wallet client: connect an account, review and submit payments | viem |
+| `@me.jango/signa/core` | The connect step, headless: sign-in options, popup or frame, callback page. Also re-exports the wallet client | viem |
+| `@me.jango/signa/wagmi` | A read-only wagmi connector for the passkey account | wagmi |
+| `@me.jango/signa/react` | The sign-in modal | React |
+
+React and wagmi are optional peers: an app that imports only the root entry or `/core` never loads them.
+These subpaths replace `@bananapus/nana-sdk-connect`; the export names are the same, so moving over only
+changes the import specifier.
+
+## Wallet client
+
+```js
+import { createCenterWalletClient } from '@me.jango/signa';
+const wallet = createCenterWalletClient({
+  issuer: 'https://signa.center', audience: 'https://api.signa.center',
+  callbackUri: window.location.origin + '/center/callback',
+});
+const prepared = await wallet.prepareConnection();
+prepared.launch(); // full-page redirect to the account
+// prepared.launch({ target: name }) submits into a window or iframe the app opened under that
+// name; Signa serves the sign-in inside an iframe only for apps its operator admits to frame.
+// On /center/callback:
+const connection = await wallet.completeConnection(window.location.href);
+```
+
+Your app origin and exact callback URI must be allowlisted by Signa. Allow the issuer in your
+`form-action` CSP directive and send `Referrer-Policy: strict-origin`. `restoreConnection()` reads the
+saved connection, `disconnect()` clears it, and `payments()` prepares, completes and submits reviewed
+payments. Protocol details: https://api.signa.center/api/docs/client
+`refreshPayment({ waitSeconds })` holds a submitted payment's read on Signa (up to 20 s) until the
+operation moves, so an app can wait on it instead of polling. A record whose app grant is gone and whose
+signed validity has passed can be cleared; it is archived as unknown and Signa keeps the outcome.
+When Signa refuses to send an approved payment, `submitPayment()` throws the refusal (with
+`payFailure` when the calls say why) after asking Signa to retire the approval. Read
+`pendingPayment()` next: `refused` means Signa retired it and never sends it, so `clearPayment()` and a
+fresh `preparePayment()` can follow at once; the fresh payment takes the refused one's nonce, so at most
+one of them executes. `pending` or `confirming` means a send won before the retirement: follow it.
+`unknown` means the retirement or the answer was lost: `retirePayment()` retires an approved payment
+Signa has not sent, or returns the submission that already claimed it.
+A reverted payment's status and a refused submission's `RestClientError` carry `payFailure`: the SDK's own
+`PayFailure`, as `decodePayFailure` reads the same revert (bigint `received` and `minimum`, plus `zeroFill`
+and `adjustable` for a shortfall), so it goes straight to the SDK's `payRetrySlippageBps` and to the same
+display as an external-wallet payment. `observation.payFailure` keeps the reason as Signa served it. Because the
+amounts are bigints, `JSON.stringify` of a status or error needs a replacer such as
+`(_, value) => typeof value === 'bigint' ? value.toString() : value`. Without `adjustable`, no setting the
+payer controls would help, so never relax a minimum then.
+
+## Connect
+
+- `/core`: `createConnectController(options)` (headless, no React or wagmi) takes the passkey option and
+  any external-wallet options (each a `ConnectOption`: `id`, `name`, optional `icon`, and `connect`, which
+  may publish a pairing URI through `handoff` for a QR code). `passkeyOption({ wallet, connected })` is the
+  Signa account. For the app's `/center/callback` page, call `deliverCenterCallback(url, { window })`, then
+  `completeCenterCallback(wallet, url)` when it returns false. The passkey account opens Signa in a popup
+  and the page stays; the callback page hands its URL back to the page, which finishes the exchange and runs
+  `connected`. A blocked popup falls back to a full-page redirect, where the callback page completes the
+  exchange itself. With `passkeyOption({ frame: true })` Signa opens in a frame the modal shows instead;
+  the callback page hands its URL up to the framing page through the same `deliverCenterCallback`. Signa
+  serves the sign-in framed only for apps its operator admits to frame (`WALLET_FRAMEABLE_APP_ORIGINS`),
+  and the page inside offers "Open as a page" when it cannot continue there. The frame delegates passkey
+  prompts and creation to Signa's origin by name, so a new user can sign up inside it.
+- `/wagmi`: `centerAccountConnector({ wallet, read })`, a read-only Base connector for the passkey account.
+  It answers reads through `read` and refuses to sign: payments go through Signa's review.
+- `/react`: `<JBConnectModal open controller onClose />` shows the passkey account as the primary button
+  (named after the platform prompt: Touch ID, Face ID, Windows Hello, unless `passkeyLabel` overrides it)
+  and external wallets as tiles. Theme it with the `--jb-connect-*` custom properties (`--jb-connect-pad`
+  is the dialog's inset, which the Signa frame bleeds through). The modal answers the frame's size reports
+  with its resolved theme, so the Signa page inside takes the app's colours, font and corners.
+
+The passkey account signs nothing in the app. Payments go through Signa's review flow.

package/core/controller.d.ts

@@ -0,0 +1,43 @@
+/** One way in. The passkey account and every external wallet share this shape, so the modal and
+ * the apps never special-case Signa. `handoff` publishes a pairing URI (WalletConnect, a mobile
+ * deep link) for the app to render as a QR code or a link. */
+type ConnectOption = {
+    id: string;
+    name: string;
+    /** A data: image URL. Apps render their own mark when absent. */
+    icon?: string;
+    disabled?: boolean;
+    connect(context: {
+        signal: AbortSignal;
+        handoff(uri: string): void;
+        /** Asks the app to show a frame under this name for the option to continue in (the passkey
+         * sign-in at Signa, when Signa admits the app to frame it). `origin` is the page that will
+         * load in it, named in the frame's `allow` so the browser delegates passkeys to it: a frame
+         * without a `src` (Signa's launch form posts into it by name) delegates nothing otherwise. */
+        frame(name: string, origin: string): void;
+    }): Promise<void>;
+};
+type ConnectState = {
+    /** The option being connected, or null when idle. A passkey connection leaves the page, so it
+     * stays pending until the browser returns. */
+    pending: string | null;
+    error: string | null;
+    handoffUri: string | null;
+    /** The name of the frame the pending option continues in, once it asks for one. */
+    frameName: string | null;
+    /** The origin the frame delegates passkeys to. */
+    frameOrigin: string | null;
+};
+type ConnectController = {
+    readonly options: readonly ConnectOption[];
+    getState(): ConnectState;
+    subscribe(listener: () => void): () => void;
+    /** Starts an option; rejections become `state.error`, never a thrown promise. */
+    choose(id: string): Promise<void>;
+    /** Aborts the in-flight option and clears the state. */
+    cancel(): void;
+};
+declare function createConnectController(options: readonly ConnectOption[]): ConnectController;
+
+export { createConnectController as c };
+export type { ConnectOption as C, ConnectController as a, ConnectState as b };

package/core/index.d.ts

@@ -0,0 +1,79 @@
+import { C as ConnectOption } from './controller.js';
+export { a as ConnectController, b as ConnectState, c as createConnectController } from './controller.js';
+export * from '../index.js';
+
+/** The wallet client surface the passkey option needs (`createCenterWalletClient` satisfies it). */
+type PasskeyWallet = {
+    prepareConnection(): Promise<{
+        /** Where the launch lands: its origin is what a frame delegates passkeys to. */
+        authorizationUrl: string;
+        launch(options?: {
+            target?: string;
+        }): void;
+    }>;
+    completeConnection(url: string): Promise<unknown>;
+    retryConnection(): Promise<unknown>;
+    /** The current connection, when one is already held in this tab. */
+    restoreConnection?(): unknown;
+    disconnect(): void;
+    payments(): {
+        pendingPayment(): {
+            status: string;
+        } | null;
+    };
+};
+/** The built-in way in: a passkey account at Signa. By default Signa opens in a popup
+ * and the page stays; the callback comes back by message and the exchange finishes here, then
+ * `connected` runs. With `frame: true` Signa opens in a frame the app shows instead (the modal
+ * renders it under the name the option asks for); Signa serves the sign-in framed only for apps
+ * its operator admits, and the page inside offers "Open as a page" when it cannot continue there.
+ * When the popup is blocked, or with `popup: false`, connecting is a full-page redirect, so
+ * `beforeLaunch` is where the app saves what it needs to come back to. */
+declare function passkeyOption(input: {
+    wallet(): Promise<PasskeyWallet> | PasskeyWallet;
+    beforeLaunch?(): void;
+    popup?: boolean;
+    frame?: boolean;
+    /** After a popup sign-in completes in this page: connect the app's wallet layer. */
+    connected?(connection: unknown): Promise<void> | void;
+    /** Defaults to the global window. */
+    window?: Window;
+}): ConnectOption;
+
+/** For the app's callback page. Hands the callback URL to the same-origin page that opened this
+ * window (a popup sign-in) or frames it (a framed sign-in or payment review), and closes a popup
+ * once that page acknowledges. The page may be slow to answer (a backgrounded
+ * tab on a phone), so the offer repeats until it is acknowledged or the opener closes. The cap
+ * (default fifteen minutes, the life of a Signa request) covers an opener that navigated away;
+ * after it the callback page completes the exchange itself, as it does after a full-page
+ * redirect, while still closing on a late acknowledgement. False when there is no same-origin
+ * opener. */
+declare function deliverCenterCallback(url: string, options?: {
+    window?: Window | undefined;
+    timeoutMs?: number;
+    retryMs?: number;
+}): Promise<boolean>;
+
+/** The wallet client surface the callback page needs. */
+type CenterCallbackWallet = {
+    completeConnection(url: string): Promise<unknown>;
+    retryConnection(): Promise<unknown>;
+    payments(): {
+        completePayment(url: string): Promise<unknown>;
+        refreshPayment(): Promise<unknown>;
+    };
+};
+type CenterCallbackResult = {
+    kind: "connection";
+    connection: unknown;
+} | {
+    kind: "payment";
+    status: unknown;
+};
+/** Finishes whatever Signa sent the browser back for: a connection (`code`) or a payment
+ * review (`review`). Without parameters it retries the pending exchange, so a reload of the
+ * callback page after a failed exchange resumes instead of starting over. */
+declare function completeCenterCallback(wallet: CenterCallbackWallet, url: string): Promise<CenterCallbackResult>;
+
+export { ConnectOption, completeCenterCallback, deliverCenterCallback, passkeyOption };
+export type { CenterCallbackResult, CenterCallbackWallet, PasskeyWallet };

package/core/index.js

@@ -0,0 +1,347 @@
+"use client";
+
+// wallet-client/src/core/controller.ts
+var idle = {
+  pending: null,
+  error: null,
+  handoffUri: null,
+  frameName: null,
+  frameOrigin: null
+};
+function createConnectController(options) {
+  let state = idle;
+  let current = null;
+  const listeners = /* @__PURE__ */ new Set();
+  const set = (next) => {
+    state = { ...state, ...next };
+    for (const listener of listeners) listener();
+  };
+  return {
+    options,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async choose(id) {
+      const option = options.find((candidate) => candidate.id === id);
+      if (!option || option.disabled || current) return;
+      const controller = current = new AbortController();
+      set({
+        pending: id,
+        error: null,
+        handoffUri: null,
+        frameName: null,
+        frameOrigin: null
+      });
+      try {
+        await option.connect({
+          signal: controller.signal,
+          handoff: (uri) => {
+            if (current === controller) set({ handoffUri: uri });
+          },
+          frame: (name, origin) => {
+            if (current === controller)
+              set({ frameName: name, frameOrigin: origin });
+          }
+        });
+      } catch (error) {
+        if (current === controller)
+          set({
+            pending: null,
+            handoffUri: null,
+            frameName: null,
+            frameOrigin: null,
+            error: messageOf(error)
+          });
+      } finally {
+        if (current === controller) current = null;
+      }
+    },
+    cancel() {
+      current?.abort();
+      current = null;
+      set(idle);
+    }
+  };
+}
+function messageOf(error) {
+  const value = error;
+  if (value?.code === 4001 || value?.name === "AbortError") return null;
+  return value?.shortMessage || error instanceof Error && error.message || "The connection did not complete.";
+}
+
+// wallet-client/src/core/popup.ts
+var popupName = "juicebox-center";
+var frameName = "juicebox-center-frame";
+var callbackType = "juicebox-center:callback";
+var receivedType = "juicebox-center:received";
+function openCenterPopup(win) {
+  if (!win) return null;
+  const width = 460, height = 720;
+  const left = Math.max(
+    0,
+    Math.round((win.outerWidth ?? width) / 2 - width / 2 + (win.screenX ?? 0))
+  );
+  const top = Math.max(
+    0,
+    Math.round(
+      (win.outerHeight ?? height) / 2 - height / 2 + (win.screenY ?? 0)
+    )
+  );
+  try {
+    return win.open(
+      "",
+      popupName,
+      `popup,width=${width},height=${height},left=${left},top=${top}`
+    );
+  } catch {
+    return null;
+  }
+}
+var abort = () => new DOMException("The sign-in window was closed.", "AbortError");
+function awaitPopupCallback(win, popup, signal) {
+  return new Promise((resolve, reject) => {
+    const origin = win.location.origin;
+    const done = () => {
+      win.removeEventListener("message", onMessage);
+      signal.removeEventListener("abort", onAbort);
+      clearInterval(timer);
+    };
+    const onMessage = (event) => {
+      const data = event.data;
+      if (event.source !== popup || event.origin !== origin || data?.type !== callbackType || typeof data.url !== "string")
+        return;
+      done();
+      popup.postMessage({ type: receivedType }, origin);
+      resolve(data.url);
+    };
+    const onAbort = () => {
+      done();
+      popup.close();
+      reject(abort());
+    };
+    const timer = setInterval(() => {
+      if (!popup.closed) return;
+      done();
+      reject(abort());
+    }, 250);
+    win.addEventListener("message", onMessage);
+    signal.addEventListener("abort", onAbort);
+  });
+}
+function awaitFrameCallback(win, frame, signal) {
+  return new Promise((resolve, reject) => {
+    const origin = win.location.origin;
+    const done = () => {
+      win.removeEventListener("message", onMessage);
+      signal.removeEventListener("abort", onAbort);
+    };
+    const onMessage = (event) => {
+      const data = event.data;
+      if (!frame.contentWindow || event.source !== frame.contentWindow || event.origin !== origin || data?.type !== callbackType || typeof data.url !== "string")
+        return;
+      done();
+      frame.contentWindow.postMessage({ type: receivedType }, origin);
+      resolve(data.url);
+    };
+    const onAbort = () => {
+      done();
+      reject(new DOMException("The sign-in was closed.", "AbortError"));
+    };
+    if (signal.aborted) return onAbort();
+    win.addEventListener("message", onMessage);
+    signal.addEventListener("abort", onAbort);
+  });
+}
+function deliverCenterCallback(url, options = {}) {
+  const win = options.window;
+  if (!win) return Promise.resolve(false);
+  const origin = win.location.origin;
+  if (win.parent && win.parent !== win) {
+    try {
+      if (win.parent.location.origin === origin) {
+        win.parent.postMessage({ type: callbackType, url }, origin);
+        return Promise.resolve(true);
+      }
+    } catch {
+    }
+  }
+  const opener = win.opener;
+  if (!opener) return Promise.resolve(false);
+  try {
+    if (opener.closed || opener.location.origin !== origin)
+      return Promise.resolve(false);
+  } catch {
+    return Promise.resolve(false);
+  }
+  return new Promise((resolve) => {
+    let settled = false;
+    const finish = (delivered) => {
+      clearInterval(again);
+      clearTimeout(cap);
+      if (delivered) {
+        win.removeEventListener("message", onMessage);
+        win.close();
+      }
+      if (!settled) {
+        settled = true;
+        resolve(delivered);
+      }
+    };
+    const onMessage = (event) => {
+      const data = event.data;
+      if (event.source !== opener || event.origin !== origin || data?.type !== receivedType)
+        return;
+      finish(true);
+    };
+    const offer = () => {
+      if (opener.closed) return finish(false);
+      opener.postMessage({ type: callbackType, url }, origin);
+    };
+    const again = setInterval(offer, options.retryMs ?? 1500);
+    const cap = setTimeout(() => finish(false), options.timeoutMs ?? 9e5);
+    win.addEventListener("message", onMessage);
+    offer();
+  });
+}
+
+// src/rest/client/paymentStates.ts
+var settledPaymentStates = ["paid", "reverted", "cancelled", "expired", "refused"];
+var isSettledPayment = (status) => settledPaymentStates.includes(status);
+
+// wallet-client/src/core/passkey.ts
+function passkeyOption(input) {
+  return {
+    id: "juicebox-center",
+    name: "Signa account",
+    async connect({ signal, frame }) {
+      signal.throwIfAborted();
+      const connected = async (connection) => {
+        signal.throwIfAborted();
+        await input.connected?.(connection);
+      };
+      const win = input.window ?? globalThis.window;
+      const popup = input.frame || input.popup === false ? null : openCenterPopup(win);
+      try {
+        const wallet = await input.wallet();
+        const payment = wallet.payments().pendingPayment();
+        if (payment && !isSettledPayment(payment.status))
+          throw new Error(
+            "Finish your pending Signa payment before signing in again."
+          );
+        input.beforeLaunch?.();
+        let prepared = await wallet.prepareConnection().catch(async (error) => {
+          const code = error?.code;
+          if (code === "WALLET_HANDOFF_PENDING" || code === "WALLET_ALREADY_CONNECTED" && wallet.restoreConnection?.())
+            return null;
+          if (code === "WALLET_HANDOFF_CHANGED")
+            return wallet.prepareConnection();
+          if (code !== "WALLET_HANDOFF_EXPIRED" && code !== "WALLET_ALREADY_CONNECTED" && code !== "WALLET_STORAGE_INVALID")
+            throw error;
+          wallet.disconnect();
+          return wallet.prepareConnection();
+        });
+        if (!prepared) {
+          const restored = wallet.restoreConnection?.();
+          if (restored) {
+            await connected(restored);
+            return;
+          }
+          let connection2;
+          try {
+            connection2 = await wallet.retryConnection();
+          } catch (error) {
+            const code = error?.code;
+            const raced = code === "WALLET_HANDOFF_CHANGED" ? wallet.restoreConnection?.() : null;
+            if (raced) {
+              await connected(raced);
+              return;
+            }
+            if (code !== "WALLET_REQUEST_REJECTED") throw error;
+            wallet.disconnect();
+            prepared = await wallet.prepareConnection();
+          }
+          if (!prepared) {
+            await connected(connection2);
+            return;
+          }
+        }
+        signal.throwIfAborted();
+        if (input.frame) {
+          frame(frameName, new URL(prepared.authorizationUrl).origin);
+          const element = await frameElement(win, signal);
+          prepared.launch({ target: frameName });
+          const url2 = await awaitFrameCallback(win, element, signal);
+          const connection2 = await wallet.completeConnection(url2);
+          await connected(connection2);
+          return;
+        }
+        if (!popup) {
+          prepared.launch();
+          return;
+        }
+        if (popup.closed)
+          throw new DOMException(
+            "The sign-in window was closed.",
+            "AbortError"
+          );
+        prepared.launch({ target: popupName });
+        const url = await awaitPopupCallback(win, popup, signal);
+        const connection = await wallet.completeConnection(url);
+        await connected(connection);
+      } finally {
+        popup?.close();
+      }
+    }
+  };
+}
+function frameElement(win, signal) {
+  return new Promise((resolve, reject) => {
+    const started = Date.now();
+    const look = () => {
+      if (signal.aborted)
+        return reject(
+          new DOMException("The sign-in was closed.", "AbortError")
+        );
+      const element = win.document?.querySelector(
+        `iframe[name="${frameName}"]`
+      );
+      if (element) return resolve(element);
+      if (Date.now() - started > 5e3)
+        return reject(new Error("The sign-in frame did not appear."));
+      setTimeout(look, 20);
+    };
+    look();
+  });
+}
+
+// wallet-client/src/core/callback.ts
+async function completeCenterCallback(wallet, url) {
+  const parameters = new URL(url).searchParams;
+  if (parameters.has("review"))
+    return {
+      kind: "payment",
+      status: await wallet.payments().completePayment(url)
+    };
+  if (parameters.has("code"))
+    return {
+      kind: "connection",
+      connection: await wallet.completeConnection(url)
+    };
+  if (parameters.has("state"))
+    return {
+      kind: "payment",
+      status: await wallet.payments().refreshPayment()
+    };
+  return { kind: "connection", connection: await wallet.retryConnection() };
+}
+
+// wallet-client/src/core/index.ts
+export * from "../index.js";
+export {
+  completeCenterCallback,
+  createConnectController,
+  deliverCenterCallback,
+  passkeyOption
+};