@meddleware/nft-gate-gateway 0.0.6 → 0.0.8

package/package.json

@@ -1,6 +1,6 @@
  {
   "name": "@meddleware/nft-gate-gateway",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "type": "module",
   "description": "Cloudflare Workers implementation of the nft-gate gateway: a wire-identical, drop-in sibling of the Rust gateway that gates any HTTP upstream behind an access_gate NFT.",
   "license": "0BSD",
@@ -22,6 +22,7 @@
   },
   "dependencies": {
     "@meddleware/nft-gate-client": "^0.0.6",
+    "@mysten/sui": "~2.30.0",
     "@noble/curves": "~2.4.0",
     "@noble/hashes": "~2.4.0"
   },

package/src/chain.ts

@@ -1,10 +1,20 @@
 /**
- * Production {@link ChainQuery} over Sui JSON-RPC (`suix_getOwnedObjects`, `suix_queryEvents`,
- * `sui_getTransactionBlock`) via `fetch`. A 1:1 port of the Rust gateway's `sui_rpc.rs`,
- * including the identical request JSON shapes. The pure match/parse helpers are exported for
- * unit tests; the RPC round-trips are covered by the localnet/integration loop.
+ * Production {@link ChainQuery} over the Sui **gRPC** API (`@mysten/sui/grpc` `SuiGrpcClient`).
+ *
+ * Public Sui fullnodes have deprecated JSON-RPC (`suix_queryEvents`, `sui_getTransactionBlock`,
+ * `suix_getOwnedObjects` now return `-32601 Method not found`), so the gateway queries the chain
+ * over gRPC — the same transport `@meddleware/walrus-client` and `@meddleware/nft-gate-client`
+ * already use. The pure match/parse helpers are exported for unit tests; the gRPC round-trips are
+ * covered by the localnet/integration loop.
+ *
+ * Single-use verification is now **digest-first**: the access proof already carries the on-chain
+ * `access_gate::consume` transaction digest, so the gateway fetches that exact transaction and
+ * verifies it succeeded and emitted a matching `AccessConsumedEvent`. This is precise (bound to the
+ * challenge nonce + sender + gate) and does not need the deprecated event-by-sender query.
  */
 
+import { SuiGrpcClient } from '@mysten/sui/grpc'
+import { fetchAccessNfts } from '@meddleware/nft-gate-client'
 import type { ChainQuery } from './verify.js'
 import { base64ToBytes } from './crypto.js'
 
@@ -20,44 +30,37 @@ interface CacheEntry {
   expiry: number
 }
 
