Skip to content

Evolution API / Evolution Go is an open-source WhatsApp integration API

7.9 KB
Raw Blame
// Package ceremony holds the in-memory state of WhatsApp passkey (WebAuthn)
// pairing ceremonies. It is written by the whatsmeow event goroutine and read
// by the public HTTP polling endpoint, so every access is mutex-guarded.
//
// The lifecycle mirrors the browser-extension contract (tools/passkey-helper):
// the extension polls GET /passkey-ceremony/{token} and drives the ceremony
// through the stages below.
package ceremony

import (
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"sync"
	"time"
)

// Stage is the ceremony state the extension polls for. The values are the
// literal strings the extension's content.js switches on.
const (
	StageChallenge            = "challenge"             // publicKey available; extension runs navigator.credentials.get()
	StageAwaitingConfirmation = "awaiting_confirmation" // response sent to WhatsApp, waiting for the confirmation code
	StageConfirmation         = "confirmation"          // code available; user must verify + confirm
	StageConfirmed            = "confirmed"             // confirmation sent, pairing completing
	StageError                = "error"                 // something failed
)

// defaultTTL mirrors the whatsmeow passkey handoff validity window (~5 min).
const defaultTTL = 5 * time.Minute

// State is the snapshot the poll endpoint serializes back to the extension.
// The extension reads json.data || json, so a flat object is fine; keys match
// what content.js expects.
//
// PublicKey is stored pre-serialized (json.RawMessage) because whatsmeow's
// types.WebAuthnPublicKey already carries the exact json tags the extension
// needs (challenge, rpId, allowCredentials[].{id,type,transports},
// userVerification, base64url-unpadded via jsonbytes). The event goroutine
// json.Marshals the WebAuthnPublicKey once and hands the bytes here — no
// field-by-field remap, no base64 re-encoding mismatch.
type State struct {
	Stage         string          `json:"stage"`
	PublicKey     json.RawMessage `json:"publicKey,omitempty"`
	Code          string          `json:"code,omitempty"`
	SkipHandoffUX bool            `json:"skipHandoffUX"`
	Error         string          `json:"error,omitempty"`
}

type entry struct {
	instanceID string
	state      State
	expiresAt  time.Time
}

// Store keeps token -> ceremony entry. It is shared (pointer) across the
// value-receiver whatsmeowService copies and the HTTP handler, so its internal
// map is protected by a RWMutex.
type Store struct {
	mu      sync.RWMutex
	byToken map[string]*entry // ephemeral ceremony token -> entry
	byInst  map[string]string // instanceID -> active token (for event-goroutine writes)
}

// NewStore builds an empty ceremony store.
func NewStore() *Store {
	return &Store{
		byToken: make(map[string]*entry),
		byInst:  make(map[string]string),
	}
}

func newToken() string {
	b := make([]byte, 32)
	// crypto/rand.Read never returns a short read on supported platforms.
	_, _ = rand.Read(b)
	return hex.EncodeToString(b)
}

func (s *Store) prune(now time.Time) {
	for tok, e := range s.byToken {
		if now.After(e.expiresAt) {
			delete(s.byToken, tok)
			if s.byInst[e.instanceID] == tok {
				delete(s.byInst, e.instanceID)
			}
		}
	}
}

// Start begins (or restarts) a ceremony for an instance with the challenge
// publicKey (pre-serialized JSON), mints a fresh ephemeral token, and returns
// it. Any previous ceremony for the same instance is replaced.
func (s *Store) Start(instanceID string, pk json.RawMessage) string {
	s.mu.Lock()
	defer s.mu.Unlock()
	now := time.Now()
	s.prune(now)

	// Drop any previous token for this instance.
	if old, ok := s.byInst[instanceID]; ok {
		delete(s.byToken, old)
	}

	tok := newToken()
	s.byToken[tok] = &entry{
		instanceID: instanceID,
		state:      State{Stage: StageChallenge, PublicKey: pk, SkipHandoffUX: false},
		expiresAt:  now.Add(defaultTTL),
	}
	s.byInst[instanceID] = tok
	return tok
}

// setStateByInstance updates the state of the active ceremony for an instance.
// No-op if the instance has no active ceremony.
func (s *Store) setStateByInstance(instanceID string, mutate func(*State)) {
	s.mu.Lock()
	defer s.mu.Unlock()
	tok, ok := s.byInst[instanceID]
	if !ok {
		return
	}
	e, ok := s.byToken[tok]
	if !ok {
		return
	}
	mutate(&e.state)
	e.expiresAt = time.Now().Add(defaultTTL)
}

