@payload-auth-link/migrate 0.5.0 → 0.7.0

package/src/importer/apply.ts

@@ -1,5 +1,8 @@
+import { isRecord } from '@payload-auth-link/core'
 import type { Payload } from 'payload'
+import { assertCreatedRowsScoped, finalizeMarkerState, hostRolesField } from './guards.js'
 import { capturedKeys, captureBefore } from './host-writes.js'
+import { authenticateManifest, signManifest } from './manifest-mac.js'
 import {
   readFlatRows,
   openSource,
@@ -69,6 +72,8 @@ export type ApplyOptions = {
   /** Injectable clock for deterministic `linkedAt` stamps. */
   readonly now?: () => Date
   readonly log?: (message: string) => void
+  /** Resume from a pre-0.6.0 manifest that has no MAC (`--allow-unsigned-manifest`). */
+  readonly allowUnsignedManifest?: boolean | undefined
 }
 
 const slugsOf = (overrides?: Readonly<Record<string, string>>): TargetSlugMap => ({
@@ -251,6 +256,41 @@ function identityRows(
   ]
 }
 
+/** The host user document as stored (depth 0). */
+async function hostDoc(payload: Payload, id: number): Promise<Record<string, unknown> | null> {
+  const doc: unknown = await payload.findByID({
+    collection: 'users',
+    id,
+    depth: 0,
+    overrideAccess: true,
+  })
+  return isRecord(doc) ? doc : null
+}
+
+/** The doc already carries exactly the identity the import writes. */
+function hasExactIdentity(doc: Record<string, unknown> | null, user: SourceUser): boolean {
+  const identities = doc?.['identities']
+  if (!Array.isArray(identities) || identities.length !== 1) {
+    return false
+  }
+  const only: unknown = identities[0]
+  return (
+    isRecord(only) &&
+    only['providerId'] === 'better-auth' &&
+    String(only['providerUserId']) === String(user.id) &&
+    only['email'] === user.email
+  )
+}
+
+/** Same stored values, same order. */
+function sameValues(stored: unknown, wanted: readonly string[]): boolean {
+  return (
+    Array.isArray(stored) &&
+    stored.length === wanted.length &&
+    stored.every((value, index) => String(value) === wanted[index])
+  )
+}
+
 export async function applyImport(options: ApplyOptions): Promise<ImportResult> {
   const {
     payload,
@@ -262,6 +302,28 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
   } = options
   const slugs = slugsOf(options.slugs)
   const sourceTables: ResolvedSourceTables = resolveSourceTables(options.sourceTables)
+  if (options.manifest !== null) {
+    // Resuming merges the old entries and re-signs them: never launder
+    // an edited manifest into a signed one, never sign created rows
+    // outside the import's own targets, and never resume a migration
+    // the database records as finalized.
+    const trust = authenticateManifest(payload.secret, options.manifest, {
+      allowUnsigned: options.allowUnsignedManifest,
+    })
+    assertCreatedRowsScoped(options.manifest, slugs)
+    const finalized =
+      options.manifest.finalized ||
+      (apply &&
+        (await finalizeMarkerState(payload, options.manifest, {
+          anyOfKind: trust !== 'signed',
+        })) === 'finalized')
+    if (apply && finalized) {
+      throw new Error(
+        'the migration is finalized; a finalized manifest is not resumed — keep it as the record, and pass a different --manifest for a new run'
+      )
+    }
+  }
+  const rolesField = hostRolesField(payload)
   const created: CreatedRow[] = [...(options.manifest?.created ?? [])]
   const fieldWrites: FieldWrite[] = [...(options.manifest?.fieldWrites ?? [])]
   // First capture wins (issue #88): fields captured by an earlier pass
@@ -343,35 +405,53 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
         // restores the pre-import document exactly.
         const hostId = Number(baId)
         if (Number.isSafeInteger(hostId)) {
-          const { present, newlyCaptured } = await captureBefore({
-            payload,
-            collection: 'users',
-            id: hostId,
-            fields: ['identities', 'roles', 'linkable', 'linkableEmail'],
-            captured,
-            into: fieldWrites,
-          })
-          fieldWriteCount += newlyCaptured
-          const writes: Record<string, unknown> = {
-            identities: identityRows(user, now),
+          // Only the values that DIFFER are written (issue #110): a
+          // second --apply over an imported user is a true no-op — no
+          // Local API update, so no fresh `updatedAt`, `linkedAt`, or
+          // re-created hasMany child rows.
+          const current = await hostDoc(payload, hostId)
+          const writes: Record<string, unknown> = {}
+          if (!hasExactIdentity(current, user)) {
+            writes.identities = identityRows(user, now)
           }
-          if (user.roles.length > 0 && present.has('roles')) {
+          if (
+            user.roles.length > 0 &&
+            current !== null &&
+            rolesField in current &&
+            !sameValues(current[rolesField], user.roles)
+          ) {
             // Stored role values pass through unchanged (issue #56: the
             // storage edge owns translation; the map is the app's).
-            writes.roles = user.roles
+            writes[rolesField] = user.roles
           }
-          if (user.emailVerified) {
+          if (
+            user.emailVerified &&
+            (current?.['linkable'] !== true || current['linkableEmail'] !== user.email)
+          ) {
             // Grant-only: the proof is bound to the address (both
             // fields), and an existing proof is never revoked here.
             writes.linkable = true
             writes.linkableEmail = user.email
           }
-          await payload.update({
-            collection: 'users',
-            id: hostId,
-            data: writes,
-            overrideAccess: true,
-          })
+          if (Object.keys(writes).length > 0) {
+            // The prior values (and the doc's updatedAt) are captured
+            // first — once — so rollback restores the pre-import doc.
+            const { newlyCaptured } = await captureBefore({
+              payload,
+              collection: 'users',
+              id: hostId,
+              fields: ['identities', rolesField, 'linkable', 'linkableEmail'],
+              captured,
+              into: fieldWrites,
+            })
+            fieldWriteCount += newlyCaptured
+            await payload.update({
+              collection: 'users',
+              id: hostId,
+              data: writes,
+              overrideAccess: true,
+            })
+          }
         }
       }
       record({
@@ -732,8 +812,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     if (apply) {
       // The manifest is the run's contract: merge this pass onto any
       // resumed run's rows and write it back (issue #50).
-      const manifest: ImportManifest = {
-        version: 2,
+      const manifest: ImportManifest = signManifest(payload.secret, {
+        version: 3,
         kind: 'import',
         createdAt: options.manifest?.createdAt ?? now().toISOString(),
         sourceDatabase: options.sourceDatabase,
@@ -743,7 +823,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
         finalized: options.manifest?.finalized ?? false,
         sourceCounts: options.sourceCounts,
         totals,
-      }
+      })
       const { writeManifest } = await import('./lifecycle.js')
       writeManifest(manifest, options.manifestPath)
     }

package/src/importer/guards.ts

@@ -0,0 +1,223 @@
+import { isRecord } from '@payload-auth-link/core'
+import type { Payload } from 'payload'
+import {
+  defaultTargetSlugs,
+  type CreatedRow,
+  type ImportManifest,
+  type TargetModel,
+  type TargetSlugMap,
+} from './types.js'
+
+/**
+ * The guards every destructive manifest operation runs, independent of
+ * the manifest's signature:
+ *
+ * - created-row scoping: a rollback only ever deletes rows the importer
+ *   itself creates — rows in the import's own target collections whose
+ *   deterministic `baId` matches the source key the manifest names;
+ * - the finalize marker: `finalize` records the point of no return in
+ *   the target DATABASE (Payload's key-value store), so a manifest file
+ *   alone can never reopen a finalized migration;
+ * - the host roles field the app configured on `authLink`.
+ */
+
+/** The `baId` prefix the importer stamps per model (see apply.ts). */
+const baIdPrefix: Readonly<Record<TargetModel, string>> = {
+  user: '',
+  account: 'acct-',
+  session: 'sess-',
+  verification: 'ver-',
+  apikey: 'key-',
+  jwks: 'jwks-',
+  organization: 'org-',
+  member: 'member-',
+  invitation: 'inv-',
+}
+
+const isTargetModel = (value: string): value is TargetModel => value in baIdPrefix
+
+/**
+ * The model and deterministic `baId` a created row's `sourceKey`
+ * (`<model>:<source id>`) names, or `null` when it names none.
+ */
+export function expectedBaId(
+  sourceKey: string
+): { readonly model: TargetModel; readonly baId: string } | null {
+  const colon = sourceKey.indexOf(':')
+  if (colon <= 0) {
+    return null
+  }
+  const model = sourceKey.slice(0, colon)
+  const sourceId = sourceKey.slice(colon + 1)
+  if (!isTargetModel(model) || sourceId === '') {
+    return null
+  }
+  return { model, baId: `${baIdPrefix[model]}${sourceId}` }
+}
+
+/** The target slugs with the defaults filled in. */
+export function targetSlugsOf(overrides?: Readonly<Record<string, string>>): TargetSlugMap {
+  return { ...defaultTargetSlugs, ...(overrides ?? {}) }
+}
+
+/**
+ * Refuse a manifest whose created rows reach outside what the importer
+ * creates, BEFORE anything is deleted (or re-signed): an `adopt-prelink`
+ * manifest creates no rows at all, and an import's rows must sit in the
+ * import's own target collections, under the model their source key
+ * names. Signed or not — the signature proves who wrote the file, this
+ * proves the file only names the kit's own rows.
+ */
+export function assertCreatedRowsScoped(
+  manifest: Pick<ImportManifest, 'kind' | 'created'>,
+  slugs: TargetSlugMap
+): void {
+  if (manifest.kind === 'adopt-prelink') {
+    if (manifest.created.length > 0) {
+      throw new Error(
+        `the adopt-prelink manifest lists ${manifest.created.length} created row(s), which adopt-prelink never creates (edited manifest?); refusing to use it — nothing was deleted`
+      )
+    }
+    return
+  }
+  const bySlug = new Map<string, TargetModel>()
+  for (const model of Object.keys(baIdPrefix) as TargetModel[]) {
+    bySlug.set(slugs[model], model)
+  }
+  const outside: string[] = []
+  for (const row of manifest.created) {
+    const expected = expectedBaId(row.sourceKey)
+    const model = bySlug.get(row.collection)
+    if (model === undefined || expected === null || expected.model !== model) {
+      outside.push(`${row.collection}#${String(row.id)} (${row.sourceKey})`)
+    }
+  }
+  if (outside.length > 0) {
+    throw new Error(
+      `the manifest lists ${outside.length} created row(s) outside the import's target collections (${[...bySlug.keys()].join(', ')}): ${outside.slice(0, 10).join(', ')}${outside.length > 10 ? ', …' : ''}. The importer only creates rows there; refusing to use the manifest — nothing was deleted. If your engine wiring renames the targets, pass the same --slugs the import ran with`
+    )
+  }
+}
+
+/** A created row whose `baId` no longer matches its source key. */
+export function baIdMismatch(row: CreatedRow, doc: unknown): boolean {
+  const expected = expectedBaId(row.sourceKey)
+  if (expected === null) {
+    return true
+  }
+  return !isRecord(doc) || String(doc['baId']) !== expected.baId
+}
+
+/** Payload's key-value store, reached structurally (Payload 3.6x+). */
+type KeyValueStore = {
+  readonly get: (key: string) => Promise<unknown>
+  readonly set: (key: string, value: NonNullable<unknown>) => Promise<void>
+  readonly keys: () => Promise<string[]>
+}
+
+function keyValueStore(payload: Payload): KeyValueStore | null {
+  const kv: unknown = (payload as { kv?: unknown }).kv
+  if (
+    isRecord(kv) &&
+    typeof kv['get'] === 'function' &&
+    typeof kv['set'] === 'function' &&
+    typeof kv['keys'] === 'function'
+  ) {
+    return kv as unknown as KeyValueStore
+  }
+  return null
+}
+
+const markerPrefix = 'payload-auth-link/migrate/finalized/'
+
+/** The finalize marker key of one manifest (its kind + first-apply stamp). */
+export function finalizeMarkerKey(manifest: Pick<ImportManifest, 'kind' | 'createdAt'>): string {
+  return `${markerPrefix}${manifest.kind ?? 'import'}/${manifest.createdAt}`
+}
+
+/**
+ * Record the point of no return in the target database. One-way: the
+ * kit never deletes the marker. Throws when the store is unavailable —
+ * `finalize` must not report success it cannot back.
+ */
+export async function recordFinalizeMarker(
+  payload: Payload,
+  manifest: Pick<ImportManifest, 'kind' | 'createdAt'>,
+  finalizedAt: string
+): Promise<void> {
+  const kv = keyValueStore(payload)
+  if (kv === null) {
+    throw new Error(
+      "this Payload version exposes no key-value store (payload.kv); finalize records its marker there — upgrade Payload to a release in the kit's supported band"
+    )
+  }
+  try {
+    await kv.set(finalizeMarkerKey(manifest), {
+      kind: manifest.kind ?? 'import',
+      createdAt: manifest.createdAt,
+      finalizedAt,
+    })
+  } catch (error) {
+    throw new Error(
+      `could not record the finalize marker in Payload's key-value store (the payload-kv collection): ${error instanceof Error ? error.message : String(error)} — create its table (run your Payload migrations) and re-run finalize; the manifest was not changed`,
+      { cause: error }
+    )
+  }
+}
+
+/**
+ * Whether the database says this migration was finalized. `anyOfKind`
+ * widens the check to every finalized manifest of the same kind — used
+ * when the manifest's own `createdAt` is not covered by a signature.
+ * Returns `'unavailable'` when the store cannot be read; the caller
+ * decides (and logs) what that means.
+ */
+export async function finalizeMarkerState(
+  payload: Payload,
+  manifest: Pick<ImportManifest, 'kind' | 'createdAt'>,
+  options: { readonly anyOfKind: boolean }
+): Promise<'finalized' | 'open' | 'unavailable'> {
+  const kv = keyValueStore(payload)
+  if (kv === null) {
+    return 'unavailable'
+  }
+  try {
+    if ((await kv.get(finalizeMarkerKey(manifest))) !== null) {
+      return 'finalized'
+    }
+    if (options.anyOfKind) {
+      const kindPrefix = `${markerPrefix}${manifest.kind ?? 'import'}/`
+      const keys = await kv.keys()
+      if (keys.some((key) => key.startsWith(kindPrefix))) {
+        return 'finalized'
+      }
+    }
+    return 'open'
+  } catch {
+    return 'unavailable'
+  }
+}
+
+/**
+ * The host roles field the app configured (`authLink({ rolesField })`),
+ * read off the plugin entry in the booted config (Payload keeps each
+ * plugin's `slug` and `options` for cross-plugin discovery). Defaults to
+ * the plugin's own default, `roles`.
+ */
+export function hostRolesField(payload: Payload): string {
+  const plugins: unknown = (payload.config as { plugins?: unknown }).plugins
+  if (Array.isArray(plugins)) {
+    for (const plugin of plugins as unknown[]) {
+      if (typeof plugin !== 'function') {
+        continue
+      }
+      const entry = plugin as { slug?: unknown; options?: unknown }
+      if (entry.slug !== 'payload-auth-link') {
+        continue
+      }
+      const rolesField = isRecord(entry.options) ? entry.options['rolesField'] : undefined
+      return typeof rolesField === 'string' && rolesField !== '' ? rolesField : 'roles'
+    }
+  }
+  return 'roles'
+}

package/src/importer/host-writes.ts

@@ -92,9 +92,18 @@ export const restorableFields: ReadonlySet<string> = new Set([
   'updatedAt',
 ])
 
+/** {@link restorableFields} plus the app's configured roles field. */
+export function restorableFieldsFor(rolesField: string): ReadonlySet<string> {
+  return new Set([...restorableFields, rolesField])
+}
+
 /** The captured prior value of one manifest entry, JSON-parsed. */
-export function priorValue(secret: string, write: FieldWrite): unknown {
-  if (!restorableFields.has(write.field)) {
+export function priorValue(
+  secret: string,
+  write: FieldWrite,
+  restorable: ReadonlySet<string> = restorableFields
+): unknown {
+  if (!restorable.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?)`
     )
@@ -170,8 +179,10 @@ export async function captureBefore(options: {
  */
 export async function restoreCaptured(
   payload: Payload,
-  manifest: Pick<ImportManifest, 'fieldWrites'>
+  manifest: Pick<ImportManifest, 'fieldWrites'>,
+  options: { readonly rolesField?: string | undefined } = {}
 ): Promise<number> {
+  const restorable = restorableFieldsFor(options.rolesField ?? 'roles')
   const byDoc = new Map<
     string,
     { collection: string; id: string | number; data: Record<string, unknown> }
@@ -179,7 +190,7 @@ export async function restoreCaptured(
   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)
+    entry.data[write.field] = priorValue(payload.secret, write, restorable)
     byDoc.set(key, entry)
   }
   let restored = 0