@buildersgarden/siwa 0.0.13 → 0.0.14

package/dist/index.d.ts

@@ -7,4 +7,5 @@ export * from './registry.js';
 export * from './addresses.js';
 export * from './receipt.js';
 export * from './erc8128.js';
+export * from './nonce-store.js';
 export * from './tba.js';

package/dist/index.js

@@ -7,4 +7,5 @@ export * from './registry.js';
 export * from './addresses.js';
 export * from './receipt.js';
 export * from './erc8128.js';
+export * from './nonce-store.js';
 export * from './tba.js';

package/dist/nonce-store.d.ts

@@ -0,0 +1,101 @@
+/**
+ * nonce-store.ts
+ *
+ * Pluggable nonce store for SIWA sign-in replay protection.
+ *
+ * The default HMAC-based stateless nonces are convenient but can be replayed
+ * within their TTL window. A SIWANonceStore tracks issued nonces server-side
+ * so each nonce can only be consumed once.
+ *
+ * Built-in factories:
+ *   - createMemorySIWANonceStore()      — single-process (Map + TTL)
+ *   - createRedisSIWANonceStore(redis)  — ioredis / node-redis
+ *   - createKVSIWANonceStore(kv)        — Cloudflare Workers KV
+ *
+ * For databases (SQL, Prisma, Drizzle), implement the SIWANonceStore interface
+ * directly — it's just two methods.
+ *
+ * No new runtime dependencies — each factory accepts a minimal interface so
+ * users bring their own client.
+ */
+export interface SIWANonceStore {
+    /** Store an issued nonce. Returns true on success, false if already exists. */
+    issue(nonce: string, ttlMs: number): Promise<boolean>;
+    /** Atomically check-and-delete a nonce. Returns true if it existed (valid), false otherwise. */
+    consume(nonce: string): Promise<boolean>;
+}
+/**
+ * In-memory nonce store with TTL-based expiry.
+ *
+ * Suitable for single-process servers. For multi-instance deployments,
+ * implement SIWANonceStore with a shared store (Redis, database, etc.).
+ */
+export declare function createMemorySIWANonceStore(): SIWANonceStore;
+/**
+ * Minimal subset of the ioredis / node-redis API used by the nonce store.
+ * Both ioredis and node-redis v4 (with legacyMode or the `.set()` overload)
+ * satisfy this interface out of the box.
+ */
+export interface RedisLikeClient {
+    set(...args: unknown[]): Promise<unknown>;
+    del(...args: unknown[]): Promise<number>;
+}
+/**
+ * Redis-backed nonce store.
+ *
+ * Uses `SET key 1 PX ttl NX` for atomic issue (fails if key exists) and
+ * `DEL key` for atomic consume (returns 1 only on first delete).
+ *
+ * @param redis   An ioredis instance or any client matching `RedisLikeClient`.
+ * @param prefix  Optional key prefix (default `"siwa:nonce:"`).
+ *
+ * @example
+ * ```ts
+ * // ioredis
+ * import Redis from "ioredis";
+ * const redis = new Redis();
+ * const nonceStore = createRedisSIWANonceStore(redis);
+ *
+ * // node-redis v4 — wrap with a tiny adapter:
+ * import { createClient } from "redis";
+ * const client = createClient(); await client.connect();
+ * const nonceStore = createRedisSIWANonceStore({
+ *   set: (...a: unknown[]) => client.set(a[0] as string, a[1] as string,
+ *     { PX: a[3] as number, NX: true }).then(r => r ?? null),
+ *   del: (k: unknown) => client.del(k as string),
+ * });
+ * ```
+ */
+export declare function createRedisSIWANonceStore(redis: RedisLikeClient, prefix?: string): SIWANonceStore;
+/**
+ * Minimal subset of the Cloudflare KV namespace binding API.
+ */
+export interface KVNamespaceLike {
+    put(key: string, value: string, options?: {
+        expirationTtl?: number;
+    }): Promise<void>;
+    get(key: string): Promise<string | null>;
+    delete(key: string): Promise<void>;
+}
+/**
+ * Cloudflare Workers KV-backed nonce store.
+ *
+ * `issue` uses `put` with an `expirationTtl` so nonces auto-expire.
+ * `consume` does a `get` + `delete` pair — not fully atomic, but acceptable
+ * for random 128-bit nonces where collisions are astronomically unlikely.
+ *
+ * @param kv      A KV namespace binding (e.g. `env.SIWA_NONCES`).
+ * @param prefix  Optional key prefix (default `"siwa:nonce:"`).
+ *
+ * @example
+ * ```ts
+ * // In a Cloudflare Worker
+ * export default {
+ *   async fetch(request, env) {
+ *     const nonceStore = createKVSIWANonceStore(env.SIWA_NONCES);
+ *     // use with createSIWANonce / verifySIWA
+ *   },
+ * };
+ * ```
+ */
+export declare function createKVSIWANonceStore(kv: KVNamespaceLike, prefix?: string): SIWANonceStore;

