app/docs/steps/step-03.md

# **File: COMMIT\_03\_AUTH.md**

## **Commit 3: ATproto OAuth Flow & SurrealDB JWT Generation**

### **Objective**

Implement the complete, high-risk ATproto OAuth flow. This is a complex, multi-step process:

1. Resolve the user's handle to their PDS.9  
2. Discover the PDS's specific authorization\_endpoint.10  
3. Redirect the user to that endpoint.  
4. Handle the callback, exchange the code for an ATproto token.11  
5. Use the ATproto token to get the user's canonical did.  
6. Mint a new, *app-specific* SurrealDB JWT containing the did claim.  
7. Set this SurrealDB JWT in a secure, httpOnly cookie for app session management.

This commit directly addresses the user's identified **Risk 1**.

### **Implementation Specification**

**1\. Create lib/auth/atproto.ts**

Create a file at /lib/auth/atproto.ts to abstract the complex ATproto discovery logic:

TypeScript

import { AtpAgent } from '@atproto/api';

/\*\*  
 \* Resolves a Bluesky handle (e.g., "user.bsky.social") to its  
 \* corresponding PDS (Personal Data Server) and DID (Decentralized Identifier).  
 \* This discovery step is mandatory before initiating OAuth.  
 \*/  
export async function resolveHandle(handle: string) {  
  try {  
    const agent \= new AtpAgent({ service: 'https://bsky.social' });  
    const response \= await agent.resolveHandle({ handle });  
    const did \= response.data.did;

    // Now, get the PDS from the DID document  
    const didDoc \= await agent.getDidDocument({ did });  
      
    // Find the 'atproto\_pds' service endpoint  
    const pdsService \= didDoc.service?.find(  
      (s) \=\> s.id \=== '\#atproto\_pds'  
    );  
      
    if (\!pdsService?.serviceEndpoint) {  
      throw new Error('PDS service endpoint not found in DID document.');  
    }  
      
    return {  
      did,  
      pdsUrl: pdsService.serviceEndpoint,  
    };  
  } catch (error) {  
    console.error('Error resolving handle:', error);  
    throw new Error('Could not resolve Bluesky handle.');  
  }  
}

/\*\*  
 \* Fetches the specific OAuth endpoints for a given PDS.  
 \* Each PDS has its own set of endpoints.  
 \*/  
