{"id":49304,"library":"secure-password","title":"secure-password","description":"Password hashing library using Argon2id via libsodium. Current stable version is 4.0.0, with maintenance releases on GitHub. It provides safe defaults, future-proof work factor upgrades, and uses Buffers for memory safety. Differentiates from bcrypt and scrypt by using the modern Argon2id algorithm and offering explicit rehashing guidance (VALID_NEEDS_REHASH).","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/emilbayes/secure-password","tags":["javascript","password","secure","argon2","libsodium","sodium","credentials"],"install":[{"cmd":"npm install secure-password","lang":"bash","label":"npm"},{"cmd":"yarn add secure-password","lang":"bash","label":"yarn"},{"cmd":"pnpm add secure-password","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Argon2id implementation via libsodium bindings","package":"sodium-native","optional":false}],"imports":[{"note":"ESM import since v4. CommonJS require works but is not recommended for new code.","wrong":"const SecurePassword = require('secure-password')","symbol":"default (SecurePassword)","correct":"import SecurePassword from 'secure-password'"},{"note":"Named export available for explicit imports.","wrong":"import securePassword from 'secure-password'","symbol":"SecurePassword (named)","correct":"import { SecurePassword } from 'secure-password'"},{"note":"Constants are exported as named exports; accessing via instance works but less clean.","wrong":"SecurePassword.MEMLIMIT_DEFAULT (after construction)","symbol":"constants (MEMLIMIT_DEFAULT, etc.)","correct":"import { MEMLIMIT_DEFAULT, MEMLIMIT_MIN, MEMLIMIT_MAX, OPSLIMIT_DEFAULT, OPSLIMIT_MIN, OPSLIMIT_MAX, INVALID, INVALID_UNRECOGNIZED_HASH, VALID, VALID_NEEDS_REHASH } from 'secure-password'"},{"note":"Type-only import for type annotations.","wrong":"import SecurePassword from 'secure-password'","symbol":"SecurePassword type (TypeScript)","correct":"import type { SecurePassword } from 'secure-password'"}],"quickstart":{"code":"import SecurePassword from 'secure-password';\n\nconst pwd = new SecurePassword();\nconst password = Buffer.from('my secret password');\n\n// Hash\nconst hash = await pwd.hash(password);\n\n// Verify\nconst result = await pwd.verify(password, hash);\n\nswitch (result) {\n  case SecurePassword.INVALID_UNRECOGNIZED_HASH:\n    console.error('Hash not made with secure-password. Try legacy.');\n    break;\n  case SecurePassword.INVALID:\n    console.log('Invalid password');\n    break;\n  case SecurePassword.VALID:\n    console.log('Authenticated');\n    break;\n  case SecurePassword.VALID_NEEDS_REHASH:\n    console.log('Authenticated; hash needs upgrade.');\n    const improvedHash = await pwd.hash(password);\n    // save improvedHash\n    break;\n}","lang":"typescript","description":"Hashes and verifies a password using Argon2id with automatic rehashing detection."},"warnings":[{"fix":"Use import syntax instead of require(). For TypeScript, ensure 'esModuleInterop' is true if using default import.","message":"Version 4 drops CommonJS support; only ESM imports are allowed.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Update from sodium-based to sodium-native; verify any custom sodium usage in your code.","message":"Version 4 replaces sodium with sodium-native, changing all crypto operations.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Convert strings to Buffer via Buffer.from(password) before calling hash or verify.","message":"Passwords must be Buffers; passing strings will throw or produce incorrect hashes.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use async/await syntax (e.g., const hash = await pwd.hash(password)).","message":"The callback-based API (pwd.hash(userPassword, cb)) is deprecated in favor of Promise-based async/await.","severity":"deprecated","affected_versions":">=4.0.0"},{"fix":"Import the constants directly: import { MEMLIMIT_DEFAULT } from 'secure-password'.","message":"The MEMLIMIT and OPSLIMIT constants are exported directly, not as properties of the class. Accessing via instance (e.g., pwd.MEMLIMIT_DEFAULT) works but may be misleading.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"search_vec":"'4.0.0':15 'algorithm':47 'argon2':59 'argon2id':8,46 'bcrypt':39 'buffer':33 'credenti':62 'current':11 'default':24 'differenti':37 'explicit':50 'factor':29 'futur':26 'future-proof':25 'github':20 'guidanc':52 'hash':5 'javascript':56 'librari':6 'libsodium':10,60 'mainten':17 'memori':35 'modern':45 'need':54 'offer':49 'password':3,4,57 'proof':27 'provid':22 'rehash':51,55 'releas':18 'safe':23 'safeti':36 'scrypt':41 'secur':2,58 'secure-password':1 'sodium':61 'stabl':12 'upgrad':30 'use':7,32,43 'valid':53 'version':13 'via':9 'work':28","created_at":"2026-06-07T17:01:04.815605+00:00","updated_at":"2026-06-07T17:01:04.815605+00:00","problems":[{"fix":"Change to import SecurePassword from 'secure-password' (ESM).","cause":"CommonJS require() returns undefined because ESM-only package.","error":"TypeError: Cannot read property 'hash' of undefined"},{"fix":"Run 'npm install' and ensure your platform supports sodium-native (requires libsodium). For Alpine Linux, install libsodium-dev.","cause":"Missing sodium-native dependency; often due to incomplete npm install or platform incompatibility.","error":"Error: sodium-native is not installed"},{"fix":"Wrap password with Buffer.from(password).","cause":"Passed a string when Buffer is required.","error":"AssertionError [ERR_ASSERTION]: password must be a Buffer"},{"fix":"Use correct import: import SecurePassword from 'secure-password' or const SecurePassword = require('secure-password').default (for CJS).","cause":"Using new with a wrong import style (e.g., import securePassword from 'secure-password' without default export).","error":"TypeError: securePassword is not a constructor"},{"fix":"Ensure hash was produced by secure-password or implement fallback verification.","cause":"Hash format not recognized; usually from another password library.","error":"Error: Unknown hash: ..."}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/emilbayes/secure-password#readme","github":"https://github.com/emilbayes/secure-password","docs":null,"changelog":null,"pypi":null,"npm":"secure-password","openapi_spec":null,"status_page":null,"smithery":null,"categories":["security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}