@atproto/lex-password-session 0.0.3 → 0.0.5

package/dist/password-session.js

@@ -5,6 +5,44 @@ const lex_client_1 = require("@atproto/lex-client");
 const error_js_1 = require("./error.js");
 const index_js_1 = require("./lexicons/index.js");
 const util_js_1 = require("./util.js");
+/**
+ * Password-based authentication session for AT Protocol services.
+ *
+ * This class provides session management for CLI tools, scripts, and bots that
+ * need to authenticate with AT Protocol services using password credentials.
+ * It implements the {@link Agent} interface, allowing it to be used directly
+ * with AT Protocol clients.
+ *
+ * **Security Warning:** It is strongly recommended to use app passwords instead
+ * of main account credentials. App passwords provide limited access and can be
+ * revoked independently without compromising your main account. For browser-based
+ * applications, use OAuth-based authentication instead.
+ *
+ * @example Basic usage with app password
+ * ```ts
+ * const session = await PasswordSession.login({
+ *   service: 'https://bsky.social',
+ *   identifier: 'alice.bsky.social',
+ *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+ *   onUpdated: (data) => saveToStorage(data),
+ *   onDeleted: (data) => clearStorage(data.did),
+ * })
+ *
+ * const client = new Client(session)
+ * // Use client to make authenticated requests
+ * ```
+ *
+ * @example Resuming a persisted session
+ * ```ts
+ * const savedData = JSON.parse(fs.readFileSync('session.json', 'utf8'))
+ * const session = await PasswordSession.resume(savedData, {
+ *   onUpdated: (data) => saveToStorage(data),
+ *   onDeleted: (data) => clearStorage(data.did),
+ * })
+ * ```
+ *
+ * @implements {Agent}
+ */
 class PasswordSession {
     options;
     /**
@@ -14,7 +52,7 @@ class PasswordSession {
     #serviceAgent;
     #sessionData;
     #sessionPromise;
-    constructor(sessionData, options) {
+    constructor(sessionData, options = {}) {
         this.options = options;
         this.#serviceAgent = (0, lex_client_1.buildAgent)({
             service: sessionData.service,
@@ -23,20 +61,56 @@ class PasswordSession {
         this.#sessionData = sessionData;
         this.#sessionPromise = Promise.resolve(this.#sessionData);
     }
+    /**
+     * The DID (Decentralized Identifier) of the authenticated account.
+     *
+     * @throws {Error} If the session has been destroyed (logged out).
+     */
     get did() {
         return this.session.did;
     }
+    /**
+     * The handle (username) of the authenticated account.
+     *
+     * @throws {Error} If the session has been destroyed (logged out).
+     */
     get handle() {
         return this.session.handle;
     }
+    /**
+     * The current session data containing authentication credentials.
+     *
+     * @throws {Error} If the session has been destroyed (logged out).
+     */
     get session() {
         if (this.#sessionData)
             return this.#sessionData;
-        throw new lex_client_1.XrpcError('AuthenticationRequired', 'Logged out');
+        throw new Error('Logged out');
     }
+    /**
+     * Whether this session has been destroyed (logged out).
+     *
+     * Once destroyed, this session instance can no longer be used for
+     * authenticated requests. Create a new session via {@link PasswordSession.login}
+     * or {@link PasswordSession.resume}.
+     */
     get destroyed() {
         return this.#sessionData === null;
     }
+    /**
+     * Handles authenticated fetch requests to the user's PDS.
+     *
+     * This method implements the {@link Agent} interface and is called by
+     * AT Protocol clients to make authenticated requests. It automatically:
+     * - Adds the access token to request headers
+     * - Detects expired tokens and triggers refresh
+     * - Retries requests after successful token refresh
+     *
+     * @param path - The request path (will be resolved against the PDS URL)
+     * @param init - Standard fetch RequestInit options (headers, body, etc.)
+     * @returns The fetch Response from the PDS
+     * @throws {TypeError} If an 'authorization' header is already set in init
+     */
     async fetchHandler(path, init) {
         const headers = new Headers(init.headers);
         if (headers.has('authorization')) {
@@ -88,17 +162,36 @@ class PasswordSession {
         headers.set('authorization', `Bearer ${newSessionData.accessJwt}`);
         return fetch(fetchUrl(newSessionData, path), { ...init, headers });
     }
+    /**
+     * Refreshes the session by obtaining new access and refresh tokens.
+     *
+     * This method is automatically called by {@link fetchHandler} when the access
+     * token expires. You can also call it manually to proactively refresh tokens.
+     *
+     * On success, the {@link PasswordSessionOptions.onUpdated} callback is invoked
+     * with the new session data. On expected failures (invalid session), the
+     * {@link PasswordSessionOptions.onDeleted} callback is invoked. On unexpected
+     * failures (network issues), the {@link PasswordSessionOptions.onUpdateFailure}
+     * callback is invoked and the existing session data is preserved.
+     *
+     * @returns The refreshed session data
+     * @throws {RefreshFailure} If the session is no longer valid (triggers onDeleted)
+     */
     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()) {
                 // Expected errors that indicate the session is no longer valid
-                await this.options.onDeleted.call(this, sessionData);
+                await this.options.onDeleted?.call(this, sessionData);
                 // Update the session promise to a rejected state
                 this.#sessionData = null;
                 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);
@@ -120,20 +213,35 @@ class PasswordSession {
                 ...data,
                 service: sessionData.service,
             };
-            await this.options.onUpdated.call(this, newSession);
+            await this.options.onUpdated?.call(this, newSession);
             return (this.#sessionData = newSession);
         });
         return this.#sessionPromise;
     }
+    /**
+     * Logs out by deleting the session on the server.
+     *
+     * This method invalidates both the access and refresh tokens on the server,
+     * preventing any further use of this session. After successful logout, the
+     * session is marked as destroyed and the {@link PasswordSessionOptions.onDeleted}
+     * callback is invoked.
+     *
+     * If the logout request fails due to network issues or server unavailability,
+     * the {@link PasswordSessionOptions.onDeleteFailure} callback is invoked and
+     * the session remains active locally. In this case, you should retry the
+     * logout later to ensure the session is properly invalidated on the server.
+     *
+     * @throws {DeleteFailure} If the logout request fails due to unexpected errors
+     */
     async logout() {
         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()) {
-                await this.options.onDeleted.call(this, sessionData);
+                await this.options.onDeleted?.call(this, sessionData);
                 // Update the session promise to a rejected state
                 this.#sessionData = null;
-                throw new lex_client_1.XrpcError('AuthenticationRequired', 'Logged out');
+                throw new Error('Logged out');
             }
             else {
                 // Capture the reason for the failure to re-throw in the outer promise
@@ -153,34 +261,94 @@ class PasswordSession {
         });
     }
     /**
-     * @note It is **not** recommended to use {@link PasswordSession} with main
-     * account credentials. Instead, it is strongly advised to use OAuth based
-     * authentication for main username/password credentials and use
-     * {@link PasswordSession} with an app-password, for bots, scripts, or similar
-     * use-cases.
+     * Creates a new account and returns an authenticated session.
      *
-     * @throws If unable to create a session. In particular, if the server
-     * requires a 2FA token, a {@link XrpcResponseError} with the
-     * `AuthFactorTokenRequired` error code will be thrown.
+     * This static method registers a new account on the specified service and
+     * automatically creates an authenticated session for it.
      *
+     * @param body - Account creation parameters (handle, email, password, etc.)
+     * @param options - Session options including the service URL
+     * @returns A new PasswordSession for the created account
+     * @throws If account creation fails (e.g., handle taken, invalid invite code)
      *
-     * @example Handling 2FA errors
+     * @example
+     * ```ts
+     * const session = await PasswordSession.createAccount(
+     *   {
+     *     handle: 'alice.bsky.social',
+     *     email: 'alice@example.com',
+     *     password: 'secure-password',
+     *   },
+     *   {
+     *     service: 'https://bsky.social',
+     *     onUpdated: (data) => saveToStorage(data),
+     *   }
+     * )
+     * ```
+     */
+    static async createAccount(body, { service, headers, ...options }) {
+        const response = await (0, lex_client_1.xrpc)((0, lex_client_1.buildAgent)({ service, headers, fetch: options.fetch }), index_js_1.com.atproto.server.createAccount.main, { body });
+        const data = {
+            ...response.body,
+            service: String(service),
+        };
+        const agent = new PasswordSession(data, options);
+        await options.onUpdated?.call(agent, data);
+        return agent;
+    }
+    /**
+     * Creates a new authenticated session using password credentials.
+     *
+     * This static method authenticates with the specified service and returns
+     * a new PasswordSession instance that can be used for authenticated requests.
+     *
+     * **Security Warning:** It is strongly recommended to use app passwords instead
+     * of main account credentials. App passwords can be created in your account
+     * settings and provide limited access that can be revoked independently. For
+     * browser-based applications, use OAuth-based authentication instead.
+     *
+     * @param options - Login options including service URL, identifier, and password
+     * @param options.service - The AT Protocol service URL (e.g., 'https://bsky.social')
+     * @param options.identifier - The user's handle or DID
+     * @param options.password - The user's password or app password
+     * @param options.allowTakendown - If true, allow login to takendown accounts
+     * @param options.authFactorToken - 2FA token if required by the server
+     * @returns A new authenticated PasswordSession
+     * @throws {LexAuthFactorError} If the server requires a 2FA token
+     * @throws If authentication fails (invalid credentials, etc.)
      *
+     * @example Basic login with app password
+     * ```ts
+     * const session = await PasswordSession.login({
+     *   service: 'https://bsky.social',
+     *   identifier: 'alice.bsky.social',
+     *   password: 'xxxx-xxxx-xxxx-xxxx', // App password
+     *   onUpdated: (data) => saveToStorage(data),
+     * })
+     * ```
+     *
+     * @example Handling 2FA requirement
      * ```ts
      * try {
-     *   const session = await PasswordSession.create({
-     *     service: 'https://example.com',
-     *     identifier: 'alice',
-     *     password: 'correct horse battery staple',
+     *   const session = await PasswordSession.login({
+     *     service: 'https://bsky.social',
+     *     identifier: 'alice.bsky.social',
+     *     password: 'xxxx-xxxx-xxxx-xxxx',
      *   })
      * } catch (err) {
-     *   if (err instanceof XrpcResponseError && err.error === 'AuthFactorTokenRequired') {
-     *     // Prompt user for 2FA token and re-attempt session creation
+     *   if (err instanceof LexAuthFactorError) {
+     *     const token = await promptUser('Enter 2FA code:')
+     *     const session = await PasswordSession.login({
+     *       service: 'https://bsky.social',
+     *       identifier: 'alice.bsky.social',
+     *       password: 'xxxx-xxxx-xxxx-xxxx',
+     *       authFactorToken: token,
+     *     })
      *   }
      * }
      * ```
      */
