@proofkit/better-auth/skills/better-auth-setup/SKILL.md

FileMaker adapter for Better Auth

---
name: better-auth-setup
description: >
  Set up self-hosted authentication with better-auth using FileMaker as the
  database backend. Covers FileMakerAdapter, FMServerConnection, betterAuth
  config, migration via npx @proofkit/better-auth migrate, OData prerequisites,
  fmodata privilege, Full Access credentials for schema modification, plugin
  migration workflow, troubleshooting "filemaker is not supported" errors.
metadata:
  type: core
  library: proofkit
  library_version: "0.4.2"
requires:
  - fmodata-client
sources:
  - "proofsh/proofkit:packages/better-auth/src/*.ts"
  - "proofsh/proofkit:apps/docs/content/docs/better-auth/*.mdx"
---

## Setup

### Prerequisites

- OData enabled on FileMaker Server
- API credentials with `fmodata` privilege enabled
- Read/write access to the better-auth tables
- Full Access credentials available for schema migration (can differ from runtime credentials)

### Install packages

```bash
pnpm add @proofkit/better-auth @proofkit/fmodata
```

### Configure auth.ts

```ts
import { betterAuth } from "better-auth";
import { FMServerConnection } from "@proofkit/fmodata";
import { FileMakerAdapter } from "@proofkit/better-auth";

const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER_URL!,
  auth: {
    username: process.env.FM_USERNAME!,
    password: process.env.FM_PASSWORD!,
  },
});

const db = connection.database(process.env.FM_DATABASE!);

export const auth = betterAuth({
  database: FileMakerAdapter({ database: db }),
  // add plugins, social providers, etc.
});
```

`FileMakerAdapter` accepts a `FileMakerAdapterConfig`:

- `database` (required) -- an fmodata `Database` instance
- `debugLogs` (optional) -- enable adapter debug logging
- `usePlural` (optional) -- set `true` if table names are plural

The adapter maps Better Auth operations (create, findOne, findMany, update, delete, count) to OData requests via `db._makeRequest`. It does not support JSON columns, native dates, or native booleans -- all values are stored as strings/numbers.

### Alternative: Data API key (OttoFMS 4.11+)

```ts
const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER_URL!,
  auth: {
    apiKey: process.env.OTTO_API_KEY!,
  },
});
```

OData must be enabled for the key.

## Core Patterns

### 1. Initial migration

After configuring `auth.ts`, run the migration CLI to create tables and fields in FileMaker:

```bash
npx @proofkit/better-auth migrate
```

The CLI:

1. Loads your `auth.ts` config (auto-detected or via `--config <path>`)
2. Calls `getSchema()` from `better-auth/db` to determine required tables/fields
3. Fetches current OData metadata via `db.getMetadata()`
4. Computes a diff: tables to create, fields to add to existing tables
5. Prints the migration plan and prompts for confirmation
6. Executes via `db.schema.createTable()` and `db.schema.addFields()`

Only schema is modified. No layouts or relationships are created.

If your runtime credentials lack Full Access, override for migration only:

```bash
npx @proofkit/better-auth migrate --username "admin" --password "admin_pass"
```

Skip confirmation with `-y`:

```bash
npx @proofkit/better-auth migrate -y
```

### 2. Adding plugins and re-migrating

When you add a Better Auth plugin (e.g. `twoFactor`, `organization`), it declares additional tables/fields. After updating `auth.ts`:

```ts
import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";
import { FMServerConnection } from "@proofkit/fmodata";
import { FileMakerAdapter } from "@proofkit/better-auth";

const connection = new FMServerConnection({
  serverUrl: process.env.FM_SERVER_URL!,
  auth: {
    username: process.env.FM_USERNAME!,
    password: process.env.FM_PASSWORD!,
  },
});

const db = connection.database(process.env.FM_DATABASE!);

export const auth = betterAuth({
  database: FileMakerAdapter({ database: db }),
  plugins: [twoFactor()],
});
```

Re-run migration:

```bash
npx @proofkit/better-auth migrate
```

The planner diffs against existing metadata, so only new tables/fields are added. Existing tables are left untouched.

### 3. Troubleshooting privilege errors

When migration fails with OData error code `207`, the account lacks schema modification privileges. The CLI outputs:

```
Failed to create table "tableName": Cannot modify schema.
The account used does not have schema modification privileges.
Use --username and --password to provide Full Access credentials.
```

Fix: provide Full Access credentials via CLI flags. These are only used for migration, not at runtime.

## Common Mistakes

### [CRITICAL] Using better-auth CLI instead of @proofkit/better-auth

Wrong:
```bash
npx better-auth migrate
```

Correct:
```bash
npx @proofkit/better-auth migrate
```

The standard better-auth CLI does not know about the FileMaker adapter and produces: `ERROR [Better Auth]: filemaker is not supported. If it is a custom adapter, please request the maintainer to implement createSchema`. The `@proofkit/better-auth` CLI loads your auth config, extracts the `Database` instance from the adapter, and handles migration via fmodata's schema API.

Source: `apps/docs/content/docs/better-auth/troubleshooting.mdx`

### [HIGH] Missing Full Access credentials for schema migration

Wrong:
```bash
# Using runtime credentials that only have fmodata privilege
npx @proofkit/better-auth migrate
# Fails with OData error 207: Cannot modify schema
```

Correct:
```bash
npx @proofkit/better-auth migrate --username "full_access_user" --password "full_access_pass"
```

Schema modification (`db.schema.createTable`, `db.schema.addFields`) requires [Full Access] privileges. Standard API accounts with `fmodata` privilege can read/write data but cannot alter schema. The CLI accepts `--username` and `--password` flags to override credentials for migration only.

Source: `packages/better-auth/src/cli/index.ts`, `packages/better-auth/src/migrate.ts`

### [HIGH] Removing fields added by migration

Wrong:
```
Manually deleting "unused" fields from better-auth tables in FileMaker
```

Correct:
```
Keep all fields created by migration, even if you don't plan to use them
```

Better Auth expects all schema fields to exist at runtime. The adapter issues OData requests that reference these fields. Removing them causes runtime errors when Better Auth attempts to read or write those columns.

Source: `apps/docs/content/docs/better-auth/installation.mdx`

### [HIGH] Forgetting to re-run migration after adding plugins

Wrong:
```ts
// Added twoFactor() plugin to auth.ts but did not re-run migration
export const auth = betterAuth({
  database: FileMakerAdapter({ database: db }),
  plugins: [twoFactor()],
});
// Runtime errors: tables/fields for twoFactor don't exist
```

Correct:
```bash
# After adding any plugin to auth.ts, always re-run:
npx @proofkit/better-auth migrate
```

Each plugin declares additional tables and fields via `getSchema()`. The migration planner diffs the full schema (including plugins) against current OData metadata. Without re-running, the new tables/fields don't exist and Better Auth throws at runtime.

Source: `apps/docs/content/docs/better-auth/installation.mdx`

## References

- **fmodata-client** -- Better Auth uses fmodata `Database` under the hood for all OData requests. `FMServerConnection` and `database()` must be configured before `FileMakerAdapter` can work. The adapter calls `db._makeRequest()` for CRUD and `db.schema.*` for migrations.