@meddleware/nft-gate-gateway 0.0.1

package/src/crypto.ts

@@ -0,0 +1,78 @@
+/**
+ * Low-level hashing + encoding helpers, mirroring the Rust gateway's `verify.rs` primitives.
+ * Uses the audited `@noble/*` primitives (the same family `@mysten/sui` builds on) so the
+ * Worker needs no WebCrypto async quirks and stays consistent across ed25519/secp256k1/p256.
+ */
+
+import { blake2b } from '@noble/hashes/blake2.js'
+import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js'
+
+export function blake2b256(data: Uint8Array): Uint8Array {
+  return blake2b(data, { dkLen: 32 })
+}
+
+export function sha256(data: Uint8Array): Uint8Array {
+  return nobleSha256(data)
+}
+
+const HEX = '0123456789abcdef'
+
+export function bytesToHex(bytes: Uint8Array): string {
+  let out = ''
+  for (let i = 0; i < bytes.length; i++) {
+    out += HEX[bytes[i] >> 4] + HEX[bytes[i] & 0x0f]
+  }
+  return out
+}
+
+export function hexToBytes(hex: string): Uint8Array {
+  const s = hex.startsWith('0x') ? hex.slice(2) : hex
+  if (s.length % 2 !== 0) throw new Error('odd-length hex')
+  const out = new Uint8Array(s.length / 2)
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(s.slice(i * 2, i * 2 + 2), 16)
+  }
+  return out
+}
+
+/** base64 (standard) → bytes. Uses `atob` (present in the Workers runtime). */
+export function base64ToBytes(b64: string): Uint8Array {
+  const bin = atob(b64.trim())
+  const out = new Uint8Array(bin.length)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+export function bytesToBase64(bytes: Uint8Array): string {
+  let s = ''
+  for (let i = 0; i < bytes.length; i++) s += String.fromCharCode(bytes[i])
+  return btoa(s)
+}
+
+/** LEB128 unsigned encoding of `v` (matches Rust `write_uleb128`). */
+export function uleb128(v: number): Uint8Array {
+  const out: number[] = []
+  let n = v >>> 0
+  // Support lengths beyond 32 bits defensively, though messages are tiny.
+  let big = v
+  do {
+    let byte = big & 0x7f
+    big = Math.floor(big / 128)
+    if (big !== 0) byte |= 0x80
+    out.push(byte)
+    n = big
+  } while (n !== 0)
+  return Uint8Array.from(out)
+}
+
+export function concatBytes(...parts: Uint8Array[]): Uint8Array {
+  let len = 0
+  for (const p of parts) len += p.length
+  const out = new Uint8Array(len)
+  let off = 0
+  for (const p of parts) {
+    out.set(p, off)
+    off += p.length
+  }
+  return out
+}

package/src/index.ts

@@ -0,0 +1,173 @@
+/**
+ * Generic NFT-gated reverse proxy — Cloudflare Workers implementation.
+ *
+ * A drop-in, wire-identical sibling of the Rust gateway (`../rust`): same routes, status
+ * codes/messages, proof format, Sui RPC calls, and env-var config. Serves `GET /v1/challenge`,
+ * proxies configured public paths unauthenticated, and requires a valid wallet-signed access
+ * proof (verified against on-chain NFT ownership) for everything else. Mirror of `main.rs`.
+ */
+
+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 { verifyAccessRequest, deniedReason } from './verify.js'
+import { forward } from './proxy.js'
+import { runQuotaGuard } from './quota.js'
+
+export { NonceRateState } from './state/durable_object.js'
+
+/**
+ * Per-isolate cached gateway state. Holds the fully resolved config, the chosen nonce
+ * backend, and the Sui RPC client so they persist across requests within the same isolate.
+ */
+interface GatewayState {
+  cfg: Config
+  backend: NonceBackend
+  chain: SuiRpc
+}
+
+/** Lazily initialised once per isolate; `null` before the first request. */
+let cached: GatewayState | null = null
+
+/**
+ * Return (or lazily build) the per-isolate {@link GatewayState}. Checks a KV-based
+ * quota-degrade flag once per isolate and may switch to the KV backend when set.
+ *
+ * @param env - The Worker environment bindings for this deployment.
+ * @returns The resolved gateway state.
+ * @throws If required config vars are missing or the chosen nonce-backend binding is absent.
+ */
+async function getState(env: Env): Promise<GatewayState> {
+  if (cached) return cached
+  const cfg = loadConfig(env)
+  // Honour an operator/quota-guard "degrade" flag once per isolate: prefer KV before DO
+  // free-tier limits bite (only when a KV binding is available).
+  let effective = cfg
+  if (cfg.nonceBackend === 'durable-object' && env.NONCE_KV) {
+    try {
+      if (await env.NONCE_KV.get('quota:degrade')) effective = { ...cfg, nonceBackend: 'kv' }
+    } catch {
+      /* ignore — stay on the configured backend */
+    }
+  }
+  cached = {
+    cfg,
+    backend: makeBackend(effective, env),
+    chain: new SuiRpc(cfg.suiRpcUrl, cfg.ownershipCacheTtlMs, cfg.suiRpcAuthHeader),
+  }
+  return cached
+}
+
+/**
+ * Build a JSON response with the given status code.
+ *
+ * @param status - HTTP status code.
+ * @param body - Value to serialize as the response body.
+ * @returns A `Response` with `content-type: application/json`.
+ */
+function json(status: number, body: unknown): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+/**
+ * Build a JSON `{"error": reason}` response with the given status code.
+ *
+ * @param status - HTTP status code.
+ * @param reason - Short, client-visible error description.
+ * @returns A JSON error response.
+ */
+function deny(status: number, reason: string): Response {
+  return json(status, { error: reason })
+}
+
+/** Prefer `Authorization: Bearer <token>`; fall back to an explicit `X-Access-Proof` header. */
+function extractProofToken(request: Request): string | undefined {
+  const auth = request.headers.get('authorization')
+  if (auth) {
+    const m = auth.match(/^Bearer\s+(.+)$/i)
+    if (m) return m[1].trim()
+  }
+  const x = request.headers.get('x-access-proof')
+  return x ? x.trim() : undefined
+}
+
+/**
+ * Derive the nonce-shard region tag for a request.
+ *
+ * @param cfg - The resolved gateway config.
+ * @param request - The incoming Worker request (Cloudflare `cf` metadata is used when present).
+ * @returns A short string identifying the region (continent code or `"g"` for global).
+ */
+function regionOf(cfg: Config, request: Request): string {
+  if (cfg.nonceShard === 'global') return 'g'
+  const cf = (request as { cf?: { continent?: string } }).cf
+  const continent = cf?.continent
+  return continent ? continent.toLowerCase() : 'g'
+}
+
+/**
+ * Main request dispatcher. Handles `/healthz`, `/v1/challenge`, configured public paths,
+ * and gated paths (signature + ownership verification before proxying to the upstream).
+ *
+ * @param request - The incoming HTTP request.
+ * @param env - The Worker environment bindings.
+ * @returns A `Response` to send to the client.
+ */
+async function handle(request: Request, env: Env): Promise<Response> {
+  const url = new URL(request.url)
+  const path = url.pathname
+
+  if (path === '/healthz') return new Response('ok', { status: 200 })
+
+  let state: GatewayState
+  try {
+    state = await getState(env)
+  } catch (e) {
+    // Missing/invalid required config — fail closed (analogous to Rust's startup abort).
+    return deny(500, `gateway misconfigured: ${(e as Error).message}`)
+  }
+  const { cfg, backend, chain } = state
+
+  if (request.method === 'GET' && path === '/v1/challenge') {
+    const { nonce, expiresAt } = await backend.issue(regionOf(cfg, request), cfg.challengeTtlSecs)
+    return json(200, { nonce, expiresAt })
+  }
+
+  // Public passthrough (e.g. /v1/tip-config): forward without auth.
+  if (isPublicPath(cfg, path)) return forward(cfg, request)
+
+  const token = extractProofToken(request)
+  if (!token) return deny(401, 'missing access proof')
+
+  const result = await verifyAccessRequest(cfg, backend, token, chain)
+  if (!result.ok) {
+    const status = result.denied === 'ChainError' ? 502 : 403
+    return deny(status, deniedReason(result.denied))
+  }
+
+  if (!(await backend.rateCheck(result.address, cfg.rateLimitPerMin, regionOf(cfg, request)))) {
+    return deny(429, 'rate limit exceeded')
+  }
+
+  return forward(cfg, request)
+}
+
+/**
+ * Cloudflare Worker entry point. The `fetch` handler routes all HTTP traffic through
+ * {@link handle}; the `scheduled` handler runs the optional quota guard on a cron trigger.
+ */
+export default {
+  fetch(request: Request, env: Env): Promise<Response> {
+    return handle(request, env)
+  },
+  async scheduled(_controller: ScheduledController, env: Env): Promise<void> {
+    if ((env.QUOTA_GUARD_ENABLED ?? 'false').toLowerCase() === 'true') {
+      await runQuotaGuard(env)
+    }
+  },
+}

package/src/proxy.ts

@@ -0,0 +1,81 @@
+/**
+ * Reverse-proxy an authorised request to the configured upstream. Mirror of the Rust
+ * gateway's `proxy.rs`: body capped at `maxBodyBytes` before forwarding; `Host` /
+ * `Authorization` / `Content-Length` stripped from the request; hop-unsafe headers stripped
+ * from the response.
+ *
+ * `cfg.upstreamAuthHeaders` are injected on the upstream fetch — use this to pass
+ * Cloudflare Access service-token headers when the relay origin is Access-locked.
+ */
+
+import type { Config } from './config.js'
+
+/**
+ * Build a JSON `{"error": reason}` response with the given status code.
+ *
+ * @param status - HTTP status code.
+ * @param reason - Short, client-visible error description.
+ * @returns A JSON error response.
+ */
+function errorResponse(status: number, reason: string): Response {
+  return new Response(JSON.stringify({ error: reason }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+/**
+ * Forward an authorised request to the configured upstream origin.
+ *
+ * Strips `Host`, `Authorization`, `X-Access-Proof`, and `Content-Length` from the request;
+ * strips `Content-Length`, `Transfer-Encoding`, and `Connection` from the response.
+ * Injects `cfg.upstreamAuthHeaders` on the upstream fetch (e.g. CF Access service-token headers).
+ * Returns 413 if the body exceeds `cfg.maxBodyBytes`.
+ *
+ * @param cfg - The resolved gateway config.
+ * @param request - The original incoming Worker request.
+ * @returns The upstream response, or an error response on failure.
+ * @throws Never — upstream failures are caught and returned as 502.
+ */
+export async function forward(cfg: Config, request: Request): Promise<Response> {
+  const url = new URL(request.url)
+  const pathAndQuery = url.pathname + url.search
+  const upstreamUrl = cfg.upstreamUrl + pathAndQuery
+
+  // Read + cap the body (a griefing guard) before forwarding.
+  let body: ArrayBuffer | undefined
+  const method = request.method.toUpperCase()
+  if (method !== 'GET' && method !== 'HEAD') {
+    const buf = await request.arrayBuffer()
+    if (buf.byteLength > cfg.maxBodyBytes) {
+      return errorResponse(413, 'request body too large')
+    }
+    body = buf
+  }
+
+  const headers = new Headers(request.headers)
+  headers.delete('host')
+  headers.delete('authorization')
+  headers.delete('x-access-proof')
+  headers.delete('content-length')
+
+  // Inject upstream auth headers (e.g. CF Access service token for the locked relay origin).
+  for (const { name, value } of cfg.upstreamAuthHeaders) {
+    headers.set(name, value)
+  }
+
+  let upstream: Response
+  try {
+    upstream = await fetch(upstreamUrl, { method: request.method, headers, body })
+  } catch {
+    return errorResponse(502, 'upstream error')
+  }
+
+  // Strip hop-unsafe / recomputed headers from the response.
+  const outHeaders = new Headers(upstream.headers)
+  outHeaders.delete('content-length')
+  outHeaders.delete('transfer-encoding')
+  outHeaders.delete('connection')
+
+  return new Response(upstream.body, { status: upstream.status, headers: outHeaders })
+}

package/src/quota.ts

@@ -0,0 +1,116 @@
+/**
+ * OPTIONAL free-tier quota guard (off by default; `QUOTA_GUARD_ENABLED=true`). Cloudflare
+ * exposes account **usage** via the GraphQL Analytics API but **not** per-account *limit*
+ * values, so this compares current usage against the published Workers-Free thresholds
+ * (constants below — verify against the current pricing docs at deploy time).
+ *
+ * It (a) logs a warning as usage approaches a threshold and (b) can set a KV "degrade" flag
+ * that {@link ../config} consumers may honour to prefer the KV backend before DO limits bite.
+ * It never pre-pays or maintains a balance; it needs only a read-only Analytics API token.
+ */
+
+import type { Env } from './config.js'
+
+/** Published Workers Free plan monthly request limit. Verify against current pricing docs at deploy time. */
+const FREE_REQUESTS_PER_MONTH = 3_000_000
+/** Published Workers Free plan monthly Durable Object GB-second limit. Verify against current pricing docs. */
+const FREE_DO_GB_S_PER_MONTH = 390_000
+/** Log a warning when usage reaches this fraction of any free-tier limit. */
+const WARN_AT = 0.8
+/** Set the KV degrade flag when usage reaches this fraction of any free-tier limit. */
+const DEGRADE_AT = 0.95
+
+/** Cloudflare GraphQL Analytics API endpoint. */
+const GRAPHQL_URL = 'https://api.cloudflare.com/client/v4/graphql'
+
+/**
+ * Aggregated monthly usage snapshot for this Cloudflare account.
+ * `requests` — total Workers + DO invocations this calendar month.
+ * `doGbSeconds` — Durable Object GB-seconds of active time this calendar month.
+ */
+interface Usage {
+  requests: number
+  doGbSeconds: number
+}
+
+/**
+ * Run the optional free-tier quota guard. Reads monthly usage via the Cloudflare GraphQL
+ * Analytics API, logs a warning near a limit, and sets (or clears) a KV `quota:degrade` flag
+ * that the isolate-state bootstrap may honour to prefer the KV nonce backend.
+ *
+ * @param env - Worker environment bindings. Requires `CF_ANALYTICS_TOKEN` and `CF_ACCOUNT_ID`;
+ *   optionally uses `NONCE_KV` to set the degrade flag.
+ * @returns Resolves when the check completes (never rejects — errors are logged and suppressed).
+ */
+export async function runQuotaGuard(env: Env): Promise<void> {
+  if (!env.CF_ANALYTICS_TOKEN || !env.CF_ACCOUNT_ID) {
+    console.warn('quota-guard: CF_ANALYTICS_TOKEN / CF_ACCOUNT_ID not set; skipping')
+    return
+  }
+  let usage: Usage
+  try {
+    usage = await fetchMonthlyUsage(env.CF_ANALYTICS_TOKEN, env.CF_ACCOUNT_ID)
+  } catch (e) {
+    console.warn('quota-guard: usage query failed:', (e as Error).message)
+    return
+  }
+
+  const reqPct = usage.requests / FREE_REQUESTS_PER_MONTH
+  const doPct = usage.doGbSeconds / FREE_DO_GB_S_PER_MONTH
+  const worst = Math.max(reqPct, doPct)
+
+  if (worst >= WARN_AT) {
+    console.warn(
+      `quota-guard: usage at ${(worst * 100).toFixed(0)}% of a Workers-Free limit ` +
+        `(requests ${(reqPct * 100).toFixed(0)}%, DO ${(doPct * 100).toFixed(0)}%)`,
+    )
+  }
+  if (env.NONCE_KV) {
+    if (worst >= DEGRADE_AT) {
+      await env.NONCE_KV.put('quota:degrade', '1', { expirationTtl: 3600 })
+      console.warn('quota-guard: set KV degrade flag (prefer KV backend)')
+    } else {
+      await env.NONCE_KV.delete('quota:degrade')
+    }
+  }
+}
+
+/**
+ * Fetch aggregated Workers + DO usage for the current UTC calendar month.
+ *
+ * @param token - Read-only Cloudflare Analytics API token.
+ * @param accountId - Cloudflare account ID (`CF_ACCOUNT_ID`).
+ * @returns A {@link Usage} snapshot for the month so far.
+ * @throws If the GraphQL HTTP response is not OK.
+ */
+async function fetchMonthlyUsage(token: string, accountId: string): Promise<Usage> {
+  const since = new Date()
+  since.setUTCDate(1)
+  since.setUTCHours(0, 0, 0, 0)
+  const query = `query($accountTag: String!, $since: Time!) {
+    viewer { accounts(filter: { accountTag: $accountTag }) {
+      workersInvocationsAdaptive(limit: 10000, filter: { datetime_geq: $since }) { sum { requests } }
+      durableObjectsInvocationsAdaptiveGroups(limit: 10000, filter: { datetime_geq: $since }) { sum { requests } }
+      durableObjectsPeriodicGroups(limit: 10000, filter: { datetime_geq: $since }) { sum { activeTime } }
+    } }
+  }`
+  const resp = await fetch(GRAPHQL_URL, {
+    method: 'POST',
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: JSON.stringify({ query, variables: { accountTag: accountId, since: since.toISOString() } }),
+  })
+  if (!resp.ok) throw new Error(`graphql http ${resp.status}`)
+  const json = (await resp.json()) as {
+    data?: { viewer?: { accounts?: Array<Record<string, Array<{ sum?: { requests?: number; activeTime?: number } }>>> } }
+  }
+  const acct = json.data?.viewer?.accounts?.[0]
+  const sumField = (rows: Array<{ sum?: { requests?: number; activeTime?: number } }> | undefined, key: 'requests' | 'activeTime'): number =>
+    (rows ?? []).reduce((n, r) => n + (r.sum?.[key] ?? 0), 0)
+  const requests =
+    sumField(acct?.workersInvocationsAdaptive, 'requests') +
+    sumField(acct?.durableObjectsInvocationsAdaptiveGroups, 'requests')
+  // activeTime is reported in microseconds → GB-seconds requires the memory tier; approximate
+  // with seconds of active time as a conservative signal (documented; refine per pricing docs).
+  const doGbSeconds = sumField(acct?.durableObjectsPeriodicGroups, 'activeTime') / 1_000_000
+  return { requests, doGbSeconds }
+}

package/src/state/durable_object.ts

@@ -0,0 +1,139 @@
+/**
+ * Region-sharded, SQLite-backed Durable Object state — the default nonce store + rate limiter.
+ *
+ * Each region gets its own DO instance (id = `nonce:<region>`), which Cloudflare places near
+ * the request that first initializes it — so the shard sits close to its users. The issued
+ * nonce embeds the region tag (`<region>.<hex>`) so a later consume always routes back to the
+ * ISSUING shard, even under anycast drift.
+ *
+ * Single-threaded per DO ⇒ `takeIfValid` is atomic (the Redis-`GETDEL` analog): a nonce is
+ * consumed exactly once. Free-tier eligible (SQLite storage on the Workers Free plan).
+ */
+
+import { DurableObject } from 'cloudflare:workers'
+import type { NonceBackend } from './types.js'
+import { randomHex24, shardOfNonce } from './types.js'
+
+/** SQLite row shape for the `nonces` table. */
+interface NonceRow {
+  expiry: number
+}
+/** SQLite row shape for the `rate` table. */
+interface RateRow {
+  start: number
+  count: number
+}
+/** Result row for `SELECT COUNT(*) AS c`. */
+interface CountRow {
+  c: number
+}
+
+/**
+ * Durable Object that provides the SQLite-backed nonce store and per-address rate limiter.
+ * Each instance corresponds to one region shard (id = `nonce:<region>`). Single-threaded
+ * per instance, so `takeIfValid` is naturally atomic (the Redis-`GETDEL` analog).
+ */
+export class NonceRateState extends DurableObject {
+  private readonly sql: SqlStorage
+
+  /**
+   * @param ctx - Durable Object state, provides the SQLite storage handle.
+   * @param env - Worker environment (not used directly; passed through to the base class).
+   */
+  constructor(ctx: DurableObjectState, env: unknown) {
+    super(ctx as DurableObjectState, env as never)
+    this.sql = ctx.storage.sql
+    this.sql.exec(
+      'CREATE TABLE IF NOT EXISTS nonces (nonce TEXT PRIMARY KEY, expiry INTEGER NOT NULL)',
+    )
+    this.sql.exec(
+      'CREATE TABLE IF NOT EXISTS rate (addr TEXT PRIMARY KEY, start INTEGER NOT NULL, count INTEGER NOT NULL)',
+    )
+  }
+
+  /** Store a fresh nonce with a hard entry cap (evict soonest-to-expire). Returns expiry ms. */
+  issue(nonce: string, ttlSecs: number, maxEntries: number): number {
+    const now = Date.now()
+    const expiry = now + ttlSecs * 1000
+    // Prune expired first (bounded growth independent of issue cadence).
+    this.sql.exec('DELETE FROM nonces WHERE expiry <= ?', now)
+    const count = (this.sql.exec('SELECT COUNT(*) AS c FROM nonces').one() as unknown as CountRow).c
+    if (count >= Math.max(1, maxEntries)) {
+      this.sql.exec(
+        'DELETE FROM nonces WHERE nonce = (SELECT nonce FROM nonces ORDER BY expiry ASC LIMIT 1)',
+      )
+    }
+    this.sql.exec('INSERT OR REPLACE INTO nonces (nonce, expiry) VALUES (?, ?)', nonce, expiry)
+    return expiry
+  }
+
+  /** Atomically consume a nonce: true iff present and unexpired. Deletes on read (single-use). */
+  takeIfValid(nonce: string): boolean {
+    const now = Date.now()
+    const rows = this.sql.exec('SELECT expiry FROM nonces WHERE nonce = ?', nonce).toArray() as unknown as NonceRow[]
+    if (rows.length === 0) return false
+    // Consume unconditionally (present ⇒ gone), so it can never be replayed.
+    this.sql.exec('DELETE FROM nonces WHERE nonce = ?', nonce)
+    return Number(rows[0].expiry) > now
+  }
+
+  /** Fixed 60s window per address. */
+  rateCheck(addr: string, maxPerMin: number): boolean {
+    if (maxPerMin === 0) return true
+    const now = Date.now()
+    const rows = this.sql.exec('SELECT start, count FROM rate WHERE addr = ?', addr).toArray() as unknown as RateRow[]
+    let start = now
+    let count = 0
+    if (rows.length > 0) {
+      const r = rows[0]
+      if (now - Number(r.start) < 60000) {
+        start = Number(r.start)
+        count = Number(r.count)
+      }
+    }
+    if (count >= maxPerMin) return false
+    this.sql.exec('INSERT OR REPLACE INTO rate (addr, start, count) VALUES (?, ?, ?)', addr, start, count + 1)
+    return true
+  }
+}
+
+/** {@link NonceBackend} that fans out to per-region {@link NonceRateState} DO shards. */
+export class DurableObjectBackend implements NonceBackend {
+  /**
+   * @param ns - The Durable Object namespace binding for `NonceRateState`.
+   * @param shardMode - `"region"` places each shard near its users; `"global"` uses one instance.
+   * @param maxEntries - Hard cap on live nonce entries per shard (evicts oldest when reached).
+   */
+  constructor(
+    private readonly ns: DurableObjectNamespace<NonceRateState>,
+    private readonly shardMode: 'region' | 'global',
+    private readonly maxEntries: number,
+  ) {}
+
+  /**
+   * Retrieve the DO stub for the given region, creating a new shard if needed.
+   *
+   * @param region - The region tag used to derive the DO instance name (`nonce:<region>`).
+   * @returns A `DurableObjectStub` for that region's shard.
+   */
+  private stub(region: string): DurableObjectStub<NonceRateState> {
+    const id = this.ns.idFromName('nonce:' + region)
+    return this.ns.get(id)
+  }
+
+  async issue(region: string, ttlSecs: number): Promise<{ nonce: string; expiresAt: number }> {
+    const shard = this.shardMode === 'global' ? 'g' : region
+    const nonce = `${shard}.${randomHex24()}`
+    const expiresAt = await this.stub(shard).issue(nonce, ttlSecs, this.maxEntries)
+    return { nonce, expiresAt }
+  }
+
+  async takeIfValid(nonce: string): Promise<boolean> {
+    return this.stub(shardOfNonce(nonce)).takeIfValid(nonce)
+  }
+
+  async rateCheck(address: string, maxPerMin: number, region: string): Promise<boolean> {
+    const shard = this.shardMode === 'global' ? 'g' : region
+    return this.stub(shard).rateCheck(address, maxPerMin)
+  }
+}

package/src/state/kv.ts

@@ -0,0 +1,81 @@
+/**
+ * Workers KV nonce store + best-effort rate limiter — the pure free-tier fallback backend
+ * (`NONCE_BACKEND=kv`). KV has native per-key TTL, but is **eventually consistent**: `get`
+ * then `delete` is not atomic, so a nonce could momentarily read valid in two regions within
+ * its TTL — a weaker cross-region replay window in the `SINGLE_USE=false` ownership mode. (In
+ * `SINGLE_USE=true` mode the on-chain `AccessConsumedEvent` remains the authoritative single-
+ * use bind, so that mode is unaffected.) Use the Durable Object backend when this matters.
+ */
+
+import type { 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:'
+/** Workers KV minimum `expirationTtl` (seconds). Sub-60s logical TTLs are enforced in-value. */
+const KV_MIN_TTL_SECS = 60
+
+/**
+ * {@link NonceBackend} implementation backed by Workers KV. Purely free-tier with no
+ * additional bindings beyond a `KVNamespace`. See the module doc for consistency caveats.
+ */
+export class KvBackend implements NonceBackend {
+  /**
+   * @param kv - The `KVNamespace` binding to use for nonce and rate-limit storage.
+   */
+  constructor(private readonly kv: KVNamespace) {}
+
+  async issue(_region: string, ttlSecs: number): Promise<{ nonce: string; expiresAt: number }> {
+    // KV is global; the shard tag is cosmetic here (kept for a uniform nonce format).
+    const nonce = `g.${randomHex24()}`
+    const expiresAt = Date.now() + ttlSecs * 1000
+    // The logical expiry is stored IN the value and enforced on read, so sub-60s TTLs are
+    // honoured exactly; KV's own `expirationTtl` (min 60s) is only a GC backstop.
+    await this.kv.put(NONCE_PREFIX + nonce, JSON.stringify({ e: expiresAt }), {
+      expirationTtl: Math.max(KV_MIN_TTL_SECS, ttlSecs),
+    })
+    return { nonce, expiresAt }
+  }
+
+  async takeIfValid(nonce: string): Promise<boolean> {
+    const key = NONCE_PREFIX + nonce
+    const v = await this.kv.get(key)
+    if (v === null) return false
+    // Best-effort single-use: delete after a positive read (not atomic — see module note).
+    await this.kv.delete(key)
+    let expiry = 0
+    try {
+      expiry = (JSON.parse(v) as { e: number }).e
+    } catch {
+      return false
+    }
+    return expiry > Date.now()
+  }
+
+  async rateCheck(address: string, maxPerMin: number, _region: string): Promise<boolean> {
+    if (maxPerMin === 0) return true
+    const key = RATE_PREFIX + address
+    const raw = await this.kv.get(key)
+    const now = Date.now()
+    let start = now
+    let count = 0
+    if (raw) {
+      try {
+        const p = JSON.parse(raw) as { start: number; count: number }
+        if (now - p.start < 60000) {
+          start = p.start
+          count = p.count
+        }
+      } catch {
+        /* treat as a fresh window */
+      }
+    }
+    if (count >= maxPerMin) return false
+    await this.kv.put(key, JSON.stringify({ start, count: count + 1 }), {
+      expirationTtl: KV_MIN_TTL_SECS,
+    })
+    return true
+  }
+}