Passwords Vault & Bookmarks

Relevant source files

The following files were used as context for generating this wiki page:

• modules/passwords/index.php
• modules/passwords/AGENTS.md
• modules/passwords/AGENT_NOTES.md
• modules/bookmarks/AGENT_NOTES.md
• modules/bookmark_folders/AGENT_NOTES.md
• scripts/api.php
• wiki/Modules.md

The Passwords Vault and Bookmarks modules provide secure, user-centric data management for sensitive credentials and productivity links. The Passwords module is a secure private manager featuring AES-256-CBC encryption at rest, a hierarchical folder structure, and a built-in password generator. The Bookmarks module complements this by allowing users to store and organize URLs, with support for both private and company-shared links.

Both modules utilize a tree-based navigation system for folders and support multi-tenant isolation, ensuring that private data remains scoped to the individual user while shared bookmarks are accessible to the wider company context.

Sources: modules/passwords/AGENTS.md:5-7, modules/bookmarks/AGENT_NOTES.md:4-5, wiki/Modules.md:38-39

Passwords Vault Architecture

The Passwords Vault is designed with a "Zero-Knowledge" approach where sensitive data is only decrypted in memory during an active session. Access requires a master_key which is verified against a hash stored in the users table. Once verified, a vault_key is derived and stored in the session to facilitate real-time encryption and decryption via the itm_encrypt() and itm_decrypt() helpers.

Security and Encryption Flow

The vault remains locked until the user provides the correct master key. The system enforces strict ownership, meaning password entries are strictly private to the user_id and are not shared across the company.

The diagram above illustrates the vault unlocking process and the establishment of the session-based encryption key.
Sources: modules/passwords/index.php:17-45, modules/passwords/AGENT_NOTES.md:14-18, modules/passwords/AGENTS.md:10-14

Data Components

Component	Table / Location	Purpose
Password Entries	password_entries	Stores encrypted account name, login, and password.
Folder Hierarchy	password_folders	Manages nested user-defined folders for organization.
Vault Key Hash	users.vault_key_hash	Used to verify the master key before unlocking the vault.
Password Generator	Frontend JS	Generates high-entropy passwords with configurable complexity.

Sources: modules/passwords/AGENT_NOTES.md:7-10, modules/passwords/index.php:14-16, modules/passwords/AGENTS.md:17-19

Bookmarks Management

The Bookmarks module allows users to manage a collection of URLs within a hierarchical folder structure. Unlike the Passwords module, Bookmarks support a dual-visibility model where a link can be private to a user or shared with the entire company.

Visibility Logic

A bookmark is visible to a user if it meets the following criteria:

1. The company_id matches the current session.
2. The user_id matches the current user OR the shared flag is set to 1.

The flow above describes the multi-tenant and user-privacy filtering applied to bookmark records.
Sources: modules/bookmarks/AGENT_NOTES.md:14-15, modules/bookmark_folders/AGENT_NOTES.md:13-14

Bookmark Folder Structure

Bookmark folders (bookmark_folders table) support nesting via a parent_folder_id and include a position column to preserve user-defined ordering. This structure is shared by both the Bookmarks and Explorer modules to provide a consistent navigation experience.
Sources: modules/bookmark_folders/AGENT_NOTES.md:7-10, modules/bookmark_folders/AGENT_NOTES.md:18-19

API and Data Mobility

Both modules provide endpoints for bulk data operations, including Excel/CSV imports and various export formats.

API Endpoints

Endpoint	Method	Module	Purpose
modules/passwords/ajax_handler.php	POST	Passwords	Async CRUD, folder management, and row imports.
modules/passwords/export_handler.php	GET	Passwords	Secure export to XLSX, CSV, PDF, or TXT.
modules/bookmarks/index.php	POST	Bookmarks	Standard JSON table import via import_excel_rows.

Sources: scripts/api.php:132-140, modules/passwords/index.php:154-165, modules/passwords/AGENT_NOTES.md:23-25

Import Implementation Example

The Passwords module handles Excel imports by parsing the file on the client side (using xlsx.full.min.js) and sending the raw rows to the server.

// From modules/passwords/index.php
function handleExcelImport() {
    const reader = new FileReader();
    reader.onload = function(e) {
        const workbook = XLSX.read(new Uint8Array(e.target.result), {type: 'array'});
        const rows = XLSX.utils.sheet_to_json(workbook.Sheets[workbook.SheetNames[0]], {header: 1});
        apiCall('import_rows', { folder_id: folderId, rows: JSON.stringify(rows) });
    };
}

Sources: modules/passwords/index.php:324-345

Business Rules and Constraints

Passwords Module

• Vault State: If the $_SESSION['vault_key'] is absent, the UI must prompt for the master key and hide all data.
• Encryption Requirement: Data must be stored encrypted using itm_encrypt and the session vault key.
• Masking: Passwords must be masked by default in the UI with a toggle to reveal them.
• Copy Icons: Fields such as Account, Login, and Password must provide a copy-to-clipboard button.

Bookmarks Module

• SQL Ambiguity: Because bookmarks and bookmark_folders both contain active and user_id columns, queries must use explicit aliases (e.g., b.active).
• Sanitization: URLs must be sanitized and prepended with http:// or https:// if missing.

Sources: modules/passwords/AGENTS.md:10-15, modules/bookmarks/AGENT_NOTES.md:27-30, modules/passwords/AGENT_NOTES.md:14-18

The Passwords Vault & Bookmarks system provides a balance between high-security credential storage and convenient link management. By leveraging session-based encryption for passwords and a flexible sharing model for bookmarks, the system ensures data privacy while maintaining multi-tenant integrity.