# Sign in with Google or GitHub ## What this builds "Continue with Google" and "Continue with GitHub" for a web app. A person is sent to the provider, comes back, and is signed in to the right account: the one they used before, a new one, or an existing one that provably belongs to them. Read `spekkr.inputs.json` first. `providers` says which buttons exist. `link_by_email` and `allow_sign_up` change R4. Use `app_name` on the pages. The spec starts a session the way the app already does. If the app has no sessions yet, build the smallest kind: a random token in an `HttpOnly`, `Secure`, `SameSite=Lax` cookie, stored as a hash. `spekkr/email-sign-in` has the full rules. ## Out of scope - Sign-in with a password or an emailed link. `spekkr/email-sign-in` builds those. - Company single sign-on through SAML. - Calling the provider's API later on the person's behalf. No provider token is kept once sign-in is done. ## Requirements Each requirement has an id. Tests name the id they cover. ### R1. Send the person to the provider - `GET /auth/PROVIDER/start` redirects to the provider's authorization address. - The request carries a `state` of 32 random bytes, a PKCE challenge made with `S256`, and for Google a `nonce`. The `state`, the PKCE verifier and the nonce are kept for 10 minutes in a cookie only this browser has. - It asks for the least it needs: `openid email profile` from Google, `read:user user:email` from GitHub. - A `next` address is kept only when it is a path on this site. Accept when: the PKCE test vector in `design.md` is reproduced, the redirect holds every parameter in the table there, and a `next` that points at another site is dropped. ### R2. The person comes back - `GET /auth/PROVIDER/callback` compares the `state` in the address with the one in the cookie, in constant time. A missing or different `state` is refused, and the cookie is cleared either way, so a `state` works once. - If the provider says the person declined, the page says so and offers the sign-in page again. - The code is exchanged from the server, with the PKCE verifier and the client secret. No token ever appears in an address or reaches the browser. Accept when: a callback with the wrong `state` starts no session, a second callback with the same `state` is refused, and a declined sign-in shows the page. ### R3. Who the provider says it is - Google: the ID token is checked before anything in it is believed: its signature against Google's published keys, the issuer, that the audience is this app's client id, that it has not expired, and that its `nonce` is the one from R1. Then `sub`, `email` and `email_verified` are read. - GitHub: the user is read for the numeric `id`, and the emails for the address that is both primary and verified. - The provider's own id for the person, `sub` or `id`, is the identity. An email address is never the identity: people change it, and providers reuse it. Accept when: an ID token with a wrong audience, a wrong nonce, an expired time or a bad signature is refused, each in its own test, and a GitHub user whose primary email is not verified is treated as having no email. ### R4. Which account In this order: 1. An identity with this provider and provider id exists: sign in to its account. 2. `link_by_email` is on, the provider says the email is verified, and an account with that email exists whose own email is confirmed: add the identity to that account and sign in. 3. An account with that email exists but rule 2 does not hold: refuse. The page says to sign in the way they did before and connect the provider from their settings. No session starts. 4. No account has that email and `allow_sign_up` is on: create an account, with its email marked confirmed only if the provider says it is verified. 5. Otherwise: refuse, and say that sign-up is closed. Accept when: each of the five rules has a test, and an attacker who controls a provider account with a victim's address unverified gets no session on the victim's account. ### R5. Connect and disconnect from settings - A signed-in person can connect another provider. That flow is tied to their session, so the identity can only land on the account that started it. - An identity that already belongs to another account is not moved. The page says it is in use. - A provider can be disconnected only while the account keeps another way to sign in: another provider, or a password if the app has them. Accept when: connecting adds the identity to the signed-in account, an identity in use elsewhere is refused, and the last way to sign in cannot be removed. ### R6. Start the session - After rules 1, 2 or 4 the app's own session starts and the person lands on `next`, or on the home page. - The provider's tokens are thrown away as soon as R3 is done. Accept when: the database holds no provider access token, refresh token or ID token after sign-in. ### R7. Pages - The buttons, named "Continue with Google" and "Continue with GitHub", for the providers in `providers`. - A page for each refusal in R2 and R4, in plain words, with a way forward. - A "Connected accounts" part of the settings page for R5. Accept when: each page works with a keyboard alone and at a 360 pixel wide screen. ## Definition of done - Every acceptance check above has an automated test, and all tests pass. Tests run against a stand-in provider on this machine, with no outside network. - No log line holds a code, a token, a `state` or a client secret. - A README explains how to create the Google client and the GitHub app, which callback addresses to give them, and how to run the tests.