export async function getAuthEndpoints(pdsUrl: string) {  
  try {  
    const metadataUrl \= \`${pdsUrl}/.well-known/oauth-authorization-server\`;  
    const response \= await fetch(metadataUrl);  
      
    if (\!response.ok) {  
      throw new Error(\`Failed to fetch auth metadata from ${pdsUrl}\`);  
    }  
      
    const metadata \= await response.json();  
      
    const { authorization\_endpoint, token\_endpoint } \= metadata;  
      
    if (\!authorization\_endpoint ||\!token\_endpoint) {  
      throw new Error('Invalid auth metadata received from PDS.');  
    }  
      
    return {  
      authorizationEndpoint: authorization\_endpoint,  
      tokenEndpoint: token\_endpoint,  
    };  
  } catch (error) {  
    console.error('Error getting auth endpoints:', error);  
    throw new Error('Could not discover OAuth endpoints.');  
  }  
}

**2\. Create lib/auth/jwt.ts**

Create a file at /lib/auth/jwt.ts to mint our app's internal JWT for SurrealDB:

TypeScript

import jwt from 'jsonwebtoken';

/\*\*  
 \* Mints a new JWT for our application's session management.  
 \* This token is what SurrealDB will validate.  
 \*  
 \* @param did \- The user's canonical ATproto DID (e.g., "did:plc:...")  
 \* @param handle \- The user's Bluesky handle (e.g., "user.bsky.social")  
 \* @returns A signed JWT string.  
 \*/  
export function mintSurrealJwt(did: string, handle: string): string {  
  const secret \= process.env.SURREALDB\_JWT\_SECRET;  
  if (\!secret) {  
    throw new Error('SURREALDB\_JWT\_SECRET is not set in environment.');  
  }

  // This payload is critical. The \`did\` claim will be used  
  // in SurrealDB's PERMISSIONS clauses.  
  const payload \= {  
    // Standard JWT claims  
    iss: 'Ponderants',  
    aud: 'SurrealDB',  
      
    // Custom claims  
    did: did,  
    handle: handle,  
  };

  // Token expires in 7 days  
  const token \= jwt.sign(payload, secret, {  
    algorithm: 'HS512',  
    expiresIn: '7d',  
  });

  return token;  
}

**3\. Create Login Page (app/login/page.tsx)**

Create a file at /app/login/page.tsx:

TypeScript

'use client';

import {  
  Button,  
  Center,  
  Paper,  
  Stack,  
  TextInput,  
  Title,  
  Text,  
} from '@mantine/core';  
import { useForm } from '@mantine/form';  
import { useState } from 'react';  
import { useRouter, useSearchParams } from 'next/navigation';

export default function LoginPage() {  
  const \[isLoading, setIsLoading\] \= useState(false);  
  const router \= useRouter();  
  const searchParams \= useSearchParams();  
  const error \= searchParams.get('error');

  const form \= useForm({  
    initialValues: {  
      handle: '',  
    },  
  });

  const handleSubmit \= async (values: { handle: string }) \=\> {  
    setIsLoading(true);  
      
    // We redirect to our \*own\* API route, which will then  
    // perform discovery and redirect to the correct Bluesky PDS.  
    // This keeps all complex logic and secrets on the server.  
    router.push(\`/api/auth/login?handle=${values.handle}\`);  
  };

  return (  
    \<Center h="100vh"\>  
      \<Paper w={400} p="xl"\>  
        \<form onSubmit={form.onSubmit(handleSubmit)}\>  
          \<Stack\>  
            \<Title order={2} ta="center"\>  
              Log in to Ponderants  
            \</Title\>  
            \<Text ta="center" c="dimmed" size="sm"\>  
              Log in with your Bluesky handle.  
            \</Text\>  
              
            {error && (  
              \<Paper withBorder p="sm" bg="red.9"\>  
                \<Text c="white" size="sm"\>  
                  Login Failed: {error}  
                \</Text\>  
              \</Paper\>  
            )}

            \<TextInput  
              label="Your Handle"  
              placeholder="e.g., yourname.bsky.social"  
              required  
              {...form.getInputProps('handle')}  
            /\>  
            \<Button type="submit" loading={isLoading} fullWidth\>  
              Log in with Bluesky  
            \</Button\>  
          \</Stack\>  
        \</form\>  
      \</Paper\>  
    \</Center\>  
  );  
}

**4\. Create Auth Start Route (app/api/auth/login/route.ts)**

Create a file at /app/api/auth/login/route.ts. This route starts the OAuth dance:

TypeScript

import { NextRequest, NextResponse } from 'next/server';  
import { cookies } from 'next/headers';  
import { getAuthEndpoints, resolveHandle } from '@/lib/auth/atproto';  
import { generators } from 'openid-client'; // For PKCE

const CLIENT\_ID \= process.env.BLUESKY\_CLIENT\_ID; // e.g., 'https://ponderants.com/client-metadata.json'  
const REDIRECT\_URI \= process.env.BLUESKY\_REDIRECT\_URI; // e.g., 'http://localhost:3000/api/auth/callback'

export async function GET(request: NextRequest) {  
  if (\!CLIENT\_ID ||\!REDIRECT\_URI) {  
    throw new Error('Bluesky client configuration is missing.');  
  }

  const { searchParams } \= new URL(request.url);  
  const handle \= searchParams.get('handle');

  if (\!handle) {  
    return NextResponse.redirect(new URL('/login?error=Handle missing', request.url));  
  }

  try {  
    // 1\. Resolve handle to get PDS  
    const { pdsUrl } \= await resolveHandle(handle);

    // 2\. Discover PDS-specific auth endpoints  
    const { authorizationEndpoint } \= await getAuthEndpoints(pdsUrl);

    // 3\. Generate PKCE challenge and state  
    const state \= generators.state();  
    const code\_verifier \= generators.codeVerifier();  
    const code\_challenge \= generators.codeChallenge(code\_verifier);

    // 4\. Store verifier and state in a temporary cookie  
    cookies().set('atproto\_oauth\_state', state, { httpOnly: true, maxAge: 600 });  
    cookies().set('atproto\_pkce\_verifier', code\_verifier, { httpOnly: true, maxAge: 600 });  
    cookies().set('atproto\_pds\_url', pdsUrl, { httpOnly: true, maxAge: 600 });

    // 5\. Construct the authorization URL  
    const authUrl \= new URL(authorizationEndpoint);  
    authUrl.searchParams.set('response\_type', 'code');  
    authUrl.searchParams.set('client\_id', CLIENT\_ID);  
    authUrl.searchParams.set('redirect\_uri', REDIRECT\_URI);  
    authUrl.searchParams.set('scope', 'atproto'); // Request full access  
    authUrl.searchParams.set('code\_challenge', code\_challenge);  
    authUrl.searchParams.set('code\_challenge\_method', 'S256');  
    authUrl.searchParams.set('state', state);

    // 6\. Redirect user to the PDS login screen  
    return NextResponse.redirect(authUrl);

  } catch (error) {  
    console.error('Auth login error:', error);  
    return NextResponse.redirect(new URL('/login?error=Invalid handle or PDS', request.url));  
  }  
}

**5\. Create Auth Callback Route (app/api/auth/callback/route.ts)**

Create a file at /app/api/auth/callback/route.ts. This route handles the user's return:

TypeScript

import { NextRequest, NextResponse } from 'next/server';  
import { cookies } from 'next/headers';  
import { getAuthEndpoints } from '@/lib/auth/atproto';  
import { mintSurrealJwt } from '@/lib/auth/jwt';  
import { AtpAgent } from '@atproto/api';

const CLIENT\_ID \= process.env.BLUESKY\_CLIENT\_ID;  
const REDIRECT\_URI \= process.env.BLUESKY\_REDIRECT\_URI;

export async function GET(request: NextRequest) {  
  const { searchParams } \= new URL(request.url);  
  const code \= searchParams.get('code');  
  const state \= searchParams.get('state');

  // Get temporary values from cookies  
  const cookieState \= cookies().get('atproto\_oauth\_state')?.value;  
  const code\_verifier \= cookies().get('atproto\_pkce\_verifier')?.value;  
  const pdsUrl \= cookies().get('atproto\_pds\_url')?.value;

  // Clear temporary cookies  
  cookies().delete('atproto\_oauth\_state');  
  cookies().delete('atproto\_pkce\_verifier');  
  cookies().delete('atproto\_pds\_url');

  // 1\. Validate state (CSRF protection)  
  if (\!state |

| state\!== cookieState) {  
    return NextResponse.redirect(new URL('/login?error=Invalid state', request.url));  
  }

  // 2\. Check for errors  
  if (\!code ||\!pdsUrl ||\!code\_verifier) {  
    return NextResponse.redirect(new URL('/login?error=Callback failed', request.url));  
  }

  try {  
    // 3\. Get the PDS's token endpoint  
    const { tokenEndpoint } \= await getAuthEndpoints(pdsUrl);

    // 4\. Exchange the code for an ATproto access token  
    const tokenResponse \= await fetch(tokenEndpoint, {  
      method: 'POST',  
      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },  
      body: new URLSearchParams({  
        grant\_type: 'authorization\_code',  
        code: code,  
        redirect\_uri: REDIRECT\_URI\!,  
        client\_id: CLIENT\_ID\!,  
        code\_verifier: code\_verifier,  
      }),  
    });

    if (\!tokenResponse.ok) {  
      throw new Error('Failed to exchange code for token');  
    }

    const { access\_token, refresh\_token } \= await tokenResponse.json();

    // 5\. Use the ATproto token to get the user's session info (did, handle)  
    const agent \= new AtpAgent({ service: pdsUrl });  
    agent.resumeSession({  
      accessJwt: access\_token,  
      refreshJwt: refresh\_token,  
      did: '', // We don't know it yet  
      handle: '', // We don't know it yet  
    });  
      
    // getSession will populate the agent with the correct did/handle  
    const session \= await agent.getSession(); 

    if (\!session.did ||\!session.handle) {  
      throw new Error('Failed to retrieve user session details');  
    }

    // 6\. Mint OUR app's SurrealDB JWT  
    const surrealJwt \= mintSurrealJwt(session.did, session.handle);

    // 7\. Set the SurrealDB JWT in a secure cookie for our app  
    cookies().set('ponderants-auth', surrealJwt, {  
      httpOnly: true,  
      secure: process.env.NODE\_ENV \=== 'production',  
      maxAge: 60 \* 60 \* 24 \* 7, // 7 days  
      path: '/',  
    });  
      
    // (Hackathon Strategy: Store the ATproto tokens for later use.  
    // In production, this would go in an encrypted DB store.)  
    cookies().set('atproto\_access\_token', access\_token, {  
      httpOnly: true, secure: process.env.NODE\_ENV \=== 'production', maxAge: 60 \* 60, path: '/',  
    });  
     cookies().set('atproto\_refresh\_token', refresh\_token, {  
      httpOnly: true, secure: process.env.NODE\_ENV \=== 'production', maxAge: 60 \* 60 \* 24 \* 30, path: '/',  
    });

    // 8\. Redirect to the main application  
    return NextResponse.redirect(new URL('/chat', request.url));

  } catch (error) {  
    console.error('Auth callback error:', error);  
    return NextResponse.redirect(new URL('/login?error=Internal auth error', request.url));  
  }  
}

### **Test Specification**

**1\. Create Test File (tests/magnitude/03-auth.mag.ts)**

Create a file at /tests/magnitude/03-auth.mag.ts:

TypeScript

import { test } from 'magnitude-test';

test('\[Happy Path\] User can log in with Bluesky', async (agent) \=\> {  
  // Act: Go to login page  
  await agent.act('Navigate to /login');

  // Act: Enter handle and submit  
  await agent.act(  
    'Enter "testuser.bsky.social" into the "Your Handle" input'  
  );  
  await agent.act('Click the "Log in with Bluesky" button');

  // Check: Verify redirect to our API route  
  // (Magnitude will follow this redirect)  
  // We will mock the external OAuth flow.  
  // We simulate a successful return from Bluesky to our callback.  
  await agent.act(  
    'Simulate a successful OAuth callback by navigating to the /api/auth/callback route with a valid code and state',  
    {  
      // This requires mocking the server's API routes to bypass the  
      // external fetch and PKCE/state verification.  
      // For the hackathon, we can test this by  
      // mocking the 'fetch' and 'cookies' calls.  
        
      // A simpler E2E test for magnitude:  
      // 1\. Mock '/api/auth/login' to redirect to '/api/auth/callback'  
      // 2\. Mock '/api/auth/callback' to return a redirect to '/chat'  
      //    and set the 'ponderants-auth' cookie.  
        
      // Let's assume magnitude can check for redirects and cookies:  
      // The previous 'click' action on 'Log in' (which hits /api/auth/login)  
      // would be mocked to redirect to the external Bluesky URL.  
      // We can't follow that.  
        
      // Let's test the callback handling directly.  
      // We assume the user has already been to Bluesky and is now  
      // hitting our callback.  
      url: '/api/auth/callback?code=mockcode\&state=mockstate',  
        
      // We must mock the server-side logic in the test setup  
      // to validate 'mockstate' and 'mockcode' and return the  
      // final redirect \+ cookie.  
    }  
  );

  // Check: User is redirected to the main app  
  await agent.check('The browser URL is now "http://localhost:3000/chat"');

  // Check: The session cookie is set  
  await agent.check('A secure, httpOnly cookie named "ponderants-auth" is set');  
});

test('\[Unhappy Path\] User sees error on failed auth', async (agent) \=\> {  
  // Act: Simulate a failed callback from Bluesky  
  await agent.act(  
    'Navigate to the /api/auth/callback route with an error',  
    {  
      url: '/api/auth/callback?error=invalid\_grant',  
    }  
  );

  // Check: User is redirected back to the login page  
  await agent.check('The browser URL is now "http://localhost:3000/login"');

  // Check: An error message is displayed  
  await agent.check('The text "Login Failed: Callback failed" is visible');  
});

test('\[Unhappy Path\] User sees error for invalid handle', async (agent) \=\> {  
  // Act: Go to login page  
  await agent.act('Navigate to /login');

  // Act: Enter a non-existent handle  
  await agent.act(  
    'Enter "nonexistent.handle.xyz" into the "Your Handle" input'  
  );  
    
  // (We mock the /api/auth/login route to fail resolution)  
  await agent.act('Click the "Log in with Bluesky" button');

  // Check: User is redirected back to login with an error  
  await agent.check('The browser URL is now "http://localhost:3000/login"');  
  await agent.check('The text "Login Failed: Invalid handle or PDS" is visible');  
});