This project demonstrates ANProto messaging on top of the AT Protocol (Bluesky/ATProto) with OAuth auth. It is designed to be clear, concise, and "LLM-friendly" (easy for AI assistants to parse and understand context).

Purpose#

To demonstrate a secure, production-ready (conceptually) OAuth flow using @atproto/oauth-client-node, including:

Handle Resolution: Converting user.bsky.social to a DID.
Session Management: Persisting sessions securely using a database.
Scopes: Requesting appropriate permissions (Standard vs. Transition).
Token Management: Handling access and refresh tokens automatically.

Quick Start#

Install Dependencies:
```
npm install
```
Run the Server:
```
npm run dev
```
Open: Visit http://localhost:3000

Documentation#

Architecture Overview: How the components (Client, DB, Storage, Express) fit together.
Understanding Scopes: Which permissions to ask for and why.
Handles vs. DIDs: How user identity works in ATProto.
Setup & Configuration: Configuring the client metadata for localhost vs. production.

Key Files#

src/index.ts: The web server and route handlers.
src/client.ts: Configuration of the OAuth client.
src/storage.ts: Interface between the OAuth client and the database.
src/db.ts: SQLite database connection.

"Do's and Don'ts"#

DO use DIDs (did:plc:...) as the primary user key in your database, not handles. Handles are mutable.
DO persist the state and session data securely.
DON'T request atproto (full access) scope unless you absolutely need it. Prefer granular scopes if available (though currently atproto or transition:generic are common).
DON'T hardcode the PDS URL. Always resolve it from the user's DID/Handle.

Clone this repository