package/dist/nonce-store.js

@@ -0,0 +1,135 @@
+/**
+ * nonce-store.ts
+ *
+ * Pluggable nonce store for SIWA sign-in replay protection.
+ *
+ * The default HMAC-based stateless nonces are convenient but can be replayed
+ * within their TTL window. A SIWANonceStore tracks issued nonces server-side
+ * so each nonce can only be consumed once.
+ *
+ * Built-in factories:
+ *   - createMemorySIWANonceStore()      — single-process (Map + TTL)
+ *   - createRedisSIWANonceStore(redis)  — ioredis / node-redis
+ *   - createKVSIWANonceStore(kv)        — Cloudflare Workers KV
+ *
+ * For databases (SQL, Prisma, Drizzle), implement the SIWANonceStore interface
+ * directly — it's just two methods.
+ *
+ * No new runtime dependencies — each factory accepts a minimal interface so
+ * users bring their own client.
+ */
+/**
+ * In-memory nonce store with TTL-based expiry.
+ *
+ * Suitable for single-process servers. For multi-instance deployments,
+ * implement SIWANonceStore with a shared store (Redis, database, etc.).
+ */
+export function createMemorySIWANonceStore() {
+    const nonces = new Map(); // nonce → expiry timestamp (ms)
+    function cleanup() {
+        const now = Date.now();
+        for (const [k, expiry] of nonces) {
+            if (expiry < now)
+                nonces.delete(k);
+        }
+    }
+    return {
+        async issue(nonce, ttlMs) {
+            cleanup();
+            if (nonces.has(nonce))
+                return false;
+            nonces.set(nonce, Date.now() + ttlMs);
+            return true;
+        },
+        async consume(nonce) {
+            cleanup();
+            if (!nonces.has(nonce))
+                return false;
+            const expiry = nonces.get(nonce);
+            nonces.delete(nonce);
+            return expiry >= Date.now();
+        },
+    };
+}
+/**
+ * Redis-backed nonce store.
+ *
+ * Uses `SET key 1 PX ttl NX` for atomic issue (fails if key exists) and
+ * `DEL key` for atomic consume (returns 1 only on first delete).
+ *
+ * @param redis   An ioredis instance or any client matching `RedisLikeClient`.
+ * @param prefix  Optional key prefix (default `"siwa:nonce:"`).
+ *
+ * @example
+ * ```ts
+ * // ioredis
+ * import Redis from "ioredis";
+ * const redis = new Redis();
+ * const nonceStore = createRedisSIWANonceStore(redis);
+ *
+ * // node-redis v4 — wrap with a tiny adapter:
+ * import { createClient } from "redis";
+ * const client = createClient(); await client.connect();
+ * const nonceStore = createRedisSIWANonceStore({
+ *   set: (...a: unknown[]) => client.set(a[0] as string, a[1] as string,
+ *     { PX: a[3] as number, NX: true }).then(r => r ?? null),
+ *   del: (k: unknown) => client.del(k as string),
+ * });
+ * ```
+ */
+export function createRedisSIWANonceStore(redis, prefix = 'siwa:nonce:') {
+    return {
+        async issue(nonce, ttlMs) {
+            // SET key "1" PX ttlMs NX → "OK" if the key was set, null otherwise
+            const result = await redis.set(prefix + nonce, '1', 'PX', ttlMs, 'NX');
+            return result === 'OK';
+        },
+        async consume(nonce) {
+            // DEL returns the number of keys removed (1 = existed, 0 = didn't)
+            const deleted = await redis.del(prefix + nonce);
+            return deleted === 1;
+        },
+    };
+}
+/**
+ * Cloudflare Workers KV-backed nonce store.
+ *
+ * `issue` uses `put` with an `expirationTtl` so nonces auto-expire.
+ * `consume` does a `get` + `delete` pair — not fully atomic, but acceptable
+ * for random 128-bit nonces where collisions are astronomically unlikely.
+ *
+ * @param kv      A KV namespace binding (e.g. `env.SIWA_NONCES`).
+ * @param prefix  Optional key prefix (default `"siwa:nonce:"`).
+ *
+ * @example
+ * ```ts
+ * // In a Cloudflare Worker
+ * export default {
+ *   async fetch(request, env) {
+ *     const nonceStore = createKVSIWANonceStore(env.SIWA_NONCES);
+ *     // use with createSIWANonce / verifySIWA
+ *   },
+ * };
+ * ```
+ */
+export function createKVSIWANonceStore(kv, prefix = 'siwa:nonce:') {
+    return {
+        async issue(nonce, ttlMs) {
+            const key = prefix + nonce;
+            // Check-before-write: KV put is unconditional, so read first
+            const existing = await kv.get(key);
+            if (existing !== null)
+                return false;
+            await kv.put(key, '1', { expirationTtl: Math.ceil(ttlMs / 1000) });
+            return true;
+        },
+        async consume(nonce) {
+            const key = prefix + nonce;
+            const value = await kv.get(key);
+            if (value === null)
+                return false;
+            await kv.delete(key);
+            return true;
+        },
+    };
+}