-/** Production {@link ChainQuery} backed by Sui JSON-RPC, with an optional ownership cache. */
-export class SuiRpc implements ChainQuery {
+/** Number of `getTransaction` attempts (absorbs fullnode indexing lag after the client's finality wait). */
+const TX_FETCH_ATTEMPTS = 4
+/** Delay between `getTransaction` retries, in ms. */
+const TX_FETCH_RETRY_MS = 500
+
+/** Production {@link ChainQuery} backed by the Sui gRPC API, with an optional ownership cache. */
+export class SuiGrpc implements ChainQuery {
   private readonly cache = new Map<string, CacheEntry>()
+  private readonly client: SuiGrpcClient
 
   /**
-   * @param rpcUrl - Sui JSON-RPC endpoint URL.
+   * @param rpcUrl - Sui gRPC endpoint base URL (e.g. `https://fullnode.testnet.sui.io:443`).
    * @param cacheTtlMs - Ownership-cache TTL in ms. 0 disables the cache (live check every request).
-   * @param authHeader - Optional header injected on every RPC call (e.g. credentialed fullnode auth).
+   * @param authHeader - Optional header injected on every gRPC call (e.g. credentialed fullnode auth).
    */
   constructor(
     private readonly rpcUrl: string,
     /** Ownership-cache TTL (ms). 0 = disabled (every gated check is live on-chain). */
     private readonly cacheTtlMs: number = 0,
-    private readonly authHeader?: { name: string; value: string },
-  ) {}
-
-  /**
-   * Send a Sui JSON-RPC 2.0 request and return the `result` field.
-   *
-   * @param method - JSON-RPC method name (e.g. `suix_getOwnedObjects`).
-   * @param params - Positional parameters array.
-   * @returns The `result` value from the RPC response, or `null`.
-   * @throws If the HTTP response is not OK or the RPC body contains an `error` field.
-   */
-  private async call(method: string, params: Json): Promise<Json> {
-    const headers: Record<string, string> = { 'content-type': 'application/json' }
-    if (this.authHeader) headers[this.authHeader.name] = this.authHeader.value
-    const resp = await fetch(this.rpcUrl, {
-      method: 'POST',
-      headers,
-      body: JSON.stringify({ jsonrpc: '2.0', id: 1, method, params }),
+    authHeader?: { name: string; value: string },
+  ) {
+    // The `network` label is cosmetic when an explicit `baseUrl` is supplied (core RPC resolves via
+    // the endpoint, not the label); infer it from the URL so a mainnet fullnode is labelled correctly.
+    const network = /mainnet/i.test(rpcUrl) ? 'mainnet' : 'testnet'
+    this.client = new SuiGrpcClient({
+      network,
+      baseUrl: rpcUrl,
+      // gRPC-web metadata keys must be lower-case ASCII; a credentialed fullnode auth header
+      // (e.g. `Authorization: Bearer …`) is threaded here on every call.
+      ...(authHeader ? { meta: { [authHeader.name.toLowerCase()]: authHeader.value } } : {}),
     })
-    if (!resp.ok) throw new Error(`rpc http ${resp.status} from ${method}`)
-    const json = (await resp.json()) as Record<string, Json>
-    if (json && typeof json === 'object' && 'error' in json && json.error) {
-      throw new Error(`rpc error from ${method}: ${JSON.stringify(json.error)}`)
-    }
-    return (json as { result?: Json }).result ?? null
   }
 
   /**
@@ -84,7 +87,9 @@ export class SuiRpc implements ChainQuery {
   }
 
   /**
-   * Uncached, live `suix_getOwnedObjects` ownership query.
+   * Uncached, live ownership query over gRPC `listOwnedObjects`. Reuses `fetchAccessNfts` from
+   * `@meddleware/nft-gate-client` (the same gRPC core-API parse the frontend uses), so the
+   * gateway and client agree on what counts as a held access NFT.
    *
    * @param address - Sui address to query.
    * @param nftType - NFT struct type to filter by.
@@ -92,16 +97,8 @@ export class SuiRpc implements ChainQuery {
    * @returns `true` if at least one qualifying NFT is owned.
    */
   private async ownsNftLive(address: string, nftType: string, gateId?: string): Promise<boolean> {
-    const params = [
-      address,
-      { filter: { StructType: nftType }, options: { showContent: true } },
-      null,
-      50,
-    ]
-    const result = (await this.call('suix_getOwnedObjects', params)) as { data?: Json[] } | null
-    const data = (result && Array.isArray(result.data) ? result.data : []) as Json[]
-    if (gateId === undefined) return data.length > 0
-    return data.some((entry) => pointerStr(entry, ['data', 'content', 'fields', 'data', 'fields', 'gate_id']) === gateId)
+    const nfts = await fetchAccessNfts(this.client, address, nftType, gateId)
+    return nfts.length > 0
   }
 
   /**
@@ -116,7 +113,7 @@ export class SuiRpc implements ChainQuery {
   async ownsNft(address: string, nftType: string, gateId?: string): Promise<boolean> {
     // Cache is OFF by default (ttl 0) so a gated action is confirmed live on-chain.
     if (this.cacheTtlMs > 0) {
-      const key = SuiRpc.cacheKey(address, nftType, gateId)
+      const key = SuiGrpc.cacheKey(address, nftType, gateId)
       const hit = this.cache.get(key)
       const now = Date.now()
       if (hit && hit.expiry > now) return hit.owns
@@ -128,70 +125,64 @@ export class SuiRpc implements ChainQuery {
   }
 
   /**
-   * Directly verify the consume transaction named by `digest` via `sui_getTransactionBlock`.
-   * The tx must have succeeded and emitted a matching `AccessConsumedEvent`. Defence-in-depth
-   * atop the sender+nonce event query.
+   * Fetch a transaction by digest via gRPC, retrying briefly to absorb the window between the
+   * client's finality wait and the gateway fullnode indexing the transaction.
    *
-   * @param digest - Transaction digest of the on-chain consume.
-   * @param nonce - The challenge nonce that was consumed.
-   * @param address - Expected transaction sender.
-   * @param gateId - Optional gate object ID constraint.
-   * @returns `true` if the transaction confirms the consume.
+   * @param digest - Transaction digest to fetch.
+   * @returns The gRPC `TransactionResult` (`$kind: 'Transaction' | 'FailedTransaction'`).
+   * @throws If every attempt fails (surfaces as a {@link ChainQuery} ChainError → 502).
    */
-  private async consumeTxMatches(
-    digest: string,
-    nonce: string,
-    address: string,
-    gateId?: string,
-  ): Promise<boolean> {
-    const params = [digest, { showEvents: true, showEffects: true }]
-    const result = (await this.call('sui_getTransactionBlock', params)) as Json
-    const status = pointerStr(result, ['effects', 'status', 'status'])
-    if (status !== 'success') return false
-    const events = (pointer(result, ['events']) as Json[] | undefined) ?? []
-    return (
-      Array.isArray(events) &&
-      events.some((ev) => isConsumedEvent(ev) && eventMatches(ev, nonce, address, gateId))
-    )
+  private async getTransaction(digest: string): Promise<Json> {
+    let lastErr: unknown
+    for (let attempt = 0; attempt < TX_FETCH_ATTEMPTS; attempt++) {
+      try {
+        return (await this.client.core.getTransaction({
+          digest,
+          include: { events: true },
+        })) as Json
+      } catch (e) {
+        lastErr = e
+        if (attempt < TX_FETCH_ATTEMPTS - 1) {
+          await new Promise<void>((r) => setTimeout(r, TX_FETCH_RETRY_MS))
+        }
+      }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr))
   }
 
   /**
-   * Verify a single-use consume via `suix_queryEvents`. Queries for an `AccessConsumedEvent`
-   * emitted by `address` carrying `nonce`; if `consumeDigest` is also provided, additionally
-   * verifies that exact transaction (F4: defence in depth).
+   * Verify a single-use consume by fetching its `consumeDigest` transaction directly and confirming
+   * it succeeded and emitted an `AccessConsumedEvent` for this sender + gate.
+   *
+   * The event is bound to the sender (which must equal the signature-verified proof address) and
+   * the gate — NOT to the challenge nonce. Decoupling from the nonce is what lets an interrupted
+   * upload resume with a fresh (free) challenge signature while reusing the same on-chain consume;
+   * single-use is then enforced by the gateway's redemption store keying on this `consumeDigest`.
+   * An attacker cannot present someone else's consume (the event `sender` would not match the
+   * signed address) nor forge one without owning the soulbound NFT.
    *
-   * @param nonce - The challenge nonce that was consumed.
-   * @param address - The Sui address that submitted the consume transaction.
-   * @param nftType - Fully-qualified NFT type used to derive the event package.
+   * @param consumeDigest - Transaction digest of the on-chain consume.
+   * @param address - The signature-verified proof address; must equal the event sender.
    * @param gateId - Optional gate object ID constraint.
-   * @param consumeDigest - Optional transaction digest for direct tx verification.
-   * @returns `true` if a matching consume event (and, when given, a matching tx) is found.
+   * @returns `true` if the transaction confirms a matching consume.
    */
-  async consumeEventMatches(
-    nonce: string,
-    address: string,
-    nftType: string,
-    gateId?: string,
-    consumeDigest?: string,
-  ): Promise<boolean> {
-    const pkg = SuiRpc.packageOf(nftType)
-    if (!pkg) throw new Error('cannot derive package from nft_type')
-    const eventType = `${pkg}::access_gate::AccessConsumedEvent`
-    // Filter by BOTH the event type AND the emitting Sender (F5): O(this user's events).
-    const params = [{ All: [{ MoveEventType: eventType }, { Sender: address }] }, null, 50, true]
-    const result = (await this.call('suix_queryEvents', params)) as { data?: Json[] } | null
-    const data = (result && Array.isArray(result.data) ? result.data : []) as Json[]
-    const primary = data.some((ev) => eventMatches(ev, nonce, address, gateId))
-    if (!primary) return false
-    // F4: if a consume tx digest was supplied, verify that exact transaction too.
-    if (consumeDigest !== undefined) {
-      return this.consumeTxMatches(consumeDigest, nonce, address, gateId)
-    }
-    return true
+  async consumeTxValid(consumeDigest: string, address: string, gateId?: string): Promise<boolean> {
+    const res = (await this.getTransaction(consumeDigest)) as Record<string, Json> | null
+    // The gRPC result is a oneof: `{ $kind: 'Transaction', Transaction }` on success, or
+    // `{ $kind: 'FailedTransaction', FailedTransaction }` when the transaction aborted.
+    if (!res || res.$kind !== 'Transaction') return false
+    const tx = res.Transaction as Record<string, Json> | undefined
+    const status = tx?.status as { success?: boolean } | undefined
+    if (!status?.success) return false
+    const events = (Array.isArray(tx?.events) ? (tx?.events as Json[]) : []) as Json[]
+    return events.some((ev) => isConsumedEvent(ev) && eventMatches(ev, address, gateId))
   }
 }
 
-// ── pure helpers (unit-tested; mirror sui_rpc.rs) ────────────────────────────
+// ── pure helpers (unit-tested; adapted to the gRPC event shape) ───────────────
+// gRPC events expose `eventType`/`sender`/`json`; JSON-RPC used `type`/`sender`/`parsedJson`.
+// The helpers read both keys so they stay tolerant to transport/shape variation (the SDK documents
+// that the `json` shape may differ between transports).
 
 /**
  * Traverse a nested JSON value by a sequence of object keys.
@@ -224,14 +215,24 @@ function pointerStr(v: Json, path: string[]): string | undefined {
   return typeof r === 'string' ? r : undefined
 }
 
+/** The event's Move type string, from the gRPC (`eventType`) or JSON-RPC (`type`) shape. */
+function eventType(ev: Json): string | undefined {
+  return pointerStr(ev, ['eventType']) ?? pointerStr(ev, ['type'])
+}
+
+/** The event's parsed Move struct fields, from the gRPC (`json`) or JSON-RPC (`parsedJson`) shape. */
+function eventFields(ev: Json): Json {
+  return pointer(ev, ['json']) ?? pointer(ev, ['parsedJson'])
+}
+
 /** True if the event's type ends with `::access_gate::AccessConsumedEvent`. */
 export function isConsumedEvent(ev: Json): boolean {
-  const t = pointerStr(ev, ['type'])
+  const t = eventType(ev)
   return t !== undefined && t.endsWith('::access_gate::AccessConsumedEvent')
 }
 
 /**
- * Match the on-chain `AccessConsumedEvent.nonce` (`vector<u8>`), rendered by RPC as either an
+ * Match the on-chain `AccessConsumedEvent.nonce` (`vector<u8>`), rendered by the API as either an
  * array of byte numbers or a base64 string, against the challenge nonce's UTF-8 bytes.
  */
 export function nonceMatches(eventNonce: Json, nonce: string): boolean {
@@ -251,11 +252,14 @@ export function nonceMatches(eventNonce: Json, nonce: string): boolean {
   return false
 }
 
-/** sender == address, nonce matches, and (if given) gate_id matches. */
-export function eventMatches(ev: Json, nonce: string, address: string, gateId?: string): boolean {
+/**
+ * `sender == address` and (if given) `gate_id` matches. The consume event is bound to the
+ * signature-verified sender + gate; single-use is enforced separately by redemption tracking on the
+ * `consumeDigest`, so the event nonce is intentionally not checked here (see `consumeTxValid`).
+ */
+export function eventMatches(ev: Json, address: string, gateId?: string): boolean {
   const senderOk = pointerStr(ev, ['sender']) === address
-  const nonceVal = pointer(ev, ['parsedJson', 'nonce'])
-  const nonceOk = nonceVal !== undefined && nonceMatches(nonceVal, nonce)
-  const gateOk = gateId === undefined ? true : pointerStr(ev, ['parsedJson', 'gate_id']) === gateId
-  return senderOk && nonceOk && gateOk
+  const fields = eventFields(ev)
+  const gateOk = gateId === undefined ? true : pointerStr(fields, ['gate_id']) === gateId
+  return senderOk && gateOk
 }

package/src/config.ts

@@ -22,6 +22,10 @@ export interface Env {
   MAX_BODY_BYTES?: string
   CHALLENGE_TTL_SECS?: string
   OWNERSHIP_CACHE_TTL_MS?: string
+  /** Single-use: seconds a consume-digest redemption lease is held during an in-flight upload. */
+  REDEMPTION_LEASE_TTL_SECS?: string
+  /** Single-use: seconds a committed (spent) consume-digest is remembered to block re-redemption. */
+  REDEMPTION_RETENTION_SECS?: string
   // ── Workers-specific ──────────────────────────────────────────────────────
   /** `durable-object` (default) | `kv`. */
   NONCE_BACKEND?: string
@@ -71,6 +75,10 @@ export interface Config {
   rateLimitPerMin: number
   maxBodyBytes: number
   ownershipCacheTtlMs: number
+  /** Single-use: lease TTL (s) for an in-flight consume-digest redemption. */
+  redemptionLeaseTtlSecs: number
+  /** Single-use: retention (s) of a committed (spent) consume-digest. */
+  redemptionRetentionSecs: number
   nonceBackend: NonceBackendKind
   nonceShard: NonceShardMode
   nonceMaxEntries: number
@@ -135,6 +143,8 @@ export function loadConfig(env: Env): Config {
     rateLimitPerMin: numOr(env.RATE_LIMIT_PER_MIN, 30),
     maxBodyBytes: numOr(env.MAX_BODY_BYTES, 262144),
     ownershipCacheTtlMs: numOr(env.OWNERSHIP_CACHE_TTL_MS, 0),
+    redemptionLeaseTtlSecs: numOr(env.REDEMPTION_LEASE_TTL_SECS, 120),
+    redemptionRetentionSecs: numOr(env.REDEMPTION_RETENTION_SECS, 2592000),
     nonceBackend,
     nonceShard,
     nonceMaxEntries: numOr(env.NONCE_MAX_ENTRIES, 1000000),

package/src/index.ts

@@ -11,7 +11,7 @@ import type { Config, Env } from './config.js'
 import { loadConfig, isPublicPath } from './config.js'
 import type { NonceBackend } from './state/types.js'
 import { makeBackend } from './state/select.js'
-import { SuiRpc } from './chain.js'
+import { SuiGrpc } from './chain.js'
 import { verifyAccessRequest, deniedReason } from './verify.js'
 import { forward } from './proxy.js'
 import { runQuotaGuard } from './quota.js'
@@ -26,7 +26,7 @@ export { NonceRateState } from './state/durable_object.js'
 interface GatewayState {
   cfg: Config
   backend: NonceBackend
-  chain: SuiRpc
+  chain: SuiGrpc
 }
 
 /** Lazily initialised once per isolate; `null` before the first request. */
@@ -56,7 +56,7 @@ async function getState(env: Env): Promise<GatewayState> {
   cached = {
     cfg,
     backend: makeBackend(effective, env),
-    chain: new SuiRpc(cfg.suiRpcUrl, cfg.ownershipCacheTtlMs, cfg.suiRpcAuthHeader),
+    chain: new SuiGrpc(cfg.suiRpcUrl, cfg.ownershipCacheTtlMs, cfg.suiRpcAuthHeader),
   }
   return cached
 }
@@ -76,14 +76,16 @@ function json(status: number, body: unknown): Response {
 }
 
 /**
- * Build a JSON `{"error": reason}` response with the given status code.
+ * Build a JSON `{"error": reason}` response with the given status code, optionally with a stable
+ * machine-readable `code` (e.g. `"redeemed"` vs `"leased"`) so the client can react precisely.
  *
  * @param status - HTTP status code.
  * @param reason - Short, client-visible error description.
+ * @param code - Optional stable code for programmatic handling.
  * @returns A JSON error response.
  */
-function deny(status: number, reason: string): Response {
-  return json(status, { error: reason })
+function deny(status: number, reason: string, code?: string): Response {
+  return json(status, code ? { error: reason, code } : { error: reason })
 }
 
 /** Prefer `Authorization: Bearer <token>`; fall back to an explicit `X-Access-Proof` header. */
@@ -160,6 +162,34 @@ async function handle(request: Request, env: Env): Promise<Response> {
     return deny(429, 'rate limit exceeded')
   }
 
+  // Single-use: the permanent on-chain `consumeDigest` is the one-time redemption token. Lease it,
+  // proxy, then COMMIT on a successful upload or RELEASE on failure — so an interrupted upload
+  // leaves the consume redeemable (the use is never lost) while a duplicate can't double-spend it.
+  const redemptionKey = result.redemptionKey
+  if (redemptionKey !== undefined) {
+    const lease = await backend.tryLeaseRedemption(redemptionKey, cfg.redemptionLeaseTtlSecs)
+    if (lease === 'redeemed') {
+      return deny(409, 'this consume has already been redeemed for an upload', 'redeemed')
+    }
+    if (lease === 'leased') {
+      return deny(409, 'an upload for this consume is already in progress', 'leased')
+    }
+    let resp: Response
+    try {
+      resp = await forward(cfg, request)
+    } catch (e) {
+      // Network/exception before a definitive upstream result — release so the user can retry.
+      await backend.releaseRedemption(redemptionKey)
+      throw e
+    }
+    if (resp.ok) {
+      await backend.commitRedemption(redemptionKey, cfg.redemptionRetentionSecs)
+    } else {
+      await backend.releaseRedemption(redemptionKey)
+    }
+    return resp
+  }
+
   return forward(cfg, request)
 }
 

package/src/state/durable_object.ts

@@ -11,9 +11,12 @@
  */
 
 import { DurableObject } from 'cloudflare:workers'
-import type { NonceBackend } from './types.js'
+import type { LeaseResult, NonceBackend } from './types.js'
 import { randomHex24, shardOfNonce } from './types.js'
 
+/** Fixed shard name for the redemption store (the `consumeDigest` carries no region tag). */
+const REDEEM_SHARD = 'redeem'
+
 /** SQLite row shape for the `nonces` table. */
 interface NonceRow {
   expiry: number
@@ -27,6 +30,11 @@ interface RateRow {
 interface CountRow {
   c: number
 }
+/** SQLite row shape for the `redemptions` table. */
+interface RedemptionRow {
+  state: string
+  expiry: number
+}
 
 /**
  * Durable Object that provides the SQLite-backed nonce store and per-address rate limiter.
@@ -49,6 +57,12 @@ export class NonceRateState extends DurableObject {
     this.sql.exec(
       'CREATE TABLE IF NOT EXISTS rate (addr TEXT PRIMARY KEY, start INTEGER NOT NULL, count INTEGER NOT NULL)',
     )
+    // Redemption store: `state` is 'leased' (an in-flight upload holds the consume) or 'committed'
+    // (the use was spent on a successful upload). `expiry` is the lease deadline / committed
+    // retention deadline (unix ms).
+    this.sql.exec(
+      'CREATE TABLE IF NOT EXISTS redemptions (key TEXT PRIMARY KEY, state TEXT NOT NULL, expiry INTEGER NOT NULL)',
+    )
   }
 
   /** Store a fresh nonce with a hard entry cap (evict soonest-to-expire). Returns expiry ms. */
@@ -95,6 +109,54 @@ export class NonceRateState extends DurableObject {
     this.sql.exec('INSERT OR REPLACE INTO rate (addr, start, count) VALUES (?, ?, ?)', addr, start, count + 1)
     return true
   }
+
+  /**
+   * Atomically claim `key` for an in-flight upload (single-threaded DO ⇒ no race). Returns
+   * `'redeemed'` if already committed, `'leased'` if an unexpired lease is held, else `'ok'`
+   * after taking a fresh lease. An expired lease (crashed request) is reclaimable as `'ok'`.
+   */
+  tryLeaseRedemption(key: string, leaseTtlSecs: number, maxEntries: number): LeaseResult {
+    const now = Date.now()
+    // Bounded growth: drop expired leases and lapsed committed rows before inserting.
+    this.sql.exec("DELETE FROM redemptions WHERE state = 'leased' AND expiry <= ?", now)
+    this.sql.exec("DELETE FROM redemptions WHERE state = 'committed' AND expiry <= ?", now)
+    const rows = this.sql
+      .exec('SELECT state, expiry FROM redemptions WHERE key = ?', key)
+      .toArray() as unknown as RedemptionRow[]
+    if (rows.length > 0) {
+      const r = rows[0]
+      if (r.state === 'committed') return 'redeemed'
+      if (r.state === 'leased' && Number(r.expiry) > now) return 'leased'
+      // else: an expired lease — fall through and re-lease.
+    }
+    const count = (this.sql.exec('SELECT COUNT(*) AS c FROM redemptions').one() as unknown as CountRow).c
+    if (count >= Math.max(1, maxEntries)) {
+      // Evict the soonest-to-expire leased row (never a committed one — that would allow reuse).
+      this.sql.exec(
+        "DELETE FROM redemptions WHERE key = (SELECT key FROM redemptions WHERE state = 'leased' ORDER BY expiry ASC LIMIT 1)",
+      )
+    }
+    this.sql.exec(
+      "INSERT OR REPLACE INTO redemptions (key, state, expiry) VALUES (?, 'leased', ?)",
+      key,
+      now + leaseTtlSecs * 1000,
+    )
+    return 'ok'
+  }
+
+  /** Permanently mark `key` redeemed (retained `retentionSecs`) — the use is spent. */
+  commitRedemption(key: string, retentionSecs: number): void {
+    this.sql.exec(
+      "INSERT OR REPLACE INTO redemptions (key, state, expiry) VALUES (?, 'committed', ?)",
+      key,
+      Date.now() + retentionSecs * 1000,
+    )
+  }
+
+  /** Release a lease on `key` (upload failed) so the consume can be retried immediately. */
+  releaseRedemption(key: string): void {
+    this.sql.exec("DELETE FROM redemptions WHERE key = ? AND state = 'leased'", key)
+  }
 }
 
 /** {@link NonceBackend} that fans out to per-region {@link NonceRateState} DO shards. */
@@ -136,4 +198,18 @@ export class DurableObjectBackend implements NonceBackend {
     const shard = this.shardMode === 'global' ? 'g' : region
     return this.stub(shard).rateCheck(address, maxPerMin)
   }
+
+  // Redemption state has no region tag, so all redemption ops route to one fixed shard — keeping
+  // every operation on a given `consumeDigest` on the same single-threaded instance (atomic).
+  async tryLeaseRedemption(key: string, leaseTtlSecs: number): Promise<LeaseResult> {
+    return this.stub(REDEEM_SHARD).tryLeaseRedemption(key, leaseTtlSecs, this.maxEntries)
+  }
+
+  async commitRedemption(key: string, retentionSecs: number): Promise<void> {
+    await this.stub(REDEEM_SHARD).commitRedemption(key, retentionSecs)
+  }
+
+  async releaseRedemption(key: string): Promise<void> {
+    await this.stub(REDEEM_SHARD).releaseRedemption(key)
+  }
 }

package/src/state/kv.ts

@@ -7,13 +7,15 @@
  * use bind, so that mode is unaffected.) Use the Durable Object backend when this matters.
  */
 
-import type { NonceBackend } from './types.js'
+import type { LeaseResult, NonceBackend } from './types.js'
 import { randomHex24 } from './types.js'
 
 /** KV key prefix for nonce entries. */
 const NONCE_PREFIX = 'nonce:'
 /** KV key prefix for per-address rate-limit windows. */
 const RATE_PREFIX = 'rate:'
+/** KV key prefix for redemption entries. */
+const REDEEM_PREFIX = 'redeem:'
 /** Workers KV minimum `expirationTtl` (seconds). Sub-60s logical TTLs are enforced in-value. */
 const KV_MIN_TTL_SECS = 60
 
@@ -78,4 +80,45 @@ export class KvBackend implements NonceBackend {
     })
     return true
   }
+
+  // Best-effort redemption on KV (eventually consistent — the get→put lease is not atomic, so a
+  // narrow concurrent-duplicate window exists; the Durable Object backend is strongly consistent
+  // and preferred when this matters). Committed always wins over a lease on read.
+  async tryLeaseRedemption(key: string, leaseTtlSecs: number): Promise<LeaseResult> {
+    const k = REDEEM_PREFIX + key
+    const raw = await this.kv.get(k)
+    if (raw) {
+      try {
+        const r = JSON.parse(raw) as { s: string; e: number }
+        if (r.s === 'committed') return 'redeemed'
+        if (r.s === 'leased' && r.e > Date.now()) return 'leased'
+      } catch {
+        /* fall through and re-lease */
+      }
+    }
+    await this.kv.put(k, JSON.stringify({ s: 'leased', e: Date.now() + leaseTtlSecs * 1000 }), {
+      expirationTtl: Math.max(KV_MIN_TTL_SECS, leaseTtlSecs),
+    })
+    return 'ok'
+  }
+
+  async commitRedemption(key: string, retentionSecs: number): Promise<void> {
+    await this.kv.put(
+      REDEEM_PREFIX + key,
+      JSON.stringify({ s: 'committed', e: Date.now() + retentionSecs * 1000 }),
+      { expirationTtl: Math.max(KV_MIN_TTL_SECS, retentionSecs) },
+    )
+  }
+
+  async releaseRedemption(key: string): Promise<void> {
+    // Only clear a lease — never a committed marker (that would allow the use to be re-redeemed).
+    const raw = await this.kv.get(REDEEM_PREFIX + key)
+    if (!raw) return
+    try {
+      if ((JSON.parse(raw) as { s: string }).s === 'committed') return
+    } catch {
+      /* malformed — safe to delete */
+    }
+    await this.kv.delete(REDEEM_PREFIX + key)
+  }
 }

package/src/state/types.ts

@@ -10,6 +10,13 @@
  *   cross-region replay window in the `SINGLE_USE=false` ownership mode).
  */
 
+/**
+ * Outcome of a redemption-lease attempt (single-use mode). `ok` — the caller now holds the lease
+ * and must `commit`/`release` it. `leased` — another in-flight request holds it (concurrent
+ * duplicate). `redeemed` — it was already committed (the use is spent).
+ */
+export type LeaseResult = 'ok' | 'leased' | 'redeemed'
+
 export interface NonceBackend {
   /**
    * Issue a fresh, time-bound nonce. `region` selects the DO shard (ignored by KV, which is
@@ -20,6 +27,22 @@ export interface NonceBackend {
   takeIfValid(nonce: string): Promise<boolean>
   /** Fixed 60s window per verified address. `maxPerMin === 0` disables limiting. */
   rateCheck(address: string, maxPerMin: number, region: string): Promise<boolean>
+
+  // ── Single-use redemption (the permanent on-chain `consumeDigest` is the one-time token) ──
+  // A use is only spent when an upload actually succeeds: lease the digest, proxy, then commit on
+  // success or release on failure. An interrupted attempt leaves the digest redeemable, so a
+  // consumed NFT use is never lost. All three are atomic per key on the Durable Object backend.
+
+  /**
+   * Atomically claim `key` for an in-flight upload. `ok` on a fresh/expired-lease/released key,
+   * `leased` if another request holds an unexpired lease, `redeemed` if already committed. The
+   * lease self-expires after `leaseTtlSecs` so a crashed request cannot strand the key.
+   */
+  tryLeaseRedemption(key: string, leaseTtlSecs: number): Promise<LeaseResult>
+  /** Permanently mark `key` redeemed (retained `retentionSecs`), after a successful upload. */
+  commitRedemption(key: string, retentionSecs: number): Promise<void>
+  /** Release a lease on `key` (upload failed) so the same consume can be retried immediately. */
+  releaseRedemption(key: string): Promise<void>
 }
 
 /**

package/src/verify.ts

@@ -117,16 +117,15 @@ function verifyEcdsa(
   return normalizeAddress(address) === deriveAddress(flag, pk)
 }
 
-/** On-chain lookups needed to authorise a request. Implemented by {@link ../chain.SuiRpc}. */
+/** On-chain lookups needed to authorise a request. Implemented by {@link ../chain.SuiGrpc}. */
 export interface ChainQuery {
   ownsNft(address: string, nftType: string, gateId?: string): Promise<boolean>
-  consumeEventMatches(
-    nonce: string,
-    address: string,
-    nftType: string,
-    gateId?: string,
-    consumeDigest?: string,
-  ): Promise<boolean>
+  /**
+   * True if `consumeDigest` names a successful `access_gate::consume` transaction that emitted an
+   * `AccessConsumedEvent` for `address` (the sender) on `gateId`. Not bound to the challenge nonce
+   * — single-use is enforced by the redemption store keying on the digest.
+   */
+  consumeTxValid(consumeDigest: string, address: string, gateId?: string): Promise<boolean>
 }
 
 /** The reason a request was rejected by {@link verifyAccessRequest}. Mirror of Rust `Denied`. */
@@ -136,6 +135,7 @@ export type Denied =
   | 'NonceInvalid'
   | 'NotOwner'
   | 'ConsumeMissing'
+  | 'RedeemConflict'
   | 'ChainError'
 
 /** A short, client-visible description of why access was denied. */
@@ -150,14 +150,22 @@ export function deniedReason(d: Denied): string {
     case 'NotOwner':
       return 'address does not hold the required access NFT'
     case 'ConsumeMissing':
-      return 'no matching single-use consume for this challenge'
+      return 'no matching single-use consume for this address'
+    case 'RedeemConflict':
+      return 'this consume is already redeemed or an upload for it is in progress'
     case 'ChainError':
       return 'on-chain verification failed'
   }
 }
 
-/** Result of {@link verifyAccessRequest}: the verified address on success, or a {@link Denied} reason. */
-export type VerifyResult = { ok: true; address: string } | { ok: false; denied: Denied }
+/**
+ * Result of {@link verifyAccessRequest}: the verified address on success, or a {@link Denied}
+ * reason. In single-use mode a successful result also carries `redemptionKey` (the `consumeDigest`)
+ * that the dispatcher leases/commits so the use is only spent on a successful upload.
+ */
+export type VerifyResult =
+  | { ok: true; address: string; redemptionKey?: string }
+  | { ok: false; denied: Denied }
 
 /**
  * Authorise a request from its base64 proof token. The nonce is consumed (single-use at the
@@ -193,26 +201,23 @@ export async function verifyAccessRequest(
     }
     let ok: boolean
     try {
-      ok = await chain.consumeEventMatches(
-        proof.nonce,
-        proof.address,
-        cfg.nftType,
-        cfg.gateId,
-        proof.consumeDigest,
-      )
+      ok = await chain.consumeTxValid(proof.consumeDigest, proof.address, cfg.gateId)
     } catch {
       return { ok: false, denied: 'ChainError' }
     }
     if (!ok) return { ok: false, denied: 'ConsumeMissing' }
-  } else {
-    let ok: boolean
-    try {
-      ok = await chain.ownsNft(proof.address, cfg.nftType, cfg.gateId)
-    } catch {
-      return { ok: false, denied: 'ChainError' }
-    }
-    if (!ok) return { ok: false, denied: 'NotOwner' }
+    // The consume is valid on-chain; the dispatcher leases/commits this digest so the use is
+    // spent only on a successful upload (and a duplicate can't double-spend it).
+    return { ok: true, address: proof.address, redemptionKey: proof.consumeDigest }
+  }
+
+  let ok: boolean
+  try {
+    ok = await chain.ownsNft(proof.address, cfg.nftType, cfg.gateId)
+  } catch {
+    return { ok: false, denied: 'ChainError' }
   }
+  if (!ok) return { ok: false, denied: 'NotOwner' }
 
   return { ok: true, address: proof.address }
 }

package/wrangler.toml

@@ -52,6 +52,13 @@ RATE_LIMIT_PER_MIN = "30"
 MAX_BODY_BYTES = "104857600"
 CHALLENGE_TTL_SECS = "300"
 OWNERSHIP_CACHE_TTL_MS = "0"
+# Single-use redemption: the permanent on-chain consumeDigest is the one-time token. A use is only
+# spent when an upload actually succeeds (commit); an interrupted upload releases the lease so the
+# consume stays redeemable (the use is never lost). LEASE_TTL bounds an in-flight upload; RETENTION
+# is how long a spent consume is remembered to block re-redemption (30d; a consume older than this
+# could be re-redeemed — an obscure, low-value edge).
+REDEMPTION_LEASE_TTL_SECS = "120"
+REDEMPTION_RETENTION_SECS = "2592000"
 # Workers-specific:
 NONCE_BACKEND = "durable-object" # "durable-object" (default) | "kv"
 NONCE_SHARD = "region"           # "region" (default) | "global"