@prsm/auth 1.0.0

package/src/errors.js

@@ -0,0 +1,173 @@
+export class AuthError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+
+export class ConfirmationExpiredError extends AuthError {
+  constructor() {
+    super("Confirmation token has expired")
+  }
+}
+
+export class ConfirmationNotFoundError extends AuthError {
+  constructor() {
+    super("Confirmation token not found")
+  }
+}
+
+export class EmailNotVerifiedError extends AuthError {
+  constructor() {
+    super("Email address has not been verified")
+  }
+}
+
+export class EmailTakenError extends AuthError {
+  constructor() {
+    super("Email address is already in use")
+  }
+}
+
+export class InvalidEmailError extends AuthError {
+  constructor() {
+    super("Invalid email address format")
+  }
+}
+
+export class InvalidPasswordError extends AuthError {
+  constructor() {
+    super("Invalid password")
+  }
+}
+
+export class InvalidTokenError extends AuthError {
+  constructor() {
+    super("Invalid token")
+  }
+}
+
+export class ResetDisabledError extends AuthError {
+  constructor() {
+    super("Password reset is disabled for this account")
+  }
+}
+
+export class ResetExpiredError extends AuthError {
+  constructor() {
+    super("Password reset token has expired")
+  }
+}
+
+export class ResetNotFoundError extends AuthError {
+  constructor() {
+    super("Password reset token not found")
+  }
+}
+
+export class TooManyResetsError extends AuthError {
+  constructor() {
+    super("Too many password reset requests")
+  }
+}
+
+export class UserInactiveError extends AuthError {
+  constructor() {
+    super("User account is inactive")
+  }
+}
+
+export class UserNotFoundError extends AuthError {
+  constructor() {
+    super("User not found")
+  }
+}
+
+export class UserNotLoggedInError extends AuthError {
+  constructor() {
+    super("User is not logged in")
+  }
+}
+
+export class RateLimitedError extends AuthError {
+  /** @param {number} [retryAfter] milliseconds until the next attempt is allowed */
+  constructor(retryAfter) {
+    super("Too many attempts")
+    this.retryAfter = retryAfter
+  }
+}
+
+// two-factor authentication errors
+
+export class SecondFactorRequiredError extends AuthError {
+  /**
+   * @param {{ totp?: boolean, email?: { otpValue: string, maskedContact: string }, sms?: { otpValue: string, maskedContact: string } }} availableMethods
+   */
+  constructor(availableMethods) {
+    super("Second factor authentication required")
+    this.availableMethods = availableMethods
+  }
+}
+
+export class InvalidTwoFactorCodeError extends AuthError {
+  constructor() {
+    super("Invalid two-factor authentication code")
+  }
+}
+
+export class TwoFactorExpiredError extends AuthError {
+  constructor() {
+    super("Two-factor authentication session has expired")
+  }
+}
+
+export class TwoFactorNotSetupError extends AuthError {
+  constructor() {
+    super("Two-factor authentication is not set up for this account")
+  }
+}
+
+export class TwoFactorAlreadyEnabledError extends AuthError {
+  constructor() {
+    super("Two-factor authentication is already enabled for this mechanism")
+  }
+}
+
+export class InvalidBackupCodeError extends AuthError {
+  constructor() {
+    super("Invalid backup code")
+  }
+}
+
+export class TwoFactorSetupIncompleteError extends AuthError {
+  constructor() {
+    super("Two-factor authentication setup is not complete")
+  }
+}
+
+// impersonation errors
+
+export class ImpersonationDisabledError extends AuthError {
+  constructor() {
+    super("Impersonation is not enabled in this configuration")
+  }
+}
+
+export class ImpersonationNotAllowedError extends AuthError {
+  constructor() {
+    super("Impersonation is not permitted for this actor and target")
+  }
+}
+
+export class AlreadyImpersonatingError extends AuthError {
+  constructor() {
+    super("An impersonation session is already active")
+  }
+}
+
+export class NotImpersonatingError extends AuthError {
+  constructor() {
+    super("No active impersonation session")
+  }
+}

package/src/hooks.js

