Go Fraud Detection Middleware, Without an SDK

<!-- templates/signup.html -->
<script async src="https://maskbreak.com/assets/sentinel.js"></script>

<form method="post" action="/signup" class="monocle-enriched">
  <input type="email" name="email" required>
  <input type="password" name="password" required>
  <button type="submit">Create account</button>
</form>

package fraud

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
	"time"
)

// "watch" (default) or "enforce".
var Mode = func() string {
	if m := os.Getenv("MASKBREAK_MODE"); m != "" {
		return m
	}
	return "watch"
}()

type Client struct {
	Key  string
	HTTP *http.Client
}

func New(key string) *Client {
	// One shared client keeps connections alive: a fresh TLS handshake
	// per signup is self-inflicted latency.
	return &Client{Key: key, HTTP: &http.Client{Timeout: 3 * time.Second}}
}

type Request struct {
	Token              string `json:"token"`
	FingerprintEventID string `json:"fingerprintEventId,omitempty"`
	TZ                 string `json:"tz,omitempty"`
	Email              string `json:"email,omitempty"`
	AccountID          string `json:"accountId,omitempty"`
}

type Verdict struct {
	Decision       string   `json:"decision"` // allow | review | block
	RiskScore      int      `json:"risk_score"`
	Reasons        []string `json:"reasons"`
	DeviceEvidence string   `json:"device_evidence"` // ok | not_sent | unavailable
	Degraded       bool     `json:"degraded"`
	Test           bool     `json:"test"`
}

// CleanAllow is a complete, production allow: what a strict action needs.
func (v *Verdict) CleanAllow() bool {
	return v != nil && v.Decision == "allow" && v.DeviceEvidence == "ok" && !v.Degraded && !v.Test
}

func (c *Client) Evaluate(ctx context.Context, in Request) (*Verdict, error) {
	body, err := json.Marshal(in)
	if err != nil {
		return nil, err
	}
	req, err := http.NewRequestWithContext(ctx, http.MethodPost,
		"https://maskbreak.com/v1/evaluate", bytes.NewReader(body))
	if err != nil {
		return nil, err
	}
	req.Header.Set("Authorization", "Bearer "+c.Key)
	req.Header.Set("Content-Type", "application/json")

	res, err := c.HTTP.Do(req)
	if err != nil {
		return nil, err
	}
	defer res.Body.Close()

	if res.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("maskbreak: status %d", res.StatusCode) // 401: the key
	}
	var v Verdict
	if err := json.NewDecoder(res.Body).Decode(&v); err != nil {
		return nil, err
	}
	return &v, nil
}

// guard.go, in the same package
package fraud

import (
	"context"
	"expvar"
	"log"
	"net/http"
	"time"
)

// Failed calls, graphable from /debug/vars or your metrics exporter.
var evalErrors = expvar.NewInt("maskbreak_eval_errors")

type ctxKey struct{}

// Guard evaluates the visit and stashes the verdict. It never refuses a
// request itself: allow/review/block is a product decision, and the same
// middleware has to serve a signup form and a payout endpoint.
func (c *Client) Guard(next http.Handler) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		// Its own deadline: a slow fraud check must not consume the
		// budget the handler needs to answer.
		ctx, cancel := context.WithTimeout(r.Context(), 3*time.Second)
		defer cancel()

		_ = r.ParseForm()
		v, err := c.Evaluate(ctx, Request{
			Token:              first(r, "monocle", "token"),
			FingerprintEventID: first(r, "sentinel_fp", "fingerprintEventId"),
			TZ:                 first(r, "sentinel_tz", "tz"),
			Email:              r.FormValue("email"),
		})
		if err != nil {
			evalErrors.Add(1) // fail open, and make the failure countable
			log.Printf("maskbreak unavailable: %v", err)
		}
		// One line per check. Never log the key, the token or form data.
		if v != nil {
			log.Printf("maskbreak mode=%s decision=%s reasons=%v device_evidence=%s degraded=%t",
				Mode, v.Decision, v.Reasons, v.DeviceEvidence, v.Degraded)
		}
		next.ServeHTTP(w, r.WithContext(context.WithValue(r.Context(), ctxKey{}, v)))
	})
}

func first(r *http.Request, a, b string) string {
	if v := r.FormValue(a); v != "" {
		return v
	}
	return r.FormValue(b)
}

// FromContext returns the verdict, or nil when the check did not complete.
func FromContext(ctx context.Context) *Verdict {
	v, _ := ctx.Value(ctxKey{}).(*Verdict)
	return v
}

mux := http.NewServeMux()
guard := fraud.New(os.Getenv("MASKBREAK_API_KEY")).Guard

// Mounted per action, not globally.
mux.Handle("/signup", guard(http.HandlerFunc(signup)))
mux.Handle("/payout", guard(http.HandlerFunc(payout)))

func signup(w http.ResponseWriter, r *http.Request) {
	v := fraud.FromContext(r.Context())
	if fraud.Mode == "enforce" && v != nil {
		switch v.Decision {
		case "block":
			http.Error(w, "unable to complete signup", http.StatusForbidden)
			return
		case "review":
			requireEmailOTP(r) // step up, do not refuse
		}
	}
	createAccount(w, r) // watch mode: always reached
}

func payout(w http.ResponseWriter, r *http.Request) {
	v := fraud.FromContext(r.Context())
	if fraud.Mode == "enforce" && !v.CleanAllow() {
		http.Error(w, "additional verification required", http.StatusConflict)
		return
	}
	sendPayout(w, r)
}

// breaker.go, same package (imports "sync" and "time")
type breaker struct {
	mu     sync.Mutex
	fails  int
	openTo time.Time
}

func (b *breaker) allow() bool {
	b.mu.Lock()
	defer b.mu.Unlock()
	return time.Now().After(b.openTo)
}

func (b *breaker) record(err error) {
	b.mu.Lock()
	defer b.mu.Unlock()
	if err == nil {
		b.fails = 0
		return
	}
	if b.fails++; b.fails >= 5 {
		b.openTo = time.Now().Add(30 * time.Second) // skip the call entirely
		b.fails = 0
	}
}

func TestVerdictShapes(t *testing.T) {
	c := fraud.New("sk_test_sandbox")
	for token, want := range map[string]string{
		"test_clean": "allow",
		"test_vpn":   "review",
		"test_proxy": "block",
		"test_tor":   "block",
	} {
		v, err := c.Evaluate(context.Background(), fraud.Request{Token: token})
		if err != nil {
			t.Fatalf("%s: %v", token, err)
		}
		if v.Decision != want {
			t.Errorf("%s: got %q want %q", token, v.Decision, want)
		}
		if !v.Test {
			t.Errorf("%s: a sandbox answer must say test", token)
		}
	}
}