Metadata-Version: 2.4
Name: secure-mypass
Version: 1.2.0
Summary: Secure local terminal password manager
Author-email: Ravi K <kravi2439@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/ravikempanayaka/mypass#
Keywords: secure-mypass,password manager,terminal tool,local storage,cli password manager,offline credentials,password-manager,credential-manager,cli,terminal,security,cybersecurity,developer-tools,password-storage,credentials,master-password,encryption,local-storage,devops,python-cli,command-line-tool
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyperclip
Requires-Dist: cryptography
Requires-Dist: pyotp
Requires-Dist: qrcode[pil]
Dynamic: license-file

# Secure MyPass

A lightweight, terminal-based password manager that stores credentials securely on your local machine.

Secure MyPass is designed for developers, system administrators, DevOps engineers, and power users who prefer local credential management without cloud synchronization or external services.

## Features

* Local-first password management
* Master password protection
* Encrypted sensitive fields
* Dynamic credential fields
* Organize credentials into sections
* Fast terminal search
* Cross-platform support
* No cloud storage
* No external dependencies beyond Python packages
* Easy backup and migration

---

# Installation

## Recommended Installation

Install using pipx:

```bash
pipx install secure-mypass
```

If pipx is not installed:

### Ubuntu / Debian

```bash
sudo apt update
sudo apt install pipx

pipx ensurepath
```

Restart your terminal and install:

```bash
pipx install secure-mypass
```

---

### Windows

Install:

```powershell
python -m pip install secure-mypass
```

## Alternative: Virtual Environment

```bash
python3 -m venv venv

source venv/bin/activate

pip install secure-mypass
```

---
##  Recommended GitHub Structure
```aiignore
secure-mypass/
│
├── docs/
│   └── images/
│       ├── workflow-overview.png
├── mypass/
├── README.md
└── pyproject.toml
```

## Workflow Overview

Figure 1: Complete Secure MyPass workflow — Initialize → Setup Master Password → Add Credentials → List → Search (masked) → Show (decrypted).

