@meddleware/nft-gate-gateway 0.0.1

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,205 @@
+# @meddleware/nft-gate-gateway-workers
+
+[![npm](https://img.shields.io/npm/v/%40meddleware%2Fnft-gate-gateway-workers)](https://www.npmjs.com/package/@meddleware/nft-gate-gateway-workers)
+[![License: 0BSD](https://img.shields.io/badge/license-0BSD-blue)](LICENSE)
+
+Cloudflare Workers implementation of the [nft-gate](../README.md) NFT-gated reverse proxy.
+Wire-identical to the [Rust gateway](../gateway-rust/): same routes, status codes, proof format,
+Sui RPC calls, and env-var names. Deploy it at the same URL the Rust gateway serves and nothing
+else changes.
+
+## Prerequisites
+
+| Tool | Minimum version | Install |
+| --- | --- | --- |
+| Node.js | 22.x | [nodejs.org](https://nodejs.org) |
+| npm | 10.x | bundled with Node |
+| Wrangler | 4.x | `npm install -g wrangler` |
+| Cloudflare account | — | [dash.cloudflare.com](https://dash.cloudflare.com) |
+
+## Getting started
+
+### 1. Get the source
+
+Clone or fork the repo, then work from the `gateway-workers/` directory:
+
+```bash
+git clone https://github.com/meddleware-org/nft-gate.git
+cd nft-gate/gateway-workers
+npm install
+```
+
+Alternatively, the package is published to npm for reference:
+
+```bash
+npm install @meddleware/nft-gate-gateway-workers
+```
+
+### 2. Configure `wrangler.toml`
+
+Edit the `[[routes]]` stanza to bind the Worker to your hostname:
+
+```toml
+[[routes]]
+pattern = "gate.example.com/*"
+zone_name = "example.com"
+```
+
+The default `[vars]` block already contains safe defaults for all optional settings. Review
+`SUI_RPC_URL` and change it to your preferred Sui fullnode:
+
+| Network | Public fullnode URL |
+| --- | --- |
+| Mainnet | `https://fullnode.mainnet.sui.io:443` |
+| Testnet | `https://fullnode.testnet.sui.io:443` |
+
+### 3. Create the Worker (first deploy)
+
+```bash
+npm run deploy
+```
+
+Wrangler creates the Worker and the Durable Object namespace in your account. The Worker will
+respond to requests immediately but will return errors until the required secrets are set.
+
+### 4. Set required secrets
+
+Run these once from the `gateway-workers/` directory after the Worker exists:
+
+```bash
+# The upstream origin the Worker proxies to.
+wrangler secret put UPSTREAM_URL
+# Value: https://your-relay.example.com
+
+# The on-chain NFT type to check ownership against.
+wrangler secret put NFT_TYPE
+# Value: 0x<PACKAGE_ID>::access_gate::SoulboundAccessNFT
+
+# CF Access service-token headers to authenticate to your origin (if Access-locked).
+# Omit if your upstream is publicly reachable or uses another auth mechanism.
+wrangler secret put UPSTREAM_AUTH_HEADERS
+# Value: CF-Access-Client-Id: <id>, CF-Access-Client-Secret: <secret>
+```
+
+Secrets are encrypted at rest and never appear in `wrangler.toml` or workflow logs. They survive
+`wrangler deploy` — setting them once is sufficient.
+
+### 5. Verify
+
+```bash
+curl https://gate.example.com/v1/challenge
+# → {"nonce":"...","expiresAt":...}
+```
+
+Any gated route without a valid proof token returns `401 Unauthorized`.
+
+## Upstream reachability
+
+The Rust gateway usually runs **inside** your network and reaches a private upstream directly.
+This Worker runs at Cloudflare's **edge**, so `UPSTREAM_URL` must be **publicly routable**.
+
+**Recommended pattern**: expose your upstream via a dedicated `cloudflared` public hostname
+locked to this Worker via Cloudflare Access, then point `UPSTREAM_URL` at it.
+
+### Locking the origin with a Cloudflare Access service token
+
+1. Cloudflare Zero Trust → Access → Service Tokens → **Create Service Token**.
+2. Create an Access **application** for your relay hostname (e.g. `relay.example.com`).
+3. Add a policy: allow requests where **Service Token** is the token you just created.
+4. Set the Worker secret — both token headers, comma-separated:
+
+   ```bash
+   wrangler secret put UPSTREAM_AUTH_HEADERS
+   # CF-Access-Client-Id: <id>, CF-Access-Client-Secret: <secret>
+   ```
+
+5. The Worker injects these headers on every upstream `fetch`. Direct browser or bot traffic to
+   the origin gets an Access login page or `403`, depending on the policy fallback.
+
+## State backend
+
+Single-use nonces and per-address rate limits need atomicity that a stateless isolate cannot
+provide. Two backends are available:
+
+| Backend | Binding | Consistency | Plan |
+| --- | --- | --- | --- |
+| `durable-object` (default) | `NONCE_STATE` (auto-created) | Strong — atomic single-use consume | Free tier |
+| `kv` | `NONCE_KV` (create manually) | Eventual — weak cross-region replay window in `SINGLE_USE=false` | Free tier |
+
+To use the KV backend, create a namespace and uncomment the binding in `wrangler.toml`:
+
+```bash
+wrangler kv namespace create NONCE_KV
+# Copy the returned ID into wrangler.toml:
+# [[kv_namespaces]]
+# binding = "NONCE_KV"
+# id = "<returned-id>"
+```
+
+Then set `NONCE_BACKEND = "kv"` in `[vars]`.
+
+## Full configuration reference
+
+| Var | Required | Default | Notes |
+| --- | --- | --- | --- |
+| `UPSTREAM_URL` | ✓ | — | Base URL of the protected upstream (set via `wrangler secret put`) |
+| `SUI_RPC_URL` | ✓ | `https://fullnode.testnet.sui.io:443` | Sui JSON-RPC endpoint; change to mainnet for production |
+| `NFT_TYPE` | ✓ | — | `<pkg>::access_gate::AccessNFT` or `SoulboundAccessNFT` (set via `wrangler secret put`) |
+| `GATE_ID` | | — | Restrict ownership checks to a specific gate registry object |
+| `SINGLE_USE` | | `false` | Require an on-chain `AccessConsumedEvent` bound to the nonce |
+| `PUBLIC_PATHS` | | `/v1/tip-config` | Comma-separated paths served without authentication |
+| `RATE_LIMIT_PER_MIN` | | `30` | Requests per verified address per 60s window (`0` disables) |
+| `MAX_BODY_BYTES` | | `262144` | Request body cap before proxying (256 KiB) |
+| `CHALLENGE_TTL_SECS` | | `300` | Nonce lifetime in seconds |
+| `OWNERSHIP_CACHE_TTL_MS` | | `0` | Ownership-check cache TTL (`0` = live check on every request) |
+| `NONCE_BACKEND` | | `durable-object` | `durable-object` or `kv` |
+| `NONCE_SHARD` | | `region` | DO shard granularity: `region` (near users) or `global` (one instance) |
+| `NONCE_MAX_ENTRIES` | | `1000000` | Hard nonce entry cap per DO shard (evict oldest when reached) |
+| `UPSTREAM_AUTH_HEADERS` | | — | Comma-separated `Name: value` pairs injected on every upstream request (secret) |
+| `SUI_RPC_AUTH_HEADER` | | — | `Name: value` header added to Sui RPC calls (secret, for authenticated nodes) |
+| `QUOTA_GUARD_ENABLED` | | `false` | Enable the scheduled free-tier quota guard |
+
+Vars listed in `wrangler.toml` are overwritten on every `wrangler deploy`. Values that must
+survive deployments (credentials, contract addresses) must be set with `wrangler secret put`.
+
+## Local development
+
+```bash
+npm run dev          # wrangler dev — local Worker runtime with DO + KV stubs
+npm test             # Vitest in the workerd runtime (tests DO, KV, crypto, routing)
+npm run type-check   # tsc --noEmit
+```
+
+## Optional: quota guard
+
+Setting `QUOTA_GUARD_ENABLED=true` and adding a cron trigger activates `src/quota.ts`. It reads
+your account's Workers usage via the Cloudflare GraphQL Analytics API and logs a warning when
+approaching the free-tier request or CPU-time limits. It can set a `quota:degrade` flag in KV to
+prefer the lighter KV backend during high-load periods.
+
+Uncomment in `wrangler.toml`:
+
+```toml
+[triggers]
+crons = ["*/15 * * * *"]
+```
+
+Set the required secrets:
+
+```bash
+wrangler secret put CF_ANALYTICS_TOKEN   # read-only Analytics API token
+wrangler secret put CF_ACCOUNT_ID        # your Cloudflare account ID
+```
+
+## Module layout
+
+| Module | Rust analog | Role |
+| --- | --- | --- |
+| `src/index.ts` | `main.rs` | Request router (challenge / public / gated paths) |
+| `src/config.ts` | `config.rs` | `env` → typed config (same var names as Rust) |
+| `src/wire.ts` | `proof.rs` | Proof helpers reused from `@meddleware/nft-gate-client` |
+| `src/verify.ts` | `verify.rs` | Signature verification + allow/deny decision |
+| `src/chain.ts` | `sui_rpc.rs` | Sui JSON-RPC ownership and consume-event queries |
+| `src/proxy.ts` | `proxy.rs` | Body-capped reverse proxy; strips `Host`/`Authorization` |
+| `src/state/` | `challenge.rs` + `ratelimit.rs` | Pluggable nonce store and rate limiter |
+| `src/quota.ts` | — | Optional free-tier quota guard (scheduled cron) |

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@meddleware/nft-gate-gateway",
+  "version": "0.0.1",
+  "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",
+  "main": "src/index.ts",
+  "files": ["src", "wrangler.toml", "tsconfig.json"],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --project unit",
+    "test:unit": "vitest run --project unit",
+    "test:integration": "vitest run --project cloudflare-integration",
+    "test:all": "vitest run",
+    "test:watch": "vitest --project unit",
+    "dev": "wrangler dev",
+    "deploy": "wrangler deploy",
+    "generate:vectors": "node scripts/gen-vectors.mjs > ../conformance/vectors.json"
+  },
+  "dependencies": {
+    "@meddleware/nft-gate-client": "^0.0.1",
+    "@noble/curves": "~2.4.0",
+    "@noble/hashes": "~2.4.0"
+  },
+  "devDependencies": {
+    "@cloudflare/vitest-pool-workers": "~0.22.0",
+    "@cloudflare/workers-types": "~5.20260827.1",
+    "typescript": "~7.0.2",
+    "vitest": "~4.1.11",
+    "wrangler": "~4.127.0"
+  }
+}

package/src/chain.ts

@@ -0,0 +1,260 @@
+/**
+ * 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.
+ */
+
+import type { ChainQuery } from './verify.js'
+import { base64ToBytes } from './crypto.js'
+
+type Json = unknown
+
+/**
+ * A cached result of a single ownership query.
+ * `owns` — whether the address held the NFT at query time.
+ * `expiry` — unix-ms timestamp after which this entry must be discarded.
+ */
+interface CacheEntry {
+  owns: boolean
+  expiry: number
+}
+
+export class SuiRpc implements ChainQuery {
+  private readonly cache = new Map<string, CacheEntry>()
+
+  /**
+   * @param rpcUrl - Sui JSON-RPC endpoint URL.
+   * @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).
+   */
+  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 }),
+    })
+    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
+  }
+
+  /**
+   * Extract the package address from a `<pkg>::module::Type` string.
+   *
+   * @param nftType - Fully-qualified Move type string.
+   * @returns The package address, or `undefined` if the string cannot be parsed.
+   */
+  static packageOf(nftType: string): string | undefined {
+    const head = nftType.split('::')[0]
+    return head && head.length > 0 ? head : undefined
+  }
+
+  /**
+   * Build a stable cache key from the three ownership-query parameters.
+   *
+   * @param address - Sui address.
+   * @param nftType - Fully-qualified NFT type string.
+   * @param gateId - Optional gate object ID constraint.
+   * @returns A pipe-delimited string suitable for use as a `Map` key.
+   */
+  static cacheKey(address: string, nftType: string, gateId?: string): string {
+    return `${address}|${nftType}|${gateId ?? '-'}`
+  }
+
+  /**
+   * Uncached, live `suix_getOwnedObjects` ownership query.
+   *
+   * @param address - Sui address to query.
+   * @param nftType - NFT struct type to filter by.
+   * @param gateId - If given, only count objects whose `gate_id` field matches.
+   * @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)
+  }
+
+  /**
+   * Check whether `address` owns at least one NFT of `nftType`. Uses the in-process ownership
+   * cache when `cacheTtlMs > 0`; otherwise every call is live on-chain.
+   *
+   * @param address - Sui address to check.
+   * @param nftType - Fully-qualified NFT type string.
+   * @param gateId - Optional gate object ID constraint.
+   * @returns `true` if the address owns a qualifying NFT.
+   */
+  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 hit = this.cache.get(key)
+      const now = Date.now()
+      if (hit && hit.expiry > now) return hit.owns
+      const owns = await this.ownsNftLive(address, nftType, gateId)
+      this.cache.set(key, { owns, expiry: now + this.cacheTtlMs })
+      return owns
+    }
+    return this.ownsNftLive(address, nftType, gateId)
+  }
+
+  /**
+   * 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.
+   *
+   * @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.
+   */
+  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))
+    )
+  }
+
+  /**
+   * 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).
+   *
+   * @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 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.
+   */
+  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
+  }
+}
+
+// ── pure helpers (unit-tested; mirror sui_rpc.rs) ────────────────────────────
+
+/**
+ * Traverse a nested JSON value by a sequence of object keys.
+ *
+ * @param v - The root JSON value.
+ * @param path - Sequence of object keys to follow.
+ * @returns The value at the path, or `undefined` if any step is missing or non-object.
+ */
+function pointer(v: Json, path: string[]): Json {
+  let cur: Json = v
+  for (const key of path) {
+    if (cur && typeof cur === 'object' && !Array.isArray(cur) && key in (cur as Record<string, Json>)) {
+      cur = (cur as Record<string, Json>)[key]
+    } else {
+      return undefined
+    }
+  }
+  return cur
+}
+
+/**
+ * Like {@link pointer} but returns `undefined` if the resolved value is not a string.
+ *
+ * @param v - The root JSON value.
+ * @param path - Sequence of object keys to follow.
+ * @returns The string value at the path, or `undefined`.
+ */
+function pointerStr(v: Json, path: string[]): string | undefined {
+  const r = pointer(v, path)
+  return typeof r === 'string' ? r : undefined
+}
+
+/** True if the event's type ends with `::access_gate::AccessConsumedEvent`. */
+export function isConsumedEvent(ev: Json): boolean {
+  const t = pointerStr(ev, ['type'])
+  return t !== undefined && t.endsWith('::access_gate::AccessConsumedEvent')
+}
+
+/**
+ * Match the on-chain `AccessConsumedEvent.nonce` (`vector<u8>`), rendered by RPC 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 {
+  const want = new TextEncoder().encode(nonce)
+  if (Array.isArray(eventNonce)) {
+    if (eventNonce.length !== want.length) return false
+    return eventNonce.every((b, i) => typeof b === 'number' && b === want[i])
+  }
+  if (typeof eventNonce === 'string') {
+    try {
+      const decoded = base64ToBytes(eventNonce)
+      return decoded.length === want.length && decoded.every((b, i) => b === want[i])
+    } catch {
+      return false
+    }
+  }
+  return false
+}
+
+/** sender == address, nonce matches, and (if given) gate_id matches. */
+export function eventMatches(ev: Json, nonce: string, 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
+}

