@meddleware/nft-gate-client 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.1] - 2026-08-27
+
+### Added
+
+- Initial release as `@meddleware/nft-gate-client`
+- `ownsAccessNft`, `fetchAccessNfts`, `fetchAccessNftById`, `parseOwnedAccessNft` — on-chain ownership queries via `@mysten/sui`
+- `buildPurchaseTx`, `buildConsumeTx`, `buildCreateGateTx` — PTB builders for purchase, single-use consume, and gate creation
+- `fetchChallenge` — `GET /v1/challenge` client for the nft-gate gateway wire protocol
+- `personalMessageForNonce`, `buildAccessProof`, `encodeAccessProof`, `decodeAccessProof` — challenge signing and proof token construction
+- Wire protocol compatible with both the Rust/Axum gateway and the Cloudflare Workers gateway in `meddleware-org/nft-gate`

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 MeddleWare
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,140 @@
+# @meddleware/nft-gate-client
+
+[![License: 0BSD](https://img.shields.io/badge/License-0BSD-blue.svg)](LICENSE)
+
+Client-side TypeScript helpers for the `access_gate` NFT access primitive on Sui. Browser-safe (runs in a wallet app) and Node-friendly. **Client-side only** — server-side verification is provided by the [nft-gate](https://github.com/meddleware-org/nft-gate) service (Rust/Axum gateway or Cloudflare Workers equivalent).
+
+## Install
+
+```bash
+npm install @meddleware/nft-gate-client
+```
+
+## API
+
+```ts
+import {
+  ownsAccessNft, fetchAccessNfts,                // ownership queries
+  buildPurchaseTx, buildConsumeTx,               // PTB builders (wallet signs + executes)
+  fetchChallenge,                                 // GET /v1/challenge
+  buildAccessProof, personalMessageForNonce,      // challenge signing + proof token
+} from '@meddleware/nft-gate-client'
+
+const cfg = { packageId, gateId, nftType, soulbound: true }
+
+// 1. Check whether the connected wallet has access:
+const hasAccess = await ownsAccessNft(suiClient, address, cfg.nftType, cfg.gateId)
+
+// 2. Purchase access if not:
+const tx = buildPurchaseTx(cfg, priceMist)       // wallet signs & executes
+
+// 3. Prove access to a gateway (single-use: submit buildConsumeTx first):
+const challenge = await fetchChallenge(gatewayHost)
+const token = await buildAccessProof({ address, challenge, sign, consumeDigest })
+// pass `token` as the relay/gateway Authorization: Bearer header
+```
+
+## API Reference
+
+### Ownership
+
+**`ownsAccessNft(client, address, nftType, gateId): Promise<boolean>`**
+
+Returns `true` if the address holds at least one unexpired access NFT matching the gate.
+
+**`fetchAccessNfts(client, address, nftType): Promise<OwnedAccessNft[]>`**
+
+Returns all access NFTs owned by an address for a given struct type.
+
+**`fetchAccessNftById(client, objectId): Promise<OwnedAccessNft | null>`**
+
+Fetch a single access NFT by object ID.
+
+**`parseOwnedAccessNft(object): OwnedAccessNft | null`**
+
+Parse a raw `SuiObjectResponse` into an `OwnedAccessNft`. Returns `null` if the object is not a valid access NFT.
+
+### PTB Builders
+
+**`buildPurchaseTx(config, priceMist): Transaction`**
+
+Build a transaction to purchase an access NFT. Caller signs and executes with their wallet.
+
+**`buildConsumeTx(config, nftObjectId): Transaction`**
+
+Build a transaction to consume (burn) a single-use access NFT, proving use. Submit before calling `buildAccessProof` with the resulting `consumeDigest`.
+
+**`buildCreateGateTx(config): Transaction`**
+
+Build a transaction to create a new access gate on-chain (admin operation).
+
+### Challenge & Proof
+
+**`fetchChallenge(gatewayHost, opts?): Promise<Challenge>`**
+
+Fetch a time-bound nonce from the gateway's `GET /v1/challenge` endpoint.
+
+**`personalMessageForNonce(nonce): Uint8Array`**
+
+Returns the exact bytes the wallet must sign for a nonce. Matches the gateway's derivation: `nft-gate:access:<nonce>`.
+
+**`buildAccessProof(opts): Promise<string>`**
+
+One-shot helper: sign the challenge with the wallet and return the base64(JSON) Bearer token to pass to the gateway or relay.
+
+**`encodeAccessProof(proof: AccessProof): string`**
+
+Encode a proof struct directly to a base64(JSON) token (lower-level, sync).
+
+**`decodeAccessProof(token: string): AccessProof`**
+
+Decode a base64(JSON) token back to a proof struct.
+
+## Wire protocol
+
+- **Challenge**: `{ nonce: string, expiresAt: number }`
+- **Signed message**: `nft-gate:access:<nonce>` (UTF-8 bytes)
+- **Proof token**: `base64(JSON { address, nonce, signature, consumeDigest? })`
+
+This format is verified by both the Rust gateway and the Cloudflare Workers gateway in the [nft-gate](https://github.com/meddleware-org/nft-gate) repo.
+
+## Types
+
+```ts
+interface AccessGateConfig {
+  packageId: string
+  gateId: string
+  nftType: string
+  soulbound: boolean
+}
+
+interface Challenge {
+  nonce: string
+  expiresAt: number
+}
+
+interface AccessProof {
+  address: string
+  nonce: string
+  signature: string
+  consumeDigest?: string
+}
+
+interface OwnedAccessNft {
+  objectId: string
+  gateId: string
+  expiresAt?: number
+}
+```
+
+## Development
+
+```bash
+npm run type-check   # tsc --noEmit
+npm test             # vitest run (19 unit tests)
+npm run test:watch   # vitest interactive
+```
+
+## License
+
+[0BSD](LICENSE)

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@meddleware/nft-gate-client",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Client-side helpers for the access_gate NFT access primitive: ownership queries, purchase/consume PTB builders, challenge signing, and access-proof assembly.",
+  "author": "MeddleWare <meddleware@proton.me>",
+  "license": "0BSD",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/meddleware-org/nft-gate-client.git"
+  },
+  "keywords": ["sui", "nft", "access-control", "web3", "move"],
+  "files": [
+    "src",
+    "CHANGELOG.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "@mysten/sui": "~2.17.0"
+  },
+  "devDependencies": {
+    "@types/node": "~24.12.2",
+    "typescript": "~6.0.3",
+    "vitest": "~4.1.10"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/challenge.ts

@@ -0,0 +1,19 @@
+import type { Challenge } from './types.js'
+
+/**
+ * Fetch a fresh challenge from a gateway's `GET /v1/challenge` endpoint. Tolerates both
+ * `expiresAt` (camelCase) and `expires_at` (snake_case) response shapes.
+ */
+export async function fetchChallenge(
+  gatewayHost: string,
+  opts: { signal?: AbortSignal } = {},
+): Promise<Challenge> {
+  const res = await fetch(`${gatewayHost.replace(/\/$/, '')}/v1/challenge`, {
+    signal: opts.signal,
+  })
+  if (!res.ok) throw new Error(`challenge request failed: ${res.status}`)
+  const data = (await res.json()) as { nonce?: string; expiresAt?: number; expires_at?: number }
+  if (!data || typeof data.nonce !== 'string') throw new Error('challenge response missing nonce')
+  const expiresAt = data.expiresAt ?? data.expires_at ?? 0
+  return { nonce: data.nonce, expiresAt }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+/**
+ * `@meddleware/nft-gate-client` — client-side helpers for the `access_gate` primitive.
+ *
+ * Client-side only: ownership queries, purchase/consume PTB builders, challenge signing,
+ * and access-proof assembly. Server-side verification lives in the Rust gateway.
+ */
+
+export type {
+  AccessGateConfig,
+  Challenge,
+  AccessProof,
+  OwnedAccessNft,
+  OwnedObjectsClient,
+  SuiObjectClient,
+} from './types.js'
+
+export { fetchAccessNfts, ownsAccessNft, parseOwnedAccessNft, fetchAccessNftById } from './ownership.js'
+export { buildPurchaseTx, buildConsumeTx, buildCreateGateTx } from './ptb.js'
+export { fetchChallenge } from './challenge.js'
+export {
+  personalMessageForNonce,
+  encodeAccessProof,
+  decodeAccessProof,
+  buildAccessProof,
+} from './proof.js'
+export type { PersonalMessageSigner } from './proof.js'

package/src/ownership.ts

@@ -0,0 +1,99 @@
+import type { OwnedAccessNft, OwnedObjectsClient, SuiObjectClient } from './types.js'
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+/**
+ * Extract `uses_remaining` from a Move enum `AccessVariant` as rendered by RPC, driven by the
+ * enum **variant tag** (typed) rather than guessing from field presence. Sui renders a Move
+ * enum as `{ variant: 'SingleUse' | 'UnlimitedPass', fields: {...} }`. Returns `null` for an
+ * unlimited pass; the remaining count for a single-use.
+ */
+function parseUsesRemaining(variant: any): number | null {
+  if (variant == null) return null
+  const tag: string | undefined = variant.variant ?? variant.type ?? variant.$kind
+  if (tag === 'UnlimitedPass') return null
+  const fields = variant.fields ?? variant
+  const ur = fields?.uses_remaining ?? fields?.SingleUse?.uses_remaining
+  if (ur != null) return Number(ur)
+  // Tagged SingleUse but the count is missing from this node's rendering — unknown, not a pass.
+  return tag === 'SingleUse' ? null : null
+}
+
+/** True if `type` names an `access_gate` NFT struct (transferable or soulbound). */
+function isAccessNftType(type: unknown): boolean {
+  return typeof type === 'string' && /::access_gate::(Soulbound)?AccessNFT\b/.test(type)
+}
+
+/**
+ * Parse a single `getOwnedObjects`/`getObject` entry into an {@link OwnedAccessNft}, or `null`
+ * if it is not an access NFT. Validates the object **type** when present (typed), and reads the
+ * nested `data.fields` deterministically.
+ */
+export function parseOwnedAccessNft(entry: any): OwnedAccessNft | null {
+  const obj = entry?.data ?? entry
+  const objectId: string | undefined = obj?.objectId ?? obj?.content?.fields?.id?.id
+  const type: unknown = obj?.type ?? obj?.content?.type
+  // When the type is present it MUST be an access NFT; when absent (some node shapes) fall back
+  // to structural checks below.
+  if (type !== undefined && !isAccessNftType(type)) return null
+  const inner = obj?.content?.fields?.data?.fields
+  const gateId: string | undefined = inner?.gate_id ?? inner?.gateId
+  if (!objectId || !gateId) return null
+  return {
+    objectId,
+    gateId,
+    usesRemaining: parseUsesRemaining(inner?.variant),
+  }
+}
+
+/**
+ * Typed single-object read of one access NFT by id (`getObject` with `showType`+`showContent`),
+ * used when a UI needs the **exact** `usesRemaining` reliably rather than the best-effort parse
+ * of an owned-objects page. Returns `null` if the object is missing or not an access NFT.
+ */
+export async function fetchAccessNftById(
+  client: SuiObjectClient,
+  objectId: string,
+): Promise<OwnedAccessNft | null> {
+  const res = await client.getObject({
+    id: objectId,
+    options: { showType: true, showContent: true },
+  })
+  return parseOwnedAccessNft(res)
+}
+
+/**
+ * Fetch all access NFTs of `nftType` owned by `owner`, optionally restricted to a specific
+ * `gateId`. Uses `getOwnedObjects` filtered by `StructType` (the standard owned-objects query).
+ */
+export async function fetchAccessNfts(
+  client: OwnedObjectsClient,
+  owner: string,
+  nftType: string,
+  gateId?: string,
+): Promise<OwnedAccessNft[]> {
+  const { data } = await client.getOwnedObjects({
+    owner,
+    filter: { StructType: nftType },
+    options: { showContent: true, showType: true },
+  })
+  const parsed = (data ?? [])
+    .map(parseOwnedAccessNft)
+    .filter((n): n is OwnedAccessNft => n !== null)
+  return gateId ? parsed.filter((n) => n.gateId === gateId) : parsed
+}
+
+/**
+ * True if `owner` holds at least one access NFT of `nftType` (optionally for `gateId`).
+ * This is the cheap check a frontend runs to decide whether to show a gated option, and a
+ * gateway runs (server-side) as part of access verification.
+ */
+export async function ownsAccessNft(
+  client: OwnedObjectsClient,
+  owner: string,
+  nftType: string,
+  gateId?: string,
+): Promise<boolean> {
+  const nfts = await fetchAccessNfts(client, owner, nftType, gateId)
+  return nfts.length > 0
+}

package/src/proof.ts

@@ -0,0 +1,57 @@
+import type { AccessProof, Challenge } from './types.js'
+
+/**
+ * The exact bytes a wallet signs (as a personal message) to answer a challenge. Both the
+ * client (signing) and the gateway (verifying) MUST derive the message identically.
+ */
+export function personalMessageForNonce(nonce: string): Uint8Array {
+  return new TextEncoder().encode(`nft-gate:access:${nonce}`)
+}
+
+function toBase64(s: string): string {
+  // Works in browsers and modern Node (globalThis.btoa is available on Node >= 16).
+  if (typeof btoa === 'function') return btoa(s)
+  return Buffer.from(s, 'utf-8').toString('base64')
+}
+
+function fromBase64(s: string): string {
+  if (typeof atob === 'function') return atob(s)
+  return Buffer.from(s, 'base64').toString('utf-8')
+}
+
+/** Encode a proof as the compact Bearer token carried in the relay auth header. */
+export function encodeAccessProof(proof: AccessProof): string {
+  return toBase64(JSON.stringify(proof))
+}
+
+/** Decode a proof token produced by {@link encodeAccessProof}. Throws on malformed input. */
+export function decodeAccessProof(token: string): AccessProof {
+  const raw = JSON.parse(fromBase64(token)) as Partial<AccessProof>
+  if (!raw || typeof raw.address !== 'string' || typeof raw.nonce !== 'string' || typeof raw.signature !== 'string') {
+    throw new Error('malformed access proof')
+  }
+  const proof: AccessProof = { address: raw.address, nonce: raw.nonce, signature: raw.signature }
+  if (typeof raw.consumeDigest === 'string') proof.consumeDigest = raw.consumeDigest
+  return proof
+}
+
+/** A wallet-provided personal-message signer (e.g. wallet-standard `sui:signPersonalMessage`). */
+export type PersonalMessageSigner = (message: Uint8Array) => Promise<{ signature: string }>
+
+/**
+ * Sign a challenge and assemble the encoded access-proof token to hand to any gateway as its
+ * auth bearer (e.g. an upload-relay client's auth-token option, an `Authorization` header).
+ */
+export async function buildAccessProof(opts: {
+  address: string
+  challenge: Challenge
+  sign: PersonalMessageSigner
+  /** Present for single-use gates: the `consume` tx digest. */
+  consumeDigest?: string
+}): Promise<string> {
+  const message = personalMessageForNonce(opts.challenge.nonce)
+  const { signature } = await opts.sign(message)
+  const proof: AccessProof = { address: opts.address, nonce: opts.challenge.nonce, signature }
+  if (opts.consumeDigest) proof.consumeDigest = opts.consumeDigest
+  return encodeAccessProof(proof)
+}

package/src/ptb.ts

@@ -0,0 +1,65 @@
+import { Transaction } from '@mysten/sui/transactions'
+import type { AccessGateConfig } from './types.js'
+
+/**
+ * Build a PTB that purchases access: split `priceMist` from the gas coin and call
+ * `access_gate::purchase(gate, payment)`. Overpayment is refunded on-chain, so the split
+ * must be exactly the price. The caller signs + executes with their wallet.
+ */
+export function buildPurchaseTx(cfg: AccessGateConfig, priceMist: bigint | number): Transaction {
+  const tx = new Transaction()
+  const [payment] = tx.splitCoins(tx.gas, [tx.pure.u64(priceMist)])
+  tx.moveCall({
+    target: `${cfg.packageId}::access_gate::purchase`,
+    arguments: [tx.object(cfg.gateId), payment],
+  })
+  return tx
+}
+
+/**
+ * Build a PTB that consumes one use of a single-use NFT, binding it to `nonce`. Selects
+ * `consume` or `consume_soulbound` from `cfg.soulbound`. For unlimited passes there is
+ * nothing to consume — do not call this.
+ */
+export function buildConsumeTx(
+  cfg: AccessGateConfig,
+  nftId: string,
+  nonce: string,
+): Transaction {
+  const tx = new Transaction()
+  const fn = cfg.soulbound ? 'consume_soulbound' : 'consume'
+  const nonceBytes = Array.from(new TextEncoder().encode(nonce))
+  tx.moveCall({
+    target: `${cfg.packageId}::access_gate::${fn}`,
+    arguments: [tx.object(nftId), tx.object(cfg.gateId), tx.pure.vector('u8', nonceBytes)],
+  })
+  return tx
+}
+
+/**
+ * Build a PTB that creates a new gate. Mostly for tooling/operators; the frontend usually
+ * only purchases/consumes an existing gate.
+ */
+export function buildCreateGateTx(
+  packageId: string,
+  opts: {
+    priceMist: bigint | number
+    paymentRecipient: string
+    defaultUses: bigint | number
+    soulbound: boolean
+    autoBurnAtZero: boolean
+  },
+): Transaction {
+  const tx = new Transaction()
+  tx.moveCall({
+    target: `${packageId}::access_gate::create_gate`,
+    arguments: [
+      tx.pure.u64(opts.priceMist),
+      tx.pure.address(opts.paymentRecipient),
+      tx.pure.u64(opts.defaultUses),
+      tx.pure.bool(opts.soulbound),
+      tx.pure.bool(opts.autoBurnAtZero),
+    ],
+  })
+  return tx
+}

package/src/types.ts

@@ -0,0 +1,72 @@
+/**
+ * Shared wire + config types for the access-gate client.
+ *
+ * These mirror the on-chain `access_gate` Move package and the challenge/proof wire
+ * protocol implemented by the generic Rust gateway. Keep the three in sync.
+ */
+
+/** Identifies a deployed gate and the NFT type that satisfies it. */
+export interface AccessGateConfig {
+  /** Published `access_gate` package ID. */
+  packageId: string
+  /** The shared `Gate` object ID. */
+  gateId: string
+  /**
+   * Fully-qualified NFT type string to filter ownership by, e.g.
+   * `<pkg>::access_gate::AccessNFT` or `<pkg>::access_gate::SoulboundAccessNFT`.
+   * Choose the variant matching the gate's `soulbound` flag.
+   */
+  nftType: string
+  /** Whether this gate mints soulbound NFTs (selects `consume` vs `consume_soulbound`). */
+  soulbound?: boolean
+}
+
+/** A server-issued, time-bound challenge the wallet signs to prove control of an address. */
+export interface Challenge {
+  /** Opaque nonce (as issued by the gateway; treated as a UTF-8 string end-to-end). */
+  nonce: string
+  /** Unix epoch milliseconds after which the challenge is rejected. */
+  expiresAt: number
+}
+
+/** The proof a client presents to a gateway to demonstrate gated access. */
+export interface AccessProof {
+  /** The Sui address claimed by the caller. */
+  address: string
+  /** The challenge nonce that was signed. */
+  nonce: string
+  /** Base64 personal-message signature over {@link personalMessageForNonce}. */
+  signature: string
+  /**
+   * For single-use gates: the digest of the on-chain `consume(nft, nonce)` transaction, so
+   * the gateway can confirm the matching `AccessConsumedEvent` before allowing the request.
+   */
+  consumeDigest?: string
+}
+
+/** A parsed owned access NFT. */
+export interface OwnedAccessNft {
+  objectId: string
+  gateId: string
+  /** `null` for an unlimited pass; otherwise remaining single-use count. */
+  usesRemaining: number | null
+}
+
+/** Minimal structural subset of a Sui client used for ownership queries (grpc or json-rpc). */
+export interface OwnedObjectsClient {
+  getOwnedObjects(params: {
+    owner: string
+    filter?: { StructType: string }
+    options?: { showContent?: boolean; showType?: boolean }
+    cursor?: string | null
+    limit?: number | null
+  }): Promise<{ data: unknown[]; hasNextPage?: boolean; nextCursor?: string | null }>
+}
+
+/** Minimal structural subset of a Sui client used for a typed single-object read. */
+export interface SuiObjectClient {
+  getObject(params: {
+    id: string
+    options?: { showContent?: boolean; showType?: boolean }
+  }): Promise<unknown>
+}