@terreno/api 0.0.17 → 0.0.18

package/src/api.ts

@@ -3,7 +3,7 @@
  *
  * @packageDocumentation
  */
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import express, {type NextFunction, type Request, type Response} from "express";
 import cloneDeep from "lodash/cloneDeep";
 import mongoose, {type Document, type Model} from "mongoose";

package/src/errors.ts

@@ -1,5 +1,5 @@
 // https://jsonapi.org/format/#errors
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
 import {Schema} from "mongoose";
 

package/src/expressServer.ts

@@ -1,4 +1,4 @@
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import openapi from "@wesleytodd/openapi";
 import cors from "cors";
 import cron from "cron";
@@ -12,6 +12,7 @@ import qs from "qs";
 import type {ModelRouterOptions} from "./api";
 import {addAuthRoutes, addMeRoutes, setupAuth, type UserModel as UserMongooseModel} from "./auth";
 import {apiErrorMiddleware, apiUnauthorizedMiddleware} from "./errors";
+import {addGitHubAuthRoutes, type GitHubAuthOptions, setupGitHubAuth} from "./githubAuth";
 import {type LoggingOptions, logger, setupLogging} from "./logger";
 import {sendToSlack} from "./notifiers";
 import {openApiEtagMiddleware} from "./openApiEtag";
@@ -168,6 +169,8 @@ interface InitializeRoutesOptions {
   logRequests?: boolean;
   loggingOptions?: LoggingOptions;
   authOptions?: AuthOptions;
+  /** GitHub OAuth configuration. When provided, enables GitHub authentication. */
+  githubAuth?: GitHubAuthOptions;
 }
 
 function initializeRoutes(
@@ -241,6 +244,13 @@ function initializeRoutes(
   }
 
   addMeRoutes(app, UserModel as any, options?.authOptions);
+
+  // Set up GitHub OAuth if configured
+  if (options.githubAuth) {
+    setupGitHubAuth(app, UserModel as any, options.githubAuth);
+    addGitHubAuthRoutes(app, UserModel as any, options.githubAuth, options.authOptions);
+  }
+
   addRoutes(app, {openApi: oapi});
 
   Sentry.setupExpressErrorHandler(app);
@@ -264,6 +274,11 @@ export interface SetupServerOptions {
   addRoutes: AddRoutes;
   loggingOptions?: LoggingOptions;
   authOptions?: AuthOptions;
+  /**
+   * GitHub OAuth configuration. When provided, enables GitHub authentication.
+   * Requires the user schema to have GitHub fields (use githubUserPlugin).
+   */
+  githubAuth?: GitHubAuthOptions;
   skipListen?: boolean;
   corsOrigin?:
     | string
@@ -279,7 +294,7 @@ export interface SetupServerOptions {
       ) => void);
   addMiddleware?: AddRoutes;
   ignoreTraces?: string[];
-  sentryOptions?: Sentry.NodeOptions;
+  sentryOptions?: Sentry.BunOptions;
 }
 
 // Sets up the routes and returns a function to launch the API.
