altcha

package module
v0.0.0-...-0000768 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 19, 2026 License: MIT Imports: 19 Imported by: 0

README

altcha

GitHub Workflow Status GoDoc

Package altcha is a middleware that provides self-hosted ALTCHA proof-of-work captchas for Flamego.

Installation

go get github.com/flamego/altcha

Getting started

<!-- templates/home.tmpl -->
<form method="POST">
  {{.AltchaHTML}}
  <button>Submit</button>
</form>
package main

import (
	"net/http"
	"os"

	"github.com/flamego/altcha"
	"github.com/flamego/flamego"
	"github.com/flamego/template"
)

func main() {
	f := flamego.Classic()
	f.Use(template.Templater())
	f.Use(altcha.Challenger(
		altcha.Options{
			Secret: []byte(os.Getenv("ALTCHA_SECRET")),
		},
	))
	f.Get("/", func(t template.Template, data template.Data, c altcha.Challenge) {
		data["AltchaHTML"] = c.HTML()
		t.HTML(http.StatusOK, "home")
	})
	f.Post("/", func(w http.ResponseWriter, r *http.Request, c altcha.Challenge) {
		if err := c.Verify(r.PostFormValue(altcha.FieldName)); err != nil {
			w.WriteHeader(http.StatusBadRequest)
			_, _ = w.Write([]byte(err.Error()))
			return
		}
		w.WriteHeader(http.StatusOK)
		_, _ = w.Write([]byte("Verified!"))
	})

	f.Run()
}

Getting help

License

This project is under the MIT License. See the LICENSE file for the full license text.

Documentation

Overview

Package altcha is a middleware that tells people from bots with a proof-of-work challenge: the browser spends a moment searching for a counter whose PBKDF2 key starts with a prefix signed by the server, and the server checks the answer with two HMACs. Nothing is shown to read and no third party is involved.

Challenges and solutions use the ALTCHA v3 format (https://altcha.org), so the official altcha-widget works as well as the widget this package serves.

Index

Constants

View Source
const FieldName = "altcha"

FieldName is the name of the form field the widget writes the solution to.

Variables

View Source
var (
	// ErrInvalid is returned when a solution is malformed, is not signed by this
	// server, or does not solve its challenge.
	ErrInvalid = errors.New("altcha: invalid solution")
	// ErrExpired is returned when a solution is valid but its challenge expired.
	ErrExpired = errors.New("altcha: challenge expired")
	// ErrReplayed is returned when a solution was already accepted once.
	ErrReplayed = errors.New("altcha: solution already used")
)

Functions

func Challenger

func Challenger(opts Options) flamego.Handler

Challenger returns a middleware handler that injects altcha.Challenge into the request context, and serves challenges and the widget script under URLPrefix.

Types

type Challenge

type Challenge interface {
	// HTML returns the HTML that renders the widget. Put it inside a form; the
	// widget writes its solution to the form field named FieldName.
	HTML() template.HTML
	// Verify verifies a solution submitted by the widget. Each solution is
	// accepted at most once. It returns ErrInvalid, ErrExpired, ErrReplayed, or
	// an error from the ReplayStore.
	Verify(payload string) error
}

Challenge is a proof-of-work service that renders the widget and verifies solutions.

type Options

type Options struct {
	// URLPrefix is the URL path prefix for serving challenges and the widget
	// scripts. A trailing slash is added when missing. Default is "/.altcha/".
	URLPrefix string
	// Secret is the key used to sign challenges. It is required, must be at
	// least 16 bytes of random data, and must be the same on every server that
	// verifies solutions.
	Secret []byte
	// Cost is the number of PBKDF2 iterations for each counter the browser
	// tries. Default is 5000.
	Cost int
	// MaxCounter is the largest counter a challenge can hide, up to
	// math.MaxUint32. The browser tries MaxCounter/2 counters on average, spread
	// over its CPU cores. Default is 500.
	MaxCounter int
	// Expiry is how long a challenge can be solved and submitted. Default is 5
	// minutes.
	Expiry time.Duration
	// Store records accepted solutions so they cannot be used twice. Default is
	// an in-memory store, which only works when a single process verifies
	// solutions.
	Store ReplayStore
}

Options contains options for the altcha.Challenger middleware.

type ReplayStore

type ReplayStore interface {
	// Use marks key as used until expiresAt. It returns false when key is
	// already marked and has not expired.
	Use(key string, expiresAt time.Time) (bool, error)
}

ReplayStore remembers which solutions were already accepted.

Directories

Path Synopsis
Command example serves a sign-up form protected by a proof-of-work check.
Command example serves a sign-up form protected by a proof-of-work check.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL