Credential Vault - README
=============================================================================
A command-line credential manager using AES-encrypted local storage.
Credentials are protected by a master password and stored in an encrypted
vault file on the local machine.

=============================================================================
PREREQUISITES
=============================================================================

  - Python 3.14.2 or greater
  - cryptography package:  pip install -r requirements.txt
  
  - chmod +x setup_vault.sh && ./setup_vault.sh
  - MacBook: python3 -m pip install cryptography --break-system-packages

=============================================================================
SETUP - RUN ONCE PER MACHINE
=============================================================================

Run the setup script for your platform from the scripts\ folder.
It installs vault.py, registers the vault command, sets all required
environment variables, and creates the vault in one pass.

  Windows:
    scripts\setup_vault.ps1

    If blocked by execution policy, unblock the file first:
      Unblock-File -Path scripts\setup_vault.ps1
      Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
    
  macOS:
    chmod +x scripts/setup_vault.sh   # first time only
    scripts/setup_vault.sh

The setup script will:
  1. Copy vault.py to %USERPROFILE%\.secure_vault\  (Windows)
                  or ~/.secure_vault/               (macOS)
  2. Create a "vault" command available system-wide
  3. Set VPATH (vault file location) as a persistent user environment variable
  4. Set ID (master password) as a persistent user environment variable
  5. Initialize vault.enc if it does not already exist

After setup, open a new terminal. No --vault-path flag is needed.
No vault entries are required in any project .env file.

Re-running setup is safe. It overwrites all settings and re-prompts
for the master password. The vault.enc file is never deleted on re-run.

=============================================================================
VAULT FILE LOCATION
=============================================================================

  Windows:  C:\Users\<username>\.secure_vault\vault.enc
  macOS:    ~/.secure_vault/vault.enc

The path is stored in the VPATH user environment variable set by setup.
vault.py reads VPATH automatically - no .env entry required.

=============================================================================
COMMANDS
=============================================================================

All commands are run from any terminal after setup. No path arguments needed.

STORE A CREDENTIAL
------------------
  vault store <SERVICE_NAME> <USERNAME>

You will be prompted for the password and optional notes (e.g., OCI region).
Multiple usernames can be stored under the same service name.

Examples:
  vault store MYDB ADMIN
  vault store MYDB RDF_SERVICE

  Note: The service name must match the database portion of the wallet folder
  name (case-sensitive). For example, wallet Wallet_MULTUMDEVDB2 requires
  service name MULTUMDEVDB2.


RETRIEVE A CREDENTIAL
---------------------
  vault get <SERVICE_NAME> [USERNAME]

Omit USERNAME to list all credentials stored under a service.
Provide USERNAME to retrieve a specific credential.

Examples:
  vault get MYDB               # lists all usernames stored for MYDB
  vault get MYDB ADMIN         # retrieves the ADMIN credential only


LIST STORED SERVICES
--------------------
  vault list


DELETE A CREDENTIAL
-------------------
  vault delete <SERVICE_NAME> <USERNAME>

USERNAME is required. Deletes only the specified credential.
If it is the last username under a service, the service is removed entirely.

Example:
  vault delete MYDB ADMIN


CHANGE MASTER PASSWORD
----------------------
  vault change-master


AVAILABLE COMMANDS
------------------
| Command        | Description                                        |
|----------------|----------------------------------------------------|
| store          | Store a credential (multiple usernames per service)|
| get            | Retrieve credentials (all users or specific user)  |
| list           | List all services and usernames                    |
| delete         | Delete a specific service/username credential      |
| change-master  | Change the master password                         |

=============================================================================
USING THE VAULT IN PYTHON SCRIPTS
=============================================================================

vault.py reads VPATH and ID from the environment automatically.
No arguments or .env vault entries are needed in consuming scripts.

  from vault import SecureVault

  vault = SecureVault()          # reads VPATH from environment
  if vault.unlock_vault():       # reads ID from environment
      creds = vault.get_password("MYDB", "ADMIN")   # service + username required
      vault.lock_vault()

=============================================================================
TROUBLESHOOTING
=============================================================================

"vault" command not found after setup:
  Open a new terminal window. The PATH update requires a fresh session.

Vault exists but password failed:
  Re-run setup_vault to reset the ID environment variable to the correct
  password. The vault.enc file will not be deleted.

Service not found by consuming script:
  The service name in the vault must exactly match the database portion of
  the wallet folder name (case-sensitive). Run "vault list" and compare
  against ORACLE_WALLET_PATH in the project .env.

Verify environment variables are set:

  Windows (PowerShell):
    [System.Environment]::GetEnvironmentVariable("VPATH", "User")
    [System.Environment]::GetEnvironmentVariable("ID", "User")

  macOS:
    echo $VPATH
    echo $ID

=============================================================================
SECURITY NOTES
=============================================================================

  - Never commit vault.enc to source control. Add it to .gitignore.
  - VPATH is stored as a user environment variable - visible only to the
    owning OS account.
  - ID (master password) is stored as a user environment variable, never
    in any project file.
  - VPATH and ID are kept in separate locations intentionally. Neither is
    useful to an attacker without the other.
  - vault.enc is readable only by the owning OS user (chmod 600 / Windows
    owner-only ACL set by the install scripts).