commit 0e5ad7149f29c22fc58372cafb74964758bce5e3 · daffl.xyz/astro-atproto-starter

+48 -17

README.md

···

       1
       1
       -
       # Astro Starter Kit: Minimal

     

       1
       1
       +
       # Astro ATProto OAuth Starter

     

       2
       2
       +
       

     

       3
       3
       +
       A minimal [Astro](https://astro.build) starter template demonstrating OAuth authentication with AT Protocol (ATProto), the decentralized social networking protocol used by Bluesky and other services.

     

       4
       4
       +
       

     

       5
       5
       +
       This starter includes:

     

       6
       6
       +
       - Complete OAuth authentication flow using `@atproto/oauth-client-node`

     

       7
       7
       +
       - Cookie-based session management

     

       8
       8
       +
       - Profile display after authentication

     

       9
       9
       +
       - Login/logout endpoints

     

       10
       10
       +
       - Tailwind CSS and DaisyUI styling

     

       11
       11
       +
       

     

       12
       12
       +
       ## 🚀 Getting Started

     

       13
       13
       +
       

     

       14
       14
       +
       1. **Install dependencies:**

     

       15
       15
       +
          ```sh

     

       16
       16
       +
          npm install

     

       17
       17
       +
          ```

     

       2
       18
        
       

     

       3
       3
       -
       ```sh

     

       4
       4
       -
       npm create astro@latest -- --template minimal

     

       5
       5
       -
       ```

     

       19
       19
       +
       2. **Configure environment variables:**

     

       20
       20
       +
          ```sh

     

       21
       21
       +
          cp .env.template .env

     

       22
       22
       +
          ```

     

       23
       23
       +
          Edit `.env` if you need to change the port (default: 4321) or set a public URL.

     

       6
       24
        
       

     

       7
       7
       -
       > 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!

     

       25
       25
       +
       3. **Start the development server:**

     

       26
       26
       +
          ```sh

     

       27
       27
       +
          npm run dev

     

       28
       28
       +
          ```

     

       29
       29
       +
          The app will be available at `http://localhost:4321`

     

       8
       30
        
       

     

       9
       9
       -
       ## 🚀 Project Structure

     

       31
       31
       +
       4. **Try logging in:**

     

       32
       32
       +
          Enter your AT Protocol handle (e.g., `alice.bsky.social`) to authenticate.

     

       10
       33
        
       

     

       11
       11
       -
       Inside of your Astro project, you'll see the following folders and files:

     

       34
       34
       +
       ## 📁 Project Structure

     

       12
       35
        
       

     

       13
       36
        
       ```text

     

       14
       37
        
       /

     

       15
       38
        
       ├── public/

     

       16
       39
        
       ├── src/

     

       17
       17
       -
       │   └── pages/

     

       18
       18
       -
       │       └── index.astro

     

       40
       40
       +
       │   ├── lib/

     

       41
       41
       +
       │   │   ├── context.ts      # OAuth client singleton

     

       42
       42
       +
       │   │   ├── oauth.ts        # OAuth client configuration

     

       43
       43
       +
       │   │   ├── session.ts      # Session management

     

       44
       44
       +
       │   │   └── storage.ts      # Cookie-based stores

     

       45
       45
       +
       │   ├── pages/

     

       46
       46
       +
       │   │   ├── api/

     

       47
       47
       +
       │   │   │   ├── login.ts    # Login endpoint

     

       48
       48
       +
       │   │   │   ├── logout.ts   # Logout endpoint

     

       49
       49
       +
       │   │   │   └── oauth/

     

       50
       50
       +
       │   │   │       └── callback.ts  # OAuth callback handler

     

       51
       51
       +
       │   │   └── index.astro     # Main page with login UI

     

       52
       52
       +
       │   └── styles.css

     

       19
       53
        
       └── package.json

     

       20
       54
        
       ```

     

       21
       21
       -
       

     

       22
       22
       -
       Astro looks for `.astro` or `.md` files in the `src/pages/` directory. Each page is exposed as a route based on its file name.

     

       23
       23
       -
       

     

       24
       24
       -
       There's nothing special about `src/components/`, but that's where we like to put any Astro/React/Vue/Svelte/Preact components.

     

       25
       25
       -
       

     

       26
       26
       -
       Any static assets, like images, can be placed in the `public/` directory.

     

       27
       55
        
       

     

       28
       56
        
       ## 🧞 Commands

     

       29
       57
        
       

     
···

       38
       66
        
       | `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |

     

       39
       67
        
       | `npm run astro -- --help` | Get help using the Astro CLI                     |

     

       40
       68
        
       

     

       41
       41
       -
       ## 👀 Want to learn more?

     

       69
       69
       +
       ## 📚 Learn More

     

       42
       70
        
       

     

       43
       43
       -
       Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).

     

       71
       71
       +
       - [Astro Documentation](https://docs.astro.build)

     

       72
       72
       +
       - [AT Protocol Documentation](https://atproto.com)

     

       73
       73
       +
       - [@atproto/oauth-client-node](https://github.com/bluesky-social/atproto/tree/main/packages/oauth/oauth-client-node)

     

       74
       74
       +
       - [Bluesky](https://bsky.app)

+4 -14

src/lib/context.ts

···

       1
       1
       -
       import { NodeOAuthClient } from '@atproto/oauth-client-node'

     

       1
       1
       +
       import type { AstroCookies } from 'astro'

     

       2
       2
        
       import { createOAuthClient } from './oauth'

     

       3
       3
        
       

     

       4
       4
       -
       export type AppContext = {

     

       5
       5
       -
         oauthClient: NodeOAuthClient

     

       6
       6
       -
       }

     

       7
       7
       -
       

     

       8
       8
       -
       let _ctx: AppContext | null = null

     

       9
       9
       -
       

     

       10
       10
       -
       export async function getAppContext(): Promise<AppContext> {

     

       11
       11
       -
         if (_ctx) return _ctx

     

       12
       12
       -
       

     

       13
       13
       -
         const oauthClient = await createOAuthClient()

     

       14
       14
       -
       

     

       15
       15
       -
         _ctx = { oauthClient }

     

       16
       16
       -
         return _ctx

     

       4
       4
       +
       // Create a request-scoped OAuth client with cookie-based storage

     

       5
       5
       +
       export function getOAuthClient(cookies: AstroCookies) {

     

       6
       6
       +
         return createOAuthClient(cookies)

     

       17
       7
        
       }

+5 -4

src/lib/oauth.ts

···

       1
       1
       +
       import type { AstroCookies } from 'astro'

     

       1
       2
        
       import {

     

       2
       3
        
         atprotoLoopbackClientMetadata,

     

       3
       4
        
         NodeOAuthClient,

     

       4
       5
        
       } from "@atproto/oauth-client-node";

     

       5
       6
        
       import { env } from "./env";

     

       6
       6
       -
       import { SessionStore, StateStore } from "./storage";

     

       7
       7
       +
       import { CookieSessionStore, CookieStateStore } from "./storage";

     

       7
       8
        
       

     

       8
       8
       -
       export async function createOAuthClient() {

     

       9
       9
       +
       export function createOAuthClient(cookies: AstroCookies) {

     

       9
       10
        
         const clientMetadata = atprotoLoopbackClientMetadata(

     

       10
       11
        
           `http://localhost?${new URLSearchParams([

     

       11
       12
        
             ["redirect_uri", `http://127.0.0.1:${env.PORT}/api/oauth/callback`],

     
···

       15
       16
        
       

     

       16
       17
        
         return new NodeOAuthClient({

     

       17
       18
        
           clientMetadata,

     

       18
       18
       -
           stateStore: new StateStore(),

     

       19
       19
       -
           sessionStore: new SessionStore(),

     

       19
       19
       +
           stateStore: new CookieStateStore(cookies),

     

       20
       20
       +
           sessionStore: new CookieSessionStore(cookies),

     

       20
       21
        
         });

     

       21
       22
        
       }

