NODE_ENV=development           # or 'production'
JWT_SECRET=your-secret-here    # used to sign/verify tokens

4. Configure your Express app to mount the admin UI and the API:

// app.js
const express = require('express')
const app = express()
const expressa = require('./expressa-src/index')

app.use('/admin', expressa.admin({ apiurl: '/api/' }))
app.use('/api', expressa.api())

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

5. Start the server and navigate to http://localhost:3000/admin to complete the installation wizard, which writes a data/settings/<NODE_ENV>.json file.

6. (Optional) For MongoDB or PostgreSQL storage, set the collection_db_type in settings (mongo or postgres) and provide connection strings in the settings document. For file-based storage (default), a data/ directory will be created automatically.

7. (TypeScript projects) Expressa is CommonJS; require it via import with esModuleInterop: true in tsconfig.json, or use require:

{
  "compilerOptions": {
    "esModuleInterop": true,
    "allowSyntheticDefaultImports": true
  }
}

Public API

auth.createHash

function createHash(password: string): string

Synchronously bcrypt-hashes a plaintext password with a cost factor of 10. Use when registering a new user or updating credentials outside the built-in user listener pipeline.

auth.isValidPassword

function isValidPassword(password: string, hashedPassword: string): boolean

Synchronously compares a plaintext password against a bcrypt hash. Use for custom login flows or when implementing alternative authentication endpoints that bypass the default /users/login route.

auth.middleware

async function authMiddleware(req: Request, res: Response, next: NextFunction): Promise<void>

Express middleware that resolves the current user from a JWT (x-access-token header or token query param) or an access key (x-access-key header or access_key query param). Sets req.uid, req.user, and req.ucollection on success. Mount before any route that requires identity.

auth.getTokenError

function getTokenError(req: Request): { tokenError?: string }

Returns a plain object describing the JWT error (expired token, jwt error) stored on req.uerror. Useful for surfacing auth failure reasons in error response bodies.

auth.doLogin

// delegates to auth/jwt.js handler
function doLogin(...args: any[]): Promise<any>

Performs the JWT-based login flow. Called internally by the /users/login controller; you can call it directly to generate tokens in custom authentication routes.

Working examples

Scenario - Minimal Express integration

Drop expressa into an existing Express app, mount the admin panel and API, and let the installation wizard handle the rest.

import express from 'express'
const expressa = require('./expressa-src/index')

const app = express()

app.use('/admin', expressa.admin({ apiurl: '/api/' }))
app.use('/api', expressa.api())

app.get('/health', (_req, res) => res.json({ ok: true }))

app.listen(3000, () => {
  console.log('Server running at http://localhost:3000')
})

Scenario - Custom route with auth middleware

Protect a custom Express route using the expressa auth middleware so req.user is populated from the incoming JWT.

import express, { Request, Response } from 'express'
const auth = require('./expressa-src/auth')

const app = express()
app.use(express.json())

// Mount auth middleware globally or per-route
app.use(auth.middleware)

app.get('/me', (req: any, res: Response) => {
  if (!req.uid) {
    const tokenErr = auth.getTokenError(req)
    return res.status(401).json({ error: 'Unauthorized', ...tokenErr })
  }
  res.json({ uid: req.uid, user: req.user })
})

app.listen(3000)

Scenario - Manual password hashing and validation

Hash a password before storing it manually (e.g., a migration script or seed script outside the listener pipeline).

const auth = require('./expressa-src/auth')

const plaintext = 'hunter2'
const hash = auth.createHash(plaintext)
console.log('Hashed:', hash)            // $2a$10$...

const valid = auth.isValidPassword(plaintext, hash)
console.log('Valid:', valid)            // true

const invalid = auth.isValidPassword('wrongpass', hash)
console.log('Invalid:', invalid)        // false

File walkthrough

