@atproto/lex-password-session 0.0.4 → 0.0.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atproto/lex-password-session",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "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.11",
-    "@atproto/lex-schema": "^0.0.11"
+    "@atproto/lex-schema": "^0.0.13",
+    "@atproto/lex-client": "^0.0.13"
   },
   "devDependencies": {
     "vitest": "^4.0.16",
-    "@atproto/lex-builder": "^0.0.13",
-    "@atproto/lex-server": "^0.0.8"
+    "@atproto/lex-builder": "^0.0.16",
+    "@atproto/lex-server": "^0.0.10"
   },
   "scripts": {
     "prebuild": "node ./scripts/lex-build.mjs",

package/src/error.ts

@@ -1,12 +1,59 @@
 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'
 
+  /**
+   * 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 })
   }

package/src/lexicons/com/atproto/server/createAccount.defs.ts

@@ -23,14 +23,14 @@ const main =
       verificationPhone: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
       password: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
       recoveryKey: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
-      plcOp: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.unknownObject()),
+      plcOp: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.lexMap()),
     }),
     /*#__PURE__*/ l.jsonPayload({
       accessJwt: /*#__PURE__*/ l.string(),
       refreshJwt: /*#__PURE__*/ l.string(),
       handle: /*#__PURE__*/ l.string({ format: 'handle' }),
       did: /*#__PURE__*/ l.string({ format: 'did' }),
-      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.unknownObject()),
+      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.lexMap()),
     }),
     [
       'InvalidHandle',
@@ -44,11 +44,17 @@ const main =
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/server/createSession.defs.ts

@@ -25,22 +25,32 @@ const main =
       refreshJwt: /*#__PURE__*/ l.string(),
       handle: /*#__PURE__*/ l.string({ format: 'handle' }),
       did: /*#__PURE__*/ l.string({ format: 'did' }),
-      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.unknownObject()),
+      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.lexMap()),
       email: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
       emailConfirmed: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
       emailAuthFactor: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
       active: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
-      status: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+      status: /*#__PURE__*/ l.optional(
+        /*#__PURE__*/ l.string<{
+          knownValues: ['takendown', 'suspended', 'deactivated']
+        }>(),
+      ),
     }),
     ['AccountTakedown', 'AuthFactorTokenRequired'],
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/server/deleteSession.defs.ts

@@ -20,11 +20,17 @@ const main =
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/lexicons/com/atproto/server/getSession.defs.ts

@@ -17,19 +17,26 @@ const main =
     /*#__PURE__*/ l.jsonPayload({
       handle: /*#__PURE__*/ l.string({ format: 'handle' }),
       did: /*#__PURE__*/ l.string({ format: 'did' }),
-      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.unknownObject()),
+      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.lexMap()),
       email: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
       emailConfirmed: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
       emailAuthFactor: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
       active: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
-      status: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+      status: /*#__PURE__*/ l.optional(
+        /*#__PURE__*/ l.string<{
+          knownValues: ['takendown', 'suspended', 'deactivated']
+        }>(),
+      ),
     }),
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = main.parameters,

package/src/lexicons/com/atproto/server/refreshSession.defs.ts

@@ -20,22 +20,32 @@ const main =
       refreshJwt: /*#__PURE__*/ l.string(),
       handle: /*#__PURE__*/ l.string({ format: 'handle' }),
       did: /*#__PURE__*/ l.string({ format: 'did' }),
-      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.unknownObject()),
+      didDoc: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.lexMap()),
       email: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
       emailConfirmed: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
       emailAuthFactor: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
       active: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.boolean()),
-      status: /*#__PURE__*/ l.optional(/*#__PURE__*/ l.string()),
+      status: /*#__PURE__*/ l.optional(
+        /*#__PURE__*/ l.string<{
+          knownValues: ['takendown', 'suspended', 'deactivated']
+        }>(),
+      ),
     }),
     ['AccountTakedown', 'InvalidToken', 'ExpiredToken'],
   )
 export { main }
 
-export type Params = l.InferMethodParams<typeof main>
-export type Input = l.InferMethodInput<typeof main>
-export type InputBody = l.InferMethodInputBody<typeof main>
-export type Output = l.InferMethodOutput<typeof main>
-export type OutputBody = l.InferMethodOutputBody<typeof main>
+export type $Params = l.InferMethodParams<typeof main>
+export type $Input<B = l.BinaryData> = l.InferMethodInput<typeof main, B>
+export type $InputBody<B = l.BinaryData> = l.InferMethodInputBody<
+  typeof main,
+  B
+>
+export type $Output<B = l.BinaryData> = l.InferMethodOutput<typeof main, B>
+export type $OutputBody<B = l.BinaryData> = l.InferMethodOutputBody<
+  typeof main,
+  B
+>
 
 export const $lxm = /*#__PURE__*/ main.nsid,
   $params = /*#__PURE__*/ main.parameters,

