secure-store-redis

Encrypt and store data in Redis. Uses AES-256-GCM encryption with unique IVs per entry.

Installation

npm install secure-store-redis

Quick Start

import SecureStore, { SecretValidator } from "secure-store-redis";

const store = new SecureStore({
    uid: "myApp",
    secret: SecretValidator.generate(),
    redis: { url: "redis://localhost:6379" },
});

await store.connect();
await store.save("key", { foo: "bar" });
const data = await store.get("key");
await store.disconnect();

API

Constructor

new SecureStore(config: SecureStoreConfig)

| Option | Type | Required | Description | | ------------------ | ------------------------------- | -------- | ----------------------------------------------------------------- | | uid | string | Yes | Unique prefix for Redis keys (e.g., "myApp", "myApp:sessions") | | secret | string | Yes | 32-character encryption secret. Use SecretValidator.generate(). | | redis | RedisOptions | { url: string } | { client: Redis | Cluster } | Yes | Redis connection config or existing client | | allowWeakSecrets | boolean | No | Bypass secret strength validation (default: false) |

Using an Existing Redis Client

You can pass your own ioredis Redis or Cluster client instead of connection options. This enables connection sharing, pre-configured clients, and integration with existing Redis infrastructure.

import { Redis } from "ioredis";
import SecureStore, { SecretValidator } from "secure-store-redis";

const redis = new Redis({ host: "localhost", port: 6379 });

const store = new SecureStore({
    uid: "myApp",
    secret: SecretValidator.generate(),
    redis: { client: redis },
});

await store.connect();
await store.save("key", "value");
await store.disconnect();

// Your client is still connected - you manage its lifecycle
console.log(redis.status); // "ready"
await redis.quit();

Redis Cluster

import { Cluster } from "ioredis";
import SecureStore, { SecretValidator } from "secure-store-redis";

const cluster = new Cluster([
    { host: "node1", port: 6379 },
    { host: "node2", port: 6379 },
]);

const store = new SecureStore({
    uid: "myApp",
    secret: SecretValidator.generate(),
    redis: { client: cluster },
});

await store.connect();

Sharing Connections

Multiple SecureStore instances can share a single Redis connection:

const redis = new Redis();

const sessionsStore = new SecureStore({
    uid: "sessions",
    secret: sessionSecret,
    redis: { client: redis },
});

const cacheStore = new SecureStore({
    uid: "cache",
    secret: cacheSecret,
    redis: { client: redis },
});

await sessionsStore.connect();
await cacheStore.connect();

// Both stores use the same connection
// Disconnecting either store does NOT close the Redis client

Important notes:

• When using an external client, disconnect() will NOT close the Redis connection - you are responsible for calling redis.quit() when done
• The client can be in any connectable state (ready, connecting, or lazyConnect); connect() will wait for it to be ready
• If the client is already closed, connect() will throw a ConnectionError

Methods

connect(): Promise<void>

Connect to Redis. Must be called before other operations.

save<T>(key: string, data: T, postfix?: string): Promise<void>

Encrypt and store data.

get<T>(key: string, postfix?: string): Promise<T | null>

Retrieve and decrypt data. Returns null if not found or decryption fails.

delete(key: string, postfix?: string): Promise<number>

Delete data. Returns count of deleted keys.

disconnect(client?: Redis): Promise<void>

Close Redis connection. Optionally pass a specific Redis client to disconnect.

namespace<TSchema>(name: string): TypedNamespace<TSchema>

Create a typed namespace for organizing data. See Namespaces for details.

Properties

• client: RedisClient | undefined - The underlying ioredis client (Redis or Cluster)
• isConnected: boolean - Connection status

Namespaces

Namespaces allow you to organize data with type-safe operations. Each namespace acts as an isolated partition within the same store.

const store = new SecureStore({
    uid: "myApp",
    secret: SecretValidator.generate(),
    redis: { url: "redis://localhost:6379" },
});
await store.connect();

// Create a typed namespace
interface UserSchema {
    profile: { name: string; age: number };
    settings: { theme: string; notifications: boolean };
}

const users = store.namespace<UserSchema>("users");

// Type-safe operations
await users.save("profile", { name: "John", age: 30 });
await users.save("settings", { theme: "dark", notifications: true });

const profile = await users.get("profile"); // { name: string; age: number } | null
const settings = await users.get("settings");

await users.delete("profile");

Namespace Methods

Each namespace provides the same core operations as the store:

• get<K>(key: K): Promise<T[K] | null>
• save<K>(key: K, data: T[K]): Promise<void>
• delete<K>(key: K): Promise<number>

Namespace Isolation

Data in different namespaces is completely isolated:

const users = store.namespace("users");
const sessions = store.namespace("sessions");

await users.save("data", "user-data");
await sessions.save("data", "session-data");

await users.get("data");    // "user-data"
await sessions.get("data"); // "session-data"
await store.get("data");    // null (root store is separate)

SecretValidator

Utility class for generating and validating encryption secrets.

Methods

generate(length?: number): string

Generate a cryptographically secure secret. Defaults to 32 characters if no length specified.

validate(secret: string): { valid: boolean; reason?: string }

Validate secret strength against security requirements.

Validation Rules

Secrets must:

• Be exactly 32 characters
• Have sufficient entropy (Shannon entropy ≥ 4.0)
• Not contain weak patterns (repeated chars, sequential numbers, etc.)
• Contain at least 3 of: uppercase, lowercase, numbers, special characters

Error Handling

All errors extend SecureStoreError and include a code property for programmatic handling.

import {
    SecureStoreError,
    ConnectionError,
    EncryptionError,
    ValidationError,
} from "secure-store-redis";

try {
    await store.connect();
} catch (err) {
    if (err instanceof ConnectionError) {
        console.error(`Connection failed (${err.code}):`, err.message);
        // err.code === "CONNECTION_ERROR"
    }
}

| Error Class | Code | When Thrown | | ----------------- | -------------------- | ------------------------------------ | | ConnectionError | CONNECTION_ERROR | Redis connection failures | | EncryptionError | ENCRYPTION_ERROR | Encryption/decryption failures | | ValidationError | VALIDATION_ERROR | Invalid configuration, keys, or data |

Security Best Practices

• Store secrets in environment variables, not code
• Use SecretValidator.generate() for cryptographically secure secrets
• Enable Redis authentication and TLS in production
• Use unique uid values per application/environment to prevent data collisions
• Rotate secrets periodically (requires re-encryption of existing data)

Migration from v3.x

Breaking Changes

| Change | Migration | | -------------------- | ------------------------------------------ | | uid required | Add explicit uid to constructor | | secret required | Use SecretValidator.generate() or provide your own | | connect() required | Call await store.connect() before use | | AES-256-GCM | Re-encrypt existing data (format changed) | | Secret validation | Use strong secrets or set allowWeakSecrets: true |

Example

// v3.x
const store = new SecureStore({ redis: { url: "..." } });
await store.init();

// v4.0
const store = new SecureStore({
    uid: "myApp",
    secret: SecretValidator.generate(),
    redis: { url: "..." },
});
await store.connect();

TypeScript

Full TypeScript support with exported types:

import SecureStore, {
    SecureStoreConfig,
    TypedNamespace,
    RedisClient,
    SecretValidator,
    SecureStoreError,
    ConnectionError,
    EncryptionError,
    ValidationError,
} from "secure-store-redis";

License

MIT