semble / docs / auth.md

# Authentication Approach Summary

This document outlines the authentication mechanism used in this AT Protocol Express application.

## Core Components and Flow:

1.  **OAuth 2.0 with AT Protocol:**
    - The primary authentication method is OAuth 2.0, delegating user authentication to their chosen AT Protocol PDS (Personal Data Server).
    - The application acts as an OAuth client, configured in `src/auth/client.ts` using `@atproto/oauth-client-node`.
    - The flow typically starts when a user attempts to log in via the `/login` route.

2.  **Session Management with `iron-session`:**
    - Once the user successfully authenticates with their PDS via the OAuth flow, the `/oauth/callback` route is invoked.
    - This callback handler uses `ctx.oauthClient.callback(params)` to finalize the OAuth exchange and retrieve an AT Protocol session (which includes the user's DID and potentially access/refresh tokens for the PDS).
    - Crucially, the user's `did` is then stored in a server-side session managed by `iron-session`.
    - `iron-session` encrypts this session data (containing the `did`) and stores it in an HTTP cookie (named `sid` by default in `src/routes.ts`). This cookie is sent to the client's browser.

3.  **Cookie-Based Session Persistence:**
    - The browser automatically includes the `sid` cookie in subsequent requests to the server.
    - This cookie is `HttpOnly` (a default and recommended practice for `iron-session`), meaning it's not accessible to client-side JavaScript, enhancing security against XSS attacks.

4.  **Session Restoration and AT Protocol Agent:**
    - For requests requiring authentication (e.g., posting a status, viewing personalized content), the `getSessionAgent` helper function in `src/routes.ts` is used.
    - `getSessionAgent` retrieves the `did` from the `iron-session` cookie.
    - It then uses `ctx.oauthClient.restore(session.did)` to restore the full AT Protocol OAuth session. This step might involve using stored refresh tokens (managed by `SessionStore` in `src/auth/storage.ts`) to obtain fresh access tokens for interacting with the user's PDS.
    - If restoration is successful, an `Agent` from `@atproto/api` is instantiated. This agent is then used to make authenticated requests to the user's PDS on their behalf.

5.  **Storage (`src/auth/storage.ts`):**
    - `StateStore`: Persists OAuth state parameters during the authorization code flow to prevent CSRF attacks.
    - `SessionStore`: Persists the AT Protocol OAuth session details (including access tokens, refresh tokens, and scopes) associated with a user's DID. This allows `oauthClient.restore()` to reconstruct an active PDS session.
    - Both stores use the application's database (SQLite by default) for persistence.

## Key Routes in `src/routes.ts`:\*\*

- **`/login` (GET & POST):** Initiates the OAuth flow by redirecting the user to their PDS for authentication.
- **`/oauth/callback` (GET):** Handles the redirect from the PDS after authentication. Exchanges the authorization code for tokens (handled by `oauthClient`), and then establishes the `iron-session` by storing the user's `did`.
- **`/logout` (POST):** Destroys the `iron-session`, effectively logging the user out by clearing the session cookie.
- **Authenticated Routes (e.g., `/status` POST, `/` GET for logged-in users):** Use `getSessionAgent` to retrieve an authenticated AT Protocol agent.

## Summary of Technologies:

- **OAuth 2.0:** Standard for delegated authentication.
- **AT Protocol SDK (`@atproto/oauth-client-node`, `@atproto/api`):** For interacting with the AT Protocol network and PDS.
- **`iron-session`:** For server-side session management with encrypted cookies.
- **HTTP Cookies (`HttpOnly`):** For persisting session identifiers on the client-side securely.
- **Express.js:** As the web server framework.