@nexwage/crypto 0.1.0 → 0.1.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.
Files changed (2) hide show
  1. package/README.md +346 -96
  2. package/package.json +6 -2
package/README.md CHANGED
@@ -1,14 +1,19 @@
1
1
  # @nexwage/crypto
2
2
 
3
- Minimal, opinionated crypto building blocks for password-based master keys, recovery keys, and file encryption. Built on libsodium with XChaCha20-Poly1305 and Argon2.
3
+ Library kripto minimal berbasis libsodium untuk alur master key, recovery key, dan enkripsi file. Menggunakan XChaCha20-Poly1305 untuk AEAD dan Argon2 untuk KDF password.
4
4
 
5
- ## Install
5
+ ## Instalasi
6
6
 
7
7
  ```sh
8
8
  npm i @nexwage/crypto
9
9
  ```
10
10
 
11
- ## Quick Start
11
+ ## Kompatibilitas
12
+
13
+ - ESM (type: module)
14
+ - Node.js 18+ (direkomendasikan)
15
+
16
+ ## Mulai Cepat
12
17
 
13
18
  ```ts
14
19
  import {
@@ -18,12 +23,14 @@ import {
18
23
  wrapMasterKeyWithRecoveryKey,
19
24
  generateFileKey,
20
25
  wrapFileKeyWithMasterKey,
26
+ unwrapFileKeyWithMasterKey,
21
27
  encryptFileData,
22
28
  decryptFileData,
29
+ fromString,
23
30
  } from "@nexwage/crypto";
24
31
 
25
32
  const password = "strong-password";
26
- const aad = new TextEncoder().encode("uid:user_123|app:v1|slot:password");
33
+ const aad = fromString("uid:user_123|app:v1|slot:password");
27
34
 
28
35
  const { masterKey, wrapped } = await generateMasterKeyWithPassword(
29
36
  password,
@@ -41,7 +48,7 @@ const wrappedByRecovery = await wrapMasterKeyWithRecoveryKey(
41
48
  const fileKey = await generateFileKey();
42
49
  const wrappedFileKey = await wrapFileKeyWithMasterKey(fileKey, masterKey, aad);
43
50
 
44
- const fileBytes = new TextEncoder().encode("file rahasia");
51
+ const fileBytes = fromString("file rahasia");
45
52
  const encryptedFile = await encryptFileData(fileKey, fileBytes, aad);
46
53
 
47
54
  const masterKey2 = await unwrapMasterKeyWithPassword(password, wrapped, aad);
@@ -53,119 +60,362 @@ const fileKey2 = await unwrapFileKeyWithMasterKey(
53
60
  const decryptedFile = await decryptFileData(fileKey2, encryptedFile, aad);
54
61
  ```
55
62
 
56
- ## Project Structure
63
+ ## Konsep Utama
64
+
65
+ - Master Key: kunci utama untuk membuka kunci lain.
66
+ - Recovery Key: kunci cadangan jika password hilang.
67
+ - File Key: kunci khusus per file.
68
+ - Wrap/Unwrap: membungkus dan membuka kunci memakai AEAD.
69
+ - AAD: data konteks yang diikat ke ciphertext (tidak dienkripsi).
70
+ - Versioning: field `v` pada payload untuk kompatibilitas format.
71
+
72
+ ## Alur Dasar
73
+
74
+ Alur 1: Setup awal + upload
75
+ 1) Generate master key lalu wrap dengan password.
76
+ 2) Generate recovery key.
77
+ 3) Wrap master key dengan recovery key (recovery).
78
+ 4) Wrap recovery key dengan master key (backup recovery key).
79
+ 5) Generate file key.
80
+ 6) Wrap file key dengan master key.
81
+ 7) Enkripsi file pakai file key.
82
+
83
+ Alur 2: Buka file (login normal)
84
+ 1) Ambil wrapped master key.
85
+ 2) Unwrap master key pakai password.
86
+ 3) Unwrap file key pakai master key.
87
+ 4) Dekripsi file.
88
+
89
+ Alur 3: Recovery + re-encrypt
90
+ 1) Ambil wrapped master key.
91
+ 2) Unwrap master key pakai recovery key.
92
+ 3) Re-wrap master key dengan password baru.
57
93
 
