Entities

Vault defines a set of entity types across its subsystem packages. All entities embed a shared vault.Entity base type (or carry equivalent timestamp fields) and use id.ID identifiers with entity-specific prefixes.

vault.Entity (base type)

Every mutable Vault entity embeds vault.Entity, which provides standard timestamp fields.

import "github.com/xraph/vault"

type Entity struct {
    CreatedAt time.Time `json:"created_at"`
    UpdatedAt time.Time `json:"updated_at"`
}

Method	Description
`vault.NewEntity()`	Creates a new Entity with both timestamps set to `time.Now().UTC()`.
`e.Touch()`	Updates `UpdatedAt` to `time.Now().UTC()`.

Secret

Package: github.com/xraph/vault/secret ID prefix: sec_

A Secret represents a stored secret with its encrypted value, version, and metadata.

type Secret struct {
    vault.Entity
    ID              id.ID             `json:"id"`
    Key             string            `json:"key"`
    Value           []byte            `json:"-"`    // decrypted value -- never serialized
    EncryptedValue  []byte            `json:"-"`    // encrypted at rest
    Version         int64             `json:"version"`
    EncryptionAlg   string            `json:"encryption_alg"`
    EncryptionKeyID string            `json:"encryption_key_id"`
    ExpiresAt       *time.Time        `json:"expires_at,omitempty"`
    AppID           string            `json:"app_id"`
    Metadata        map[string]string `json:"metadata,omitempty"`
}

Field	Description
`ID`	Unique identifier with `sec_` prefix.
`Key`	Human-readable key (e.g. `"openai-api-key"`). Unique within an app.
`Value`	Decrypted plaintext. Never serialized to JSON -- only available after `Service.Get`.
`EncryptedValue`	AES-256-GCM ciphertext with prepended nonce. Never serialized to JSON.
`Version`	Auto-incrementing version number. Starts at 1, incremented on every `Set`.
`EncryptionAlg`	Algorithm label (e.g. `"AES-256-GCM"`). Set automatically by the service.
`EncryptionKeyID`	Identifier of the encryption key used (for key rotation tracking).
`ExpiresAt`	Optional expiration time.
`AppID`	Application scope identifier.
`Metadata`	Arbitrary key-value metadata.

Secret.Meta

Meta is the public-facing metadata for a secret. It never includes the value or encrypted value.

type Meta struct {
    ID        id.ID             `json:"id"`
    Key       string            `json:"key"`
    Version   int64             `json:"version"`
    ExpiresAt *time.Time        `json:"expires_at,omitempty"`
    AppID     string            `json:"app_id"`
    Metadata  map[string]string `json:"metadata,omitempty"`
    CreatedAt time.Time         `json:"created_at"`
    UpdatedAt time.Time         `json:"updated_at"`
}

Secret.ToMeta() converts a Secret to its Meta representation.

Secret.Version

Version records a historical version of a secret.

type Version struct {
    ID             id.ID     `json:"id"`              // ver_ prefix
    SecretKey      string    `json:"secret_key"`
    AppID          string    `json:"app_id"`
    Version        int64     `json:"version"`
    EncryptedValue []byte    `json:"-"`
    CreatedBy      string    `json:"created_by"`
    CreatedAt      time.Time `json:"created_at"`
}

Flag Definition

Package: github.com/xraph/vault/flag ID prefix: flag_

A Definition represents a feature flag definition with its type, default value, variants, and enabled state.

type Definition struct {
    vault.Entity
    ID           id.ID             `json:"id"`
    Key          string            `json:"key"`
    Type         Type              `json:"type"`
    DefaultValue any               `json:"default_value"`
    Description  string            `json:"description"`
    Tags         []string          `json:"tags,omitempty"`
    Variants     []Variant         `json:"variants,omitempty"`
    Enabled      bool              `json:"enabled"`
    AppID        string            `json:"app_id"`
    Metadata     map[string]string `json:"metadata,omitempty"`
}

Field	Description
`Key`	Unique flag key within an app (e.g. `"new-dashboard"`).
`Type`	Value type: `TypeBool`, `TypeString`, `TypeInt`, `TypeFloat`, or `TypeJSON`.
`DefaultValue`	Value returned when no rules match or the flag is disabled.
`Tags`	Optional string tags for filtering and grouping.
`Variants`	Named variants for A/B testing (each has a `Value` and `Description`).
`Enabled`	When `false`, the engine always returns `DefaultValue` regardless of rules.

