Files
mtusi2026lab3/internal/cursor/codec.go
T

109 lines
3.2 KiB
Go

// 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
}