payload-better-auth 1.1.6 → 2.1.0

package/README.md

@@ -5,9 +5,11 @@ A Payload CMS plugin that integrates [Better Auth](https://better-auth.com) for
 ## Features
 
 - **Better Auth as Single Source of Truth** — All user operations managed through Better Auth
-- **Real-time Sync** — Automatic synchronization via database hooks
-- **Background Reconciliation** — Periodic full sync ensures data consistency
-- **Cryptographic Security** — Signed operations prevent unauthorized modifications
+- **SecondaryStorage Pattern** — Pluggable storage with SQLite (dev) or Redis (production)
+- **Instant Session Validation** — Payload reads sessions directly from shared storage (no HTTP calls)
+- **Automatic Session Invalidation** — Logout in Better Auth immediately invalidates Payload sessions
+- **Horizontal Scaling** — Redis adapter supports multiple instances
+- **Timestamp-based Coordination** — Automatic reconciliation without race conditions
 - **Custom Login UI** — Replaces Payload's default login with Better Auth authentication
 
 ## Installation
@@ -16,11 +18,29 @@ A Payload CMS plugin that integrates [Better Auth](https://better-auth.com) for
 pnpm add payload-better-auth better-auth
 ```
 
-**Requirements:** Node.js 18.20.2+, Better Auth 1.4.10+, Payload CMS 3.37.0+
+**Requirements:** Node.js 22+ (for native SQLite), Better Auth 1.4.10+, Payload CMS 3.37.0+
 
 ## Quick Start
 
-### 1. Configure Better Auth
+### 1. Create Shared Storage & EventBus
+
+```typescript
+// lib/syncAdapter.ts
+import { DatabaseSync } from 'node:sqlite'
+import { createSqliteStorage } from 'payload-better-auth/storage'
+
+const db = new DatabaseSync('.sync-state.db')
+export const storage = createSqliteStorage({ db })
+
+// lib/eventBus.ts
+import { DatabaseSync } from 'node:sqlite'
+import { createSqlitePollingEventBus } from 'payload-better-auth/eventBus'
+
+const db = new DatabaseSync('.event-bus.db')
+export const eventBus = createSqlitePollingEventBus({ db })
+```
+
+### 2. Configure Better Auth
 
 ```typescript
 // lib/auth.ts
@@ -29,6 +49,8 @@ import { admin, apiKey } from 'better-auth/plugins'
 import Database from 'better-sqlite3'
 import { payloadBetterAuthPlugin } from 'payload-better-auth'
 import buildConfig from './payload.config.js'
+import { eventBus } from './eventBus'
+import { storage } from './syncAdapter'
 
 export const auth = betterAuth({
   database: new Database(process.env.BETTER_AUTH_DB_PATH || './better-auth.db'),
@@ -40,26 +62,38 @@ export const auth = betterAuth({
     payloadBetterAuthPlugin({
       payloadConfig: buildConfig,
       token: process.env.RECONCILE_TOKEN,
+      storage,   // Shared with Payload plugin
+      eventBus,  // Shared with Payload plugin
     }),
   ],
 })
 ```
 
-### 2. Configure Payload
+### 3. Configure Payload
 
 ```typescript
 // payload.config.ts
 import { buildConfig } from 'payload'
-import { betterAuthPlugin } from 'payload-better-auth'
-import { auth } from './lib/auth.js'
+import { betterAuthPayloadPlugin } from 'payload-better-auth'
+import { eventBus } from './lib/eventBus'
+import { storage } from './lib/syncAdapter'
 
 export default buildConfig({
-  plugins: [betterAuthPlugin({ betterAuth: auth })],
+  plugins: [
+    betterAuthPayloadPlugin({
+      betterAuthClientOptions: {
+        externalBaseURL: process.env.NEXT_PUBLIC_SERVER_URL || 'http://localhost:3000',
+        internalBaseURL: process.env.INTERNAL_SERVER_URL || 'http://localhost:3000',
+      },
+      storage,   // Shared with Better Auth plugin
+      eventBus,  // Shared with Better Auth plugin
+    }),
+  ],
   // ... rest of your config
 })
 ```
 
-### 3. Set Environment Variables
+### 4. Set Environment Variables
 
 ```bash
 BETTER_AUTH_SECRET=your-secret-min-32-chars
@@ -70,6 +104,47 @@ PAYLOAD_SECRET=your-payload-secret
 DATABASE_URI=file:./payload.db
 ```
 
+## Production Setup with Redis
+
+For multi-server or geo-distributed deployments, use the Redis storage and EventBus adapters:
+
+```typescript
+// lib/syncAdapter.ts
+import { createRedisStorage } from 'payload-better-auth/storage'
+import Redis from 'ioredis'
+
+const redis = new Redis(process.env.REDIS_URL)
+export const storage = createRedisStorage({ redis })
+
+// lib/eventBus.ts
+import { createRedisEventBus } from 'payload-better-auth/eventBus'
+import Redis from 'ioredis'
+
+// Redis Pub/Sub requires separate connections for publishing and subscribing
+const publisher = new Redis(process.env.REDIS_URL)
+const subscriber = new Redis(process.env.REDIS_URL)
+export const eventBus = createRedisEventBus({ publisher, subscriber })
+```
+
+Then pass the **same instances** to both plugins:
+
+```typescript
+// In Better Auth config:
+payloadBetterAuthPlugin({ 
+  storage,
+  eventBus,
+  payloadConfig: buildConfig,
+  token: process.env.RECONCILE_TOKEN,
+})
+
+// In Payload config:
+betterAuthPayloadPlugin({ 
+  storage,
+  eventBus,
+  betterAuthClientOptions: { ... },
+})
+```
+
 ## Documentation
 
 For detailed configuration options, API endpoints, architecture details, and production considerations, see the **[MANUAL.md](./MANUAL.md)**.
@@ -91,6 +166,21 @@ pnpm dev
 
 The dev server starts at [http://localhost:3000](http://localhost:3000) with a mail server at port 1080.
 
+### Testing with Redis
+
+To test the Redis integration locally:
+
+```bash
+# Start Redis container
+pnpm docker:redis
+
+# Run dev server with Redis (instead of SQLite)
+pnpm dev:redis
+
+# Stop Redis when done
+pnpm docker:redis:stop
+```
+
 ### Git Hooks
 
 This project uses [Husky](https://typicode.github.io/husky/) for Git hooks:
@@ -134,6 +224,9 @@ pnpm add github:benjaminpreiss/payload-better-auth#v1.2.0
 | Script | Description |
 |--------|-------------|
 | `pnpm dev` | Start dev server with mail server |
+| `pnpm dev:redis` | Start dev server with Redis (instead of SQLite) |
+| `pnpm docker:redis` | Start Redis container via Docker Compose |
+| `pnpm docker:redis:stop` | Stop Redis container |
 | `pnpm build` | Build the plugin |
 | `pnpm reset` | Reset databases and run all migrations |
 | `pnpm test` | Run all tests |
@@ -145,10 +238,13 @@ pnpm add github:benjaminpreiss/payload-better-auth#v1.2.0
 
 ```
 ├── src/                    # Plugin source code
-│   ├── better-auth/        # Better Auth integration
-│   ├── collections/        # Payload collections
-│   ├── components/         # React components
+│   ├── storage/            # SecondaryStorage implementations (SQLite, Redis)
+│   ├── eventBus/           # EventBus implementations (SQLite polling, Redis Pub/Sub)
+│   ├── better-auth/        # Better Auth integration & reconcile queue
+│   ├── collections/        # Payload collections (Users)
+│   ├── components/         # React components (Login UI)
 │   ├── payload/            # Payload plugin
+│   ├── shared/             # Shared utilities (deduplicated logger)
 │   └── exports/            # Client/RSC exports
 ├── dev/                    # Development environment
 │   ├── app/                # Next.js app

package/dist/better-auth/crypto-shared.d.ts

@@ -9,28 +9,6 @@ export interface CryptoSignature {
     /** Unix timestamp as string */
     ts: string;
 }
-/**
- * Input parameters for signature verification
- */
-export interface VerifySignatureInput {
-    /** The data that was signed */
-    body: unknown;
-    /** Maximum allowed time skew in seconds (default: 300) */
-    maxSkewSec?: number;
-    /** Secret key for verification */
-    secret: string;
-    /** The signature to verify */
-    signature: CryptoSignature;
-}
-/**
- * Input parameters for signature creation
- */
-export interface SignCanonicalInput {
-    /** The data to sign */
-    body: unknown;
-    /** Secret key for signing */
-    secret: string;
-}
 /**
  * Creates a cryptographic signature for the given data
  * @param body - The data to sign
@@ -47,15 +25,3 @@ export declare function signCanonical(body: unknown, secret: string): CryptoSign
  * @returns true if signature is valid, false otherwise
  */
 export declare function verifyCanonical(body: unknown, sig: CryptoSignature, secret: string, maxSkewSec?: number): boolean;
-/**
- * Convenience function for verifying signatures with input object
- * @param input - Verification parameters
- * @returns true if signature is valid, false otherwise
- */
-export declare function verifySignature(input: VerifySignatureInput): boolean;
-/**
- * Convenience function for creating signatures with input object
- * @param input - Signing parameters
- * @returns Signature object
- */
-export declare function createSignature(input: SignCanonicalInput): CryptoSignature;

package/dist/better-auth/crypto-shared.js

@@ -72,19 +72,5 @@ import crypto from 'crypto';
         return false;
     }
 }
-/**
- * Convenience function for verifying signatures with input object
- * @param input - Verification parameters
- * @returns true if signature is valid, false otherwise
- */ export function verifySignature(input) {
-    return verifyCanonical(input.body, input.signature, input.secret, input.maxSkewSec);
-}
-/**
- * Convenience function for creating signatures with input object
- * @param input - Signing parameters
- * @returns Signature object
- */ export function createSignature(input) {
-    return signCanonical(input.body, input.secret);
-}
 
 //# sourceMappingURL=crypto-shared.js.map

package/dist/better-auth/crypto-shared.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/better-auth/crypto-shared.ts"],"sourcesContent":["// crypto-shared.ts\nimport crypto from 'crypto'\n\n/**\n * Type for serializable values that can be canonically stringified\n */\ntype SerializableValue =\n  | boolean\n  | null\n  | number\n  | SerializableArray\n  | SerializableObject\n  | string\n  | undefined\n\ninterface SerializableObject {\n  [key: string]: SerializableValue\n}\n\ninterface SerializableArray extends Array<SerializableValue> {}\n\n/**\n * Signature object containing timestamp, nonce, and MAC\n */\nexport interface CryptoSignature {\n  /** HMAC-SHA256 signature */\n  mac: string\n  /** Unique nonce for this signature */\n  nonce: string\n  /** Unix timestamp as string */\n  ts: string\n}\n\n/**\n * Input parameters for signature verification\n */\nexport interface VerifySignatureInput {\n  /** The data that was signed */\n  body: unknown\n  /** Maximum allowed time skew in seconds (default: 300) */\n  maxSkewSec?: number\n  /** Secret key for verification */\n  secret: string\n  /** The signature to verify */\n  signature: CryptoSignature\n}\n\n/**\n * Input parameters for signature creation\n */\nexport interface SignCanonicalInput {\n  /** The data to sign */\n  body: unknown\n  /** Secret key for signing */\n  secret: string\n}\n\n/**\n * Converts an object to a canonical string representation\n * Handles circular references and ensures consistent ordering\n */\nfunction canonicalStringify(obj: unknown): string {\n  const seen = new WeakSet<object>()\n\n  const walk = (v: unknown): string => {\n    if (v && typeof v === 'object') {\n      if (seen.has(v)) {\n        throw new Error('Circular reference detected in object')\n      }\n      seen.add(v)\n\n      if (Array.isArray(v)) {\n        const result = `[${v.map(walk).join(',')}]`\n        seen.delete(v)\n        return result\n      }\n\n      const keys = Object.keys(v).sort()\n      const result = `{${keys.map((k) => `\"${k}\":${walk((v as Record<string, unknown>)[k])}`).join(',')}}`\n      seen.delete(v)\n      return result\n    }\n    return JSON.stringify(v)\n  }\n\n  return walk(obj)\n}\n\n/**\n * Creates a cryptographic signature for the given data\n * @param body - The data to sign\n * @param secret - Secret key for signing\n * @returns Signature object with timestamp, nonce, and MAC\n */\nexport function signCanonical(body: unknown, secret: string): CryptoSignature {\n  if (!secret || typeof secret !== 'string') {\n    throw new Error('Secret must be a non-empty string')\n  }\n\n  const ts = Math.floor(Date.now() / 1000).toString()\n  const nonce = crypto.randomUUID()\n  const payload = canonicalStringify(body)\n  const mac = crypto.createHmac('sha256', secret).update(`${ts}.${nonce}.${payload}`).digest('hex')\n\n  return { mac, nonce, ts }\n}\n\n/**\n * Verifies a cryptographic signature\n * @param body - The original data that was signed\n * @param sig - The signature to verify\n * @param secret - Secret key for verification\n * @param maxSkewSec - Maximum allowed time skew in seconds (default: 300)\n * @returns true if signature is valid, false otherwise\n */\nexport function verifyCanonical(\n  body: unknown,\n  sig: CryptoSignature,\n  secret: string,\n  maxSkewSec: number = 300,\n) {\n  if (!secret || typeof secret !== 'string') {\n    return false\n  }\n\n  if (!sig || typeof sig !== 'object' || !sig.ts || !sig.nonce || !sig.mac) {\n    return false\n  }\n\n  // Validate timestamp\n  const now = Math.floor(Date.now() / 1000)\n  const t = Number(sig.ts)\n  if (!Number.isFinite(t) || Math.abs(now - t) > maxSkewSec) {\n    return false\n  }\n\n  try {\n    const payload = canonicalStringify(body)\n    const expected = crypto\n      .createHmac('sha256', secret)\n      .update(`${sig.ts}.${sig.nonce}.${payload}`)\n      .digest('hex')\n\n    return crypto.timingSafeEqual(\n      new Uint8Array(Buffer.from(sig.mac, 'hex')),\n      new Uint8Array(Buffer.from(expected, 'hex')),\n    )\n  } catch {\n    return false\n  }\n}\n\n/**\n * Convenience function for verifying signatures with input object\n * @param input - Verification parameters\n * @returns true if signature is valid, false otherwise\n */\nexport function verifySignature(input: VerifySignatureInput) {\n  return verifyCanonical(input.body, input.signature, input.secret, input.maxSkewSec)\n}\n\n/**\n * Convenience function for creating signatures with input object\n * @param input - Signing parameters\n * @returns Signature object\n */\nexport function createSignature(input: SignCanonicalInput) {\n  return signCanonical(input.body, input.secret)\n}\n"],"names":["crypto","canonicalStringify","obj","seen","WeakSet","walk","v","has","Error","add","Array","isArray","result","map","join","delete","keys","Object","sort","k","JSON","stringify","signCanonical","body","secret","ts","Math","floor","Date","now","toString","nonce","randomUUID","payload","mac","createHmac","update","digest","verifyCanonical","sig","maxSkewSec","t","Number","isFinite","abs","expected","timingSafeEqual","Uint8Array","Buffer","from","verifySignature","input","signature","createSignature"],"mappings":"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"}
+{"version":3,"sources":["../../src/better-auth/crypto-shared.ts"],"sourcesContent":["// crypto-shared.ts\nimport crypto from 'crypto'\n\n/**\n * Type for serializable values that can be canonically stringified\n */\ntype SerializableValue =\n  | boolean\n  | null\n  | number\n  | SerializableArray\n  | SerializableObject\n  | string\n  | undefined\n\ninterface SerializableObject {\n  [key: string]: SerializableValue\n}\n\ninterface SerializableArray extends Array<SerializableValue> {}\n\n/**\n * Signature object containing timestamp, nonce, and MAC\n */\nexport interface CryptoSignature {\n  /** HMAC-SHA256 signature */\n  mac: string\n  /** Unique nonce for this signature */\n  nonce: string\n  /** Unix timestamp as string */\n  ts: string\n}\n\n\n/**\n * Converts an object to a canonical string representation\n * Handles circular references and ensures consistent ordering\n */\nfunction canonicalStringify(obj: unknown): string {\n  const seen = new WeakSet<object>()\n\n  const walk = (v: unknown): string => {\n    if (v && typeof v === 'object') {\n      if (seen.has(v)) {\n        throw new Error('Circular reference detected in object')\n      }\n      seen.add(v)\n\n      if (Array.isArray(v)) {\n        const result = `[${v.map(walk).join(',')}]`\n        seen.delete(v)\n        return result\n      }\n\n      const keys = Object.keys(v).sort()\n      const result = `{${keys.map((k) => `\"${k}\":${walk((v as Record<string, unknown>)[k])}`).join(',')}}`\n      seen.delete(v)\n      return result\n    }\n    return JSON.stringify(v)\n  }\n\n  return walk(obj)\n}\n\n/**\n * Creates a cryptographic signature for the given data\n * @param body - The data to sign\n * @param secret - Secret key for signing\n * @returns Signature object with timestamp, nonce, and MAC\n */\nexport function signCanonical(body: unknown, secret: string): CryptoSignature {\n  if (!secret || typeof secret !== 'string') {\n    throw new Error('Secret must be a non-empty string')\n  }\n\n  const ts = Math.floor(Date.now() / 1000).toString()\n  const nonce = crypto.randomUUID()\n  const payload = canonicalStringify(body)\n  const mac = crypto.createHmac('sha256', secret).update(`${ts}.${nonce}.${payload}`).digest('hex')\n\n  return { mac, nonce, ts }\n}\n\n/**\n * Verifies a cryptographic signature\n * @param body - The original data that was signed\n * @param sig - The signature to verify\n * @param secret - Secret key for verification\n * @param maxSkewSec - Maximum allowed time skew in seconds (default: 300)\n * @returns true if signature is valid, false otherwise\n */\nexport function verifyCanonical(\n  body: unknown,\n  sig: CryptoSignature,\n  secret: string,\n  maxSkewSec: number = 300,\n) {\n  if (!secret || typeof secret !== 'string') {\n    return false\n  }\n\n  if (!sig || typeof sig !== 'object' || !sig.ts || !sig.nonce || !sig.mac) {\n    return false\n  }\n\n  // Validate timestamp\n  const now = Math.floor(Date.now() / 1000)\n  const t = Number(sig.ts)\n  if (!Number.isFinite(t) || Math.abs(now - t) > maxSkewSec) {\n    return false\n  }\n\n  try {\n    const payload = canonicalStringify(body)\n    const expected = crypto\n      .createHmac('sha256', secret)\n      .update(`${sig.ts}.${sig.nonce}.${payload}`)\n      .digest('hex')\n\n    return crypto.timingSafeEqual(\n      new Uint8Array(Buffer.from(sig.mac, 'hex')),\n      new Uint8Array(Buffer.from(expected, 'hex')),\n    )\n  } catch {\n    return false\n  }\n}\n\n"],"names":["crypto","canonicalStringify","obj","seen","WeakSet","walk","v","has","Error","add","Array","isArray","result","map","join","delete","keys","Object","sort","k","JSON","stringify","signCanonical","body","secret","ts","Math","floor","Date","now","toString","nonce","randomUUID","payload","mac","createHmac","update","digest","verifyCanonical","sig","maxSkewSec","t","Number","isFinite","abs","expected","timingSafeEqual","Uint8Array","Buffer","from"],"mappings":"AAAA,mBAAmB;AACnB,OAAOA,YAAY,SAAQ;AAiC3B;;;CAGC,GACD,SAASC,mBAAmBC,GAAY;IACtC,MAAMC,OAAO,IAAIC;IAEjB,MAAMC,OAAO,CAACC;QACZ,IAAIA,KAAK,OAAOA,MAAM,UAAU;YAC9B,IAAIH,KAAKI,GAAG,CAACD,IAAI;gBACf,MAAM,IAAIE,MAAM;YAClB;YACAL,KAAKM,GAAG,CAACH;YAET,IAAII,MAAMC,OAAO,CAACL,IAAI;gBACpB,MAAMM,SAAS,CAAC,CAAC,EAAEN,EAAEO,GAAG,CAACR,MAAMS,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC3CX,KAAKY,MAAM,CAACT;gBACZ,OAAOM;YACT;YAEA,MAAMI,OAAOC,OAAOD,IAAI,CAACV,GAAGY,IAAI;YAChC,MAAMN,SAAS,CAAC,CAAC,EAAEI,KAAKH,GAAG,CAAC,CAACM,IAAM,CAAC,CAAC,EAAEA,EAAE,EAAE,EAAEd,KAAK,AAACC,CAA6B,CAACa,EAAE,GAAG,EAAEL,IAAI,CAAC,KAAK,CAAC,CAAC;YACpGX,KAAKY,MAAM,CAACT;YACZ,OAAOM;QACT;QACA,OAAOQ,KAAKC,SAAS,CAACf;IACxB;IAEA,OAAOD,KAAKH;AACd;AAEA;;;;;CAKC,GACD,OAAO,SAASoB,cAAcC,IAAa,EAAEC,MAAc;IACzD,IAAI,CAACA,UAAU,OAAOA,WAAW,UAAU;QACzC,MAAM,IAAIhB,MAAM;IAClB;IAEA,MAAMiB,KAAKC,KAAKC,KAAK,CAACC,KAAKC,GAAG,KAAK,MAAMC,QAAQ;IACjD,MAAMC,QAAQ/B,OAAOgC,UAAU;IAC/B,MAAMC,UAAUhC,mBAAmBsB;IACnC,MAAMW,MAAMlC,OAAOmC,UAAU,CAAC,UAAUX,QAAQY,MAAM,CAAC,GAAGX,GAAG,CAAC,EAAEM,MAAM,CAAC,EAAEE,SAAS,EAAEI,MAAM,CAAC;IAE3F,OAAO;QAAEH;QAAKH;QAAON;IAAG;AAC1B;AAEA;;;;;;;CAOC,GACD,OAAO,SAASa,gBACdf,IAAa,EACbgB,GAAoB,EACpBf,MAAc,EACdgB,aAAqB,GAAG;IAExB,IAAI,CAAChB,UAAU,OAAOA,WAAW,UAAU;QACzC,OAAO;IACT;IAEA,IAAI,CAACe,OAAO,OAAOA,QAAQ,YAAY,CAACA,IAAId,EAAE,IAAI,CAACc,IAAIR,KAAK,IAAI,CAACQ,IAAIL,GAAG,EAAE;QACxE,OAAO;IACT;IAEA,qBAAqB;IACrB,MAAML,MAAMH,KAAKC,KAAK,CAACC,KAAKC,GAAG,KAAK;IACpC,MAAMY,IAAIC,OAAOH,IAAId,EAAE;IACvB,IAAI,CAACiB,OAAOC,QAAQ,CAACF,MAAMf,KAAKkB,GAAG,CAACf,MAAMY,KAAKD,YAAY;QACzD,OAAO;IACT;IAEA,IAAI;QACF,MAAMP,UAAUhC,mBAAmBsB;QACnC,MAAMsB,WAAW7C,OACdmC,UAAU,CAAC,UAAUX,QACrBY,MAAM,CAAC,GAAGG,IAAId,EAAE,CAAC,CAAC,EAAEc,IAAIR,KAAK,CAAC,CAAC,EAAEE,SAAS,EAC1CI,MAAM,CAAC;QAEV,OAAOrC,OAAO8C,eAAe,CAC3B,IAAIC,WAAWC,OAAOC,IAAI,CAACV,IAAIL,GAAG,EAAE,SACpC,IAAIa,WAAWC,OAAOC,IAAI,CAACJ,UAAU;IAEzC,EAAE,OAAM;QACN,OAAO;IACT;AACF"}

package/dist/better-auth/plugin.d.ts

@@ -1,14 +1,52 @@
 import type { AuthContext, BetterAuthPlugin } from 'better-auth';
 import type { SanitizedConfig } from 'payload';
+import type { EventBus } from '../eventBus/types';
+import type { SecondaryStorage } from '../storage/types';
 import { type InitOptions } from './reconcile-queue';
 type CreateAdminsUser = Parameters<AuthContext['internalAdapter']['createUser']>['0'];
-export declare const payloadBetterAuthPlugin: (opts: {
+export interface PayloadBetterAuthPluginOptions extends InitOptions {
     createAdmins?: {
         overwrite?: boolean;
         user: CreateAdminsUser;
     }[];
     enableLogging?: boolean;
+    /**
+     * EventBus for timestamp-based coordination between plugins.
+     * Both plugins MUST share the same eventBus instance.
+     *
+     * Available implementations:
+     * - `createSqlitePollingEventBus()` - Uses SQLite for cross-process coordination
+     *
+     * @example
+     * // Create shared eventBus (e.g., in a separate file)
+     * import { createSqlitePollingEventBus } from 'payload-better-auth'
+     * import { DatabaseSync } from 'node:sqlite'
+     * const db = new DatabaseSync('.event-bus.db')
+     * export const eventBus = createSqlitePollingEventBus({ db })
+     */
+    eventBus: EventBus;
     payloadConfig: Promise<SanitizedConfig>;
+    /**
+     * Secondary storage for state coordination between Better Auth and Payload.
+     * Both plugins MUST share the same storage instance.
+     *
+     * This storage is automatically passed to Better Auth as `secondaryStorage`,
+     * enabling session caching - Payload validates sessions directly from storage
+     * without HTTP calls to Better Auth.
+     *
+     * Available storage adapters:
+     * - `createSqliteStorage()` - Uses Node.js 22+ native SQLite (no external dependencies, recommended for dev)
+     * - `createRedisStorage(redis)` - Redis-backed, for distributed/multi-server production
+     *
+     * @example
+     * // Create shared storage (e.g., in a separate file)
+     * import { createSqliteStorage } from 'payload-better-auth'
+     * import { DatabaseSync } from 'node:sqlite'
+     * const db = new DatabaseSync('.sync-state.db')
+     * export const storage = createSqliteStorage({ db })
+     */
+    storage: SecondaryStorage;
     token: string;
-} & InitOptions) => BetterAuthPlugin;
+}
+export declare const payloadBetterAuthPlugin: (opts: PayloadBetterAuthPluginOptions) => BetterAuthPlugin;
 export {};

package/dist/better-auth/plugin.js

@@ -1,13 +1,52 @@
 // src/plugins/reconcile-queue-plugin.ts
 import { APIError } from 'better-auth/api';
 import { createAuthEndpoint, createAuthMiddleware } from 'better-auth/plugins';
-import { createDatabaseHooks } from './databaseHooks';
+import { createDeduplicatedLogger } from '../shared/deduplicatedLogger';
+import { SESSION_COOKIE_NAME_KEY, TIMESTAMP_PREFIX } from '../storage/keys';
 import { Queue } from './reconcile-queue';
 import { createDeleteUserFromPayload, createListPayloadUsersPage, createSyncUserToPayload } from './sources';
 const defaultLog = (msg, extra)=>{
     console.log(`[reconcile] ${msg}`, extra ? JSON.stringify(extra, null, 2) : '');
 };
+/**
+ * Create database hooks that enqueue user changes to the reconciliation queue.
+ * All sync operations go through the queue for consistent handling with retries.
+ */ function createQueueBasedHooks(queue) {
+    return {
+        user: {
+            create: {
+                after: (user)=>{
+                    queue.enqueueEnsure(user, true, 'user-operation');
+                    return Promise.resolve();
+                }
+            },
+            delete: {
+                after: (user)=>{
+                    queue.enqueueDelete(user.id, true, 'user-operation');
+                    return Promise.resolve();
+                }
+            },
+            update: {
+                after: (user)=>{
+                    queue.enqueueEnsure(user, true, 'user-operation');
+                    return Promise.resolve();
+                }
+            }
+        }
+    };
+}
 export const payloadBetterAuthPlugin = (opts)=>{
+    const { eventBus, storage } = opts;
+    // Create deduplicated logger
+    const logger = createDeduplicatedLogger({
+        enabled: opts.enableLogging ?? false,
+        prefix: '[better-auth]',
+        storage
+    });
+    // Keep the simple log for queue operations (they handle their own deduplication)
+    const queueLog = opts.enableLogging ? defaultLog : undefined;
+    // Track subscription for cleanup
+    let unsubscribeFromPayload = null;
     return {
         id: 'reconcile-queue-plugin',
         endpoints: {
@@ -119,18 +158,30 @@ export const payloadBetterAuthPlugin = (opts)=>{
                 }
             ]
         },
-        schema: {
-            user: {
-                fields: {
-                    locale: {
-                        type: 'string',
-                        required: false
-                    }
-                }
+        async init ({ internalAdapter, options, password }) {
+            // Compute and store the session cookie name for Payload to read
+            // This accounts for cookiePrefix, custom cookie names, and __Secure- prefix
+            const cookiePrefix = options.advanced?.cookiePrefix ?? 'better-auth';
+            const customCookieName = options.advanced?.cookies?.session_token?.name;
+            // Better Auth uses secure cookies when:
+            // 1. Explicitly set via useSecureCookies option
+            // 2. NODE_ENV is 'production'
+            // 3. baseURL starts with 'https://'
+            const isHttps = options.baseURL?.startsWith('https://') ?? false;
+            const useSecureCookies = options.advanced?.useSecureCookies ?? (process.env.NODE_ENV === 'production' || isHttps);
+            let sessionCookieName;
+            if (customCookieName) {
+                // Custom cookie name takes precedence
+                sessionCookieName = useSecureCookies ? `__Secure-${customCookieName}` : customCookieName;
+            } else {
+                // Default format: {prefix}.session_token
+                const baseName = `${cookiePrefix}.session_token`;
+                sessionCookieName = useSecureCookies ? `__Secure-${baseName}` : baseName;
             }
-        },
-        // TODO: the queue must be destroyed on better auth instance destruction, as it utilizes timers.
-        async init ({ internalAdapter, password }) {
+            // Store session cookie name in KV for Payload plugin to read
+            await storage.set(SESSION_COOKIE_NAME_KEY, sessionCookieName);
+            await logger.log('cookie-config', `Session cookie name: ${sessionCookieName}`);
+            // Create admin users if configured
             if (opts.createAdmins) {
                 try {
                     await Promise.all(opts.createAdmins.map(async ({ overwrite, user })=>{
@@ -143,7 +194,6 @@ export const payloadBetterAuthPlugin = (opts)=>{
                                     ...user,
                                     role: 'admin'
                                 });
-                                // assuming this creates an account?
                                 await internalAdapter.linkAccount({
                                     accountId: createdUser.id,
                                     password: await password.hash(user.password),
@@ -165,18 +215,84 @@ export const payloadBetterAuthPlugin = (opts)=>{
                         }
                     }));
                 } catch (error) {
-                    if (opts.enableLogging) {
-                        defaultLog('Failed to create Admin user', error);
-                    }
+                    logger.always('Failed to create Admin user', error);
                 }
             }
+            // Create the reconciliation queue
             const queue = new Queue({
                 deleteUserFromPayload: createDeleteUserFromPayload(opts.payloadConfig),
                 internalAdapter,
                 listPayloadUsersPage: createListPayloadUsersPage(opts.payloadConfig),
-                log: opts.enableLogging ? defaultLog : undefined,
+                log: queueLog,
                 syncUserToPayload: createSyncUserToPayload(opts.payloadConfig)
-            }, opts);
+            }, {
+                ...opts,
+                // Don't run reconcile on boot - we use timestamp-based coordination instead
+                runOnBoot: false
+            });
+            // Log init (deduplicated)
+            await logger.log('init', 'Initialized');
+            // Timestamp-based reconciliation coordination
+            async function attemptReconciliation() {
+                logger.always('Syncing users to Payload...');
+                await storage.set(TIMESTAMP_PREFIX + 'better-auth', String(Date.now()));
+                try {
+                    await queue.seedFullReconcile();
+                    logger.always('Sync completed successfully');
+                    // Success - unsubscribe if we were watching
+                    if (unsubscribeFromPayload) {
+                        unsubscribeFromPayload();
+                        unsubscribeFromPayload = null;
+                    }
+                } catch (error) {
+                    logger.always('Sync failed, will retry when Payload restarts', error);
+                    // Subscribe to Payload timestamp changes if not already
+                    if (!unsubscribeFromPayload) {
+                        unsubscribeFromPayload = eventBus.subscribeToTimestamp('payload', ()=>{
+                            attemptReconciliation().catch((err)=>{
+                                logger.always('Sync attempt failed', err);
+                            });
+                        });
+                    }
+                }
+            }
+            // Check if Payload is online and started more recently than our last reconcile
+            const payloadTsStr = await storage.get(TIMESTAMP_PREFIX + 'payload');
+            const baTsStr = await storage.get(TIMESTAMP_PREFIX + 'better-auth');
+            const payloadTs = payloadTsStr ? parseInt(payloadTsStr, 10) : null;
+            const baTs = baTsStr ? parseInt(baTsStr, 10) : null;
+            // Determine reconciliation state
+            if (payloadTs === null) {
+                // Payload hasn't started yet
+                await logger.log('status', 'Waiting for Payload to start...');
+                unsubscribeFromPayload = eventBus.subscribeToTimestamp('payload', ()=>{
+                    attemptReconciliation().catch((err)=>{
+                        logger.always('Sync attempt failed', err);
+                    });
+                });
+            } else if (baTs === null) {
+                // First run - always sync
+                attemptReconciliation().catch((err)=>{
+                    logger.always('Initial sync failed', err);
+                });
+            } else if (payloadTs > baTs) {
+                // Payload restarted since last reconcile - sync needed
+                attemptReconciliation().catch((err)=>{
+                    logger.always('Sync failed', err);
+                });
+            } else {
+                // Already reconciled and up-to-date
+                await logger.log('status', 'Already synchronized', {
+                    lastSync: new Date(baTs).toISOString()
+                });
+                unsubscribeFromPayload = eventBus.subscribeToTimestamp('payload', ()=>{
+                    attemptReconciliation().catch((err)=>{
+                        logger.always('Sync attempt failed', err);
+                    });
+                });
+            }
+            // Create queue-based database hooks - all user sync goes through the queue
+            const queueBasedHooks = createQueueBasedHooks(queue);
             return {
                 context: {
                     payloadSyncPlugin: {
@@ -184,9 +300,10 @@ export const payloadBetterAuthPlugin = (opts)=>{
                     }
                 },
                 options: {
-                    databaseHooks: createDatabaseHooks({
-                        config: opts.payloadConfig
-                    }),
+                    databaseHooks: queueBasedHooks,
+                    // Pass storage to Better Auth as secondaryStorage - this makes BA write sessions
+                    // to the shared storage, allowing Payload to validate sessions directly from cache
+                    secondaryStorage: storage,
                     user: {
                         deleteUser: {
                             enabled: true
@@ -194,6 +311,16 @@ export const payloadBetterAuthPlugin = (opts)=>{
                     }
                 }
             };
+        },
+        schema: {
+            user: {
+                fields: {
+                    locale: {
+                        type: 'string',
+                        required: false
+                    }
+                }
+            }
         }
     };
 };