nonce

Documentation

Overview

Package nonce provides authentication middleware for agbero REST replay endpoints.

A replay endpoint is a serverless rest block with no fixed url — the target URL is supplied by the client at request time. Because the endpoint effectively proxies arbitrary upstream resources on behalf of a browser, it must be guarded so that only legitimate clients on the same agbero host can use it.

Three guard methods are supported, selected via auth.method in HCL:

meta   — agbero injects a single-use nonce into HTML responses served from
         the same host. Client JS reads it from

         and sends it back in the X-Agbero-Replay-Nonce header. Nonces are
         single-use and expire after a configurable TTL (default 1 h).
         Suitable for public pages.

token  — a short-lived scoped JWT is minted by agbero and fetched by the
         client from /.agbero/replay//token. The token is validated on
         every request. Suitable for pages behind agbero auth.

direct — a valid agbero session cookie (agbero_sess) is required on every
         request. Suitable when the page is already behind agbero's admin
         or OAuth auth.

Index

• Constants
• type Guard
  • func NewDirectGuard() *Guard
  • func NewMetaGuard(store *Store) *Guard
  • func NewTokenGuard(verify func(string) bool) *Guard
  • func (g *Guard) Middleware(next http.Handler) http.Handler
• type Store
  • func NewStore(ttl time.Duration) *Store
  • func (s *Store) Consume(nonce string) bool
  • func (s *Store) Generate() (string, error)
  • func (s *Store) Len() int
  • func (s *Store) StartSweeper(interval time.Duration, done <-chan struct{})

Constants

const (
	// DefaultNonceTTL is how long a generated nonce remains valid.
	DefaultNonceTTL = time.Hour
	// NonceBytes is the length of the random nonce in bytes (32 → 64 hex chars).
	NonceBytes = 32
)

Types

type Guard

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

Guard enforces replay authentication using one of three methods.

func NewDirectGuard

func NewDirectGuard() *Guard

NewDirectGuard creates a Guard that checks for an agbero session cookie.

func NewMetaGuard

func NewMetaGuard(store *Store) *Guard

NewMetaGuard creates a Guard that validates single-use nonces from store.

func NewTokenGuard

func NewTokenGuard(verify func(string) bool) *Guard

NewTokenGuard creates a Guard that validates Bearer JWTs using verify. verify must return true iff the token is valid and unexpired.

func (*Guard) Middleware

func (g *Guard) Middleware(next http.Handler) http.Handler

Middleware wraps next and enforces the guard. Unauthenticated requests receive 401; misconfigured guards receive 500.

type Store

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

Store is a lock-free, single-use nonce store backed by mappo.Concurrent.

Each nonce is consumed on first use. Expired nonces are swept lazily on access and periodically by the background goroutine started via StartSweeper.

func NewStore

func NewStore(ttl time.Duration) *Store

NewStore creates a Store with the given TTL. Zero → DefaultNonceTTL.

func (*Store) Consume

func (s *Store) Consume(nonce string) bool

Consume validates and removes the nonce atomically. Returns true only if the nonce exists and has not expired. A consumed or unknown nonce returns false.

func (*Store) Generate

func (s *Store) Generate() (string, error)

Generate creates a cryptographically random nonce, stores it, and returns its hex-encoded value. The nonce expires after the store's TTL.

func (*Store) Len

func (s *Store) Len() int

Len returns the number of nonces currently in the store. For tests and monitoring.

func (*Store) StartSweeper

func (s *Store) StartSweeper(interval time.Duration, done <-chan struct{})

StartSweeper launches a background goroutine that cleans up expired nonces every interval. The goroutine exits when done is closed.