@livo-build/kit 0.2.2 → 0.2.3

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from "./provider";
 export * from "./contracts";
 export * from "./tx";
 export * from "./auth";
+export * from "./verify";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";

package/dist/index.js

@@ -7,6 +7,8 @@
 //   contracts/ — useContractValue, createLivoContracts (bound to Livo's generated bindings)
 //   tx/        — useTx, TxButton, TxProgress, decodeRevert
 //   auth/      — useSiwe, SignInWithEthereum (Sign-In With Ethereum vs a same-origin /api/auth)
+//   verify/    — useWalletVerify, WalletVerifyButton (prove wallet ownership by signing an
+//                app-specific message → POST to a backend; the frontend half of runtime Gatekeeper)
 //   toast/     — ToastProvider, useToast
 //   data/      — useApi, useSubgraph, useCollection + DataTable (search/sort/paginate), useEventSource/useWebSocket (realtime)
 //   web3/      — Address, Balance, NetworkGuard, TokenAmount(Input)
@@ -30,6 +32,7 @@ export * from "./provider";
 export * from "./contracts";
 export * from "./tx";
 export * from "./auth";
+export * from "./verify";
 export * from "./toast";
 export * from "./data";
 export * from "./web3";

package/dist/verify/WalletVerifyButton.d.ts

@@ -0,0 +1,17 @@
+import "../wallet/wallet.css";
+import { type ReactNode } from "react";
+import { type UseWalletVerifyOptions, type WalletVerifyState } from "./useWalletVerify";
+export interface WalletVerifyButtonProps extends UseWalletVerifyOptions {
+    className?: string;
+    /** Override the button copy per state. */
+    labels?: {
+        idle?: string;
+        signing?: string;
+        verifying?: string;
+        verified?: string;
+        error?: string;
+    };
+    /** Custom render — receives the full hook state. */
+    children?: (api: WalletVerifyState) => ReactNode;
+}
+export declare function WalletVerifyButton({ className, labels, children, ...opts }: WalletVerifyButtonProps): import("react").JSX.Element;

package/dist/verify/WalletVerifyButton.js

@@ -0,0 +1,31 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import "../wallet/wallet.css";
+import {} from "react";
+import { useWalletVerify } from "./useWalletVerify";
+import { ConnectWallet } from "../wallet";
+import { useIsConnected } from "../account";
+import { cx } from "../util";
+// Drop-in: prompts a wallet connect if needed, then runs connect → sign → verify and
+// reflects the result. Reuses the wallet-connect button styling (wm-cta / wm-account).
+// Pair with the runtime `Gatekeeper` (set `endpoint` to your verifyAndLink route).
+export function WalletVerifyButton({ className, labels, children, ...opts }) {
+    const v = useWalletVerify(opts);
+    const connected = useIsConnected();
+    if (children)
+        return _jsx(_Fragment, { children: children(v) });
+    // Not connected yet — let the user connect first (the proof needs a wallet).
+    if (!connected)
+        return _jsx(ConnectWallet, {});
+    if (v.status === "verified") {
+        return (_jsx("button", { className: cx("wm-account", className), disabled: true, children: labels?.verified ?? "Verified ✓" }));
+    }
+    const busy = v.status === "signing" || v.status === "verifying";
+    const label = v.status === "signing"
+        ? labels?.signing ?? "Check your wallet…"
+        : v.status === "verifying"
+            ? labels?.verifying ?? "Verifying…"
+            : v.status === "error"
+                ? labels?.error ?? "Try again"
+                : labels?.idle ?? "Verify wallet";
+    return (_jsx("button", { className: cx("wm-cta", className), disabled: busy, onClick: () => (v.status === "error" ? v.reset() : void v.verify()), children: label }));
+}

package/dist/verify/index.d.ts

@@ -0,0 +1,2 @@
+export { useWalletVerify, buildVerifyMessage, isVerifySuccess, DEFAULT_VERIFY_MESSAGE_PREFIX, type UseWalletVerifyOptions, type WalletVerifyState, type WalletVerifyStatus, type WalletVerifyResult, } from "./useWalletVerify";
+export { WalletVerifyButton, type WalletVerifyButtonProps } from "./WalletVerifyButton";

package/dist/verify/index.js

