npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@tayho/nestjs-altcha

v0.1.0

Published

Self-hosted ALTCHA proof-of-work bot protection for NestJS, with an optional Better Auth plugin

Readme

@tayho/nestjs-altcha

npm CI License: MIT

Bot protection for NestJS with ALTCHA – self-hosted, no third-party service, no cookies. The browser solves a small proof-of-work challenge in the background; your backend verifies the solution and claims it so it cannot be reused.

The package offers two integrations on top of one shared verifier:

| Integration | Import | Protects | |-------------|--------|----------| | Nest guard @RequireAltcha() | @tayho/nestjs-altcha | your own controller routes, e.g. POST /public/bookings | | Better Auth plugin altcha() | @tayho/nestjs-altcha/better-auth | Better Auth routes, e.g. magic link, email OTP, sign-in |

Both share configuration and replay protection: a solution is accepted exactly once, no matter which route it is used on. Better Auth is an optional peer dependency – without it you only use the main entry point.

This is an independent community package and is not affiliated with the ALTCHA project.

Requirements

  • Node.js ≥ 22.12 (Better Auth is ESM-only and is loaded from CommonJS via require(esm))
  • @nestjs/common 11 or 12
  • optionally better-auth ≥ 1.7
  • TypeScript with moduleResolution set to node16, nodenext or bundler (for the /better-auth subpath)
  • the altcha widget ≥ 3 in the frontend

Installation

npm install @tayho/nestjs-altcha

Quick start

1. Register the verifier

import { AltchaModule } from "@tayho/nestjs-altcha";

@Module({
    imports: [
        AltchaModule.forRootAsync({
            inject: [ConfigService],
            useFactory: (config: ConfigService) => ({
                // one secret per application, at least 32 characters
                hmacSecret: config.getOrThrow<string>("ALTCHA_HMAC_SECRET"),
            }),
        }),
    ],
})
export class AppModule {}

The module is global. AltchaModule.forRoot(verifierOrOptions) is available as well if you create the verifier yourself.

2. Protect routes

import { RequireAltcha } from "@tayho/nestjs-altcha";

@Controller("public/bookings")
export class PublicBookingController {
    @RequireAltcha()
    @Post()
    createBooking(@Body() dto: CreateBookingDto) {
        // …
    }
}

@RequireAltcha() also works on the controller class. The guard runs after global guards (session, rate limiting) and before pipes. It reads the solution from the x-altcha header, falling back to the altcha body field (JSON or application/x-www-form-urlencoded). The body field is removed before validation so that strict schemas do not reject it as an unknown key. The result is available in the handler as request.altcha.

  • Multipart uploads: with multipart/form-data (Multer, FileInterceptor) the body is still empty when the guard runs. Send the solution in the header.
  • HTTP only: in other contexts (WebSockets, microservices, GraphQL) the guard always rejects.

3a. Challenge endpoint with Better Auth

The plugin serves <basePath>/altcha/challenge (with the default base path: /api/auth/altcha/challenge) and protects the configured auth routes. Pass the same verifier instance as the Nest module – with @thallesp/nestjs-better-auth via inject:

import { ALTCHA_VERIFIER, type AltchaVerifier } from "@tayho/nestjs-altcha";
import { altcha } from "@tayho/nestjs-altcha/better-auth";

BetterAuthModule.forRootAsync({
    inject: [ALTCHA_VERIFIER],
    useFactory: (verifier: AltchaVerifier) => ({
        auth: betterAuth({
            // …
            plugins: [
                altcha({
                    verifier,
                    endpoints: ["/sign-in/magic-link", "/email-otp/send-verification-otp", "/sign-in/email"],
                }),
            ],
        }),
    }),
});
  • Without endpoints, /sign-up/email, /sign-in/email, /sign-in/magic-link, /email-otp/send-verification-otp and /request-password-reset are protected. A custom list replaces these entirely. A trailing * matches one segment, ** any number of segments.
  • The solution must be sent in the header. Better Auth endpoints accept JSON only; a body field is not evaluated.
  • Only HTTP requests are checked (onRequest). Server-side calls via auth.api.* are not affected. OPTIONS and HEAD requests (CORS preflight) are not checked.
  • Protected paths are resolved relative to the path of baseURL, exactly like the Better Auth router does. This also holds when baseURL or BETTER_AUTH_URL contains a path.
  • The challenge endpoint requires no session, sends Cache-Control: no-store and is rate limited to 30 requests per minute (challengeRateLimit) when the Better Auth rate limiter is enabled. Behind a reverse proxy, Better Auth must be able to detect the client IP (advanced.ipAddress.ipAddressHeaders, e.g. ["x-real-ip"] with Traefik). Otherwise all visitors share one counter, and a single client could block challenge requests – and with them every protected sign-in – for everybody.

3b. Challenge endpoint without Better Auth

import { InjectAltchaVerifier, type AltchaVerifier } from "@tayho/nestjs-altcha";