58
- | Path | Purpose |
59
- | --- | --- |
60
- | `src/index.ts` | Public exports. |
61
- | `src/types.ts` | Payload types + versioning. |
62
- | `src/crypto/password-kdf.ts` | Password KDF + key wrapping. |
63
- | `src/crypto/master-key.ts` | Master key lifecycle. |
64
- | `src/crypto/recovery-key.ts` | Recovery key wrapping. |
65
- | `src/crypto/file-encryption.ts` | File key + file encryption. |
66
- | `src/utils/encoding.ts` | Base64 helpers. |
67
- | `src/utils/bytes.ts` | Byte length assertions. |
68
- | `src/sodium.ts` | libsodium wrapper exports. |
69
- | `examples/basic-flow.ts` | End-to-end flow. |
70
- | `examples/master-key-example.ts` | Master key example. |
94
+ ## Referensi API
71
95
 
72
- ## AAD and Versioning
96
+ Semua fungsi diekspor dari `@nexwage/crypto`.
97
+
98
+ ### Peta Penggunaan di Kasus Industri (Per Domain)
99
+
100
+ #### Simetris (Password + File + Recovery)
101
+
102
+ | Metode/Fitur | Kasus Industri Nyata | Kenapa Dipakai | Contoh Implementasi |
103
+ | --- | --- | --- | --- |
104
+ | Master Key + Password KDF | Zero‑knowledge SaaS (password vault, secure notes) | Password tidak pernah dikirim ke server; master key tetap terenkripsi | `generateMasterKeyWithPassword` saat signup, simpan `wrapped` di server |
105
+ | Recovery Key | Recovery akun tanpa reset password | Memberi opsi recovery tanpa membuka password | Simpan `wrapMasterKeyWithRecoveryKey` di server, recovery key dipegang user |
106
+ | File Key + Wrap | Enkripsi per file untuk performa dan isolasi | Setiap file punya key sendiri; kompromi satu file tidak bocor semua | `generateFileKey` + `wrapFileKeyWithMasterKey` per file |
107
+ | AEAD XChaCha20-Poly1305 | Enkripsi data at rest/in transit | Authenticated encryption, tahan tampering | `encryptFileData` / `decryptFileData` |
108
+ | AAD | Bind data ke konteks (userId, fileId, slot) | Mencegah swap/replay antar konteks | AAD berisi `userId|fileId|slot` |
109
+ | Versioning (`v`) | Migrasi format/enkripsi | Menjaga kompatibilitas payload lama | Simpan `v` di payload, upgrade saat decrypt |
110
+
111
+ #### Asimetris (Key Exchange + Signature)
112
+
113
+ | Metode/Fitur | Kasus Industri Nyata | Kenapa Dipakai | Contoh Implementasi |
114
+ | --- | --- | --- | --- |
115
+ | Key Exchange (X25519) | Secure session key (chat, realtime sync) | Negosiasi kunci simetris tanpa berbagi rahasia | `deriveClientSessionKeys` + `deriveServerSessionKeys` |
116
+ | Sealed Box | Share ke penerima tanpa keypair pengirim | Enkripsi langsung ke public key penerima | `encryptSealedBox` untuk file sharing 1:1 |
117
+ | Signature (Ed25519) | Audit log, proof of authorship | Verifikasi integritas dan sumber data | Tanda tangan metadata/commit dengan `signMessage` |
118
+
119
+ #### Group (MLS-like)
120
+
121
+ | Metode/Fitur | Kasus Industri Nyata | Kenapa Dipakai | Contoh Implementasi |
122
+ | --- | --- | --- | --- |
123
+ | Group Commit + Epoch | Team sharing (drive tim, workspace) | Rotasi kunci saat member berubah | `createGroupCommit` + `applyGroupCommit` setiap perubahan anggota |
124
+ | Group Key Derivation | Enkripsi grup skala besar | Satu group key untuk banyak file | `deriveGroupKey` untuk wrap file key |
125
+ | Welcome Payload | Onboarding member baru | Distribusi secret awal dengan aman | `createGroupState` + `openGroupWelcome` |
126
+
127
+ #### Wrapper libsodium
128
+
129
+ | Metode/Fitur | Kasus Industri Nyata | Kenapa Dipakai | Contoh Implementasi |
130
+ | --- | --- | --- | --- |
131
+ | libsodium Wrapper | Akses primitive low-level | Integrasi fleksibel ke arsitektur existing | `cryptoPwhash`, `aeadXChaCha20Poly1305IetfEncrypt` |
132
+
133
+ ### Tipe Export
134
+
135
+ - `AeadEnvelopeV1`
136
+ - `PasswordKdfParamsV1`
137
+ - `PasswordWrappedKeyV1`
138
+ - `PasswordKdfOptions`
139
+ - `KeyExchangeKeyPair`
140
+ - `SessionKeys`
141
+ - `SigningKeyPair`
142
+ - `GroupMember`
143
+ - `GroupMemberWire`
144
+ - `GroupState`
145
+ - `GroupWelcome`
146
+ - `GroupCommit`
147
+ - `GroupCommitAction`
148
+
149
+ ### Master Key
150
+
151
+ - `generateMasterKey(): Promise<Uint8Array>`
152
+ - `generateMasterKeyWithPassword(password, opts?, aad?): Promise<{ masterKey; wrapped }>`
153
+ - `wrapMasterKeyWithPassword(masterKey, password, opts?, aad?): Promise<PasswordWrappedKeyV1>`
154
+ - `unwrapMasterKeyWithPassword(password, wrapped, aad?): Promise<Uint8Array>`
155
+
156
+ ### Recovery Key
157
+
158
+ - `generateRecoveryKey(): Promise<Uint8Array>`
159
+ - `wrapMasterKeyWithRecoveryKey(masterKey, recoveryKey, aad?): Promise<AeadEnvelopeV1>`
160
+ - `unwrapMasterKeyWithRecoveryKey(recoveryKey, wrapped, aad?): Promise<Uint8Array>`
161
+ - `wrapRecoveryKeyWithMasterKey(recoveryKey, masterKey, aad?): Promise<AeadEnvelopeV1>`
162
+ - `unwrapRecoveryKeyWithMasterKey(masterKey, wrapped, aad?): Promise<Uint8Array>`
163
+
164
+ ### File Encryption
165
+
166
+ - `generateFileKey(): Promise<Uint8Array>`
167
+ - `wrapFileKeyWithMasterKey(fileKey, masterKey, aad?): Promise<AeadEnvelopeV1>`
168
+ - `unwrapFileKeyWithMasterKey(masterKey, wrapped, aad?): Promise<Uint8Array>`
169
+ - `encryptFileData(fileKey, plaintext, aad?): Promise<AeadEnvelopeV1>`
170
+ - `decryptFileData(fileKey, wrapped, aad?): Promise<Uint8Array>`
171
+
172
+ ### Password KDF
173
+
174
+ - `deriveKeyFromPassword(password, opts?): Promise<{ key; kdf }>`
175
+ - `wrapKeyWithPassword(key, password, opts?, aad?): Promise<PasswordWrappedKeyV1>`
176
+ - `unwrapKeyWithPassword(password, wrapped, aad?): Promise<Uint8Array>`
177
+
178
+ Opsi KDF (`PasswordKdfOptions`):
179
+ - `opslimit` (number)
180
+ - `memlimit` (number)
181
+ - `salt` (Uint8Array)
182
+
183
+ ### Utilitas Encoding
184
+
185
+ - `encodeBase64(u8): string`
186
+ - `decodeBase64(s): Uint8Array`
187
+ - `fromString(s): Uint8Array`
188
+ - `toString(u8): string`
189
+
190
+ ### Wrapper libsodium
191
+
192
+ Wrapper disediakan agar fungsi libsodium bisa dipanggil dari library ini:
73
193
 
