ironpass 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aryan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,20 @@
+# IronPass 🔐
+
+Modern password hashing library for Node.js built on PBKDF2.
+
+## Features
+
+- Secure PBKDF2 hashing
+- Configurable iterations
+- Salted password hashing
+- Structured encoded output
+
+## Installation
+
+npm install ironpass
+
+## Usage
+
+import { hash } from 'ironpass';
+
+const hashed = await hash('password123');

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "ironpass",
+  "version": "0.1.0",
+  "description": "Secure password hashing library for Node.js using PBKDF2.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "check-format": "prettier --check .",
+    "prepare": "npm run lint && npm run test"
+  },
+  "keywords": [
+    "password",
+    "password-hashing",
+    "security",
+    "authentication",
+    "pbkdf2",
+    "crypto",
+    "node",
+    "nodejs"
+  ],
+  "author": "Aryan Yadav",
+  "license": "MIT",
+ "repository": {
+  "type": "git",
+  "url": "git+https://github.com/krptonox/Iron-Pass.git"
+},
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.6.0",
+    "globals": "^17.7.0",
+    "prettier": "^3.9.4",
+    "vitest": "^4.1.9"
+  }
+}

package/src/constants/defaults.js

@@ -0,0 +1,11 @@
+export const DEFAULT_SALT_LENGTH = 16;
+
+export const DEFAULT_ITERATIONS = 300000;
+
+export const DEFAULT_KEY_LENGTH = 32;
+
+export const DEFAULT_DIGEST = 'sha256';
+
+export const DEFAULT_ALGORITHM = 'pbkdf2'; 
+
+export const DEFAULT_VERSION = 'v1';

package/src/constants/password.js

@@ -0,0 +1 @@
+export const MAX_PASSWORD_LENGTH = 1024;

package/src/core/audit.core.js

@@ -0,0 +1 @@
+//TO DO

package/src/core/breach.core.js

@@ -0,0 +1 @@
+//TO DO

package/src/core/hash.core.js

@@ -0,0 +1,25 @@
+import { normalizePassword } from '../password/normalizePassword.js';
+
+import { validatePassword } from '../validators/validatePassword.js';
+
+import { generateSalt } from '../crypto/generateSalt.js';
+
+import { deriveKey } from '../crypto/deriveKey.js';
+
+import { encodeHash } from '../crypto/encodeHash.js';
+
+
+export async function hash(password, options = {}){
+    
+    const normalizedPassword = normalizePassword(password);
+
+    const validatedPassword = validatePassword(normalizedPassword);
+
+    const salt = generateSalt();
+
+    const  derivedKey = await deriveKey(validatedPassword, salt, options);
+
+    const encodedHash = encodeHash(derivedKey, salt, options);
+
+    return encodedHash;
+}

package/src/core/verify.core.js

@@ -0,0 +1 @@
+//TO DO

package/src/crypto/deriveKey.js

@@ -0,0 +1,30 @@
+import { DEFAULT_ITERATIONS, DEFAULT_KEY_LENGTH,DEFAULT_DIGEST } from '../constants/defaults.js';
+import crypto from 'node:crypto';
+import { validateOptions } from '../validators/validateDeriveKeyOptions.js';
+import { validatePassword } from '../validators/validatePassword.js';
+import { validateSalt } from '../validators/validateSalt.js';
+
+export function deriveKey(password, salt, options = {
+}){
+
+    validatePassword(password);
+    validateOptions(options);
+    validateSalt(salt);
+
+    const {
+    iterations = DEFAULT_ITERATIONS,
+    keyLength = DEFAULT_KEY_LENGTH,
+    digest = DEFAULT_DIGEST,
+    } = options;
+
+  return new Promise((resolve, reject) => {
+      crypto.pbkdf2(password,salt,iterations,keyLength,digest,(error, derivedKey)=>{
+        if(error){
+            reject(error);
+            return;
+        }
+
+        resolve(derivedKey);
+      });
+  });
+}

package/src/crypto/encodeHash.js

@@ -0,0 +1,32 @@
+import { DEFAULT_ALGORITHM, DEFAULT_VERSION, DEFAULT_DIGEST, DEFAULT_ITERATIONS, DEFAULT_KEY_LENGTH } from '../constants/defaults.js';
+
+import { validateSalt } from '../validators/validateSalt.js';
+
+import { validateDerivedKey } from '../validators/validateDerivedKey.js';
+
+import { validateOptions } from '../validators/validateDeriveKeyOptions.js';
+
+
+
+export function encodeHash(derivedKey, salt, options={}){
+
+    validateSalt(salt);
+    validateDerivedKey(derivedKey);
+    validateOptions(options);
+
+    const version = DEFAULT_VERSION;
+    const algorithm = DEFAULT_ALGORITHM;
+    
+    const {
+        iterations = DEFAULT_ITERATIONS,
+        keyLength = DEFAULT_KEY_LENGTH,
+        digest = DEFAULT_DIGEST,
+    } = options;
+
+    const derivedKeyHex = derivedKey.toString('hex');
+
+    const hash = `${version}$${algorithm}$${digest}$${iterations}$${keyLength}$${salt}$${derivedKeyHex}`;
+
+    return hash;
+
+}

package/src/crypto/generateSalt.js

@@ -0,0 +1,12 @@
+import {randomBytes} from '../crypto/random.js';
+import { DEFAULT_SALT_LENGTH } from '../constants/defaults.js';
+import { validateSalt } from '../validators/validateSalt.js';
+
+export function generateSalt(length = DEFAULT_SALT_LENGTH){
+
+    const buffer = randomBytes(length);
+
+    validateSalt(buffer.toString('hex'));
+
+    return buffer.toString('hex');
+}

package/src/crypto/random.js

