@meddleware/nft-gate-gateway 0.0.1

package/src/state/select.ts

@@ -0,0 +1,35 @@
+/**
+ * Backend selection — the Workers analog of the Rust gateway's `main.rs` store bootstrap
+ * (`REDIS_URL ? redis : in_memory`). Chooses the Durable Object or KV backend from config +
+ * available bindings, failing fast if the chosen backend's binding is missing.
+ */
+
+import type { Config, Env } from '../config.js'
+import type { NonceBackend } from './types.js'
+import type { NonceRateState } from './durable_object.js'
+import { DurableObjectBackend } from './durable_object.js'
+import { KvBackend } from './kv.js'
+
+/**
+ * Instantiate the appropriate {@link NonceBackend} from config and available bindings.
+ * Mirrors the Rust gateway's startup-time store selection (`REDIS_URL ? redis : in_memory`).
+ *
+ * @param cfg - The resolved gateway config, potentially modified by the quota-degrade flag.
+ * @param env - Worker environment bindings.
+ * @returns A configured `NonceBackend` instance.
+ * @throws If the required binding for the chosen backend is absent.
+ */
+export function makeBackend(cfg: Config, env: Env): NonceBackend {
+  if (cfg.nonceBackend === 'kv') {
+    if (!env.NONCE_KV) throw new Error('NONCE_BACKEND=kv but the NONCE_KV binding is missing')
+    return new KvBackend(env.NONCE_KV)
+  }
+  if (!env.NONCE_STATE) {
+    throw new Error('NONCE_BACKEND=durable-object but the NONCE_STATE binding is missing')
+  }
+  return new DurableObjectBackend(
+    env.NONCE_STATE as DurableObjectNamespace<NonceRateState>,
+    cfg.nonceShard,
+    cfg.nonceMaxEntries,
+  )
+}

package/src/state/types.ts

@@ -0,0 +1,49 @@
+/**
+ * The pluggable state backend — the Workers analog of the Rust gateway's `NonceStore` enum
+ * (in-memory | Redis). It holds the single-use nonce store AND the per-address rate-limit
+ * windows, because both need the same per-key atomicity a stateless isolate cannot give.
+ *
+ * Two implementations:
+ * - `DurableObjectBackend` (default): region-sharded, SQLite-backed Durable Objects. Strongly
+ *   consistent, atomic single-use consume (the Redis-`GETDEL` analog). Free-tier eligible.
+ * - `KvBackend`: Workers KV + best-effort rate limit. Eventually consistent (documented weaker
+ *   cross-region replay window in the `SINGLE_USE=false` ownership mode).
+ */
+
+export interface NonceBackend {
+  /**
+   * Issue a fresh, time-bound nonce. `region` selects the DO shard (ignored by KV, which is
+   * global). Returns the opaque `<region>.<hex>` nonce and its unix-ms expiry.
+   */
+  issue(region: string, ttlSecs: number): Promise<{ nonce: string; expiresAt: number }>
+  /** Consume a nonce exactly once; true iff it was valid, unexpired, and unused. */
+  takeIfValid(nonce: string): Promise<boolean>
+  /** Fixed 60s window per verified address. `maxPerMin === 0` disables limiting. */
+  rateCheck(address: string, maxPerMin: number, region: string): Promise<boolean>
+}
+
+/**
+ * Parse the shard tag embedded in a `<region>.<hex>` nonce so a consume call always routes
+ * back to the shard that issued it, even under anycast region drift.
+ *
+ * @param nonce - A nonce in `<region>.<hex>` format.
+ * @returns The region prefix (e.g. `"eu"`), or `"g"` if no dot is present.
+ */
+export function shardOfNonce(nonce: string): string {
+  const dot = nonce.indexOf('.')
+  return dot > 0 ? nonce.slice(0, dot) : 'g'
+}
+
+/**
+ * Generate a cryptographically random 48-character hex string (24 bytes of entropy). Matches
+ * the Rust gateway's `random_nonce()` entropy so conformance vectors apply to both.
+ *
+ * @returns A 48-character lowercase hex string.
+ */
+export function randomHex24(): string {
+  const buf = new Uint8Array(24)
+  crypto.getRandomValues(buf)
+  let out = ''
+  for (let i = 0; i < buf.length; i++) out += buf[i].toString(16).padStart(2, '0')
+  return out
+}

package/src/verify.ts