Flag types

const (
    TypeBool   Type = "bool"
    TypeString Type = "string"
    TypeInt    Type = "int"
    TypeFloat  Type = "float"
    TypeJSON   Type = "json"
)

Variant

type Variant struct {
    Value       any    `json:"value"`
    Description string `json:"description"`
}

Flag Rule

Package: github.com/xraph/vault/flag ID prefix: rule_

A Rule represents a targeting rule for a feature flag. Rules are evaluated in priority order (lower number = higher priority).

type Rule struct {
    vault.Entity
    ID          id.ID      `json:"id"`
    FlagKey     string     `json:"flag_key"`
    AppID       string     `json:"app_id"`
    Priority    int        `json:"priority"`      // lower = higher priority
    Type        RuleType   `json:"type"`
    Config      RuleConfig `json:"config"`
    ReturnValue any        `json:"return_value"`
}

Rule types

Constant	Value	Description
`RuleWhenTenant`	`"when_tenant"`	Match specific tenant IDs
`RuleWhenTenantTag`	`"when_tenant_tag"`	Match tenants with a specific tag key/value
`RuleWhenUser`	`"when_user"`	Match specific user IDs
`RuleRollout`	`"rollout"`	Deterministic percentage-based rollout (0-100)
`RuleSchedule`	`"schedule"`	Active only within a time window
`RuleCustom`	`"custom"`	Plugin-evaluated via a named evaluator

RuleConfig

type RuleConfig struct {
    TenantIDs  []string       `json:"tenant_ids,omitempty"`   // WhenTenant
    TagKey     string         `json:"tag_key,omitempty"`      // WhenTenantTag
    TagValue   string         `json:"tag_value,omitempty"`    // WhenTenantTag
    UserIDs    []string       `json:"user_ids,omitempty"`     // WhenUser
    Percentage int            `json:"percentage,omitempty"`   // Rollout (0-100)
    StartAt    *time.Time     `json:"start_at,omitempty"`     // Schedule
    EndAt      *time.Time     `json:"end_at,omitempty"`       // Schedule
    Evaluator  string         `json:"evaluator,omitempty"`    // Custom (plugin name)
    Params     map[string]any `json:"params,omitempty"`       // Custom (plugin params)
}

Rule constructors

The flag package provides convenience constructors for common rule types:

// Match specific tenants.
rule := flag.WhenTenant("tenant-1", "tenant-2").Return(true)

// Match tenants with a tag.
rule := flag.WhenTenantTag("plan", "enterprise").Return(true)

// Match specific users.
rule := flag.WhenUser("user-42", "user-99").Return(true)

// Percentage rollout (deterministic hash of tenantID:flagKey).
rule := flag.Rollout(25).Return(true)

// Time-window schedule.
rule := flag.Schedule(startTime, endTime).Return(true)

The .Return(value) method sets the value returned when the rule matches.

Flag TenantOverride

A TenantOverride is a direct per-tenant flag value that bypasses all rules.

type TenantOverride struct {
    vault.Entity
    ID       id.ID  `json:"id"`
    FlagKey  string `json:"flag_key"`
    AppID    string `json:"app_id"`
    TenantID string `json:"tenant_id"`
    Value    any    `json:"value"`
}

Config Entry

Package: github.com/xraph/vault/config ID prefix: cfg_

An Entry represents a runtime configuration entry with a typed value and version history.

type Entry struct {
    vault.Entity
    ID          id.ID             `json:"id"`
    Key         string            `json:"key"`
    Value       any               `json:"value"`
    ValueType   string            `json:"value_type"`
    Version     int64             `json:"version"`
    Description string            `json:"description"`
    AppID       string            `json:"app_id"`
    Metadata    map[string]string `json:"metadata,omitempty"`
}

Field	Description
`Key`	Unique config key within an app (e.g. `"rate-limit"`).
`Value`	The configuration value (`any` type -- coerced via type-safe accessors).
`ValueType`	Type label: `"string"`, `"bool"`, `"int"`, `"float"`, or `"json"`. Auto-inferred if not set.
`Version`	Auto-incrementing version number.
`Description`	Human-readable description.