@@ -295,6 +310,7 @@ export function setupServer(options: SetupServerOptions) {
       addMiddleware: options.addMiddleware,
       authOptions: options.authOptions,
       corsOrigin: options.corsOrigin,
+      githubAuth: options.githubAuth,
     });
   } catch (error: any) {
     logger.error(`Error initializing routes: ${error.stack}`);

package/src/githubAuth.test.ts

@@ -0,0 +1,223 @@
+import {afterEach, beforeEach, describe, expect, it, setSystemTime} from "bun:test";
+import type express from "express";
+import mongoose, {model, Schema} from "mongoose";
+import passportLocalMongoose from "passport-local-mongoose";
+import supertest from "supertest";
+import type TestAgent from "supertest/lib/agent";
+
+import {setupServer} from "./expressServer";
+import {type GitHubUserFields, githubUserPlugin} from "./githubAuth";
+import {logger} from "./logger";
+import {createdUpdatedPlugin, isDisabledPlugin} from "./plugins";
+
+interface TestUser extends GitHubUserFields {
+  admin: boolean;
+  name?: string;
+  username: string;
+  email: string;
+  disabled?: boolean;
+}
+
+// Create schema for GitHub-enabled user
+const testUserSchema = new Schema<TestUser>({
+  admin: {default: false, type: Boolean},
+  name: String,
+  username: String,
+});
+
+testUserSchema.plugin(passportLocalMongoose as any, {
+  attemptsField: "attempts",
+  interval: 1,
+  limitAttempts: true,
+  maxAttempts: 3,
+  maxInterval: 1,
+  usernameCaseInsensitive: true,
+  usernameField: "email",
+});
+testUserSchema.plugin(createdUpdatedPlugin);
+testUserSchema.plugin(isDisabledPlugin);
+testUserSchema.plugin(githubUserPlugin);
+
+// Get or create model to avoid model redefinition errors
+const GitHubTestUserModel =
+  mongoose.models.GitHubTestUser || model<TestUser>("GitHubTestUser", testUserSchema);
+
+// Connect to database before tests
+const connectDb = async () => {
+  if (mongoose.connection.readyState === 0) {
+    await mongoose
+      .connect("mongodb://127.0.0.1/terreno?&connectTimeoutMS=360000")
+      .catch(logger.catch);
+  }
+  process.env.REFRESH_TOKEN_SECRET = "refresh_secret";
+  process.env.TOKEN_SECRET = "secret";
+  process.env.TOKEN_EXPIRES_IN = "30m";
+  process.env.TOKEN_ISSUER = "example.com";
+  process.env.SESSION_SECRET = "session";
+};
+
+describe("githubUserPlugin", () => {
+  it("adds GitHub fields to schema", () => {
+    const paths = testUserSchema.paths;
+    expect(paths.githubId).toBeDefined();
+    expect(paths.githubUsername).toBeDefined();
+    expect(paths.githubProfileUrl).toBeDefined();
+    expect(paths.githubAvatarUrl).toBeDefined();
+  });
+
+  it("githubId is indexed and sparse", () => {
+    const githubIdPath = testUserSchema.path("githubId");
+    expect((githubIdPath as any).options.index).toBe(true);
+    expect((githubIdPath as any).options.sparse).toBe(true);
+    expect((githubIdPath as any).options.unique).toBe(true);
+  });
+});
+
+describe("GitHub auth routes", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+
+  beforeEach(async () => {
+    setSystemTime();
+    await connectDb();
+
+    await GitHubTestUserModel.deleteMany({});
+
+    // Create test user with password
+    const testUser = await GitHubTestUserModel.create({
+      admin: false,
+      email: "test@example.com",
+      name: "Test User",
+    });
+    await (testUser as any).setPassword("password123");
+    await testUser.save();
+
+    function addRoutes(router: express.Router): void {
+      router.get("/test", (_req, res) => res.json({ok: true}));
+    }
+
+    app = setupServer({
+      addRoutes,
+      githubAuth: {
+        allowAccountLinking: true,
+        callbackURL: "http://localhost:9000/auth/github/callback",
+        clientId: "test-client-id",
+        clientSecret: "test-client-secret",
+      },
+      skipListen: true,
+      userModel: GitHubTestUserModel as any,
+    });
+    agent = supertest.agent(app);
+  });
+
+  afterEach(async () => {
+    setSystemTime();
+  });
+
+  it("GET /auth/github redirects to GitHub OAuth", async () => {
+    const res = await agent.get("/auth/github").expect(302);
+    expect(res.headers.location).toContain("github.com");
+    expect(res.headers.location).toContain("client_id=test-client-id");
+  });
+
+  it("GET /auth/github/failure returns 401", async () => {
+    const res = await agent.get("/auth/github/failure").expect(401);
+    expect(res.body.message).toBe("GitHub authentication failed");
+  });
+
+  it("DELETE /auth/github/unlink requires authentication", async () => {
+    const res = await agent.delete("/auth/github/unlink").expect(401);
+    expect(res.body).toBeDefined();
+  });
+
+  it("DELETE /auth/github/unlink works when authenticated with password", async () => {
+    // Login as test user
+    const loginRes = await agent
+      .post("/auth/login")
+      .send({email: "test@example.com", password: "password123"})
+      .expect(200);
+
+    // Link github to this user
+    const user = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    if (user) {
+      (user as any).githubId = "99999";
+      (user as any).githubUsername = "testghuser";
+      await user.save();
+    }
+
+    // Unlink
+    const res = await agent
+      .delete("/auth/github/unlink")
+      .set("authorization", `Bearer ${loginRes.body.data.token}`)
+      .expect(200);
+
+    expect(res.body.data.message).toBe("GitHub account unlinked successfully");
+
+    // Verify github fields are cleared
+    const updatedUser = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    expect((updatedUser as any).githubId).toBeUndefined();
+    expect((updatedUser as any).githubUsername).toBeUndefined();
+  });
+
+  it("user can have both password and GitHub auth", async () => {
+    const user = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    expect(user).toBeDefined();
+    if (!user) {
+      return;
+    }
+
+    // Link GitHub
+    (user as any).githubId = "88888";
+    (user as any).githubUsername = "linkeduser";
+    await user.save();
+
+    // Can still login with password
+    const res = await agent
+      .post("/auth/login")
+      .send({email: "test@example.com", password: "password123"})
+      .expect(200);
+
+    expect(res.body.data.token).toBeDefined();
+
+    // User has both auth methods - successful login proves password works
+    // and we verify GitHub fields are set
+    const updatedUser = await GitHubTestUserModel.findOne({email: "test@example.com"});
+    expect(updatedUser).toBeDefined();
+    expect((updatedUser as any).githubId).toBe("88888");
+    expect((updatedUser as any).githubUsername).toBe("linkeduser");
+  });
+});
+
+describe("GitHub auth disabled", () => {
+  let app: express.Application;
+  let agent: TestAgent;
+
+  beforeEach(async () => {
+    setSystemTime();
+    await connectDb();
+
+    await GitHubTestUserModel.deleteMany({});
+
+    function addRoutes(router: express.Router): void {
+      router.get("/test", (_req, res) => res.json({ok: true}));
+    }
+
+    // Setup server WITHOUT GitHub auth
+    app = setupServer({
+      addRoutes,
+      skipListen: true,
+      userModel: GitHubTestUserModel as any,
+    });
+    agent = supertest.agent(app);
+  });
+
+  afterEach(async () => {
+    setSystemTime();
+  });
+
+  it("GitHub routes are not available when githubAuth is not configured", async () => {
+    await agent.get("/auth/github").expect(404);
+    await agent.get("/auth/github/callback").expect(404);
+    await agent.delete("/auth/github/unlink").expect(404);
+  });
+});

