Backend Runtime & Adapters

The @copypatch/backend package is the headless core of CopyPatch v2. It provides a standard Web Request/Response pipeline that handles routing, authorization, CSRF checks, and optimistic revision coordination.

1. Creating a Backend Instance

Instantiate the backend with your choice of storage adapter and authentication strategy:

lib/copypatch.ts

import { createCopyPatchBackend } from '@copypatch/backend';
import { createSQLitePersistence } from '@copypatch/storage-sqlite';

const persistence = createSQLitePersistence('./data/copypatch.sqlite');
await persistence.migrate();

export const copypatch = createCopyPatchBackend({
  persistence,
  passphraseHash: process.env.COPYPATCH_PASSPHRASE_HASH!,
});

2. Authentication Strategies

createCopyPatchBackend accepts exactly one of two mutually exclusive authentication options:

Strategy A: Built-in Passphrase (`passphraseHash`)

Managed entirely by CopyPatch with zero host auth configuration required.
Uses an Argon2id password hash (RFC 9106 recommended parameters).
Issues secure HttpOnly, SameSite=Strict session cookies and dual-token CSRF headers.
Ideal for marketing sites, agency handoffs, and teams without complex existing auth.

Strategy B: Host Auth Adapter (`authAdapter`)

Delegates user resolution and role assignment to your application's existing auth provider (e.g. NextAuth, Lucia, Clerk, Auth0, Supabase).
Maps your user permissions to CopyPatch's editor and publisher roles.
Delegates mutation integrity verification to the host.

lib/copypatch-custom-auth.ts

import { createCopyPatchBackend, type CopyPatchAuthAdapter } from '@copypatch/backend';
import { createPostgresPersistence } from '@copypatch/storage-postgres';

// Custom adapter connecting CopyPatch to your existing auth system (e.g. NextAuth, Clerk, Auth0)
const hostAuthAdapter: CopyPatchAuthAdapter = {
  async resolvePrincipal(context) {
    const user = context.hostAuth?.user;
    if (!user) return null;

    const roles: ('editor' | 'publisher')[] = [];
    if (user.isAdmin || user.canEditCopy) roles.push('editor');
    if (user.isAdmin || user.canPublishCopy) roles.push('publisher');

    return { id: user.id, roles };
  },

  async verifyMutation(request, context) {
    // Verify host CSRF token or session integrity
    return context.hostAuth?.csrfValid === true;
  },
};

export const backend = createCopyPatchBackend({
  persistence: createPostgresPersistence({ connectionString: process.env.DATABASE_URL! }),
  authAdapter: hostAuthAdapter,
});

3. Persistence Engines

Adapter	Driver	Best Suited For	Concurrency & Transactions
`@copypatch/storage-sqlite`	`better-sqlite3`	Single Node server, VPS (Hetzner, DigitalOcean), Docker container with mounted volume.	Synchronous SQLite transactions, WAL journal mode, atomic CAS revisions.
`@copypatch/storage-postgres`	`pg`	Horizontally scaled clusters, Kubernetes, serverless platforms (Vercel, AWS ECS, Fly.io).	Connection pooling, PostgreSQL advisory transaction locks, multi-instance rate limits.

4. Node Framework Adapters

The @copypatch/node package exports lightweight HTTP bridges for all major Node server runtimes:

createNodeHandler(backend) – Native Node.js http.createServer
expressMiddleware(backend) – Express middleware
fastifyCopyPatchHandler(backend) – Fastify route handler
createHonoHandler(backend) – Hono Web standard handler

Legacy Note: @copypatch/server was the v1 standalone server process. In v2, it is fully replaced by the embedded @copypatch/backend and @copypatch/node libraries. Existing v1 packages remain published on npm, but new projects should use v2.