Autenticazione

Efesto non include un sistema di autenticazione. Ti offre due hook e li esegue attorno a ogni richiesta; ciò che accade al loro interno — JWT, sessioni, API key, OAuth — è il tuo codice. Questa pagina documenta esattamente cosa sono questi hook e dove vengono eseguiti.

Cosa fornisce realmente Efesto

• Express: un authMiddleware globale che passi a efesto(), più un override per metodo (_<method>OverrideAuth).
• Bun/Elysia: nulla di specifico per Efesto. Ti autentichi nativamente in setup (es. onBeforeHandle), perché quell'hook viene eseguito sulla root prima del mount delle rotte.

Tutto il resto (verificare un token, cercare un utente, rinnovare una sessione) vive nel tuo middleware, non nel framework.

L'hook globale

Express

Passi authMiddleware a efesto(). Viene eseguito prima di ogni resolver. Per lasciare un'app aperta, passa un middleware che chiama semplicemente next():

import efesto from "efesto";

app.use(
  "/api/v1",
  efesto({
    authMiddleware: (req, res, next) => {
      // verifica la richiesta qui; allega ciò che ti serve a `req`
      // chiama next(err) / lancia un'eccezione per rifiutare, o next() per consentire
      next();
    },
    errorMiddleware: (req, res, next) => next(),
    isProduction: false,
    options: { absoluteDirRoutes: `${__dirname}/routes` },
  })
);

Qualsiasi cosa alleghi a req all'interno di questo middleware è disponibile in ogni metodo Efesto e nel controllo ABAC (vedi Permessi ABAC).

Un middleware realistico di verifica del token è normale Express: Efesto non lo incapsula:

const authMiddleware = (req, res, next) => {
  const token = req.headers.authorization?.replace("Bearer ", "");
  if (!token) return res.status(401).json({ error: "Missing token" });
  try {
    req.user = verifyYourToken(token); // la tua logica / la tua libreria
    next();
  } catch {
    res.status(401).json({ error: "Invalid token" });
  }
};

Bun/Elysia

L'adapter Elysia non ha un hook di autenticazione proprio. Autenticati in setup, che viene eseguito sull'istanza root prima del mount delle rotte, così si applica a ogni rotta:

import efesto from "efesto/elysia";
import { Elysia } from "elysia";

const app = efesto({
  isProduction: process.env.NODE_ENV === "production",
  routesDir: `${import.meta.dir}/routes`,
  prefix: "/api/v1",
  setup: (root: Elysia) => {
    root.onBeforeHandle(({ headers, set }) => {
      const token = headers.authorization?.replace("Bearer ", "");
      if (!token) {
        set.status = 401;
        return { error: "Missing token" };
      }
      // verifica il token qui; lancia un'eccezione o restituisci una risposta per rifiutare
    });
  },
}).listen(2014);

Per rendere i dati utente disponibili agli handler (e all'ability ABAC), usa derive:

setup: (root) =>
  root.derive(({ headers }) => ({
    user: resolveUserFromHeaders(headers), // la tua logica
  })),

Autenticazione per endpoint (Express)

Non tutti gli endpoint hanno bisogno della stessa regola. Sullo stack Express puoi sovrascrivere il middleware globale per un singolo metodo dichiarando _<method>OverrideAuth sul servizio. È un middleware normale e sostituisce quello globale solo per quel verbo:

import { BaseApiService } from "efesto";
import type { Request, Response, NextFunction } from "express";

class Users extends BaseApiService {
  constructor() {
    super(__filename);
  }

  // GET pubblica: salta del tutto l'auth globale
  _getOverrideAuth = (req: Request, res: Response, next: NextFunction) => {
    next();
  };

  _get(req, res) {
    return res.json(listUsers());
  }

  // POST usa ancora l'authMiddleware globale (nessun override dichiarato)
  _post(req, res) {
    return res.json(createUser(req.body));
  }
}
export default Users;

Elysia

Non esiste un equivalente di _overrideAuth. L'auth per rotta sullo stack Elysia si fa nel modo idiomatico di Elysia (un guard / beforeHandle sul modulo di rotta, o un plugin con scope), non tramite una convenzione di Efesto.

Gestione degli errori (Express)

errorMiddleware è il secondo hook che passi a efesto(). È collegato alla catena Express così che gli errori lanciati e le chiamate next(err) lo raggiungano. Un pass-through è valido quando non hai nulla da gestire:

errorMiddleware: (req, res, next) => next();

Il controllo ABAC lancia un ForbiddenError di CASL quando un permesso fallisce: è l'errore che gestisci più spesso qui. Vedi Permessi ABAC.

Cosa Efesto non fa

Queste sono esigenze comuni, ma sono responsabilità della tua applicazione, non funzionalità del framework. Implementale all'interno del tuo middleware:

• Verifica/rinnovo del token, store di sessione, lookup delle API key, flussi OAuth.
• Rate limiting, header sicuri, CORS (usa middleware Express/Elysia standard).

Una volta autenticate le richieste, autorizzale con ABAC.