@@ -0,0 +1,41 @@
+// thin, duck-typed adapters for the optional @prsm/trace and @prsm/limit
+// instances. auth never imports those packages; it only calls what's passed in,
+// so either can be absent without any coupling
+
+/**
+ * @typedef {import("./types.js").Tracer} Tracer
+ * @typedef {import("./types.js").Limiter} Limiter
+ */
+
+/**
+ * Run fn inside a tracing span when a tracer is provided, otherwise run it plain.
+ * Matches the @prsm/trace tracer shape: tracer.span(name, attributes, fn).
+ * @template T
+ * @param {Tracer | undefined} tracer
+ * @param {string} name
+ * @param {Record<string, any>} attributes
+ * @param {() => Promise<T>} fn
+ * @returns {Promise<T>}
+ */
+export function withSpan(tracer, name, attributes, fn) {
+  if (tracer && typeof tracer.span === "function") {
+    return tracer.span(name, attributes, fn)
+  }
+  return fn()
+}
+
+/**
+ * Consume one unit against a limiter for the given key. The @prsm/limit
+ * algorithms expose different verbs (tokenBucket.take, slidingWindow.hit,
+ * leakyBucket.drip); all return { allowed, retryAfter }. We accept any of them
+ * plus a generic consume/check so callers can pass a limiter instance directly.
+ * @param {Limiter | undefined} limiter
+ * @param {string} key
+ * @returns {Promise<{ allowed: boolean, retryAfter?: number } | null>}
+ */
+export async function consumeLimit(limiter, key) {
+  if (!limiter) return null
+  const fn = limiter.take || limiter.hit || limiter.drip || limiter.consume || limiter.check
+  if (typeof fn !== "function") return null
+  return fn.call(limiter, key)
+}

package/src/index.js

@@ -0,0 +1,23 @@
+export { createAuthMiddleware } from "./middleware.js"
+export { createAuthTables, dropAuthTables, cleanupExpiredTokens, getAuthTableStats } from "./schema.js"
+export { createAuthContext } from "./auth-context.js"
+export * as authFunctions from "./auth-functions.js"
+export * from "./auth-functions.js"
+export { defineRoles, addRoleToUser, removeRoleFromUser, setUserRoles, getUserRoles } from "./user-roles.js"
+
+// types and runtime enums (AuthStatus, AuthRole, AuthActivityAction, TwoFactorMechanism)
+export * from "./types.js"
+
+// error classes
+export * from "./errors.js"
+
+export { isValidEmail, validateEmail } from "./util.js"
+
+export { ActivityLogger } from "./activity-logger.js"
+
+export { TwoFactorManager, TotpProvider, OtpProvider } from "./two-factor/index.js"
+
+export { GitHubProvider, GoogleProvider, AzureProvider, BaseOAuthProvider } from "./providers/index.js"
+
+// cross-instance invalidation teardown (graceful shutdown / tests)
+export { closeInvalidationListeners } from "./invalidation.js"

package/src/invalidation.js

