@verisure-italy/express-authentication-middleware

Express middleware for Bearer-token authentication backed by DynamoDB. It resolves the token, validates expiration, loads the user, and populates req._auth with a typed request contract.

Installation

pnpm add @verisure-italy/express-authentication-middleware

Main Exports

• dynamoAuthMiddleware(settings)
• createAuthMiddleware(dependencies)
• AuthenticationError
• type Settings
• type AuthResponse
• repository-facing types for custom integrations and tests

Runtime Flow

1. read Authorization: Bearer ...
2. if the header is missing or empty, call next() with no error
3. query the token repository on the token-index
4. reject invalid or expired tokens
5. resolve the user by id or, when configured, by username
6. populate req._auth

Settings

| Field | Type | Required | Description | | --- | --- | --- | --- | | dynamoConfig | Partial<DynamoConfig> | No | DynamoDB overrides forwarded to @verisure-italy/dynamo-kit | | tokenTableName | string | No | Token table name. Defaults to access_token | | userTableName | string | No | User table name. Defaults to user | | userLookup.field | 'auto' | 'id' | 'username' | No | User lookup strategy | | userLookup.usernameIndexName | string | No | Secondary index used for username lookup. Defaults to username-index |

AuthResponse

| Field | Type | Required | Description | | --- | --- | --- | --- | | user | UserDetails | Yes | Resolved AAA user | | token.accessToken | string | Yes | Raw bearer token | | token.accessTokenExpiresAt | string | Yes | ISO string derived from the token expiration | | token.scope | string[] | Yes | Parsed scope array |

Express Integration

import express from 'express'
import { dynamoAuthMiddleware } from '@verisure-italy/express-authentication-middleware'

const app = express()

app.use(dynamoAuthMiddleware({
  tokenTableName: 'access_token',
  userTableName: 'user',
  dynamoConfig: {
    region: 'eu-west-1',
    endpoint: 'http://localhost:8000',
  },
}))

app.get('/me', (req, res) => {
  if (!req._auth) {
    return res.status(401).json({ error: 'Not authenticated' })
  }

  res.json(req._auth)
})

Repository-Level Integration

Use createAuthMiddleware() when you want to provide your own repositories:

import { createAuthMiddleware } from '@verisure-italy/express-authentication-middleware'

const middleware = createAuthMiddleware({
  tokenRepo,
  userRepo,
  userLookup: {
    field: 'auto',
  },
})

Notes

• Importing the package automatically augments Express so req._auth is typed.
• scope is always exposed as string[].
• The token lookup requires a token-index secondary index.
• In auto mode the middleware tries userRepo.get(id) first, then falls back to username lookup.