@@ -0,0 +1,216 @@
+/**
+ * Access verification — the security core. Direct Sui personal-message signature checking
+ * plus the allow/deny decision. A 1:1 port of the Rust gateway's `verify.rs`; the on-chain
+ * lookups are abstracted behind {@link ChainQuery} so the decision is unit-testable offline.
+ */
+
+import { ed25519 } from '@noble/curves/ed25519.js'
+import { secp256k1 } from '@noble/curves/secp256k1.js'
+import { p256 } from '@noble/curves/nist.js'
+import type { Config } from './config.js'
+import type { NonceBackend } from './state/types.js'
+import { blake2b256, base64ToBytes, bytesToHex, concatBytes, uleb128 } from './crypto.js'
+import { personalMessageForNonce, decodeAccessProof } from './wire.js'
+
+// Sui signature-scheme flag bytes (first byte of a serialized signature).
+const FLAG_ED25519 = 0x00
+const FLAG_SECP256K1 = 0x01
+const FLAG_SECP256R1 = 0x02
+const FLAG_MULTISIG = 0x03
+const FLAG_ZKLOGIN = 0x05
+
+/** blake2b256( intent(PersonalMessage,V0,Sui) || bcs(Vec<u8> message) ) — what a Sui wallet signs. */
+export function signingDigest(message: Uint8Array): Uint8Array {
+  const intent = Uint8Array.from([3, 0, 0]) // IntentScope::PersonalMessage, V0, AppId::Sui
+  return blake2b256(concatBytes(intent, uleb128(message.length), message))
+}
+
+/** Sui address for a scheme: `0x` + hex(blake2b256(flag || pubkey)). */
+export function deriveAddress(flag: number, pk: Uint8Array): string {
+  return '0x' + bytesToHex(blake2b256(concatBytes(Uint8Array.from([flag]), pk)))
+}
+
+export function normalizeAddress(a: string): string {
+  const s = a.trim().replace(/^0x/i, '').toLowerCase()
+  return '0x' + s.padStart(64, '0')
+}
+
+/**
+ * Verify a Sui personal-message signature recovers `address` over `message`, dispatching on
+ * the scheme flag byte. Serialized layout: `flag(1) || signature || pubkey` (base64).
+ *
+ * Supported: ed25519 (0x00), secp256k1 (0x01), secp256r1 (0x02). multisig (0x03) and zkLogin
+ * (0x05) are recognised but not yet verified (they need the official Sui verifier) and fail
+ * **closed** — identical posture to the Rust gateway (audit F1).
+ */
+export function verifyPersonalMessageSignature(
+  address: string,
+  message: Uint8Array,
+  signatureB64: string,
+): boolean {
+  let raw: Uint8Array
+  try {
+    raw = base64ToBytes(signatureB64)
+  } catch {
+    return false
+  }
+  if (raw.length === 0) return false
+  const flag = raw[0]
+  const body = raw.subarray(1)
+  switch (flag) {
+    case FLAG_ED25519:
+      return verifyEd25519(address, message, body)
+    case FLAG_SECP256K1:
+      return verifyEcdsa(secp256k1, FLAG_SECP256K1, address, message, body)
+    case FLAG_SECP256R1:
+      return verifyEcdsa(p256, FLAG_SECP256R1, address, message, body)
+    case FLAG_MULTISIG:
+    case FLAG_ZKLOGIN:
+      // Recognised but not yet supported by this verifier (fails closed); see gateway audit F1.
+      return false
+    default:
+      return false
+  }
+}
+
+/** ed25519 (flag 0x00): body = `sig(64) || pubkey(32)`. */
+function verifyEd25519(address: string, message: Uint8Array, body: Uint8Array): boolean {
+  if (body.length !== 96) return false
+  const sig = body.subarray(0, 64)
+  const pk = body.subarray(64, 96)
+  const digest = signingDigest(message)
+  let ok = false
+  try {
+    ok = ed25519.verify(sig, digest, pk)
+  } catch {
+    return false
+  }
+  if (!ok) return false
+  return normalizeAddress(address) === deriveAddress(FLAG_ED25519, pk)
+}
+
+/**
+ * secp256k1 (0x01) / secp256r1 (0x02): body = `sig(64, compact r||s) || pubkey(33, SEC1-
+ * compressed)`. Sui signs `SHA256(blake2b256(intent||msg))` with ECDSA; noble's `verify` applies
+ * the SHA256 step internally, so we pass the blake2b digest and let the curve do the rest.
+ * `lowS: true` matches Sui's low-S normalisation.
+ */
+function verifyEcdsa(
+  curve: typeof secp256k1 | typeof p256,
+  flag: number,
+  address: string,
+  message: Uint8Array,
+  body: Uint8Array,
+): boolean {
+  if (body.length !== 97) return false
+  const sig = body.subarray(0, 64)
+  const pk = body.subarray(64, 97)
+  const msgHash = signingDigest(message)
+  let ok = false
+  try {
+    ok = curve.verify(sig, msgHash, pk, { lowS: true })
+  } catch {
+    return false
+  }
+  if (!ok) return false
+  return normalizeAddress(address) === deriveAddress(flag, pk)
+}
+
+/** On-chain lookups needed to authorise a request. Implemented by {@link ../chain.SuiRpc}. */
+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>
+}
+
+export type Denied =
+  | 'BadProof'
+  | 'BadSignature'
+  | 'NonceInvalid'
+  | 'NotOwner'
+  | 'ConsumeMissing'
+  | 'ChainError'
+
+export function deniedReason(d: Denied): string {
+  switch (d) {
+    case 'BadProof':
+      return 'malformed access proof'
+    case 'BadSignature':
+      return 'signature does not recover address'
+    case 'NonceInvalid':
+      return 'challenge nonce invalid, expired, or already used'
+    case 'NotOwner':
+      return 'address does not hold the required access NFT'
+    case 'ConsumeMissing':
+      return 'no matching single-use consume for this challenge'
+    case 'ChainError':
+      return 'on-chain verification failed'
+  }
+}
+
+export type VerifyResult = { ok: true; address: string } | { ok: false; denied: Denied }
+
+/**
+ * Authorise a request from its base64 proof token. The nonce is consumed (single-use at the
+ * gateway) as part of a successful signature check, so a replay presents an already-used
+ * nonce and is rejected. Mirror of Rust `verify_access_request`.
+ */
+export async function verifyAccessRequest(
+  cfg: Config,
+  store: NonceBackend,
+  token: string,
+  chain: ChainQuery,
+): Promise<VerifyResult> {
+  let proof
+  try {
+    proof = decodeAccessProof(token)
+  } catch {
+    return { ok: false, denied: 'BadProof' }
+  }
+
+  const message = personalMessageForNonce(proof.nonce)
+  if (!verifyPersonalMessageSignature(proof.address, message, proof.signature)) {
+    return { ok: false, denied: 'BadSignature' }
+  }
+
+  // Consume the nonce exactly once (fresh, unexpired, unused) — before the chain call.
+  if (!(await store.takeIfValid(proof.nonce))) {
+    return { ok: false, denied: 'NonceInvalid' }
+  }
+
+  if (cfg.singleUse) {
+    if (proof.consumeDigest === undefined) {
+      return { ok: false, denied: 'ConsumeMissing' }
+    }
+    let ok: boolean
+    try {
+      ok = await chain.consumeEventMatches(
+        proof.nonce,
+        proof.address,
+        cfg.nftType,
+        cfg.gateId,
+        proof.consumeDigest,
+      )
+    } 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' }
+  }
+
+  return { ok: true, address: proof.address }
+}
+
+export { FLAG_ED25519, FLAG_SECP256K1, FLAG_SECP256R1, FLAG_MULTISIG, FLAG_ZKLOGIN }