@@ -0,0 +1,166 @@
+// optional cross-instance session invalidation over postgres LISTEN/NOTIFY.
+// when config.invalidation.listen is true, security-relevant account writes
+// (force-logout, status, role, password) emit pg_notify, and every process
+// running a listener drops the matching session on its next request instead of
+// waiting up to resyncInterval. this needs no extra dependency - postgres is
+// already required. it degrades silently to poll-based resync when the listener
+// connection or NOTIFY is unavailable (e.g. pgbouncer in transaction mode)
+
+/**
+ * @typedef {import("./types.js").AuthConfig} AuthConfig
+ */
+
+const DEFAULT_CHANNEL = "prsm_auth_invalidate"
+
+// prune invalidation marks older than this; a mark only matters until the
+// affected session resyncs, which happens well within a minute
+const MARK_TTL_MS = 5 * 60 * 1000
+
+/**
+ * @typedef {object} ListenerState
+ * @property {string} channel
+ * @property {Map<number, number>} invalidated accountId -> timestamp of last signal
+ * @property {boolean} started
+ * @property {boolean} broken
+ * @property {import("pg").PoolClient | null} client
+ */
+
+// per-pool, per-channel listener state. pools are long-lived objects, so a Map
+// keyed by the pool is the natural scope
+/** @type {Map<import("pg").Pool, Map<string, ListenerState>>} */
+const registry = new Map()
+
+/**
+ * @param {AuthConfig} config
+ * @returns {string}
+ */
+function channelFor(config) {
+  return config.invalidation?.channel || DEFAULT_CHANNEL
+}
+
+/**
+ * @param {AuthConfig} config
+ * @returns {ListenerState | null}
+ */
+function getState(config) {
+  const pool = config.db
+  const channel = channelFor(config)
+  let byChannel = registry.get(pool)
+  if (!byChannel) {
+    byChannel = new Map()
+    registry.set(pool, byChannel)
+  }
+  let state = byChannel.get(channel)
+  if (!state) {
+    state = { channel, invalidated: new Map(), started: false, broken: false, client: null }
+    byChannel.set(channel, state)
+  }
+  return state
+}
+
+/**
+ * Start the LISTEN connection for this config's pool/channel if it isn't already
+ * running. Idempotent and non-blocking - the first call kicks off the connection
+ * and returns; failures mark the listener broken so callers fall back to polling.
+ * @param {AuthConfig} config
+ */
+export function ensureListener(config) {
+  if (!config.invalidation?.listen) return
+
+  const state = getState(config)
+  if (!state || state.started || state.broken) return
+  state.started = true
+
+  const pool = config.db
+  const channel = state.channel
+
+  pool
+    .connect()
+    .then(async (client) => {
+      state.client = client
+      client.on("notification", (msg) => {
+        if (msg.channel !== channel || !msg.payload) return
+        const accountId = parseInt(msg.payload, 10)
+        if (!Number.isNaN(accountId)) {
+          state.invalidated.set(accountId, Date.now())
+          pruneMarks(state)
+        }
+      })
+      client.on("error", () => {
+        state.broken = true
+      })
+      await client.query(`LISTEN ${channel}`)
+    })
+    .catch(() => {
+      // listener unavailable (e.g. pooler without session support) - fall back to poll
+      state.broken = true
+      state.started = false
+    })
+}
+
+/**
+ * Broadcast that an account's auth state changed so other instances resync it
+ * immediately. No-op unless invalidation is enabled.
+ * @param {AuthConfig} config
+ * @param {number} accountId
+ * @returns {Promise<void>}
+ */
+export async function notifyInvalidation(config, accountId) {
+  if (!config.invalidation?.listen) return
+  try {
+    await config.db.query("SELECT pg_notify($1, $2)", [channelFor(config), String(accountId)])
+  } catch {
+    // notify is best-effort; poll-based resync remains the backstop
+  }
+}
+
+/**
+ * Whether the given account was signaled invalid more recently than `sinceTs`.
+ * @param {AuthConfig} config
+ * @param {number} accountId
+ * @param {number} sinceTs epoch millis
+ * @returns {boolean}
+ */
+export function wasInvalidatedSince(config, accountId, sinceTs) {
+  if (!config.invalidation?.listen) return false
+  const pool = config.db
+  const byChannel = registry.get(pool)
+  if (!byChannel) return false
+  const state = byChannel.get(channelFor(config))
+  if (!state) return false
+  const ts = state.invalidated.get(accountId)
+  return ts != null && ts > sinceTs
+}
+
+/**
+ * @param {ListenerState} state
+ */
+function pruneMarks(state) {
+  const cutoff = Date.now() - MARK_TTL_MS
+  for (const [accountId, ts] of state.invalidated) {
+    if (ts < cutoff) state.invalidated.delete(accountId)
+  }
+}
+
+/**
+ * Release all listener connections. Intended for test teardown and graceful
+ * shutdown - production processes normally keep listeners for their lifetime.
+ * @returns {Promise<void>}
+ */
+export async function closeInvalidationListeners() {
+  for (const byChannel of registry.values()) {
+    for (const state of byChannel.values()) {
+      if (state.client) {
+        try {
+          state.client.release()
+        } catch {
+          // ignore
+        }
+      }
+      state.client = null
+      state.started = false
+      state.invalidated.clear()
+    }
+  }
+  registry.clear()
+}

package/src/middleware.js

@@ -0,0 +1,33 @@
+import { AuthManager } from "./auth-manager.js"
+import { ensureListener } from "./invalidation.js"
+
+/**
+ * @typedef {import("./types.js").AuthConfig} AuthConfig
+ */
+
+/**
+ * Create the Express middleware that attaches an AuthManager to req.auth,
+ * resyncs the session, and processes any remember-me token.
+ * @param {AuthConfig} config
+ * @returns {import("express").RequestHandler}
+ */
+export function createAuthMiddleware(config) {
+  // start the cross-instance invalidation listener once if enabled; idempotent
+  // and non-blocking, falls back to poll-based resync if unavailable
+  ensureListener(config)
+
+  return async (req, res, next) => {
+    try {
+      const authManager = new AuthManager(req, res, config)
+
+      req.auth = authManager
+
+      await authManager.resyncSession()
+      await authManager.processRememberDirective()
+
+      next()
+    } catch (error) {
+      next(error)
+    }
+  }
+}

