@openfort/better-auth

A Better Auth plugin for integrating Openfort wallets into your authentication flow.

Features

• Encryption Session Support: Securely create encryption sessions for wallet recovery
• Seamless Integration: Works with Better Auth's authentication flow
• TypeScript Support: Fully typed for better developer experience

Installation

pnpm add better-auth @openfort/better-auth @openfort/openfort-node

Setup

1. Get Your Openfort Credentials

Go to your Openfort Dashboard and get:

• Your Openfort API key for the SDK client
• Your Shield API key and Shield secret key for encryption session management
• Your encryption part (from your Shield configuration)

# .env
OPENFORT_API_KEY=sk_test_...
SHIELD_API_KEY=...
SHIELD_SECRET_KEY=...
SHIELD_ENCRYPTION_PART=...

2. Configure BetterAuth Server

import { betterAuth } from "better-auth";
import { openfort, encryptionSession } from "@openfort/better-auth";
import Openfort from "@openfort/openfort-node";

const openfortClient = new Openfort("sk_test_...");

const auth = betterAuth({
  // ... Better Auth config
  plugins: [
    openfort({
      client: openfortClient,
      use: [
        encryptionSession({
          config: {
            apiKey: process.env.SHIELD_API_KEY!,
            secretKey: process.env.SHIELD_SECRET_KEY!,
            encryptionPart: process.env.SHIELD_ENCRYPTION_PART!,
          },
        }),
      ],
    }),
  ],
});

3. Configure BetterAuth Client

import { createAuthClient } from "better-auth/react";
import { openfortClient } from "@openfort/better-auth";

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

Usage

Encryption Session

The encryption session plugin allows authenticated users to create secure encryption sessions for wallet recovery.

Server Configuration

The encryptionSession plugin is included in the use array and requires the encryption session configuration:

encryptionSession({
  config: {
    apiKey: process.env.SHIELD_API_KEY!,
    secretKey: process.env.SHIELD_SECRET_KEY!,
    encryptionPart: process.env.SHIELD_ENCRYPTION_PART!,
    shieldAPIBaseURL: "https://shield.openfort.io", // Optional
  },
})

Client Usage

import { authClient } from "./auth-client";

// Create an encryption session
try {
  const { sessionId, success } = await authClient.createEncryptionSession();

  console.log("Encryption session created:", sessionId);
} catch (error) {
  console.error("Failed to create encryption session:", error);
}

Configuration Options

Main Plugin Options

interface OpenfortOptions {
  // Required: Openfort client instance
  client: Openfort;

  // Required: Array of Openfort plugins to use
  use: OpenfortPlugins;
}

Encryption Session Plugin Options

interface EncryptionSessionOptions {
  config?: {
    apiKey: string; // Shield API Key
    secretKey: string; // Shield Secret Key
    encryptionPart: string; // Encryption part from Shield configuration
    shieldAPIBaseURL?: string; // Default: 'https://shield.openfort.io'
  };
}

API Reference

Server-Side

openfort(options)

Creates the main Openfort plugin for Better Auth.

encryptionSession(options)

Creates an encryption session endpoint at /encryption-session.

Client-Side

openfortClient()

Creates the client-side plugin for Better Auth.

authClient.createEncryptionSession()

Creates an encryption session for the authenticated user using the encryption part configured on the server.

Parameters:

• fetchOptions (optional): BetterAuth fetch options

Returns:

{
  sessionId: string;
  success: boolean;
}

Examples

Basic Setup

// server/auth.ts
import { betterAuth } from "better-auth";
import { openfort, encryptionSession } from "@openfort/better-auth";
import Openfort from "@openfort/openfort-node";

const openfortClient = new Openfort(process.env.OPENFORT_API_KEY!);

export const auth = betterAuth({
  database: {
    // ... your database config
  },
  plugins: [
    openfort({
      client: openfortClient,
      use: [
        encryptionSession({
          config: {
            apiKey: process.env.SHIELD_API_KEY!,
            secretKey: process.env.SHIELD_SECRET_KEY!,
            encryptionPart: process.env.SHIELD_ENCRYPTION_PART!,
          },
        }),
      ],
    }),
  ],
});

// client/auth.ts
import { createAuthClient } from "better-auth/react";
import { openfortClient } from "@openfort/better-auth";

export const authClient = createAuthClient({
  baseURL: "http://localhost:3000",
  plugins: [openfortClient()],
});

Using Encryption Sessions

// In your React component
import { authClient } from "./auth";

async function setupWallet() {
  try {
    const result = await authClient.createEncryptionSession();

    if (result.success) {
      console.log("Wallet setup complete. Session ID:", result.sessionId);
    }
  } catch (error) {
    console.error("Wallet setup failed:", error);
  }
}

License

Apache-2.0