@payload-auth-link/migrate 0.6.0 → 0.7.0

package/src/importer/lifecycle.ts

@@ -1,10 +1,19 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { writePrivateFile } from '../private-file.js'
 import type { Payload } from 'payload'
+import {
+  assertCreatedRowsScoped,
+  baIdMismatch,
+  finalizeMarkerState,
+  hostRolesField,
+  recordFinalizeMarker,
+  targetSlugsOf,
+} from './guards.js'
 import { restoreCaptured } from './host-writes.js'
 import { authenticateManifest, signManifest } from './manifest-mac.js'
 import {
   defaultTargetSlugs,
+  type CreatedRow,
   resolveSourceTables,
   sourceModelNames,
   type ResolvedSourceTables,
@@ -13,9 +22,10 @@ import {
 
 /**
  * Manifest lifecycle (issue #50): `verify` checks both sides, `rollback`
- * undoes exactly what the manifest records, and `finalize` marks the
- * manifest so the source tables may be dropped — by the operator, as a
- * separate later step.
+ * undoes exactly what the manifest records, and `finalize` records the
+ * point of no return (a database marker plus the re-signed manifest) so
+ * the source tables may be dropped — by the operator, as a separate
+ * later step.
  */
 
 /**
@@ -262,6 +272,9 @@ export async function verifyImport(options: {
     // lookup findByProviderIdentity issues on the next provider
     // sign-in. The host docs also carry the stored roles (issue #68's
     // users_role accounting) whenever the host declares the field.
+    // The roles field the app configured on authLink (issue #110: a
+    // hard-coded `roles` silently skipped the check on `role` layouts).
+    const rolesField = hostRolesField(payload)
     let identityIssues = 0
     let roleMismatchDocs = 0
     let hostDocsWithRoles = 0
@@ -301,7 +314,7 @@ export async function verifyImport(options: {
       if (identities.length !== 1 || resolving.length !== 1) {
         identityIssues += 1
       }
-      const roles = record['roles']
+      const roles = record[rolesField]
       if (Array.isArray(roles)) {
         hostDocsWithRoles += 1
         const stored = new Set(roles.map((role) => String(role)))
@@ -319,11 +332,11 @@ export async function verifyImport(options: {
       check(
         'source roles carried onto the host docs',
         roleMismatchDocs === 0,
-        `${roleMismatchDocs} host doc(s) missing stored role values`
+        `${roleMismatchDocs} host doc(s) missing stored role values in '${rolesField}'`
       )
     } else if (sourceTables['users_role'] !== null && users.some((user) => user.roles.length > 0)) {
       checks.push({
-        name: 'source roles carried onto the host docs (skipped: the host users carry no roles field)',
+        name: `source roles carried onto the host docs (skipped: the host users carry no '${rolesField}' field)`,
         passed: true,
       })
     }
@@ -486,13 +499,8 @@ export async function verifyImport(options: {
   return { ok: issues.length === 0, issues, checks }
 }
 
-/**
- * Rollback (issue #50): delete the created rows in reverse order and
- * restore every captured field value. The manifest records exactly
- * what to undo — nothing else is touched, and the source tables were
- * never modified.
- */
-export async function rollbackImport(options: {
+/** Options of {@link rollbackImport}. */
+export type RollbackOptions = {
   readonly payload: Payload
   readonly manifest: ImportManifest
   readonly log?: (message: string) => void
@@ -504,9 +512,44 @@ export async function rollbackImport(options: {
    */
   readonly manifestPath?: string | undefined
   readonly now?: (() => Date) | undefined
-  /** Accept a pre-0.6.0 manifest that has no MAC (`--allow-unsigned-manifest`). */
+  /** Target slugs the import ran with (`--slugs`); defaults to the ba-* set. */
+  readonly slugs?: Readonly<Record<string, string>> | undefined
+  /**
+   * Accept a manifest without a full signature (`--allow-unsigned-manifest`):
+   * a pre-0.6.0 manifest without a MAC, or a 0.6.0 manifest whose MAC
+   * does not cover `finalized`.
+   */
   readonly allowUnsignedManifest?: boolean | undefined
-}): Promise<{ deleted: number; restored: number }> {
+  /**
+   * Let a rollback driven by an UNSIGNED (pre-0.6.0) manifest delete the
+   * rows it lists and restore plaintext (version-1) values
+   * (`--allow-unsigned-deletes`). Without it, an unsigned manifest may
+   * only restore sealed field values.
+   */
+  readonly allowUnsignedDeletes?: boolean | undefined
+}
+
+/**
+ * Rollback (issue #50): delete the created rows in reverse order and
+ * restore every captured field value. The manifest records exactly
+ * what to undo — nothing else is touched, and the source tables were
+ * never modified.
+ *
+ * Before anything is written, rollback refuses: a finalized manifest,
+ * or a migration the DATABASE records as finalized (the marker
+ * `finalize` writes — a manifest file alone cannot reopen it); a
+ * manifest that fails its signature; created rows outside the import's
+ * own target collections (signed or not), or whose row no longer
+ * carries the importer's deterministic `baId`; and any delete or
+ * plaintext restore driven by an unsigned manifest without
+ * `allowUnsignedDeletes`. A row already absent is fine (the goal is
+ * "absent"); a delete that FAILS (a foreign key, a hook, a permission)
+ * aborts the rollback with the rows named, before any field is
+ * restored or the manifest reset — so it can be re-run once fixed.
+ */
+export async function rollbackImport(
+  options: RollbackOptions
+): Promise<{ deleted: number; restored: number }> {
   const { payload, manifest, log = () => {} } = options
   if (manifest.finalized) {
     // The point of no return: after `finalize`, the manifest's rows are
@@ -515,21 +558,93 @@ export async function rollbackImport(options: {
   }
   // Every row below is deleted, and every field restored, with
   // overrideAccess: only a manifest this app signed may drive that.
-  authenticateManifest(payload.secret, manifest, { allowUnsigned: options.allowUnsignedManifest })
-  let deleted = 0
+  const trust = authenticateManifest(payload.secret, manifest, {
+    allowUnsigned: options.allowUnsignedManifest,
+  })
+  if (trust === 'signed-legacy' && options.allowUnsignedManifest !== true) {
+    throw new Error(
+      "the manifest was signed by migrate 0.6.0, whose signature does not cover the 'finalized' flag. If you are sure this migration was never finalized and nobody has edited the manifest, re-run with --allow-unsigned-manifest; the rollback re-signs what it leaves behind"
+    )
+  }
+  // The database's own record of `finalize`, independent of the file.
+  // A manifest whose `createdAt` is not covered by a full signature is
+  // checked against every finalized migration of its kind.
+  const marker = await finalizeMarkerState(payload, manifest, { anyOfKind: trust !== 'signed' })
+  if (marker === 'finalized') {
+    throw new Error(
+      'the database records this migration as finalized; rollback is no longer possible (the manifest file does not override that)'
+    )
+  }
+  if (marker === 'unavailable') {
+    log(
+      "rollback: Payload's key-value store is unavailable, so the database finalize marker could not be checked; relying on the manifest's own flag"
+    )
+  }
+  assertCreatedRowsScoped(manifest, targetSlugsOf(options.slugs))
+  if (trust === 'unsigned' && options.allowUnsignedDeletes !== true) {
+    const plaintext = manifest.fieldWrites.filter((write) => write.before !== undefined).length
+    if (manifest.created.length > 0 || plaintext > 0) {
+      throw new Error(
+        `the manifest is unsigned: --allow-unsigned-manifest lets it restore sealed field values only, and it lists ${manifest.created.length} row(s) to delete and ${plaintext} plaintext value(s) to restore. Review the manifest's created rows, then re-run with --allow-unsigned-deletes as well — nothing was changed`
+      )
+    }
+  }
+
+  // Pre-flight every created row BEFORE the first delete: a present row
+  // must still carry the importer's deterministic baId for its source
+  // key (the imported row, not one that took its id since).
+  const present: CreatedRow[] = []
+  const foreign: string[] = []
+  let absent = 0
   for (const row of [...manifest.created].reverse()) {
+    const doc = await findRow(payload, row)
+    if (doc === null) {
+      absent += 1
+    } else if (baIdMismatch(row, doc)) {
+      foreign.push(`${row.collection}#${String(row.id)} (${row.sourceKey})`)
+    } else {
+      present.push(row)
+    }
+  }
+  if (foreign.length > 0) {
+    throw new Error(
+      `${foreign.length} created row(s) no longer carry the baId the importer gave them, so they are not the imported rows: ${listSome(foreign, ', ')}. Refusing to delete anything`
+    )
+  }
+
+  let deleted = 0
+  const failed: string[] = []
+  for (const row of present) {
     try {
       await payload.delete({ collection: row.collection, id: row.id, overrideAccess: true })
       deleted += 1
-    } catch {
-      // Already gone (a crash after delete, a manual cleanup) — the
-      // goal state is "row absent", so absence is success.
-      log(`rollback: ${row.collection}#${row.id} already absent`)
+    } catch (error) {
+      if ((await findRow(payload, row)) === null) {
+        // Removed concurrently: the goal state is "row absent".
+        absent += 1
+        continue
+      }
+      failed.push(
+        `${row.collection}#${String(row.id)}: ${error instanceof Error ? error.message : String(error)}`
+      )
     }
   }
+  if (failed.length > 0) {
+    for (const line of failed) {
+      log(`rollback: FAILED to delete ${line}`)
+    }
+    throw new Error(
+      `rollback deleted ${deleted} row(s) but could not delete ${failed.length}: ${listSome(failed, '; ')}. No field value was restored and the manifest was kept — fix the cause (e.g. rows that reference them) and re-run rollback`
+    )
+  }
+  if (absent > 0) {
+    log(`rollback: ${absent} created row(s) were already absent`)
+  }
   // Captured values go back through the adapter, one write per
   // document, `updatedAt` included — see host-writes.ts for why.
-  const restored = await restoreCaptured(payload, manifest)
+  const restored = await restoreCaptured(payload, manifest, {
+    rolesField: hostRolesField(payload),
+  })
   if (options.manifestPath !== undefined) {
     const reset: ImportManifest = signManifest(payload.secret, {
       ...manifest,
@@ -544,12 +659,53 @@ export async function rollbackImport(options: {
   return { deleted, restored }
 }
 
-/** Finalize (issue #50): the point of no return — mark the manifest. */
-export function finalizeManifest(manifest: ImportManifest, path: string): ImportManifest {
-  if (manifest.finalized) {
-    return manifest
-  }
-  const finalized: ImportManifest = { ...manifest, finalized: true }
-  writeManifest(finalized, path)
+/** The created row as stored, or `null` when it does not exist. */
+async function findRow(payload: Payload, row: CreatedRow): Promise<unknown> {
+  const doc: unknown = await payload.findByID({
+    collection: row.collection,
+    id: row.id,
+    depth: 0,
+    overrideAccess: true,
+    disableErrors: true,
+  })
+  return doc ?? null
+}
+
+function listSome(items: readonly string[], separator: string): string {
+  return `${items.slice(0, 10).join(separator)}${items.length > 10 ? `${separator}…` : ''}`
+}
+
+/** Options of {@link finalizeManifest}. */
+export type FinalizeOptions = {
+  readonly payload: Payload
+  readonly manifest: ImportManifest
+  /** Where the finalized, re-signed manifest is written. */
+  readonly path: string
+  readonly now?: (() => Date) | undefined
+  /** Accept a manifest without a full signature (`--allow-unsigned-manifest`). */
+  readonly allowUnsignedManifest?: boolean | undefined
+}
+
+/**
+ * Finalize (issue #50): the point of no return. Records a one-way
+ * marker in the target database (Payload's key-value store) that every
+ * later rollback checks independently of the file, then marks the
+ * manifest `finalized` and re-signs it — the signature covers the flag.
+ * Idempotent: finalizing a finalized manifest re-records the marker and
+ * upgrades its signature.
+ */
+export async function finalizeManifest(options: FinalizeOptions): Promise<ImportManifest> {
+  const { payload, manifest } = options
+  authenticateManifest(payload.secret, manifest, { allowUnsigned: options.allowUnsignedManifest })
+  const finalizedAt = manifest.finalizedAt ?? (options.now ?? (() => new Date()))().toISOString()
+  // The database marker first: a finalize that cannot record it fails
+  // with the manifest unchanged.
+  await recordFinalizeMarker(payload, manifest, finalizedAt)
+  const finalized: ImportManifest = signManifest(payload.secret, {
+    ...manifest,
+    finalized: true,
+    finalizedAt,
+  })
+  writeManifest(finalized, options.path)
   return finalized
 }

package/src/importer/manifest-mac.ts

@@ -2,26 +2,36 @@ import { createHash, createHmac, timingSafeEqual } from 'node:crypto'
 import type { ImportManifest } from './types.js'
 
 /**
- * Manifest integrity (GHSA-p76j-5qwx-rpwx follow-up). Sealing each
- * captured value is not enough: the manifest also says WHICH rows
- * rollback deletes (`created`) and WHICH fields it restores
- * (`fieldWrites`), and both run with `overrideAccess`. A version-3
- * manifest therefore carries an HMAC-SHA256 over its whole body, keyed
- * from the target app's Payload `secret`. Rollback and every resumed
- * `--apply` refuse a manifest whose MAC does not verify, so an edited
- * file can neither delete arbitrary rows nor set arbitrary fields, and
- * a re-run never re-signs an edited file.
+ * Manifest integrity. Sealing each captured value is not enough: the
+ * manifest also says WHICH rows rollback deletes (`created`), WHICH
+ * fields it restores (`fieldWrites`), and WHETHER rollback is still
+ * allowed (`finalized`), and those writes run with `overrideAccess`. A
+ * version-3 manifest therefore carries an HMAC-SHA256 over its whole
+ * body, keyed from the target app's Payload `secret`. Rollback, every
+ * resumed `--apply`, and `finalize` refuse a manifest whose MAC does
+ * not verify, so an edited file can neither delete arbitrary rows, set
+ * arbitrary fields, nor reopen a finalized migration — and a re-run
+ * never re-signs an edited file.
  *
- * `finalized` is left out of the MAC: `finalize` is manifest-only and
- * loads no Payload instance (so it has no secret). The flag only ever
- * blocks rollback, and the rows a rollback would touch stay covered.
+ * Two MAC schemes exist:
+ *
+ * - `v2.` covers EVERY field, `finalized` included: `finalize` boots
+ *   the target app, so it holds the secret and signs its own write.
+ * - `v1.` (migrate 0.6.0) left `finalized` out, because `finalize`
+ *   then loaded no Payload instance. Such a manifest still verifies —
+ *   its rows and field writes are covered — but its `finalized` flag
+ *   is not, so it authenticates as `signed-legacy` and destructive
+ *   callers gate on that. The next write re-signs it under `v2.`.
  */
 
-const macPrefix = 'v1.'
+const macPrefix = 'v2.'
+const legacyMacPrefix = 'v1.'
+
+type MacScheme = 'v1' | 'v2'
 
-function macKey(secret: string): Buffer {
+function macKey(secret: string, scheme: MacScheme): Buffer {
   return createHash('sha256')
-    .update('payload-auth-link/migrate/manifest-mac/v1\u0000')
+    .update(`payload-auth-link/migrate/manifest-mac/${scheme}\u0000`)
     .update(secret)
     .digest()
 }
@@ -40,18 +50,39 @@ function canonical(value: unknown): string {
   return JSON.stringify(value)
 }
 
-function macOf(secret: string, manifest: ImportManifest): string {
+function macOf(secret: string, manifest: ImportManifest, scheme: MacScheme): string {
   const body: Record<string, unknown> = { ...manifest }
   delete body['mac']
-  delete body['finalized']
-  const digest = createHmac('sha256', macKey(secret)).update(canonical(body)).digest()
-  return `${macPrefix}${digest.toString('base64url')}`
+  if (scheme === 'v1') {
+    // The 0.6.0 scheme kept `finalized` outside the MAC.
+    delete body['finalized']
+  }
+  const digest = createHmac('sha256', macKey(secret, scheme)).update(canonical(body)).digest()
+  return `${scheme === 'v1' ? legacyMacPrefix : macPrefix}${digest.toString('base64url')}`
 }
 
-/** Stamp `manifest` as version 3 and sign it under the app's secret. */
+/** Stamp `manifest` as version 3 and sign every field under the app's secret. */
 export function signManifest(secret: string, manifest: ImportManifest): ImportManifest {
   const unsigned: ImportManifest = { ...manifest, version: 3, mac: undefined }
-  return { ...unsigned, mac: macOf(secret, unsigned) }
+  return { ...unsigned, mac: macOf(secret, unsigned, 'v2') }
+}
+
+/**
+ * How far a manifest is vouched for:
+ *
+ * - `signed`: a `v2.` MAC verified; every field, `finalized` included,
+ *   is the app's own.
+ * - `signed-legacy`: a 0.6.0 `v1.` MAC verified; rows and field writes
+ *   are the app's own, `finalized` is NOT covered.
+ * - `unsigned`: a version-1/2 manifest (pre-0.6.0) the operator vouched
+ *   for with `--allow-unsigned-manifest`; nothing is covered.
+ */
+export type ManifestTrust = 'signed' | 'signed-legacy' | 'unsigned'
+
+function macMatches(expected: string, actual: string): boolean {
+  const want = Buffer.from(expected, 'utf8')
+  const got = Buffer.from(actual, 'utf8')
+  return got.length === want.length && timingSafeEqual(got, want)
 }
 
 /**
@@ -60,22 +91,25 @@ export function signManifest(secret: string, manifest: ImportManifest): ImportMa
  * (written before 0.6.0) has no MAC: it is accepted only when the
  * operator passes `allowUnsigned` (`--allow-unsigned-manifest`) to vouch
  * for the file, and even then a version-2 manifest may not hold
- * plaintext values, which that version never wrote.
+ * plaintext values, which that version never wrote. Returns how far the
+ * manifest is vouched for; destructive callers gate on it.
  */
 export function authenticateManifest(
   secret: string,
   manifest: ImportManifest,
   options: { readonly allowUnsigned?: boolean | undefined } = {}
-): void {
+): ManifestTrust {
   if (manifest.version === 3) {
-    const expected = Buffer.from(macOf(secret, manifest), 'utf8')
-    const actual = Buffer.from(typeof manifest.mac === 'string' ? manifest.mac : '', 'utf8')
-    if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
-      throw new Error(
-        'the manifest failed its integrity check: it was edited, or written by an app with a different PAYLOAD_SECRET. Refusing to use it — run against the same app that wrote it, with the manifest it wrote'
-      )
+    const mac = typeof manifest.mac === 'string' ? manifest.mac : ''
+    if (mac.startsWith(macPrefix) && macMatches(macOf(secret, manifest, 'v2'), mac)) {
+      return 'signed'
     }
-    return
+    if (mac.startsWith(legacyMacPrefix) && macMatches(macOf(secret, manifest, 'v1'), mac)) {
+      return 'signed-legacy'
+    }
+    throw new Error(
+      'the manifest failed its integrity check: it was edited, or written by an app with a different PAYLOAD_SECRET. Refusing to use it — run against the same app that wrote it, with the manifest it wrote'
+    )
   }
   if (options.allowUnsigned !== true) {
     throw new Error(
@@ -87,4 +121,5 @@ export function authenticateManifest(
       'the version-2 manifest holds a plaintext prior value, which version 2 never writes (edited manifest?); refusing to use it'
     )
   }
+  return 'unsigned'
 }

package/src/importer/prelink.ts

@@ -1,4 +1,5 @@
 import type { Payload } from 'payload'
+import { assertCreatedRowsScoped, finalizeMarkerState, targetSlugsOf } from './guards.js'
 import { capturedKeys, captureBefore } from './host-writes.js'
 import { authenticateManifest, signManifest } from './manifest-mac.js'
 import type { FieldWrite, ImportManifest, Unmappable } from './types.js'
@@ -81,9 +82,20 @@ export async function prelinkUsers(options: PrelinkOptions): Promise<PrelinkResu
   const emailField = options.emailField ?? 'email'
   if (options.manifest !== null) {
     // Resuming re-signs the old entries: verify them first.
-    authenticateManifest(payload.secret, options.manifest, {
+    const trust = authenticateManifest(payload.secret, options.manifest, {
       allowUnsigned: options.allowUnsignedManifest,
     })
+    // A pre-link creates no rows: never re-sign a manifest that lists some.
+    assertCreatedRowsScoped({ ...options.manifest, kind: 'adopt-prelink' }, targetSlugsOf())
+    if (
+      apply &&
+      (options.manifest.finalized ||
+        (await finalizeMarkerState(payload, options.manifest, {
+          anyOfKind: trust !== 'signed',
+        })) === 'finalized')
+    ) {
+      throw new Error('the pre-link is finalized; nothing to pre-link')
+    }
   }
   const fieldWrites: FieldWrite[] = [...(options.manifest?.fieldWrites ?? [])]
   const captured = capturedKeys(fieldWrites)

package/src/importer/run-import.ts

@@ -39,8 +39,9 @@ import {
  * Dry run prints planned row counts per model, collisions, and
  * anything unmappable; unmappable data aborts `--apply` before any
  * write. The manifest records every created row and field change;
- * source tables are never modified — `finalize` only marks the
- * manifest, and dropping them stays the operator's later step.
+ * source tables are never modified — `finalize` records the point of
+ * no return (in the database and the re-signed manifest), and dropping
+ * them stays the operator's later step.
  */
 
 export type ImportCommandOptions = {
@@ -59,8 +60,18 @@ 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`). */
+  /**
+   * Accept a manifest without a full signature (`--allow-unsigned-manifest`):
+   * a pre-0.6.0 manifest without a MAC, or a 0.6.0 one whose MAC does
+   * not cover `finalized`.
+   */
   readonly allowUnsignedManifest?: boolean | undefined
+  /**
+   * `rollback` only (`--allow-unsigned-deletes`): let an UNSIGNED
+   * manifest delete its created rows and restore plaintext values.
+   * Without it, `--allow-unsigned-manifest` never deletes anything.
+   */
+  readonly allowUnsignedDeletes?: boolean | undefined
 }
 
 const log_ = (options: Pick<ImportCommandOptions, 'log'>): ((message: string) => void) =>
@@ -517,27 +528,57 @@ export async function runRollback(
         manifest,
         log,
         manifestPath,
+        slugs: slugsOf(options),
         allowUnsignedManifest: options.allowUnsignedManifest,
+        allowUnsignedDeletes: options.allowUnsignedDeletes,
       }),
     requireTargets
   )
 }
 
-/** The `finalize` command — manifest-only; no Payload instance is loaded. */
-export function runFinalize(
-  options: Pick<ImportCommandOptions, 'manifestPath' | 'log'>
-): Promise<ImportManifest> {
+/** Options for `finalize`: the target app (for the secret and the database marker). */
+export type FinalizeCommandOptions = Pick<
+  ImportCommandOptions,
+  'configPath' | 'manifestPath' | 'log' | 'loadPayload' | 'allowUnsignedManifest' | 'slugsJson'
+>
+
+/**
+ * The `finalize` command: boots the target app (like `rollback`), records
+ * the one-way finalize marker in its database, and re-signs the manifest
+ * with `finalized` covered by the signature.
+ */
+export async function runFinalize(options: FinalizeCommandOptions): Promise<ImportManifest> {
   const log = log_(options)
   const manifestPath = options.manifestPath ?? defaultManifestPath
   const manifest = readManifest(manifestPath)
   if (manifest === null) {
-    return Promise.reject(new Error(`no manifest at ${manifestPath}; run --apply first`))
+    throw new Error(`no manifest at ${manifestPath}; run --apply first`)
   }
-  const finalized = finalizeManifest(manifest, manifestPath)
+  const importOptions: ImportCommandOptions = {
+    configPath: options.configPath,
+    databaseUrl: '',
+    apply: true,
+    sessions: 'carry',
+    ...(options.slugsJson === undefined ? {} : { slugsJson: options.slugsJson }),
+    ...(options.loadPayload === undefined ? {} : { loadPayload: options.loadPayload }),
+  }
+  const finalized = await withTargetPayload(
+    importOptions,
+    (payload) =>
+      finalizeManifest({
+        payload,
+        manifest,
+        path: manifestPath,
+        allowUnsignedManifest: options.allowUnsignedManifest,
+      }),
+    manifest.kind !== 'adopt-prelink'
+  )
   log(
-    `finalized: the manifest at ${manifestPath} is now read-only. Legacy tables may be dropped in a separate, later migration — nothing is dropped for you.`
+    manifest.kind === 'adopt-prelink'
+      ? `finalized: the pre-link manifest at ${manifestPath} is now read-only, and the database records the finalize. Rollback is no longer possible. Adopt mode serves Better Auth from your existing tables — they are the LIVE tables; do not drop them.`
+      : `finalized: the manifest at ${manifestPath} is now read-only, and the database records the finalize. Rollback is no longer possible. The legacy payload-auth tables may be dropped in a separate, later migration — nothing is dropped for you.`
   )
-  return Promise.resolve(finalized)
+  return finalized
 }
 
 /** Options for `adopt-prelink` (issue #88). */

package/src/importer/types.ts

@@ -9,8 +9,8 @@
  * target app's Payload `secret`), so only the same app can restore it.
  * The file is written with mode 0600.
  *
- * Integrity: a version-3 manifest is signed (`mac`), and rollback or a
- * resumed run refuses one that does not verify.
+ * Integrity: a version-3 manifest is signed (`mac`), and rollback,
+ * finalize, or a resumed run refuses one that does not verify.
  */
 export type CreatedRow = {
   /** Target collection slug. */
@@ -60,9 +60,12 @@ export type ImportManifest = {
   readonly totals: Readonly<Record<string, number>>
   /** When the last rollback reset this manifest (issue #88). */
   readonly rolledBackAt?: string | undefined
+  /** When `finalize` ran (recorded alongside the database marker). */
+  readonly finalizedAt?: string | undefined
   /**
-   * Version 3: HMAC over the whole manifest (except `finalized`), keyed
-   * from the target app's Payload secret. See `manifest-mac.ts`.
+   * Version 3: HMAC over the whole manifest, keyed from the target
+   * app's Payload secret. `v2.` MACs cover every field; 0.6.0's `v1.`
+   * MACs left `finalized` out. See `manifest-mac.ts`.
    */
   readonly mac?: string | undefined
 }

package/src/index.ts

@@ -22,6 +22,7 @@ export {
   runRollback,
   runFinalize,
   runAdoptPrelink,
+  type FinalizeCommandOptions,
   type ImportCommandOptions,
   type PrelinkCommandOptions,
 } from './importer/run-import.js'
@@ -50,6 +51,8 @@ export {
   finalizeManifest,
   defaultManifestPath,
   defaultPrelinkManifestPath,
+  type FinalizeOptions,
+  type RollbackOptions,
   type VerifyIssue,
   type VerifyResult,
 } from './importer/lifecycle.js'
@@ -74,7 +77,13 @@ export {
   type PlanRow,
   type Unmappable,
 } from './importer/types.js'
-export { exportToJsonl, parseExportTables, exportTables } from './exporters.js'
+export {
+  exportToJsonl,
+  parseExportTables,
+  exportTables,
+  optionalAuthTables,
+  resolveAuthTables,
+} from './exporters.js'
 export { cliMain } from './cli.js'
 export type {
   BehaviourChange,