74
- - AAD (Additional Authenticated Data) binds ciphertext to context (userId, slot, fileId).
75
- - Versioning (`v`) keeps payloads forward-compatible when formats or algorithms change.
194
+ - `sodiumReady(): Promise<void>`: wajib dipanggil jika ingin akses konstanta libsodium secara aman.
195
+ - `randombytesBuf(size): Uint8Array`
196
+ - `cryptoPwhash(outLen, password, salt, opslimit, memlimit, alg): Uint8Array`
197
+ - `cryptoPwhashSaltBytes`
198
+ - `cryptoPwhashOpslimitModerate`
199
+ - `cryptoPwhashMemlimitModerate`
200
+ - `aeadXChaCha20Poly1305IetfEncrypt(message, aad, secretNonce, publicNonce, key)`
201
+ - `aeadXChaCha20Poly1305IetfDecrypt(secretNonce, ciphertext, aad, publicNonce, key)`
202
+ - `aeadXChaCha20Poly1305IetfNpubBytes`
203
+ - `toBase64(u8): string`
204
+ - `fromBase64(s): Uint8Array`
205
+ - `base64VariantOriginal`
206
+ - `memcmp(a, b): boolean`
207
+ - `sodium` (akses penuh ke instance libsodium)
208
+
209
+ Catatan: konstanta seperti `cryptoPwhashSaltBytes` diisi setelah `sodiumReady()` dipanggil.
210
+
211
+ ### Asimetris: Key Exchange & Signature
212
+
213
+ Library ini menyediakan dua keypair terpisah:
214
+ 1) X25519 untuk key exchange/shared key.
215
+ 2) Ed25519 untuk tanda tangan digital.
216
+
217
+ Key exchange (X25519):
218
+ - `generateKeyExchangeKeyPair(): Promise<{ publicKey; privateKey }>`
219
+ - `deriveClientSessionKeys(clientKeyPair, serverPublicKey): Promise<{ rx; tx }>`
220
+ - `deriveServerSessionKeys(serverKeyPair, clientPublicKey): Promise<{ rx; tx }>`
221
+ - `encryptSealedBox(message, recipientPublicKey): Promise<Uint8Array>`
222
+ - `decryptSealedBox(ciphertext, recipientKeyPair): Promise<Uint8Array>`
223
+
224
+ Signature (Ed25519):
225
+ - `generateSigningKeyPair(): Promise<{ publicKey; privateKey }>`
226
+ - `signMessage(message, privateKey): Promise<Uint8Array>`
227
+ - `verifySignature(message, signature, publicKey): Promise<boolean>`
228
+
229
+ ### Group (MLS-like, tahap awal)
230
+
231
+ Implementasi awal untuk group key management dengan commit + epoch. Saat ini masih O(n) karena secret baru dibagikan via sealed box ke setiap member. Struktur API disiapkan agar dapat ditingkatkan ke tree-based MLS.
232
+
233
+ - `createGroupState(groupId, members): Promise<{ state; welcome }>`
234
+ - `openGroupWelcome(welcome, recipientId, recipientKeyPair): Promise<GroupState>`
235
+ - `deriveGroupKey(state): Promise<Uint8Array>`
236
+ - `createGroupCommit(state, senderId, senderSignPrivateKey, action, updates?): Promise<{ commit; state }>`
237
+ - `verifyGroupCommitSignature(commit, senderSignPublicKey): Promise<boolean>`
238
+ - `applyGroupCommit(state, commit, recipientId, recipientKeyPair, senderSignPublicKey): Promise<GroupState>`
239
+
240
+ Catatan:
241
+ - `GroupMember.signPublicKey` bersifat opsional dan hanya diperlukan jika kamu ingin menyimpan public key signature di metadata group.
242
+ - Semua payload group disarankan disimpan sebagai JSON di server (zero-knowledge friendly).
243
+
244
+ ## Format Payload
76
245
 