-    static async create({ service, identifier, password, allowTakendown, authFactorToken, ...options }) {
+    static async login({ service, identifier, password, allowTakendown, authFactorToken, ...options }) {
         const xrpcAgent = (0, lex_client_1.buildAgent)({
             service,
             fetch: options.fetch,
@@ -197,7 +365,7 @@ class PasswordSession {
             service: String(service),
         };
         const agent = new PasswordSession(data, options);
-        await options.onUpdated.call(agent, data);
+        await options.onUpdated?.call(agent, data);
         return agent;
     }
     /**
@@ -226,11 +394,7 @@ class PasswordSession {
      * meaning that the session may still be valid.
      */
     static async delete(data, options) {
-        const agent = new PasswordSession(data, {
-            ...options,
-            onUpdated: options?.onUpdated ?? util_js_1.noop,
-            onDeleted: options?.onDeleted ?? util_js_1.noop,
-        });
+        const agent = new PasswordSession(data, options);
         await agent.logout();
     }
 }

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  XrpcError,\n  XrpcFailure,\n  buildAgent,\n  xrpcSafe,\n} from '@atproto/lex-client'\nimport { LexAuthFactorError } from './error.js'\nimport { com } from './lexicons/index.js'\nimport { extractPdsUrl, extractXrpcErrorCode, noop } from './util.js'\n\nexport type RefreshFailure = XrpcFailure<\n  typeof com.atproto.server.refreshSession.main\n>\n\nexport type DeleteFailure = XrpcFailure<\n  typeof com.atproto.server.deleteSession.main\n>\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\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  get did() {\n    return this.session.did\n  }\n\n  get handle() {\n    return this.session.handle\n  }\n\n  get session() {\n    if (this.#sessionData) return this.#sessionData\n    throw new XrpcError('AuthenticationRequired', 'Logged out')\n  }\n\n  get destroyed(): boolean {\n    return this.#sessionData === null\n  }\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  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        // 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  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 XrpcError('AuthenticationRequired', '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   * @note It is **not** recommended to use {@link PasswordSession} with main\n   * account credentials. Instead, it is strongly advised to use OAuth based\n   * authentication for main username/password credentials and use\n   * {@link PasswordSession} with an app-password, for bots, scripts, or similar\n   * use-cases.\n   *\n   * @throws If unable to create a session. In particular, if the server\n   * requires a 2FA token, a {@link XrpcResponseError} with the\n   * `AuthFactorTokenRequired` error code will be thrown.\n   *\n   *\n   * @example Handling 2FA errors\n   *\n   * ```ts\n   * try {\n   *   const session = await PasswordSession.create({\n   *     service: 'https://example.com',\n   *     identifier: 'alice',\n   *     password: 'correct horse battery staple',\n   *   })\n   * } catch (err) {\n   *   if (err instanceof XrpcResponseError && err.error === 'AuthFactorTokenRequired') {\n   *     // Prompt user for 2FA token and re-attempt session creation\n   *   }\n   * }\n   * ```\n   */\n  static async create({\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?: Partial<PasswordSessionOptions>,\n  ): Promise<void> {\n    const agent = new PasswordSession(data, {\n      ...options,\n      onUpdated: options?.onUpdated ?? noop,\n      onDeleted: options?.onDeleted ?? noop,\n    })\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 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"]}

package/dist/util.d.ts

@@ -1,5 +1,4 @@
 import { LexMap } from '@atproto/lex-client';
-export declare const noop: () => void;
 export declare function extractXrpcErrorCode(response: Response): Promise<string | null>;
 export declare function extractPdsUrl(didDoc?: LexMap): string | null;
 //# sourceMappingURL=util.d.ts.map

package/dist/util.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAY,MAAM,qBAAqB,CAAA;AAGtD,eAAO,MAAM,IAAI,YAAW,CAAA;AAE5B,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AA4BD,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5D"}
+{"version":3,"file":"util.d.ts","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAY,MAAM,qBAAqB,CAAA;AAGtD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAKxB;AA4BD,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAM5D"}

package/dist/util.js

@@ -1,16 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.noop = void 0;
 exports.extractXrpcErrorCode = extractXrpcErrorCode;
 exports.extractPdsUrl = extractPdsUrl;
 const lex_schema_1 = require("@atproto/lex-schema");
-const noop = () => { };
-exports.noop = noop;
 async function extractXrpcErrorCode(response) {
     const json = await peekJson(response, 10 * 1024); // Avoid reading large bodies
     if (json === undefined)
         return null;
-    if (!lex_schema_1.l.lexErrorData.matches(json))
+    if (!lex_schema_1.lexErrorDataSchema.matches(json))
         return null;
     return json.error;
 }

package/dist/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":";;;AAKA,oDAOC;AA4BD,sCAMC;AA7CD,oDAAuC;AAEhC,MAAM,IAAI,GAAG,GAAG,EAAE,GAAE,CAAC,CAAA;AAAf,QAAA,IAAI,QAAW;AAErB,KAAK,UAAU,oBAAoB,CACxC,QAAkB;IAElB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA,CAAC,6BAA6B;IAC9E,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACnC,IAAI,CAAC,cAAC,CAAC,YAAY,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAA;AACnB,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,QAAkB,EAClB,OAAO,GAAG,QAAQ;IAElB,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAA;IAClC,IAAI,IAAI,KAAK,kBAAkB;QAAE,OAAO,SAAS,CAAA;IACjD,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;IACtC,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,GAAG,OAAO;QAAE,OAAO,SAAS,CAAA;IAExD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAsB,CAAA;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,EAAE,OAAO,EAAY;IAC1C,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAClC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACvC,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,SAAS,WAAW,CAAC,EAAE,OAAO,EAAY;IACxC,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;AACzE,CAAC;AAED,SAAgB,aAAa,CAAC,MAAe;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAC5D,QAAQ,CAAE,OAAe,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CACzD,CAAA;IACD,MAAM,WAAW,GAAG,QAAQ,CAAE,UAAkB,EAAE,eAAe,CAAC,CAAA;IAClE,OAAO,WAAW,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAA;AACtE,CAAC;AAED,MAAM,QAAQ,GAAG,CAAI,CAAI,EAAE,EAAE,CAC3B,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAIvB,CAAA;AAEjB,MAAM,OAAO,GAAG,CAAI,CAAI,EAAE,EAAE,CAC1B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAIlB,CAAA","sourcesContent":["import { LexMap, LexValue } from '@atproto/lex-client'\nimport { l } from '@atproto/lex-schema'\n\nexport const noop = () => {}\n\nexport async function extractXrpcErrorCode(\n  response: Response,\n): Promise<string | null> {\n  const json = await peekJson(response, 10 * 1024) // Avoid reading large bodies\n  if (json === undefined) return null\n  if (!l.lexErrorData.matches(json)) return null\n  return json.error\n}\n\nasync function peekJson(\n  response: Response,\n  maxSize = Infinity,\n): Promise<undefined | LexValue> {\n  const type = extractType(response)\n  if (type !== 'application/json') return undefined\n  const length = extractLength(response)\n  if (length != null && length > maxSize) return undefined\n\n  try {\n    return (await response.clone().json()) as Promise<LexValue>\n  } catch {\n    return undefined\n  }\n}\n\nfunction extractLength({ headers }: Response) {\n  return headers.get('Content-Length')\n    ? Number(headers.get('Content-Length'))\n    : undefined\n}\n\nfunction extractType({ headers }: Response) {\n  return headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase()\n}\n\nexport function extractPdsUrl(didDoc?: LexMap): string | null {\n  const pdsService = ifArray(didDoc?.service)?.find((service) =>\n    ifString((service as any)?.id)?.endsWith('#atproto_pds'),\n  )\n  const pdsEndpoint = ifString((pdsService as any)?.serviceEndpoint)\n  return pdsEndpoint && URL.canParse(pdsEndpoint) ? pdsEndpoint : null\n}\n\nconst ifString = <T>(v: T) =>\n  (typeof v === 'string' ? v : undefined) as unknown extends T\n    ? undefined | string\n    : T extends string\n      ? string\n      : undefined\n\nconst ifArray = <T>(v: T) =>\n  (Array.isArray(v) ? v : undefined) as unknown extends T\n    ? undefined | unknown[]\n    : T extends unknown[]\n      ? Extract<T, unknown[]>\n      : undefined\n"]}
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":";;AAGA,oDAOC;AA4BD,sCAMC;AA3CD,oDAAwD;AAEjD,KAAK,UAAU,oBAAoB,CACxC,QAAkB;IAElB,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,IAAI,CAAC,CAAA,CAAC,6BAA6B;IAC9E,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACnC,IAAI,CAAC,+BAAkB,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAA;IAClD,OAAO,IAAI,CAAC,KAAK,CAAA;AACnB,CAAC;AAED,KAAK,UAAU,QAAQ,CACrB,QAAkB,EAClB,OAAO,GAAG,QAAQ;IAElB,MAAM,IAAI,GAAG,WAAW,CAAC,QAAQ,CAAC,CAAA;IAClC,IAAI,IAAI,KAAK,kBAAkB;QAAE,OAAO,SAAS,CAAA;IACjD,MAAM,MAAM,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAA;IACtC,IAAI,MAAM,IAAI,IAAI,IAAI,MAAM,GAAG,OAAO;QAAE,OAAO,SAAS,CAAA;IAExD,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,CAAsB,CAAA;IAC7D,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,EAAE,OAAO,EAAY;IAC1C,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC;QAClC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;QACvC,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED,SAAS,WAAW,CAAC,EAAE,OAAO,EAAY;IACxC,OAAO,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;AACzE,CAAC;AAED,SAAgB,aAAa,CAAC,MAAe;IAC3C,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAC5D,QAAQ,CAAE,OAAe,EAAE,EAAE,CAAC,EAAE,QAAQ,CAAC,cAAc,CAAC,CACzD,CAAA;IACD,MAAM,WAAW,GAAG,QAAQ,CAAE,UAAkB,EAAE,eAAe,CAAC,CAAA;IAClE,OAAO,WAAW,IAAI,GAAG,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAA;AACtE,CAAC;AAED,MAAM,QAAQ,GAAG,CAAI,CAAI,EAAE,EAAE,CAC3B,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAIvB,CAAA;AAEjB,MAAM,OAAO,GAAG,CAAI,CAAI,EAAE,EAAE,CAC1B,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAIlB,CAAA","sourcesContent":["import { LexMap, LexValue } from '@atproto/lex-client'\nimport { lexErrorDataSchema } from '@atproto/lex-schema'\n\nexport async function extractXrpcErrorCode(\n  response: Response,\n): Promise<string | null> {\n  const json = await peekJson(response, 10 * 1024) // Avoid reading large bodies\n  if (json === undefined) return null\n  if (!lexErrorDataSchema.matches(json)) return null\n  return json.error\n}\n\nasync function peekJson(\n  response: Response,\n  maxSize = Infinity,\n): Promise<undefined | LexValue> {\n  const type = extractType(response)\n  if (type !== 'application/json') return undefined\n  const length = extractLength(response)\n  if (length != null && length > maxSize) return undefined\n\n  try {\n    return (await response.clone().json()) as Promise<LexValue>\n  } catch {\n    return undefined\n  }\n}\n\nfunction extractLength({ headers }: Response) {\n  return headers.get('Content-Length')\n    ? Number(headers.get('Content-Length'))\n    : undefined\n}\n\nfunction extractType({ headers }: Response) {\n  return headers.get('Content-Type')?.split(';')[0]?.trim().toLowerCase()\n}\n\nexport function extractPdsUrl(didDoc?: LexMap): string | null {\n  const pdsService = ifArray(didDoc?.service)?.find((service) =>\n    ifString((service as any)?.id)?.endsWith('#atproto_pds'),\n  )\n  const pdsEndpoint = ifString((pdsService as any)?.serviceEndpoint)\n  return pdsEndpoint && URL.canParse(pdsEndpoint) ? pdsEndpoint : null\n}\n\nconst ifString = <T>(v: T) =>\n  (typeof v === 'string' ? v : undefined) as unknown extends T\n    ? undefined | string\n    : T extends string\n      ? string\n      : undefined\n\nconst ifArray = <T>(v: T) =>\n  (Array.isArray(v) ? v : undefined) as unknown extends T\n    ? undefined | unknown[]\n    : T extends unknown[]\n      ? Extract<T, unknown[]>\n      : undefined\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-password-session",
-  "version": "0.0.3",
+  "version": "0.0.5",
   "license": "MIT",
   "description": "Password based client authentication for AT Lexicons",
   "keywords": [
@@ -31,18 +31,18 @@
       "types": "./dist/index.d.ts",
       "browser": "./dist/index.js",
       "import": "./dist/index.js",
-      "require": "./dist/index.js"
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.8.1",
-    "@atproto/lex-client": "0.0.10",
-    "@atproto/lex-schema": "0.0.10"
+    "@atproto/lex-client": "^0.0.12",
+    "@atproto/lex-schema": "^0.0.12"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-builder": "0.0.12",
-    "@atproto/lex-server": "0.0.6"
+    "@atproto/lex-builder": "^0.0.14",
+    "@atproto/lex-server": "^0.0.9"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

package/src/error.ts

@@ -1,14 +1,60 @@
-import { LexError, XrpcResponseError } from '@atproto/lex-client'
-import { com } from './lexicons'
+import { LexError, XrpcFailure } from '@atproto/lex-client'
 
+/**
+ * Error thrown when two-factor authentication (2FA) is required.
+ *
+ * This error is thrown by {@link PasswordSession.login} when the server
+ * requires an additional authentication factor (e.g., email code). Catch this
+ * error to prompt the user for their 2FA code and retry the login with the
+ * `authFactorToken` parameter.
+ *
+ * @example Handling 2FA requirement
+ * ```ts
+ * import { PasswordSession, LexAuthFactorError } from '@atproto/lex-password-session'
+ *
+ * try {
+ *   const session = await PasswordSession.login({
+ *     service: 'https://bsky.social',
+ *     identifier: 'alice.bsky.social',
+ *     password: 'xxxx-xxxx-xxxx-xxxx',
+ *   })
+ * } catch (err) {
+ *   if (err instanceof LexAuthFactorError) {
+ *     // Prompt user for 2FA code
+ *     const token = await promptUser('Enter 2FA code from email:')
+ *
+ *     // Retry with the 2FA token
+ *     const session = await PasswordSession.login({
+ *       service: 'https://bsky.social',
+ *       identifier: 'alice.bsky.social',
+ *       password: 'xxxx-xxxx-xxxx-xxxx',
+ *       authFactorToken: token,
+ *     })
+ *   }
+ * }
+ * ```
+ *
+ * @extends LexError
+ */
 export class LexAuthFactorError extends LexError {
   name = 'LexAuthFactorError'
 
-  constructor(
-    readonly response: XrpcResponseError<
-      typeof com.atproto.server.createSession.main
-    >,
-  ) {
-    super(response.error, response.message, { cause: response.reason })
+  /**
+   * Creates a new LexAuthFactorError.
+   *
+   * @param cause - The underlying XRPC failure response from the server
+   */
+  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 })
   }
 }