Salta al contenuto principale

04 - Bun e Hono: un'API edge minimale con JWT e Zod

Un'API Hono con JWT, validazione Zod e SQLite, provata su Bun e Node senza aprire porte: struttura, trappole del middleware e limiti dell'edge.

Cosa ne pensi di questo articolo?

04 - Bun e Hono: un'API edge minimale con JWT e Zod
Bun Runtime 2027Foto:SiddePexels

In Breve

Un'API Hono con JWT, validazione Zod e SQLite, provata su Bun e Node senza aprire porte: struttura, trappole del middleware e limiti dell'edge.

Un'API piccola che non dipende da dove gira

Una API REST con login, un archivio e la validazione dei dati richiede di solito un framework, un driver di database e qualche libreria. Hono permette di scriverla come una funzione che riceve una Request e restituisce una Response, gli stessi oggetti del web, e di eseguirla su runtime diversi. Questo è il senso di «edge» che l'articolo difende: non che Bun giri sull'edge, ma che il codice dell'API non conosca il runtime. Il runtime lo scegli all'ultimo momento.

Qui costruisco una API con tre funzioni: un login che emette un token JWT, un elenco di articoli protetto dal token, e un inserimento validato con Zod. Ho eseguito tutto con Bun 1.4.4 e Node 24.11.0 (novembre 2026), con Hono 4.13.18, @hono/zod-validator 0.9.1 e Zod 4.6.7. Le prove chiamano il metodo fetch dell'applicazione direttamente, senza aprire porte, quindi i risultati sono riproducibili ovunque. Per chi arriva da questa serie: SQLite lo abbiamo visto nell'articolo su SQLite e Redis in Bun, e il confronto con gli altri runtime è in Bun, Node e Deno.

Setup: tre pacchetti

Il progetto parte da un package.json con "type": "module" e un solo comando di installazione. Fissare le versioni (il lockfile lo fa per te) conta qui più del solito, perché le API dei middleware cambiano fra versioni minori: come vedremo, il middleware JWT oggi richiede un'opzione che molti tutorial non conoscono.

installazione delle dipendenze con bun add
$ bun add hono @hono/zod-validator zod
installed hono@4.13.18
installed @hono/zod-validator@0.9.1
installed zod@4.6.7

3 packages installed

Hono è il framework, Zod descrive e verifica la forma dei dati, e @hono/zod-validator li collega come middleware. Non serve altro: JWT, CORS e gestione degli errori sono già dentro Hono, e SQLite viene dal runtime.

L'applicazione: una funzione che riceve le sue dipendenze

Il file app.ts esporta una funzione creaApp invece di un'applicazione già pronta. Le due cose che cambiano fra ambienti, l'archivio dei dati e i segreti, entrano come argomenti. Questo permette di provare l'API con un archivio in memoria, di metterla in produzione con SQLite, e di non scrivere mai i segreti nel codice.

app.ts
import { timingSafeEqual } from "node:crypto";
import { Hono } from "hono";
import { HTTPException } from "hono/http-exception";
import { jwt, sign } from "hono/jwt";
import { zValidator } from "@hono/zod-validator";
import { z } from "zod";

export interface Articolo { id: number; titolo: string; testo: string }
export interface Store {
  elenco(): Articolo[];
  crea(titolo: string, testo: string): Articolo;
}

const NuovoArticolo = z.object({
  titolo: z.string().min(5).max(200),
  testo: z.string().min(10),
});

const uguali = (a: string, b: string) => {
  const x = Buffer.from(a), y = Buffer.from(b);
  return x.length === y.length && timingSafeEqual(x, y);
};

export function creaApp(store: Store, env: { JWT_SECRET: string; ADMIN_PASSWORD: string }) {
  const app = new Hono();

  app.get("/health", (c) => c.json({ stato: "ok" }));

  app.post("/login", async (c) => {
    const { password } = await c.req.json().catch(() => ({ password: "" }));
    if (typeof password !== "string" || !uguali(password, env.ADMIN_PASSWORD)) {
      return c.json({ errore: "credenziali non valide" }, 401);
    }
    const scadenza = Math.floor(Date.now() / 1000) + 15 * 60; // 15 minuti
    return c.json({ token: await sign({ sub: "admin", exp: scadenza }, env.JWT_SECRET, "HS256") });
  });

  // Tutto ciò che sta sotto /api richiede un token valido
  app.use("/api/*", jwt({ secret: env.JWT_SECRET, alg: "HS256" }));

  app.get("/api/articoli", (c) => c.json(store.elenco()));

  app.post("/api/articoli", zValidator("json", NuovoArticolo), (c) => {
    const { titolo, testo } = c.req.valid("json");
    return c.json(store.crea(titolo, testo), 201);
  });

  app.onError((err, c) => {
    // 401, 403, 400 lanciati dai middleware sono HTTPException: hanno già la loro risposta
    if (err instanceof HTTPException) return err.getResponse();
    console.error(err); // il dettaglio resta nel log, al client non va
    return c.json({ errore: "errore interno" }, 500);
  });
  return app;
}