77
- ## Manual Test
246
+ AEAD envelope:
247
+ ```json
248
+ {
249
+ "v": 1,
250
+ "nonce": "base64",
251
+ "ct": "base64"
252
+ }
253
+ ```
78
254
 
79
- See `examples/basic-flow.ts` for the full 3-flow example.
255
+ Password-wrapped key:
256
+ ```json
257
+ {
258
+ "v": 1,
259
+ "kdf": { "v": 1, "salt": "...", "opslimit": 3, "memlimit": 268435456 },
260
+ "nonce": "....",
261
+ "ct": "...."
262
+ }
263
+ ```
80
264
 
81
- ## Glossary
265
+ ## AAD (Additional Authenticated Data)
82
266
 
83
- Panduan ringkas istilah dan konsep yang dipakai di modul ini.
267
+ AAD digunakan untuk mengikat ciphertext ke konteks (mis. userId, slot, fileId). Jika AAD salah, proses decrypt akan gagal.
84
268
 
85
- | Term | Meaning |
86
- | --- | --- |
87
- | Master Key (MK) | Kunci utama untuk membuka kunci lain (file key, recovery key). |
88
- | Recovery Key | Kunci cadangan jika lupa password. |
89
- | File Key | Kunci khusus per file. |
90
- | Wrap/Unwrap | Membungkus dan membuka kunci menggunakan enkripsi. |
91
- | AEAD | Enkripsi + integritas dalam satu skema. |
92
- | AAD | Metadata yang diikat ke ciphertext tanpa dienkripsi. |
93
- | KDF | Mengubah password menjadi key yang kuat. |
94
- | Nonce | Angka acak sekali pakai untuk enkripsi. |
95
- | Ciphertext (ct) | Hasil enkripsi. |
96
- | Envelope | Struktur payload berisi `nonce`, `ct`, dan `v`. |
97
- | Versioning (v) | Versi format payload. |
269
+ Contoh AAD:
270
+ ```ts
271
+ import { fromString } from "@nexwage/crypto";
272
+ const aad = fromString("uid:user_123|app:v1|slot:password");
273
+ ```
98
274
 
