better-auth AT Protocol (Bluesky) Plugin

Common errors

• TypeError: Cannot read properties of undefined (reading 'split') OR Invalid DPoP Private Key: The privateKey option must be a valid PEM-encoded ES256 private key.

  cause Missing, invalid, or improperly formatted private key provided in a production environment.
  fix Verify that `process.env.BSKY_PRIVATE_KEY` contains the full PEM-encoded ES256 private key string and is correctly passed to the `privateKey` option in `atprotoAuth`.

• Error: Failed to initiate Bluesky sign-in: authClient.signIn.bsky is not a function

  cause The client-side `atprotoAuthClient` plugin was not correctly configured or imported into `createAuthClient`.
  fix Ensure `import { atprotoAuthClient } from 'better-auth-atproto/client';` is used and `atprotoAuthClient()` is passed within the `plugins` array to `createAuthClient`.

• Database error: column "bskyDid" of relation "user" does not exist (or similar schema mismatch error)

  cause Database migrations were not executed after the `better-auth-atproto` plugin was added to the server configuration.
  fix Run `npx auth migrate` in your project's root directory to apply the necessary database schema changes for the plugin.

Warnings

• gotcha The provided README snippet incorrectly suggests 'better-auth-bsky' for installation and client imports. The correct package name for installation and client-side imports is 'better-auth-atproto'.
  Fix: Use `npm install better-auth-atproto` and `import { atprotoAuthClient } from 'better-auth-atproto/client';` consistently.
• gotcha A PEM-encoded ES256 private key is mandatory for production deployments to secure OAuth interactions (DPoP). It is not needed for localhost development due to AT Protocol's loopback client support.
  Fix: Generate a private key (e.g., `openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem`) and provide its contents via the `privateKey` option in `atprotoAuth` configuration for production environments.
• gotcha Database migrations must be run after adding the plugin to your `better-auth` configuration. This extends the `user` table and creates new tables for OAuth state and sessions.
  Fix: Execute `npx auth migrate` (or `npx auth generate` during development) after installing and configuring the plugin.
• gotcha The `baseURL` option is a required global configuration for the core `better-auth` instance. It is used by the plugin to construct callback URLs and auto-hosted discovery endpoint URLs.
  Fix: Ensure `baseURL` is explicitly set in your `betterAuth` configuration, e.g., `baseURL: 'https://myapp.com'`.

Install

• npm install better-auth-atproto npm
• yarn add better-auth-atproto yarn
• pnpm add better-auth-atproto pnpm

Imports

• atprotoAuth
  wrong:

  const atprotoAuth = require('better-auth-atproto');

  correct:

  import { atprotoAuth } from 'better-auth-atproto';

  This is the primary named export for the server-side plugin. The package is ESM-first.
• atprotoAuthClient
  wrong:

  import { atprotoAuthClient } from 'better-auth-atproto';

  correct:

  import { atprotoAuthClient } from 'better-auth-atproto/client';

  The client-side plugin is imported from a specific subpath. The README snippet incorrectly references 'better-auth-bsky/client' due to a likely typo.
• betterAuth
  wrong:

  import betterAuth from 'better-auth';

  correct:

  import { betterAuth } from 'better-auth';

  The core 'better-auth' factory function is a named export, not a default export.
• createAuthClient
  wrong:

  import { createAuthClient } from 'better-auth';

  correct:

  import { createAuthClient } from 'better-auth/client';

  The client-side factory for 'better-auth' is imported from its dedicated client subpath.

Quickstart

This quickstart demonstrates how to integrate the better-auth-atproto plugin on both the server and client sides, including basic configuration with a private key (for production) and initiating a Bluesky sign-in flow.

import { betterAuth } from 'better-auth';
import { atprotoAuth } from 'better-auth-atproto';
import { createAuthClient } from 'better-auth/client';
import { atprotoAuthClient } from 'better-auth-atproto/client';

// 1. (Optional) Generate a private key for production:
// openssl ecparam -name prime256v1 -genkey -noout -out ec-private.pem

// 2. Server-side configuration
export const auth = betterAuth({
  baseURL: process.env.NEXT_PUBLIC_BASE_URL || 'http://localhost:3000', // Required for callbacks and discovery endpoints
  plugins: [
    atprotoAuth({
      privateKey: process.env.BSKY_PRIVATE_KEY ?? '', // Required for production, optional for localhost
      clientMetadata: {
        clientName: 'My Awesome App',
        scope: 'atproto transition:generic'
      },
      mapProfileToUser: (profile) => ({
        name: profile.displayName || `@${profile.handle}`,
        image: profile.avatar,
      }),
    }),
  ],
});

// 3. Run migrations after adding plugin: `npx auth migrate` or `npx auth generate`

// 4. Client-side configuration
export const authClient = createAuthClient({
  plugins: [atprotoAuthClient()],
});

// 5. Example client-side sign-in flow
async function initiateSignIn(handle: string, callbackURL: string) {
  try {
    await authClient.signIn.bsky({
      handle: handle,
      callbackURL: callbackURL,
    });
    console.log('Bluesky sign-in initiated successfully!');
  } catch (error) {
    console.error('Failed to initiate Bluesky sign-in:', error);
  }
}

// Example usage (e.g., in a React component or server action)
// initiateSignIn('example.bsky.social', '/dashboard');