@meddleware/nft-gate-client 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -5,6 +5,12 @@ 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.8] - 2026-09-17
+
+### Added
+
+- `homepage` in `package.json` — links to the Access Gate section of the documentation site.
+
 ## [0.0.3] - 2026-08-29
 
 ### Added

package/dist/proof.d.ts

@@ -6,7 +6,6 @@ import type { AccessProof, Challenge } from './types.js';
 export declare function personalMessageForNonce(nonce: string): Uint8Array;
 /** Encode a proof as the compact Bearer token carried in the relay auth header. */
 export declare function encodeAccessProof(proof: AccessProof): string;
-/** Decode a proof token produced by {@link encodeAccessProof}. Throws on malformed input. */
 export declare function decodeAccessProof(token: string): AccessProof;
 /** A wallet-provided personal-message signer (e.g. wallet-standard `sui:signPersonalMessage`). */
 export type PersonalMessageSigner = (message: Uint8Array) => Promise<{

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@meddleware/nft-gate-client",
-  "version": "0.0.7",
+  "version": "0.0.9",
+  "homepage": "https://docs.meddleware.co.uk/blockchain/sui/access-gate/",
   "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>",
@@ -36,7 +37,7 @@
     "test:integration": "vitest run --config vitest.integration.config.ts"
   },
   "dependencies": {
-    "@mysten/sui": "^2.28.0"
+    "@mysten/sui": "^2.31.0"
   },
   "devDependencies": {
     "@types/node": "~24.12.2",

package/src/ownership.ts

@@ -27,8 +27,9 @@ function parseUsesRemaining(variant: any): number | 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
+  // Either an unknown tag, or a SingleUse whose count is missing from this node's rendering — in
+  // both cases the remaining count is unknown, so report null (never a fabricated 0).
+  return null
 }
 
 /** True if `type` names an `access_gate` NFT struct (transferable or soulbound). */

package/src/proof.ts

@@ -8,12 +8,29 @@ export function personalMessageForNonce(nonce: string): Uint8Array {
   return new TextEncoder().encode(`nft-gate:access:${nonce}`)
 }
 
+// UTF-8-safe base64. The naive `btoa(str)` operates on Latin-1 and throws/corrupts on any code
+// point > 0xFF, so we round-trip through UTF-8 bytes first. For pure-ASCII payloads (the only kind
+// this wire format carries — see the ASCII contract below) the output is byte-identical to `btoa`,
+// so the gateways' decoders are unaffected.
 function toBase64(s: string): string {
-  return btoa(s)
+  const bytes = new TextEncoder().encode(s)
+  let bin = ''
+  for (const b of bytes) bin += String.fromCharCode(b)
+  return btoa(bin)
 }
 
 function fromBase64(s: string): string {
-  return atob(s)
+  const bin = atob(s)
+  const bytes = Uint8Array.from(bin, (c) => c.charCodeAt(0))
+  return new TextDecoder().decode(bytes)
+}
+
+/** True iff every character is ASCII (code point ≤ 0x7F). */
+function isAscii(s: string): boolean {
+  for (let i = 0; i < s.length; i++) {
+    if (s.charCodeAt(i) > 0x7f) return false
+  }
+  return true
 }
 
 /** Encode a proof as the compact Bearer token carried in the relay auth header. */
@@ -21,12 +38,29 @@ export function encodeAccessProof(proof: AccessProof): string {
   return toBase64(JSON.stringify(proof))
 }
 
-/** Decode a proof token produced by {@link encodeAccessProof}. Throws on malformed input. */
+/**
+ * Decode a proof token produced by {@link encodeAccessProof}. Throws on malformed input.
+ *
+ * ASCII contract: both gateways issue ASCII-only nonces (`<region>.<hex>` or hex) and treat
+ * `address`/`nonce` as ASCII end-to-end. We enforce that here so a non-ASCII field is rejected
+ * rather than silently diverging between the client and a gateway verifier. `address` is emitted
+ * verbatim (raw); canonicalisation is owned gateway-side (see nft-gate `verify.rs`/`verify.ts`), so
+ * the wire format is unchanged and the golden vector stays stable.
+ */
+/** Maximum encoded token length (bytes). Prevents a multi-MB blob from saturating `atob`/`JSON.parse`. */
+const MAX_TOKEN_BYTES = 4096
+
 export function decodeAccessProof(token: string): AccessProof {
+  if (token.length > MAX_TOKEN_BYTES) {
+    throw new Error(`access proof token too large (${token.length} > ${MAX_TOKEN_BYTES})`)
+  }
   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')
   }
+  if (!isAscii(raw.address) || !isAscii(raw.nonce) || !isAscii(raw.signature)) {
+    throw new Error('non-ASCII field in 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