@@ -0,0 +1,2 @@
+export { useWalletVerify, buildVerifyMessage, isVerifySuccess, DEFAULT_VERIFY_MESSAGE_PREFIX, } from "./useWalletVerify";
+export { WalletVerifyButton } from "./WalletVerifyButton";

package/dist/verify/useWalletVerify.d.ts

@@ -0,0 +1,68 @@
+export type WalletVerifyStatus = "idle" | "signing" | "verifying" | "verified" | "error";
+/** Whatever the backend returns from the verify route (ok + any extra fields). */
+export interface WalletVerifyResult {
+    ok: boolean;
+    address?: string;
+    [key: string]: unknown;
+}
+export interface UseWalletVerifyOptions {
+    /**
+     * POST endpoint that verifies the signature + records the proof (default
+     * "/api/verify"). Mirrors the backend `Gatekeeper.verifyAndLink` route — it
+     * receives `{ nonce, address, signature }` and returns `{ ok, ... }`. When
+     * pairing with the `wallet-link-bot` template (which serves it at `/link`), set
+     * `endpoint: "/link"`.
+     */
+    endpoint?: string;
+    /**
+     * The challenge nonce. Defaults to the `?n=` query param — the backend
+     * `Gatekeeper.challenge()` embeds it in the link URL it DMs the user. Pass it
+     * explicitly, or use `nonceEndpoint` to have the frontend mint one.
+     */
+    nonce?: string;
+    /** GET endpoint that mints a nonce (and optionally the exact message) → `{ nonce, message? }`. */
+    nonceEndpoint?: string;
+    /**
+     * Prefix prepended to the nonce to form the signed message. MUST match the
+     * backend `Gatekeeper`'s `messagePrefix` byte-for-byte. Default matches the
+     * Gatekeeper default — override on BOTH sides to make the text app-specific.
+     */
+    messagePrefix?: string;
+    /** Full control of the signed text (overrides messagePrefix). A server-supplied message wins. */
+    message?: string | ((address: string, nonce: string) => string);
+    /** Send cookies with the verify POST (for a session-issuing backend). */
+    credentials?: boolean;
+    onVerified?: (result: WalletVerifyResult) => void;
+    onError?: (error: Error) => void;
+}
+export interface WalletVerifyState {
+    status: WalletVerifyStatus;
+    /** The connected wallet address (the one being proven). */
+    address?: string;
+    /** The nonce used for the current/last attempt. */
+    nonce?: string;
+    /** The backend's response on success. */
+    result?: WalletVerifyResult;
+    /** Connect-aware: false until a wallet is connected. */
+    ready: boolean;
+    verify: () => Promise<void>;
+    reset: () => void;
+    error?: Error;
+}
+/** The default signed-message prefix — matches the runtime `Gatekeeper` default. */
+export declare const DEFAULT_VERIFY_MESSAGE_PREFIX = "Link my wallet to this community \u00B7 nonce: ";
+/**
+ * Build the exact text to sign. A server-supplied message wins (guaranteed match);
+ * otherwise `message` (string or fn), otherwise `messagePrefix + nonce`. Pure —
+ * exported for testing and so callers can preview the message.
+ */
+export declare function buildVerifyMessage(opts: Pick<UseWalletVerifyOptions, "message" | "messagePrefix">, address: string, nonce: string, serverMessage?: string): string;
+/** Read success out of a verify response, accepting ok/verified/linked. Pure — tested. */
+export declare function isVerifySuccess(httpOk: boolean, json: Record<string, unknown>): boolean;
+/**
+ * Prove the connected wallet owns an address by signing an app-specific message and
+ * POSTing the proof to your backend (the frontend half of the runtime `Gatekeeper`:
+ * connect → sign(messagePrefix + nonce) → verifyAndLink). No gas, no transaction.
+ * Use `<WalletVerifyButton>` for a drop-in button, or this hook for custom UI.
+ */
+export declare function useWalletVerify(options?: UseWalletVerifyOptions): WalletVerifyState;

package/dist/verify/useWalletVerify.js

