passit.go

// Package passit provides a password generation toolkit. It features a variety of
// different password generators from charsets to regular expressions and emoji.
//
// All generators implement [Generator]. Once a suitable [Generator] has been
// constructed, passwords can be generated by calling the [Generator].Password
// method. All generators in this package are deterministic unless otherwise noted.
//
// Most generators only generate a single of something, be it a rune, ASCII
// character or word. For generating longer passwords use [Repeat] or
// [RandomRepeat], possibly with [Join] or [Alternate]. In this way the various
// generators can be composed to generator arbitrarily long and complex passwords,
// or short and simple passwords as is needed.
//
// For generating random passwords, [Generator].Password should be called with
// [crypto/rand.Reader]. Avoid using poor quality sources of randomness like
// [math/rand].
//
// For generating deterministic passwords, [Generator].Password should be called
// with a deterministic stream that should be indistinguishable from a random string
// of the same length. Care must be taken when using deterministic password
// generation as the generated password is only ever as good as the provided source
// of randomness.
//
// Note: Wrapping the [io.Reader] with [bufio.NewReader] (if it doesn't already
// implement [io.ByteReader]) will greatly improve the performance of the
// generators.
package passit

import "io"

// Generator is an interface for generating passwords.
type Generator interface {
	// Password returns a randomly generated password using r as the source of
	// randomness.
	//
	// The returned password may or may not be deterministic with respect to r.
	// All generators in this package are deterministic unless otherwise noted.
	//
	// The output of r should be indistinguishable from a random string of the
	// same length. This is a property of a good CSPRNG. Fundamentally the
	// strength of the generated password is only as good as the provided source
	// of randomness.
	//
	// r should implement the io.ByteReader interface for improved performance.
	Password(r io.Reader) (string, error)
}

// The GeneratorFunc type is an adapter to allow the use of ordinary functions as
// password generators. If f is a function with the appropriate signature,
// GeneratorFunc(f) is a Generator that calls f.
type GeneratorFunc func(r io.Reader) (string, error)

// Password implements Generator, calling f(r).
func (f GeneratorFunc) Password(r io.Reader) (string, error) {
	return f(r)
}