@studiocms/github 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,27 @@
+# @studiocms/github Plugin
+
+This plugin integrates GitHub as an OAuth authentication provider for StudioCMS. It sets up the necessary authentication service, including the provider's name, endpoint paths and required environment variables.
+
+## Usage
+
+Add this plugin in your StudioCMS config. (`studiocms.config.mjs`)
+
+```ts
+import { defineStudioCMSConfig } from 'studiocms/config';
+import github from '@studiocms/github';
+
+export default defineStudioCMSConfig({
+    // other options here
+    plugins: [github()]
+});
+```
+
+## Required ENV Variables
+
+- `CMS_GITHUB_CLIENT_ID`
+- `CMS_GITHUB_CLIENT_SECRET`
+- `CMS_GITHUB_REDIRECT_URI`
+
+## License
+
+[MIT Licensed](./LICENSE).

package/dist/effect/github.d.ts

@@ -0,0 +1,87 @@
+import { HttpClient } from '@effect/platform';
+import type { APIContext } from 'astro';
+import { Effect, Schema } from 'studiocms/effect';
+declare const GitHubUser_base: Schema.Class<GitHubUser, {
+    id: typeof Schema.Number;
+    html_url: typeof Schema.String;
+    login: typeof Schema.String;
+    avatar_url: typeof Schema.String;
+    name: Schema.optional<typeof Schema.String>;
+    blog: Schema.optional<typeof Schema.String>;
+    email: Schema.optional<typeof Schema.String>;
+}, Schema.Struct.Encoded<{
+    id: typeof Schema.Number;
+    html_url: typeof Schema.String;
+    login: typeof Schema.String;
+    avatar_url: typeof Schema.String;
+    name: Schema.optional<typeof Schema.String>;
+    blog: Schema.optional<typeof Schema.String>;
+    email: Schema.optional<typeof Schema.String>;
+}>, never, {
+    readonly id: number;
+} & {
+    readonly html_url: string;
+} & {
+    readonly login: string;
+} & {
+    readonly avatar_url: string;
+} & {
+    readonly name?: string | undefined;
+} & {
+    readonly blog?: string | undefined;
+} & {
+    readonly email?: string | undefined;
+}, {}, {}>;
+/**
+ * Represents a GitHub user profile as returned by the GitHub API.
+ *
+ * @property id - The unique identifier for the user.
+ * @property html_url - The URL to the user's GitHub profile.
+ * @property login - The user's GitHub username.
+ * @property avatar_url - The URL to the user's avatar image.
+ * @property name - The user's display name.
+ * @property blog - The user's blog URL.
+ * @property email - The user's public email address.
+ */
+export declare class GitHubUser extends GitHubUser_base {
+}
+declare const GitHubOAuthAPI_base: Effect.Service.Class<GitHubOAuthAPI, "GitHubOAuthAPI", {
+    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 GitHub OAuth authentication effects for the StudioCMS API.
+ *
+ * This service handles the OAuth flow with GitHub, including:
+ * - Initializing the OAuth session and redirecting users to GitHub for authorization.
+ * - Validating the authorization code returned by GitHub and fetching user data.
+ * - Handling the callback from GitHub, including:
+ *   - Linking OAuth accounts to existing users.
+ *   - Creating new users from GitHub profile data.
+ *   - Verifying user email addresses.
+ *   - Creating user sessions and redirecting to appropriate pages.
+ *
+ * @remarks
+ * - Depends on session management, user library, email verification, and SDK core services.
+ * - Handles both first-time setup and linking additional OAuth providers to existing accounts.
+ *
+ * @example
+ * ```typescript
+ * const githubOAuth = new GitHubOAuthAPI();
+ * yield* githubOAuth.initSession(context);
+ * yield* githubOAuth.initCallback(context);
+ * ```
+ *
+ * @see {@link Session}
+ * @see {@link SDKCore}
+ * @see {@link VerifyEmail}
+ * @see {@link User}
+ */
+export declare class GitHubOAuthAPI extends GitHubOAuthAPI_base {
+    static ProviderID: string;
+    static ProviderCookieName: string;
+}
+export {};

package/dist/effect/github.js

@@ -0,0 +1,152 @@
+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 { GitHub, generateState } from "arctic";
+import { Effect, genLogger, Schema } from "studiocms/effect";
+import { getCookie, getUrlParam, ValidateAuthCodeError } from "studiocms/oAuthUtils";
+class GitHubUser extends Schema.Class("GitHubUser")({
+  id: Schema.Number,
+  html_url: Schema.String,
+  login: Schema.String,
+  avatar_url: Schema.String,
+  name: Schema.optional(Schema.String),
+  blog: Schema.optional(Schema.String),
+  email: Schema.optional(Schema.String)
+}) {
+}
+const GITHUB = {
+  CLIENT_ID: getSecret("GITHUB_CLIENT_ID") ?? "",
+  CLIENT_SECRET: getSecret("GITHUB_CLIENT_SECRET") ?? "",
+  REDIRECT_URI: getSecret("GITHUB_REDIRECT_URI") ?? null
+};
+class GitHubOAuthAPI extends Effect.Service()("GitHubOAuthAPI", {
+  dependencies: [Session.Default, VerifyEmail.Default, User.Default, FetchHttpClient.layer],
+  effect: genLogger("studiocms/routes/api/auth/github/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, REDIRECT_URI } = GITHUB;
+    const github = new GitHub(CLIENT_ID, CLIENT_SECRET, REDIRECT_URI);
+    const validateAuthCode = (code) => genLogger("studiocms/routes/api/auth/github/effect.validateAuthCode")(function* () {
+      const tokens = yield* Effect.tryPromise(() => github.validateAuthorizationCode(code));
+      return yield* fetchClient.get("https://api.github.com/user", {
+        headers: {
+          Authorization: `Bearer ${tokens.accessToken}`
+        }
+      }).pipe(
+        Effect.flatMap(HttpClientResponse.schemaBodyJson(GitHubUser)),
+        Effect.catchAll(
+          (error) => Effect.fail(
+            new ValidateAuthCodeError({
+              provider: GitHubOAuthAPI.ProviderID,
+              message: `Failed to fetch user info: ${error.message}`
+            })
+          )
+        )
+      );
+    });
+    return {
+      initSession: (context) => genLogger("studiocms/routes/api/auth/github/effect.initSession")(function* () {
+        const state = generateState();
+        const scopes = ["user:email", "repo"];
+        const url = github.createAuthorizationURL(state, scopes);
+        yield* setOAuthSessionTokenCookie(context, GitHubOAuthAPI.ProviderCookieName, state);
+        return context.redirect(url.toString());
+      }),
+      initCallback: (context) => genLogger("studiocms/routes/api/auth/github/effect.initCallback")(function* () {
+        const { cookies, redirect } = context;
+        const [code, state, storedState] = yield* Effect.all([
+          getUrlParam(context, "code"),
+          getUrlParam(context, "state"),
+          getCookie(context, GitHubOAuthAPI.ProviderCookieName)
+        ]);
+        if (!code || !state || !storedState || state !== storedState) {
+          return redirect(StudioCMSRoutes.authLinks.loginURL);
+        }
+        const githubUser = yield* validateAuthCode(code);
+        const { id: githubUserId, login: githubUsername } = githubUser;
+        const existingOAuthAccount = yield* sdk.AUTH.oAuth.searchProvidersForId(
+          GitHubOAuthAPI.ProviderID,
+          `${githubUserId}`
+        );
+        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: GitHubOAuthAPI.ProviderID,
+              providerUserId: `${githubUserId}`
+            });
+            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: githubUsername,
+            email: githubUser.email,
+            name: githubUser.name || githubUsername,
+            avatar: githubUser.avatar_url,
+            createdAt: /* @__PURE__ */ new Date(),
+            url: githubUser.blog
+          },
+          { provider: GitHubOAuthAPI.ProviderID, providerUserId: `${githubUserId}` }
+        );
+        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 = "github";
+  static ProviderCookieName = "github_oauth_state";
+}
+export {
+  GitHubOAuthAPI,
+  GitHubUser
+};

package/dist/endpoint.d.ts

@@ -0,0 +1,24 @@
+import type { APIRoute } from 'astro';
+/**
+ * API route handler for initializing a GitHub session.
+ *
+ * This function uses the Effect system to compose asynchronous operations,
+ * retrieving the `initSession` method from the `GitHubOAuthAPI` 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 GitHub OAuth callback endpoint.
+ *
+ * This API route initializes the GitHub OAuth callback process by invoking the `initCallback`
+ * method from the `GitHubOAuthAPI`. It uses the Effect system to manage dependencies and
+ * asynchronous control flow, providing the default implementation of `GitHubOAuthAPI`.
+ *
+ * @param context - The API context containing request and response objects.
+ * @returns A promise resolving to the result of the GitHub OAuth callback process.
+ */
+export declare const initCallback: APIRoute;

package/dist/endpoint.js

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

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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';
+/**
+ * Creates and returns the StudioCMS GitHub plugin configuration.
+ *
+ * This plugin integrates GitHub as an OAuth authentication provider for StudioCMS.
+ * It sets up the necessary authentication service, including the provider's name,
+ * endpoint path, required environment variables, and SVG logo.
+ *
+ * @returns {StudioCMSPlugin} The configured StudioCMS GitHub plugin.
+ *
+ * @example
+ * import { studiocmsGithub } from '@studiocms/github';
+ * const githubPlugin = studiocmsGithub();
+ */
+export declare function studiocmsGithub(): StudioCMSPlugin;
+export default studiocmsGithub;

package/dist/index.js

@@ -0,0 +1,33 @@
+import { createResolver } from "astro-integration-kit";
+import { definePlugin } from "studiocms/plugins";
+function studiocmsGithub() {
+  const { resolve } = createResolver(import.meta.url);
+  const packageIdentifier = "@studiocms/github";
+  return definePlugin({
+    identifier: packageIdentifier,
+    name: "StudioCMS GitHub Plugin",
+    studiocmsMinimumVersion: "0.1.0-beta.22",
+    hooks: {
+      "studiocms:config:setup": ({ setAuthService }) => {
+        setAuthService({
+          oAuthProvider: {
+            name: "github",
+            formattedName: "GitHub",
+            endpointPath: resolve("./endpoint.js"),
+            requiredEnvVariables: [
+              "CMS_GITHUB_CLIENT_ID",
+              "CMS_GITHUB_CLIENT_SECRET",
+              "CMS_GITHUB_REDIRECT_URI"
+            ],
+            svg: '<svg width="24px" height="24px" viewBox="0 0 98 96" xmlns="http://www.w3.org/2000/svg" class="oauth-logo"><path fill-rule="evenodd" clip-rule="evenodd" d="M48.854 0C21.839 0 0 22 0 49.217c0 21.756 13.993 40.172 33.405 46.69 2.427.49 3.316-1.059 3.316-2.362 0-1.141-.08-5.052-.08-9.127-13.59 2.934-16.42-5.867-16.42-5.867-2.184-5.704-5.42-7.17-5.42-7.17-4.448-3.015.324-3.015.324-3.015 4.934.326 7.523 5.052 7.523 5.052 4.367 7.496 11.404 5.378 14.235 4.074.404-3.178 1.699-5.378 3.074-6.6-10.839-1.141-22.243-5.378-22.243-24.283 0-5.378 1.94-9.778 5.014-13.2-.485-1.222-2.184-6.275.486-13.038 0 0 4.125-1.304 13.426 5.052a46.97 46.97 0 0 1 12.214-1.63c4.125 0 8.33.571 12.213 1.63 9.302-6.356 13.427-5.052 13.427-5.052 2.67 6.763.97 11.816.485 13.038 3.155 3.422 5.015 7.822 5.015 13.2 0 18.905-11.404 23.06-22.324 24.283 1.78 1.548 3.316 4.481 3.316 9.126 0 6.6-.08 11.897-.08 13.526 0 1.304.89 2.853 3.316 2.364 19.412-6.52 33.405-24.935 33.405-46.691C97.707 22 75.788 0 48.854 0z" fill="currentColor"/></svg>'
+          }
+        });
+      }
+    }
+  });
+}
+var index_default = studiocmsGithub;
+export {
+  index_default as default,
+  studiocmsGithub
+};

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@studiocms/github",
+  "version": "0.1.0-beta.23",
+  "description": "Add GitHub OAuth Support to your StudioCMS project.",
+  "author": {
+    "name": "withstudiocms",
+    "url": "https://studiocms.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstudiocms/studiocms.git",
+    "directory": "packages/@studiocms/github"
+  },
+  "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"
+  }
+}