How 99designs/aws-vault works
Main System Components
• CLI Layer (located in the cli directory) – This handles user commands such as add, list, login, remove, rotate, and export. The tests in this package ensure that command operations work as expected.
• Vault Module (under the vault directory) – Implements various credential providers and session management (e.g., handling MFA, role assumptions, caching, and processing AWS STS responses).
• Server Module (in the server directory) – Implements functionality for starting a local instance metadata server that proxies temporary credentials to applications using Amazon SDKs.
• Prompt Module (in the prompt directory) – Abstracts platform-specific prompting logic (supporting macOS, Windows, Linux variants via osascript, terminal prompts and other UI methods) for MFA and user input.
• Auxiliary Libraries/Utilities:
– The iso8601 module provides date/time parsing for handling credential expiration.
– The contrib directory includes Dockerfiles, shell completions, and helpful scripts which make the tool more portable and extendable.
• External Dependencies:
– Interactions with AWS STS (external API) for generating temporary credentials.
– Integration with OS-specific secure keystores (using underlying OS APIs for Keychain, Credential Manager, Secret Service, etc.).
Relationships and Data Flows
• The CLI layer (triggered by user command) interacts with the vault module to manage stored credentials.
• The vault module communicates with AWS STS endpoints for obtaining temporary session tokens with role assumption and MFA features.
• When the “--server” flag is used, the CLI also triggers the server module to start a local metadata server; both components (CLI and server) work in tandem to supply environment variables or metadata endpoints.
• The prompt module acts as an intermediary during authentication when the user’s MFA input is required.
• Auxiliary libraries (such as iso8601) are used by these components to correctly parse and use date/time information (like credential expiration).
• The contrib scripts and Docker configurations show options for wider deployment and extension, but are loosely coupled to the core credential management functionality.
Architectural Patterns and Design Principles
• Separation of concerns is clearly implemented: the CLI, vault, server, and prompt modules are each responsible for distinct aspects of the functionality.
• Modular design helps facilitate testing (notice the presence of test files throughout) and a degree of platform abstraction (especially in prompt and server directories).
• Interaction with external systems (AWS STS, OS keystore services) is isolated into manageable components.