Fix StatusButton status when creating account. Add docs on GitHub OAuth app set up (#675)

Author: rustworthy

app/routes/_auth+/onboarding_.$provider.tsx

@@ -92,16 +92,15 @@ export async function loader({ request, params }: LoaderFunctionArgs) {
 	const prefilledProfile = verifySession.get(prefilledProfileKey)
 
 	const formError = authSession.get(authenticator.sessionErrorKey)
+	const hasError = typeof formError === 'string'
 
 	return json({
 		email,
 		status: 'idle',
 		submission: {
-			status: 'error',
+			status: hasError ? 'error' : undefined,
 			initialValue: prefilledProfile ?? {},
-			error: {
-				'': typeof formError === 'string' ? [formError] : [],
-			},
+			error: { '': hasError ? [formError] : [] },
 		} as SubmissionResult,
 	})
 }

app/utils/honeypot.server.ts

@@ -1,7 +1,7 @@
 import { Honeypot, SpamError } from 'remix-utils/honeypot/server'
 
 export const honeypot = new Honeypot({
-	validFromFieldName: process.env.TESTING ? null : undefined,
+	validFromFieldName: process.env.NODE_ENV === "test" ? null : undefined,
 	encryptionSeed: process.env.HONEYPOT_SECRET,
 })
 

docs/authentication.md

@@ -34,6 +34,64 @@ can expand beyond this to add any other provider you'd like, and if you need to
 support SAML, you may look into
 [`@boxyhq/remix-auth-sso`](https://github.com/boxyhq/remix-auth-sso).
 
+### GitHub OAuth App
+
+You will see in `.env.example` the `GITHUB_CLIENT_ID` is set to `MOCK_...`. This
+is a precondition for a "Mock GitHub server" to be installed (with the help of
+[`msw`](https://github.com/mswjs/msw) library). See this
+[module](../tests/mocks/github.ts) for more details and pay attention to how the
+calls to `https://github.com/login/oauth/access_token` are being intercepted.
+But once deployed to an environment where `process.env.MOCKS` is not set to
+`'true'` (see how this is done when launching the
+[dev server](../server/dev-server.js) and checked in the
+[entrypoint](../index.js)), or even when developing _locally_ but not setting
+`GITHUB_CLIENT_ID` to `MOCK_...`, the requests will actually reach the GitHub
+auth server. This is where you will want to have a GitHub OAuth application
+properly set up, otherwise the logging in with GitHub will fail and a
+corresponding toast will appear on the screen.
+
+To set up a real OAuth application, log in to GitHub, go to
+`Settings -> Developer settings -> OAuth Apps`, and hit the
+`Register a new application` button. Type in `http://localhost:3000` for
+"Homepage URL" and `http://localhost:3000/auth/github/callback` for
+"Authorization callback URL". As for the `Application name` set to something
+meaningful (because your users will see the app's name), e.g.
+`MY_EPIC_APPLICATION_DEVELOPMENT`. Hit `Register application` button. You will
+be redirected to the page with your newly created OAuth app's details. You will
+see your app has got `0` users and no client secrets just yet, but the Client ID
+has already been assigned to your app. Copy over this value to
+`GITHUB_CLIENT_ID` in your _.env_ file. Now hit `Generate client secret` button,
+and copy over the newly generted secret to `GITHUB_CLIENT_SECRET` in the dotenv
+file. Hit `Update application` button on your GitHub OAuth app page.
+
+Your `.env` file should resemble this (values have been redacted):
+
+```bash
+# some other secrets and env vars
+...
+
+GITHUB_CLIENT_ID="72fa***************a"
+GITHUB_CLIENT_SECRET="b2c6d323b**************************eae016"
+```
+
+Now, run the epic-stack app in dev mode, go to login page, and use the
+`Login with GitHub` option. You will be redirected to GitHub, and prompted to
+authorize the "MY_EPIC_APPLICATION_DEVELOPMENT" (or whatever the name of your
+OAuth app is) OAuth app to access your GitHub account data. After you give your
+consent, you will be redirected to your epic-stack app running on localhost, and
+the onboarding will kick off. You can now refresh your GitHub OAuth app page and
+see how the number of registered users increased to `1`.
+
+Something to appreciate here, is that you as the GitHub OAuth app owner (since
+you created it in your GitHub account) and you as a user authorizing this GitHub
+OAuth app to access your account's data are _two different_ entities. The OAuth
+app could have been registered with an Organisation or another person's GitHub
+account.
+
+Also make sure to register separate additional OAuth apps for each of your
+deployed environments (e.g. `staging` and `production`) and specify corresponding
+homepage and redirect urls in there.
+
 ## TOTP and Two-Factor Authentication
 
 Two factor authentication is built-into the Epic Stack. It's managed using a the

tests/mocks/github.ts

@@ -118,7 +118,9 @@ async function getUser(request: Request) {
 }
 
 const passthroughGitHub =
-	!process.env.GITHUB_CLIENT_ID.startsWith('MOCK_') && !process.env.TESTING
+	!process.env.GITHUB_CLIENT_ID.startsWith('MOCK_') &&
+	process.env.NODE_ENV !== 'test'
+
 export const handlers: Array<HttpHandler> = [
 	http.post(
 		'https://github.com/login/oauth/access_token',