@payload-auth-link/migrate 0.4.3 → 0.6.0

package/src/importer/prelink.ts

@@ -0,0 +1,237 @@
+import type { Payload } from 'payload'
+import { capturedKeys, captureBefore } from './host-writes.js'
+import { authenticateManifest, signManifest } from './manifest-mac.js'
+import type { FieldWrite, ImportManifest, Unmappable } from './types.js'
+
+/**
+ * The adopt-mode pre-link (issues #49, #88): `migrate adopt-prelink`.
+ *
+ * In adopt mode the users collection IS Better Auth's user table
+ * (`schemaMap.user`, `idStrategy: 'payload'`), so Better Auth's user id
+ * for a document is the document id. What adopt mode does NOT do by
+ * itself is link the plugin side: without an identity row, the first
+ * provider sign-in reaches JIT linking, which links an existing
+ * document only on the verified-email proof (`linkable === true` with
+ * `linkableEmail` equal to the document email).
+ *
+ * This command mirrors exactly what the importer writes on the host
+ * users (issue #69):
+ *
+ * - ONE `better-auth` identity per user, `providerUserId` = the
+ *   document id (other providers' identity rows are kept);
+ * - `linkable: true` + `linkableEmail: <email>` for users whose
+ *   verified-email field (`emailVerified` on payload-auth layouts) is
+ *   `true` — grant-only, never revoked.
+ *
+ * Dry run by default. `--apply` records every prior value in a manifest
+ * (first capture wins, sealed, mode 0600) so `rollback --manifest`
+ * restores the documents exactly, `updatedAt` included.
+ */
+
+export type PrelinkOptions = {
+  readonly payload: Payload
+  readonly apply: boolean
+  readonly manifest: ImportManifest | null
+  readonly manifestPath: string
+  /** Users collection slug. Defaults to `users`. */
+  readonly usersSlug?: string | undefined
+  /** The users' verified-email checkbox. Defaults to `emailVerified`. */
+  readonly verifiedField?: string | undefined
+  /** Email field. Defaults to `email`. */
+  readonly emailField?: string | undefined
+  readonly now?: () => Date
+  readonly log?: (message: string) => void
+  /** Resume from a pre-0.6.0 manifest that has no MAC (`--allow-unsigned-manifest`). */
+  readonly allowUnsignedManifest?: boolean | undefined
+}
+
+export type PrelinkResult = {
+  readonly users: number
+  /** Documents that received (or would receive) the better-auth identity. */
+  readonly linked: number
+  /** Documents already carrying the exact identity. */
+  readonly alreadyLinked: number
+  /** Verified documents granted (or to be granted) the linking proof. */
+  readonly proofGranted: number
+  /** Users without a verified email: identity only, no linking proof. */
+  readonly unverified: number
+  readonly unmappable: readonly Unmappable[]
+  readonly fieldWrites: number
+}
+
+type IdentityRow = {
+  readonly id?: unknown
+  readonly providerId?: unknown
+  readonly providerUserId?: unknown
+  readonly email?: unknown
+  readonly linkedAt?: unknown
+}
+
+function identitiesOf(doc: Record<string, unknown>): IdentityRow[] {
+  const raw = doc['identities']
+  return Array.isArray(raw)
+    ? raw.filter((row): row is IdentityRow => typeof row === 'object' && row !== null)
+    : []
+}
+
+export async function prelinkUsers(options: PrelinkOptions): Promise<PrelinkResult> {
+  const { payload, apply, log = () => {}, now = () => new Date() } = options
+  const usersSlug = options.usersSlug ?? 'users'
+  const verifiedField = options.verifiedField ?? 'emailVerified'
+  const emailField = options.emailField ?? 'email'
+  if (options.manifest !== null) {
+    // Resuming re-signs the old entries: verify them first.
+    authenticateManifest(payload.secret, options.manifest, {
+      allowUnsigned: options.allowUnsignedManifest,
+    })
+  }
+  const fieldWrites: FieldWrite[] = [...(options.manifest?.fieldWrites ?? [])]
+  const captured = capturedKeys(fieldWrites)
+
+  type Planned = {
+    readonly id: string | number
+    readonly email: string
+    readonly writeIdentity: boolean
+    readonly grantProof: boolean
+    readonly keep: IdentityRow[]
+  }
+  const planned: Planned[] = []
+  const unmappable: Unmappable[] = []
+  let users = 0
+  let alreadyLinked = 0
+  let unverified = 0
+
+  // Plan the WHOLE collection before any write: a conflicting identity
+  // anywhere aborts the run with nothing written.
+  for (let page = 1; ; page += 1) {
+    const batch = await payload.find({
+      collection: usersSlug,
+      depth: 0,
+      limit: 200,
+      page,
+      sort: 'id',
+      overrideAccess: true,
+    })
+    for (const doc of batch.docs as unknown as Record<string, unknown>[]) {
+      users += 1
+      const id = doc['id']
+      const email = doc[emailField]
+      if ((typeof id !== 'string' && typeof id !== 'number') || typeof email !== 'string') {
+        unmappable.push({
+          model: 'user',
+          key: String(id),
+          reason: `document has no usable id/'${emailField}'`,
+        })
+        continue
+      }
+      const providerUserId = String(id)
+      const identities = identitiesOf(doc)
+      const own = identities.filter((row) => row.providerId === 'better-auth')
+      const conflicting = own.filter((row) => String(row.providerUserId) !== providerUserId)
+      if (conflicting.length > 0) {
+        unmappable.push({
+          model: 'user',
+          key: providerUserId,
+          reason: `user #${providerUserId} already carries a better-auth identity for a different provider user id; adopt mode serves the document id as the Better Auth user id — resolve the link by hand first`,
+        })
+        continue
+      }
+      const verified = doc[verifiedField] === true
+      if (!verified) {
+        unverified += 1
+      }
+      const writeIdentity = own.length !== 1
+      const grantProof = verified && (doc['linkable'] !== true || doc['linkableEmail'] !== email)
+      if (!writeIdentity) {
+        alreadyLinked += 1
+      }
+      if (writeIdentity || grantProof) {
+        planned.push({
+          id,
+          email,
+          writeIdentity,
+          grantProof,
+          keep: identities.filter((row) => row.providerId !== 'better-auth'),
+        })
+      }
+    }
+    if (!batch.hasNextPage) {
+      break
+    }
+  }
+
+  const linked = planned.filter((row) => row.writeIdentity).length
+  const proofGranted = planned.filter((row) => row.grantProof).length
+  if (unmappable.length > 0) {
+    log(`ABORT: ${unmappable.length} unmappable user(s); nothing was written`)
+    return {
+      users,
+      linked: 0,
+      alreadyLinked,
+      proofGranted: 0,
+      unverified,
+      unmappable,
+      fieldWrites: 0,
+    }
+  }
+
+  let fieldWriteCount = 0
+  if (apply) {
+    for (const row of planned) {
+      const { newlyCaptured } = await captureBefore({
+        payload,
+        collection: usersSlug,
+        id: row.id,
+        fields: ['identities', 'linkable', 'linkableEmail'],
+        captured,
+        into: fieldWrites,
+      })
+      fieldWriteCount += newlyCaptured
+      const data: Record<string, unknown> = {}
+      if (row.writeIdentity) {
+        data.identities = [
+          ...row.keep.map((identity) => ({
+            providerId: identity.providerId,
+            providerUserId: identity.providerUserId,
+            email: identity.email,
+            linkedAt: identity.linkedAt,
+          })),
+          {
+            providerId: 'better-auth',
+            providerUserId: String(row.id),
+            email: row.email,
+            linkedAt: now().toISOString(),
+          },
+        ]
+      }
+      if (row.grantProof) {
+        data.linkable = true
+        data.linkableEmail = row.email
+      }
+      await payload.update({ collection: usersSlug, id: row.id, data, overrideAccess: true })
+    }
+    const manifest: ImportManifest = signManifest(payload.secret, {
+      version: 3,
+      kind: 'adopt-prelink',
+      createdAt: options.manifest?.createdAt ?? now().toISOString(),
+      sourceDatabase: '(adopt mode: the target app database)',
+      options: { sessions: 'carry' },
+      created: [],
+      fieldWrites,
+      finalized: options.manifest?.finalized ?? false,
+      sourceCounts: {},
+      totals: { user: users, linked, proofGranted },
+    })
+    const { writeManifest } = await import('./lifecycle.js')
+    writeManifest(manifest, options.manifestPath)
+  }
+  return {
+    users,
+    linked,
+    alreadyLinked,
+    proofGranted,
+    unverified,
+    unmappable,
+    fieldWrites: fieldWriteCount,
+  }
+}

