Amphora Authentication Adapter

Common errors

• TypeError: Cannot read properties of undefined (reading 'get') or storage.get is not a function

  cause The `storage` parameter passed to `amphoraAuth` is not a valid DB instance or lacks the required `get` and `put` methods.
  fix Ensure the `storage` object passed during initialization conforms to the expected interface with `get` and `put` methods, typically an Amphora storage instance.

• Error: Missing environment variable for [ProviderName] provider

  cause An authentication provider (e.g., Google, Twitter) is configured, but its corresponding environment variables (consumer key, secret, etc.) are not set.
  fix Set the required environment variables for the specified provider (e.g., `export GOOGLE_CONSUMER_KEY='your_key'`) in the environment where the application runs.

• Error: Failed to fetch user data for [username]

  cause The user account does not exist in the database or the `user.yml` import was incorrect/incomplete, or the specified provider doesn't match the imported user's provider.
  fix Verify the user exists in your Clay instance and that their `username` and `provider` in `user.yml` (and thus in the database) match the login attempt. Re-import the `user.yml` if necessary.

• Error: Passport session setup requires a session store.

  cause The Express session middleware is not correctly configured with a session store before `amphora-auth` is initialized, or `connect-redis` is not properly set up.
  fix Ensure `express-session` is initialized with a `store` (e.g., `RedisStore`) and mounted on the Express app *before* `amphora-auth` is called, and that `redis` and `connect-redis` are correctly configured.

Warnings

• gotcha Missing or incorrectly configured environment variables for authentication providers will prevent users from authenticating via those methods. Each provider (Google, Twitter, Slack, Cognito, LDAP) requires specific `_CONSUMER_KEY`, `_CONSUMER_SECRET`, and potentially other variables to be exported.
  Fix: Ensure all necessary environment variables (e.g., `GOOGLE_CONSUMER_KEY`, `TWITTER_CONSUMER_SECRET`, `COGNITO_CONSUMER_DOMAIN`, `LDAP_URL`) are correctly set in the deployment environment where `amphora-auth` is running.
• breaking The `clayhandlebars` package is a peer dependency, specifically requiring version `5`. Mismatches with other versions of `clayhandlebars` or its absence can lead to runtime errors, particularly in template rendering related to authentication pages.
  Fix: Verify that `clayhandlebars@5` is installed in your project's dependencies alongside `amphora-auth`. Use `npm install clayhandlebars@5` or `yarn add clayhandlebars@5` if missing or incorrect.
• gotcha Setting the `MAINTENANCE_MODE_ENABLED` environment variable to `true` will prevent all users from entering edit mode or making any edits, redirecting them to a login page with a maintenance message. This can be enabled even if users were already in an editing session.
  Fix: Be mindful of this flag's impact. Only enable `MAINTENANCE_MODE_ENABLED=true` when intended for a system-wide maintenance event. Ensure clear communication with users if this feature is used unexpectedly.
• gotcha User accounts must be imported correctly using `claycli` with a `user.yml` file. Incorrect `username`, `provider`, `password`, or `auth` roles will result in failed login attempts, even if provider configurations are otherwise correct.
  Fix: Double-check the `user.yml` configuration (username, provider, password, auth role) and ensure `clay import` is run with the correct API key and target instance. For OAuth users, the username must match the provider's identifier (e.g., full email for Google).

Install

• npm install amphora-auth npm
• yarn add amphora-auth yarn
• pnpm add amphora-auth pnpm

Imports

• amphoraAuth
  wrong:

  import { amphoraAuth } from 'amphora-auth';
  const amphoraAuth = require('amphora-auth');

  correct:

  import amphoraAuth from 'amphora-auth';

  The module typically exports a single function as its default export, which is then immediately invoked for configuration.
• AuthService
  wrong:

  const { AuthService } = require('amphora-auth');

  correct:

  import { AuthService } from 'amphora-auth';

  While the primary usage is the default export, advanced scenarios might require direct access to internal services like AuthService.

Quickstart

This quickstart demonstrates how to initialize `amphora-auth` within an Express application, showing the required parameters for basic setup and mocking dependencies like Redis store, site metadata, and storage. It highlights the primary configuration function of the module.

import amphoraAuth from 'amphora-auth';
import express from 'express';
import redis from 'redis';
import session from 'express-session';
import connectRedis from 'connect-redis';

const app = express();
const router = express.Router();
const RedisStore = connectRedis(session);

// Dummy implementations for required parameters
const providers = {
  google: {
    // In a real app, these would come from env vars
    consumerKey: process.env.GOOGLE_CONSUMER_KEY ?? '',
    consumerSecret: process.env.GOOGLE_CONSUMER_SECRET ?? ''
  }
  // ... other providers like twitter, slack, cognito, ldap
};

const redisClient = redis.createClient();
const store = new RedisStore({ client: redisClient });

const site = { slug: 'my-site', host: 'localhost:3001' }; // Example site metadata
const storage = { 
  get: () => Promise.resolve({ data: {} }),
  put: () => Promise.resolve({})
}; // Mock DB instance
const bus = { 
  publish: () => {},
  subscribe: () => {}
}; // Mock Redis bus instance

// Initialize auth module
amphoraAuth({
  router, // Site router for auth routes
  providers, // Authentication providers configuration
  store, // Redis Session Store for sessions
  site, // Site metadata
  storage, // DB instance for user storage
  bus // Redis bus instance for inter-process communication
});

app.use(session({
  store: store,
  secret: 'supersecretkey',
  resave: false,
  saveUninitialized: false,
  cookie: { secure: false } // Set to true in production with HTTPS
}));

app.use(router);

app.get('/', (req, res) => {
  res.send('Amphora Auth is running!');
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});