System Token

The system token is a server-side Vault token used exclusively for background services and restricted-access fallbacks. It is never exposed to the browser.

What It's Used For

Operation	Description
Restricted-access key resolution	When a user can list a secret path but can't read it, the system token reads the secret to extract field names only — values are never exposed
Secure merge	Reading existing secrets server-side so the backend can merge user-supplied keys without revealing values the user can't read
Rotation scheduler	Reading and rotating KV v2 secrets based on rotate-interval metadata
Audit watcher	Polling the Vault audit log for webhook event matching
Backup scheduler	Creating full KV backups on schedule
Shared secrets	Storing/retrieving OpenPGP ciphertext in Vault cubbyhole
Policy initialization	Auto-creating vaultlens-admin and vaultlens-system policies at startup

Resolution Order

VaultLens resolves the system token in priority order:

1. Kubernetes auth — authenticates via the pod's service account JWT using VAULT_K8S_AUTH_ROLE. Token is auto-renewed at 75% of TTL.
2. AppRole auth — credentials generated by the setup wizard, stored encrypted in config storage.
3. Static token — VAULT_SYSTEM_TOKEN environment variable. Simplest for development; not recommended for production.

Setup Wizard

The first time VaultLens starts without a system token configured, it redirects all authenticated users to the Setup Wizard (/setup).

The wizard:

1. Uses your logged-in token to check required Vault permissions
2. Creates the vaultlens-system policy in Vault
3. Enables the AppRole auth method (if not already enabled)
4. Creates a VaultLens AppRole and generates role_id + secret_id
5. Encrypts and stores both credentials in config storage

Once complete, the wizard redirects to the dashboard and the system token is available for background services.

Credential Encryption

AppRole credentials are stored encrypted using AES-256-GCM (authenticated encryption):

• The encryption key is derived from VAULT_ADDR using SHA-256
• Format: v1:<base64(iv)>:<base64(ciphertext)>:<base64(authTag)>
• Versioned for future key rotation
• Backward compatible with plaintext (pre-encryption) values — auto-converted on first read

This means all VaultLens instances pointing to the same Vault server can decrypt the same credentials, enabling stateless multi-replica deployments.

Security Invariants

1. The system token is never returned in any API response or included in logs
2. When used for restricted-access key resolution, only field names are returned — values are never exposed
3. All user-initiated operations use the logged-in user's own token — Vault's ACL controls what users can access
4. The vaultlens-system policy must never be assigned to human users

Required Vault Permissions

The system token's vaultlens-system policy grants:

• Full CRUD on all KV engines (for rotation, backup, shared secrets)
• Read on sys/mounts and sys/auth
• Create/update on sys/policies/acl/* (for policy initialization)
• Auth token operations for cubbyhole (shared secrets)
• Audit device management (for webhook registration)
• Read on sys/audit (for audit log access)