feat: configure BetterAuth with org and API key plugins

Author: richiemcilroy

apps/api/package.json

@@ -8,5 +8,12 @@
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "test": "echo 'no tests yet'"
+  },
+  "dependencies": {
+    "better-auth": "^1.4.18",
+    "mysql2": "^3.17.4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0"
   }
 }

apps/api/src/auth-client.ts

@@ -0,0 +1,6 @@
+import { createAuthClient } from 'better-auth/client'
+import { organizationClient, apiKeyClient } from 'better-auth/client/plugins'
+
+export const authClient = createAuthClient({
+  plugins: [organizationClient(), apiKeyClient()],
+})

apps/api/src/auth.ts

@@ -0,0 +1,28 @@
+import { betterAuth } from 'better-auth'
+import { organization, apiKey } from 'better-auth/plugins'
+import { createPool } from 'mysql2/promise'
+
+export const auth = betterAuth({
+  database: createPool({
+    uri: process.env.DATABASE_URL!,
+    waitForConnections: true,
+    connectionLimit: 10,
+  }),
+  emailAndPassword: { enabled: true },
+  socialProviders: {
+    github: {
+      clientId: process.env.GITHUB_CLIENT_ID!,
+      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    },
+    google: {
+      clientId: process.env.GOOGLE_CLIENT_ID!,
+      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    },
+  },
+  plugins: [
+    organization(),
+    apiKey({
+      enableMetadata: true,
+    }),
+  ],
+})

apps/api/src/index.ts

@@ -1 +1,2 @@
-export {}
+export { auth } from './auth.js'
+export { authClient } from './auth-client.js'

bun.lock

@@ -789,7 +789,7 @@ From `docs/spec/09-infrastructure.md` → "Build tooling" and `docs/spec/11-mile
 
 ## Task 9: Set up BetterAuth with organization and API key plugins
 
-- [ ] **Status**: Pending
+- [x] **Status**: Done
 - **Commit type**: `feat`
 - **Commit message**: `feat: configure BetterAuth with org and API key plugins`
 
@@ -870,4 +870,10 @@ Reference `docs/spec/10-security.md` → "Authentication" and `docs/spec/08-data
 - Auth config includes `organization()` plugin
 
 ### Learnings
-<!-- Filled in after completion -->
+- BetterAuth v1.4.18 uses `mysql2/promise` `createPool()` directly as its database adapter — the `{ type: 'mysql', url }` shorthand from some docs is not the preferred approach for mysql2
+- `@better-auth/cli generate` requires a running MySQL database to introspect existing schema — migration SQL was hand-written based on BetterAuth source code schema definitions since no local MySQL is available
+- Organization plugin adds `activeOrganizationId` column to the `session` table for tracking which org a user is operating in
+- API key plugin has built-in rate limiting columns (`rateLimitEnabled`, `rateLimitTimeWindow`, `rateLimitMax`, `requestCount`) — separate from Redis-backed rate limiting at the API layer
+- `enableMetadata: true` on apiKey plugin allows storing `org_id` and `environment` in the `metadata` JSON column for org/env scoping
+- `@types/node` needed as devDependency in `apps/api` since `process.env` is used for config
+- All BetterAuth tables use `VARCHAR(36)` string IDs (not UUIDv7/BINARY(16)) — consistent with the spec's guidance that BetterAuth owns its ID format

docs/spec/phases/phase-1.md

@@ -0,0 +1,109 @@
+-- BetterAuth schema migration
+-- Generated from better-auth v1.4.18 with organization + apiKey plugins
+-- DO NOT hand-edit — regenerate via: npx @better-auth/cli generate
+-- PlanetScale/Vitess: no foreign key constraints
+
+CREATE TABLE `user` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `name` VARCHAR(255) NOT NULL,
+  `email` VARCHAR(255) NOT NULL UNIQUE,
+  `emailVerified` BOOLEAN NOT NULL DEFAULT FALSE,
+  `image` VARCHAR(255),
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE `session` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `userId` VARCHAR(36) NOT NULL,
+  `token` VARCHAR(255) NOT NULL UNIQUE,
+  `expiresAt` DATETIME NOT NULL,
+  `ipAddress` VARCHAR(255),
+  `userAgent` VARCHAR(255),
+  `activeOrganizationId` VARCHAR(36),
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE `account` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `userId` VARCHAR(36) NOT NULL,
+  `accountId` VARCHAR(255) NOT NULL,
+  `providerId` VARCHAR(255) NOT NULL,
+  `accessToken` TEXT,
+  `refreshToken` TEXT,
+  `accessTokenExpiresAt` DATETIME,
+  `refreshTokenExpiresAt` DATETIME,
+  `scope` VARCHAR(255),
+  `idToken` TEXT,
+  `password` VARCHAR(255),
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE `verification` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `identifier` VARCHAR(255) NOT NULL,
+  `value` VARCHAR(255) NOT NULL,
+  `expiresAt` DATETIME NOT NULL,
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
+);
+
+CREATE TABLE `organization` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `name` VARCHAR(255) NOT NULL,
+  `slug` VARCHAR(255) NOT NULL UNIQUE,
+  `logo` VARCHAR(255),
+  `metadata` TEXT,
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE `member` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `organizationId` VARCHAR(36) NOT NULL,
+  `userId` VARCHAR(36) NOT NULL,
+  `role` VARCHAR(255) NOT NULL DEFAULT 'member',
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  INDEX `idx_member_org` (`organizationId`),
+  INDEX `idx_member_user` (`userId`)
+);
+
+CREATE TABLE `invitation` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `organizationId` VARCHAR(36) NOT NULL,
+  `email` VARCHAR(255) NOT NULL,
+  `role` VARCHAR(255),
+  `status` VARCHAR(255) NOT NULL DEFAULT 'pending',
+  `expiresAt` DATETIME NOT NULL,
+  `inviterId` VARCHAR(36) NOT NULL,
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  INDEX `idx_invitation_org` (`organizationId`),
+  INDEX `idx_invitation_email` (`email`)
+);
+
+CREATE TABLE `apikey` (
+  `id` VARCHAR(36) NOT NULL PRIMARY KEY,
+  `name` VARCHAR(255),
+  `start` VARCHAR(255),
+  `prefix` VARCHAR(255),
+  `key` VARCHAR(255) NOT NULL,
+  `userId` VARCHAR(36) NOT NULL,
+  `refillInterval` INT,
+  `refillAmount` INT,
+  `lastRefillAt` DATETIME,
+  `enabled` BOOLEAN DEFAULT TRUE,
+  `rateLimitEnabled` BOOLEAN DEFAULT TRUE,
+  `rateLimitTimeWindow` INT,
+  `rateLimitMax` INT,
+  `requestCount` INT DEFAULT 0,
+  `remaining` INT,
+  `lastRequest` DATETIME,
+  `expiresAt` DATETIME,
+  `createdAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  `updatedAt` DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
+  `permissions` TEXT,
+  `metadata` TEXT,
+  INDEX `idx_apikey_key` (`key`),
+  INDEX `idx_apikey_user` (`userId`)
+);