Added tests, better workflows and some better contributing guidelines

Author: PixNyb

Diff for: .github/workflows/deploy.yml

@@ -49,9 +49,29 @@ jobs:
             fi
           fi
 
+  lint:
+    runs-on: self-hosted
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run eslint
+        run: npm run lint
+
+  test:
+    runs-on: self-hosted
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Run tests
+        run: npm run test
+
   build-and-push:
     runs-on: self-hosted
-    needs: setup
+    needs: [setup, lint, test]
 
     steps:
       - name: Set up Docker Buildx

Diff for: CONTRIBUTING.md

@@ -5,3 +5,14 @@ Contributions are welcome! In order to get started, please fork the repository a
 ## Local Development
 
 To get started with local development, the [Docker Compose](/docs/compose.md) example is a good place to start. This will allow you to run the authentication proxy locally and test your changes.
+
+## Provider Development
+
+In order to add a new provider, simply create a new file in the `src/providers/` directory. This file should contain an implementation using a [Passport.js](http://www.passportjs.org/) strategy. New providers will automatically be discovered. Look at the existing providers for examples.
+
+Implementations without a corresponding Passport.js strategy may be possible, but is not tested or supported.
+
+Be sure to include unit tests for your provider. These tests should be placed in the `__test__/providers/` directory. Look at the existing tests for examples.
+
+> [!NOTE]
+> All provider configuration should be able to be set via environment variables. This allows the application to remain stateless and easily scalable. For some providers, a configuration file may be required. In this case, the volume should be mounted to the container and the path should be able to be set via an environment variable. (defaulting to `/etc/auth/<filename>`)

Diff for: README.md

@@ -55,8 +55,10 @@ As mentioned above, there are a few environment variables that can be used to co
 | SESSION_SECRET            | The secret used to sign the session cookie                                                            |                  |
 | ACCESS_TOKEN_NAME         | The name of the access token cookie                                                                   | `_access_token`  |
 | ACCESS_TOKEN_SECRET       | The secret used to sign the access token cookie                                                       | `secret`         |
+| ACCESS_TOKEN_EXPIRATION   | The expiration time for the access token cookie                                                       | `15m`             |
 | REFRESH_TOKEN_NAME        | The name of the refresh token cookie                                                                  | `_refresh_token` |
 | REFRESH_TOKEN_SECRET      | The secret used to sign the refresh token cookie                                                      | `refresh`        |
+| REFRESH_TOKEN_EXPIRATION  | The expiration time for the refresh token cookie                                                      | `7d`             |
 | COOKIE_SECURE             | Whether the cookies should be secure or not                                                           | `true`           |
 | COOKIE_HOSTS              | A list of hosts that the authentication proxy is available on                                         | `localhost`      |
 | COOKIE_HOSTS_USE_ROOT     | Whether the base domain should be used as the cookie domain                                           | `false`          |
@@ -68,6 +70,9 @@ As mentioned above, there are a few environment variables that can be used to co
 | FORM_DISABLE_CREDITS      | Whether the credits should be disabled or not                                                         | `false`          |
 | PROMETHEUS_PREFIX         | The prefix for the Prometheus metrics endpoint. Since this route is not secured, it should be random  |                  |
 
+> [!NOTE]
+> The `(ACCESS|REFRESH)_TOKEN_EXPIRATION` variables should be in the format `<duration><unit>`, where `<duration>` is a number and `<unit>` is one of `s`, `m`, `h`, `d`.
+
 > [!NOTE]
 > The `LONG_LIVED_TOKENS` variable should be in the format `name:token,name:token`. These tokens can be found after logging in to the auth service and visiting the `AUTH_HOST`.
 > ![LONG_LIVED_TOKENS](docs/images/long-lived-tokens.png)

Diff for: __tests__/app.test.js

@@ -0,0 +1,28 @@
+// tests/app.test.js
+const request = require("supertest");
+const jwt = require("jsonwebtoken");
+const { app, server } = require("../app");
+
+jest.mock("jsonwebtoken");
+
+describe("Authentication Proxy Tests", () => {
+  describe("Application Routes", () => {
+    it("should return OK for the health check route", async () => {
+      const response = await request(app).get("/healthz");
+      expect(response.statusCode).toBe(200);
+      expect(response.text).toBe("OK");
+    });
+
+    it("should redirect unauthenticated users to login", async () => {
+      jwt.verify.mockImplementation(() => {
+        throw new Error("Invalid token");
+      });
+      const response = await request(app).get("/");
+      expect(response.statusCode).toBe(302);
+    });
+  });
+});
+
+afterAll(() => {
+  server.close();
+});

Diff for: __tests__/providers/apple.test.js

@@ -0,0 +1,55 @@
+const { server } = require("../../app");
+
+jest.mock("jsonwebtoken", () => ({
+  decode: jest.fn().mockReturnValue({
+    sub: "apple123",
+    email: "[email protected]",
+  }),
+}));
+
+describe("Apple Authentication Strategy", () => {
+  // Mock environment variables
+  process.env.APPLE_TEST_CLIENT_ID = "test-client-id";
+  process.env.APPLE_TEST_TEAM_ID = "test-team-id";
+  process.env.APPLE_TEST_KEY_ID = "test-key-id";
+  process.env.APPLE_TEST_PRIVATE_KEY_LOCATION = "/path/to/key";
+  process.env.APPLE_TEST_DOMAIN_WHITELIST = "example.com";
+  process.env.APPLE_TEST_USER_WHITELIST = "[email protected]";
+  process.env.APPLE_TEST_DISPLAY_NAME = "Test Apple";
+  process.env.APPLE_TEST_ICON = "test-icon";
+  const appleProvider = require("../../src/providers/apple");
+
+  it("should correctly configure the Apple strategy", () => {
+    const provider = appleProvider("test", "TEST");
+
+    expect(provider.name).toBe("apple_test");
+    expect(provider.type).toBe("apple");
+    expect(provider.params.clientID).toBe("test-client-id");
+    expect(provider.params.teamID).toBe("test-team-id");
+    expect(provider.params.keyID).toBe("test-key-id");
+    expect(provider.params.privateKeyLocation).toBe("/path/to/key");
+    expect(provider.params.loginURL).toBe("/_apple/test");
+    expect(provider.params.callbackURL).toBe("/_apple/test/callback");
+  });
+
+  it("should correctly process idToken in verify callback", (done) => {
+    const provider = appleProvider("test", "TEST");
+    const mockIdToken = "mockIdToken";
+    provider.verify({}, null, null, mockIdToken, {}, (err, user) => {
+      expect(err).toBeNull();
+      expect(user).toEqual({
+        id: "[email protected]",
+        strategy: "apple_test",
+        profile: {
+          appleId: "apple123",
+          email: "[email protected]",
+        },
+      });
+      done();
+    });
+  });
+});
+
+afterAll(() => {
+  server.close();
+});

Diff for: __tests__/providers/google.test.js

@@ -0,0 +1,54 @@
+const { server } = require("../../app");
+
+jest.mock("jsonwebtoken");
+
+describe("Google Authentication Strategy", () => {
+  // Mock environment variables
+  process.env.GOOGLE_TEST_CLIENT_ID = "test-client-id";
+  process.env.GOOGLE_TEST_CLIENT_SECRET = "test-client-secret";
+  process.env.GOOGLE_TEST_SCOPE = "profile email";
+  process.env.GOOGLE_TEST_DOMAIN_WHITELIST = "example.com";
+  process.env.GOOGLE_TEST_USER_WHITELIST = "[email protected]";
+  process.env.GOOGLE_TEST_DISPLAY_NAME = "Test Google";
+  process.env.GOOGLE_TEST_ICON = "test-icon";
+  const googleProvider = require("../../src/providers/google");
+
+  it("should correctly configure the Google strategy", () => {
+    const provider = googleProvider("test", "TEST");
+
+    expect(provider.name).toBe("google_test");
+    expect(provider.type).toBe("google");
+    expect(provider.params.clientID).toBe("test-client-id");
+    expect(provider.params.clientSecret).toBe("test-client-secret");
+    expect(provider.params.loginURL).toBe("/_google/test");
+    expect(provider.params.callbackURL).toBe("/_google/test/callback");
+  });
+
+  it("should correctly process user profile in verify callback", (done) => {
+    const provider = googleProvider("test", "TEST");
+
+    const mockProfile = {
+      id: "google123",
+      displayName: "Test User",
+      emails: [{ value: "[email protected]" }],
+    };
+
+    provider.verify(null, null, mockProfile, (err, user) => {
+      expect(err).toBeNull();
+      expect(user).toEqual({
+        id: "[email protected]",
+        strategy: "google_test",
+        profile: {
+          googleId: "google123",
+          displayName: "Test User",
+          email: "[email protected]",
+        },
+      });
+      done();
+    });
+  });
+});
+
+afterAll(() => {
+  server.close();
+});

Diff for: __tests__/providers/local.test.js

@@ -0,0 +1,31 @@
+const { server } = require("../../app");
+
+jest.mock("jsonwebtoken");
+
+describe("Local Authentication Strategy", () => {
+  // Mock environment variables
+  process.env.LOCAL_TEST_USERS = "user:$apr1$PJ3UdeuW$sdScbEB7d/HK0mFIx/oN1.";
+  const localProvider = require("../../src/providers/local");
+
+  it("should authenticate a user with correct credentials", (done) => {
+    const verifyCallback = localProvider("test", "TEST").verify;
+    verifyCallback("user", "password", (err, user) => {
+      expect(err).toBeNull();
+      expect(user).toBeTruthy();
+      done();
+    });
+  });
+
+  it("should reject a user with incorrect credentials", (done) => {
+    const verifyCallback = localProvider("test", "TEST").verify;
+    verifyCallback("testuser", "wrongpassword", (err, user) => {
+      expect(err).toBeNull();
+      expect(user).toBeFalsy();
+      done();
+    });
+  });
+});
+
+afterAll(() => {
+  server.close();
+});

Diff for: __tests__/providers/oauth2.test.js

@@ -0,0 +1,47 @@
+const { server } = require("../../app");
+
+jest.mock("jsonwebtoken");
+jest.mock("request");
+
+describe("OAuth2 Authentication Strategy", () => {
+  // Mock environment variables
+  process.env.OAUTH2_TEST_AUTH_URL = "https://example.com/auth";
+  process.env.OAUTH2_TEST_TOKEN_URL = "https://example.com/token";
+  process.env.OAUTH2_TEST_CLIENT_ID = "test-client-id";
+  process.env.OAUTH2_TEST_CLIENT_SECRET = "test-client-secret";
+  process.env.OAUTH2_TEST_DOMAIN_WHITELIST = "example.com";
+  process.env.OAUTH2_TEST_USER_WHITELIST = "[email protected]";
+  process.env.OAUTH2_TEST_DISPLAY_NAME = "Test OAuth2";
+  process.env.OAUTH2_TEST_ICON = "test-icon";
+  const oauth2Provider = require("../../src/providers/oauth2");
+
+  it("should correctly configure the OAuth2 strategy", () => {
+    const provider = oauth2Provider("test", "TEST");
+
+    expect(provider.name).toBe("oauth2_test");
+    expect(provider.type).toBe("oauth2");
+    expect(provider.params.clientID).toBe("test-client-id");
+    expect(provider.params.clientSecret).toBe("test-client-secret");
+    expect(provider.params.loginURL).toBe("/_oauth2/test");
+    expect(provider.params.callbackURL).toBe("/_oauth2/test/callback");
+  });
+
+  it("should correctly process user profile in verify callback", (done) => {
+    const provider = oauth2Provider("test", "TEST");
+    const mockProfile = { id: "[email protected]", displayName: "Test User" };
+
+    provider.verify(null, null, mockProfile, (error, user) => {
+      expect(error).toBeNull();
+      expect(user).toEqual({
+        id: mockProfile.id,
+        strategy: "oauth2_test",
+        profile: mockProfile,
+      });
+      done();
+    });
+  });
+});
+
+afterAll(() => {
+  server.close();
+});

Diff for: __tests__/providers/oidc.test.js

@@ -0,0 +1,58 @@
+const { server } = require("../../app");
+
+jest.mock("jsonwebtoken");
+
+describe("OAuth2 Authentication Strategy", () => {
+  // Mock environment variables
+  process.env.OIDC_TEST_ISSUER = "https://example.com";
+  process.env.OIDC_TEST_AUTH_URL = "https://example.com/auth";
+  process.env.OIDC_TEST_TOKEN_URL = "https://example.com/token";
+  process.env.OIDC_TEST_USER_URL = "https://example.com/userinfo";
+  process.env.OIDC_TEST_CLIENT_ID = "test-client-id";
+  process.env.OIDC_TEST_CLIENT_SECRET = "test-client-secret";
+  process.env.OIDC_TEST_DOMAIN_WHITELIST = "example.com";
+  process.env.OIDC_TEST_USER_WHITELIST = "[email protected]";
+  process.env.OIDC_TEST_DISPLAY_NAME = "Test OIDC";
+  process.env.OIDC_TEST_ICON = "fas fa-test";
+  const oidcProvider = require("../../src/providers/oidc");
+
+  it("should correctly configure the OIDC strategy", () => {
+    const provider = oidcProvider("test", "TEST");
+
+    expect(provider.name).toBe("oidc_test");
+    expect(provider.type).toBe("oidc");
+    expect(provider.params.clientID).toBe("test-client-id");
+    expect(provider.params.clientSecret).toBe("test-client-secret");
+    expect(provider.params.loginURL).toBe("/_oidc/test");
+    expect(provider.params.callbackURL).toBe("/_oidc/test/callback");
+  });
+
+  it("should correctly process user profile in verify callback", (done) => {
+    const provider = oidcProvider("test", "TEST");
+    const mockProfile = {
+      id: "oidc123",
+      displayName: "Test User",
+      emails: [{ value: "[email protected]" }],
+      photos: [{ value: "http://example.com/photo.jpg" }],
+    };
+
+    provider.verify(null, "oidc123", mockProfile, null, null, (err, user) => {
+      expect(err).toBeNull();
+      expect(user).toEqual({
+        id: "[email protected]",
+        strategy: "oidc_test",
+        profile: {
+          oidcId: "oidc123",
+          displayName: "Test User",
+          email: "[email protected]",
+          photo: "http://example.com/photo.jpg",
+        },
+      });
+      done();
+    });
+  });
+});
+
+afterAll(() => {
+  server.close();
+});