package/src/password-session.test.ts

@@ -62,7 +62,7 @@ describe(PasswordSession, () => {
       .add(com.atproto.server.createSession, async ({ input }) => {
         const session = await authVerifier.create(input.body)
 
-        const body: com.atproto.server.createSession.OutputBody = {
+        const body: com.atproto.server.createSession.$OutputBody = {
           accessJwt: session.accessJwt,
           refreshJwt: session.refreshJwt,
 
@@ -86,7 +86,7 @@ describe(PasswordSession, () => {
       .add(com.atproto.server.getSession, {
         auth: authVerifier.accessStrategy,
         handler: async ({ credentials: { session } }) => {
-          const body: com.atproto.server.getSession.OutputBody = {
+          const body: com.atproto.server.getSession.$OutputBody = {
             did: session.did,
             didDoc: {
               '@context': 'https://w3.org/ns/did/v1',
@@ -117,7 +117,7 @@ describe(PasswordSession, () => {
 
           // Note, we omit email and didDoc here to test that they are properly
           // fetched via getSession in the agent
-          const body: com.atproto.server.refreshSession.OutputBody = {
+          const body: com.atproto.server.refreshSession.$OutputBody = {
             accessJwt: session.accessJwt,
             refreshJwt: session.refreshJwt,
 

package/src/password-session.ts

@@ -9,15 +9,36 @@ import { LexAuthFactorError } from './error.js'
 import { com } from './lexicons/index.js'
 import { extractPdsUrl, extractXrpcErrorCode } from './util.js'
 
+/**
+ * Represents a failure response when refreshing a session.
+ *
+ * This type captures the possible error responses from
+ * `com.atproto.server.refreshSession`, including both expected errors
+ * (e.g., invalid/expired refresh token) and unexpected errors (e.g., network issues).
+ */
 export type RefreshFailure = XrpcFailure<
   typeof com.atproto.server.refreshSession.main
 >
 
+/**
+ * Represents a failure response when deleting a session.
+ *
+ * This type captures the possible error responses from
+ * `com.atproto.server.deleteSession`, including both expected errors
+ * and unexpected errors (e.g., network issues, server unavailability).
+ */
 export type DeleteFailure = XrpcFailure<
   typeof com.atproto.server.deleteSession.main
 >
 
-export type SessionData = com.atproto.server.createSession.OutputBody & {
+/**
+ * Persisted session data containing authentication credentials and service information.
+ *
+ * This type extends the response from `com.atproto.server.createSession` with the
+ * service URL used for authentication. Store this data securely to resume sessions
+ * later without re-authenticating.
+ */
+export type SessionData = com.atproto.server.createSession.$OutputBody & {
   service: string
 }
 
@@ -84,6 +105,44 @@ export type PasswordSessionOptions = {
   ) => void | Promise<void>
 }
 
+/**
+ * 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}
+ */
 export class PasswordSession implements Agent {
   /**
    * Internal {@link Agent} used for session management towards the
@@ -107,23 +166,59 @@ export class PasswordSession implements Agent {
     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 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(): boolean {
     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: string, init: RequestInit): Promise<Response> {
     const headers = new Headers(init.headers)
     if (headers.has('authorization')) {
@@ -190,6 +285,21 @@ export class PasswordSession implements Agent {
     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(): Promise<SessionData> {
     this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
       const response = await xrpcSafe(
@@ -250,6 +360,21 @@ export class PasswordSession implements Agent {
     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(): Promise<void> {
     let reason: DeleteFailure | null = null
 
@@ -290,8 +415,34 @@ export class PasswordSession implements Agent {
     )
   }
 
+  /**
+   * Creates a new account and returns an authenticated session.
+   *
+   * 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
+   * ```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: com.atproto.server.createAccount.InputBody,
+    body: com.atproto.server.createAccount.$InputBody,
     {
       service,
       headers,
@@ -318,29 +469,53 @@ export class PasswordSession implements Agent {
   }
 
   /**
-   * @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 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.
    *
-   * @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.
+   * **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 Handling 2FA errors
+   * @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.login({
-   *     service: 'https://example.com',
-   *     identifier: 'alice',
-   *     password: 'correct horse battery staple',
+   *     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,
+   *     })
    *   }
    * }
    * ```