Sign in with Google or GitHub

Sign-in through Google and GitHub, with linking rules that cannot be used to take over someone else's account.

This is an app part spec on Spekkr, published by kato. It is listed with the other specs. Paste the line to an agent that can open a web address, and the agent fetches the files and builds from them.

Spec
kato/oauth-sign-in
Version
0.1.2
Published by
kato
Updated
15 Nov 2026

Build this spec

Build the spec at https://spekkr.com/kato/oauth-sign-in/start.md.

Paste this to your AI agent. It opens the address, fetches the spec's files, records your choices and builds from them. Nothing to install, no account.

Published by kato.

What does the result look like?

Sign in with Google or GitHub: sign in desktopSign in with Google or GitHub: signed in homeSign in with Google or GitHub: connected accountsSign in with Google or GitHub: sign in mobile

What can I customize?

Database
Which providers

Your choices go into the line you copy. Anything else is yours to edit, but it leaves the tested path.

What do I get?

  • spec.md Requirements and acceptance criteria.

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

    Open spec.md as plain text

  • design.md Data model, rules and flows.

    Design

    This file fixes the parts that are easy to get wrong. Choose the language and framework that fit the person's project; nothing here depends on them.

    Data model

    Use the database in the database input.

    TableColumns
    oauth_identitiesid, provider, provider_user_id, user_id, email_at_link, created_at; unique on provider and provider_user_id

    users needs an email and a way to tell whether it is confirmed.

    Addresses

    These were right when this was written. Confirm them in each provider's own documentation before building.

    GoogleGitHub
    Authorizehttps://accounts.google.com/o/oauth2/v2/authhttps://github.com/login/oauth/authorize
    Tokenhttps://oauth2.googleapis.com/tokenhttps://github.com/login/oauth/access_token
    Who it isThe id_token in the token answerhttps://api.github.com/user and /user/emails
    Keyshttps://www.googleapis.com/oauth2/v3/certsnone
    Issuerhttps://accounts.google.comnone

    Ask GitHub's token address for JSON with Accept: application/json. Take every address from configuration, so tests can point at a stand-in.

    What the redirect carries

    ParameterValue
    client_idThe app's client id for the provider
    redirect_uriThis site's callback address, exactly as registered
    response_typecode
    scopeAs in R1
    state32 random bytes, base64url
    code_challengeFrom the verifier, as below
    code_challenge_methodS256
    nonceGoogle only: 32 random bytes, base64url

    Send the PKCE parameters to both providers. One that ignores them loses nothing.

    PKCE test vector

    The challenge is the SHA-256 of the verifier's ASCII bytes, in base64url without padding. From RFC 7636:

    VerifierdBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
    ChallengeE9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

    Rules

    • The cookie that holds the state, the verifier, the nonce and next is HttpOnly, Secure, SameSite=Lax, lasts 10 minutes, and is signed or encrypted with SESSION_SECRET so the browser cannot change it.
    • Cache Google's keys as their Cache-Control header allows. Fetch them again once when a token names a key that is not in the cache.
    • Use a maintained library to check the ID token's signature. Check the issuer, audience, expiry and nonce yourself as well, each with a test.
    • Rule 2 of R4 needs both sides proven: the provider vouches for the email, and the account's own email was confirmed. Linking on one side alone is how an account is taken over.
    • Adding an identity and starting the session is one transaction. The unique index is the last guard against two requests linking one identity twice.

    Configuration

    SecretPurpose
    DATABASE_URLConnection string for the chosen database.
    SESSION_SECRETProtects the cookie in R1. At least 32 random bytes.
    GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETFrom the Google OAuth client. Not needed without Google.
    GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRETFrom the GitHub OAuth app. Not needed without GitHub.

    Named here

    • The provider says the person declined with error=access_denied.
    • The token request also carries grant_type=authorization_code and the same redirect_uri.
    • The audience may be the client id as text, or a list that holds it.
    • A session lasts 30 days. Email addresses are compared trimmed and in lowercase.

    What this spec leaves to you

    Where this spec names something, use that name, so that two builds of it agree. Where it does not, the choice is yours. List what you chose in the README.

    # Design
    
    This file fixes the parts that are easy to get wrong. Choose the language and
    framework that fit the person's project; nothing here depends on them.
    
    ## Data model
    
    Use the database in the `database` input.
    
    | Table | Columns |
    | --- | --- |
    | `oauth_identities` | `id`, `provider`, `provider_user_id`, `user_id`, `email_at_link`, `created_at`; unique on `provider` and `provider_user_id` |
    
    `users` needs an `email` and a way to tell whether it is confirmed.
    
    ## Addresses
    
    These were right when this was written. Confirm them in each provider's own
    documentation before building.
    
    | | Google | GitHub |
    | --- | --- | --- |
    | Authorize | `https://accounts.google.com/o/oauth2/v2/auth` | `https://github.com/login/oauth/authorize` |
    | Token | `https://oauth2.googleapis.com/token` | `https://github.com/login/oauth/access_token` |
    | Who it is | The `id_token` in the token answer | `https://api.github.com/user` and `/user/emails` |
    | Keys | `https://www.googleapis.com/oauth2/v3/certs` | none |
    | Issuer | `https://accounts.google.com` | none |
    
    Ask GitHub's token address for JSON with `Accept: application/json`. Take every
    address from configuration, so tests can point at a stand-in.
    
    ## What the redirect carries
    
    | Parameter | Value |
    | --- | --- |
    | `client_id` | The app's client id for the provider |
    | `redirect_uri` | This site's callback address, exactly as registered |
    | `response_type` | `code` |
    | `scope` | As in R1 |
    | `state` | 32 random bytes, base64url |
    | `code_challenge` | From the verifier, as below |
    | `code_challenge_method` | `S256` |
    | `nonce` | Google only: 32 random bytes, base64url |
    
    Send the PKCE parameters to both providers. One that ignores them loses nothing.
    
    ## PKCE test vector
    
    The challenge is the SHA-256 of the verifier's ASCII bytes, in base64url without
    padding. From RFC 7636:
    
    | | |
    | --- | --- |
    | Verifier | `dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk` |
    | Challenge | `E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM` |
    
    ## Rules
    
    - The cookie that holds the `state`, the verifier, the nonce and `next` is
      `HttpOnly`, `Secure`, `SameSite=Lax`, lasts 10 minutes, and is signed or
      encrypted with `SESSION_SECRET` so the browser cannot change it.
    - Cache Google's keys as their `Cache-Control` header allows. Fetch them again
      once when a token names a key that is not in the cache.
    - Use a maintained library to check the ID token's signature. Check the issuer,
      audience, expiry and nonce yourself as well, each with a test.
    - Rule 2 of R4 needs both sides proven: the provider vouches for the email, and
      the account's own email was confirmed. Linking on one side alone is how an
      account is taken over.
    - Adding an identity and starting the session is one transaction. The unique
      index is the last guard against two requests linking one identity twice.
    
    ## Configuration
    
    | Secret | Purpose |
    | --- | --- |
    | `DATABASE_URL` | Connection string for the chosen database. |
    | `SESSION_SECRET` | Protects the cookie in R1. At least 32 random bytes. |
    | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | From the Google OAuth client. Not needed without Google. |
    | `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET` | From the GitHub OAuth app. Not needed without GitHub. |
    
    ## Named here
    
    - The provider says the person declined with `error=access_denied`.
    - The token request also carries `grant_type=authorization_code` and the same
      `redirect_uri`.
    - The audience may be the client id as text, or a list that holds it.
    - A session lasts 30 days. Email addresses are compared trimmed and in
      lowercase.
    
    ## What this spec leaves to you
    
    Where this spec names something, use that name, so that two builds of it agree.
    Where it does not, the choice is yours. List what you chose in the README.
    

    Open design.md as plain text

  • tasks.md Build tasks in order, each with a check.

    Tasks

    Work in order. Finish a task's check before starting the next.

    1. Set up. Add the table in design.md. If there is no app yet, build the smallest one: a users table and sessions. Write a stand-in provider that tests can drive. Check: migrations run from empty and the stand-in answers on this machine.
    2. PKCE and the redirect (R1). For the providers in the providers input. Check: a test reproduces the vector in design.md, and the R1 tests pass.
    3. The callback (R2). Check: the R2 acceptance tests pass.
    4. Who it is (R3). The ID token checks for Google, the two calls for GitHub. Check: the R3 acceptance tests pass, one per way a token can be wrong.
    5. Which account (R4). A pure function from what the provider said and what the database holds to one of the five outcomes. Honour link_by_email and allow_sign_up. Check: the R4 acceptance tests pass without a network.
    6. Session (R6) and settings (R5). Check: the R5 and R6 acceptance tests pass.
    7. Pages (R7). Use the app_name input. Check: every page can be used with a keyboard alone and at 360 pixels wide.
    8. Finish. Write the README and run the whole test suite. Check: every item under "Definition of done" in spec.md is true.
    # Tasks
    
    Work in order. Finish a task's check before starting the next.
    
    1. **Set up.** Add the table in `design.md`. If there is no app yet, build the
       smallest one: a `users` table and sessions. Write a stand-in provider that
       tests can drive.
       Check: migrations run from empty and the stand-in answers on this machine.
    
    2. **PKCE and the redirect (R1).** For the providers in the `providers` input.
       Check: a test reproduces the vector in `design.md`, and the R1 tests pass.
    
    3. **The callback (R2).**
       Check: the R2 acceptance tests pass.
    
    4. **Who it is (R3).** The ID token checks for Google, the two calls for GitHub.
       Check: the R3 acceptance tests pass, one per way a token can be wrong.
    
    5. **Which account (R4).** A pure function from what the provider said and what
       the database holds to one of the five outcomes. Honour `link_by_email` and
       `allow_sign_up`.
       Check: the R4 acceptance tests pass without a network.
    
    6. **Session (R6) and settings (R5).**
       Check: the R5 and R6 acceptance tests pass.
    
    7. **Pages (R7).** Use the `app_name` input.
       Check: every page can be used with a keyboard alone and at 360 pixels wide.
    
    8. **Finish.** Write the README and run the whole test suite.
       Check: every item under "Definition of done" in `spec.md` is true.
    

    Open tasks.md as plain text

Is it for me?

Platforms
web, backend

What does it need?

Accounts
A Google OAuth client, A GitHub OAuth app
Agent permissions
shell, network
Secrets it reads
DATABASE_URL SESSION_SECRET GOOGLE_CLIENT_ID GOOGLE_CLIENT_SECRET GITHUB_CLIENT_ID GITHUB_CLIENT_SECRET

What changed?

  • 0.1.215 Nov 2026Names what it builds.
  • 0.1.114 Nov 2026Says "person" where it said "buyer".
  • 0.1.014 Nov 2026Moved from dwrtz/oauth-sign-in.

For agents: start.md says how to build this spec, spec.json holds everything on this page, and bundle.tar.gz holds its files.