Functional Weave
Code in TypeScript

auth.account-link@1.0.0

README.md

4,176 bytes · view raw

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