kalzu-value-store/types/types.go

package types

import "encoding/json"

// Core data structures
type StoredValue struct {
	UUID      string          `json:"uuid"`
	Timestamp int64           `json:"timestamp"`
	Data      json.RawMessage `json:"data"`
}

// Authentication & Authorization data structures

// User represents a system user
type User struct {
	UUID         string   `json:"uuid"`          // Server-generated UUID
	NicknameHash string   `json:"nickname_hash"` // SHA3-512 hash of nickname
	Groups       []string `json:"groups"`        // List of group UUIDs this user belongs to
	CreatedAt    int64    `json:"created_at"`    // Unix timestamp
	UpdatedAt    int64    `json:"updated_at"`    // Unix timestamp
}

// Group represents a user group
type Group struct {
	UUID      string   `json:"uuid"`       // Server-generated UUID
	NameHash  string   `json:"name_hash"`  // SHA3-512 hash of group name
	Members   []string `json:"members"`    // List of user UUIDs in this group
	CreatedAt int64    `json:"created_at"` // Unix timestamp
	UpdatedAt int64    `json:"updated_at"` // Unix timestamp
}

// APIToken represents a JWT authentication token
type APIToken struct {
	TokenHash string   `json:"token_hash"` // SHA3-512 hash of JWT token
	UserUUID  string   `json:"user_uuid"`  // UUID of the user who owns this token
	Scopes    []string `json:"scopes"`     // List of permitted scopes (e.g., "read", "write")
	IssuedAt  int64    `json:"issued_at"`  // Unix timestamp when token was issued
	ExpiresAt int64    `json:"expires_at"` // Unix timestamp when token expires
}

// ResourceMetadata contains ownership and permission information for stored resources
type ResourceMetadata struct {
	OwnerUUID   string `json:"owner_uuid"`  // UUID of the resource owner
	GroupUUID   string `json:"group_uuid"`  // UUID of the resource group
	Permissions int    `json:"permissions"` // 12-bit permission mask (POSIX-inspired)
	TTL         string `json:"ttl"`         // Time-to-live duration (Go format)
	CreatedAt   int64  `json:"created_at"`  // Unix timestamp when resource was created
	UpdatedAt   int64  `json:"updated_at"`  // Unix timestamp when resource was last updated
}

// Permission constants for POSIX-inspired ACL
const (
	// Owner permissions (bits 11-8)
	PermOwnerCreate = 1 << 11
	PermOwnerDelete = 1 << 10
	PermOwnerWrite  = 1 << 9
	PermOwnerRead   = 1 << 8

	// Group permissions (bits 7-4)
	PermGroupCreate = 1 << 7
	PermGroupDelete = 1 << 6
	PermGroupWrite  = 1 << 5
	PermGroupRead   = 1 << 4

	// Others permissions (bits 3-0)
	PermOthersCreate = 1 << 3
	PermOthersDelete = 1 << 2
	PermOthersWrite  = 1 << 1
	PermOthersRead   = 1 << 0

	// Default permissions: Owner(1111), Group(0110), Others(0010)
	DefaultPermissions = (PermOwnerCreate | PermOwnerDelete | PermOwnerWrite | PermOwnerRead) |
		(PermGroupWrite | PermGroupRead) |
		(PermOthersRead)
)

// API request/response structures for authentication endpoints

// User Management API structures
type CreateUserRequest struct {
	Nickname string `json:"nickname"`
}

type CreateUserResponse struct {
	UUID string `json:"uuid"`
}

type UpdateUserRequest struct {
	Nickname string   `json:"nickname,omitempty"`
	Groups   []string `json:"groups,omitempty"`
}

type GetUserResponse struct {
	UUID         string   `json:"uuid"`
	NicknameHash string   `json:"nickname_hash"`
	Groups       []string `json:"groups"`
	CreatedAt    int64    `json:"created_at"`
	UpdatedAt    int64    `json:"updated_at"`
}

// Group Management API structures
type CreateGroupRequest struct {
	Groupname string   `json:"groupname"`
	Members   []string `json:"members,omitempty"`
}

type CreateGroupResponse struct {
	UUID string `json:"uuid"`
}

