@atproto/lex-password-session 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @atproto/lex-password-session
 
+## 0.0.8
+
+### Patch Changes
+
+- Updated dependencies [[`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`f7c2610`](https://github.com/bluesky-social/atproto/commit/f7c26103a6d4e24e5bedbb6fd908be140420e0dd), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7), [`52834ab`](https://github.com/bluesky-social/atproto/commit/52834aba182da8df3611fd9dff924e6c6a3973a7)]:
+  - @atproto/lex-schema@0.0.14
+  - @atproto/lex-client@0.0.15
+
+## 0.0.7
+
+### Patch Changes
+
+- [#4672](https://github.com/bluesky-social/atproto/pull/4672) [`38852f0`](https://github.com/bluesky-social/atproto/commit/38852f0ddfa9fbce8036233dc6af87614e9ae4b2) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Make `PasswordSession` async disposable for better use with hard coded app passwords
+
+- [#4672](https://github.com/bluesky-social/atproto/pull/4672) [`38852f0`](https://github.com/bluesky-social/atproto/commit/38852f0ddfa9fbce8036233dc6af87614e9ae4b2) Thanks [@matthieusieben](https://github.com/matthieusieben)! - Add easy login for app password based bots
+
+- Updated dependencies [[`38852f0`](https://github.com/bluesky-social/atproto/commit/38852f0ddfa9fbce8036233dc6af87614e9ae4b2)]:
+  - @atproto/lex-client@0.0.14
+
 ## 0.0.6
 
 ### Patch Changes

package/dist/error.d.ts

@@ -44,12 +44,5 @@ export declare class LexAuthFactorError extends LexError {
      * @param cause - The underlying XRPC failure response from the server
      */
     constructor(cause: XrpcFailure);
-    /**
-     * Converts this error to an HTTP Response.
-     *
-     * @returns A 500 Internal Server Error response (2FA errors should not be
-     * exposed to end users in server contexts)
-     */
-    toResponse(): Response;
 }
 //# sourceMappingURL=error.d.ts.map

package/dist/error.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAQlC,QAAQ,CAAC,KAAK,EAAE,WAAW;IAPvC,IAAI,SAAuB;IAE3B;;;;OAIG;gBACkB,KAAK,EAAE,WAAW;IAIvC;;;;;OAKG;IACM,UAAU,IAAI,QAAQ;CAGhC"}
+{"version":3,"file":"error.d.ts","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAA;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,qBAAa,kBAAmB,SAAQ,QAAQ;IAQlC,QAAQ,CAAC,KAAK,EAAE,WAAW;IAPvC,IAAI,SAAuB;IAE3B;;;;OAIG;gBACkB,KAAK,EAAE,WAAW;CAGxC"}

package/dist/error.js

@@ -50,15 +50,6 @@ class LexAuthFactorError extends lex_client_1.LexError {
         super(cause.error, cause.message ?? 'Auth factor token required', { cause });
         this.cause = cause;
     }
-    /**
-     * Converts this error to an HTTP Response.
-     *
-     * @returns A 500 Internal Server Error response (2FA errors should not be
-     * exposed to end users in server contexts)
-     */
-    toResponse() {
-        return Response.json({ error: 'InternalServerError' }, { status: 500 });
-    }
 }
 exports.LexAuthFactorError = LexAuthFactorError;
 //# sourceMappingURL=error.js.map

package/dist/error.js.map

@@ -1 +1 @@
-{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,oDAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,kBAAmB,SAAQ,qBAAQ;IAQzB;IAPrB,IAAI,GAAG,oBAAoB,CAAA;IAE3B;;;;OAIG;IACH,YAAqB,KAAkB;QACrC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,IAAI,4BAA4B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QADzD,UAAK,GAAL,KAAK,CAAa;IAEvC,CAAC;IAED;;;;;OAKG;IACM,UAAU;QACjB,OAAO,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,qBAAqB,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAA;IACzE,CAAC;CACF;AArBD,gDAqBC","sourcesContent":["import { LexError, XrpcFailure } from '@atproto/lex-client'\n\n/**\n * Error thrown when two-factor authentication (2FA) is required.\n *\n * This error is thrown by {@link PasswordSession.login} when the server\n * requires an additional authentication factor (e.g., email code). Catch this\n * error to prompt the user for their 2FA code and retry the login with the\n * `authFactorToken` parameter.\n *\n * @example Handling 2FA requirement\n * ```ts\n * import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'\n *\n * try {\n *   const session = await PasswordSession.login({\n *     service: 'https://bsky.social',\n *     identifier: 'alice.bsky.social',\n *     password: 'xxxx-xxxx-xxxx-xxxx',\n *   })\n * } catch (err) {\n *   if (err instanceof LexAuthFactorError) {\n *     // Prompt user for 2FA code\n *     const token = await promptUser('Enter 2FA code from email:')\n *\n *     // Retry with the 2FA token\n *     const session = await PasswordSession.login({\n *       service: 'https://bsky.social',\n *       identifier: 'alice.bsky.social',\n *       password: 'xxxx-xxxx-xxxx-xxxx',\n *       authFactorToken: token,\n *     })\n *   }\n * }\n * ```\n *\n * @extends LexError\n */\nexport class LexAuthFactorError extends LexError {\n  name = 'LexAuthFactorError'\n\n  /**\n   * Creates a new LexAuthFactorError.\n   *\n   * @param cause - The underlying XRPC failure response from the server\n   */\n  constructor(readonly cause: XrpcFailure) {\n    super(cause.error, cause.message ?? 'Auth factor token required', { cause })\n  }\n\n  /**\n   * Converts this error to an HTTP Response.\n   *\n   * @returns A 500 Internal Server Error response (2FA errors should not be\n   * exposed to end users in server contexts)\n   */\n  override toResponse(): Response {\n    return Response.json({ error: 'InternalServerError' }, { status: 500 })\n  }\n}\n"]}
+{"version":3,"file":"error.js","sourceRoot":"","sources":["../src/error.ts"],"names":[],"mappings":";;;AAAA,oDAA2D;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAa,kBAAmB,SAAQ,qBAAQ;IAQzB;IAPrB,IAAI,GAAG,oBAAoB,CAAA;IAE3B;;;;OAIG;IACH,YAAqB,KAAkB;QACrC,KAAK,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,OAAO,IAAI,4BAA4B,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;QADzD,UAAK,GAAL,KAAK,CAAa;IAEvC,CAAC;CACF;AAXD,gDAWC","sourcesContent":["import { LexError, XrpcFailure } from '@atproto/lex-client'\n\n/**\n * Error thrown when two-factor authentication (2FA) is required.\n *\n * This error is thrown by {@link PasswordSession.login} when the server\n * requires an additional authentication factor (e.g., email code). Catch this\n * error to prompt the user for their 2FA code and retry the login with the\n * `authFactorToken` parameter.\n *\n * @example Handling 2FA requirement\n * ```ts\n * import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'\n *\n * try {\n *   const session = await PasswordSession.login({\n *     service: 'https://bsky.social',\n *     identifier: 'alice.bsky.social',\n *     password: 'xxxx-xxxx-xxxx-xxxx',\n *   })\n * } catch (err) {\n *   if (err instanceof LexAuthFactorError) {\n *     // Prompt user for 2FA code\n *     const token = await promptUser('Enter 2FA code from email:')\n *\n *     // Retry with the 2FA token\n *     const session = await PasswordSession.login({\n *       service: 'https://bsky.social',\n *       identifier: 'alice.bsky.social',\n *       password: 'xxxx-xxxx-xxxx-xxxx',\n *       authFactorToken: token,\n *     })\n *   }\n * }\n * ```\n *\n * @extends LexError\n */\nexport class LexAuthFactorError extends LexError {\n  name = 'LexAuthFactorError'\n\n  /**\n   * Creates a new LexAuthFactorError.\n   *\n   * @param cause - The underlying XRPC failure response from the server\n   */\n  constructor(readonly cause: XrpcFailure) {\n    super(cause.error, cause.message ?? 'Auth factor token required', { cause })\n  }\n}\n"]}

package/dist/password-session.d.ts

@@ -26,6 +26,13 @@ export type DeleteFailure = XrpcFailure<typeof com.atproto.server.deleteSession.
 export type SessionData = com.atproto.server.createSession.$OutputBody & {
     service: string;
 };
+export type LoginOptions = PasswordSessionOptions & {
+    service: string | URL;
+    identifier: string;
+    password: string;
+    allowTakendown?: boolean;
+    authFactorToken?: string;
+};
 export type PasswordSessionOptions = {
     /**
      * Custom fetch implementation to use for network requests
@@ -114,7 +121,7 @@ export type PasswordSessionOptions = {
  *
  * @implements {Agent}
  */
-export declare class PasswordSession implements Agent {
+export declare class PasswordSession implements Agent, AsyncDisposable {
     #private;
     protected readonly options: PasswordSessionOptions;
     constructor(sessionData: SessionData, options?: PasswordSessionOptions);
@@ -191,6 +198,7 @@ export declare class PasswordSession implements Agent {
      * @throws {DeleteFailure} If the logout request fails due to unexpected errors
      */
     logout(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
     /**
      * Creates a new account and returns an authenticated session.
      *
@@ -242,23 +250,42 @@ export declare class PasswordSession implements Agent {
      * @throws {LexAuthFactorError} If the server requires a 2FA token
      * @throws If authentication fails (invalid credentials, etc.)
      *
-     * @example Basic login with app password
+     * **Basic login with app password in script**
+     * @example
+     * ```ts
+     * // .env
+     * // APP_PASSWORD_CREDENTIALS="https://<handle>:<app-password>@<pds-hosting-provider>"
+     *
+     * // Make sure to dispose (or logout) the session when done to avoid leaking
+     * // resources and leaving orphaned sessions on the server
+     * await using session = await PasswordSession.login(process.env.APP_PASSWORD_CREDENTIALS)
+     *
+     * // Use session to make authenticated requests
+     * ```
+     *
+     * **Basic login with user password (not recommended!!!)**
+     * @example
      * ```ts
      * const session = await PasswordSession.login({
      *   service: 'https://bsky.social',
      *   identifier: 'alice.bsky.social',
-     *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+     *   password: 'xxxx',
      *   onUpdated: (data) => saveToStorage(data),
+     *   onDeleted: (data) => clearStorage(data.did),
      * })
+     *
+     * // Next time, use resume with the persisted session data to avoid storing
+     * // user credentials.
      * ```
      *
-     * @example Handling 2FA requirement
+     * **Handling 2FA requirement**
+     * @example
      * ```ts
      * try {
      *   const session = await PasswordSession.login({
      *     service: 'https://bsky.social',
      *     identifier: 'alice.bsky.social',
-     *     password: 'xxxx-xxxx-xxxx-xxxx',
+     *     password: 'xxxx',
      *   })
      * } catch (err) {
      *   if (err instanceof LexAuthFactorError) {
@@ -266,20 +293,14 @@ export declare class PasswordSession implements Agent {
      *     const session = await PasswordSession.login({
      *       service: 'https://bsky.social',
      *       identifier: 'alice.bsky.social',
-     *       password: 'xxxx-xxxx-xxxx-xxxx',
+     *       password: 'xxxx',
      *       authFactorToken: token,
      *     })
      *   }
      * }
      * ```
      */
-    static login({ service, identifier, password, allowTakendown, authFactorToken, ...options }: PasswordSessionOptions & {
-        service: string | URL;
-        identifier: string;
-        password: string;
-        allowTakendown?: boolean;
-        authFactorToken?: string;
-    }): Promise<PasswordSession>;
+    static login(input: string | URL | LoginOptions): Promise<PasswordSession>;
     /**
      * Resume an existing session, ensuring it is still valid by refreshing it.
      * Any error thrown here indicates that the session is definitely no longer

package/dist/password-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"password-session.d.ts","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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"}

package/dist/password-session.js

@@ -180,7 +180,7 @@ class PasswordSession {
     async refresh() {
         this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
             const response = await (0, lex_client_1.xrpcSafe)(this.#serviceAgent, index_js_1.com.atproto.server.refreshSession.main, { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } });
-            if (!response.success && response.matchesSchema()) {
+            if (!response.success && response.matchesSchemaErrors()) {
                 // Expected errors that indicate the session is no longer valid
                 await this.options.onDeleted?.call(this, sessionData);
                 // Update the session promise to a rejected state
@@ -188,10 +188,6 @@ class PasswordSession {
                 throw response;
             }
             if (!response.success) {
-                response.error;
-                if (response.matchesSchema()) {
-                    response.error;
-                }
                 // We failed to refresh the token, assume the session might still be
                 // valid by returning the existing session.
                 await this.options.onUpdateFailure?.call(this, sessionData, response);
@@ -237,7 +233,7 @@ class PasswordSession {
         let reason = null;
         this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
             const result = await (0, lex_client_1.xrpcSafe)(this.#serviceAgent, index_js_1.com.atproto.server.deleteSession.main, { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } });
-            if (result.success || result.matchesSchema()) {
+            if (result.success || result.matchesSchemaErrors()) {
                 await this.options.onDeleted?.call(this, sessionData);
                 // Update the session promise to a rejected state
                 this.#sessionData = null;
@@ -260,6 +256,9 @@ class PasswordSession {
             // Successful logout
         });
     }
+    async [Symbol.asyncDispose]() {
+        await this.logout();
+    }
     /**
      * Creates a new account and returns an authenticated session.
      *
@@ -317,23 +316,42 @@ class PasswordSession {
      * @throws {LexAuthFactorError} If the server requires a 2FA token
      * @throws If authentication fails (invalid credentials, etc.)
      *
-     * @example Basic login with app password
+     * **Basic login with app password in script**
+     * @example
+     * ```ts
+     * // .env
+     * // APP_PASSWORD_CREDENTIALS="https://<handle>:<app-password>@<pds-hosting-provider>"
+     *
+     * // Make sure to dispose (or logout) the session when done to avoid leaking
+     * // resources and leaving orphaned sessions on the server
+     * await using session = await PasswordSession.login(process.env.APP_PASSWORD_CREDENTIALS)
+     *
+     * // Use session to make authenticated requests
+     * ```
+     *
+     * **Basic login with user password (not recommended!!!)**
+     * @example
      * ```ts
      * const session = await PasswordSession.login({
      *   service: 'https://bsky.social',
      *   identifier: 'alice.bsky.social',
-     *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+     *   password: 'xxxx',
      *   onUpdated: (data) => saveToStorage(data),
+     *   onDeleted: (data) => clearStorage(data.did),
      * })
+     *
+     * // Next time, use resume with the persisted session data to avoid storing
+     * // user credentials.
      * ```
      *
-     * @example Handling 2FA requirement
+     * **Handling 2FA requirement**
+     * @example
      * ```ts
      * try {
      *   const session = await PasswordSession.login({
      *     service: 'https://bsky.social',
      *     identifier: 'alice.bsky.social',
-     *     password: 'xxxx-xxxx-xxxx-xxxx',
+     *     password: 'xxxx',
      *   })
      * } catch (err) {
      *   if (err instanceof LexAuthFactorError) {
@@ -341,14 +359,17 @@ class PasswordSession {
      *     const session = await PasswordSession.login({
      *       service: 'https://bsky.social',
      *       identifier: 'alice.bsky.social',
-     *       password: 'xxxx-xxxx-xxxx-xxxx',
+     *       password: 'xxxx',
      *       authFactorToken: token,
      *     })
      *   }
      * }
      * ```
      */
-    static async login({ service, identifier, password, allowTakendown, authFactorToken, ...options }) {
+    static async login(input) {
+        const { service, identifier, password, allowTakendown, authFactorToken, ...options } = typeof input === 'string' || input instanceof URL
+            ? parseLoginUrl(input)
+            : input;
         const xrpcAgent = (0, lex_client_1.buildAgent)({
             service,
             fetch: options.fetch,
@@ -403,4 +424,24 @@ function fetchUrl(sessionData, path) {
     const pdsUrl = (0, util_js_1.extractPdsUrl)(sessionData.didDoc);
     return new URL(path, pdsUrl ?? sessionData.service);
 }
+function parseLoginUrl(input) {
+    const url = typeof input === 'string' ? new URL(input) : input;
+    if (url.pathname !== '/') {
+        throw new TypeError('Invalid login URL: unexpected pathname');
+    }
+    if (url.hash) {
+        throw new TypeError('Invalid login URL: unexpected hash');
+    }
+    if (url.search) {
+        throw new TypeError('Invalid login URL: unexpected search parameters');
+    }
+    if (!url.username || !url.password) {
+        throw new TypeError('Invalid login URL: missing identifier or password');
+    }
+    return {
+        service: url.origin,
+        identifier: url.username,
+        password: url.password,
+    };
+}
 //# sourceMappingURL=password-session.js.map

package/dist/password-session.js.map

@@ -1 +1 @@
-{"version":3,"file":"password-session.js","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Agent,\n  XrpcFailure,\n  buildAgent,\n  xrpc,\n  xrpcSafe,\n} from '@atproto/lex-client'\nimport { LexAuthFactorError } from './error.js'\nimport { com } from './lexicons/index.js'\nimport { extractPdsUrl, extractXrpcErrorCode } from './util.js'\n\n/**\n * Represents a failure response when refreshing a session.\n *\n * This type captures the possible error responses from\n * `com.atproto.server.refreshSession`, including both expected errors\n * (e.g., invalid/expired refresh token) and unexpected errors (e.g., network issues).\n */\nexport type RefreshFailure = XrpcFailure<\n  typeof com.atproto.server.refreshSession.main\n>\n\n/**\n * Represents a failure response when deleting a session.\n *\n * This type captures the possible error responses from\n * `com.atproto.server.deleteSession`, including both expected errors\n * and unexpected errors (e.g., network issues, server unavailability).\n */\nexport type DeleteFailure = XrpcFailure<\n  typeof com.atproto.server.deleteSession.main\n>\n\n/**\n * Persisted session data containing authentication credentials and service information.\n *\n * This type extends the response from `com.atproto.server.createSession` with the\n * service URL used for authentication. Store this data securely to resume sessions\n * later without re-authenticating.\n */\nexport type SessionData = com.atproto.server.createSession.$OutputBody & {\n  service: string\n}\n\nexport type PasswordSessionOptions = {\n  /**\n   * Custom fetch implementation to use for network requests\n   */\n  fetch?: typeof globalThis.fetch\n\n  /**\n   * Called whenever the session is successfully created/refreshed, and new\n   * credentials have been obtained. Use this hook to persist the updated\n   * session information.\n   *\n   * If this callback returns a promise, this function will never be called\n   * again (on the same process) until the promise resolves.\n   *\n   * @note this function **must** not throw\n   */\n  onUpdated?: (this: PasswordSession, data: SessionData) => void | Promise<void>\n\n  /**\n   * Called whenever the session update fails due to an expected error, such as\n   * a network issue or server unavailability. This function can be used to log\n   * the error or notify the user, but should not assume that the session is\n   * invalid.\n   *\n   * @note this function **must** not throw\n   */\n  onUpdateFailure?: (\n    this: PasswordSession,\n    data: SessionData,\n    err: RefreshFailure,\n  ) => void | Promise<void>\n\n  /**\n   * Called whenever the session is deleted, either due to an explicit logout or\n   * because the refresh operation indicated that the session is no longer\n   * valid. Use this hook to clean up any persisted session information and\n   * update the application state accordingly.\n   *\n   * @note this function **must** not throw\n   */\n  onDeleted?: (this: PasswordSession, data: SessionData) => void | Promise<void>\n\n  /**\n   * Called whenever a session deletion fails due to an unexpected error, such\n   * as a network issue or server unavailability. This function can be used to\n   * log the error or notify the user. When this function is called, the session\n   * might still be valid on the server. It is up to the implementation to\n   * decide whether to retry the deletion or keep the session active. Ignoring\n   * these errors is not recommended as it can lead to orphaned sessions on the\n   * server, or security issues if the user believes they have logged out when a\n   * bad actor is still using the session. The implementation should consider\n   * keeping track of failed deletions and retrying them later, until they\n   * succeed.\n   *\n   * @note this function **must** not throw\n   */\n  onDeleteFailure?: (\n    this: PasswordSession,\n    data: SessionData,\n    err: DeleteFailure,\n  ) => void | Promise<void>\n}\n\n/**\n * Password-based authentication session for AT Protocol services.\n *\n * This class provides session management for CLI tools, scripts, and bots that\n * need to authenticate with AT Protocol services using password credentials.\n * It implements the {@link Agent} interface, allowing it to be used directly\n * with AT Protocol clients.\n *\n * **Security Warning:** It is strongly recommended to use app passwords instead\n * of main account credentials. App passwords provide limited access and can be\n * revoked independently without compromising your main account. For browser-based\n * applications, use OAuth-based authentication instead.\n *\n * @example Basic usage with app password\n * ```ts\n * const session = await PasswordSession.login({\n *   service: 'https://bsky.social',\n *   identifier: 'alice.bsky.social',\n *   password: 'xxxx-xxxx-xxxx-xxxx', // App password\n *   onUpdated: (data) => saveToStorage(data),\n *   onDeleted: (data) => clearStorage(data.did),\n * })\n *\n * const client = new Client(session)\n * // Use client to make authenticated requests\n * ```\n *\n * @example Resuming a persisted session\n * ```ts\n * const savedData = JSON.parse(fs.readFileSync('session.json', 'utf8'))\n * const session = await PasswordSession.resume(savedData, {\n *   onUpdated: (data) => saveToStorage(data),\n *   onDeleted: (data) => clearStorage(data.did),\n * })\n * ```\n *\n * @implements {Agent}\n */\nexport class PasswordSession implements Agent {\n  /**\n   * Internal {@link Agent} used for session management towards the\n   * authentication service only.\n   */\n  #serviceAgent: Agent\n\n  #sessionData: null | SessionData\n  #sessionPromise: Promise<SessionData>\n\n  constructor(\n    sessionData: SessionData,\n    protected readonly options: PasswordSessionOptions = {},\n  ) {\n    this.#serviceAgent = buildAgent({\n      service: sessionData.service,\n      fetch: options.fetch,\n    })\n\n    this.#sessionData = sessionData\n    this.#sessionPromise = Promise.resolve(this.#sessionData)\n  }\n\n  /**\n   * The DID (Decentralized Identifier) of the authenticated account.\n   *\n   * @throws {Error} If the session has been destroyed (logged out).\n   */\n  get did() {\n    return this.session.did\n  }\n\n  /**\n   * The handle (username) of the authenticated account.\n   *\n   * @throws {Error} If the session has been destroyed (logged out).\n   */\n  get handle() {\n    return this.session.handle\n  }\n\n  /**\n   * The current session data containing authentication credentials.\n   *\n   * @throws {Error} If the session has been destroyed (logged out).\n   */\n  get session() {\n    if (this.#sessionData) return this.#sessionData\n    throw new Error('Logged out')\n  }\n\n  /**\n   * Whether this session has been destroyed (logged out).\n   *\n   * Once destroyed, this session instance can no longer be used for\n   * authenticated requests. Create a new session via {@link PasswordSession.login}\n   * or {@link PasswordSession.resume}.\n   */\n  get destroyed(): boolean {\n    return this.#sessionData === null\n  }\n\n  /**\n   * Handles authenticated fetch requests to the user's PDS.\n   *\n   * This method implements the {@link Agent} interface and is called by\n   * AT Protocol clients to make authenticated requests. It automatically:\n   * - Adds the access token to request headers\n   * - Detects expired tokens and triggers refresh\n   * - Retries requests after successful token refresh\n   *\n   * @param path - The request path (will be resolved against the PDS URL)\n   * @param init - Standard fetch RequestInit options (headers, body, etc.)\n   * @returns The fetch Response from the PDS\n   * @throws {TypeError} If an 'authorization' header is already set in init\n   */\n  async fetchHandler(path: string, init: RequestInit): Promise<Response> {\n    const headers = new Headers(init.headers)\n    if (headers.has('authorization')) {\n      throw new TypeError(\"Unexpected 'authorization' header set\")\n    }\n\n    const sessionPromise = this.#sessionPromise\n    const sessionData = await sessionPromise\n\n    const fetch = this.options.fetch ?? globalThis.fetch\n\n    headers.set('authorization', `Bearer ${sessionData.accessJwt}`)\n    const initialRes = await fetch(fetchUrl(sessionData, path), {\n      ...init,\n      headers,\n    })\n\n    const refreshNeeded =\n      initialRes.status === 401 ||\n      (initialRes.status === 400 &&\n        (await extractXrpcErrorCode(initialRes)) === 'ExpiredToken')\n\n    if (!refreshNeeded) {\n      return initialRes\n    }\n\n    // Refresh session (unless it was already refreshed in the meantime)\n    const newSessionPromise =\n      this.#sessionPromise === sessionPromise\n        ? this.refresh()\n        : this.#sessionPromise\n\n    // Error should have been propagated through hooks\n    const newSessionData = await newSessionPromise.catch((_err) => null)\n    if (!newSessionData) {\n      return initialRes\n    }\n\n    // refresh silently failed, no point in retrying.\n    if (newSessionData.accessJwt === sessionData.accessJwt) {\n      return initialRes\n    }\n\n    if (init?.signal?.aborted) {\n      return initialRes\n    }\n\n    // The stream was already consumed. We cannot retry the request. A solution\n    // would be to tee() the input stream but that would bufferize the entire\n    // stream in memory which can lead to memory starvation. Instead, we will\n    // return the original response and let the calling code handle retries.\n    if (ReadableStream && init?.body instanceof ReadableStream) {\n      return initialRes\n    }\n\n    // Make sure the initial request is cancelled to avoid leaking resources\n    // (NodeJS 👀): https://undici.nodejs.org/#/?id=garbage-collection\n    if (!initialRes.bodyUsed) {\n      await initialRes.body?.cancel()\n    }\n\n    // Finally, retry the request with the new access token\n    headers.set('authorization', `Bearer ${newSessionData.accessJwt}`)\n    return fetch(fetchUrl(newSessionData, path), { ...init, headers })\n  }\n\n  /**\n   * Refreshes the session by obtaining new access and refresh tokens.\n   *\n   * This method is automatically called by {@link fetchHandler} when the access\n   * token expires. You can also call it manually to proactively refresh tokens.\n   *\n   * On success, the {@link PasswordSessionOptions.onUpdated} callback is invoked\n   * with the new session data. On expected failures (invalid session), the\n   * {@link PasswordSessionOptions.onDeleted} callback is invoked. On unexpected\n   * failures (network issues), the {@link PasswordSessionOptions.onUpdateFailure}\n   * callback is invoked and the existing session data is preserved.\n   *\n   * @returns The refreshed session data\n   * @throws {RefreshFailure} If the session is no longer valid (triggers onDeleted)\n   */\n  async refresh(): Promise<SessionData> {\n    this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n      const response = await xrpcSafe(\n        this.#serviceAgent,\n        com.atproto.server.refreshSession.main,\n        { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n      )\n\n      if (!response.success && response.matchesSchema()) {\n        // Expected errors that indicate the session is no longer valid\n        await this.options.onDeleted?.call(this, sessionData)\n\n        // Update the session promise to a rejected state\n        this.#sessionData = null\n        throw response\n      }\n\n      if (!response.success) {\n        response.error\n        if (response.matchesSchema()) {\n          response.error\n        }\n        // We failed to refresh the token, assume the session might still be\n        // valid by returning the existing session.\n        await this.options.onUpdateFailure?.call(this, sessionData, response)\n\n        return sessionData\n      }\n\n      const data = response.body\n\n      // Historically, refreshSession did not return all the fields from\n      // getSession. In particular, emailConfirmed and didDoc were missing.\n      // Similarly, some servers might not return the didDoc in refreshSession.\n      // We fetch them via getSession if missing, allowing to ensure that we are\n      // always talking with the right PDS.\n      if (data.emailConfirmed == null || data.didDoc == null) {\n        const extraData = await xrpcSafe(\n          this.#serviceAgent,\n          com.atproto.server.getSession.main,\n          { headers: { Authorization: `Bearer ${data.accessJwt}` } },\n        )\n        if (extraData.success && extraData.body.did === data.did) {\n          Object.assign(data, extraData.body)\n        }\n      }\n\n      const newSession: SessionData = {\n        ...data,\n        service: sessionData.service,\n      }\n\n      await this.options.onUpdated?.call(this, newSession)\n\n      return (this.#sessionData = newSession)\n    })\n\n    return this.#sessionPromise\n  }\n\n  /**\n   * Logs out by deleting the session on the server.\n   *\n   * This method invalidates both the access and refresh tokens on the server,\n   * preventing any further use of this session. After successful logout, the\n   * session is marked as destroyed and the {@link PasswordSessionOptions.onDeleted}\n   * callback is invoked.\n   *\n   * If the logout request fails due to network issues or server unavailability,\n   * the {@link PasswordSessionOptions.onDeleteFailure} callback is invoked and\n   * the session remains active locally. In this case, you should retry the\n   * logout later to ensure the session is properly invalidated on the server.\n   *\n   * @throws {DeleteFailure} If the logout request fails due to unexpected errors\n   */\n  async logout(): Promise<void> {\n    let reason: DeleteFailure | null = null\n\n    this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n      const result = await xrpcSafe(\n        this.#serviceAgent,\n        com.atproto.server.deleteSession.main,\n        { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n      )\n\n      if (result.success || result.matchesSchema()) {\n        await this.options.onDeleted?.call(this, sessionData)\n\n        // Update the session promise to a rejected state\n        this.#sessionData = null\n        throw new Error('Logged out')\n      } else {\n        // Capture the reason for the failure to re-throw in the outer promise\n        reason = result\n\n        // An unknown/unexpected error occurred (network, server down, etc)\n        await this.options.onDeleteFailure?.call(this, sessionData, result)\n\n        // Keep the session in an active state\n        return sessionData\n      }\n    })\n\n    return this.#sessionPromise.then(\n      (_session) => {\n        // If the promise above resolved, then logout failed. Re-throw the\n        // reason captured earlier.\n        throw reason!\n      },\n      (_err) => {\n        // Successful logout\n      },\n    )\n  }\n\n  /**\n   * Creates a new account and returns an authenticated session.\n   *\n   * This static method registers a new account on the specified service and\n   * automatically creates an authenticated session for it.\n   *\n   * @param body - Account creation parameters (handle, email, password, etc.)\n   * @param options - Session options including the service URL\n   * @returns A new PasswordSession for the created account\n   * @throws If account creation fails (e.g., handle taken, invalid invite code)\n   *\n   * @example\n   * ```ts\n   * const session = await PasswordSession.createAccount(\n   *   {\n   *     handle: 'alice.bsky.social',\n   *     email: 'alice@example.com',\n   *     password: 'secure-password',\n   *   },\n   *   {\n   *     service: 'https://bsky.social',\n   *     onUpdated: (data) => saveToStorage(data),\n   *   }\n   * )\n   * ```\n   */\n  static async createAccount(\n    body: com.atproto.server.createAccount.$InputBody,\n    {\n      service,\n      headers,\n      ...options\n    }: PasswordSessionOptions & {\n      headers?: HeadersInit\n      service: string | URL\n    },\n  ): Promise<PasswordSession> {\n    const response = await xrpc(\n      buildAgent({ service, headers, fetch: options.fetch }),\n      com.atproto.server.createAccount.main,\n      { body },\n    )\n\n    const data: SessionData = {\n      ...response.body,\n      service: String(service),\n    }\n\n    const agent = new PasswordSession(data, options)\n    await options.onUpdated?.call(agent, data)\n    return agent\n  }\n\n  /**\n   * Creates a new authenticated session using password credentials.\n   *\n   * This static method authenticates with the specified service and returns\n   * a new PasswordSession instance that can be used for authenticated requests.\n   *\n   * **Security Warning:** It is strongly recommended to use app passwords instead\n   * of main account credentials. App passwords can be created in your account\n   * settings and provide limited access that can be revoked independently. For\n   * browser-based applications, use OAuth-based authentication instead.\n   *\n   * @param options - Login options including service URL, identifier, and password\n   * @param options.service - The AT Protocol service URL (e.g., 'https://bsky.social')\n   * @param options.identifier - The user's handle or DID\n   * @param options.password - The user's password or app password\n   * @param options.allowTakendown - If true, allow login to takendown accounts\n   * @param options.authFactorToken - 2FA token if required by the server\n   * @returns A new authenticated PasswordSession\n   * @throws {LexAuthFactorError} If the server requires a 2FA token\n   * @throws If authentication fails (invalid credentials, etc.)\n   *\n   * @example Basic login with app password\n   * ```ts\n   * const session = await PasswordSession.login({\n   *   service: 'https://bsky.social',\n   *   identifier: 'alice.bsky.social',\n   *   password: 'xxxx-xxxx-xxxx-xxxx', // App password\n   *   onUpdated: (data) => saveToStorage(data),\n   * })\n   * ```\n   *\n   * @example Handling 2FA requirement\n   * ```ts\n   * try {\n   *   const session = await PasswordSession.login({\n   *     service: 'https://bsky.social',\n   *     identifier: 'alice.bsky.social',\n   *     password: 'xxxx-xxxx-xxxx-xxxx',\n   *   })\n   * } catch (err) {\n   *   if (err instanceof LexAuthFactorError) {\n   *     const token = await promptUser('Enter 2FA code:')\n   *     const session = await PasswordSession.login({\n   *       service: 'https://bsky.social',\n   *       identifier: 'alice.bsky.social',\n   *       password: 'xxxx-xxxx-xxxx-xxxx',\n   *       authFactorToken: token,\n   *     })\n   *   }\n   * }\n   * ```\n   */\n  static async login({\n    service,\n    identifier,\n    password,\n    allowTakendown,\n    authFactorToken,\n    ...options\n  }: PasswordSessionOptions & {\n    service: string | URL\n    identifier: string\n    password: string\n    allowTakendown?: boolean\n    authFactorToken?: string\n  }): Promise<PasswordSession> {\n    const xrpcAgent = buildAgent({\n      service,\n      fetch: options.fetch,\n    })\n\n    const response = await xrpcSafe(\n      xrpcAgent,\n      com.atproto.server.createSession.main,\n      { body: { identifier, password, allowTakendown, authFactorToken } },\n    )\n\n    if (!response.success) {\n      if (response.error === 'AuthFactorTokenRequired') {\n        throw new LexAuthFactorError(response)\n      }\n      throw response.reason\n    }\n\n    const data: SessionData = {\n      ...response.body,\n      service: String(service),\n    }\n\n    const agent = new PasswordSession(data, options)\n    await options.onUpdated?.call(agent, data)\n    return agent\n  }\n\n  /**\n   * Resume an existing session, ensuring it is still valid by refreshing it.\n   * Any error thrown here indicates that the session is definitely no longer\n   * valid. Network errors will be propagated through the\n   * {@link PasswordSessionOptions.onUpdateFailure} hook, and not re-thrown\n   * here. This means that a resolved promise does not necessarily indicate a\n   * valid session, only that it's refresh did not definitively fail.\n   *\n   * This is the same as calling {@link PasswordSession.refresh} after\n   * constructing the {@link PasswordSession} manually.\n   *\n   * @throws If, and only if, the session is definitely no longer valid.\n   */\n  static async resume(\n    data: SessionData,\n    options: PasswordSessionOptions,\n  ): Promise<PasswordSession> {\n    const agent = new PasswordSession(data, options)\n    await agent.refresh()\n    return agent\n  }\n\n  /**\n   * Delete a session without having to {@link resume resume()} it first, or\n   * provide hooks.\n   *\n   * @throws In case of unexpected error (network issue, server down, etc)\n   * meaning that the session may still be valid.\n   */\n  static async delete(\n    data: SessionData,\n    options?: PasswordSessionOptions,\n  ): Promise<void> {\n    const agent = new PasswordSession(data, options)\n    await agent.logout()\n  }\n}\n\nfunction fetchUrl(sessionData: SessionData, path: string): URL {\n  const pdsUrl = extractPdsUrl(sessionData.didDoc)\n  return new URL(path, pdsUrl ?? sessionData.service)\n}\n"]}
+{"version":3,"file":"password-session.js","sourceRoot":"","sources":["../src/password-session.ts"],"names":[],"mappings":"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","sourcesContent":["import {\n  Agent,\n  XrpcFailure,\n  buildAgent,\n  xrpc,\n  xrpcSafe,\n} from '@atproto/lex-client'\nimport { LexAuthFactorError } from './error.js'\nimport { com } from './lexicons/index.js'\nimport { extractPdsUrl, extractXrpcErrorCode } from './util.js'\n\n/**\n * Represents a failure response when refreshing a session.\n *\n * This type captures the possible error responses from\n * `com.atproto.server.refreshSession`, including both expected errors\n * (e.g., invalid/expired refresh token) and unexpected errors (e.g., network issues).\n */\nexport type RefreshFailure = XrpcFailure<\n  typeof com.atproto.server.refreshSession.main\n>\n\n/**\n * Represents a failure response when deleting a session.\n *\n * This type captures the possible error responses from\n * `com.atproto.server.deleteSession`, including both expected errors\n * and unexpected errors (e.g., network issues, server unavailability).\n */\nexport type DeleteFailure = XrpcFailure<\n  typeof com.atproto.server.deleteSession.main\n>\n\n/**\n * Persisted session data containing authentication credentials and service information.\n *\n * This type extends the response from `com.atproto.server.createSession` with the\n * service URL used for authentication. Store this data securely to resume sessions\n * later without re-authenticating.\n */\nexport type SessionData = com.atproto.server.createSession.$OutputBody & {\n  service: string\n}\n\nexport type LoginOptions = PasswordSessionOptions & {\n  service: string | URL\n  identifier: string\n  password: string\n  allowTakendown?: boolean\n  authFactorToken?: string\n}\n\nexport type PasswordSessionOptions = {\n  /**\n   * Custom fetch implementation to use for network requests\n   */\n  fetch?: typeof globalThis.fetch\n\n  /**\n   * Called whenever the session is successfully created/refreshed, and new\n   * credentials have been obtained. Use this hook to persist the updated\n   * session information.\n   *\n   * If this callback returns a promise, this function will never be called\n   * again (on the same process) until the promise resolves.\n   *\n   * @note this function **must** not throw\n   */\n  onUpdated?: (this: PasswordSession, data: SessionData) => void | Promise<void>\n\n  /**\n   * Called whenever the session update fails due to an expected error, such as\n   * a network issue or server unavailability. This function can be used to log\n   * the error or notify the user, but should not assume that the session is\n   * invalid.\n   *\n   * @note this function **must** not throw\n   */\n  onUpdateFailure?: (\n    this: PasswordSession,\n    data: SessionData,\n    err: RefreshFailure,\n  ) => void | Promise<void>\n\n  /**\n   * Called whenever the session is deleted, either due to an explicit logout or\n   * because the refresh operation indicated that the session is no longer\n   * valid. Use this hook to clean up any persisted session information and\n   * update the application state accordingly.\n   *\n   * @note this function **must** not throw\n   */\n  onDeleted?: (this: PasswordSession, data: SessionData) => void | Promise<void>\n\n  /**\n   * Called whenever a session deletion fails due to an unexpected error, such\n   * as a network issue or server unavailability. This function can be used to\n   * log the error or notify the user. When this function is called, the session\n   * might still be valid on the server. It is up to the implementation to\n   * decide whether to retry the deletion or keep the session active. Ignoring\n   * these errors is not recommended as it can lead to orphaned sessions on the\n   * server, or security issues if the user believes they have logged out when a\n   * bad actor is still using the session. The implementation should consider\n   * keeping track of failed deletions and retrying them later, until they\n   * succeed.\n   *\n   * @note this function **must** not throw\n   */\n  onDeleteFailure?: (\n    this: PasswordSession,\n    data: SessionData,\n    err: DeleteFailure,\n  ) => void | Promise<void>\n}\n\n/**\n * Password-based authentication session for AT Protocol services.\n *\n * This class provides session management for CLI tools, scripts, and bots that\n * need to authenticate with AT Protocol services using password credentials.\n * It implements the {@link Agent} interface, allowing it to be used directly\n * with AT Protocol clients.\n *\n * **Security Warning:** It is strongly recommended to use app passwords instead\n * of main account credentials. App passwords provide limited access and can be\n * revoked independently without compromising your main account. For browser-based\n * applications, use OAuth-based authentication instead.\n *\n * @example Basic usage with app password\n * ```ts\n * const session = await PasswordSession.login({\n *   service: 'https://bsky.social',\n *   identifier: 'alice.bsky.social',\n *   password: 'xxxx-xxxx-xxxx-xxxx', // App password\n *   onUpdated: (data) => saveToStorage(data),\n *   onDeleted: (data) => clearStorage(data.did),\n * })\n *\n * const client = new Client(session)\n * // Use client to make authenticated requests\n * ```\n *\n * @example Resuming a persisted session\n * ```ts\n * const savedData = JSON.parse(fs.readFileSync('session.json', 'utf8'))\n * const session = await PasswordSession.resume(savedData, {\n *   onUpdated: (data) => saveToStorage(data),\n *   onDeleted: (data) => clearStorage(data.did),\n * })\n * ```\n *\n * @implements {Agent}\n */\nexport class PasswordSession implements Agent, AsyncDisposable {\n  /**\n   * Internal {@link Agent} used for session management towards the\n   * authentication service only.\n   */\n  #serviceAgent: Agent\n\n  #sessionData: null | SessionData\n  #sessionPromise: Promise<SessionData>\n\n  constructor(\n    sessionData: SessionData,\n    protected readonly options: PasswordSessionOptions = {},\n  ) {\n    this.#serviceAgent = buildAgent({\n      service: sessionData.service,\n      fetch: options.fetch,\n    })\n\n    this.#sessionData = sessionData\n    this.#sessionPromise = Promise.resolve(this.#sessionData)\n  }\n\n  /**\n   * The DID (Decentralized Identifier) of the authenticated account.\n   *\n   * @throws {Error} If the session has been destroyed (logged out).\n   */\n  get did() {\n    return this.session.did\n  }\n\n  /**\n   * The handle (username) of the authenticated account.\n   *\n   * @throws {Error} If the session has been destroyed (logged out).\n   */\n  get handle() {\n    return this.session.handle\n  }\n\n  /**\n   * The current session data containing authentication credentials.\n   *\n   * @throws {Error} If the session has been destroyed (logged out).\n   */\n  get session() {\n    if (this.#sessionData) return this.#sessionData\n    throw new Error('Logged out')\n  }\n\n  /**\n   * Whether this session has been destroyed (logged out).\n   *\n   * Once destroyed, this session instance can no longer be used for\n   * authenticated requests. Create a new session via {@link PasswordSession.login}\n   * or {@link PasswordSession.resume}.\n   */\n  get destroyed(): boolean {\n    return this.#sessionData === null\n  }\n\n  /**\n   * Handles authenticated fetch requests to the user's PDS.\n   *\n   * This method implements the {@link Agent} interface and is called by\n   * AT Protocol clients to make authenticated requests. It automatically:\n   * - Adds the access token to request headers\n   * - Detects expired tokens and triggers refresh\n   * - Retries requests after successful token refresh\n   *\n   * @param path - The request path (will be resolved against the PDS URL)\n   * @param init - Standard fetch RequestInit options (headers, body, etc.)\n   * @returns The fetch Response from the PDS\n   * @throws {TypeError} If an 'authorization' header is already set in init\n   */\n  async fetchHandler(path: string, init: RequestInit): Promise<Response> {\n    const headers = new Headers(init.headers)\n    if (headers.has('authorization')) {\n      throw new TypeError(\"Unexpected 'authorization' header set\")\n    }\n\n    const sessionPromise = this.#sessionPromise\n    const sessionData = await sessionPromise\n\n    const fetch = this.options.fetch ?? globalThis.fetch\n\n    headers.set('authorization', `Bearer ${sessionData.accessJwt}`)\n    const initialRes = await fetch(fetchUrl(sessionData, path), {\n      ...init,\n      headers,\n    })\n\n    const refreshNeeded =\n      initialRes.status === 401 ||\n      (initialRes.status === 400 &&\n        (await extractXrpcErrorCode(initialRes)) === 'ExpiredToken')\n\n    if (!refreshNeeded) {\n      return initialRes\n    }\n\n    // Refresh session (unless it was already refreshed in the meantime)\n    const newSessionPromise =\n      this.#sessionPromise === sessionPromise\n        ? this.refresh()\n        : this.#sessionPromise\n\n    // Error should have been propagated through hooks\n    const newSessionData = await newSessionPromise.catch((_err) => null)\n    if (!newSessionData) {\n      return initialRes\n    }\n\n    // refresh silently failed, no point in retrying.\n    if (newSessionData.accessJwt === sessionData.accessJwt) {\n      return initialRes\n    }\n\n    if (init?.signal?.aborted) {\n      return initialRes\n    }\n\n    // The stream was already consumed. We cannot retry the request. A solution\n    // would be to tee() the input stream but that would bufferize the entire\n    // stream in memory which can lead to memory starvation. Instead, we will\n    // return the original response and let the calling code handle retries.\n    if (ReadableStream && init?.body instanceof ReadableStream) {\n      return initialRes\n    }\n\n    // Make sure the initial request is cancelled to avoid leaking resources\n    // (NodeJS 👀): https://undici.nodejs.org/#/?id=garbage-collection\n    if (!initialRes.bodyUsed) {\n      await initialRes.body?.cancel()\n    }\n\n    // Finally, retry the request with the new access token\n    headers.set('authorization', `Bearer ${newSessionData.accessJwt}`)\n    return fetch(fetchUrl(newSessionData, path), { ...init, headers })\n  }\n\n  /**\n   * Refreshes the session by obtaining new access and refresh tokens.\n   *\n   * This method is automatically called by {@link fetchHandler} when the access\n   * token expires. You can also call it manually to proactively refresh tokens.\n   *\n   * On success, the {@link PasswordSessionOptions.onUpdated} callback is invoked\n   * with the new session data. On expected failures (invalid session), the\n   * {@link PasswordSessionOptions.onDeleted} callback is invoked. On unexpected\n   * failures (network issues), the {@link PasswordSessionOptions.onUpdateFailure}\n   * callback is invoked and the existing session data is preserved.\n   *\n   * @returns The refreshed session data\n   * @throws {RefreshFailure} If the session is no longer valid (triggers onDeleted)\n   */\n  async refresh(): Promise<SessionData> {\n    this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n      const response = await xrpcSafe(\n        this.#serviceAgent,\n        com.atproto.server.refreshSession.main,\n        { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n      )\n\n      if (!response.success && response.matchesSchemaErrors()) {\n        // Expected errors that indicate the session is no longer valid\n        await this.options.onDeleted?.call(this, sessionData)\n\n        // Update the session promise to a rejected state\n        this.#sessionData = null\n        throw response\n      }\n\n      if (!response.success) {\n        // We failed to refresh the token, assume the session might still be\n        // valid by returning the existing session.\n        await this.options.onUpdateFailure?.call(this, sessionData, response)\n\n        return sessionData\n      }\n\n      const data = response.body\n\n      // Historically, refreshSession did not return all the fields from\n      // getSession. In particular, emailConfirmed and didDoc were missing.\n      // Similarly, some servers might not return the didDoc in refreshSession.\n      // We fetch them via getSession if missing, allowing to ensure that we are\n      // always talking with the right PDS.\n      if (data.emailConfirmed == null || data.didDoc == null) {\n        const extraData = await xrpcSafe(\n          this.#serviceAgent,\n          com.atproto.server.getSession.main,\n          { headers: { Authorization: `Bearer ${data.accessJwt}` } },\n        )\n        if (extraData.success && extraData.body.did === data.did) {\n          Object.assign(data, extraData.body)\n        }\n      }\n\n      const newSession: SessionData = {\n        ...data,\n        service: sessionData.service,\n      }\n\n      await this.options.onUpdated?.call(this, newSession)\n\n      return (this.#sessionData = newSession)\n    })\n\n    return this.#sessionPromise\n  }\n\n  /**\n   * Logs out by deleting the session on the server.\n   *\n   * This method invalidates both the access and refresh tokens on the server,\n   * preventing any further use of this session. After successful logout, the\n   * session is marked as destroyed and the {@link PasswordSessionOptions.onDeleted}\n   * callback is invoked.\n   *\n   * If the logout request fails due to network issues or server unavailability,\n   * the {@link PasswordSessionOptions.onDeleteFailure} callback is invoked and\n   * the session remains active locally. In this case, you should retry the\n   * logout later to ensure the session is properly invalidated on the server.\n   *\n   * @throws {DeleteFailure} If the logout request fails due to unexpected errors\n   */\n  async logout(): Promise<void> {\n    let reason: DeleteFailure | null = null\n\n    this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {\n      const result = await xrpcSafe(\n        this.#serviceAgent,\n        com.atproto.server.deleteSession.main,\n        { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },\n      )\n\n      if (result.success || result.matchesSchemaErrors()) {\n        await this.options.onDeleted?.call(this, sessionData)\n\n        // Update the session promise to a rejected state\n        this.#sessionData = null\n        throw new Error('Logged out')\n      } else {\n        // Capture the reason for the failure to re-throw in the outer promise\n        reason = result\n\n        // An unknown/unexpected error occurred (network, server down, etc)\n        await this.options.onDeleteFailure?.call(this, sessionData, result)\n\n        // Keep the session in an active state\n        return sessionData\n      }\n    })\n\n    return this.#sessionPromise.then(\n      (_session) => {\n        // If the promise above resolved, then logout failed. Re-throw the\n        // reason captured earlier.\n        throw reason!\n      },\n      (_err) => {\n        // Successful logout\n      },\n    )\n  }\n\n  async [Symbol.asyncDispose]() {\n    await this.logout()\n  }\n\n  /**\n   * Creates a new account and returns an authenticated session.\n   *\n   * This static method registers a new account on the specified service and\n   * automatically creates an authenticated session for it.\n   *\n   * @param body - Account creation parameters (handle, email, password, etc.)\n   * @param options - Session options including the service URL\n   * @returns A new PasswordSession for the created account\n   * @throws If account creation fails (e.g., handle taken, invalid invite code)\n   *\n   * @example\n   * ```ts\n   * const session = await PasswordSession.createAccount(\n   *   {\n   *     handle: 'alice.bsky.social',\n   *     email: 'alice@example.com',\n   *     password: 'secure-password',\n   *   },\n   *   {\n   *     service: 'https://bsky.social',\n   *     onUpdated: (data) => saveToStorage(data),\n   *   }\n   * )\n   * ```\n   */\n  static async createAccount(\n    body: com.atproto.server.createAccount.$InputBody,\n    {\n      service,\n      headers,\n      ...options\n    }: PasswordSessionOptions & {\n      headers?: HeadersInit\n      service: string | URL\n    },\n  ): Promise<PasswordSession> {\n    const response = await xrpc(\n      buildAgent({ service, headers, fetch: options.fetch }),\n      com.atproto.server.createAccount.main,\n      { body },\n    )\n\n    const data: SessionData = {\n      ...response.body,\n      service: String(service),\n    }\n\n    const agent = new PasswordSession(data, options)\n    await options.onUpdated?.call(agent, data)\n    return agent\n  }\n\n  /**\n   * Creates a new authenticated session using password credentials.\n   *\n   * This static method authenticates with the specified service and returns\n   * a new PasswordSession instance that can be used for authenticated requests.\n   *\n   * **Security Warning:** It is strongly recommended to use app passwords instead\n   * of main account credentials. App passwords can be created in your account\n   * settings and provide limited access that can be revoked independently. For\n   * browser-based applications, use OAuth-based authentication instead.\n   *\n   * @param options - Login options including service URL, identifier, and password\n   * @param options.service - The AT Protocol service URL (e.g., 'https://bsky.social')\n   * @param options.identifier - The user's handle or DID\n   * @param options.password - The user's password or app password\n   * @param options.allowTakendown - If true, allow login to takendown accounts\n   * @param options.authFactorToken - 2FA token if required by the server\n   * @returns A new authenticated PasswordSession\n   * @throws {LexAuthFactorError} If the server requires a 2FA token\n   * @throws If authentication fails (invalid credentials, etc.)\n   *\n   * **Basic login with app password in script**\n   * @example\n   * ```ts\n   * // .env\n   * // APP_PASSWORD_CREDENTIALS=\"https://<handle>:<app-password>@<pds-hosting-provider>\"\n   *\n   * // Make sure to dispose (or logout) the session when done to avoid leaking\n   * // resources and leaving orphaned sessions on the server\n   * await using session = await PasswordSession.login(process.env.APP_PASSWORD_CREDENTIALS)\n   *\n   * // Use session to make authenticated requests\n   * ```\n   *\n   * **Basic login with user password (not recommended!!!)**\n   * @example\n   * ```ts\n   * const session = await PasswordSession.login({\n   *   service: 'https://bsky.social',\n   *   identifier: 'alice.bsky.social',\n   *   password: 'xxxx',\n   *   onUpdated: (data) => saveToStorage(data),\n   *   onDeleted: (data) => clearStorage(data.did),\n   * })\n   *\n   * // Next time, use resume with the persisted session data to avoid storing\n   * // user credentials.\n   * ```\n   *\n   * **Handling 2FA requirement**\n   * @example\n   * ```ts\n   * try {\n   *   const session = await PasswordSession.login({\n   *     service: 'https://bsky.social',\n   *     identifier: 'alice.bsky.social',\n   *     password: 'xxxx',\n   *   })\n   * } catch (err) {\n   *   if (err instanceof LexAuthFactorError) {\n   *     const token = await promptUser('Enter 2FA code:')\n   *     const session = await PasswordSession.login({\n   *       service: 'https://bsky.social',\n   *       identifier: 'alice.bsky.social',\n   *       password: 'xxxx',\n   *       authFactorToken: token,\n   *     })\n   *   }\n   * }\n   * ```\n   */\n  static async login(\n    input: string | URL | LoginOptions,\n  ): Promise<PasswordSession> {\n    const {\n      service,\n      identifier,\n      password,\n      allowTakendown,\n      authFactorToken,\n      ...options\n    } =\n      typeof input === 'string' || input instanceof URL\n        ? parseLoginUrl(input)\n        : input\n\n    const xrpcAgent = buildAgent({\n      service,\n      fetch: options.fetch,\n    })\n\n    const response = await xrpcSafe(\n      xrpcAgent,\n      com.atproto.server.createSession.main,\n      { body: { identifier, password, allowTakendown, authFactorToken } },\n    )\n\n    if (!response.success) {\n      if (response.error === 'AuthFactorTokenRequired') {\n        throw new LexAuthFactorError(response)\n      }\n      throw response.reason\n    }\n\n    const data: SessionData = {\n      ...response.body,\n      service: String(service),\n    }\n\n    const agent = new PasswordSession(data, options)\n    await options.onUpdated?.call(agent, data)\n    return agent\n  }\n\n  /**\n   * Resume an existing session, ensuring it is still valid by refreshing it.\n   * Any error thrown here indicates that the session is definitely no longer\n   * valid. Network errors will be propagated through the\n   * {@link PasswordSessionOptions.onUpdateFailure} hook, and not re-thrown\n   * here. This means that a resolved promise does not necessarily indicate a\n   * valid session, only that it's refresh did not definitively fail.\n   *\n   * This is the same as calling {@link PasswordSession.refresh} after\n   * constructing the {@link PasswordSession} manually.\n   *\n   * @throws If, and only if, the session is definitely no longer valid.\n   */\n  static async resume(\n    data: SessionData,\n    options: PasswordSessionOptions,\n  ): Promise<PasswordSession> {\n    const agent = new PasswordSession(data, options)\n    await agent.refresh()\n    return agent\n  }\n\n  /**\n   * Delete a session without having to {@link resume resume()} it first, or\n   * provide hooks.\n   *\n   * @throws In case of unexpected error (network issue, server down, etc)\n   * meaning that the session may still be valid.\n   */\n  static async delete(\n    data: SessionData,\n    options?: PasswordSessionOptions,\n  ): Promise<void> {\n    const agent = new PasswordSession(data, options)\n    await agent.logout()\n  }\n}\n\nfunction fetchUrl(sessionData: SessionData, path: string): URL {\n  const pdsUrl = extractPdsUrl(sessionData.didDoc)\n  return new URL(path, pdsUrl ?? sessionData.service)\n}\n\nfunction parseLoginUrl(input: string | URL): LoginOptions {\n  const url = typeof input === 'string' ? new URL(input) : input\n  if (url.pathname !== '/') {\n    throw new TypeError('Invalid login URL: unexpected pathname')\n  }\n  if (url.hash) {\n    throw new TypeError('Invalid login URL: unexpected hash')\n  }\n  if (url.search) {\n    throw new TypeError('Invalid login URL: unexpected search parameters')\n  }\n  if (!url.username || !url.password) {\n    throw new TypeError('Invalid login URL: missing identifier or password')\n  }\n  return {\n    service: url.origin,\n    identifier: url.username,\n    password: url.password,\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-password-session",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "license": "MIT",
   "description": "Password based client authentication for AT Lexicons",
   "keywords": [
@@ -36,13 +36,13 @@
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-schema": "^0.0.13",
-    "@atproto/lex-client": "^0.0.13"
+    "@atproto/lex-client": "^0.0.15",
+    "@atproto/lex-schema": "^0.0.14"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-builder": "^0.0.16",
-    "@atproto/lex-server": "^0.0.10"
+    "@atproto/lex-builder": "^0.0.17",
+    "@atproto/lex-server": "^0.0.12"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

package/src/error.ts

@@ -47,14 +47,4 @@ export class LexAuthFactorError extends LexError {
   constructor(readonly cause: XrpcFailure) {
     super(cause.error, cause.message ?? 'Auth factor token required', { cause })
   }
-
-  /**
-   * Converts this error to an HTTP Response.
-   *
-   * @returns A 500 Internal Server Error response (2FA errors should not be
-   * exposed to end users in server contexts)
-   */
-  override toResponse(): Response {
-    return Response.json({ error: 'InternalServerError' }, { status: 500 })
-  }
 }

package/src/password-session.ts

@@ -42,6 +42,14 @@ export type SessionData = com.atproto.server.createSession.$OutputBody & {
   service: string
 }
 
+export type LoginOptions = PasswordSessionOptions & {
+  service: string | URL
+  identifier: string
+  password: string
+  allowTakendown?: boolean
+  authFactorToken?: string
+}
+
 export type PasswordSessionOptions = {
   /**
    * Custom fetch implementation to use for network requests
@@ -143,7 +151,7 @@ export type PasswordSessionOptions = {
  *
  * @implements {Agent}
  */
-export class PasswordSession implements Agent {
+export class PasswordSession implements Agent, AsyncDisposable {
   /**
    * Internal {@link Agent} used for session management towards the
    * authentication service only.
@@ -308,7 +316,7 @@ export class PasswordSession implements Agent {
         { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },
       )
 
-      if (!response.success && response.matchesSchema()) {
+      if (!response.success && response.matchesSchemaErrors()) {
         // Expected errors that indicate the session is no longer valid
         await this.options.onDeleted?.call(this, sessionData)
 
@@ -318,10 +326,6 @@ export class PasswordSession implements Agent {
       }
 
       if (!response.success) {
-        response.error
-        if (response.matchesSchema()) {
-          response.error
-        }
         // We failed to refresh the token, assume the session might still be
         // valid by returning the existing session.
         await this.options.onUpdateFailure?.call(this, sessionData, response)
@@ -385,7 +389,7 @@ export class PasswordSession implements Agent {
         { headers: { Authorization: `Bearer ${sessionData.refreshJwt}` } },
       )
 
-      if (result.success || result.matchesSchema()) {
+      if (result.success || result.matchesSchemaErrors()) {
         await this.options.onDeleted?.call(this, sessionData)
 
         // Update the session promise to a rejected state
@@ -415,6 +419,10 @@ export class PasswordSession implements Agent {
     )
   }
 
+  async [Symbol.asyncDispose]() {
+    await this.logout()
+  }
+
   /**
    * Creates a new account and returns an authenticated session.
    *
@@ -489,23 +497,42 @@ export class PasswordSession implements Agent {
    * @throws {LexAuthFactorError} If the server requires a 2FA token
    * @throws If authentication fails (invalid credentials, etc.)
    *
-   * @example Basic login with app password
+   * **Basic login with app password in script**
+   * @example
+   * ```ts
+   * // .env
+   * // APP_PASSWORD_CREDENTIALS="https://<handle>:<app-password>@<pds-hosting-provider>"
+   *
+   * // Make sure to dispose (or logout) the session when done to avoid leaking
+   * // resources and leaving orphaned sessions on the server
+   * await using session = await PasswordSession.login(process.env.APP_PASSWORD_CREDENTIALS)
+   *
+   * // Use session to make authenticated requests
+   * ```
+   *
+   * **Basic login with user password (not recommended!!!)**
+   * @example
    * ```ts
    * const session = await PasswordSession.login({
    *   service: 'https://bsky.social',
    *   identifier: 'alice.bsky.social',
-   *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+   *   password: 'xxxx',
    *   onUpdated: (data) => saveToStorage(data),
+   *   onDeleted: (data) => clearStorage(data.did),
    * })
+   *
+   * // Next time, use resume with the persisted session data to avoid storing
+   * // user credentials.
    * ```
    *
-   * @example Handling 2FA requirement
+   * **Handling 2FA requirement**
+   * @example
    * ```ts
    * try {
    *   const session = await PasswordSession.login({
    *     service: 'https://bsky.social',
    *     identifier: 'alice.bsky.social',
-   *     password: 'xxxx-xxxx-xxxx-xxxx',
+   *     password: 'xxxx',
    *   })
    * } catch (err) {
    *   if (err instanceof LexAuthFactorError) {
@@ -513,27 +540,28 @@ export class PasswordSession implements Agent {
    *     const session = await PasswordSession.login({
    *       service: 'https://bsky.social',
    *       identifier: 'alice.bsky.social',
-   *       password: 'xxxx-xxxx-xxxx-xxxx',
+   *       password: 'xxxx',
    *       authFactorToken: token,
    *     })
    *   }
    * }
    * ```
    */
-  static async login({
-    service,
-    identifier,
-    password,
-    allowTakendown,
-    authFactorToken,
-    ...options
-  }: PasswordSessionOptions & {
-    service: string | URL
-    identifier: string
-    password: string
-    allowTakendown?: boolean
-    authFactorToken?: string
-  }): Promise<PasswordSession> {
+  static async login(
+    input: string | URL | LoginOptions,
+  ): Promise<PasswordSession> {
+    const {
+      service,
+      identifier,
+      password,
+      allowTakendown,
+      authFactorToken,
+      ...options
+    } =
+      typeof input === 'string' || input instanceof URL
+        ? parseLoginUrl(input)
+        : input
+
     const xrpcAgent = buildAgent({
       service,
       fetch: options.fetch,
@@ -604,3 +632,24 @@ function fetchUrl(sessionData: SessionData, path: string): URL {
   const pdsUrl = extractPdsUrl(sessionData.didDoc)
   return new URL(path, pdsUrl ?? sessionData.service)
 }
+
+function parseLoginUrl(input: string | URL): LoginOptions {
+  const url = typeof input === 'string' ? new URL(input) : input
+  if (url.pathname !== '/') {
+    throw new TypeError('Invalid login URL: unexpected pathname')
+  }
+  if (url.hash) {
+    throw new TypeError('Invalid login URL: unexpected hash')
+  }
+  if (url.search) {
+    throw new TypeError('Invalid login URL: unexpected search parameters')
+  }
+  if (!url.username || !url.password) {
+    throw new TypeError('Invalid login URL: missing identifier or password')
+  }
+  return {
+    service: url.origin,
+    identifier: url.username,
+    password: url.password,
+  }
+}