package/src/importer/run-import.ts

@@ -1,8 +1,10 @@
 import { isRecord } from '@payload-auth-link/core'
 import { pathToFileURL } from 'node:url'
 import { applyImport, summarizePlanRows } from './apply.js'
+import { prelinkUsers, type PrelinkResult } from './prelink.js'
 import {
   defaultManifestPath,
+  defaultPrelinkManifestPath,
   finalizeManifest,
   readManifest,
   rollbackImport,
@@ -57,6 +59,8 @@ export type ImportCommandOptions = {
   readonly json?: boolean
   readonly log?: (message: string) => void
   readonly loadPayload?: (configPath: string) => Promise<import('payload').Payload>
+  /** Accept a pre-0.6.0 manifest without a MAC (`--allow-unsigned-manifest`). */
+  readonly allowUnsignedManifest?: boolean | undefined
 }
 
 const log_ = (options: Pick<ImportCommandOptions, 'log'>): ((message: string) => void) =>
@@ -122,10 +126,17 @@ function assertTargetCollections(config: unknown, slugs: TargetSlugMap): void {
  * Boot the loaded config with a watchdog (#75): a boot that never
  * settles must fail loudly after a bounded wait, not park the CLI
  * forever.
+ *
+ * A FRESH, uncached instance (issue #88): `getPayload`'s module cache
+ * would hand a later command in the same process the instance an
+ * earlier command already destroyed. The caller owns the instance and
+ * destroys it (pool, crons) when the command ends.
  */
 async function bootPayload(config: unknown): Promise<import('payload').Payload> {
-  const { getPayload } = await import('payload')
-  const boot = getPayload({ config: config as Parameters<typeof getPayload>[0]['config'] })
+  const { BasePayload } = await import('payload')
+  const boot = new BasePayload().init({
+    config: config as Parameters<InstanceType<typeof BasePayload>['init']>[0]['config'],
+  })
   let timer: NodeJS.Timeout | undefined
   const watchdog = new Promise<never>((_, reject) => {
     timer = setTimeout(() => {
@@ -163,16 +174,93 @@ function slugsOf(options: ImportCommandOptions): TargetSlugMap {
  * be a placeholder the loader never reads.
  */
 async function bootTargetPayload(
-  options: ImportCommandOptions
+  options: ImportCommandOptions,
+  requireTargets = true
 ): Promise<import('payload').Payload> {
   if (options.loadPayload !== undefined) {
     return options.loadPayload(options.configPath)
   }
   const { config } = await loadConfigModule(options.configPath)
-  assertTargetCollections(config, slugsOf(options))
+  if (requireTargets) {
+    assertTargetCollections(config, slugsOf(options))
+  }
   return bootPayload(config)
 }
 
+/**
+ * Run `work` against the target Payload and ALWAYS release it
+ * (issue #88): an instance this command booted is destroyed —
+ * database pool closed, crons stopped — whether `work` succeeds or
+ * throws, so the CLI exits after a successful run instead of idling
+ * on open handles. An injected `loadPayload` instance belongs to the
+ * caller and is left running.
+ */
+async function withTargetPayload<T>(
+  options: ImportCommandOptions,
+  work: (payload: import('payload').Payload) => Promise<T>,
+  requireTargets = true
+): Promise<T> {
+  const payload = await bootTargetPayload(options, requireTargets)
+  try {
+    return await work(payload)
+  } finally {
+    if (options.loadPayload === undefined) {
+      await releasePayload(payload)
+    }
+  }
+}
+
+/**
+ * Destroy a booted Payload AND close its connection pool (issue #88).
+ * `payload.destroy()` stops crons and resets the adapter, but the SQL
+ * adapters' `destroy` leaves the driver pool open — and
+ * `@payloadcms/db-postgres` checks one client out of the pool at
+ * connect time and never releases it, so even `pool.end()` would wait
+ * forever. Those are exactly the handles that kept a finished CLI
+ * alive. The pool is reached structurally: every checked-out client
+ * is released-and-destroyed, then `pool.end()` (bounded); SQLite/libsql
+ * closes its `client`.
+ */
+async function releasePayload(payload: import('payload').Payload): Promise<void> {
+  const db: unknown = payload.db
+  await payload.destroy()
+  if (!isRecord(db)) {
+    return
+  }
+  const pool = db['pool']
+  if (isRecord(pool) && typeof pool['end'] === 'function') {
+    const clients: unknown = pool['_clients']
+    if (Array.isArray(clients)) {
+      for (const client of (clients as unknown[]).slice()) {
+        if (isRecord(client) && typeof client['release'] === 'function') {
+          try {
+            // `true` destroys the connection instead of returning it.
+            ;(client['release'] as (destroy: boolean) => void).call(client, true)
+          } catch {
+            // Already released (an idle client) — `end()` closes it.
+          }
+        }
+      }
+    }
+    let timer: NodeJS.Timeout | undefined
+    await Promise.race([
+      (pool['end'] as () => Promise<void>).call(pool),
+      new Promise<void>((resolve) => {
+        timer = setTimeout(resolve, 5_000)
+        timer.unref()
+      }),
+    ])
+    if (timer !== undefined) {
+      clearTimeout(timer)
+    }
+    return
+  }
+  const client = db['client']
+  if (isRecord(client) && typeof client['close'] === 'function') {
+    ;(client['close'] as () => void).call(client)
+  }
+}
+
 /**
  * Pre-flight only (no boot): refuse configs that declare no target
  * collections. Runs before EVERYTHING — including the source-database
@@ -306,20 +394,22 @@ export async function runFromPayloadAuth(options: ImportCommandOptions): Promise
   const manifestPath = options.manifestPath ?? defaultManifestPath
   const existingManifest = readManifest(manifestPath)
 
-  const payload = await bootTargetPayload(options)
-  const result = await applyImport({
-    payload,
-    sourceConnectionString: options.databaseUrl,
-    apply: options.apply,
-    sessions: options.sessions,
-    manifest: existingManifest,
-    manifestPath,
-    sourceCounts,
-    sourceDatabase: options.databaseUrl.replace(/\/\/[^@]*@/, '//***@'),
-    slugs,
-    sourceTables,
-    log,
-  })
+  const result = await withTargetPayload(options, (payload) =>
+    applyImport({
+      payload,
+      sourceConnectionString: options.databaseUrl,
+      apply: options.apply,
+      sessions: options.sessions,
+      manifest: existingManifest,
+      manifestPath,
+      sourceCounts,
+      sourceDatabase: options.databaseUrl.replace(/\/\/[^@]*@/, '//***@'),
+      slugs,
+      sourceTables,
+      log,
+      allowUnsignedManifest: options.allowUnsignedManifest,
+    })
+  )
   const plan: ImportPlan = {
     ...result.plan,
     warnings: [
@@ -340,6 +430,13 @@ export async function runFromPayloadAuth(options: ImportCommandOptions): Promise
     for (const row of plan.unmappable) {
       log(`  X ${row.model} #${row.key}: ${row.reason}`)
     }
+    if (options.apply && plan.unmappable.length === 0) {
+      log(
+        `applied: manifest at ${manifestPath} (mode 0600; ids and sealed values only). Next: verify, then finalize after your soak window.`
+      )
+    } else if (!options.apply) {
+      log('dry run: nothing was written. Re-run with --apply to copy.')
+    }
   }
   return {
     exitCode: result.plan.unmappable.length > 0 ? 1 : 0,
@@ -375,14 +472,15 @@ export async function runVerify(options: ImportCommandOptions): Promise<VerifyRe
     return result
   }
 
-  const payload = await bootTargetPayload(options)
-  const result = await verifyImport({
-    payload,
-    sourceConnectionString: options.databaseUrl,
-    slugs: slugsOf(options),
-    sourceTables: sourceTablesOf(options),
-    sessions: options.sessions,
-  })
+  const result = await withTargetPayload(options, (payload) =>
+    verifyImport({
+      payload,
+      sourceConnectionString: options.databaseUrl,
+      slugs: slugsOf(options),
+      sourceTables: sourceTablesOf(options),
+      sessions: options.sessions,
+    })
+  )
   if (!options.json) {
     for (const check of result.checks) {
       log(`  ${check.passed ? 'ok ' : 'FAIL'} ${check.name}`)
@@ -390,6 +488,7 @@ export async function runVerify(options: ImportCommandOptions): Promise<VerifyRe
     for (const issue of result.issues) {
       log(`  [${issue.code}] ${issue.detail}`)
     }
+    log(result.ok ? 'verify: ok' : `verify: ${result.issues.length} mismatch(es)`)
   }
   return result
 }
@@ -407,9 +506,21 @@ export async function runRollback(
   if (manifest.finalized) {
     throw new Error('the migration is finalized; rollback is no longer possible')
   }
-  const payload = await bootTargetPayload(options)
-  const result = await rollbackImport({ payload, manifest, log })
-  return result
+  // A prelink manifest touches only host fields; its rollback needs no
+  // ba-* target collections in the config.
+  const requireTargets = manifest.kind !== 'adopt-prelink'
+  return withTargetPayload(
+    options,
+    (payload) =>
+      rollbackImport({
+        payload,
+        manifest,
+        log,
+        manifestPath,
+        allowUnsignedManifest: options.allowUnsignedManifest,
+      }),
+    requireTargets
+  )
 }
 
 /** The `finalize` command — manifest-only; no Payload instance is loaded. */
@@ -428,3 +539,70 @@ export function runFinalize(
   )
   return Promise.resolve(finalized)
 }
+
+/** Options for `adopt-prelink` (issue #88). */
+export type PrelinkCommandOptions = Pick<
+  ImportCommandOptions,
+  'configPath' | 'apply' | 'manifestPath' | 'json' | 'log' | 'loadPayload' | 'allowUnsignedManifest'
+> & {
+  readonly usersSlug?: string | undefined
+  readonly verifiedField?: string | undefined
+}
+
+/**
+ * The `adopt-prelink` command (issues #49, #88): pre-link every adopted
+ * user (one better-auth identity; the linking proof for verified
+ * emails). Dry run by default; `--apply` writes and records the
+ * manifest that `rollback --manifest` undoes exactly.
+ */
+export async function runAdoptPrelink(options: PrelinkCommandOptions): Promise<PrelinkResult> {
+  const log = log_(options)
+  const manifestPath = options.manifestPath ?? defaultPrelinkManifestPath
+  const existing = readManifest(manifestPath)
+  if (existing !== null && existing.kind !== 'adopt-prelink') {
+    throw new Error(
+      `the manifest at ${manifestPath} belongs to an import run, not adopt-prelink — pass a different --manifest`
+    )
+  }
+  if (existing?.finalized === true) {
+    throw new Error(`the manifest at ${manifestPath} is finalized; nothing to pre-link`)
+  }
+  const importOptions: ImportCommandOptions = {
+    configPath: options.configPath,
+    databaseUrl: '',
+    apply: options.apply,
+    sessions: 'carry',
+    ...(options.loadPayload === undefined ? {} : { loadPayload: options.loadPayload }),
+  }
+  const result = await withTargetPayload(
+    importOptions,
+    (payload) =>
+      prelinkUsers({
+        payload,
+        apply: options.apply,
+        manifest: existing,
+        manifestPath,
+        usersSlug: options.usersSlug,
+        verifiedField: options.verifiedField,
+        log,
+        allowUnsignedManifest: options.allowUnsignedManifest,
+      }),
+    false
+  )
+  if (options.json !== true) {
+    log(
+      `  users ${result.users}: ${result.linked} to link, ${result.alreadyLinked} already linked, ${result.proofGranted} verified-email proof grant(s), ${result.unverified} unverified (identity only)`
+    )
+    for (const row of result.unmappable) {
+      log(`  X ${row.model} #${row.key}: ${row.reason}`)
+    }
+    if (result.unmappable.length === 0) {
+      log(
+        options.apply
+          ? `applied: manifest at ${manifestPath} (mode 0600). Undo with: rollback --config <config> --manifest ${manifestPath}`
+          : 'dry run: nothing was written. Re-run with --apply to pre-link.'
+      )
+    }
+  }
+  return result
+}