// SetConfirmation moves the ceremony to the confirmation stage with a code.
// skipHandoffUX is intentionally forced to false by callers (DOC2 §4.2: never
// auto-confirm), so the extension always shows the manual "Confirmar" button.
func (s *Store) SetConfirmation(instanceID, code string, skipHandoffUX bool) {
	s.setStateByInstance(instanceID, func(st *State) {
		st.Stage = StageConfirmation
		st.Code = code
		st.SkipHandoffUX = skipHandoffUX
		st.Error = ""
	})
}

// SetAwaitingConfirmation is set right after the WebAuthn response is submitted.
func (s *Store) SetAwaitingConfirmation(instanceID string) {
	s.setStateByInstance(instanceID, func(st *State) {
		st.Stage = StageAwaitingConfirmation
		st.PublicKey = nil
		st.Error = ""
	})
}

// SetConfirmed marks the confirmation as sent; pairing is finishing.
func (s *Store) SetConfirmed(instanceID string) {
	s.setStateByInstance(instanceID, func(st *State) {
		st.Stage = StageConfirmed
		st.Error = ""
	})
}

// SetError records a ceremony error.
func (s *Store) SetError(instanceID, msg string) {
	s.setStateByInstance(instanceID, func(st *State) {
		st.Stage = StageError
		st.Error = msg
	})
}

// Clear removes the ceremony for an instance (e.g. on PairSuccess). After this,
// the poll endpoint returns not-found, and the extension treats a cleared state
// after having started as "pairing concluded".
func (s *Store) Clear(instanceID string) {
	s.mu.Lock()
	defer s.mu.Unlock()
	if tok, ok := s.byInst[instanceID]; ok {
		delete(s.byToken, tok)
		delete(s.byInst, instanceID)
	}
}

// Lookup resolves a ceremony token to its instance id and current state.
// ok is false if the token is unknown or expired.
func (s *Store) Lookup(token string) (instanceID string, state State, ok bool) {
	s.mu.Lock()
	defer s.mu.Unlock()
	s.prune(time.Now())
	e, found := s.byToken[token]
	if !found {
		return "", State{}, false
	}
	return e.instanceID, e.state, true
}

// InstanceForToken resolves just the instance id for a token (used by the
// response/confirm endpoints to reach the right whatsmeow client).
func (s *Store) InstanceForToken(token string) (string, bool) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	e, ok := s.byToken[token]
	if !ok {
		return "", false
	}
	if time.Now().After(e.expiresAt) {
		return "", false
	}
	return e.instanceID, true
}

// StateByInstance returns the active ceremony token and state for an instance,
// or ok=false if there is no non-expired ceremony. Used by the authenticated
// instance/QR poll so the manager can render the passkey UI (the token lets it
// rebuild the #wapk openUrl).
func (s *Store) StateByInstance(instanceID string) (token string, state State, ok bool) {
	s.mu.RLock()
	defer s.mu.RUnlock()
	tok, has := s.byInst[instanceID]
	if !has {
		return "", State{}, false
	}
	e, has := s.byToken[tok]
	if !has {
		return "", State{}, false
	}
	if time.Now().After(e.expiresAt) {
		return "", State{}, false
	}
	return tok, e.state, true
}

// HasActiveByInstance reports whether an instance has a non-expired passkey
// ceremony in progress that is NOT yet in a terminal (error) stage. The QR
// rotation uses this to avoid tearing down the socket/client while a passkey
// ceremony — which is driven by a human in a browser and can easily outlast the
// QR rotation window — is still in flight. Without this, teardownQR would delete
// the client mid-ceremony and the /response and /confirm steps would fail.
func (s *Store) HasActiveByInstance(instanceID string) bool {
	s.mu.RLock()
	defer s.mu.RUnlock()
	tok, ok := s.byInst[instanceID]
	if !ok {
		return false
	}
	e, ok := s.byToken[tok]
	if !ok {
		return false
	}
	if time.Now().After(e.expiresAt) {
		return false
	}
	// A ceremony in the error stage is terminal — QR teardown may proceed.
	return e.state.Stage != StageError
}