@atcute/password-session 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2025 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,111 @@
+# @atcute/password-session
+
+password-based session management for AT Protocol services. manages access/refresh token lifecycle,
+automatic refresh on 401, and session persistence via callbacks.
+
+for browser-based applications, prefer OAuth-based authentication. when using password auth, use app
+passwords rather than main account credentials.
+
+```sh
+npm install @atcute/password-session @atcute/client @atcute/bluesky
+```
+
+## usage
+
+### login
+
+```ts
+import { Client, ok } from '@atcute/client';
+import { PasswordSession } from '@atcute/password-session';
+
+import type {} from '@atcute/bluesky';
+
+const session = await PasswordSession.login(
+	{ service: 'https://bsky.social', identifier: 'you.bsky.social', password: 'your-app-password' },
+	{
+		onUpdate(data) {
+			// called on login and token refresh — persist the session
+			localStorage.setItem('session', JSON.stringify(data));
+		},
+		onDelete(data) {
+			// called on logout or session invalidation — clean up
+			localStorage.removeItem('session');
+		},
+	},
+);
+
+const rpc = new Client({ handler: session });
+
+const data = await ok(rpc.get('com.atproto.server.getSession'));
+console.log(data.did);
+```
+
+### URL shorthand
+
+for bots and scripts, use URL shorthand with `await using` for automatic logout:
+
+```ts
+await using session = await PasswordSession.login('https://handle:app-pass@bsky.social');
+const rpc = new Client({ handler: session });
+```
+
+### resuming sessions
+
+resume a persisted session without re-entering credentials:
+
+```ts
+const saved = localStorage.getItem('session');
+if (saved) {
+	const session = await PasswordSession.resume(JSON.parse(saved), {
+		onUpdate(data) {
+			localStorage.setItem('session', JSON.stringify(data));
+		},
+		onDelete(data) {
+			localStorage.removeItem('session');
+		},
+	});
+	const rpc = new Client({ handler: session });
+}
+```
+
+### cached session with credential fallback
+
+for bots with both stored credentials and cached sessions, `login()` can try the cached session
+first and fall back to fresh authentication:
+
+```ts
+const session = await PasswordSession.login('https://handle:app-pass@bsky.social', {
+	session: loadFromDisk(),
+	onUpdate(data) {
+		saveToDisk(data);
+	},
+});
+```
+
+### lazy construction
+
+if you don't need upfront validation, construct directly — tokens refresh lazily on 401:
+
+```ts
+const session = new PasswordSession(savedData, { onUpdate, onDelete });
+const rpc = new Client({ handler: session });
+```
+
+### cleanup
+
+delete an orphaned session server-side without resuming:
+
+```ts
+await PasswordSession.delete(savedData);
+```
+
+## callbacks
+
+| callback          | when                                        | session state      |
+| ----------------- | ------------------------------------------- | ------------------ |
+| `onUpdate`        | login succeeds, tokens refresh successfully | active (updated)   |
+| `onUpdateFailure` | token refresh fails transiently (network)   | active (preserved) |
+| `onDelete`        | logout succeeds, session invalidated        | destroyed          |
+| `onDeleteFailure` | logout fails transiently (network)          | active (preserved) |
+
+all callbacks receive `this: PasswordSession` context and must not throw.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export * from './password-session.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export * from './password-session.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAC"}

package/dist/password-session.d.ts

