Stage Auth Middleware

1.0.9 · active · verified Wed Apr 22

The `stage-auth-middleware` package provides an Express.js middleware specifically designed to secure staging environments for Akarion-related websites. Its core function is to enforce user authentication for access to stage URLs, thereby restricting public access, and to display a visual hint on the page indicating that the user is currently interacting with a staging site. The package is currently stable at version 1.0.9. It operates with an irregular release cadence, likely aligned with internal development cycles rather than public feature rollouts. This utility is highly specialized, serving a niche within the Akarion ecosystem, and should not be considered a general-purpose authentication solution. Its primary differentiator is its tailored integration with specific staging security requirements, offering a streamlined approach without the overhead of more comprehensive identity management systems.

Common errors

```
TypeError: app.use() requires middleware functions but got a Object
```
cause The `stageAuthMiddleware` function was not called with its configuration object when passed to `app.use()`. It expects `stageAuthMiddleware({ options })`.

fix Ensure you call the middleware function with an options object: `app.use(stageAuthMiddleware({ pass: 'your-pass', enabled: true }))`.
```
ReferenceError: require is not defined in ES module scope
```
cause You are attempting to use CommonJS `require` syntax in an ES module (`type: "module"` in `package.json` or `.mjs` file).

fix Change your import statement to `import stageAuthMiddleware from 'stage-auth-middleware';`.
```
Error: Missing 'pass' option for stage-auth-middleware
```
cause The `pass` option is a mandatory configuration parameter for the middleware, and it was not provided or was `undefined`.

fix Ensure the `pass` property is present and has a string value in the options object passed to the middleware, e.g., `stageAuthMiddleware({ pass: process.env.YOUR_SECRET, enabled: true })`.

Warnings

gotcha The `pass` option should never be hardcoded or exposed in production environments. Always use environment variables (e.g., `process.env.STAGE_AUTH_PASS`) to manage this password securely, especially in non-production deployments.
Fix: Replace hardcoded `pass` strings with `process.env.YOUR_SECRET_VAR` and ensure this variable is set in your deployment environment.
gotcha This middleware is specifically designed for 'Akarion' staging sites and internal use. While it might function elsewhere, its features and underlying assumptions may not align with general-purpose authentication needs or other project ecosystems. Using it outside its intended context may lead to unexpected behavior or security gaps.
Fix: Evaluate if this specific middleware truly fits your use case if you are not operating within the Akarion staging environment; consider a more generic authentication solution if not.
gotcha For the staging hint and client-side authentication flow to work correctly, the `<script src="/stage-auth-middleware.js"></script>` tag *must* be included in the HTML files of your staging application. If this script is not loaded, users may experience an incomplete or non-functional authentication process and will not see the staging indicator.
Fix: Ensure the client-side script `<script src="/stage-auth-middleware.js" async defer></script>` is present in the `<head>` or `<body>` of all HTML pages that require staging authentication. Confirm your Express server configuration serves this static file correctly, typically by mounting a static middleware.

Install

npm install stage-auth-middleware npm
yarn add stage-auth-middleware yarn
pnpm add stage-auth-middleware pnpm

Imports

stageAuthMiddleware
wrong:
```
const stageAuthMiddleware = require('stage-auth-middleware');
```
correct:
```
import stageAuthMiddleware from 'stage-auth-middleware';
```
While the README shows CommonJS `require`, it exports as a default module, so ESM `import` is the idiomatic way. Both work.
stageAuthMiddleware (CJS)
```
const stageAuthMiddleware = require('stage-auth-middleware');
```
This is the CommonJS pattern shown in the original documentation and is fully supported in Node.js environments.
Middleware Configuration
wrong:
```
app.use(stageAuthMiddleware);
```
correct:
```
app.use(stageAuthMiddleware({ pass: process.env.STAGE_AUTH_PASS || 'default-password', enabled: process.env.NODE_ENV !== 'production' }));
```
The middleware must be called as a function with an options object, including a 'pass' and 'enabled' property, to be correctly initialized.

Quickstart

This quickstart initializes an Express server with the stage-auth-middleware, demonstrating basic setup and environment variable usage for the password, and a simple route.

import express from 'express';
import stageAuthMiddleware from 'stage-auth-middleware';

const app = express();

// It's crucial to load environment variables first in a real app (e.g., using dotenv)
const STAGE_AUTH_PASS = process.env.STAGE_AUTH_PASS || 'your-secret-staging-pass';

app.use(stageAuthMiddleware({
  pass: STAGE_AUTH_PASS,
  enabled: process.env.NODE_ENV !== 'production' // Only enable for non-production environments
}));

// Example route
app.get('/', (req, res) => {
  res.send('<h1>Welcome to the Staging Site!</h1><p>You have authenticated successfully.</p>');
});

// IMPORTANT: Ensure the client-side script is served.
// If you are not serving static files from the root, you might need a dedicated route:
// app.get('/stage-auth-middleware.js', (req, res) => {
//   res.sendFile(path.resolve('node_modules/stage-auth-middleware/dist/client.js')); // (path might vary)
// // This library might also serve it implicitly based on configuration.
// });

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Staging server running on http://localhost:${PORT}`);
  console.log('Access with password: ' + STAGE_AUTH_PASS);
});

view raw JSON →