type UpdateGroupRequest struct {
	Members []string `json:"members"`
}

type GetGroupResponse struct {
	UUID      string   `json:"uuid"`
	NameHash  string   `json:"name_hash"`
	Members   []string `json:"members"`
	CreatedAt int64    `json:"created_at"`
	UpdatedAt int64    `json:"updated_at"`
}

// Token Management API structures
type CreateTokenRequest struct {
	UserUUID string   `json:"user_uuid"`
	Scopes   []string `json:"scopes"`
}

type CreateTokenResponse struct {
	Token     string `json:"token"`
	ExpiresAt int64  `json:"expires_at"`
}

// Resource Metadata Management API structures (Issue #12)
type GetResourceMetadataResponse struct {
	OwnerUUID   string `json:"owner_uuid"`
	GroupUUID   string `json:"group_uuid"`
	Permissions int    `json:"permissions"`
	TTL         string `json:"ttl"`
	CreatedAt   int64  `json:"created_at"`
	UpdatedAt   int64  `json:"updated_at"`
}

type UpdateResourceMetadataRequest struct {
	OwnerUUID   *string `json:"owner_uuid,omitempty"`
	GroupUUID   *string `json:"group_uuid,omitempty"`
	Permissions *int    `json:"permissions,omitempty"`
}

// Cluster and member management types
type Member struct {
	ID              string `json:"id"`
	Address         string `json:"address"`
	LastSeen        int64  `json:"last_seen"`
	JoinedTimestamp int64  `json:"joined_timestamp"`
}

type JoinRequest struct {
	ID              string `json:"id"`
	Address         string `json:"address"`
	JoinedTimestamp int64  `json:"joined_timestamp"`
}

type LeaveRequest struct {
	ID string `json:"id"`
}

type PairsByTimeRequest struct {
	StartTimestamp int64  `json:"start_timestamp"`
	EndTimestamp   int64  `json:"end_timestamp"`
	Limit          int    `json:"limit"`
	Prefix         string `json:"prefix,omitempty"`
}

type PairsByTimeResponse struct {
	Path      string `json:"path"`
	UUID      string `json:"uuid"`
	Timestamp int64  `json:"timestamp"`
}

type PutResponse struct {
	UUID      string `json:"uuid"`
	Timestamp int64  `json:"timestamp"`
}

// TTL-enabled PUT request structure
type PutWithTTLRequest struct {
	Data json.RawMessage `json:"data"`
	TTL  string          `json:"ttl,omitempty"` // Go duration format
}

// Tamper-evident logging data structures
type TamperLogEntry struct {
	Timestamp string `json:"timestamp"` // RFC3339 format
	Action    string `json:"action"`    // Type of action
	UserUUID  string `json:"user_uuid"` // User who performed the action
	Resource  string `json:"resource"`  // Resource affected
	Signature string `json:"signature"` // SHA3-512 hash of all fields
}

// Backup system data structures
type BackupStatus struct {
	LastBackupTime    int64  `json:"last_backup_time"`    // Unix timestamp
	LastBackupSuccess bool   `json:"last_backup_success"` // Whether last backup succeeded
	LastBackupPath    string `json:"last_backup_path"`    // Path to last backup file
	NextBackupTime    int64  `json:"next_backup_time"`    // Unix timestamp of next scheduled backup
	BackupsRunning    int    `json:"backups_running"`     // Number of backups currently running
}

// Merkle Tree specific data structures
type MerkleNode struct {
	Hash     []byte `json:"hash"`
	StartKey string `json:"start_key"` // The first key in this node's range
	EndKey   string `json:"end_key"`   // The last key in this node's range
}

// MerkleRootResponse is the response for getting the root hash
type MerkleRootResponse struct {
	Root *MerkleNode `json:"root"`
}

// MerkleTreeDiffRequest is used to request children hashes for a given key range
type MerkleTreeDiffRequest struct {
	ParentNode MerkleNode `json:"parent_node"` // The node whose children we want to compare (from the remote peer's perspective)
	LocalHash  []byte     `json:"local_hash"`  // The local hash of this node/range (from the requesting peer's perspective)
}

