@hypercerts-org/sdk-core 0.2.0-beta.0

package/dist/storage.d.ts

@@ -0,0 +1,474 @@
+import { NodeSavedSession, NodeSavedState } from '@atproto/oauth-client-node';
+
+/**
+ * Storage interface for persisting OAuth sessions.
+ *
+ * Implement this interface to provide persistent storage for user sessions.
+ * Sessions contain sensitive data including access tokens, refresh tokens,
+ * and DPoP key pairs.
+ *
+ * The SDK provides {@link InMemorySessionStore} for development/testing,
+ * but **production applications should implement persistent storage**
+ * (e.g., Redis, PostgreSQL, MongoDB).
+ *
+ * @remarks
+ * - Sessions are keyed by the user's DID (Decentralized Identifier)
+ * - The `NodeSavedSession` type comes from `@atproto/oauth-client-node`
+ * - Sessions may be large (~2-4KB) due to embedded cryptographic keys
+ * - Consider encrypting sessions at rest for additional security
+ *
+ * @example Redis implementation
+ * ```typescript
+ * import { Redis } from "ioredis";
+ * import type { SessionStore } from "@hypercerts-org/sdk";
+ * import type { NodeSavedSession } from "@atproto/oauth-client-node";
+ *
+ * class RedisSessionStore implements SessionStore {
+ *   constructor(private redis: Redis, private prefix = "session:") {}
+ *
+ *   async get(did: string): Promise<NodeSavedSession | undefined> {
+ *     const data = await this.redis.get(this.prefix + did);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async set(did: string, session: NodeSavedSession): Promise<void> {
+ *     // Set with 30-day expiry (sessions can be refreshed)
+ *     await this.redis.setex(
+ *       this.prefix + did,
+ *       30 * 24 * 60 * 60,
+ *       JSON.stringify(session)
+ *     );
+ *   }
+ *
+ *   async del(did: string): Promise<void> {
+ *     await this.redis.del(this.prefix + did);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link InMemorySessionStore} for the default in-memory implementation
+ */
+interface SessionStore {
+    /**
+     * Retrieves a session by DID.
+     *
+     * @param did - The user's Decentralized Identifier (e.g., "did:plc:abc123...")
+     * @returns The stored session, or `undefined` if not found
+     */
+    get(did: string): Promise<NodeSavedSession | undefined>;
+    /**
+     * Stores or updates a session.
+     *
+     * This is called after successful authentication and whenever tokens are refreshed.
+     *
+     * @param did - The user's DID to use as the storage key
+     * @param session - The session data to store (contains tokens, DPoP keys, etc.)
+     */
+    set(did: string, session: NodeSavedSession): Promise<void>;
+    /**
+     * Deletes a session.
+     *
+     * Called when a user logs out or when a session is revoked.
+     *
+     * @param did - The user's DID
+     */
+    del(did: string): Promise<void>;
+}
+/**
+ * Storage interface for OAuth state during the authorization flow.
+ *
+ * Implement this interface to provide temporary storage for OAuth state
+ * parameters. State is used for CSRF protection and PKCE (Proof Key for
+ * Code Exchange) during the authorization flow.
+ *
+ * @remarks
+ * - State is short-lived (typically 10-15 minutes)
+ * - Keys are random state strings generated by the OAuth client
+ * - The `NodeSavedState` type comes from `@atproto/oauth-client-node`
+ * - State should be automatically cleaned up after expiry
+ *
+ * @example Redis implementation with automatic expiry
+ * ```typescript
+ * import { Redis } from "ioredis";
+ * import type { StateStore } from "@hypercerts-org/sdk";
+ * import type { NodeSavedState } from "@atproto/oauth-client-node";
+ *
+ * class RedisStateStore implements StateStore {
+ *   constructor(
+ *     private redis: Redis,
+ *     private prefix = "oauth-state:",
+ *     private ttlSeconds = 900  // 15 minutes
+ *   ) {}
+ *
+ *   async get(key: string): Promise<NodeSavedState | undefined> {
+ *     const data = await this.redis.get(this.prefix + key);
+ *     return data ? JSON.parse(data) : undefined;
+ *   }
+ *
+ *   async set(key: string, state: NodeSavedState): Promise<void> {
+ *     await this.redis.setex(
+ *       this.prefix + key,
+ *       this.ttlSeconds,
+ *       JSON.stringify(state)
+ *     );
+ *   }
+ *
+ *   async del(key: string): Promise<void> {
+ *     await this.redis.del(this.prefix + key);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link InMemoryStateStore} for the default in-memory implementation
+ */
+interface StateStore {
+    /**
+     * Retrieves OAuth state by key.
+     *
+     * @param key - The state key (random string from authorization URL)
+     * @returns The stored state, or `undefined` if not found or expired
+     */
+    get(key: string): Promise<NodeSavedState | undefined>;
+    /**
+     * Stores OAuth state temporarily.
+     *
+     * Called when starting the authorization flow. The state should be
+     * stored with a short TTL (10-15 minutes recommended).
+     *
+     * @param key - The state key to use for storage
+     * @param state - The OAuth state data (includes PKCE verifier, etc.)
+     */
+    set(key: string, state: NodeSavedState): Promise<void>;
+    /**
+     * Deletes OAuth state.
+     *
+     * Called after the state has been used (successful or failed callback).
+     *
+     * @param key - The state key to delete
+     */
+    del(key: string): Promise<void>;
+}
+/**
+ * Generic cache interface for profiles, metadata, and other data.
+ *
+ * Implement this interface to provide caching for frequently accessed data.
+ * Caching can significantly reduce API calls and improve performance.
+ *
+ * @remarks
+ * The SDK does not provide a default cache implementation - you must
+ * implement this interface if you want caching. Consider using:
+ * - In-memory cache (e.g., `lru-cache`) for single-instance applications
+ * - Redis for distributed applications
+ * - Database-backed cache for persistence
+ *
+ * @example LRU cache implementation
+ * ```typescript
+ * import { LRUCache } from "lru-cache";
+ * import type { CacheInterface } from "@hypercerts-org/sdk";
+ *
+ * class LRUCacheAdapter implements CacheInterface {
+ *   private cache = new LRUCache<string, unknown>({
+ *     max: 1000,
+ *     ttl: 5 * 60 * 1000,  // 5 minutes default
+ *   });
+ *
+ *   async get<T>(key: string): Promise<T | undefined> {
+ *     return this.cache.get(key) as T | undefined;
+ *   }
+ *
+ *   async set<T>(key: string, value: T, ttlSeconds?: number): Promise<void> {
+ *     this.cache.set(key, value, {
+ *       ttl: ttlSeconds ? ttlSeconds * 1000 : undefined,
+ *     });
+ *   }
+ *
+ *   async del(key: string): Promise<void> {
+ *     this.cache.delete(key);
+ *   }
+ *
+ *   async clear(): Promise<void> {
+ *     this.cache.clear();
+ *   }
+ * }
+ * ```
+ */
+interface CacheInterface {
+    /**
+     * Gets a cached value by key.
+     *
+     * @typeParam T - The expected type of the cached value
+     * @param key - The cache key
+     * @returns The cached value, or `undefined` if not found or expired
+     */
+    get<T>(key: string): Promise<T | undefined>;
+    /**
+     * Sets a cached value with optional TTL (time-to-live).
+     *
+     * @typeParam T - The type of the value being cached
+     * @param key - The cache key
+     * @param value - The value to cache
+     * @param ttlSeconds - Optional time-to-live in seconds. If not provided,
+     *                     the cache implementation should use its default TTL.
+     */
+    set<T>(key: string, value: T, ttlSeconds?: number): Promise<void>;
+    /**
+     * Deletes a cached value.
+     *
+     * @param key - The cache key to delete
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Clears all cached values.
+     *
+     * Use with caution in production as this affects all cached data.
+     */
+    clear(): Promise<void>;
+}
+
+/**
+ * In-memory implementation of the SessionStore interface.
+ *
+ * This store keeps OAuth sessions in memory using a Map. It's intended
+ * for development, testing, and simple use cases where session persistence
+ * across restarts is not required.
+ *
+ * @remarks
+ * **Warning**: This implementation is **not suitable for production** because:
+ * - Sessions are lost when the process restarts
+ * - Sessions cannot be shared across multiple server instances
+ * - No automatic cleanup of expired sessions
+ *
+ * For production, implement {@link SessionStore} with a persistent backend:
+ * - **Redis**: Good for distributed systems, supports TTL
+ * - **PostgreSQL/MySQL**: Good for existing database infrastructure
+ * - **MongoDB**: Good for document-based storage
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { InMemorySessionStore } from "@hypercerts-org/sdk/storage";
+ *
+ * const sessionStore = new InMemorySessionStore();
+ *
+ * const sdk = new ATProtoSDK({
+ *   oauth: { ... },
+ *   storage: {
+ *     sessionStore,  // Will warn in logs for production
+ *   },
+ * });
+ * ```
+ *
+ * @example Testing usage
+ * ```typescript
+ * const sessionStore = new InMemorySessionStore();
+ *
+ * // After tests, clean up
+ * sessionStore.clear();
+ * ```
+ *
+ * @see {@link SessionStore} for the interface definition
+ * @see {@link InMemoryStateStore} for the corresponding state store
+ */
+declare class InMemorySessionStore implements SessionStore {
+    /**
+     * Internal storage for sessions, keyed by DID.
+     * @internal
+     */
+    private sessions;
+    /**
+     * Retrieves a session by DID.
+     *
+     * @param did - The user's Decentralized Identifier
+     * @returns Promise resolving to the session, or `undefined` if not found
+     *
+     * @example
+     * ```typescript
+     * const session = await sessionStore.get("did:plc:abc123");
+     * if (session) {
+     *   console.log("Session found");
+     * }
+     * ```
+     */
+    get(did: string): Promise<NodeSavedSession | undefined>;
+    /**
+     * Stores or updates a session.
+     *
+     * @param did - The user's DID to use as the key
+     * @param session - The session data to store
+     *
+     * @remarks
+     * If a session already exists for the DID, it is overwritten.
+     *
+     * @example
+     * ```typescript
+     * await sessionStore.set("did:plc:abc123", sessionData);
+     * ```
+     */
+    set(did: string, session: NodeSavedSession): Promise<void>;
+    /**
+     * Deletes a session by DID.
+     *
+     * @param did - The DID of the session to delete
+     *
+     * @remarks
+     * If no session exists for the DID, this is a no-op.
+     *
+     * @example
+     * ```typescript
+     * await sessionStore.del("did:plc:abc123");
+     * ```
+     */
+    del(did: string): Promise<void>;
+    /**
+     * Clears all stored sessions.
+     *
+     * This is primarily useful for testing to ensure a clean state
+     * between test runs.
+     *
+     * @remarks
+     * This method is synchronous (not async) for convenience in test cleanup.
+     *
+     * @example
+     * ```typescript
+     * // In test teardown
+     * afterEach(() => {
+     *   sessionStore.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+}
+
+/**
+ * In-memory implementation of the StateStore interface.
+ *
+ * This store keeps OAuth state parameters in memory using a Map. State is
+ * used during the OAuth authorization flow for CSRF protection and PKCE.
+ *
+ * @remarks
+ * **Warning**: This implementation is **not suitable for production** because:
+ * - State is lost when the process restarts (breaking in-progress OAuth flows)
+ * - State cannot be shared across multiple server instances
+ * - No automatic cleanup of expired state (memory leak potential)
+ *
+ * For production, implement {@link StateStore} with a persistent backend
+ * that supports TTL (time-to-live):
+ * - **Redis**: Ideal choice with built-in TTL support
+ * - **Database with cleanup job**: PostgreSQL/MySQL with periodic cleanup
+ *
+ * **State Lifecycle**:
+ * 1. Created when user starts OAuth flow (`authorize()`)
+ * 2. Retrieved and validated during callback
+ * 3. Deleted after successful or failed callback
+ * 4. Should expire after ~15 minutes if callback never happens
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { InMemoryStateStore } from "@hypercerts-org/sdk/storage";
+ *
+ * const stateStore = new InMemoryStateStore();
+ *
+ * const sdk = new ATProtoSDK({
+ *   oauth: { ... },
+ *   storage: {
+ *     stateStore,  // Will warn in logs for production
+ *   },
+ * });
+ * ```
+ *
+ * @example Testing usage
+ * ```typescript
+ * const stateStore = new InMemoryStateStore();
+ *
+ * // After tests, clean up
+ * stateStore.clear();
+ * ```
+ *
+ * @see {@link StateStore} for the interface definition
+ * @see {@link InMemorySessionStore} for the corresponding session store
+ */
+declare class InMemoryStateStore implements StateStore {
+    /**
+     * Internal storage for OAuth state, keyed by state string.
+     * @internal
+     */
+    private states;
+    /**
+     * Retrieves OAuth state by key.
+     *
+     * @param key - The state key (random string from authorization URL)
+     * @returns Promise resolving to the state, or `undefined` if not found
+     *
+     * @remarks
+     * The key is a cryptographically random string generated during
+     * the authorization request. It's included in the callback URL
+     * and used to retrieve the associated PKCE verifier and other data.
+     *
+     * @example
+     * ```typescript
+     * // During OAuth callback
+     * const state = await stateStore.get(params.get("state")!);
+     * if (!state) {
+     *   throw new Error("Invalid or expired state");
+     * }
+     * ```
+     */
+    get(key: string): Promise<NodeSavedState | undefined>;
+    /**
+     * Stores OAuth state temporarily.
+     *
+     * @param key - The state key to use for storage
+     * @param state - The OAuth state data (includes PKCE verifier, etc.)
+     *
+     * @remarks
+     * In production implementations, state should be stored with a TTL
+     * of approximately 10-15 minutes to prevent stale state accumulation.
+     *
+     * @example
+     * ```typescript
+     * // Called internally by OAuthClient during authorize()
+     * await stateStore.set(stateKey, {
+     *   // PKCE code verifier, redirect URI, etc.
+     * });
+     * ```
+     */
+    set(key: string, state: NodeSavedState): Promise<void>;
+    /**
+     * Deletes OAuth state by key.
+     *
+     * @param key - The state key to delete
+     *
+     * @remarks
+     * Called after the OAuth callback is processed (whether successful or not)
+     * to clean up the temporary state.
+     *
+     * @example
+     * ```typescript
+     * // After processing callback
+     * await stateStore.del(stateKey);
+     * ```
+     */
+    del(key: string): Promise<void>;
+    /**
+     * Clears all stored state.
+     *
+     * This is primarily useful for testing to ensure a clean state
+     * between test runs.
+     *
+     * @remarks
+     * This method is synchronous (not async) for convenience in test cleanup.
+     * In production, be careful using this as it will invalidate all
+     * in-progress OAuth flows.
+     *
+     * @example
+     * ```typescript
+     * // In test teardown
+     * afterEach(() => {
+     *   stateStore.clear();
+     * });
+     * ```
+     */
+    clear(): void;
+}
+
+export { InMemorySessionStore, InMemoryStateStore };
+export type { CacheInterface, SessionStore, StateStore };