Config EntryVersion

type EntryVersion struct {
    ID        id.ID     `json:"id"`           // ver_ prefix
    ConfigKey string    `json:"config_key"`
    AppID     string    `json:"app_id"`
    Version   int64     `json:"version"`
    Value     any       `json:"value"`
    CreatedBy string    `json:"created_by"`
    CreatedAt time.Time `json:"created_at"`
}

Override

Package: github.com/xraph/vault/override ID prefix: ovr_

An Override represents a per-tenant override for a config entry. When a tenant has an override for a key, the override.Resolver returns the override value instead of the app-level config.

type Override struct {
    vault.Entity
    ID       id.ID             `json:"id"`
    Key      string            `json:"key"`
    Value    any               `json:"value"`
    AppID    string            `json:"app_id"`
    TenantID string            `json:"tenant_id"`
    Metadata map[string]string `json:"metadata,omitempty"`
}

Field	Description
`Key`	The config key this override applies to.
`Value`	The tenant-specific value that replaces the app-level config.
`TenantID`	The tenant this override applies to.

Rotation Policy

Package: github.com/xraph/vault/rotation ID prefix: rot_

A Policy defines a scheduled rotation policy for a secret.

type Policy struct {
    vault.Entity
    ID             id.ID         `json:"id"`
    SecretKey      string        `json:"secret_key"`
    AppID          string        `json:"app_id"`
    Interval       time.Duration `json:"interval"`
    Enabled        bool          `json:"enabled"`
    LastRotatedAt  *time.Time    `json:"last_rotated_at,omitempty"`
    NextRotationAt *time.Time    `json:"next_rotation_at,omitempty"`
}

Field	Description
`SecretKey`	The secret key this policy applies to.
`Interval`	How often the secret should be rotated (e.g. `24 * time.Hour`).
`Enabled`	When `false`, the rotation manager skips this policy.
`LastRotatedAt`	Timestamp of the last successful rotation.
`NextRotationAt`	Computed as `LastRotatedAt + Interval`. The manager rotates when `time.Now()` is past this time.

Rotation Record

Package: github.com/xraph/vault/rotation ID prefix: rot_

A Record captures a completed rotation event.

type Record struct {
    ID         id.ID     `json:"id"`
    SecretKey  string    `json:"secret_key"`
    AppID      string    `json:"app_id"`
    OldVersion int64     `json:"old_version"`
    NewVersion int64     `json:"new_version"`
    RotatedBy  string    `json:"rotated_by"`
    RotatedAt  time.Time `json:"rotated_at"`
}

Field	Description
`OldVersion`	Secret version before rotation.
`NewVersion`	Secret version after rotation.
`RotatedBy`	Identifier of who/what triggered the rotation (e.g. `"rotation-manager"`).

Audit Entry

Package: github.com/xraph/vault/audit ID prefix: vaudit_

An Entry is a single audit log entry recording a Vault operation.

type Entry struct {
    ID        id.ID          `json:"id"`
    Action    string         `json:"action"`
    Resource  string         `json:"resource"`
    Key       string         `json:"key"`
    AppID     string         `json:"app_id"`
    TenantID  string         `json:"tenant_id,omitempty"`
    UserID    string         `json:"user_id,omitempty"`
    IP        string         `json:"ip,omitempty"`
    Outcome   string         `json:"outcome"`
    Metadata  map[string]any `json:"metadata,omitempty"`
    CreatedAt time.Time      `json:"created_at"`
}

Field	Description
`Action`	The operation performed (e.g. `"secret.accessed"`, `"flag.evaluated"`, `"config.set"`).
`Resource`	The resource type (`"secret"`, `"flag"`, `"config"`, `"override"`).
`Key`	The entity key that was operated on.
`Outcome`	`"success"` or `"failure"`.
`TenantID`	Extracted from context via `scope.FromContext`.
`UserID`	Extracted from context via `scope.FromContext`.
`IP`	Client IP extracted from context via `scope.FromContext`.
`Metadata`	Additional context (e.g. `{"error": "..."}` on failure).

Audit entries are append-only. There is no update or delete operation in the audit.Store interface.

Entities

On this page