@@ -0,0 +1,136 @@
+import { type FetchHandlerObject } from '@atcute/client';
+import type { Did } from '@atcute/lexicons';
+/** persistable session data */
+export interface PasswordSessionData {
+    /** authentication service URL */
+    service: string;
+    accessJwt: string;
+    refreshJwt: string;
+    handle: string;
+    did: Did;
+    /** PDS endpoint derived from DID document */
+    pdsUri?: string;
+    email?: string;
+    emailConfirmed?: boolean;
+    emailAuthFactor?: boolean;
+    active: boolean;
+    inactiveStatus?: string;
+}
+export interface PasswordSessionOptions {
+    /** custom fetch implementation */
+    fetch?: typeof fetch;
+    /**
+     * called when session is successfully created or refreshed with new
+     * credentials. use this to persist the updated session.
+     * receives `this: PasswordSession` context.
+     * @note must not throw
+     */
+    onUpdate?: (this: PasswordSession, data: PasswordSessionData) => void | Promise<void>;
+    /**
+     * called when a session refresh fails due to a transient error (network,
+     * server down). the session is preserved — consider retry logic.
+     * @note must not throw
+     */
+    onUpdateFailure?: (this: PasswordSession, data: PasswordSessionData, error: unknown) => void | Promise<void>;
+    /**
+     * called when the session is terminated — either explicit logout or
+     * server-side invalidation (expired/invalid refresh token).
+     * use this to clean up persisted session data.
+     * @note must not throw
+     */
+    onDelete?: (this: PasswordSession, data: PasswordSessionData) => void | Promise<void>;
+    /**
+     * called when logout network request fails due to a transient error.
+     * the session stays active locally so you can retry.
+     * @note must not throw
+     */
+    onDeleteFailure?: (this: PasswordSession, data: PasswordSessionData, error: unknown) => void | Promise<void>;
+}
+/** credentials for login */
+export interface PasswordSessionLoginCredentials {
+    service: string;
+    identifier: string;
+    password: string;
+    /** two-factor authentication code */
+    code?: string;
+    /** allow signing in even if the account has been taken down */
+    allowTakendown?: boolean;
+}
+/** options for login — second parameter, behavior config */
+export interface PasswordSessionLoginOptions extends PasswordSessionOptions {
+    /** cached session to try resuming before falling back to fresh login */
+    session?: PasswordSessionData;
+}
+/**
+ * password-based authentication session for AT Protocol services.
+ *
+ * manages access/refresh token lifecycle, automatic refresh on 401, and
+ * session persistence via callbacks. instances are always in an authenticated
+ * state — use the static factories for validated construction.
+ *
+ * for browser-based applications, prefer OAuth-based authentication instead.
+ * when using password auth, use app passwords rather than main account credentials.
+ */
+export declare class PasswordSession implements FetchHandlerObject, AsyncDisposable {
+    #private;
+    /**
+     * construct with existing session data. tokens refresh lazily on 401.
+     * use static `login()` or `resume()` for validated sessions.
+     * @param session existing session data
+     * @param options session options
+     */
+    constructor(session: PasswordSessionData, options?: PasswordSessionOptions);
+    /**
+     * account DID
+     * @throws if the session has been destroyed
+     */
+    get did(): Did;
+    /** whether this session has been destroyed (logged out) */
+    get destroyed(): boolean;
+    /**
+     * current session data — serialize this for persistence
+     * @throws if the session has been destroyed
+     */
+    get session(): PasswordSessionData;
+    /** URL to dispatch API requests to (PDS from DID doc, or service URL) */
+    get dispatchUrl(): string;
+    /**
+     * authenticate with credentials. optionally tries resuming a cached
+     * session first, falling back to fresh createSession on failure.
+     * @param credentials login credentials or URL shorthand (`https://handle:pass@service`)
+     * @param options login options
+     * @returns authenticated session
+     */
+    static login(credentials: PasswordSessionLoginCredentials | string | URL, options?: PasswordSessionLoginOptions): Promise<PasswordSession>;
+    /**
+     * resume from persisted session data. if the access token is still valid,
+     * returns immediately and refreshes metadata in the background.
+     * if expired, refreshes synchronously. throws only if the session is
+     * definitively invalid.
+     * @param session persisted session data
+     * @param options session options
+     * @returns resumed session
+     */
+    static resume(session: PasswordSessionData, options?: PasswordSessionOptions): Promise<PasswordSession>;
+    /**
+     * delete a session server-side without resuming it.
+     * useful for cleanup of orphaned sessions.
+     * @param session session data to delete
+     * @param options session options
+     */
+    static delete(session: PasswordSessionData, options?: PasswordSessionOptions): Promise<void>;
+    /** refresh the session tokens */
+    refresh(): Promise<void>;
+    /**
+     * sign out — invalidates session server-side.
+     * on success, the session is destroyed and `onDelete` is called.
+     * on transient failure (network), `onDeleteFailure` is called and
+     * the session stays active for retry.
+     * @throws on transient failure when the session couldn't be deleted
+     */
+    logout(): Promise<void>;
+    /** AsyncDisposable — calls `logout()` */
+    [Symbol.asyncDispose](): Promise<void>;
+    handle(pathname: string, init: RequestInit): Promise<Response>;
+}
+//# sourceMappingURL=password-session.d.ts.map

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

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

package/dist/password-session.js