package/src/wire.ts

@@ -0,0 +1,20 @@
+/**
+ * The shared wire-format helpers, REUSED from `@meddleware/nft-gate-client` rather than
+ * re-implemented — there must be exactly one source for `personalMessageForNonce` and the
+ * proof token shape across the toolkit (the "one contract that spans all three" rule in
+ * nft-gate/CLAUDE.md).
+ *
+ * Imported by relative path (the in-repo convention) directly from the client's `proof.ts` /
+ * `types.ts`, which import only `./types.js` — so this pulls in NO `@mysten/sui` and keeps the
+ * Worker bundle lean.
+ *
+ * Self-contained-mirror alternative (documented for future review): if the Worker must ship
+ * fully decoupled from the client package, replace these two lines with a local copy of
+ * `personalMessageForNonce` + `decodeAccessProof` guarded by `conformance/vectors.json`.
+ */
+
+export {
+  personalMessageForNonce,
+  decodeAccessProof,
+} from '@meddleware/nft-gate-client'
+export type { AccessProof } from '@meddleware/nft-gate-client'

package/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "lib": ["ES2022"],
+    "types": ["@cloudflare/workers-types"],
+    "strict": true,
+    "noUncheckedIndexedAccess": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": false,
+    "noEmit": true,
+    "resolveJsonModule": true
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts", "../conformance/**/*.json"]
+}