Le parti che contano, in ordine. L'interfaccia Store descrive cosa l'API chiede all'archivio (elencare e creare) senza dire come: è ciò che permette di cambiare SQLite con altro. Il login confronta la password con timingSafeEqual da node:crypto, che richiede tempo costante: un confronto con === si ferma al primo carattere diverso, e il tempo di risposta può rivelare quanti caratteri erano giusti. Il token riceve una scadenza di 15 minuti nel claim exp, che la RFC 7519 definisce come il momento oltre il quale il token non deve essere accettato. Il middleware jwt protegge tutto ciò che sta sotto /api, mentre /health e /login restano pubblici perché il middleware è agganciato solo al percorso /api/*.

La validazione è dichiarata nello schema NuovoArticolo: titolo da 5 a 200 caratteri, testo di almeno 10. zValidator("json", ...) la applica prima del gestore, che quindi riceve dati già verificati e tipizzati con c.req.valid("json"). Se la verifica fallisce, risponde 400 senza che il tuo codice parta. I limiti qui sono esempi miei, non una regola di Hono: decidili in base a ciò che il tuo database e la tua interfaccia possono accettare.

Gli archivi: SQLite per il runtime, memoria per i test

L'implementazione con SQLite usa bun:sqlite, quindi gira solo con Bun. Apre il database in modalità strict, attiva WAL, e prepara le due istruzioni una volta. RETURNING fa restituire all'INSERT la riga appena creata, con l'identificativo assegnato, senza una seconda query.

store-sqlite.ts
import { Database } from "bun:sqlite";
import type { Articolo, Store } from "./app.ts";

export function storeSqlite(file = ":memory:"): Store {
  const db = new Database(file, { strict: true });
  db.run("PRAGMA journal_mode = WAL");
  db.run(`CREATE TABLE IF NOT EXISTS articoli (
    id INTEGER PRIMARY KEY, titolo TEXT NOT NULL, testo TEXT NOT NULL)`);
  const tutti = db.query("SELECT id, titolo, testo FROM articoli ORDER BY id");
  const inserisci = db.query(
    "INSERT INTO articoli (titolo, testo) VALUES ($titolo, $testo) RETURNING id, titolo, testo",
  );
  return {
    elenco: () => tutti.all() as Articolo[],
    crea: (titolo, testo) => inserisci.get({ titolo, testo }) as Articolo,
  };
}

La versione in memoria (store-memoria.ts, un array con un contatore) ha la stessa forma e gira ovunque. Ha una funzione precisa: i test dell'API non devono dipendere da un file su disco, e il test di portabilità fra runtime non può importare un modulo che esiste solo in Bun.

Provarla senza avviare un server

Un'applicazione Hono ha un metodo fetch(request). Chiamarlo equivale a ricevere una richiesta HTTP, ma senza rete: ideale per i test e per questo articolo, che non apre porte. Lo script costruisce le richieste, le passa all'app e stampa stato e inizio del corpo. Include i casi che contano in una API protetta: senza token, con credenziali sbagliate, con dati non validi, con un token alterato e con un token firmato bene ma scaduto.

prova.ts (il listato di sopra, eseguito con «bun prova.ts»)
import { sign } from "hono/jwt";
import { creaApp } from "./app.ts";
import { storeInMemoria } from "./store-memoria.ts";

const env = { JWT_SECRET: "segreto-solo-per-la-prova", ADMIN_PASSWORD: "password-di-prova" };
const store = process.env.STORE === "sqlite"
  ? (await import("./store-sqlite.ts")).storeSqlite()
  : storeInMemoria();
const app = creaApp(store, env);

// app.fetch riceve una Request e restituisce una Response: nessuna porta aperta
async function chiama(metodo: string, percorso: string, corpo?: unknown, token?: string) {
  const res = await app.fetch(new Request(`http://prova${percorso}`, {
    method: metodo,
    headers: {
      ...(corpo ? { "content-type": "application/json" } : {}),
      ...(token ? { authorization: `Bearer ${token}` } : {}),
    },
    body: corpo ? JSON.stringify(corpo) : undefined,
  }));
  return { stato: res.status, testo: await res.text() };
}
const riga = (etichetta: string, r: { stato: number; testo: string }) =>
  console.log(`${etichetta.padEnd(18)}${r.stato}  ${r.testo.slice(0, 60)}`);

