@payload-auth-link/migrate 0.4.2 → 0.5.0

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,
@@ -122,10 +124,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 +172,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 +392,21 @@ 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,
+    })
+  )
   const plan: ImportPlan = {
     ...result.plan,
     warnings: [
@@ -340,6 +427,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 +469,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 +485,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 +503,14 @@ 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 }),
+    requireTargets
+  )
 }
 
 /** The `finalize` command — manifest-only; no Payload instance is loaded. */
@@ -428,3 +529,69 @@ export function runFinalize(
   )
   return Promise.resolve(finalized)
 }
+
+/** Options for `adopt-prelink` (issue #88). */
+export type PrelinkCommandOptions = Pick<
+  ImportCommandOptions,
+  'configPath' | 'apply' | 'manifestPath' | 'json' | 'log' | 'loadPayload'
+> & {
+  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,
+      }),
+    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
+}

package/src/importer/source.ts

@@ -31,10 +31,22 @@ export type SourceUser = {
   /** Stored role values from the `users_role` child table. */
   readonly roles: readonly string[]
   readonly accounts: readonly SourceAccount[]
+  /**
+   * Better Auth admin-plugin ban state (issue #88), `null` when the
+   * source layout has no such column (the plugin was never installed).
+   */
+  readonly banned: boolean | null
+  readonly banReason: string | null
+  readonly banExpires: Date | null
+  /** Better Auth anonymous-plugin marker; `null` when no column exists. */
+  readonly isAnonymous: boolean | null
 }
 
 export type SourceAccount = {
   readonly id: string
+  /** Source row timestamps, carried onto the target row (issue #88). */
+  readonly createdAt: Date | null
+  readonly updatedAt: Date | null
   readonly accountId: string
   readonly providerId: string
   readonly password: string | null
@@ -76,14 +88,24 @@ const requiredColumns: Readonly<Record<SourceModel, readonly string[]>> = {
   users_role: ['parent_id', 'value'],
 }
 
-export async function openSource(connectionString: string): Promise<Client> {
+/**
+ * The slice of a `pg` client the read side uses. Public signatures take
+ * this structural type (a `pg.Client` satisfies it) so the published
+ * `.d.ts` never references `pg` — consumers need no `@types/pg`.
+ */
+export interface SourceClient {
+  query(text: string, values?: unknown[]): Promise<{ rows: unknown[] }>
+  end(): Promise<void>
+}
+
+export async function openSource(connectionString: string): Promise<SourceClient> {
   const client = new Client({ connectionString })
   await client.connect()
   return client
 }
 
 /** The columns one table actually has (customized layouts drop columns). */
-async function columnsOf(client: Client, table: string): Promise<Set<string>> {
+async function columnsOf(client: SourceClient, table: string): Promise<Set<string>> {
   const result = await client.query(
     `SELECT column_name FROM information_schema.columns
      WHERE table_schema = 'public' AND table_name = $1`,
@@ -92,7 +114,7 @@ async function columnsOf(client: Client, table: string): Promise<Set<string>> {
   return new Set(result.rows.map((row) => String((row as { column_name: unknown }).column_name)))
 }
 
-async function tableExists(client: Client, table: string): Promise<boolean> {
+async function tableExists(client: SourceClient, table: string): Promise<boolean> {
   const result = await client.query(
     `SELECT 1 FROM information_schema.tables WHERE table_schema = 'public' AND table_name = $1`,
     [table]
@@ -108,7 +130,7 @@ async function tableExists(client: Client, table: string): Promise<boolean> {
  * read, planned, or written past a failed probe.
  */
 export async function probeSourceLayout(
-  client: Client,
+  client: SourceClient,
   tables: ResolvedSourceTables
 ): Promise<readonly SourceLayoutIssue[]> {
   const issues: SourceLayoutIssue[] = []
@@ -146,7 +168,7 @@ export async function probeSourceLayout(
  * throw here means the probe was skipped.
  */
 export async function countTables(
-  client: Client,
+  client: SourceClient,
   tables: readonly string[]
 ): Promise<Record<string, number>> {
   const counts: Record<string, number> = {}
@@ -170,7 +192,7 @@ function text(value: unknown): string | null {
 
 /** Every source user, with role rows and accounts attached. */
 export async function readSourceUsers(
-  client: Client,
+  client: SourceClient,
   tables: ResolvedSourceTables = defaultSourceTables
 ): Promise<SourceUser[]> {
   const usersTable = tables['users']
@@ -179,8 +201,14 @@ export async function readSourceUsers(
   if (usersTable === null) {
     return []
   }
+  // Plugin columns (admin bans, anonymous marker) exist only when the
+  // payload-auth app installed those plugins — read them when present.
+  const userColumns = await columnsOf(client, usersTable)
+  const optionalUserColumns = ['banned', 'ban_reason', 'ban_expires', 'is_anonymous'].filter(
+    (column) => userColumns.has(column)
+  )
   const users = await client.query(
-    `SELECT id, email, name, email_verified, image, created_at, updated_at FROM ${usersTable} ORDER BY id`
+    `SELECT ${['id', 'email', 'name', 'email_verified', 'image', 'created_at', 'updated_at', ...optionalUserColumns].join(', ')} FROM ${usersTable} ORDER BY id`
   )
   const rolesTable = tables['users_role']
   const roleRows =
@@ -193,19 +221,37 @@ export async function readSourceUsers(
     list.push(row.value)
     rolesByUser.set(String(row.parent_id), list)
   }
+  const accountColumns =
+    accountsTable === null ? new Set<string>() : await columnsOf(client, accountsTable)
+  const accountTimestamps = ['created_at', 'updated_at'].filter((column) =>
+    accountColumns.has(column)
+  )
   const accounts =
     accountsTable === null
       ? { rows: [] as unknown[] }
       : await client.query(
-          `SELECT id, account_id, provider_id, password, access_token, refresh_token, id_token,
-            scope, access_token_expires_at, refresh_token_expires_at, user_id
-     FROM ${accountsTable} ORDER BY id`
+          `SELECT ${[
+            'id',
+            'account_id',
+            'provider_id',
+            'password',
+            'access_token',
+            'refresh_token',
+            'id_token',
+            'scope',
+            'access_token_expires_at',
+            'refresh_token_expires_at',
+            'user_id',
+            ...accountTimestamps,
+          ].join(', ')} FROM ${accountsTable} ORDER BY id`
         )
   const accountsByUser = new Map<string, SourceAccount[]>()
   for (const row of accounts.rows as Record<string, unknown>[]) {
     const userId = String(row.user_id)
     const account: SourceAccount = {
       id: String(row.id),
+      createdAt: iso(row.created_at),
+      updatedAt: iso(row.updated_at),
       accountId: String(row.account_id),
       providerId: String(row.provider_id),
       password: text(row.password),
@@ -233,6 +279,10 @@ export async function readSourceUsers(
       updatedAt: iso(row.updated_at) ?? new Date(),
       roles: rolesByUser.get(id) ?? [],
       accounts: accountsByUser.get(id) ?? [],
+      banned: userColumns.has('banned') ? row.banned === true : null,
+      banReason: userColumns.has('ban_reason') ? text(row.ban_reason) : null,
+      banExpires: userColumns.has('ban_expires') ? iso(row.ban_expires) : null,
+      isAnonymous: userColumns.has('is_anonymous') ? row.is_anonymous === true : null,
     })
   }
   return out
@@ -244,14 +294,22 @@ export async function readSourceUsers(
  * asking for it, and an unmapped missing table aborts at the probe.
  */
 export async function readFlatRows(
-  client: Client,
+  client: SourceClient,
   table: string,
-  columns: readonly string[]
+  columns: readonly string[],
+  /**
+   * Columns read only when the layout has them (issue #88: row
+   * timestamps) — an absent optional column is simply not selected,
+   * and the row carries no key for it.
+   */
+  optionalColumns: readonly string[] = []
 ): Promise<SourceRow[]> {
   if (!(await tableExists(client, table))) {
     throw new Error(`source table '${table}' is missing — run probeSourceLayout first`)
   }
-  const result = await client.query(`SELECT ${columns.join(', ')} FROM ${table} ORDER BY id`)
+  const existing = optionalColumns.length > 0 ? await columnsOf(client, table) : new Set<string>()
+  const selected = [...columns, ...optionalColumns.filter((column) => existing.has(column))]
+  const result = await client.query(`SELECT ${selected.join(', ')} FROM ${table} ORDER BY id`)
   return result.rows as SourceRow[]
 }
 
@@ -274,7 +332,7 @@ export type OrphanScan = {
  * of passing silently.
  */
 export async function findOrphans(
-  client: Client,
+  client: SourceClient,
   tables: ResolvedSourceTables = defaultSourceTables
 ): Promise<OrphanScan> {
   const orphans: Unmappable[] = []

package/src/importer/types.ts

@@ -2,6 +2,12 @@
  * Importer manifest (issue #50): every row created and every field
  * changed, so `rollback` is exact. The manifest is the run's contract —
  * `verify`, `rollback`, and `finalize` all read it.
+ *
+ * Privacy (issue #88): a version-2 manifest holds NO email address or
+ * other field value in the clear. Created rows are named by ids only,
+ * and every captured prior value is sealed (AES-256-GCM, keyed from the
+ * target app's Payload `secret`), so only the same app can restore it.
+ * The file is written with mode 0600.
  */
 export type CreatedRow = {
   /** Target collection slug. */
@@ -16,12 +22,27 @@ export type FieldWrite = {
   readonly collection: string
   readonly id: string | number
   readonly field: string
-  /** The prior value, JSON-serialized, restored by rollback. */
-  readonly before: string | null
+  /**
+   * The prior value, JSON-serialized — version-1 manifests only.
+   * Version 2 never stores values in the clear; see `sealedBefore`.
+   */
+  readonly before?: string | null | undefined
+  /**
+   * The prior value, JSON-serialized and sealed with the target app's
+   * Payload secret (version 2, issue #88), restored by rollback. Only
+   * the FIRST capture per document field is kept, so a rollback after
+   * any number of `--apply` passes restores the pre-import state.
+   */
+  readonly sealedBefore?: string | undefined
 }
 
+/** Which command produced the manifest (issue #88). */
+export type ManifestKind = 'import' | 'adopt-prelink'
+
 export type ImportManifest = {
-  readonly version: 1
+  readonly version: 1 | 2
+  /** The producing command; absent on version-1 manifests (imports). */
+  readonly kind?: ManifestKind | undefined
   readonly createdAt: string
   readonly sourceDatabase: string
   readonly options: {
@@ -32,8 +53,10 @@ export type ImportManifest = {
   readonly finalized: boolean
   /** Counts per source table at plan time (the rollback baseline). */
   readonly sourceCounts: Readonly<Record<string, number>>
-  /** Cumulative plan totals (rows created + skipped across resumes). */
+  /** Rows the LATEST pass planned per model — never summed across passes (#88). */
   readonly totals: Readonly<Record<string, number>>
+  /** When the last rollback reset this manifest (issue #88). */
+  readonly rolledBackAt?: string | undefined
 }
 
 /** Per-model plan row for the dry run. */

package/src/index.ts

@@ -16,7 +16,16 @@ export { classifyPlugins, pluginsFromSourceTree } from './doctor/plugins.js'
 export { scanSource, projectedUserFields, listSourceFiles } from './doctor/source-scan.js'
 export { analyzeUsersCollection, findUsersCollection, localStrategyOn } from './doctor/users.js'
 export { introspectDatabase } from './doctor/database.js'
-export { runFromPayloadAuth, runVerify, runRollback, runFinalize } from './importer/run-import.js'
+export {
+  runFromPayloadAuth,
+  runVerify,
+  runRollback,
+  runFinalize,
+  runAdoptPrelink,
+  type ImportCommandOptions,
+  type PrelinkCommandOptions,
+} from './importer/run-import.js'
+export { prelinkUsers, type PrelinkOptions, type PrelinkResult } from './importer/prelink.js'
 export { applyImport, summarizePlanRows } from './importer/apply.js'
 export {
   countTables,
@@ -27,6 +36,7 @@ export {
   readSourceUsers,
   unverifiedEmails,
   type OrphanScan,
+  type SourceClient,
   type SourceLayoutIssue,
   type SourceAccount,
   type SourceRow,
@@ -39,6 +49,7 @@ export {
   rollbackImport,
   finalizeManifest,
   defaultManifestPath,
+  defaultPrelinkManifestPath,
   type VerifyIssue,
   type VerifyResult,
 } from './importer/lifecycle.js'
@@ -57,6 +68,7 @@ export {
   type TargetSlugMap,
   type FieldWrite,
   type ImportManifest,
+  type ManifestKind,
   type ImportPlan,
   type ImportResult,
   type PlanRow,

package/src/private-file.ts

@@ -0,0 +1,18 @@
+import { closeSync, fchmodSync, ftruncateSync, openSync, writeSync } from 'node:fs'
+
+/**
+ * Write `content` to `path` readable by the owner only (0600). The
+ * mode is tightened on the open descriptor BEFORE any content lands, so
+ * a pre-existing world-readable file (an older kit's manifest, a
+ * reused `--out` path) never holds the new content with its old mode.
+ */
+export function writePrivateFile(path: string, content: string): void {
+  const fd = openSync(path, 'a', 0o600)
+  try {
+    fchmodSync(fd, 0o600)
+    ftruncateSync(fd, 0)
+    writeSync(fd, content, 0)
+  } finally {
+    closeSync(fd)
+  }
+}