Vaultx.Sys.Leases (Vaultx v0.7.0)

Enterprise lease management for HashiCorp Vault.

This module provides comprehensive lease lifecycle management capabilities for Vault secrets, supporting all lease operations from creation to revocation with enterprise-grade features for large-scale deployments.

Lease Management Capabilities

Core Operations

Lease Lookup: Detailed lease information and metadata
Lease Renewal: Extend lease durations with custom increments
Lease Revocation: Individual and bulk lease termination
Lease Listing: Enumerate leases by prefix patterns

Administrative Operations

Bulk Operations: Mass lease management for operational efficiency
Force Revocation: Emergency lease termination
Lease Cleanup: Administrative maintenance and tidying
Lease Counting: Operational metrics and monitoring

Enterprise Features

Namespace Support: Multi-tenant lease management
Audit Integration: Complete lease operation auditing
Performance Optimization: Efficient bulk operations
Monitoring Integration: Comprehensive lease metrics

Security Considerations

Privilege Requirements: Many operations require sudo capabilities
Audit Logging: All lease operations are audited
Access Control: Lease access controlled by policies
Emergency Procedures: Force revocation for security incidents

API Compliance

Fully implements HashiCorp Vault Leases API:

Leases API
Lease Concepts
POST /sys/leases/lookup - Lookup lease information
POST /sys/leases/renew - Renew a lease
POST /sys/leases/revoke - Revoke a lease
GET /sys/leases/lookup/:prefix?list=true - List leases by prefix
POST /sys/leases/revoke-prefix/:prefix - Revoke all leases with prefix
POST /sys/leases/revoke-force/:prefix - Force revoke leases
POST /sys/leases/tidy - Clean up dangling lease entries

Lease Operations

Basic Operations

lookup/2 - Get detailed lease information
renew/3 - Extend lease duration
revoke/2 - Revoke a single lease

Bulk Operations

revoke_prefix/2 - Revoke all leases with a prefix
revoke_force/2 - Force revoke ignoring backend errors
list/2 - List leases by prefix

Administrative Operations

tidy/1 - Clean up dangling lease entries
count/2 - Count leases by type
list_all/2 - List all leases with details

Usage Examples

# Lookup lease information
{:ok, lease} = Vaultx.Sys.Leases.lookup("aws/creds/deploy/abcd-1234")
lease.renewable #=> true
lease.ttl #=> 3600

# Renew lease for additional time
{:ok, renewed} = Vaultx.Sys.Leases.renew("aws/creds/deploy/abcd-1234", 1800)
renewed.lease_duration #=> 1800

# Revoke a lease
:ok = Vaultx.Sys.Leases.revoke("aws/creds/deploy/abcd-1234")

# List leases by prefix (requires sudo)
{:ok, leases} = Vaultx.Sys.Leases.list("aws/creds/deploy/")
leases #=> ["aws/creds/deploy/abcd-1234", "aws/creds/deploy/efgh-5678"]

# Bulk revoke by prefix (requires sudo)
:ok = Vaultx.Sys.Leases.revoke_prefix("aws/creds/deploy/")

# Force revoke for emergency situations
:ok = Vaultx.Sys.Leases.revoke_force("aws/creds/deploy/")

# Clean up dangling lease entries
:ok = Vaultx.Sys.Leases.tidy()

Security Considerations

Sudo Required: Lease listing and bulk operations require 'sudo' capability
Emergency Use: Force revocation should only be used in emergency situations
Performance Impact: Tidy operations can be I/O intensive on large deployments
Immediate Effect: Lease revocation takes effect immediately and cannot be undone
Audit Trail: All lease operations are logged for security auditing
Token Validation: Lease operations validate the requesting token's permissions

Error Handling

All operations return standardized error tuples:

{:error, %Vaultx.Base.Error{
  type: :not_found,
  message: "Lease not found: aws/creds/deploy/abcd-1234",
  details: %{lease_id: "aws/creds/deploy/abcd-1234"}
}}

Summary

Types

count_result()

Lease count result.

lease_info()

Lease information structure.

lease_opts()

Lease management options.

renewal_result()

Lease renewal result.

Functions

list(prefix, opts \\ [])

List leases by prefix.

lookup(lease_id, opts \\ [])

Lookup lease information by lease ID.

renew(lease_id, increment \\ 0, opts \\ [])