const runtime = typeof Bun !== "undefined" ? `bun ${Bun.version}` : `node ${process.versions.node}`;
console.log(`${runtime}, store ${process.env.STORE ?? "memoria"}`);
riga("health", await chiama("GET", "/health"));
riga("api senza token", await chiama("GET", "/api/articoli"));
riga("login sbagliato", await chiama("POST", "/login", { password: "no" }));

const login = await chiama("POST", "/login", { password: env.ADMIN_PASSWORD });
const token = JSON.parse(login.testo).token as string;
console.log("token".padEnd(18) + `${login.stato}  ${token.split(".").length} parti separate da punti`);

riga("crea valido", await chiama("POST", "/api/articoli", { titolo: "Primo articolo", testo: "Testo abbastanza lungo" }, token));
riga("crea non valido", await chiama("POST", "/api/articoli", { titolo: "x" }, token));
riga("elenco", await chiama("GET", "/api/articoli", undefined, token));
riga("token alterato", await chiama("GET", "/api/articoli", undefined, token.slice(0, -2) + "xx"));

// Un token firmato bene ma già scaduto (exp un'ora fa)
const scaduto = await sign({ sub: "admin", exp: Math.floor(Date.now() / 1000) - 3600 }, env.JWT_SECRET, "HS256");
riga("token scaduto", await chiama("GET", "/api/articoli", undefined, scaduto));

// Output:
// bun 1.4.4, store memoria
// health            200  {"stato":"ok"}
// api senza token   401  Unauthorized
// login sbagliato   401  {"errore":"credenziali non valide"}
// token             200  3 parti separate da punti
// crea valido       201  {"id":1,"titolo":"Primo articolo","testo":"Testo abbastanza 
// crea non valido   400  {"success":false,"error":{"name":"ZodError","message":"[\n  
// elenco            200  [{"id":1,"titolo":"Primo articolo","testo":"Testo abbastanza
// token alterato    401  Unauthorized
// token scaduto     401  Unauthorized

Le nove righe di risultato dicono che il sistema si comporta come deve: 401 senza token, 401 con una password sbagliata (senza dire se l'errore era l'utente o la password), 201 sulla creazione, 400 sui dati non validi, e 401 sia per il token alterato sia per quello scaduto. Il corpo della risposta 400 è l'errore di Zod così com'è, con la struttura interna della libreria: per un'API pubblica conviene sostituirlo con un messaggio tuo, perché espone dettagli che non servono a chi chiama.

La portabilità l'ho verificata, non assunta. Ho rieseguito lo stesso prova.ts con STORE=sqlite bun prova.ts e con node prova.ts (Node 24 esegue direttamente il TypeScript, vedi l'articolo di confronto): le nove righe dopo l'intestazione sono identiche byte per byte, e ho confrontato le tre uscite con una somma di controllo. L'applicazione Hono è la stessa; cambia solo l'archivio, e quello in SQLite funziona solo con Bun.

Due trappole che ho trovato eseguendola

La prima: il middleware JWT di Hono richiede l'opzione alg, l'algoritmo di firma. Molti esempi in rete la omettono perché risalgono a versioni precedenti; con la 4.13 Hono rifiuta di registrare il middleware. La seconda è meno evidente. Un onError globale che trasforma tutto in 500 intercetta anche le HTTPException che i middleware lanciano per segnalare 401 e 403: una richiesta senza token restituirebbe 500 invece di 401, e i tuoi allarmi sui 500 suonerebbero a ogni scansione. Lo script riproduce entrambe.

guasti.ts
import { Hono } from "hono";
import { jwt } from "hono/jwt";

// 1) jwt() senza l'algoritmo: Hono rifiuta di partire
try {
  // @ts-expect-error alg è obbligatorio nel tipo
  new Hono().use("/api/*", jwt({ secret: "s" }));
} catch (e) {
  console.log("senza alg:", (e as Error).message);
}

// 2) onError che trasforma ogni errore in 500, comprese le 401 dei middleware
const app = new Hono();
app.use("/api/*", jwt({ secret: "s", alg: "HS256" }));
app.get("/api/x", (c) => c.text("ok"));
app.onError((_err, c) => c.json({ errore: "errore interno" }, 500));
const res = await app.fetch(new Request("http://prova/api/x"));
console.log("onError ingenuo, richiesta senza token ->", res.status);

// Output:
// senza alg: JWT auth middleware requires options for "alg"
// onError ingenuo, richiesta senza token -> 500

Il messaggio della prima prova indica quale opzione manca, e il numero della seconda è il bug: 500 dove doveva esserci 401. Il rimedio è nella versione di app.ts sopra: dentro onError, se l'errore è un'HTTPException restituisci la sua risposta con err.getResponse(), come descrive la documentazione, e solo per gli altri errori registri il dettaglio nel log e rispondi con un messaggio generico. Il dettaglio non va mai al client: uno stack trace in una risposta racconta a chi attacca come è fatto il tuo codice.