package/dist/siwa.d.ts

@@ -10,6 +10,7 @@
 import { type PublicClient } from 'viem';
 import { AgentProfile, ServiceType, TrustModel } from './registry.js';
 import type { Signer, SignerType } from './signer.js';
+import type { SIWANonceStore } from './nonce-store.js';
 export declare enum SIWAErrorCode {
     INVALID_SIGNATURE = "INVALID_SIGNATURE",
     DOMAIN_MISMATCH = "DOMAIN_MISMATCH",
@@ -117,6 +118,7 @@ export interface SIWANonceParams {
 export interface SIWANonceOptions {
     expirationTTL?: number;
     secret?: string;
+    nonceStore?: SIWANonceStore;
 }
 export type SIWANonceResult = {
     status: 'nonce_issued';
@@ -203,6 +205,8 @@ export declare function signSIWAMessage(fields: SIWASignFields, signer: Signer):
 export type NonceValidator = ((nonce: string) => boolean | Promise<boolean>) | {
     nonceToken: string;
     secret: string;
+} | {
+    nonceStore: SIWANonceStore;
 };
 /**
  * Verify a SIWA message + signature.

package/dist/siwa.js

@@ -272,6 +272,10 @@ export async function createSIWANonce(params, client, options) {
     const now = new Date();
     const expiresAt = new Date(now.getTime() + ttl);
     const nonce = generateNonce();
+    // Track nonce in the store (for replay protection)
+    if (options?.nonceStore) {
+        await options.nonceStore.issue(nonce, ttl);
+    }
     const result = {
         status: 'nonce_issued',
         nonce,
@@ -385,6 +389,10 @@ export async function verifySIWA(message, signature, expectedDomain, nonceValid,
         if (typeof nonceValid === 'function') {
             nonceOk = await nonceValid(fields.nonce);
         }
+        else if ('nonceStore' in nonceValid) {
+            // Store-based validation: atomic consume (check + delete)
+            nonceOk = await nonceValid.nonceStore.consume(fields.nonce);
+        }
         else {
             // Stateless validation via HMAC token
             const payload = verifyNonceToken(nonceValid.nonceToken, nonceValid.secret);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildersgarden/siwa",
-  "version": "0.0.13",
+  "version": "0.0.14",
   "type": "module",
   "exports": {
     ".": {
@@ -43,6 +43,10 @@
       "types": "./dist/erc8128.d.ts",
       "default": "./dist/erc8128.js"
     },
+    "./nonce-store": {
+      "types": "./dist/nonce-store.d.ts",
+      "default": "./dist/nonce-store.js"
+    },
     "./next": {
       "types": "./dist/next.d.ts",
       "default": "./dist/next.js"