docs: update contributors guide

CONTRIBUTING.md

@@ -4,40 +4,39 @@ Contributions are always welcome, no matter how large or small. Before contribut
 please read the [code of conduct](CODE_OF_CONDUCT.md).
 
 ## Setup
-
 * Install Go 1.16
+* Install Docker 
 * Install [Soda CLI](https://gobuffalo.io/en/docs/db/toolbox)
-* Install Docker to run tests
-
-GoTrue uses the Go Modules support built into Go 1.11 to build. The easiest is to clone GoTrue in a directory outside of GOPATH, as in the following example:
-
-```sh
-$ git clone https://github.com/supabase/gotrue
-$ cd gotrue
-$ make deps
-```
-
-## Building
-
-```sh
-$ make build
-```
+  * `go install github.com/gobuffalo/pop/soda@latest`
+* Clone this repo: `git clone https://github.com/supabase/gotrue`
+* `cd gotrue`
+* To start the gotrue postgresql container running locally: `./hack/postgresd.sh` 
+* To compile the gotrue binary for execution: `make build` 
+* Before executing the binary (`./gotrue`), create a `.env` file in the root of the project and copy the following config in [example.env](example.env)
+* Gotrue requires a set of smtp credentials to run, you can generate your own smtp credentials via an smtp provider such as AWS SES, SendGrid, MailChimp, SendInBlue or any other smtp providers.
 
 ## Running database migrations for supabase
 - Create a `.env` file to store the custom gotrue environment variables. You can refer to an example of the `.env` file [here](hack/test.env)
-- Start PostgreSQL inside a docker container running `hack/postgresd.sh`
-- Build the gotrue binary `make build`
-- Execute the binary `./gotrue`
-  - gotrue runs any database migrations from `/migrations` on start 
+- Start PostgreSQL inside a docker container running `./hack/postgresd.sh`
+- Run `make migrate_test`
 
 ## Testing
-- Currently, we don't use a test db. You can just create a new postgres container, make sure docker is running and do:
+- Currently, we don't use a test db. The following commands should help in setting up a test database and running the tests:
 ```sh
+# Runs the database in a docker container 
 $ ./hack/postgresd.sh
+
+# Applies the migrations to the database (requires soda cli)
 $ make migrate_test
+
+# Executes the tests
 $ make test
 ```
 
+## Updating package dependencies
+1. `make deps`
+2. `go mod tidy` if necessary
+
 ## Pull Requests
 
 We actively welcome your pull requests.
@@ -48,6 +47,23 @@ We actively welcome your pull requests.
 4. Ensure the test suite passes.
 5. Make sure your code lints.
 
+### Guidelines for submitting PRs
+1. Is there a corresponding issue created for it? If so, please include it in the PR description so we can track / refer to it.
+2. Does your PR follow the [semantic-release commit guidelines](https://github.com/angular/angular.js/blob/master/DEVELOPERS.md#-git-commit-guidelines)?
+3. If the PR is a `feat`, an [RFC](https://github.com/supabase/rfcs) or a detailed description of the design implementation is required. The former (RFC) is prefered before starting on the PR.
+4. Are the existing tests passing?
+5. Have you written some tests for your PR?
+
+### Guidelines for implementing additional oauth providers
+1. Please ensure that an end-to-end test is done for the oauth provider implemented. An end-to-end test includes:
+  * Creating an application on the oauth provider site
+  * Generating your own client_id and secret
+  * Testing that `http://localhost:9999/authorize?provider=MY_COOL_NEW_PROVIDER` redirects you to the provider sign-in page
+  * The callback is handled properly
+  * Gotrue redirects to the `SITE_URL` or one of the URI's specified in the `URI_ALLOW_LIST` with the access_token, provider_token, expiry and refresh_token as query fragments
+
+2. [Writing tests for the new oauth provider implemented] Since implementing an additional oauth provider consists of making api calls to an external api, we set up a mock server to attempt to mock the responses expected from the oauth provider. 
+
 ## License
 
 By contributing to Gotrue, you agree that your contributions will be licensed

README.md

@@ -10,11 +10,13 @@ user data.
 
 Create a `.env` file to store your own custom env vars. See [`example.env`](example.env)
 
-```sh
-./hack/postgresd.sh
-make build
-./gotrue
+1. Start the local postgres database in a postgres container: `./hack/postgresd.sh` 
+2. Build the gotrue binary: `make build` . You should see an output like this:
 ```
+go build -ldflags "-X github.com/supabase/gotrue/cmd.Version=`git rev-parse HEAD`"
+GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/gotrue/cmd.Version=`git rev-parse HEAD`" -o gotrue-arm64
+```
+3. Execute the gotrue binary: `./gotrue` (if you're on x86) `./gotrue-arm64` (if you're on arm)
 
 ## Configuration
 

example.env

@@ -1,114 +1,168 @@
+# General Config
+# NOTE: The service_role key is required as an authorization header for /admin endpoints
+
 GOTRUE_JWT_SECRET="CHANGE-THIS! VERY IMPORTANT!"
 GOTRUE_JWT_EXP="3600"
 GOTRUE_JWT_AUD="authenticated"
 GOTRUE_JWT_DEFAULT_GROUP_NAME="authenticated"
 GOTRUE_JWT_ADMIN_ROLES="supabase_admin,service_role"
+
+# Database & API connection details
 GOTRUE_DB_DRIVER="postgres"
+NAMESPACE="auth"
+DATABASE_URL="postgres://supabase_auth_admin:root@localhost:5432/postgres"
 API_EXTERNAL_URL="http://localhost:9999"
 GOTRUE_API_HOST="localhost"
 PORT="9999"
-GOTRUE_DISABLE_SIGNUP="false"
-GOTRUE_SITE_URL="http://example.com"
-GOTRUE_URI_ALLOW_LIST="http://example.com/settings"
+
+# SMTP config (generate credentials for signup to work)
 GOTRUE_SMTP_HOST=""
 GOTRUE_SMTP_PORT=""
 GOTRUE_SMTP_USER=""
-GOTRUE_SMTP_MAX_FREQUENCY="60s"
+GOTRUE_SMTP_MAX_FREQUENCY="5s"
 GOTRUE_SMTP_PASS=""
 GOTRUE_SMTP_ADMIN_EMAIL=""
 GOTRUE_SMTP_SENDER_NAME=""
-GOTRUE_MAILER_AUTOCONFIRM="false"
+
+# Mailer config 
+GOTRUE_MAILER_AUTOCONFIRM="true"
 GOTRUE_MAILER_URLPATHS_CONFIRMATION="/verify"
 GOTRUE_MAILER_URLPATHS_INVITE="/verify"
 GOTRUE_MAILER_URLPATHS_RECOVERY="/verify"
 GOTRUE_MAILER_URLPATHS_EMAIL_CHANGE="/verify"
-GOTRUE_MAILER_SUBJECTS_CONFIRMATION="Confirm Your Signup"
+GOTRUE_MAILER_SUBJECTS_CONFIRMATION="Confirm Your Email"
 GOTRUE_MAILER_SUBJECTS_RECOVERY="Reset Your Password"
 GOTRUE_MAILER_SUBJECTS_MAGIC_LINK="Your Magic Link"
 GOTRUE_MAILER_SUBJECTS_EMAIL_CHANGE="Confirm Email Change"
 GOTRUE_MAILER_SUBJECTS_INVITE="You have been invited"
+GOTRUE_MAILER_SECURE_EMAIL_CHANGE_ENABLED="true"
+
+# Custom mailer template config
+GOTRUE_MAILER_TEMPLATES_INVITE=""
+GOTRUE_MAILER_TEMPLATES_CONFIRMATION=""
+GOTRUE_MAILER_TEMPLATES_RECOVERY=""
+GOTRUE_MAILER_TEMPLATES_MAGIC_LINK=""
+GOTRUE_MAILER_TEMPLATES_EMAIL_CHANGE=""
+
+# Signup config
+GOTRUE_DISABLE_SIGNUP="false"
+GOTRUE_SITE_URL="http://localhost:3000"
 GOTRUE_EXTERNAL_EMAIL_ENABLED="true"
 GOTRUE_EXTERNAL_PHONE_ENABLED="true"
-GOTRUE_EXTERNAL_GITHUB_ENABLED="false"
-GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=""
-GOTRUE_EXTERNAL_GITHUB_SECRET=""
-GOTRUE_EXTERNAL_BITBUCKET_ENABLED="false"
-GOTRUE_EXTERNAL_BITBUCKET_CLIENT_ID=""
-GOTRUE_EXTERNAL_BITBUCKET_SECRET=""
+GOTRUE_EXTERNAL_IOS_BUNDLE_ID="com.supabase.gotrue"
+
+# Whitelist redirect to URLs here
+GOTRUE_URI_ALLOW_LIST=["http://localhost:3000"]
+
+# Apple OAuth config
+GOTRUE_EXTERNAL_APPLE_ENABLED="false"
+GOTRUE_EXTERNAL_APPLE_CLIENT_ID=""
+GOTRUE_EXTERNAL_APPLE_SECRET=""
+GOTRUE_EXTERNAL_APPLE_REDIRECT_URI="http://localhost:9999/callback"
+
+# Azure OAuth config
 GOTRUE_EXTERNAL_AZURE_ENABLED="false"
 GOTRUE_EXTERNAL_AZURE_CLIENT_ID=""
 GOTRUE_EXTERNAL_AZURE_SECRET=""
+GOTRUE_EXTERNAL_AZURE_REDIRECT_URI="https://localhost:9999/callback"
+
+# Bitbucket OAuth config
+GOTRUE_EXTERNAL_BITBUCKET_ENABLED="false"
+GOTRUE_EXTERNAL_BITBUCKET_CLIENT_ID=""
+GOTRUE_EXTERNAL_BITBUCKET_SECRET=""
+GOTRUE_EXTERNAL_BITBUCKET_REDIRECT_URI="http://localhost:9999/callback"
+
+# Discord OAuth config
+GOTRUE_EXTERNAL_DISCORD_ENABLED="false"
+GOTRUE_EXTERNAL_DISCORD_CLIENT_ID=""
+GOTRUE_EXTERNAL_DISCORD_SECRET=""
+GOTRUE_EXTERNAL_DISCORD_REDIRECT_URI="https://localhost:9999/callback"
+
+# Gitlab OAuth config
+GOTRUE_EXTERNAL_GITLAB_ENABLED="false"
+GOTRUE_EXTERNAL_GITLAB_CLIENT_ID=""
+GOTRUE_EXTERNAL_GITLAB_SECRET=""
+GOTRUE_EXTERNAL_GITLAB_REDIRECT_URI="http://localhost:9999/callback"
+
+# Google OAuth config
+GOTRUE_EXTERNAL_GOOGLE_ENABLED="false"
+GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID=""
+GOTRUE_EXTERNAL_GOOGLE_SECRET=""
+GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI="http://localhost:9999/callback"
+
+# Github OAuth config
+GOTRUE_EXTERNAL_GITHUB_ENABLED="false"
+GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=""
+GOTRUE_EXTERNAL_GITHUB_SECRET=""
+GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI="http://localhost:9999/callback"
+
+# Facebook OAuth config
 GOTRUE_EXTERNAL_FACEBOOK_ENABLED="false"
 GOTRUE_EXTERNAL_FACEBOOK_CLIENT_ID=""
 GOTRUE_EXTERNAL_FACEBOOK_SECRET=""
-GOTRUE_EXTERNAL_SPOTIFY_ENABLED="true"
+GOTRUE_EXTERNAL_FACEBOOK_REDIRECT_URI="https://localhost:9999/callback"
+
+# Twitter OAuth1 config
+GOTRUE_EXTERNAL_TWITTER_ENABLED="false"
+GOTRUE_EXTERNAL_TWITTER_CLIENT_ID=""
+GOTRUE_EXTERNAL_TWITTER_SECRET=""
+GOTRUE_EXTERNAL_TWITTER_REDIRECT_URI="http://localhost:9999/callback"
+
+# Twitch OAuth config
+GOTRUE_EXTERNAL_TWITCH_ENABLED="false"
+GOTRUE_EXTERNAL_TWITCH_CLIENT_ID=""
+GOTRUE_EXTERNAL_TWITCH_SECRET=""
+GOTRUE_EXTERNAL_TWITCH_REDIRECT_URI="http://localhost:9999/callback"
+
+# Spotify OAuth config
+GOTRUE_EXTERNAL_SPOTIFY_ENABLED="false"
 GOTRUE_EXTERNAL_SPOTIFY_CLIENT_ID=""
 GOTRUE_EXTERNAL_SPOTIFY_SECRET=""
-GOTRUE_EXTERNAL_SLACK_ENABLED="true"
+GOTRUE_EXTERNAL_SPOTIFY_REDIRECT_URI="http://localhost:9999/callback"
+
+# Slack OAuth config
+GOTRUE_EXTERNAL_SLACK_ENABLED="false"
 GOTRUE_EXTERNAL_SLACK_CLIENT_ID=""
 GOTRUE_EXTERNAL_SLACK_SECRET=""
-GOTRUE_EXTERNAL_TWITTER_ENABLED="false"
-GOTRUE_EXTERNAL_TWITTER_CLIENT_ID=""
-GOTRUE_EXTERNAL_TWITTER_SECRET=""
-GOTRUE_EXTERNAL_APPLE_ENABLED=""
-GOTRUE_EXTERNAL_APPLE_CLIENT_ID=""
-GOTRUE_EXTERNAL_APPLE_SECRET=""
-GOTRUE_EXTERNAL_GOOGLE_ENABLED="true"
-GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID=""
-GOTRUE_EXTERNAL_GOOGLE_SECRET=""
-GOTRUE_EXTERNAL_DISCORD_ENABLED="true"
-GOTRUE_EXTERNAL_DISCORD_CLIENT_ID=""
-GOTRUE_EXTERNAL_DISCORD_SECRET=""
-GOTRUE_EXTERNAL_GITLAB_ENABLED="false"
-GOTRUE_EXTERNAL_GITLAB_CLIENT_ID=""
-GOTRUE_EXTERNAL_GITLAB_SECRET=""
-GOTRUE_EXTERNAL_GITLAB_REDIRECT_URI=""
-GOTRUE_EXTERNAL_SAML_ENABLED="false"
-GOTRUE_EXTERNAL_SAML_METADATA_URL="/"
-GOTRUE_EXTERNAL_SAML_API_BASE="/"
-GOTRUE_EXTERNAL_SAML_NAME="auth0"
-GOTRUE_EXTERNAL_SAML_SIGNING_CERT="/"
-GOTRUE_EXTERNAL_SAML_SIGNING_KEY="/"
-GOTRUE_MAILER_TEMPLATES_INVITE="https://app.supabase.io/api/auth/example-project-ref/templates/invite"
-GOTRUE_MAILER_TEMPLATES_CONFIRMATION="https://app.supabase.io/api/auth/example-project-ref/templates/confirmation"
-GOTRUE_MAILER_TEMPLATES_RECOVERY="https://app.supabase.io/api/auth/example-project-ref/templates/recovery"
-GOTRUE_MAILER_TEMPLATES_MAGIC_LINK="https://app.supabase.io/api/auth/example-project-ref/templates/magic-link"
-GOTRUE_MAILER_TEMPLATES_EMAIL_CHANGE="https://app.supabase.io/api/auth/example-project-ref/templates/email-change"
-GOTRUE_EXTERNAL_DISCORD_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_GITHUB_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_BITBUCKET_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_AZURE_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_FACEBOOK_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_TWITTER_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_APPLE_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_SPOTIFY_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_SLACK_REDIRECT_URI="http://example.com/callback"
-GOTRUE_EXTERNAL_TWITCH_ENABLED=true
-GOTRUE_EXTERNAL_TWITCH_CLIENT_ID="6ww3qbjo9luvlj22yxk0u0negp381s"
-GOTRUE_EXTERNAL_TWITCH_SECRET="ubu4pfs2ghk39cn0bsxmzyv7cykgu0"
-GOTRUE_EXTERNAL_TWITCH_REDIRECT_URI="http://example.com/callback"
-GOTRUE_LOG_LEVEL="debug"
-GOTRUE_OPERATOR_TOKEN="super-secret-operator-token"
-GOTRUE_RATE_LIMIT_HEADER="X-Real-IP"
-DATABASE_URL=""
+GOTRUE_EXTERNAL_SLACK_REDIRECT_URI="https://localhost:9999/callback"
+
+# Phone provider config
 GOTRUE_SMS_AUTOCONFIRM="false"
 GOTRUE_SMS_MAX_FREQUENCY="5s"
-GOTRUE_SMS_OTP_EXP="60"
+GOTRUE_SMS_OTP_EXP="6000"
 GOTRUE_SMS_OTP_LENGTH="6"
 GOTRUE_SMS_PROVIDER="twilio"
 GOTRUE_SMS_TWILIO_ACCOUNT_SID=""
 GOTRUE_SMS_TWILIO_AUTH_TOKEN=""
 GOTRUE_SMS_TWILIO_MESSAGE_SERVICE_SID=""
-GOTRUE_SMS_TEMPLATE=""
+GOTRUE_SMS_TEMPLATE="This is from supabase. Your code is {{ .Code }} ."
 GOTRUE_SMS_MESSAGEBIRD_ACCESS_KEY=""
 GOTRUE_SMS_MESSAGEBIRD_ORIGINATOR=""
+
+# Captcha config
+GOTRUE_SECURITY_CAPTCHA_ENABLED="false"
+GOTRUE_SECURITY_CAPTCHA_PROVIDER="hcaptcha"
+GOTRUE_SECURITY_CAPTCHA_SECRET="0x0000000000000000000000000000000000000000"
+GOTRUE_SESSION_KEY=""
+
+# SAML config
+GOTRUE_EXTERNAL_SAML_ENABLED="true"
+GOTRUE_EXTERNAL_SAML_METADATA_URL=""
+GOTRUE_EXTERNAL_SAML_API_BASE="http://localhost:9999"
+GOTRUE_EXTERNAL_SAML_NAME="auth0"
+GOTRUE_EXTERNAL_SAML_SIGNING_CERT=""
+GOTRUE_EXTERNAL_SAML_SIGNING_KEY=""
+
+# Additional Security config
+GOTRUE_LOG_LEVEL="debug"
+GOTRUE_REFRESH_TOKEN_ROTATION_ENABLED="false"
+GOTRUE_OPERATOR_TOKEN="unused-operator-token"
+GOTRUE_RATE_LIMIT_HEADER="X-Forwarded-For"
+GOTRUE_RATE_LIMIT_EMAIL_SENT="100"
+
+# Webhook config
 GOTRUE_WEBHOOK_URL=http://register-lambda:3000/
 GOTRUE_WEBHOOK_SECRET=test_secret
 GOTRUE_WEBHOOK_RETRIES=5
 GOTRUE_WEBHOOK_TIMEOUT_SEC=3
 GOTRUE_WEBHOOK_EVENTS=validate,signup,login
-
-GOTRUE_SECURITY_CAPTCHA_ENABLED="true"
-GOTRUE_SECURITY_CAPTCHA_PROVIDER="hcaptcha"
-GOTRUE_SECURITY_CAPTCHA_SECRET="0x0000000000000000000000000000000000000000"