// MerkleTreeDiffResponse returns the remote children nodes or the actual keys if it's a leaf level
type MerkleTreeDiffResponse struct {
	Children []MerkleNode `json:"children,omitempty"` // Children of the remote node
	Keys     []string     `json:"keys,omitempty"`     // Actual keys if this is a leaf-level diff
}

// For fetching a range of KV pairs
type KVRangeRequest struct {
	StartKey string `json:"start_key"`
	EndKey   string `json:"end_key"`
	Limit    int    `json:"limit"` // Max number of items to return
}

type KVRangeResponse struct {
	Pairs []struct {
		Path        string      `json:"path"`
		StoredValue StoredValue `json:"stored_value"`
	} `json:"pairs"`
}

// Configuration
type Config struct {
	NodeID               string   `yaml:"node_id"`
	BindAddress          string   `yaml:"bind_address"`
	Port                 int      `yaml:"port"`
	DataDir              string   `yaml:"data_dir"`
	SeedNodes            []string `yaml:"seed_nodes"`
	ReadOnly             bool     `yaml:"read_only"`
	LogLevel             string   `yaml:"log_level"`
	GossipIntervalMin    int      `yaml:"gossip_interval_min"`
	GossipIntervalMax    int      `yaml:"gossip_interval_max"`
	SyncInterval         int      `yaml:"sync_interval"`
	CatchupInterval      int      `yaml:"catchup_interval"`
	BootstrapMaxAgeHours int      `yaml:"bootstrap_max_age_hours"`
	ThrottleDelayMs      int      `yaml:"throttle_delay_ms"`
	FetchDelayMs         int      `yaml:"fetch_delay_ms"`

	// Database compression configuration
	CompressionEnabled bool `yaml:"compression_enabled"`
	CompressionLevel   int  `yaml:"compression_level"`

	// TTL configuration
	DefaultTTL  string `yaml:"default_ttl"`   // Go duration format, "0" means no default TTL
	MaxJSONSize int    `yaml:"max_json_size"` // Maximum JSON size in bytes

	// Rate limiting configuration
	RateLimitRequests int    `yaml:"rate_limit_requests"` // Max requests per window
	RateLimitWindow   string `yaml:"rate_limit_window"`   // Window duration (Go format)

	// Tamper-evident logging configuration
	TamperLogActions []string `yaml:"tamper_log_actions"` // Actions to log

	// Backup system configuration
	BackupEnabled   bool   `yaml:"backup_enabled"`   // Enable/disable automated backups
	BackupSchedule  string `yaml:"backup_schedule"`  // Cron schedule format
	BackupPath      string `yaml:"backup_path"`      // Directory to store backups
	BackupRetention int    `yaml:"backup_retention"` // Days to keep backups

	// Feature toggles for optional functionalities
	AuthEnabled            bool `yaml:"auth_enabled"`             // Enable/disable authentication system
	TamperLoggingEnabled   bool `yaml:"tamper_logging_enabled"`   // Enable/disable tamper-evident logging
	ClusteringEnabled      bool `yaml:"clustering_enabled"`       // Enable/disable clustering/gossip
	RateLimitingEnabled    bool `yaml:"rate_limiting_enabled"`    // Enable/disable rate limiting
	RevisionHistoryEnabled bool `yaml:"revision_history_enabled"` // Enable/disable revision history

	// Anonymous access control (Issue #5)
	AllowAnonymousRead  bool `yaml:"allow_anonymous_read"`  // Allow unauthenticated read access to KV endpoints
	AllowAnonymousWrite bool `yaml:"allow_anonymous_write"` // Allow unauthenticated write access to KV endpoints

	// Cluster authentication (Issue #13)
	ClusterSecret        string `yaml:"cluster_secret"`          // Shared secret for cluster authentication (auto-generated if empty)
	ClusterTLSEnabled    bool   `yaml:"cluster_tls_enabled"`     // Require TLS for inter-node communication
	ClusterTLSCertFile   string `yaml:"cluster_tls_cert_file"`   // Path to TLS certificate file
	ClusterTLSKeyFile    string `yaml:"cluster_tls_key_file"`    // Path to TLS private key file
	ClusterTLSSkipVerify bool   `yaml:"cluster_tls_skip_verify"` // Skip TLS verification (insecure, for testing only)
}