package/wrangler.toml

@@ -0,0 +1,83 @@
+# nft-gate-gateway — Cloudflare Workers deployment.
+#
+# Wire-identical to the Rust gateway (../gateway). Bind it to the SAME public hostname the
+# Rust gateway serves (see [routes] below) to switch implementations with nothing else changing.
+#
+# OPERATOR SETUP — run these once before deploying, then never touch them again:
+#
+#   UPSTREAM_URL (required — your CF-Access-locked relay/upstream origin):
+#     wrangler secret put UPSTREAM_URL
+#     Value: the full origin URL (e.g. https://your-origin.example.com)
+#     This is kept as a secret so it does not appear in this public file and is
+#     not overwritten by `wrangler deploy`.
+#
+#   NFT_TYPE (required — set after publishing your access_gate contract on-chain):
+#     wrangler secret put NFT_TYPE
+#     Value: "<PACKAGE_ID>::access_gate::SoulboundAccessNFT"
+#     Update this whenever you redeploy the on-chain contract.
+#
+#   UPSTREAM_AUTH_HEADERS (required for CF-Access-locked origin):
+#     wrangler secret put UPSTREAM_AUTH_HEADERS
+#     Value: "CF-Access-Client-Id: <id>, CF-Access-Client-Secret: <secret>"
+#     Obtain from: Cloudflare Zero Trust → Access → Service Tokens → create token
+#     The Access policy on your origin hostname must allow this token.
+#
+#   SUI_RPC_AUTH_HEADER (optional — only if using an authenticated/private RPC):
+#     wrangler secret put SUI_RPC_AUTH_HEADER
+#     Value: "Authorization: Bearer <token>"
+#
+#   CF_ANALYTICS_TOKEN (optional — only if QUOTA_GUARD_ENABLED=true):
+#     wrangler secret put CF_ANALYTICS_TOKEN
+#   CF_ACCOUNT_ID (optional — only if QUOTA_GUARD_ENABLED=true):
+#     wrangler secret put CF_ACCOUNT_ID
+
+name = "nft-gate-gateway"
+main = "src/index.ts"
+compatibility_date = "2025-04-01"
+compatibility_flags = ["nodejs_compat"]
+
+# ── config (parity with the Rust gateway env; see README.md for the mapping) ─────────────────
+[vars]
+# UPSTREAM_URL and NFT_TYPE are set via `wrangler secret put` (see above) so that
+# deployment-specific values never appear in this public file and are never overwritten
+# by `wrangler deploy`. Do not add them here.
+
+# Public fullnode — safe to keep as a plain var (no sensitive information).
+SUI_RPC_URL = "https://fullnode.testnet.sui.io:443"
+
+GATE_ID = ""         # operator: set to the access_gate registry object ID (single-registry mode)
+SINGLE_USE = "false"
+PUBLIC_PATHS = "/v1/tip-config"
+RATE_LIMIT_PER_MIN = "30"
+MAX_BODY_BYTES = "262144"
+CHALLENGE_TTL_SECS = "300"
+OWNERSHIP_CACHE_TTL_MS = "0"
+# Workers-specific:
+NONCE_BACKEND = "durable-object" # "durable-object" (default) | "kv"
+NONCE_SHARD = "region"           # "region" (default) | "global"
+NONCE_MAX_ENTRIES = "1000000"
+QUOTA_GUARD_ENABLED = "false"
+
+# ── nonce store + rate limiter: region-sharded, SQLite-backed Durable Objects (free-tier) ────
+[[durable_objects.bindings]]
+name = "NONCE_STATE"
+class_name = "NonceRateState"
+
+[[migrations]]
+tag = "v1"
+new_sqlite_classes = ["NonceRateState"]
+
+# ── KV backend (only needed when NONCE_BACKEND=kv) ────────────────────────────────────────────
+# [[kv_namespaces]]
+# binding = "NONCE_KV"
+# id = "<KV_NAMESPACE_ID>"   # create with: wrangler kv namespace create NONCE_KV
+
+# ── route: Worker serves as the public NFT-gated relay endpoint ───────────────────────────────
+# operator: uncomment and fill in after creating the Worker route in the CF dashboard
+# [[routes]]
+# pattern = "nft-gate.example.com/*"
+# zone_name = "example.com"
+
+# ── optional quota guard (needs QUOTA_GUARD_ENABLED=true + the secrets above) ────────────────
+# [triggers]
+# crons = ["*/15 * * * *"]