package/src/config.ts

@@ -0,0 +1,144 @@
+/**
+ * Gateway configuration, loaded from Worker `env` bindings. Mirror of the Rust gateway's
+ * `config.rs` — the SAME env-var names and defaults, so a deployment's settings map 1:1
+ * between the two implementations (the interchangeability contract).
+ *
+ * Omitted vs. Rust (runtime-specific): `BIND_ADDR` (Workers has no listen socket);
+ * `REDIS_URL` / `NONCE_MAX_ENTRIES` (the in-memory cap lives in the DO) /
+ * `NONCE_PRUNE_INTERVAL_SECS` (the DO prunes on access) are superseded by the DO/KV backend.
+ * Added (Workers-specific): `NONCE_BACKEND`, `NONCE_SHARD`, `SUI_RPC_AUTH_HEADER`,
+ * `UPSTREAM_AUTH_HEADERS`, `QUOTA_GUARD_ENABLED`.
+ */
+
+export interface Env {
+  // ── config (parity with the Rust gateway) ─────────────────────────────────
+  UPSTREAM_URL: string
+  SUI_RPC_URL: string
+  NFT_TYPE: string
+  GATE_ID?: string
+  SINGLE_USE?: string
+  PUBLIC_PATHS?: string
+  RATE_LIMIT_PER_MIN?: string
+  MAX_BODY_BYTES?: string
+  CHALLENGE_TTL_SECS?: string
+  OWNERSHIP_CACHE_TTL_MS?: string
+  // ── Workers-specific ──────────────────────────────────────────────────────
+  /** `durable-object` (default) | `kv`. */
+  NONCE_BACKEND?: string
+  /** `region` (default) | `global` — DO shard granularity. */
+  NONCE_SHARD?: string
+  /** Hard cap on nonce rows per DO shard (evict soonest-to-expire beyond it). */
+  NONCE_MAX_ENTRIES?: string
+  /** Optional `Name: value` header line added to every Sui RPC call (secret). */
+  SUI_RPC_AUTH_HEADER?: string
+  /**
+   * Comma-separated `Name: value` header lines injected into every upstream (relay) request.
+   * Use this to pass Cloudflare Access service-token headers when the relay origin is
+   * Access-locked (your CF-Access-protected origin hostname).
+   *
+   * Format: `"CF-Access-Client-Id: <id>, CF-Access-Client-Secret: <secret>"`
+   *
+   * Set via `wrangler secret put UPSTREAM_AUTH_HEADERS` — never in wrangler.toml.
+   */
+  UPSTREAM_AUTH_HEADERS?: string
+  /** `true` enables the scheduled quota guard. */
+  QUOTA_GUARD_ENABLED?: string
+  // ── bindings ──────────────────────────────────────────────────────────────
+  NONCE_STATE?: DurableObjectNamespace
+  NONCE_KV?: KVNamespace
+  // ── quota-guard secrets (optional) ────────────────────────────────────────
+  CF_ANALYTICS_TOKEN?: string
+  CF_ACCOUNT_ID?: string
+}
+
+export type NonceBackendKind = 'durable-object' | 'kv'
+export type NonceShardMode = 'region' | 'global'
+
+export interface Config {
+  upstreamUrl: string
+  suiRpcUrl: string
+  suiRpcAuthHeader?: { name: string; value: string }
+  /** Headers injected into every upstream relay request (e.g. CF Access service token). */
+  upstreamAuthHeaders: Array<{ name: string; value: string }>
+  nftType: string
+  gateId?: string
+  challengeTtlSecs: number
+  singleUse: boolean
+  publicPaths: string[]
+  rateLimitPerMin: number
+  maxBodyBytes: number
+  ownershipCacheTtlMs: number
+  nonceBackend: NonceBackendKind
+  nonceShard: NonceShardMode
+  nonceMaxEntries: number
+  quotaGuardEnabled: boolean
+}
+
+function req(env: Env, key: keyof Env): string {
+  const v = env[key]
+  if (typeof v !== 'string' || v.length === 0) {
+    throw new Error(`${key} is required`)
+  }
+  return v
+}
+
+function numOr(v: string | undefined, dflt: number): number {
+  if (v === undefined) return dflt
+  const n = Number(v)
+  return Number.isFinite(n) ? n : dflt
+}
+
+function parseAuthHeader(v: string | undefined): { name: string; value: string } | undefined {
+  if (!v) return undefined
+  const idx = v.indexOf(':')
+  // "Name: value" → {name, value}; a bare value defaults to an Authorization header.
+  if (idx > 0) return { name: v.slice(0, idx).trim(), value: v.slice(idx + 1).trim() }
+  return { name: 'Authorization', value: v.trim() }
+}
+
+/**
+ * Parse `UPSTREAM_AUTH_HEADERS`: comma-separated `Name: value` pairs.
+ * Each entry follows the same `Name: value` format as `SUI_RPC_AUTH_HEADER`.
+ * Entries that cannot be parsed (no colon) are silently skipped.
+ */
+function parseUpstreamAuthHeaders(v: string | undefined): Array<{ name: string; value: string }> {
+  if (!v || v.trim().length === 0) return []
+  return v
+    .split(',')
+    .map((entry) => parseAuthHeader(entry.trim()))
+    .filter((h): h is { name: string; value: string } => h !== undefined)
+}
+
+/** Build the typed config from `env`. Throws if a required var is missing (fail fast). */
+export function loadConfig(env: Env): Config {
+  const backendRaw = (env.NONCE_BACKEND ?? 'durable-object').toLowerCase()
+  const nonceBackend: NonceBackendKind = backendRaw === 'kv' ? 'kv' : 'durable-object'
+  const shardRaw = (env.NONCE_SHARD ?? 'region').toLowerCase()
+  const nonceShard: NonceShardMode = shardRaw === 'global' ? 'global' : 'region'
+
+  return {
+    upstreamUrl: req(env, 'UPSTREAM_URL').replace(/\/+$/, ''),
+    suiRpcUrl: req(env, 'SUI_RPC_URL'),
+    suiRpcAuthHeader: parseAuthHeader(env.SUI_RPC_AUTH_HEADER),
+    upstreamAuthHeaders: parseUpstreamAuthHeaders(env.UPSTREAM_AUTH_HEADERS),
+    nftType: req(env, 'NFT_TYPE'),
+    gateId: env.GATE_ID && env.GATE_ID.length > 0 ? env.GATE_ID : undefined,
+    challengeTtlSecs: numOr(env.CHALLENGE_TTL_SECS, 300),
+    singleUse: (env.SINGLE_USE ?? 'false').toLowerCase() === 'true',
+    publicPaths: (env.PUBLIC_PATHS ?? '/v1/tip-config')
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0),
+    rateLimitPerMin: numOr(env.RATE_LIMIT_PER_MIN, 30),
+    maxBodyBytes: numOr(env.MAX_BODY_BYTES, 262144),
+    ownershipCacheTtlMs: numOr(env.OWNERSHIP_CACHE_TTL_MS, 0),
+    nonceBackend,
+    nonceShard,
+    nonceMaxEntries: numOr(env.NONCE_MAX_ENTRIES, 1000000),
+    quotaGuardEnabled: (env.QUOTA_GUARD_ENABLED ?? 'false').toLowerCase() === 'true',
+  }
+}
+
+export function isPublicPath(cfg: Config, path: string): boolean {
+  return cfg.publicPaths.some((p) => p === path)
+}