Renew a lease for additional time.

revoke(lease_id, opts \\ [])

Revoke a lease immediately.

revoke_force(prefix, opts \\ [])

Force revoke all leases with the specified prefix.

revoke_prefix(prefix, opts \\ [])

Revoke all leases with the specified prefix.

tidy(opts \\ [])

Clean up dangling lease entries.

Types

count_result()

@type count_result() :: %{
  lease_count: integer(),
  counts: %{required(String.t()) => integer()}
}

Lease count result.

lease_info()

@type lease_info() :: %{
  id: String.t(),
  issue_time: String.t(),
  expire_time: String.t(),
  last_renewal_time: String.t() | nil,
  renewable: boolean(),
  ttl: integer()
}

Lease information structure.

lease_opts()

@type lease_opts() :: [
  increment: pos_integer(),
  sync: boolean(),
  include_child_namespaces: boolean(),
  limit: String.t(),
  timeout: pos_integer(),
  retry_attempts: non_neg_integer(),
  namespace: String.t()
]

Lease management options.

renewal_result()

@type renewal_result() :: %{
  lease_id: String.t(),
  renewable: boolean(),
  lease_duration: integer()
}

Lease renewal result.

Functions

list(prefix, opts \\ [])

@spec list(String.t(), lease_opts()) :: Vaultx.Types.result([String.t()])

List leases by prefix.

Returns a list of lease IDs that match the specified prefix. Requires 'sudo' capability.

Examples

{:ok, leases} = Vaultx.Sys.Leases.list("aws/creds/deploy/")
leases #=> ["aws/creds/deploy/abcd-1234", "aws/creds/deploy/efgh-5678"]

lookup(lease_id, opts \\ [])

@spec lookup(String.t(), lease_opts()) :: Vaultx.Types.result(lease_info())

Lookup lease information by lease ID.

Retrieves detailed information about a specific lease including expiration time, renewal status, and associated metadata.

Examples

{:ok, lease} = Vaultx.Sys.Leases.lookup("aws/creds/deploy/abcd-1234")
lease.renewable #=> true
lease.ttl #=> 3600

renew(lease_id, increment \\ 0, opts \\ [])

@spec renew(String.t(), integer(), lease_opts()) ::
  Vaultx.Types.result(renewal_result())

Renew a lease for additional time.

Extends the lease duration by the specified increment or the default lease duration if no increment is provided.

Options

:increment - Additional time in seconds to extend the lease

Examples

{:ok, renewed} = Vaultx.Sys.Leases.renew("aws/creds/deploy/abcd-1234", 1800)
renewed.lease_duration #=> 1800

revoke(lease_id, opts \\ [])

@spec revoke(String.t(), lease_opts()) :: Vaultx.Types.result(:ok)

Revoke a lease immediately.

Permanently revokes the specified lease and any associated credentials.

Options

:sync - Wait for revocation to complete (default: false)

Examples

:ok = Vaultx.Sys.Leases.revoke("aws/creds/deploy/abcd-1234")

revoke_force(prefix, opts \\ [])

@spec revoke_force(String.t(), lease_opts()) :: Vaultx.Types.result(:ok)

Force revoke all leases with the specified prefix.

Revokes all secrets or tokens generated under a given prefix immediately, ignoring backend errors. This is potentially dangerous and should only be used in emergency situations. Requires 'sudo' capability.

Examples

:ok = Vaultx.Sys.Leases.revoke_force("aws/creds/deploy/")

revoke_prefix(prefix, opts \\ [])

@spec revoke_prefix(String.t(), lease_opts()) :: Vaultx.Types.result(:ok)

Revoke all leases with the specified prefix.

Revokes all secrets (via lease ID prefix) or tokens (via the tokens' path property) generated under a given prefix immediately. Requires 'sudo' capability.

Options

:sync - Wait for all revocations to complete (default: false)

Examples

:ok = Vaultx.Sys.Leases.revoke_prefix("aws/creds/deploy/")

tidy(opts \\ [])

@spec tidy(lease_opts()) :: Vaultx.Types.result(:ok)

Clean up dangling lease entries.

For each lease entry in storage, Vault will verify that it has an associated valid non-expired token in storage, and if not, the lease will be revoked.

Examples

:ok = Vaultx.Sys.Leases.tidy()