@payload-auth-link/migrate 0.4.3 → 0.6.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,8 @@
-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 { authenticateManifest, signManifest } from './manifest-mac.js'
 import {
   defaultTargetSlugs,
   resolveSourceTables,
@@ -15,25 +18,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 && version !== 3) {
+    throw new Error(`manifest at ${path} is not a version-1/2/3 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 +85,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 +138,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 +178,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 +374,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 +496,16 @@ 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
+  /** Accept a pre-0.6.0 manifest that has no MAC (`--allow-unsigned-manifest`). */
+  readonly allowUnsignedManifest?: boolean | undefined
 }): Promise<{ deleted: number; restored: number }> {
   const { payload, manifest, log = () => {} } = options
   if (manifest.finalized) {
@@ -409,6 +513,9 @@ export async function rollbackImport(options: {
     // the migration's history, not a TODO to undo.
     throw new Error('the migration is finalized; rollback is no longer possible')
   }
+  // 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
   for (const row of [...manifest.created].reverse()) {
     try {
@@ -420,18 +527,18 @@ 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),
-    }
-    await payload.update({
-      collection: write.collection,
-      id: write.id,
-      data,
-      overrideAccess: true,
+  // 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 = signManifest(payload.secret, {
+      ...manifest,
+      created: [],
+      fieldWrites: [],
+      totals: {},
+      rolledBackAt: (options.now ?? (() => new Date()))().toISOString(),
     })
-    restored += 1
+    writeManifest(reset, options.manifestPath)
   }
   log(`rollback: ${deleted} row(s) deleted, ${restored} field value(s) restored`)
   return { deleted, restored }

package/src/importer/manifest-mac.ts

@@ -0,0 +1,90 @@
+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.
+ *
+ * `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.
+ */
+
+const macPrefix = 'v1.'
+
+function macKey(secret: string): Buffer {
+  return createHash('sha256')
+    .update('payload-auth-link/migrate/manifest-mac/v1\u0000')
+    .update(secret)
+    .digest()
+}
+
+/** JSON with object keys sorted at every level (stable across rewrites). */
+function canonical(value: unknown): string {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => (item === undefined ? 'null' : canonical(item))).join(',')}]`
+  }
+  if (typeof value === 'object' && value !== null) {
+    const entries = Object.entries(value as Record<string, unknown>)
+      .filter(([, item]) => item !== undefined)
+      .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+    return `{${entries.map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`).join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+function macOf(secret: string, manifest: ImportManifest): 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')}`
+}
+
+/** Stamp `manifest` as version 3 and sign it 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) }
+}
+
+/**
+ * Refuse a manifest this app did not write. A version-3 manifest must
+ * carry a MAC that verifies under `secret`. A version-1/2 manifest
+ * (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.
+ */
+export function authenticateManifest(
+  secret: string,
+  manifest: ImportManifest,
+  options: { readonly allowUnsigned?: boolean | undefined } = {}
+): void {
+  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'
+      )
+    }
+    return
+  }
+  if (options.allowUnsigned !== true) {
+    throw new Error(
+      `the manifest is version ${String(manifest.version)} (written before 0.6.0) and carries no integrity check. If you are sure nobody has edited it, re-run with --allow-unsigned-manifest; the next write signs it`
+    )
+  }
+  if (manifest.version === 2 && manifest.fieldWrites.some((write) => write.before !== undefined)) {
+    throw new Error(
+      'the version-2 manifest holds a plaintext prior value, which version 2 never writes (edited manifest?); refusing to use it'
+    )
+  }
+}