Backend Runtime & Adapters

The @copypatch/backend package is the headless core of CopyPatch v3. 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:

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

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

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.

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

// Custom adapter connecting CopyPatch to your existing auth system (e.g. NextAuth, Clerk, Auth0)
interface HostAuthContext {
  user?: {
    id: string;
    isAdmin: boolean;
    canEditCopy: boolean;
    canPublishCopy: boolean;
  };
  csrfValid?: boolean;
}

const hostAuthAdapter: CopyPatchAuthAdapter<HostAuthContext> = {
  async authenticate(_request, 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 { subject: user.id, roles };
  },

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

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

3. Persistence Engines

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.