@gesturegate/sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,146 @@
+import { type Address, type Hex, type PublicClient } from "viem";
+export declare const monadTestnetChainId = 10143;
+export declare const gestureGateIntentDomain: {
+    readonly name: "GestureGate";
+    readonly version: "1";
+    readonly chainId: 10143;
+};
+export declare const gestureGateIntentTypes: {
+    readonly GateIntent: readonly [{
+        readonly name: "subject";
+        readonly type: "address";
+    }, {
+        readonly name: "action";
+        readonly type: "string";
+    }, {
+        readonly name: "nonce";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "expiresAt";
+        readonly type: "uint256";
+    }];
+};
+export declare const gestureGateRegistryAbi: readonly [{
+    readonly type: "function";
+    readonly name: "isVerifiedWithin";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "subject";
+        readonly type: "address";
+    }, {
+        readonly name: "maxAge";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+export type SignTypedData = (args: {
+    domain: typeof gestureGateIntentDomain;
+    types: typeof gestureGateIntentTypes;
+    primaryType: "GateIntent";
+    message: {
+        subject: Address;
+        action: "REQUEST_CHALLENGE";
+        nonce: Hex;
+        expiresAt: bigint;
+    };
+}) => Promise<Hex>;
+export type HostedStart = {
+    challengeId: string;
+    expiresAt: string;
+    transactionHash: Hex;
+    verifyUrl: string;
+};
+export type HostedVerifiedMessage = {
+    type: "gesturegate:verified";
+    challengeId: string;
+    transactionHash: Hex;
+};
+export type VerificationCheck = {
+    publicClient: PublicClient;
+    registryAddress: Address;
+    address: Address;
+    ttlSeconds: number;
+};
+export type VerificationStatus = Pick<VerificationCheck, "address" | "ttlSeconds"> & {
+    isVerified: boolean;
+};
+export type EnsureVerifiedOptions = VerificationCheck & {
+    apiOrigin: string;
+    signTypedData: SignTypedData;
+    popupName?: string;
+    popupFeatures?: string;
+};
+export type GestureGateClientOptions = Omit<VerificationCheck, "address" | "ttlSeconds"> & {
+    apiOrigin: string;
+    defaultTtlSeconds: number;
+};
+export declare function createChallengeIntent(subject: Address, signTypedData: SignTypedData, now?: number): Promise<{
+    subject: `0x${string}`;
+    nonce: `0x${string}`;
+    expiresAt: string;
+    signature: `0x${string}`;
+}>;
+export declare function startHostedVerification(options: {
+    apiOrigin: string;
+    address: Address;
+    signTypedData: SignTypedData;
+}): Promise<{
+    challengeId: string;
+    expiresAt: string;
+    transactionHash: `0x${string}`;
+    verifyUrl: string;
+}>;
+export declare function isVerifiedWithin(options: VerificationCheck): Promise<boolean>;
+/** Returns an explicit address-bound status for application UI and guards. */
+export declare function getVerificationStatus(options: VerificationCheck): Promise<VerificationStatus>;
+export declare function openHostedVerification(options: {
+    apiOrigin: string;
+    address: Address;
+    signTypedData: SignTypedData;
+    popupName?: string;
+    popupFeatures?: string;
+}): Promise<HostedVerifiedMessage>;
+/**
+ * The complete dApp lifecycle: check the registry, open the hosted flow only
+ * when stale, then read the registry again before the protected action.
+ */
+export declare function ensureVerified(options: EnsureVerifiedOptions): Promise<{
+    status: VerificationStatus;
+    wasAlreadyVerified: boolean;
+    transactionHash: undefined;
+} | {
+    status: VerificationStatus;
+    wasAlreadyVerified: boolean;
+    transactionHash: `0x${string}`;
+}>;
+/**
+ * A framework-neutral facade. Construct it once with shared network settings;
+ * each call only needs the user's address and, for verification, their signer.
+ */
+export declare function createGestureGateClient(options: GestureGateClientOptions): Readonly<{
+    check: (address: Address, ttlSeconds?: number) => Promise<VerificationStatus>;
+    open: (input: {
+        address: Address;
+        signTypedData: SignTypedData;
+        popupName?: string;
+        popupFeatures?: string;
+    }) => Promise<HostedVerifiedMessage>;
+    ensureVerified: (input: {
+        address: Address;
+        signTypedData: SignTypedData;
+        ttlSeconds?: number;
+        popupName?: string;
+        popupFeatures?: string;
+    }) => Promise<{
+        status: VerificationStatus;
+        wasAlreadyVerified: boolean;
+        transactionHash: undefined;
+    } | {
+        status: VerificationStatus;
+        wasAlreadyVerified: boolean;
+        transactionHash: `0x${string}`;
+    }>;
+}>;
+//# 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":"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"}

package/dist/index.js

@@ -0,0 +1,170 @@
+import { keccak256, toHex } from "viem";
+export const monadTestnetChainId = 10143;
+export const gestureGateIntentDomain = {
+    name: "GestureGate",
+    version: "1",
+    chainId: monadTestnetChainId,
+};
+export const gestureGateIntentTypes = {
+    GateIntent: [
+        { name: "subject", type: "address" },
+        { name: "action", type: "string" },
+        { name: "nonce", type: "bytes32" },
+        { name: "expiresAt", type: "uint256" },
+    ],
+};
+export const gestureGateRegistryAbi = [{
+        type: "function",
+        name: "isVerifiedWithin",
+        stateMutability: "view",
+        inputs: [{ name: "subject", type: "address" }, { name: "maxAge", type: "uint256" }],
+        outputs: [{ type: "bool" }],
+    }];
+function randomNonce() {
+    if (!globalThis.crypto?.getRandomValues)
+        throw new Error("A secure browser crypto API is required to start GestureGate verification.");
+    const bytes = new Uint8Array(32);
+    globalThis.crypto.getRandomValues(bytes);
+    return keccak256(toHex(bytes));
+}
+function apiPath(apiOrigin, path) {
+    return `${apiOrigin.replace(/\/$/, "")}${path}`;
+}
+export async function createChallengeIntent(subject, signTypedData, now = Date.now()) {
+    const expiresAt = BigInt(Math.floor(now / 1_000) + 180);
+    const nonce = randomNonce();
+    const signature = await signTypedData({
+        domain: gestureGateIntentDomain,
+        types: gestureGateIntentTypes,
+        primaryType: "GateIntent",
+        message: { subject, action: "REQUEST_CHALLENGE", nonce, expiresAt },
+    });
+    return { subject, nonce, expiresAt: expiresAt.toString(), signature };
+}
+export async function startHostedVerification(options) {
+    const intent = await createChallengeIntent(options.address, options.signTypedData);
+    const response = await fetch(apiPath(options.apiOrigin, "/api/challenges"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(intent),
+    });
+    const result = await response.json();
+    if (!response.ok)
+        throw new Error(result.error ?? "GestureGate could not start verification.");
+    if (!result.challengeId || !result.expiresAt || !result.transactionHash || !result.verifyUrl) {
+        throw new Error("GestureGate returned an incomplete verification session.");
+    }
+    // The API also returns an inline-flow session token. Hosted partners never
+    // need it, so deliberately keep it out of the SDK result.
+    return {
+        challengeId: result.challengeId,
+        expiresAt: result.expiresAt,
+        transactionHash: result.transactionHash,
+        verifyUrl: result.verifyUrl,
+    };
+}
+export async function isVerifiedWithin(options) {
+    if (!Number.isInteger(options.ttlSeconds) || options.ttlSeconds <= 0) {
+        throw new Error("ttlSeconds must be a positive whole number.");
+    }
+    return options.publicClient.readContract({
+        address: options.registryAddress,
+        abi: gestureGateRegistryAbi,
+        functionName: "isVerifiedWithin",
+        args: [options.address, BigInt(options.ttlSeconds)],
+    });
+}
+/** Returns an explicit address-bound status for application UI and guards. */
+export async function getVerificationStatus(options) {
+    return {
+        address: options.address,
+        ttlSeconds: options.ttlSeconds,
+        isVerified: await isVerifiedWithin(options),
+    };
+}
+export async function openHostedVerification(options) {
+    if (typeof window === "undefined")
+        throw new Error("Hosted verification must be opened in the user's browser.");
+    // Opening this synchronously keeps browsers from blocking the popup while the
+    // wallet signature is pending.
+    const popup = window.open("about:blank", options.popupName ?? "gesturegate_verify", options.popupFeatures ?? "popup,width=520,height=760");
+    if (!popup)
+        throw new Error("Popup was blocked. Allow popups to verify with GestureGate.");
+    try {
+        const start = await startHostedVerification(options);
+        popup.location.assign(start.verifyUrl);
+        const expectedOrigin = new URL(options.apiOrigin).origin;
+        return await new Promise((resolve, reject) => {
+            const closeTimer = window.setInterval(() => {
+                if (popup.closed) {
+                    cleanup();
+                    reject(new Error("GestureGate verification window was closed."));
+                }
+            }, 500);
+            const timeout = window.setTimeout(() => {
+                cleanup();
+                reject(new Error("GestureGate verification expired. Start a new challenge."));
+            }, Math.max(1_000, Number(start.expiresAt) * 1_000 - Date.now() + 5_000));
+            const onMessage = (event) => {
+                if (event.origin !== expectedOrigin || event.data?.type !== "gesturegate:verified")
+                    return;
+                cleanup();
+                resolve(event.data);
+            };
+            const cleanup = () => {
+                window.clearInterval(closeTimer);
+                window.clearTimeout(timeout);
+                window.removeEventListener("message", onMessage);
+            };
+            window.addEventListener("message", onMessage);
+        });
+    }
+    catch (error) {
+        popup.close();
+        throw error;
+    }
+}
+/**
+ * The complete dApp lifecycle: check the registry, open the hosted flow only
+ * when stale, then read the registry again before the protected action.
+ */
+export async function ensureVerified(options) {
+    const before = await getVerificationStatus(options);
+    if (before.isVerified)
+        return { status: before, wasAlreadyVerified: true, transactionHash: undefined };
+    const completion = await openHostedVerification(options);
+    const status = await getVerificationStatus(options);
+    if (!status.isVerified) {
+        throw new Error("GestureGate completed but the verification is not fresh onchain. Please retry your action.");
+    }
+    return { status, wasAlreadyVerified: false, transactionHash: completion.transactionHash };
+}
+/**
+ * A framework-neutral facade. Construct it once with shared network settings;
+ * each call only needs the user's address and, for verification, their signer.
+ */
+export function createGestureGateClient(options) {
+    if (!Number.isInteger(options.defaultTtlSeconds) || options.defaultTtlSeconds <= 0) {
+        throw new Error("defaultTtlSeconds must be a positive whole number.");
+    }
+    const check = (address, ttlSeconds = options.defaultTtlSeconds) => getVerificationStatus({
+        publicClient: options.publicClient,
+        registryAddress: options.registryAddress,
+        address,
+        ttlSeconds,
+    });
+    return Object.freeze({
+        check,
+        open: (input) => openHostedVerification({
+            apiOrigin: options.apiOrigin,
+            ...input,
+        }),
+        ensureVerified: (input) => ensureVerified({
+            publicClient: options.publicClient,
+            registryAddress: options.registryAddress,
+            apiOrigin: options.apiOrigin,
+            ttlSeconds: input.ttlSeconds ?? options.defaultTtlSeconds,
+            ...input,
+        }),
+    });
+}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@gesturegate/sdk",
+  "version": "0.1.0",
+  "description": "Framework-neutral hosted verification client for GestureGate on Monad.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "keywords": ["captcha", "human-verification", "monad", "viem", "web3"],
+  "files": ["dist"],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "viem": ">=2.0.0"
+  }
+}