99
- ## libsodium Functions Used
275
+ ## Penanganan Error
100
276
 
101
- | Function/Property | Description |
102
- | --- | --- |
103
- | `sodium.ready` | Menunggu libsodium siap dipakai. |
104
- | `sodium.randombytes_buf` | Generate bytes acak (kunci, nonce). |
105
- | `sodium.crypto_pwhash` | Derivasi key dari password (Argon2). |
106
- | `sodium.crypto_pwhash_SALTBYTES` | Panjang salt untuk KDF. |
107
- | `sodium.crypto_pwhash_OPSLIMIT_MODERATE` | Default opslimit KDF. |
108
- | `sodium.crypto_pwhash_MEMLIMIT_MODERATE` | Default memlimit KDF. |
109
- | `sodium.crypto_aead_xchacha20poly1305_ietf_encrypt` | Enkripsi AEAD XChaCha20-Poly1305. |
110
- | `sodium.crypto_aead_xchacha20poly1305_ietf_decrypt` | Dekripsi AEAD XChaCha20-Poly1305. |
111
- | `sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES` | Panjang nonce AEAD XChaCha20-Poly1305. |
112
- | `sodium.to_base64` | Encode bytes ke base64. |
113
- | `sodium.from_base64` | Decode base64 ke bytes. |
114
- | `sodium.base64_variants.ORIGINAL` | Variant base64 yang dipakai. |
115
- | `sodium.from_string` | Encode string ke bytes (UTF-8). |
116
- | `sodium.to_string` | Decode bytes ke string (UTF-8). |
117
- | `sodium.memcmp` | Bandingkan bytes secara aman (constant-time). |
118
-
119
- ## Planned libsodium Functions
120
-
121
- | Function/Property | Planned use |
277
+ - Jika ukuran key/salt/nonce salah, fungsi akan melempar error validasi.
278
+ - Jika password/AAD salah, decrypt akan gagal dan melempar error.
279
+
280
+ ## Struktur Proyek
281
+
282
+ | Path | Tujuan |
122
283
  | --- | --- |