+53 -12

src/lib/storage.ts

···

       1
       1
       +
       import type { AstroCookies } from 'astro'

     

       1
       2
        
       import type {

     

       2
       3
        
         NodeSavedSession,

     

       3
       4
        
         NodeSavedSessionStore,

     
···

       5
       6
        
         NodeSavedStateStore,

     

       6
       7
        
       } from '@atproto/oauth-client-node'

     

       7
       8
        
       

     

       8
       8
       -
       // In-memory storage for OAuth state and sessions

     

       9
       9
       -
       // For production, you'd want to use a proper database or distributed cache

     

       9
       9
       +
       // Cookie-based storage for OAuth state and sessions

     

       10
       10
       +
       // All data is serialized into cookies for stateless operation

     

       10
       11
        
       

     

       11
       11
       -
       export class StateStore implements NodeSavedStateStore {

     

       12
       12
       -
         private store = new Map<string, NodeSavedState>()

     

       12
       12
       +
       export class CookieStateStore implements NodeSavedStateStore {

     

       13
       13
       +
         constructor(private cookies: AstroCookies) {}

     

       13
       14
        
       

     

       14
       15
        
         async get(key: string): Promise<NodeSavedState | undefined> {

     

       15
       15
       -
           return this.store.get(key)

     

       16
       16
       +
           const cookieName = `oauth_state_${key}`

     

       17
       17
       +
           const cookie = this.cookies.get(cookieName)

     

       18
       18
       +
           if (!cookie?.value) return undefined

     

       19
       19
       +
       

     

       20
       20
       +
           try {

     

       21
       21
       +
             const decoded = atob(cookie.value)

     

       22
       22
       +
             return JSON.parse(decoded) as NodeSavedState

     

       23
       23
       +
           } catch (err) {

     

       24
       24
       +
             console.warn('Failed to decode OAuth state:', err)

     

       25
       25
       +
             return undefined

     

       26
       26
       +
           }

     

       16
       27
        
         }

     

       17
       28
        
       

     

       18
       29
        
         async set(key: string, val: NodeSavedState) {

     

       19
       19
       -
           this.store.set(key, val)

     

       30
       30
       +
           const cookieName = `oauth_state_${key}`

     

       31
       31
       +
           const encoded = btoa(JSON.stringify(val))

     

       32
       32
       +
       

     

       33
       33
       +
           this.cookies.set(cookieName, encoded, {

     

       34
       34
       +
             httpOnly: true,

     

       35
       35
       +
             secure: false,

     

       36
       36
       +
             sameSite: 'lax',

     

       37
       37
       +
             path: '/',

     

       38
       38
       +
             maxAge: 60 * 10, // 10 minutes (OAuth flow timeout)

     

       39
       39
       +
           })

     

       20
       40
        
         }

     

       21
       41
        
       

     

       22
       42
        
         async del(key: string) {

     

       23
       23
       -
           this.store.delete(key)

     

       43
       43
       +
           const cookieName = `oauth_state_${key}`

     

       44
       44
       +
           this.cookies.delete(cookieName, { path: '/' })

     

       24
       45
        
         }

     

       25
       46
        
       }

     

       26
       47
        
       

     

       27
       27
       -
       export class SessionStore implements NodeSavedSessionStore {

     

       28
       28
       -
         private store = new Map<string, NodeSavedSession>()

     

       48
       48
       +
       export class CookieSessionStore implements NodeSavedSessionStore {

     

       49
       49
       +
         constructor(private cookies: AstroCookies) {}

     

       29
       50
        
       

     

       30
       51
        
         async get(key: string): Promise<NodeSavedSession | undefined> {

     

       31
       31
       -
           return this.store.get(key)

     

       52
       52
       +
           const cookieName = `oauth_session_${key}`

     

       53
       53
       +
           const cookie = this.cookies.get(cookieName)

     

       54
       54
       +
           if (!cookie?.value) return undefined

     

       55
       55
       +
       

     

       56
       56
       +
           try {

     

       57
       57
       +
             const decoded = atob(cookie.value)

     

       58
       58
       +
             return JSON.parse(decoded) as NodeSavedSession

     

       59
       59
       +
           } catch (err) {

     

       60
       60
       +
             console.warn('Failed to decode OAuth session:', err)

     

       61
       61
       +
             return undefined

     

       62
       62
       +
           }

     

       32
       63
        
         }

     

       33
       64
        
       

     

       34
       65
        
         async set(key: string, val: NodeSavedSession) {

     

       35
       35
       -
           this.store.set(key, val)

     

       66
       66
       +
           const cookieName = `oauth_session_${key}`

     

       67
       67
       +
           const encoded = btoa(JSON.stringify(val))

     

       68
       68
       +
       

     

       69
       69
       +
           this.cookies.set(cookieName, encoded, {

     

       70
       70
       +
             httpOnly: true,

     

       71
       71
       +
             secure: false,

     

       72
       72
       +
             sameSite: 'lax',

     

       73
       73
       +
             path: '/',

     

       74
       74
       +
             maxAge: 60 * 60 * 24 * 30, // 30 days

     

       75
       75
       +
           })

     

       36
       76
        
         }

     

       37
       77
        
       

     

       38
       78
        
         async del(key: string) {

     

       39
       39
       -
           this.store.delete(key)

     

       79
       79
       +
           const cookieName = `oauth_session_${key}`

     

       80
       80
       +
           this.cookies.delete(cookieName, { path: '/' })

     

       40
       81
        
         }

     

       41
       82
        
       }

+4 -4

src/pages/api/login.ts

···

       1
       1
        
       import type { APIRoute } from 'astro'

     

       2
       2
       -
       import { getAppContext } from '../../lib/context'

     

       2
       2
       +
       import { getOAuthClient } from '../../lib/context'

     

       3
       3
        
       

     

       4
       4
       -
       export const POST: APIRoute = async ({ request, redirect }) => {

     

       4
       4
       +
       export const POST: APIRoute = async ({ request, cookies, redirect }) => {

     

       5
       5
        
         try {

     

       6
       6
       -
           const ctx = await getAppContext()

     

       6
       6
       +
           const oauthClient = getOAuthClient(cookies)

     

       7
       7
        
           const formData = await request.formData()

     

       8
       8
        
           const handle = formData.get('handle')

     

       9
       9
        
       

     
···

       11
       11
        
             return new Response('Invalid handle', { status: 400 })

     

       12
       12
        
           }

     

       13
       13
        
       

     

       14
       14
       -
           const url = await ctx.oauthClient.authorize(handle, {

     

       14
       14
       +
           const url = await oauthClient.authorize(handle, {

     

       15
       15
        
             scope: 'atproto transition:generic',

     

       16
       16
        
           })

     

       17
       17

+3 -3

src/pages/api/logout.ts

···

       1
       1
        
       import type { APIRoute } from 'astro'

     

       2
       2
       -
       import { getAppContext } from '../../lib/context'

     

       2
       2
       +
       import { getOAuthClient } from '../../lib/context'

     

       3
       3
        
       import { getSession } from '../../lib/session'

     

       4
       4
        
       

     

       5
       5
        
       export const POST: APIRoute = async (context) => {

     

       6
       6
        
         try {

     

       7
       7
       -
           const ctx = await getAppContext()

     

       7
       7
       +
           const oauthClient = getOAuthClient(context.cookies)

     

       8
       8
        
           const session = getSession(context.cookies)

     

       9
       9
        
       

     

       10
       10
        
           if (session.did) {

     

       11
       11
        
             try {

     

       12
       12
       -
               const oauthSession = await ctx.oauthClient.restore(session.did)

     

       12
       12
       +
               const oauthSession = await oauthClient.restore(session.did)

     

       13
       13
        
               if (oauthSession) await oauthSession.signOut()

     

       14
       14
        
             } catch (err) {

     

       15
       15
        
               console.warn('Failed to revoke credentials:', err)

+4 -4

src/pages/api/oauth/callback.ts

···

       1
       1
        
       import type { APIRoute } from 'astro'

     

       2
       2
       -
       import { getAppContext } from '../../../lib/context'

     

       2
       2
       +
       import { getOAuthClient } from '../../../lib/context'

     

       3
       3
        
       import { getSession } from '../../../lib/session'

     

       4
       4
        
       

     

       5
       5
        
       export const GET: APIRoute = async (context) => {

     

       6
       6
        
         try {

     

       7
       7
       -
           const ctx = await getAppContext()

     

       7
       7
       +
           const oauthClient = getOAuthClient(context.cookies)

     

       8
       8
        
           const url = new URL(context.request.url)

     

       9
       9
        
           const params = new URLSearchParams(url.search)

     

       10
       10
        
       

     
···

       12
       12
        
       

     

       13
       13
        
           if (session.did) {

     

       14
       14
        
             try {

     

       15
       15
       -
               const oauthSession = await ctx.oauthClient.restore(session.did)

     

       15
       15
       +
               const oauthSession = await oauthClient.restore(session.did)

     

       16
       16
        
               if (oauthSession) await oauthSession.signOut()

     

       17
       17
        
             } catch (err) {

     

       18
       18
        
               console.warn('OAuth restore failed during callback:', err)

     

       19
       19
        
             }

     

       20
       20
        
           }

     

       21
       21
        
       

     

       22
       22
       -
           const oauth = await ctx.oauthClient.callback(params)

     

       22
       22
       +
           const oauth = await oauthClient.callback(params)

     

       23
       23
        
           session.did = oauth.session.did

     

       24
       24
        
           await session.save()

     

       25
       25

+3 -3

src/pages/index.astro

···

       1
       1
        
       ---

     

       2
       2
        
       import "../styles.css";

     

       3
       3
        
       import { getSession } from "../lib/session";

     

       4
       4
       -
       import { getAppContext } from "../lib/context";

     

       4
       4
       +
       import { getOAuthClient } from "../lib/context";

     

       5
       5
        
       import { Agent } from "@atproto/api";

     

       6
       6
        
       

     

       7
       7
        
       const session = getSession(Astro.cookies);

     

       8
       8
       -
       const ctx = await getAppContext();

     

       8
       8
       +
       const oauthClient = getOAuthClient(Astro.cookies);

     

       9
       9
        
       

     

       10
       10
        
       let agent: Agent | null = null;

     

       11
       11
        
       let profile: any = null;

     

       12
       12
        
       

     

       13
       13
        
       if (session.did) {

     

       14
       14
        
         try {

     

       15
       15
       -
           const oauthSession = await ctx.oauthClient.restore(session.did);

     

       15
       15
       +
           const oauthSession = await oauthClient.restore(session.did);

     

       16
       16
        
           if (oauthSession) {

     

       17
       17
        
             agent = new Agent(oauthSession);

     

       18
       18