# GitHub

## Implemented flow

The mock implements the **OAuth 2.0 authorization code flow for OAuth Apps**:
authorize a user, exchange the code for an access token, then read `/user` and
`/user/emails` for the profile and email addresses. PKCE with S256 is supported.

It does not implement GitHub Apps: app installation, installation access tokens,
app JWT authentication, and GitHub App permissions are outside this flow. There
are no OIDC ID tokens or discovery. Repository and organization APIs are not served.

Sources: [OAuth App web flow](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/authorizing-oauth-apps#web-application-flow),
[OAuth Apps and GitHub Apps](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps),
[email API](https://docs.github.com/en/rest/users/emails#list-email-addresses-for-the-authenticated-user).

## Using the connector

```ts
// Better Auth: pass the same options you give socialProviders.github
import { mockGitHub } from "@mockatoo/connect-better-auth";
const github = { clientId: process.env.GITHUB_CLIENT_ID!,
                 clientSecret: process.env.GITHUB_CLIENT_SECRET! };
export const auth = betterAuth({
  socialProviders: process.env.NODE_ENV === "production" ? { github } : {},
  plugins: process.env.NODE_ENV === "production" ? [] : [mockGitHub(github)],
});

// Auth.js
import GitHub from "next-auth/providers/github";
import { MockGitHub } from "@mockatoo/connect-authjs";
providers: [process.env.NODE_ENV === "production" ? GitHub() : MockGitHub()],
```

- Normal sign-in issues a non-expiring `gho_` access token with no refresh token.
  The mock's `offline_access` extension issues expiring tokens and refresh tokens
  for testing refresh handling; it does not simulate a GitHub App registration.
- A private email is `null` in `/user`. Request `user:email` (or `user`) so the
  connector can load `/user/emails`; handle an unverified primary email.
- The API uses `/github/api/v3` so Auth.js can use its Enterprise URL option.
  This URL layout does not mean GitHub Enterprise features are implemented.
- Custom API requests need a `User-Agent`. Token errors can have HTTP 200;
  check the response body, and request JSON if your client expects it.

## Special test addresses

Log in as `you+<tag>@example.com` with your own account's password to get a distinct, stable test user. Tags combine with dots, such as `you+hd.unverified@example.com`. Any other tag, such as `you+1@example.com`, is just another user; see [Email tags](../email-tags.md).

| Tag | Behavior | |
| --- | --- | --- |
| `unverified` | `email_verified: false` (GitHub: primary email `verified: false`; Discord: `verified: false`; LinkedIn: `"false"` in the ID token) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/unverified.spec.ts) |
| `renamed` | Same user ID (`sub`, Microsoft `oid`, GitHub, Discord, X and Facebook `id`) as the address without `+renamed`, different email | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/renamed.spec.ts) |
| `noname` | No name (Google: also no `given_name`/`family_name`; GitHub: `name: null`; Discord: `global_name: null`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/noname.spec.ts) |
| `private` | Private email: `/user` has `email: null`, so the app must read `/user/emails` | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/private.spec.ts) |
| `revoked` | Sign-in works; every refresh returns `invalid_grant` (GitHub: `bad_refresh_token`, and only with `offline_access`; X: `invalid_request`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/revoked.spec.ts) |
| `badcode` | The code exchange fails (`invalid_grant`; GitHub: `bad_verification_code`; LinkedIn and X: `invalid_request`; Facebook: `Invalid verification code format.`) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/badcode.spec.ts) |
| `down` | The token endpoint returns 503 | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/down.spec.ts) |
| `flaky` | The first exchange of each code returns 503; a retry succeeds | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/flaky.spec.ts) |
| `slow` | Token responses are delayed (10 seconds) | [Example](https://github.com/mockatoo/examples/blob/main/better-auth-next/tests/tags/slow.spec.ts) |

## Known differences



### This provider

| Difference | Effect |
| --- | --- |
| Better Auth hardcodes `github.com`, so `mockGitHub()` contains a copy of Better Auth's token request and profile lookup with the URLs changed. | Hides changes in a newer Better Auth until the copy is updated. |
| The API is served at GitHub Enterprise's path, `/github/api/v3/user`, not at `api.github.com/user`. | Breaks code that builds `api.github.com` URLs itself. |
| OAuth App sign-in is modeled; GitHub App installation, permissions, app JWTs and installation tokens are not. Normal `gho_` tokens do not expire. The mock-only `offline_access` extension issues expiring tokens and refresh tokens without a GitHub App registration. | Cannot validate a GitHub App integration; `offline_access` only exercises refresh handling. |

### Shared mock limits

| Difference | Effect |
| --- | --- |
| ID tokens are issued to the shared mock client. Native bundle IDs and native client registrations are not modeled. | Hides a native audience setting that does not match your production registration. |
| Refresh tokens do not expire from age or inactivity, even when a response advertises `refresh_token_expires_in`. Rotation and revocation still apply where supported; `+revoked` forces refresh failure. | Hides failures after long periods without sign-in. Use `+revoked` to exercise expired or revoked grant handling. |
| Any `http`/`https` callback URL is accepted, including `localhost`. Apple refuses `http` and `localhost`, and Microsoft refuses `http` except for `localhost`, whatever the app registered. | Hides a callback URL the real provider refuses outright. |
| Everyone uses one shared client (`mockatoo` / `mockatoo-secret`). The connectors replace your production client ID and secret, Apple's signed client secret, and Microsoft's client assertion. | Hides wrong production credentials or a broken client-secret setup. |
| The login form and the consent screen appear on every sign-in; there is no remembered session. `prompt=none` fails for Google (`interaction_required`) and Microsoft (`login_required`), and Discord and LinkedIn, which skip consent for a returning user (LinkedIn even with `prompt=consent`), always ask again. | Breaks silent sign-in that works with a real signed-in user. |
| Issuers and signing keys are the mock's (for example `https://app.mockatoo.globalunderdog.com/google`, not `https://accounts.google.com`). Discord's authorization responses carry `iss=https://app.mockatoo.globalunderdog.com/discord`, not `https://discord.com`. | Breaks code that hardcodes a real issuer or key URL. |
| Tokens are only valid at the mock. Real provider APIs (Google APIs, Microsoft Graph, GitHub's `api.github.com`, Discord's `discord.com/api`, LinkedIn's `api.linkedin.com`, X's `api.x.com`, Facebook's `graph.facebook.com`) reject them, and the mock doesn't serve those APIs beyond what sign-in needs. | Breaks app features that call the provider's API after sign-in. |
| A special address (`you+tag@…`) is a different test user with the same password. Apps that strip `+tags` from emails will merge them into one user. | Breaks special addresses in such apps. |