@@ -0,0 +1,371 @@
+import { Client, ClientResponseError, isXRPCErrorPayload, ok, simpleFetchHandler, } from '@atcute/client';
+import { getPdsEndpoint } from '@atcute/identity';
+// #endregion
+// #region class
+/**
+ * password-based authentication session for AT Protocol services.
+ *
+ * manages access/refresh token lifecycle, automatic refresh on 401, and
+ * session persistence via callbacks. instances are always in an authenticated
+ * state — use the static factories for validated construction.
+ *
+ * for browser-based applications, prefer OAuth-based authentication instead.
+ * when using password auth, use app passwords rather than main account credentials.
+ */
+export class PasswordSession {
+    #sessionData;
+    #sessionPromise;
+    #server;
+    #fetch;
+    #onUpdate;
+    #onUpdateFailure;
+    #onDelete;
+    #onDeleteFailure;
+    /**
+     * construct with existing session data. tokens refresh lazily on 401.
+     * use static `login()` or `resume()` for validated sessions.
+     * @param session existing session data
+     * @param options session options
+     */
+    constructor(session, options = {}) {
+        this.#sessionData = session;
+        this.#sessionPromise = Promise.resolve(session);
+        this.#fetch = options.fetch ?? fetch;
+        this.#server = new Client({
+            handler: simpleFetchHandler({ service: session.service, fetch: this.#fetch }),
+        });
+        this.#onUpdate = options.onUpdate;
+        this.#onUpdateFailure = options.onUpdateFailure;
+        this.#onDelete = options.onDelete;
+        this.#onDeleteFailure = options.onDeleteFailure;
+    }
+    /**
+     * account DID
+     * @throws if the session has been destroyed
+     */
+    get did() {
+        return this.session.did;
+    }
+    /** whether this session has been destroyed (logged out) */
+    get destroyed() {
+        return this.#sessionData === null;
+    }
+    /**
+     * current session data — serialize this for persistence
+     * @throws if the session has been destroyed
+     */
+    get session() {
+        if (this.#sessionData) {
+            return this.#sessionData;
+        }
+        throw new Error(`session has been destroyed`);
+    }
+    /** URL to dispatch API requests to (PDS from DID doc, or service URL) */
+    get dispatchUrl() {
+        return this.session.pdsUri ?? this.session.service;
+    }
+    // --- static factories ---
+    /**
+     * authenticate with credentials. optionally tries resuming a cached
+     * session first, falling back to fresh createSession on failure.
+     * @param credentials login credentials or URL shorthand (`https://handle:pass@service`)
+     * @param options login options
+     * @returns authenticated session
+     */
+    static async login(credentials, options = {}) {
+        const creds = typeof credentials === 'string' || credentials instanceof URL
+            ? parseLoginUrl(credentials)
+            : credentials;
+        // try cached session first if provided
+        if (options.session) {
+            try {
+                return await PasswordSession.resume(options.session, options);
+            }
+            catch {
+                // fall through to fresh login
+            }
+        }
+        const _fetch = options.fetch ?? fetch;
+        const server = new Client({
+            handler: simpleFetchHandler({ service: creds.service, fetch: _fetch }),
+        });
+        const data = await ok(server.post('com.atproto.server.createSession', {
+            input: {
+                identifier: creds.identifier,
+                password: creds.password,
+                authFactorToken: creds.code,
+                allowTakendown: creds.allowTakendown,
+            },
+        }));
+        const sessionData = buildSessionData(creds.service, data);
+        const session = new PasswordSession(sessionData, options);
+        await options.onUpdate?.call(session, sessionData);
+        return session;
+    }
+    /**
+     * resume from persisted session data. if the access token is still valid,
+     * returns immediately and refreshes metadata in the background.
+     * if expired, refreshes synchronously. throws only if the session is
+     * definitively invalid.
+     * @param session persisted session data
+     * @param options session options
+     * @returns resumed session
+     */
+    static async resume(session, options = {}) {
+        const instance = new PasswordSession(session, options);
+        const now = Date.now() / 1_000 + 60 * 5;
+        const accessToken = decodeJwt(session.accessJwt);
+        if (now >= accessToken.exp) {
+            // access token expired or expiring soon, refresh synchronously
+            await instance.refresh();
+        }
+        else {
+            // access token still valid, fetch session metadata in background
+            instance.#refreshMetadata(session);
+        }
+        if (instance.destroyed) {
+            throw new ClientResponseError({ status: 401, data: { error: 'InvalidToken' } });
+        }
+        return instance;
+    }
+    /**
+     * delete a session server-side without resuming it.
+     * useful for cleanup of orphaned sessions.
+     * @param session session data to delete
+     * @param options session options
+     */
+    static async delete(session, options = {}) {
+        const instance = new PasswordSession(session, options);
+        await instance.logout();
+    }
+    // --- lifecycle ---
+    /** refresh the session tokens */
+    async refresh() {
+        await this.#refresh();
+    }
+    /**
+     * sign out — invalidates session server-side.
+     * on success, the session is destroyed and `onDelete` is called.
+     * on transient failure (network), `onDeleteFailure` is called and
+     * the session stays active for retry.
+     * @throws on transient failure when the session couldn't be deleted
+     */
+    async logout() {
+        let failure = null;
+        this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
+            const response = await this.#server.post('com.atproto.server.deleteSession', {
+                as: null,
+                headers: {
+                    authorization: `Bearer ${sessionData.refreshJwt}`,
+                },
+            });
+            if (!response.ok) {
+                const isExpected = response.status === 401 ||
+                    response.data.error === 'InvalidToken' ||
+                    response.data.error === 'ExpiredToken';
+                if (!isExpected) {
+                    // transient error — keep session alive
+                    failure = new ClientResponseError(response);
+                    await this.#onDeleteFailure?.(sessionData, failure);
+                    return sessionData;
+                }
+            }
+            // success or expected error → session is gone
+            await this.#onDelete?.(sessionData);
+            this.#sessionData = null;
+            throw new Error(`session has been destroyed`);
+        });
+        return this.#sessionPromise.then(() => {
+            // resolved means logout failed (transient error)
+            throw failure;
+        }, () => {
+            // rejected means session was destroyed (successful logout)
+        });
+    }
+    /** AsyncDisposable — calls `logout()` */
+    async [Symbol.asyncDispose]() {
+        await this.logout();
+    }
+    // --- FetchHandlerObject ---
+    async handle(pathname, init) {
+        const sessionPromise = this.#sessionPromise;
+        const sessionData = await sessionPromise;
+        const url = new URL(pathname, sessionData.pdsUri ?? sessionData.service);
+        const headers = new Headers(init.headers);
+        if (headers.has('authorization')) {
+            return (0, this.#fetch)(url, init);
+        }
+        headers.set('authorization', `Bearer ${sessionData.accessJwt}`);
+        const initialResponse = await (0, this.#fetch)(url, { ...init, headers });
+        if (initialResponse.status !== 401 && !(await isExpiredTokenResponse(initialResponse))) {
+            return initialResponse;
+        }
+        // refresh unless another call already started one
+        const refreshPromise = this.#sessionPromise === sessionPromise ? this.#refresh() : this.#sessionPromise;
+        const newSessionData = await refreshPromise.catch(() => null);
+        if (!newSessionData ||
+            newSessionData.accessJwt === sessionData.accessJwt ||
+            init.signal?.aborted ||
+            init.body instanceof ReadableStream) {
+            return initialResponse;
+        }
+        // cancel initial response to avoid resource leaks
+        if (!initialResponse.bodyUsed) {
+            await initialResponse.body?.cancel();
+        }
+        headers.set('authorization', `Bearer ${newSessionData.accessJwt}`);
+        return await (0, this.#fetch)(url, { ...init, headers });
+    }
+    // --- internal ---
+    #refresh() {
+        this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
+            const response = await this.#server.post('com.atproto.server.refreshSession', {
+                headers: {
+                    authorization: `Bearer ${sessionData.refreshJwt}`,
+                },
+            });
+            if (!response.ok) {
+                const isExpected = response.status === 401 ||
+                    response.data.error === 'ExpiredToken' ||
+                    response.data.error === 'InvalidToken';
+                if (isExpected) {
+                    await this.#onDelete?.(sessionData);
+                    this.#sessionData = null;
+                    throw new ClientResponseError(response);
+                }
+                // transient error — preserve session
+                await this.#onUpdateFailure?.(sessionData, new ClientResponseError(response));
+                return sessionData;
+            }
+            // DID must not change during refresh
+            if (response.data.did !== sessionData.did) {
+                await this.#onDelete?.(sessionData);
+                this.#sessionData = null;
+                throw new ClientResponseError({ status: 401, data: { error: 'InvalidToken' } });
+            }
+            const newSession = buildSessionData(sessionData.service, { ...sessionData, ...response.data });
+            this.#sessionData = newSession;
+            await this.#onUpdate?.(newSession);
+            return newSession;
+        });
+        return this.#sessionPromise;
+    }
+    #refreshMetadata(session) {
+        const promise = ok(this.#server.get('com.atproto.server.getSession', {
+            headers: {
+                authorization: `Bearer ${session.accessJwt}`,
+            },
+        }));
+        promise.then((next) => {
+            const existing = this.#sessionData;
+            if (!existing || existing.did !== next.did) {
+                return;
+            }
+            const updated = buildSessionData(existing.service, { ...existing, ...next });
+            this.#sessionData = updated;
+            this.#onUpdate?.(updated);
+        }, () => {
+            // ignore background metadata fetch errors
+        });
+    }
+}
+// #endregion
+// #region helpers
+const buildSessionData = (service, raw) => {
+    const didDoc = raw.didDoc;
+    let pdsUri = raw.pdsUri;
+    if (didDoc) {
+        pdsUri = getPdsEndpoint(didDoc) ?? pdsUri;
+    }
+    return {
+        service,
+        accessJwt: raw.accessJwt,
+        refreshJwt: raw.refreshJwt,
+        handle: raw.handle,
+        did: raw.did,
+        pdsUri,
+        email: raw.email,
+        emailConfirmed: raw.emailConfirmed,
+        emailAuthFactor: raw.emailAuthFactor,
+        active: raw.active ?? true,
+        inactiveStatus: raw.status,
+    };
+};
+/**
+ * parse a login URL into credentials.
+ * format: `https://identifier:password@service`
+ * @param input URL string or URL object
+ * @returns parsed credentials
+ */
+const 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: decodeURIComponent(url.username),
+        password: decodeURIComponent(url.password),
+    };
+};
+/** decode a JWT token's payload */
+const decodeJwt = (token) => {
+    const part = token.split('.')[1];
+    if (typeof part !== 'string') {
+        throw new Error(`invalid token: missing part 2`);
+    }
+    let b64 = part.replace(/-/g, '+').replace(/_/g, '/');
+    switch (b64.length % 4) {
+        case 0:
+            break;
+        case 2:
+            b64 += '==';
+            break;
+        case 3:
+            b64 += '=';
+            break;
+        default:
+            throw new Error(`invalid token: invalid base64 length`);
+    }
+    return JSON.parse(atob(b64));
+};
+const isExpiredTokenResponse = async (response) => {
+    if (response.status !== 400) {
+        return false;
+    }
+    if (extractContentType(response.headers) !== 'application/json') {
+        return false;
+    }
+    // this is nasty as it relies heavily on what the PDS returns, but avoiding
+    // cloning and reading the request as much as possible is better.
+    // {"error":"ExpiredToken","message":"Token has expired"}
+    // {"error":"ExpiredToken","message":"Token is expired"}
+    if (extractContentLength(response.headers) > 54 * 1.5) {
+        return false;
+    }
+    try {
+        const data = await response.clone().json();
+        if (isXRPCErrorPayload(data)) {
+            return data.error === 'ExpiredToken';
+        }
+    }
+    catch { }
+    return false;
+};
+const extractContentType = (headers) => {
+    return headers.get('content-type')?.split(';')[0]?.trim();
+};
+const extractContentLength = (headers) => {
+    return Number(headers.get('content-length') ?? ';');
+};
+// #endregion
+//# sourceMappingURL=password-session.js.map