![Workflow](https://raw.githubusercontent.com/ravikempanayaka/mypass/main/docs/images/workflow-overview.png)


# First Time Setup

## Step 1: Initialize the Vault

```bash
mypass init
```

This creates:

```text
~/.mypass
```

---

## Step 2: Configure Master Password

```bash
mypass setup
```

Example:

```text
Create Master Password:
Confirm Master Password:
```

The master password is required whenever you:

* Add credentials
* View decrypted credentials
* Delete credentials
* Change the master password

---

# Step 3: Enable Multi-Factor Authentication (MFA) (Optional)

For additional security, Secure MyPass supports:

* Microsoft Authenticator
* Google Authenticator

MFA adds a second layer of protection by requiring a one-time verification code (OTP) in addition to your master password.

---

## Enable MFA

```bash
mypass enable-mfa
```

Example:

```text
Select Authenticator

1. Microsoft Authenticator
2. Google Authenticator

Choice: 1
```

---

## Scan QR Code

A QR code will be displayed directly in the terminal.

### Microsoft Authenticator

1. Open Microsoft Authenticator
2. Tap **+**
3. Select **Other Account**
4. Scan the QR code

### Google Authenticator

1. Open Google Authenticator
2. Tap **+**
3. Select **Scan QR Code**
4. Scan the QR code

---

## Verify Setup

After scanning the QR code, enter the OTP generated by your authenticator application.

Example:

```text
Enter OTP to verify setup: 123456
```

If verification succeeds:

```text
✓ MFA enabled successfully.
```

---

## Disable MFA

```bash
mypass disable-mfa
```

---

## MFA Authentication Flow

When MFA is enabled:

```bash
mypass show personal
```

Example:

```text
Master Password:
OTP:
```

Only after both the master password and OTP are verified will the credential be displayed.

---

# Session Management

Secure MyPass supports session-based authentication to improve usability while maintaining security.

Once authenticated successfully:

```text
Master Password
+
OTP
```

you can continue using Secure MyPass without re-entering credentials until the session expires.

---

## Check Session Status

```bash
mypass status
```

Example:

```text
Vault: Unlocked
Expires in: 15 minutes
```

---

## Lock the Vault

Immediately terminate the active session:

```bash
mypass lock
```

Output:

```text
Vault locked.
```

---

# Storage Location

## Linux / macOS

```text
~/.mypass
~/.mypass.key
~/.mypass.mfa
~/.mypass.session
```

## Windows

```text
C:\Users\<username>\.mypass
C:\Users\<username>\.mypass.key
C:\Users\<username>\.mypass.mfa
C:\Users\<username>\.mypass.session
```

### File Description

| File              | Purpose                                                             |
| ----------------- | ------------------------------------------------------------------- |
| `.mypass`         | Stores credentials and sections                                     |
| `.mypass.key`     | Master password configuration and encryption settings               |
| `.mypass.mfa`     | Encrypted MFA configuration and authenticator details               |
| `.mypass.session` | Temporary session information used for session-based authentication |

---

# Security Notes

* Credentials are stored locally on your machine.
* Sensitive fields are encrypted before storage.
* MFA secrets are encrypted using the master-password-derived encryption key.
* Session information automatically expires after the configured timeout period.
* No cloud synchronization or external credential storage is used.
* Your data remains under your control at all times.

```
```
# Secure MyPass Workflow Overview

The image below demonstrates the complete Secure MyPass security workflow, including vault initialization, master password protection, MFA configuration, credential management, session handling, and vault locking.

**Workflow Steps**

1. Configure a Master Password
2. Enable Multi-Factor Authentication (Microsoft Authenticator or Google Authenticator)
3. Scan the QR Code and Verify OTP
4. Add and Manage Credentials
5. Check Session Status
6. Access Credentials Securely
7. Lock the Vault When Finished

> **Figure 1:** Complete Secure MyPass workflow showing Master Password Setup, MFA Configuration, Credential Management, Session Monitoring, and Vault Locking.

![Secure MyPass Workflow](https://raw.githubusercontent.com/ravikempanayaka/mypass/main/docs/images/secure-mypass-workflow.png)


# Daily Usage

## Add a Credential

```bash
mypass add
```

Example:

```text
Master Password:

Sections

1. Email Accounts
2. Cloud Accounts
0. New Section

Select: 0

Section Name: Email Accounts

System Name: Personal Mail

Field Name: Email
Email: user@example.com

Field Name: Password
Password:

Field Name:
```

Press Enter on an empty field name to finish.

---

## Search Credentials

Search without revealing secrets:

```bash
mypass search personal
```

Example:

```text
[Email Accounts]

Name: Personal Mail
Email: user@example.com
Password: ********
```

---

## Show Credential

Reveal encrypted values:

```bash
mypass show personal
```

Example:

```text
Master Password:

[Email Accounts]

Name: Personal Mail
Email: user@example.com
Password: MySecretPassword
```

---

## List All Credentials

```bash
mypass list
```

Example:

```text
[Email Accounts]
- Personal Mail

[Cloud Accounts]
- Development Account
```

---

## Delete a Credential

```bash
mypass delete personal
```

---

# Supported Dynamic Fields

You can store any field you want.

Examples:

```text
Email
Username
Password
URL
Token
API Key
Recovery Codes
Access Key
Secret Key
Database Host
Database User
Database Password
```

No predefined schema is required.

---

# Security

Secure MyPass uses a master password to protect sensitive data.

Sensitive fields are encrypted before being stored.

Examples:

```text
Password
Token
API Key
Recovery Codes
Secret Key
```

When searching:

```bash
mypass search personal
```

Sensitive values are hidden:

```text
Password: ********
```

When viewing:

```bash
mypass show personal
```

The master password is required before decryption.

---

---

# Backup

Backup your vault:

```bash
cp ~/.mypass backup.mypass
cp ~/.mypass.key backup.key
```

To restore:

```bash
cp backup.mypass ~/.mypass
cp backup.key ~/.mypass.key
```

Important:

Both files are required.

Without `.mypass.key`, encrypted credentials cannot be decrypted.

---

# Commands

| Command                   | Description                                                 |
|---------------------------|-------------------------------------------------------------|
| `mypass init`             | Create vault file                                           |
| `mypass setup`            | Configure master password                                   |
| `mypass enable-mfa`       | Enable and configure Multi-Factor Authentication (Optional) |
| `mypass disable-mfa`      | Disable Multi-Factor Authentication (MFA)                   |
| `mypass add`              | Add a credential                                            |
| `mypass list`             | List credentials                                            |
| `mypass search <keyword>` | Search credentials (masked output)                          |
| `mypass show <keyword>`   | Show decrypted credential                                   |
| `mypass delete <keyword>` | Delete credential                                           |
| `mypass status`           | Show current vault and session status                       |
| `mypass lock`             | Lock the vault and clear the active session                 |

---

# Supported Platforms

* Ubuntu
* Debian
* Fedora
* CentOS
* macOS
* Windows Command Prompt
* Windows PowerShell

---

# Why Secure MyPass?

Many password managers depend on cloud synchronization, browser extensions, or subscriptions.

Secure MyPass focuses on:

* Local storage
* Terminal workflow
* Simplicity
* Speed
* Developer productivity

Your credentials remain under your control at all times.

---

# License

MIT License

---

# Author

Ravi K
