Registry / auth-security / amphora-auth

amphora-auth

JSON →
library2.1.0jsnpmunverified

amphora-auth serves as an authentication adapter specifically designed for the Amphora content management system, providing robust user authentication capabilities within the Clay ecosystem. It facilitates both local username/password authentication and seamless integration with a variety of third-party OAuth providers, including Google, Twitter, Slack, Cognito, and LDAP. This broad support enables flexible and secure authentication strategies for applications built on the Clay platform. The current stable version is 2.1.0. While a specific release cadence isn't explicitly stated, updates likely align with developments in the broader Clay platform. Its primary differentiator is its deep, opinionated integration with Amphora and Clay, which significantly simplifies the setup and management of diverse authentication backends for Clay-based applications, streamlining security configuration.

npm install amphora-auth
INSTALL
IMPORT
SIG · AMPHORA-AUTH
A
amphora-auth
auth-securityjavascriptv2.1.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

amphoraAuth
import amphoraAuth from 'amphora-auth';
import { amphoraAuth } from 'amphora-auth'; const amphoraAuth = require('amphora-auth');
The module typically exports a single function as its default export, which is then immediately invoked for configuration.
AuthService
import { AuthService } from 'amphora-auth';
const { AuthService } = require('amphora-auth');
While the primary usage is the default export, advanced scenarios might require direct access to internal services like AuthService.

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'); });
Debug
Known issues
gotchaMissing 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.
affects: >=1.0.0
breakingThe `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.
affects: >=2.0.0
gotchaSetting 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.
affects: >=1.0.0
gotchaUser 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).
affects: >=1.0.0
Errors
Common errors & fixes
TypeError: Cannot read properties of undefined (reading 'get') or storage.get is not a function
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
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]
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.
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.
Upgrade
Version history
2.1.0latest on npm
Audit
Dependencies
clayhandlebarsrequiredPeer dependency required for template rendering within the Clay ecosystem, potentially for login pages or email templates.
Agent activity
37 hits · last 30 days
node
34
OpenAI (training)
1
Resources