Documentation
¶
Overview ¶
Package domain defines core tokenization domain models for data tokenization. Supports multiple token formats (UUID, Numeric, Luhn-preserving, Alphanumeric) with configurable deterministic behavior.
Index ¶
Constants ¶
View Source
const ( // MaxTokenLength is the maximum allowed token length for format-preserving tokens. // This limit applies to Numeric, Luhn-Preserving, and Alphanumeric formats. MaxTokenLength = 255 // MinLuhnTokenLength is the minimum token length required for Luhn algorithm validation. // Luhn check requires at least 2 digits (payload + check digit). MinLuhnTokenLength = 2 // MaxPlaintextSize is the maximum allowed plaintext size for tokenization (64 KB). // This limit prevents DoS attacks from extremely large inputs and ensures reasonable // encryption performance. MaxPlaintextSize = 65536 // 64 KB )
Token length constraints
Variables ¶
View Source
var ( // ErrTokenizationKeyNotFound indicates the tokenization key was not found. ErrTokenizationKeyNotFound = errors.Wrap(errors.ErrNotFound, "tokenization key not found") // ErrTokenizationKeyAlreadyExists indicates a tokenization key with the same name and version already exists. ErrTokenizationKeyAlreadyExists = errors.Wrap(errors.ErrConflict, "tokenization key already exists") // ErrTokenNotFound indicates the token was not found. ErrTokenNotFound = errors.Wrap(errors.ErrNotFound, "token not found") // ErrTokenExpired indicates the token has expired. ErrTokenExpired = errors.Wrap(errors.ErrInvalidInput, "token has expired") // ErrTokenRevoked indicates the token has been revoked. ErrTokenRevoked = errors.Wrap(errors.ErrInvalidInput, "token has been revoked") // ErrInvalidFormatType indicates an invalid token format type was provided. ErrInvalidFormatType = errors.Wrap(errors.ErrInvalidInput, "invalid format type") // ErrInvalidTokenLength indicates the token length is invalid for the specified format. ErrInvalidTokenLength = errors.Wrap(errors.ErrInvalidInput, "invalid token length for format") // ErrValueTooLong indicates the value exceeds the maximum allowed length. ErrValueTooLong = errors.Wrap(errors.ErrInvalidInput, "value exceeds maximum length") // ErrPlaintextTooLarge indicates the plaintext exceeds maximum allowed size. ErrPlaintextTooLarge = errors.Wrap(errors.ErrInvalidInput, "plaintext exceeds maximum size of 64KB") // ErrPlaintextEmpty indicates the plaintext is empty. ErrPlaintextEmpty = errors.Wrap(errors.ErrInvalidInput, "plaintext cannot be empty") // ErrTokenLengthInvalid indicates the token length is invalid for the format. ErrTokenLengthInvalid = errors.Wrap(errors.ErrInvalidInput, "token length invalid for format type") // ErrTokenizationKeyNameEmpty indicates the tokenization key name is empty. ErrTokenizationKeyNameEmpty = errors.Wrap(errors.ErrInvalidInput, "tokenization key name cannot be empty") // ErrTokenizationKeyVersionInvalid indicates the version is invalid (must be > 0). ErrTokenizationKeyVersionInvalid = errors.Wrap( errors.ErrInvalidInput, "tokenization key version must be greater than 0", ) // ErrTokenizationKeyDekIDInvalid indicates the DEK ID is invalid (nil UUID). ErrTokenizationKeyDekIDInvalid = errors.Wrap( errors.ErrInvalidInput, "tokenization key DEK ID cannot be nil", ) )
Functions ¶
This section is empty.
Types ¶
type FormatType ¶
type FormatType string
FormatType defines the token format type.
const ( FormatUUID FormatType = "uuid" FormatNumeric FormatType = "numeric" FormatLuhnPreserving FormatType = "luhn-preserving" FormatAlphanumeric FormatType = "alphanumeric" )
func (FormatType) String ¶
func (f FormatType) String() string
String returns the string representation of the format type.
func (FormatType) Validate ¶
func (f FormatType) Validate() error
Validate checks if the format type is valid.
type Token ¶
type Token struct {
ID uuid.UUID
TokenizationKeyID uuid.UUID
Token string
ValueHash *string
Ciphertext []byte
Nonce []byte
// Metadata stores optional unencrypted display data (e.g., last 4 digits, expiry date).
// Stored as JSON in the database with recommended maximum size of 1KB.
// Supported types: string, int, float64, bool, nil, and nested maps/slices of these types.
// Example: map[string]any{"last4": "1234", "exp": "12/25", "brand": "Visa"}
// WARNING: Do not store sensitive data in metadata as it is NOT encrypted.
Metadata map[string]any
CreatedAt time.Time
ExpiresAt *time.Time
RevokedAt *time.Time
}
Token represents a tokenization mapping between a token and its encrypted original value. Supports optional expiration, revocation, and metadata for display purposes.
type TokenizationKey ¶
type TokenizationKey struct {
// ID is the unique identifier for this specific key version.
ID uuid.UUID
// Name is the logical name for this tokenization key (e.g., "payment-cards", "ssn").
// Multiple versions can share the same name.
Name string
// Version is the key version number, starting at 1 and incremented on rotation.
// Higher versions are preferred for tokenization; all versions support detokenization.
Version uint
// FormatType defines the token format (UUID, Numeric, Luhn-Preserving, Alphanumeric).
FormatType FormatType
// IsDeterministic indicates whether the same plaintext always produces the same token.
// When true, enables efficient duplicate detection; when false, provides better privacy.
IsDeterministic bool
// DekID is the reference to the Data Encryption Key used to encrypt values for this version.
DekID uuid.UUID
// CreatedAt is the timestamp when this key version was created (UTC).
CreatedAt time.Time
// DeletedAt is the timestamp when this key was soft-deleted (nil if active).
DeletedAt *time.Time
}
TokenizationKey represents a versioned tokenization key configuration. Each key defines the token format and deterministic behavior for tokenization operations.
func (*TokenizationKey) Validate ¶ added in v0.22.0
func (tk *TokenizationKey) Validate() error
Validate checks if the TokenizationKey has valid field values. Returns an error if any field constraint is violated.
Source Files
Click to show internal directories.
Click to hide internal directories.