@@ -0,0 +1,104 @@
+import { useCallback, useState } from "react";
+import { useConnection, useSignMessage } from "wagmi";
+/** The default signed-message prefix — matches the runtime `Gatekeeper` default. */
+export const DEFAULT_VERIFY_MESSAGE_PREFIX = "Link my wallet to this community · nonce: ";
+/** Read the `?n=` nonce from the page URL (browser only). */
+function nonceFromUrl() {
+    if (typeof window === "undefined")
+        return undefined;
+    return new URLSearchParams(window.location.search).get("n") ?? undefined;
+}
+/**
+ * Build the exact text to sign. A server-supplied message wins (guaranteed match);
+ * otherwise `message` (string or fn), otherwise `messagePrefix + nonce`. Pure —
+ * exported for testing and so callers can preview the message.
+ */
+export function buildVerifyMessage(opts, address, nonce, serverMessage) {
+    if (serverMessage)
+        return serverMessage;
+    if (typeof opts.message === "function")
+        return opts.message(address, nonce);
+    if (typeof opts.message === "string")
+        return opts.message;
+    return (opts.messagePrefix ?? DEFAULT_VERIFY_MESSAGE_PREFIX) + nonce;
+}
+/** Read success out of a verify response, accepting ok/verified/linked. Pure — tested. */
+export function isVerifySuccess(httpOk, json) {
+    return httpOk && (json.ok === true || json.verified === true || json.linked === true);
+}
+/**
+ * Prove the connected wallet owns an address by signing an app-specific message and
+ * POSTing the proof to your backend (the frontend half of the runtime `Gatekeeper`:
+ * connect → sign(messagePrefix + nonce) → verifyAndLink). No gas, no transaction.
+ * Use `<WalletVerifyButton>` for a drop-in button, or this hook for custom UI.
+ */
+export function useWalletVerify(options = {}) {
+    const base = options.endpoint ?? "/api/verify";
+    const { address } = useConnection();
+    const { signMessageAsync } = useSignMessage();
+    const [status, setStatus] = useState("idle");
+    const [nonce, setNonce] = useState();
+    const [result, setResult] = useState();
+    const [error, setError] = useState();
+    const verify = useCallback(async () => {
+        if (!address) {
+            const e = new Error("Connect a wallet first.");
+            setError(e);
+            setStatus("error");
+            options.onError?.(e);
+            return;
+        }
+        setStatus("signing");
+        setError(undefined);
+        try {
+            // 1) Resolve the nonce: explicit option → ?n= link → mint from nonceEndpoint.
+            let n = options.nonce ?? nonceFromUrl();
+            let serverMessage;
+            if (!n && options.nonceEndpoint) {
+                const nr = await fetch(`${options.nonceEndpoint}?address=${address}`, {
+                    credentials: options.credentials ? "include" : "same-origin",
+                });
+                const nj = (await nr.json());
+                n = nj.nonce;
+                serverMessage = nj.message;
+            }
+            if (!n) {
+                throw new Error("No challenge nonce — pass `nonce`, open via a `?n=` link, or set `nonceEndpoint`.");
+            }
+            setNonce(n);
+            // 2) Sign the app-specific message (must match the backend's reconstruction).
+            const msg = buildVerifyMessage(options, address, n, serverMessage);
+            const signature = await signMessageAsync({ message: msg });
+            // 3) POST the proof to the backend (Gatekeeper.verifyAndLink).
+            setStatus("verifying");
+            const res = await fetch(base, {
+                method: "POST",
+                credentials: options.credentials ? "include" : "same-origin",
+                headers: { "content-type": "application/json" },
+                body: JSON.stringify({ nonce: n, address, signature }),
+            });
+            const j = (await res.json().catch(() => ({})));
+            if (!isVerifySuccess(res.ok, j)) {
+                throw new Error(j.error ?? "Verification failed");
+            }
+            const out = { ok: true, address, ...j };
+            setResult(out);
+            setStatus("verified");
+            options.onVerified?.(out);
+        }
+        catch (e) {
+            setError(e);
+            setStatus("error");
+            options.onError?.(e);
+        }
+        // options is intentionally read fresh each call (callbacks/config may change).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [address, base, signMessageAsync]);
+    const reset = useCallback(() => {
+        setStatus("idle");
+        setNonce(undefined);
+        setResult(undefined);
+        setError(undefined);
+    }, []);
+    return { status, address, nonce, result, ready: Boolean(address), verify, reset, error };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livo-build/kit",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Livo frontend kit — reusable React + wagmi v3 building blocks (wallet connect modal, providers, hooks) for web3 apps built on Livo.",
   "type": "module",
   "license": "UNLICENSED",