@payload-auth-link/migrate 0.4.3 → 0.5.0

package/src/importer/host-writes.ts

@@ -0,0 +1,231 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto'
+import type { Payload } from 'payload'
+import type { FieldWrite, ImportManifest } from './types.js'
+
+/**
+ * Host-document field writes with exact rollback (issues #50, #88).
+ *
+ * Capture: before the importer (or `adopt-prelink`) writes a host
+ * field, its CURRENT value is captured into the manifest — once per
+ * document field, the FIRST capture wins, so a second `--apply` can
+ * never overwrite the pre-import value with imported state. The
+ * document's `updatedAt` is captured the same way, because the Local
+ * API write bumps it.
+ *
+ * Privacy: captured values (identity rows and `linkableEmail` carry
+ * email addresses) are sealed with AES-256-GCM under a key derived
+ * from the target app's Payload `secret`; the manifest stores no value
+ * in the clear. Rollback needs the same secret — it boots the same
+ * app.
+ *
+ * Restore: rollback writes the captured values back through the
+ * DATABASE ADAPTER (`payload.db.updateOne`), not the Local API
+ * operation: the operation would stamp a fresh `updatedAt` and re-run
+ * hooks, so the "restored" row would differ from the original. The
+ * adapter write sets exactly the captured fields — `updatedAt`
+ * included — on every adapter (Postgres, SQLite, Mongo). What it
+ * cannot preserve is documented in docs/migrating-from-payload-auth.md
+ * (the forward Local API write re-creates hasMany child rows such as
+ * `users_role` with new row ids; their values and order are intact).
+ */
+
+const sealPrefix = 'v1.'
+
+const writeKey = (collection: string, id: string | number, field: string): string =>
+  `${collection}\u0000${String(id)}\u0000${field}`
+
+function keyFor(secret: string): Buffer {
+  return createHash('sha256')
+    .update('payload-auth-link/migrate/manifest-seal/v1\u0000')
+    .update(secret)
+    .digest()
+}
+
+/**
+ * Seal one JSON-serialized value under the app's Payload secret. The
+ * entry it belongs to (`collection\0id\0field`) is bound as GCM
+ * associated data, so a sealed value cannot be moved onto another
+ * entry of the manifest.
+ */
+export function sealValue(secret: string, plaintext: string, entry: string): string {
+  const iv = randomBytes(12)
+  const cipher = createCipheriv('aes-256-gcm', keyFor(secret), iv)
+  cipher.setAAD(Buffer.from(entry, 'utf8'))
+  const body = Buffer.concat([cipher.update(plaintext, 'utf8'), cipher.final()])
+  const tag = cipher.getAuthTag()
+  return `${sealPrefix}${Buffer.concat([iv, tag, body]).toString('base64url')}`
+}
+
+/** Open a sealed value; throws when the secret is not the sealing one. */
+export function unsealValue(secret: string, sealed: string, entry: string): string {
+  if (!sealed.startsWith(sealPrefix)) {
+    throw new Error('manifest value is not a sealed v1 value')
+  }
+  const raw = Buffer.from(sealed.slice(sealPrefix.length), 'base64url')
+  const iv = raw.subarray(0, 12)
+  const tag = raw.subarray(12, 28)
+  const body = raw.subarray(28)
+  const decipher = createDecipheriv('aes-256-gcm', keyFor(secret), iv)
+  decipher.setAuthTag(tag)
+  decipher.setAAD(Buffer.from(entry, 'utf8'))
+  try {
+    return Buffer.concat([decipher.update(body), decipher.final()]).toString('utf8')
+  } catch {
+    throw new Error(
+      'cannot open the manifest: a value was sealed with a different PAYLOAD_SECRET or for a different entry (edited manifest) — run rollback against the same app (same secret) that ran the import, with the manifest it wrote'
+    )
+  }
+}
+
+/**
+ * The only host fields the kit ever writes (importer and
+ * `adopt-prelink`), plus the `updatedAt` it captures alongside them.
+ * Rollback restores nothing else: a manifest is a file on disk, and an
+ * edited one must not become a way to set arbitrary fields (roles are
+ * restored only because the importer writes them).
+ */
+export const restorableFields: ReadonlySet<string> = new Set([
+  'identities',
+  'roles',
+  'linkable',
+  'linkableEmail',
+  'updatedAt',
+])
+
+/** The captured prior value of one manifest entry, JSON-parsed. */
+export function priorValue(secret: string, write: FieldWrite): unknown {
+  if (!restorableFields.has(write.field)) {
+    throw new Error(
+      `manifest entry for '${write.collection}.${write.field}' is not a field this kit writes; refusing to restore it (edited manifest?)`
+    )
+  }
+  if (write.sealedBefore !== undefined) {
+    return JSON.parse(
+      unsealValue(secret, write.sealedBefore, writeKey(write.collection, write.id, write.field))
+    ) as unknown
+  }
+  // Version-1 manifests stored the value in the clear.
+  return write.before === null || write.before === undefined
+    ? null
+    : (JSON.parse(write.before) as unknown)
+}
+
+/** Keys of the field writes a manifest already holds (first capture wins). */
+export function capturedKeys(writes: readonly FieldWrite[]): Set<string> {
+  return new Set(writes.map((write) => writeKey(write.collection, write.id, write.field)))
+}
+
+/**
+ * Capture `fields` (plus `updatedAt`) of one document before it is
+ * written. Fields the document does not carry are skipped — they are
+ * neither written nor restored. Returns the fields the document DOES
+ * carry, so the caller writes only those.
+ */
+export async function captureBefore(options: {
+  readonly payload: Payload
+  readonly collection: string
+  readonly id: string | number
+  readonly fields: readonly string[]
+  readonly captured: Set<string>
+  readonly into: FieldWrite[]
+}): Promise<{ readonly present: ReadonlySet<string>; readonly newlyCaptured: number }> {
+  const { payload, collection, id, fields, captured, into } = options
+  const doc: unknown = await payload.findByID({
+    collection,
+    id,
+    depth: 0,
+    overrideAccess: true,
+  })
+  const record =
+    typeof doc === 'object' && doc !== null ? (doc as Record<string, unknown>) : undefined
+  const present = new Set<string>()
+  let newlyCaptured = 0
+  for (const field of [...fields, 'updatedAt']) {
+    if (record === undefined || !(field in record)) {
+      continue
+    }
+    present.add(field)
+    const key = writeKey(collection, id, field)
+    if (captured.has(key)) {
+      // The FIRST capture is the pre-import value; a later pass would
+      // only capture this tool's own earlier write (issue #88).
+      continue
+    }
+    captured.add(key)
+    into.push({
+      collection,
+      id,
+      field,
+      sealedBefore: sealValue(payload.secret, JSON.stringify(record[field] ?? null), key),
+    })
+    newlyCaptured += 1
+  }
+  return { present, newlyCaptured }
+}
+
+/**
+ * Restore every captured field, one adapter write per document so
+ * `updatedAt` lands exactly as captured. Returns the number of field
+ * values restored.
+ */
+export async function restoreCaptured(
+  payload: Payload,
+  manifest: Pick<ImportManifest, 'fieldWrites'>
+): Promise<number> {
+  const byDoc = new Map<
+    string,
+    { collection: string; id: string | number; data: Record<string, unknown> }
+  >()
+  for (const write of manifest.fieldWrites) {
+    const key = `${write.collection}\u0000${String(write.id)}`
+    const entry = byDoc.get(key) ?? { collection: write.collection, id: write.id, data: {} }
+    entry.data[write.field] = priorValue(payload.secret, write)
+    byDoc.set(key, entry)
+  }
+  let restored = 0
+  for (const entry of byDoc.values()) {
+    const fields = payload.collections[entry.collection]?.config.flattenedFields ?? []
+    const isChildRowField = (name: string): boolean => {
+      const field = fields.find((candidate) => candidate.name === name)
+      return (
+        field !== undefined &&
+        (field.type === 'array' ||
+          field.type === 'blocks' ||
+          ('hasMany' in field && field.hasMany === true))
+      )
+    }
+    const childRows: Record<string, unknown> = {}
+    const columns: Record<string, unknown> = {}
+    for (const [field, value] of Object.entries(entry.data)) {
+      if (isChildRowField(field)) {
+        childRows[field] = value
+      } else {
+        columns[field] = value
+      }
+    }
+    // Child-row fields (arrays, hasMany) go through the Local API: the
+    // SQL adapters rewrite child tables only through a full-document
+    // upsert, which the operation provides.
+    if (Object.keys(childRows).length > 0) {
+      await payload.update({
+        collection: entry.collection,
+        id: entry.id,
+        data: childRows,
+        overrideAccess: true,
+      })
+    }
+    // Column fields — `updatedAt` LAST-WRITTEN, exactly as captured —
+    // go straight through the adapter: a plain UPDATE of just these
+    // columns, no fresh timestamp, no hooks.
+    if (Object.keys(columns).length > 0) {
+      await payload.db.updateOne({
+        collection: entry.collection,
+        id: entry.id,
+        data: columns,
+        returning: false,
+      })
+    }
+    restored += Object.keys(entry.data).length
+  }
+  return restored
+}

