atproto-better-auth 0.1.0

package/README.md

@@ -0,0 +1,348 @@
+# atproto-better-auth
+
+A [better-auth](https://better-auth.com) plugin for authenticating with [ATProto](https://atproto.com)/[Bluesky](https://bsky.app).
+
+## Repository Structure
+
+This is a monorepo containing:
+
+- `packages/atproto-better-auth` - The main plugin package
+- `apps/example` - A Next.js example application
+
+To get started with the example, see [apps/example/README.md](./apps/example/README.md).
+
+## Features
+
+- Full ATProto OAuth support (PKCE, PAR, DPoP)
+- Automatic token refresh
+- Account linking with existing users
+- Server-side Agent restoration for API calls
+- TypeScript support
+
+## Installation
+
+```bash
+bun add atproto-better-auth
+# or
+npm install atproto-better-auth
+# or
+pnpm add atproto-better-auth
+```
+
+## Prerequisites
+
+### 1. Generate an ES256 Key Pair
+
+ATProto OAuth requires an ES256 (ECDSA P-256) key pair. You can generate one using the included utility:
+
+```typescript
+import { generateES256Key } from "atproto-better-auth";
+
+const privateKey = await generateES256Key();
+console.log(JSON.stringify(privateKey, null, 2));
+```
+
+Or generate one at [jwkset.com/generate](https://jwkset.com/generate):
+
+- **Key type**: ECDSA
+- **Key algorithm**: ES256
+
+The key should look like:
+
+```json
+{
+  "kty": "EC",
+  "alg": "ES256",
+  "kid": "your-key-id",
+  "crv": "P-256",
+  "x": "...",
+  "y": "...",
+  "d": "..." 
+}
+```
+
+> **Important**: Keep the `"d"` field secret! This is your private key.
+
+### 2. Host Required Endpoints
+
+ATProto OAuth requires two publicly accessible JSON endpoints:
+
+#### `/client-metadata.json`
+
+Your OAuth client metadata. The URL to this file becomes your `client_id`.
+
+#### `/jwks.json`
+
+Your public key(s) in JWKS format. This is your private key **without** the `"d"` field.
+
+See [Setup Examples](#setup-examples) below for how to create these endpoints.
+
+## Quick Start
+
+### Server Setup
+
+```typescript
+// lib/auth.ts
+import { betterAuth } from "better-auth";
+import { atprotoAuth } from "atproto-better-auth";
+
+// Your ES256 private key (store securely, e.g., in environment variables)
+const privateKey = JSON.parse(process.env.ATPROTO_PRIVATE_KEY!);
+
+export const auth = betterAuth({
+  database: {
+    // Your database configuration
+  },
+  plugins: [
+    atprotoAuth({
+      clientMetadata: {
+        clientId: "https://yourapp.com/client-metadata.json",
+        clientName: "Your App Name",
+        clientUri: "https://yourapp.com",
+        redirectUris: ["https://yourapp.com/api/auth/callback/atproto"],
+        jwksUri: "https://yourapp.com/jwks.json",
+        // Optional
+        logoUri: "https://yourapp.com/logo.png",
+        tosUri: "https://yourapp.com/terms",
+        policyUri: "https://yourapp.com/privacy",
+      },
+      privateKey,
+    }),
+  ],
+});
+```
+
+### Client Setup
+
+```typescript
+// lib/auth-client.ts
+import { createAuthClient } from "better-auth/client";
+import { atprotoAuthClient } from "atproto-better-auth/client";
+
+export const authClient = createAuthClient({
+  plugins: [atprotoAuthClient()],
+});
+```
+
+### Sign In
+
+```typescript
+// In your component/page
+import { authClient } from "@/lib/auth-client";
+
+function SignInButton() {
+  const handleSignIn = () => {
+    authClient.signIn.atproto({
+      handle: "user.bsky.social", // The user's Bluesky handle
+      callbackURL: "/dashboard",  // Where to redirect after auth
+    });
+  };
+
+  return <button onClick={handleSignIn}>Sign in with Bluesky</button>;
+}
+```
+
+## Setup Examples
+
+### Next.js App Router
+
+#### `/app/client-metadata.json/route.ts`
+
+```typescript
+import { createClientMetadataHandler } from "atproto-better-auth";
+
+const privateKey = JSON.parse(process.env.ATPROTO_PRIVATE_KEY!);
+
+const options = {
+  clientMetadata: {
+    clientId: "https://yourapp.com/client-metadata.json",
+    clientName: "Your App",
+    redirectUris: ["https://yourapp.com/api/auth/callback/atproto"],
+    jwksUri: "https://yourapp.com/jwks.json",
+  },
+  privateKey,
+};
+
+export const GET = createClientMetadataHandler(options);
+```
+
+#### `/app/jwks.json/route.ts`
+
+```typescript
+import { createJwksHandler } from "atproto-better-auth";
+
+const privateKey = JSON.parse(process.env.ATPROTO_PRIVATE_KEY!);
+
+export const GET = createJwksHandler(privateKey);
+```
+
+### Express/Hono/Other Frameworks
+
+```typescript
+import { createClientMetadata, createJwks } from "atproto-better-auth";
+
+// Serve client metadata
+app.get("/client-metadata.json", (req, res) => {
+  const metadata = createClientMetadata(authOptions);
+  res.json(metadata);
+});
+
+// Serve JWKS
+app.get("/jwks.json", (req, res) => {
+  const jwks = createJwks(privateKey);
+  res.json(jwks);
+});
+```
+
+## API Reference
+
+### Server Plugin Options
+
+```typescript
+interface AtprotoAuthOptions {
+  clientMetadata: {
+    clientId: string;        // URL to your client-metadata.json
+    clientName: string;      // Your app's display name
+    clientUri?: string;      // Your app's homepage
+    logoUri?: string;        // URL to your logo
+    tosUri?: string;         // Terms of service URL
+    policyUri?: string;      // Privacy policy URL
+    redirectUris: string[];  // OAuth callback URLs
+    jwksUri?: string;        // URL to your JWKS endpoint
+    scope?: string;          // OAuth scopes (default: "atproto transition:generic")
+  };
+  
+  privateKey: ES256PrivateJwk;  // Your ES256 private key
+  
+  callbackPath?: string;        // Custom callback path (default: "/api/auth/callback/atproto")
+  
+  mapProfileToUser?: (profile: AtprotoProfile) => Partial<User>;  // Custom profile mapping
+}
+```
+
+### Client Methods
+
+```typescript
+// Sign in with ATProto
+authClient.signIn.atproto({
+  handle: string;       // User's ATProto handle
+  callbackURL?: string; // Redirect URL after auth
+});
+
+// Get current ATProto session info
+const { session } = await authClient.atproto.getSession();
+// session: { did, handle, displayName, avatar, active } | null
+
+// Restore/refresh ATProto session
+const result = await authClient.atproto.restore();
+// result: { did, active } | { error }
+```
+
+### Utility Functions
+
+```typescript
+import {
+  generateES256Key,      // Generate a new ES256 key pair
+  getPublicJwk,          // Extract public key from private key
+  createJwks,            // Create JWKS object for endpoint
+  createClientMetadata,  // Create client metadata for endpoint
+  isValidES256PrivateKey // Validate a JWK is a valid ES256 private key
+} from "atproto-better-auth";
+```
+
+## Database Schema
+
+The plugin extends the `user` table and adds two new tables:
+
+### User Table Extensions
+
+| Column | Type | Description |
+|--------|------|-------------|
+| atprotoDid | string | User's ATProto DID (unique) |
+| atprotoHandle | string | User's handle (e.g., `alice.bsky.social`) |
+| atprotoBio | string | User's bio/description |
+| atprotoBanner | string | URL to banner/cover image |
+
+### `atprotoState`
+
+Stores temporary OAuth state during authorization flow.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| key | string | State key |
+| state | string | Serialized OAuth state |
+| expiresAt | date | Expiration timestamp |
+
+### `atprotoSession`
+
+Stores ATProto OAuth sessions (tokens, DPoP keys, etc.).
+
+| Column | Type | Description |
+|--------|------|-------------|
+| did | string | ATProto DID |
+| session | string | Serialized session data |
+| userId | string | Foreign key to user |
+| updatedAt | date | Last update timestamp |
+
+Run your database migrations after adding the plugin to create these tables and columns.
+
+## Server-Side API Calls
+
+After authentication, you can make ATProto API calls on behalf of the user:
+
+```typescript
+import { Agent } from "@atproto/api";
+import { auth } from "@/lib/auth";
+
+async function postToBluesky(userId: string, text: string) {
+  // Get the user's ATProto account
+  const account = await auth.api.getAccount({
+    userId,
+    providerId: "atproto",
+  });
+
+  if (!account) {
+    throw new Error("User not connected to ATProto");
+  }
+
+  // The OAuth client handles token refresh automatically
+  // You'll need to restore the session from the oauth client
+  // This is handled internally by the plugin's session store
+}
+```
+
+## Local Development
+
+For local development, you need a publicly accessible URL for ATProto servers to fetch your client metadata. Options:
+
+1. **ngrok**: `ngrok http 3000`
+2. **Cloudflare Tunnel**: `cloudflared tunnel`
+3. **localtunnel**: `lt --port 3000`
+
+Update your `clientId` and `redirectUris` to use the tunnel URL.
+
+## Security Notes
+
+1. **Never expose your private key** - The `"d"` field in your JWK is your private key. Only the public key (without `"d"`) should be in your JWKS endpoint.
+
+2. **Store keys securely** - Use environment variables or a secrets manager for your private key.
+
+3. **Use HTTPS in production** - ATProto OAuth requires HTTPS URLs for client metadata and callbacks.
+
+4. **Key rotation** - Include a `kid` (Key ID) in your JWK to support key rotation.
+
+## How ATProto OAuth Works
+
+Unlike traditional OAuth where you register with a central provider, ATProto is decentralized:
+
+1. **Self-hosted metadata**: Your app hosts its own client metadata at a public URL
+2. **Dynamic discovery**: ATProto servers fetch your metadata to verify your app
+3. **DPoP tokens**: Access tokens are bound to cryptographic proofs
+4. **Handle resolution**: User handles are resolved to find their PDS (Personal Data Server)
+5. **Account portability**: Users can migrate between servers while keeping their identity
+
+This plugin handles all of this complexity using the official `@atproto/oauth-client-node` package.
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,42 @@
+import type { AtprotoSessionInfo, AtprotoSignInParams } from "./types.js";
+import type { atprotoAuth } from "./server.js";
+/**
+ * Client-side ATProto authentication plugin for better-auth.
+ */
+export declare const atprotoAuthClient: () => {
+    id: "atproto";
+    $InferServerPlugin: ReturnType<typeof atprotoAuth>;
+    getActions($fetch: import("better-auth/client").BetterFetch): {
+        /**
+         * Sign in with ATProto/Bluesky
+         */
+        signIn: {
+            atproto: (params: AtprotoSignInParams) => Promise<void>;
+        };
+        atproto: {
+            /**
+             * Get the current ATProto session information
+             */
+            getSession: () => Promise<{
+                session: AtprotoSessionInfo | null;
+            }>;
+            /**
+             * Restore/refresh the ATProto session
+             * Useful to ensure the session is valid before making API calls
+             */
+            restore: () => Promise<{
+                did: string;
+                active: boolean;
+            } | {
+                error: string;
+            }>;
+        };
+    };
+    pathMethods: {
+        "/atproto/sign-in": "GET";
+        "/callback/atproto": "GET";
+        "/atproto/session": "GET";
+        "/atproto/restore": "POST";
+    };
+};
+export type { AtprotoSessionInfo, AtprotoSignInParams };

package/dist/client.js

@@ -0,0 +1,52 @@
+// src/client.ts
+var atprotoAuthClient = () => {
+  return {
+    id: "atproto",
+    $InferServerPlugin: {},
+    getActions($fetch) {
+      return {
+        signIn: {
+          atproto: async (params) => {
+            const { handle, callbackURL } = params;
+            const searchParams = new URLSearchParams({ handle });
+            if (callbackURL) {
+              searchParams.set("callbackURL", callbackURL);
+            }
+            if (typeof window !== "undefined") {
+              window.location.href = `/api/auth/atproto/sign-in?${searchParams.toString()}`;
+            }
+          }
+        },
+        atproto: {
+          getSession: async () => {
+            const response = await $fetch("/atproto/session", {
+              method: "GET"
+            });
+            if (!response.data) {
+              return { session: null };
+            }
+            return response.data;
+          },
+          restore: async () => {
+            const response = await $fetch("/atproto/restore", {
+              method: "POST"
+            });
+            if (!response.data) {
+              return { error: response.error?.message ?? "Unknown error" };
+            }
+            return response.data;
+          }
+        }
+      };
+    },
+    pathMethods: {
+      "/atproto/sign-in": "GET",
+      "/callback/atproto": "GET",
+      "/atproto/session": "GET",
+      "/atproto/restore": "POST"
+    }
+  };
+};
+export {
+  atprotoAuthClient
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ATProto Better-Auth Plugin
+ *
+ * A better-auth plugin for authenticating with ATProto/Bluesky.
+ *
+ * @example
+ * ```ts
+ * import { betterAuth } from "better-auth";
+ * import { atprotoAuth } from "atproto-better-auth";
+ *
+ * export const auth = betterAuth({
+ *   plugins: [
+ *     atprotoAuth({
+ *       clientMetadata: {
+ *         clientId: "https://myapp.com/client-metadata.json",
+ *         clientName: "My App",
+ *         redirectUris: ["https://myapp.com/api/auth/callback/atproto"],
+ *       },
+ *       privateKey: JSON.parse(process.env.ATPROTO_PRIVATE_KEY!),
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export { atprotoAuth } from "./server.js";
+export { atprotoSchema, atprotoUserSchema, atprotoStateSchema, atprotoSessionSchema } from "./schema.js";
+export type { AtprotoAuthOptions, AtprotoClientMetadata, AtprotoClientMetadataInput, AtprotoProfile, AtprotoSessionInfo, AtprotoSignInParams, AtprotoStateRecord, AtprotoSessionRecord, ES256PrivateJwk, ES256PublicJwk, } from "./types.js";
+export { getPublicJwk, createJwks, createClientMetadata, generateES256Key, isValidES256PrivateKey, createClientMetadataHandler, createJwksHandler, DEFAULT_ATPROTO_SCOPES, } from "./utils.js";
+export type { CreateClientMetadataOptions } from "./utils.js";