docs: polish readme, update example.env, and gitignore (#2173)

## What kind of change does this PR introduce?

Docs update / configuration cleanup

## What is the current behavior?

* README contained inconsistent wording, capitalization, and formatting.
* `example.env` provider sections weren’t fully normalized (e.g., brand
naming).
* `.idea` IDE files were not ignored, risking accidental commits.

## What is the new behavior?

* README polished for clarity and consistency (terminology, grammar,
branding).
* `example.env` updated with cleaner provider sections and improved
comments (e.g., explicit **Twitter (X)** naming).
* `.gitignore` updated to exclude `.idea` directories.
* Inherited features section: updated the outdated note on JWT signing.
It now reflects current Supabase Auth behavior: asymmetric signing keys
(RS256 by default, ECC/Ed25519 optional) are supported and recommended,
while HS256 remains for compatibility.

## Additional context

This PR improves documentation and developer ergonomics only. Read
through the readme because I wanted to contribute to the project and
just updated everything that didn't look right. No functional or runtime
changes.

---------

Co-authored-by: Chris Stockton <180184+cstockton@users.noreply.github.com>

Author: nicokempe

.gitignore

@@ -12,6 +12,7 @@ coverage.out
 
 .DS_Store
 .vscode
+.idea
 www/dist/
 www/.DS_Store
 www/node_modules

README.md

@@ -16,7 +16,7 @@ It is originally based on the excellent
 
 If you wish to contribute to the project, please refer to the [contributing guide](/CONTRIBUTING.md).
 
-## Table Of Contents
+## Table of Contents
 
 - [Quick Start](#quick-start)
 - [Running in Production](#running-in-production)
@@ -25,9 +25,9 @@ If you wish to contribute to the project, please refer to the [contributing guid
 
 ## Quick Start
 
-Create a `.env` file to store your own custom env vars. See [`example.env`](example.env)
+Create a `.env` file to store your own custom environment variables. See [`example.env`](example.env)
 
-1. Start the local postgres database in a postgres container: `docker-compose -f docker-compose-dev.yml up postgres`
+1. Start the local Postgres database in a Postgres container: `docker-compose -f docker-compose-dev.yml up postgres`
 2. Build the auth binary: `make build` . You should see an output like this:
 
 ```bash
@@ -37,22 +37,22 @@ GOOS=linux GOARCH=arm64 go build -ldflags "-X github.com/supabase/auth/cmd.Versi
 
 3. Execute the auth binary: `./auth`
 
-### If you have docker installed
+### If you have Docker installed
 
 Create a `.env.docker` file to store your own custom env vars. See [`example.docker.env`](example.docker.env)
 
 1. `make build`
 2. `make dev`
-3. `docker ps` should show 2 docker containers (`auth-auth-1` and `auth-postgres-1`)
-4. That's it! Visit the [health checkendpoint](http://localhost:9999/health) to confirm that auth is running.
+3. `docker ps` should show two Docker containers (`auth-auth-1` and `auth-postgres-1`)
+4. That's it! Visit the [health check endpoint](http://localhost:9999/health) to confirm that auth is running.
 
 ## Running in production
 
 Running an authentication server in production is not an easy feat. We
 recommend using [Supabase Auth](https://supabase.com/auth) which gets regular
 security updates.
 
-Otherwise, please make sure you setup a process to promptly update to the
+Otherwise, please make sure you set up a process to promptly update to the
 latest version. You can do that by following this repository, specifically the
 [Releases](https://github.com/supabase/auth/releases) and [Security
 Advisories](https://github.com/supabase/auth/security/advisories) sections.
@@ -65,8 +65,8 @@ further clarifications on backward compatibility guarantees:
 **Go API compatibility**
 
 Auth is not meant to be used as a Go library. There are no guarantees on
-backward API compatibility when used this way regardless which version number
-changes.
+backward API compatibility when used this way regardless of which version 
+number changes.
 
 **Patch**
 
@@ -145,9 +145,12 @@ comprehensive list of those features:
 3. Super admin via the `is_super_admin` column.
 4. Group information in JWTs via `GOTRUE_JWT_ADMIN_GROUP_NAME` and other
    configuration fields.
-5. Symmetrics JWTs. In the future it is very likely that Auth will begin
-   issuing asymmetric JWTs (subject to configuration), so do not rely on the
-   assumption that only HS256 signed JWTs will be issued long term.
+5. JWT signing. Supabase Auth supports asymmetric keys (RS256 by default;
+   ECC/Ed25519 optional). HS256 is still supported for compatibility, but
+   migrating to asymmetric keys is recommended for easier validation and
+   rotation. Future deprecations will be announced in the changelog. See the
+   [JWT Signing Keys](https://supabase.com/docs/guides/auth/signing-keys) and
+   [JWTs guide](https://supabase.com/docs/guides/auth/jwts) for details.
 
 Note that this is not an exhaustive list and it may change.
 
@@ -158,7 +161,7 @@ compatibility with Auth:
 
 1. Do not modify the schema managed by Auth. You can see all of the
    migrations in the `migrations` directory.
-2. Do not rely on schema and structure of data in the database. Always use
+2. Do not rely on the schema and the structure of data in the database. Always use
    Auth APIs and JWTs to infer information about users.
 3. Always run Auth behind a TLS-capable proxy such as a load balancer, CDN,
    nginx or other similar software.
@@ -180,7 +183,7 @@ The base URL your site is located at. Currently used in combination with other s
 
 `URI_ALLOW_LIST` - `string`
 
-A comma separated list of URIs (e.g. `"https://foo.example.com,https://*.foo.example.com,https://bar.example.com"`) which are permitted as valid `redirect_to` destinations. Defaults to []. Supports wildcard matching through globbing. e.g. `https://*.foo.example.com` will allow `https://a.foo.example.com` and `https://b.foo.example.com` to be accepted. Globbing is also supported on subdomains. e.g. `https://foo.example.com/*` will allow `https://foo.example.com/page1` and `https://foo.example.com/page2` to be accepted.
+A comma-separated list of URIs (e.g. `"https://foo.example.com,https://*.foo.example.com,https://bar.example.com"`) which are permitted as valid `redirect_to` destinations. Defaults to []. Supports wildcard matching through globbing. e.g. `https://*.foo.example.com` will allow `https://a.foo.example.com` and `https://b.foo.example.com` to be accepted. Globbing is also supported on subdomains. e.g. `https://foo.example.com/*` will allow `https://foo.example.com/page1` and `https://foo.example.com/page2` to be accepted.
 
 For more common glob patterns, check out the [following link](https://pkg.go.dev/github.com/gobwas/glob#Compile).
 
@@ -195,19 +198,19 @@ When signup is disabled the only way to create new users is through invites. Def
 
 `GOTRUE_EXTERNAL_EMAIL_ENABLED` - `bool`
 
-Use this to disable email signups (users can still use external oauth providers to sign up / sign in)
+Use this to disable email signups (users can still use external OAuth providers to sign up / sign in)
 
 `GOTRUE_EXTERNAL_PHONE_ENABLED` - `bool`
 
-Use this to disable phone signups (users can still use external oauth providers to sign up / sign in)
+Use this to disable phone signups (users can still use external OAuth providers to sign up / sign in)
 
 `GOTRUE_RATE_LIMIT_HEADER` - `string`
 
 Header on which to rate limit the `/token` endpoint.
 
 `GOTRUE_RATE_LIMIT_EMAIL_SENT` - `string`
 
-Rate limit the number of emails sent per hr on the following endpoints: `/signup`, `/invite`, `/magiclink`, `/recover`, `/otp`, & `/user`.
+Rate limit the number of emails sent per hour on the following endpoints: `/signup`, `/invite`, `/magiclink`, `/recover`, `/otp`, & `/user`.
 
 `GOTRUE_PASSWORD_MIN_LENGTH` - `int`
 
@@ -217,7 +220,7 @@ Minimum password length, defaults to 6.
 
 `GOTRUE_SECURITY_REFRESH_TOKEN_ROTATION_ENABLED` - `bool`
 
-If refresh token rotation is enabled, auth will automatically detect malicious attempts to reuse a revoked refresh token. When a malicious attempt is detected, gotrue immediately revokes all tokens that descended from the offending token.
+If refresh token rotation is enabled, auth will automatically detect malicious attempts to reuse a revoked refresh token. When a malicious attempt is detected, GoTrue immediately revokes all tokens that descended from the offending token.
 
 `GOTRUE_SECURITY_REFRESH_TOKEN_REUSE_INTERVAL` - `string`
 
@@ -247,7 +250,7 @@ Controls what endpoint Netlify can access this API on.
 
 `API_EXTERNAL_URL` - `string` **required**
 
-The URL on which Gotrue might be accessed at.
+The URL on which GoTrue might be accessed at.
 
 `REQUEST_ID_HEADER` - `string`
 
@@ -307,7 +310,7 @@ Auth has basic observability built in. It is able to export
 
 To enable tracing configure these variables:
 
-`GOTRUE_TRACING_ENABLED` - `boolean`
+`GOTRUE_TRACING_ENABLED` - `bool`
 
 `GOTRUE_TRACING_EXPORTER` - `string` only `opentelemetry` supported
 
@@ -498,7 +501,7 @@ To try out external authentication with Apple locally, you will need to do the f
 3. Generate the crt and key file. See [here](https://www.freecodecamp.org/news/how-to-get-https-working-on-your-local-development-environment-in-5-minutes-7af615770eec/) for more information.
 4. Generate the `GOTRUE_EXTERNAL_APPLE_SECRET` by following this [post](https://medium.com/identity-beyond-borders/how-to-configure-sign-in-with-apple-77c61e336003)!
 
-### E-Mail
+### Email
 
 Sending email is not required, but highly recommended for password recovery.
 If enabled, you must provide the required values below.
@@ -546,7 +549,7 @@ If you do not require email confirmation, you may set this to `true`. Defaults t
 
 `MAILER_OTP_EXP` - `number`
 
-Controls the duration an email link or otp is valid for.
+Controls the duration an email link or OTP is valid for.
 
 `MAILER_URLPATHS_INVITE` - `string`
 
@@ -831,15 +834,15 @@ If you do not require phone confirmation, you may set this to `true`. Defaults t
 
 `SMS_MAX_FREQUENCY` - `number`
 
-Controls the minimum amount of time that must pass before sending another sms otp. The value is the number of seconds. Defaults to 60 (1 minute)).
+Controls the minimum amount of time that must pass before sending another SMS OTP. The value is the number of seconds. Defaults to 60 (1 minute).
 
 `SMS_OTP_EXP` - `number`
 
-Controls the duration an sms otp is valid for.
+Controls the duration an SMS OTP is valid for.
 
 `SMS_OTP_LENGTH` - `number`
 
-Controls the number of digits of the sms otp sent.
+Controls the number of digits of the SMS OTP sent.
 
 `SMS_PROVIDER` - `string`
 
@@ -866,7 +869,7 @@ Whether captcha middleware is enabled
 
 `SECURITY_CAPTCHA_PROVIDER` - `string`
 
-for now the only options supported are: `hcaptcha` and `turnstile`
+for now the only options supported are: hCaptcha and Turnstile
 
 - `SECURITY_CAPTCHA_SECRET` - `string`
 - `SECURITY_CAPTCHA_TIMEOUT` - `string`
@@ -1121,7 +1124,7 @@ Returns:
 }
 ```
 
-Verify a phone signup or sms otp. Type should be set to `sms`.
+Verify a phone signup or SMS OTP. Type should be set to `sms`.
 
 ```json
 {
@@ -1171,7 +1174,7 @@ or show an account confirmed/welcome message in the case of `signup`, or direct
 
 ### **POST /otp**
 
-One-Time-Password. Will deliver a magiclink or sms otp to the user depending on whether the request body contains an "email" or "phone" key.
+One-Time-Password. Will deliver a magic link or SMS OTP to the user depending on whether the request body contains an "email" or "phone" key.
 
 If `"create_user": true`, user will not be automatically signed up if the user doesn't exist.
 
@@ -1217,7 +1220,7 @@ Returns:
 {}
 ```
 
-when clicked the magic link will redirect the user to `<SITE_URL>#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=magiclink` (see `/verify` above)
+When the magic link is clicked, it will redirect to `<SITE_URL>#access_token=x&refresh_token=y&expires_in=z&token_type=bearer&type=magiclink` (see `/verify` above)
 
 ### **POST /recover**
 
@@ -1314,7 +1317,7 @@ Returns:
 ### **PUT /user**
 
 Update a user (Requires authentication). Apart from changing email/password, this
-method can be used to set custom user data. Changing the email will result in a magiclink being sent out.
+method can be used to set custom user data. Changing the email will result in a magic link being sent out.
 
 ```json
 {
@@ -1367,7 +1370,7 @@ headers: {
 Logout a user (Requires authentication).
 
 This will revoke all refresh tokens for the user. Remember that the JWT tokens
-will still be valid for stateless auth until they expires.
+will still be valid for stateless auth until they expire.
 
 ### **GET /authorize**
 
@@ -1383,11 +1386,11 @@ scopes=<optional additional scopes depending on the provider (email and name are
 
 Redirects to provider and then to `/callback`
 
-For apple specific setup see: <https://github.com/supabase/auth#apple-oauth>
+For Apple-specific setup see: <https://github.com/supabase/auth#apple-oauth>
 
 ### **GET /callback**
 
-External provider should redirect to here
+External provider should redirect to this endpoint
 
 Redirects to `<GOTRUE_SITE_URL>#access_token=<access_token>&refresh_token=<refresh_token>&provider_token=<provider_oauth_token>&expires_in=3600&provider=<provider_name>`
 If additional scopes were requested then `provider_token` will be populated, you can use this to fetch additional data from the provider or interact with their services

example.env

@@ -114,7 +114,7 @@ GOTRUE_EXTERNAL_FIGMA_CLIENT_ID=""
 GOTRUE_EXTERNAL_FIGMA_SECRET=""
 GOTRUE_EXTERNAL_FIGMA_REDIRECT_URI="https://localhost:9999/callback"
 
-# Gitlab OAuth config
+# GitLab OAuth config
 GOTRUE_EXTERNAL_GITLAB_ENABLED="false"
 GOTRUE_EXTERNAL_GITLAB_CLIENT_ID=""
 GOTRUE_EXTERNAL_GITLAB_SECRET=""
@@ -126,7 +126,7 @@ GOTRUE_EXTERNAL_GOOGLE_CLIENT_ID=""
 GOTRUE_EXTERNAL_GOOGLE_SECRET=""
 GOTRUE_EXTERNAL_GOOGLE_REDIRECT_URI="http://localhost:9999/callback"
 
-# Github OAuth config
+# GitHub OAuth config
 GOTRUE_EXTERNAL_GITHUB_ENABLED="false"
 GOTRUE_EXTERNAL_GITHUB_CLIENT_ID=""
 GOTRUE_EXTERNAL_GITHUB_SECRET=""
@@ -144,7 +144,7 @@ GOTRUE_EXTERNAL_NOTION_CLIENT_ID=""
 GOTRUE_EXTERNAL_NOTION_SECRET=""
 GOTRUE_EXTERNAL_NOTION_REDIRECT_URI="https://localhost:9999/callback"
 
-# Twitter OAuth1 config
+# Twitter (X) OAuth1 config
 GOTRUE_EXTERNAL_TWITTER_ENABLED="false"
 GOTRUE_EXTERNAL_TWITTER_CLIENT_ID=""
 GOTRUE_EXTERNAL_TWITTER_SECRET=""
@@ -169,7 +169,7 @@ GOTRUE_EXTERNAL_KEYCLOAK_SECRET=""
 GOTRUE_EXTERNAL_KEYCLOAK_REDIRECT_URI="http://localhost:9999/callback"
 GOTRUE_EXTERNAL_KEYCLOAK_URL="https://keycloak.example.com/auth/realms/myrealm"
 
-# Linkedin OAuth config
+# LinkedIn OAuth config
 GOTRUE_EXTERNAL_LINKEDIN_ENABLED="true"
 GOTRUE_EXTERNAL_LINKEDIN_CLIENT_ID=""
 GOTRUE_EXTERNAL_LINKEDIN_SECRET=""