# 99designs/aws-vault architecture

> Architecture diagram of the GitHub repository 99designs/aws-vault, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/99designs/aws-vault
- Repository: https://github.com/99designs/aws-vault

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    subgraph "Internal Modules"
        CLI("CLI Layer (cli)"):::internal
        Vault("Vault Module (vault)"):::internal
        Server("Server Module (server)"):::internal
        Prompt("Prompt Module (prompt)"):::internal
    end

    %% Auxiliary Modules
    subgraph "Auxiliary Modules"
        Iso8601("Date/Time Parsing (iso8601)"):::aux
        Contrib("Deployment & Scripts (contrib)"):::aux
    end

    %% External Dependencies
    subgraph "External Dependencies"
        STS("AWS STS"):::external
        Keystore("OS Keystore Services"):::external
    end

    %% Data Flow
    CLI -->|"commands"| Vault
    CLI -->|"prompts"| Prompt
    CLI -->|"activates"| Server
    Vault -->|"requests temporary tokens"| STS
    Vault -->|"securely stores credentials in"| Keystore
    Vault -->|"parses dates using"| Iso8601
    %% Note: Contrib provides auxiliary support and deployment tools

    %% Click Events for Component Mapping
    click CLI "https://github.com/99designs/aws-vault/tree/master/cli"
    click Vault "https://github.com/99designs/aws-vault/tree/master/vault"
    click Server "https://github.com/99designs/aws-vault/tree/master/server"
    click Prompt "https://github.com/99designs/aws-vault/tree/master/prompt"
    click Iso8601 "https://github.com/99designs/aws-vault/tree/master/iso8601"
    click Contrib "https://github.com/99designs/aws-vault/tree/master/contrib"

    %% Styles
    classDef internal fill:#A0D3FF,stroke:#000,stroke-width:2px;
    classDef aux fill:#C1F0C1,stroke:#000,stroke-width:2px;
    classDef external fill:#FFF79F,stroke:#000,stroke-width:2px;
```
