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

package/dist/storage.cjs

@@ -0,0 +1,270 @@
+'use strict';
+
+/**
+ * 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
+ */
+class InMemorySessionStore {
+    constructor() {
+        /**
+         * Internal storage for sessions, keyed by DID.
+         * @internal
+         */
+        this.sessions = new Map();
+    }
+    /**
+     * 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");
+     * }
+     * ```
+     */
+    async get(did) {
+        return this.sessions.get(did);
+    }
+    /**
+     * 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);
+     * ```
+     */
+    async set(did, session) {
+        this.sessions.set(did, session);
+    }
+    /**
+     * 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");
+     * ```
+     */
+    async del(did) {
+        this.sessions.delete(did);
+    }
+    /**
+     * 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() {
+        this.sessions.clear();
+    }
+}
+
+/**
+ * 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
+ */
+class InMemoryStateStore {
+    constructor() {
+        /**
+         * Internal storage for OAuth state, keyed by state string.
+         * @internal
+         */
+        this.states = new Map();
+    }
+    /**
+     * 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");
+     * }
+     * ```
+     */
+    async get(key) {
+        return this.states.get(key);
+    }
+    /**
+     * 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.
+     * });
+     * ```
+     */
+    async set(key, state) {
+        this.states.set(key, state);
+    }
+    /**
+     * 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);
+     * ```
+     */
+    async del(key) {
+        this.states.delete(key);
+    }
+    /**
+     * 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() {
+        this.states.clear();
+    }
+}
+
+exports.InMemorySessionStore = InMemorySessionStore;
+exports.InMemoryStateStore = InMemoryStateStore;
+//# sourceMappingURL=storage.cjs.map

package/dist/storage.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.cjs","sources":["../src/storage/InMemorySessionStore.ts","../src/storage/InMemoryStateStore.ts"],"sourcesContent":["import type { SessionStore } from \"../core/interfaces.js\";\nimport type { NodeSavedSession } from \"@atproto/oauth-client-node\";\n\n/**\n * In-memory implementation of the SessionStore interface.\n *\n * This store keeps OAuth sessions in memory using a Map. It's intended\n * for development, testing, and simple use cases where session persistence\n * across restarts is not required.\n *\n * @remarks\n * **Warning**: This implementation is **not suitable for production** because:\n * - Sessions are lost when the process restarts\n * - Sessions cannot be shared across multiple server instances\n * - No automatic cleanup of expired sessions\n *\n * For production, implement {@link SessionStore} with a persistent backend:\n * - **Redis**: Good for distributed systems, supports TTL\n * - **PostgreSQL/MySQL**: Good for existing database infrastructure\n * - **MongoDB**: Good for document-based storage\n *\n * @example Basic usage\n * ```typescript\n * import { InMemorySessionStore } from \"@hypercerts-org/sdk/storage\";\n *\n * const sessionStore = new InMemorySessionStore();\n *\n * const sdk = new ATProtoSDK({\n *   oauth: { ... },\n *   storage: {\n *     sessionStore,  // Will warn in logs for production\n *   },\n * });\n * ```\n *\n * @example Testing usage\n * ```typescript\n * const sessionStore = new InMemorySessionStore();\n *\n * // After tests, clean up\n * sessionStore.clear();\n * ```\n *\n * @see {@link SessionStore} for the interface definition\n * @see {@link InMemoryStateStore} for the corresponding state store\n */\nexport class InMemorySessionStore implements SessionStore {\n  /**\n   * Internal storage for sessions, keyed by DID.\n   * @internal\n   */\n  private sessions = new Map<string, NodeSavedSession>();\n\n  /**\n   * Retrieves a session by DID.\n   *\n   * @param did - The user's Decentralized Identifier\n   * @returns Promise resolving to the session, or `undefined` if not found\n   *\n   * @example\n   * ```typescript\n   * const session = await sessionStore.get(\"did:plc:abc123\");\n   * if (session) {\n   *   console.log(\"Session found\");\n   * }\n   * ```\n   */\n  async get(did: string): Promise<NodeSavedSession | undefined> {\n    return this.sessions.get(did);\n  }\n\n  /**\n   * Stores or updates a session.\n   *\n   * @param did - The user's DID to use as the key\n   * @param session - The session data to store\n   *\n   * @remarks\n   * If a session already exists for the DID, it is overwritten.\n   *\n   * @example\n   * ```typescript\n   * await sessionStore.set(\"did:plc:abc123\", sessionData);\n   * ```\n   */\n  async set(did: string, session: NodeSavedSession): Promise<void> {\n    this.sessions.set(did, session);\n  }\n\n  /**\n   * Deletes a session by DID.\n   *\n   * @param did - The DID of the session to delete\n   *\n   * @remarks\n   * If no session exists for the DID, this is a no-op.\n   *\n   * @example\n   * ```typescript\n   * await sessionStore.del(\"did:plc:abc123\");\n   * ```\n   */\n  async del(did: string): Promise<void> {\n    this.sessions.delete(did);\n  }\n\n  /**\n   * Clears all stored sessions.\n   *\n   * This is primarily useful for testing to ensure a clean state\n   * between test runs.\n   *\n   * @remarks\n   * This method is synchronous (not async) for convenience in test cleanup.\n   *\n   * @example\n   * ```typescript\n   * // In test teardown\n   * afterEach(() => {\n   *   sessionStore.clear();\n   * });\n   * ```\n   */\n  clear(): void {\n    this.sessions.clear();\n  }\n}\n","import type { StateStore } from \"../core/interfaces.js\";\nimport type { NodeSavedState } from \"@atproto/oauth-client-node\";\n\n/**\n * In-memory implementation of the StateStore interface.\n *\n * This store keeps OAuth state parameters in memory using a Map. State is\n * used during the OAuth authorization flow for CSRF protection and PKCE.\n *\n * @remarks\n * **Warning**: This implementation is **not suitable for production** because:\n * - State is lost when the process restarts (breaking in-progress OAuth flows)\n * - State cannot be shared across multiple server instances\n * - No automatic cleanup of expired state (memory leak potential)\n *\n * For production, implement {@link StateStore} with a persistent backend\n * that supports TTL (time-to-live):\n * - **Redis**: Ideal choice with built-in TTL support\n * - **Database with cleanup job**: PostgreSQL/MySQL with periodic cleanup\n *\n * **State Lifecycle**:\n * 1. Created when user starts OAuth flow (`authorize()`)\n * 2. Retrieved and validated during callback\n * 3. Deleted after successful or failed callback\n * 4. Should expire after ~15 minutes if callback never happens\n *\n * @example Basic usage\n * ```typescript\n * import { InMemoryStateStore } from \"@hypercerts-org/sdk/storage\";\n *\n * const stateStore = new InMemoryStateStore();\n *\n * const sdk = new ATProtoSDK({\n *   oauth: { ... },\n *   storage: {\n *     stateStore,  // Will warn in logs for production\n *   },\n * });\n * ```\n *\n * @example Testing usage\n * ```typescript\n * const stateStore = new InMemoryStateStore();\n *\n * // After tests, clean up\n * stateStore.clear();\n * ```\n *\n * @see {@link StateStore} for the interface definition\n * @see {@link InMemorySessionStore} for the corresponding session store\n */\nexport class InMemoryStateStore implements StateStore {\n  /**\n   * Internal storage for OAuth state, keyed by state string.\n   * @internal\n   */\n  private states = new Map<string, NodeSavedState>();\n\n  /**\n   * Retrieves OAuth state by key.\n   *\n   * @param key - The state key (random string from authorization URL)\n   * @returns Promise resolving to the state, or `undefined` if not found\n   *\n   * @remarks\n   * The key is a cryptographically random string generated during\n   * the authorization request. It's included in the callback URL\n   * and used to retrieve the associated PKCE verifier and other data.\n   *\n   * @example\n   * ```typescript\n   * // During OAuth callback\n   * const state = await stateStore.get(params.get(\"state\")!);\n   * if (!state) {\n   *   throw new Error(\"Invalid or expired state\");\n   * }\n   * ```\n   */\n  async get(key: string): Promise<NodeSavedState | undefined> {\n    return this.states.get(key);\n  }\n\n  /**\n   * Stores OAuth state temporarily.\n   *\n   * @param key - The state key to use for storage\n   * @param state - The OAuth state data (includes PKCE verifier, etc.)\n   *\n   * @remarks\n   * In production implementations, state should be stored with a TTL\n   * of approximately 10-15 minutes to prevent stale state accumulation.\n   *\n   * @example\n   * ```typescript\n   * // Called internally by OAuthClient during authorize()\n   * await stateStore.set(stateKey, {\n   *   // PKCE code verifier, redirect URI, etc.\n   * });\n   * ```\n   */\n  async set(key: string, state: NodeSavedState): Promise<void> {\n    this.states.set(key, state);\n  }\n\n  /**\n   * Deletes OAuth state by key.\n   *\n   * @param key - The state key to delete\n   *\n   * @remarks\n   * Called after the OAuth callback is processed (whether successful or not)\n   * to clean up the temporary state.\n   *\n   * @example\n   * ```typescript\n   * // After processing callback\n   * await stateStore.del(stateKey);\n   * ```\n   */\n  async del(key: string): Promise<void> {\n    this.states.delete(key);\n  }\n\n  /**\n   * Clears all stored state.\n   *\n   * This is primarily useful for testing to ensure a clean state\n   * between test runs.\n   *\n   * @remarks\n   * This method is synchronous (not async) for convenience in test cleanup.\n   * In production, be careful using this as it will invalidate all\n   * in-progress OAuth flows.\n   *\n   * @example\n   * ```typescript\n   * // In test teardown\n   * afterEach(() => {\n   *   stateStore.clear();\n   * });\n   * ```\n   */\n  clear(): void {\n    this.states.clear();\n  }\n}\n"],"names":[],"mappings":";;AAGA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CG;MACU,oBAAoB,CAAA;AAAjC,IAAA,WAAA,GAAA;AACE;;;AAGG;AACK,QAAA,IAAA,CAAA,QAAQ,GAAG,IAAI,GAAG,EAA4B;IA2ExD;AAzEE;;;;;;;;;;;;;AAaG;IACH,MAAM,GAAG,CAAC,GAAW,EAAA;QACnB,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC;IAC/B;AAEA;;;;;;;;;;;;;AAaG;AACH,IAAA,MAAM,GAAG,CAAC,GAAW,EAAE,OAAyB,EAAA;QAC9C,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC;IACjC;AAEA;;;;;;;;;;;;AAYG;IACH,MAAM,GAAG,CAAC,GAAW,EAAA;AACnB,QAAA,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC;IAC3B;AAEA;;;;;;;;;;;;;;;;AAgBG;IACH,KAAK,GAAA;AACH,QAAA,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;IACvB;AACD;;AC3HD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA+CG;MACU,kBAAkB,CAAA;AAA/B,IAAA,WAAA,GAAA;AACE;;;AAGG;AACK,QAAA,IAAA,CAAA,MAAM,GAAG,IAAI,GAAG,EAA0B;IAyFpD;AAvFE;;;;;;;;;;;;;;;;;;;AAmBG;IACH,MAAM,GAAG,CAAC,GAAW,EAAA;QACnB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;IAC7B;AAEA;;;;;;;;;;;;;;;;;AAiBG;AACH,IAAA,MAAM,GAAG,CAAC,GAAW,EAAE,KAAqB,EAAA;QAC1C,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC;IAC7B;AAEA;;;;;;;;;;;;;;AAcG;IACH,MAAM,GAAG,CAAC,GAAW,EAAA;AACnB,QAAA,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC;IACzB;AAEA;;;;;;;;;;;;;;;;;;AAkBG;IACH,KAAK,GAAA;AACH,QAAA,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE;IACrB;AACD;;;;;"}