altcha-lib 2.8.0

v2.8.0

on Node.js NPM

This release adds support for Nuxt 4 (#22). The H3 plugin (altcha-lib/frameworks/h3) works with both h3 v1 (Nuxt 4, Nitro 2) and h3 v2 (Nitro 3). It no longer fails with event.req.headers.get is not a function in Nuxt 4 projects.

Compatibility: no changes to challenges, payloads or verification results. The H3 plugin's handlers have new TypeScript types, and its errors are no longer instances of h3's HTTPError class; see Upgrade notes. Other framework plugins are unchanged.

Fixes

• Nuxt 4 / h3 v1 support. Nuxt 4 runs on h3 v1, but the plugin only supported h3 v2 and listed h3: ^2.0.0 as a peer dependency. Package managers such as pnpm therefore installed a second copy of h3 (v2) for altcha-lib. The plugin then used h3 v2 helpers on the h3 v1 events created by Nuxt, which failed. The plugin no longer imports h3 at runtime and handles both event formats itself, so it works whichever h3 version is installed for altcha-lib. The optional h3 peer dependency now accepts ^1.15.0 || ^2.0.0.
• Request body stays readable. The middleware reads the payload without consuming the request body, so handlers that run after it can still call readBody. On h3 v1, the body is cached where h3 v1's own readBody looks for it. On h3 v2, the middleware reads from a clone of the request. Before, the middleware used up the body on h3 v2.
• Errors are recognized by both h3 versions. Failed verification responds with 403, and an invalid JSON or form data body responds with 400. Both h3 v1 and v2 recognize these errors as HTTP errors. Before, h3 v1 treated them as unhandled errors: it logged them, and Nitro hid their message. An invalid multipart body used to cause an unhandled 500 error and now returns 400.
• Nuxt docs. The example in docs/nuxt.md puts route files under server/routes/, which Nuxt registers automatically. It imports from ~~/server/utils/altcha, because ~ points to app/ in Nuxt 4, and uses createError, which works in h3 v1 and v2.

Changes

• H3 handler types. challengeHandler, verifyHandler and the function returned by middleware() are plain async functions that take an H3EventLike (H3WebEvent | H3NodeEvent), all exported from altcha-lib/frameworks/h3. Before, they were typed as h3 v2's EventHandler. They can still be passed directly to h3 v1 and v2 routers and used as Nuxt or Nitro route handlers. getPayloadFromEvent also takes an H3EventLike.
• TypeScript 6. The library is built with TypeScript 6. The CommonJS build keeps moduleResolution: "node", with ignoreDeprecations: "6.0" in tsconfig.cjs.json. The emitted .d.ts files use the same import paths as before.

Upgrade notes

Most deployments need no changes.

• Nuxt 4. Upgrade altcha-lib. If you added h3@2 to your project, or an overrides/resolutions entry, to work around the error, remove it.
• Checking errors with instanceof HTTPError. The plugin's errors are no longer created with h3's HTTPError. If your error handler checks error instanceof HTTPError, use HTTPError.isError(error) (h3 v2) or isError(error) (h3 v1) instead, or check error.statusCode. Both return true for the plugin's errors.

Full changelog: v2.7.0...v2.8.0