Add programmatic configuration API (#43)

* add configure configuration

* replace env-variables with config

* improve DX around getConfig, add defaults and required fields checking

* updating types for config values

* add getWorkOS to the export, exposing it to end users

* fixing tests

* fixing the rest of the tests

* add additional test

* README updates

* add warning about non-node runtimes

* add getFullConfig function and expose to end users

* add note about getFullConfig to the README

* lint fixes

* remove getFullConfig function

* export the `createWorkOSInstance` function to make it easier to work/test with internally

* wrap config in a class and manage a lazily-instantiated singleton of it

Author: nicknisi

README.md

@@ -16,36 +16,89 @@ or
 yarn add @workos-inc/authkit-remix
 ```
 
-## Pre-flight
+## Configuration
 
-Make sure the following values are present in your `.env.local` environment variables file. The client ID and API key can be found in the [WorkOS dashboard](https://dashboard.workos.com), and the redirect URI can also be configured there.
+AuthKit for Remix offers a flexible configuration system that allows you to customize various settings. You can configure the library in three ways:
 
-```sh
-WORKOS_CLIENT_ID="client_..." # retrieved from the WorkOS dashboard
-WORKOS_API_KEY="sk_test_..." # retrieved from the WorkOS dashboard
-WORKOS_REDIRECT_URI="http://localhost:5173/callback" # configured in the WorkOS dashboard
-WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
-```
+### 1. Environment Variables
 
-`WORKOS_COOKIE_PASSWORD` is the private key used to encrypt the session cookie. It has to be at least 32 characters long. You can use the [1Password generator](https://1password.com/password-generator/) or the `openssl` library to generate a strong password via the command line:
+  The simplest way is to set environment variables in your `.env.local` file:
 
+  ```bash
+  WORKOS_CLIENT_ID="client_..." # retrieved from the WorkOS dashboard
+  WORKOS_API_KEY="sk_test_..." # retrieved from the WorkOS dashboard
+  WORKOS_REDIRECT_URI="http://localhost:5173/callback" # configured in the WorkOS dashboard
+  WORKOS_COOKIE_PASSWORD="<your password>" # generate a secure password here
 ```
-openssl rand -base64 24
+
+### 2. Programmatic Configuration
+
+You can also configure AuthKit programmatically by importing the `configure` function:
+
+```typescript
+import { configure } from '@workos-inc/authkit-remix';
+// In your root or entry file
+configure({
+  clientId: 'client_1234567890',
+  apiKey: 'sk_test_1234567890',
+  redirectUri: 'http://localhost:5173/callback',
+  cookiePassword: 'your-secure-cookie-password',
+  // Optional settings
+  cookieName: 'my-custom-cookie-name',
+  apiHttps: true,
+  cookieMaxAge: 60 * 60 * 24 * 30, // 30 days
+});
 ```
 
-To use the `signOut` method, you'll need to set your app's homepage in your WorkOS dashboard settings under "Redirects".
+### 3. Custom Environment Source
 
-### Optional configuration
+For non-standard environments (like Deno or Edge functions), you can provide a custom environment variable source:
 
-Certain environment variables are optional and can be used to debug or configure cookie settings.
+> [!Warning]
+>
+>While this library includes support for custom environment sources that could theoretically work in non-Node.js runtimes like Deno or Edge functions, this functionality has not been extensively tested (yet). If you're planning to use AuthKit in these environments, you may encounter unexpected issues. We welcome feedback and contributions from users who test in these environments.
 
-```sh
-WORKOS_COOKIE_MAX_AGE='600' # maximum age of the cookie in seconds. Defaults to 400 days
-WORKOS_API_HOSTNAME='api.workos.com' # base WorkOS API URL
-WORKOS_API_HTTPS=true # whether to use HTTPS in API calls
-WORKOS_API_PORT=5173 # port to use for API calls
+```typescript
+import { configure } from '@workos-inc/authkit-remix';
+
+configure(key => Deno.env.get(key));
+// Or combine with explicit values
+configure(
+  { clientId: 'client_1234567890' },
+  key => Deno.env.get(key)
+);
 ```
 
+### Configuration Priority
+
+When retrieving configuration values, AuthKit follows this priority order:
+
+1. Programmatically provided values via `configure()`
+2. Environment variables (prefixed with `WORKOS_`)
+3. Default values for optional settings
+
+### Available Configuration Options
+
+>[!NOTE]
+>
+>To print out the entire config, a `getFullConfig` function is provided for debugging purposes.
+
+|  Option |  Environment Variable |  Default |  Required |  Description |  
+| ---- | ---- | ---- | ---- | ----  |
+|  `clientId` |  `WORKOS_CLIENT_ID` |  - |  Yes |  Your WorkOS Client ID |  
+|  `apiKey` |  `WORKOS_API_KEY` |  - |  Yes |  Your WorkOS API Key |  
+|  `redirectUri` |  `WORKOS_REDIRECT_URI` |  - |  Yes |  The callback URL configured in WorkOS |  
+|  `cookiePassword` |  `WORKOS_COOKIE_PASSWORD` |  - |  Yes |  Password for cookie encryption (min 32 chars) |  
+|  `cookieName` |  `WORKOS_COOKIE_NAME` |  `wos-session` |  No |  Name of the session cookie |  
+|  `apiHttps` |  `WORKOS_API_HTTPS` |  `true` |  No |  Whether to use HTTPS for API calls |  
+|  `cookieMaxAge` |  `WORKOS_COOKIE_MAX_AGE` |  `34560000` (400 days) |  No |  Maximum age of cookie in seconds |  
+|  `apiHostname` |  `WORKOS_API_HOSTNAME` |  `api.workos.com` |  No |  WorkOS API hostname |  
+|  `apiPort` |  `WORKOS_API_PORT` |  - |  No |  Port to use for API calls | 
+
+>[!NOTE]
+>
+>The `cookiePassword` must be at least 32 characters long for security reasons.
+
 ## Setup
 
 ### Callback route

jest.setup.ts

@@ -3,6 +3,5 @@ process.env.WORKOS_CLIENT_ID = 'client_1234567890';
 process.env.WORKOS_COOKIE_PASSWORD = 'kR620keEzOIzPThfnMEAba8XYgKdQ5vg';
 process.env.WORKOS_REDIRECT_URI = 'http://localhost:5173/callback';
 process.env.WORKOS_COOKIE_DOMAIN = 'example.com';
-process.env.WORKOS_API_HOSTNAME = 'api.workos.com';
 
 export {};

src/authkit-callback-route.spec.ts

@@ -1,5 +1,5 @@
 import type { LoaderFunction } from '@remix-run/node';
-import { workos as workosInstance } from '../src/workos.js';
+import { getWorkOS } from './workos.js';
 import { authLoader } from './authkit-callback-route.js';
 import {
   createRequestWithSearchParams,
@@ -9,19 +9,22 @@ import {
 import { configureSessionStorage } from './sessionStorage.js';
 
 // Mock dependencies
-jest.mock('../src/workos.js', () => ({
-  workos: {
-    userManagement: {
-      authenticateWithCode: jest.fn(),
-      getJwksUrl: jest.fn(() => 'https://api.workos.com/sso/jwks/client_1234567890'),
-    },
+const fakeWorkosInstance = {
+  userManagement: {
+    authenticateWithCode: jest.fn(),
+    getJwksUrl: jest.fn(() => 'https://api.workos.com/sso/jwks/client_1234567890'),
   },
+};
+
+jest.mock('./workos.js', () => ({
+  getWorkOS: jest.fn(() => fakeWorkosInstance),
 }));
 
 describe('authLoader', () => {
   let loader: LoaderFunction;
   let request: Request;
-  const workos = jest.mocked(workosInstance);
+  const workos = getWorkOS();
+  const authenticateWithCode = jest.mocked(workos.userManagement.authenticateWithCode);
 
   beforeAll(() => {
     // Silence console.error during tests
@@ -30,10 +33,8 @@ describe('authLoader', () => {
   });
 
   beforeEach(async () => {
-    jest.resetAllMocks();
-
     const mockAuthResponse = createAuthWithCodeResponse();
-    workos.userManagement.authenticateWithCode.mockResolvedValue(mockAuthResponse);
+    authenticateWithCode.mockResolvedValue(mockAuthResponse);
 
     loader = authLoader();
     const url = new URL('http://example.com/callback');
@@ -55,15 +56,15 @@ describe('authLoader', () => {
     });
 
     it('should handle authentication failure', async () => {
-      workos.userManagement.authenticateWithCode.mockRejectedValue(new Error('Auth failed'));
+      authenticateWithCode.mockRejectedValue(new Error('Auth failed'));
       request = createRequestWithSearchParams(request, { code: 'invalid-code' });
       const response = (await loader({ request, params: {}, context: {} })) as Response;
 
       expect(response.status).toBe(500);
     });
 
     it('should handle authentication failure with string error', async () => {
-      workos.userManagement.authenticateWithCode.mockRejectedValue('Auth failed');
+      authenticateWithCode.mockRejectedValue('Auth failed');
       request = createRequestWithSearchParams(request, { code: 'invalid-code' });
       const response = (await loader({ request, params: {}, context: {} })) as Response;
 
@@ -141,7 +142,7 @@ describe('authLoader', () => {
 
   it('provides impersonator to onSuccess callback when provided', async () => {
     const onSuccess = jest.fn();
-    workos.userManagement.authenticateWithCode.mockResolvedValue(
+    authenticateWithCode.mockResolvedValue(
       createAuthWithCodeResponse({
         impersonator: {
           email: '[email protected]',
@@ -162,7 +163,7 @@ describe('authLoader', () => {
 
   it('provides oauthTokens to onSuccess callback when provided', async () => {
     const onSuccess = jest.fn();
-    workos.userManagement.authenticateWithCode.mockResolvedValue(
+    authenticateWithCode.mockResolvedValue(
       createAuthWithCodeResponse({
         oauthTokens: {
           accessToken: 'access123',

src/authkit-callback-route.ts

@@ -1,9 +1,9 @@
+import { LoaderFunctionArgs, json, redirect } from '@remix-run/node';
+import { getConfig } from './config.js';
 import { HandleAuthOptions } from './interfaces.js';
-import { WORKOS_CLIENT_ID } from './env-variables.js';
-import { workos } from './workos.js';
 import { encryptSession } from './session.js';
 import { getSessionStorage } from './sessionStorage.js';
-import { redirect, json, LoaderFunctionArgs } from '@remix-run/node';
+import { getWorkOS } from './workos.js';
 
 export function authLoader(options: HandleAuthOptions = {}) {
   return async function loader({ request }: LoaderFunctionArgs) {
@@ -19,8 +19,8 @@ export function authLoader(options: HandleAuthOptions = {}) {
     if (code) {
       try {
         const { accessToken, refreshToken, user, impersonator, oauthTokens } =
-          await workos.userManagement.authenticateWithCode({
-            clientId: WORKOS_CLIENT_ID,
+          await getWorkOS().userManagement.authenticateWithCode({
+            clientId: getConfig('clientId'),
             code,
           });
 

src/config.spec.ts

@@ -0,0 +1,124 @@
+import type { configure as ConfigureType, getConfig as GetConfigType } from './config.js';
+import { AuthKitConfig } from './interfaces.js';
+
+describe('config', () => {
+  let configure: typeof ConfigureType;
+  let getConfig: typeof GetConfigType;
+
+  beforeEach(() => {
+    jest.resetModules();
+    ({ configure, getConfig } = require('./config.js'));
+  });
+
+  it('reads values from process.env with no configure call', () => {
+    expect(getConfig('clientId')).toBe(process.env.WORKOS_CLIENT_ID);
+    expect(getConfig('apiKey')).toBe(process.env.WORKOS_API_KEY);
+  });
+
+  it('reads values from the provided config', () => {
+    configure({
+      clientId: 'client_1234567890',
+      apiKey: 'sk_test_1234567890',
+    });
+
+    expect(getConfig('clientId')).toBe('client_1234567890');
+    expect(getConfig('apiKey')).toBe('sk_test_1234567890');
+  });
+
+  it('reads env variables from the provided config', () => {
+    configure(
+      {},
+      {
+        WORKOS_CLIENT_ID: 'client_123456789',
+        WORKOS_API_KEY: 'sk_test_123456789',
+      },
+    );
+
+    expect(getConfig('clientId')).toBe('client_123456789');
+    expect(getConfig('apiKey')).toBe('sk_test_123456789');
+  });
+
+  it('reads values from the provided config', () => {
+    configure({
+      clientId: 'client_1234567890',
+    });
+
+    expect(getConfig('clientId')).toBe('client_1234567890');
+    expect(getConfig('apiKey')).toBe(process.env.WORKOS_API_KEY);
+  });
+
+  it('reads values from the provided source', () => {
+    configure((key) => {
+      if (key === 'WORKOS_CLIENT_ID') {
+        return 'client_1234567890';
+      } else if (key === 'WORKOS_API_KEY') {
+        return 'sk_test_1234567890';
+      }
+
+      return undefined;
+    });
+
+    expect(getConfig('clientId')).toBe('client_1234567890');
+    expect(getConfig('apiKey')).toBe('sk_test_1234567890');
+  });
+
+  it('reads from provided config, falling back to provided source', () => {
+    configure(
+      {
+        clientId: 'overridden client id',
+        redirectUri: 'http://localhost:5173/callback',
+        cookiePassword: 'a really long cookie password that is definitely more than 32 characters',
+      },
+      (key) => {
+        if (key === 'WORKOS_API_KEY') {
+          return 'overridden api key';
+        }
+      },
+    );
+
+    expect(getConfig('clientId')).toBe('overridden client id');
+    expect(getConfig('apiKey')).toBe('overridden api key');
+  });
+
+  it('reads from defaults when no values are provided', () => {
+    configure(() => undefined);
+
+    expect(getConfig('apiHttps')).toBe(true);
+    expect(getConfig('apiHostname')).toBe('api.workos.com');
+  });
+
+  it('returns undefined for unknown values', () => {
+    expect(getConfig('unknown' as keyof AuthKitConfig)).toBeUndefined();
+  });
+
+  it('converts strings to appropriate types', () => {
+    configure((key) => {
+      switch (key) {
+        case 'WORKOS_API_PORT':
+          return '3000';
+        case 'WORKOS_COOKIE_MAX_AGE':
+          return '3600';
+        case 'WORKOS_API_HTTPS':
+          return 'true';
+        default:
+          return undefined;
+      }
+    });
+    expect(typeof getConfig('apiPort')).toBe('number');
+    expect(typeof getConfig('cookieMaxAge')).toBe('number');
+    expect(typeof getConfig('apiHttps')).toBe('boolean');
+  });
+
+  it('throws an error if cookiePassword is too short', () => {
+    expect(() => {
+      configure({ cookiePassword: 'short' });
+    }).toThrow('cookiePassword must be at least 32 characters long');
+  });
+
+  it('throws an error if required values are missing', () => {
+    expect(() => {
+      configure(() => undefined);
+      getConfig('apiKey');
+    }).toThrow();
+  });
+});