Avviarla: il file principale esporta fetch

Per mettere in ascolto l'API, Bun non richiede Bun.serve esplicito: se il file principale esporta come default un oggetto con fetch e, opzionalmente, port, avvia da solo il server. Il file index.ts legge i segreti dall'ambiente e si rifiuta di partire se mancano, invece di ripiegare su un valore di comodo: un segreto di sviluppo dimenticato in produzione è uno dei modi più comuni di rendere inutile la firma dei token.

index.ts (avvio con «JWT_SECRET=... ADMIN_PASSWORD=... bun index.ts»)
import { creaApp } from "./app.ts";
import { storeSqlite } from "./store-sqlite.ts";

const { JWT_SECRET, ADMIN_PASSWORD, DB_FILE = "dati.db", PORT = "3000" } = process.env;
if (!JWT_SECRET || !ADMIN_PASSWORD) {
  throw new Error("Servono JWT_SECRET e ADMIN_PASSWORD nell'ambiente");
}

const app = creaApp(storeSqlite(DB_FILE), { JWT_SECRET, ADMIN_PASSWORD });

// Bun avvia da solo un server se il file principale esporta { fetch }
export default { port: Number(PORT), fetch: app.fetch };

Questo listato non l'ho avviato come server, perché aprirebbe una porta; ne ho però importato il modulo da uno script separato per verificare le due cose che non dipendono dalla rete. Senza le variabili d'ambiente l'importazione fallisce con «Servono JWT_SECRET e ADMIN_PASSWORD nell'ambiente». Con le variabili impostate, il modulo esporta la porta 3000 e una funzione fetch che risponde 200 a /health. Il comportamento di ascolto sulla porta, invece, è quello descritto dalla documentazione di Bun e di Hono, e va provato da te.

Che cosa significa «edge» qui, e dove finisce

La documentazione di Hono presenta il framework come costruito sugli standard del web, e prevede guide di avvio per Bun, Cloudflare Workers e altri ambienti. In pratica significa che creaApp si può portare su un runtime a basso avvio senza riscriverla. Le cose da sapere prima di dire «gira sull'edge» sono tre.

  • Il database: bun:sqlite esiste solo in Bun; su un altro runtime l'archivio va riscritto con quello che offre.
  • Lo stato: un array in memoria vive quanto il processo, e se le istanze sono più d'una ciascuna ha il suo.
  • I segreti: ogni piattaforma ha il suo modo di passarli; la funzione creaApp li riceve come argomento proprio per questo.

Il filo comune è che la portabilità riguarda il codice delle rotte, non l'infrastruttura intorno. Il tuo lavoro è tenere le rotte pulite da tutto ciò che è specifico del runtime e mettere ciò che è specifico dietro interfacce piccole, come lo Store qui. Ho provato il codice su Bun e Node; non l'ho provato su Cloudflare Workers, e chi lo usa deve verificare i propri limiti.

Domande frequenti

Hono funziona anche su Node?

Sì per quanto riguarda l'applicazione: lo stesso prova.ts è stato eseguito con Node 24 e con l'archivio in memoria dando le stesse risposte. Per mettere Hono in ascolto su Node serve un adattatore dedicato, che qui non ho provato. L'archivio in SQLite, invece, dipende da Bun.

Posso tenere il token in un cookie invece che nell'intestazione?

Il middleware JWT di Hono lo prevede, con un'opzione per il nome del cookie, e il codice del middleware che ho letto contiene il ramo per i cookie. Un cookie protegge dalla lettura via JavaScript se è HttpOnly, ma ti espone a richieste da altri siti, quindi richiede una difesa aggiuntiva; l'intestazione Authorization non ha quel problema.

Come invalido un token prima della scadenza?

Con un JWT firmato non puoi, finché non cambia il segreto o non tieni un elenco di token revocati. Per questo la scadenza è breve (qui 15 minuti): è il costo che accetti in cambio di non interrogare il database a ogni richiesta.

Che cosa sai fare adesso

Sai strutturare una API Hono come una funzione che riceve le sue dipendenze, proteggerla con un JWT che scade e confronti a tempo costante, validare i dati prima del gestore, provarla chiamando fetch senza aprire porte, e riconoscere le due trappole che fanno rispondere 500 al posto di 401. Il passo successivo è metterla in un container: Bun in produzione con Docker e Kubernetes.

Fonti

Commenti

Caricamento commenti...

Accedi per commentare

Articoli e strumenti nuovi anche su Telegram

Il canale Telegram segnala gli articoli e gli strumenti nuovi del sito.

Ti è piaciuto questo articolo?

Esplora altri contenuti sul blog o scopri i miei progetti