@studiocms/auth0 0.1.0-beta.23

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present StudioCMS - withstudiocms (https://github.com/withstudiocms)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+# @studiocms/auth0 Plugin
+
+This plugin integrates Auth0 as an OAuth provider for StudioCMS, enabling authentication via Auth0. It sets up the necessary configuration, including required environment variables and endpoint paths.
+
+## Usage
+
+Add this plugin in your StudioCMS config. (`studiocms.config.mjs`)
+
+```ts
+import { defineStudioCMSConfig } from 'studiocms/config';
+import auth0 from '@studiocms/auth0';
+
+export default defineStudioCMSConfig({
+    // other options here
+    plugins: [auth0()]
+});
+```
+
+## Required ENV Variables
+
+- `CMS_AUTH0_CLIENT_ID`
+- `CMS_AUTH0_CLIENT_SECRET`
+- `CMS_AUTH0_DOMAIN`
+- `CMS_AUTH0_REDIRECT_URI`
+
+## License
+
+[MIT Licensed](./LICENSE).

package/dist/effect/auth0.d.ts

@@ -0,0 +1,93 @@
+import { HttpClient } from '@effect/platform';
+import type { APIContext } from 'astro';
+import { Effect, Schema } from 'studiocms/effect';
+declare const Auth0User_base: Schema.Class<Auth0User, {
+    sub: typeof Schema.String;
+    name: typeof Schema.String;
+    email: typeof Schema.String;
+    picture: typeof Schema.String;
+    nickname: typeof Schema.String;
+}, Schema.Struct.Encoded<{
+    sub: typeof Schema.String;
+    name: typeof Schema.String;
+    email: typeof Schema.String;
+    picture: typeof Schema.String;
+    nickname: typeof Schema.String;
+}>, never, {
+    readonly sub: string;
+} & {
+    readonly name: string;
+} & {
+    readonly email: string;
+} & {
+    readonly picture: string;
+} & {
+    readonly nickname: string;
+}, {}, {}>;
+/**
+ * Represents a user authenticated via Auth0.
+ *
+ * @property {string} sub - The unique identifier for the user (subject).
+ * @property {string} name - The full name of the user.
+ * @property {string} email - The email address of the user.
+ * @property {string} picture - The URL to the user's profile picture.
+ * @property {string} nickname - The user's nickname.
+ */
+export declare class Auth0User extends Auth0User_base {
+}
+/**
+ * Returns the normalized domain string for Auth0 authentication.
+ *
+ * This function performs the following transformations:
+ * - Removes any leading slash from the domain.
+ * - Strips out the "http://" or "https://" protocol from the domain.
+ * - Prepends "https://" to the resulting domain.
+ *
+ * @returns {string} The normalized domain string with "https://" prepended.
+ */
+export declare const cleanDomain: (domain: string) => string;
+declare const Auth0OAuthAPI_base: Effect.Service.Class<Auth0OAuthAPI, "Auth0OAuthAPI", {
+    readonly dependencies: readonly [import("effect/Layer").Layer<import("studiocms/lib/auth/session").Session, never, never>, import("effect/Layer").Layer<import("studiocms/lib/auth/verify-email").VerifyEmail, import("studiocms/lib/effects/smtp").SMTPError | import("effect/Cause").UnknownException, never>, import("effect/Layer").Layer<import("studiocms/lib/auth/user").User, import("studiocms/lib/effects/smtp").SMTPError | import("effect/Cause").UnknownException, never>, import("effect/Layer").Layer<HttpClient.HttpClient, never, never>];
+    readonly effect: Effect.Effect<{
+        initSession: (context: APIContext) => Effect.Effect<Response, import("studiocms/lib/auth/session").SessionError, never>;
+        initCallback: (context: APIContext) => Effect.Effect<Response, import("studiocms/sdk/effect/db").LibSQLDatabaseError | import("studiocms/sdk/errors").SDKCoreError | Error, never>;
+    }, never, import("studiocms/lib/auth/session").Session | import("studiocms/lib/auth/verify-email").VerifyEmail | import("studiocms/lib/auth/user").User | HttpClient.HttpClient>;
+}>;
+/**
+ * Provides Auth0 OAuth authentication effects for the StudioCMS API.
+ *
+ * This service handles the OAuth flow with Auth0, including session initialization,
+ * authorization code validation, user account linking, and user creation.
+ *
+ * @remarks
+ * - Uses generator-based effects for async operations.
+ * - Integrates with session management, user library, and email verification.
+ * - Handles first-time setup and redirects based on authentication state.
+ *
+ * @example
+ * ```typescript
+ * const auth0Api = yield* Auth0OAuthAPI;
+ * yield* auth0Api.initSession(context);
+ * yield* auth0Api.initCallback(context);
+ * ```
+ *
+ * @dependencies
+ * - Session.Default
+ * - SDKCore.Default
+ * - VerifyEmail.Default
+ * - User.Default
+ *
+ * @method initSession
+ * Initializes the OAuth session by generating state and code verifier, setting cookies,
+ * and redirecting to the Auth0 authorization URL.
+ *
+ * @method initCallback
+ * Handles the OAuth callback, validates the authorization code, manages user linking,
+ * creates new users if necessary, verifies email, and creates user sessions.
+ */
+export declare class Auth0OAuthAPI extends Auth0OAuthAPI_base {
+    static ProviderID: string;
+    static ProviderCookieName: string;
+    static ProviderCodeVerifier: string;
+}
+export {};

package/dist/effect/auth0.js

@@ -0,0 +1,166 @@
+import { getSecret } from "astro:env/server";
+import { Session, User, VerifyEmail } from "studiocms:auth/lib";
+import config from "studiocms:config";
+import { StudioCMSRoutes } from "studiocms:lib";
+import { SDKCore } from "studiocms:sdk";
+import { FetchHttpClient, HttpClient, HttpClientResponse } from "@effect/platform";
+import { Auth0, generateCodeVerifier, generateState } from "arctic";
+import { Effect, genLogger, pipe, Schema } from "studiocms/effect";
+import { getCookie, getUrlParam, ValidateAuthCodeError } from "studiocms/oAuthUtils";
+class Auth0User extends Schema.Class("Auth0User")({
+  sub: Schema.String,
+  name: Schema.String,
+  email: Schema.String,
+  picture: Schema.String,
+  nickname: Schema.String
+}) {
+}
+const cleanDomain = (domain) => pipe(
+  domain,
+  (domain2) => domain2.replace(/^\//, ""),
+  (domain2) => domain2.replace(/(?:http|https):\/\//, ""),
+  (domain2) => `https://${domain2}`
+);
+const AUTH0 = {
+  CLIENT_ID: getSecret("CMS_AUTH0_CLIENT_ID") || "",
+  CLIENT_SECRET: getSecret("CMS_AUTH0_CLIENT_SECRET") || "",
+  DOMAIN: getSecret("CMS_AUTH0_DOMAIN") || "",
+  REDIRECT_URI: getSecret("CMS_AUTH0_REDIRECT_URI") || ""
+};
+class Auth0OAuthAPI extends Effect.Service()("Auth0OAuthAPI", {
+  dependencies: [Session.Default, VerifyEmail.Default, User.Default, FetchHttpClient.layer],
+  effect: genLogger("studiocms/routes/api/auth/auth0/effect")(function* () {
+    const [
+      sdk,
+      fetchClient,
+      { setOAuthSessionTokenCookie, createUserSession },
+      { isEmailVerified, sendVerificationEmail },
+      { getUserData, createOAuthUser }
+    ] = yield* Effect.all([SDKCore, HttpClient.HttpClient, Session, VerifyEmail, User]);
+    const { CLIENT_ID, CLIENT_SECRET, DOMAIN, REDIRECT_URI } = AUTH0;
+    const CLIENT_DOMAIN = cleanDomain(DOMAIN);
+    const auth0 = new Auth0(CLIENT_DOMAIN, CLIENT_ID, CLIENT_SECRET, REDIRECT_URI);
+    const validateAuthCode = (code, codeVerifier) => genLogger("studiocms/routes/api/auth/auth0/effect.validateAuthCode")(function* () {
+      const tokens = yield* Effect.tryPromise(
+        () => auth0.validateAuthorizationCode(code, codeVerifier)
+      );
+      return yield* fetchClient.get(`${CLIENT_DOMAIN}/userinfo`, {
+        headers: { Authorization: `Bearer ${tokens.accessToken()}` }
+      }).pipe(
+        Effect.flatMap(HttpClientResponse.schemaBodyJson(Auth0User)),
+        Effect.catchAll(
+          (error) => Effect.fail(
+            new ValidateAuthCodeError({
+              provider: Auth0OAuthAPI.ProviderID,
+              message: `Failed to fetch user info: ${error.message}`
+            })
+          )
+        )
+      );
+    });
+    return {
+      initSession: (context) => genLogger("studiocms/routes/api/auth/auth0/effect.initSession")(function* () {
+        const state = generateState();
+        const codeVerifier = generateCodeVerifier();
+        const scopes = ["openid", "profile", "email"];
+        const url = auth0.createAuthorizationURL(state, codeVerifier, scopes);
+        yield* setOAuthSessionTokenCookie(context, Auth0OAuthAPI.ProviderCookieName, state);
+        yield* setOAuthSessionTokenCookie(
+          context,
+          Auth0OAuthAPI.ProviderCodeVerifier,
+          codeVerifier
+        );
+        return context.redirect(url.toString());
+      }),
+      initCallback: (context) => genLogger("studiocms/routes/api/auth/auth0/effect.initCallback")(function* () {
+        const { cookies, redirect } = context;
+        const [code, state, storedState, codeVerifier] = yield* Effect.all([
+          getUrlParam(context, "code"),
+          getUrlParam(context, "state"),
+          getCookie(context, Auth0OAuthAPI.ProviderCookieName),
+          getCookie(context, Auth0OAuthAPI.ProviderCodeVerifier)
+        ]);
+        if (!code || !storedState || !codeVerifier || state !== storedState) {
+          return redirect(StudioCMSRoutes.authLinks.loginURL);
+        }
+        const auth0User = yield* validateAuthCode(code, codeVerifier);
+        const { sub: auth0UserId, name: auth0Username } = auth0User;
+        const existingOAuthAccount = yield* sdk.AUTH.oAuth.searchProvidersForId(
+          Auth0OAuthAPI.ProviderID,
+          auth0UserId
+        );
+        if (existingOAuthAccount) {
+          const user = yield* sdk.GET.users.byId(existingOAuthAccount.userId);
+          if (!user) {
+            return new Response("User not found", { status: 404 });
+          }
+          const isEmailAccountVerified2 = yield* isEmailVerified(user);
+          if (!isEmailAccountVerified2) {
+            return new Response("Email not verified, please verify your account first.", {
+              status: 400
+            });
+          }
+          yield* createUserSession(user.id, context);
+          return redirect(StudioCMSRoutes.mainLinks.dashboardIndex);
+        }
+        const loggedInUser = yield* getUserData(context);
+        const linkNewOAuth = !!cookies.get(User.LinkNewOAuthCookieName)?.value;
+        if (loggedInUser.user && linkNewOAuth) {
+          const existingUser2 = yield* sdk.GET.users.byId(loggedInUser.user.id);
+          if (existingUser2) {
+            yield* sdk.AUTH.oAuth.create({
+              userId: existingUser2.id,
+              provider: Auth0OAuthAPI.ProviderID,
+              providerUserId: auth0UserId
+            });
+            const isEmailAccountVerified2 = yield* isEmailVerified(existingUser2);
+            if (!isEmailAccountVerified2) {
+              return new Response("Email not verified, please verify your account first.", {
+                status: 400
+              });
+            }
+            yield* createUserSession(existingUser2.id, context);
+            return redirect(StudioCMSRoutes.mainLinks.dashboardIndex);
+          }
+        }
+        const newUser = yield* createOAuthUser(
+          {
+            // @ts-expect-error drizzle broke the id variable...
+            id: crypto.randomUUID(),
+            username: auth0Username,
+            name: auth0User.name,
+            email: auth0User.email,
+            avatar: auth0User.picture,
+            createdAt: /* @__PURE__ */ new Date()
+          },
+          { provider: Auth0OAuthAPI.ProviderID, providerUserId: auth0UserId }
+        );
+        if ("error" in newUser) {
+          return new Response("Error creating user", { status: 500 });
+        }
+        if (config.dbStartPage) {
+          return redirect("/done");
+        }
+        yield* sendVerificationEmail(newUser.id, true);
+        const existingUser = yield* sdk.GET.users.byId(newUser.id);
+        const isEmailAccountVerified = yield* isEmailVerified(existingUser);
+        if (!isEmailAccountVerified) {
+          return new Response("Email not verified, please verify your account first.", {
+            status: 400
+          });
+        }
+        yield* createUserSession(newUser.id, context);
+        return redirect(StudioCMSRoutes.mainLinks.dashboardIndex);
+      })
+    };
+  })
+}) {
+  static ProviderID = "auth0";
+  static ProviderCookieName = "auth0_oauth_state";
+  static ProviderCodeVerifier = "auth0_oauth_code_verifier";
+}
+export {
+  Auth0OAuthAPI,
+  Auth0User,
+  cleanDomain
+};

package/dist/endpoint.d.ts

@@ -0,0 +1,24 @@
+import type { APIRoute } from 'astro';
+/**
+ * API route handler for initializing an Auth0 session.
+ *
+ * This function uses the Effect system to compose asynchronous operations,
+ * retrieving the `initSession` method from the `Auth0OAuthAPI` and invoking it
+ * with the provided API context. The result is converted to a vanilla response
+ * using `convertToVanilla`.
+ *
+ * @param context - The API context containing request and environment information.
+ * @returns A promise resolving to the API response after session initialization.
+ */
+export declare const initSession: APIRoute;
+/**
+ * Handles the Auth0 OAuth callback endpoint.
+ *
+ * This API route initializes the Auth0 OAuth callback process by invoking the `initCallback`
+ * method from the `Auth0OAuthAPI`. It uses the Effect system to manage dependencies and
+ * asynchronous control flow, providing the default implementation of `Auth0OAuthAPI`.
+ *
+ * @param context - The API context containing request and response objects.
+ * @returns A promise resolving to the result of the Auth0 OAuth callback process.
+ */
+export declare const initCallback: APIRoute;

package/dist/endpoint.js

@@ -0,0 +1,18 @@
+import { convertToVanilla, Effect } from "studiocms/effect";
+import { Auth0OAuthAPI } from "./effect/auth0.js";
+const initSession = async (context) => await convertToVanilla(
+  Effect.gen(function* () {
+    const { initSession: initSession2 } = yield* Auth0OAuthAPI;
+    return yield* initSession2(context);
+  }).pipe(Effect.provide(Auth0OAuthAPI.Default))
+);
+const initCallback = async (context) => await convertToVanilla(
+  Effect.gen(function* () {
+    const { initCallback: initCallback2 } = yield* Auth0OAuthAPI;
+    return yield* initCallback2(context);
+  }).pipe(Effect.provide(Auth0OAuthAPI.Default))
+);
+export {
+  initCallback,
+  initSession
+};

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * These triple-slash directives defines dependencies to various declaration files that will be
+ * loaded when a user imports the StudioCMS plugin in their Astro configuration file. These
+ * directives must be first at the top of the file and can only be preceded by this comment.
+ */
+import { type StudioCMSPlugin } from 'studiocms/plugins';
+/**
+ * Registers the StudioCMS Auth0 plugin.
+ *
+ * This plugin integrates Auth0 as an OAuth provider for StudioCMS, enabling authentication via Auth0.
+ * It sets up the necessary configuration, including required environment variables and endpoint path.
+ *
+ * @returns {StudioCMSPlugin} The configured StudioCMS Auth0 plugin.
+ *
+ * @remarks
+ * - The following environment variables must be set:
+ *   - `CMS_AUTH0_CLIENT_ID`
+ *   - `CMS_AUTH0_CLIENT_SECRET`
+ *   - `CMS_AUTH0_DOMAIN`
+ *   - `CMS_AUTH0_REDIRECT_URI`
+ *
+ * @example
+ * ```typescript
+ * import { studiocmsAuth0 } from '@studiocms/auth0';
+ * const plugin = studiocmsAuth0();
+ * ```
+ */
+export declare function studiocmsAuth0(): StudioCMSPlugin;
+export default studiocmsAuth0;

package/dist/index.js

@@ -0,0 +1,34 @@
+import { createResolver } from "astro-integration-kit";
+import { definePlugin } from "studiocms/plugins";
+function studiocmsAuth0() {
+  const { resolve } = createResolver(import.meta.url);
+  const packageIdentifier = "@studiocms/auth0";
+  return definePlugin({
+    identifier: packageIdentifier,
+    name: "StudioCMS Auth0 Provider Plugin",
+    studiocmsMinimumVersion: "0.1.0-beta.22",
+    hooks: {
+      "studiocms:config:setup": ({ setAuthService }) => {
+        setAuthService({
+          oAuthProvider: {
+            name: "auth0",
+            formattedName: "Auth0",
+            endpointPath: resolve("./endpoint.js"),
+            requiredEnvVariables: [
+              "CMS_AUTH0_CLIENT_ID",
+              "CMS_AUTH0_CLIENT_SECRET",
+              "CMS_AUTH0_DOMAIN",
+              "CMS_AUTH0_REDIRECT_URI"
+            ],
+            svg: '<svg xmlns="http://www.w3.org/2000/svg"  width="24px" height="24px" viewBox="0 0 32 32" class="oauth-logo"><path fill="currentColor" d="M29.307 9.932L26.161 0H5.796L2.692 9.932c-1.802 5.75.042 12.271 5.089 16.021L16.01 32l8.208-6.068c5.005-3.75 6.911-10.25 5.089-16.021l-8.214 6.104l3.12 9.938l-8.208-6.13l-8.208 6.104l3.141-9.911l-8.25-6.063l10.177-.063l3.146-9.891l3.141 9.87z"/></svg>'
+          }
+        });
+      }
+    }
+  });
+}
+var index_default = studiocmsAuth0;
+export {
+  index_default as default,
+  studiocmsAuth0
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@studiocms/auth0",
+  "version": "0.1.0-beta.23",
+  "description": "Add Auth0 OAuth Support into your StudioCMS project.",
+  "author": {
+    "name": "withstudiocms",
+    "url": "https://studiocms.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstudiocms/studiocms.git",
+    "directory": "packages/@studiocms/auth0"
+  },
+  "contributors": [
+    "Adammatthiesen",
+    "jdtjenkins",
+    "dreyfus92",
+    "code.spirit"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "astro",
+    "astrocms",
+    "astrodb",
+    "astrostudio",
+    "astro-integration",
+    "astro-studio",
+    "astro-studiocms",
+    "cms",
+    "studiocms",
+    "withastro",
+    "plugin",
+    "studiocms-plugin"
+  ],
+  "homepage": "https://studiocms.dev",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "astro-integration-kit": "^0.18",
+    "arctic": "^3.7.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "@effect/platform": "^0.90.0",
+    "astro": "^5.12.6",
+    "effect": "^3.17.3",
+    "vite": "^6.3.4",
+    "studiocms": "0.1.0-beta.23"
+  },
+  "scripts": {
+    "build": "buildkit build 'src/**/*.{ts,astro,css,json,png}'",
+    "dev": "buildkit dev 'src/**/*.{ts,astro,css,json,png}'",
+    "typecheck": "tspc -p tsconfig.tspc.json"
+  }
+}