Module vault_ssh 

Structs

ActiveCert

One row in the Keys-tab Vault SSH strip.

SignResult

Result of a certificate signing operation.

VaultSignTarget

One host resolved to a Vault SSH role, ready for bulk signing.

Enums

CertStatus

Certificate validity status.

Constants

CERT_ERROR_BACKOFF_SECS

Shorter TTL for cached CertStatus::Invalid entries produced by check failures (e.g. unresolvable cert path). Error entries use this backoff instead of the 5-minute re-check TTL so transient errors recover quickly without hammering the background check thread on every poll tick.

CERT_STATUS_CACHE_TTL_SECS

TTL (in seconds) for the in-memory cert status cache before we re-run ssh-keygen -L against an on-disk certificate. Distinct from RENEWAL_THRESHOLD_SECS: this controls how often we re-check a cert’s validity, while RENEWAL_THRESHOLD_SECS is the minimum lifetime below which we actually request a new signature from Vault.

RENEWAL_THRESHOLD_SECS

Minimum remaining seconds before a cert needs renewal (5 minutes).

Functions

active_certs_for_strip

Build the strip’s row list from the cert cache. Hosts that have a configured role (or a purple-managed cert path) but no cached Valid status are omitted; the gauge has nothing to fill until the lazy cert check populates the cache. Sort: longest remaining first so the user sees healthy certs at the top and expiring ones at the bottom.

cert_file_in_purple_dir

CertificateFile path looks like a purple-managed cert when it references the per-user .purple/certs/ directory. We match on the substring so the check works regardless of whether the path is tilde-expanded or absolute.

cert_fill_ratio

Compute the fill ratio (0.0..=1.0) for a Vault SSH cert TTL gauge. Clamped so a cert in renewal-overlap or one whose total_secs was recorded as i64::MAX (“Valid: forever”) does not produce NaN.

cert_path_for

Return the certificate path for a given alias: ~/.purple/certs/<alias>-cert.pub

check_cert_validity

Check the validity of an SSH certificate file via ssh-keygen -L.

ensure_cert

Ensure a valid certificate exists for a host. Signs a new one if needed. Checks at the CertificateFile path (or purple’s default) before signing.

format_remaining

Format remaining certificate time for display.

has_purple_vault_context

True iff a host has any purple-managed Vault context: either an explicit # purple:vault-ssh role marker, or a CertificateFile directive pointing into ~/.purple/certs/. The second branch covers users who sign certs directly with the vault CLI and wire them in via CertificateFile without setting the role marker.

is_valid_role

Validate a Vault SSH role path. Accepts ASCII alphanumerics plus /, _ and -. Rejects empty strings and values longer than 128 chars.

is_valid_vault_addr

Validate a VAULT_ADDR value passed to the Vault CLI as an env var.

needs_renewal

Check if a certificate needs renewal.

normalize_vault_addr

Normalize a vault address so bare IPs and hostnames work.

resolve_cert_path

Resolve the actual certificate file path for a host. Priority: CertificateFile directive > purple’s default cert path.

resolve_proxy_chain

Resolve the effective ProxyJump chain for an alias by asking ssh itself.

resolve_pubkey_path

Resolve the public key path for signing. Priority: host IdentityFile + “.pub” > ~/.ssh/id_ed25519.pub fallback. Returns an error when the user’s home directory cannot be determined. Any IdentityFile pointing outside $HOME is rejected and falls back to the default ~/.ssh/id_ed25519.pub to prevent reading arbitrary filesystem locations via a crafted IdentityFile directive.

resolve_vault_addr

Resolve the effective Vault address for a host.

resolve_vault_role

Resolve the effective vault role for a host. Priority: host-level vault_ssh > provider-level vault_role > None.

scrub_vault_stderr

Scrub a raw Vault CLI stderr for display. Drops lines containing credential-like tokens (token, secret, x-vault-, cookie, authorization), joins the rest with spaces and truncates to 200 chars.

sign_certificate

Sign an SSH public key via Vault SSH secrets engine. Runs: vault write -field=signed_key <role> public_key=@<pubkey_path> Writes the signed certificate to ~/.purple/certs/<alias>-cert.pub.

vault_ssh_in_use

True when any host has a purple-managed Vault context. The Keys-tab strip renders iff this returns true. Even hosts whose cert is not yet cached count, so the strip appears the moment the user configures their first Vault role or sets a cert path.