Data models

The most important persistent data shapes inside Vault. These are the structures that travel from Go code to the storage barrier; understanding them is essential for reading code that touches storage, replication, or audit.

Mount entry

vault/mount.go::MountEntry. Persisted under core/mounts, core/auth, core/audit.

type MountEntry struct {
    Table       string         // "mounts" | "auth" | "audit"
    Path        string         // "secret/", "auth/userpass/", ...
    Type        string         // "kv", "userpass", "file", ...
    Description string
    Config      MountConfig
    Local       bool           // local-only, never replicated
    SealWrap    bool           // wrap critical paths in seal
    ExternalEntropyAccess bool
    Tainted     bool           // marked for unmount
    Options     map[string]string
    UUID        string         // unique ID; used for storage view prefix
    BackendAwareUUID string
    Accessor    string         // human-friendly handle for ACL/audit
    NamespaceID string
    Version     string         // plugin version pin
    RunningVersion string
    PluginVersion  string
    PluginRunningVersion string
    PluginCatalogVersion string
    SHA256      string         // plugin hash
}

Token entry

vault/token_store.go::TokenEntry. Persisted under sys/token/<id> and indexed by accessor under sys/token/accessor/<accessor>.

type TokenEntry struct {
    Type             logical.TokenType  // service | batch
    ID               string
    ExternalID       string
    Accessor         string
    Parent           string
    Policies         []string
    Path             string             // mount that issued
    Meta             map[string]string
    DisplayName      string
    NumUses          int
    CreationTime     int64
    TTL              time.Duration
    ExplicitMaxTTL   time.Duration
    Role             string
    Period           time.Duration
    EntityID         string
    NoIdentityPolicies bool
    BoundCIDRs       []*sockaddr.SockAddrMarshaler
    NamespaceID      string
    CubbyholeID      string
    InternalMeta     map[string]string
}

Lease entry

vault/expiration.go::leaseEntry. Persisted under sys/expire/id/<lease_id> (encoded).

type leaseEntry struct {
    LeaseID         string
    ClientToken     string
    Path            string
    Data            map[string]any
    Secret          *logical.Secret
    Auth            *logical.Auth
    IssueTime       time.Time
    ExpireTime      time.Time
    LastRenewalTime time.Time
    Version         int                // schema version
    namespace       *namespace.Namespace
    LoginRole       string
    ClientTokenType logical.TokenType
}

Policy

vault/policy.go::Policy. Persisted under sys/policy/<namespace>/<name> (with separate trees for ACL, RGP, EGP).

type Policy struct {
    Name      string
    Paths     []*PathRules
    Raw       string             // original HCL text
    Type      PolicyType         // ACL | RGP | EGP
    Templated bool
    namespace *namespace.Namespace
}

type PathRules struct {
    Path                string
    Policy              string                   // legacy "policy=read"
    Permissions         *ACLPermissions
    IsPrefix            bool
    HasSegmentWildcards bool
    Capabilities        []string
    MFAMethods          []string
    ControlGroup        *ControlGroup
}

Identity entity

helper/identity/types.proto::Entity. Persisted under entity/buckets/<bucket-id> (sharded by entity ID hash).

message Entity {
  repeated Alias aliases = 1;
  string id = 2;
  string name = 3;
  map<string,string> metadata = 4;
  int64 creation_time = 5;
  int64 last_update_time = 6;
  repeated string merged_entity_ids = 7;
  repeated string policies = 8;
  string bucket_key = 9;
  string mfa_secrets = 10;
  bool disabled = 11;
  string namespace_id = 12;
}

The protobuf-defined types are shared with replication so primary and secondary clusters can serialize identity state across the wire.

Lease tree

Tokens form a tree (parent → child). Persisted edges:

• sys/parent/<parent_token_id>/<child_token_id> — empty value.
• sys/expire/leases/<lease_id> — registered leases.

When revoking a parent, revokeTreeInternal walks the tree iteratively to avoid deep recursion.

Audit table

vault/audit.go::AuditTable is structurally identical to a mount table but stored separately under core/audit. Each entry knows the device type, options, salt key, and HMAC pepper for that device.

Seal config

Persisted under core/seal-config:

type SealConfig struct {
    Type            string
    SecretShares    int
    SecretThreshold int
    Nonce           string
    PGPKeys         []string
    Backup          bool
    StoredShares    int            // how many shares to keep encrypted in storage (auto-unseal)
    Name            string
    RekeyProgress   [][]byte       // transient
    VerificationRequired bool
    VerificationKey      []byte
    VerificationNonce    string
    RewrapStaticConfig   *AutoSealRewrapConfig
}

Keyring

The barrier's keyring (vault/keyring.go) holds the active and historical AES-GCM keys. Encrypted with the master key and stored at core/keyring. New versions are added on rekey; old versions are kept so historic ciphertext can still decrypt.

OIDC objects

Hosted by the identity store:

• identity/oidc/key/<name> — signing key with rotation schedule.
• identity/oidc/scope/<name> — claim template.
• identity/oidc/role/<name> — older single-tenant ID-token issuance flow.
• identity/oidc/provider/<name> — multi-client issuer.
• identity/oidc/client/<name> — per-client config.
• identity/oidc/assignment/<name> — entity/group → client allowlist.

How they all fit

graph LR
    Tok[TokenEntry] -- entity_id --> Ent[Entity]
    Tok -- parent --> ParentTok[Parent token]
    Tok -- accessor --> Audit[AuditTable]
    Lease[leaseEntry] -- ClientToken --> Tok
    Lease -- Path --> Mount[MountEntry]
    Pol[Policy] -- attached to --> Tok
    Pol -- attached to --> Ent
    Ent -- alias --> Mount
    Mount -- UUID --> StorageView[(barrier-prefixed view)]

This graph is what Core.HandleRequest traverses on every request: token → entity → policies → ACL → mount → backend → storage.