package/src/githubAuth.ts

@@ -0,0 +1,335 @@
+import type express from "express";
+import passport from "passport";
+import {Strategy as GitHubStrategy, type Profile} from "passport-github2";
+import {generateTokens, type UserModel} from "./auth";
+import {APIError} from "./errors";
+import type {AuthOptions} from "./expressServer";
+import {logger} from "./logger";
+
+/** Options for configuring GitHub OAuth authentication */
+export interface GitHubAuthOptions {
+  /** GitHub OAuth Client ID */
+  clientId: string;
+  /** GitHub OAuth Client Secret */
+  clientSecret: string;
+  /** Callback URL for GitHub OAuth (e.g., https://yourapp.com/auth/github/callback) */
+  callbackURL: string;
+  /** OAuth scopes to request from GitHub. Defaults to ["user:email"] */
+  scope?: string[];
+  /**
+   * Whether to allow linking GitHub to existing accounts.
+   * If true, authenticated users can link their GitHub account.
+   * Defaults to true.
+   */
+  allowAccountLinking?: boolean;
+  /**
+   * Custom function to handle user creation or lookup from GitHub profile.
+   * If not provided, a default implementation will be used.
+   */
+  findOrCreateUser?: (
+    profile: Profile,
+    accessToken: string,
+    refreshToken: string,
+    existingUser?: any
+  ) => Promise<any>;
+}
+
+/** Fields added to user documents for GitHub authentication */
+export interface GitHubUserFields {
+  /** GitHub user ID */
+  githubId?: string;
+  /** GitHub username */
+  githubUsername?: string;
+  /** GitHub profile URL */
+  githubProfileUrl?: string;
+  /** GitHub avatar URL */
+  githubAvatarUrl?: string;
+}
+
+/**
+ * Plugin to add GitHub authentication fields to a user schema.
+ * Apply this plugin to your User schema if you want to enable GitHub auth.
+ *
+ * @example
+ * ```typescript
+ * import {githubUserPlugin} from "@terreno/api";
+ *
+ * userSchema.plugin(githubUserPlugin);
+ * ```
+ */
+export function githubUserPlugin(schema: any) {
+  schema.add({
+    githubAvatarUrl: {type: String},
+    githubId: {index: true, sparse: true, type: String, unique: true},
+    githubProfileUrl: {type: String},
+    githubUsername: {type: String},
+  });
+}
+
+/**
+ * Sets up GitHub OAuth authentication strategy.
+ * Call this after setupAuth() in your server initialization.
+ */
+export function setupGitHubAuth(
+  _app: express.Application,
+  userModel: UserModel,
+  githubOptions: GitHubAuthOptions
+) {
+  const scope = githubOptions.scope ?? ["user:email"];
+
+  passport.use(
+    "github",
+    new GitHubStrategy(
+      {
+        callbackURL: githubOptions.callbackURL,
+        clientID: githubOptions.clientId,
+        clientSecret: githubOptions.clientSecret,
+        passReqToCallback: true,
+        scope,
+      },
+      async (
+        req: express.Request,
+        accessToken: string,
+        refreshToken: string,
+        profile: Profile,
+        done: (error: any, user?: any) => void
+      ) => {
+        try {
+          const existingUser = req.user;
+
+          // If custom handler provided, use it
+          if (githubOptions.findOrCreateUser) {
+            const user = await githubOptions.findOrCreateUser(
+              profile,
+              accessToken,
+              refreshToken,
+              existingUser
+            );
+            return done(null, user);
+          }
+
+          // Default implementation
+          const githubId = profile.id;
+
+          // Check if user with this GitHub ID already exists
+          const existingGitHubUser = await userModel.findOne({githubId} as any);
+
+          // Case 1: User is authenticated and wants to link GitHub account
+          if (existingUser) {
+            if (!githubOptions.allowAccountLinking) {
+              return done(new APIError({status: 400, title: "Account linking is disabled"}));
+            }
+
+            if (
+              existingGitHubUser &&
+              existingGitHubUser._id.toString() !== existingUser._id.toString()
+            ) {
+              return done(
+                new APIError({
+                  status: 400,
+                  title: "This GitHub account is already linked to another user",
+                })
+              );
+            }
+
+            // Link GitHub to existing user
+            const user = await userModel.findById(existingUser._id);
+            if (user) {
+              (user as any).githubId = githubId;
+              (user as any).githubUsername = profile.username;
+              (user as any).githubProfileUrl = profile.profileUrl;
+              (user as any).githubAvatarUrl = profile.photos?.[0]?.value;
+              await user.save();
+              return done(null, user);
+            }
+            return done(new APIError({status: 404, title: "User not found"}));
+          }
+
+          // Case 2: User with this GitHub ID exists - log them in
+          if (existingGitHubUser) {
+            return done(null, existingGitHubUser);
+          }
+
+          // Case 3: Create new user with GitHub credentials
+          const email = profile.emails?.[0]?.value;
+
+          // Check if user with this email already exists
+          if (email) {
+            const existingEmailUser = await userModel.findOne({email} as any);
+            if (existingEmailUser) {
+              // If account linking is allowed, link GitHub to existing email account
+              if (githubOptions.allowAccountLinking !== false) {
+                (existingEmailUser as any).githubId = githubId;
+                (existingEmailUser as any).githubUsername = profile.username;
+                (existingEmailUser as any).githubProfileUrl = profile.profileUrl;
+                (existingEmailUser as any).githubAvatarUrl = profile.photos?.[0]?.value;
+                await existingEmailUser.save();
+                return done(null, existingEmailUser);
+              }
+              return done(
+                new APIError({
+                  status: 400,
+                  title:
+                    "An account with this email already exists. Please log in and link your GitHub account.",
+                })
+              );
+            }
+          }
+
+          // Create new user
+          const newUser = new userModel({
+            admin: false,
+            email,
+            githubAvatarUrl: profile.photos?.[0]?.value,
+            githubId,
+            githubProfileUrl: profile.profileUrl,
+            githubUsername: profile.username,
+          } as any);
+
+          await newUser.save();
+          return done(null, newUser);
+        } catch (error) {
+          logger.error(`GitHub auth error: ${error}`);
+          return done(error);
+        }
+      }
+    ) as passport.Strategy
+  );
+}
+
+/**
+ * Adds GitHub OAuth routes to the Express application.
+ *
+ * Routes added:
+ * - GET /auth/github - Initiates GitHub OAuth flow
+ * - GET /auth/github/callback - Handles GitHub OAuth callback
+ * - POST /auth/github/link - Links GitHub account to authenticated user (requires JWT auth)
+ * - DELETE /auth/github/unlink - Unlinks GitHub account from authenticated user (requires JWT auth)
+ */
+export function addGitHubAuthRoutes(
+  app: express.Application,
+  userModel: UserModel,
+  githubOptions: GitHubAuthOptions,
+  authOptions?: AuthOptions
+): void {
+  const router = require("express").Router();
+
+  // Initiate GitHub OAuth flow
+  router.get(
+    "/github",
+    (req: express.Request, _res: express.Response, next: express.NextFunction) => {
+      // Store the return URL in session or query for redirect after auth
+      const returnTo = req.query.returnTo as string | undefined;
+      if (returnTo) {
+        (req as any).session = (req as any).session || {};
+        (req as any).session.returnTo = returnTo;
+      }
+      next();
+    },
+    passport.authenticate("github", {session: false})
+  );
+
+  // GitHub OAuth callback
+  router.get(
+    "/github/callback",
+    passport.authenticate("github", {
+      failureRedirect: "/auth/github/failure",
+      session: false,
+    }),
+    async (req: express.Request, res: express.Response) => {
+      try {
+        const tokens = await generateTokens(req.user, authOptions);
+        const returnTo = (req as any).session?.returnTo;
+
+        // If there's a return URL, redirect with tokens as query params
+        if (returnTo) {
+          const url = new URL(returnTo);
+          url.searchParams.set("token", tokens.token || "");
+          if (tokens.refreshToken) {
+            url.searchParams.set("refreshToken", tokens.refreshToken);
+          }
+          url.searchParams.set("userId", (req.user as any)?._id?.toString() || "");
+          return res.redirect(url.toString());
+        }
+
+        // Otherwise return JSON response
+        return res.json({
+          data: {
+            refreshToken: tokens.refreshToken,
+            token: tokens.token,
+            userId: (req.user as any)?._id,
+          },
+        });
+      } catch (error) {
+        logger.error(`GitHub callback error: ${error}`);
+        return res.status(500).json({message: "Authentication failed"});
+      }
+    }
+  );
+
+  // GitHub auth failure handler
+  router.get("/github/failure", (_req: express.Request, res: express.Response) => {
+    return res.status(401).json({message: "GitHub authentication failed"});
+  });
+
+  // Link GitHub to existing authenticated user
+  if (githubOptions.allowAccountLinking !== false) {
+    router.get(
+      "/github/link",
+      (req: express.Request, res: express.Response, next: express.NextFunction): void => {
+        // Require JWT authentication for linking
+        passport.authenticate("jwt", {session: false}, (err: any, user: any) => {
+          if (err || !user) {
+            res.status(401).json({message: "Authentication required to link GitHub account"});
+            return;
+          }
+          req.user = user;
+          next();
+        })(req, res, next);
+      },
+      passport.authenticate("github", {session: false})
+    );
+
+    // Unlink GitHub from user account
+    router.delete(
+      "/github/unlink",
+      passport.authenticate("jwt", {session: false}),
+      async (req: express.Request, res: express.Response) => {
+        if (!req.user) {
+          return res.status(401).json({message: "Authentication required"});
+        }
+
+        try {
+          // Explicitly select hash and salt fields which may be hidden by default
+          const user = await userModel.findById((req.user as any)._id).select("+hash +salt");
+          if (!user) {
+            return res.status(404).json({message: "User not found"});
+          }
+
+          // Check if user has other authentication methods before unlinking
+          // passport-local-mongoose stores password in hash and salt fields
+          const hasPassword = !!(user as any).hash || !!(user as any).salt;
+          if (!hasPassword) {
+            return res.status(400).json({
+              message:
+                "Cannot unlink GitHub account without another authentication method. Set a password first.",
+            });
+          }
+
+          (user as any).githubId = undefined;
+          (user as any).githubUsername = undefined;
+          (user as any).githubProfileUrl = undefined;
+          (user as any).githubAvatarUrl = undefined;
+          await user.save();
+
+          return res.json({data: {message: "GitHub account unlinked successfully"}});
+        } catch (error) {
+          logger.error(`GitHub unlink error: ${error}`);
+          return res.status(500).json({message: "Failed to unlink GitHub account"});
+        }
+      }
+    );
+  }
+
+  app.use("/auth", router);
+}

