# PassGram v6.00

**Secure Password Manager with PGP Key Store, Public Key Directory, Group Collaboration, Per-User PGP Encryption Mode, GPG Agent Bridge & Encrypted Import/Export**

PassGram is a standalone PHP password manager featuring group-based credential sharing, a PGP public key store with optional public directory listing, PGP encryption using native PHP OpenSSL, encrypted JSON file storage, and an invite-only registration system. All styled with an authentic OS/2 Warp 3.0 interface with purple title bars.

## Features

### Core Functionality
- **Encrypted Password Storage** - AES-256-GCM encryption for all credentials
- **Group Collaboration** - Users belong to groups and can share credentials and PGP keys
- **Complete Group Management** - Create, edit, delete groups, add/remove members, transfer ownership
- **Group-Level Credential Sharing** - Share credentials with entire groups (read-only or read/write permissions)
- **PGP Key Store** - Import, store, and share public PGP keys with groups (just like credentials)
- **Public PGP Key Directory** - Optionally list public keys in an unauthenticated searchable directory
- **PGP Key Management** - Generate RSA, DSA, or Elliptic Curve keys with configurable sizes
- **Cross-User Credential Access** - Group members can view and edit shared credentials across user boundaries
- **Copy Password from List** - Copy passwords to clipboard directly from the credential list via AJAX
- **Group Assignment at Creation** - Assign credentials and PGP keys to groups at creation time
- **Credential Sharing** - Share passwords with group members using PGP encryption
- **Invite-Only Registration** - Secure invite codes tied to specific groups
- **Notes System** - Add notes to users (group-visible) and credentials (private)
- **Multi-Field Credentials** - Store passwords, usernames, URLs, custom fields, tags
- **Password Generator** - Built-in secure random password generator
- **Copy-to-Clipboard** - One-click copying for credentials, invites, URLs, PGP keys, and fingerprints
- **Persistent Navigation** - Dashboard menu accessible on all pages when logged in

### Encrypted Import / Export (Added in v6.00)
- **Individual Export** - Export your own credentials as an AES-256-GCM encrypted `.passgram` file protected by a passphrase you choose
- **Group Export** - Export all credentials shared with a specific group (from all member-owners) in a single encrypted file
- **Passphrase-Based Encryption** - PBKDF2-SHA256 (100,000 iterations) derives the export key from your passphrase; the passphrase is never transmitted to the server during import
- **Import from .passgram** - Upload any `.passgram` file, provide the passphrase, and credentials are merged into your vault and re-encrypted with your master key
- **GPG Agent Bridge Export** - For users with a local GPG agent bridge (`localhost:7655`), credentials are fetched decrypted from the server and encrypted entirely in the browser via the bridge — the private key never leaves the user's machine
- **GPG Agent Bridge Import** - Upload a `.passgram.gpg` file; the bridge decrypts it via `gpg-agent` and posts the plaintext to PassGram for re-encryption and merge
- **Portable Format** - Export files contain only portable credential fields (title, username, password, URL, notes, tags, folder); internal IDs and sharing metadata are stripped

### Key-Only Groups (Added in v6.00)
- **`require_pgp` group setting** — group creator checks a box at creation or edit time to mark the group as key-users only
- **Membership gate** — manually adding a member who has neither `has_pgp_key` nor `has_gnupg_key` is blocked with a clear error
- **Registration gate** — accepting an invite to a key-required group fails at registration unless the user checks "Generate GnuPG key"; if GnuPG is disabled server-side an informative error is shown instead
- **Autocomplete filtering** — the "Add Member" username autocomplete only suggests eligible (key-holding) users when the group requires a key
- **Visual indicators** — purple `GPG KEY REQUIRED` badge shown on the group list and group detail view; registration page shows a yellow warning banner and pre-checks the GnuPG key checkbox
- **Non-retroactive** — existing members without a key are not removed when the setting is toggled on

### Admin Panel (Added in v6.00)
- **Role-Based Access Control** - Users have `admin` or `user` roles; first registered user auto-gets admin
- **Admin Panel** - View and manage all users, suspend accounts, generate password reset links
- **Audit Log** - Encrypted revision history for all user and credential changes (`AuditLog`)
- **Password Reset** - Admin-generated 24-hour reset tokens; users reset via a public URL