package/dist/password-session.js.map

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

package/lib/index.ts

@@ -0,0 +1 @@
+export * from './password-session.ts';

package/lib/password-session.ts

@@ -0,0 +1,557 @@
+import type { ComAtprotoServerCreateSession } from '@atcute/atproto';
+import {
+	Client,
+	ClientResponseError,
+	isXRPCErrorPayload,
+	ok,
+	simpleFetchHandler,
+	type FetchHandlerObject,
+} from '@atcute/client';
+import { getPdsEndpoint, type DidDocument } from '@atcute/identity';
+import type { Did } from '@atcute/lexicons';
+
+// #region session data
+
+/** persistable session data */
+export interface PasswordSessionData {
+	/** authentication service URL */
+	service: string;
+	accessJwt: string;
+	refreshJwt: string;
+	handle: string;
+	did: Did;
+	/** PDS endpoint derived from DID document */
+	pdsUri?: string;
+	email?: string;
+	emailConfirmed?: boolean;
+	emailAuthFactor?: boolean;
+	active: boolean;
+	inactiveStatus?: string;
+}
+
+// #endregion
+
+// #region options
+
+export interface PasswordSessionOptions {
+	/** custom fetch implementation */
+	fetch?: typeof fetch;
+
+	/**
+	 * called when session is successfully created or refreshed with new
+	 * credentials. use this to persist the updated session.
+	 * receives `this: PasswordSession` context.
+	 * @note must not throw
+	 */
+	onUpdate?: (this: PasswordSession, data: PasswordSessionData) => void | Promise<void>;
+
+	/**
+	 * called when a session refresh fails due to a transient error (network,
+	 * server down). the session is preserved — consider retry logic.
+	 * @note must not throw
+	 */
+	onUpdateFailure?: (
+		this: PasswordSession,
+		data: PasswordSessionData,
+		error: unknown,
+	) => void | Promise<void>;
+
+	/**
+	 * called when the session is terminated — either explicit logout or
+	 * server-side invalidation (expired/invalid refresh token).
+	 * use this to clean up persisted session data.
+	 * @note must not throw
+	 */
+	onDelete?: (this: PasswordSession, data: PasswordSessionData) => void | Promise<void>;
+
+	/**
+	 * called when logout network request fails due to a transient error.
+	 * the session stays active locally so you can retry.
+	 * @note must not throw
+	 */
+	onDeleteFailure?: (
+		this: PasswordSession,
+		data: PasswordSessionData,
+		error: unknown,
+	) => void | Promise<void>;
+}
+
+/** credentials for login */
+export interface PasswordSessionLoginCredentials {
+	service: string;
+	identifier: string;
+	password: string;
+	/** two-factor authentication code */
+	code?: string;
+	/** allow signing in even if the account has been taken down */
+	allowTakendown?: boolean;
+}
+
+/** options for login — second parameter, behavior config */
+export interface PasswordSessionLoginOptions extends PasswordSessionOptions {
+	/** cached session to try resuming before falling back to fresh login */
+	session?: PasswordSessionData;
+}
+
+// #endregion
+
+// #region class
+
+/**
+ * password-based authentication session for AT Protocol services.
+ *
+ * manages access/refresh token lifecycle, automatic refresh on 401, and
+ * session persistence via callbacks. instances are always in an authenticated
+ * state — use the static factories for validated construction.
+ *
+ * for browser-based applications, prefer OAuth-based authentication instead.
+ * when using password auth, use app passwords rather than main account credentials.
+ */
+export class PasswordSession implements FetchHandlerObject, AsyncDisposable {
+	#sessionData: PasswordSessionData | null;
+	#sessionPromise: Promise<PasswordSessionData>;
+	#server: Client;
+	#fetch: typeof fetch;
+
+	#onUpdate: PasswordSessionOptions['onUpdate'];
+	#onUpdateFailure: PasswordSessionOptions['onUpdateFailure'];
+	#onDelete: PasswordSessionOptions['onDelete'];
+	#onDeleteFailure: PasswordSessionOptions['onDeleteFailure'];
+
+	/**
+	 * construct with existing session data. tokens refresh lazily on 401.
+	 * use static `login()` or `resume()` for validated sessions.
+	 * @param session existing session data
+	 * @param options session options
+	 */
+	constructor(session: PasswordSessionData, options: PasswordSessionOptions = {}) {
+		this.#sessionData = session;
+		this.#sessionPromise = Promise.resolve(session);
+		this.#fetch = options.fetch ?? fetch;
+
+		this.#server = new Client({
+			handler: simpleFetchHandler({ service: session.service, fetch: this.#fetch }),
+		});
+
+		this.#onUpdate = options.onUpdate;
+		this.#onUpdateFailure = options.onUpdateFailure;
+		this.#onDelete = options.onDelete;
+		this.#onDeleteFailure = options.onDeleteFailure;
+	}
+
+	/**
+	 * account DID
+	 * @throws if the session has been destroyed
+	 */
+	get did(): Did {
+		return this.session.did;
+	}
+
+	/** whether this session has been destroyed (logged out) */
+	get destroyed(): boolean {
+		return this.#sessionData === null;
+	}
+
+	/**
+	 * current session data — serialize this for persistence
+	 * @throws if the session has been destroyed
+	 */
+	get session(): PasswordSessionData {
+		if (this.#sessionData) {
+			return this.#sessionData;
+		}
+		throw new Error(`session has been destroyed`);
+	}
+
+	/** URL to dispatch API requests to (PDS from DID doc, or service URL) */
+	get dispatchUrl(): string {
+		return this.session.pdsUri ?? this.session.service;
+	}
+
+	// --- static factories ---
+
+	/**
+	 * authenticate with credentials. optionally tries resuming a cached
+	 * session first, falling back to fresh createSession on failure.
+	 * @param credentials login credentials or URL shorthand (`https://handle:pass@service`)
+	 * @param options login options
+	 * @returns authenticated session
+	 */
+	static async login(
+		credentials: PasswordSessionLoginCredentials | string | URL,
+		options: PasswordSessionLoginOptions = {},
+	): Promise<PasswordSession> {
+		const creds =
+			typeof credentials === 'string' || credentials instanceof URL
+				? parseLoginUrl(credentials)
+				: credentials;
+
+		// try cached session first if provided
+		if (options.session) {
+			try {
+				return await PasswordSession.resume(options.session, options);
+			} catch {
+				// fall through to fresh login
+			}
+		}
+
+		const _fetch = options.fetch ?? fetch;
+		const server = new Client({
+			handler: simpleFetchHandler({ service: creds.service, fetch: _fetch }),
+		});
+
+		const data = await ok(
+			server.post('com.atproto.server.createSession', {
+				input: {
+					identifier: creds.identifier,
+					password: creds.password,
+					authFactorToken: creds.code,
+					allowTakendown: creds.allowTakendown,
+				},
+			}),
+		);
+
+		const sessionData = buildSessionData(creds.service, data);
+		const session = new PasswordSession(sessionData, options);
+		await options.onUpdate?.call(session, sessionData);
+		return session;
+	}
+
+	/**
+	 * resume from persisted session data. if the access token is still valid,
+	 * returns immediately and refreshes metadata in the background.
+	 * if expired, refreshes synchronously. throws only if the session is
+	 * definitively invalid.
+	 * @param session persisted session data
+	 * @param options session options
+	 * @returns resumed session
+	 */
+	static async resume(
+		session: PasswordSessionData,
+		options: PasswordSessionOptions = {},
+	): Promise<PasswordSession> {
+		const instance = new PasswordSession(session, options);
+
+		const now = Date.now() / 1_000 + 60 * 5;
+		const accessToken = decodeJwt(session.accessJwt) as { exp: number };
+
+		if (now >= accessToken.exp) {
+			// access token expired or expiring soon, refresh synchronously
+			await instance.refresh();
+		} else {
+			// access token still valid, fetch session metadata in background
+			instance.#refreshMetadata(session);
+		}
+
+		if (instance.destroyed) {
+			throw new ClientResponseError({ status: 401, data: { error: 'InvalidToken' } });
+		}
+
+		return instance;
+	}
+
+	/**
+	 * delete a session server-side without resuming it.
+	 * useful for cleanup of orphaned sessions.
+	 * @param session session data to delete
+	 * @param options session options
+	 */
+	static async delete(session: PasswordSessionData, options: PasswordSessionOptions = {}): Promise<void> {
+		const instance = new PasswordSession(session, options);
+		await instance.logout();
+	}
+
+	// --- lifecycle ---
+
+	/** refresh the session tokens */
+	async refresh(): Promise<void> {
+		await this.#refresh();
+	}
+
+	/**
+	 * sign out — invalidates session server-side.
+	 * on success, the session is destroyed and `onDelete` is called.
+	 * on transient failure (network), `onDeleteFailure` is called and
+	 * the session stays active for retry.
+	 * @throws on transient failure when the session couldn't be deleted
+	 */
+	async logout(): Promise<void> {
+		let failure: unknown = null;
+
+		this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
+			const response = await this.#server.post('com.atproto.server.deleteSession', {
+				as: null,
+				headers: {
+					authorization: `Bearer ${sessionData.refreshJwt}`,
+				},
+			});
+
+			if (!response.ok) {
+				const isExpected =
+					response.status === 401 ||
+					response.data.error === 'InvalidToken' ||
+					response.data.error === 'ExpiredToken';
+
+				if (!isExpected) {
+					// transient error — keep session alive
+					failure = new ClientResponseError(response);
+					await this.#onDeleteFailure?.(sessionData, failure);
+					return sessionData;
+				}
+			}
+
+			// success or expected error → session is gone
+			await this.#onDelete?.(sessionData);
+			this.#sessionData = null;
+			throw new Error(`session has been destroyed`);
+		});
+
+		return this.#sessionPromise.then(
+			() => {
+				// resolved means logout failed (transient error)
+				throw failure!;
+			},
+			() => {
+				// rejected means session was destroyed (successful logout)
+			},
+		);
+	}
+
+	/** AsyncDisposable — calls `logout()` */
+	async [Symbol.asyncDispose](): Promise<void> {
+		await this.logout();
+	}
+
+	// --- FetchHandlerObject ---
+
+	async handle(pathname: string, init: RequestInit): Promise<Response> {
+		const sessionPromise = this.#sessionPromise;
+		const sessionData = await sessionPromise;
+
+		const url = new URL(pathname, sessionData.pdsUri ?? sessionData.service);
+		const headers = new Headers(init.headers);
+
+		if (headers.has('authorization')) {
+			return (0, this.#fetch)(url, init);
+		}
+
+		headers.set('authorization', `Bearer ${sessionData.accessJwt}`);
+
+		const initialResponse = await (0, this.#fetch)(url, { ...init, headers });
+
+		if (initialResponse.status !== 401 && !(await isExpiredTokenResponse(initialResponse))) {
+			return initialResponse;
+		}
+
+		// refresh unless another call already started one
+		const refreshPromise = this.#sessionPromise === sessionPromise ? this.#refresh() : this.#sessionPromise;
+
+		const newSessionData = await refreshPromise.catch(() => null);
+
+		if (
+			!newSessionData ||
+			newSessionData.accessJwt === sessionData.accessJwt ||
+			init.signal?.aborted ||
+			init.body instanceof ReadableStream
+		) {
+			return initialResponse;
+		}
+
+		// cancel initial response to avoid resource leaks
+		if (!initialResponse.bodyUsed) {
+			await initialResponse.body?.cancel();
+		}
+
+		headers.set('authorization', `Bearer ${newSessionData.accessJwt}`);
+		return await (0, this.#fetch)(url, { ...init, headers });
+	}
+
+	// --- internal ---
+
+	#refresh(): Promise<PasswordSessionData> {
+		this.#sessionPromise = this.#sessionPromise.then(async (sessionData) => {
+			const response = await this.#server.post('com.atproto.server.refreshSession', {
+				headers: {
+					authorization: `Bearer ${sessionData.refreshJwt}`,
+				},
+			});
+
+			if (!response.ok) {
+				const isExpected =
+					response.status === 401 ||
+					response.data.error === 'ExpiredToken' ||
+					response.data.error === 'InvalidToken';
+
+				if (isExpected) {
+					await this.#onDelete?.(sessionData);
+					this.#sessionData = null;
+					throw new ClientResponseError(response);
+				}
+
+				// transient error — preserve session
+				await this.#onUpdateFailure?.(sessionData, new ClientResponseError(response));
+				return sessionData;
+			}
+
+			// DID must not change during refresh
+			if (response.data.did !== sessionData.did) {
+				await this.#onDelete?.(sessionData);
+				this.#sessionData = null;
+				throw new ClientResponseError({ status: 401, data: { error: 'InvalidToken' } });
+			}
+
+			const newSession = buildSessionData(sessionData.service, { ...sessionData, ...response.data });
+			this.#sessionData = newSession;
+			await this.#onUpdate?.(newSession);
+			return newSession;
+		});
+
+		return this.#sessionPromise;
+	}
+
+	#refreshMetadata(session: PasswordSessionData): void {
+		const promise = ok(
+			this.#server.get('com.atproto.server.getSession', {
+				headers: {
+					authorization: `Bearer ${session.accessJwt}`,
+				},
+			}),
+		);
+
+		promise.then(
+			(next) => {
+				const existing = this.#sessionData;
+				if (!existing || existing.did !== next.did) {
+					return;
+				}
+
+				const updated = buildSessionData(existing.service, { ...existing, ...next });
+				this.#sessionData = updated;
+				this.#onUpdate?.(updated);
+			},
+			() => {
+				// ignore background metadata fetch errors
+			},
+		);
+	}
+}
+
+// #endregion
+
+// #region helpers
+
+const buildSessionData = (
+	service: string,
+	raw: ComAtprotoServerCreateSession.$output & { pdsUri?: string },
+): PasswordSessionData => {
+	const didDoc = raw.didDoc as DidDocument | undefined;
+
+	let pdsUri = raw.pdsUri;
+	if (didDoc) {
+		pdsUri = getPdsEndpoint(didDoc) ?? pdsUri;
+	}
+
+	return {
+		service,
+		accessJwt: raw.accessJwt,
+		refreshJwt: raw.refreshJwt,
+		handle: raw.handle,
+		did: raw.did,
+		pdsUri,
+		email: raw.email,
+		emailConfirmed: raw.emailConfirmed,
+		emailAuthFactor: raw.emailAuthFactor,
+		active: raw.active ?? true,
+		inactiveStatus: raw.status,
+	};
+};
+
+/**
+ * parse a login URL into credentials.
+ * format: `https://identifier:password@service`
+ * @param input URL string or URL object
+ * @returns parsed credentials
+ */
+const parseLoginUrl = (input: string | URL): PasswordSessionLoginCredentials => {
+	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: decodeURIComponent(url.username),
+		password: decodeURIComponent(url.password),
+	};
+};
+
+/** decode a JWT token's payload */
+const decodeJwt = (token: string): unknown => {
+	const part = token.split('.')[1];
+	if (typeof part !== 'string') {
+		throw new Error(`invalid token: missing part 2`);
+	}
+
+	let b64 = part.replace(/-/g, '+').replace(/_/g, '/');
+	switch (b64.length % 4) {
+		case 0:
+			break;
+		case 2:
+			b64 += '==';
+			break;
+		case 3:
+			b64 += '=';
+			break;
+		default:
+			throw new Error(`invalid token: invalid base64 length`);
+	}
+
+	return JSON.parse(atob(b64));
+};
+
+const isExpiredTokenResponse = async (response: Response): Promise<boolean> => {
+	if (response.status !== 400) {
+		return false;
+	}
+
+	if (extractContentType(response.headers) !== 'application/json') {
+		return false;
+	}
+
+	// this is nasty as it relies heavily on what the PDS returns, but avoiding
+	// cloning and reading the request as much as possible is better.
+
+	// {"error":"ExpiredToken","message":"Token has expired"}
+	// {"error":"ExpiredToken","message":"Token is expired"}
+	if (extractContentLength(response.headers) > 54 * 1.5) {
+		return false;
+	}
+
+	try {
+		const data = await response.clone().json();
+		if (isXRPCErrorPayload(data)) {
+			return data.error === 'ExpiredToken';
+		}
+	} catch {}
+
+	return false;
+};
+
+const extractContentType = (headers: Headers) => {
+	return headers.get('content-type')?.split(';')[0]?.trim();
+};
+const extractContentLength = (headers: Headers) => {
+	return Number(headers.get('content-length') ?? ';');
+};
+
+// #endregion

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@atcute/password-session",
+  "version": "0.1.0",
+  "description": "password-based session management for AT Protocol",
+  "license": "0BSD",
+  "repository": {
+    "url": "https://github.com/mary-ext/atcute",
+    "directory": "packages/clients/password-session"
+  },
+  "files": [
+    "dist/",
+    "lib/",
+    "!lib/**/*.bench.ts",
+    "!lib/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@atcute/client": "^4.2.1",
+    "@atcute/identity": "^1.1.3",
+    "@atcute/lexicons": "^1.2.9"
+  },
+  "devDependencies": {
+    "vitest": "^4.0.18",
+    "@atcute/atproto": "^3.1.10",
+    "@atcute/internal-dev-env": "^1.0.2",
+    "@atcute/bluesky": "^3.2.19"
+  },
+  "scripts": {
+    "build": "tsgo --project tsconfig.build.json",
+    "test": "vitest run",
+    "prepublish": "rm -rf dist; pnpm run build"
+  }
+}