package/src/index.ts

@@ -2,6 +2,7 @@ export * from "./api";
 export * from "./auth";
 export * from "./errors";
 export * from "./expressServer";
+export * from "./githubAuth";
 export * from "./logger";
 export * from "./middleware";
 export * from "./notifiers";

package/src/logger.ts

@@ -1,6 +1,6 @@
 import fs from "node:fs";
 import {inspect} from "node:util";
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import winston from "winston";
 
 function isPrimitive(val: any) {

package/src/middleware.ts

@@ -1,4 +1,4 @@
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import type {NextFunction, Request, Response} from "express";
 
 /**

package/src/notifiers/googleChatNotifier.test.ts

@@ -1,5 +1,5 @@
 import {afterAll, afterEach, beforeEach, describe, expect, it, type Mock, spyOn} from "bun:test";
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import axios from "axios";
 
 import {sendToGoogleChat} from "./googleChatNotifier";

package/src/notifiers/googleChatNotifier.ts

@@ -1,4 +1,4 @@
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import axios from "axios";
 
 import {APIError} from "../errors";

package/src/notifiers/slackNotifier.test.ts

@@ -1,5 +1,5 @@
 import {afterAll, afterEach, beforeEach, describe, expect, it, type Mock, spyOn} from "bun:test";
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import axios from "axios";
 
 import {sendToSlack} from "./slackNotifier";

package/src/notifiers/slackNotifier.ts

@@ -1,4 +1,4 @@
-import * as Sentry from "@sentry/node";
+import * as Sentry from "@sentry/bun";
 import axios from "axios";
 
 import {APIError} from "../errors";