123
- | `sodium.crypto_generichash` | Hash konteks/AAD jika perlu bentuk stabil dan ringkas. |
124
- | `sodium.crypto_kdf_derive_from_key` | Derivasi sub-key per domain dari satu kunci root. |
125
- | `sodium.crypto_aead_aes256gcm_encrypt` | Alternatif AEAD dengan akselerasi hardware. |
126
- | `sodium.crypto_aead_aes256gcm_decrypt` | Pasangan decrypt AES-GCM. |
127
- | `sodium.crypto_secretbox_easy` | Enkripsi simetris sederhana untuk payload non-AEAD. |
128
- | `sodium.crypto_secretbox_open_easy` | Dekripsi secretbox. |
284
+ | `src/index.ts` | Public exports. |
285
+ | `src/types.ts` | Tipe payload dan versioning. |
286
+ | `src/crypto/password-kdf.ts` | KDF password + wrap/unwrap key. |
287
+ | `src/crypto/master-key.ts` | Lifecycle master key. |
288
+ | `src/crypto/recovery-key.ts` | Recovery key wrapping. |
289
+ | `src/crypto/file-encryption.ts` | File key + enkripsi/dekripsi file. |
290
+ | `src/crypto/key-exchange.ts` | Key exchange (X25519) + sealed box. |
291
+ | `src/crypto/signature.ts` | Tanda tangan digital (Ed25519). |
292
+ | `src/crypto/group.ts` | Group key management (MLS-like tahap awal). |
293
+ | `src/utils/encoding.ts` | Helper base64. |
294
+ | `src/utils/bytes.ts` | Validasi panjang bytes. |
295
+ | `src/sodium.ts` | Wrapper libsodium. |
296
+ | `examples/basic-flow.ts` | Contoh alur end-to-end. |
297
+ | `examples/master-key-example.ts` | Contoh master key + KDF. |
298
+ | `examples/asymmetric-key-exchange.ts` | Contoh key exchange + sealed box. |
299
+ | `examples/asymmetric-signature.ts` | Contoh signature. |
300
+ | `examples/group-basic.ts` | Contoh group basic. |
301
+ | `SIMULATION.md` | Simulasi ringkas simetris & asimetris. |
302
+
303
+ ## Pengujian
129
304
 
130
- ## AAD Example
305
+ ```sh
306
+ npm test
307
+ ```
131
308
 
132
- ```ts
133
- import { fromString } from "@nexwage/crypto";
309
+ ## Build
134
310
 
135
- const aad = fromString("uid:user_123|app:v1|slot:password");
311
+ ```sh
312
+ npm run build
136
313
  ```
137
314
 
138
- ## KDF Parameters
315
+ ## Examples
139
316
 
140
- | Parameter | Purpose |
141
- | --- | --- |
142
- | opslimit | Jumlah operasi KDF (lebih besar = lebih lambat, lebih tahan brute-force). |
143
- | memlimit | Batas memori KDF (lebih besar = lebih tahan GPU/ASIC). |
144
- | salt | Salt acak 32-byte untuk mencegah rainbow table. |
317
+ Jalankan contoh:
145
318
 
146
- ## Envelope Format
319
+ ```sh
320
+ npm run example:kx
321
+ npm run example:sign
322
+ npm run example:basic
323
+ npm run example:group
324
+ ```
147
325
 
148
- ```json
149
- {
150
- "v": 1,
151
- "nonce": "base64",
152
- "ct": "base64"
153
- }
326
+ Contoh output (ringkas):
327
+
328
+ Key exchange + sealed box:
329
+ ```text
330
+ [kx] generate keypairs
331
+ [kx] client public key (b64): ...
332
+ [kx] server public key (b64): ...
333
+ [kx] derive session keys
334
+ [kx] client tx (b64): ...
335
+ [kx] client rx (b64): ...
336
+ [kx] server tx (b64): ...
337
+ [kx] server rx (b64): ...
338
+ [kx] shared tx/rx matches (base64 compare):
339
+ [kx] client tx == server rx: true
340
+ [kx] client rx == server tx: true
341
+ [sealed] encrypt to server public key
342
+ [sealed] ciphertext (b64): ...
343
+ [sealed] ciphertext bytes: ...
344
+ [sealed] decrypt with server keypair
345
+ [sealed] plaintext: hello sealed box
154
346
  ```
155
347
 
156
- ## Versioning Rules
348
+ Signature:
349
+ ```text
350
+ [sign] generate keypair
351
+ [sign] public key (b64): ...
352
+ [sign] private key bytes: 64
353
+ [sign] message bytes: ...
354
+ [sign] create signature
355
+ [sign] signature (b64): ...
356
+ [sign] signature bytes: 64
357
+ [sign] verify signature (valid)
358
+ [sign] result: true
359
+ [sign] verify signature (invalid)
360
+ [sign] result: false
361
+ ```
157
362
 
