captchouli

README

captchouli

booru-backed procedurally-generated anime image captcha library and server

Captchouli scrapes boorus for admin-defined tags and generates and verifies captchas for user anti-bot authentication.

Installation

1. Install OpenCV >= 4.0 development library (libopencv-dev on Debian-based systems)
2. Install Go >= 1.10
3. Run go install github.com/bakape/captchouli/cmd/captchouli@latest
4. The captchouli server binary will be located under $HOME/go/bin/captchouli, if the default $GOPATH is used.

Usage

Captchouli can be used as either a library or standalone server.

Server

Run captchouli --help for a list CLI flags.

After the server has been started and the inital tag pool populated captchouli can be accessed using a HTTP API:

Method	Address	Receives	Returns
GET	/	Optional query parameters "captchouli-color" and "captchouli-background" for overriding the default captcha text colour and background	New captcha form HTML
POST	/	Form data from the user	Either the ID of the solved captcha on success or a redirect to a fresh captcha, if incorrectly solved
POST	/status	"captchouli-id" parameter - the ID of the captcha you wish to check the status of	"true", if captcha exists and has been solved or "false" otherwise. Note that this unregisters the captcha to prevent reply-again attacks.

Advanced use cases

For more advanced use cases please refer to the Go API documented here .

Documentation

Index

• Constants
• Variables
• func CheckCaptcha(id [64]byte, solution []byte) error
• func Close() error
• func DecodeID(s string) (id [64]byte, err error)
• func ExtractCaptcha(r io.Reader) (id [64]byte, solution []byte, err error)
• func ExtractID(r *http.Request) (id [64]byte, err error)
• func ExtractSolution(r *http.Request) (solution []byte, err error)
• func Open() error
• func ServeStatus(w http.ResponseWriter, r *http.Request) (err error)
• type DataSource
• type Error
• type Options
• type Rating
• type Service
  • func NewService(opts Options) (s *Service, err error)
  • func (s *Service) NewCaptcha(w io.Writer, colour, background string) (id [64]byte, err error)
  • func (s *Service) Router() *httprouter.Router
  • func (s *Service) ServeCheckCaptcha(w http.ResponseWriter, r *http.Request) (err error)
  • func (s *Service) ServeNewCaptcha(w http.ResponseWriter, r *http.Request) (err error)

Constants

const (
	// Keys used as names for input elements in captcha form HTML
	IDKey         = common.IDKey
	ColourKey     = common.ColourKey
	BackgroundKey = common.BackgroundKey
)

const (
	Gelbooru = common.Gelbooru
	Danbooru = common.Danbooru
)

Variables

var (

	// Signifies the client had solved the captcha incorrectly
	ErrInvalidSolution = Error{errors.New("invalid captcha solution")}

	// Captcha ID is of invalid format
	ErrInvalidID = Error{errors.New("invalid captcha id")}
)

var (
	// No faces detected in downloaded image
	ErrNoFace = Error{fmt.Errorf("no faces detected")}
)

Functions

func CheckCaptcha

func CheckCaptcha(id [64]byte, solution []byte) error

Check a captcha solution for validity. solution: slice of selected image numbers

func Close

func Close() error

Close open resources

func DecodeID

func DecodeID(s string) (id [64]byte, err error)

Decode captcha ID from base64 string

func ExtractCaptcha

func ExtractCaptcha(r io.Reader) (id [64]byte, solution []byte, err error)

Extract captcha from GZipped HTML body and return together with its solution

func ExtractID

func ExtractID(r *http.Request) (id [64]byte, err error)

Decode captcha ID from POST request

func ExtractSolution

func ExtractSolution(r *http.Request) (solution []byte, err error)

Extact captcha ID and solution from request

func Open

func Open() error

Init storage and start the runtime

func ServeStatus

func ServeStatus(w http.ResponseWriter, r *http.Request) (err error)

Serve captcha solved status. The captcha is deleted on a successful check to prevent replayagain attacks.

Types

type DataSource

type DataSource = common.DataSource

Source of image database to use for captcha image generation

type Error

type Error = common.Error

Generic error with prefix string

type Options

type Options struct {
	// Silence non-error log outputs
	Quiet bool

	// Allow images with varying explicitness. Defaults to only Safe.
	Explicitness []Rating

	// Tags to source for captcha solutions. One tag is randomly chosen for each
	// generated captcha. Required to contain at least 3 tags.
	//
	// Note that you can only include tags that are discernable from the
	// character's face, such as who the character is (example: "cirno") or a
	// facial feature of the character (example: "smug").
	Tags []string
}

Options passed on Service creation

type Rating

type Rating = boorufetch.Rating

Explicitness rating of image

const (
	Safe Rating = iota
	Questionable
	Explicit
)

type Service

type Service struct {
	// contains filtered or unexported fields
}

Encapsulates a configured captcha-generation and verification service

func NewService

func NewService(opts Options) (s *Service, err error)

Create new captcha-generation and verification service

func (*Service) NewCaptcha

func (s *Service) NewCaptcha(w io.Writer, colour, background string,
) (id [64]byte, err error)

Creates a new captcha, writes its HTML contents to w and returns captcha ID.

Depending on what type w is, you might want to buffer the output with bufio.NewWriter.

func (*Service) Router

func (s *Service) Router() *httprouter.Router

Creates a routed handler for serving the API. The router implements http.Handler.

func (*Service) ServeCheckCaptcha

func (s *Service) ServeCheckCaptcha(w http.ResponseWriter, r *http.Request,
) (err error)

Serve POST requests for captcha solution validation

func (*Service) ServeNewCaptcha

func (s *Service) ServeNewCaptcha(w http.ResponseWriter, r *http.Request,
) (err error)

Generate new captcha and serve its HTML form