Eartho Provider Integration for NextAuth.js

docs/pages/data/manifest.json

@@ -47,6 +47,7 @@
     "twitter": "Twitter",
     "apple": "Apple",
     "discord": "Discord",
+    "eartho": "Eartho",
     "auth0": "Auth0",
     "facebook": "Facebook",
     "keycloak": "Keycloak",

docs/pages/getting-started/providers/eartho.mdx

@@ -0,0 +1,145 @@
+```markdown
+import { Callout } from "nextra/components"
+import { Code } from "@/components/Code"
+
+<img align="right" src="/img/providers/eartho.svg" height="64" width="64" />
+
+# Eartho Provider
+
+Eartho is an open-source, privacy-focused alternative to traditional login providers such as Google, Facebook, and Apple. It allows users to authenticate without sacrificing personal data privacy or control. By acting as a privacy-first layer over popular login providers, Eartho offers a simple, secure, and privacy-respecting sign-in experience that ensures user data remains out of reach from Big Tech tracking.
+
+## Resources
+
+- [Eartho OAuth documentation](https://docs.eartho.io)
+- [Eartho Developer Console](https://console.eartho.io)
+
+## Setup
+
+### Callback URL
+
+<Code>
+  <Code.Next>
+
+```bash
+https://example.com/api/auth/callback/eartho
+```
+
+  </Code.Next>
+  <Code.Qwik>
+
+```bash
+https://example.com/auth/callback/eartho
+```
+
+  </Code.Qwik>
+  <Code.Svelte>
+
+```bash
+https://example.com/auth/callback/eartho
+```
+
+  </Code.Svelte>
+</Code>
+
+### Environment Variables
+
+```
+AUTH_EARTHO_ID
+AUTH_EARTHO_SECRET
+```
+
+### Configuration
+
+<Code>
+  <Code.Next>
+
+```ts filename="@/auth.ts"
+import NextAuth from "next-auth"
+import Eartho from "next-auth/providers/eartho"
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [Eartho],
+})
+```
+
+  </Code.Next>
+  <Code.Qwik>
+
+```ts filename="/src/routes/plugin@auth.ts"
+import { QwikAuth$ } from "@auth/qwik"
+import Eartho from "@auth/qwik/providers/eartho"
+
+export const { onRequest, useSession, useSignIn, useSignOut } = QwikAuth$(
+  () => ({
+    providers: [Eartho],
+  })
+)
+```
+
+  </Code.Qwik>
+  <Code.Svelte>
+
+```ts filename="/src/auth.ts"
+import { SvelteKitAuth } from "@auth/sveltekit"
+import Eartho from "@auth/sveltekit/providers/eartho"
+
+export const { handle, signIn, signOut } = SvelteKitAuth({
+  providers: [Eartho],
+})
+```
+
+  </Code.Svelte>
+  <Code.Express>
+
+```ts filename="/src/app.ts"
+import { ExpressAuth } from "@auth/express"
+import Eartho from "@auth/express/providers/eartho"
+
+app.use("/auth/*", ExpressAuth({ providers: [Eartho] }))
+```
+
+  </Code.Express>
+</Code>
+
+## Notes
+
+### Refresh Token
+
+Eartho provides a Refresh Token to applications on the first user sign-in. If users need a new Refresh Token, they must re-authenticate or reauthorize the application via the Eartho console: [Eartho User Dashboard](https://console.eartho.io/permissions).
+
+```ts filename="app/api/auth/[...nextauth]/route.ts"
+import Eartho from "next-auth/providers/eartho"
+
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  providers: [
+    Eartho({
+      authorization: {
+        params: {
+          prompt: "consent",
+          access_type: "offline",
+          response_type: "code",
+        },
+      },
+    }),
+  ],
+})
+```
+
+For more information on exchanging a code for an access token and refresh token, see the [Eartho OAuth documentation](https://eartho.io/docs/oauth#token-exchange).
+
+### Email Verified
+
+Eartho provides an `email_verified` property in the OAuth profile. You can use it to restrict access to users with verified emails from specific domains.
+
+```ts filename="@/auth.ts"
+export const { handlers, auth, signIn, signOut } = NextAuth({
+  callbacks: {
+    async signIn({ account, profile }) {
+      if (account.provider === "eartho") {
+        return profile.email_verified && profile.email.endsWith("@example.com")
+      }
+      return true
+    },
+  },
+})
+```

packages/core/src/providers/eartho.ts

@@ -0,0 +1,118 @@
+/**
+ * <div class="provider" style={{backgroundColor: "#000", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
+ * <span>Built-in <b>Eartho</b> integration.</span>
+ * <a href="https://eartho.io">
+ *   <img style={{display: "block"}} src="https://eartho.io/logo.png" height="48" width="48"/>
+ * </a>
+ * </div>
+ *
+ * @module providers/eartho
+ */
+import type { OAuthConfig, OAuthUserConfig } from "./index.js"
+
+export interface EarthoProfile extends Record<string, any> {
+  aud: string
+  email: string
+  email_verified: boolean
+  exp: number
+  family_name?: string
+  given_name: string
+  iat: number
+  iss: string
+  locale?: string
+  name: string
+  picture: string
+  sub: string
+}
+
+/**
+ * Add Eartho login to your page.
+ *
+ * ### Setup
+ *
+ * #### Callback URL
+ * ```
+ * https://example.com/api/auth/callback/eartho
+ * ```
+ *
+ * #### Configuration
+ *```ts
+ * import { Auth } from "@auth/core"
+ * import Eartho from "@auth/core/providers/eartho"
+ *
+ * const request = new Request(origin)
+ * const response = await Auth(request, {
+ *   providers: [
+ *     Eartho({ clientId: EARTHO_CLIENT_ID, clientSecret: EARTHO_CLIENT_SECRET }),
+ *   ],
+ * })
+ * ```
+ *
+ * ### Resources
+ *
+ *  - [Eartho OAuth documentation](https://docs.eartho.io/)
+ *  - [Eartho OAuth Configuration](https://console.eartho.io)
+ *
+ * ### Notes
+ *
+ * By default, Auth.js assumes that the Eartho provider is
+ * based on the [OpenID Connect](https://openid.net/specs/openid-connect-core-1_0.html) specification.
+ *
+ * The "Authorized redirect URIs" used when creating the credentials must include your full domain and end in the callback path. For example;
+ *
+ * - For production: `https://{YOUR_DOMAIN}/api/auth/callback/eartho`
+ * - For development: `http://localhost:3000/api/auth/callback/eartho`
+ *
+ * :::
+ *
+ * :::tip
+ * Eartho also returns an `email_verified` boolean property in the OAuth profile.
+ *
+ * You can use this property to restrict access to people with verified accounts.
+ *
+ * ```ts
+ * const options = {
+ *   ...
+ *   callbacks: {
+ *     async signIn({ account, profile }) {
+ *       if (account.provider === "eartho") {
+ *         return profile.email_verified
+ *       }
+ *       return true
+ *     },
+ *   }
+ *   ...
+ * }
+ * ```
+ *
+ * :::
+ *
+ * The Eartho provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/eartho.ts).
+ * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/configuring-oauth-providers).
+ *
+ * :::
+ */
+export default function Eartho<P extends EarthoProfile>(
+  options: OAuthUserConfig<P>
+): OAuthConfig<P> {
+  return {
+    id: "eartho",
+    name: "Eartho",
+    type: "oidc",
+    issuer: "https://account.eartho.io",
+    idToken: false,
+    checks: ["pkce"],
+    style: {
+      brandColor: "#000",
+      logo: "https://eartho.io/logo.png",
+    },
+    profile: (profile: any) => {
+      return {
+        id: profile.sub,
+        image: profile.picture,
+        ...profile
+      }
+    },
+    options,
+  }
+}