pearpass-lib-vault

A secure JavaScript library for managing encrypted vaults in applications. The pearpass-lib-vault provides robust encryption, decryption, and storage capabilities for sensitive data with React and Redux integration.

This library requires one of the following client implementations to function:

• pearpass-lib-vault-bare - For React Native applications
• pearpass-lib-vault-desktop - For Pear desktop applications

Without a proper client implementation, the vault operations cannot be performed.

Table of Contents

• Features
• Security Notice
• Installation
• Usage Examples
• Dependencies
• Related Projects

Features

• Secure Vault Management

  • Create, list, and access encrypted vaults
  • Password-protected vaults with strong encryption
  • Master password protection for vault access

• Storage Flexibility

  • Configurable storage paths
  • Structured data organization

• React & Redux Integration

  • Redux state management for vaults
  • React hooks for easy component integration
  • Actions and selectors for state management

• Comprehensive Testing

  • Full test coverage with Jest
  • Mocked clients for reliable testing

Security Notice

1. To ensure the security and integrity of your projects, please note that official PearPass packages are distributed exclusively through our GitHub organization.
2. Any packages with similar names found on the npm registry or other third-party package managers are not affiliated with PearPass and should be strictly avoided. We recommend installing directly from this repository to ensure you are using the verified, open-source version.

Installation

Install via npm:

npm install git+https://github.com/tetherto/pearpass-lib-vault.git

Usage Examples

Initializing the Library

import { setPearpassVaultClient } from '@tetherto/pearpass-lib-vault';

// Set up the vault client with your implementation
// Choose one of the client implementations:
import { createPearpassVaultClient } from '@tetherto/pearpass-lib-vault-bare';
// OR
import { createPearpassVaultClient } from '@tetherto/pearpass-lib-vault-desktop'

// Initialize the appropriate client
const  vaultClient  = createPearpassVaultClient();

// Set the client for the vault library
setPearpassVaultClient(vaultClient);

Creating a Master Password

import { createMasterPassword } from '@tetherto/pearpass-lib-vault';

// Create a master password to secure all vaults
const encryptionData = await createMasterPassword('your-secure-password');

Using with React Components

import React from 'react';
import { useVaults } from '@tetherto/pearpass-lib-vault';

function VaultManager() {
  const { 
    data: vaults, 
    isLoading, 
    initVaults, 
    refetch 
  } = useVaults({
    onInitialize: (vaults) => console.log('Vaults initialized', vaults),
    onCompleted: (vaults) => console.log('Vaults loaded', vaults)
  });

  // Component implementation...
}

Working with Folders

import React from 'react';
import { useCreateFolder, useFolders } from '@tetherto/pearpass-lib-vault';

function FolderManager() {
  const { data: folders, isLoading } = useFolders({
    variables: { searchPattern: 'personal' }
  });

  const { createFolder, isLoading: isCreatingFolder } = useCreateFolder({
    onCompleted: (payload) => console.log('Folder created:', payload.name),
    onError: (error) => console.error('Error creating folder:', error)
  });

  const handleCreateFolder = () => {
    createFolder('New Personal Folder');
  };

  // Component implementation...
}

Managing Records

import React, { useState } from 'react';
import { useCreateRecord, useRecords, useUpdateRecord } from '@tetherto/pearpass-lib-vault';

function RecordManager({ vaultId }) {
  const [selectedRecord, setSelectedRecord] = useState(null);
  
  const { data: records, isLoading, refetch } = useRecords({
    variables: {
      vaultId,
      filters: {
        type: 'login',
        isFavorite: false
      },
      sort: { field: 'title', direction: 'asc' }
    }
  });

  const { createRecord, isLoading: isCreating } = useCreateRecord({
    onCompleted: () => refetch()
  });

  const { updateRecord, updateFavoriteState } = useUpdateRecord({
    onCompleted: () => refetch()
  });

  const handleCreateRecord = () => {
    createRecord({
      title: 'New Login',
      type: 'login',
      fields: {
        username: '[email protected]',
        password: 'secure-password',
        url: 'https://example.com'
      }
    });
  };

  const handleToggleFavorite = (recordId, currentState) => {
    updateFavoriteState(recordId, !currentState);
  };

  // Component implementation...
}

Dependencies

Peer Dependencies

• react
• react-redux
• redux-toolkit

Related Projects

• @tetherto/pearpass-app-mobile - A mobile app for PearPass, a password manager
• @tetherto/pearpass-app-desktop - A desktop app for PearPass, a password manager
• @tetherto/pearpass-lib-vault-bare - Client implementation for React Native applications
• @tetherto/pearpass-lib-vault-desktop - Client implementation for Pear desktop applications
• @tetherto/pear-apps-utils-validator - A library for validating data in Pear applications
• @tetherto/tether-dev-docs - Documentations and guides for developers

License

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.