package/src/importer/lifecycle.ts

@@ -1,5 +1,7 @@
-import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, readFileSync } from 'node:fs'
+import { writePrivateFile } from '../private-file.js'
 import type { Payload } from 'payload'
+import { restoreCaptured } from './host-writes.js'
 import {
   defaultTargetSlugs,
   resolveSourceTables,
@@ -15,25 +17,40 @@ import {
  * separate later step.
  */
 
+/**
+ * The importer's default manifest location: the CURRENT WORKING
+ * DIRECTORY. Pass `--manifest` to put it somewhere access-controlled;
+ * it holds ids and sealed values only (no emails in the clear) and is
+ * written with mode 0600. Keep it until `finalize` + your soak period
+ * ends, then delete it (docs/migrating-from-payload-auth.md).
+ */
 export const defaultManifestPath = 'payload-auth-link-migration.json'
 
+/** The `adopt-prelink` default manifest location (cwd; same rules). */
+export const defaultPrelinkManifestPath = 'payload-auth-link-prelink.json'
+
 export function readManifest(path: string): ImportManifest | null {
   if (!existsSync(path)) {
     return null
   }
   const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
-  if (
-    typeof parsed !== 'object' ||
-    parsed === null ||
-    (parsed as { version?: unknown }).version !== 1
-  ) {
-    throw new Error(`manifest at ${path} is not a version-1 import manifest`)
+  const version =
+    typeof parsed === 'object' && parsed !== null
+      ? (parsed as { version?: unknown }).version
+      : undefined
+  if (version !== 1 && version !== 2) {
+    throw new Error(`manifest at ${path} is not a version-1/2 import manifest`)
   }
   return parsed as ImportManifest
 }
 
+/**
+ * Write the manifest owner-read/write only (0600, issue #88) — on
+ * create AND on every rewrite, so a manifest created by an older kit
+ * is tightened too.
+ */
 export function writeManifest(manifest: ImportManifest, path: string): void {
-  writeFileSync(path, `${JSON.stringify(manifest, null, 2)}\n`)
+  writePrivateFile(path, `${JSON.stringify(manifest, null, 2)}\n`)
 }
 
 export type VerifyIssue = {
@@ -67,6 +84,8 @@ export async function verifyImport(options: {
   readonly sourceTables?: Readonly<Record<string, string | null>> | undefined
   /** Whether the import carried sessions; `drop` skips the session count. */
   readonly sessions?: 'carry' | 'drop' | undefined
+  /** Injectable clock: what counts as an expired source session. */
+  readonly now?: (() => Date) | undefined
 }): Promise<VerifyResult> {
   const { payload, sourceConnectionString } = options
   const slugs: Record<string, string> = {
@@ -118,11 +137,6 @@ export async function verifyImport(options: {
     }[] = [
       { label: 'users', table: sourceTables['users'], collection: String(slugs['user']) },
       { label: 'accounts', table: sourceTables['accounts'], collection: String(slugs['account']) },
-      {
-        label: 'sessions',
-        table: sessions === 'carry' ? sourceTables['sessions'] : null,
-        collection: String(slugs['session']),
-      },
       {
         label: 'verifications',
         table: sourceTables['verifications'],
@@ -163,6 +177,58 @@ export async function verifyImport(options: {
         name: 'count sessions (skipped: the import dropped them)',
         passed: true,
       })
+    } else if (sourceTables['sessions'] === null) {
+      checks.push({
+        name: 'count sessions (skipped: null-mapped — not installed on the source)',
+        passed: true,
+      })
+    } else {
+      // Sessions are LIVE data after go-live (issue #88): sign-ins add
+      // ba-sessions rows, and Better Auth deletes expired rows when a
+      // lookup meets them. So the check is scoped to the IMPORTED rows
+      // (deterministic `sess-<source id>` baIds): every unexpired source
+      // session must be present; sessions created after cutover and
+      // expired sessions already cleaned up are reported, never failed.
+      const nowMs = (options.now ?? (() => new Date()))().getTime()
+      const sourceSessions = await client.query(
+        `SELECT id, expires_at FROM ${sourceTables['sessions']}`
+      )
+      const target = await payload.find({
+        collection: String(slugs['session']),
+        depth: 0,
+        pagination: false,
+        overrideAccess: true,
+        select: { baId: true },
+      })
+      const targetBaIds = new Set(
+        target.docs.map((doc) => String((doc as Record<string, unknown>)['baId']))
+      )
+      let missingLive = 0
+      let cleanedExpired = 0
+      const imported = new Set<string>()
+      for (const row of sourceSessions.rows as { id: unknown; expires_at: unknown }[]) {
+        const baId = `sess-${String(row.id)}`
+        imported.add(baId)
+        if (targetBaIds.has(baId)) {
+          continue
+        }
+        const expires = row.expires_at instanceof Date ? row.expires_at.getTime() : Number.NaN
+        if (Number.isFinite(expires) && expires <= nowMs) {
+          cleanedExpired += 1
+        } else {
+          missingLive += 1
+        }
+      }
+      const created = [...targetBaIds].filter((baId) => !imported.has(baId)).length
+      check(
+        'imported sessions present (unexpired source sessions)',
+        missingLive === 0,
+        `${missingLive} unexpired source session(s) missing from ${String(slugs['session'])}`
+      )
+      checks.push({
+        name: `sessions after cutover (info): ${created} created since the import, ${cleanedExpired} expired imported session(s) already cleaned up`,
+        passed: true,
+      })
     }
 
     // 2. every source user has exactly one target row and its host doc.
@@ -307,6 +373,33 @@ export async function verifyImport(options: {
       'no credential account carries a password hash'
     )
 
+    // 3b. bans carried (issue #88): a banned source user stays banned.
+    // The importer refuses to run when banned users exist and the
+    // target declares no `banned` field, so here the field is present
+    // whenever it matters.
+    const bannedSource = users.filter((user) => user.banned === true)
+    if (bannedSource.length > 0) {
+      let notBanned = 0
+      for (const user of bannedSource) {
+        const found = await payload.find({
+          collection: String(slugs['user']),
+          where: { baId: { equals: user.id } },
+          limit: 1,
+          depth: 0,
+          overrideAccess: true,
+        })
+        const doc = found.docs[0] as Record<string, unknown> | undefined
+        if (doc?.['banned'] !== true) {
+          notBanned += 1
+        }
+      }
+      check(
+        'banned source users stay banned',
+        notBanned === 0,
+        `${notBanned} banned source user(s) are not banned on ${String(slugs['user'])}`
+      )
+    }
+
     // 4. API keys: hash present, owner resolves, rate-limit state kept.
     const keys = await payload.find({
       collection: String(slugs['apikey']),
@@ -402,6 +495,14 @@ export async function rollbackImport(options: {
   readonly payload: Payload
   readonly manifest: ImportManifest
   readonly log?: (message: string) => void
+  /**
+   * When given, the manifest at this path is RESET after a successful
+   * rollback (issue #88): no created rows, no field writes, no totals —
+   * so a later `--apply` starts from the restored state instead of
+   * building on stale entries.
+   */
+  readonly manifestPath?: string | undefined
+  readonly now?: (() => Date) | undefined
 }): Promise<{ deleted: number; restored: number }> {
   const { payload, manifest, log = () => {} } = options
   if (manifest.finalized) {
@@ -420,18 +521,19 @@ export async function rollbackImport(options: {
       log(`rollback: ${row.collection}#${row.id} already absent`)
     }
   }
-  let restored = 0
-  for (const write of manifest.fieldWrites) {
-    const data: Record<string, unknown> = {
-      [write.field]: write.before === null ? null : (JSON.parse(write.before) as unknown),
+  // 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)
+  if (options.manifestPath !== undefined) {
+    const reset: ImportManifest = {
+      ...manifest,
+      version: 2,
+      created: [],
+      fieldWrites: [],
+      totals: {},
+      rolledBackAt: (options.now ?? (() => new Date()))().toISOString(),
     }
-    await payload.update({
-      collection: write.collection,
-      id: write.id,
-      data,
-      overrideAccess: true,
-    })
-    restored += 1
+    writeManifest(reset, options.manifestPath)
   }
   log(`rollback: ${deleted} row(s) deleted, ${restored} field value(s) restored`)
   return { deleted, restored }

package/src/importer/prelink.ts

@@ -0,0 +1,228 @@
+import type { Payload } from 'payload'
+import { capturedKeys, captureBefore } from './host-writes.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
+}
+
+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'
+  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 = {
+      version: 2,
+      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,
+  }
+}