158
- 1. Saat encrypt, isi `v` dengan versi terbaru.
159
- 2. Saat decrypt, cek `v` lalu pilih logika yang sesuai.
160
- 3. Jika `v` tidak didukung, tolak dekripsi atau lakukan migrasi.
363
+ Basic flow:
364
+ ```text
365
+ [alur1] masterKey: ...
366
+ [alur1] wrappedMasterKey: ...
367
+ [alur1] wrappedMasterKeyByRecovery: ...
368
+ [alur1] wrappedRecoveryKey: ...
369
+ [alur1] wrappedFileKey: ...
370
+ [alur1] encryptedFile: ...
371
+ [alur2] masterKey2: ...
372
+ [alur2] fileKey2: ...
373
+ [alur2] fileBytes2: file rahasia
374
+ [alur3] masterKey3: ...
375
+ [alur3] wrappedMasterKeyNew: ...
376
+ [alur3] wrappedMasterKeyByRecoveryNew: ...
377
+ [done] semua alur OK
378
+ ```
161
379
 
162
- Contoh payload:
380
+ Contoh output error (AAD/password salah):
381
+ ```text
382
+ Error: Gagal membuka file: ciphertext/AAD/keys tidak valid
383
+ Error: Gagal membuka key: ciphertext/AAD/keys tidak valid
384
+ Error: Gagal membuka payload: ciphertext/AAD/keys tidak valid
385
+ ```
163
386
 
164
- ```json
165
- {
166
- "v": 1,
167
- "kdf": { "v": 1, "salt": "...", "opslimit": 3, "memlimit": 268435456 },
168
- "nonce": "....",
169
- "ct": "...."
170
- }
387
+ Group:
388
+ ```text
389
+ [group] create members
390
+ [group] create group state
391
+ [group] welcome epoch: 0
392
+ [group] members: alice, bob
393
+ [group] bob open welcome
394
+ [group] bob groupKey epoch 0 (b64): ...
395
+ [group] add carol with commit
396
+ [group] commit epoch: 1
397
+ [group] commit action: add
398
+ [group] commit members: alice, bob, carol
399
+ [group] bob apply commit
400
+ [group] bob groupKey epoch 1 (b64): ...
171
401
  ```
402
+
403
+ ## Glossary
404
+
405
+ | Istilah | Makna |
406
+ | --- | --- |
407
+ | Master Key (MK) | Kunci utama untuk membuka kunci lain (file key, recovery key). |
408
+ | Recovery Key | Kunci cadangan jika lupa password. |
409
+ | File Key | Kunci khusus per file. |
410
+ | Wrap/Unwrap | Membungkus dan membuka kunci menggunakan enkripsi. |
411
+ | AEAD | Enkripsi + integritas dalam satu skema. |
412
+ | AAD | Metadata yang diikat ke ciphertext tanpa dienkripsi. |
413
+ | KDF | Mengubah password menjadi key yang kuat. |
414
+ | Nonce | Angka acak sekali pakai untuk enkripsi. |
415
+ | Ciphertext (ct) | Hasil enkripsi. |
416
+ | Envelope | Struktur payload berisi `nonce`, `ct`, dan `v`. |
417
+ | Versioning (v) | Versi format payload. |
418
+
419
+ ## Lisensi
420
+
421
+ ISC
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@nexwage/crypto",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Minimal crypto building blocks using libsodium (XChaCha20-Poly1305 + Argon2).",
5
5
  "main": "./dist/index.js",
6
6
  "types": "./dist/index.d.ts",
@@ -13,7 +13,11 @@
13
13
  "scripts": {
14
14
  "test": "NODE_OPTIONS=--experimental-vm-modules jest --coverage",
15
15
  "start": "tsx examples/basic-flow.ts",
16
- "build": "tsc -p tsconfig.json"
16
+ "build": "tsc -p tsconfig.json",
17
+ "example:kx": "tsx examples/asymmetric-key-exchange.ts",
18
+ "example:sign": "tsx examples/asymmetric-signature.ts",
19
+ "example:basic": "tsx examples/basic-flow.ts",
20
+ "example:group": "tsx examples/group-basic.ts"
17
21
  },
18
22
  "keywords": [],
19
23
  "author": "",