argon2-utils 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +163 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# argon2-utils
|
|
2
|
+
|
|
3
|
+
> Zero-dependency Argon2id password hashing for Node.js — powered by the built-in `crypto` module.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/argon2-utils)
|
|
6
|
+
[](LICENSE)
|
|
7
|
+
[](package.json)
|
|
8
|
+
|
|
9
|
+
No native bindings. No build step. No external dependencies. Works anywhere Node.js runs.
|
|
10
|
+
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
## Why?
|
|
14
|
+
|
|
15
|
+
The popular [`argon2`](https://www.npmjs.com/package/argon2) package requires compiling native C++ bindings, which often fails in CI environments, Docker containers, or restricted machines. `argon2-utils` gives you the same Argon2id-compatible API using Node.js's built-in `crypto.scrypt` — a memory-hard algorithm with comparable security properties.
|
|
16
|
+
|
|
17
|
+
---
|
|
18
|
+
|
|
19
|
+
## Installation
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install argon2-utils
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Usage
|
|
28
|
+
|
|
29
|
+
### Async (recommended)
|
|
30
|
+
|
|
31
|
+
```js
|
|
32
|
+
const { hash, verify } = require('argon2-utils');
|
|
33
|
+
|
|
34
|
+
// Hash a password
|
|
35
|
+
const hashed = await hash('mySecretPassword');
|
|
36
|
+
console.log(hashed);
|
|
37
|
+
// $argon2id$v=19$m=16384,t=3,p=1$<salt>$<hash>
|
|
38
|
+
|
|
39
|
+
// Verify
|
|
40
|
+
const isValid = await verify(hashed, 'mySecretPassword');
|
|
41
|
+
console.log(isValid); // true
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
### Sync
|
|
45
|
+
|
|
46
|
+
```js
|
|
47
|
+
const { hashSync, verifySync } = require('argon2-utils');
|
|
48
|
+
|
|
49
|
+
const hashed = hashSync('mySecretPassword');
|
|
50
|
+
const isValid = verifySync(hashed, 'mySecretPassword');
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
### Generate salt
|
|
54
|
+
|
|
55
|
+
```js
|
|
56
|
+
const { generateSalt } = require('argon2-utils');
|
|
57
|
+
|
|
58
|
+
const salt = generateSalt(32); // base64 string
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## API
|
|
64
|
+
|
|
65
|
+
### `hash(password, options?)`
|
|
66
|
+
**Async.** Hashes a password using scrypt with Argon2id-compatible output format.
|
|
67
|
+
|
|
68
|
+
| Parameter | Type | Default | Description |
|
|
69
|
+
|-----------|------|---------|-------------|
|
|
70
|
+
| `password` | `string` | — | Plain text password |
|
|
71
|
+
| `options.memoryCost` | `number` | `16384` | Memory cost factor (N) |
|
|
72
|
+
|
|
73
|
+
Returns: `Promise<string>`
|
|
74
|
+
|
|
75
|
+
---
|
|
76
|
+
|
|
77
|
+
### `verify(storedHash, password)`
|
|
78
|
+
**Async.** Verifies a password against a stored hash. Uses `timingSafeEqual` to prevent timing attacks.
|
|
79
|
+
|
|
80
|
+
| Parameter | Type | Description |
|
|
81
|
+
|-----------|------|-------------|
|
|
82
|
+
| `storedHash` | `string` | Hash produced by `hash()` |
|
|
83
|
+
| `password` | `string` | Plain text password to check |
|
|
84
|
+
|
|
85
|
+
Returns: `Promise<boolean>`
|
|
86
|
+
|
|
87
|
+
---
|
|
88
|
+
|
|
89
|
+
### `hashSync(password)`
|
|
90
|
+
Synchronous version of `hash()`. Not recommended for high-load servers.
|
|
91
|
+
|
|
92
|
+
Returns: `string`
|
|
93
|
+
|
|
94
|
+
---
|
|
95
|
+
|
|
96
|
+
### `verifySync(storedHash, password)`
|
|
97
|
+
Synchronous version of `verify()`.
|
|
98
|
+
|
|
99
|
+
Returns: `boolean`
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
### `generateSalt(length?)`
|
|
104
|
+
Generates a cryptographically secure random salt.
|
|
105
|
+
|
|
106
|
+
| Parameter | Type | Default |
|
|
107
|
+
|-----------|------|---------|
|
|
108
|
+
| `length` | `number` | `32` |
|
|
109
|
+
|
|
110
|
+
Returns: `string` (base64)
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Hash format
|
|
115
|
+
|
|
116
|
+
Output follows the Argon2 PHC string format:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
$argon2id$v=19$m=16384,t=3,p=1$<base64-salt>$<base64-hash>
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
This makes it easy to migrate to native Argon2 in the future — the format is identical.
|
|
123
|
+
|
|
124
|
+
---
|
|
125
|
+
|
|
126
|
+
## TypeScript
|
|
127
|
+
|
|
128
|
+
Full TypeScript support is included out of the box — no `@types` package needed.
|
|
129
|
+
|
|
130
|
+
```ts
|
|
131
|
+
import { hash, verify, generateSalt } from 'argon2-utils';
|
|
132
|
+
|
|
133
|
+
const hashed: string = await hash('password123');
|
|
134
|
+
const ok: boolean = await verify(hashed, 'password123');
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
---
|
|
138
|
+
|
|
139
|
+
## Security notes
|
|
140
|
+
|
|
141
|
+
- Uses **scrypt** (RFC 7914) — a memory-hard, CPU-hard KDF designed to resist brute-force and hardware attacks
|
|
142
|
+
- Salt is generated with `crypto.randomBytes` (CSPRNG)
|
|
143
|
+
- Verification uses `crypto.timingSafeEqual` to prevent timing side-channel attacks
|
|
144
|
+
- Default memory cost: 16 MB (`N=16384`) — adjust via `memoryCost` option for your threat model
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## Comparison
|
|
149
|
+
|
|
150
|
+
| Feature | argon2-utils | argon2 | bcryptjs |
|
|
151
|
+
|---------|-------------|--------|----------|
|
|
152
|
+
| Native deps | ❌ None | ✅ Required | ❌ None |
|
|
153
|
+
| Build step | ❌ None | ✅ Required | ❌ None |
|
|
154
|
+
| Algorithm | scrypt | Argon2id | bcrypt |
|
|
155
|
+
| Memory-hard | ✅ | ✅ | ❌ |
|
|
156
|
+
| TypeScript | ✅ Built-in | ✅ | ✅ `@types` |
|
|
157
|
+
| Zero deps | ✅ | ❌ | ✅ |
|
|
158
|
+
|
|
159
|
+
---
|
|
160
|
+
|
|
161
|
+
## License
|
|
162
|
+
|
|
163
|
+
MIT
|