@Controller("public/altcha")
export class AltchaController {
    constructor(@InjectAltchaVerifier() private readonly verifier: AltchaVerifier) {}

    @Throttle({ default: { limit: 10, ttl: 60_000 } })
    @Header("Cache-Control", "no-store")
    @Get("challenge")
    challenge() {
        return this.verifier.createChallenge();
    }
}

4. Frontend

<altcha-widget challenge="/api/auth/altcha/challenge" auto="onload"></altcha-widget>
<script type="module">import "altcha";</script>

The widget stores the solution in a hidden altcha input. For classic form posts that is all you need. For JSON requests send it as a header:

const payload = (document.querySelector('input[name="altcha"]') as HTMLInputElement).value;

await fetch("/api/public/bookings", {
    method: "POST",
    headers: { "content-type": "application/json", "x-altcha": payload },
    body: JSON.stringify(data),
});
await authClient.signIn.magicLink({ email }, { headers: { "x-altcha": payload } });

Each solution is accepted only once. After a failed request, reset the widget (widget.reset()) so it fetches a new challenge.

Configuration

Options for createAltchaVerifier(options) and AltchaModule.forRoot(options):

| Option | Default | Description | |--------|---------|-------------| | hmacSecret | – | required, at least 32 characters, one secret per application | | algorithm | "PBKDF2/SHA-256" | also PBKDF2/SHA-384/512, SHA-256/384/512 | | cost | 5000 | cost per attempt (PBKDF2: iterations) | | counter | { min: 5000, max: 10000 } | range of attempts the browser has to compute on average | | expiresInSeconds | 600 | lifetime of a challenge | | store | createMemoryReplayStore() | replay protection | | header | "x-altcha" | header carrying the solution | | fieldName | "altcha" | body field used as fallback | | maxPayloadLength | 8192 | longer payloads are rejected without verification | | onStoreError | console.error | called when the replay store throws, e.g. for your own logging |

The defaults for algorithm, cost and counter follow the recommendation of altcha-lib. Thanks to the key signature, server-side verification costs only a few HMAC computations, regardless of the difficulty.

Solving time in the browser grows roughly with cost × counter. Measured with the real widget v3 in headless Chromium on 2 CPU cores: defaults about 9 s, counter 1000–2000 about 1.3 s, 2000–4000 about 2.1 s. Current desktop browsers and phones with more cores are faster, older phones slower. With auto="onload" the widget computes while the visitor fills in the form. For short forms (email address only) choose a smaller counter.

Replay protection

  • createMemoryReplayStore({ maxSize }) – in-process, the default. Sufficient for a single instance. A restart only opens a window for solutions whose challenge has not expired yet. Choose maxSize (default 10,000) well above the number of submissions within expiresInSeconds: when the limit is reached, expired entries are purged and then the oldest claim is evicted – that solution could be reused once.
  • createRedisReplayStore(redis, { keyPrefix }) – for multiple instances. Expects a client with set(key, value, "EX", ttl, "NX"), such as ioredis.
import Redis from "ioredis";
import { createRedisReplayStore } from "@tayho/nestjs-altcha";

const store = createRedisReplayStore(new Redis(redisUrl), { keyPrefix: "myapp:altcha:" });

Custom stores implement claim(id, ttlSeconds): claim atomically and return true if the id was new.

Solutions are claimed only after successful verification, so failed attempts cannot fill up the store.

Error responses

The Nest guard and the Better Auth plugin both respond with 403 when verification fails (503 for store_unavailable):

{ "code": "ALTCHA_FAILED", "reason": "replayed", "message": "ALTCHA verification failed" }

| reason | Meaning | |----------|---------| | missing | no solution in the request | | malformed | not valid base64 JSON, wrong structure or too long | | expired | challenge has expired | | invalid_signature | challenge not issued by this server, or tampered with | | invalid_solution | wrong solution | | replayed | solution has already been used | | store_unavailable | replay store unavailable (e.g. Redis outage); rejected because reuse could not be ruled out. Errors are passed to onStoreError. |

What ALTCHA does – and what it does not

Proof of work makes automated requests more expensive; it does not prevent them. A determined attacker simply computes the challenges. Use ALTCHA in addition to server-side limits (rate limits per IP and per email address, business rules such as "one pending reservation per email"), not instead of them.

Development

npm install
npm run typecheck
npm test               # Vitest: verifier, stores, Nest guard, Better Auth plugin
npm run build
npm run test:widget    # real widget v3 in Chromium against dist/ (set CHROMIUM_PATH)

ALTCHA_COUNTER_MAX and ALTCHA_COST let test:widget measure the solving time for other parameters.

Releasing

Releases are published to npm by GitHub Actions (.github/workflows/release.yml) using trusted publishing, with provenance.

  1. Update version in package.json and add an entry to CHANGELOG.md.
  2. Commit, then create and push a matching tag: git tag v0.2.0 && git push origin main --tags.
  3. The workflow verifies that the tag matches package.json, runs type checks, tests and the build, and publishes.

License

MIT © Tayho Solutions