# auth.account-link Someone has just come back from "Sign in with Google" (auth.oauth-sign-in did the OAuth part). Is this a returning user, someone who already has a password account under the same email, or someone new? `decideAccountLink` answers that from what the app already holds, without touching the database: the app looks up the rows, calls it, and carries out the decision. ```ts const decision = decideAccountLink( { provider: "google", subject: claims.sub, email: claims.email, emailVerified: claims.email_verified === true }, await db.accountsByEmail(claims.email), // candidates; extra rows are fine await db.links({ provider: "google", subject: claims.sub, orAccountsOf: claims.email }), ); switch (decision.action) { case "sign-in": /* start a session for decision.accountId */ break; case "link": /* insert (provider, subject, decision.accountId), then sign in */ break; case "create": /* create an account for decision.email, link it, sign in */ break; case "require-verification": /* send an email.token link to decision.email first */ break; case "refuse": /* explain decision.reason; sign in another way */ break; } ``` ## The rules, in order 1. **An empty provider or subject throws.** They are the identity; nothing else can be decided without them. 2. **An existing link wins** (`sign-in`, `existing_link`). The provider's subject is the stable identity, so a user who changed their email at Google still lands in their account. If the linked account is not among `accounts`, the answer is `refuse` / `linked_account_missing` (with the account id, so the app can clean the link up) rather than creating a second account behind the user's back. 3. **No email, no matching** (`refuse`, `no_email`). Without an address there is nothing safe to match on. A provider that returns none (GitHub with a private email) has to be asked for the `user:email` scope. 4. Emails are compared after `auth.normalise-email` on both sides: trimmed, domain lower-cased, **local part as typed**, exactly as that capability stores them. `Ada@example.com` and `ada@example.com` are two addresses; if your app folds the local part, store and pass it folded. 5. **No account has the email**: a verified provider email creates one (`create`, `new_account`); an unverified one needs the app to prove the address first (`require-verification`, `unverified_new_email`), with its own email token (auth.email-token), so the account is never created for an address its creator does not hold. 6. **Two or more accounts have the email** (`refuse`, `ambiguous_email`). The function will not pick one: merging accounts is a support decision. 7. **One account has the email**, and then: - the provider did not verify the email: `refuse`, `unverified_email`. **Account takeover**: some providers let anyone type any address, so linking on it would hand the account to whoever typed it. - the account already has a link to the same provider with another subject: `refuse`, `provider_already_linked`. A second Google account claiming the same address is a conflict for the user to sort out, never a silent second link. - the account's own email was never verified by the app: `require-verification`, `account_email_unverified`. **Pre-account hijacking**: an attacker registers victim@example.com with a password and waits; when the victim later signs in with Google, linking would leave the attacker's password working on the victim's account. Have the account's address verified (or reset its password) before linking. - otherwise `link`, `verified_email_match`. `accountId` is set for `sign-in`, `link` and every decision about one existing account (so the app can log or explain it), and null for `create`, `no_email`, `ambiguous_email` and a new address awaiting verification. `email` is the identity's normalised email whenever it has one. ## What it does not do It stores nothing and sends nothing. It does not merge accounts, and it does not decide whether your app allows sign-up at all: treat `create` as "create if sign-up is open".