npm - @bufinance/kawaii-gate - Versions diffs - 0.1.0 - Mend

@bufinance/kawaii-gate 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "@bufinance/kawaii-gate",
+  "version": "0.1.0",
+  "type": "module",
+  "sideEffects": false,
+  "description": "Shared Kawaii Punk NFT access gate — the 'holders only' wall (wallet connect + on-chain mainnet-Avalanche ownership verify) for BUFI private-beta deploys. Self-contained + prop-driven so fx (defi-web) and desk-v1 share ONE gate. Ships the <KawaiiGate/> component, the HMAC cookie token, the /api/gate route handlers, and a middleware guard.",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./server": "./src/server.ts",
+    "./middleware": "./src/middleware.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test"
+  },
+  "peerDependencies": {
+    "next": ">=14",
+    "react": ">=18",
+    "react-dom": ">=18",
+    "viem": ">=2",
+    "wagmi": ">=2"
+  },
+  "devDependencies": {
+    "@types/react": "^19",
+    "bun-types": "1.3.10",
+    "next": "16.2.6",
+    "react": "^19",
+    "typescript": "5",
+    "viem": "2.45.3",
+    "wagmi": "2.14.11"
+  }
+}

package/src/component.tsx ADDED Viewed

@@ -0,0 +1,191 @@
+"use client";
+import { useEffect, useState, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import { useAccount, useConnect, useDisconnect, useSignMessage } from "wagmi";
+import { gateMessage } from "./message";
+function truncate(addr: string): string {
+  return addr.length > 10 ? `${addr.slice(0, 6)}…${addr.slice(-4)}` : addr;
+}
+export interface KawaiiGateProps {
+  /** Where to GET a nonce + POST the signed proof. Default "/api/gate". */
+  apiPath?: string;
+  /** Kawaii Punks logo (host provides the asset). Falls back to a 👻 if unset. */
+  logoSrc?: string;
+  /** "Mint a Kawaii Punk at …" link. Default https://fx.bu.finance. */
+  mintUrl?: string;
+  title?: string;
+  subtitle?: ReactNode;
+  /** Called after a successful verify; default reloads the page so the gate clears. */
+  onVerified?: () => void;
+}
+type Phase = "idle" | "verifying";
+/**
+ * KawaiiGate — the full-screen "holders only" wall. Connect a wallet, sign a
+ * nonce'd message, the host's /api/gate verifies on-chain Kawaii ownership and
+ * sets the cookie. Portals to <body> so it escapes the host layout's stacking
+ * context. Requires a wagmi provider in the tree.
+ */
+export function KawaiiGate({
+  apiPath = "/api/gate",
+  logoSrc,
+  mintUrl = "https://fx.bu.finance",
+  title = "Kawaii Punk holders only",
+  subtitle,
+  onVerified,
+}: KawaiiGateProps) {
+  const { address, isConnected } = useAccount();
+  const { connect, connectors, isPending: connecting } = useConnect();
+  const { disconnect } = useDisconnect();
+  const { signMessageAsync } = useSignMessage();
+  const [phase, setPhase] = useState<Phase>("idle");
+  const [error, setError] = useState<string | null>(null);
+  const [mounted, setMounted] = useState(false);
+  useEffect(() => setMounted(true), []);
+  // Dedupe wallets that announce twice (EIP-6963 + the legacy injected provider).
+  const wallets = (() => {
+    const seen = new Set<string>();
+    return connectors.filter((c) => {
+      const key = c.name.toLowerCase();
+      if (seen.has(key)) return false;
+      seen.add(key);
+      return true;
+    });
+  })();
+  async function verify() {
+    if (!address) return;
+    setError(null);
+    setPhase("verifying");
+    try {
+      const { nonce } = (await fetch(apiPath, { method: "GET" }).then((r) => r.json())) as {
+        nonce: string;
+      };
+      const issuedAt = Date.now();
+      const signature = await signMessageAsync({ message: gateMessage(address, nonce, issuedAt) });
+      const res = await fetch(apiPath, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify({ address, signature, issuedAt }),
+      });
+      const data = (await res.json().catch(() => ({}))) as { ok?: boolean; reason?: string; error?: string };
+      if (res.ok && data.ok) {
+        if (onVerified) onVerified();
+        else window.location.reload();
+        return;
+      }
+      setPhase("idle");
+      setError(
+        data.reason ||
+          (data.error === "not_holder"
+            ? "This wallet doesn't hold a Kawaii Punk on Avalanche."
+            : "Verification failed — please try again."),
+      );
+    } catch {
+      setPhase("idle");
+      setError("Signature cancelled or failed. Try again.");
+    }
+  }
+  const showConnected = isConnected && address;
+  const overlay = (
+    <div className="fixed inset-0 z-[9999] flex items-center justify-center overflow-auto bg-[#0b0320] p-6 text-white">
+      <div className="w-full max-w-lg rounded-3xl border border-white/10 bg-white/[0.03] p-8 backdrop-blur">
+        <div className="mb-6 text-center">
+          {logoSrc ? (
+            // eslint-disable-next-line @next/next/no-img-element
+            <img src={logoSrc} alt="Kawaii Punks" className="mx-auto mb-4 h-24 w-auto object-contain" />
+          ) : (
+            <div className="mx-auto mb-4 grid h-16 w-16 place-items-center rounded-2xl bg-purple-500/20 text-3xl">
+              👻
+            </div>
+          )}
+          <h1 className="text-2xl font-extrabold">{title}</h1>
+          <p className="mt-2 text-sm text-white/60">
+            {subtitle ?? (
+              <>
+                This is the BUFI private beta. Connect the wallet that holds your{" "}
+                <span className="font-semibold text-white/80">Kawaii Punk on Avalanche</span> to enter.
+              </>
+            )}
+          </p>
+        </div>
+        {!showConnected ? (
+          <div className="grid grid-cols-2 gap-2 sm:grid-cols-3">
+            {wallets.map((c) => {
+              const icon = (c as { icon?: string }).icon;
+              return (
+                <button
+                  key={c.uid}
+                  type="button"
+                  disabled={connecting}
+                  onClick={() => connect({ connector: c })}
+                  className="flex flex-col items-center justify-center gap-1.5 rounded-xl bg-purpleDanis px-2 py-3 text-xs font-bold text-white transition hover:brightness-110 disabled:opacity-50"
+                >
+                  {icon ? (
+                    // eslint-disable-next-line @next/next/no-img-element
+                    <img src={icon} alt="" className="h-6 w-6 rounded" />
+                  ) : (
+                    <span className="grid h-6 w-6 place-items-center rounded bg-white/20 text-[10px] uppercase">
+                      {c.name.slice(0, 2)}
+                    </span>
+                  )}
+                  <span className="w-full truncate text-center">{c.name}</span>
+                </button>
+              );
+            })}
+            {wallets.length === 0 && (
+              <p className="col-span-full text-center text-xs text-white/50">No wallet connector available.</p>
+            )}
+          </div>
+        ) : (
+          <div className="space-y-3">
+            <div className="flex items-center justify-between rounded-xl border border-white/10 bg-white/[0.04] px-4 py-3">
+              <span className="text-sm text-white/70">{truncate(address)}</span>
+              <button
+                type="button"
+                onClick={() => {
+                  disconnect();
+                  setError(null);
+                }}
+                className="text-xs text-white/50 underline hover:text-white/80"
+              >
+                Disconnect
+              </button>
+            </div>
+            <button
+              type="button"
+              disabled={phase === "verifying"}
+              onClick={verify}
+              className="w-full rounded-xl bg-purpleDanis px-4 py-3 text-sm font-bold transition hover:brightness-110 disabled:opacity-60"
+            >
+              {phase === "verifying" ? "Verifying ownership…" : "Verify & enter"}
+            </button>
+          </div>
+        )}
+        {error && (
+          <p className="mt-4 rounded-lg bg-red-500/10 px-3 py-2 text-center text-xs text-red-300">{error}</p>
+        )}
+        <p className="mt-6 text-center text-[11px] text-white/30">
+          Don&apos;t have one yet? Mint a Kawaii Punk at{" "}
+          <a href={mintUrl} className="underline hover:text-white/60">
+            {mintUrl.replace(/^https?:\/\//, "")}
+          </a>
+          .
+        </p>
+      </div>
+    </div>
+  );
+  return mounted ? createPortal(overlay, document.body) : null;
+}

package/src/handlers.ts ADDED Viewed

@@ -0,0 +1,96 @@
+import { NextResponse, type NextRequest } from "next/server";
+import { isAddress, recoverMessageAddress } from "viem";
+import { gateMessage } from "./message";
+import type { CheckHolder } from "./holder";
+import {
+  GATE_COOKIE,
+  GATE_NONCE_COOKIE,
+  GATE_TTL_MS,
+  GATE_MESSAGE_MAX_AGE_MS,
+  signGateToken,
+} from "./token";
+export interface GateHandlerOptions {
+  /** HMAC secret for the gate cookie. Keep identical between route + middleware. */
+  secret: string;
+  /** "Does this wallet hold a mainnet Kawaii Punk?" — see holder.ts. */
+  checkHolder: CheckHolder;
+  /**
+   * Override signature verification (e.g. to support ERC-1271 smart wallets via a
+   * chain client). Default: EOA recovery (recoverMessageAddress).
+   */
+  verifySignature?: (args: { address: string; message: string; signature: string }) => Promise<boolean>;
+  /** Cookie Domain (e.g. ".bu.finance" to share across subdomains). Default host-only. */
+  cookieDomain?: string;
+  /** Secure cookies. Default: production. */
+  secure?: boolean;
+}
+async function defaultVerify({ address, message, signature }: { address: string; message: string; signature: string }): Promise<boolean> {
+  try {
+    const recovered = await recoverMessageAddress({ message, signature: signature as `0x${string}` });
+    return recovered.toLowerCase() === address.toLowerCase();
+  } catch {
+    return false;
+  }
+}
+/**
+ * Build the GET (nonce) + POST (verify) handlers for `/api/gate`. Mount in the
+ * host app:  `export const { GET, POST } = createGateHandlers({ secret, checkHolder })`.
+ */
+export function createGateHandlers(opts: GateHandlerOptions) {
+  const verify = opts.verifySignature ?? defaultVerify;
+  const cookieBase = {
+    httpOnly: true,
+    secure: opts.secure ?? process.env.NODE_ENV === "production",
+    sameSite: "lax" as const,
+    path: "/",
+    ...(opts.cookieDomain ? { domain: opts.cookieDomain } : {}),
+  };
+  async function GET() {
+    const nonce = crypto.randomUUID();
+    const res = NextResponse.json({ nonce });
+    res.cookies.set(GATE_NONCE_COOKIE, nonce, { ...cookieBase, maxAge: 600 });
+    return res;
+  }
+  async function POST(req: NextRequest) {
+    let body: { address?: string; signature?: string; issuedAt?: number };
+    try {
+      body = await req.json();
+    } catch {
+      return NextResponse.json({ error: "bad_json" }, { status: 400 });
+    }
+    const { address, signature, issuedAt } = body;
+    if (!address || !isAddress(address) || !signature || typeof issuedAt !== "number") {
+      return NextResponse.json({ error: "bad_request" }, { status: 400 });
+    }
+    if (Math.abs(Date.now() - issuedAt) > GATE_MESSAGE_MAX_AGE_MS) {
+      return NextResponse.json({ error: "stale_message" }, { status: 400 });
+    }
+    const nonce = req.cookies.get(GATE_NONCE_COOKIE)?.value;
+    if (!nonce) return NextResponse.json({ error: "no_nonce" }, { status: 400 });
+    const message = gateMessage(address, nonce, issuedAt);
+    if (!(await verify({ address, message, signature }))) {
+      return NextResponse.json({ error: "bad_signature" }, { status: 401 });
+    }
+    if (!(await opts.checkHolder(address))) {
+      return NextResponse.json(
+        { error: "not_holder", reason: "This wallet doesn't hold a Kawaii Punk on Avalanche." },
+        { status: 403 },
+      );
+    }
+    const token = await signGateToken(address, opts.secret);
+    const res = NextResponse.json({ ok: true });
+    res.cookies.set(GATE_COOKIE, token, { ...cookieBase, maxAge: Math.floor(GATE_TTL_MS / 1000) });
+    res.cookies.set(GATE_NONCE_COOKIE, "", { ...cookieBase, maxAge: 0 });
+    return res;
+  }
+  return { GET, POST };
+}

package/src/holder.ts ADDED Viewed

@@ -0,0 +1,39 @@
+/**
+ * Holder check — "does this wallet hold a mainnet (Avalanche) Kawaii Punk?"
+ *
+ * App-agnostic by design: the package ships a default that queries a BUFI
+ * `/api/kawaii/status` endpoint (fx.bu.finance) so a consumer with NO on-chain
+ * pipeline of its own (e.g. desk-v1) works standalone. A consumer that already
+ * has the authoritative check (defi-web) passes its own `CheckHolder` instead.
+ */
+export type CheckHolder = (address: string) => Promise<boolean>;
+interface StatusResponse {
+  hasNft?: boolean;
+  tier?: string | null;
+  chainId?: number | null;
+}
+/**
+ * Default check: GET `${baseUrl}/api/kawaii/status?wallet=…` and require a
+ * MAINNET (Avalanche 43114) Kawaii Punk. Fails closed on a non-OK response or a
+ * network error (never grants access on a blip). `baseUrl` defaults to the live
+ * fx app, which is the source of truth for the on-chain ownership read.
+ */
+export function statusEndpointChecker(baseUrl = "https://fx.bu.finance"): CheckHolder {
+  const base = baseUrl.replace(/\/+$/, "");
+  return async (address: string): Promise<boolean> => {
+    try {
+      const res = await fetch(`${base}/api/kawaii/status?wallet=${address}`, {
+        cache: "no-store",
+        headers: { accept: "application/json" },
+      });
+      if (!res.ok) return false;
+      const d = (await res.json()) as StatusResponse;
+      return d.hasNft === true && (d.tier === "mainnet" || d.chainId === 43114);
+    } catch {
+      return false;
+    }
+  };
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,3 @@
+// Client entry — the gate UI + the shared signed-message format.
+export { KawaiiGate, type KawaiiGateProps } from "./component";
+export { gateMessage } from "./message";

package/src/message.ts ADDED Viewed

@@ -0,0 +1,13 @@
+/**
+ * The exact message a wallet signs to prove control of `address`. Shared by the
+ * <KawaiiGate/> client (to sign) and the verify handler (to reconstruct) so the
+ * two produce byte-identical strings. Pure — safe to import client-side.
+ */
+export function gateMessage(address: string, nonce: string, issuedAtMs: number): string {
+  return [
+    "BUFI beta access — verify you hold a Kawaii Punk (Avalanche mainnet).",
+    `Wallet: ${address.toLowerCase()}`,
+    `Nonce: ${nonce}`,
+    `Issued: ${new Date(issuedAtMs).toISOString()}`,
+  ].join("\n");
+}

package/src/middleware.ts ADDED Viewed

@@ -0,0 +1,33 @@
+import type { NextRequest } from "next/server";
+import { GATE_COOKIE, verifyGateToken } from "./token";
+export interface GateGuardOptions {
+  /** HMAC secret — identical to the one the /api/gate handlers use. */
+  secret: string;
+  /** Hosts behind the gate (e.g. ["kawaii-beta.bu.finance"]). */
+  gatedHosts: Iterable<string>;
+  /** Paths that stay reachable so a visitor can verify. Default: the gate API + OG. */
+  exemptPaths?: string[];
+}
+/**
+ * Returns true when this request must be sent to the gate: it's for a gated host,
+ * the path isn't exempt, and there's no valid gate cookie. Edge-safe. The host app
+ * does the actual rewrite (it owns its gate route + locale handling), e.g.:
+ *
+ *   if (await shouldGate(req, { secret, gatedHosts: ["kawaii-beta.bu.finance"] })) {
+ *     return NextResponse.rewrite(new URL(`/${locale}/gate`, req.url));
+ *   }
+ */
+export async function shouldGate(req: NextRequest, opts: GateGuardOptions): Promise<boolean> {
+  const hosts = opts.gatedHosts instanceof Set ? opts.gatedHosts : new Set(opts.gatedHosts);
+  const host = (req.headers.get("host") ?? req.nextUrl.hostname).split(":")[0].toLowerCase();
+  if (!hosts.has(host)) return false;
+  const { pathname } = req.nextUrl;
+  const exempt = opts.exemptPaths ?? ["/api/gate", "/api/og/"];
+  if (exempt.some((p) => pathname === p || pathname.startsWith(p))) return false;
+  return !(await verifyGateToken(req.cookies.get(GATE_COOKIE)?.value, opts.secret));
+}

package/src/server.ts ADDED Viewed

@@ -0,0 +1,14 @@
+// Server entry — the /api/gate handlers, the holder check, and the cookie token.
+// (The edge middleware guard is a separate, edge-safe entry: "@bufinance/kawaii-gate/middleware".)
+export { createGateHandlers, type GateHandlerOptions } from "./handlers";
+export { statusEndpointChecker, type CheckHolder } from "./holder";
+export { gateMessage } from "./message";
+export {
+  GATE_COOKIE,
+  GATE_NONCE_COOKIE,
+  GATE_TTL_MS,
+  GATE_MESSAGE_MAX_AGE_MS,
+  hmacHex,
+  signGateToken,
+  verifyGateToken,
+} from "./token";

package/src/token.test.ts ADDED Viewed

@@ -0,0 +1,36 @@
+import { describe, expect, test } from "bun:test";
+import { GATE_TTL_MS, signGateToken, verifyGateToken } from "./token";
+const SECRET = "test-secret-key";
+const ADDR = "0xC6ee3c13214A37e66f3d2eE477c3205e89a99b38";
+describe("@bufinance/kawaii-gate token — HMAC roundtrip", () => {
+  test("sign → verify returns the lowercased address", async () => {
+    const t = await signGateToken(ADDR, SECRET, 1_000_000);
+    expect(await verifyGateToken(t, SECRET, 1_000_500)).toBe(ADDR.toLowerCase());
+  });
+  test("a different secret never verifies", async () => {
+    const t = await signGateToken(ADDR, SECRET, 1_000_000);
+    expect(await verifyGateToken(t, "other-secret", 1_000_500)).toBeNull();
+  });
+  test("expired token is rejected", async () => {
+    const now = 1_000_000;
+    const t = await signGateToken(ADDR, SECRET, now);
+    expect(await verifyGateToken(t, SECRET, now + GATE_TTL_MS + 1)).toBeNull();
+  });
+  test("tampered signature is rejected", async () => {
+    const t = await signGateToken(ADDR, SECRET, 1_000_000);
+    const [, exp, sig] = t.split(".");
+    const flipped = (sig[0] === "0" ? "1" : "0") + sig.slice(1);
+    expect(await verifyGateToken(`${ADDR.toLowerCase()}.${exp}.${flipped}`, SECRET, 1_000_500)).toBeNull();
+  });
+  test("malformed tokens are rejected (no throw)", async () => {
+    expect(await verifyGateToken(undefined, SECRET)).toBeNull();
+    expect(await verifyGateToken("a.b", SECRET)).toBeNull();
+  });
+});

package/src/token.ts ADDED Viewed

@@ -0,0 +1,72 @@
+/**
+ * Beta-gate cookie token — an HMAC-signed `<address>.<exp>.<hexsig>` proving a
+ * wallet passed the Kawaii ownership check. Tamper-proof (signed with a host
+ * secret) so a non-holder can't forge access. Plain hex/decimal so the SAME
+ * token verifies in BOTH Node (the route) and the Edge middleware (Web Crypto).
+ */
+export const GATE_COOKIE = "bufi_beta_gate";
+/** Nonce cookie set by GET /api/gate, consumed once by POST (anti-replay). */
+export const GATE_NONCE_COOKIE = "bufi_beta_nonce";
+export const GATE_TTL_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+export const GATE_MESSAGE_MAX_AGE_MS = 10 * 60 * 1000; // 10 min
+function hex(bytes: ArrayBuffer | Uint8Array): string {
+  const u8 = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+  let s = "";
+  for (const b of u8) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+/** HMAC-SHA256(message, secret) → hex, via Web Crypto (Node 20+ and Edge). */
+export async function hmacHex(message: string, secret: string): Promise<string> {
+  const enc = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    "raw",
+    enc.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"],
+  );
+  const sig = await crypto.subtle.sign("HMAC", key, enc.encode(message));
+  return hex(sig);
+}
+/** Mint a signed gate token for `address`. */
+export async function signGateToken(
+  address: string,
+  secret: string,
+  now: number = Date.now(),
+): Promise<string> {
+  const addr = address.toLowerCase();
+  const exp = now + GATE_TTL_MS;
+  const sig = await hmacHex(`${addr}:${exp}`, secret);
+  return `${addr}.${exp}.${sig}`;
+}
+/**
+ * Verify a gate token. Returns the verified lowercase address, or null if it's
+ * malformed, expired, or the signature doesn't match. Edge- and Node-safe.
+ */
+export async function verifyGateToken(
+  token: string | undefined | null,
+  secret: string,
+  now: number = Date.now(),
+): Promise<string | null> {
+  if (!token) return null;
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const [addr, expStr, sig] = parts;
+  const exp = Number(expStr);
+  if (!addr || !Number.isFinite(exp) || exp < now) return null;
+  const expected = await hmacHex(`${addr}:${exp}`, secret);
+  if (!safeEqual(expected, sig)) return null;
+  return addr;
+}

package/tsconfig.json ADDED Viewed

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "types": ["bun-types"]
+  },
+  "include": ["src"]
+}