volta

package module
v0.0.0-...-c6a886f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jun 28, 2025 License: Apache-2.0 Imports: 29 Imported by: 0

README

volta

Tests Coverage

Volta: An Embedded Go Library for Multi-Tenant Encryption and Secrets Management

Volta is a zero-dependency Go library designed for multi-tenant encryption and secret management, intended to be embedded directly within an application.

It is used by SouthWinds Tech to protect Personally Identifiable Information (PII) and other sensitive data within their own applications. It establishes a cryptographic boundary within the application's process, providing data protection controls without reliance on external services.

Why Volta? An Architectural and Comparative Context

A common question for architects and developers is, "Why use Volta instead of a dedicated secrets manager like HashiCorp Vault, AWS Secrets Manager, or just a simpler approach like AES-GCM with keys in environment variables?"

The answer lies in understanding the specific problem Volta is designed to solve. Volta does not aim to compete with centralised secret vaults; it is designed to complement them by addressing a narrow, yet critical, challenge: * scalable, application-level, multi-tenant data encryption with minimal operational overhead.*

Volta is best understood as an implementation of the Embedded Library Model for data protection, distinct from the * External Service Model* of traditional vaults.

Here is a pragmatic comparison of the architectural patterns:

Aspect Centralised Vaults (e.g. HashiCorp Vault, AWS SM) Embedded Library Pattern (e.g. Volta)
Primary Problem Domain Secret Brokering & Identity Management. Centralising and brokering access to secrets (database credentials, API keys) for infrastructure and applications. Application-Level Data Encryption. Per-tenant cryptographic isolation of sensitive data (like PII) stored in a shared database or storage layer.
Operational Model Requires deploying, managing, and securing a separate, highly-available service cluster. Embedded directly into the application. No external service to manage, reducing operational scope to application configuration.
Typical Workload Low-frequency operations. Applications fetch configuration or short-lived credentials at startup or infrequently. High-frequency operations. Encrypting and decrypting data fields on nearly every read/write path that is considered to manage PII within the application's business logic.
Network Overhead Each cryptographic operation (if using Encryption-as-a-Service) incurs network latency. Zero network latency for cryptographic operations, as they occur in-process.
Multi-Tenancy Handled via policies, paths, and namespaces at the infrastructure level. A core, native architectural primitive. The library is fundamentally designed to manage distinct cryptographic contexts for a large amount of tenants.
The Hybrid Pattern: Complementing, Not Competing

The most powerful approach is a hybrid model that leverages the strengths of both patterns. While Volta excels at high-frequency, in-process encryption, it still faces the classic "first secret" problem: where does the application get the master passphrase to unlock a tenant's vault?

This is where centralised vaults shine. The ideal architecture becomes:

  1. Bootstrapping (The "First Secret"): An application, using a platform-managed identity (e.g., AWS IAM Role, Kubernetes Service Account), authenticates to a centralised secret manager (AWS Secrets Manager, HashiCorp Vault).
  2. Secure Handoff: The secret manager securely provides the master passphrase to the application instance at startup. This is a low-frequency, highly secure event.
  3. Application-Level Encryption: Once bootstrapped, the embedded Volta library uses the passphrase to manage its key hierarchy and perform high-frequency, low-latency encryption and decryption of tenant data for the application's entire lifecycle.

In this model, the centralised vault handles infrastructure-level identity and bootstrapping, while Volta provides the specialised, high-performance application-level cryptographic engine.

The following diagram shows how the hybrid pattern could work:

architecture

What About Simpler Approaches (e.g., AES-GCM)?

For a single-tenant application with one or two keys, a direct implementation of a cryptographic cipher might seem sufficient. However, this approach does not scale to a multi-tenant SaaS environment and lacks critical features that Volta provides out-of-the-box:

  • Key Lifecycle Management: No built-in support for secure key generation, rotation, or destruction per tenant.
  • Auditing: No integrated, pluggable audit trail for all cryptographic and administrative operations.
  • Secure Storage: Lacks a structured, encrypted format for persisting a large number of tenant keys.
  • In-Memory Protection: Does not provide safeguards for keys and plaintext while resident in application memory.

Volta offers a practical, robust implementation for a specific and complex problem, providing the architectural components necessary for secure, compliant, and maintainable multi-tenant applications. Its goal is to serve as a reference pattern for this problem, reducing redundant-engineering effort across the industry.

Design Principles

Volta's architecture is guided by the following principles:

  • Multi-tenancy: Provides cryptographic isolation for distinct tenants (e.g., applications, services, or organizational units). Each tenant operates with its own dedicated keys, secrets, and audit trails.
  • Pluggable Backends: Storage and audit logging are defined by interfaces (persist.Store, audit.Logger), enabling integration with various persistence and observability systems.
  • In-Memory Protection: Utilizes memory-protection libraries (e.g., memguard) to secure keys and plaintext secrets while resident in application memory.
  • Embedded, API-less Design: Operates as a library without an external REST API. This minimizes the attack surface and places the control of cryptographic operations within the application's own security context.
  • Non-Exportable Keys: Encryption keys are managed internally and are not designed to be exported.
  • Administrative CLI: A command-line interface is provided for out-of-band vault management and administrative operations.
Key Components

  1. Vault Manager (VaultManagerService): The top-level service that manages the lifecycle of all tenant vaults. It is the primary entry point for an application, responsible for retrieving, initializing, and closing tenant-specific vault instances.

  2. Vault (VaultService): Represents an individual tenant's vault. It is the interface for all cryptographic operations and secret management for a single tenant, including encryption, decryption, secret storage, and key management.

Feature Set
  • Per-Tenant Cryptography: Securely encrypt and decrypt data with keys isolated to each tenant, forming the foundation of the multi-tenant security model.
  • Secret Management: Provides full CRUD (Create, Retrieve, Update, Delete) operations for managing secrets like API keys, credentials, or other sensitive configuration.
  • Key Lifecycle Management: Automates secure, per-tenant key management, including generation, rotation, and destruction, complete with auditable reasoning.
  • Backup and Restore: Supports the creation of encrypted, passphrase-protected backups of individual tenant vaults and enables secure restoration for disaster recovery.
  • In-Memory Protection: Limits the exposure of plaintext secrets in application memory using techniques like memory-protection libraries and scoped access functions.
  • Pluggable Backends: Designed for extensibility with pluggable interfaces for both the persistence layer (storage) and the audit logging system, allowing integration with existing infrastructure.
  • Administrative CLI: Includes a command-line interface for performing out-of-band administrative tasks, such as bulk operations, backups, and maintenance across tenants.
Basic Usage
Storing and Retrieving Secrets

The example here demonstrates initialising the vault manager, accessing a tenant's vault, storing and retrieving secrets.

Encryption of sensitive data

The example here demonstrates initialising the vault manager, accessing a tenant's vault, and using it to directly encrypt and decrypt sensitive data, such as PII.

Key Encryption Key (KEK) Rotation

The example here demonstrates the process of Key Encryption Key (KEK) rotation, while maintaining access to existing encrypted data without requiring data re-encryption.

Data Encryption Key (DEK) Rotation

The example here demonstrates the complete lifecycle of Data Encryption Key (DEK) rotation and its impact on encrypted data accessibility.

Volta's Backup & Restore

The example here demonstrates the complete backup/restore cycle of a vault with encrypted PII and secrets.

KEK Rotation Performance Testing

The example here provides a simple performance test tool to evaluate the speed and reliability of Key Encryption Key (KEK) rotation operations across multiple tenants using Volta.

Installation
go get southwinds.dev/volta
Security Model

The security of a tenant's vault relies on the strength and confidentiality of its passphrase. This passphrase is used to derive the Key Encryption Key (KEK) that protects all of the tenant's Data Encryption Keys (DEKs).

Volta uses libraries like memguard to provide in-memory protection for sensitive data (e.g., keys, plaintext secrets), making it more difficult for other processes on the host to inspect the application's memory. This is part of a defense-in-depth strategy and is not a substitute for securing the host environment.

Extensibility

Volta is designed to be adaptable to different infrastructures. Custom backends can be created by implementing the following interfaces:

  • persist.Store: For connecting to different storage systems (e.g., databases, cloud object storage, key-value stores).
  • audit.Logger: For routing audit events to centralized logging or observability platforms (e.g., ELK Stack, Splunk, CloudWatch).
Detailed Documentation

For a deeper understanding of the architecture, data structures, security patterns, and compliance guides, please see the /docs directory:

Core Concepts

Understanding the following concepts is fundamental to working with Volta:

  1. Tenancy: Volta's multitenant architecture enables a single instance to serve multiple, isolated tenants. Each tenant (e.g., a distinct application, microservice, or department) operates within its own secure context, with dedicated encryption keys, secrets, and audit trails. This isolation is crucial for managing data access and compliance across different entities.

  2. Vault (VaultService): The VaultService interface represents an individual tenant's vault. It is the primary interaction point for all cryptographic operations and secret management activities pertinent to that tenant. This includes encrypting and decrypting data, managing the lifecycle of secrets (storing, retrieving, updating, deleting), and handling tenant-specific encryption keys. Each VaultService instance is scoped to a single tenant.

  3. Vault Manager (VaultManagerService): The VaultManagerService interface acts as the top-level orchestrator for the entire Volta deployment. It manages the lifecycle of tenant vaults (e.g., retrieving a vault for a specific tenant, closing tenant sessions). It also supports administrative operations that span across multiple tenants, such as bulk key rotations, passphrase changes, and querying aggregated audit logs from various tenants. This service is the main entry point for applications interacting with Volta.

  4. Secrets: In Volta, a "secret" refers to any piece of sensitive information that requires secure storage and controlled access. Examples include API keys, database credentials, personal identifiable information (PII), or configuration parameters. Volta ensures secrets are encrypted at rest using strong cryptographic measures, with access governed by the tenant's vault.

  5. Encryption Keys: Cryptographic keys are the cornerstone of Volta's security. Volta manages the lifecycle of these keys—including generation, rotation, and secure destruction—on a per-tenant basis. Data and secrets are encrypted using these keys, ensuring that even if the underlying storage is compromised, the sensitive information remains protected.

  6. Storage Backend (Store Interface): Volta abstracts its persistence layer through the Store interface. This design allows developers to integrate Volta with various storage mechanisms, such as local file systems, distributed key-value stores, or cloud-based storage services. While Volta may provide default implementations, the pluggable nature of the Store interface ensures that organizations can use storage solutions that align with their existing infrastructure and policies. The store is responsible for persisting encrypted key metadata, encrypted secrets data, and other essential vault state.

  7. Audit Backend (audit.Logger Interface): Comprehensive and immutable audit trails are critical for security monitoring, compliance, and forensic analysis. Volta utilizes the audit.Logger interface to log significant events. These events include key management operations (creation, rotation, destruction), secret access patterns (creation, retrieval, updates, deletion), administrative actions, and failed operations. Like the storage backend, the audit backend is pluggable, enabling integration with various logging systems, Security Information and Event Management (SIEM) tools, or custom audit repositories.

  8. In-Memory Protection: Protecting sensitive data, especially cryptographic keys, while it is actively being used in application memory is a significant challenge. Volta incorporates techniques to mitigate risks associated with memory exposure (e.g., from memory dumps or certain side-channel attacks). This is achieved through mechanisms like leveraging secure memory enclaves and careful handling of sensitive byte slices. The VaultService.SecureMemoryProtection() method provides insight into the status or configuration of these protections.

High-Level Operational Flow

A typical interaction with Volta involves the following conceptual steps:

  1. Initialization: An application initializes the VaultManagerService. This step typically involves configuring the desired storage and audit backends.
  2. Tenant Vault Access: The application requests a VaultService instance for a specific tenantID from the VaultManagerService. If a vault for this tenant doesn't exist and auto-creation is configured (or a specific provisioning step is taken), it might be initialized.
  3. Secure Operations: Using the obtained VaultService instance, the application can:
    • Encrypt and decrypt data.
    • Store, retrieve, update, and delete secrets securely.
    • Manage encryption keys (e.g., initiate key rotation).
    • Utilize features like UseSecret for safely working with secret data in memory for a limited scope.
  4. Auditing: All significant operations are automatically audited through the configured audit backend, providing a trail of activities.
  5. Tenant Closure: When a tenant's operations are complete, or during application shutdown, the VaultManagerService can be used to close individual tenant vaults or all active vaults to release resources and ensure data is securely persisted.

Operational Guidance and Extensibility

This section provides guidance on good practices for operating Volta, discusses important security considerations, and outlines how Volta's pluggable architecture allows for extensibility.

Good Practices for Utilizing Volta

Effective and secure operation of Volta relies on adhering to sound security principles and operational disciplines:

  1. Secure Tenant Passphrase Management: Volta uses a single passphrase to generate a derived key. The security of the entire tenant vault hinges on the secrecy and strength of this initial passphrase. Applications integrating Volta must implement robust mechanisms for managing these passphrases, ensuring they are not hardcoded, exposed in logs, or insecurely stored. Consider using environment variables, dedicated secret management systems (for bootstrapping Volta's passphrase), or user-provided input where appropriate.

  2. Regular Key Rotation: Volta supports key rotation (VaultService.RotateKey and VaultManagerService.RotateAllTenantKeys). Regularly rotating Data Encryption Keys (DEKs) is a crucial security hygiene practice. It limits the amount of data encrypted with any single key, reducing the impact if a key is ever compromised. Establish a policy for key rotation frequency based on your organization's risk assessment and compliance requirements. Provide clear, auditable reason strings for each rotation.

  3. Backup Management and Testing:

    • Secure Backup Passphrases: Backup archives created by Volta are encrypted. The passphrase used for backup encryption must be strong and managed with extreme care, separately from the backup files themselves. Losing this passphrase means losing access to the backup.
    • Regular Backups: Implement a regular schedule for backing up tenant vaults. The frequency should align with your Recovery Point Objectives (RPOs).
    • Test Restore Procedures: Regularly test the restoration process (VaultService.RestoreBackup) in a non-production environment to ensure backup integrity and verify that your recovery procedures are effective. Untested backups provide a false sense of security.
    • Secure Backup Storage: Store backup files in a secure, access-controlled location, separate from the primary operational environment.

  4. Principle of Least Privilege: When designing applications that interact with VaultManagerService, ensure that access to administrative functions (like RotateAllTenantKeys, RotateAllTenantPassphrases, or broad audit queries) is restricted to privileged components or users. Individual application instances should typically only interact with their designated VaultService.

  5. Audit Log Monitoring: Volta provides comprehensive auditing capabilities. Regularly monitor and review audit logs (QueryAuditLogs, GetAuditSummary, etc.) for suspicious activities, unauthorized access attempts, frequent failed operations, or unusual patterns. Integrate audit logs with your central Security Information and Event Management (SIEM) system if possible.

  6. Graceful Shutdown and Resource Management: Ensure that VaultService.Close() (for individual tenant vaults) and VaultManagerService.CloseTenant() or VaultManagerService.CloseAll() are called appropriately during application shutdown or when a tenant's session ends. This ensures that resources are released, pending writes are flushed, and sensitive data is cleared from memory.

  7. Scope of Plaintext Secret Exposure: While methods like Decrypt provide direct access to plaintext, exercise caution. Prefer using scoped access patterns like those implied by UseSecret (not explicitly defined but a common secure pattern) where plaintext exists in memory for the shortest necessary duration and within a controlled function scope. When handling plaintext byte slices, ensure they are explicitly cleared from memory as soon as they are no longer needed, if not managed by Volta's secure memory enclaves.

  8. Backend Selection: Choose storage (StoreConfig) and audit backends that align with your operational environment, security requirements, and scalability needs. Consider factors like data durability, availability, access control mechanisms, and existing infrastructure.

  9. Understanding Memory Protection: Be aware of the configured memoryProtectionLevel (as suggested by the internal Vault struct). Understand what protections are offered (e.g., non-swappable memory, guard pages) and their limitations. While Volta aims to protect critical data in memory, this is part of a defense-in-depth strategy.

Security Considerations

Volta is designed with security as a core tenet, but its overall security posture also depends on the environment and practices surrounding its deployment.

  1. Root of Trust - Tenant Passphrase/Key: The ultimate security of a tenant's data within Volta relies on the protection of its primary secret (e.g., passphrase or master key) from which its Key Encryption Key (KEK) is derived. If this root secret is compromised, the encrypted data it protects can be decrypted. Volta itself does not manage this initial secret but uses it to bootstrap its own internal key hierarchy.

  2. In-Memory Protection (memguard): Volta's use of libraries like memguard to protect sensitive data (keys, temporarily held secrets) in memory significantly raises the bar for attackers. However, no in-memory protection is infallible. Sophisticated attackers with sufficient privileges on the host OS (e.g., root access) or those exploiting severe kernel vulnerabilities might still be able to bypass or undermine these protections. Physical memory attacks (e.g., cold boot attacks) also remain a theoretical concern for extremely high-security scenarios.

  3. Storage Backend Security: Volta encrypts data before writing it to the persist.Store. However, the underlying storage system (filesystem, database, cloud storage) must also be secured. This includes proper access controls, encryption at rest for the storage medium itself (as an additional layer), and protection against unauthorized administrative access to the backend.

  4. Audit Log Integrity and Security: The audit backend should be configured to be as tamper-evident as possible. For instance, append-only logs, logs shipped to a separate, secured system, or cryptographic signing of log entries can enhance integrity. Unauthorized modification or deletion of audit logs can mask malicious activity.

  5. Application-Layer Vulnerabilities: Volta secures secrets within its boundary. If the application embedding Volta has vulnerabilities (e.g., SQL injection, Remote Code Execution, insecure API endpoints), these could be exploited to misuse Volta's VaultService API, potentially leading to secret exposure. Application security is a critical complementary layer.

  6. Backup Security: Backup files (BackupContainer) contain encrypted copies of highly sensitive data. These files must be protected with strong access controls, both in transit and at rest in their storage location. The backup encryption passphrase is a critical secret.

  7. Physical Security: Physical access to the systems running Volta can bypass many software-based security controls. Ensure appropriate physical security measures are in place for the host infrastructure.

  8. Operational Security: Secure operational practices, such as restricting access to production environments, robust identity and access management, and regular security patching of the underlying OS and Go runtime, are essential.

Extensibility and Pluggability

A key design principle of Volta is its adaptability through pluggable components. This allows integration into diverse environments and extension with custom functionality.

  1. Pluggable Storage Backends (persist.Store): Volta allows applications to define their own persistence mechanisms for storing encrypted vault data. This is achieved by implementing a persist.Store interface (the exact definition of which would be provided by Volta). A custom storage backend might interact with various systems:

    • Relational databases (PostgreSQL, MySQL, SQL Server)
    • NoSQL databases (MongoDB, Cassandra, DynamoDB)
    • Distributed key-value stores (etcd, Consul, ZooKeeper)
    • Cloud storage services (AWS S3, Google Cloud Storage, Azure Blob Storage) beyond any built-in support.
    • Proprietary in-house storage solutions. The implementation would need to handle safe storage and retrieval of byte arrays (representing encrypted data and metadata) keyed by tenant ID and potentially other identifiers. The StoreConfig structure facilitates configuring these custom (or pre-built) backends.

  2. Pluggable Audit Backends (audit.Logger): Similarly, Volta enables custom audit logging implementations by adhering to an audit.Logger interface. This allows audit events to be routed to various destinations:

    • Local log files in specific formats (e.g., JSON, CEF).
    • Centralized logging systems (Splunk, ELK Stack, Graylog).
    • Cloud-native monitoring services (AWS CloudWatch Logs, Google Cloud Logging, Azure Monitor).
    • Databases designed for audit trails. A custom logger would receive audit.Event data (or similar structured information) and be responsible for its durable and secure recording.

Volta allows to tailor its deployment to specific infrastructure and security requirements, ensuring that it can evolve with changing needs without compromising its core mission of providing simple, secure secret management.

License

Volta is licensed under the Apache 2.0 License. See LICENSE for the full license text.

Documentation

Overview

Package volta provides a secure vault service for encrypting, decrypting, and managing secrets. It implements a hierarchical key management system with automatic key rotation, secure backups, and comprehensive audit logging. The vault uses authenticated encryption and follows cryptographic best practices for secret management.

Key Features:

  • Hierarchical key management with automatic rotation
  • Authenticated encryption using ChaCha20-Poly1305
  • Secure backup and restore functionality
  • Secret metadata management with versioning
  • Comprehensive audit logging
  • Memory protection for sensitive data

Basic Usage: 

vault, err := volta.New(config)
if err != nil {
    log.Fatal(err)
}
defer vault.Close()

// Store a secret
metadata, err := vault.StoreSecret("my-secret", []byte("secret-data"), []string{"tag1"}, volta.ContentTypeText)

// Retrieve a secret
data, metadata, err := vault.GetSecret("my-secret")

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AuditSummary 

type AuditSummary struct {
	TenantID                 string    `json:"tenant_id"`
	TotalEvents              int       `json:"total_events"`
	SuccessfulEvents         int       `json:"successful_events"`
	FailedEvents             int       `json:"failed_events"`
	CredsAccessCount         int       `json:"passphrase_access_count"`
	SensitiveDataAccessCount int       `json:"secret_access_count"`
	KeyOperations            int       `json:"key_operations"`
	LastActivity             time.Time `json:"last_activity"`
}

AuditSummary provides aggregated audit statistics for tenant activity analysis.

OVERVIEW: This structure delivers high-level audit metrics for a specific tenant, enabling rapid assessment of tenant activity patterns, security posture, and operational health. It provides both quantitative metrics and temporal context for comprehensive tenant monitoring.

ANALYTICAL CAPABILITIES: 

ACTIVITY PROFILING:
The summary enables creation of tenant activity profiles by categorizing
operations into functional groups (passphrase access, secret operations,
key management) and providing success/failure ratios for each category.

SECURITY MONITORING:
By tracking failed events alongside successful operations, the summary
supports security monitoring workflows that can identify unusual patterns,
potential attacks, or system issues affecting specific tenants.

OPERATIONAL HEALTH:
The ratio of successful to failed operations provides immediate insight
into tenant operational health and can trigger automated alerting or
remediation workflows when thresholds are exceeded.

METRIC CATEGORIES: - Total Events: Complete audit trail volume for the tenant - Success/Failure Breakdown: Operational health indicators - Operation Type Breakdown: Functional usage patterns - Temporal Context: Activity recency and pattern analysis

PERFORMANCE CONSIDERATIONS: Summary generation is optimized for frequent querying and can be efficiently cached for dashboard and monitoring applications. The structure is designed to support both real-time monitoring and historical trend analysis.

Fields: 

TenantID:           Unique identifier for the tenant being summarized
TotalEvents:        Complete count of all audit events for the tenant
SuccessfulEvents:   Count of operations that completed successfully
FailedEvents:       Count of operations that failed or were denied
CredsAccessCount: 	Count of passphrase-related operations
SensitiveDataAccessCount: Count of secret retrieval and manipulation operations
KeyOperations:      Count of cryptographic key operations
LastActivity:       Timestamp of the most recent audit event

type BulkOperationResult 

type BulkOperationResult struct {
	TenantID  string                 `json:"tenant_id"`
	Success   bool                   `json:"success"`
	Error     string                 `json:"error,omitempty"`
	Details   map[string]interface{} `json:"details,omitempty"`
	Timestamp time.Time              `json:"timestamp"`
}

BulkOperationResult represents the outcome of a bulk operation on a tenant.

OVERVIEW: This structure provides comprehensive result information for bulk operations that affect multiple tenants simultaneously, such as key rotation, passphrase updates, or administrative actions. It enables detailed tracking of operation outcomes across tenant boundaries with full audit trail support.

RESULT SEMANTICS: 

SUCCESS DETERMINATION:
The Success field indicates whether the operation completed successfully
for the specific tenant. This is a binary determination - partial success
is considered failure with details provided in the Error and Details fields.

ERROR REPORTING:
Failed operations include human-readable error messages in the Error field
and structured diagnostic information in the Details field. This dual
approach supports both user-facing error reporting and programmatic
error handling.

TEMPORAL TRACKING:
The Timestamp field records the exact moment when the operation completed
(successfully or unsuccessfully) for the tenant, enabling precise audit
trails and temporal analysis of bulk operations.

AUDIT INTEGRATION: All bulk operation results are automatically integrated with the audit system, providing full traceability of administrative actions across tenant boundaries. Results can be correlated with audit events using the timestamp and tenant ID fields.

Fields: 

TenantID:  Unique identifier for the tenant affected by the operation
Success:   Boolean indicating successful completion for this tenant
Error:     Human-readable error message if Success is false
Details:   Structured diagnostic data for programmatic error handling
Timestamp: Exact completion time for audit and temporal correlation

type ContentType 

type ContentType string

ContentType represents the type of data stored in a secret.

Content types help with proper handling, validation, and presentation of secret data. They provide metadata that applications can use to correctly interpret the stored information without needing to examine the actual secret content. 

const (
	// ContentTypeText indicates plain text content (UTF-8 encoded).
	// Use for passwords, API keys, simple configuration values, etc.
	ContentTypeText ContentType = "text/plain"

	// ContentTypeJSON indicates JSON-formatted data.
	// Use for structured configuration data, API responses, or complex secret structures.
	ContentTypeJSON ContentType = "application/json"

	// ContentTypeTOML indicates TOML-formatted data.
	// Use for structured configuration data, API responses, or complex secret structures.
	ContentTypeTOML ContentType = "application/toml"

	// ContentTypeXML indicates XML-formatted data.
	// Use for structured configuration data, API responses, or complex secret structures.
	ContentTypeXML ContentType = "application/xml"

	// ContentTypeYAML indicates YAML-formatted data.
	// Use for configuration files, Kubernetes secrets, or structured data in YAML format.
	ContentTypeYAML ContentType = "application/yaml"

	// ContentTypePEM indicates PEM-encoded data (certificates, private keys).
	// Use for SSL certificates, private keys, public keys, or other cryptographic material.
	ContentTypePEM ContentType = "application/x-pem-file"

	// ContentTypeBinary indicates arbitrary binary data.
	// Use for encrypted files, binary keys, or any non-text data.
	ContentTypeBinary ContentType = "application/octet-stream"
)

type CryptoAlgorithm 

type CryptoAlgorithm string

CryptoAlgorithm represents the cryptographic algorithm used for encryption operations.

The vault supports multiple encryption algorithms, though ChaCha20-Poly1305 is currently the primary implementation. This enumeration allows for future algorithm support while maintaining backward compatibility. 

const (
	// ChaCha20Poly1305 represents the ChaCha20-Poly1305 authenticated encryption algorithm.
	// This is a modern, fast, and secure AEAD (Authenticated Encryption with Additional Data)
	// cipher that provides both confidentiality and authenticity. It's resistant to timing
	// attacks and performs well on both hardware with and without AES acceleration.
	//
	// Key characteristics:
	//   - 256-bit key size
	//   - 96-bit nonce (automatically generated)
	//   - 128-bit authentication tag
	//   - Constant-time implementation
	ChaCha20Poly1305 CryptoAlgorithm = "chacha20poly1305"
)

type KeyMetadata 

type KeyMetadata struct {
	// KeyID is the unique, immutable identifier for this cryptographic key.
	//
	// This field contains a cryptographically secure, globally unique identifier
	// that remains constant throughout the key's entire lifecycle. The identifier
	// is used for key lookup, audit trail correlation, and operational references.
	// Once assigned, the KeyID never changes, ensuring consistent referencing
	// across all vault operations and external systems.
	//
	// Identifier Characteristics:
	// - 32-character hexadecimal string providing 128 bits of entropy
	// - Generated using cryptographically secure pseudo-random number generator
	// - Globally unique within the vault instance and across backups
	// - Case-insensitive for operational convenience
	// - URL-safe for integration with external systems and APIs
	// - Immutable once assigned to prevent confusion and security issues
	//
	// Generation Process:
	// - Uses cryptographically secure random number generation (CSPRNG)
	// - Includes uniqueness validation against existing key identifiers
	// - Generated atomically during key creation process
	// - Preserved exactly during backup/restore operations
	// - Validated for format compliance during deserialization
	//
	// Usage Patterns:
	// - Primary key for all key management operations
	// - Reference in encryption/decryption operation metadata
	// - Audit trail correlation and security event analysis
	// - External system integration and API operations
	// - Backup/restore operation key identification
	//
	// Security Considerations:
	// - High entropy prevents guessing or collision attacks
	// - Immutability prevents substitution and confusion attacks
	// - No sensitive information embedded in identifier
	// - Safe for logging and external system integration
	// - Collision resistance ensures global uniqueness
	//
	// Example: "f47ac10b58cc4372a5670e02b2c3d479"
	// Format: ^[a-fA-F0-9]{32}$ (32 hexadecimal characters)
	// Validation: Must be exactly 32 characters, hexadecimal only
	KeyID string `json:"key_id"`

	// Status represents the current operational status of the key within its lifecycle.
	//
	// This field provides precise information about the key's availability and
	// authorized usage within the vault system. The status directly controls
	// whether the key can be used for new cryptographic operations while
	// preserving access to historical data encrypted with the key.
	//
	// Status Values and Meanings:
	// - KeyStatusActive: Key is fully operational and available for all operations
	//   * Can encrypt new data and decrypt existing data
	//   * Participates in normal vault operations
	//   * Subject to usage monitoring and policy enforcement
	//   * Available for high-performance cryptographic operations
	//
	// - KeyStatusRetired: Key is preserved for historical access only
	//   * Cannot encrypt new data but can decrypt existing data
	//   * Maintained for backward compatibility and data recovery
	//   * Subject to retention policies and archival procedures
	//   * May have reduced performance characteristics
	//
	// - KeyStatusCompromised: Key is suspected or known to be compromised
	//   * Immediately disabled for all new encryption operations
	//   * May be restricted for decryption based on security policies
	//   * Requires immediate attention and potential data re-encryption
	//   * Triggers security incident procedures and audit alerts
	//
	// - KeyStatusArchived: Key is in long-term storage for compliance
	//   * Available for decryption under specific compliance procedures
	//   * Subject to special access controls and audit requirements
	//   * May require additional authentication for access
	//   * Optimized for infrequent access patterns
	//
	// Status Transitions:
	// - Active → Retired: Normal key rotation process
	// - Active → Compromised: Security incident response
	// - Retired → Archived: Long-term retention policy
	// - Compromised → Archived: Post-incident stabilization
	// - Status transitions are logged and audited
	// - Transitions may trigger automated processes and notifications
	//
	// Operational Impact:
	// - Direct control over key availability for cryptographic operations
	// - Integration with access control and security policies
	// - Affects performance and caching strategies
	// - Influences backup and retention policies
	// - Controls integration with external systems and APIs
	Status KeyStatus `json:"status"`

	// Active is a boolean flag indicating immediate operational availability.
	//
	// This field provides a high-performance, binary indicator of whether
	// the key can be used for new cryptographic operations. It offers O(1)
	// status checking for performance-critical code paths while complementing
	// the more detailed Status field for comprehensive key management.
	//
	// Relationship to Status Field:
	// - Active=true: Key is available for new encryption (Status=Active)
	// - Active=false: Key is not available for new encryption (all other statuses)
	// - Derived from Status field but cached for performance
	// - Updated atomically with Status field changes
	// - Validated for consistency during metadata operations
	//
	// Performance Optimization:
	// - Enables fast key filtering without Status enum evaluation
	// - Optimized for high-frequency encryption path decisions
	// - Reduces CPU cycles in performance-critical operations
	// - Supports efficient key selection algorithms
	// - Minimizes lock contention during concurrent operations
	//
	// Usage Patterns:
	// - Quick filtering of available keys for encryption operations
	// - Fast validation in high-performance encryption paths
	// - Efficient key pool management and selection
	// - Rapid operational status checking without enum parsing
	// - Performance-optimized audit and monitoring operations
	//
	// Consistency Guarantees:
	// - Always consistent with Status field value
	// - Updated atomically during status transitions
	// - Validated during metadata serialization/deserialization
	// - Maintained correctly during backup/restore operations
	// - Verified during periodic consistency checks
	//
	// Example Values:
	// - true: Key can encrypt new data (Status=Active)
	// - false: Key cannot encrypt new data (Status≠Active)
	Active bool `json:"active"`

	// CreatedAt records the precise UTC timestamp when the key was generated.
	//
	// This field provides essential audit information and enables time-based
	// key management policies. The timestamp is captured at the moment of
	// cryptographic key generation and remains immutable throughout the
	// key's lifecycle. High precision timing supports accurate audit trails
	// and security event correlation across distributed systems.
	//
	// Timestamp Characteristics:
	// - Nanosecond precision for accurate ordering and correlation
	// - Always stored and represented in UTC timezone
	// - Immutable once set during key creation
	// - RFC3339 format for JSON serialization compatibility
	// - High resolution for distributed system event ordering
	//
	// Audit and Compliance Applications:
	// - Legal and regulatory audit trail requirements
	// - Security incident timeline reconstruction
	// - Key age calculation for rotation policy enforcement
	// - Compliance reporting and validation
	// - Forensic analysis and investigation support
	//
	// Policy Enforcement:
	// - Maximum key age policies and automated rotation
	// - Compliance-driven retention and archival policies
	// - Security baseline enforcement and validation
	// - Operational lifecycle management and planning
	// - Capacity planning and resource management
	//
	// Precision and Accuracy:
	// - Nanosecond precision: time.Time with nanosecond resolution
	// - Monotonic timing: Immune to system clock adjustments
	// - UTC normalization: Consistent across time zones and DST
	// - High accuracy: Suitable for distributed system event ordering
	// - Immutable value: Never modified after initial assignment
	//
	// Usage Examples:
	// - Age calculation: time.Since(metadata.CreatedAt)
	// - Policy evaluation: CreatedAt.Add(maxAge).Before(time.Now())
	// - Audit reporting: CreatedAt.Format(time.RFC3339Nano)
	// - Timeline analysis: Event ordering and correlation
	//
	// Example: 2024-01-15T14:30:22.123456789Z
	// Format: RFC3339 with nanosecond precision
	// Timezone: Always UTC (Z suffix)
	CreatedAt time.Time `json:"created_at"`

	// DeactivatedAt records when the key was deactivated/retired (nil if still active).
	//
	// This optional field captures the precise moment when a key transitions
	// from active use to retired status. The field remains nil for active keys
	// and is set atomically during key deactivation operations. This timestamp
	// is crucial for audit trails, retention policies, and security analysis.
	//
	// Lifecycle Semantics:
	// - nil value: Key is currently active and available for new encryption
	// - non-nil value: Key has been deactivated and timestamp recorded
	// - Set atomically during key rotation or manual deactivation
	// - Immutable once set (deactivation is permanent)
	// - Preserved exactly during backup/restore operations
	//
	// Audit and Security Applications:
	// - Key rotation audit trail and compliance reporting
	// - Security incident timeline and impact analysis
	// - Retention policy enforcement and archival planning
	// - Operational lifecycle tracking and management
	// - Forensic investigation and timeline reconstruction
	//
	// JSON Serialization:
	// - Uses "omitempty" tag to exclude nil values from JSON
	// - Reduces serialized metadata size for active keys
	// - RFC3339 format with nanosecond precision when present
	// - Consistent with CreatedAt field formatting and precision
	// - Handles timezone normalization to UTC automatically
	//
	// Policy Integration:
	// - Retention period calculation from deactivation timestamp
	// - Archival policy triggers based on deactivation age
	// - Access control policies for retired key usage
	// - Cleanup and disposal policies for expired keys
	// - Compliance validation for key lifecycle requirements
	//
	// Performance Considerations:
	// - Nil check is O(1) operation for active key identification
	// - Pointer type minimizes memory usage for active keys
	// - Efficient serialization with omitempty tag
	// - Fast filtering operations for retired key identification
	//
	// Usage Patterns:
	// - Active key check: metadata.DeactivatedAt == nil
	// - Retirement age: time.Since(*metadata.DeactivatedAt)
	// - Policy evaluation: DeactivatedAt.Add(retention).Before(time.Now())
	// - Audit reporting: Deactivation event documentation
	//
	// Example Values:
	// - nil: Key is currently active
	// - &time.Time{2024-01-20T09:15:30.456789Z}: Deactivated timestamp
	DeactivatedAt *time.Time `json:"deactivated_at,omitempty"`

	// Version indicates the metadata structure version for this key record.
	//
	// This field enables metadata format evolution and compatibility management
	// as the vault system develops new features and capabilities. Version
	// tracking ensures proper handling of metadata from different vault
	// versions and supports migration between metadata formats.
	//
	// Version Evolution:
	// - Version 1: Initial KeyMetadata implementation with basic lifecycle
	// - Version 2: Enhanced with detailed status tracking and audit fields
	// - Version 3: Added compliance metadata and policy integration
	// - Version 4: Extended with performance optimization and caching fields
	// - Future versions: Will add new capabilities while maintaining compatibility
	//
	// Compatibility Management:
	// - Forward compatibility: Newer vault versions handle older metadata
	// - Backward compatibility: Preserved during vault downgrades when possible
	// - Migration support: Automatic upgrade of metadata format when needed
	// - Validation: Version compatibility checked during deserialization
	// - Documentation: Version history maintained for operational reference
	//
	// Migration and Upgrade:
	// - Automatic migration during vault startup when safe
	// - Manual migration tools for major version transitions
	// - Backup preservation of original metadata format
	// - Rollback capability for failed migration scenarios
	// - Validation of migration integrity and completeness
	//
	// Operational Usage:
	// - Version validation during metadata loading and processing
	// - Feature availability determination based on metadata version
	// - Migration planning and compatibility assessment
	// - Backup/restore compatibility verification
	// - System integration and API compatibility management
	//
	// Best Practices:
	// - Always set to current version during key creation
	// - Validate version compatibility during operations
	// - Document version changes and migration requirements
	// - Test compatibility across version boundaries
	// - Monitor version distribution in production systems
	//
	// Example Values:
	// - 1: Original metadata format
	// - 2: Enhanced format with additional audit fields
	// - 3: Current production format with full feature support
	Version int `json:"version"`

	// Reason documents the rationale for key creation or status changes.
	//
	// This field provides essential context for audit trails, compliance
	// reporting, and security analysis. It captures human-readable explanations
	// for key lifecycle events, enabling comprehensive documentation of
	// key management decisions and security operations.
	//
	// Content Categories:
	// - Creation reasons: Why the key was initially generated
	// - Rotation reasons: Rationale for key rotation operations
	// - Deactivation reasons: Explanation for key retirement
	// - Status change reasons: Context for operational status updates
	// - Security reasons: Documentation of security-related decisions
	//
	// Common Creation Reasons:
	// - "Initial vault setup and configuration"
	// - "Scheduled key rotation per security policy"
	// - "Emergency replacement due to security incident"
	// - "Compliance-driven key generation for new requirements"
	// - "Performance optimization with new cryptographic algorithms"
	// - "Disaster recovery key restoration from backup"
	// - "Multi-tenant isolation requiring dedicated keys"
	//
	// Security and Incident Reasons:
	// - "Potential key compromise detected in security audit"
	// - "Precautionary rotation following infrastructure breach"
	// - "Compliance violation remediation and key replacement"
	// - "Unauthorized access attempt detected"
	// - "Security policy violation requiring immediate rotation"
	// - "External security advisory recommending key rotation"
	//
	// Operational Reasons:
	// - "Scheduled maintenance window key rotation"
	// - "Algorithm upgrade to improve performance"
	// - "Infrastructure migration requiring new keys"
	// - "Load balancing and performance optimization"
	// - "Geographic distribution and compliance requirements"
	// - "Integration with new security systems and controls"
	//
	// Audit and Compliance Integration:
	// - Required documentation for regulatory compliance frameworks
	// - Essential evidence for security audits and assessments
	// - Supporting documentation for incident response procedures
	// - Historical context for forensic analysis and investigation
	// - Compliance validation and reporting automation support
	//
	// Best Practices:
	// - Use consistent terminology and format across the organization
	// - Include relevant incident, ticket, or policy reference numbers
	// - Provide sufficient detail for audit and compliance requirements
	// - Document emergency actions with appropriate urgency indicators
	// - Include regulatory or policy drivers when applicable
	// - Reference external events or advisories when relevant
	//
	// Format and Constraints:
	// - Maximum length: 1000 characters to prevent excessive storage usage
	// - UTF-8 encoding: Support for international characters and symbols
	// - Free-form text: Flexible format while encouraging consistency
	// - Required field: Must not be empty for audit trail completeness
	// - Preserved exactly: Maintained during backup/restore operations
	//
	// Privacy and Security:
	// - Should not contain sensitive information or credentials
	// - Safe for logging and external system integration
	// - Appropriate for compliance reporting and audit documentation
	// - Does not expose cryptographic material or internal secrets
	//
	// Example Values:
	// - "Initial vault deployment for production workload encryption"
	// - "Quarterly key rotation per security policy SEC-2024-001"
	// - "Emergency rotation following security incident INC-2024-0156"
	// - "Compliance rotation for SOC 2 Type II audit requirements"
	// - "Performance optimization migration to ChaCha20-Poly1305"
	//
	// Integration with External Systems:
	// - ITSM ticket references: "ServiceNow ticket CHG0012345"
	// - Security incident references: "PagerDuty incident PD-2024-0089"
	// - Compliance framework references: "NIST CSF requirement RSK-3.2"
	// - Policy references: "Corporate policy SEC-POL-2024-003"
	Reason string `json:"reason"`
}

KeyMetadata represents comprehensive metadata and lifecycle information for individual vault keys.

This structure provides detailed tracking and management information for each cryptographic key within the vault system. It serves as the authoritative record of a key's lifecycle, status, and operational history. KeyMetadata enables fine-grained key management, audit reporting, compliance validation, and security policy enforcement while maintaining complete separation from the actual key material for enhanced security.

STRUCTURE PURPOSE AND SCOPE: KeyMetadata serves multiple critical functions in the vault ecosystem: - Tracks individual key lifecycle from creation through deactivation - Provides operational status information for key usage decisions - Enables audit trail generation for compliance and security reporting - Supports key rotation planning and policy enforcement - Facilitates security incident response and forensic analysis - Enables automated key management and lifecycle policies - Provides data for capacity planning and performance optimization - Supports regulatory compliance and governance requirements

SECURITY ARCHITECTURE: The metadata structure implements security-by-design principles: - Complete separation of metadata from actual cryptographic key material - Immutable key identifiers prevent confusion and substitution attacks - Comprehensive audit trail for all key lifecycle events - Status tracking prevents unauthorized key usage - Timestamp precision enables accurate security event correlation - Version tracking supports secure metadata evolution - Reason documentation enables security incident investigation

KEY LIFECYCLE INTEGRATION: KeyMetadata integrates with the complete key lifecycle management system: - Creation: Records initial key generation with secure timestamps - Activation: Tracks when keys become available for cryptographic operations - Usage: Monitors key operational status and availability - Rotation: Documents key transitions during rotation operations - Deactivation: Records key retirement with preservation for historical access - Archival: Supports long-term retention with appropriate status tracking - Recovery: Enables backup/restore with complete lifecycle preservation

FIELD SPECIFICATIONS:

type KeyRotationMetadata 

type KeyRotationMetadata struct {
	// Version indicates the metadata format version for compatibility management.
	//
	// This field enables forward and backward compatibility as the key rotation
	// system evolves. It supports metadata format migrations and ensures
	// proper handling of different metadata versions during vault upgrades.
	//
	// Version History:
	// - Version 1: Initial implementation with basic rotation support
	// - Version 2: Enhanced with rotation reason tracking and audit data
	// - Version 3: Added compliance metadata and policy enforcement
	//
	// Usage:
	// - Always set to current metadata version during rotation operations
	// - Validated during metadata loading to ensure compatibility
	// - Used for migration logic when upgrading vault versions
	// - Preserved during backup/restore to maintain compatibility
	//
	// Range: 1-N (where N is the latest supported version)
	// Default: Set to current implementation version
	Version int `json:"version"`

	// CurrentKeyID identifies the active encryption key for new operations.
	//
	// This field contains the unique identifier of the key currently used
	// for all new encryption operations. The key ID is a cryptographically
	// secure random identifier that uniquely identifies each key throughout
	// its lifecycle. This field is updated atomically during key rotation.
	//
	// Key ID Format:
	// - 32-character hexadecimal string (128-bit entropy)
	// - Generated using cryptographically secure random number generator
	// - Globally unique within the vault instance
	// - Immutable once assigned to a key
	//
	// Usage:
	// - Referenced during all new encryption operations
	// - Updated atomically during successful key rotation
	// - Validated against Keys map to ensure consistency
	// - Used for key selection in high-performance encryption paths
	//
	// Example: "a1b2c3d4e5f6789012345678901234567890abcd"
	// Validation: Must exist as a key in both Keys and EncryptedKeys maps
	CurrentKeyID string `json:"current_key_id"`

	// LastRotation records the timestamp of the most recent key rotation.
	//
	// This field enables rotation policy enforcement, audit reporting,
	// and operational monitoring. The timestamp is always stored in UTC
	// to ensure consistent behavior across different time zones and
	// daylight saving time transitions.
	//
	// Precision: Nanosecond precision for ordering and audit accuracy
	// Format: RFC3339 with nanosecond precision in JSON serialization
	// Timezone: Always UTC to ensure consistent behavior
	//
	// Usage:
	// - Used for rotation policy enforcement (e.g., rotate every 90 days)
	// - Provides audit trail for compliance reporting
	// - Enables monitoring and alerting on rotation frequency
	// - Supports disaster recovery timeline reconstruction
	//
	// Policy Applications:
	// - Automatic rotation scheduling based on age
	// - Compliance reporting for regulatory requirements
	// - Security monitoring for unusual rotation patterns
	// - Operational dashboards and health monitoring
	LastRotation time.Time `json:"last_rotation"`

	// Keys contains metadata for all keys in the vault (current and historical).
	//
	// This map provides comprehensive information about each key without
	// exposing the actual key material. The metadata includes creation
	// timestamps, usage statistics, rotation history, and lifecycle status.
	// This information is essential for key management, audit reporting,
	// and compliance operations.
	//
	// Map Structure:
	// - Key: Unique key identifier (same format as CurrentKeyID)
	// - Value: KeyMetadata struct containing detailed key information
	//
	// KeyMetadata Contents:
	// - CreatedAt: UTC timestamp of key generation
	// - Status: Key lifecycle status (Active, Retired, Archived)
	// - Algorithm: Cryptographic algorithm and parameters
	// - UsageCount: Number of encryption operations performed
	// - LastUsed: Timestamp of most recent usage
	// - RetiredAt: Timestamp when key was retired (if applicable)
	// - Purpose: Intended use case and scope
	// - Compliance: Regulatory and policy compliance information
	//
	// Usage Patterns:
	// - Lookup key metadata during encryption/decryption operations
	// - Generate key usage reports for audit and compliance
	// - Implement key lifecycle policies and automated management
	// - Support key rotation planning and capacity management
	//
	// Example:
	// {
	//   "a1b2c3d4...": {
	//     "CreatedAt": "2024-01-01T00:00:00Z",
	//     "Status": "Active",
	//     "Algorithm": "ChaCha20-Poly1305",
	//     "UsageCount": 15234,
	//     "LastUsed": "2024-01-15T14:30:22Z"
	//   }
	// }
	Keys map[string]KeyMetadata `json:"keys"`

	// EncryptedKeys stores the actual encrypted key material for all keys.
	//
	// This map contains the cryptographic key material encrypted using the
	// vault's derivation key. The encrypted keys enable decryption of
	// historical data while maintaining security through encryption at rest.
	// This is the most security-sensitive field in the metadata structure.
	//
	// Encryption Details:
	// - Keys are encrypted using ChaCha20-Poly1305 authenticated encryption
	// - Encryption key derived from vault's master derivation key
	// - Each key is encrypted independently with unique nonce
	// - Authenticated encryption provides integrity and authenticity
	// - Key material is securely cleared from memory after encryption
	//
	// Map Structure:
	// - Key: Unique key identifier (matches Keys map keys)
	// - Value: Encrypted key material as byte slice
	//
	// Storage Format:
	// - Encrypted key material (32 bytes for ChaCha20-Poly1305)
	// - Authentication tag (16 bytes)
	// - Nonce/IV (12 bytes for ChaCha20-Poly1305)
	// - Total: 60 bytes per encrypted key
	//
	// Security Considerations:
	// - Key material never stored in plaintext
	// - Encrypted keys are useless without vault's derivation key
	// - Memory is securely cleared after key operations
	// - Access to encrypted keys requires full vault authentication
	// - Backup encryption provides additional protection layer
	//
	// Usage:
	// - Decrypt keys on-demand for cryptographic operations
	// - Support historical data decryption with retired keys
	// - Enable key rotation without data migration
	// - Facilitate backup/restore operations with full key recovery
	//
	// Example:
	// {
	//   "a1b2c3d4...": [...encrypted key bytes...],
	//   "b2c3d4e5...": [...encrypted key bytes...]
	// }
	EncryptedKeys map[string][]byte `json:"encrypted_keys"`

	// Reason documents the rationale for the most recent key rotation.
	//
	// This field provides essential audit information and helps with
	// compliance reporting, security incident response, and operational
	// documentation. The reason is stored as free-form text but should
	// follow organizational standards for consistency and searchability.
	//
	// Common Rotation Reasons:
	// - "Scheduled rotation per policy" - Regular policy-driven rotation
	// - "Security incident response" - Rotation due to security concerns
	// - "Compliance requirement" - Rotation for regulatory compliance
	// - "Administrative request" - Manual rotation by administrators
	// - "Key compromise suspected" - Precautionary rotation
	// - "Vault migration" - Rotation during infrastructure changes
	// - "Algorithm upgrade" - Rotation to newer cryptographic algorithms
	// - "Performance optimization" - Rotation for operational improvements
	//
	// Best Practices:
	// - Use consistent terminology across the organization
	// - Include relevant incident or ticket numbers
	// - Specify regulatory or policy requirements when applicable
	// - Document emergency rotations with appropriate detail
	// - Include timing rationale for non-scheduled rotations
	//
	// Audit and Compliance:
	// - Required for many regulatory compliance frameworks
	// - Essential for security audit trails and incident response
	// - Supports forensic analysis and timeline reconstruction
	// - Enables automated compliance reporting and validation
	//
	// Example Values:
	// - "Scheduled quarterly rotation per security policy SP-2024-001"
	// - "Emergency rotation following security incident INC-2024-0234"
	// - "Compliance rotation required by SOC 2 Type II audit"
	// - "Proactive rotation during infrastructure maintenance window"
	//
	// Maximum Length: 1000 characters (to prevent excessive storage usage)
	// Encoding: UTF-8 to support international characters
	Reason string `json:"reason"`
}

KeyRotationMetadata represents the complete state and history of vault key rotation operations.

This structure serves as the authoritative record of all key management activities within the vault, including current key status, rotation history, and encrypted key material. It provides the foundation for key lifecycle management, audit trails, and disaster recovery operations. The metadata is persisted to storage and maintained across vault restarts and backup/restore operations.

STRUCTURE PURPOSE AND SCOPE: The KeyRotationMetadata serves multiple critical functions: - Tracks the current active encryption key for new operations - Maintains complete history of all keys (active and retired) - Stores encrypted key material for all historical keys - Records rotation timing and reasoning for audit purposes - Enables key lifecycle management and compliance reporting - Supports disaster recovery and backup/restore operations - Provides data for key rotation policy enforcement - Facilitates cryptographic key inventory and management

SECURITY ARCHITECTURE: The metadata structure implements defense-in-depth security: - Key material is stored encrypted using vault's derivation key - Multiple layers of encryption protect sensitive key data - Metadata separation from actual key material prevents leakage - Audit information is stored separately from cryptographic material - Version tracking enables rollback and recovery scenarios - Tamper detection through metadata integrity verification - Secure serialization with authenticated encryption

KEY LIFECYCLE MANAGEMENT: The structure supports complete key lifecycle operations: - Key creation with secure random generation - Key activation for new encryption operations - Key retirement without data loss (historical keys remain accessible) - Key rotation with seamless transition and no service interruption - Key archival with long-term retention policies - Key destruction with secure memory clearing - Key recovery from backup with full operational capability

FIELD SPECIFICATIONS:

type KeyStatus 

type KeyStatus string

KeyStatus represents the lifecycle state of a vault key.

Keys progress through different states during their lifecycle:

  • Active: The key is currently used for new encryption operations
  • Inactive: The key is no longer used for new encryptions but remains available for decryption

This status system enables key rotation while maintaining the ability to decrypt existing data encrypted with older keys. 

const (
	// KeyStatusActive indicates the key is currently used for new encryptions.
	// Only one key should be active at any given time. When a new key is generated
	// through rotation, it becomes active and the previous active key becomes inactive.
	KeyStatusActive KeyStatus = "active"

	// KeyStatusInactive indicates the key is not used for new encryptions,
	// but can still be used for decryption of existing data.
	// Inactive keys are retained to ensure data encrypted with them remains accessible.
	// Inactive keys can be destroyed if no longer needed, but this makes associated
	// encrypted data permanently unrecoverable.
	KeyStatusInactive KeyStatus = "inactive"
)

type Options 

type Options struct {
	// KEY DERIVATION CONFIGURATION:
	// Critical cryptographic parameters that control the security and uniqueness
	// of derived encryption keys. These parameters directly impact vault security
	// and must be handled with extreme care to prevent unauthorized access.
	//
	// DerivationSalt provides cryptographic uniqueness and prevents rainbow table attacks.
	// This field contains high-entropy random data that ensures each vault instance
	// derives unique encryption keys even when using identical passphrases. The salt
	// must be cryptographically random, sufficiently long (minimum 32 bytes recommended),
	// and unique per vault instance to provide maximum security benefits.
	//
	// Security Characteristics:
	// - Prevents precomputed attack vectors through cryptographic uniqueness
	// - Ensures vault instance isolation even with shared passphrases
	// - Provides forward security through unique key derivation per instance
	// - Protects against correlation attacks across multiple vault instances
	//
	// Operational Requirements:
	// - Generated using cryptographically secure random number generator (CSPRNG)
	// - Minimum entropy of 256 bits (32 bytes) for cryptographic security
	// - Stored securely and backed up with same protection as vault data
	// - Never transmitted in plaintext or stored in configuration files
	// - Consistent across vault backups and disaster recovery operations
	//
	// Serialization Security:
	// - json:"-" tag prevents inclusion in JSON serialization
	// - Never persisted in configuration files or transmitted over networks
	// - Excluded from all logging and audit output for security protection
	// - Must be provided through secure channels during vault initialization
	//
	// Backup and Recovery Implications:
	// - Required for vault access after disaster recovery operations
	// - Must be stored securely separate from encrypted data backups
	// - Critical for emergency access and business continuity procedures
	// - Loss of salt renders vault data permanently inaccessible
	DerivationSalt []byte `json:"-"` // Don't serialize salt for security

	// DerivationPassphrase provides authentication and key material for vault access.
	// This field contains the master passphrase used in conjunction with the salt
	// to derive the vault's master encryption key through cryptographic key derivation.
	// The passphrase represents the primary authentication factor for vault access
	// and must meet strict security requirements for length, complexity, and entropy.
	//
	// Security Requirements:
	// - Minimum length of 12 characters, recommended 20+ characters
	// - High entropy combining multiple character classes and unpredictable patterns
	// - Unique to the vault instance and not reused across systems
	// - Protected against brute force attacks through key derivation parameters
	// - Regularly rotated according to security policy and compliance requirements
	//
	// Passphrase Composition Guidelines:
	// - Combination of uppercase and lowercase letters for character diversity
	// - Numeric digits for increased keyspace and entropy
	// - Special characters for maximum cryptographic strength
	// - Avoid dictionary words, predictable patterns, and personal information
	// - Consider passphrase generators for maximum entropy and unpredictability
	//
	// Operational Security:
	// - Never logged, displayed, or included in error messages
	// - Cleared from memory immediately after key derivation
	// - Transmitted only through secure channels during initialization
	// - Never stored persistently or included in configuration files
	// - Protected against shoulder surfing and social engineering attacks
	//
	// Serialization Security:
	// - json:"-" tag prevents inclusion in JSON serialization
	// - Excluded from all configuration output and system documentation
	// - Never appears in process arguments or environment variable listings
	// - Protected against accidental exposure through debugging or logging
	//
	// Emergency Access Considerations:
	// - Required for vault access during emergency and disaster recovery
	// - Must be secured using approved key management and escrow procedures
	// - Split knowledge and dual control recommended for high-security environments
	// - Recovery procedures must balance security and operational accessibility
	DerivationPassphrase string `json:"-"` // Don't serialize passphrase for security

	// EnvPassphraseVar specifies environment variable name containing the vault passphrase.
	// This field enables secure passphrase delivery through environment variables,
	// avoiding exposure through command-line arguments or configuration files.
	// When specified, the vault retrieves the passphrase from the named environment
	// variable during initialization, providing secure integration with deployment
	// automation and orchestration systems.
	//
	// Security Benefits:
	// - Avoids command-line argument exposure in process lists and system logs
	// - Prevents passphrase inclusion in configuration files and version control
	// - Enables secure integration with container orchestration and deployment systems
	// - Supports automated deployment while maintaining security boundaries
	// - Facilitates secure credential management and rotation procedures
	//
	// Environment Variable Security:
	// - Environment variable should be set with restricted access permissions
	// - Consider using secure secret management systems for environment variable population
	// - Ensure environment variables are not logged or exposed in system monitoring
	// - Use process isolation to prevent unauthorized environment variable access
	// - Clear environment variables after vault initialization when possible
	//
	// Deployment Integration:
	// - Compatible with Docker secrets and Kubernetes secret management
	// - Supports HashiCorp Vault integration for secure credential delivery
	// - Enables AWS Secrets Manager and Azure Key Vault integration
	// - Compatible with enterprise credential management and rotation systems
	// - Supports CI/CD pipeline integration with secure credential handling
	//
	// Operational Considerations:
	// - Environment variable name should follow organizational naming conventions
	// - Consider using prefixes like "VAULT_" or "SECURE_" for clear identification
	// - Document environment variable requirements in deployment procedures
	// - Include in backup and disaster recovery documentation and procedures
	// - Monitor for environment variable availability during vault startup
	//
	// Example Values:
	// - "VAULT_MASTER_PASSPHRASE" - Clear identification and organizational consistency
	// - "SECURE_VAULT_KEY" - Security-focused naming convention
	// - "APP_VAULT_PASSPHRASE" - Application-specific identification
	// - Custom naming based on organizational security and operational policies
	EnvPassphraseVar string `json:"env_passphrase_var,omitempty"`

	// MEMORY PROTECTION SETTINGS:
	// Advanced security configuration that controls memory handling and protection
	// mechanisms to prevent sensitive data exposure through memory dumps, swap files,
	// or unauthorized memory access. Memory protection is critical for high-security
	// environments and regulatory compliance requirements.
	//
	// EnableMemoryLock controls memory locking to prevent sensitive data paging to disk.
	// When enabled, the vault attempts to lock critical memory regions containing
	// encryption keys, passphrases, and sensitive data in physical RAM to prevent
	// exposure through swap files, hibernation files, or memory dumps. This provides
	// additional protection against cold boot attacks and forensic memory analysis.
	//
	// Memory Locking Benefits:
	// - Prevents sensitive data exposure through virtual memory paging
	// - Protects against swap file analysis and forensic memory recovery
	// - Reduces risk of sensitive data persistence in hibernation files
	// - Provides defense against cold boot attacks and memory imaging
	// - Supports compliance requirements for data protection and privacy regulations
	//
	// Operating System Integration:
	// - Unix/Linux: Uses mlock()/mlockall() system calls for memory locking
	// - Windows: Uses VirtualLock() for memory page locking and protection
	// - Requires appropriate process privileges for memory locking operations
	// - May require system configuration for memory locking limits and permissions
	// - Performance impact varies by operating system and available physical memory
	//
	// Security Considerations:
	// - Memory locking is not a complete protection against all memory-based attacks
	// - Consider additional protections like memory encryption and secure enclaves
	// - Monitor system performance impact and adjust memory allocation accordingly
	// - Combine with other security measures for comprehensive protection
	// - Regular security assessment and penetration testing for memory protection validation
	//
	// Operational Requirements:
	// - Sufficient physical memory to accommodate locked memory regions
	// - Operating system configuration for memory locking permission and limits
	// - Process privilege configuration for memory management operations
	// - Monitoring for memory locking success and failure conditions
	// - Documentation of memory protection requirements and troubleshooting procedures
	//
	// Performance Impact:
	// - Locked memory cannot be swapped, potentially increasing physical memory usage
	// - May impact system performance under memory pressure conditions
	// - Consider memory allocation patterns and vault usage characteristics
	// - Monitor system performance and memory utilization during operations
	// - Balance security requirements with operational performance needs
	//
	// Compliance and Regulatory Support:
	// - Supports PCI DSS requirements for cardholder data protection in memory
	// - HIPAA compliance for protected health information memory handling
	// - SOX compliance for financial data protection and memory security
	// - GDPR compliance for personal data protection and privacy requirements
	// - Custom regulatory requirements for memory protection and data handling
	EnableMemoryLock bool `json:"enable_memory_lock"`

	// the user creating and using the vault manager instance
	UserID string `json:"-"`
}

Options represents comprehensive configuration parameters for vault initialization and operation.

This structure provides fine-grained control over vault security, performance, and operational characteristics during initialization and runtime operation. It encompasses critical security settings, memory protection configurations, key derivation parameters, and operational modes that collectively define the vault's security posture and operational behavior. The Options structure implements security-by-design principles with clear separation between serializable configuration and sensitive operational parameters that must never be persisted or transmitted.

STRUCTURE PURPOSE AND SCOPE: Options serves as the comprehensive configuration interface for vault operations: - Controls cryptographic key derivation parameters and security settings - Manages memory protection and secure memory handling configurations - Defines operational modes and debugging capabilities for development and production - Provides environment-based security configuration for deployment flexibility - Enables security policy enforcement through configuration-driven controls - Supports compliance requirements through configurable security parameters - Facilitates operational monitoring and troubleshooting through controlled debugging - Enables secure deployment patterns through environment variable integration

SECURITY ARCHITECTURE AND DESIGN: The Options structure implements multiple layers of security protection:

Serialization Security: - Critical security fields marked with `json:"-"` prevent accidental serialization - Salt and passphrase never included in JSON output or configuration files - Clear distinction between persistent configuration and runtime security parameters - Protection against configuration file exposure and unauthorized access - Secure logging integration that automatically excludes sensitive fields

Memory Security Integration: - Memory locking configuration prevents sensitive data swapping to disk - Integration with secure memory management and protection systems - Configuration-driven security policy enforcement for memory handling - Support for high-security environments requiring memory protection

Environment Variable Security: - Secure passphrase delivery through environment variables - Avoids command-line argument exposure in process lists - Supports secure deployment automation and orchestration - Enables configuration management integration without credential exposure

Configuration Security: - Separates security-critical parameters from operational configuration - Prevents accidental exposure through configuration management systems - Supports secure configuration validation and policy enforcement - Enables audit trail generation for security configuration changes

func (Options) Validate 

func (o Options) Validate() error

Validate validates the Options configuration

type RetryConfig 

type RetryConfig struct {
	MaxRetries int
	BaseDelay  time.Duration
	MaxDelay   time.Duration
}

RetryConfig configures retry behavior for concurrent operations

func DefaultRetryConfig 

func DefaultRetryConfig() RetryConfig

DefaultRetryConfig returns a sensible default retry configuration

type SecretEntry 

type SecretEntry struct {
	// ID is the unique identifier for this secret within the vault.
	// IDs should be unique across the entire vault namespace and are used
	// for all retrieval, update, and deletion operations.
	ID string `json:"id"`

	// Data contains the encrypted secret payload.
	// This data is encrypted using the vault's current encryption algorithm
	// and includes authentication information to detect tampering.
	// The data remains encrypted at rest and is only decrypted in memory
	// during GetSecret operations.
	Data []byte `json:"data"`

	// Metadata contains descriptive information about the secret.
	// This includes content type, description, tags, encryption details,
	// access patterns, and custom fields. Metadata is stored in encrypted form
	// alongside the secret data.
	Metadata *SecretMetadata `json:"metadata"`

	// CreatedAt indicates when this secret was first stored in the vault.
	// This timestamp is set once during initial secret creation and never changes.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt indicates when this secret was last modified.
	// This includes updates to the secret data, metadata, or tags.
	// It's updated automatically during UpdateSecret operations.
	UpdatedAt time.Time `json:"updated_at"`

	// Tags provide a way to categorize and filter secrets.
	// Tags can be used for organizing secrets, implementing access controls,
	// or facilitating batch operations. They're indexed for efficient querying.
	Tags []string `json:"tags,omitempty"`

	// Version indicates the current version number of this secret.
	// The version is incremented each time the secret is updated,
	// providing a simple way to track changes and detect concurrent modifications.
	Version int `json:"version"`
}

SecretEntry represents a complete secret record including encrypted data and metadata.

This structure contains everything needed to manage a secret throughout its lifecycle: the encrypted payload, descriptive metadata, versioning information, and audit trails.

SecretEntry is used internally by the vault for storage and retrieval operations. The encrypted Data field is only decrypted when explicitly requested through the GetSecret operation.

type SecretListEntry 

type SecretListEntry struct {
	// ID is the unique identifier for this secret.
	// This is used for subsequent operations like GetSecret, UpdateSecret, or DeleteSecret.
	ID string `json:"id"`

	// Metadata contains all descriptive information about the secret.
	// This includes content type, tags, creation dates, access patterns,
	// and custom fields, but excludes the encrypted payload.
	Metadata *SecretMetadata `json:"metadata"`

	// CreatedAt indicates when this secret was first stored.
	// Duplicated from metadata for convenient access during listing operations.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt indicates when this secret was last modified.
	// Duplicated from metadata for convenient sorting and filtering.
	UpdatedAt time.Time `json:"updated_at"`

	// Tags provide categorization information for filtering and organization.
	// Duplicated from metadata for efficient query operations.
	Tags []string `json:"tags,omitempty"`

	// Version indicates the current version of this secret.
	// Useful for detecting changes and managing concurrent access.
	Version int `json:"version"`

	// DataSize indicates the size of the encrypted data in bytes.
	// This provides storage utilization information without exposing
	// the actual secret size or content.
	DataSize int `json:"data_size"`
}

SecretListEntry represents a secret entry for listing operations without exposing encrypted data.

This structure provides all the information needed for secret management operations (listing, filtering, metadata operations) while maintaining security by excluding the actual encrypted secret payload.

SecretListEntry is returned by ListSecrets and similar operations where bulk secret information is needed without the overhead and security implications of including encrypted data.

type SecretListOptions 

type SecretListOptions struct {
	// Tags filters results to include only secrets that have ALL specified tags.
	// This implements AND logic - a secret must have every tag in this list
	// to be included in results. Use empty slice or nil for no tag filtering.
	Tags []string `json:"tags,omitempty"`

	// Prefix filters results to include only secrets whose ID starts with this string.
	// This enables hierarchical secret organization (e.g., "app1/", "prod/")
	// and efficient range-based queries. Case-sensitive matching is used.
	Prefix string `json:"prefix,omitempty"`

	// Limit restricts the maximum number of results returned.
	// Use 0 or negative values for no limit. When combined with Offset,
	// this enables pagination through large result sets.
	Limit int `json:"limit,omitempty"`

	// Offset specifies how many matching results to skip before returning data.
	// Use with Limit to implement pagination. Results should be consistently
	// ordered (typically by ID or creation time) for reliable pagination.
	Offset int `json:"offset,omitempty"`

	// ContentType filters results to include only secrets of the specified type.
	// This helps applications find secrets of specific formats
	// (e.g., only certificates, only JSON configurations).
	ContentType ContentType `json:"contentType,omitempty"`
}

SecretListOptions provides filtering and pagination options for listing secrets.

These options enable efficient querying of large secret collections without requiring full table scans or loading unnecessary data into memory.

Multiple filter criteria can be combined (AND logic) to narrow results. Pagination options help manage large result sets and API response times.

type SecretMetadata 

type SecretMetadata struct {
	// SecretID is the unique identifier matching the parent SecretEntry.ID.
	// This redundancy ensures metadata can be processed independently
	// and provides data integrity validation.
	SecretID string `json:"secret_id"`

	// Version matches the parent SecretEntry version number.
	// This provides consistency checking and helps detect data corruption
	// or synchronization issues.
	Version int `json:"version"`

	// ContentType indicates the format/type of the secret data.
	// This helps applications properly interpret and handle the decrypted data
	// without needing to examine the content itself.
	ContentType ContentType `json:"content_type,omitempty"`

	// Description provides human-readable information about the secret's purpose.
	// This can include usage instructions, owner information, or context
	// about when and why the secret was created.
	Description string `json:"description,omitempty"`

	// Tags enable categorization and filtering of secrets.
	// Common patterns include environment tags (prod, staging, dev),
	// application tags, or security classification tags.
	Tags []string `json:"tags,omitempty"`

	// KeyID identifies which vault key was used to encrypt this secret.
	// This enables the vault to select the correct key for decryption
	// and supports key rotation scenarios where multiple keys may be active.
	KeyID string `json:"key_id"`

	// CreatedAt indicates when this secret was first created.
	// This timestamp is immutable and used for audit trails and lifecycle management.
	CreatedAt time.Time `json:"created_at"`

	// UpdatedAt indicates when this secret was last modified.
	// This includes changes to the secret data, metadata, or tags.
	UpdatedAt time.Time `json:"updated_at"`

	// Size indicates the size in bytes of the original (decrypted) secret data.
	// This helps with capacity planning and provides insight into secret
	// sizes without requiring decryption.
	Size int `json:"size"`

	// Checksum provides integrity verification for the decrypted secret data.
	// This can be used to detect corruption or unauthorized modification
	// of secret data during storage or transmission.
	Checksum string `json:"checksum,omitempty"`

	// AccessCount tracks how many times this secret has been retrieved.
	// This metric supports usage analysis, license compliance,
	// and identification of unused secrets.
	AccessCount int64 `json:"access_count"`

	// LastAccessed indicates when this secret was last retrieved.
	// Combined with AccessCount, this provides usage pattern analysis
	// and helps identify stale or abandoned secrets.
	LastAccessed *time.Time `json:"last_accessed,omitempty"`

	// ExpiresAt provides automatic expiration for time-sensitive secrets.
	// When set, the vault can warn about or automatically handle
	// expired secrets according to configured policies.
	ExpiresAt *time.Time `json:"expires_at,omitempty"`

	// CustomFields allows applications to store additional structured metadata.
	// This provides extensibility for application-specific requirements
	// without modifying the core metadata schema.
	// Examples: cost center, compliance classification, rotation schedule.
	CustomFields map[string]string `json:"custom_fields,omitempty"`
}

SecretMetadata contains descriptive and operational information about a secret.

Metadata provides rich context about secrets without exposing the actual secret data. This information supports secret lifecycle management, access control, audit requirements, and operational monitoring.

The metadata is stored alongside the encrypted secret data and is itself encrypted at rest to prevent information leakage.

type SecretResult 

type SecretResult struct {
	Data          []byte
	Metadata      *SecretMetadata
	UsedActiveKey bool
}

SecretResult represents the complete result of a GetSecret operation

type SecretWithContext 

type SecretWithContext struct {
	// contains filtered or unexported fields
}

SecretWithContext provides context-based automatic cleanup for secrets. Always call Close() when done to ensure immediate cleanup.

func (*SecretWithContext) Close 

func (swc *SecretWithContext) Close()

Close manually closes and clears the secret immediately

func (*SecretWithContext) Data 

func (swc *SecretWithContext) Data() []byte

Data returns the secret data. Use with caution - data will be cleared when context expires or Close() is called.

func (*SecretWithContext) Done 

func (swc *SecretWithContext) Done() <-chan struct{}

Done returns the context done channel

func (*SecretWithContext) IsCleared 

func (swc *SecretWithContext) IsCleared() bool

IsCleared returns whether the secret has been cleared

func (*SecretWithContext) String 

func (swc *SecretWithContext) String() string

String returns the secret as a string. Use with caution - data will be cleared when context expires or Close() is called.

type SecretsContainer 

type SecretsContainer struct {
	// Version indicates the schema version of the secrets container format.
	// This enables backward compatibility and migration strategies when the
	// container format evolves.
	Version string `json:"version"`

	// Timestamp indicates when this container was last modified.
	// This can be used for synchronization, backup verification, and audit purposes.
	Timestamp time.Time `json:"timestamp"`

	// Secrets contains the actual secret entries, indexed by their unique identifiers.
	// The map key is the secret ID, and the value contains both the encrypted data
	// and associated metadata.
	Secrets map[string]*SecretEntry `json:"secrets"`
}

SecretsContainer contains metadata about a stored secret and serves as the top-level structure for persisting secrets to storage.

This container provides versioning and timestamp information for the entire collection of secrets, enabling migration strategies and data integrity verification.

The container is typically serialized to JSON when persisted to disk or transmitted over the network in encrypted form.

type SecureString 

type SecureString struct {
	// contains filtered or unexported fields
}

SecureString provides secure string handling with automatic cleanup using memguard

func NewSecureString 

func NewSecureString(data []byte) (*SecureString, error)

NewSecureString creates a new SecureString from byte data

func (*SecureString) Bytes 

func (ss *SecureString) Bytes() []byte

Bytes returns the underlying byte slice. Data will be cleared when Close() is called.

func (*SecureString) Close 

func (ss *SecureString) Close()

Close securely wipes the string from memory

func (*SecureString) IsCleared 

func (ss *SecureString) IsCleared() bool

IsCleared returns whether the string has been cleared

func (*SecureString) String 

func (ss *SecureString) String() string

String returns the string value. Data will be cleared when Close() is called.

type Vault 

type Vault struct {
	// contains filtered or unexported fields
}

Vault an implementation of VaultService that stores the master key and vault configuration

func (*Vault) Backup 

func (v *Vault) Backup(destinationDir, passphrase string) error

Backup creates a complete encrypted backup of the vault to a specified directory.

This method performs a comprehensive backup operation that captures all vault state including master keys, encrypted data, configuration, and metadata. The backup is encrypted using a user-provided passphrase and stored in a portable format that can be restored to any compatible vault instance.

BACKUP SCOPE AND CONTENTS: The backup includes all critical vault components: - All master encryption keys (current and historical) - Vault configuration and settings - Key rotation history and metadata - Audit log configuration (not log data itself) - Internal vault state and counters - Key derivation parameters and salt values - Vault metadata and version information

SECURITY ARCHITECTURE: - Uses passphrase-based encryption independent of vault keys - Backup passphrase can be different from vault passphrase - Strong key derivation (PBKDF2/Argon2) for backup encryption - Authenticated encryption with integrity protection - Cryptographic checksum validation for backup integrity - No dependency on vault's internal encryption keys - Secure memory handling during backup creation

ENCRYPTION DETAILS: - Encryption Method: Passphrase-only (independent of vault keys) - Algorithm: ChaCha20-Poly1305 with derived key - Key Derivation: High-iteration PBKDF2 or Argon2 (configurable) - Salt: Randomly generated for each backup - Authentication: Poly1305 MAC for integrity verification - Format: Self-contained encrypted container

BACKUP CONTAINER FORMAT: The backup is stored as a JSON container with the following structure: 

{
  "backup_id": "unique-backup-identifier",
  "backup_timestamp": "2024-01-01T00:00:00Z",
  "vault_version": "1.0",
  "backup_version": "1.0",
  "encryption_method": "passphrase-only",
  "encrypted_data": "base64-encoded-encrypted-backup-data",
  "checksum": "sha256-checksum-of-encrypted-data"
}

PERFORMANCE CHARACTERISTICS: - Time Complexity: O(k + n) where k=number of keys, n=data size - Space Complexity: O(n) where n=total vault data size - Memory Usage: ~3x vault data size during backup creation - I/O Operations: Sequential write to destination directory - CPU Usage: High during encryption (key derivation and data encryption) - Disk Usage: Backup size roughly equals serialized vault data

PORTABILITY GUARANTEES: - Backup is completely self-contained - Can be restored to any compatible vault instance - No dependency on original vault's internal keys - Cross-platform compatibility (JSON + base64 encoding) - Version compatibility tracked in backup metadata - Independent of storage backend implementation

DISASTER RECOVERY FEATURES: - Complete vault state reconstruction capability - All historical keys preserved for old data decryption - Configuration and settings fully restored - Backup integrity verification before restoration - Multiple backup generations supported - Offline storage compatibility

Parameters:

  • destinationDir: Target directory path for backup storage. Must be writable and have sufficient space. Directory will be created if it doesn't exist. Path must be absolute or relative to current working directory.

  • passphrase: Encryption passphrase for backup protection. Must be non-empty and sufficiently strong. This passphrase is independent of the vault's master passphrase and can be different. Passphrase strength directly impacts backup security. Minimum recommended length: 12 characters with mixed character types.

Returns:

  • error: nil on successful backup creation, detailed error on failure

Possible Errors:

  • "vault is closed": Vault instance is not operational
  • "destination directory cannot be empty": destinationDir parameter is empty
  • "passphrase cannot be empty": passphrase parameter is empty
  • "failed to collect backup data": Error gathering vault state
  • "failed to serialize backup data": JSON marshaling error
  • "failed to encrypt with passphrase": Backup encryption failed
  • "failed to create destination directory": Directory creation error
  • "insufficient disk space": Not enough space for backup
  • "permission denied": Write permissions insufficient
  • Various I/O errors related to file system operations

Thread Safety: 

This method is thread-safe for concurrent operations. It acquires a read lock
to ensure consistent vault state during backup, allowing normal vault operations
to continue while backup is in progress. However, avoid concurrent backups
to the same destination directory.

Audit Logging: 

All backup operations are comprehensively logged:
- Backup initiation with destination and unique backup ID
- Backup completion status and timing information
- Error details for failed backup attempts
- Backup file size and checksum information
- Security events (passphrase validation, encryption operations)

Memory Safety:

  • Vault keys are accessed through memguard protected memory
  • Sensitive backup data is cleared from memory after encryption
  • Passphrase is handled securely during key derivation
  • No sensitive data persists in standard Go memory
  • Temporary buffers are securely cleared

Usage Examples: 

// Basic backup operation
err := vault.Backup("/backup/location", "strong-backup-passphrase")
if err != nil {
    log.Printf("Backup failed: %v", err)
    return
}
log.Println("Backup completed successfully")

// Scheduled backup with error handling
backupDir := path.Join("/backups", time.Now().Format("2006-01-02"))
backupPassphrase := getSecureBackupPassphrase() // From secure source

err := vault.Backup(backupDir, backupPassphrase)
if err != nil {
    // Log error and send alert
    log.Printf("Scheduled backup failed: %v", err)
    alerting.SendBackupFailureAlert(err)
    return
}

log.Printf("Backup saved to: %s", backupDir)
metrics.IncrementBackupSuccess()

// Enterprise backup with validation
func performEnterpriseBackup(vault *Vault) error {
    backupPath := generateTimestampedBackupPath()
    passphrase := generateSecureBackupPassphrase()

    // Create backup
    err := vault.Backup(backupPath, passphrase)
    if err != nil {
        return fmt.Errorf("backup creation failed: %w", err)
    }

    // Verify backup integrity
    if err := validateBackupIntegrity(backupPath); err != nil {
        return fmt.Errorf("backup validation failed: %w", err)
    }

    // Store passphrase securely (separate from backup)
    if err := storeBackupPassphrase(backupPath, passphrase); err != nil {
        return fmt.Errorf("passphrase storage failed: %w", err)
    }

    return nil
}

Security Best Practices:

  • Use strong, unique passphrases for each backup
  • Store backup passphrases separately from backup files
  • Verify backup integrity after creation
  • Store backups in secure, access-controlled locations
  • Implement backup retention policies
  • Test backup restoration procedures regularly
  • Monitor backup operations through audit logs
  • Use different passphrases for different backup generations
  • Consider backup encryption at rest in storage systems

Operational Best Practices:

  • Schedule regular automated backups
  • Implement backup rotation and cleanup policies
  • Monitor backup file sizes for unexpected changes
  • Validate backup integrity as part of backup process
  • Test restoration procedures in non-production environments
  • Document backup and recovery procedures
  • Implement monitoring and alerting for backup failures
  • Plan for disaster recovery scenarios

Performance Optimization:

  • Schedule backups during low-usage periods
  • Use high-performance storage for backup destinations
  • Monitor memory usage during backup operations
  • Consider backup compression for large vaults
  • Implement incremental backup strategies for very large datasets
  • Use SSD storage for backup encryption operations

Integration Considerations:

  • Backup files are portable across different vault instances
  • Consider integration with enterprise backup systems
  • Plan for network storage and cloud backup scenarios
  • Implement backup verification as part of CI/CD pipelines
  • Consider automated disaster recovery triggers
  • Integrate with monitoring and alerting systems
  • Plan for compliance and regulatory backup requirements

Disaster Recovery Planning:

  • Document backup restoration procedures
  • Test restoration in isolated environments
  • Plan for partial restoration scenarios
  • Consider geographic distribution of backups
  • Implement emergency access procedures for backup passphrases
  • Plan for backup corruption scenarios
  • Document recovery time objectives (RTO) and point objectives (RPO)

Compliance and Governance:

  • Backup creation is fully audited and logged
  • Backup integrity can be cryptographically verified
  • Backup contents are encrypted at rest
  • Access to backups can be controlled and monitored
  • Backup retention policies can be implemented
  • Backup procedures support compliance requirements

func (*Vault) Close 

func (v *Vault) Close() error

Close performs a secure shutdown of the vault with guaranteed data persistence and memory cleanup.

This function implements a comprehensive shutdown sequence that ensures data integrity, security, and proper resource cleanup. It coordinates the orderly termination of all vault operations while maintaining security guarantees and preventing data loss.

SHUTDOWN SEQUENCE: 1. Acquire exclusive lock to prevent concurrent operations 2. Persist all in-memory secrets to durable storage 3. Set closed flag to reject new operations 4. Log shutdown event for audit compliance 5. Close audit logging subsystem 6. Securely destroy all memguard enclaves containing sensitive data 7. Clear all references to prevent accidental access 8. Report any errors that occurred during shutdown

DATA PERSISTENCE GUARANTEE: Before any cleanup occurs, the function ensures all in-memory secrets are persisted to the backing store. This prevents data loss even if the application terminates unexpectedly after calling Close(). If persistence fails, the error is captured but cleanup continues to prevent memory leaks.

SECURE MEMORY CLEANUP: All sensitive data stored in memguard enclaves is securely wiped: • secretsContainer: Encrypted secrets metadata • keyEnclaves: All encryption/decryption keys • derivationKeyEnclave: Master key derivation material • derivationSaltEnclave: Cryptographic salt values

The cleanup leverages memguard's secure deallocation which: - Overwrites memory with cryptographically secure random data - Performs multiple overwrite passes where supported - Uses platform-specific secure memory clearing functions - Protects against cold boot attacks and memory forensics

AUDIT COMPLIANCE: A shutdown event is logged before closing the audit subsystem, providing a complete audit trail that includes vault termination. This supports: • Compliance with security logging requirements • Operational monitoring and alerting • Forensic analysis of vault lifecycle events • Detection of unexpected or unauthorized shutdowns

ERROR HANDLING STRATEGY: The function uses a "best effort" approach where errors during one cleanup step don't prevent other cleanup steps from executing. All errors are collected and returned as a combined error, allowing calling code to: • Log all issues that occurred during shutdown • Take corrective action if needed • Implement retry logic for critical failures

THREAD SAFETY: Close() acquires an exclusive lock at the beginning and holds it throughout the entire shutdown sequence. This ensures: • No concurrent operations can interfere with shutdown • All in-flight operations complete before cleanup begins • Memory cleanup is atomic and cannot be interrupted • The closed flag is set atomically

POST-CLOSE BEHAVIOR: After Close() completes, the vault instance becomes permanently unusable. The closed flag prevents any further operations, and all sensitive data has been securely destroyed. Attempting to use the vault after closing will result in errors from operation methods that check the closed flag.

RESOURCE MANAGEMENT: This function is designed to be called from defer statements, finalizers, or explicit cleanup code. It's safe to call multiple times (subsequent calls will be no-ops due to the closed flag and nil checks).

SECURITY CONSIDERATIONS: • Memory cleanup occurs even if persistence fails • Audit logging happens before audit system shutdown • Errors don't prevent security-critical cleanup steps • All sensitive data references are explicitly cleared • The function cannot be bypassed once the lock is acquired

Returns:

  • error: Combined error containing all issues encountered during shutdown, or nil if shutdown completed successfully. Errors don't indicate security failures, as cleanup always proceeds regardless of errors.

Example Usage: 

// Explicit cleanup
if err := vault.Close(); err != nil {
    log.Errorf("Vault shutdown encountered issues: %v", err)
}

// Defer pattern for guaranteed cleanup
vault, err := NewVault(config)
if err != nil {
    return err
}
defer func() {
    if closeErr := vault.Close(); closeErr != nil {
        log.Errorf("Vault cleanup failed: %v", closeErr)
    }
}()

// Graceful application shutdown
func (app *Application) Shutdown(ctx context.Context) error {
    if app.vault != nil {
        return app.vault.Close()
    }
    return nil
}

func (*Vault) Decrypt 

func (v *Vault) Decrypt(base64CiphertextWithKeyID string) ([]byte, error)

Decrypt decrypts previously encrypted data using the appropriate master key.

This method provides secure authenticated decryption with automatic key selection based on the embedded key ID. It supports both current and historical keys to enable seamless key rotation without breaking existing encrypted data.

SECURITY FEATURES: - Uses ChaCha20-Poly1305 authenticated encryption (AEAD) - Automatic authentication tag verification prevents tampering - Supports multiple key versions for key rotation scenarios - Protected memory access using memguard enclaves - Comprehensive audit logging for security monitoring - Thread-safe with read lock protection - Strict format validation prevents malformed data processing

DECRYPTION ALGORITHM: - Cipher: ChaCha20-Poly1305 (RFC 8439) - Key Size: 256 bits (32 bytes) - Nonce Size: 96 bits (12 bytes) - extracted from encrypted data - Authentication: Poly1305 MAC verification (128-bit authentication tag) - Automatic key selection based on embedded key ID

INPUT FORMAT: The method requires base64-encoded binary data structured as: 

[2 bytes: Key ID Length (big-endian)]
[N bytes: Key ID (UTF-8)]
[12 bytes: Nonce]
[M bytes: Ciphertext + Authentication Tag]

This format ensures proper key identification and prevents ambiguity during decryption operations.

PERFORMANCE CHARACTERISTICS: - Time Complexity: O(n) where n is ciphertext length - Space Complexity: O(n) for output buffer - Memory Usage: ~2x ciphertext size during decryption - CPU Usage: Optimized ChaCha20 implementation with hardware acceleration - I/O Operations: Key retrieval from secure storage

SECURITY GUARANTEES: - Confidentiality: Only holders of the correct key can decrypt - Authenticity: Authentication tag verification prevents forged data - Integrity: Any tampering with ciphertext is detected and rejected - Key Agility: Automatic selection of correct historical keys - Non-repudiation: Audit trail of all decryption attempts - Format Validation: Strict parsing prevents malformed data attacks

KEY ROTATION SUPPORT: - Automatically detects which key was used for encryption - Maintains access to historical keys for old ciphertexts - Seamless operation during and after key rotation - No need to re-encrypt existing data immediately - Gradual migration support for large datasets

Parameters:

  • base64CiphertextWithKeyID: Base64-encoded encrypted data string. Must be output from the Encrypt() method. Cannot be empty. Must be valid base64 encoding with proper internal format.

Returns:

  • []byte: The original plaintext data. Caller is responsible for handling this sensitive data appropriately (zeroing if needed).
  • error: nil on success, detailed error on failure

Possible Errors:

  • "empty encrypted string": Input parameter is empty
  • "invalid base64 encoding": Input is not valid base64
  • "encrypted data too short": Input data is shorter than minimum required
  • "invalid data format": Data doesn't follow expected format structure
  • "key [ID] not available": Required decryption key not found
  • "failed to access master key": Cannot open the key enclave
  • "failed to create cipher": ChaCha20-Poly1305 cipher initialization failed
  • "failed to decrypt": Authentication failed or data is corrupted
  • Various internal errors related to memory or system resources

Thread Safety: 

This method is thread-safe for concurrent reads. It acquires a read lock
to ensure consistent key state during decryption, allowing multiple
simultaneous decryptions.

Audit Logging: 

All decryption attempts are logged with the following information:
- Operation success/failure status
- Input data size (base64 string length)
- Output size and key ID used (on success)
- Error details (on failure)
- Timestamp and contextual information

Memory Safety:

  • Master keys are accessed through memguard protected memory
  • Key buffers are automatically destroyed after use
  • No sensitive key material remains in standard Go memory
  • Plaintext output is returned in standard memory (caller's responsibility)

Usage Examples: 

// Basic decryption
encrypted := "base64-encoded-encrypted-data"
plaintext, err := vault.Decrypt(encrypted)
if err != nil {
    log.Printf("Decryption failed: %v", err)
    return
}
defer func() {
    // Clear sensitive data when done
    for i := range plaintext {
        plaintext[i] = 0
    }
}()
fmt.Printf("Plaintext: %s\n", plaintext)

// Decrypt JSON data
encryptedJSON := getEncryptedDataFromDB()
jsonBytes, err := vault.Decrypt(encryptedJSON)
if err != nil {
    log.Printf("Failed to decrypt JSON: %v", err)
    return
}

var data map[string]interface{}
err = json.Unmarshal(jsonBytes, &data)
if err != nil {
    log.Printf("Failed to parse JSON: %v", err)
    return
}

// Batch decryption with error handling
encryptedItems := getEncryptedDataBatch()
for i, encrypted := range encryptedItems {
    plaintext, err := vault.Decrypt(encrypted)
    if err != nil {
        log.Printf("Failed to decrypt item %d: %v", i, err)
        continue
    }

    // Process decrypted data
    processSensitiveData(plaintext)

    // Clear sensitive data
    for j := range plaintext {
        plaintext[j] = 0
    }
}

Error Handling Best Practices:

  • Always check for errors before using decrypted data
  • Log authentication failures for security monitoring
  • Implement retry logic for transient key access failures
  • Handle key rotation scenarios gracefully
  • Monitor for systematic decryption failures
  • Validate input format before processing

Security Best Practices:

  • Clear sensitive plaintext data after use when possible
  • Validate decrypted data format before processing
  • Monitor audit logs for unusual decryption patterns
  • Implement rate limiting to prevent brute force attacks
  • Use decrypted data immediately or re-protect it
  • Never log or expose plaintext data in error messages
  • Validate that input data came from trusted sources

Performance Optimization:

  • Key lookups are optimized with internal caching
  • Memory allocations are minimized during decryption
  • Consider batching for high-throughput scenarios
  • Monitor memory usage in systems processing large datasets
  • Pre-validate input format to fail fast on invalid data

Integration Considerations:

  • Decrypted data is returned as []byte for maximum flexibility
  • Handle character encoding conversions as needed
  • Consider streaming decryption for very large datasets
  • Coordinate key retention policies with data lifecycle
  • Plan for emergency key recovery scenarios
  • Ensure all encrypted data follows the expected format

Cryptographic Security:

  • Authentication tag verification is automatic and mandatory
  • Timing attacks are mitigated by constant-time operations
  • Side-channel attacks are prevented by secure implementations
  • The underlying primitives are cryptographically proven secure
  • Format validation prevents malformed data attacks

Failure Recovery:

  • Transient failures (key access, memory) can be retried safely
  • Authentication failures indicate tampering or corruption
  • Format errors indicate invalid or corrupted input data
  • Missing key errors may require key recovery procedures
  • Systematic failures may indicate system compromise
  • Audit logs provide forensic information for investigation

func (*Vault) DeleteSecret 

func (v *Vault) DeleteSecret(secretID string) error

DeleteSecret permanently removes a secret from the vault by its ID.

This function performs a secure deletion operation with the following guarantees: 1. Validates vault state and secret ID format 2. Verifies the secret exists before attempting deletion 3. Creates a complete backup for potential rollback scenarios 4. Atomically removes the secret from the container 5. Persists changes to storage with automatic rollback on failure 6. Comprehensive audit logging of the deletion operation

IMPORTANT BEHAVIORS: - Deletion is permanent and cannot be undone once successfully completed - The operation is atomic - either the secret is fully deleted or remains unchanged - Automatic rollback occurs if storage persistence fails - Both the encrypted data and all associated metadata are removed - Container timestamp is updated to reflect the modification

SECURITY CONSIDERATIONS: - Deleted secrets are removed from memory and storage immediately - No recovery mechanism exists - ensure deletion is intentional - Audit trail preserves record of deletion event and secret metadata - Rollback capability prevents partial deletions that could cause data corruption

FAILURE HANDLING: - Storage persistence failures trigger automatic rollback to previous state - Critical errors (both deletion and rollback failures) are specially logged - Detailed error messages distinguish between different failure scenarios

Parameters:

  • secretID: Unique identifier of the secret to delete

Returns:

  • error: Any error encountered during validation, deletion, or persistence Returns nil on successful deletion

Thread Safety: This function is thread-safe through internal mutex locking

Audit Logging: Comprehensive logging includes:

  • Deletion attempts (successful and failed)
  • Secret metadata at time of deletion
  • Critical system errors requiring attention

Storage: Changes are immediately persisted with rollback protection

Example Usage: 

err := vault.DeleteSecret("old-api-key")
if err != nil {
    if strings.Contains(err.Error(), "does not exist") {
        log.Printf("Secret was already deleted")
    } else {
        return fmt.Errorf("failed to delete secret: %w", err)
    }
}
log.Printf("Secret successfully deleted")

func (*Vault) DeleteTenant 

func (v *Vault) DeleteTenant(tenantID string) error

DeleteTenant securely removes all resources associated with a specified tenant.

This operation is irreversible, ensuring that all data related to the tenant, including secrets, keys, and metadata, are securely deleted from storage.

Parameters:

  • tenantID: A unique identifier for the tenant whose resources are to be deleted. This ID is used to locate and remove all associated data.

Returns:

  • error: Returns nil if the deletion is successful, or an error if the deletion fails. The error provides detailed information about what went wrong, which can be useful for auditing and troubleshooting.

Security Notes:

  • This operation ensures that all data associated with the tenant ID is securely wiped, eliminating risks of data recovery.
  • Actions taken are logged for audit purposes, capturing both successful deletions and any errors encountered during the process.

Example Usage: 

err := vault.DeleteTenant("tenant-1234")
if err != nil {
    log.Printf("Failed to delete tenant: %v", err)
} else {
    log.Println("Tenant deleted successfully.")
}

func (*Vault) DestroyKey 

func (v *Vault) DestroyKey(keyID string) error

DestroyKey permanently removes an inactive encryption key from the vault.

This method provides secure and irreversible destruction of cryptographic keys that are no longer needed for vault operations. It implements comprehensive safety checks to prevent accidental destruction of active keys or keys still protecting encrypted data. The operation is permanent and cannot be undone, making it critical for key lifecycle management, compliance requirements, and security policy enforcement. DestroyKey supports secure key retirement while maintaining data accessibility and operational integrity through rigorous validation and safety mechanisms.

FUNCTIONALITY OVERVIEW AND PURPOSE: DestroyKey serves multiple critical functions in vault key management: - Permanent removal of inactive keys from memory and persistent storage - Security policy enforcement through comprehensive pre-destruction validation - Compliance support for key retention and destruction requirements - Memory cleanup and resource optimization for long-running vault instances - Audit trail generation for regulatory compliance and security monitoring - Risk mitigation through controlled key lifecycle management - Support for key rotation policies and automated key management workflows - Prevention of key sprawl and unauthorized key accumulation

KEY DESTRUCTION SAFETY FRAMEWORK: The method implements multiple layers of safety validation to prevent data loss:

Vault State Validation: - Closed State Check: Prevents operations on closed vault instances - Initialization Check: Confirms vault is properly initialized and operational - Consistency Check: Validates internal state consistency before destruction - Lock Acquisition: Ensures exclusive access during critical destruction operations

Key Existence and Status Validation: - Existence Verification: Confirms target key exists in vault key registry - Status Validation: Ensures key is in appropriate state for destruction - Active Key Protection: Prevents destruction of currently active encryption key - Metadata Consistency: Validates key metadata accuracy and current status

Data Protection Validation: - Usage Analysis: Checks if any vault secrets still depend on target key - Dependency Validation: Ensures no encrypted data would become inaccessible - Cross-Reference Analysis: Validates key usage across all vault data structures - Impact Assessment: Confirms destruction will not compromise data accessibility

ACTIVE KEY PROTECTION MECHANISM: Critical safety feature preventing destruction of operational keys:

Current Active Key Protection: - Primary Check: Direct comparison with v.currentKeyID for active key identification - Status Validation: Confirms key is not marked as active in metadata - Operational Protection: Prevents disruption of ongoing encryption operations - Rotation Requirement: Enforces key rotation before destruction of active keys

Protection Benefits: - Prevents operational disruption and service unavailability - Maintains encryption capability for new secret storage operations - Enforces proper key lifecycle management and rotation procedures - Provides clear error messaging for operational guidance and troubleshooting

Operational Guidance: - Error messages provide clear instruction to rotate before destruction - Supports automated key management workflows with proper sequencing - Enables integration with key rotation policies and procedures - Facilitates documentation of key lifecycle management requirements

DATA PROTECTION AND USAGE VALIDATION: Comprehensive analysis to prevent data loss through premature key destruction:

Usage Detection Logic: - Secret Enumeration: Analyzes all stored secrets for key dependency - Encryption Metadata: Examines encryption metadata for key references - Cross-Reference Validation: Validates key usage across vault data structures - Dependency Mapping: Creates comprehensive key usage map for validation

Protection Mechanisms: - Prevents destruction of keys protecting accessible encrypted data - Maintains data integrity through comprehensive dependency analysis - Provides detailed error reporting for data protection violations - Supports data migration planning through usage analysis and reporting

Data Migration Support: - Identifies specific secrets requiring key migration before destruction - Supports automated data migration workflows and validation procedures - Enables batch processing for large-scale key lifecycle management - Facilitates compliance with data retention and accessibility requirements

func (*Vault) Encrypt 

func (v *Vault) Encrypt(plaintext []byte) (ciphertextWithKeyID string, err error)

Encrypt encrypts plaintext data using the vault's current master key with ChaCha20-Poly1305 AEAD.

This method provides secure authenticated encryption with additional data integrity guarantees. The encrypted output includes the key ID to support key rotation and ensure proper decryption even after the master key has been rotated.

SECURITY FEATURES: - Uses ChaCha20-Poly1305 authenticated encryption (AEAD) - Generates cryptographically secure random nonce for each encryption - Includes authentication tag to detect tampering - Embeds key ID to support key rotation scenarios - Protected memory access using memguard enclaves - Comprehensive audit logging for security monitoring - Thread-safe with read lock protection

ENCRYPTION ALGORITHM: - Cipher: ChaCha20-Poly1305 (RFC 8439) - Key Size: 256 bits (32 bytes) - Nonce Size: 96 bits (12 bytes) - randomly generated per encryption - Authentication: Poly1305 MAC provides 128-bit authentication tag - No additional authenticated data (AAD) is used

OUTPUT FORMAT: The encrypted output follows this binary format before base64 encoding: 

[2 bytes: Key ID Length (big-endian)]
[N bytes: Key ID (UTF-8)]
[12 bytes: Nonce (random)]
[M bytes: Ciphertext + Authentication Tag]

The final output is base64-encoded for safe text transmission and storage.

PERFORMANCE CHARACTERISTICS: - Time Complexity: O(n) where n is plaintext length - Space Complexity: O(n) for temporary buffers - Memory Usage: ~3x plaintext size during encryption (temporary copies) - CPU Usage: Optimized ChaCha20 implementation with hardware acceleration when available

SECURITY GUARANTEES: - Confidentiality: Plaintext is hidden from attackers without the key - Authenticity: Authentication tag prevents undetected modifications - Freshness: Unique nonce prevents replay attacks and ensures semantic security - Key Agility: Embedded key ID supports seamless key rotation - Forward Security: Old ciphertexts remain secure even after key rotation

Parameters:

  • plaintext: The data to be encrypted. Must not be empty. Maximum size is 10MB to prevent DoS attacks and memory exhaustion. The data is not modified during encryption.

Returns:

  • ciphertextWithKeyID: Base64-encoded encrypted data with embedded key ID. This string can be safely transmitted over text protocols or stored in databases.
  • err: nil on success, detailed error on failure

Possible Errors:

  • "empty plaintext": Plaintext parameter is empty or nil
  • "plaintext too large": Plaintext exceeds 10MB size limit
  • "master key not available": Current encryption key cannot be retrieved
  • "failed to access master key": Cannot open the master key enclave
  • "failed to create cipher": ChaCha20-Poly1305 cipher initialization failed
  • "failed to generate nonce": Cryptographic random number generation failed
  • "key ID too long": Key identifier exceeds maximum length (65535 bytes)
  • Various internal errors related to memory or system resources

Thread Safety: 

This method is thread-safe for concurrent reads. It acquires a read lock
to ensure the key state doesn't change during encryption, allowing multiple
simultaneous encryptions with the same key.

Audit Logging: 

All encryption attempts are logged with the following information:
- Operation success/failure status
- Input data size (not the actual data for security)
- Output size and key ID (on success)
- Error details (on failure)
- Timestamp and contextual information

Memory Safety:

  • Master key is accessed through memguard protected memory
  • Key buffer is automatically destroyed after use
  • No sensitive data remains in standard Go memory
  • Temporary nonce and ciphertext are cleared by Go's GC

Usage Examples: 

// Basic encryption
plaintext := []byte("sensitive data")
encrypted, err := vault.Encrypt(plaintext)
if err != nil {
    log.Printf("Encryption failed: %v", err)
    return
}
fmt.Printf("Encrypted: %s\n", encrypted)

// Encrypt JSON data
jsonData := `{"secret": "value", "password": "123456"}`
encrypted, err := vault.Encrypt([]byte(jsonData))
if err != nil {
    log.Printf("Failed to encrypt JSON: %v", err)
    return
}

// Store encrypted data
err = database.Store("user_secrets", encrypted)
if err != nil {
    log.Printf("Failed to store encrypted data: %v", err)
}

Key Rotation Compatibility: 

The encrypted output includes the key ID that was used for encryption.
This ensures that:
- Old ciphertexts can still be decrypted after key rotation
- Multiple key versions can coexist in the same system
- Gradual migration to new keys is possible
- Emergency key rotation doesn't break existing data

Security Best Practices:

  • Always check the returned error before using encrypted data
  • Store encrypted data securely (proper database permissions, etc.)
  • Monitor audit logs for unusual encryption patterns
  • Implement rate limiting to prevent abuse
  • Consider data classification and apply appropriate controls
  • Regularly rotate encryption keys according to your security policy

Performance Optimization:

  • For high-throughput scenarios, consider batching small encryptions
  • Monitor memory usage in systems processing large datasets
  • The 10MB size limit can be adjusted based on your security requirements
  • Consider using streaming encryption for very large datasets

Integration Considerations:

  • The base64 output is safe for JSON, XML, and database storage
  • Output length is approximately 1.33x the input length plus overhead
  • Key rotation requires coordination with decryption systems
  • Audit logs should be monitored and retained per compliance requirements

Cryptographic Details:

  • ChaCha20 provides the confidentiality protection
  • Poly1305 provides authentication and integrity protection
  • The combination is proven secure and resistant to timing attacks
  • Nonce uniqueness is critical - never reuse nonces with the same key
  • The implementation follows RFC 8439 specifications

func (*Vault) GetActiveKeyMetadata 

func (v *Vault) GetActiveKeyMetadata() (KeyMetadata, error)

GetActiveKeyMetadata retrieves the metadata for the currently active encryption key.

This method provides detailed information about the key currently being used for new encryption operations within the vault. It serves as the primary interface for determining active key status, monitoring key lifecycle, and supporting operational decisions that depend on current key state. The method ensures real-time accuracy by dynamically updating status fields to reflect the key's current operational role regardless of stored metadata state.

FUNCTIONALITY OVERVIEW: GetActiveKeyMetadata performs several critical operations: - Identifies the currently active key used for new encryption operations - Retrieves comprehensive metadata for operational and audit purposes - Validates vault initialization and operational readiness - Ensures metadata consistency with current vault operational state - Provides real-time key status information for monitoring and automation - Supports key lifecycle management and policy enforcement decisions - Enables operational visibility into current cryptographic configuration - Facilitates security monitoring and audit trail generation

ACTIVE KEY DETERMINATION: The method uses a multi-layered approach to identify the active key: - Primary Source: v.currentKeyID field contains the authoritative active key identifier - Validation: Cross-references with existing key metadata registry - Consistency: Ensures active key exists in operational key enclaves - Verification: Confirms key is available for cryptographic operations - Status Update: Dynamically updates metadata to reflect current active status

Active Key Characteristics: - Used for all new encryption operations performed by the vault - Represents the current generation in the key rotation lifecycle - Maintained as the primary key until next rotation operation - Available for both encryption and decryption operations - Subject to key rotation policies and lifecycle management rules

VAULT INITIALIZATION VALIDATION: The method implements comprehensive validation to ensure vault readiness:

Pre-Lock Validation: - Derivation Key Enclave: Validates master key derivation system availability - Key Metadata Registry: Confirms key metadata storage system initialization - Prevents operations on partially initialized or corrupted vault state - Provides early failure detection before acquiring locks

Post-Lock Validation: - Key Enclaves: Validates operational key storage system availability - Current Key ID: Confirms active key identification and assignment - Metadata Consistency: Ensures active key metadata exists and is accessible - Operational Readiness: Verifies vault can perform cryptographic operations

Initialization State Matrix: - Fully Initialized: All validation checks pass, method proceeds normally - Partially Initialized: Some components missing, returns initialization error - Uninitialized: No initialization detected, returns clear error message - Corrupted State: Inconsistent state detected, returns appropriate error

REAL-TIME STATUS SYNCHRONIZATION: The method ensures returned metadata accurately reflects current operational state:

Status Field Updates: - Active: Set to true to indicate this key is currently active - Status: Set to KeyStatusActive to reflect operational status - DeactivatedAt: Set to nil as active keys cannot have deactivation timestamps - Other Fields: Preserved exactly as stored in metadata registry

Consistency Guarantees: - Metadata reflects current operational reality, not historical state - Active status fields are synchronized with vault's current configuration - Updates applied dynamically without modifying stored metadata - Ensures operational decisions are based on current, accurate information

Temporal Accuracy: - Metadata reflects key status at the exact moment of method execution - No stale or cached information that might mislead operational decisions - Immediate reflection of key rotation or status changes - Suitable for real-time monitoring and automated decision-making systems

SECURITY AND ACCESS CONTROL: The method implements comprehensive security measures:

Data Protection: - Returns only metadata, never actual cryptographic key material - Information is safe for audit trails and compliance reporting - No sensitive operational details that could compromise security - Suitable for external system integration and monitoring

Access Control Features: - Read-only operation with no vault state modification - Thread-safe concurrent access through appropriate locking - Audit-safe information suitable for logging and external integration - Rate limiting compatibility for high-frequency monitoring access

Security Boundary Enforcement: - Clear separation between metadata and actual cryptographic material - No information leakage that could assist in cryptographic attacks - Appropriate for security monitoring and incident response systems - Compliant with security frameworks and regulatory requirements

PERFORMANCE CHARACTERISTICS: The method is optimized for frequent access and operational efficiency:

Computational Complexity: - O(1) active key identification through direct currentKeyID lookup - O(1) metadata retrieval through hash map access - Minimal computational overhead for status field updates - Efficient validation with early failure detection

Memory Efficiency: - Single metadata structure allocation for return value - No large data structure copying or deep cloning - Minimal memory footprint suitable for high-frequency access - Efficient for integration with monitoring and automation systems

Concurrency Performance: - Read lock usage enables concurrent access with other read operations - Compatible with high-frequency monitoring and status checking - Minimal lock contention with other operational methods - Suitable for real-time operational dashboards and automation

OPERATIONAL MONITORING INTEGRATION: GetActiveKeyMetadata provides essential data for operational monitoring:

Key Health Monitoring: - Active key age analysis for rotation policy enforcement - Key lifecycle position tracking for proactive management - Status consistency monitoring for operational health assessment - Performance impact analysis for key management operations

Monitoring Use Cases: - Automated key rotation scheduling based on key age and policy - Operational health dashboards showing current key status - Security monitoring for unusual key lifecycle patterns - Compliance monitoring for key management policy adherence - Performance monitoring for key-related operational efficiency

Integration Points: - SIEM system integration for security event correlation - Monitoring system integration for operational visibility - Alerting system integration for proactive issue detection - Dashboard integration for real-time operational status display - Automation system integration for policy enforcement

AUDIT AND COMPLIANCE SUPPORT: The method provides comprehensive audit and compliance capabilities:

Audit Trail Enhancement: - Current key identification for audit trail correlation - Key lifecycle position documentation for compliance reporting - Status timestamp information for audit event sequencing - Operational readiness verification for compliance validation

Regulatory Compliance: - SOX: Current key documentation for financial data protection audit - PCI DSS: Active key identification for payment card data security - HIPAA: Current encryption key documentation for healthcare data protection - SOC 2: Security control evidence for service organization compliance - ISO 27001: Information security management system documentation - GDPR: Data protection key management for privacy compliance

Compliance Reporting: - Automated compliance report generation with current key information - Audit evidence collection for regulatory examinations - Policy compliance verification for governance frameworks - Exception reporting for policy violations or operational issues

DISASTER RECOVERY INTEGRATION: GetActiveKeyMetadata plays a critical role in disaster recovery:

Recovery Validation: - Post-recovery active key verification ensuring operational continuity - Metadata consistency validation after backup restoration - Operational readiness confirmation for service resumption - Key availability verification for cryptographic operations

Recovery Scenarios: - Primary Site Failure: Validates active key availability at recovery site - Data Corruption: Confirms active key metadata integrity after restoration - Partial Recovery: Validates specific key availability during incremental recovery - Testing: Confirms recovery procedures maintain active key operational status

Business Continuity: - Service resumption validation through active key verification - Operational continuity confirmation for critical business processes - Recovery time objective (RTO) support through rapid key status validation - Recovery point objective (RPO) validation through key metadata consistency

func (*Vault) GetAudit 

func (v *Vault) GetAudit() audit.Logger

GetAudit returns the audit logger instance associated with this vault.

This function provides access to the vault's audit logging system, allowing external components to perform custom audit logging using the same logger configuration and destination as the vault's internal operations.

USAGE SCENARIOS: - Custom audit logging for application-specific events - Integration with external security monitoring systems - Implementing additional compliance logging requirements - Debugging and troubleshooting vault operations

IMPORTANT NOTES: - Returns nil if auditing was not enabled during vault initialization - The returned logger shares the same configuration as internal vault auditing - External logging through this interface maintains consistency with vault logs - Caller is responsible for proper error handling of audit operations

SECURITY CONSIDERATIONS: - Audit logs may contain sensitive metadata (not secret data itself) - Ensure proper access controls when exposing audit functionality - Consider the security implications of custom audit events

Returns:

  • audit.Logger: The configured audit logger instance, or nil if auditing is disabled

Thread Safety: The returned logger implementation should be thread-safe

Example Usage: 

auditLogger := vault.GetAudit()
if auditLogger != nil {
    err := auditLogger.Log("custom_event", true, map[string]interface{}{
        "user_id": userID,
        "action":  "secret_export",
    })
    if err != nil {
        log.Printf("Audit logging failed: %v", err)
    }
}

func (*Vault) GetBackupInfo 

func (v *Vault) GetBackupInfo(backupPath string) (*persist.BackupInfo, error)

GetBackupInfo retrieves metadata and integrity information about a backup without decrypting it.

This method provides a safe, non-destructive way to inspect backup files and verify their integrity without requiring the backup passphrase or modifying vault state. It's essential for backup management, disaster recovery planning, and backup validation workflows. The method performs cryptographic integrity verification but does not decrypt the backup contents.

INSPECTION CAPABILITIES: The method extracts and validates several aspects of backup files: - Backup container metadata (ID, timestamps, versions) - Cryptographic integrity verification via checksum validation - Version compatibility assessment between backup and current vault - Backup format validation and structure verification - Encryption method identification and compatibility - Backup creation timestamp and age information - Basic backup file structure and format validation

SECURITY AND SAFETY FEATURES: - No passphrase required - completely safe inspection - No vault state modification or interference - No decryption of sensitive backup contents - Cryptographic integrity validation without content access - Read-only operation with no side effects - Thread-safe concurrent access with other vault operations - No audit logging of sensitive information - Safe for automated monitoring and validation systems

INTEGRITY VERIFICATION PROCESS: The method performs comprehensive backup integrity checks: 1. Backup container format validation 2. Required metadata fields verification 3. Base64 encoding integrity validation 4. Cryptographic checksum calculation and comparison 5. Backup structure and format compliance verification 6. Version compatibility assessment 7. Encryption method validation and identification

BACKUP INFO STRUCTURE: The returned BackupInfo contains the following validated information: - BackupID: Unique identifier for the backup instance - BackupTimestamp: UTC timestamp when backup was created - VaultVersion: Version of vault that created the backup - BackupVersion: Format version of the backup structure - EncryptionMethod: Encryption algorithm and method used - IsValid: Boolean indicating cryptographic integrity status

PERFORMANCE CHARACTERISTICS: - Time Complexity: O(n) where n is encrypted backup size - Space Complexity: O(1) - minimal memory usage - Memory Usage: <100MB regardless of backup size - I/O Operations: Single sequential read of backup container - CPU Usage: Minimal - only checksum calculation - Disk Usage: No temporary files or additional storage - Network Usage: Minimal for remote backup locations - Lock Usage: No vault locks required - completely independent

VERSION COMPATIBILITY ASSESSMENT: - Compares backup version with current vault capabilities - Identifies potential restoration compatibility issues - Provides version information for upgrade/downgrade planning - Supports backup format evolution and migration planning - Enables proactive compatibility validation

BACKUP MANAGEMENT INTEGRATION: - Essential for backup catalog and inventory systems - Supports automated backup validation workflows - Enables backup age and retention policy enforcement - Provides data for backup integrity monitoring - Supports backup selection and recovery planning - Enables backup metadata indexing and search

Parameters:

  • backupPath: Directory path containing the backup to inspect. Must point to a valid backup directory created by the Backup method. Path can be absolute or relative to current working directory. Directory must be readable and contain backup container files. Supports local directories, network paths, and cloud storage URLs.

Returns:

  • *persist.BackupInfo: Detailed backup metadata and integrity information. Contains all discoverable backup properties and validation results. IsValid field indicates cryptographic integrity verification result. nil on any error during backup inspection or validation.

  • error: nil on successful inspection, detailed error on failure. Error provides specific information about inspection failure cause.

Possible Errors:

  • "backup path cannot be empty": backupPath parameter is empty
  • "failed to load backup": Backup container loading or access error
  • "backup container not found": Specified path doesn't contain backup
  • "failed to decode backup data": Base64 decoding error in container
  • "invalid backup container format": Container structure validation error
  • "missing required backup metadata": Essential fields missing from container
  • "unsupported backup format version": Backup format not recognized
  • Various I/O errors related to backup file reading and access
  • Permission errors for backup directory or file access
  • Network errors for remote backup locations

Thread Safety: 

This method is completely thread-safe and can be called concurrently with
all other vault operations. It requires no locks, performs no vault state
modifications, and has no side effects. Multiple threads can safely inspect
the same or different backups simultaneously without coordination.

Audit Logging: 

Backup inspection operations generate minimal audit logs:
- Backup inspection requests with source path
- Backup integrity validation results (success/failure only)
- No sensitive backup metadata or content information
- Error details for failed inspection attempts
- Performance and timing information for monitoring
- No passphrase attempts or decryption activities logged

Memory Safety:

  • No sensitive data loaded into memory during inspection
  • Backup contents remain encrypted and inaccessible
  • Minimal memory footprint regardless of backup size
  • No persistent memory allocations or caching
  • Safe for automated and frequent inspection operations
  • No memguard enclaves required for inspection operations

Usage Examples: 

// Basic backup inspection
info, err := vault.GetBackupInfo("/backups/2024-01-01")
if err != nil {
    log.Printf("Failed to inspect backup: %v", err)
    return
}

fmt.Printf("Backup ID: %s\n", info.BackupID)
fmt.Printf("Created: %v\n", info.BackupTimestamp)
fmt.Printf("Valid: %t\n", info.IsValid)

// Backup validation workflow
func validateBackupIntegrity(backupPath string) error {
    info, err := vault.GetBackupInfo(backupPath)
    if err != nil {
        return fmt.Errorf("backup inspection failed: %w", err)
    }

    if !info.IsValid {
        return fmt.Errorf("backup integrity check failed")
    }

    // Check backup age
    age := time.Since(info.BackupTimestamp)
    if age > 30*24*time.Hour {
        log.Printf("WARNING: Backup is %v old", age)
    }

    // Version compatibility check
    if !isVersionCompatible(info.VaultVersion, currentVaultVersion) {
        return fmt.Errorf("backup version %s incompatible with vault %s",
            info.VaultVersion, currentVaultVersion)
    }

    return nil
}

// Backup catalog management
func catalogBackups(backupDirectory string) ([]*persist.BackupInfo, error) {
    var catalog []*persist.BackupInfo

    backupDirs, err := filepath.Glob(filepath.Join(backupDirectory, "*"))
    if err != nil {
        return nil, fmt.Errorf("failed to scan backup directory: %w", err)
    }

    for _, dir := range backupDirs {
        info, err := vault.GetBackupInfo(dir)
        if err != nil {
            log.Printf("Skipping invalid backup %s: %v", dir, err)
            continue
        }

        catalog = append(catalog, info)
    }

    // Sort by creation time (newest first)
    sort.Slice(catalog, func(i, j int) bool {
        return catalog[i].BackupTimestamp.After(catalog[j].BackupTimestamp)
    })

    return catalog, nil
}

// Disaster recovery backup selection
func selectBestBackupForRecovery(backupPaths []string) (string, error) {
    var candidates []struct {
        path string
        info *persist.BackupInfo
    }

    // Evaluate all available backups
    for _, path := range backupPaths {
        info, err := vault.GetBackupInfo(path)
        if err != nil {
            log.Printf("Cannot use backup %s: %v", path, err)
            continue
        }

        // Only consider valid, compatible backups
        if !info.IsValid {
            log.Printf("Skipping corrupted backup: %s", path)
            continue
        }

        if !isVersionCompatible(info.VaultVersion, currentVaultVersion) {
            log.Printf("Skipping incompatible backup: %s", path)
            continue
        }

        candidates = append(candidates, struct {
            path string
            info *persist.BackupInfo
        }{path, info})
    }

    if len(candidates) == 0 {
        return "", errors.New("no valid backups available for recovery")
    }

    // Select most recent valid backup
    best := candidates[0]
    for _, candidate := range candidates[1:] {
        if candidate.info.BackupTimestamp.After(best.info.BackupTimestamp) {
            best = candidate
        }
    }

    log.Printf("Selected backup %s created %v",
        best.info.BackupID, best.info.BackupTimestamp)
    return best.path, nil
}

// Automated backup monitoring
func monitorBackupHealth(backupPaths []string) error {
    var issues []string

    for _, path := range backupPaths {
        info, err := vault.GetBackupInfo(path)
        if err != nil {
            issues = append(issues, fmt.Sprintf("Backup %s: inspection failed - %v", path, err))
            continue
        }

        if !info.IsValid {
            issues = append(issues, fmt.Sprintf("Backup %s: integrity check failed", path))
            continue
        }

        // Check backup age
        age := time.Since(info.BackupTimestamp)
        if age > 7*24*time.Hour {
            issues = append(issues, fmt.Sprintf("Backup %s: aged %v (consider refresh)", path, age))
        }

        // Check version compatibility
        if !isVersionCompatible(info.VaultVersion, currentVaultVersion) {
            issues = append(issues, fmt.Sprintf("Backup %s: version compatibility issue", path))
        }
    }

    if len(issues) > 0 {
        return fmt.Errorf("backup health issues detected:\n%s", strings.Join(issues, "\n"))
    }

    return nil
}

// Enterprise backup governance
func enterpriseBackupAudit(backupLocations []string) (*BackupAuditReport, error) {
    report := &BackupAuditReport{
        AuditTimestamp: time.Now(),
        BackupsScanned: 0,
        ValidBackups:   0,
        CorruptBackups: 0,
        Issues:        make([]string, 0),
    }

    for _, location := range backupLocations {
        report.BackupsScanned++

        info, err := vault.GetBackupInfo(location)
        if err != nil {
            report.Issues = append(report.Issues,
                fmt.Sprintf("Location %s: %v", location, err))
            continue
        }

        if info.IsValid {
            report.ValidBackups++
        } else {
            report.CorruptBackups++
            report.Issues = append(report.Issues,
                fmt.Sprintf("Backup %s: integrity validation failed", info.BackupID))
        }

        // Compliance checks
        age := time.Since(info.BackupTimestamp)
        if age > 30*24*time.Hour {
            report.Issues = append(report.Issues,
                fmt.Sprintf("Backup %s: exceeds retention policy (%v old)",
                    info.BackupID, age))
        }

        if info.EncryptionMethod != "passphrase-only" {
            report.Issues = append(report.Issues,
                fmt.Sprintf("Backup %s: non-compliant encryption method",
                    info.BackupID))
        }
    }

    return report, nil
}

Security Best Practices:

  • Use backup inspection to validate integrity before restoration attempts
  • Implement automated backup health monitoring using this method
  • Verify backup compatibility before disaster recovery scenarios
  • Include backup inspection in security auditing workflows
  • Monitor backup age and implement retention policies
  • Validate backup authenticity and chain of custody
  • Use inspection results for backup rotation and cleanup decisions

Operational Best Practices:

  • Implement regular automated backup validation using this method
  • Include backup inspection in monitoring and alerting systems
  • Use backup metadata for disaster recovery planning and documentation
  • Implement backup catalog systems using inspection capabilities
  • Plan backup selection algorithms using metadata and integrity information
  • Document backup inspection procedures and validation criteria
  • Integrate backup inspection with change management processes

Integration Considerations:

  • Method can be safely called from monitoring scripts and automation
  • Results should be integrated with backup management systems
  • Inspection data supports compliance reporting and auditing
  • Method supports both manual operations and automated workflows
  • Compatible with backup scheduling and retention management systems
  • Results can drive backup cleanup and rotation policies

Compliance and Governance:

  • Backup inspection supports compliance validation requirements
  • Inspection results provide audit trail for backup integrity
  • Method supports backup authenticity verification workflows
  • Results enable backup retention and disposal policy enforcement
  • Inspection data supports regulatory backup validation requirements

func (*Vault) GetSecret 

func (v *Vault) GetSecret(secretID string) (*SecretResult, error)

GetSecret retrieves and decrypts a secret from the vault by its ID.

This function performs the following operations: 1. Validates the vault state and secret ID format 2. Retrieves and decrypts the secret from storage 3. Updates access tracking metadata (access count and last accessed time) 4. Returns both the decrypted secret data and complete metadata

SECURITY CONSIDERATIONS: - The returned secret data remains in memory until garbage collected - For embedded applications, consider using UseSecret() family functions instead - These safe functions automatically clear secrets from memory after use

Parameters:

  • secretID: Unique identifier for the secret to retrieve

Returns:

  • SecretResult: Contains decrypted data, metadata, and key usage info
  • error: Any error encountered during retrieval or decryption

Thread Safety: This function is thread-safe through internal mutex locking

Audit Logging: All access attempts (successful and failed) are logged if auditing is enabled

Key Rotation Support: The function can decrypt secrets encrypted with older keys and reports whether the current active key was used via SecretResult.UsedActiveKey

Example Usage: 

result, err := vault.GetSecret("my-secret-id")
if err != nil {
    return err
}
// CAUTION: Secret data is now in memory - handle carefully
secretData := result.Data

// RECOMMENDED: Use safe retrieval functions instead for embedded applications:
// vault.UseSecret("my-secret-id", func(data []byte) error {
//     // Work with secret data here - automatically cleared after function returns
//     return processSecret(data)
// })

func (*Vault) GetSecretMetadata 

func (v *Vault) GetSecretMetadata(secretID string) (*SecretMetadata, error)

GetSecretMetadata retrieves only the metadata for a specific secret without accessing encrypted data.

This function provides access to all descriptive and organizational information about a secret while maintaining security by never decrypting or exposing the actual secret payload. It's designed for operations that need secret information but not the sensitive data itself.

RETURNED METADATA INCLUDES: - Content type and encoding information - Creation and modification timestamps - Access patterns and usage statistics - Tags and categorization data - Version information and checksums - Custom metadata fields - Encryption key references

PERFORMANCE CHARACTERISTICS: - Uses read-only locking for optimal concurrent access - No decryption operations performed - Minimal memory footprint - Fast operation suitable for frequent metadata checks - Safe for caching as no sensitive data is involved

SECURITY CONSIDERATIONS: - Does not decrypt or expose any secret data - Does not trigger access logging (unlike GetSecret) - Does not update access counters or timestamps - Safe for permission validation workflows - Metadata may contain sensitive organizational information

USE CASES: - Pre-validation before secret access operations - Secret organization and management workflows - Compliance reporting and auditing - Version checking for concurrent access control - Content type validation before processing - Tag-based categorization and filtering - Secret lifecycle management

ERROR CONDITIONS: - Returns error if secret does not exist - Returns error for invalid secret ID format - Returns error if vault container cannot be accessed

Parameters:

  • secretID: Unique identifier of the secret whose metadata to retrieve

Returns:

  • SecretMetadata: Complete metadata structure for the secret
  • error: Any error encountered during validation, access, or if secret not found

Thread Safety: This function is thread-safe using read-only locking

Audit Logging: This operation is not audited as it does not access secret data

Example Usage: 

metadata, err := vault.GetSecretMetadata("api-key")
if err != nil {
    if strings.Contains(err.Error(), "not found") {
        log.Printf("Secret does not exist")
        return nil
    }
    return fmt.Errorf("failed to get metadata: %w", err)
}

fmt.Printf("Secret: %s\n", metadata.Name)
fmt.Printf("Content Type: %s\n", metadata.ContentType)
fmt.Printf("Last Updated: %s\n", metadata.UpdatedAt.Format(time.RFC3339))
fmt.Printf("Version: %d\n", metadata.Version)
fmt.Printf("Tags: %v\n", metadata.Tags)

func (*Vault) GetSecretWithContext 

func (v *Vault) GetSecretWithContext(ctx context.Context, secretID string) (*SecretWithContext, error)

GetSecretWithContext retrieves secret with custom context. Returns a SecretWithContext that auto-clears when context is done. Users must call Close() to ensure immediate cleanup.

func (*Vault) GetSecretWithTimeout 

func (v *Vault) GetSecretWithTimeout(secretID string, timeout time.Duration) (*SecretWithContext, error)

GetSecretWithTimeout retrieves secret with automatic timeout cleanup. Returns a SecretWithContext that auto-clears when timeout expires. Users must call Close() to ensure immediate cleanup.

func (*Vault) ListKeyMetadata 

func (v *Vault) ListKeyMetadata() ([]KeyMetadata, error)

ListKeyMetadata retrieves a complete snapshot of all key metadata in the vault.

This method provides comprehensive visibility into the vault's key management state, including all historical and current keys with their complete lifecycle information. It serves as the primary interface for key inventory management, audit reporting, compliance validation, and operational monitoring. The method returns a point-in-time snapshot with real-time status updates computed dynamically based on current vault state.

FUNCTIONALITY OVERVIEW: ListKeyMetadata performs several critical operations: - Retrieves all key metadata from the vault's internal key registry - Computes real-time active status based on current operational state - Updates key status information to reflect current vault configuration - Provides complete key inventory for audit and compliance purposes - Enables key lifecycle management and policy enforcement decisions - Supports operational monitoring and security analysis workflows - Facilitates disaster recovery planning and backup validation - Enables automated key management and governance processes

REAL-TIME STATUS COMPUTATION: The method dynamically computes accurate key status information: - Active Status: Determined by comparison with current active key ID - Operational Status: Updated based on current vault key configuration - Lifecycle Status: Reflects current position in key management lifecycle - Availability Status: Indicates current availability for cryptographic operations - Policy Status: Shows compliance with current key management policies

Status Update Logic: - Keys matching currentKeyID are marked as Active with KeyStatusActive - All other keys are marked as Inactive with KeyStatusInactive - Status updates reflect current vault operational state - Changes are computed dynamically without modifying stored metadata - Real-time accuracy ensures operational decisions are based on current state

SECURITY AND ACCESS CONTROL: The method implements comprehensive security measures: - Read-only operation with no sensitive data exposure - No cryptographic key material included in responses - Thread-safe concurrent access through read locks - Audit-safe information suitable for logging and external integration - Access control enforcement through vault authentication mechanisms - Rate limiting and resource protection for large-scale deployments

Data Protection Features: - Only metadata exposed, never actual cryptographic key material - Sanitized information safe for audit trails and compliance reporting - No sensitive operational details that could compromise security - Information suitable for external system integration and monitoring - Compliance-ready data format for regulatory reporting requirements

PERFORMANCE CHARACTERISTICS: The method is optimized for various operational scenarios: - O(n) complexity where n is the number of keys in the vault - Efficient memory allocation with pre-sized slice capacity - Read lock usage enables concurrent access with other read operations - Minimal computational overhead for real-time status updates - Optimized for frequent monitoring and audit access patterns

Performance Optimizations: - Pre-allocated slice with exact capacity to minimize memory allocations - Efficient map iteration with minimal memory copying - Read-lock usage prevents blocking other concurrent read operations - Lazy computation of status updates only when method is called - Memory-efficient snapshot creation without deep copying unnecessary data

Scalability Considerations: - Linear scaling with number of keys managed by vault - Efficient operation even with hundreds or thousands of keys - Memory usage scales predictably with key count - Network transfer efficiency for remote API access - Suitable for high-frequency monitoring and automated access

AUDIT AND COMPLIANCE INTEGRATION: ListKeyMetadata provides essential data for comprehensive audit and compliance: - Complete key inventory for regulatory compliance requirements - Historical key information for audit trail validation - Current status information for operational compliance verification - Lifecycle tracking data for policy compliance assessment - Timestamp information for retention and archival policy enforcement

Compliance Framework Support: - SOX: Complete key inventory and lifecycle documentation - PCI DSS: Cryptographic key management audit trail - HIPAA: Access control and key management documentation - SOC 2: Security control evidence and operational validation - ISO 27001: Information security management system documentation - GDPR: Data protection key management and audit requirements

Audit Trail Enhancement: - Key creation and rotation timeline visibility - Status transition history and current state validation - Policy compliance verification and exception identification - Security incident investigation and forensic analysis support - Regulatory reporting automation and validation capabilities

OPERATIONAL MONITORING INTEGRATION: The method supports comprehensive operational monitoring and alerting: - Key age analysis for rotation policy enforcement - Status distribution monitoring for operational health assessment - Capacity planning through key count and growth trend analysis - Performance monitoring for key management operation efficiency - Security monitoring for anomalous key lifecycle patterns

Monitoring Use Cases: - Automated key rotation policy enforcement and compliance validation - Security anomaly detection through key creation and status patterns - Operational health dashboard integration and real-time status display - Capacity planning and resource allocation for key management systems - Integration with SIEM systems for security event correlation and analysis

DISASTER RECOVERY AND BACKUP VALIDATION: ListKeyMetadata plays a critical role in disaster recovery operations: - Pre-disaster key inventory documentation for recovery validation - Post-recovery key state verification and completeness validation - Backup integrity verification through key count and metadata comparison - Recovery process validation ensuring all keys are properly restored - Operational continuity verification after disaster recovery procedures

Recovery Validation Capabilities: - Complete key inventory comparison between backup and restored state - Metadata integrity verification ensuring accurate restoration - Status consistency validation for operational continuity - Audit trail preservation verification for compliance continuity - Performance baseline re-establishment after recovery operations

func (*Vault) ListSecrets 

func (v *Vault) ListSecrets(options *SecretListOptions) ([]*SecretListEntry, error)

ListSecrets retrieves a filtered list of secrets from the vault without exposing encrypted data.

This function provides comprehensive secret discovery and inventory capabilities while maintaining security by returning only metadata and organizational information. The actual encrypted secret data is never included in the results, making this operation safe for broader access patterns and bulk operations.

FILTERING CAPABILITIES: - Prefix matching: Filter secrets by ID prefix (e.g., "prod-", "dev-") - Tag filtering: Return only secrets containing all specified tags - Content type filtering: Filter by specific content types (text, binary, JSON, etc.) - Pagination: Limit and offset support for large secret inventories

PERFORMANCE CHARACTERISTICS: - Uses read-only locking for optimal concurrent access - Does not decrypt any secret data, only processes metadata - Memory efficient for large secret stores - Results can be cached safely as they contain no sensitive data

SECURITY CONSIDERATIONS: - No encrypted data or decrypted secrets are returned - Exposes only organizational metadata and usage statistics - Does not trigger access logging or increment access counters - Safe for inventory and management operations - DataSize field provides storage info without revealing actual content size

PAGINATION BEHAVIOR: - If Limit is 0, all matching results are returned - Offset allows skipping initial results for pagination - Empty slice returned if offset exceeds total results - Pagination applied after all filtering operations

USE CASES: - Secret inventory and discovery - Bulk operations planning (backup, migration, cleanup) - Compliance reporting and auditing - Secret organization and categorization - Application configuration management - Secret lifecycle management

Parameters:

  • options: Filtering and pagination options (nil for all secrets)
  • Prefix: Filter by secret ID prefix
  • Tags: Filter by required tags (AND operation)
  • ContentType: Filter by specific content type
  • Limit: Maximum number of results (0 for unlimited)
  • Offset: Number of results to skip for pagination

Returns:

  • []*SecretListEntry: Array of secret metadata entries matching filters
  • error: Any error encountered during container access or processing

Thread Safety: This function is thread-safe using read-only locking

Audit Logging: This operation is not audited as it does not access secret data

Example Usage: 

// List all production secrets
options := &SecretListOptions{
    Prefix: "prod-",
    Tags:   []string{"production", "active"},
    Limit:  50,
}
secrets, err := vault.ListSecrets(options)
if err != nil {
    return fmt.Errorf("failed to list secrets: %w", err)
}
for _, secret := range secrets {
    fmt.Printf("Secret: %s, Size: %d bytes, Updated: %s\n",
        secret.ID, secret.DataSize, secret.UpdatedAt.Format(time.RFC3339))
}

func (*Vault) Restore 

func (v *Vault) Restore(backupDir, passphrase string) error

Restore performs a complete vault restoration from an encrypted backup.

This method completely replaces the current vault state with data from a previously created backup. The restoration process is destructive - all existing vault data including keys, secrets, and configuration will be permanently replaced with the backup contents. This operation is typically used for disaster recovery, data migration, or vault cloning scenarios.

RESTORATION SCOPE AND PROCESS: The restore operation performs a complete vault state replacement: - Destroys ALL existing vault data (keys, secrets, configuration) - Validates backup integrity before proceeding - Decrypts backup using provided passphrase - Restores all master encryption keys (current and historical) - Recreates vault configuration and settings - Restores key rotation history and metadata - Rebuilds internal vault state and counters - Reloads key derivation parameters and salt values - Initializes secrets container with restored data

SECURITY ARCHITECTURE: - Cryptographic backup integrity verification before restoration - Passphrase-based decryption independent of current vault state - Secure memory handling throughout restoration process - Complete state isolation during restoration - Atomic restoration semantics (succeeds completely or fails safely) - Comprehensive audit logging of restoration operations - Protected memory usage for all sensitive operations - Secure cleanup of intermediate restoration data

RESTORATION ALGORITHM: The restoration follows a strict sequence to ensure consistency: 1. Acquire exclusive vault lock (prevents concurrent operations) 2. Load and validate backup container format 3. Verify backup integrity using cryptographic checksum 4. Decrypt backup data using provided passphrase 5. Parse and validate backup data structure 6. DESTRUCTIVELY clear all existing vault state 7. Restore backup data to persistent storage 8. Recreate derivation key using restored salt 9. Initialize key enclaves from restored key metadata 10. Restore secrets container from backup data 11. Verify restored vault state consistency

BACKUP CONTAINER VALIDATION: The method validates multiple aspects of the backup: - Container format and required fields - Version compatibility between backup and vault - Base64 encoding integrity of encrypted data - Cryptographic checksum verification - Backup data structure and required components - Passphrase correctness and decryption success - Internal data consistency after restoration

PERFORMANCE CHARACTERISTICS: - Time Complexity: O(k + n) where k=number of keys, n=backup size - Space Complexity: O(n) where n=total backup data size - Memory Usage: ~4x backup size during restoration peak - I/O Operations: Sequential read from backup + write to storage - CPU Usage: High during decryption and key recreation - Disk Usage: Temporary space ~2x backup size during restoration - Lock Duration: Exclusive lock held for entire operation

ATOMIC OPERATION GUARANTEES: - Restoration either succeeds completely or fails safely - No partial restoration states - vault remains consistent - Failure during restoration leaves vault in closed state - Original vault state is completely replaced on success - No data corruption scenarios during restoration process - Rollback to previous state not supported (backup first if needed)

DISASTER RECOVERY CAPABILITIES: - Complete vault reconstruction from backup - All historical keys restored for old data access - Configuration and operational settings fully restored - Backup can be restored to different vault instances - Cross-platform restoration support - Network and cloud backup restoration support

Parameters:

  • backupDir: Directory path containing the backup files. Must contain a valid backup container created by the Backup method. Directory must be readable and contain required backup metadata. Path can be absolute or relative to current working directory.

  • passphrase: Decryption passphrase for the backup. Must exactly match the passphrase used during backup creation. This is the backup passphrase, which may differ from the vault's operational passphrase. Passphrase is used for backup decryption and subsequent vault initialization.

Returns:

  • error: nil on successful restoration, detailed error on failure

Possible Errors:

  • "vault is not initialized": Vault instance is not properly set up
  • "backup directory cannot be empty": backupDir parameter is empty
  • "passphrase cannot be empty": passphrase parameter is empty
  • "failed to load backup": Backup container loading error
  • "failed to decode backup data": Base64 decoding error
  • "backup integrity check failed": Checksum mismatch detected
  • "failed to decrypt with passphrase": Wrong passphrase or corruption
  • "failed to serialize backup data": JSON parsing error
  • "version incompatibility": Backup version not supported
  • "failed to restore backup data": Storage restoration error
  • "failed to load restored salt": Salt restoration error
  • "failed to recreate derivation key": Key derivation error
  • "failed to load keys from restored metadata": Key loading error
  • "failed to restore secrets": Secrets restoration error
  • "failed to initialize secrets container": Container initialization error
  • Various I/O errors related to backup reading and storage operations

Thread Safety: 

This method is NOT thread-safe for concurrent operations. It acquires an
exclusive write lock for the entire operation duration, preventing all
other vault operations during restoration. This ensures data consistency
but means restoration can be a blocking operation for vault access.

Audit Logging: 

All restoration operations are comprehensively logged:
- Restoration initiation with backup source information
- Backup validation and integrity check results
- Restoration progress through major phases
- Error details for failed restoration attempts
- Restoration completion status and timing
- Security events (passphrase validation, key operations)
- State transition logging throughout the process

Memory Safety:

  • All existing vault enclaves are properly destroyed before restoration
  • Backup decryption uses protected memory throughout
  • Restored keys are loaded into memguard enclaves
  • Intermediate restoration data is securely cleared
  • Passphrase handling uses secure memory practices
  • No sensitive data persists in standard Go memory

State Management:

  • Current vault state is COMPLETELY DESTROYED during restoration
  • Restoration is irreversible once started
  • Failed restoration leaves vault in closed/unusable state
  • Successful restoration replaces all vault identity and data
  • Vault becomes operationally identical to backup source
  • All previous vault history is lost and replaced

Usage Examples: 

// Basic disaster recovery restoration
err := vault.Restore("/backup/2024-01-01", "backup-passphrase")
if err != nil {
    log.Printf("Restoration failed: %v", err)
    // Vault is now in unusable state - needs fresh initialization
    return
}
log.Println("Vault successfully restored from backup")

// Production disaster recovery with validation
func performDisasterRecovery(vault *Vault, backupPath, passphrase string) error {
    // Pre-restoration validation
    if err := validateBackupIntegrity(backupPath); err != nil {
        return fmt.Errorf("backup validation failed: %w", err)
    }

    // Log disaster recovery initiation
    log.Printf("DISASTER RECOVERY: Starting restoration from %s", backupPath)

    // Perform restoration
    err := vault.Restore(backupPath, passphrase)
    if err != nil {
        log.Printf("DISASTER RECOVERY FAILED: %v", err)
        // Vault is now unusable - may need manual intervention
        return fmt.Errorf("restoration failed: %w", err)
    }

    // Post-restoration verification
    if err := verifyRestoredVaultIntegrity(vault); err != nil {
        return fmt.Errorf("post-restoration verification failed: %w", err)
    }

    log.Printf("DISASTER RECOVERY COMPLETE: Vault restored successfully")
    return nil
}

// Vault migration/cloning scenario
func migrateVaultToNewInstance(sourceBackup, passphrase string) (*Vault, error) {
    // Create new vault instance
    newVault, err := NewVault(storage.NewConfig())
    if err != nil {
        return nil, fmt.Errorf("failed to create new vault: %w", err)
    }

    // Restore from backup (this replaces any initial state)
    err = newVault.Restore(sourceBackup, passphrase)
    if err != nil {
        return nil, fmt.Errorf("failed to restore vault: %w", err)
    }

    // Verify migration success
    if !newVault.IsOperational() {
        return nil, errors.New("restored vault is not operational")
    }

    return newVault, nil
}

// Enterprise restoration with comprehensive error handling
func enterpriseVaultRestore(backupLocation, passphraseSource string) error {
    // Securely retrieve restoration passphrase
    passphrase, err := getSecureRestorePassphrase(passphraseSource)
    if err != nil {
        return fmt.Errorf("failed to retrieve passphrase: %w", err)
    }
    defer clearPassphrase(passphrase)

    // Create restoration checkpoint for rollback if needed
    checkpoint, err := createRestorationCheckpoint()
    if err != nil {
        log.Printf("WARNING: Could not create checkpoint: %v", err)
    }

    // Perform restoration with timeout
    ctx, cancel := context.WithTimeout(context.Background(), 30*time.Minute)
    defer cancel()

    errChan := make(chan error, 1)
    go func() {
        errChan <- vault.Restore(backupLocation, passphrase)
    }()

    select {
    case err := <-errChan:
        if err != nil {
            if checkpoint != nil {
                log.Printf("Restoration failed, checkpoint available: %s", checkpoint.ID)
            }
            return fmt.Errorf("restoration failed: %w", err)
        }
        return nil
    case <-ctx.Done():
        return errors.New("restoration timed out after 30 minutes")
    }
}

Security Best Practices:

  • Verify backup integrity before restoration
  • Use secure channels for passphrase transmission
  • Ensure backup source authenticity and chain of custody
  • Log all restoration attempts for security monitoring
  • Verify restored vault state before returning to service
  • Change operational passphrases after restoration if needed
  • Review audit logs after restoration for anomalies
  • Implement access controls for restoration operations
  • Consider backup source validation and signing

Operational Best Practices:

  • Test restoration procedures regularly in non-production environments
  • Document restoration procedures and recovery time objectives
  • Implement restoration monitoring and alerting
  • Plan for restoration failure scenarios and manual recovery
  • Maintain secure storage and access for backup passphrases
  • Implement restoration authorization and approval processes
  • Consider database and service dependencies during restoration
  • Plan for application restart and reconfiguration after restoration
  • Document post-restoration verification procedures

Risk Considerations:

  • Restoration completely destroys existing vault state
  • Failed restoration may require manual intervention
  • Restoration time depends on backup size and system performance
  • Exclusive lock prevents all vault operations during restoration
  • Incorrect passphrase detection only occurs during decryption
  • Backup corruption may not be detected until restoration fails
  • Version incompatibilities may cause restoration failure

Integration Considerations:

  • Applications using the vault should be stopped during restoration
  • Database connections and external resources should be managed
  • Load balancers should route traffic away during restoration
  • Monitoring systems should expect vault unavailability
  • Dependent services should be prepared for vault restart
  • Configuration management should account for restoration scenarios

Compliance and Governance:

  • All restoration operations are fully audited and logged
  • Restoration access can be controlled and monitored
  • Backup chain of custody is maintained through audit logs
  • Restoration procedures support compliance requirements
  • Data lineage and provenance are tracked through backup metadata
  • Restoration authorization can be integrated with approval workflows

Performance Optimization:

  • Schedule restoration during maintenance windows
  • Use high-performance storage for backup sources
  • Monitor memory usage during large backup restoration
  • Consider restoration parallelization for very large backups
  • Use SSD storage for restoration temporary files
  • Plan for network bandwidth requirements for remote backups

func (*Vault) RotateDataEncryptionKey 

func (v *Vault) RotateDataEncryptionKey(reason string) (*KeyMetadata, error)

RotateDataEncryptionKey performs secure cryptographic key rotation with comprehensive data protection.

This method implements a complete key rotation workflow that generates new cryptographic keys, re-encrypts all protected data with the new key, and safely transitions the vault to use the new key for all future operations. The rotation process maintains complete data accessibility throughout the operation while implementing multiple layers of validation, rollback capability, and audit trail generation. RotateKey is critical for key lifecycle management, security policy compliance, and maintaining forward secrecy in long-running vault deployments.

FUNCTIONALITY OVERVIEW AND PURPOSE: RotateKey serves as the comprehensive key lifecycle management interface: - Generates cryptographically secure new encryption keys with entropy validation - Re-encrypts all vault data with new key maintaining complete data accessibility - Atomically transitions vault to new key with rollback capability on failure - Maintains complete audit trail for compliance and security monitoring - Implements comprehensive validation at each stage preventing data loss - Supports automated key rotation policies and compliance requirements - Provides secure key lifecycle management with forward secrecy guarantees - Enables operational continuity during key rotation without service disruption

KEY ROTATION SECURITY ARCHITECTURE: The method implements defense-in-depth security throughout the rotation process:

Pre-Rotation Security Validation: - Vault State Verification: Ensures vault operational readiness before rotation - Derivation Key Accessibility: Validates key derivation capability availability - Current Key Validation: Confirms existing key accessibility and operational status - Memory Integrity: Validates key enclave accessibility and cryptographic readiness - Audit Integration: Comprehensive logging of rotation initiation and progress

Cryptographic Key Generation Security: - Secure Random Generation: Uses cryptographically secure random number generation - Entropy Validation: Implements weak key detection preventing compromised keys - Key Format Validation: Ensures generated keys meet cryptographic requirements - Collision Detection: Prevents duplicate key ID generation and conflicts - Memory Protection: Secure key handling with immediate cleanup of intermediate values

Data Re-encryption Security: - Atomic Data Transition: Ensures all data successfully re-encrypted before key transition - Rollback Capability: Complete operation reversal on any failure during re-encryption - Data Integrity: Validates successful re-encryption before committing key changes - Access Continuity: Maintains data accessibility throughout rotation process - Error Isolation: Prevents partial failures from compromising vault data integrity

Persistent Storage Security: - Atomic Metadata Updates: Ensures consistent metadata storage during rotation - Encryption Validation: Validates all keys properly encrypted before storage persistence - Rollback Integration: Supports complete operation reversal on storage failures - Consistency Checking: Validates storage consistency after successful rotation - Audit Trail Persistence: Ensures audit information captured for all rotation events

PRE-ROTATION VALIDATION AND READINESS: Comprehensive validation ensures safe rotation execution:

Derivation Key Availability: Critical validation ensuring vault can perform cryptographic operations required for key rotation including new key encryption and metadata protection. Derivation key unavailability indicates fundamental vault initialization issues that must be resolved before attempting key rotation operations.

Vault Operational State: - Closed State Detection: Prevents rotation on closed vault instances - Initialization Validation: Confirms vault properly initialized and operational - Resource Availability: Validates required cryptographic resources accessible - Concurrency Control: Ensures exclusive access during critical rotation operations

Current Key Accessibility: - Key Existence: Validates current active key exists and is accessible - Memory Availability: Confirms key material accessible in memory enclaves - Operational Readiness: Ensures current key functional for re-encryption operations - Consistency Validation: Verifies current key state consistent with metadata

CRYPTOGRAPHIC KEY GENERATION AND VALIDATION: Secure new key generation with comprehensive validation:

Key Identifier Generation: - Unique ID Creation: Generates cryptographically unique key identifiers - Format Validation: Ensures key IDs meet length and format requirements - Collision Detection: Prevents duplicate key ID conflicts with existing keys - Security Requirements: Validates key ID meets cryptographic security standards

Master Key Generation: - Cryptographic Randomness: Uses secure random number generation for key material - Key Length Validation: Ensures 32-byte keys for AES-256 encryption standards - Entropy Assessment: Implements weak key detection preventing compromised keys - Security Standards: Meets FIPS 140-2 and Common Criteria cryptographic requirements

Entropy and Security Validation: - Weak Key Detection: Prevents keys with insufficient entropy or known weaknesses - Cryptographic Analysis: Validates key material meets security requirements - Pattern Detection: Identifies and prevents predictable or compromised key patterns - Compliance Validation: Ensures keys meet regulatory and industry standards

Memory Protection: - Secure Enclave Storage: Protects key material in secure memory enclaves - Intermediate Cleanup: Immediate cleanup of temporary key material and buffers - Garbage Collection: Forces garbage collection to clear intermediate values - Memory Security: Prevents key material exposure through memory analysis

DATA RE-ENCRYPTION AND INTEGRITY PROTECTION: Critical process ensuring data accessibility throughout rotation:

Re-encryption Strategy: - Sequential Processing: Re-encrypts all vault data with new cryptographic key - Integrity Validation: Validates successful re-encryption before key transition - Access Preservation: Maintains data accessibility throughout rotation process - Error Handling: Implements comprehensive error handling with rollback capability

Critical Sequencing: The method implements crucial sequencing where data re-encryption occurs BEFORE updating the current key ID. This ensures re-encryption uses the correct current key for decryption and new key for encryption, preventing data accessibility issues during rotation.

Rollback Protection: - Failure Detection: Comprehensive error detection during re-encryption process - State Restoration: Complete rollback to pre-rotation state on any failure - Data Integrity: Ensures no data loss or corruption during failed rotations - Resource Cleanup: Proper cleanup of new key resources during rollback operations

METADATA MANAGEMENT AND PERSISTENCE: Comprehensive metadata handling ensuring vault state consistency:

Key Metadata Updates: - New Key Registration: Creates complete metadata for newly generated key - Active Status Management: Updates active/inactive status for old and new keys - Timestamp Management: Accurate creation and deactivation timestamp recording - Version Management: Proper versioning for key lifecycle tracking

Rotation Metadata Creation: - Comprehensive Recording: Captures complete rotation context and metadata - Deep Copy Protection: Prevents metadata mutations during rotation processing - Encryption Validation: Ensures all keys properly encrypted before storage - Consistency Validation: Validates metadata consistency before persistence

Persistent Storage Integration: - Atomic Updates: Ensures consistent metadata storage during rotation - Validation Before Save: Comprehensive validation before storage persistence - Rollback Capability: Supports complete operation reversal on storage failures - Integrity Checking: Validates storage integrity after successful updates

func (*Vault) RotateKeyEncryptionKey 

func (v *Vault) RotateKeyEncryptionKey(newPassphrase string, reason string) error

RotateKeyEncryptionKey performs emergency passphrase rotation for the vault effectively changing the Key Encryption Key.

This method implements a secure passphrase rotation process that re-encrypts all existing encryption keys with a new derivation key derived from the new passphrase. The operation is atomic - either all changes succeed or the vault is rolled back to its original state.

SECURITY FEATURES: - Uses memguard enclaves to protect sensitive data in memory - Generates cryptographically secure random salt (32 bytes) - Derives new key using Argon2id key derivation function - Re-encrypts all existing keys with new derivation key - Implements rollback on failure to maintain vault integrity - Wipes all temporary sensitive data from memory - Thread-safe with mutex protection

OPERATION FLOW: 1. Validation: Checks vault state and parameters 2. Salt Generation: Creates new cryptographically secure salt 3. Key Derivation: Derives new key from passphrase + salt using Argon2id 4. Key Re-encryption: Re-encrypts all existing keys with new derivation key 5. Persistence: Saves new salt and metadata to storage 6. Rollback: Reverts changes if any step fails 7. Cleanup: Destroys old keys and logs operation

MEMORY SAFETY: - All sensitive data is protected using memguard enclaves - Temporary copies are wiped immediately after use - Ownership transfer prevents premature cleanup - Deferred cleanup ensures no memory leaks

ERROR HANDLING: - Comprehensive rollback on any failure - Preserves original vault state on errors - Critical rollback failures are logged for investigation - Detailed error messages for debugging

ATOMICITY: The operation maintains ACID properties: - Atomic: Either completely succeeds or fails with rollback - Consistent: Vault remains in valid state throughout - Isolated: Thread-safe with mutex protection - Durable: Changes are persisted to storage

Parameters:

  • newPassphrase: The new passphrase to use for key derivation. Must be non-empty. Should be sufficiently strong (12+ characters recommended).
  • reason: Human-readable reason for the rotation (used for audit logging). If empty, defaults to "manual rotation".

Returns:

  • error: nil on success, detailed error on failure

Possible Errors:

  • "vault is closed": Vault has been closed and cannot be used
  • "new passphrase cannot be empty": Invalid passphrase provided
  • "failed to generate new salt": Cryptographic random generation failed
  • "failed to access key X during rotation": Cannot decrypt existing key
  • "failed to re-encrypt key X": Cannot encrypt key with new derivation key
  • "failed to save new salt": Storage layer error saving salt
  • "failed to save new metadata": Storage layer error saving metadata
  • "failed to access new salt for saving": Memory access error
  • Various rollback-related errors if recovery fails

Thread Safety: 

This method is thread-safe. It uses a read-write mutex to ensure
exclusive access during the rotation process.

Performance Considerations:

  • Time complexity: O(n) where n is the number of keys
  • Memory usage: Temporary copies of all keys during re-encryption
  • I/O operations: Multiple storage writes (salt, metadata)
  • CPU intensive: Argon2id key derivation and AES encryption operations

Usage Examples: 

// Basic rotation
err := vault.RotateKeyEncryptionKey("new-secure-passphrase", "scheduled rotation")
if err != nil {
    log.Printf("Rotation failed: %v", err)
}

// Emergency rotation
err := vault.RotateKeyEncryptionKey("emergency-passphrase", "potential compromise detected")
if err != nil {
    log.Printf("Emergency rotation failed: %v", err)
}

Security Considerations:

  • The old passphrase should be considered compromised after rotation
  • The new passphrase should be generated securely and stored safely
  • This operation should be logged and monitored
  • Consider notifying relevant parties about the rotation
  • Backup the vault before rotation in critical environments

Post-Rotation Steps:

  • Update any external systems that use the old passphrase
  • Verify vault integrity with test encryption/decryption
  • Monitor audit logs for any anomalies
  • Consider rotating dependent credentials if compromise is suspected

func (*Vault) SecretExists 

func (v *Vault) SecretExists(secretID string) (bool, error)

SecretExists checks whether a secret with the given ID exists in the vault.

This function provides a lightweight way to verify secret existence without retrieving or decrypting the actual secret data, making it suitable for validation, conditional logic, and existence checks in application workflows.

PERFORMANCE CHARACTERISTICS: - Uses read-only locking for better concurrent access performance - Does not decrypt or load secret data, only checks metadata presence - Minimal memory footprint compared to full secret retrieval - Fast operation suitable for frequent existence checks

SECURITY CONSIDERATIONS: - Does not trigger access logging (unlike GetSecret operations) - Does not increment access counters or update last accessed timestamps - Safe for permission-checking workflows before actual secret access - Returns only boolean existence, no sensitive metadata exposure

USE CASES: - Pre-validation before secret operations (update, delete, access) - Conditional secret creation (create only if not exists) - Bulk operations requiring existence verification - Application logic requiring secret presence confirmation

Parameters:

  • secretID: Unique identifier of the secret to check for existence

Returns:

  • bool: true if secret exists, false if it does not exist
  • error: Any error encountered during validation or container access Note: Non-existence is not an error condition

Thread Safety: This function is thread-safe using read-only locking

Audit Logging: This operation is not audited as it does not access secret data

Example Usage: 

exists, err := vault.SecretExists("api-key")
if err != nil {
    return fmt.Errorf("failed to check secret existence: %w", err)
}
if !exists {
    log.Printf("Secret 'api-key' not found, creating new one")
    // Proceed with secret creation
}

func (*Vault) SecureMemoryProtection 

func (v *Vault) SecureMemoryProtection() string

SecureMemoryProtection returns a human-readable description of the current memory protection level.

This function provides visibility into the vault's comprehensive memory security configuration, which combines memguard secure enclaves with platform-specific memory locking to provide defense-in-depth against memory-based attacks and data exposure.

IMPLEMENTATION DETAILS: The vault uses a layered memory protection approach: • memguard.Enclave containers for all sensitive data (keys, secrets, salts) • Platform-specific memory locking via mlockall() system calls • Automatic secure memory wiping on deallocation • Canary-based buffer overflow detection • Signal handler protection against memory dumps

PROTECTION LEVELS EXPLAINED:

• ProtectionNone: memguard enclaves active, but system memory locking failed

  • Sensitive data is still protected in secure enclaves with canary guards
  • Memory pages may still be swapped to disk by the operating system
  • Provides baseline protection but vulnerable to swap file analysis
  • Typically occurs due to insufficient system privileges

• ProtectionPartial: memguard enclaves + limited system memory locking

  • Full memguard protection with secure allocation and cleanup
  • Memory locking attempted but failed with EPERM (permission) or ENOSYS (not supported)
  • Better than ProtectionNone due to memguard's inherent protections
  • Suitable for environments where full memory locking isn't available

• ProtectionFull: memguard enclaves + complete system memory locking

  • All memory pages locked via mlockall(MCL_CURRENT | MCL_FUTURE)
  • Maximum protection against swap files, hibernation, and memory dumps
  • Requires elevated privileges (CAP_IPC_LOCK on Linux)
  • Recommended for production environments handling highly sensitive data

SECURITY FEATURES ACTIVE AT ALL LEVELS: • Secure memory allocation via memguard enclaves • Cryptographically secure memory wiping on deallocation • Buffer overflow detection with canary values • Protection against memory dumps during process crashes • Isolation of sensitive data from regular heap allocation

PLATFORM COMPATIBILITY: • Linux: Full support for mlockall() with proper capabilities • Darwin (macOS): Full support with administrator privileges • BSD variants: Full support where mlockall() is available • Windows: Separate implementation (not shown) using VirtualLock()

OPERATIONAL REQUIREMENTS: • ProtectionFull requires CAP_IPC_LOCK capability or root privileges on Unix systems • Memory locking may be limited by RLIMIT_MEMLOCK resource limits • Locked memory cannot be swapped, potentially affecting system performance • Process memory usage becomes non-swappable, affecting system memory management

Returns:

  • string: Detailed description of active memory protection measures including both memguard and system-level protections

Example Usage: 

protection := vault.SecureMemoryProtection()
log.Printf("Memory protection status: %s", protection)

// Check if running with maximum security
if strings.Contains(protection, "Full") {
    log.Info("Running with maximum memory protection")
} else {
    log.Warn("Consider running with elevated privileges for full protection")
}

func (*Vault) StoreSecret 

func (v *Vault) StoreSecret(secretID string, secretData []byte, tags []string, contentType ContentType) (*SecretMetadata, error)

StoreSecret encrypts and stores new secret data in the vault with associated metadata and tags.

This method creates a new secret entry in the vault, encrypting the provided data using the currently active encryption key. The secret is assigned version 1 and comprehensive metadata is generated including creation timestamps, checksums, and access tracking information.

The storage operation is atomic - if any step fails, no partial data is stored and the vault remains in a consistent state. All sensitive operations are performed within protected memory enclaves to prevent data exposure.

Parameters:

  • secretID: Unique identifier for the secret (must be valid according to ID rules)
  • secretData: The raw secret data to encrypt and store (cannot be empty)
  • tags: Optional list of tags for categorization and filtering (duplicates removed)
  • contentType: MIME-type indication of the secret data format for proper handling

Returns:

  • *SecretMetadata: Complete metadata for the newly stored secret including:
  • Unique secret ID and version number (1 for new secrets)
  • Encryption key ID used for the operation
  • Creation and update timestamps (identical for new secrets)
  • Size and checksum of the encrypted data
  • Content type and tags as provided
  • Access tracking fields (initialized to zero)
  • Custom fields map (empty for new secrets)
  • error: Error if storage fails for any reason

Error Conditions:

  • Vault is closed or not properly initialized
  • Invalid secret ID (empty, invalid characters, reserved names, etc.)
  • Empty secret data (zero-length byte slice)
  • Invalid secret data for the specified content type
  • Invalid or malformed tags (after validation and sanitization)
  • Invalid content type (not in supported ContentType constants)
  • Secret with the same ID already exists (use UpdateSecret instead)
  • Encryption failure (key unavailable, cryptographic error)
  • Storage persistence failure (disk full, permissions, network error)
  • Container update failure (corruption, concurrent access issues)

Security Behavior:

  • Secret data is encrypted using authenticated encryption (ChaCha20-Poly1305)
  • Encryption key is the currently active key from the key management system
  • Original secret data is never persisted in plaintext
  • Checksum is calculated on plaintext data before encryption for integrity verification
  • All cryptographic operations occur in protected memory enclaves
  • Sensitive data is immediately cleared from working memory after encryption

Validation Rules:

  • Secret IDs must follow naming conventions (alphanumeric, hyphens, underscores typically)
  • Secret data is validated against the declared content type when possible
  • Tags are sanitized to remove invalid characters and duplicates
  • Content type must be one of the supported ContentType constants
  • Maximum size limits may apply depending on storage backend

Audit and Logging:

  • Successful storage operations generate "STORE" audit events
  • Audit logs include secret ID but never secret content
  • Failed operations may generate audit entries depending on failure type
  • Timing information is recorded for security monitoring

Concurrency and Atomicity:

  • Method uses write locks to prevent concurrent modifications
  • Container updates are atomic - partial failures leave vault unchanged
  • Storage persistence is separate from in-memory updates for consistency
  • Multiple secrets can be stored concurrently by different vault instances

Storage Layout:

  • Secret is added to the vault's secrets container structure
  • Container versioning is updated to reflect the change
  • Encrypted data includes authentication tags for tamper detection
  • Metadata is stored alongside encrypted data for efficient access

Performance Considerations:

  • Encryption performance scales with secret data size
  • Tag validation and deduplication adds minimal overhead
  • Storage persistence latency depends on backend implementation
  • Memory usage is proportional to secret size during encryption

Example Usage: 

tags := []string{"production", "database", "credentials"}
metadata, err := vault.StoreSecret(
    "db-password",
    []byte("super-secret-password"),
    tags,
    volta.ContentTypeText,
)
if err != nil {
    if strings.Contains(err.Error(), "already exists") {
        // Handle duplicate secret ID
        return fmt.Errorf("secret already exists: use update instead")
    }
    return fmt.Errorf("failed to store secret: %w", err)
}
fmt.Printf("Stored secret %s (v%d) with key %s\n",
    metadata.SecretID, metadata.Version, metadata.KeyID)

Related Methods:

  • UpdateSecret: For modifying existing secrets (increments version)
  • GetSecret: For retrieving and decrypting stored secrets
  • SecretExists: For checking secret existence before storage
  • DeleteSecret: For removing secrets from the vault

func (*Vault) UpdateSecret 

func (v *Vault) UpdateSecret(secretID string, secretData []byte, tags []string, contentType ContentType) (*SecretMetadata, error)

UpdateSecret modifies an existing secret with new data, tags, and content type.

This function performs a complete update of an existing secret, including: 1. Validation of vault state, secret ID, and new data 2. Verification that the secret exists in the vault 3. Re-encryption of the secret data with the current active key 4. Update of all mutable metadata fields (size, checksum, tags, etc.) 5. Version increment for change tracking 6. Persistence of changes to storage

IMPORTANT BEHAVIOR: - The secret is re-encrypted with the current active key (supports key rotation) - Version number is automatically incremented - UpdatedAt timestamp is set to current time - Original creation metadata (CreatedAt, SecretID) is preserved - Access tracking (AccessCount, LastAccessed) is preserved - Tags are deduplicated automatically

SECURITY CONSIDERATIONS: - Input secret data should be handled securely (consider clearing from memory after use) - The operation is atomic - either all updates succeed or none do - All changes are logged for audit purposes if auditing is enabled

Parameters:

  • secretID: Unique identifier of the secret to update
  • secretData: New secret data to encrypt and store (must not be empty)
  • tags: New set of tags for organization/classification (duplicates removed)
  • contentType: Content type hint for the secret data format

Returns:

  • SecretMetadata: Complete updated metadata including new version and timestamps
  • error: Any error encountered during validation, encryption, or persistence

Thread Safety: This function is thread-safe through internal mutex locking

Audit Logging: Update operations are logged if auditing is enabled

Storage: Changes are immediately persisted to the underlying storage system

Example Usage: 

metadata, err := vault.UpdateSecret(
    "my-secret",
    []byte("new-secret-value"),
    []string{"production", "database"},
    ContentTypeText,
)
if err != nil {
    return fmt.Errorf("failed to update secret: %w", err)
}
fmt.Printf("Secret updated to version %d\n", metadata.Version)

func (*Vault) UseSecret 

func (v *Vault) UseSecret(secretID string, fn func(data []byte) error) error

UseSecret executes a function with a secret and ensures automatic cleanup. This is the recommended way to work with secrets for maximum security.

This function implements the "secure callback" pattern that provides controlled access to secret data while guaranteeing secure cleanup regardless of how the callback function terminates. It eliminates the risk of secret data remaining in memory after use and prevents common security vulnerabilities associated with manual secret lifecycle management.

SECURITY GUARANTEES:

  1. AUTOMATIC CLEANUP: Secret data is unconditionally cleared from memory using secure wiping techniques when the callback completes, whether through normal return, panic, or early termination. The defer statement ensures cleanup even if the callback function encounters unexpected errors.

  2. CONTROLLED ACCESS SCOPE: The secret data is only accessible within the callback function's execution context. This temporal isolation prevents accidental retention of references to secret data and enforces proper secret handling boundaries.

  3. SECURE MEMORY MANAGEMENT: The underlying secret data is stored in memguard-protected memory that: • Prevents memory dumps from exposing secrets • Uses secure allocation techniques resistant to cold boot attacks • Implements cryptographically secure memory clearing • Protects against swap file exposure through memory locking

  4. ZERO-COPY ARCHITECTURE: The secret data is provided directly to the callback without intermediate copies, reducing the memory footprint of sensitive data and minimizing the attack surface for memory-based attacks.

Parameters:

  • secretID: Unique identifier for the secret to retrieve and use
  • fn: Callback function that receives the secret data and performs operations

Returns:

  • error: Secret retrieval error or callback execution error. Nil indicates successful completion of both secret access and callback execution.

func (*Vault) UseSecretPair 

func (v *Vault) UseSecretPair(secretID1, secretID2 string, fn func(secret1, secret2 []byte) error) error

UseSecretPair executes a function with exactly two secrets. Convenience method for common two-secret operations like key+password or username+password combinations.

This function is optimized for the common case of operations requiring exactly two secrets, providing a cleaner interface than the general UseSecrets function while maintaining all the same security guarantees.

SECURITY GUARANTEES: Same as UseSecrets, with compile-time guarantee of exactly two secrets.

Example usage: 

err := vault.UseSecretPair("private-key", "key-password",
    func(key, password []byte) error {
        decryptedKey, err := decryptPrivateKey(key, password)
        if err != nil {
            return err
        }
        return usePrivateKey(decryptedKey)
    })

Parameters:

  • secretID1: First secret identifier
  • secretID2: Second secret identifier
  • fn: Callback function receiving both secrets as separate parameters

Returns:

  • error: Returns nil on successful completion, non-nil on failure

func (*Vault) UseSecretPairString 

func (v *Vault) UseSecretPairString(secretID1, secretID2 string, fn func(secret1, secret2 string) error) error

UseSecretPairString executes a function with exactly two secrets as strings. String version of UseSecretPair for text-based secret pairs.

Parameters:

  • secretID1: First secret identifier
  • secretID2: Second secret identifier
  • fn: Callback function receiving both secrets as strings

Returns:

  • error: Returns nil on successful completion, non-nil on failure

func (*Vault) UseSecretString 

func (v *Vault) UseSecretString(secretID string, fn func(secret string) error) error

UseSecretString executes a function with a secret string and ensures cleanup. This is a convenience method specifically designed for string-based secrets that provides the same security guarantees as UseSecret but with automatic string conversion for enhanced usability.

This function implements the "secure callback" pattern optimized for text-based secrets such as passwords, API keys, tokens, and configuration values. It ensures that string secrets are handled with the same rigorous security standards as binary secrets while providing a more convenient interface for text operations.

SECURITY GUARANTEES:

  1. MEMGUARD PROTECTION: Secret data is protected using memguard's secure memory allocation that: • Locks memory pages to prevent swapping to disk • Uses guard pages to detect buffer overruns • Implements cryptographically secure memory wiping • Protects against memory dump attacks and cold boot attacks

  2. AUTOMATIC STRING CONVERSION: The raw secret bytes are converted to a string within the secure context, eliminating the need for manual conversion that could leave intermediate copies in unprotected memory. The conversion happens directly from the memguard-protected buffer.

  3. DETERMINISTIC CLEANUP: Secret data is unconditionally cleared when the callback completes: • memguard.LockedBuffer.Destroy() securely wipes the string data • memguard.Enclave.Destroy() releases the secure container • Cleanup occurs regardless of callback success, failure, or panic • No residual string data remains in Go's string pool or heap

  4. ZERO-COPY STRING ACCESS: The string is created directly from the secure buffer without intermediate allocations, minimizing the memory footprint and reducing exposure time of sensitive string data in system memory.

USAGE PATTERNS:

This method is specifically designed for text-based secret operations: • Password verification and authentication • API key insertion into HTTP headers • Database connection string processing • JWT token validation and signing • Configuration value injection • Certificate PEM processing • OAuth token handling

Example usage: 

err := vault.UseSecretString("api-key", func(apiKey string) error {
    client := &http.Client{}
    req, _ := http.NewRequest("GET", "https://api.example.com/data", nil)
    req.Header.Set("Authorization", "Bearer " + apiKey)
    resp, err := client.Do(req)
    return handleResponse(resp, err)
})

CALLBACK FUNCTION CONSTRAINTS:

The callback function must observe strict memory safety rules: • NEVER store the string parameter in variables that outlive the callback • NEVER pass the string to goroutines launched within the callback • NEVER assign the string to struct fields or global variables • NEVER append the string to slices that persist beyond callback scope • Complete all string operations before returning from the callback

SAFE OPERATIONS within callback: • String comparison and equality checks • String parsing and validation • Immediate use in function calls (HTTP headers, database queries) • Temporary string manipulation (splitting, trimming) within callback scope • Copy operations that consume the string immediately

UNSAFE OPERATIONS that violate security: 

var storedKey string  // DANGEROUS: Persisted reference
err := vault.UseSecretString("api-key", func(key string) error {
    storedKey = key     // VIOLATION: String persists after cleanup
    go useKey(key)      // VIOLATION: Goroutine access after cleanup
    return nil
})
// storedKey now contains cleared/invalid memory reference

ERROR HANDLING:

Errors can occur at multiple stages: 1. Secret Retrieval (secretID not found, access denied, decryption failure) 2. Memguard Operations (memory allocation failure, buffer opening failure) 3. Callback Execution (application-specific errors returned by fn)

In all error scenarios, automatic cleanup is guaranteed: • If secret retrieval fails: no cleanup needed, error returned immediately • If memguard operations fail: partial cleanup performed, error propagated • If callback fails: full cleanup performed before error propagation • If callback panics: defer statements ensure cleanup before panic propagates

PERFORMANCE CHARACTERISTICS:

• Single memory allocation in secure space (no copying overhead) • Direct string access without intermediate buffers • Minimal garbage collection impact (secure memory managed separately) • Deterministic cleanup latency (bounded by memguard operations) • Thread-safe concurrent access (vault handles internal synchronization)

MEMORY SECURITY DETAILS:

String lifecycle within callback: 1. Secret retrieved from secure storage 2. Data loaded into memguard.Enclave (encrypted at rest) 3. Enclave opened to memguard.LockedBuffer (locked, guarded memory) 4. String created by direct cast from buffer bytes 5. Callback executed with string parameter 6. Buffer destroyed (cryptographic wiping of string data) 7. Enclave destroyed (cleanup of secure container)

COMPLIANCE AND AUDITING:

This function integrates with compliance monitoring systems: • Access events logged with timestamp and secret identifier • Callback execution duration tracked for audit trails • Memory access patterns monitored for security analysis • Integration with SIEM systems for security event correlation

COMPATIBILITY:

This function is compatible with: • All UTF-8 encoded string secrets • Binary secrets that represent text data • Multi-byte character encodings stored as UTF-8 • Secrets containing null bytes (handled as Go string semantics)

Parameters:

  • secretID: Unique identifier for the secret to retrieve. Must be a valid secret identifier that exists in the vault and is accessible with current permissions. Case-sensitive string that follows vault naming conventions.
  • fn: Callback function that receives the secret as a string parameter. The function signature must match func(string) error exactly. The string parameter is only valid within the callback scope and must not be retained.

Returns:

  • error: Returns nil on successful completion of both secret retrieval and callback execution. Non-nil errors indicate:
  • Secret retrieval failures (ErrSecretNotFound, ErrAccessDenied)
  • Memguard operation failures (ErrMemoryAllocation, ErrBufferAccess)
  • Callback execution errors (application-specific errors from fn)
  • System-level failures (ErrVaultCorrupt, ErrInternalError)

Thread Safety: This function is fully thread-safe and can be called concurrently from multiple goroutines. Each invocation creates its own secure memory context and cleanup is isolated per call.

Related Functions:

  • UseSecret(): For binary secret data requiring byte slice access
  • UseSecretWithTimeout(): For time-bounded string secret operations
  • UseSecretWithContext(): For context-controlled string secret operations

func (*Vault) UseSecretWithContext 

func (v *Vault) UseSecretWithContext(ctx context.Context, secretID string, fn func(data []byte) error) error

UseSecretWithContext executes a function with a secret with context. Secret is automatically cleared when function completes or context is cancelled.

This function extends the secure callback pattern with context-aware cancellation support, enabling timeout control and cooperative cancellation of secret operations.

Parameters:

  • ctx: Context for cancellation and timeout control
  • secretID: Unique identifier for the secret to retrieve and use
  • fn: Callback function that receives secret data

Returns:

  • error: Returns context errors, secret retrieval errors, or callback execution errors

func (*Vault) UseSecretWithTimeout 

func (v *Vault) UseSecretWithTimeout(secretID string, timeout time.Duration, fn func(data []byte) error) error

UseSecretWithTimeout executes a function with a secret with timeout. Secret is automatically cleared when function completes or timeout occurs.

This function extends the secure callback pattern with automatic timeout protection, ensuring that secret data cannot remain in memory beyond a specified duration.

Parameters:

  • secretID: Unique identifier for the secret to retrieve and use
  • timeout: Maximum duration the callback is allowed to execute before forced termination and secret cleanup
  • fn: Callback function that receives secret data and should respect context cancellation for cooperative timeout handling

Returns:

  • error: Returns context.DeadlineExceeded if timeout occurs, secret retrieval errors, or callback execution errors.

func (*Vault) UseSecrets 

func (v *Vault) UseSecrets(secretIDs []string, fn func(secrets map[string][]byte) error) error

UseSecrets executes a function with multiple secrets and ensures cleanup. This function extends the secure callback pattern to support operations that require multiple secrets simultaneously, such as cryptographic operations requiring both a private key and password, or API integrations needing multiple authentication tokens.

This function implements the "multi-secret secure callback" pattern that provides controlled access to multiple secret values while maintaining the same security guarantees as single-secret operations. It ensures all secrets are properly cleaned up regardless of callback execution outcome.

SECURITY GUARANTEES:

  1. ATOMIC SECRET RETRIEVAL: All secrets are retrieved and prepared before the callback executes. If any secret fails to load, no secrets are exposed and the operation fails safely. This prevents partial secret exposure in error scenarios.

  2. SYNCHRONIZED CLEANUP: All secrets are cleaned up simultaneously when the callback completes, ensuring no temporal windows where some secrets remain in memory while others are cleared. Cleanup is guaranteed even if the callback panics.

  3. MEMGUARD PROTECTION FOR ALL SECRETS: Each secret is independently protected using memguard's secure memory allocation, providing the same security guarantees as single-secret operations: memory locking, guard pages, secure wiping, and dump protection.

  4. ORDERED ACCESS PATTERN: Secrets are provided to the callback in a deterministic map structure, allowing consistent access patterns and reducing the risk of secret confusion in multi-secret operations.

USAGE PATTERNS:

This method is designed for operations requiring multiple secrets: • Cryptographic signing (private key + passphrase) • Multi-factor authentication (password + TOTP seed) • API chaining (primary token + refresh token + API key) • Database operations (username + password + connection string) • Certificate operations (private key + certificate + CA bundle) • Multi-tenant operations (tenant key + shared secret + API token)

Example usage: 

secretIDs := []string{"private-key", "key-passphrase", "api-token"}
err := vault.UseSecrets(secretIDs, func(secrets map[string][]byte) error {
    privateKey := secrets["private-key"]
    passphrase := secrets["key-passphrase"]
    apiToken := secrets["api-token"]

    // Decrypt private key with passphrase
    decryptedKey, err := decryptPrivateKey(privateKey, passphrase)
    if err != nil {
        return err
    }

    // Use decrypted key and API token for operation
    return performSignedAPICall(decryptedKey, apiToken)
})

CALLBACK FUNCTION CONSTRAINTS:

The callback function receives a map[string][]byte where keys are secret IDs and values are the corresponding secret data. All standard security constraints apply to each secret: • NEVER store secret data beyond the callback scope • NEVER pass secrets to concurrent goroutines • NEVER assign secrets to persistent data structures • Complete all operations with secrets before returning

ERROR HANDLING:

Multi-secret operations have additional error scenarios: • If ANY secret fails to retrieve, the entire operation fails • Partial success is not possible - all secrets must be available • If callback fails, ALL secrets are cleaned up before error propagation • Memory allocation failures for any secret abort the entire operation

PERFORMANCE CHARACTERISTICS:

• Parallel secret retrieval where possible (vault implementation dependent) • Single memory allocation per secret in secure space • Batch cleanup operations for optimal performance • Memory overhead scales linearly with secret count

Parameters:

  • secretIDs: Slice of unique secret identifiers to retrieve. Order is preserved in the callback map keys. Duplicate IDs will result in error.
  • fn: Callback function receiving map of secretID -> secret data pairs. All secrets are guaranteed to be available when callback executes.

Returns:

  • error: Returns nil on successful completion. Errors indicate secret retrieval failures, duplicate secret IDs, or callback execution errors.

func (*Vault) UseSecretsString 

func (v *Vault) UseSecretsString(secretIDs []string, fn func(secrets map[string]string) error) error

UseSecretsString executes a function with multiple secrets as strings. Convenience method for string-based multi-secret operations.

This function provides the same multi-secret capabilities as UseSecrets but with automatic string conversion for all secrets. It's particularly useful for operations involving multiple text-based secrets like passwords, tokens, and configuration values.

SECURITY GUARANTEES: All security guarantees from UseSecrets apply, with additional string-specific protections: • String conversion happens within secure memory context • No intermediate string copies in unprotected memory • All string data cleared simultaneously on callback completion

Example usage: 

secretIDs := []string{"db-password", "api-key", "jwt-secret"}
err := vault.UseSecretsString(secretIDs, func(secrets map[string]string) error {
    dbPassword := secrets["db-password"]
    apiKey := secrets["api-key"]
    jwtSecret := secrets["jwt-secret"]

    // Use all secrets for complex authentication flow
    return performMultiStepAuth(dbPassword, apiKey, jwtSecret)
})

Parameters:

  • secretIDs: Slice of unique secret identifiers to retrieve as strings
  • fn: Callback function receiving map of secretID -> secret string pairs

Returns:

  • error: Returns nil on successful completion, non-nil on failure

type VaultManager 

type VaultManager struct {
	// contains filtered or unexported fields
}

VaultManager manages vault instances per tenant

OVERVIEW: The VaultManager is responsible for handling the lifecycle and operations of vault instances for different tenants. Each tenant can have its own vault configuration, storage implementation, and security policies. The VaultManager provides methods to create, close, and manage tenant vaults, facilitating complete isolation and security compliance.

CLIENT REQUIREMENTS: Clients utilizing the VaultManager should implement the VaultManagerService interface to interact with tenant vaults, ensuring adherence to the operational and security policies set for each tenant. It should be initiated with a comprehensive set of options that dictate cryptographic behaviors, memory management, and audit configurations for optimal security posture.

KEY FUNCTIONALITIES:

  1. **Tenant Vault Management**: - GetVault: Retrieve the vault associated with the specified tenant ID. - CloseTenant: Gracefully close and release resources associated with a tenant's vault. - CloseAll: Close all tenant vaults, ensuring cleanup of resources and auditing operations. - ListTenants: Retrieve a list of all tenant IDs currently managed by the VaultManager.

  2. **Key and Passphrase Rotation**: - RotateAllTenantKeys: Rotate encryption keys for specified tenant IDs, with an optional reason for auditing. - RotateAllTenantPassphrases: Update the master passphrase for tenants, ensuring secure transition from the old passphrase to the new one.

  3. **Audit Logging**: - QueryAuditLogs: Fetch audit logs based on specified query options for compliance monitoring. - GetAuditSummary: Obtain a summary of audit logs for a tenant since a defined time. - QueryKeyOperations, QuerySecretAccess, QueryFailedOperations, and QueryPassphraseAccessLogs: Specific queries for detailed insights into vault usage, failures, and access patterns.

INITIALIZATION CONSIDERATIONS: Clients should initialize the VaultManager with a suitable store factory or store configuration, allowing for tailored storage backends suitable for individual tenants. The factory should provide security, isolation, and flexibility in handling tenant data without risk of exposure or compromise.

USAGE EXAMPLE: 

```go
// Create base vault options with secure configuration
vaultOptions := Options{
    DerivationSalt:       generateSecureSalt(),
    DerivationPassphrase: "very-secure-passphrase-12345!",
    EnableMemoryLock:     true,
    Debug:                false,
}

// Create a centralized audit logger
auditLogger := audit.NewFileLogger("/var/log/vault/audit.log")

// Define a storage factory for tenant vaults
storeFactory := func(tenantID string) (persist.Store, error) {
    return persist.NewS3Store(fmt.Sprintf("vault-%s", tenantID))
}

// Initialize the VaultManager with defined options
vaultManager := NewVaultManagerWithStoreFactory(vaultOptions, storeFactory, auditLogger)

// Use the vault manager to manage tenant vaults
tenantVault, err := vaultManager.GetVault("tenant-001")
if err != nil {
    log.Fatalf("Failed to retrieve tenant vault: %v", err)
}
```

PARAMETERS: 

options: A set of cryptographic and operational configurations applicable to all tenant vaults.
storeFactory: A function that generates a tenant-specific storage backend based on the tenant ID.
auditLogger: An instance of the centralized audit logger for monitoring and compliance tracking.

RETURNS: 

VaultManagerService: An instance of the VaultManagerService that provides access to tenant vault operations.

func NewVaultManagerWithStoreConfig 

func NewVaultManagerWithStoreConfig(baseOptions Options, storeConfig persist.StoreConfig, auditLogger audit.Logger) *VaultManager

NewVaultManagerWithStoreConfig creates a new VaultManager with configurable storage backends.

OVERVIEW: This constructor provides advanced storage configuration capabilities for the VaultManager, enabling organizations to select and configure specific storage backends based on their operational requirements, compliance needs, and infrastructure constraints. It supports multiple storage types through a unified configuration interface while maintaining consistent vault management functionality.

STORAGE BACKEND ARCHITECTURE: 

FACTORY PATTERN IMPLEMENTATION:
The constructor implements a factory pattern that creates tenant-specific storage
instances based on the provided StoreConfig. Each tenant receives an isolated
storage instance configured with the same backend parameters but scoped to their
specific tenant context, ensuring complete data isolation.

SUPPORTED STORAGE TYPES:
Currently supports StoreTypeFileSystem and StoreTypeS3 storage backends through
the persist.StoreConfig configuration system. Each storage type accepts specific
configuration parameters through the Config map[string]interface{} field to
accommodate backend-specific requirements and optimization settings.

TENANT ISOLATION:
Each tenant receives a dedicated storage instance created through the factory
function, ensuring complete data isolation at the storage layer. Storage paths,
buckets, or other tenant-specific identifiers are automatically handled by the
underlying storage implementation based on the provided tenant ID.

CONFIGURATION STRUCTURE: 

StoreConfig Parameters:
- Type: Specifies the storage backend (StoreTypeFileSystem, StoreTypeS3)
- Config: Backend-specific configuration parameters as key-value pairs

FileSystem Storage Configuration:
- "base_path": Root directory for vault storage (string)
- "permissions": File/directory permissions (int, default 0700)
- "sync_writes": Enable synchronous writes for durability (bool)

S3 Storage Configuration:
- "bucket": S3 bucket name for storage (string, required)
- "region": AWS region for bucket access (string, required)
- "access_key_id": AWS access key ID (string)
- "secret_access_key": AWS secret access key (string)
- "session_token": AWS session token for temporary credentials (string)
- "endpoint": Custom S3 endpoint for S3-compatible services (string)
- "use_path_style": Enable path-style bucket addressing (bool)

AUDIT INTEGRATION: 

COMPREHENSIVE AUDIT LOGGING:
The constructor integrates a centralized audit logger that captures all vault
operations across tenants. The audit logger configuration supports multiple
audit backends (file, syslog) with configurable log levels and output formats
for compliance and security monitoring requirements.

AUDIT CONFIGURATION:
audit.Config supports:
- Enabled: Enable/disable audit logging (bool)
- TenantID: Tenant-specific audit context (string)
- Type: Audit backend type (FileAuditType, SyslogAuditType, NoOp)
- Options: Backend-specific audit configuration (map[string]interface{})
- LogLevel: Audit logging verbosity level (string)

OPERATIONAL CHARACTERISTICS: 

LAZY INITIALIZATION:
Tenant-specific storage instances are created on-demand when tenants are
first accessed or created. This approach minimizes resource consumption
and enables efficient scaling for environments with large numbers of
potential tenants that may not be actively used.

THREAD SAFETY:
The vault manager implements comprehensive thread safety through RWMutex
protection, enabling safe concurrent access to tenant vaults while
maintaining performance for read-heavy workloads through read-write
lock optimization.

ERROR ISOLATION:
Storage configuration errors are isolated per tenant, preventing
configuration issues with one tenant from affecting others. Invalid
configurations are detected during tenant initialization and reported
through appropriate error channels.

USAGE EXAMPLES: 

FILESYSTEM STORAGE CONFIGURATION:
  storeConfig := persist.StoreConfig{
      Type: StoreTypeFileSystem,
      Config: map[string]interface{}{
          "base_path":    "/var/lib/volta/vaults",
          "permissions":  0700,
          "sync_writes":  true,
      },
  }

  auditConfig := &audit.Config{
      Enabled:  true,
      Type:     audit.FileAuditType,
      LogLevel: "info",
      Options: map[string]interface{}{
          "file_path": "/var/log/volta/audit.log",
          "max_size":  100, // MB
          "max_files": 5,
      },
  }

  auditLogger, err := audit.NewLogger(auditConfig)
  if err != nil {
      log.Fatalf("Failed to create audit logger: %v", err)
  }

  vaultManager := NewVaultManagerWithStoreConfig(
      Options{
          DefaultKeySize: 32,
          MaxSecrets:     10000,
      },
      storeConfig,
      auditLogger,
  )

S3 STORAGE CONFIGURATION:
  storeConfig := persist.StoreConfig{
      Type: StoreTypeS3,
      Config: map[string]interface{}{
          "bucket":            "my-company-vault-storage",
          "region":            "us-west-2",
          "access_key_id":     os.Getenv("AWS_ACCESS_KEY_ID"),
          "secret_access_key": os.Getenv("AWS_SECRET_ACCESS_KEY"),
          "use_path_style":    false,
      },
  }

  auditConfig := &audit.Config{
      Enabled: true,
      Type:    audit.SyslogAuditType,
      Options: map[string]interface{}{
          "facility": "local0",
          "tag":      "volta-vault",
          "network":  "udp",
          "address":  "localhost:514",
      },
  }

  auditLogger, err := audit.NewLogger(auditConfig)
  if err != nil {
      log.Fatalf("Failed to create audit logger: %v", err)
  }

  vaultManager := NewVaultManagerWithStoreConfig(
      Options{
          DefaultKeySize:     32,
          MaxSecrets:        50000,
          RetentionPeriod:   time.Hour * 24 * 90, // 90 days
      },
      storeConfig,
      auditLogger,
  )

CUSTOM STORAGE BACKEND:
  // For storage backends not supported by the built-in factory,
  // use NewVaultManagerWithFactory instead:
  customFactory := func(tenantID string) (persist.Store, error) {
      return myCustomStorage.NewStore(customConfig, tenantID)
  }

  vaultManager := NewVaultManagerWithFactory(baseOptions, customFactory, auditLogger)

SECURITY CONSIDERATIONS: 

CREDENTIAL MANAGEMENT:
Storage backend credentials should be managed securely through environment
variables, credential management services, or secure configuration management
systems. Avoid hardcoding credentials in configuration files or source code.

ACCESS CONTROL:
Ensure storage backend access controls are properly configured to restrict
access to authorized vault manager instances only. Use least-privilege
principles for storage backend permissions and regularly audit access.

ENCRYPTION AT REST:
Configure storage backends with appropriate encryption-at-rest capabilities.
For S3, enable server-side encryption. For filesystem storage, consider
full-disk encryption or filesystem-level encryption for sensitive environments.

PERFORMANCE CONSIDERATIONS: 

STORAGE BACKEND SELECTION:
Choose storage backends based on performance requirements, scalability needs,
and operational constraints. S3 provides better scalability and durability
but may have higher latency. Filesystem storage offers lower latency but
requires careful capacity planning and backup strategies.

CONFIGURATION OPTIMIZATION:
Optimize storage backend configurations for expected workloads. Enable
appropriate caching, connection pooling, and performance tuning options
based on the specific storage backend and usage patterns.

ERROR HANDLING: 

CONFIGURATION VALIDATION:
Invalid storage configurations are detected during tenant initialization
and result in clear error messages indicating the specific configuration
issues. Validate configurations in development environments before
production deployment.

STORAGE BACKEND FAILURES:
Storage backend connectivity issues or failures are handled gracefully
with appropriate error reporting and retry mechanisms where applicable.
Monitor storage backend health and connectivity for operational visibility.

Parameters: 

baseOptions: Base vault manager configuration options
storeConfig: Storage backend configuration specifying type and parameters
auditLogger: Configured audit logger for comprehensive operation logging

Returns: 

*VaultManager: Configured vault manager instance with specified storage backend

func (*VaultManager) CloseAll 

func (tm *VaultManager) CloseAll() error

CloseAll closes all tenant vaults and performs comprehensive resource cleanup.

OVERVIEW: This method performs a controlled shutdown of all active tenant vaults within the VaultManager instance. It implements a best-effort closure strategy that attempts to cleanly shut down every vault while collecting and reporting any errors encountered during the process.

SHUTDOWN SEMANTICS: 

COMPREHENSIVE CLOSURE:
Every active tenant vault is individually closed, ensuring that all
cryptographic resources, secure memory allocations, and system handles
are properly released. This prevents resource leaks and ensures clean
system shutdown even in error scenarios.

BEST-EFFORT STRATEGY:
The method continues attempting to close remaining vaults even if some
closures fail. This ensures maximum resource cleanup while providing
detailed error reporting for any problematic vaults that couldn't be
cleanly shut down.

ATOMIC STATE RESET:
After attempting to close all vaults, the internal vault registry is
completely reset regardless of individual closure outcomes. This ensures
the VaultManager returns to a clean state and prevents access to
potentially corrupted vault instances.

CONCURRENCY SAFETY: The method acquires exclusive access to the VaultManager during the entire shutdown process, preventing concurrent operations from interfering with the cleanup process or accessing vaults during shutdown.

ERROR AGGREGATION: Individual vault closure errors are collected and aggregated into a comprehensive error report that identifies which specific tenants experienced closure issues, enabling targeted troubleshooting and administrator notification.

SECURITY CONSIDERATIONS: - All tenant cryptographic material is securely cleared - Secure memory allocations are properly released - No tenant data persists in memory after successful completion - Partial failures still result in maximum possible resource cleanup

OPERATIONAL IMPACT: - All tenant vaults become inaccessible immediately - In-flight operations may fail with vault closure errors - Service requires reinitialization before tenant access can resume - Audit logs record the mass closure event for compliance tracking

USE CASES: - Application shutdown and graceful service termination - Emergency security procedures requiring immediate vault closure - Administrative maintenance requiring service restart - Resource cleanup during service scaling or redeployment

Returns: 

error: nil if all vaults closed successfully, aggregated error describing
       any closure failures while still performing maximum cleanup

func (*VaultManager) CloseTenant 

func (tm *VaultManager) CloseTenant(tenantID string) error

CloseTenant closes and removes a tenant's vault from the manager.

OVERVIEW: This method performs a controlled shutdown of a specific tenant's vault, ensuring all cryptographic resources are properly cleaned up and removed from the manager's active vault registry. It implements secure resource deallocation with comprehensive error handling and state management.

OPERATIONAL SEMANTICS: 

GRACEFUL SHUTDOWN:
The method performs a graceful shutdown of the tenant's vault, allowing
any in-progress operations to complete before initiating the closure
process. This prevents data corruption or partial operations that could
compromise security or data integrity.

RESOURCE CLEANUP:
All cryptographic materials, secure memory allocations, and file handles
associated with the tenant are properly disposed of according to security
best practices. This includes secure memory wiping and proper disposal
of sensitive resources.

REGISTRY MANAGEMENT:
The tenant is atomically removed from the active vault registry, preventing
future access attempts while ensuring thread-safe state transitions.
This maintains consistency even under concurrent access scenarios.

SECURITY CONSIDERATIONS:

SECURE DISPOSAL: - All cryptographic keys and sensitive data are securely wiped from memory - File handles and temporary resources are properly closed and cleaned - Audit trails are generated for tenant closure operations - No sensitive data remnants are left in system memory or storage

CONCURRENCY SAFETY: - Thread-safe operation with proper locking mechanisms - Atomic state transitions prevent race conditions - Concurrent access to other tenants remains unaffected - Pending operations on the tenant are safely handled

ERROR HANDLING:

FAULT TOLERANCE: The method implements best-effort cleanup semantics where partial failures in vault closure do not prevent registry cleanup. This prevents resource leaks while maintaining system stability even when underlying vault operations encounter errors.

ERROR REPORTING: Detailed error information is provided for vault closure failures, enabling administrators to identify and resolve underlying issues that may affect system performance or security posture.

USE CASES:

TENANT LIFECYCLE MANAGEMENT: - Normal tenant deprovisioning and cleanup operations - Resource optimization by closing inactive tenant vaults - System maintenance and resource management procedures - Emergency tenant isolation for security incidents

OPERATIONAL PROCEDURES: - Scheduled maintenance and resource cleanup operations - Capacity management and resource optimization - Incident response and security containment procedures - System shutdown and restart procedures

IDEMPOTENCY: The operation is idempotent - calling CloseTenant multiple times for the same tenant ID will not result in errors or side effects. Non-existent tenants are handled gracefully without error conditions.

AUDIT IMPLICATIONS: Tenant closure operations are automatically logged to the audit system, providing full traceability of tenant lifecycle events for compliance and security monitoring purposes.

Parameters: 

tenantID: Unique identifier for the tenant vault to close and remove

Returns: 

error: nil on successful closure, error if vault closure fails

Thread Safety: Safe for concurrent use across multiple goroutines

func (*VaultManager) DeleteTenant 

func (tm *VaultManager) DeleteTenant(tenantID string) error

DeleteTenant permanently removes a tenant and its associated vault from the VaultManager.

This method implements a "fail-safe" deletion strategy where the tenant is immediately removed from the active vaults map to prevent zombie states, even if subsequent cleanup operations fail. All operations are comprehensively audited for compliance and monitoring.

Parameters:

  • tenantID: Unique identifier for the tenant to be deleted. Must be a non-empty string.

Returns:

  • error: nil on successful deletion and cleanup
  • error: tenant not found error if tenantID doesn't exist in the vault map
  • error: cleanup error if tenant was removed but resource cleanup failed

Thread Safety: 

This method is thread-safe and uses a mutex lock to ensure atomic operations
during tenant lookup and removal from the vaults map.

Audit Events:

  • DELETE_TENANT_INITIATED: When deletion process begins
  • DELETE_TENANT_NOT_FOUND: When tenant doesn't exist
  • DELETE_TENANT_REMOVED_FROM_MAP: When tenant is removed from active vaults
  • DELETE_TENANT_VAULT_CLEANUP_FAILED: When vault deletion fails
  • DELETE_TENANT_CLOSE_FAILED: When vault close operation fails
  • DELETE_TENANT_COMPLETED: When deletion completes successfully
  • DELETE_TENANT_PARTIAL_FAILURE: When deletion completes with cleanup errors

func (*VaultManager) GetAuditSummary 

func (tm *VaultManager) GetAuditSummary(tenantID string, since *time.Time) (AuditSummary, error)

GetAuditSummary generates comprehensive audit activity summaries for tenant monitoring and analysis.

OVERVIEW: This function provides high-level statistical analysis of tenant audit activity over a specified time period. It aggregates detailed audit events into actionable metrics for security monitoring, compliance reporting, operational dashboards, and tenant activity analysis. The summary includes categorized event counts, success/failure ratios, and activity timestamps for comprehensive tenant oversight.

ANALYTICAL CAPABILITIES: 

EVENT CATEGORIZATION:
The function analyzes all audit events and categorizes them into distinct operational
types including passphrase accesses, secret operations, key management activities,
and general vault operations. This categorization enables targeted analysis of
different security-sensitive activities within the tenant environment.

SUCCESS/FAILURE ANALYSIS:
All events are classified by success or failure status, providing insights into
operational health, potential security issues, and system reliability. High
failure rates may indicate configuration problems, security attacks, or user
training needs.

TEMPORAL ANALYSIS:
The summary includes the timestamp of the most recent activity, enabling
administrators to understand tenant engagement patterns, identify inactive
tenants, and monitor for unexpected activity periods.

SECURITY MONITORING: 

THREAT DETECTION:
Unusual patterns in the audit summary can indicate security threats such as
brute force attacks (high failure rates), unauthorized access attempts, or
abnormal usage patterns that warrant further investigation.

COMPLIANCE TRACKING:
The categorized metrics support compliance requirements by providing clear
visibility into sensitive operations like passphrase accesses and secret
retrievals, enabling audit trail analysis for regulatory compliance.

ACCESS PATTERN ANALYSIS:
The summary enables identification of access patterns that may indicate
compromised accounts, insider threats, or policy violations requiring
administrative attention or automated response.

OPERATIONAL INSIGHTS: 

TENANT ACTIVITY MONITORING:
Administrators can use audit summaries to monitor tenant engagement,
identify underutilized resources, and understand usage patterns for
capacity planning and resource optimization.

SYSTEM HEALTH INDICATORS:
Success/failure ratios and activity patterns provide indicators of system
health, configuration issues, and potential problems requiring proactive
maintenance or user support.

PERFORMANCE BASELINE:
Regular audit summaries establish baseline activity patterns that can be
used for anomaly detection and performance comparison over time.

SUMMARY METRICS: 

TOTAL EVENTS:
Complete count of all audit events within the specified time range,
providing overall activity volume metrics for capacity planning and
comparative analysis across tenants or time periods.

SUCCESS/FAILURE BREAKDOWN:
Categorized counts of successful and failed operations, enabling quick
assessment of operational health and identification of potential issues
requiring investigation or remediation.

ACTIVITY-SPECIFIC COUNTS:
Specialized metrics for security-sensitive operations including passphrase
accesses, secret retrievals, and key management operations, providing
focused visibility into the most critical security activities.

TEMPORAL MARKERS:
Last activity timestamp enables identification of tenant engagement
patterns and detection of unusual activity timing that may indicate
security concerns or operational issues.

PERFORMANCE CHARACTERISTICS: 

SCALABLE ANALYSIS:
The function uses a high limit (10,000 events) to capture comprehensive
activity data while maintaining reasonable performance. For tenants with
extremely high activity, consider using shorter time windows or implementing
sampling strategies for very large datasets.

MEMORY EFFICIENCY:
Event analysis is performed in a single pass through the data, minimizing
memory usage and processing time. The function aggregates metrics without
storing detailed event data, making it suitable for regular monitoring.

CONCURRENT SAFETY:
The function operates under read-lock protection, ensuring thread-safe
access to tenant resources while allowing concurrent summary generation
for multiple tenants or time periods.

USAGE PATTERNS AND BEST PRACTICES: 

REGULAR MONITORING:
Schedule regular audit summary generation (daily, weekly, monthly) to
establish baseline patterns and enable trend analysis over time.
Consistent monitoring intervals improve anomaly detection capabilities.

ALERT THRESHOLDS:
Establish thresholds for various metrics (failure rates, activity volumes,
time gaps) to trigger automated alerts for unusual patterns requiring
investigation or immediate attention.

COMPARATIVE ANALYSIS:
Compare audit summaries across tenants, time periods, or baseline patterns
to identify outliers, trends, and patterns that may indicate security
concerns or operational optimization opportunities.

DRILL-DOWN CAPABILITIES:
Use audit summaries as starting points for detailed analysis. When summaries
indicate unusual patterns, use detailed audit queries to investigate
specific events and root causes.

INTEGRATION SCENARIOS: 

DASHBOARD INTEGRATION:
Audit summaries provide ideal metrics for operational dashboards, executive
reports, and real-time monitoring displays. The structured format enables
easy integration with visualization tools and monitoring systems.

AUTOMATED MONITORING:
Integrate audit summary generation into automated monitoring workflows,
creating scheduled reports, threshold-based alerts, and trend analysis
systems for proactive security and operational management.

COMPLIANCE REPORTING:
Use audit summaries as components of larger compliance reports, providing
high-level metrics that support regulatory requirements while maintaining
detailed audit trails for deeper investigation when needed.

ERROR HANDLING: 

TENANT VALIDATION:
The function validates tenant existence and access permissions before
attempting audit queries. Invalid tenants or access violations are
reported as errors with appropriate diagnostic information.

QUERY RESILIENCE:
Audit query failures are propagated as errors, but the function provides
partial results when possible, ensuring maximum utility even during
degraded conditions or partial system failures.

USAGE EXAMPLE: 

// Generate daily audit summary for tenant monitoring
dailyStart := time.Now().AddDate(0, 0, -1)
summary, err := vaultManager.GetAuditSummary("tenant-123", &dailyStart)
if err != nil {
    log.Printf("Failed to generate audit summary: %v", err)
    return
}

// Analyze security metrics
failureRate := float64(summary.FailedEvents) / float64(summary.TotalEvents)
if failureRate > 0.1 { // Alert if >10% failure rate
    log.Printf("HIGH FAILURE RATE for tenant %s: %.2f%%",
               summary.TenantID, failureRate*100)
}

// Check for suspicious activity patterns
if summary.PassphraseAccesses > 100 {
    log.Printf("High passphrase activity for tenant %s: %d accesses",
               summary.TenantID, summary.PassphraseAccesses)
}

// Monitor tenant engagement
inactiveHours := time.Since(summary.LastActivity).Hours()
if inactiveHours > 168 { // Alert if inactive for >1 week
    log.Printf("Tenant %s inactive for %.1f hours",
               summary.TenantID, inactiveHours)
}

// Generate formatted report
fmt.Printf("Audit Summary for %s:\n", summary.TenantID)
fmt.Printf("  Total Events: %d\n", summary.TotalEvents)
fmt.Printf("  Success Rate: %.2f%%\n",
           float64(summary.SuccessfulEvents)/float64(summary.TotalEvents)*100)
fmt.Printf("  Secret Accesses: %d\n", summary.SecretAccesses)
fmt.Printf("  Key Operations: %d\n", summary.KeyOperations)
fmt.Printf("  Last Activity: %s\n", summary.LastActivity.Format(time.RFC3339))

Parameters: 

tenantID: Unique identifier for the tenant to analyze
since: Starting timestamp for summary analysis (nil for all available data)

Returns: 

AuditSummary: Comprehensive activity summary with categorized metrics
error: nil on success, error on tenant access failure or query errors

func (*VaultManager) GetVault 

func (tm *VaultManager) GetVault(tenantID string) (VaultService, error)

GetVault returns a vault for the given tenant, creating it if needed.

OVERVIEW: This method provides the primary entry point for accessing tenant-specific vault services within the multi-tenant architecture. It implements a lazy initialization pattern that creates vault instances on-demand while ensuring thread-safe access to the tenant vault registry.

LAZY INITIALIZATION SEMANTICS: 

ON-DEMAND CREATION:
Vaults are created only when first accessed, optimizing memory usage and
startup performance in environments with large numbers of tenants. This
approach scales efficiently from single-tenant to enterprise deployments
with thousands of tenants.

SINGLETON GUARANTEE:
Once created, each tenant vault is cached and reused for all subsequent
requests from that tenant. This ensures consistent state management and
optimal resource utilization while maintaining strict tenant isolation.

THREAD-SAFE REGISTRY:
The tenant vault registry is protected by a mutex to ensure thread-safe
concurrent access. Multiple goroutines can safely request vaults for the
same or different tenants without race conditions or duplicate creation.

TENANT ISOLATION ARCHITECTURE: 

DEDICATED STORAGE:
Each tenant receives a completely isolated storage backend created through
the configured storeFactory. This ensures cryptographic isolation where
tenant data cannot accidentally leak across tenant boundaries.

INDEPENDENT LIFECYCLE:
Each tenant vault maintains independent lifecycle management, allowing
individual tenants to be created, managed, and destroyed without affecting
other tenants in the system.

SECURITY BOUNDARIES:
Tenant isolation provides strong security guarantees where compromise of
one tenant cannot affect the security or availability of other tenants.
Each vault operates with tenant-specific encryption keys and access controls.

PERFORMANCE CHARACTERISTICS: 

MEMORY EFFICIENCY:
Lazy initialization prevents memory overhead from unused tenant vaults.
In environments with many registered but inactive tenants, this approach
provides significant memory savings.

ACCESS LATENCY:
First-time vault creation incurs additional latency for store and vault
initialization. Subsequent accesses are optimized with O(1) lookup from
the in-memory registry.

SCALABILITY:
The registry scales linearly with active tenant count. Cache eviction
strategies may be implemented for environments with extremely high tenant
counts.

ERROR HANDLING PATTERNS: 

STORE CREATION FAILURES:
If tenant-specific store creation fails, the error is wrapped with tenant
context and propagated. No partial state is retained, ensuring clean
failure semantics.

VAULT INITIALIZATION FAILURES:
Vault creation failures result in complete cleanup of any partially
initialized resources. The tenant registry remains consistent and
subsequent requests will retry initialization.

ATOMIC OPERATIONS:
All registry modifications are atomic - either a vault is successfully
created and registered, or no changes are made to the system state.

OPERATIONAL CONSIDERATIONS: 

MONITORING INTEGRATION:
Vault creation events should be monitored for capacity planning and
security analysis. Sudden spikes in new tenant vault creation may indicate
security issues or legitimate business growth.

AUDIT INTEGRATION:
All vault access requests are implicitly audited through the underlying
vault operations. Consider explicit audit logging for vault creation
events for administrative tracking.

RESOURCE MANAGEMENT:
Long-running systems may benefit from vault eviction policies for inactive
tenants to manage memory usage. Such policies must carefully balance
performance and resource utilization.

SECURITY CONSIDERATIONS: 

TENANT VALIDATION:
The tenantID parameter should be validated and sanitized before use in
storage operations. Malicious tenant IDs could potentially cause security
issues in the underlying storage implementation.

ACCESS CONTROL:
This method should be called only after proper tenant authorization has
been verified by the calling context. The VaultManager itself does not
enforce tenant access policies.

INFORMATION DISCLOSURE:
Error messages are carefully crafted to avoid leaking sensitive information
about system internals while providing sufficient detail for debugging.

USAGE PATTERNS: 

REQUEST LIFECYCLE:
Typically called at the beginning of request processing to obtain the
appropriate vault instance for the authenticated tenant context.

SERVICE INTEGRATION:
Used by higher-level services to abstract away multi-tenant complexity
and present a unified vault interface to application logic.

TESTING AND DEVELOPMENT:
Supports easy testing with mock store factories and simplified development
patterns for single-tenant scenarios.

Parameters: 

tenantID: Unique identifier for the tenant requesting vault access.
          Must be non-empty and conform to tenant ID validation rules.

Returns: 

VaultService: Thread-safe vault instance for the specified tenant.
              Instance is cached and reused for subsequent calls.
error:        nil on success, wrapped error with tenant context on failure.
              Failures leave no partial state in the system.

Thread Safety: 

This method is fully thread-safe and can be called concurrently from
multiple goroutines. Internal locking ensures consistent state management.

func (*VaultManager) ListTenants 

func (tm *VaultManager) ListTenants() ([]string, error)

ListTenants returns all available tenants from the storage backend.

OVERVIEW: This method provides tenant discovery capabilities by querying the underlying storage backend to enumerate all configured tenants. It serves as the primary mechanism for tenant discovery in multi-tenant vault environments, supporting administrative operations, monitoring, and tenant lifecycle management.

DISCOVERY MECHANISM: 

STORAGE-BACKEND ENUMERATION:
The method creates a temporary storage connection specifically for tenant
discovery, bypassing tenant-specific initialization to access the global
tenant registry. This approach ensures accurate tenant enumeration even
when individual tenant vaults may be in various states (locked, unlocked,
corrupted, or undergoing maintenance).

LIGHTWEIGHT OPERATION:
Discovery operations are designed to be lightweight and non-intrusive,
requiring minimal resources and avoiding any tenant-specific cryptographic
operations. This ensures tenant enumeration can succeed even under
resource-constrained conditions or partial system failures.

CONSISTENT VIEW:
The method provides a consistent point-in-time snapshot of available
tenants, though the actual tenant states may change between enumeration
and subsequent operations. Callers should handle tenant availability
changes gracefully in subsequent operations.

SECURITY CONSIDERATIONS: 

AUTHORIZATION REQUIREMENTS:
Tenant enumeration is a privileged operation that reveals organizational
structure and tenant deployment patterns. Access should be restricted to
administrative users and service accounts with legitimate operational
requirements for tenant discovery.

INFORMATION DISCLOSURE:
Tenant IDs may contain sensitive organizational information or reveal
business relationships, customer structures, or deployment patterns.
Results should be handled with appropriate confidentiality controls
and never logged in plaintext or transmitted over unsecured channels.

AUDIT IMPLICATIONS:
Tenant enumeration operations are fully audited, including the identity
of the caller, timing, and the complete list of returned tenants. This
supports compliance requirements and security monitoring for unauthorized
reconnaissance activities.

OPERATIONAL USE CASES: 

ADMINISTRATIVE OPERATIONS:
- Bulk operations across multiple tenants (key rotation, updates)
- System maintenance and health checking procedures
- Tenant lifecycle management and provisioning workflows
- Monitoring and alerting system configuration

MONITORING AND OBSERVABILITY:
- Health dashboard population and status reporting
- Metrics collection and performance monitoring setup
- Capacity planning and resource utilization analysis
- Service discovery for tenant-specific monitoring endpoints

COMPLIANCE AND REPORTING:
- Compliance audit preparation and tenant inventory
- Security posture assessment across all tenants
- Tenant-specific policy enforcement and validation
- Regulatory reporting and documentation requirements

ERROR HANDLING: 

STORAGE BACKEND FAILURES:
Storage connectivity issues, authentication failures, or backend
unavailability result in immediate error return with no tenant
information disclosed. Callers should implement appropriate retry
logic with exponential backoff for transient failures.

PARTIAL FAILURES:
If the storage backend is partially available or some tenant
metadata is corrupted, the method returns successfully enumerated
tenants rather than failing completely. This degraded-mode operation
supports continued service availability during partial outages.

CONCURRENT MODIFICATIONS:
Since tenant creation and deletion may occur concurrently with
enumeration, the returned list represents a point-in-time snapshot
that may not reflect real-time tenant availability. Callers must
handle tenant availability changes in subsequent operations.

PERFORMANCE CHARACTERISTICS: 

SCALABILITY PROFILE:
The operation scales linearly with the number of configured tenants
and logarithmically with storage backend size. For deployments with
thousands of tenants, consider implementing caching strategies or
pagination for large-scale tenant enumeration operations.

RESOURCE UTILIZATION:
Tenant discovery requires minimal CPU and memory resources but may
consume significant I/O bandwidth for large tenant deployments.
The temporary storage connection is automatically cleaned up to
prevent resource leaks.

CACHING CONSIDERATIONS:
Results may be cached for performance optimization, but cache
invalidation must be carefully managed to ensure accuracy during
tenant provisioning and deprovisioning operations. Consider
implementing cache TTL policies appropriate for tenant change
frequency.

IMPLEMENTATION DETAILS: 

TEMPORARY STORE PATTERN:
The method creates a temporary store connection with an empty tenant
ID, which signals the storage backend to operate in discovery mode
rather than tenant-specific mode. This architectural pattern ensures
clean separation between tenant-specific operations and administrative
discovery operations.

RESOURCE CLEANUP:
The temporary store connection is automatically closed via defer
statement, ensuring proper resource cleanup even if the underlying
ListTenants operation fails or panics. This prevents resource leaks
in long-running services.

FACTORY ABSTRACTION:
By using the storeFactory with an empty tenant ID, the method
leverages the same factory pattern used for tenant-specific operations
while accessing global tenant enumeration capabilities. This ensures
consistent configuration and connection handling across all storage
operations.

Returns: 

[]string: Slice of tenant IDs for all available tenants
error: nil on success, error on storage failures or authorization issues

Example Usage: 

tenants, err := vaultManager.ListTenants()
if err != nil {
    log.Error("Failed to enumerate tenants", "error", err)
    return err
}
log.Info("Discovered tenants", "count", len(tenants), "tenants", tenants)

func (*VaultManager) QueryAllTenantsAuditLogs 

func (tm *VaultManager) QueryAllTenantsAuditLogs(options audit.QueryOptions) (map[string]audit.QueryResult, error)

QueryAllTenantsAuditLogs performs cross-tenant audit log queries for administrative oversight.

OVERVIEW: This administrative function enables comprehensive audit log queries across all active tenants within the vault manager's scope. It provides organization-wide visibility into security events, operational activities, and compliance-related data while maintaining strict tenant isolation and access controls.

ADMINISTRATIVE SCOPE: 

CROSS-TENANT VISIBILITY:
This function provides administrative users with the ability to query audit logs
across tenant boundaries, enabling organization-wide security monitoring,
compliance reporting, and incident response capabilities. Results maintain
clear tenant attribution for proper analysis and reporting.

FAULT TOLERANCE:
Individual tenant query failures do not abort the entire operation. Failed
queries are logged as warnings and return empty result sets, ensuring
maximum data availability even when some tenants experience issues.

CONCURRENT SAFETY:
The function operates under read-lock protection to ensure thread-safe
access to the tenant registry while allowing concurrent read operations
from other administrative functions.

OPERATIONAL BEHAVIOR: 

TENANT DISCOVERY:
The function automatically discovers all active tenants within the vault
manager and attempts to query each tenant's audit subsystem. Tenants
without configured audit logging are handled gracefully with empty results.

QUERY CONSISTENCY:
The same query options are applied consistently across all tenants,
with automatic tenant ID injection to ensure proper scoping and
result attribution for each tenant's audit subsystem.

ERROR ISOLATION:
Query failures for individual tenants are isolated and logged, but do
not prevent successful queries from other tenants. This ensures maximum
data availability during partial system failures or tenant-specific issues.

SECURITY CONSIDERATIONS: 

ADMINISTRATIVE PRIVILEGE:
This function requires administrative privileges due to its cross-tenant
nature. Access should be restricted to authorized security personnel,
compliance officers, and system administrators with legitimate oversight
responsibilities.

AUDIT TRAIL:
All cross-tenant audit queries are themselves audited, creating a complete
trail of who accessed what audit data across tenant boundaries. This
ensures accountability for administrative access to sensitive audit information.

DATA MINIMIZATION:
While this function provides broad access, it should be used judiciously
and with appropriate filtering to minimize unnecessary data exposure.
Prefer tenant-specific queries when investigating tenant-specific issues.

USE CASES: 

SECURITY MONITORING:
Organization-wide security event correlation, threat detection across
tenant boundaries, and identification of multi-tenant attack patterns
or security anomalies requiring coordinated response.

COMPLIANCE REPORTING:
Regulatory compliance often requires organization-wide audit reporting
that spans all tenant boundaries. This function provides the necessary
data aggregation capabilities for comprehensive compliance reporting.

INCIDENT RESPONSE:
Security incidents may affect multiple tenants or require correlation
of events across tenant boundaries. This function supports comprehensive
incident response investigations and forensic analysis.

OPERATIONAL ANALYSIS:
System-wide operational analysis, performance monitoring, and capacity
planning activities that require visibility into usage patterns and
operational metrics across all tenants.

PERFORMANCE CONSIDERATIONS: 

RESOURCE INTENSIVE:
Cross-tenant queries can be resource-intensive, especially with large
numbers of tenants or broad query criteria. Consider using appropriate
filtering and pagination to manage resource consumption.

CONCURRENT IMPACT:
Large cross-tenant queries may impact system performance. Consider
scheduling intensive queries during off-peak hours or using background
processing for comprehensive analytical queries.

ERROR HANDLING: 

GRACEFUL DEGRADATION:
The function implements graceful degradation where individual tenant
query failures are logged but do not abort the entire operation. This
ensures maximum data availability even during partial system failures.

DIAGNOSTIC INFORMATION:
Query failures are logged with diagnostic information to aid in
troubleshooting and system maintenance. Administrators should monitor
these logs for systematic issues affecting audit query capabilities.

Parameters: 

options: Query options applied consistently across all tenants

Returns: 

map[string]audit.QueryResult: Audit results organized by tenant ID
error: Always nil - individual tenant failures are handled gracefully

func (*VaultManager) QueryAuditLogs 

func (tm *VaultManager) QueryAuditLogs(options audit.QueryOptions) (*audit.QueryResult, error)

QueryAuditLogs performs comprehensive audit log queries across tenant boundaries.

OVERVIEW: This method provides the primary interface for querying audit logs within the Volta vault management system. It supports both single-tenant and multi-tenant queries based on the provided options, enabling flexible audit analysis for security monitoring, compliance reporting, and operational analysis.

QUERY SCOPE DETERMINATION: 

SINGLE-TENANT MODE:
When options.TenantID is specified, the query is limited to that specific
tenant's audit logs. This provides optimized performance for tenant-focused
analysis and ensures efficient resource utilization for targeted queries.

MULTI-TENANT MODE:
When options.TenantID is empty, the query spans all accessible tenants
within the vault manager's scope. This enables organization-wide security
analysis and comprehensive compliance reporting across tenant boundaries.

TENANT ACCESS CONTROL:
The method respects tenant access permissions and silently skips tenants
that are inaccessible due to authorization restrictions, ensuring that
results only include data the caller is authorized to access.

FILTERING AND PROCESSING: 

PROGRESSIVE FILTERING:
Events are collected from all applicable tenants first, then filtered
based on the query criteria. This approach ensures consistent filtering
behavior across tenant boundaries and maintains query result integrity.

RESULT LIMITING:
When options.Limit is specified, the method applies the limit after
filtering to ensure the most relevant results are returned. The limit
applies to the final result set, not per-tenant results.

ERROR TOLERANCE:
Individual tenant query failures do not abort the entire operation.
The method continues processing remaining tenants and returns partial
results, enabling resilient operation in multi-tenant environments.

PERFORMANCE CHARACTERISTICS: 

SCALABILITY CONSIDERATIONS:
Multi-tenant queries can be resource-intensive for large tenant counts.
Consider using specific tenant queries or additional filtering criteria
for performance-sensitive applications.

MEMORY MANAGEMENT:
Large result sets are aggregated in memory before filtering. Monitor
memory usage for queries spanning many tenants or long time periods.

CONCURRENT ACCESS:
The method safely handles concurrent access to tenant vaults but does
not implement query-level locking. Results represent a point-in-time
snapshot across all queried tenants.

AUDIT RESULT STRUCTURE: 

COMPREHENSIVE METRICS:
Results include both the filtered events and comprehensive metrics
about the query execution, including total events found and filtering
effectiveness for query optimization and analysis.

CROSS-TENANT CORRELATION:
Events from multiple tenants retain their tenant context, enabling
cross-tenant correlation analysis while maintaining tenant isolation
boundaries for security and compliance.

ERROR HANDLING: 

GRACEFUL DEGRADATION:
Tenant enumeration failures return errors immediately, while individual
tenant access failures are handled gracefully with continued processing
of accessible tenants.

PARTIAL RESULTS:
When some tenants are inaccessible, the method returns partial results
from accessible tenants rather than failing completely, maximizing
operational utility in degraded conditions.

SECURITY CONSIDERATIONS: 

TENANT ISOLATION:
Despite cross-tenant querying capabilities, tenant data isolation is
maintained throughout the query process. Inaccessible tenants are
silently skipped without exposure of their existence or configuration.

AUDIT TRAIL:
The query operation itself is audited, providing full traceability of
audit log access for security monitoring and compliance requirements.

Parameters: 

options: Comprehensive query options including tenant scope, filtering
         criteria, time ranges, result limits, and sorting preferences

Returns: 

*audit.QueryResult: Complete query results with events and metadata
error: nil on success, error on critical failures like tenant enumeration

func (*VaultManager) QueryFailedOperations 

func (tm *VaultManager) QueryFailedOperations(tenantID string, since *time.Time) ([]audit.Event, error)

QueryFailedOperations provides specialized queries for failed vault operations within a tenant.

OVERVIEW: This convenience method is specifically designed for security monitoring and operational troubleshooting by focusing exclusively on failed vault operations. It provides an optimized interface for identifying security incidents, operational issues, and system anomalies that require immediate attention or investigation.

OPERATIONAL FOCUS: 

FAILURE-SPECIFIC FILTERING:
The method automatically configures audit queries to return only failed operations,
eliminating the need for manual filtering of successful operations. This targeted
approach significantly reduces result set size and improves query performance for
security and operational analysis.

TEMPORAL SCOPING:
The optional 'since' parameter enables time-bounded queries, allowing users to
focus on recent failures or specific time periods of interest. When nil, queries
return all historical failed operations subject to the configured result limit.

TENANT ISOLATION:
Failed operations are queried within the context of a specific tenant, ensuring
proper data isolation and access control while enabling focused troubleshooting
and security analysis for individual tenants.

RESULT CHARACTERISTICS: 

COMPREHENSIVE FAILURE DATA:
Results include complete audit event information for failed operations, including
operation type, failure reason, timestamps, user context, and any associated
error messages or diagnostic information.

PERFORMANCE OPTIMIZED:
The method includes a reasonable default limit (1000 events) to prevent
performance issues while providing sufficient data for most analysis scenarios.
This limit balances comprehensiveness with system performance.

CHRONOLOGICAL ORDERING:
Failed operations are typically returned in chronological order, facilitating
timeline analysis and correlation of related failure events for incident
investigation and root cause analysis.

SECURITY MONITORING APPLICATIONS: 

THREAT DETECTION:
Failed operations often indicate security attacks, unauthorized access attempts,
or suspicious activities. Regular monitoring of failed operations helps identify
potential security threats before they escalate to successful breaches.

ANOMALY IDENTIFICATION:
Patterns in failed operations can reveal system anomalies, configuration issues,
or unusual usage patterns that may indicate security concerns or operational
problems requiring investigation.

INCIDENT RESPONSE:
During security incidents, failed operations provide crucial forensic evidence
for understanding attack methods, timeline reconstruction, and impact assessment
for comprehensive incident response.

OPERATIONAL TROUBLESHOOTING: 

SYSTEM HEALTH MONITORING:
Regular queries for failed operations help identify system health issues,
performance problems, or configuration errors that impact vault reliability
and user experience.

USER SUPPORT:
Failed operations help support teams understand user-reported issues and
provide targeted assistance for resolving authentication, authorization,
or operational problems.

CAPACITY PLANNING:
Analysis of failure patterns helps identify resource constraints, rate limiting
issues, or scaling requirements for maintaining optimal vault performance
under varying load conditions.

USAGE PATTERNS: 

REGULAR MONITORING:
Implement periodic queries (e.g., hourly or daily) to maintain awareness of
failure rates and patterns for proactive system management and security
monitoring.

INCIDENT INVESTIGATION:
Use targeted time-range queries during incident response to gather forensic
evidence and understand the scope and timeline of security or operational
incidents.

TREND ANALYSIS:
Compare failure rates and patterns across different time periods to identify
trends, seasonal patterns, or gradual degradation in system performance
or security posture.

PERFORMANCE CONSIDERATIONS: 

RESULT LIMITING:
The default 1000-event limit prevents excessive memory usage and response times
for tenants with high failure rates. Consider implementing pagination for
comprehensive historical analysis of high-volume failure scenarios.

QUERY FREQUENCY:
Frequent queries for failed operations can impact system performance. Implement
appropriate caching, rate limiting, or background processing for high-frequency
monitoring scenarios.

INDEX OPTIMIZATION:
Ensure audit storage systems have appropriate indexes on tenant ID, timestamp,
and success/failure status for optimal query performance.

ERROR HANDLING: 

TENANT VALIDATION:
The method validates tenant existence and access permissions before executing
queries, returning appropriate errors for invalid or inaccessible tenants.

AUDIT SYSTEM AVAILABILITY:
Failures in the underlying audit system are propagated to callers with
descriptive error messages to enable appropriate error handling and retry logic.

USAGE EXAMPLE: 

```go
// Monitor recent failures for security analysis
since := time.Now().Add(-24 * time.Hour) // Last 24 hours
failures, err := vaultManager.QueryFailedOperations("tenant-123", &since)
if err != nil {
    log.Printf("Failed to query failed operations: %v", err)
    return
}

// Analyze failure patterns
for _, event := range failures {
    log.Printf("Failed operation: %s at %s - %s",
        event.Operation, event.Timestamp.Format(time.RFC3339), event.Error)

    // Check for security-relevant failures
    if isSecurityRelevant(event) {
        alertSecurityTeam(event)
    }
}

// Generate failure rate metrics
if len(failures) > 100 {
    log.Printf("WARNING: High failure rate detected for tenant %s: %d failures in 24h",
        "tenant-123", len(failures))
}
```

INTEGRATION PATTERNS: 

MONITORING SYSTEMS:
Integrate with monitoring and alerting systems to automatically detect and
respond to elevated failure rates or specific failure patterns that indicate
security or operational issues.

SECURITY TOOLS:
Feed failed operation data to SIEM systems, security analytics platforms,
or threat detection systems for comprehensive security monitoring and
correlation with other security events.

DASHBOARD INTEGRATION:
Use failed operation data in operational dashboards to provide real-time
visibility into system health and security status for operations and
security teams.

Parameters: 

tenantID: Target tenant identifier for failure query scope
since: Optional time boundary for temporal filtering (nil = all history)

Returns: 

[]audit.Event: Collection of failed operation audit events
error: nil on success, error on tenant validation or audit system failures

func (*VaultManager) QueryKeyOperations 

func (tm *VaultManager) QueryKeyOperations(tenantID string, keyID string, since *time.Time) ([]audit.Event, error)

QueryKeyOperations provides specialized audit querying for key-specific operations and activities.

OVERVIEW: This convenience method offers a streamlined interface for querying audit logs related to specific cryptographic keys within a tenant's vault. It abstracts the complexity of constructing detailed audit queries and provides optimized access to key lifecycle events, operations, and security-related activities for forensic analysis, compliance reporting, and operational monitoring.

KEY-CENTRIC ANALYSIS: 

COMPREHENSIVE KEY TRACKING:
The method captures all audit events associated with a specific key throughout its
entire lifecycle, including key generation, rotation, usage, access attempts,
configuration changes, and deletion events. This provides complete visibility
into key operations for security analysis and compliance requirements.

OPERATION TYPE COVERAGE:
Results include diverse key-related operations such as:
- Key creation and initialization events
- Encryption/decryption operations using the key
- Key rotation and version management activities
- Access control modifications and permission changes
- Key backup, export, and import operations
- Key deletion and destruction events
- Failed access attempts and security violations

SECURITY EVENT CORRELATION:
The method captures both successful operations and security events, enabling
comprehensive analysis of key usage patterns, access violations, and potential
security incidents involving specific cryptographic keys.

QUERY OPTIMIZATION: 

PRE-CONFIGURED FILTERING:
The method applies intelligent default filtering optimized for key-centric analysis,
including a reasonable result limit (1000 events) to balance comprehensive coverage
with performance considerations for interactive use cases.

TEMPORAL SCOPING:
When a 'since' timestamp is provided, the query focuses on recent key activities,
enabling efficient analysis of current key usage patterns or investigation of
recent security events without processing extensive historical data.

TENANT ISOLATION:
All queries operate within strict tenant boundaries, ensuring that key operation
analysis respects multi-tenant security boundaries while providing comprehensive
visibility within the authorized tenant scope.

RESULT CHARACTERISTICS: 

EVENT DETAIL RICHNESS:
Each returned audit event contains comprehensive details including:
- Precise timestamps for temporal analysis and correlation
- Operation success/failure status for reliability analysis
- User and session context for access pattern analysis
- Source information (IP addresses, hostnames) for security analysis
- Command details and operation duration for performance analysis
- Custom metadata for application-specific analysis requirements

CHRONOLOGICAL ORDERING:
Results are typically ordered chronologically, enabling timeline analysis
of key operations and identification of operation sequences that may
indicate security issues or operational problems.

OPERATIONAL APPLICATIONS: 

SECURITY ANALYSIS:
Investigate suspicious key usage patterns, unauthorized access attempts,
or security violations involving specific cryptographic keys. The method
provides the detailed audit trail necessary for forensic investigation
and security incident response.

COMPLIANCE REPORTING:
Generate detailed reports on key usage and access patterns required by
regulatory frameworks such as PCI DSS, HIPAA, SOX, or industry-specific
compliance requirements that mandate cryptographic key monitoring.

OPERATIONAL MONITORING:
Monitor key performance characteristics, usage patterns, and operational
health for capacity planning, performance optimization, and proactive
identification of operational issues affecting key management operations.

FORENSIC INVESTIGATION:
Support detailed forensic analysis of security incidents involving
specific keys, including timeline reconstruction, impact assessment,
and evidence collection for security incident response procedures.

PERFORMANCE CONSIDERATIONS: 

RESULT SET MANAGEMENT:
The default limit of 1000 events balances comprehensive analysis with
performance considerations. For keys with extensive operation history,
consider using multiple queries with appropriate time ranges to manage
result set sizes and response times.

QUERY EFFICIENCY:
Key-specific queries are typically well-optimized by underlying audit
systems due to key ID indexing. However, very broad time ranges may
still require significant processing time for highly active keys.

USAGE EXAMPLES: 

RECENT KEY ACTIVITY ANALYSIS:
// Analyze all operations on a specific key in the last 24 hours
since := time.Now().Add(-24 * time.Hour)
events, err := vaultManager.QueryKeyOperations("tenant-123", "key-456", &since)
if err != nil {
    return fmt.Errorf("failed to query key operations: %w", err)
}

// Analyze patterns and identify anomalies
for _, event := range events {
    if !event.Success {
        log.Printf("Failed key operation: %s by user %s from %s",
            event.Action, event.UserID, event.Source)
    }
}

COMPLETE KEY LIFECYCLE ANALYSIS:
// Retrieve complete history of key operations (no time limit)
events, err := vaultManager.QueryKeyOperations("tenant-123", "key-456", nil)
if err != nil {
    return fmt.Errorf("failed to query key lifecycle: %w", err)
}

// Generate comprehensive lifecycle report
report := generateKeyLifecycleReport(events)

SECURITY INCIDENT INVESTIGATION:
// Investigate specific key after security alert
alertTime := time.Unix(securityAlert.Timestamp, 0).Add(-1 * time.Hour)
events, err := vaultManager.QueryKeyOperations(
    securityAlert.TenantID,
    securityAlert.KeyID,
    &alertTime,
)
if err != nil {
    return fmt.Errorf("failed to investigate key security incident: %w", err)
}

// Analyze for indicators of compromise
indicators := analyzeSecurityIndicators(events, securityAlert)

COMPLIANCE AUDIT PREPARATION:
// Prepare audit evidence for specific key compliance review
auditPeriodStart := time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)
events, err := vaultManager.QueryKeyOperations("tenant-123", "key-456", &auditPeriodStart)
if err != nil {
    return fmt.Errorf("failed to prepare compliance audit: %w", err)
}

// Generate compliance report with required details
complianceReport := generateComplianceReport(events, auditPeriodStart)

ERROR HANDLING: 

TENANT VALIDATION:
Returns specific errors for non-existent tenants, enabling calling applications
to distinguish between authorization issues, configuration problems, and
legitimate query failures for appropriate error handling and user feedback.

AUDIT SYSTEM AVAILABILITY:
Gracefully handles cases where audit logging is not configured for the tenant,
returning empty results rather than errors to support optional audit logging
deployment scenarios.

QUERY EXECUTION FAILURES:
Provides detailed error context for query failures, including tenant information
and underlying error details to support troubleshooting and system monitoring.

SECURITY CONSIDERATIONS: 

ACCESS CONTROL ENFORCEMENT:
The method respects all tenant-level access controls and audit system permissions.
Callers must have appropriate authorization to access audit logs for the specified
tenant and key to prevent unauthorized access to sensitive audit information.

AUDIT TRAIL INTEGRITY:
The query process itself is audited, maintaining complete traceability of who
accessed key operation audit logs and when, supporting security monitoring
and compliance requirements for audit log access.

DATA SENSITIVITY:
Audit events may contain sensitive operational details. Ensure appropriate
handling of query results according to organizational security policies
and regulatory requirements for audit data protection.

Parameters: 

tenantID: Unique identifier for the tenant containing the target key
keyID: Specific key identifier to analyze (must exist within the tenant)
since: Optional time boundary for query scope (nil for complete history)

Returns: 

[]audit.Event: Chronologically ordered key operation events with full details
error: nil on success, specific error on tenant/query failures

func (*VaultManager) QueryPassphraseAccessLogs 

func (tm *VaultManager) QueryPassphraseAccessLogs(tenantID string, since *time.Time) ([]audit.Event, error)

QueryPassphraseAccessLogs provides specialized querying for passphrase-related security events.

OVERVIEW: This convenience method offers a streamlined interface for querying passphrase access events within a specific tenant. It abstracts the complexity of audit query configuration and provides focused access to critical security events related to passphrase usage, authentication attempts, and access pattern analysis.

SECURITY FOCUS: 

PASSPHRASE EVENT FILTERING:
The method automatically configures query options to capture only passphrase-related
events, including successful authentications, failed attempts, passphrase changes,
policy violations, and suspicious access patterns. This focused approach enables
efficient security monitoring and threat detection.

AUTHENTICATION MONITORING:
Passphrase access logs are critical for detecting unauthorized access attempts,
credential stuffing attacks, brute force attempts, and other authentication-related
security threats. This method provides direct access to these high-priority events.

ACCESS PATTERN ANALYSIS:
The chronological ordering of passphrase events enables analysis of access patterns,
identification of anomalous behavior, and detection of potential security incidents
requiring investigation or response.

OPERATIONAL CHARACTERISTICS: 

TIME-BASED FILTERING:
The 'since' parameter enables efficient time-bounded queries, allowing callers to
retrieve only recent events or events from specific time periods. This is essential
for both real-time monitoring and historical analysis of passphrase access patterns.

REASONABLE RESULT LIMITS:
The method applies a default limit of 1000 events to prevent resource exhaustion
while providing sufficient data for most analysis scenarios. This balance ensures
good performance while capturing comprehensive event data for security analysis.

TENANT-SPECIFIC SCOPE:
All queries are strictly scoped to the specified tenant, ensuring tenant isolation
and preventing cross-tenant data leakage while enabling focused security analysis
for specific tenant environments.

CONVENIENCE FEATURES: 

SIMPLIFIED INTERFACE:
This method eliminates the need for callers to construct complex audit query
options, providing a clean interface focused specifically on passphrase events.
This reduces integration complexity and potential configuration errors.

OPTIMIZED CONFIGURATION:
The method uses pre-configured query options optimized for passphrase event
retrieval, including appropriate filtering, sorting, and limiting parameters
that provide the most relevant results for security analysis.

CONSISTENT BEHAVIOR:
By standardizing the query configuration, this method ensures consistent
behavior across different callers and use cases, reducing variability in
result quality and enabling reliable security monitoring workflows.

SECURITY MONITORING USE CASES: 

REAL-TIME THREAT DETECTION:
Monitor recent passphrase access events to detect ongoing authentication
attacks, credential abuse, or suspicious access patterns requiring immediate
security response and investigation.

FORENSIC INVESTIGATION:
Analyze historical passphrase access events during security incident response
to understand attack timelines, identify compromised credentials, and assess
the scope and impact of authentication-related security breaches.

COMPLIANCE REPORTING:
Generate compliance reports focusing on authentication events and access
controls, demonstrating adherence to security policies and regulatory
requirements for credential management and access monitoring.

BEHAVIORAL ANALYSIS:
Study passphrase usage patterns over time to identify normal vs. anomalous
behavior, establish behavioral baselines, and detect deviations that may
indicate security threats or policy violations.

OPERATIONAL INTEGRATION: 

SECURITY DASHBOARDS:
Integrate with security monitoring dashboards to provide real-time visibility
into passphrase access events, authentication trends, and security metrics
for operational security teams and management oversight.

AUTOMATED ALERTING:
Use this method in automated security monitoring systems to trigger alerts
based on passphrase access patterns, failed authentication thresholds, or
other security-critical events requiring immediate attention.

INCIDENT RESPONSE:
Incorporate into incident response workflows to quickly gather authentication-
related evidence during security incidents, enabling faster response times
and more effective incident containment and remediation.

PERFORMANCE CONSIDERATIONS: 

EFFICIENT FILTERING:
The method leverages optimized backend filtering to efficiently retrieve
only passphrase-related events, minimizing network traffic, memory usage,
and processing overhead compared to broader audit queries.

TIME-BOUNDED QUERIES:
Using the 'since' parameter effectively helps limit result sets and improve
query performance, especially important for tenants with high authentication
volumes or long operational histories.

RESULT SET MANAGEMENT:
The 1000-event limit prevents excessive memory usage and ensures reasonable
response times, while still providing sufficient data for most analysis
scenarios. Consider multiple queries for comprehensive historical analysis.

ERROR HANDLING AND RELIABILITY: 

TENANT VALIDATION:
The method validates tenant existence and access permissions before executing
queries, providing clear error messages for invalid tenant IDs or access
permission failures.

GRACEFUL DEGRADATION:
Query failures are handled gracefully with appropriate error reporting,
enabling calling applications to implement appropriate retry logic or
fallback mechanisms for reliable security monitoring.

DATA QUALITY AND CONSISTENCY: 

STANDARDIZED EVENTS:
Returned events follow standardized audit event schemas, ensuring consistent
data structure and content across different vault implementations and
enabling reliable automated processing and analysis.

CHRONOLOGICAL ORDERING:
Events are returned in chronological order, enabling timeline analysis and
proper sequencing of authentication events for accurate security analysis
and incident reconstruction.

Parameters: 

tenantID: Unique identifier for the tenant whose passphrase events to query
since: Optional timestamp to limit results to events after this time (nil for all events)

Returns: 

[]audit.Event: Chronologically ordered passphrase access events (max 1000)
error: nil on success, error on tenant validation failure or query execution failure

func (*VaultManager) QuerySecretAccess 

func (tm *VaultManager) QuerySecretAccess(tenantID string, secretID string, since *time.Time) ([]audit.Event, error)

QuerySecretAccess provides targeted querying of secret access events for security analysis.

OVERVIEW: This convenience method specializes in retrieving audit events related to specific secret access activities within a tenant's vault. It streamlines the process of investigating secret usage patterns, detecting unauthorized access, and performing forensic analysis on specific secret resources.

OPERATIONAL BEHAVIOR: 

TARGETED FILTERING:
The method automatically configures query parameters to focus exclusively on
events related to the specified secret within the target tenant. This includes
read operations, access attempts, permission checks, and usage tracking events
associated with the secret resource.

TIME-BASED ANALYSIS:
When a 'since' timestamp is provided, the query retrieves all secret access
events from that point forward, enabling time-bounded analysis for incident
investigation, compliance auditing, or operational monitoring of recent activity.

RESULT LIMITATION:
The method applies a default limit of 1000 events to prevent excessive memory
usage and ensure responsive query performance. For comprehensive historical
analysis requiring more events, use the full QueryAuditLogs method with
custom pagination parameters.

SECURITY ANALYSIS CAPABILITIES: 

ACCESS PATTERN DETECTION:
Results enable identification of unusual access patterns, including frequency
anomalies, off-hours access, geographic inconsistencies, or access from
unexpected sources that may indicate security concerns or policy violations.

COMPLIANCE VERIFICATION:
The method supports compliance auditing by providing detailed trails of who
accessed specific secrets, when access occurred, and the context of each
access event, enabling verification of access controls and policy adherence.

FORENSIC INVESTIGATION:
During security incidents, the method provides focused forensic data about
specific secret compromise, enabling investigators to understand the scope,
timeline, and impact of potential security breaches.

USAGE PATTERNS: 

INCIDENT RESPONSE:
When investigating potential security incidents involving specific secrets,
this method provides rapid access to relevant audit trails without requiring
complex query construction or broad audit log analysis.

OPERATIONAL MONITORING:
Regular monitoring of high-value secrets can be automated using this method
to detect unusual activity patterns, ensure proper access controls, and
maintain operational security awareness.

COMPLIANCE REPORTING:
Regulatory requirements often mandate detailed tracking of sensitive data
access. This method facilitates generation of secret-specific access reports
for compliance documentation and regulatory submissions.

PERFORMANCE CHARACTERISTICS: 

OPTIMIZED QUERIES:
The method leverages tenant-specific and secret-specific indexes to provide
efficient query performance, even for tenants with large audit log volumes.
Query optimization focuses on the specific secret identifier and time range.

MEMORY EFFICIENCY:
The default 1000-event limit prevents excessive memory consumption while
providing sufficient data for most analysis scenarios. Consider implementing
pagination for comprehensive historical analysis requirements.

CONCURRENT SAFETY:
The method safely handles concurrent access to audit data and maintains
consistent results even during simultaneous secret access operations or
other audit querying activities.

ERROR HANDLING: 

TENANT VALIDATION:
Invalid or inaccessible tenant IDs result in appropriate error responses,
ensuring proper tenant isolation and access control enforcement.

GRACEFUL DEGRADATION:
If audit logging is not available for the specified tenant, the method
returns empty results rather than failing, enabling resilient operation
in mixed-configuration environments.

RESULT INTERPRETATION: 

EVENT TYPES:
Results may include various event types such as successful access, failed
access attempts, permission denials, secret retrievals, and metadata
queries, providing comprehensive visibility into secret interaction patterns.

CONTEXTUAL INFORMATION:
Each event contains contextual metadata including user identification,
source information, operation types, and timestamps, enabling detailed
analysis of access patterns and security implications.

SECURITY CONSIDERATIONS: 

ACCESS AUTHORIZATION:
The method respects tenant access controls and only returns audit data
for secrets within tenants that the caller is authorized to access,
maintaining proper security boundaries.

AUDIT TRAIL:
The query operation itself is audited, creating a complete trail of
audit log access for security monitoring and compliance verification.

INTEGRATION PATTERNS: 

AUTOMATED MONITORING:
The method integrates well with monitoring systems and alerting frameworks
for automated detection of suspicious secret access patterns or policy
violations requiring immediate attention.

REPORTING SYSTEMS:
Results can be directly integrated into reporting systems for compliance
documentation, security dashboards, and operational visibility tools.

USAGE EXAMPLE: 

// Investigate recent access to a sensitive database credential
since := time.Now().Add(-24 * time.Hour) // Last 24 hours
events, err := vaultManager.QuerySecretAccess(
    "prod-tenant-001",
    "database/prod/credentials",
    &since,
)
if err != nil {
    log.Printf("Failed to query secret access: %v", err)
    return
}

// Analyze access patterns for security review
for _, event := range events {
    fmt.Printf("Access: %s by %s at %s from %s\n",
        event.Operation,
        event.UserID,
        event.Timestamp.Format(time.RFC3339),
        event.SourceIP,
    )

    // Check for suspicious patterns
    if isOffHours(event.Timestamp) {
        fmt.Printf("WARNING: Off-hours access detected\n")
    }
    if isUnusualLocation(event.SourceIP) {
        fmt.Printf("WARNING: Access from unusual location\n")
    }
}

// Generate compliance report
report := generateAccessReport(events)
saveComplianceReport(report)

ADVANCED USAGE: 

// Continuous monitoring with periodic checks
func monitorSecretAccess(tenantID, secretID string) {
    ticker := time.NewTicker(5 * time.Minute)
    defer ticker.Stop()

    lastCheck := time.Now()

    for range ticker.C {
        events, err := vaultManager.QuerySecretAccess(
            tenantID,
            secretID,
            &lastCheck,
        )
        if err != nil {
            log.Printf("Monitoring error: %v", err)
            continue
        }

        for _, event := range events {
            if detectAnomalousPattern(event) {
                triggerSecurityAlert(event)
            }
        }

        lastCheck = time.Now()
    }
}

// Batch analysis for multiple secrets
func analyzeSecretPortfolio(tenantID string, secretIDs []string) {
    since := time.Now().Add(-7 * 24 * time.Hour) // Last week

    for _, secretID := range secretIDs {
        events, err := vaultManager.QuerySecretAccess(
            tenantID,
            secretID,
            &since,
        )
        if err != nil {
            log.Printf("Failed to analyze %s: %v", secretID, err)
            continue
        }

        analysis := performSecurityAnalysis(events)
        updateSecurityDashboard(secretID, analysis)
    }
}

Parameters: 

tenantID: Unique identifier for the target tenant
secretID: Unique identifier for the specific secret to analyze
since: Optional timestamp for time-bounded queries (nil for all history)

Returns: 

[]audit.Event: Array of audit events related to secret access (max 1000)
error: nil on success, error on tenant access failure or system issues

func (*VaultManager) QueryTenantAuditLogs 

func (tm *VaultManager) QueryTenantAuditLogs(tenantID string, options audit.QueryOptions) (audit.QueryResult, error)

QueryTenantAuditLogs performs comprehensive audit queries for a single tenant.

OVERVIEW: This method provides the most comprehensive audit querying capabilities for a single tenant, combining the flexibility of QueryAuditLogs with tenant-specific optimizations and enhanced filtering capabilities.

TENANT-OPTIMIZED QUERYING: 

PERFORMANCE OPTIMIZATION:
Tenant-specific queries are optimized using tenant-specific indexes
and data structures, providing better performance than cross-tenant
queries for tenant-focused analysis and reporting.

COMPREHENSIVE FILTERING:
The method supports all available filtering options with tenant-specific
enhancements such as secret-specific filters, key-specific filters,
and tenant-specific custom field matching. This enables highly
precise audit queries for detailed security analysis.

CONTEXTUAL ENRICHMENT:
Results include tenant-specific contextual information and metadata
that may not be available in cross-tenant queries, providing richer
analysis capabilities for tenant-focused investigations.

ANALYTICAL CAPABILITIES: - Deep-dive analysis of tenant-specific security events - Comprehensive compliance reporting for individual tenants - Detailed forensic investigation capabilities - Performance-optimized queries for large tenant datasets

USE CASES: - Detailed security analysis for specific tenants - Tenant-specific compliance audits and reporting - Forensic investigation of tenant security incidents - Operational analysis and optimization for specific tenants

OPERATIONAL BEHAVIOR: 

TENANT VALIDATION:
The method first validates that the specified tenant exists and is
accessible by the caller. Non-existent or inaccessible tenants result
in immediate error return with appropriate error messages.

AUDIT AVAILABILITY:
If the tenant vault does not have audit logging enabled or configured,
the method returns an empty but valid result set rather than failing.
This ensures consistent behavior across tenants with different audit
configurations.

QUERY OPTION ENFORCEMENT:
The method automatically ensures the tenant ID is properly set in the
query options, preventing accidental cross-tenant queries and ensuring
tenant isolation is maintained at the audit level.

ERROR HANDLING: - Returns specific errors for tenant validation failures - Provides detailed error context for audit system failures - Maintains tenant isolation even in error scenarios - Ensures consistent error formatting for operational monitoring

SECURITY CONSIDERATIONS: - Tenant isolation is enforced at all levels of the query operation - Audit access is subject to the same authorization as vault access - Query operations themselves are audited for security monitoring - Results filtering respects tenant-specific access controls

Parameters: 

tenantID: Unique identifier for the tenant to query
options: Comprehensive query options with tenant-specific enhancements

Returns: 

audit.QueryResult: Comprehensive audit results for the tenant
error: nil on success, error on failure or authorization denial

func (*VaultManager) RotateAllTenantKeys 

func (tm *VaultManager) RotateAllTenantKeys(tenantIDs []string, reason string) ([]BulkOperationResult, error)

RotateAllTenantKeys performs cryptographic key rotation across multiple tenants.

OVERVIEW: This method orchestrates the rotation of encryption keys for multiple tenants in a coordinated bulk operation. It provides enterprise-scale key management capabilities with comprehensive audit trails, detailed result reporting, and robust error handling for each tenant operation.

OPERATIONAL SEMANTICS: 

BULK PROCESSING MODEL:
The operation processes each tenant sequentially, ensuring that failures
in one tenant do not affect others. Each tenant's key rotation is treated
as an independent operation with its own success/failure status and
detailed result reporting.

AUTO-DISCOVERY CAPABILITY:
When no tenant IDs are specified (empty slice), the method automatically
discovers and rotates keys for all tenants in the system. This supports
organization-wide key rotation policies and compliance requirements.

ATOMIC PER-TENANT OPERATIONS:
Each tenant's key rotation is atomic - either the entire rotation succeeds
or it fails completely with no partial state changes. This ensures
cryptographic consistency and prevents corrupted key states.

SECURITY CONSIDERATIONS: 

CRYPTOGRAPHIC CONTINUITY:
The method maintains cryptographic continuity by preserving access to
previously encrypted data while establishing new encryption keys. Old
keys remain accessible for decryption while new keys are used for
encryption operations.

AUDIT TRAIL COMPLETENESS:
Every key rotation operation generates comprehensive audit entries
including the rotation reason, old key identifier, new key identifier,
and operation timestamp. This provides complete audit trails for
compliance and security analysis.

FAILURE ISOLATION:
Tenant failures are isolated - if one tenant's key rotation fails,
other tenants continue to be processed. This prevents cascading
failures in multi-tenant environments.

ENTERPRISE INTEGRATION: 

COMPLIANCE SUPPORT:
The method supports regulatory compliance requirements for periodic
key rotation by providing detailed audit trails, success/failure
reporting, and comprehensive metadata about rotation operations.

OPERATIONAL VISIBILITY:
Detailed result reporting enables operations teams to monitor bulk
key rotation progress, identify failed operations, and take corrective
action. Each result includes diagnostic information for troubleshooting.

AUTOMATION INTEGRATION:
The method is designed for integration with automated key rotation
systems, scheduled operations, and compliance automation tools.
Results can be processed programmatically for further automation.

RESULT INTERPRETATION: 

SUCCESS METRICS:
Results include both per-tenant success/failure status and aggregate
success metrics. Operations teams can quickly identify overall operation
success rates and individual tenant issues.

DIAGNOSTIC INFORMATION:
Failed operations include detailed error messages and diagnostic
information to support troubleshooting and remediation efforts.
Successful operations include metadata about the rotation results.

BEST PRACTICES:

1. SCHEDULING: Perform bulk rotations during maintenance windows 2. MONITORING: Monitor rotation progress and results in real-time 3. VALIDATION: Verify rotation results and test key accessibility 4. DOCUMENTATION: Maintain detailed records of rotation activities 5. AUTOMATION: Integrate with automated compliance and monitoring systems 6. TESTING: Test rotation procedures in non-production environments 7. RECOVERY: Maintain recovery procedures for failed rotations

Parameters: 

tenantIDs: Slice of tenant IDs to rotate (empty slice rotates all tenants)
reason: Human-readable reason for rotation (recorded in audit logs)

Returns: 

[]BulkOperationResult: Detailed results for each tenant operation
error: nil on successful completion, error on system-level failures

func (*VaultManager) RotateAllTenantPassphrases 

func (tm *VaultManager) RotateAllTenantPassphrases(tenantIDs []string, newPassphrase string, reason string) ([]BulkOperationResult, error)

RotateAllTenantPassphrases performs coordinated passphrase rotation across multiple tenants for enhanced security management.

OVERVIEW: This administrative function enables bulk passphrase rotation operations across specified tenants or all tenants within the vault manager. It provides essential security lifecycle management capabilities for organizations requiring coordinated password policy enforcement, security incident response, or compliance-driven credential rotation procedures.

OPERATIONAL SCOPE: 

TARGETED ROTATION:
When tenantIDs slice contains specific tenant identifiers, the operation is limited
to those tenants only. This enables selective rotation for specific security zones,
compliance groups, or incident response scenarios affecting particular tenants.

GLOBAL ROTATION:
When tenantIDs is nil or empty, the operation automatically discovers and processes
all tenants within the vault manager's scope. This provides organization-wide
passphrase rotation for comprehensive security policy enforcement.

FAULT ISOLATION:
Individual tenant rotation failures are isolated and do not abort the entire
operation. Each tenant's result is captured independently, ensuring maximum
operational coverage even during partial system failures.

SECURITY CHARACTERISTICS: 

COORDINATED TIMING:
All tenant rotations use the same new passphrase and are processed sequentially
to ensure coordinated security policy application. This approach minimizes the
window of inconsistent passphrase states across the organization.

AUDIT INTEGRATION:
The operation generates comprehensive audit trails including bulk operation
initiation, individual tenant rotation events, and completion summaries.
This provides complete traceability for security and compliance requirements.

ROLLBACK CONSIDERATIONS:
Failed rotations do not automatically rollback successful ones. Organizations
should implement appropriate rollback procedures based on their security
policies and operational requirements.

RESULT REPORTING: 

COMPREHENSIVE OUTCOMES:
Each tenant operation produces a detailed BulkOperationResult containing
success status, error information, operational metadata, and timestamps
for complete audit trail and debugging capabilities.

OPERATIONAL METRICS:
The function tracks and reports success/failure counts through audit logs,
providing operational visibility into bulk operation effectiveness and
enabling automated monitoring and alerting integration.

ERROR CATEGORIZATION:
Errors are categorized by failure type (vault access, rotation execution)
to enable targeted remediation and operational process improvements.

PERFORMANCE CONSIDERATIONS: 

SEQUENTIAL PROCESSING:
Tenants are processed sequentially to ensure system stability and enable
proper error handling. For large tenant counts, consider breaking operations
into smaller batches or implementing job scheduling for optimal performance.

RESOURCE MANAGEMENT:
Each rotation operation may involve cryptographic operations and storage
updates. Monitor system resources during bulk operations and consider
scheduling during maintenance windows for large-scale rotations.

TRANSACTION ISOLATION:
Each tenant rotation is processed as an independent transaction, providing
isolation but requiring careful consideration of partial completion scenarios
in operational procedures and recovery planning.

ERROR HANDLING STRATEGY: 

GRACEFUL DEGRADATION:
The function implements graceful degradation where individual tenant failures
are recorded but do not prevent processing of remaining tenants. This maximizes
operational coverage while providing complete failure visibility.

DIAGNOSTIC INFORMATION:
Detailed error messages are captured for each failure, including the specific
failure reason and context to enable effective troubleshooting and remediation.

PARTIAL SUCCESS HANDLING:
Operations resulting in partial success require careful post-operation analysis
to determine appropriate remediation actions for failed tenant rotations.

COMPLIANCE AND GOVERNANCE: 

REGULATORY ALIGNMENT:
The function supports regulatory requirements for credential rotation by providing
documented rotation reasons, complete audit trails, and timestamp information
for compliance reporting and validation.

POLICY ENFORCEMENT:
Bulk rotation enables consistent policy enforcement across organizational
boundaries, ensuring uniform security posture and compliance adherence
across all tenant environments.

AUDIT TRAIL COMPLETENESS:
All aspects of the bulk operation are audited, including initiation parameters,
individual tenant outcomes, and completion metrics for comprehensive
compliance documentation and security monitoring.

OPERATIONAL INTEGRATION: 

INCIDENT RESPONSE:
The function supports security incident response procedures requiring rapid
credential rotation across affected tenants or organization-wide rotation
in response to potential credential compromise scenarios.

MAINTENANCE SCHEDULING:
Regular passphrase rotation can be scheduled using this function as part of
automated security maintenance procedures, supporting proactive security
lifecycle management and compliance requirements.

MONITORING INTEGRATION:
Operation results can be integrated with monitoring systems to track rotation
success rates, identify systematic issues, and maintain operational visibility
into security credential management effectiveness.

USAGE EXAMPLE: 

// Emergency rotation for specific tenants after security incident
affectedTenants := []string{"tenant-prod-1", "tenant-prod-2", "tenant-staging-1"}
newPassphrase := generateSecurePassphrase() // Use secure generation
reason := "Emergency rotation due to security incident INC-2024-001"

results, err := vaultManager.RotateAllTenantPassphrases(affectedTenants, newPassphrase, reason)
if err != nil {
    log.Fatalf("Bulk rotation failed: %v", err)
}

// Process results for monitoring and follow-up
var failed []string
successCount := 0
for _, result := range results {
    if result.Success {
        successCount++
        log.Printf("Successfully rotated passphrase for tenant: %s", result.TenantID)
    } else {
        failed = append(failed, result.TenantID)
        log.Errorf("Failed to rotate passphrase for tenant %s: %s",
                  result.TenantID, result.Error)
    }
}

// Report outcomes and handle failures
log.Printf("Bulk rotation completed: %d/%d successful", successCount, len(results))
if len(failed) > 0 {
    // Trigger manual remediation process for failed tenants
    triggerManualRotation(failed, reason)
    sendSecurityAlert("Partial bulk rotation failure", failed)
}

// Organization-wide scheduled rotation (quarterly compliance requirement)
quarterlyPassphrase := generateCompliantPassphrase()
reason := "Q1 2024 scheduled compliance rotation"

// Pass nil/empty slice to rotate all tenants
results, err := vaultManager.RotateAllTenantPassphrases(nil, quarterlyPassphrase, reason)
if err != nil {
    log.Fatalf("Scheduled rotation failed: %v", err)
}

generateComplianceReport(results, "Q1_2024_Rotation_Report")

SECURITY BEST PRACTICES: 

PASSPHRASE GENERATION:
Always use cryptographically secure passphrase generation methods that meet
organizational complexity requirements and security policies. Never use
predictable or weak passphrases for bulk operations.

REASON DOCUMENTATION:
Provide clear, specific reasons for bulk operations to support audit
requirements, incident documentation, and compliance reporting. Reasons
should include reference numbers for incidents or compliance requirements.

POST-OPERATION VALIDATION:
Implement validation procedures to verify successful rotation and test
access with new passphrases. Failed rotations may require manual
intervention and specialized recovery procedures.

COMMUNICATION PROTOCOLS:
Establish communication protocols for bulk operations to ensure affected
users and systems are notified appropriately and access disruption is
minimized through coordinated change management.

Parameters: 

tenantIDs: Slice of tenant identifiers to rotate; nil/empty processes all tenants
newPassphrase: New passphrase to apply; must be non-empty and meet security requirements
reason: Human-readable reason for rotation; used for audit trail and compliance documentation

Returns: 

[]BulkOperationResult: Detailed results for each tenant operation with success/failure status
error: Critical errors preventing operation initiation; individual tenant failures reported in results

type VaultManagerService 

type VaultManagerService interface {

	// GetVault retrieves a VaultService instance for a specific tenant.
	//
	// OVERVIEW:
	// This method provides access to tenant-specific vault instances, serving
	// as the primary entry point for tenant-scoped operations. It implements
	// lazy initialization patterns and resource pooling to optimize performance
	// while maintaining strict tenant isolation.
	//
	// RESOURCE MANAGEMENT:
	//
	//   LAZY INITIALIZATION:
	//   Vault instances are created on-demand when first accessed, reducing
	//   memory footprint and startup time for deployments with many inactive
	//   tenants. Initialization includes loading tenant-specific encryption
	//   keys and establishing secure memory contexts.
	//
	//   CONNECTION POOLING:
	//   The service maintains a pool of initialized vault instances to avoid
	//   repeated initialization costs. Pool management includes automatic
	//   cleanup of idle instances and load balancing across active instances.
	//
	//   TENANT ISOLATION:
	//   Each returned VaultService instance is completely isolated from other
	//   tenants, with separate encryption keys, audit contexts, and resource
	//   allocations. Cross-tenant contamination is prevented at the service
	//   architecture level.
	//
	// SECURITY CONSIDERATIONS:
	// - Tenant access is subject to authorization checks
	// - Audit logging captures all vault instance requests
	// - Encryption keys are tenant-specific and never shared
	// - Resource limits prevent tenant-based denial of service
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant vault to retrieve
	//
	// Returns:
	//   VaultService: Tenant-specific vault instance for secret operations
	//   error: nil on success, detailed error on failure or access denial
	GetVault(tenantID string) (VaultService, error)

	// CloseTenant gracefully shuts down and cleans up resources for a tenant.
	//
	// OVERVIEW:
	// This method performs controlled shutdown of a tenant's vault instance,
	// ensuring all resources are properly cleaned up and all sensitive data
	// is securely wiped from memory. It supports both graceful shutdown
	// scenarios and emergency cleanup operations.
	//
	// CLEANUP OPERATIONS:
	//
	//   MEMORY SANITIZATION:
	//   All tenant-specific encryption keys, cached secrets, and intermediate
	//   cryptographic material are securely wiped from memory using
	//   cryptographically secure wiping techniques that prevent recovery
	//   through memory dump analysis.
	//
	//   RESOURCE DEALLOCATION:
	//   File handles, network connections, and system resources allocated
	//   to the tenant are properly closed and released. This includes
	//   cleaning up any temporary files or cached data structures.
	//
	//   AUDIT FINALIZATION:
	//   Pending audit events are flushed to persistent storage and audit
	//   streams are properly closed. Final audit events record the tenant
	//   shutdown operation with timestamp and reason information.
	//
	// SAFETY GUARANTEES:
	// - Secure memory wiping prevents data recovery attacks
	// - Graceful shutdown preserves audit trail integrity
	// - Resource cleanup prevents memory leaks in long-running services
	// - Operation is idempotent (safe to call multiple times)
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant to shut down
	//
	// Returns:
	//   error: nil on successful cleanup, error on shutdown failures
	CloseTenant(tenantID string) error

	// CloseAll performs graceful shutdown of all active tenant vaults.
	//
	// OVERVIEW:
	// This method orchestrates shutdown of all tenant vault instances,
	// typically used during service shutdown or emergency maintenance
	// operations. It ensures orderly cleanup across all tenants while
	// maintaining audit trail integrity and security guarantees.
	//
	// SHUTDOWN ORCHESTRATION:
	//
	//   PARALLEL SHUTDOWN:
	//   Tenant shutdown operations are executed in parallel to minimize
	//   total shutdown time. The degree of parallelism is configurable
	//   to balance shutdown speed with system resource utilization.
	//
	//   FAILURE ISOLATION:
	//   Shutdown failures for individual tenants do not prevent shutdown
	//   of other tenants. The method collects and reports all shutdown
	//   errors while ensuring maximum cleanup is achieved.
	//
	//   AUDIT PRESERVATION:
	//   All audit data is preserved during shutdown operations, with
	//   special audit events recorded for the service-wide shutdown
	//   operation and any tenant-specific shutdown failures.
	//
	// OPERATIONAL USES:
	// - Service shutdown and restart operations
	// - Emergency maintenance procedures
	// - Resource cleanup after configuration changes
	// - Disaster recovery preparation
	//
	// Parameters: None
	//
	// Returns:
	//   error: nil if all tenants shut down successfully, error with details
	//          of any failures (partial success still cleans up other tenants)
	CloseAll() error

	// ListTenants returns identifiers for all currently active tenants.
	//
	// OVERVIEW:
	// This method provides discovery of active tenant vault instances,
	// supporting administrative operations, monitoring, and bulk operation
	// planning. It returns only tenants that are currently active or
	// have been recently active within the service.
	//
	// TENANT DISCOVERY:
	//
	//   ACTIVE TENANT DETECTION:
	//   The method returns tenants that have active vault instances or
	//   have been accessed within a configurable time window. This
	//   prevents returning stale tenant identifiers from historical
	//   operations while ensuring recently active tenants are visible.
	//
	//   AUTHORIZATION FILTERING:
	//   The returned list is filtered based on the caller's authorization
	//   level. Administrative users may see all tenants, while limited
	//   users may only see tenants they have been granted access to.
	//
	//   PERFORMANCE OPTIMIZATION:
	//   The method is optimized for frequent polling by monitoring and
	//   dashboard applications. Results may be cached for short periods
	//   to reduce overhead on the underlying tenant management system.
	//
	// SECURITY CONSIDERATIONS:
	// - Tenant list access is subject to authorization checks
	// - Audit logging captures tenant discovery operations
	// - Results are filtered based on caller permissions
	// - No sensitive tenant data is included in the response
	//
	// Parameters: None
	//
	// Returns:
	//   []string: Array of tenant identifiers for active tenants
	//   error: nil on success, error on authorization failure or system error
	ListTenants() ([]string, error)

	// RotateAllTenantKeys performs encryption key rotation for multiple tenants.
	//
	// OVERVIEW:
	// This method orchestrates simultaneous key rotation across multiple tenants,
	// supporting compliance requirements, security hardening, and routine
	// key lifecycle management. It ensures cryptographic continuity while
	// upgrading encryption keys to maintain security posture.
	//
	// KEY ROTATION PROCESS:
	//
	//   CRYPTOGRAPHIC CONTINUITY:
	//   Key rotation is performed using a migration process that maintains
	//   access to existing encrypted data while establishing new encryption
	//   keys for future operations. This ensures no data loss or service
	//   interruption during the rotation process.
	//
	//   ATOMIC OPERATIONS:
	//   Key rotation for each tenant is atomic - either the rotation completes
	//   successfully or the tenant remains on the previous key with no
	//   partial state. This prevents cryptographic inconsistencies that
	//   could result in data loss or security vulnerabilities.
	//
	//   ROLLBACK CAPABILITIES:
	//   The rotation process supports rollback to previous keys if issues
	//   are detected during or after rotation. Rollback operations are
	//   also atomic and maintain the same security guarantees.
	//
	// SECURITY ENHANCEMENTS:
	// - New keys use latest cryptographic algorithms and key sizes
	// - Forward secrecy: compromise of old keys doesn't affect new operations
	// - Audit trail includes complete key lifecycle events
	// - Secure key material destruction after successful rotation
	//
	// OPERATIONAL CONSIDERATIONS:
	// - Operations are performed in parallel across tenants
	// - Resource usage is controlled to prevent system overload
	// - Progress monitoring and status reporting for long-running operations
	// - Automatic retry logic for transient failures
	//
	// Parameters:
	//   tenantIDs: Array of tenant identifiers to rotate keys for
	//   reason: Human-readable reason for the rotation (for audit trail)
	//
	// Returns:
	//   []BulkOperationResult: Per-tenant results with success/failure details
	//   error: nil on successful orchestration, error on systematic failures
	RotateAllTenantKeys(tenantIDs []string, reason string) ([]BulkOperationResult, error)

	// RotateAllTenantPassphrases updates master passphrases for multiple tenants.
	//
	// OVERVIEW:
	// This method performs coordinated passphrase rotation across multiple
	// tenants, supporting security policies that require periodic passphrase
	// updates, incident response procedures, or administrative access changes.
	// It maintains cryptographic integrity while updating authentication
	// credentials.
	//
	// PASSPHRASE ROTATION MECHANICS:
	//
	//   CRYPTOGRAPHIC RE-ENCRYPTION:
	//   Passphrase rotation involves re-encrypting the tenant's master key
	//   using the new passphrase-derived key. This process maintains access
	//   to all existing secrets while updating the authentication layer.
	//
	//   SECURE PASSPHRASE HANDLING:
	//   The new passphrase is handled using secure memory techniques throughout
	//   the rotation process. Intermediate cryptographic material is protected
	//   using memguard and securely wiped after use.
	//
	//   VERIFICATION PROCESS:
	//   After rotation, the new passphrase is verified by attempting to
	//   unlock the tenant vault. Only after successful verification is
	//   the old passphrase material destroyed, ensuring the rotation
	//   process cannot result in locked-out tenants.
	//
	// COMPLIANCE SUPPORT:
	// - Audit events record passphrase rotation with timestamps
	// - Rotation reason is preserved for compliance reporting
	// - Support for compliance-driven rotation schedules
	// - Integration with identity management systems
	//
	// SECURITY CONSIDERATIONS:
	// - New passphrase is never logged or stored in plaintext
	// - Old passphrase material is cryptographically wiped
	// - Rotation process is resistant to timing attacks
	// - Failed rotations do not compromise existing security
	//
	// Parameters:
	//   tenantIDs: Array of tenant identifiers to rotate passphrases for
	//   newPassphrase: New passphrase to set for all specified tenants
	//   reason: Human-readable reason for the rotation (for audit trail)
	//
	// Returns:
	//   []BulkOperationResult: Per-tenant results with success/failure details
	//   error: nil on successful orchestration, error on systematic failures
	RotateAllTenantPassphrases(tenantIDs []string, newPassphrase string, reason string) ([]BulkOperationResult, error)

	// QueryAuditLogs performs flexible audit log queries with advanced filtering.
	//
	// OVERVIEW:
	// This method provides comprehensive audit log querying capabilities with
	// support for complex filtering, temporal ranges, and result aggregation.
	// It enables security analysis, compliance reporting, and operational
	// monitoring across single tenants or the entire multi-tenant deployment.
	//
	// QUERY CAPABILITIES:
	//
	//   FLEXIBLE FILTERING:
	//   The QueryOptions parameter supports complex filtering criteria including
	//   tenant scope, operation types, time ranges, success/failure status,
	//   and custom field matching. Multiple filters can be combined using
	//   logical operators for sophisticated queries.
	//
	//   PERFORMANCE OPTIMIZATION:
	//   Query execution is optimized for large audit datasets using indexing,
	//   result pagination, and streaming responses. Large result sets are
	//   handled efficiently without overwhelming system resources.
	//
	//   RESULT AGGREGATION:
	//   The method supports aggregation operations such as counting, grouping,
	//   and statistical analysis of audit events. This enables dashboard
	//   applications and analytical tools to efficiently process audit data.
	//
	// SECURITY AND COMPLIANCE:
	// - Audit queries are themselves audited for security monitoring
	// - Result sets are filtered based on caller authorization
	// - Immutable audit trail ensures tamper detection
	// - Support for regulatory compliance queries and reporting
	//
	// Parameters:
	//   options: Comprehensive query options including filters and aggregations
	//
	// Returns:
	//   *audit.QueryResult: Structured query results with metadata
	//   error: nil on success, error on query failure or authorization denial
	QueryAuditLogs(options audit.QueryOptions) (*audit.QueryResult, error)

	// GetAuditSummary generates aggregated audit statistics for a tenant.
	//
	// OVERVIEW:
	// This method produces comprehensive audit summaries for individual tenants,
	// providing key operational metrics and activity patterns. It supports
	// monitoring dashboards, security analysis, and tenant health assessment
	// through pre-calculated statistical summaries.
	//
	// SUMMARY GENERATION:
	//
	//   STATISTICAL AGGREGATION:
	//   The summary includes counts, ratios, and temporal analysis of audit
	//   events categorized by operation type and outcome. Statistical
	//   calculations are performed efficiently using pre-built indexes
	//   and incremental aggregation techniques.
	//
	//   TEMPORAL ANALYSIS:
	//   When a 'since' parameter is provided, the summary covers only events
	//   from that point forward, enabling trend analysis and delta reporting.
	//   Without the parameter, the summary covers the tenant's complete
	//   audit history.
	//
	//   PERFORMANCE CACHING:
	//   Summary data is cached and incrementally updated to support frequent
	//   polling by monitoring applications. Cache invalidation ensures
	//   summaries reflect recent activity while maintaining query performance.
	//
	// MONITORING INTEGRATION:
	// - Designed for integration with monitoring and alerting systems
	// - Supports threshold-based alerting on activity patterns
	// - Provides baseline metrics for anomaly detection
	// - Enables capacity planning and usage trend analysis
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant to summarize
	//   since: Optional timestamp to limit summary to recent events
	//
	// Returns:
	//   AuditSummary: Comprehensive audit statistics for the tenant
	//   error: nil on success, error on failure or authorization denial
	GetAuditSummary(tenantID string, since *time.Time) (AuditSummary, error)

	// QueryKeyOperations retrieves audit events for cryptographic key operations.
	//
	// OVERVIEW:
	// This method provides specialized querying for cryptographic key operations
	// within a tenant's audit trail. It supports security analysis of key
	// usage patterns, compliance auditing of key lifecycle events, and
	// investigation of key-related security incidents.
	//
	// KEY OPERATION TRACKING:
	//
	//   COMPREHENSIVE KEY LIFECYCLE:
	//   The method returns events for all key-related operations including
	//   key generation, rotation, usage, and destruction. This provides
	//   complete visibility into key lifecycle management for security
	//   analysis and compliance reporting.
	//
	//   CRYPTOGRAPHIC ANALYSIS:
	//   Results include sufficient detail for cryptographic security analysis
	//   such as key algorithms, key sizes, usage patterns, and performance
	//   metrics. This supports security assessments and algorithm migration
	//   planning.
	//
	//   TEMPORAL CORRELATION:
	//   Key operation events can be correlated with other audit events to
	//   analyze the relationship between key operations and secret access
	//   patterns, supporting comprehensive security analysis.
	//
	// SECURITY MONITORING:
	// - Detects unusual key usage patterns that may indicate compromise
	// - Supports forensic analysis of cryptographic operations
	// - Enables compliance reporting for key management standards
	// - Provides evidence for incident response investigations
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant to query
	//   keyID: Specific key identifier to filter events for
	//   since: Optional timestamp to limit results to recent events
	//
	// Returns:
	//   []audit.Event: Array of key operation events matching the criteria
	//   error: nil on success, error on failure or authorization denial
	QueryKeyOperations(tenantID string, keyID string, since *time.Time) ([]audit.Event, error)

	// QuerySecretAccess retrieves audit events for secret access operations.
	//
	// OVERVIEW:
	// This method provides specialized querying for secret access operations,
	// supporting security monitoring, access pattern analysis, and investigation
	// of unauthorized access attempts. It enables detailed tracking of how
	// secrets are accessed and used within a tenant's vault.
	//
	// ACCESS PATTERN ANALYSIS:
	//
	//   DETAILED ACCESS TRACKING:
	//   The method returns comprehensive information about secret access
	//   including access timestamps, operation types (read/write/delete),
	//   success/failure status, and contextual information about the
	//   access attempt.
	//
	//   BEHAVIORAL ANALYSIS:
	//   Access patterns can be analyzed to establish baselines for normal
	//   secret usage and detect anomalies that may indicate unauthorized
	//   access, compromised credentials, or misuse of privileged access.
	//
	//   COMPLIANCE REPORTING:
	//   The detailed access logs support compliance requirements for
	//   sensitive data access tracking, including who accessed what
	//   secrets when and for what purpose.
	//
	// SECURITY APPLICATIONS:
	// - Unauthorized access detection and incident response
	// - Compliance auditing for sensitive secret access
	// - Usage pattern analysis for security optimization
	// - Forensic investigation of security incidents
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant to query
	//   secretID: Specific secret identifier to filter events for
	//   since: Optional timestamp to limit results to recent events
	//
	// Returns:
	//   []audit.Event: Array of secret access events matching the criteria
	//   error: nil on success, error on failure or authorization denial
	QuerySecretAccess(tenantID string, secretID string, since *time.Time) ([]audit.Event, error)

	// QueryFailedOperations retrieves audit events for failed operations.
	//
	// OVERVIEW:
	// This method provides specialized querying for failed operations across
	// all vault functions, supporting security monitoring, troubleshooting,
	// and incident response. It enables rapid identification of security
	// issues, system problems, and attack patterns.
	//
	// FAILURE ANALYSIS:
	//
	//   SECURITY INCIDENT DETECTION:
	//   Failed operations often indicate security events such as unauthorized
	//   access attempts, brute force attacks, or compromised credentials.
	//   The method supports rapid identification and analysis of potential
	//   security incidents.
	//
	//   SYSTEM HEALTH MONITORING:
	//   Patterns of failed operations can indicate system issues, resource
	//   constraints, or configuration problems that require operational
	//   attention. This supports proactive system maintenance and optimization.
	//
	//   ATTACK PATTERN RECOGNITION:
	//   Clustering and analysis of failed operations can reveal attack
	//   patterns, reconnaissance activities, and systematic attempts to
	//   compromise the vault system.
	//
	// OPERATIONAL USES:
	// - Security incident detection and response
	// - System troubleshooting and health monitoring
	// - Attack pattern analysis and threat intelligence
	// - Operational optimization and error reduction
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant to query
	//   since: Optional timestamp to limit results to recent events
	//
	// Returns:
	//   []audit.Event: Array of failed operation events matching the criteria
	//   error: nil on success, error on failure or authorization denial
	QueryFailedOperations(tenantID string, since *time.Time) ([]audit.Event, error)

	// QueryPassphraseAccessLogs retrieves audit events for passphrase operations.
	//
	// OVERVIEW:
	// This method provides specialized querying for passphrase-related operations
	// including authentication attempts, passphrase changes, and vault unlock
	// operations. It supports security monitoring of authentication events
	// and analysis of passphrase-based attack patterns.
	//
	// AUTHENTICATION MONITORING:
	//
	//   CREDENTIAL SECURITY:
	//   Passphrase access events are critical security indicators that can
	//   reveal unauthorized access attempts, credential compromise, or
	//   authentication system issues. The method provides detailed tracking
	//   of all passphrase-related security events.
	//
	//   ATTACK DETECTION:
	//   Failed passphrase attempts, unusual timing patterns, or high-frequency
	//   access attempts may indicate brute force attacks, credential stuffing,
	//   or other authentication-based attacks.
	//
	//   COMPLIANCE TRACKING:
	//   Many compliance frameworks require detailed logging of authentication
	//   events. This method provides the necessary audit trail for regulatory
	//   compliance and security certifications.
	//
	// SECURITY MONITORING:
	// - Brute force attack detection and prevention
	// - Credential compromise investigation
	// - Authentication system health monitoring
	// - Compliance reporting for access control systems
	//
	// Parameters:
	//   tenantID: Unique identifier for the tenant to query
	//   since: Optional timestamp to limit results to recent events
	//
	// Returns:
	//   []audit.Event: Array of passphrase access events matching the criteria
	//   error: nil on success, error on failure or authorization denial
	QueryPassphraseAccessLogs(tenantID string, since *time.Time) ([]audit.Event, error)

	// QueryAllTenantsAuditLogs performs cross-tenant audit log queries.
	//
	// OVERVIEW:
	// This method enables audit log queries across multiple tenants simultaneously,
	// supporting organization-wide security monitoring, compliance reporting,
	// and incident response operations. It provides comprehensive visibility
	// into multi-tenant security events while maintaining tenant isolation.
	//
	// CROSS-TENANT ANALYSIS:
	//
	//   ORGANIZATIONAL SECURITY:
	//   Cross-tenant queries enable detection of security patterns that span
	//   multiple tenants, such as coordinated attacks, compromised administrative
	//   accounts, or systematic reconnaissance activities.
	//
	//   COMPLIANCE REPORTING:
	//   Many regulatory frameworks require organization-wide audit reporting
	//   that spans all tenant boundaries. This method provides the necessary
	//   capabilities for comprehensive compliance reporting.
	//
	//   INCIDENT RESPONSE:
	//   Security incidents often affect multiple tenants or require correlation
	//   of events across tenant boundaries. This method supports comprehensive
	//   incident response investigations.
	//
	// AUTHORIZATION AND ISOLATION:
	// - Results are filtered based on caller's cross-tenant permissions
	// - Tenant data isolation is maintained even in cross-tenant queries
	// - Administrative audit trails track cross-tenant access
	// - Results are organized by tenant for analysis and reporting
	//
	// Parameters:
	//   options: Comprehensive query options applied across all tenants
	//
	// Returns:
	//   map[string]audit.QueryResult: Results organized by tenant ID
	//   error: nil on success, error on failure or authorization denial
	QueryAllTenantsAuditLogs(options audit.QueryOptions) (map[string]audit.QueryResult, error)

	// QueryTenantAuditLogs performs comprehensive audit queries for a single tenant.
	//
	// OVERVIEW:
	// This method provides the most comprehensive audit querying capabilities
	// for a single tenant, combining the flexibility of QueryAuditLogs with
	// tenant-specific optimizations and enhanced filtering capabilities.
	//
	// TENANT-OPTIMIZED QUERYING:
	//
	//   PERFORMANCE OPTIMIZATION:
	//   Tenant-specific queries are optimized using tenant-specific indexes
	//   and data structures, providing better performance than cross-tenant
	//   queries for tenant-focused analysis and reporting.
	//
	//   COMPREHENSIVE FILTERING:
	//
	// COMPREHENSIVE FILTERING:
	// The method supports all available filtering options with tenant-specific
	// enhancements such as secret-specific filters, key-specific filters,
	// and tenant-specific custom field matching. This enables highly
	// precise audit queries for detailed security analysis.
	//
	// CONTEXTUAL ENRICHMENT:
	// Results include tenant-specific contextual information and metadata
	// that may not be available in cross-tenant queries, providing richer
	// analysis capabilities for tenant-focused investigations.
	//
	// ANALYTICAL CAPABILITIES:
	// - Deep-dive analysis of tenant-specific security events
	// - Comprehensive compliance reporting for individual tenants
	// - Detailed forensic investigation capabilities
	// - Performance-optimized queries for large tenant datasets
	//
	// USE CASES:
	// - Detailed security analysis for specific tenants
	// - Tenant-specific compliance audits and reporting
	// - Forensic investigation of tenant security incidents
	// - Operational analysis and optimization for specific tenants
	//
	// Parameters:
	// tenantID: Unique identifier for the tenant to query
	// options: Comprehensive query options with tenant-specific enhancements
	//
	// Returns:
	// audit.QueryResult: Comprehensive audit results for the tenant
	// error: nil on success, error on failure or authorization denial
	QueryTenantAuditLogs(tenantID string, options audit.QueryOptions) (audit.QueryResult, error)

	DeleteTenant(tenatID string) error
}

VaultManagerService provides multi-tenant vault orchestration and administration.

OVERVIEW: This service interface defines the administrative and orchestration layer for managing multiple isolated vault instances in a multi-tenant environment. It provides capabilities for tenant lifecycle management, bulk operations, comprehensive audit querying, and cross-tenant administrative functions.

ARCHITECTURAL ROLE: 

TENANT ISOLATION:
The service ensures complete isolation between tenants while providing
centralized management capabilities. Each tenant's vault operates
independently with its own encryption keys, audit trails, and access
controls, preventing any form of cross-tenant data leakage.

ADMINISTRATIVE ORCHESTRATION:
Bulk operations enable efficient management of multiple tenants
simultaneously, supporting enterprise-scale deployments where hundreds
or thousands of tenants require coordinated administrative actions.

AUDIT AGGREGATION:
The service provides both tenant-specific and cross-tenant audit
capabilities, enabling comprehensive security monitoring and compliance
reporting across the entire multi-tenant deployment.

SECURITY MODEL: 

PRINCIPLE OF LEAST PRIVILEGE:
Administrative operations require explicit authorization and are subject
to role-based access controls. The service supports delegation of
administrative privileges with fine-grained permission scoping.

AUDIT COMPLETENESS:
All administrative operations are fully audited with immutable audit
trails. Bulk operations create detailed audit records for each affected
tenant, enabling complete reconstruction of administrative actions.

TENANT BOUNDARY ENFORCEMENT:
The service enforces strict tenant boundaries and prevents unauthorized
cross-tenant access even by administrative users. Tenant isolation is
maintained at the cryptographic level with separate encryption keys.

OPERATIONAL CHARACTERISTICS: 

SCALABILITY:
The service is designed to support large-scale multi-tenant deployments
with thousands of tenants. Operations are optimized for concurrent
execution and can be distributed across multiple service instances.

RELIABILITY:
Bulk operations implement transactional semantics where possible, with
detailed error reporting and rollback capabilities. Failed operations
on individual tenants do not affect operations on other tenants.

PERFORMANCE:
The service includes caching and optimization strategies for frequently
accessed tenant data and audit information. Administrative operations
are designed to minimize impact on tenant-facing vault operations.

=============================================================================

func NewVaultManagerFileStore 

func NewVaultManagerFileStore(options Options, basePath string, auditLogger audit.Logger) VaultManagerService

NewVaultManagerFileStore creates a new instance of VaultManager configured to use a file-based storage system. This function initializes the VaultManager with the provided options, base path for the storage, and an audit logger for tracking actions and secret accesses.

Parameters:

  • options (Options): A structure containing critical configuration parameters for vault operation, including key derivation settings, passphrase handling, and memory protection options.

  • basePath (string): The directory path where vault data will be stored and managed. This path should be secure and accessible only to authorized users or processes.

  • auditLogger (audit.Logger): An implementation of the Logger interface that will handle audit logging for actions performed by the VaultManager, ensuring that operations can be tracked and monitored for security and compliance purposes.

Returns:

  • *VaultManager: A pointer to the newly created VaultManager instance, which is ready for use in managing tenant-specific vaults for encryption, decryption, and secure storage.

Usage Example: ```go 

options := Options{
   DerivationSalt: []byte("random-salt-here"),
   DerivationPassphrase: "secure-passphrase-here",
   EnvPassphraseVar: "VAULT_MASTER_PASSPHRASE",
   EnableMemoryLock: true,
   Debug: false,
}

auditLogger := myAuditLoggerImplementation() // Assume this implements audit.Logger. basePath := "/path/to/vault/storage"

vaultManager := NewVaultManagerFileStore(options, basePath, auditLogger)

// Now, vaultManager can be used to manage vault operations for different tenants.

func NewVaultManagerS3Store 

func NewVaultManagerS3Store(options Options, storeConfig persist.S3Config, auditLogger audit.Logger) (VaultManagerService, error)

NewVaultManagerS3Store initializes a new VaultManager instance configured to use an S3 storage backend.

Parameters: - options: Options that configure the vault management behavior. This includes settings such as the derivation salt and passphrase, the environment variable for the passphrase, whether memory locking is enabled, and a debug flag. - storeConfig: A persist.StoreConfig object that defines the configuration of the S3 storage, including the storage type and specific settings for the backend. - auditLogger: An audit.Logger implementation used for logging access and operations on the vaults.

Returns: - A pointer to an initialized VaultManager and an error. If the initialization is successful, error will be nil. If there are issues during initialization, an appropriate error will be returned.

Usage Example: ```go 

options := Options{
   DerivationSalt:       []byte("some_salt"),
   DerivationPassphrase: "securepass",
   EnvPassphraseVar:     "VAULT_PASSPHRASE",
   EnableMemoryLock:     true,
   Debug:                false,
}

storeConfig := StoreConfig{
   Type:   StoreTypeS3,
   Config: map[string]interface{}{"endpoint": "s3.example.com", "bucket": "vault-bucket"},
}

auditLogger := &MyAuditLogger{} // Your implementation of the audit.Logger

vaultManager, err := NewVaultManagerS3Store(options, storeConfig, auditLogger) 

if err != nil {
   log.Fatalf("Error initializing Vault Manager: %v", err)
}

// Use vaultManager as needed...

func NewVaultManagerWithStoreFactory 

func NewVaultManagerWithStoreFactory(baseOptions Options, storeFactory func(tenantID string) (persist.Store, error), auditLogger audit.Logger) VaultManagerService

NewVaultManagerWithStoreFactory creates a new vault manager instance with a custom store factory.

OVERVIEW: This constructor function creates a VaultManager instance with a configurable storage factory that enables custom storage backend implementations for each tenant. The store factory approach provides maximum flexibility for multi-tenant storage strategies, allowing different tenants to utilize different storage backends, configurations, or security policies based on their specific requirements or organizational constraints.

FACTORY PATTERN BENEFITS: 

STORAGE FLEXIBILITY:
The factory pattern enables dynamic storage backend selection during tenant vault creation.
Each tenant can use different storage implementations (file-based, cloud storage, databases,
HSMs, or custom backends) without requiring changes to the vault manager core logic.
This supports diverse deployment scenarios and tenant-specific storage requirements.

MULTI-TENANT ISOLATION:
The factory approach ensures complete storage isolation between tenants by creating
independent storage instances for each tenant. This prevents data leakage, supports
different security policies per tenant, and enables tenant-specific compliance requirements
such as data residency, encryption standards, or backup procedures.

CONFIGURATION FLEXIBILITY:
Different tenants can receive storage configurations optimized for their usage patterns,
performance requirements, or security policies. High-security tenants might use HSM-backed
storage while development tenants use file-based storage, all managed by the same
vault manager instance.

INITIALIZATION BEHAVIOR: 

LAZY TENANT CREATION:
The vault manager initializes with an empty tenant registry and creates tenant vaults
on-demand when first accessed. This approach minimizes startup time, reduces resource
consumption, and enables dynamic tenant provisioning without vault manager restarts.

STORAGE FACTORY VALIDATION:
The store factory function is validated during tenant vault creation, not during
manager initialization. This allows for dynamic storage configuration and supports
storage backends that may not be immediately available during manager startup.

BASE OPTIONS INHERITANCE:
All tenant vaults inherit the base cryptographic options (derivation parameters,
memory protection settings, debug configuration) while maintaining independent
storage through the factory-provided stores.

STORAGE FACTORY REQUIREMENTS: 

FACTORY FUNCTION SIGNATURE:
func(tenantID string) (persist.Store, error)

The factory receives the tenant ID and must return a configured storage instance
or an error if storage cannot be created. The factory is responsible for:
- Creating or connecting to appropriate storage backend
- Applying tenant-specific configuration and security policies
- Ensuring proper access controls and data isolation
- Handling storage initialization and connection errors

ERROR HANDLING:
Storage factory errors prevent tenant vault creation and are propagated to callers.
The factory should implement appropriate retry logic, connection pooling, and
error recovery mechanisms based on the storage backend characteristics.

THREAD SAFETY:
The storage factory may be called concurrently from multiple goroutines during
parallel tenant vault creation. The factory implementation must be thread-safe
and handle concurrent storage creation requests appropriately.

SECURITY CONSIDERATIONS: 

TENANT ISOLATION:
The factory must ensure complete storage isolation between tenants. Storage instances
returned for different tenants must not share data, connection pools, or access
credentials that could lead to cross-tenant data exposure or unauthorized access.

ACCESS CONTROL:
Each storage instance should implement appropriate access controls for its tenant.
Consider implementing storage-level authentication, authorization, and audit logging
to provide defense-in-depth security and compliance support.

CREDENTIAL MANAGEMENT:
Storage backend credentials and connection details should be managed securely,
preferably through integration with enterprise credential management systems.
Avoid hardcoded credentials and implement secure credential rotation procedures.

OPERATIONAL CONSIDERATIONS: 

RESOURCE MANAGEMENT:
The factory should implement appropriate resource management including connection
pooling, resource cleanup, and graceful shutdown procedures. Consider resource
limits and monitoring to prevent resource exhaustion in multi-tenant environments.

MONITORING AND OBSERVABILITY:
Implement comprehensive monitoring for storage factory operations including
creation success rates, error conditions, performance metrics, and resource
utilization. This supports operational visibility and troubleshooting.

BACKUP AND RECOVERY:
Consider backup and recovery requirements for factory-created storage instances.
Different storage backends may require different backup strategies and recovery
procedures, which should be documented and tested regularly.

COMMON USAGE PATTERNS: 

ENVIRONMENT-BASED STORAGE:
Different environments (development, staging, production) can use different
storage backends through factory logic that examines tenant IDs or configuration
to determine appropriate storage types and configurations.

PERFORMANCE TIERING:
High-performance tenants can receive SSD-backed or memory-cached storage while
archival tenants receive cost-optimized storage, all managed through factory
logic that examines tenant characteristics or service levels.

COMPLIANCE SEGMENTATION:
Tenants with different compliance requirements can receive appropriately
configured storage backends (encrypted, geographically constrained, audit-enabled)
through factory logic that applies compliance policies based on tenant metadata.

USAGE EXAMPLE: 

```go
// Create base vault options with security configuration
baseOptions := vault.Options{
    DerivationSalt:       generateSecureSalt(),
    DerivationPassphrase: "secure-master-passphrase",
    EnableMemoryLock:     true,
    Debug:                false,
}

// Create audit logger for compliance and security monitoring
auditLogger := audit.NewFileLogger("/var/log/vault/audit.log")

// Define storage factory with tenant-specific logic
storeFactory := func(tenantID string) (persist.Store, error) {
    // Example: Different storage strategies based on tenant type
    if strings.HasPrefix(tenantID, "enterprise-") {
        // Enterprise tenants get database-backed storage
        return persist.NewDatabaseStore(fmt.Sprintf("vault_tenant_%s", tenantID))
    } else if strings.HasPrefix(tenantID, "dev-") {
        // Development tenants get file-based storage
        return persist.NewFileStore(fmt.Sprintf("/data/vault/%s", tenantID))
    } else if strings.HasPrefix(tenantID, "secure-") {
        // High-security tenants get HSM-backed storage
        return persist.NewHSMStore(tenantID, hsmConfig)
    } else {
        // Default tenants get cloud storage
        return persist.NewS3Store(fmt.Sprintf("vault-tenant-%s", tenantID))
    }
}

// Create vault manager with custom storage factory
vaultManager := vault.NewVaultManagerWithStoreFactory(
    baseOptions,
    storeFactory,
    auditLogger,
)

// Tenants will automatically receive appropriate storage backends
enterpriseVault, err := vaultManager.GetTenantVault("enterprise-client-001")
if err != nil {
    log.Fatalf("Failed to create enterprise vault: %v", err)
}

devVault, err := vaultManager.GetTenantVault("dev-team-alpha")
if err != nil {
    log.Fatalf("Failed to create development vault: %v", err)
}

secureVault, err := vaultManager.GetTenantVault("secure-gov-agency")
if err != nil {
    log.Fatalf("Failed to create secure vault: %v", err)
}
```

ERROR SCENARIOS: 

STORAGE FACTORY FAILURES:
When the storage factory returns an error, tenant vault creation fails and
the error is propagated to the caller. Implement appropriate error handling
and retry logic in calling code for resilient operation.

CONFIGURATION ERRORS:
Invalid base options or audit logger configuration will result in vault
creation failures. Validate configuration parameters before creating the
vault manager to ensure proper initialization.

RESOURCE EXHAUSTION:
In high-tenant environments, consider implementing resource limits and
monitoring to prevent excessive resource consumption from large numbers
of storage instances and vault operations.

Parameters: 

baseOptions: Cryptographic and operational configuration inherited by all tenant vaults
storeFactory: Factory function that creates tenant-specific storage backends
auditLogger: Centralized audit logging instance for security and compliance

Returns: 

VaultManagerService: Configured vault manager ready for multi-tenant operations

type VaultService 

type VaultService interface {

	// Encrypt encrypts plaintext data using the current active key.
	//
	// The returned string is a base64 encoded representation that includes
	// the KeyID necessary for decryption in a non-malleable format.
	// The ciphertext includes authentication data to detect tampering.
	//
	// Parameters:
	//   - plaintext: The data to encrypt (any byte sequence)
	//
	// Returns:
	//   - ciphertextWithKeyID: Base64-encoded ciphertext with embedded key identifier
	//   - err: Error if encryption fails (no active key, cryptographic failure, etc.)
	//
	// Security Notes:
	//   - A fresh nonce is generated for each encryption operation
	//   - The same plaintext will produce different ciphertexts each time
	//   - The KeyID is authenticated as part of the ciphertext to prevent substitution attacks
	//
	// Example:
	//   ciphertext, err := vault.Encrypt([]byte("my secret data"))
	//   if err != nil {
	//       return fmt.Errorf("encryption failed: %w", err)
	//   }
	Encrypt(plaintext []byte) (ciphertextWithKeyID string, err error)

	// Decrypt decrypts data that was previously encrypted by this vault instance
	// (or another instance sharing the same underlying key material and metadata).
	//
	// It automatically identifies the correct key using the KeyID embedded
	// in the ciphertext and verifies the authentication tag to detect tampering.
	//
	// Parameters:
	//   - base64CiphertextWithKeyID: The base64-encoded ciphertext returned by Encrypt
	//
	// Returns:
	//   - plaintext: The original data that was encrypted
	//   - err: Error if decryption fails (invalid format, wrong key, authentication failure, etc.)
	//
	// Security Notes:
	//   - Authentication is verified before returning any plaintext
	//   - Timing attacks are mitigated through constant-time operations
	//   - Invalid ciphertexts fail fast without revealing information about keys or plaintext
	//
	// Example:
	//   plaintext, err := vault.Decrypt(ciphertext)
	//   if err != nil {
	//       return fmt.Errorf("decryption failed: %w", err)
	//   }
	//   fmt.Printf("Secret: %s\n", string(plaintext))
	Decrypt(base64CiphertextWithKeyID string) (plaintext []byte, err error)

	// RotateDataEncryptionKey generates a new data encryption key (DEK), makes it the active key for
	// new encryptions, and deactivates the previously active key (marking it as inactive).
	//
	// The old key remains available for decrypting existing data, ensuring no data loss.
	// This operation should be performed regularly as part of key lifecycle management.
	//
	// Parameters:
	//   - reason: Human-readable explanation for the key rotation (for audit logs)
	//
	// Returns:
	//   - KeyMetadata: Metadata for the newly created active key
	//   - error: Error if rotation fails (entropy issues, storage problems, etc.)
	//
	// Security Notes:
	//   - New keys use cryptographically secure random generation
	//   - The operation is atomic - either fully succeeds or leaves the vault unchanged
	//   - All key state changes are logged for audit purposes
	//
	// Example:
	//   metadata, err := vault.RotateDataEncryptionKey("scheduled monthly rotation")
	//   if err != nil {
	//       return fmt.Errorf("key rotation failed: %w", err)
	//   }
	//   fmt.Printf("New active key: %s\n", metadata.KeyID)
	RotateDataEncryptionKey(reason string) (*KeyMetadata, error)

	// DestroyKey permanently removes an inactive key and its material from the vault.
	//
	// Once a key is destroyed, any data encrypted solely with this key will be
	// irrecoverable by the vault. This operation is irreversible and should only
	// be performed after ensuring no encrypted data depends on the key.
	//
	// Parameters:
	//   - keyID: The identifier of the key to destroy (must be inactive)
	//
	// Returns:
	//   - error: Error if destruction fails (key is active, key not found, etc.)
	//
	// Security Notes:
	//   - Key material is securely wiped from memory and storage
	//   - The operation is logged for audit and compliance purposes
	//   - Attempting to destroy the active key returns an error
	//
	// Example:
	//   err := vault.DestroyKey("old-key-id-123")
	//   if err != nil {
	//       return fmt.Errorf("key destruction failed: %w", err)
	//   }
	DestroyKey(keyID string) error

	// Backup creates an encrypted backup of all non-decommissioned keys,
	// their operational metadata, and the vault's derivation salt to the
	// specified destination directory.
	//
	// This backup's key material is encrypted using the vault's Key Encryption Key (KEK),
	// which is derived from the vault's passphrase and the (now backed up) salt.
	// This provides a comprehensive backup for vault recovery scenarios.
	//
	// Parameters:
	//   - destinationDir: Directory where backup files will be created
	//   - passphrase: Passphrase used to encrypt the backup (should be strong and securely stored)
	//
	// Returns:
	//   - error: Error if backup fails (I/O issues, encryption problems, etc.)
	//
	// Backup Structure:
	//   - destinationDir/keys/ - Encrypted key material files
	//   - destinationDir/metadata.enc - Encrypted key metadata
	//   - destinationDir/derivation.salt.backup - Key derivation salt
	//
	// Security Notes:
	//   - All sensitive data in the backup is encrypted
	//   - The backup passphrase should be different from the vault passphrase
	//   - Backup integrity can be verified before attempting restoration
	//
	// Example:
	//   err := vault.Backup("/secure/backup/location", "strong-backup-passphrase")
	//   if err != nil {
	//       return fmt.Errorf("backup failed: %w", err)
	//   }
	Backup(destinationDir, passphrase string) error

	// Restore recovers vault state from a previously created backup.
	//
	// This operation reconstructs the vault's keys, metadata, and derivation salt
	// from encrypted backup files. The vault instance should be newly created
	// or reset before calling this method.
	//
	// Parameters:
	//   - destinationDir: Directory containing the backup files
	//   - passphrase: Passphrase used when creating the backup
	//
	// Returns:
	//   - error: Error if restoration fails (wrong passphrase, corrupted backup, etc.)
	//
	// Security Notes:
	//   - The correct backup passphrase is required for successful restoration
	//   - Backup integrity is verified before applying any changes
	//   - The operation is atomic - either fully succeeds or leaves vault unchanged
	//
	// Example:
	//   err := vault.Restore("/secure/backup/location", "strong-backup-passphrase")
	//   if err != nil {
	//       return fmt.Errorf("restore failed: %w", err)
	//   }
	Restore(destinationDir, passphrase string) error

	// ListKeyMetadata returns metadata for all known keys managed by the vault,
	// including active, inactive, and decommissioned keys.
	//
	// This provides visibility into the vault's key lifecycle state and supports
	// key management operations like rotation scheduling and cleanup.
	//
	// Returns:
	//   - []KeyMetadata: List of metadata for all keys (actual key material not included)
	//   - error: Error if metadata retrieval fails
	//
	// The returned metadata includes creation times, status, usage statistics,
	// and other operational information but never includes actual key material.
	//
	// Example:
	//   keys, err := vault.ListKeyMetadata()
	//   if err != nil {
	//       return err
	//   }
	//   for _, key := range keys {
	//       fmt.Printf("Key %s: %s (created %v)\n", key.KeyID, key.Status, key.CreatedAt)
	//   }
	ListKeyMetadata() ([]KeyMetadata, error)

	// GetActiveKeyMetadata returns the metadata for the key currently
	// active for encryption operations.
	//
	// Returns:
	//   - KeyMetadata: Metadata for the active key
	//   - error: Error if no key is active or metadata retrieval fails
	//
	// This is useful for monitoring key age, planning rotations, and
	// understanding current encryption capabilities.
	//
	// Example:
	//   activeKey, err := vault.GetActiveKeyMetadata()
	//   if err != nil {
	//       return fmt.Errorf("no active key available: %w", err)
	//   }
	//   fmt.Printf("Active key %s created %v\n", activeKey.KeyID, activeKey.CreatedAt)
	GetActiveKeyMetadata() (KeyMetadata, error)

	// StoreSecret encrypts and stores secret data with optional metadata.
	//
	// The secret data is encrypted using the current active key and stored
	// with rich metadata for lifecycle management and organization.
	//
	// Parameters:
	//   - secretID: Unique identifier for the secret (must be unique within the vault)
	//   - secretData: The actual secret data to encrypt and store
	//   - tags: Optional tags for categorization and filtering
	//   - contentType: The type/format of the secret data
	//
	// Returns:
	//   - *SecretMetadata: Metadata for the stored secret (including generated fields)
	//   - error: Error if storage fails (duplicate ID, encryption failure, etc.)
	//
	// Security Notes:
	//   - Secret data is encrypted before being written to storage
	//   - Metadata includes integrity checksums for tamper detection
	//   - All operations are logged for audit purposes
	//
	// Example:
	//   metadata, err := vault.StoreSecret(
	//       "database-password",
	//       []byte("super-secret-password"),
	//       []string{"database", "production"},
	//       volta.ContentTypeText,
	//   )
	//   if err != nil {
	//       return fmt.Errorf("failed to store secret: %w", err)
	//   }
	StoreSecret(secretID string, secretData []byte, tags []string, contentType ContentType) (*SecretMetadata, error)

	GetSecret(secretID string) (*SecretResult, error)

	// UpdateSecret updates existing secret data and increments the version number.
	//
	// This operation preserves the original creation timestamp while updating
	// the modification timestamp and version number.
	//
	// Parameters:
	//   - secretID: The unique identifier of the secret to update
	//   - secretData: The new secret data to encrypt and store
	//   - tags: Updated tags (replaces existing tags)
	//   - contentType: Updated content type
	//
	// Returns:
	//   - *SecretMetadata: Updated metadata reflecting the changes
	//   - error: Error if update fails (secret not found, encryption failure, etc.)
	//
	// Security Notes:
	//   - Old secret data is securely overwritten
	//   - Version numbers prevent lost update problems
	//   - All changes are logged for audit purposes
	//
	// Example:
	//   metadata, err := vault.UpdateSecret(
	//       "database-password",
	//       []byte("new-super-secret-password"),
	//       []string{"database", "production", "rotated"},
	//       volta.ContentTypeText,
	//   )
	//   if err != nil {
	//       return fmt.Errorf("failed to update secret: %w", err)
	//   }
	//   fmt.Printf("Secret updated to version %d\n", metadata.Version)
	UpdateSecret(secretID string, secretData []byte, tags []string, contentType ContentType) (*SecretMetadata, error)

	// DeleteSecret removes a secret and its metadata from the vault.
	//
	// This operation is irreversible. Once deleted, the secret cannot be recovered
	// without restoring from a backup.
	//
	// Parameters:
	//   - secretID: The unique identifier of the secret to delete
	//
	// Returns:
	//   - error: Error if deletion fails (secret not found, storage error, etc.)
	//
	// Security Notes:
	//   - Secret data is securely wiped from storage
	//   - The operation is logged for audit purposes
	//   - Deletion is atomic - either fully succeeds or leaves data unchanged
	//
	// Example:
	//   err := vault.DeleteSecret("old-api-key")
	//   if err != nil {
	//       return fmt.Errorf("failed to delete secret: %w", err)
	//   }
	DeleteSecret(secretID string) error

	// SecretExists checks if a secret exists without retrieving its data.
	//
	// This is useful for conditional operations and avoiding unnecessary
	// decryption operations when only existence needs to be verified.
	//
	// Parameters:
	//   - secretID: The unique identifier to check
	//
	// Returns:
	//   - bool: true if the secret exists, false otherwise
	//   - error: Error if the existence check fails (storage error, etc.)
	//
	// Security Notes:
	//   - No secret data is decrypted during this operation
	//   - The check may still be logged for audit purposes
	//
	// Example:
	//   exists, err := vault.SecretExists("api-key")
	//   if err != nil {
	//       return fmt.Errorf("existence check failed: %w", err)
	//   }
	//   if !exists {
	//       // Create the secret
	//   }
	SecretExists(secretID string) (bool, error)

	// ListSecrets returns secret metadata based on filter options.
	//
	// This operation provides efficient querying and pagination over large
	// secret collections without decrypting any actual secret data.
	//
	// Parameters:
	//   - options: Filter and pagination options (nil for default behavior)
	//
	// Returns:
	//   - []*SecretListEntry: List of matching secrets (without encrypted data)
	//   - error: Error if listing fails (storage error, invalid options, etc.)
	//
	// The returned entries include all metadata but exclude the encrypted
	// secret payload for security and performance reasons.
	//
	// Example:
	//   options := &volta.SecretListOptions{
	//       Tags: []string{"production"},
	//       Prefix: "api-",
	//       Limit: 50,
	//   }
	//   secrets, err := vault.ListSecrets(options)
	//   if err != nil {
	//       return fmt.Errorf("failed to list secrets: %w", err)
	//   }
	//   for _, secret := range secrets {
	//       fmt.Printf("%s: %s (v%d)\n", secret.ID, secret.Metadata.Description, secret.Version)
	//   }
	ListSecrets(options *SecretListOptions) ([]*SecretListEntry, error)

	// GetSecretMetadata returns only the metadata for a secret without decrypting the data.
	//
	// This is useful for displaying secret information, checking expiration,
	// or performing management operations without the overhead of decryption.
	//
	// Parameters:
	//   - secretID: The unique identifier of the secret
	//
	// Returns:
	//   - *SecretMetadata: Complete metadata for the secret
	//   - error: Error if metadata retrieval fails (secret not found, etc.)
	//
	// Security Notes:
	//   - No secret data is decrypted during this operation
	//   - Access may still be logged for audit purposes
	//   - Metadata itself is stored encrypted and decrypted for this operation
	//
	// Example:
	//   metadata, err := vault.GetSecretMetadata("database-password")
	//   if err != nil {
	//       return fmt.Errorf("failed to get metadata: %w", err)
	//   }
	//   if metadata.ExpiresAt != nil && metadata.ExpiresAt.Before(time.Now()) {
	//       fmt.Printf("Warning: Secret %s has expired\n", secretID)
	//   }
	GetSecretMetadata(secretID string) (*SecretMetadata, error)

	// Close securely wipes all sensitive key material (active key, KEK candidate, salt cache)
	// from the vault's memory and releases associated resources.
	//
	// After Close() is called, the vault instance becomes unusable and any further
	// calls to its methods will likely result in errors. This method should be called
	// when the vault is no longer needed to prevent keys from lingering in memory.
	//
	// Returns:
	//   - error: Error if cleanup fails (though the vault should still be considered closed)
	//
	// Security Notes:
	//   - All cryptographic key material is securely zeroed in memory
	//   - File handles and other resources are properly released
	//   - The operation is idempotent - safe to call multiple times
	//   - Memory protection mechanisms are disabled after successful close
	//
	// Example:
	//   vault, err := volta.New(config)
	//   if err != nil {
	//       return err
	//   }
	//   defer func() {
	//       if err := vault.Close(); err != nil {
	//           log.Printf("Warning: vault cleanup failed: %v", err)
	//       }
	//   }()
	Close() error

	// UseSecret executes a function with a secret and ensures automatic cleanup.
	//
	// This is the RECOMMENDED method for accessing secrets securely. The secret data
	// is automatically cleared from memory when the function returns, regardless of
	// success or failure.
	//
	// Parameters:
	//   - secretID: Unique identifier for the secret (e.g., "api/keys/stripe", "db/credentials/prod")
	//   - fn: Function to execute with the secret data. The data slice is only valid
	//         within this function and will be cleared immediately after return.
	//
	// Returns:
	//   - error: Returns any error from secret retrieval or from the executed function
	//
	// Security Notes:
	//   - Secret data is stored in secure memory and cleared with multiple overwrites
	//   - Data is automatically zeroed even if the function panics
	//   - The data slice becomes invalid after the function returns
	//   - Memory is force garbage collected after clearing
	//
	// Examples:
	//
	//	// Database connection
	//	err := vault.UseSecret("db/password", func(password []byte) error {
	//	    dsn := fmt.Sprintf("user=app password=%s host=localhost", string(password))
	//	    db, err := sql.Open("postgres", dsn)
	//	    if err != nil {
	//	        return err
	//	    }
	//	    defer db.Close()
	//	    return db.Ping()
	//	})
	//
	//	// API authentication
	//	err := vault.UseSecret("api/token", func(token []byte) error {
	//	    req.Header.Set("Authorization", "Bearer "+string(token))
	//	    return client.Do(req)
	//	})
	//
	//	// File encryption
	//	err := vault.UseSecret("encryption/key", func(key []byte) error {
	//	    cipher, err := aes.NewCipher(key)
	//	    if err != nil {
	//	        return err
	//	    }
	//	    return encryptFile(cipher, inputFile, outputFile)
	//	})
	//
	// Best Practices:
	//   - Do NOT store references to the data slice outside the function
	//   - Do NOT copy the data to long-lived variables without proper clearing
	//   - Process the secret immediately within the function
	//   - Keep the function execution time as short as possible
	//
	// Thread Safety: Safe for concurrent use
	UseSecret(secretID string, fn func(data []byte) error) error

	// UseSecretWithTimeout executes a function with a secret with automatic timeout.
	//
	// Similar to UseSecret but with a timeout mechanism. If the function execution
	// exceeds the timeout, the context is cancelled and the secret is immediately
	// cleared from memory.
	//
	// Parameters:
	//   - secretID: Unique identifier for the secret
	//   - timeout: Maximum duration to wait for function completion
	//   - fn: Function to execute with the secret data
	//
	// Returns:
	//   - error: Returns context.DeadlineExceeded if timeout occurs,
	//            retrieval errors, or errors from the executed function
	//
	// Security Notes:
	//   - All security guarantees of UseSecret apply
	//   - Secret is cleared immediately when timeout occurs
	//   - Function execution is monitored via goroutine
	//   - Panic recovery ensures cleanup even on function panic
	//
	// Examples:
	//
	//	// API call with timeout
	//	err := vault.UseSecretWithTimeout("api/key", 30*time.Second, func(key []byte) error {
	//	    client := &http.Client{Timeout: 25 * time.Second}
	//	    req.Header.Set("X-API-Key", string(key))
	//	    resp, err := client.Do(req)
	//	    if err != nil {
	//	        return err
	//	    }
	//	    defer resp.Body.Close()
	//	    return processResponse(resp)
	//	})
	//	if err == context.DeadlineExceeded {
	//	    log.Println("API call timed out")
	//	}
	//
	//	// Database operation with timeout
	//	err := vault.UseSecretWithTimeout("db/password", 10*time.Second, func(pwd []byte) error {
	//	    ctx, cancel := context.WithTimeout(context.Background(), 8*time.Second)
	//	    defer cancel()
	//	    return performDatabaseOperation(ctx, string(pwd))
	//	})
	//
	// Use Cases:
	//   - Network operations that might hang
	//   - Database queries with unknown execution time
	//   - External service calls
	//   - Any operation where you need guaranteed cleanup time
	//
	// Thread Safety: Safe for concurrent use
	UseSecretWithTimeout(secretID string, timeout time.Duration, fn func(data []byte) error) error

	// UseSecretWithContext executes a function with a secret using a custom context.
	//
	// Provides full context control for secret usage. The secret is cleared when
	// the function completes OR when the context is cancelled, whichever comes first.
	//
	// Parameters:
	//   - ctx: Context for controlling execution (cancellation, timeout, deadlines)
	//   - secretID: Unique identifier for the secret
	//   - fn: Function to execute with the secret data
	//
	// Returns:
	//   - error: Returns context errors (Cancelled, DeadlineExceeded),
	//            retrieval errors, or errors from the executed function
	//
	// Context Behavior:
	//   - If context is already cancelled, returns immediately with context error
	//   - If context is cancelled during execution, function may continue but
	//     secret will be cleared when context cancellation is detected
	//   - Function execution happens in separate goroutine to monitor context
	//
	// Security Notes:
	//   - All security guarantees of UseSecret apply
	//   - Context cancellation triggers immediate secret clearing
	//   - Goroutine-safe execution with panic recovery
	//   - Secret clearing is guaranteed regardless of context state
	//
	// Examples:
	//
	//	// User-cancellable operation
	//	ctx, cancel := context.WithCancel(context.Background())
	//	go func() {
	//	    <-userCancelSignal
	//	    cancel()
	//	}()
	//	err := vault.UseSecretWithContext(ctx, "crypto/key", func(key []byte) error {
	//	    return performLongCryptographicOperation(key)
	//	})
	//
	//	// Request-scoped secret usage
	//	func handleRequest(w http.ResponseWriter, r *http.Request) {
	//	    err := vault.UseSecretWithContext(r.Context(), "api/secret", func(secret []byte) error {
	//	        return callDownstreamService(r.Context(), secret)
	//	    })
	//	    if err != nil {
	//	        http.Error(w, "Service unavailable", 503)
	//	    }
	//	}
	//
	//	// Batch processing with cancellation
	//	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	//	defer cancel()
	//	err := vault.UseSecretWithContext(ctx, "batch/key", func(key []byte) error {
	//	    for _, item := range batchItems {
	//	        select {
	//	        case <-ctx.Done():
	//	            return ctx.Err()
	//	        default:
	//	            if err := processItem(item, key); err != nil {
	//	                return err
	//	            }
	//	        }
	//	    }
	//	    return nil
	//	})
	//
	// Use Cases:
	//   - Request-scoped operations in web servers
	//   - User-cancellable long-running operations
	//   - Integration with existing context-aware code
	//   - Complex timeout and deadline scenarios
	//
	// Thread Safety: Safe for concurrent use
	UseSecretWithContext(ctx context.Context, secretID string, fn func(data []byte) error) error

	// UseSecretString executes a function with a secret as a string and ensures cleanup.
	//
	// Convenience method for secrets that are naturally string-based (passwords,
	// tokens, keys, etc.). Provides the same security guarantees as UseSecret
	// but with string handling.
	//
	// Parameters:
	//   - secretID: Unique identifier for the secret
	//   - fn: Function to execute with the secret string. The string is only valid
	//         within this function and underlying memory is cleared after return.
	//
	// Returns:
	//   - error: Returns any error from secret retrieval or from the executed function
	//
	// Security Notes:
	//   - String and underlying byte data are both securely cleared
	//   - Multiple memory overwrites before zeroing
	//   - Automatic cleanup even on function panic
	//   - String becomes invalid/empty after function returns
	//
	// Examples:
	//
	//	// JWT token usage
	//	err := vault.UseSecretString("auth/jwt-secret", func(secret string) error {
	//	    token := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	//	    tokenString, err := token.SignedString([]byte(secret))
	//	    if err != nil {
	//	        return err
	//	    }
	//	    return sendTokenToClient(tokenString)
	//	})
	//
	//	// Password validation
	//	err := vault.UseSecretString("users/admin/password", func(password string) error {
	//	    if !validatePasswordComplexity(password) {
	//	        return fmt.Errorf("password does not meet complexity requirements")
	//	    }
	//	    return updateUserPassword("admin", password)
	//	})
	//
	//	// Configuration with secrets
	//	err := vault.UseSecretString("config/database-url", func(dbURL string) error {
	//	    config := &AppConfig{
	//	        DatabaseURL: dbURL,
	//	        // ... other config
	//	    }
	//	    return initializeApplication(config)
	//	})
	//
	//	// API key usage
	//	err := vault.UseSecretString("external/api-key", func(apiKey string) error {
	//	    client := externalapi.NewClient(apiKey)
	//	    result, err := client.FetchData()
	//	    if err != nil {
	//	        return err
	//	    }
	//	    return processExternalData(result)
	//	})
	//
	// Best Practices:
	//   - Do NOT assign the string to variables outside the function
	//   - Do NOT store the string in structs that outlive the function
	//   - Process string-based secrets immediately
	//   - Use for passwords, tokens, URLs with embedded secrets, etc.
	//
	// Thread Safety: Safe for concurrent use
	UseSecretString(secretID string, fn func(secret string) error) error

	// GetSecretWithTimeout retrieves a secret with automatic timeout-based cleanup.
	//
	// ADVANCED METHOD: Returns a SecretWithContext that provides direct access to
	// secret data but with automatic cleanup when the timeout expires. Use this
	// when you need persistent access to secret data across multiple operations
	// within a time limit.
	//
	// Parameters:
	//   - secretID: Unique identifier for the secret
	//   - timeout: Duration after which the secret will be automatically cleared
	//
	// Returns:
	//   - *SecretWithContext: Object providing access to secret data and metadata
	//   - error: Any error from secret retrieval
	//
	// IMPORTANT: Always call Close() on the returned SecretWithContext to ensure
	// immediate cleanup. The timeout provides a safety net but should not be
	// relied upon for timely cleanup.
	//
	// SecretWithContext Methods:
	//   - Data() []byte - Returns secret data (nil after timeout/close)
	//   - Metadata() *SecretMetadata - Returns secret metadata
	//   - Done() <-chan struct{} - Channel that closes when timeout occurs
	//   - Close() - Immediately clear secret and cancel timeout
	//   - IsCleared() bool - Check if secret has been cleared
	//
	// Security Notes:
	//   - Secret is automatically cleared when timeout expires
	//   - Background goroutine monitors timeout
	//   - Memory is securely overwritten on cleanup
	//   - Close() should be called for immediate cleanup
	//   - Data() returns nil after timeout or close
	//
	// Examples:
	//
	//	// Multi-step operation with timeout
	//	secretCtx, err := vault.GetSecretWithTimeout("crypto/key", 5*time.Minute)
	//	if err != nil {
	//	    return err
	//	}
	//	defer secretCtx.Close() // Always cleanup
	//
	//	// Step 1: Initialize
	//	cipher, err := aes.NewCipher(secretCtx.Data())
	//	if err != nil {
	//	    return err
	//	}
	//
	//	// Step 2: Process multiple files
	//	for _, file := range filesToEncrypt {
	//	    select {
	//	    case <-secretCtx.Done():
	//	        return fmt.Errorf("operation timed out")
	//	    default:
	//	        if err := encryptFile(cipher, file); err != nil {
	//	            return err
	//	        }
	//	    }
	//	}
	//
	//	// Connection pooling with secret rotation
	//	secretCtx, err := vault.GetSecretWithTimeout("db/password", 1*time.Hour)
	//	if err != nil {
	//	    return err
	//	}
	//	defer secretCtx.Close()
	//
	//	pool := &ConnectionPool{}
	//	for {
	//	    select {
	//	    case <-secretCtx.Done():
	//	        // Secret expired, need to refresh
	//	        pool.Close()
	//	        return refreshSecret()
	//	    case req := <-connectionRequests:
	//	        conn := pool.GetConnection(secretCtx.Data())
	//	        go handleRequest(conn, req)
	//	    }
	//	}
	//
	// Use Cases:
	//   - Multi-step operations requiring the same secret
	//   - Connection pools with authentication
	//   - Batch processing with time limits
	//   - Operations where UseSecret callback pattern is insufficient
	//
	// Thread Safety: Safe for concurrent use. The returned SecretWithContext
	// is also thread-safe for read operations.
	//
	// WARNING: This method provides direct access to secret data. Ensure proper
	// cleanup and do not store references beyond the intended lifetime.
	GetSecretWithTimeout(secretID string, timeout time.Duration) (*SecretWithContext, error)

	// GetSecretWithContext retrieves a secret with custom context-based cleanup.
	//
	// ADVANCED METHOD: Returns a SecretWithContext tied to the provided context.
	// The secret is automatically cleared when the context is cancelled or expires.
	// Use this for integrating secret access with existing context-aware code.
	//
	// Parameters:
	//   - ctx: Context controlling the secret lifetime
	//   - secretID: Unique identifier for the secret
	//
	// Returns:
	//   - *SecretWithContext: Object providing access to secret data and metadata
	//   - error: Any error from secret retrieval
	//
	// IMPORTANT: The returned SecretWithContext will be automatically cleared when
	// the provided context is cancelled. Always call Close() for immediate cleanup
	// if needed before context cancellation.
	//
	// Context Behavior:
	//   - Secret is cleared when context is cancelled/expires
	//   - If context is already cancelled, secret is still retrieved but immediately scheduled for cleanup
	//   - Child context is created to avoid affecting parent context
	//   - Background goroutine monitors context state
	//
	// Security Notes:
	//   - All security guarantees of GetSecretWithTimeout apply
	//   - Context cancellation triggers immediate secure cleanup
	//   - Data() returns nil after context cancellation or Close()
	//   - Memory is securely overwritten on cleanup
	//
	// Examples:
	//
	//	// Request-scoped database access
	//	func handleDatabaseRequest(ctx context.Context, query string) error {
	//	    secretCtx, err := vault.GetSecretWithContext(ctx, "db/credentials")
	//	    if err != nil {
	//	        return err
	//	    }
	//	    defer secretCtx.Close()
	//
	//	    db, err := sql.Open("postgres", buildDSN(secretCtx.Data()))
	//	    if err != nil {
	//	        return err
	//	    }
	//	    defer db.Close()
	//
	//	    return db.QueryRowContext(ctx, query).Scan(&result)
	//	}
	//
	//	// Background service with graceful shutdown
	//	func runBackgroundService(ctx context.Context) error {
	//	    secretCtx, err := vault.GetSecretWithContext(ctx, "service/api-key")
	//	    if err != nil {
	//	        return err
	//	    }
	//	    defer secretCtx.Close()
	//
	//	    client := api.NewClient(string(secretCtx.Data()))
	//	    ticker := time.NewTicker(30 * time.Second)
	//	    defer ticker.Stop()
	//
	//	    for {
	//	        select {
	//	        case <-ctx.Done():
	//	            return ctx.Err()
	//	        case <-secretCtx.Done():
	//	            return fmt.Errorf("secret context expired")
	//	        case <-ticker.C:
	//	            if err := performPeriodicTask(client); err != nil {
	//	                return err
	//	            }
	//	        }
	//	    }
	//	}
	//
	//	// Stream processing with cancellation
	//	func processStream(ctx context.Context, stream <-chan Data) error {
	//	    secretCtx, err := vault.GetSecretWithContext(ctx, "encryption/key")
	//	    if err != nil {
	//	        return err
	//	    }
	//	    defer secretCtx.Close()
	//
	//	    cipher, err := aes.NewCipher(secretCtx.Data())
	//	    if err != nil {
	//	        return err
	//	    }
	//
	//	    for {
	//	        select {
	//	        case <-ctx.Done():
	//	            return ctx.Err()
	//	        case data, ok := <-stream:
	//	            if !ok {
	//	                return nil // Stream closed
	//	            }
	//	            if err := processData(cipher, data); err != nil {
	//	                return err
	//	            }
	//	        }
	//	    }
	//	}
	//
	// Use Cases:
	//   - Request-scoped operations in web applications
	//   - Background services with graceful shutdown
	//   - Stream processing with cancellation
	//   - Integration with existing context-aware APIs
	//   - Long-running operations that can be cancelled
	//
	// Thread Safety: Safe for concurrent use. The returned SecretWithContext
	// is also thread-safe for read operations.
	//
	// Best Practices:
	//   - Always use defer secretCtx.Close() immediately after creation
	//   - Monitor secretCtx.Done() channel in long-running operations
	//   - Do not store secretCtx beyond the lifetime of the controlling context
	//   - Use IsCleared() to check secret state in error conditions
	//
	// WARNING: This method provides direct access to secret data. The secret
	// remains in memory until context cancellation or Close() is called.
	GetSecretWithContext(ctx context.Context, secretID string) (*SecretWithContext, error)

	// UseSecrets provides secure access to multiple secrets within a single callback.
	//
	// OVERVIEW:
	// This method extends Volta's secure callback pattern to operations requiring
	// multiple secrets simultaneously. It implements atomic retrieval semantics
	// where all secrets must be successfully loaded before any are exposed to the
	// callback, preventing partial secret exposure in error scenarios.
	//
	// CORE PRINCIPLES:
	//
	//   ALL-OR-NOTHING RETRIEVAL:
	//   Either all requested secrets are successfully retrieved and made available
	//   to the callback, or the operation fails completely with no secrets exposed.
	//   This prevents scenarios where some secrets are accessible while others fail,
	//   which could lead to incomplete operations or security vulnerabilities.
	//
	//   SYNCHRONIZED LIFECYCLE:
	//   All secrets share the same lifecycle within the callback scope. They are
	//   simultaneously opened before callback execution and simultaneously destroyed
	//   after callback completion, ensuring no temporal security gaps where some
	//   secrets remain in memory while others are cleared.
	//
	//   MEMGUARD PROTECTION PER SECRET:
	//   Each secret is independently protected using memguard's secure memory
	//   allocation, providing per-secret isolation while maintaining collective
	//   security guarantees. Memory corruption or attacks against one secret
	//   cannot compromise others.
	//
	// SECURITY MODEL:
	// - Atomic exposure (all secrets available simultaneously)
	// - Atomic cleanup (all secrets cleared simultaneously)
	// - Individual memory protection for each secret
	// - Guaranteed cleanup on panic or error conditions
	// - No residual data in system memory after completion
	//
	// USE CASES:
	// • Multi-factor authentication (password + TOTP seed + backup codes)
	// • Cryptographic operations (private key + certificate + CA chain)
	// • API orchestration (primary token + refresh token + service keys)
	// • Database clustering (primary credentials + replica credentials + admin key)
	// • Multi-tenant operations requiring tenant-specific secrets
	//
	// Parameters:
	//   secretIDs: Array of unique secret identifiers. Duplicates will cause error.
	//   fn: Callback receiving map[secretID]secretData for all requested secrets.
	//
	// Returns:
	//   error: nil on success, detailed error on retrieval or callback failure.
	UseSecrets(secretIDs []string, fn func(secrets map[string][]byte) error) error

	// UseSecretsString provides secure access to multiple secrets as UTF-8 strings.
	//
	// OVERVIEW:
	// String-optimized variant of UseSecrets designed specifically for text-based
	// secrets such as passwords, API keys, tokens, and configuration values. This
	// method provides the same security guarantees as UseSecrets while eliminating
	// the need for manual byte-to-string conversion within the callback.
	//
	// STRING HANDLING GUARANTEES:
	//
	//   SECURE CONVERSION:
	//   Byte-to-string conversion occurs within the memguard-protected memory
	//   context, ensuring no intermediate string copies exist in unprotected
	//   heap memory. The string data remains under memguard protection throughout
	//   the callback execution.
	//
	//   UTF-8 SAFETY:
	//   All secrets are treated as UTF-8 encoded strings. Invalid UTF-8 sequences
	//   are handled according to Go's standard string conversion semantics, with
	//   replacement characters used for invalid bytes.
	//
	//   STRING POOL ISOLATION:
	//   The converted strings are ephemeral and do not enter Go's string literal
	//   pool, preventing long-term retention in program memory beyond the callback
	//   scope. Each invocation creates fresh string instances.
	//
	// PERFORMANCE CHARACTERISTICS:
	// - Zero-copy string creation where possible
	// - Batch conversion of all secrets before callback execution
	// - Optimized for scenarios with multiple text-based secrets
	// - Memory overhead equivalent to UseSecrets plus string headers
	//
	// USE CASES:
	// • Configuration management (database URLs + API endpoints + service tokens)
	// • Authentication flows (username + password + MFA codes)
	// • Multi-service API integration (service keys + authentication tokens)
	// • Certificate processing (PEM-encoded certificates + private keys)
	// • Multi-environment deployments (environment-specific credentials)
	//
	// Parameters:
	//   secretIDs: Array of unique secret identifiers for text-based secrets.
	//   fn: Callback receiving map[secretID]secretString for all requested secrets.
	//
	// Returns:
	//   error: nil on success, detailed error on retrieval or callback failure.
	UseSecretsString(secretIDs []string, fn func(secrets map[string]string) error) error

	// UseSecretPair provides secure access to exactly two secrets with ergonomic API.
	//
	// OVERVIEW:
	// Specialized variant optimized for the common pattern of operations requiring
	// exactly two secrets, such as public/private key pairs, username/password
	// combinations, or primary/backup credential sets. This method provides a more
	// ergonomic interface than UseSecrets for two-secret scenarios while maintaining
	// identical security guarantees.
	//
	// DESIGN RATIONALE:
	//
	//   COMPILE-TIME CORRECTNESS:
	//   By accepting exactly two secret parameters and providing them as separate
	//   callback arguments, this method eliminates runtime errors associated with
	//   map key lookups and provides compile-time verification of secret usage
	//   patterns in two-secret operations.
	//
	//   ERGONOMIC ADVANTAGE:
	//   The callback receives secrets as individual named parameters rather than
	//   requiring map access, leading to cleaner, more readable code for common
	//   two-secret patterns. This reduces the cognitive overhead of secret handling
	//   in straightforward scenarios.
	//
	//   SEMANTIC CLARITY:
	//   The method signature clearly communicates the expectation of exactly two
	//   secrets, making the API more self-documenting and reducing the likelihood
	//   of incorrect usage patterns in two-secret scenarios.
	//
	// COMMON PATTERNS:
	// - Asymmetric cryptography (private key + certificate)
	// - Database operations (username + password)
	// - API authentication (client ID + client secret)
	// - Backup strategies (primary credential + backup credential)
	// - Key derivation (base key + salt/password)
	//
	// SECURITY GUARANTEES:
	// Identical to UseSecrets: atomic retrieval, synchronized cleanup, individual
	// memguard protection, and guaranteed cleanup on all exit paths.
	//
	// Parameters:
	//   secretID1: Identifier for the first secret (provided as first callback parameter).
	//   secretID2: Identifier for the second secret (provided as second callback parameter).
	//   fn: Callback receiving both secrets as separate byte slice parameters.
	//
	// Returns:
	//   error: nil on success, detailed error on retrieval or callback failure.
	UseSecretPair(secretID1, secretID2 string, fn func(secret1, secret2 []byte) error) error

	// UseSecretPairString provides secure access to exactly two secrets as UTF-8 strings.
	//
	// OVERVIEW:
	// String-optimized variant of UseSecretPair that combines the ergonomic benefits
	// of two-parameter secret access with automatic string conversion. This method is
	// specifically designed for text-based two-secret operations such as username/password
	// authentication, API key/secret pairs, and configuration key/value combinations.
	//
	// OPTIMIZATION BENEFITS:
	//
	//   TYPE SAFETY:
	//   By providing string parameters directly, this method eliminates the need for
	//   error-prone string conversion within callback functions and provides compile-time
	//   type safety for string-based secret operations.
	//
	//   REDUCED BOILERPLATE:
	//   Applications working with text-based secret pairs can avoid repetitive
	//   byte-to-string conversion code, leading to cleaner and more maintainable
	//   secret handling logic.
	//
	//   SEMANTIC PRECISION:
	//   The method name and signature clearly indicate intent to work with text-based
	//   secrets, improving code self-documentation and reducing the likelihood of
	//   type-related errors in string secret operations.
	//
	// TYPICAL APPLICATIONS:
	// - User authentication (username + password verification)
	// - OAuth flows (client_id + client_secret)
	// - Database connections (username + password for connection strings)
	// - API integrations (API key + API secret)
	// - Certificate operations (certificate PEM + private key PEM)
	// - Configuration pairs (encryption key + signing key as text)
	//
	// STRING PROCESSING NOTES:
	// - All UTF-8 encoding considerations from UseSecretsString apply
	// - Both secrets are converted within secure memory context
	// - No intermediate string copies in unprotected memory
	// - Strings are ephemeral and cleared on callback completion
	//
	// Parameters:
	//   secretID1: Identifier for the first secret (provided as first string parameter).
	//   secretID2: Identifier for the second secret (provided as second string parameter).
	//   fn: Callback receiving both secrets as separate string parameters.
	//
	// Returns:
	//   error: nil on success, detailed error on retrieval or callback failure.
	UseSecretPairString(secretID1, secretID2 string, fn func(secret1, secret2 string) error) error

	// SecureMemoryProtection returns information about the memory protection
	// mechanisms currently active for this vault instance.
	//
	// This can include details about memory locking (mlock), guard pages,
	// secure allocation methods, or other platform-specific protections.
	//
	// Returns:
	//   - string: Human-readable description of active memory protection features
	//
	// The returned information is primarily for diagnostic and security
	// assessment purposes. Different implementations may provide different
	// levels of memory protection based on platform capabilities.
	//
	// Example:
	//   protection := vault.SecureMemoryProtection()
	//   fmt.Printf("Memory protection: %s\n", protection)
	//   // Output might be: "mlock enabled, guard pages active, secure heap in use"
	SecureMemoryProtection() string

	// RotateKeyEncryptionKey changes the vault's master passphrase used for key derivation.
	//
	// This operation re-encrypts all key material with a new Key Encryption Key (KEK)
	// derived from the new passphrase. This is a sensitive operation that affects
	// the security of all stored keys and secrets.
	//
	// Parameters:
	//   - newPassphrase: The new passphrase to use (should meet security requirements)
	//   - reason: Human-readable explanation for the rotation (for audit logs)
	//
	// Returns:
	//   - error: Error if rotation fails (weak passphrase, cryptographic failure, etc.)
	//
	// Security Notes:
	//   - The operation is atomic - either fully succeeds or leaves vault unchanged
	//   - Old passphrase-derived keys are securely wiped from memory
	//   - All key re-encryption is performed in memory before persisting
	//   - The operation is logged extensively for audit purposes
	//
	// Example:
	//   err := vault.RotateKeyEncryptionKey("new-strong-passphrase-123!", "security policy compliance")
	//   if err != nil {
	//       return fmt.Errorf("key encryption key rotation failed: %w", err)
	//   }
	//   fmt.Println("Key Encryption Key successfully rotated")
	RotateKeyEncryptionKey(newPassphrase string, reason string) error

	// GetAudit returns the audit logger instance used by this vault.
	//
	// The audit logger captures all significant operations performed by the vault,
	// including key operations, secret access, administrative changes, and security events.
	// This supports compliance requirements, security monitoring, and forensic analysis.
	//
	// Returns:
	//   - audit.Logger: The audit logger instance (never nil for properly initialized vaults)
	//
	// The audit logger typically records:
	//   - Timestamp and operation type
	//   - User/session context (where available)
	//   - Resource identifiers (key IDs, secret IDs)
	//   - Operation outcomes (success/failure)
	//   - Security-relevant events (authentication failures, suspicious patterns)
	//
	// Example:
	//   auditLogger := vault.GetAudit()
	//   auditLogger.LogSecurityEvent("vault_accessed", map[string]interface{}{
	//       "source_ip": "192.168.1.100",
	//       "user_agent": "MyApplication/1.0",
	//   })
	GetAudit() audit.Logger

	// DeleteTenant securely removes all resources (secrets, keys, metadata) associated with a tenant.
	// This operation is irreversible, ensuring that no data can be recovered after deletion.
	DeleteTenant(tenantID string) error
}

VaultService defines the public interface for interacting with the vault.

The vault manages its primary keys internally and ensures they are not directly exportable. It uses these keys to encrypt and decrypt provided data while maintaining strict separation between key material and application data.

Key Design Principles:

  • Zero-trust: Keys are never exposed outside the vault instance
  • Fail-secure: Operations fail safely when keys are unavailable
  • Audit-first: All operations are logged for compliance and security monitoring
  • Memory-safe: Sensitive data is cleared from memory when no longer needed

Thread Safety: Implementations of VaultService should be thread-safe for concurrent access, though individual operations may acquire locks as needed for consistency.

Error Handling: All operations return errors that provide sufficient detail for troubleshooting while avoiding information disclosure that could aid attackers.

func NewWithStore 

func NewWithStore(options Options, store persist.Store, auditLogger audit.Logger, tenantID string) (VaultService, error)

NewWithStore creates a new VaultService instance with the specified storage backend and audit logger.

This is the primary constructor for creating a vault service with custom storage and audit implementations. It handles all aspects of vault initialization including memory protection, key derivation, storage connectivity testing, and audit logging setup.

The function performs several critical initialization steps:

  1. Validates configuration options
  2. Tests storage backend connectivity
  3. Sets up memory protection (best-effort)
  4. Initializes cryptographic key derivation
  5. Loads existing keys or creates initial key material
  6. Initializes the secrets container
  7. Establishes audit logging

Parameters:

  • options: Configuration options for the vault (passphrase, salt, etc.)
  • store: Storage backend implementation for persisting encrypted data
  • auditLogger: Logger for security events and operations (nil creates no-op logger)

Returns:

  • VaultService: Fully initialized vault service ready for use
  • error: Error if initialization fails at any stage

Error Conditions:

  • Invalid configuration options
  • Storage backend connectivity failure
  • Memory protection setup failure (logged as warning, not fatal)
  • Key derivation or encryption key setup failure
  • Existing vault data corruption or inaccessibility

Security Notes:

  • Memory protection is attempted but vault remains functional if unavailable
  • All cryptographic material is stored in protected memory enclaves
  • Storage connectivity is verified before proceeding with initialization
  • Audit events are logged for the initialization process

Example: 

options := volta.Options{
    DerivationPassphrase: "secure-passphrase",
    DerivationSalt: []byte("optional-custom-salt"),
}
store := persist.NewFileStore("/path/to/vault")
auditLogger := audit.NewFileLogger("/path/to/audit.log")

vault, err := volta.NewWithStore(options, store, auditLogger)
if err != nil {
    return fmt.Errorf("failed to create vault: %w", err)
}
defer vault.Close()

Source Files

View all Source files

Directories

Path Synopsis
audit/file_logger.go
 audit/file_logger.go
cli
cmd
volta command
examples
backup command
dek_rotation command
encryption command
kek_rotation command
performance command
secrets command
internal
backup
crypto
debug
mem
misc

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.