@@ -0,0 +1,20 @@
+/**
+ * Generate cryptographically secure random bytes.
+ *
+ * @param {number} length
+ * @returns {Buffer}
+ */
+
+
+import crypto from 'node:crypto';
+import {InvalidLengthError} from '../errors/InvalidLengthError.js';
+
+export function randomBytes(length){
+    if(typeof length !== 'number' || length <= 0 || !Number.isInteger(length)){
+        throw new InvalidLengthError();
+    }
+
+    const buffer = crypto.randomBytes(length);
+
+    return buffer;
+}

package/src/errors/InvalidLengthError.js

@@ -0,0 +1,10 @@
+class InvalidLengthError extends Error {
+  constructor(
+    message = 'Length must be a positive integer greater than 0.'
+  ) {
+    super(message);
+    this.name = 'InvalidLengthError';
+  }
+}
+
+export { InvalidLengthError };

package/src/errors/InvalidNormalizationFormError.js

@@ -0,0 +1,8 @@
+class InvalidNormalizationFormError extends Error {
+    constructor(message= 'Invalid normalization form. Must be one of NFC, NFD, NFKC, or NFKD. or pass a String'){
+        super(message);
+        this.message = message;
+    }
+}
+
+export { InvalidNormalizationFormError };

package/src/errors/InvalidOptionsError.js

@@ -0,0 +1,8 @@
+class InvalidOptionsError extends Error{
+    constructor(message='Invalid options provided. Please check the options and try again.'){
+        super(message);
+        this.message = message;
+    }
+}
+
+export default InvalidOptionsError;

package/src/errors/InvalidPasswordError.js

@@ -0,0 +1,9 @@
+class InvalidPasswordError extends Error{
+    constructor(message = 'Invalid password provided.'){
+        super(message);
+        this.name = 'InvalidPasswordError';
+        this.message = message;
+    }
+}
+
+export default InvalidPasswordError;

package/src/errors/InvalidSaltError.js

@@ -0,0 +1,8 @@
+class InvalidSaltError extends Error {
+    constructor(message='Invalid salt provided'){
+        super(message);
+        this.name = message;
+    }
+}
+
+export {InvalidSaltError};

package/src/index.js

@@ -0,0 +1,2 @@
+// src/index.js
+export { hash } from './core/hash.core.js';

package/src/password/normalizePassword.js

@@ -0,0 +1,19 @@
+import { InvalidNormalizationFormError } from '../errors/InvalidNormalizationFormError.js';
+
+
+const VALID_NORMALIZATION_FORMS = ['NFC','NFD','NFKC','NFKD'];
+
+
+export function normalizePassword(password,form = 'NFC'){
+    if(typeof password !== 'string'){
+        throw new TypeError('Password must be a string.');
+    }
+
+    if(!VALID_NORMALIZATION_FORMS.includes(form)){
+        throw new InvalidNormalizationFormError('Invalid normalization form');
+    }
+
+    const normalizedPassword = password.normalize(form);
+
+    return normalizedPassword;
+}

package/src/validators/validateDeriveKeyOptions.js

@@ -0,0 +1,39 @@
+import InvalidOptionsError from '../errors/InvalidOptionsError.js';
+
+export function validateOptions(options){
+ //to check the options , are they valid or not 
+ const VALID_KEYS = [
+    'iterations',
+    'keyLength',
+    'digest'
+];
+
+ 
+    if (!options || typeof options !== 'object') {
+    throw new InvalidOptionsError('Options must be an object');
+    }
+    
+ for(const key of Object.keys(options)){
+
+    if(!VALID_KEYS.includes(key)){
+        throw new InvalidOptionsError(`Invalid option provided: ${key}`);
+    }
+
+    if(key === 'digest' && typeof options[key] !== 'string'){
+        throw new InvalidOptionsError(`Invalid type for option ${key}. Expected a string.`);
+    }
+
+    if(key === 'iterations' && (options[key] <= 0 || !Number.isInteger(options[key]))){
+        throw new InvalidOptionsError(`Invalid value for option ${key}. Must be a positive integer.`);
+    }
+
+    if(key === 'keyLength' && (options[key] <= 0 || !Number.isInteger(options[key]))){
+        throw new InvalidOptionsError(`Invalid value for option ${key}. Must be a positive integer.`);
+    }
+
+    if(key === 'digest' && !['sha256', 'sha512'].includes(options[key])){
+        throw new InvalidOptionsError(`Invalid value for option ${key}. Must be either 'sha256' or 'sha512'.`);
+    }
+    
+ }
+}

package/src/validators/validateDerivedKey.js

@@ -0,0 +1,5 @@
+export function validateDerivedKey(derivedKey) {
+    if (!Buffer.isBuffer(derivedKey)) {
+        throw new Error('Derived key must be a Buffer');
+    }
+}

package/src/validators/validatePassword.js

@@ -0,0 +1,18 @@
+import InvalidPasswordError from '../errors/InvalidPasswordError.js';
+import { MAX_PASSWORD_LENGTH } from '../constants/password.js';
+
+export function validatePassword(password){
+    if(typeof password !== 'string'){
+        throw new InvalidPasswordError('Password must be a string.');
+    }
+
+    if(password === ''){
+        throw new InvalidPasswordError('Password is required.');
+    }
+
+    if(password.length > MAX_PASSWORD_LENGTH){
+        throw new InvalidPasswordError('Password is too long.');
+    }
+
+    return password;
+}

package/src/validators/validateSalt.js

@@ -0,0 +1,10 @@
+import {InvalidSaltError} from '../errors/InvalidSaltError.js';
+
+export function validateSalt(salt) {
+    if (!salt) {
+        throw new InvalidSaltError();
+    }
+    if (typeof salt !== 'string') {
+        throw new InvalidSaltError('Salt must be a string');
+    }
+}