Passim (TypeScript)

Passim is a lightweight, secure TypeScript library for checking password similarity during password changes or resets. It ensures users don't reuse passwords that are too similar to their previous ones, enhancing security in authentication systems. This version (v1) uses an n-gram-based approach, with a future v2 planned to leverage homomorphic encryption for improved security.

Features

• Secure password hashing with bcrypt.
• Similarity checking using n-gram sketches.
• Configurable parameters (n-gram size, similarity threshold, etc.).

Installation

Install via npm:

npm install passim

Or from source:

git clone https://github.com/nasredeenabdulhaleem/passim-ts.git
cd passim-ts
npm install
npm run build

Dependencies

• Node.js 14+
• bcrypt (included in package)

Usage

import { Passim } from "passim";

// Initialize Passim with default settings
const p = new Passim();

// Store an initial password
(async () => {
  const [hash, sketch] = await p.storePassword("Password123");
  console.log(`Stored hash: ${hash.slice(0, 10)}...`);
  console.log(`Stored sketch:`, sketch);

  // Check a similar password
  const newPassword = "Password124";
  const isSimilar = p.checkSimilarity(sketch, newPassword);
  console.log(`'${newPassword}' is${isSimilar ? " " : " not "}too similar`);

  // Attempt to change password
  const [success, [newHash, newSketch]] = await p.changePassword(
    hash,
    sketch,
    "TotallyNew"
  );
  console.log(`Password change: ${success ? "Accepted" : "Rejected"}`);
})();

API Documentation

Configuration

Passim supports customization via constructor parameters:

• nGramSize (number, default: 3): Size of n-grams for similarity checking.
• similarityThreshold (number, 0-1, default: 0.5): Proportion of matching n-grams that flags a password as "too similar."
• numNgramsToStore (number, default: 5): Maximum n-grams stored in the sketch.

Example:

const p = new Passim(4, 0.7, 3);

Methods

storePassword

Stores a password by generating a bcrypt hash and similarity sketch.

• Input: password (string)
• Output: Promise resolving to [hash: string, sketch: Set]

checkSimilarity

Checks if a new password is too similar to an old one.

• Input: oldSketch (Set), newPassword (string)
• Output: boolean (true if too similar)

changePassword

Attempts to change a password, rejecting it if too similar.

• Input: oldHash (string), oldSketch (Set), newPassword (string)
• Output: Promise resolving to [success: boolean, [newHash: string, newSketch: Set] | [null, null]]

Security Notes

• Password Hashing: Uses bcrypt with a cost factor of 10.
• Similarity Sketch: Stores hashed n-grams, not plaintext. However, this method may leak structural info (e.g., common trigrams). A future v2 will use homomorphic encryption to eliminate this risk.
• Storage: Store hash and sketch securely (e.g., in a database with access controls).

Roadmap

• v2: Replace n-gram sketches with homomorphic encryption.
• Add more similarity metrics (e.g., edit distance).
• Expand test coverage.

Contributing

Open issues or submit pull requests at: github.com/nasredeenabdulhaleem/passim-ts

License

MIT License © 2025 Abdulhaleem Nasredeen