### PGP Key Store (Added in v2.0)
- **Import Public Keys** - Paste PEM-encoded public keys (RSA, DSA, EC)
- **Key Metadata** - Label, owner name, owner email, fingerprint, algorithm, key bits
- **Group Sharing** - Share PGP keys with groups, same pattern as credential sharing
- **Cross-User Access** - Group members can view keys shared by other users
- **Public Directory Listing** - Optionally make keys visible to unauthenticated visitors
- **Search & Filter** - Client-side search by name, email, label, or fingerprint
- **Copy to Clipboard** - Copy full public key text or fingerprint with one click
- **Download Keys** - Download public keys as .pem files

### Public PGP Key Directory (Added in v2.0)
- **Unauthenticated Access** - No login required to browse publicly listed keys
- **Search & Filter** - Real-time client-side filtering by name, email, label, or fingerprint
- **Copy Key** - Copy the full PGP public key to clipboard
- **Copy Fingerprint** - Copy key fingerprint to clipboard
- **Privacy Controls** - Only owner name, email, label, fingerprint, algorithm, and public key are exposed; notes, tags, and group info are never published
- **Accessible from Login Page** - Link on the login page for easy discovery

### Security Features
- **Master Application Key (MAK)** - Encrypts all JSON database files
- **User Master Password** - Never stored, only hashed (bcrypt + Argon2id)
- **Field-Level Encryption** - Sensitive credential fields encrypted individually
- **PGP Public Key Cryptography** - For secure credential sharing between users
- **CSRF Protection** - All state-changing operations protected
- **Rate Limiting** - Brute force protection on authentication
- **Session Security** - Secure, httponly, samesite cookies
- **Comprehensive Logging** - Audit trail of all security events
- **Encrypted Export** - AES-256-GCM with PBKDF2-derived passphrase key; private key never seen by server
- **GPG Agent Zero-Knowledge Export** - Private key never leaves `gpg-agent`; PassGram only sees ciphertext

