# 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".