package/src/providers/azure-provider.js

@@ -0,0 +1,114 @@
+import { BaseOAuthProvider } from "./base-provider.js"
+
+/**
+ * @typedef {import("../types.js").AuthConfig} AuthConfig
+ * @typedef {import("../types.js").OAuthUserData} OAuthUserData
+ * @typedef {import("../types.js").AzureProviderConfig} AzureProviderConfig
+ */
+
+export class AzureProvider extends BaseOAuthProvider {
+  /**
+   * @param {AzureProviderConfig} config
+   * @param {AuthConfig} authConfig
+   * @param {import("../auth-manager.js").AuthManager} authManager
+   */
+  constructor(config, authConfig, authManager) {
+    super(config, authConfig, authManager)
+  }
+
+  /**
+   * Build the Azure AD authorization URL.
+   * @param {string} [state]
+   * @param {string[]} [scopes]
+   * @returns {string}
+   */
+  getAuthUrl(state, scopes) {
+    const azureConfig = this.config
+    const params = new URLSearchParams({
+      client_id: azureConfig.clientId,
+      redirect_uri: azureConfig.redirectUri,
+      scope: scopes?.join(" ") || "openid profile email User.Read",
+      state: state || crypto.randomUUID(),
+      response_type: "code",
+      response_mode: "query",
+    })
+
+    return `https://login.microsoftonline.com/${azureConfig.tenantId}/oauth2/v2.0/authorize?${params}`
+  }
+
+  /**
+   * Exchange the callback code and resolve the Azure user profile.
+   * @param {import("express").Request} req
+   * @returns {Promise<OAuthUserData>}
+   * @throws {Error} when no code is provided or no email is found
+   */
+  async getUserData(req) {
+    const code = req.query.code
+    if (!code) {
+      throw new Error("No authorization code provided")
+    }
+
+    // exchange code for access token
+    const azureConfig = this.config
+    const accessToken = await this.exchangeCodeForToken(code, `https://login.microsoftonline.com/${azureConfig.tenantId}/oauth2/v2.0/token`)
+
+    // fetch user data from Microsoft Graph
+    const user = await this.fetchUserFromAPI(accessToken, "https://graph.microsoft.com/v1.0/me")
+
+    if (!user.mail && !user.userPrincipalName) {
+      throw new Error("No email found in Azure account")
+    }
+
+    return {
+      id: user.id,
+      email: user.mail || user.userPrincipalName,
+      username: user.mailNickname || user.userPrincipalName?.split("@")[0],
+      name: user.displayName,
+      avatar: undefined, // Azure doesn't provide avatar in basic profile
+    }
+  }
+
+  /**
+   * @returns {string}
+   */
+  getProviderName() {
+    return "azure"
+  }
+
+  /**
+   * Exchange an authorization code for an Azure access token.
+   * @param {string} code
+   * @param {string} tokenUrl
+   * @returns {Promise<string>}
+   * @throws {Error} when the exchange fails or no access token is returned
+   */
+  async exchangeCodeForToken(code, tokenUrl) {
+    const azureConfig = this.config
+    const response = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        client_id: azureConfig.clientId,
+        client_secret: azureConfig.clientSecret,
+        code,
+        redirect_uri: azureConfig.redirectUri,
+        grant_type: "authorization_code",
+        scope: "openid profile email User.Read",
+      }),
+    })
+
+    if (!response.ok) {
+      throw new Error(`OAuth token exchange failed: ${response.status} ${response.statusText}`)
+    }
+
+    const data = await response.json()
+    if (!data.access_token) {
+      throw new Error("No access token received from Azure")
+    }
+
+    return data.access_token
+  }
+}

package/src/providers/base-provider.js