### User Interface
- **OS/2 Warp 3.0 Theme** - Authentic purple title bars (#5D009D), beveled borders, classic gray backgrounds
- **Server-Side Rendered** - Traditional PHP approach, works without JavaScript
- **Enhanced User Experience** - Copy buttons, show/hide passwords, dynamic forms
- **Responsive Design** - Works on desktop and mobile devices

## System Requirements

- **PHP 7.4+** (PHP 8.x recommended)
- **OpenSSL Extension** (standard on all servers)
- **JSON Extension** (standard on all servers)
- **Writable `data/` directory** for encrypted storage
- **HTTPS** (required for production - configured in web server)

## Installation

### 1. Upload Files

Transfer all PassGram files to your web server. The `public/` directory should be your web root.

```
your-domain.com/
├── public/          <- Point your web server here
├── src/
├── data/
├── config/
├── autoload.php
└── install.php
```

### 2. Set Permissions

```bash
chmod 700 data/
chmod 700 config/
chmod 644 public/.htaccess
```

### 3. Run Installation

Visit `https://your-domain.com/install.php` in your browser.

The installer will:
- Generate a secure Master Application Key (MAK)
- Create the first admin user
- Create a default group
- Generate an invite code for additional users
- Initialize the encrypted database

**IMPORTANT:**
- Save the invite code displayed after installation
- Backup `config/security.php` to a secure location
- Delete `install.php` after successful installation

### 4. Configure Web Server

**Apache (.htaccess already included):**
Point DocumentRoot to `/public/` directory.

**Nginx:**
```nginx
server {
    listen 443 ssl;
    server_name your-domain.com;

    root /path/to/passgram/v3.0/public;
    index index.php;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
        fastcgi_index index.php;
        include fastcgi_params;
    }

    # Block access to sensitive directories
    location ~ ^/(config|data|src)/ {
        deny all;
    }
}
```

### 5. Update Configuration

Edit `config/config.php`:
- Set `base_url` to your domain
- Enable `cookie_secure` when using HTTPS
- Adjust security settings as needed

## Directory Structure

```
v3.0/
├── autoload.php                 # Standalone PSR-4 autoloader
├── install.php                  # Installation script (delete after install)
├── public/                      # Web root
│   ├── index.php               # Main entry point & router
│   ├── login.php               # Login page
│   ├── logout.php              # Logout handler
│   ├── register.php            # Invite-based registration
│   ├── assets/
│   │   ├── css/style.css       # OS/2 Warp 3.0 theme
│   │   └── js/app.js           # Client-side interactions
│   └── .htaccess               # Apache security & rewrite rules
├── src/                         # Application code
│   ├── Core/                   # Core infrastructure
│   │   ├── Config.php          # Configuration loader
│   │   ├── Database.php        # Encrypted JSON file operations (AES + PGP mode)
│   │   └── Session.php         # Secure session management
│   ├── Security/               # Security components
│   │   ├── Encryption.php      # AES-256-GCM encryption
│   │   ├── PGP.php             # Native PHP OpenSSL RSA/DSA/EC key generation
│   │   ├── PGPEncryption.php   # Hybrid RSA+AES-256-GCM per-user encryption (v3.0)
│   │   ├── Auth.php            # Authentication
│   │   └── CSRF.php            # CSRF protection
│   ├── Models/                 # Data models
│   │   ├── User.php            # User management + PGP encryption mode setting
│   │   ├── Group.php           # Group management
│   │   ├── Invite.php          # Invite code system
│   │   ├── Credential.php      # Password storage + cross-user access
│   │   ├── PGPKey.php          # PGP key store + public catalog sync
│   │   ├── Share.php           # PGP-encrypted sharing
│   │   └── Note.php            # Notes system
│   ├── Controllers/            # Request handlers
│   │   ├── AuthController.php
│   │   ├── DashboardController.php
│   │   ├── CredentialController.php
│   │   ├── GroupController.php
│   │   ├── InviteController.php
│   │   ├── PGPController.php         # Key generation + encryption mode toggle (v3.0)
│   │   ├── PGPKeyController.php      # Key Store CRUD + group sharing
│   │   ├── PublicKeyController.php   # Unauthenticated public directory
│   │   ├── ShareController.php
│   │   └── NoteController.php
│   ├── Views/                  # PHP templates
│   │   ├── layouts/            # header.php, footer.php, navigation.php
│   │   ├── auth/               # login.php, register.php
│   │   ├── dashboard/          # index.php
│   │   ├── credentials/        # list, view, create, edit
│   │   ├── pgpkeys/            # list, view, create, edit
│   │   ├── public/             # keys.php (unauthenticated directory)
│   │   ├── groups/             # list, view, create, edit
│   │   ├── invites/            # list
│   │   ├── pgp/                # view (with encryption mode toggle), generate
│   │   └── shares/             # list, view
│   └── Helpers/                # Utility classes
│       ├── Validator.php       # Input validation
│       ├── Sanitizer.php       # XSS prevention
│       └── Logger.php          # Activity logging
├── data/                        # Encrypted storage (outside web root)
│   ├── users.json.enc          # Encrypted user database
│   ├── groups.json.enc         # Encrypted groups
│   ├── invites.json.enc        # Encrypted invites
│   ├── credentials/            # Per-user credential files
│   │   ├── {userId}.json.enc   #   AES mode  – master application key
│   │   └── {userId}.pgp.enc    #   PGP mode  – user's own RSA/EC key pair
│   ├── pgpkeys/                # Per-user PGP public-key stores
│   │   ├── {userId}.json.enc   #   AES mode  – master application key
│   │   ├── {userId}.json       #   PGP mode  – plain JSON (public keys need no encryption)
│   │   └── public_catalog.json.enc  # Shared public key catalog
│   ├── shares/                 # Shared credential metadata
│   ├── notes/                  # Notes storage
│   ├── pgp/                    # Personal PGP key pairs
│   │   ├── {userId}_public.key     # PEM public key
│   │   └── {userId}_private.key.enc # Passphrase-protected private key
│   └── logs/                   # Activity logs
└── config/                      # Configuration files
    ├── config.php              # Main configuration
    ├── database.php            # Storage paths
    └── security.php            # Master key & crypto settings
```

## Usage

### First Steps

1. **Login** with admin credentials created during installation
2. **Generate PGP Keys** (My PGP -> Generate)
   - Choose encryption algorithm (RSA recommended)
   - Select key size (4096 bits for maximum security)
   - Or choose Elliptic Curve for modern cryptography
3. **Add Credentials** (Dashboard -> New Credential)
   - Optionally assign to groups at creation time
4. **Import PGP Keys** (Key Store -> Import PGP Key)
   - Optionally list in public directory
5. **Create Groups** (Groups -> Create Group)
6. **Invite Users** (Invites -> Generate Invite Code)
7. **Share Credentials** (Credential -> Share with Group)

### Credential Types

PassGram supports multiple credential types:
- **Password** - Standard login credentials
- **Note** - Secure notes
- **Card** - Credit card information
- **Identity** - Personal information

### Sharing Credentials with Groups

1. Navigate to the credential
2. Scroll to "Group Sharing" section
3. Select a group from the dropdown
4. Choose permission level:
   - **Read Only** - Members can view the credential
   - **Read & Write** - Members can view and edit the credential
5. Click "Share with Group"

All group members will immediately have access to the credential based on their permission level.

### PGP Key Store

1. Navigate to **Key Store** in the navigation
2. Click **Import PGP Key**
3. Fill in label, owner name, owner email
4. Paste the PEM-encoded public key
5. Optionally check **"List this key in the public directory"**
6. Optionally select groups to share with
7. Click **Store PGP Key**

### Public PGP Key Directory

- Accessible at `/index.php?page=keys` without logging in
- Linked from the login page
- Search by name, email, label, or fingerprint using the search box
- Click **Copy Key** to copy the full public key to clipboard
- Click **Copy FP** to copy the fingerprint

### Managing Groups

As a group owner, you can:

1. **Add Members** - Enter username to add existing users
2. **Remove Members** - Click "Remove" next to member name
3. **Transfer Ownership** - Select new owner from dropdown
4. **Edit Group** - Change name and description
5. **Delete Group** - Permanently remove group (with confirmation)

### PGP Key Options

When generating PGP keys, choose from multiple encryption algorithms:

**RSA (Recommended)**
- Most widely compatible
- Key sizes: 2048, 3072, or 4096 bits
- Best for general use

**DSA (Legacy)**
- For compatibility with older systems
- Limited to signing operations
- Not recommended for new deployments

**Elliptic Curve (Modern)**
- Strong security with smaller keys
- Curves: secp384r1 (recommended), secp521r1 (maximum), prime256v1
- May have compatibility issues with older systems

## Security Considerations

### Master Application Key (MAK)
- Generated during installation
- Encrypts all JSON database files
- **Never change it** - all data becomes unrecoverable
- Backup `config/security.php` securely offline

### User Master Password
- Used for authentication (bcrypt hash)
- Derives encryption key for PGP private key (Argon2id)
- **Never stored** - only hashes stored
- Cannot be recovered if forgotten

### Public Key Directory
- Only voluntarily published data is shown (owner must check the "public" box)
- Notes, tags, and group sharing info are never exposed
- The public catalog is a separate encrypted file synced on create/edit/delete
- Public keys are inherently public data - no sensitive information is leaked

### HTTPS
**Always use HTTPS in production.** Password managers should never run over HTTP.

### Backups
Backup these regularly:
- `config/security.php` - Contains MAK
- `data/` directory - All encrypted data

## Technical Details

### No Dependencies
PassGram is completely standalone:
- **No Composer** required
- **No external libraries**
- Uses native PHP OpenSSL for RSA/PGP operations
- Simple PSR-4 autoloader included

### Encryption Architecture

**Layer 1: Master Application Key**
- Encrypts all JSON database files
- AES-256-GCM algorithm

**Layer 2: User Master Password**
- Hashed with bcrypt for authentication
- Hashed with Argon2id for key derivation
- Never stored in plain text

**Layer 3: PGP Encryption**
- Multiple algorithms: RSA (2048/3072/4096 bits), DSA, Elliptic Curve
- Used for credential sharing between users
- Private keys encrypted with user's PGP passphrase (AES-256-GCM + Argon2id)
- Native PHP OpenSSL implementation

**Layer 3b: PGP Encryption Mode (v3.0)**
- Optional per-user switch to encrypt credential and key-store files with the user's own key pair instead of the master application key
- Hybrid RSA+AES-256-GCM: random session key wrapped with user's public key
- Passphrase stored in server-side session only; cleared on logout
- Credentials: `{userId}.pgp.enc` | Public keys: `{userId}.json` (plain)

**Layer 4: Field-Level Encryption**
- Sensitive credential fields encrypted individually
- AES-256-GCM with random IV per field

### Data Storage
All data stored in encrypted JSON files:
- No SQL database required
- Atomic write operations
- File locking for concurrent access
- Per-user credential and PGP key files for scalability
- Public key catalog synced automatically on create/edit/delete

## Known Limitations

- **No Database** - Uses encrypted JSON files instead of SQL (intentional design choice)
- **Single Server** - Not designed for distributed/clustered deployments
- **File-Based Sessions** - PHP session files (can be configured for Redis/Memcached)
- **No Email** - Invite codes must be shared manually (no email sending)
- **No 2FA** - Two-factor authentication not yet implemented
- **No API** - Web interface only, no REST API

## Browser Compatibility

- Modern browsers (Chrome, Firefox, Safari, Edge)
- JavaScript optional but recommended for enhanced UX
- Copy-to-clipboard requires modern browser with Clipboard API or execCommand support

## License

PassGram v6.00 - Copyright 2025-2026 Jason Page / Amfile.org

## Developer

Developed by **Jason Page** of [Amfile.org](https://amfile.org).

For issues, questions, or contributions, please contact the developer.

---

**PassGram v6.00** - Secure. Simple. Standalone.