@sockethub/data-layer 1.0.0-alpha.12 → 1.0.0-alpha.14

package/README.md

@@ -56,7 +56,7 @@ encryption/decryption and session-based isolation.
 **Dependencies:**
 
 - Redis server (6.0+)
-- `@sockethub/crypto` for encryption
+- `@sockethub/util` (`@sockethub/util/crypto`) for encryption
 - `@sockethub/schemas` for type definitions
 
 ## API Documentation

package/dist/credentials-store.d.ts

@@ -0,0 +1,140 @@
+import type { CredentialsObject } from "@sockethub/schemas";
+import { type Redis } from "ioredis";
+import SecureStore from "secure-store-redis";
+import type { RedisConfig } from "./types.js";
+/**
+ * Creates or returns a shared Redis connection for CredentialsStore instances.
+ * This prevents connection exhaustion by reusing a single connection across
+ * all credential storage operations.
+ *
+ * @param config - Redis configuration
+ * @returns Shared Redis connection instance
+ */
+export declare function createCredentialsRedisConnection(config: RedisConfig): Redis;
+/**
+ * Creates or returns a dedicated shared Redis connection for HTTP idempotency.
+ */
+export declare function createIdempotencyRedisConnection(config: RedisConfig): Redis;
+/**
+ * Creates or returns a dedicated shared Redis connection for rate limiting.
+ * A dedicated connection keeps rate-limit traffic off the credentials and
+ * idempotency connections and lets a Redis-backed limiter share request budgets
+ * across instances.
+ */
+export declare function createRateLimitRedisConnection(config: RedisConfig): Redis;
+/**
+ * Resets the shared credentials Redis connection. Used primarily for testing.
+ */
+export declare function resetSharedCredentialsRedisConnection(): Promise<void>;
+export declare function resetSharedIdempotencyRedisConnection(): Promise<void>;
+export declare function resetSharedRateLimitRedisConnection(): Promise<void>;
+export interface CredentialsStoreInterface {
+    get(actor: string, credentialsHash?: string, options?: CredentialsValidationOptions): Promise<CredentialsObject | undefined>;
+    save(actor: string, creds: CredentialsObject): Promise<number>;
+    /**
+     * Delete this session's entire credential namespace from Redis. Used by
+     * single-use sessions (e.g. HTTP actions requests) whose credentials are
+     * never read again once the request completes. Optional: long-lived socket
+     * sessions do not implement it.
+     */
+    teardown?(): Promise<void>;
+}
+export interface CredentialsStoreOptions {
+    /**
+     * Sliding time-to-live in milliseconds applied to this session's
+     * credential key in Redis, refreshed on every save and read. A backstop
+     * against keys orphaned by crashes or ungraceful shutdowns where explicit
+     * teardown never runs — size it generously (idle sessions do not refresh
+     * it). Omit or 0 to disable expiry.
+     */
+    ttlMs?: number;
+}
+export interface CredentialsValidationOptions {
+    /**
+     * Enables stricter checks used only when trying to attach a second socket
+     * session to an already-running actor-scoped platform instance.
+     */
+    validateSessionShare?: boolean;
+}
+export declare class CredentialsMismatchError extends Error {
+    constructor(message: string);
+}
+export declare class CredentialsNotShareableError extends Error {
+    constructor(message: string);
+}
+export declare function verifySecureStore(config: RedisConfig): Promise<void>;
+/**
+ * Secure, encrypted storage for user credentials with session-based isolation.
+ *
+ * Provides automatic encryption/decryption of credential objects stored in Redis,
+ * ensuring that sensitive authentication data is never stored in plaintext.
+ * Each session gets its own isolated credential store.
+ *
+ * @example
+ * ```typescript
+ * const store = new CredentialsStore('session123', secret, redisConfig);
+ *
+ * // Store credentials
+ * await store.save('user@example.com', {
+ *   username: 'user',
+ *   password: 'secret',
+ *   server: 'irc.freenode.net'
+ * });
+ *
+ * // Retrieve credentials
+ * const creds = await store.get('user@example.com', credentialsHash);
+ * ```
+ */
+export declare class CredentialsStore implements CredentialsStoreInterface {
+    readonly uid: string;
+    store: SecureStore;
+    objectHash: (o: unknown) => string;
+    private readonly log;
+    /**
+     * Creates a new CredentialsStore instance.
+     *
+     * @param parentId - Unique identifier for the parent instance (e.g. server ID)
+     * @param sessionId - Client session identifier for credential isolation
+     * @param secret - 32-character encryption secret for credential security
+     * @param redisConfig - Redis connection configuration
+     * @throws Error if secret is not exactly 32 characters
+     */
+    constructor(parentId: string, sessionId: string, secret: string, redisConfig: RedisConfig, options?: CredentialsStoreOptions);
+    initCrypto(): void;
+    initSecureStore(secret: string, redisConfig: RedisConfig, ttlMs?: number): void;
+    /**
+     * Gets the credentials for a given actor ID.
+     * @param actor
+     * @param credentialsHash - Optional hash to validate credentials.
+     *   If undefined, validation is skipped.
+     */
+    get(actor: string, credentialsHash?: string, options?: CredentialsValidationOptions): Promise<CredentialsObject>;
+    /**
+     * Saves the credentials for a given actor ID
+     * @param actor
+     * @param creds
+     */
+    save(actor: string, creds: CredentialsObject): Promise<number>;
+    /**
+     * Delete this session's entire credential hash from Redis, promptly
+     * reclaiming the key instead of waiting for its TTL (if any) to lapse.
+     * Called when the session ends (socket disconnect, HTTP actions request
+     * cleanup). Best-effort and safe to call when nothing was stored — a
+     * missing key is a no-op.
+     */
+    teardown(): Promise<void>;
+}
+/**
+ * Delete every credential-store key belonging to `parentId`. Called from
+ * server shutdown so an instance reclaims its own keys instead of stranding
+ * them under a parentId that no future boot will ever reference (each boot
+ * randomizes its parentId). Scoped strictly to the given parentId: Redis may
+ * be shared by multiple running instances, so keys under other parentIds are
+ * never touched. Returns the number of keys removed.
+ */
+export declare function purgeCredentialsStoreKeys(client: Redis, parentId: string): Promise<number>;
+/**
+ * Convenience wrapper over {@link purgeCredentialsStoreKeys} using the shared
+ * credentials Redis connection.
+ */
+export declare function purgeCredentialsStores(parentId: string, config: RedisConfig): Promise<number>;

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+import { CredentialsMismatchError, CredentialsNotShareableError, CredentialsStore, type CredentialsStoreInterface, type CredentialsStoreOptions, type CredentialsValidationOptions, createCredentialsRedisConnection, createIdempotencyRedisConnection, createRateLimitRedisConnection, purgeCredentialsStoreKeys, purgeCredentialsStores, resetSharedCredentialsRedisConnection, resetSharedIdempotencyRedisConnection, resetSharedRateLimitRedisConnection } from "./credentials-store.js";
+import { getRedisConnectionCount, resetSharedRedisConnection } from "./job-base.js";
+import { JobQueue } from "./job-queue.js";
+import { JobWorker, type JobWorkerOptions } from "./job-worker.js";
+export * from "./types.js";
+import type { RedisConfig } from "./types.js";
+declare function redisCheck(config: RedisConfig): Promise<void>;
+export { CredentialsMismatchError, CredentialsNotShareableError, CredentialsStore, type CredentialsStoreInterface, type CredentialsStoreOptions, type CredentialsValidationOptions, createCredentialsRedisConnection, createIdempotencyRedisConnection, createRateLimitRedisConnection, getRedisConnectionCount, JobQueue, purgeCredentialsStoreKeys, purgeCredentialsStores, JobWorker, type JobWorkerOptions, redisCheck, resetSharedCredentialsRedisConnection, resetSharedIdempotencyRedisConnection, resetSharedRateLimitRedisConnection, resetSharedRedisConnection, };