@@ -0,0 +1,152 @@
+/**
+ * @typedef {import("../types.js").AuthConfig} AuthConfig
+ * @typedef {import("../types.js").OAuthUserData} OAuthUserData
+ * @typedef {import("../types.js").OAuthCallbackResult} OAuthCallbackResult
+ * @typedef {import("../types.js").OAuthProviderConfig} OAuthProviderConfig
+ */
+
+export class BaseOAuthProvider {
+  /**
+   * @param {OAuthProviderConfig} config
+   * @param {AuthConfig} authConfig
+   * @param {import("../auth-manager.js").AuthManager} authManager
+   */
+  constructor(config, authConfig, authManager) {
+    this.config = config
+    this.authConfig = authConfig
+    this.authManager = authManager
+  }
+
+  /**
+   * Handle an OAuth provider callback request and resolve the login.
+   * @param {import("express").Request} req
+   * @returns {Promise<OAuthCallbackResult>}
+   */
+  async handleCallback(req) {
+    const userData = await this.getUserData(req)
+    return this.processOAuthLogin(userData, req)
+  }
+
+  /**
+   * Resolve or create an account for the OAuth user and record the login.
+   * @param {OAuthUserData} userData
+   * @param {import("express").Request} req
+   * @returns {Promise<OAuthCallbackResult>}
+   * @throws {Error} when an account already exists for the user's email
+   */
+  async processOAuthLogin(userData, req) {
+    const { queries } = this.authManager
+    const providerName = this.getProviderName()
+
+    const existingProvider = await queries.findProviderByProviderIdAndType(userData.id, providerName)
+
+    if (existingProvider) {
+      const account = await queries.findAccountById(existingProvider.account_id)
+      if (account) {
+        await this.authManager.onLoginSuccessful(account, true)
+        return { isNewUser: false }
+      }
+    }
+
+    // new OAuth user - check if email already exists
+    if (userData.email) {
+      const existingAccount = await queries.findAccountByEmail(userData.email)
+      if (existingAccount) {
+        throw new Error("You already have an account associated with this email address.")
+      }
+    }
+
+    // create new user and account
+    let userId
+
+    if (this.authConfig.createUser) {
+      userId = await this.authConfig.createUser(userData)
+    } else {
+      // Generate UUID for OAuth users when no createUser function is provided
+      userId = crypto.randomUUID()
+    }
+
+    // create the auth account (no password for OAuth)
+    const account = await queries.createAccount({
+      userId,
+      email: userData.email,
+      password: null,
+      verified: true, // OAuth providers are pre-verified
+      status: 0, // AuthStatus.Normal
+      rolemask: 0,
+    })
+
+    // create the provider record
+    await queries.createProvider({
+      accountId: account.id,
+      provider: providerName,
+      providerId: userData.id,
+      providerEmail: userData.email,
+      providerUsername: userData.username || null,
+      providerName: userData.name || null,
+      providerAvatar: userData.avatar || null,
+    })
+
+    await this.authManager.onLoginSuccessful(account, true)
+    return { isNewUser: true }
+  }
+
+  /**
+   * Exchange an authorization code for an access token.
+   * @param {string} code
+   * @param {string} tokenUrl
+   * @returns {Promise<string>}
+   * @throws {Error} when the exchange fails or no access token is returned
+   */
+  async exchangeCodeForToken(code, tokenUrl) {
+    const response = await fetch(tokenUrl, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        client_id: this.config.clientId,
+        client_secret: this.config.clientSecret,
+        code,
+        redirect_uri: this.config.redirectUri,
+        grant_type: "authorization_code",
+      }),
+    })
+
+    if (!response.ok) {
+      throw new Error(`OAuth token exchange failed: ${response.status} ${response.statusText}`)
+    }
+
+    const data = await response.json()
+    if (!data.access_token) {
+      throw new Error("No access token received from OAuth provider")
+    }
+
+    return data.access_token
+  }
+
+  /**
+   * Fetch the authenticated user profile from a provider API.
+   * @param {string} accessToken
+   * @param {string} apiUrl
+   * @param {Record<string, string>} [headers]
+   * @returns {Promise<any>}
+   * @throws {Error} when the request fails
+   */
+  async fetchUserFromAPI(accessToken, apiUrl, headers = {}) {
+    const response = await fetch(apiUrl, {
+      headers: {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: "application/json",
+        ...headers,
+      },
+    })
+
+    if (!response.ok) {
+      throw new Error(`Failed to fetch user data: ${response.status} ${response.statusText}`)
+    }
+
+    return response.json()
+  }
+}