guardian-risk-redis 0.1.1 → 0.2.1

package/README.md

@@ -4,35 +4,56 @@
 
 ```bash
 npm install guardian-risk guardian-risk-redis
+# optional peer for real Redis:
+npm install ioredis
 ```
 
-> **Stub package** — API may change before `1.0.0`.
+Session and rate-limit signals backed by Redis (or in-memory for development).
 
-Redis integration for [guardian-risk](https://www.npmjs.com/package/guardian-risk). Stores events and exposes session-based counters as signals.
-
-## Planned signals
+## Signals
 
 | Signal | Source |
 |--------|--------|
-| `requestsPerMinute` | Sliding window counter |
-| `sessionAge` | First-seen timestamp |
-| `failedLoginCount` | Incremented on auth failures |
-| `uniqueIpsPerSession` | HyperLogLog or set cardinality |
+| `sessionId` | Sanitized session header or `anonymous` |
+| `requestsInWindow` | Atomic counter in sliding window |
+| `requestsPerMinute` | Same as `requestsInWindow` (compat alias) |
+| `loginAttempts` | Incremented via `recordLoginAttempt()` |
+| `sessionAgeSeconds` | Age since session creation or window start |
+| `signalSource` | Always `'session'` |
 
-## Usage (stub)
+## Production usage
 
 ```typescript
 import { Guardian } from 'guardian-risk';
-import { redisPlugin, loadSessionSignals } from 'guardian-risk-redis';
-
-const guardian = new Guardian().use(
-  redisPlugin({ url: process.env.REDIS_URL, keyPrefix: 'app:risk:' }),
+import { redisPlugin, recordLoginAttempt } from 'guardian-risk-redis';
+
+const template = new Guardian().use(
+  redisPlugin({
+    url: process.env.REDIS_URL,
+    keyPrefix: 'myapp:risk:',
+    sessionIdHeader: 'x-session-id',
+    allowInMemoryFallback: false, // default — fail loud if Redis unavailable
+    rateLimitByIpWhenNoSession: true,
+  }),
 );
 
-await loadSessionSignals('session-123', guardian);
-const report = guardian.analyze();
+// On failed login:
+await recordLoginAttempt(sessionId, store);
 ```
 
-## Status
+## Security notes
+
+- **`x-session-id` is client-supplied** — bind it to your server session in production.
+- Session IDs are **sanitized** (length + charset); invalid IDs are ignored.
+- When no session is present, rate limiting falls back to **validated `clientIp`** (from express plugin).
+- **`allowInMemoryFallback` defaults to `false`** — `createRedisStore()` throws if `ioredis` is missing.
+- Do not use in-memory store in multi-instance deployments.
+
+## API
+
+- `redisPlugin(options)` — `beforeAnalyze` hook
+- `loadSessionSignals(sessionId, guardian, options)` — manual preload
+- `recordLoginAttempt(sessionId, store?)` — increment login counter
+- `createRedisStore({ url, keyPrefix, allowInMemoryFallback })` — standalone store
 
-Not yet published. Implementation in progress.
+See [SECURITY.md](../../SECURITY.md).

package/dist/index.cjs

@@ -1,17 +1,251 @@
 'use strict';
 
+var guardianRisk = require('guardian-risk');
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/sessionStore.ts
+var sessionStore_exports = {};
+__export(sessionStore_exports, {
+  InMemorySessionStore: () => exports.InMemorySessionStore,
+  defaultSessionStore: () => exports.defaultSessionStore
+});
+exports.InMemorySessionStore = void 0; exports.defaultSessionStore = void 0;
+var init_sessionStore = __esm({
+  "src/sessionStore.ts"() {
+    exports.InMemorySessionStore = class {
+      requests = /* @__PURE__ */ new Map();
+      logins = /* @__PURE__ */ new Map();
+      maxEntries;
+      constructor(maxEntries = 1e4) {
+        this.maxEntries = maxEntries;
+      }
+      async incrementRequests(sessionId, windowMs) {
+        this.evictIfNeeded(this.requests);
+        const now = Date.now();
+        let entry = this.requests.get(sessionId);
+        if (!entry || now - entry.windowStart > windowMs) {
+          entry = { count: 0, windowStart: now };
+        }
+        entry.count += 1;
+        this.requests.set(sessionId, entry);
+        return {
+          requestsInWindow: entry.count,
+          windowStartedAt: entry.windowStart,
+          loginAttempts: this.logins.get(sessionId) ?? 0
+        };
+      }
+      async incrementLoginAttempts(sessionId) {
+        const next = (this.logins.get(sessionId) ?? 0) + 1;
+        this.logins.set(sessionId, next);
+        return next;
+      }
+      async getLoginAttempts(sessionId) {
+        return this.logins.get(sessionId) ?? 0;
+      }
+      evictIfNeeded(map) {
+        if (map.size < this.maxEntries) {
+          return;
+        }
+        const firstKey = map.keys().next().value;
+        if (firstKey) {
+          map.delete(firstKey);
+        }
+      }
+    };
+    exports.defaultSessionStore = new exports.InMemorySessionStore();
+  }
+});
+
 // src/index.ts
+init_sessionStore();
+
+// src/redisStore.ts
+var RedisSessionStore = class {
+  constructor(client, keyPrefix) {
+    this.client = client;
+    this.keyPrefix = keyPrefix;
+  }
+  client;
+  keyPrefix;
+  async incrementRequests(sessionId, windowMs) {
+    const windowSlot = Math.floor(Date.now() / windowMs);
+    const requestKey = `${this.keyPrefix}req:${sessionId}:${windowSlot}`;
+    const loginKey = `${this.keyPrefix}login:${sessionId}`;
+    const ttlSeconds = Math.max(1, Math.ceil(windowMs / 1e3) + 1);
+    const count = await this.client.incr(requestKey);
+    await this.client.expire(requestKey, ttlSeconds);
+    return {
+      requestsInWindow: count,
+      windowStartedAt: windowSlot * windowMs,
+      loginAttempts: await this.readLoginAttempts(loginKey)
+    };
+  }
+  async incrementLoginAttempts(sessionId) {
+    const loginKey = `${this.keyPrefix}login:${sessionId}`;
+    return this.client.incr(loginKey);
+  }
+  async getLoginAttempts(sessionId) {
+    return this.readLoginAttempts(`${this.keyPrefix}login:${sessionId}`);
+  }
+  async readLoginAttempts(loginKey) {
+    const raw = await this.client.get(loginKey);
+    return raw ? Number(raw) : 0;
+  }
+};
+async function createRedisStore(urlOrOptions, legacyKeyPrefix = "guardian:") {
+  const options = typeof urlOrOptions === "string" ? { url: urlOrOptions, keyPrefix: legacyKeyPrefix } : urlOrOptions;
+  const { url, keyPrefix = "guardian:", allowInMemoryFallback = false } = options;
+  const { InMemorySessionStore: InMemorySessionStore2 } = await Promise.resolve().then(() => (init_sessionStore(), sessionStore_exports));
+  try {
+    const module = await import('ioredis');
+    const client = new module.default(url);
+    return new RedisSessionStore(client, keyPrefix);
+  } catch (error) {
+    if (allowInMemoryFallback) {
+      return new InMemorySessionStore2();
+    }
+    const message = error instanceof Error ? error.message : "unknown error";
+    throw new Error(
+      `Failed to connect Redis store. Install ioredis or set allowInMemoryFallback: true. ${message}`
+    );
+  }
+}
+
+// src/index.ts
+var DEFAULT_WINDOW_MS = 6e4;
+var storePromises = /* @__PURE__ */ new Map();
 function redisPlugin(options = {}) {
-  const { url = "redis://localhost:6379", keyPrefix = "guardian:" } = options;
+  const {
+    windowMs = DEFAULT_WINDOW_MS,
+    sessionIdHeader = "x-session-id",
+    keyPrefix = "guardian:",
+    url,
+    store: providedStore,
+    rateLimitByIpWhenNoSession = true,
+    allowInMemoryFallback = false
+  } = options;
   return {
     name: "guardian-risk-redis",
-    install(_guardian) {
+    install(guardian) {
+      guardian.beforeAnalyze(async ({ data, guardian: g }) => {
+        const sessionId = resolveSessionId(data, sessionIdHeader);
+        const store = await resolvePluginStore({
+          providedStore,
+          url,
+          keyPrefix,
+          allowInMemoryFallback
+        });
+        if (sessionId) {
+          await applySessionSignals(sessionId, g, store, windowMs);
+          return;
+        }
+        if (rateLimitByIpWhenNoSession) {
+          const ip = readValidatedClientIp(g, data);
+          if (ip) {
+            await applySessionSignals(`ip:${ip}`, g, store, windowMs);
+          }
+        }
+      });
     }
   };
 }
-async function loadSessionSignals(_sessionId, guardian) {
-  return guardian.signal("signalSource", "redis").signal("redisPlugin", "stub");
+async function loadSessionSignals(sessionId, guardian, options = {}) {
+  const sanitized = guardianRisk.sanitizeSessionId(sessionId);
+  if (!sanitized) {
+    throw new TypeError("Invalid session ID");
+  }
+  const store = await resolvePluginStore({
+    providedStore: options.store,
+    url: options.url,
+    keyPrefix: options.keyPrefix ?? "guardian:",
+    allowInMemoryFallback: options.allowInMemoryFallback ?? false
+  });
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  await applySessionSignals(sanitized, guardian, store, windowMs, options.sessionCreatedAt);
+  return guardian;
+}
+async function recordLoginAttempt(sessionId, store = exports.defaultSessionStore) {
+  const sanitized = guardianRisk.sanitizeSessionId(sessionId);
+  if (!sanitized) {
+    throw new TypeError("Invalid session ID");
+  }
+  return store.incrementLoginAttempts(sanitized);
+}
+async function applySessionSignals(counterKey, guardian, store, windowMs, sessionCreatedAt) {
+  const snapshot = await store.incrementRequests(counterKey, windowMs);
+  const sessionAgeSeconds = sessionCreatedAt ? Math.max(0, Math.floor((Date.now() - sessionCreatedAt) / 1e3)) : Math.max(0, Math.floor((Date.now() - snapshot.windowStartedAt) / 1e3));
+  guardian.signal("sessionId", counterKey.startsWith("ip:") ? "anonymous" : counterKey).signal("requestsInWindow", snapshot.requestsInWindow).signal("requestsPerMinute", snapshot.requestsInWindow).signal("loginAttempts", snapshot.loginAttempts).signal("sessionAgeSeconds", sessionAgeSeconds).signal("signalSource", "session");
+}
+function resolveSessionId(data, headerName) {
+  if (data !== null && typeof data === "object" && "sessionId" in data) {
+    const value = data.sessionId;
+    if (typeof value === "string") {
+      return guardianRisk.sanitizeSessionId(value) ?? void 0;
+    }
+  }
+  if (data !== null && typeof data === "object" && "headers" in data) {
+    const headers = data.headers;
+    const raw = headers[headerName] ?? headers[headerName.toLowerCase()];
+    const candidate = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof candidate === "string") {
+      return guardianRisk.sanitizeSessionId(candidate) ?? void 0;
+    }
+  }
+  return void 0;
+}
+function readValidatedClientIp(guardian, data) {
+  const fromSignal = guardian.getSignal("clientIp");
+  if (typeof fromSignal === "string") {
+    const parsed = guardianRisk.parseIpAddress(fromSignal);
+    if (parsed) {
+      return parsed;
+    }
+  }
+  if (data !== null && typeof data === "object" && "ip" in data) {
+    const ip = data.ip;
+    if (typeof ip === "string") {
+      return guardianRisk.parseIpAddress(ip);
+    }
+  }
+  return null;
+}
+async function resolvePluginStore(options) {
+  if (options.providedStore) {
+    return options.providedStore;
+  }
+  if (options.url) {
+    const cacheKey = `${options.url}::${options.keyPrefix}`;
+    if (!storePromises.has(cacheKey)) {
+      storePromises.set(
+        cacheKey,
+        createRedisStore({
+          url: options.url,
+          keyPrefix: options.keyPrefix,
+          allowInMemoryFallback: options.allowInMemoryFallback
+        })
+      );
+    }
+    return storePromises.get(cacheKey);
+  }
+  return exports.defaultSessionStore;
 }
 
+exports.RedisSessionStore = RedisSessionStore;
+exports.createRedisStore = createRedisStore;
 exports.loadSessionSignals = loadSessionSignals;
+exports.recordLoginAttempt = recordLoginAttempt;
 exports.redisPlugin = redisPlugin;

package/dist/index.d.cts

@@ -1,23 +1,85 @@
 import * as guardian_risk from 'guardian-risk';
 import { Plugin } from 'guardian-risk';
 
-/** Options for the Redis plugin (stub). */
-interface RedisPluginOptions {
-    /** Redis connection URL. */
-    readonly url?: string;
-    /** Key prefix for Guardian counters. */
+/** In-memory session counter store (single-node). Swap for Redis in production. */
+interface SessionSnapshot {
+    readonly requestsInWindow: number;
+    readonly windowStartedAt: number;
+    readonly loginAttempts: number;
+}
+interface SessionStore {
+    incrementRequests(sessionId: string, windowMs: number): Promise<SessionSnapshot>;
+    incrementLoginAttempts(sessionId: string): Promise<number>;
+    getLoginAttempts(sessionId: string): Promise<number>;
+}
+declare class InMemorySessionStore implements SessionStore {
+    private readonly requests;
+    private readonly logins;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    incrementRequests(sessionId: string, windowMs: number): Promise<SessionSnapshot>;
+    incrementLoginAttempts(sessionId: string): Promise<number>;
+    getLoginAttempts(sessionId: string): Promise<number>;
+    private evictIfNeeded;
+}
+/** Shared default store for single-process apps and tests. */
+declare const defaultSessionStore: InMemorySessionStore;
+
+/** Minimal Redis client surface used by Guardian. */
+interface RedisClientLike {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    quit(): Promise<unknown>;
+}
+interface CreateRedisStoreOptions {
+    readonly url: string;
     readonly keyPrefix?: string;
+    /**
+     * When true, falls back to in-memory if ioredis is unavailable.
+     * Default: false (throws on failure — recommended for production).
+     */
+    readonly allowInMemoryFallback?: boolean;
 }
 /**
- * Redis plugin for guardian-risk.
- *
- * @stub Future versions will read/write session counters in Redis and
- * expose signals like `requestsPerMinute` and `sessionAge`.
+ * Redis-backed session store with atomic windowed counters.
  */
-declare function redisPlugin(options?: RedisPluginOptions): Plugin;
+declare class RedisSessionStore implements SessionStore {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(client: RedisClientLike, keyPrefix: string);
+    incrementRequests(sessionId: string, windowMs: number): Promise<SessionSnapshot>;
+    incrementLoginAttempts(sessionId: string): Promise<number>;
+    getLoginAttempts(sessionId: string): Promise<number>;
+    private readLoginAttempts;
+}
 /**
- * @stub Future helper to load session counters from Redis into signals.
+ * Create a Redis session store.
+ * @throws When ioredis is unavailable and `allowInMemoryFallback` is false.
  */
-declare function loadSessionSignals(_sessionId: string, guardian: guardian_risk.Guardian): Promise<guardian_risk.Guardian>;
+declare function createRedisStore(urlOrOptions: string | CreateRedisStoreOptions, legacyKeyPrefix?: string): Promise<SessionStore>;
+
+/** Options for the Redis / session plugin. */
+interface RedisPluginOptions {
+    readonly url?: string;
+    readonly keyPrefix?: string;
+    readonly windowMs?: number;
+    readonly sessionIdHeader?: string;
+    readonly store?: SessionStore;
+    /** Rate-limit by validated client IP when no session ID is present (default: true). */
+    readonly rateLimitByIpWhenNoSession?: boolean;
+    /** Only used with `url` — default false (fail loud in production). */
+    readonly allowInMemoryFallback?: boolean;
+}
+declare function redisPlugin(options?: RedisPluginOptions): Plugin;
+interface SessionContext {
+    readonly sessionId: string;
+    readonly sessionCreatedAt?: number;
+}
+declare function loadSessionSignals(sessionId: string, guardian: guardian_risk.Guardian, options?: RedisPluginOptions & {
+    sessionCreatedAt?: number;
+}): Promise<guardian_risk.Guardian>;
+declare function recordLoginAttempt(sessionId: string, store?: SessionStore): Promise<number>;
 
-export { type RedisPluginOptions, loadSessionSignals, redisPlugin };
+export { type CreateRedisStoreOptions, InMemorySessionStore, type RedisClientLike, type RedisPluginOptions, RedisSessionStore, type SessionContext, type SessionSnapshot, type SessionStore, createRedisStore, defaultSessionStore, loadSessionSignals, recordLoginAttempt, redisPlugin };

package/dist/index.d.ts

@@ -1,23 +1,85 @@
 import * as guardian_risk from 'guardian-risk';
 import { Plugin } from 'guardian-risk';
 
-/** Options for the Redis plugin (stub). */
-interface RedisPluginOptions {
-    /** Redis connection URL. */
-    readonly url?: string;
-    /** Key prefix for Guardian counters. */
+/** In-memory session counter store (single-node). Swap for Redis in production. */
+interface SessionSnapshot {
+    readonly requestsInWindow: number;
+    readonly windowStartedAt: number;
+    readonly loginAttempts: number;
+}
+interface SessionStore {
+    incrementRequests(sessionId: string, windowMs: number): Promise<SessionSnapshot>;
+    incrementLoginAttempts(sessionId: string): Promise<number>;
+    getLoginAttempts(sessionId: string): Promise<number>;
+}
+declare class InMemorySessionStore implements SessionStore {
+    private readonly requests;
+    private readonly logins;
+    private readonly maxEntries;
+    constructor(maxEntries?: number);
+    incrementRequests(sessionId: string, windowMs: number): Promise<SessionSnapshot>;
+    incrementLoginAttempts(sessionId: string): Promise<number>;
+    getLoginAttempts(sessionId: string): Promise<number>;
+    private evictIfNeeded;
+}
+/** Shared default store for single-process apps and tests. */
+declare const defaultSessionStore: InMemorySessionStore;
+
+/** Minimal Redis client surface used by Guardian. */
+interface RedisClientLike {
+    incr(key: string): Promise<number>;
+    expire(key: string, seconds: number): Promise<number>;
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<unknown>;
+    quit(): Promise<unknown>;
+}
+interface CreateRedisStoreOptions {
+    readonly url: string;
     readonly keyPrefix?: string;
+    /**
+     * When true, falls back to in-memory if ioredis is unavailable.
+     * Default: false (throws on failure — recommended for production).
+     */
+    readonly allowInMemoryFallback?: boolean;
 }
 /**
- * Redis plugin for guardian-risk.
- *
- * @stub Future versions will read/write session counters in Redis and
- * expose signals like `requestsPerMinute` and `sessionAge`.
+ * Redis-backed session store with atomic windowed counters.
  */
-declare function redisPlugin(options?: RedisPluginOptions): Plugin;
+declare class RedisSessionStore implements SessionStore {
+    private readonly client;
+    private readonly keyPrefix;
+    constructor(client: RedisClientLike, keyPrefix: string);
+    incrementRequests(sessionId: string, windowMs: number): Promise<SessionSnapshot>;
+    incrementLoginAttempts(sessionId: string): Promise<number>;
+    getLoginAttempts(sessionId: string): Promise<number>;
+    private readLoginAttempts;
+}
 /**
- * @stub Future helper to load session counters from Redis into signals.
+ * Create a Redis session store.
+ * @throws When ioredis is unavailable and `allowInMemoryFallback` is false.
  */
-declare function loadSessionSignals(_sessionId: string, guardian: guardian_risk.Guardian): Promise<guardian_risk.Guardian>;
+declare function createRedisStore(urlOrOptions: string | CreateRedisStoreOptions, legacyKeyPrefix?: string): Promise<SessionStore>;
+
+/** Options for the Redis / session plugin. */
+interface RedisPluginOptions {
+    readonly url?: string;
+    readonly keyPrefix?: string;
+    readonly windowMs?: number;
+    readonly sessionIdHeader?: string;
+    readonly store?: SessionStore;
+    /** Rate-limit by validated client IP when no session ID is present (default: true). */
+    readonly rateLimitByIpWhenNoSession?: boolean;
+    /** Only used with `url` — default false (fail loud in production). */
+    readonly allowInMemoryFallback?: boolean;
+}
+declare function redisPlugin(options?: RedisPluginOptions): Plugin;
+interface SessionContext {
+    readonly sessionId: string;
+    readonly sessionCreatedAt?: number;
+}
+declare function loadSessionSignals(sessionId: string, guardian: guardian_risk.Guardian, options?: RedisPluginOptions & {
+    sessionCreatedAt?: number;
+}): Promise<guardian_risk.Guardian>;
+declare function recordLoginAttempt(sessionId: string, store?: SessionStore): Promise<number>;
 
-export { type RedisPluginOptions, loadSessionSignals, redisPlugin };
+export { type CreateRedisStoreOptions, InMemorySessionStore, type RedisClientLike, type RedisPluginOptions, RedisSessionStore, type SessionContext, type SessionSnapshot, type SessionStore, createRedisStore, defaultSessionStore, loadSessionSignals, recordLoginAttempt, redisPlugin };

package/dist/index.js

@@ -1,14 +1,176 @@
+import { defaultSessionStore } from './chunk-E6WVCFQU.js';
+export { InMemorySessionStore, defaultSessionStore } from './chunk-E6WVCFQU.js';
+import { sanitizeSessionId, parseIpAddress } from 'guardian-risk';
+
+// src/redisStore.ts
+var RedisSessionStore = class {
+  constructor(client, keyPrefix) {
+    this.client = client;
+    this.keyPrefix = keyPrefix;
+  }
+  client;
+  keyPrefix;
+  async incrementRequests(sessionId, windowMs) {
+    const windowSlot = Math.floor(Date.now() / windowMs);
+    const requestKey = `${this.keyPrefix}req:${sessionId}:${windowSlot}`;
+    const loginKey = `${this.keyPrefix}login:${sessionId}`;
+    const ttlSeconds = Math.max(1, Math.ceil(windowMs / 1e3) + 1);
+    const count = await this.client.incr(requestKey);
+    await this.client.expire(requestKey, ttlSeconds);
+    return {
+      requestsInWindow: count,
+      windowStartedAt: windowSlot * windowMs,
+      loginAttempts: await this.readLoginAttempts(loginKey)
+    };
+  }
+  async incrementLoginAttempts(sessionId) {
+    const loginKey = `${this.keyPrefix}login:${sessionId}`;
+    return this.client.incr(loginKey);
+  }
+  async getLoginAttempts(sessionId) {
+    return this.readLoginAttempts(`${this.keyPrefix}login:${sessionId}`);
+  }
+  async readLoginAttempts(loginKey) {
+    const raw = await this.client.get(loginKey);
+    return raw ? Number(raw) : 0;
+  }
+};
+async function createRedisStore(urlOrOptions, legacyKeyPrefix = "guardian:") {
+  const options = typeof urlOrOptions === "string" ? { url: urlOrOptions, keyPrefix: legacyKeyPrefix } : urlOrOptions;
+  const { url, keyPrefix = "guardian:", allowInMemoryFallback = false } = options;
+  const { InMemorySessionStore: InMemorySessionStore2 } = await import('./sessionStore-KDK2DHV7.js');
+  try {
+    const module = await import('ioredis');
+    const client = new module.default(url);
+    return new RedisSessionStore(client, keyPrefix);
+  } catch (error) {
+    if (allowInMemoryFallback) {
+      return new InMemorySessionStore2();
+    }
+    const message = error instanceof Error ? error.message : "unknown error";
+    throw new Error(
+      `Failed to connect Redis store. Install ioredis or set allowInMemoryFallback: true. ${message}`
+    );
+  }
+}
+
 // src/index.ts
+var DEFAULT_WINDOW_MS = 6e4;
+var storePromises = /* @__PURE__ */ new Map();
 function redisPlugin(options = {}) {
-  const { url = "redis://localhost:6379", keyPrefix = "guardian:" } = options;
+  const {
+    windowMs = DEFAULT_WINDOW_MS,
+    sessionIdHeader = "x-session-id",
+    keyPrefix = "guardian:",
+    url,
+    store: providedStore,
+    rateLimitByIpWhenNoSession = true,
+    allowInMemoryFallback = false
+  } = options;
   return {
     name: "guardian-risk-redis",
-    install(_guardian) {
+    install(guardian) {
+      guardian.beforeAnalyze(async ({ data, guardian: g }) => {
+        const sessionId = resolveSessionId(data, sessionIdHeader);
+        const store = await resolvePluginStore({
+          providedStore,
+          url,
+          keyPrefix,
+          allowInMemoryFallback
+        });
+        if (sessionId) {
+          await applySessionSignals(sessionId, g, store, windowMs);
+          return;
+        }
+        if (rateLimitByIpWhenNoSession) {
+          const ip = readValidatedClientIp(g, data);
+          if (ip) {
+            await applySessionSignals(`ip:${ip}`, g, store, windowMs);
+          }
+        }
+      });
     }
   };
 }
-async function loadSessionSignals(_sessionId, guardian) {
-  return guardian.signal("signalSource", "redis").signal("redisPlugin", "stub");
+async function loadSessionSignals(sessionId, guardian, options = {}) {
+  const sanitized = sanitizeSessionId(sessionId);
+  if (!sanitized) {
+    throw new TypeError("Invalid session ID");
+  }
+  const store = await resolvePluginStore({
+    providedStore: options.store,
+    url: options.url,
+    keyPrefix: options.keyPrefix ?? "guardian:",
+    allowInMemoryFallback: options.allowInMemoryFallback ?? false
+  });
+  const windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+  await applySessionSignals(sanitized, guardian, store, windowMs, options.sessionCreatedAt);
+  return guardian;
+}
+async function recordLoginAttempt(sessionId, store = defaultSessionStore) {
+  const sanitized = sanitizeSessionId(sessionId);
+  if (!sanitized) {
+    throw new TypeError("Invalid session ID");
+  }
+  return store.incrementLoginAttempts(sanitized);
+}
+async function applySessionSignals(counterKey, guardian, store, windowMs, sessionCreatedAt) {
+  const snapshot = await store.incrementRequests(counterKey, windowMs);
+  const sessionAgeSeconds = sessionCreatedAt ? Math.max(0, Math.floor((Date.now() - sessionCreatedAt) / 1e3)) : Math.max(0, Math.floor((Date.now() - snapshot.windowStartedAt) / 1e3));
+  guardian.signal("sessionId", counterKey.startsWith("ip:") ? "anonymous" : counterKey).signal("requestsInWindow", snapshot.requestsInWindow).signal("requestsPerMinute", snapshot.requestsInWindow).signal("loginAttempts", snapshot.loginAttempts).signal("sessionAgeSeconds", sessionAgeSeconds).signal("signalSource", "session");
+}
+function resolveSessionId(data, headerName) {
+  if (data !== null && typeof data === "object" && "sessionId" in data) {
+    const value = data.sessionId;
+    if (typeof value === "string") {
+      return sanitizeSessionId(value) ?? void 0;
+    }
+  }
+  if (data !== null && typeof data === "object" && "headers" in data) {
+    const headers = data.headers;
+    const raw = headers[headerName] ?? headers[headerName.toLowerCase()];
+    const candidate = Array.isArray(raw) ? raw[0] : raw;
+    if (typeof candidate === "string") {
+      return sanitizeSessionId(candidate) ?? void 0;
+    }
+  }
+  return void 0;
+}
+function readValidatedClientIp(guardian, data) {
+  const fromSignal = guardian.getSignal("clientIp");
+  if (typeof fromSignal === "string") {
+    const parsed = parseIpAddress(fromSignal);
+    if (parsed) {
+      return parsed;
+    }
+  }
+  if (data !== null && typeof data === "object" && "ip" in data) {
+    const ip = data.ip;
+    if (typeof ip === "string") {
+      return parseIpAddress(ip);
+    }
+  }
+  return null;
+}
+async function resolvePluginStore(options) {
+  if (options.providedStore) {
+    return options.providedStore;
+  }
+  if (options.url) {
+    const cacheKey = `${options.url}::${options.keyPrefix}`;
+    if (!storePromises.has(cacheKey)) {
+      storePromises.set(
+        cacheKey,
+        createRedisStore({
+          url: options.url,
+          keyPrefix: options.keyPrefix,
+          allowInMemoryFallback: options.allowInMemoryFallback
+        })
+      );
+    }
+    return storePromises.get(cacheKey);
+  }
+  return defaultSessionStore;
 }
 
-export { loadSessionSignals, redisPlugin };
+export { RedisSessionStore, createRedisStore, loadSessionSignals, recordLoginAttempt, redisPlugin };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "guardian-risk-redis",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Redis plugin for guardian-risk — session counters and event history",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -54,7 +54,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "guardian-risk": "^0.2.0",
+    "guardian-risk": "^0.3.1",
     "ioredis": ">=5"
   },
   "peerDependenciesMeta": {
@@ -65,10 +65,12 @@
   "devDependencies": {
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",
-    "guardian-risk": "0.2.1"
+    "vitest": "^4.1.9",
+    "guardian-risk": "0.3.1"
   },
   "scripts": {
     "build": "tsup",
+    "test": "vitest run",
     "typecheck": "tsc --noEmit"
   }
 }