• index.js - Bootstraps the expressa router, loads all db adapters, wires controllers and listeners, exports api() and admin().
• auth/index.js - Exports createHash, isHashed, isValidPassword, doLogin, getTokenError, and middleware; delegates JWT work to auth/jwt.js.
• auth/jwt.js - Low-level JWT signing and verification via jsonwebtoken.
• controllers/collections.js - Express route handlers for GET/POST/PUT/DELETE /:collection and /:collection/:id.
• controllers/users.js - Handles /users/login and user-specific routes.
• controllers/install.js - One-time installation endpoint used by the admin wizard.
• controllers/status.js - Health/status endpoint.
• db/file.js - JSON-file-backed database adapter using jfs.
• db/memory.js - In-memory adapter, useful for testing.
• db/mongo.js - MongoDB adapter using the mongodb driver.
• db/postgres.js - PostgreSQL adapter using pg with JSONB storage.
• db/cached.js - Caching wrapper around another db adapter.
• middleware/permissions.js - Enforces per-collection permissions on every request.
• middleware/logging.js - Logs request/response lifecycle using debug and on-finished.
• listeners.js - Registers core before/after listeners for collection CRUD events.
• listeners_collection_permissions.js - Registers ACL enforcement listeners per collection.
• listeners_users.js - Hooks user create/update to auto-hash passwords.
• listeners_validation.js - Hooks collection save to validate against JSON schema via ajv.
• util.js - Shared helpers (object traversal, schema utilities).
• modules/access_keys/ - Adds API access key generation and validation.
• modules/admin/ - Vue 2 SPA admin interface; built output is served by expressa.admin().
• modules/collections/ - Collection management module.
• modules/core/ - Core module bootstrapped on every router instance.
• modules/logging/ - Request logging module.
• modules/permissions/ - Permission definition and enforcement module.
• cypress/ - End-to-end integration tests for install, users, and collections.
• doc/ - Authoritative markdown docs for auth, permissions, querying, database, and listeners.

Common pitfalls and fixes

• Settings file not found on startup: Run the install wizard at /admin before any API calls; it writes data/settings/<NODE_ENV>.json which is required at boot.
• jwt_secret not set: The JWT secret must be saved in settings via the admin wizard or pre-seeded in data/settings/<NODE_ENV>.json; tokens will fail to verify without it.
• Wrong NODE_ENV: Expressa reads process.env.NODE_ENV to pick the settings file; mismatching env between seeding and running causes "settings not found" errors.
• MongoDB alias: The adapter key mongodb is aliased to mongo; use "collection_db_type": "mongo" in settings (not "mongodb") to avoid a "missing dbtype" error at bootstrap.
• CJS/ESM interop: Expressa is CommonJS; in ESM projects use import expressa from './expressa-src/index' only with "esModuleInterop": true, or use createRequire.
• Bcrypt on serverless/Alpine: bcryptjs is pure JS and has no native bindings; no extra build flags needed, but do not swap it for bcrypt without updating all auth/ imports.

Vibe-coding prompt template

I have purchased an AVCP block that contains the source of the `expressa` npm
package (v2.1.1) in the `source/` directory of my project. I also have a
`USAGE.md` file describing its API and integration steps.

Please help me integrate expressa into my existing Express/Node.js project
step by step:

1. Read `USAGE.md` and `source/index.js` to understand the public API.
2. Mount `expressa.admin()` at `/admin` and `expressa.api()` at `/api` in my
   main Express app file.
3. Add `source/auth/index.js` middleware to protect my existing custom routes,
   populating `req.user` from JWTs.
4. Show me how to hash passwords using `auth.createHash` and verify them with
   `auth.isValidPassword` in my user registration logic.
5. Confirm which environment variables (`NODE_ENV`, `jwt_secret`) I need and
   where they are read from.
6. Do not install the upstream `expressa` package from npm; import directly
   from `./source/index.js`.
7. Use TypeScript with `esModuleInterop: true`.

License and credit

Expressa is released under the MIT License. See source/LICENSE for the full text. Upstream package: expressa on npm by thomas4019, version 2.1.1. Source repository: https://github.com/thomas4019/expressa.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.