better-auth-bsky

A better-auth plugin for Bluesky / AT Protocol OAuth. Sign in with Bluesky, persist atproto sessions, and make authenticated API calls on behalf of users.

Features

• Sign in with Bluesky via AT Protocol OAuth (PKCE + DPoP)
• Localhost development without tunnels (loopback client support)
• Auto-hosted client metadata and JWKS endpoints
• DB-backed OAuth state and session stores
• Account linking for users who are already signed in
• Session restoration for making authenticated atproto API calls
• Profile sync (handle, display name, avatar, bio, banner)

Install

npm install better-auth-bsky
# or
bun add better-auth-bsky

Quick Start

1. Generate a private key (production)

openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem

For localhost development, no key is needed.

2. Server plugin

import { betterAuth } from "better-auth";
import { atprotoAuth } from "better-auth-atproto";

export const auth = betterAuth({
  // baseURL is required
  baseURL: "https://myapp.com",
  plugins: [
    atprotoAuth({
      privateKey: process.env.BSKY_PRIVATE_KEY, // contents of ec-private.pem
    }),
  ],
});

3. Run migrations

The plugin adds columns to the user table and creates two new tables. Run migrations after adding the plugin:

npx auth migrate
# or
npx auth generate

4. Client plugin

import { createAuthClient } from "better-auth/client";
import { atprotoAuthClient } from "better-auth-bsky/client";

export const authClient = createAuthClient({
  plugins: [atprotoAuthClient()],
});

5. Sign in

await authClient.signIn.bsky({
  handle: "thepope.dev",
  callbackURL: "/dashboard",
});

Configuration

atprotoAuth({
  // PEM-encoded ES256 private key.
  // Required for production. Optional for localhost.
  privateKey: process.env.BSKY_PRIVATE_KEY,

  clientMetadata: {
    // Name shown on the authorization screen.
    clientName: "My App",
    // OAuth scopes. Default: "atproto transition:generic"
    scope: "atproto transition:generic",
  },

  // Customize how the atproto profile maps to better-auth user fields.
  mapProfileToUser: (profile) => ({
    name: profile.displayName || `@${profile.handle}`,
    image: profile.avatar,
  }),

  // Prevent new user creation. Only existing users can sign in.
  disableSignUp: false,
});

Localhost Development

For local development, no private key or tunnel is needed. The plugin uses AT Protocol's loopback client mode automatically when baseURL is http://localhost:* or http://127.0.0.1:*.

export const auth = betterAuth({
  baseURL: "http://localhost:3000",
  plugins: [
    atprotoAuth(), // no privateKey needed
  ],
});

Production Setup

For production deployments, the plugin auto-hosts two discovery endpoints that the AT Protocol PDS needs to verify your app's identity:

| Endpoint | URL | | --------------- | ---------------------------------------------- | | Client Metadata | {baseURL}/api/auth/bsky/client-metadata.json | | JWKS | {baseURL}/api/auth/bsky/jwks.json |

These are served automatically. No extra routes needed.

Database Schema

The plugin extends the user table and adds two new tables:

User table extensions

| Column | Type | Description | | ------------ | --------------- | -------------------------------------- | | bskyDid | string (unique) | AT Protocol DID (did:plc:...) | | bskyHandle | string | Bluesky handle (thepope.bsky.social) | | bskyBio | string | Profile description | | bskyBanner | string | Banner image URL |

bskyState table

Ephemeral storage for in-flight OAuth requests (auto-expires after 10 minutes).

| Column | Type | | ----------- | --------------- | | key | string (unique) | | state | string (JSON) | | expiresAt | date |

bskySession table

Persistent storage for atproto OAuth sessions (tokens, DPoP keys).

| Column | Type | | ----------- | ------------------------------- | | did | string (unique) | | session | string (JSON) | | userId | string (FK -> user.id, cascade) | | updatedAt | date |

API

Endpoints

| Method | Path | Auth | Description | | ------ | ---------------------------- | ---- | -------------------------------------------------- | | GET | /bsky/client-metadata.json | No | OAuth client metadata for PDS discovery | | GET | /bsky/jwks.json | No | Public JWKS for private_key_jwt auth | | POST | /bsky/sign-in | No | Initiate sign-in. Body: { handle, callbackURL? } | | GET | /bsky/callback | No | OAuth callback (handled automatically) | | GET | /bsky/session | Yes | Get atproto session status + fresh profile | | POST | /bsky/restore | Yes | Restore atproto session (lightweight check) |

Client Actions

// Sign in with Bluesky handle
await authClient.signIn.bsky({
  handle: "thepope.dev",
  callbackURL: "/dashboard", // where to redirect after auth
});

// Get atproto session status and fresh profile data
const { data } = await authClient.bsky.getSession();
// { active: true, did: "did:plc:...", handle: "thepope.dev", ... }

// Lightweight session check (no profile fetch)
const { data } = await authClient.bsky.restore();
// { active: true, did: "did:plc:..." }

Account Linking

If a user is already signed in with another provider (email, Google, etc.) and then signs in with Bluesky, the plugin automatically links the Bluesky account to their existing user rather than creating a duplicate.

This respects better-auth's account.accountLinking.enabled setting. If account linking is disabled in your config, the plugin will return a FORBIDDEN error instead of linking.

Security

The plugin applies rate limiting to sensitive endpoints by default:

| Endpoint | Window | Max Requests | | ---------------- | ------ | ------------ | | /bsky/sign-in | 60s | 5 | | /bsky/callback | 60s | 10 |

These limits protect against brute-force handle resolution and callback replay. Metadata endpoints (/bsky/client-metadata.json, /bsky/jwks.json) are not rate limited.

The disableSignUp option prevents new user creation, restricting the plugin to sign-in for existing users and account linking only:

atprotoAuth({
  disableSignUp: true, // returns FORBIDDEN for unknown DIDs
});

How It Works

1. User enters their Bluesky handle and clicks sign in
2. The plugin resolves the handle to a DID, discovers their PDS authorization server
3. User is redirected to their PDS to authenticate (OAuth 2.0 + PKCE + DPoP)
4. PDS redirects back to /bsky/callback
5. Plugin exchanges the code for tokens, fetches the user's profile
6. Creates or links the better-auth user/account, sets the session cookie
7. Redirects to the app's callbackURL

The atproto OAuth session (including DPoP-bound tokens) is persisted in the bskySession table, allowing token refresh and authenticated API calls via session restoration.

License

MIT