feat(shared): add tokens package for secure token generation and validation (#1331)

* feat(shared): add tokens package for secure token generation and validation

Adds shared/pkg/tokens with GenerateToken, HashToken, ValidateTokenHash,
TokenWithExpiry, IsExpired, and TimeUntilExpiry. Uses crypto/rand and
SHA256 for secure single-use token workflows (invitations, password resets).

* fix(shared/tokens): use constant-time comparison in ValidateTokenHash

Replace string equality with crypto/subtle.ConstantTimeCompare to
prevent timing side-channel attacks during token validation.

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

shared/pkg/tokens/expiry.go

@@ -0,0 +1,26 @@
+package tokens
+
+import "time"
+
+// TTL constants for different token types.
+const (
+	InvitationTokenTTL    = 72 * time.Hour
+	PasswordResetTokenTTL = 1 * time.Hour
+)
+
+// TokenWithExpiry pairs a stored token hash with its expiry time.
+type TokenWithExpiry struct {
+	Hash      string
+	ExpiresAt time.Time
+}
+
+// IsExpired returns true if the token's expiry time is at or before the current time.
+func IsExpired(t TokenWithExpiry) bool {
+	return !time.Now().Before(t.ExpiresAt)
+}
+
+// TimeUntilExpiry returns the duration remaining until the token expires.
+// A negative or zero duration indicates the token has already expired.
+func TimeUntilExpiry(t TokenWithExpiry) time.Duration {
+	return time.Until(t.ExpiresAt)
+}

shared/pkg/tokens/expiry_test.go

@@ -0,0 +1,87 @@
+// Package tokens_test provides tests for the tokens package.
+package tokens_test
+
+import (
+	"testing"
+	"time"
+
+	"github.com/stretchr/testify/assert"
+
+	"github.com/meridianhub/meridian/shared/pkg/tokens"
+)
+
+func TestIsExpired(t *testing.T) {
+	t.Run("returns false for token with future expiry", func(t *testing.T) {
+		tok := tokens.TokenWithExpiry{
+			Hash:      "somehash",
+			ExpiresAt: time.Now().Add(1 * time.Hour),
+		}
+		assert.False(t, tokens.IsExpired(tok))
+	})
+
+	t.Run("returns true for token with past expiry", func(t *testing.T) {
+		tok := tokens.TokenWithExpiry{
+			Hash:      "somehash",
+			ExpiresAt: time.Now().Add(-1 * time.Second),
+		}
+		assert.True(t, tokens.IsExpired(tok))
+	})
+
+	t.Run("returns true for token expiring exactly now (boundary)", func(t *testing.T) {
+		tok := tokens.TokenWithExpiry{
+			Hash:      "somehash",
+			ExpiresAt: time.Now(),
+		}
+		// At-or-past expiry is expired
+		assert.True(t, tokens.IsExpired(tok))
+	})
+}
+
+func TestTimeUntilExpiry(t *testing.T) {
+	t.Run("returns positive duration for future token", func(t *testing.T) {
+		tok := tokens.TokenWithExpiry{
+			Hash:      "somehash",
+			ExpiresAt: time.Now().Add(1 * time.Hour),
+		}
+		d := tokens.TimeUntilExpiry(tok)
+		assert.Greater(t, d, time.Duration(0))
+	})
+
+	t.Run("returns zero or negative for expired token", func(t *testing.T) {
+		tok := tokens.TokenWithExpiry{
+			Hash:      "somehash",
+			ExpiresAt: time.Now().Add(-1 * time.Second),
+		}
+		d := tokens.TimeUntilExpiry(tok)
+		assert.LessOrEqual(t, d, time.Duration(0))
+	})
+
+	t.Run("is approximately correct", func(t *testing.T) {
+		future := time.Now().Add(72 * time.Hour)
+		tok := tokens.TokenWithExpiry{
+			Hash:      "somehash",
+			ExpiresAt: future,
+		}
+		d := tokens.TimeUntilExpiry(tok)
+		// Should be within 1 second of 72 hours
+		assert.InDelta(t, (72 * time.Hour).Seconds(), d.Seconds(), 1.0)
+	})
+}
+
+func TestConstants(t *testing.T) {
+	t.Run("InvitationTokenLength is 32", func(t *testing.T) {
+		assert.Equal(t, 32, tokens.InvitationTokenLength)
+	})
+
+	t.Run("PasswordResetTokenLength is 32", func(t *testing.T) {
+		assert.Equal(t, 32, tokens.PasswordResetTokenLength)
+	})
+
+	t.Run("InvitationTokenTTL is 72 hours", func(t *testing.T) {
+		assert.Equal(t, 72*time.Hour, tokens.InvitationTokenTTL)
+	})
+
+	t.Run("PasswordResetTokenTTL is 1 hour", func(t *testing.T) {
+		assert.Equal(t, 1*time.Hour, tokens.PasswordResetTokenTTL)
+	})
+}

shared/pkg/tokens/token.go

@@ -0,0 +1,56 @@
+// Package tokens provides secure token generation, hashing, and validation utilities
+// for single-use tokens such as invitations and password resets.
+package tokens
+
+import (
+	"crypto/rand"
+	"crypto/sha256"
+	"crypto/subtle"
+	"encoding/base64"
+	"encoding/hex"
+	"errors"
+)
+
+// ErrInvalidLength is returned when a non-positive token length is provided.
+var ErrInvalidLength = errors.New("token length must be positive")
+
+// Token length constants for different use cases.
+const (
+	InvitationTokenLength    = 32
+	PasswordResetTokenLength = 32
+)
+
+// GenerateToken generates a cryptographically secure random token of the given byte length.
+// Returns the URL-safe base64 plaintext (for delivery to the user) and its SHA256 hex hash
+// (for storage). The plaintext must never be stored — only the hash is persisted.
+func GenerateToken(length int) (plaintext, hash string, err error) {
+	if length <= 0 {
+		return "", "", ErrInvalidLength
+	}
+
+	b := make([]byte, length)
+	if _, err = rand.Read(b); err != nil {
+		return "", "", err
+	}
+
+	plaintext = base64.RawURLEncoding.EncodeToString(b)
+	hash = HashToken(plaintext)
+	return plaintext, hash, nil
+}
+
+// HashToken returns the SHA256 hex digest of the given plaintext token.
+// Use this to produce a storable hash; never store the plaintext.
+func HashToken(plaintext string) string {
+	sum := sha256.Sum256([]byte(plaintext))
+	return hex.EncodeToString(sum[:])
+}
+
+// ValidateTokenHash returns true if the SHA256 hash of plaintext matches the stored hash.
+// Uses constant-time comparison to prevent timing attacks.
+func ValidateTokenHash(plaintext, hash string) bool {
+	if plaintext == "" || hash == "" {
+		return false
+	}
+	computed := HashToken(plaintext)
+	return subtle.ConstantTimeCompare([]byte(computed), []byte(hash)) == 1
+}

shared/pkg/tokens/token_test.go

@@ -0,0 +1,134 @@
+// Package tokens_test provides tests for the tokens package.
+package tokens_test
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/meridianhub/meridian/shared/pkg/tokens"
+)
+
+func TestGenerateToken(t *testing.T) {
+	t.Run("returns plaintext and hash", func(t *testing.T) {
+		plaintext, hash, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		assert.NotEmpty(t, plaintext)
+		assert.NotEmpty(t, hash)
+	})
+
+	t.Run("plaintext length matches requested bytes encoded as base64url", func(t *testing.T) {
+		plaintext, _, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		// base64url RawEncoding: ceil(n * 4/3), no padding
+		// 32 bytes -> 43 chars
+		assert.GreaterOrEqual(t, len(plaintext), 40)
+	})
+
+	t.Run("plaintext contains only URL-safe characters", func(t *testing.T) {
+		plaintext, _, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		for _, c := range plaintext {
+			assert.True(t, isURLSafeChar(c), "unexpected char: %c", c)
+		}
+	})
+
+	t.Run("hash matches HashToken of plaintext", func(t *testing.T) {
+		plaintext, hash, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		expected := tokens.HashToken(plaintext)
+		assert.Equal(t, expected, hash)
+	})
+
+	t.Run("returns error for zero length", func(t *testing.T) {
+		_, _, err := tokens.GenerateToken(0)
+		assert.Error(t, err)
+	})
+
+	t.Run("returns error for negative length", func(t *testing.T) {
+		_, _, err := tokens.GenerateToken(-1)
+		assert.Error(t, err)
+	})
+
+	t.Run("generates unique tokens", func(t *testing.T) {
+		const count = 10000
+		seen := make(map[string]struct{}, count)
+		for i := 0; i < count; i++ {
+			plaintext, _, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+			require.NoError(t, err)
+			_, exists := seen[plaintext]
+			assert.False(t, exists, "duplicate token at iteration %d", i)
+			seen[plaintext] = struct{}{}
+		}
+	})
+}
+
+func TestHashToken(t *testing.T) {
+	t.Run("returns non-empty hex string", func(t *testing.T) {
+		hash := tokens.HashToken("some-plaintext-token")
+		assert.NotEmpty(t, hash)
+		assert.True(t, isHex(hash), "hash should be hex: %s", hash)
+	})
+
+	t.Run("SHA256 produces 64-char hex string", func(t *testing.T) {
+		hash := tokens.HashToken("some-plaintext-token")
+		assert.Len(t, hash, 64)
+	})
+
+	t.Run("is deterministic", func(t *testing.T) {
+		plaintext := "deterministic-token-value"
+		hash1 := tokens.HashToken(plaintext)
+		hash2 := tokens.HashToken(plaintext)
+		assert.Equal(t, hash1, hash2)
+	})
+
+	t.Run("different inputs produce different hashes", func(t *testing.T) {
+		hash1 := tokens.HashToken("token-a")
+		hash2 := tokens.HashToken("token-b")
+		assert.NotEqual(t, hash1, hash2)
+	})
+}
+
+func TestValidateTokenHash(t *testing.T) {
+	t.Run("returns true for matching plaintext and hash", func(t *testing.T) {
+		plaintext, hash, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		assert.True(t, tokens.ValidateTokenHash(plaintext, hash))
+	})
+
+	t.Run("returns false for wrong plaintext", func(t *testing.T) {
+		_, hash, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		assert.False(t, tokens.ValidateTokenHash("wrong-plaintext", hash))
+	})
+
+	t.Run("returns false for empty plaintext", func(t *testing.T) {
+		_, hash, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		assert.False(t, tokens.ValidateTokenHash("", hash))
+	})
+
+	t.Run("returns false for empty hash", func(t *testing.T) {
+		plaintext, _, err := tokens.GenerateToken(tokens.InvitationTokenLength)
+		require.NoError(t, err)
+		assert.False(t, tokens.ValidateTokenHash(plaintext, ""))
+	})
+}
+
+func isURLSafeChar(c rune) bool {
+	return (c >= 'A' && c <= 'Z') ||
+		(c >= 'a' && c <= 'z') ||
+		(c >= '0' && c <= '9') ||
+		c == '-' || c == '_'
+}
+
+func isHex(s string) bool {
+	for _, c := range strings.ToLower(s) {
+		if (c < '0' || c > '9') && (c < 'a' || c > 'f') {
+			return false
+		}
+	}
+	return true
+}