@payload-auth-link/migrate 0.3.1 → 0.4.0

package/src/importer/apply.ts

@@ -1,8 +1,16 @@
 import type { Payload } from 'payload'
-import { readFlatRows, openSource, readSourceUsers, type SourceUser } from './source.js'
+import {
+  readFlatRows,
+  openSource,
+  readSourceUsers,
+  type SourceRow,
+  type SourceUser,
+} from './source.js'
 import {
   defaultTargetSlugs,
+  resolveSourceTables,
   type CreatedRow,
+  type ResolvedSourceTables,
   type TargetSlugMap,
   type FieldWrite,
   type ImportManifest,
@@ -41,6 +49,11 @@ export type ApplyOptions = {
   readonly sourceDatabase: string
   /** Target collection slugs; defaults must match the engine wiring. */
   readonly slugs?: Readonly<Record<string, string>> | undefined
+  /**
+   * Source-side model → table map (issue #68). Defaults to
+   * payload-auth's layout; a `null` model is treated as not installed.
+   */
+  readonly sourceTables?: Readonly<Record<string, string | null>> | undefined
   /** Injectable clock for deterministic `linkedAt` stamps. */
   readonly now?: () => Date
   readonly log?: (message: string) => void
@@ -63,6 +76,20 @@ function numberOrNull(value: unknown): number | undefined {
   return Number.isFinite(numeric) ? numeric : undefined
 }
 
+/**
+ * Rows for one mapped model. A `null` mapping records the model as
+ * not installed (issue #68) — no read, no rows; anything else goes
+ * through the strict `readFlatRows` (a missing mapped table throws;
+ * the probe aborts the run first).
+ */
+async function readMapped(
+  client: Awaited<ReturnType<typeof openSource>>,
+  table: string | null,
+  columns: readonly string[]
+): Promise<SourceRow[]> {
+  return table === null ? [] : readFlatRows(client, table, columns)
+}
+
 /** Find an existing target row by `baId` — the resumable dedupe key. */
 async function findByBaId(payload: Payload, collection: string, baId: string): Promise<boolean> {
   const found = await payload.find({
@@ -120,26 +147,36 @@ async function captureBefore(
   return JSON.stringify((doc as Record<string, unknown>)[field] ?? null)
 }
 
-/** Identity rows pre-populated on the host user (verified emails only). */
+/**
+ * The identity rows pre-populated on the host user (issue #69): ONE
+ * `better-auth` identity per imported user, `providerUserId` set to
+ * the ba-users row this import created for them. The engine-created
+ * models key their rows by `baId` and serve Better Auth's own
+ * `user.id` from that column, so the value here — the deterministic
+ * `baId` derived from the source user id — is exactly what
+ * `findByProviderIdentity` queries back
+ * (`{ providerId: 'better-auth', providerUserId: <BA user id> }`).
+ *
+ * Every imported user gets the identity — verified or not,
+ * credential-only included: the import itself proves the
+ * BA-user↔document binding, so identity resolution never depends on
+ * the (verified-only) `linkable` proof, which keeps its current
+ * granting below. An unverified user who verifies their email later
+ * resolves to their ORIGINAL document on the next sign-in instead of
+ * being provisioned a fresh one.
+ */
 function identityRows(
   user: SourceUser,
   now: () => Date
 ): { providerId: string; providerUserId: string; email: string; linkedAt: string }[] {
-  const rows: { providerId: string; providerUserId: string; email: string; linkedAt: string }[] = []
-  for (const account of user.accounts) {
-    if (account.providerId === 'credential') {
-      // A password credential is not an identity: the engine signs the
-      // user in through ba-accounts; no link is claimed.
-      continue
-    }
-    rows.push({
-      providerId: account.providerId,
-      providerUserId: account.accountId,
+  return [
+    {
+      providerId: 'better-auth',
+      providerUserId: String(user.id),
       email: user.email,
       linkedAt: now().toISOString(),
-    })
-  }
-  return rows
+    },
+  ]
 }
 
 export async function applyImport(options: ApplyOptions): Promise<ImportResult> {
@@ -152,6 +189,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     now = () => new Date(),
   } = options
   const slugs = slugsOf(options.slugs)
+  const sourceTables: ResolvedSourceTables = resolveSourceTables(options.sourceTables)
   const created: CreatedRow[] = [...(options.manifest?.created ?? [])]
   const fieldWrites: FieldWrite[] = [...(options.manifest?.fieldWrites ?? [])]
   const totals: Record<string, number> = { ...(options.manifest?.totals ?? {}) }
@@ -167,7 +205,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
 
   const client = await openSource(sourceConnectionString)
   try {
-    const users = await readSourceUsers(client)
+    const users = await readSourceUsers(client, sourceTables)
     const seenUsers = new Set<string>()
 
     // --- 1. ba-users + host field writes ---------------------------------
@@ -240,7 +278,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'user',
-        sourceTable: 'users',
+        sourceTable: sourceTables['users'] ?? 'users',
         targetCollection: slugs.user,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,
@@ -249,6 +287,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     }
 
     // --- 2. accounts (hashes verbatim) ------------------------------------
+    const accountsTable = sourceTables['accounts']
     for (const user of users) {
       for (const account of user.accounts) {
         totals.account = (totals.account ?? 0) + 1
@@ -287,7 +326,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
         }
         record({
           model: 'account',
-          sourceTable: 'accounts',
+          sourceTable: accountsTable ?? 'accounts',
           targetCollection: slugs.account,
           rows: 1,
           skipped: isNew ? 0 : apply ? 1 : 0,
@@ -297,8 +336,9 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     }
 
     // --- 3. sessions (carry keeps every token) -----------------------------
+    const sessionsTable = sourceTables['sessions']
     if (sessions === 'carry') {
-      const rows = await readFlatRows(client, 'sessions', [
+      const rows = await readMapped(client, sessionsTable, [
         'id',
         'user_id',
         'token',
@@ -349,7 +389,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
         }
         record({
           model: 'session',
-          sourceTable: 'sessions',
+          sourceTable: sessionsTable ?? 'sessions',
           targetCollection: slugs.session,
           rows: 1,
           skipped: isNew ? 0 : apply ? 1 : 0,
@@ -359,7 +399,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     }
 
     // --- 4. verifications ---------------------------------------------------
-    const verifications = await readFlatRows(client, 'verifications', [
+    const verificationsTable = sourceTables['verifications']
+    const verifications = await readMapped(client, verificationsTable, [
       'id',
       'identifier',
       'value',
@@ -392,7 +433,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'verification',
-        sourceTable: 'verifications',
+        sourceTable: verificationsTable ?? 'verifications',
         targetCollection: slugs.verification,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,
@@ -401,7 +442,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     }
 
     // --- 5. api keys (hash, prefix, metadata, rate-limit state) --------------
-    const apiKeys = await readFlatRows(client, 'api_keys', [
+    const apiKeysTable = sourceTables['api_keys']
+    const apiKeys = await readMapped(client, apiKeysTable, [
       'id',
       'config_id',
       'name',
@@ -495,7 +537,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'apikey',
-        sourceTable: 'api_keys',
+        sourceTable: apiKeysTable ?? 'api_keys',
         targetCollection: slugs.apikey,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,
@@ -504,7 +546,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     }
 
     // --- 6. jwks --------------------------------------------------------------
-    const jwks = await readFlatRows(client, 'jwks', ['id', 'public_key', 'private_key'])
+    const jwksTable = sourceTables['jwks']
+    const jwks = await readMapped(client, jwksTable, ['id', 'public_key', 'private_key'])
     for (const row of jwks) {
       totals.jwks = (totals.jwks ?? 0) + 1
       const baId = `jwks-${String(row.id)}`
@@ -530,7 +573,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'jwks',
-        sourceTable: 'jwks',
+        sourceTable: jwksTable ?? 'jwks',
         targetCollection: slugs.jwks,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,
@@ -539,7 +582,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
     }
 
     // --- 7. organization plugin rows ---------------------------------------
-    const organizations = await readFlatRows(client, 'organizations', [
+    const organizationsTable = sourceTables['organizations']
+    const organizations = await readMapped(client, organizationsTable, [
       'id',
       'name',
       'slug',
@@ -575,7 +619,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'organization',
-        sourceTable: 'organizations',
+        sourceTable: organizationsTable ?? 'organizations',
         targetCollection: slugs.organization,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,
@@ -583,7 +627,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       })
     }
 
-    const members = await readFlatRows(client, 'members', [
+    const membersTable = sourceTables['members']
+    const members = await readMapped(client, membersTable, [
       'id',
       'organization_id',
       'user_id',
@@ -615,7 +660,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'member',
-        sourceTable: 'members',
+        sourceTable: membersTable ?? 'members',
         targetCollection: slugs.member,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,
@@ -623,7 +668,8 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       })
     }
 
-    const invitations = await readFlatRows(client, 'invitations', [
+    const invitationsTable = sourceTables['invitations']
+    const invitations = await readMapped(client, invitationsTable, [
       'id',
       'organization_id',
       'email',
@@ -663,7 +709,7 @@ export async function applyImport(options: ApplyOptions): Promise<ImportResult>
       }
       record({
         model: 'invitation',
-        sourceTable: 'invitations',
+        sourceTable: invitationsTable ?? 'invitations',
         targetCollection: slugs.invitation,
         rows: 1,
         skipped: isNew ? 0 : apply ? 1 : 0,

package/src/importer/lifecycle.ts

@@ -1,6 +1,12 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs'
 import type { Payload } from 'payload'
-import type { ImportManifest } from './types.js'
+import {
+  defaultTargetSlugs,
+  resolveSourceTables,
+  sourceModelNames,
+  type ResolvedSourceTables,
+  type ImportManifest,
+} from './types.js'
 
 /**
  * Manifest lifecycle (issue #50): `verify` checks both sides, `rollback`
@@ -42,30 +48,33 @@ export type VerifyResult = {
 }
 
 /**
- * Verify (issue #50): per-model counts match, every source user has
- * exactly one target row, every credential account resolves to its
- * user, every API key carries its hash with a resolvable owner, and
- * every member/invitation references an existing org and user. Exits
- * non-zero on any mismatch (the caller maps `ok` to the exit code).
+ * Verify (issues #50, #68, #69): fail closed on the source layout
+ * (the probe runs first), per-model counts match EXACTLY (zero never
+ * skips; every mapped model is either counted or explicitly
+ * null-mapped), every source user has exactly one target row, every
+ * imported user resolves through exactly one `better-auth` identity
+ * pointing at their ba-users id, every credential account resolves to
+ * its user, every API key carries its hash with a resolvable owner,
+ * and every member/invitation references an existing org and user.
+ * Exits non-zero on any mismatch (the caller maps `ok` to the exit
+ * code).
  */
 export async function verifyImport(options: {
   readonly payload: Payload
   readonly sourceConnectionString: string
   readonly slugs?: Readonly<Record<string, string>> | undefined
+  /** Model → source table map (issue #68); defaults to the default layout. */
+  readonly sourceTables?: Readonly<Record<string, string | null>> | undefined
+  /** Whether the import carried sessions; `drop` skips the session count. */
+  readonly sessions?: 'carry' | 'drop' | undefined
 }): Promise<VerifyResult> {
   const { payload, sourceConnectionString } = options
   const slugs: Record<string, string> = {
-    ...{
-      user: 'ba-users',
-      account: 'ba-accounts',
-      session: 'ba-sessions',
-      apikey: 'ba-apikey',
-      organization: 'ba-organization',
-      member: 'ba-member',
-      invitation: 'ba-invitation',
-    },
+    ...defaultTargetSlugs,
     ...(options.slugs ?? {}),
   }
+  const sourceTables: ResolvedSourceTables = resolveSourceTables(options.sourceTables)
+  const sessions = options.sessions ?? 'carry'
   const issues: VerifyIssue[] = []
   const checks: { name: string; passed: boolean }[] = []
   const check = (name: string, passed: boolean, detail?: string): void => {
@@ -81,42 +90,80 @@ export async function verifyImport(options: {
   }
 
   // Source side, read directly.
-  const { openSource, readSourceUsers, countTables } = await import('./source.js')
+  const { openSource, probeSourceLayout, readSourceUsers, countTables } =
+    await import('./source.js')
   const client = await openSource(sourceConnectionString)
   try {
-    const sourceCounts = await countTables(client, [
-      'users',
-      'accounts',
-      'sessions',
-      'verifications',
-      'api_keys',
-      'jwks',
-      'organizations',
-      'members',
-      'invitations',
-    ])
-    const users = await readSourceUsers(client)
+    // Fail closed (issue #68): a missing mapped table or column aborts
+    // the check with an actionable report instead of reading zeros.
+    const probe = await probeSourceLayout(client, sourceTables)
+    if (probe.length > 0) {
+      for (const issue of probe) {
+        issues.push({ code: 'source-table-missing', detail: issue.reason })
+      }
+      return { ok: false, issues, checks }
+    }
+    const sourceCounts = await countTables(
+      client,
+      sourceModelNames.map((model) => sourceTables[model]).filter((t): t is string => t !== null)
+    )
+    const users = await readSourceUsers(client, sourceTables)
 
-    // 1. per-model counts match (sessions only when carried).
-    const countPairs: readonly [string, string, number][] = [
-      ['users', String(slugs['user']), sourceCounts['users'] ?? 0],
-      ['accounts', String(slugs['account']), sourceCounts['accounts'] ?? 0],
-      ['api keys', String(slugs['apikey']), sourceCounts['api_keys'] ?? 0],
-      ['organizations', String(slugs['organization']), sourceCounts['organizations'] ?? 0],
-      ['members', String(slugs['member']), sourceCounts['members'] ?? 0],
-      ['invitations', String(slugs['invitation']), sourceCounts['invitations'] ?? 0],
+    // 1. per-model counts match EXACTLY (issue #68) — zero never skips.
+    // A null-mapped model is recorded as skipped-by-config, visibly.
+    const countPairs: readonly {
+      readonly label: string
+      readonly table: string | null
+      readonly collection: string
+    }[] = [
+      { 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'],
+        collection: String(slugs['verification']),
+      },
+      { label: 'api keys', table: sourceTables['api_keys'], collection: String(slugs['apikey']) },
+      { label: 'jwks', table: sourceTables['jwks'], collection: String(slugs['jwks']) },
+      {
+        label: 'organizations',
+        table: sourceTables['organizations'],
+        collection: String(slugs['organization']),
+      },
+      { label: 'members', table: sourceTables['members'], collection: String(slugs['member']) },
+      {
+        label: 'invitations',
+        table: sourceTables['invitations'],
+        collection: String(slugs['invitation']),
+      },
     ]
-    for (const [label, collection, expected] of countPairs) {
-      if (expected === 0) {
+    for (const pair of countPairs) {
+      if (pair.table === null) {
+        checks.push({
+          name: `count ${pair.label} (skipped: null-mapped — not installed on the source)`,
+          passed: true,
+        })
         continue
       }
-      const actual = await targetCounts(collection)
+      const expected = sourceCounts[pair.table] ?? 0
+      const actual = await targetCounts(pair.collection)
       check(
-        `count ${label}`,
-        actual >= expected,
-        `expected >= ${expected} ${label} in ${collection}, found ${actual}`
+        `count ${pair.label}`,
+        actual === expected,
+        `expected exactly ${expected} ${pair.label} in ${pair.collection}, found ${actual}`
       )
     }
+    if (sessions === 'drop') {
+      checks.push({
+        name: 'count sessions (skipped: the import dropped them)',
+        passed: true,
+      })
+    }
 
     // 2. every source user has exactly one target row and its host doc.
     let userMatches = 0
@@ -143,6 +190,77 @@ export async function verifyImport(options: {
     )
     void userMatches
 
+    // 2b. every imported user resolves through EXACTLY ONE better-auth
+    // identity pointing at their ba-users id (issue #69) — that is the
+    // 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.
+    let identityIssues = 0
+    let roleMismatchDocs = 0
+    let hostDocsWithRoles = 0
+    for (const user of users) {
+      const hostId = Number(user.id)
+      if (!Number.isSafeInteger(hostId)) {
+        identityIssues += 1
+        continue
+      }
+      let doc: unknown
+      try {
+        doc = await payload.findByID({
+          collection: 'users',
+          id: hostId,
+          depth: 0,
+          overrideAccess: true,
+        })
+      } catch {
+        identityIssues += 1
+        continue
+      }
+      if (typeof doc !== 'object' || doc === null) {
+        identityIssues += 1
+        continue
+      }
+      const record = doc as Record<string, unknown>
+      const identities = Array.isArray(record['identities'])
+        ? (record['identities'] as readonly unknown[])
+        : []
+      const resolving = identities.filter(
+        (entry) =>
+          typeof entry === 'object' &&
+          entry !== null &&
+          (entry as Record<string, unknown>)['providerId'] === 'better-auth' &&
+          String((entry as Record<string, unknown>)['providerUserId']) === String(user.id)
+      )
+      if (identities.length !== 1 || resolving.length !== 1) {
+        identityIssues += 1
+      }
+      const roles = record['roles']
+      if (Array.isArray(roles)) {
+        hostDocsWithRoles += 1
+        const stored = new Set(roles.map((role) => String(role)))
+        if (!user.roles.every((role) => stored.has(role))) {
+          roleMismatchDocs += 1
+        }
+      }
+    }
+    check(
+      'every imported user resolves through one better-auth identity',
+      identityIssues === 0,
+      `${identityIssues} user(s) without exactly one better-auth identity resolving to their ba-users id`
+    )
+    if (hostDocsWithRoles > 0) {
+      check(
+        'source roles carried onto the host docs',
+        roleMismatchDocs === 0,
+        `${roleMismatchDocs} host doc(s) missing stored role values`
+      )
+    } 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)',
+        passed: true,
+      })
+    }
+
     // 3. every credential account resolves to its user.
     const accounts = await payload.find({
       collection: String(slugs['account']),
@@ -181,9 +299,11 @@ export async function verifyImport(options: {
       orphanAccounts === 0,
       `${orphanAccounts} account(s) with a missing user or empty credential hash`
     )
+    const sourceAccountsCount =
+      sourceTables['accounts'] === null ? 0 : (sourceCounts[sourceTables['accounts']] ?? 0)
     check(
       'credential accounts carry hashes',
-      sourceCounts.accounts === 0 || credentialAccounts > 0,
+      sourceAccountsCount === 0 || credentialAccounts > 0,
       'no credential account carries a password hash'
     )