forked from mtusi2026/mtusi2026lab3
109 lines
3.2 KiB
Go
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
|
|
}
|