@payload-auth-link/migrate 0.0.0-stage → 0.2.1

package/src/doctor/source-scan.ts

@@ -0,0 +1,148 @@
+import { readdirSync, readFileSync, statSync } from 'node:fs'
+import { extname, join, relative } from 'node:path'
+import type { SourceFinding } from './types.js'
+
+/**
+ * Read-only source scan (issue #52): the call sites a payload-auth app
+ * must migrate, found by pattern over `--src`. Regex-level on
+ * purpose — the doctor must run before any code changes, on apps the
+ * compiler cannot type-check against payload-auth-link yet.
+ */
+
+const scanExtensions = new Set(['.ts', '.tsx', '.js', '.jsx', '.mts', '.mjs'])
+const skipDirs = new Set([
+  'node_modules',
+  'dist',
+  '.next',
+  '.turbo',
+  'coverage',
+  'test-results',
+  'playwright-report',
+])
+
+const payloadAuthImport =
+  /from\s+['"]payload-auth(?:\/[A-Za-z0-9_./-]+)?['"]|import\s*\(\s*['"]payload-auth(?:\/[A-Za-z0-9_./-]+)?['"]/g
+const betterAuthAccessor = /\bpayload\.betterAuth\b|\bbetterAuth\.api\b/g
+const getPayloadAuth = /\bgetPayloadAuth\s*\(/g
+// Holding the Better Auth context at all (`$context`) means reaching
+// past the supported surface — hand-hashed keys, hand-signed cookies —
+// whether or not the call sits adjacent on one line.
+const baInternals = /\$context\b|\binternalAdapter\b/g
+// `req` and `request` are both idiomatic parameter names.
+const reqUserField = /\b(?:req|request)\.user\.([A-Za-z_$][A-Za-z0-9_$]*)/g
+
+/**
+ * The fields the auth-link strategy projects onto `req.user` by
+ * default (`reqUser: 'projection'`). Anything else a payload-auth app
+ * reads off `req.user` is `undefined` under the projection — silent
+ * access-control drift — until `reqUser: 'document'` lands (#57).
+ */
+export const projectedUserFields: ReadonlySet<string> = new Set([
+  'id',
+  'collection',
+  'email',
+  'roles',
+  'mfaRequired',
+  'assurance',
+  'actor',
+  'organizationId',
+])
+
+function walk(dir: string, into: string[]): void {
+  let entries: string[]
+  try {
+    entries = readdirSync(dir)
+  } catch {
+    return
+  }
+  for (const entry of entries) {
+    if (skipDirs.has(entry) || entry.startsWith('.')) {
+      continue
+    }
+    const full = join(dir, entry)
+    let stats
+    try {
+      stats = statSync(full)
+    } catch {
+      continue
+    }
+    if (stats.isDirectory()) {
+      walk(full, into)
+    } else if (scanExtensions.has(extname(entry))) {
+      into.push(full)
+    }
+  }
+}
+
+export function scanSource(srcDir: string): SourceFinding[] {
+  const files: string[] = []
+  walk(srcDir, files)
+  const importFiles = new Set<string>()
+  const accessorFiles = new Set<string>()
+  const getPayloadAuthFiles = new Set<string>()
+  const internalsFiles = new Set<string>()
+  const reqUserFiles = new Set<string>()
+  const reqUserFields = new Set<string>()
+  for (const file of files) {
+    let content: string
+    try {
+      content = readFileSync(file, 'utf8')
+    } catch {
+      continue
+    }
+    const track = (pattern: RegExp, into: Set<string>): void => {
+      pattern.lastIndex = 0
+      if (pattern.test(content)) {
+        into.add(file)
+      }
+    }
+    track(payloadAuthImport, importFiles)
+    track(betterAuthAccessor, accessorFiles)
+    track(getPayloadAuth, getPayloadAuthFiles)
+    track(baInternals, internalsFiles)
+    for (const match of content.matchAll(reqUserField)) {
+      const field = match[1]
+      if (field !== undefined && !projectedUserFields.has(field)) {
+        reqUserFields.add(field)
+        reqUserFiles.add(file)
+      }
+    }
+  }
+  const rel = (file: string): string => relative(srcDir, file)
+  const findings: SourceFinding[] = [
+    {
+      kind: 'payload-auth-import',
+      files: [...importFiles].map(rel).sort(),
+      fields: [],
+      detail: 'imports from payload-auth; each becomes a payload-auth-link import (codemod, #53)',
+    },
+    {
+      kind: 'get-payload-auth',
+      files: [...getPayloadAuthFiles].map(rel).sort(),
+      fields: [],
+      detail: 'getPayloadAuth(config) call sites; become getPayload({ config }) (codemod, #53)',
+    },
+    {
+      kind: 'better-auth-accessor',
+      files: [...accessorFiles].map(rel).sort(),
+      fields: [],
+      detail:
+        'payload.betterAuth accessors; migrate to the supported session API (#54), with the opt-in shim (#53) in between',
+    },
+    {
+      kind: 'ba-internals',
+      files: [...internalsFiles].map(rel).sort(),
+      fields: [],
+      detail:
+        'Better Auth internals ($context.internalAdapter / $context.adapter) — unsupported; the supported server API replaces each bridge (#54)',
+    },
+    {
+      kind: 'req-user-field',
+      files: [...reqUserFiles].map(rel).sort(),
+      fields: [...reqUserFields].sort(),
+      detail:
+        "req.user.<field> reads outside the session projection; under the default projection they read undefined — audit each or opt into reqUser: 'document' (#57)",
+    },
+  ]
+  return findings.filter((finding) => finding.files.length > 0)
+}

package/src/doctor/types.ts

@@ -0,0 +1,92 @@
+/**
+ * The doctor's report shape (issue #52): read-only findings, every
+ * one carrying a stable machine code so tests (and the guide) assert
+ * exact blocker lists instead of prose.
+ */
+
+/** A finding the doctor is confident about: fix it before migrating. */
+export type DoctorIssue = {
+  /** Stable machine code — e.g. `better-auth-out-of-band`. */
+  readonly code: string
+  /** Human detail: what was found, what closes it. */
+  readonly detail: string
+}
+
+/** One upstream dependency against its supported band. */
+export type VersionFinding = {
+  readonly name: string
+  /** `null` when no manifest resolved (exotic bundling). */
+  readonly installed: string | null
+  /** The supported band, human-readable. */
+  readonly band: string
+  readonly status: 'ok' | 'warning' | 'blocker' | 'unknown'
+  readonly detail: string
+}
+
+/** One Better Auth plugin's migration posture. */
+export type PluginFinding = {
+  /** The plugin's `id` (or the satellite package name). */
+  readonly id: string
+  readonly status: 'supported' | 'auto-declarable' | 'unprobed' | 'unsupported' | 'removed-upstream'
+  readonly detail: string
+}
+
+/** The users collection, as the migration will meet it. */
+export type UsersFinding = {
+  /** Collection slug (payload-auth's `users` by default). */
+  readonly slug: string
+  readonly roleField: {
+    readonly name: string
+    readonly type: string
+    readonly hasMany: boolean
+    /** Declared select values, when the field is a select. */
+    readonly values: readonly string[]
+    /** Values that are not canonical lowercase slugs. */
+    readonly nonCanonical: readonly string[]
+  } | null
+  /** Payload's own email+password local strategy is active. */
+  readonly localStrategy: boolean
+  /** Host fields colliding with the plugin's injected field names. */
+  readonly collisions: readonly string[]
+  readonly notes: readonly string[]
+}
+
+/** One source-scan category with the files that matched. */
+export type SourceFinding = {
+  readonly kind:
+    | 'payload-auth-import'
+    | 'better-auth-accessor'
+    | 'get-payload-auth'
+    | 'ba-internals'
+    | 'req-user-field'
+  readonly files: readonly string[]
+  /** For `req-user-field`: every field read off `req.user`. */
+  readonly fields: readonly string[]
+  readonly detail: string
+}
+
+/** Database state, as far as a read-only connection can see. */
+export type DatabaseFinding = {
+  readonly tables: readonly { readonly name: string; readonly rows: number }[]
+  /** Users with `emailVerified = false` — they will not JIT-link. */
+  readonly unverifiedUsers: number | null
+  readonly orphans: readonly { readonly kind: string; readonly count: number }[]
+}
+
+/** Default-behaviour changes in payload-auth-link 0.7.0 that bite. */
+export type BehaviourChange = {
+  readonly title: string
+  readonly detail: string
+}
+
+/** The full read-only doctor report (`--json` prints this object). */
+export type DoctorReport = {
+  readonly versions: readonly VersionFinding[]
+  readonly plugins: readonly PluginFinding[]
+  readonly users: UsersFinding | null
+  readonly source: readonly SourceFinding[]
+  readonly database: DatabaseFinding | null
+  readonly behaviourChanges: readonly BehaviourChange[]
+  readonly blockers: readonly DoctorIssue[]
+  readonly warnings: readonly DoctorIssue[]
+}

package/src/doctor/users.ts

@@ -0,0 +1,207 @@
+import { isRecord } from '@payload-auth-link/core'
+import type { DoctorIssue, UsersFinding } from './types.js'
+
+/**
+ * The users collection analysis (issue #52): collisions with the
+ * plugin's injected fields, the existing role field and its values,
+ * and whether Payload's local strategy is on — the three things that
+ * decide whether a payload-auth app's user table can be adopted as-is.
+ */
+
+/**
+ * The plugin's injected users-collection field names (see
+ * `packages/plugin/src/collections.ts`). The `roles` field is special:
+ * the plugin ADOPTS a compatible host select instead of throwing, so a
+ * host `roles`/`role` field is analyzed as the role field, not
+ * reported as a collision.
+ */
+const injectedFieldNames: ReadonlySet<string> = new Set([
+  'identities',
+  'phone',
+  'suspendedUntil',
+  'suspendReason',
+  'linkable',
+  'linkableEmail',
+])
+
+/** Canonical roles are lowercase slugs (`staff`, `front-plugin`). */
+const canonicalRole = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+
+/** Narrow a config field list; configs are untyped at this boundary. */
+function fieldList(collection: Record<string, unknown>): Record<string, unknown>[] {
+  const fields: unknown = collection.fields
+  if (!Array.isArray(fields)) {
+    return []
+  }
+  return fields.filter(isRecord)
+}
+
+function fieldName(field: Record<string, unknown>): string | null {
+  return typeof field.name === 'string' && field.name !== '' ? field.name : null
+}
+
+function fieldType(field: Record<string, unknown>): string {
+  return typeof field.type === 'string' ? field.type : 'unknown'
+}
+
+function selectValues(field: Record<string, unknown>): string[] {
+  const options: unknown = field.options
+  if (!Array.isArray(options)) {
+    return []
+  }
+  return options
+    .map((option) => (typeof option === 'string' ? option : isRecord(option) ? option.value : null))
+    .filter((value): value is string => typeof value === 'string')
+}
+
+/** Find the payload-auth-shaped users collection (or the app's own users slug). */
+export function findUsersCollection(
+  config: unknown,
+  usersSlug: string
+): Record<string, unknown> | null {
+  if (!isRecord(config) || !Array.isArray(config.collections)) {
+    return null
+  }
+  for (const collection of config.collections) {
+    if (isRecord(collection) && collection.slug === usersSlug) {
+      return collection
+    }
+  }
+  return null
+}
+
+/**
+ * Payload's local email+password strategy for a collection. payload-auth
+ * leaves it on (its own Better Auth strategy rides alongside), which is
+ * exactly the surface 0.7.0 closes for provider-linked documents.
+ */
+/** Names of the custom auth strategies a collection declares. */
+function strategiesOf(collection: Record<string, unknown>): string[] {
+  const auth: unknown = collection.auth
+  if (!isRecord(auth) || !Array.isArray(auth.strategies)) {
+    return []
+  }
+  return auth.strategies
+    .filter(isRecord)
+    .map((strategy) => strategy.name)
+    .filter((name): name is string => typeof name === 'string')
+}
+
+export function localStrategyOn(collection: Record<string, unknown>): boolean {
+  const auth: unknown = collection.auth
+  if (auth === undefined || auth === null) {
+    return false
+  }
+  if (auth === true) {
+    return true
+  }
+  return isRecord(auth) ? auth.disableLocalStrategy !== true : false
+}
+
+export function analyzeUsersCollection(
+  collection: Record<string, unknown> | null,
+  rolesFieldName: string
+): { finding: UsersFinding | null; issues: DoctorIssue[] } {
+  if (collection === null) {
+    return {
+      finding: null,
+      issues: [
+        { code: 'users-collection-missing', detail: 'no users collection found in the config' },
+      ],
+    }
+  }
+  const fields = fieldList(collection)
+  const issues: DoctorIssue[] = []
+  const notes: string[] = []
+
+  const collisions = fields
+    .map(fieldName)
+    .filter((name): name is string => name !== null)
+    .filter((name) => injectedFieldNames.has(name))
+
+  let roleField: UsersFinding['roleField'] = null
+  const roleCandidates = fields.filter((field) => {
+    const name = fieldName(field)
+    return name === rolesFieldName || name === 'role'
+  })
+  for (const field of roleCandidates) {
+    const name = fieldName(field) ?? 'role'
+    if (fieldType(field) === 'select') {
+      const values = selectValues(field)
+      const nonCanonical = values.filter((value) => !canonicalRole.test(value))
+      roleField = {
+        name,
+        type: fieldType(field),
+        hasMany: field.hasMany === true,
+        values,
+        nonCanonical,
+      }
+      if (nonCanonical.length > 0) {
+        issues.push({
+          code: 'non-canonical-role-value',
+          detail: `the '${name}' field stores non-canonical value(s) ${nonCanonical
+            .map((value) => `'${value}'`)
+            .join(
+              ', '
+            )}; the role value map (#56) keeps them stored as-is while roles stay canonical inside the plugin`,
+        })
+      }
+      if (field.hasMany !== true) {
+        issues.push({
+          code: 'roles-field-single-select',
+          detail: `the '${name}' field is a single-select; the plugin can only adopt a multi-select (hasMany) covering every configured role`,
+        })
+      }
+    } else if (name === rolesFieldName) {
+      issues.push({
+        code: 'roles-field-not-select',
+        detail: `the '${rolesFieldName}' field is a '${fieldType(field)}', not a select; rename it and let the plugin inject its governed field`,
+      })
+    }
+  }
+
+  if (collisions.length > 0) {
+    issues.push({
+      code: 'injected-field-collision',
+      detail: `field(s) ${collisions
+        .map((name) => `'${name}'`)
+        .join(
+          ', '
+        )} collide with the plugin's injected fields; rename them before booting payload-auth-link (its config throws on collisions)`,
+    })
+  }
+
+  const local = localStrategyOn(collection)
+  if (local) {
+    notes.push(
+      'Payload local strategy is ON (payload-auth leaves it active): since 0.7.0, provider-linked documents refuse local sign-in and forgot/reset by default — break-glass operator accounts keep theirs; allowLocalCredentialsForLinkedDocs: true reopens it only for a migration window'
+    )
+  } else {
+    const strategies = Array.isArray(collection.auth) ? [] : strategiesOf(collection)
+    notes.push(
+      strategies.length > 0
+        ? `Payload local strategy is OFF; authentication rides custom strategy/ies: ${strategies.join(', ')}`
+        : 'Payload local strategy is OFF for this collection'
+    )
+  }
+  if (isRecord(collection.auth) && collection.auth.useAPIKey === true) {
+    notes.push(
+      'useAPIKey is enabled: API keys are refused for suspended users at request time since 0.7.0 and never carry MFA-gated roles'
+    )
+  }
+
+  return {
+    finding: {
+      slug: typeof collection.slug === 'string' ? collection.slug : 'users',
+      roleField,
+      localStrategy: local,
+      collisions,
+      notes,
+    },
+    issues,
+  }
+}
+
+export function injectedFieldNamesForDocs(): readonly string[] {
+  return [...injectedFieldNames, 'roles', 'email']
+}