// Package cursor signs and verifies resource-bound keyset positions. package cursor import ( "crypto/hmac" "crypto/rand" "crypto/sha256" "encoding/base64" "encoding/json" "errors" "fmt" "time" "github.com/google/uuid" ) const ( cursorSigningKeyBytes = 32 maxEncodedCursorBytes = 1024 ) // ErrInvalid means a cursor is malformed, tampered with or bound to another resource. var ErrInvalid = errors.New("invalid cursor") // Position identifies the last record already returned by keyset pagination. type Position struct { // CreatedAt is the creation timestamp of the last returned record. CreatedAt time.Time // ID breaks ties between records sharing a timestamp. ID uuid.UUID } // Codec authenticates pagination positions with an immutable process-local key. type Codec struct { key [cursorSigningKeyBytes]byte } type cursorPayload struct { // Resource binds the position to a chat history or one user's chat list. Resource string `json:"r"` // Time is the creation timestamp of the last record in the previous page. Time time.Time `json:"t"` // ID breaks ties between records with the same creation timestamp. ID uuid.UUID `json:"i"` } // New creates a cursor codec with a random process-local signing key. func New() (*Codec, error) { codec := &Codec{} if _, err := rand.Read(codec.key[:]); err != nil { return nil, err } return codec, nil } // Encode serializes and signs a pagination position bound to a resource. func (codec *Codec) Encode(resource string, position Position) (string, error) { payload, err := json.Marshal(cursorPayload{ Resource: resource, Time: position.CreatedAt, ID: position.ID, }) if err != nil { return "", fmt.Errorf("encode cursor: %w", err) } payload = append(payload, codec.signature(payload)...) return base64.RawURLEncoding.EncodeToString(payload), nil } // Decode verifies the cursor signature and extracts its resource-bound position. func (codec *Codec) Decode(encoded, resource string) (Position, error) { if encoded == "" { return Position{}, nil } if len(encoded) > maxEncodedCursorBytes { return Position{}, ErrInvalid } signed, err := base64.RawURLEncoding.DecodeString(encoded) if err != nil || len(signed) <= sha256.Size { return Position{}, ErrInvalid } boundary := len(signed) - sha256.Size payload, signature := signed[:boundary], signed[boundary:] if !hmac.Equal(signature, codec.signature(payload)) { return Position{}, ErrInvalid } return decodeCursorPosition(payload, resource) } // signature computes the HMAC-SHA256 authentication tag for a cursor payload. func (codec *Codec) signature(payload []byte) []byte { mac := hmac.New(sha256.New, codec.key[:]) // hash.Hash.Write is documented to always return a nil error. _, _ = mac.Write(payload) return mac.Sum(nil) } // decodeCursorPosition validates the decoded cursor resource and timestamp. func decodeCursorPosition(payload []byte, resource string) (Position, error) { var cursor cursorPayload if err := json.Unmarshal(payload, &cursor); err != nil { return Position{}, ErrInvalid } if cursor.Resource != resource || cursor.Time.IsZero() { return Position{}, ErrInvalid } return Position{CreatedAt: cursor.Time, ID: cursor.ID}, nil }