The Real Story of Account Linking — How I Learned Auth Is a Flow, Not a Login

1️⃣  User clicks "Login with Google"
    └─ AuthFlow created with a unique flowId

2️⃣  Provider authenticates
    └─ Google verifies user → returns identity (sub, email, verified?)

3️⃣  resolveAccount() runs
    └─ The brain. Decides: return user? Create? Or pause?

4a ❌ LINK_REQUIRED — Flow pauses
    └─ Email exists with verified password
    └─ Flow saves state, throws error with flowId
    └─ Frontend shows: "Log in with your password first"

4b ✅ OK — Flow completes
    └─ User resolved. AuthFlow deleted. Session created.

5️⃣  linkAccount() — If paused at 4a
    └─ User proves password ownership
    └─ OAuth identity linked. Flow deleted. Session created.

const authenticate = async (providerName, payload, opts) => {
  // Step 1: Get the provider (Google, GitHub, password, etc.)
  const provider = getProvider(providerName);

  // Step 2: Provider gives us an identity
  const identity = await provider.authenticate(payload);

  // Step 3: Resolve — find or create user
  const { type, user } = await opts.Account.resolveAccount(identity);

  // Step 4a: If linking is needed, pause the flow
  if (type === "LINK_REQUIRED") {
    await updateAuthFlow(opts.flowId, {
      status:  "LINK_REQUIRED",
      intent:  "ACCOUNT_LINK",
      identity
    });
    throw Error("Email already linked. Authenticate with password first.");
  }

  // Step 4b: Flow complete — clean up and create session
  await deleteAuthFlow(opts.flowId);
  return await opts.Session.createSession(user, opts);
};

Is the provider "password"?
├── Yes → Find user by ID. Return OK ✅
└── No ↓

Does provider + provider_user_id exist in accounts table?
├── Yes → Return that user. OK ✅
└── No ↓

Did the provider give us a VERIFIED email?
├── No  → Create new user with just provider_user_id. OK ✅
└── Yes ↓

Does that email already exist in users table?
├── No  → Create new user + account row. OK ✅
└── Yes ↓

⚡ Does this existing user have a password credential?
├── Yes + email IS verified     → LINK_REQUIRED ❌ (pause flow)
├── Yes + email is NOT verified → DELETE that credential. Ghost account.
│                                  Link and continue. OK ✅
└── No password at all          → Safe to link directly. OK ✅

const resolveAccount = async (identity: AuthResult) => {

  // ── Password provider is simple: just find the user ──
  if (identity.provider === "password") {
    const user = await opts.User.findById(identity.user_id);
    return { type: "OK", user };
  }

  // ── Already seen this provider before? Return that user ──
  const existing = await opts.Account
    .getByProviderAndId(identity.provider, identity.provider_user_id);

  if (existing) {
    const user = await opts.User.findById(existing.user_id);
    return { type: "OK", user };
  }

  // ── New provider identity. Check if email is verified ──
  const email    = identity.provider_email;
  const verified = identity.metadata?.provider_email_verified;

  if (email && verified) {
    const existingUser = await opts.User.findByEmail(email);

    if (existingUser) {
      const hasCred = await opts.Cred.getCred(existingUser.id);

      if (hasCred) {
        // ⚡ The critical split
        if (existingUser.email_verified)
          return { type: "LINK_REQUIRED" }; // Must prove password ownership

        // Unverified + has password = ghost account. Delete it.
        await opts.Cred.delCred(hasCred.id);
        await opts.User.setEmailVerified(existingUser.id);
      }

      // Safe to link — no password conflict
      await opts.Account.insertAccount({ ...identity, user_id: existingUser.id });
      return { type: "OK", user: existingUser };
    }
  }

  // ── Nothing matched. Create a brand new user ──
  const newUser = await opts.User.create({
    email: email,
    email_verified: !!verified,
    full_name: identity.metadata.name
  });
  await opts.Account.insertAccount({ ...identity, user_id: newUser.id });
  return { type: "OK", user: newUser };
};

const linkAccount = async (flowId, password, opts) => {
  // Retrieve the paused flow
  const flow = await getAuthFlow(flowId);
  if (!flow || flow.status !== "LINK_REQUIRED")
    throw Error("Flow not found or not in LINK_REQUIRED state");

  // Prove password ownership
  const passwordProvider = getProvider("password");
  const primaryIdentity = await passwordProvider.authenticate({
    email: flow.identity.provider_email,
    password
  });

  // Link the OAuth identity to the password user
  const user = await opts.Account.linkAccount(
    primaryIdentity,   // The password user (proven owner)
    flow.identity      // The OAuth identity waiting to link
  );

  // Clean up and create session
  await deleteAuthFlow(flowId);
  return await opts.Session.createSession(user, opts);
};