@nexwage/crypto 0.1.0

package/README.md

@@ -0,0 +1,171 @@
+# @nexwage/crypto
+
+Minimal, opinionated crypto building blocks for password-based master keys, recovery keys, and file encryption. Built on libsodium with XChaCha20-Poly1305 and Argon2.
+
+## Install
+
+```sh
+npm i @nexwage/crypto
+```
+
+## Quick Start
+
+```ts
+import {
+  generateMasterKeyWithPassword,
+  unwrapMasterKeyWithPassword,
+  generateRecoveryKey,
+  wrapMasterKeyWithRecoveryKey,
+  generateFileKey,
+  wrapFileKeyWithMasterKey,
+  encryptFileData,
+  decryptFileData,
+} from "@nexwage/crypto";
+
+const password = "strong-password";
+const aad = new TextEncoder().encode("uid:user_123|app:v1|slot:password");
+
+const { masterKey, wrapped } = await generateMasterKeyWithPassword(
+  password,
+  undefined,
+  aad
+);
+
+const recoveryKey = await generateRecoveryKey();
+const wrappedByRecovery = await wrapMasterKeyWithRecoveryKey(
+  masterKey,
+  recoveryKey,
+  aad
+);
+
+const fileKey = await generateFileKey();
+const wrappedFileKey = await wrapFileKeyWithMasterKey(fileKey, masterKey, aad);
+
+const fileBytes = new TextEncoder().encode("file rahasia");
+const encryptedFile = await encryptFileData(fileKey, fileBytes, aad);
+
+const masterKey2 = await unwrapMasterKeyWithPassword(password, wrapped, aad);
+const fileKey2 = await unwrapFileKeyWithMasterKey(
+  masterKey2,
+  wrappedFileKey,
+  aad
+);
+const decryptedFile = await decryptFileData(fileKey2, encryptedFile, aad);
+```
+
+## Project Structure
+
+| Path | Purpose |
+| --- | --- |
+| `src/index.ts` | Public exports. |
+| `src/types.ts` | Payload types + versioning. |
+| `src/crypto/password-kdf.ts` | Password KDF + key wrapping. |
+| `src/crypto/master-key.ts` | Master key lifecycle. |
+| `src/crypto/recovery-key.ts` | Recovery key wrapping. |
+| `src/crypto/file-encryption.ts` | File key + file encryption. |
+| `src/utils/encoding.ts` | Base64 helpers. |
+| `src/utils/bytes.ts` | Byte length assertions. |
+| `src/sodium.ts` | libsodium wrapper exports. |
+| `examples/basic-flow.ts` | End-to-end flow. |
+| `examples/master-key-example.ts` | Master key example. |
+
+## AAD and Versioning
+
+- AAD (Additional Authenticated Data) binds ciphertext to context (userId, slot, fileId).
+- Versioning (`v`) keeps payloads forward-compatible when formats or algorithms change.
+
+## Manual Test
+
+See `examples/basic-flow.ts` for the full 3-flow example.
+
+## Glossary
+
+Panduan ringkas istilah dan konsep yang dipakai di modul ini.
+
+| Term | Meaning |
+| --- | --- |
+| Master Key (MK) | Kunci utama untuk membuka kunci lain (file key, recovery key). |
+| Recovery Key | Kunci cadangan jika lupa password. |
+| File Key | Kunci khusus per file. |
+| Wrap/Unwrap | Membungkus dan membuka kunci menggunakan enkripsi. |
+| AEAD | Enkripsi + integritas dalam satu skema. |
+| AAD | Metadata yang diikat ke ciphertext tanpa dienkripsi. |
+| KDF | Mengubah password menjadi key yang kuat. |
+| Nonce | Angka acak sekali pakai untuk enkripsi. |
+| Ciphertext (ct) | Hasil enkripsi. |
+| Envelope | Struktur payload berisi `nonce`, `ct`, dan `v`. |
+| Versioning (v) | Versi format payload. |
+
+## libsodium Functions Used
+
+| Function/Property | Description |
+| --- | --- |
+| `sodium.ready` | Menunggu libsodium siap dipakai. |
+| `sodium.randombytes_buf` | Generate bytes acak (kunci, nonce). |
+| `sodium.crypto_pwhash` | Derivasi key dari password (Argon2). |
+| `sodium.crypto_pwhash_SALTBYTES` | Panjang salt untuk KDF. |
+| `sodium.crypto_pwhash_OPSLIMIT_MODERATE` | Default opslimit KDF. |
+| `sodium.crypto_pwhash_MEMLIMIT_MODERATE` | Default memlimit KDF. |
+| `sodium.crypto_aead_xchacha20poly1305_ietf_encrypt` | Enkripsi AEAD XChaCha20-Poly1305. |
+| `sodium.crypto_aead_xchacha20poly1305_ietf_decrypt` | Dekripsi AEAD XChaCha20-Poly1305. |
+| `sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES` | Panjang nonce AEAD XChaCha20-Poly1305. |
+| `sodium.to_base64` | Encode bytes ke base64. |
+| `sodium.from_base64` | Decode base64 ke bytes. |
+| `sodium.base64_variants.ORIGINAL` | Variant base64 yang dipakai. |
+| `sodium.from_string` | Encode string ke bytes (UTF-8). |
+| `sodium.to_string` | Decode bytes ke string (UTF-8). |
+| `sodium.memcmp` | Bandingkan bytes secara aman (constant-time). |
+
+## Planned libsodium Functions
+
+| Function/Property | Planned use |
+| --- | --- |
+| `sodium.crypto_generichash` | Hash konteks/AAD jika perlu bentuk stabil dan ringkas. |
+| `sodium.crypto_kdf_derive_from_key` | Derivasi sub-key per domain dari satu kunci root. |
+| `sodium.crypto_aead_aes256gcm_encrypt` | Alternatif AEAD dengan akselerasi hardware. |
+| `sodium.crypto_aead_aes256gcm_decrypt` | Pasangan decrypt AES-GCM. |
+| `sodium.crypto_secretbox_easy` | Enkripsi simetris sederhana untuk payload non-AEAD. |
+| `sodium.crypto_secretbox_open_easy` | Dekripsi secretbox. |
+
+## AAD Example
+
+```ts
+import { fromString } from "@nexwage/crypto";
+
+const aad = fromString("uid:user_123|app:v1|slot:password");
+```
+
+## KDF Parameters
+
+| Parameter | Purpose |
+| --- | --- |
+| opslimit | Jumlah operasi KDF (lebih besar = lebih lambat, lebih tahan brute-force). |
+| memlimit | Batas memori KDF (lebih besar = lebih tahan GPU/ASIC). |
+| salt | Salt acak 32-byte untuk mencegah rainbow table. |
+
+## Envelope Format
+
+```json
+{
+  "v": 1,
+  "nonce": "base64",
+  "ct": "base64"
+}
+```
+
+## Versioning Rules
+
+1. Saat encrypt, isi `v` dengan versi terbaru.
+2. Saat decrypt, cek `v` lalu pilih logika yang sesuai.
+3. Jika `v` tidak didukung, tolak dekripsi atau lakukan migrasi.
+
+Contoh payload:
+
+```json
+{
+  "v": 1,
+  "kdf": { "v": 1, "salt": "...", "opslimit": 3, "memlimit": 268435456 },
+  "nonce": "....",
+  "ct": "...."
+}
+```

package/dist/crypto/file-encryption.d.ts

@@ -0,0 +1,59 @@
+import type { AeadEnvelopeV1 } from "../types.js";
+/**
+ * Generate file key 32-byte secara acak.
+ *
+ * @returns Bytes file key.
+ *
+ * @example
+ * const fileKey = await generateFileKey();
+ */
+export declare function generateFileKey(): Promise<Uint8Array>;
+/**
+ * Bungkus file key menggunakan master key.
+ *
+ * @param fileKey - File key 32-byte.
+ * @param masterKey - Master key 32-byte.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Envelope hasil wrap.
+ *
+ * @example
+ * const wrapped = await wrapFileKeyWithMasterKey(fileKey, masterKey);
+ */
+export declare function wrapFileKeyWithMasterKey(fileKey: Uint8Array, masterKey: Uint8Array, aad?: Uint8Array): Promise<AeadEnvelopeV1>;
+/**
+ * Buka file key menggunakan master key.
+ *
+ * @param masterKey - Master key 32-byte.
+ * @param wrapped - Envelope hasil wrap file key.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes file key.
+ *
+ * @example
+ * const fileKey = await unwrapFileKeyWithMasterKey(masterKey, wrapped);
+ */
+export declare function unwrapFileKeyWithMasterKey(masterKey: Uint8Array, wrapped: AeadEnvelopeV1, aad?: Uint8Array): Promise<Uint8Array>;
+/**
+ * Enkripsi isi file menggunakan file key.
+ *
+ * @param fileKey - File key 32-byte.
+ * @param plaintext - Isi file (bytes).
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Envelope hasil enkripsi file.
+ *
+ * @example
+ * const encrypted = await encryptFileData(fileKey, fileBytes);
+ */
+export declare function encryptFileData(fileKey: Uint8Array, plaintext: Uint8Array, aad?: Uint8Array): Promise<AeadEnvelopeV1>;
+/**
+ * Dekripsi isi file menggunakan file key.
+ *
+ * @param fileKey - File key 32-byte.
+ * @param wrapped - Envelope hasil enkripsi file.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes isi file.
+ *
+ * @example
+ * const fileBytes = await decryptFileData(fileKey, encrypted);
+ */
+export declare function decryptFileData(fileKey: Uint8Array, wrapped: AeadEnvelopeV1, aad?: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=file-encryption.d.ts.map

package/dist/crypto/file-encryption.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-encryption.d.ts","sourceRoot":"","sources":["../../src/crypto/file-encryption.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAwElD;;;;;;;GAOG;AACH,wBAAsB,eAAe,IAAI,OAAO,CAAC,UAAU,CAAC,CAG3D;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,wBAAwB,CAC5C,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,cAAc,CAAC,CAIzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,0BAA0B,CAC9C,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,cAAc,EACvB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAKrB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,cAAc,CAAC,CAGzB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,UAAU,EACnB,OAAO,EAAE,cAAc,EACvB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAGrB"}

package/dist/crypto/file-encryption.js

@@ -0,0 +1,118 @@
+import sodium from "libsodium-wrappers-sumo";
+import { assertByteLength } from "../utils/bytes.js";
+import { decodeBase64, encodeBase64 } from "../utils/encoding.js";
+// Domain: file keys + file data encryption/decryption.
+/**
+ * Enkripsi payload dengan key menggunakan AEAD.
+ *
+ * @param key - Key 32-byte.
+ * @param plaintext - Data plaintext.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Envelope hasil enkripsi.
+ */
+async function encryptWithKey(key, plaintext, aad) {
+    await sodium.ready;
+    const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    const ct = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, aad ?? null, null, nonce, key);
+    return {
+        v: 1,
+        nonce: encodeBase64(nonce),
+        ct: encodeBase64(ct),
+    };
+}
+/**
+ * Dekripsi payload dengan key menggunakan AEAD.
+ *
+ * @param key - Key 32-byte.
+ * @param wrapped - Envelope hasil enkripsi.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes hasil dekripsi.
+ */
+async function decryptWithKey(key, wrapped, aad) {
+    await sodium.ready;
+    const nonce = decodeBase64(wrapped.nonce);
+    assertByteLength("nonce", nonce, sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    const ct = decodeBase64(wrapped.ct);
+    try {
+        return sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ct, aad ?? null, nonce, key);
+    }
+    catch {
+        throw new Error("Gagal membuka file: ciphertext/AAD/keys tidak valid");
+    }
+}
+/**
+ * Generate file key 32-byte secara acak.
+ *
+ * @returns Bytes file key.
+ *
+ * @example
+ * const fileKey = await generateFileKey();
+ */
+export async function generateFileKey() {
+    await sodium.ready;
+    return sodium.randombytes_buf(32);
+}
+/**
+ * Bungkus file key menggunakan master key.
+ *
+ * @param fileKey - File key 32-byte.
+ * @param masterKey - Master key 32-byte.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Envelope hasil wrap.
+ *
+ * @example
+ * const wrapped = await wrapFileKeyWithMasterKey(fileKey, masterKey);
+ */
+export async function wrapFileKeyWithMasterKey(fileKey, masterKey, aad) {
+    assertByteLength("fileKey", fileKey, 32);
+    assertByteLength("masterKey", masterKey, 32);
+    return encryptWithKey(masterKey, fileKey, aad);
+}
+/**
+ * Buka file key menggunakan master key.
+ *
+ * @param masterKey - Master key 32-byte.
+ * @param wrapped - Envelope hasil wrap file key.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes file key.
+ *
+ * @example
+ * const fileKey = await unwrapFileKeyWithMasterKey(masterKey, wrapped);
+ */
+export async function unwrapFileKeyWithMasterKey(masterKey, wrapped, aad) {
+    assertByteLength("masterKey", masterKey, 32);
+    const fileKey = await decryptWithKey(masterKey, wrapped, aad);
+    assertByteLength("fileKey", fileKey, 32);
+    return fileKey;
+}
+/**
+ * Enkripsi isi file menggunakan file key.
+ *
+ * @param fileKey - File key 32-byte.
+ * @param plaintext - Isi file (bytes).
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Envelope hasil enkripsi file.
+ *
+ * @example
+ * const encrypted = await encryptFileData(fileKey, fileBytes);
+ */
+export async function encryptFileData(fileKey, plaintext, aad) {
+    assertByteLength("fileKey", fileKey, 32);
+    return encryptWithKey(fileKey, plaintext, aad);
+}
+/**
+ * Dekripsi isi file menggunakan file key.
+ *
+ * @param fileKey - File key 32-byte.
+ * @param wrapped - Envelope hasil enkripsi file.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes isi file.
+ *
+ * @example
+ * const fileBytes = await decryptFileData(fileKey, encrypted);
+ */
+export async function decryptFileData(fileKey, wrapped, aad) {
+    assertByteLength("fileKey", fileKey, 32);
+    return decryptWithKey(fileKey, wrapped, aad);
+}
+//# sourceMappingURL=file-encryption.js.map

package/dist/crypto/file-encryption.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-encryption.js","sourceRoot":"","sources":["../../src/crypto/file-encryption.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,yBAAyB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAGlE,uDAAuD;AACvD;;;;;;;GAOG;AACH,KAAK,UAAU,cAAc,CAC3B,GAAe,EACf,SAAqB,EACrB,GAAgB;IAEhB,MAAM,MAAM,CAAC,KAAK,CAAC;IAEnB,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAClC,MAAM,CAAC,4CAA4C,CACpD,CAAC;IACF,MAAM,EAAE,GAAG,MAAM,CAAC,0CAA0C,CAC1D,SAAS,EACT,GAAG,IAAI,IAAI,EACX,IAAI,EACJ,KAAK,EACL,GAAG,CACJ,CAAC;IAEF,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC;QAC1B,EAAE,EAAE,YAAY,CAAC,EAAE,CAAC;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,cAAc,CAC3B,GAAe,EACf,OAAuB,EACvB,GAAgB;IAEhB,MAAM,MAAM,CAAC,KAAK,CAAC;IAEnB,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,gBAAgB,CACd,OAAO,EACP,KAAK,EACL,MAAM,CAAC,4CAA4C,CACpD,CAAC;IACF,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,0CAA0C,CACtD,IAAI,EACJ,EAAE,EACF,GAAG,IAAI,IAAI,EACX,KAAK,EACL,GAAG,CACJ,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe;IACnC,MAAM,MAAM,CAAC,KAAK,CAAC;IACnB,OAAO,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,OAAmB,EACnB,SAAqB,EACrB,GAAgB;IAEhB,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACzC,gBAAgB,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAC7C,OAAO,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,0BAA0B,CAC9C,SAAqB,EACrB,OAAuB,EACvB,GAAgB;IAEhB,gBAAgB,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAC7C,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,SAAS,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;IAC9D,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAmB,EACnB,SAAqB,EACrB,GAAgB;IAEhB,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,cAAc,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAmB,EACnB,OAAuB,EACvB,GAAgB;IAEhB,gBAAgB,CAAC,SAAS,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IACzC,OAAO,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AAC/C,CAAC"}

package/dist/crypto/master-key.d.ts

@@ -0,0 +1,68 @@
+import type { PasswordWrappedKeyV1 } from "../types.js";
+import type { PasswordKdfOptions } from "./password-kdf.js";
+/**
+ * Generate master key 32-byte secara acak.
+ *
+ * @returns Bytes master key.
+ *
+ * @example
+ * const masterKey = await generateMasterKey();
+ */
+export declare function generateMasterKey(): Promise<Uint8Array>;
+/**
+ * Generate master key baru lalu bungkus (wrap) dengan password.
+ *
+ * @param password - String password pengguna yang dipakai untuk KDF.
+ * @param opts - Opsi KDF.
+ * @param opts.opslimit - Jumlah operasi KDF (Argon2). Semakin besar -> semakin lama proses derivasi,
+ *   lebih tahan brute-force.
+ * @param opts.memlimit - Batas memori KDF. Semakin besar -> lebih sulit diserang GPU/ASIC,
+ *   tapi lebih berat di device.
+ * @param opts.salt - Salt KDF (32 bytes). Jika tidak diberikan, dibuat acak otomatis.
+ * @param aad - Data tambahan yang diikat ke ciphertext (integritas) tapi tidak dienkripsi.
+ *   Contoh: userId, appVersion, slot.
+ * @returns Object berisi `masterKey` dan `wrapped`.
+ *
+ * Catatan: `nonce` untuk encrypt dibuat otomatis di wrapKeyWithPassword, tidak diisi manual.
+ *
+ * @example
+ * const aad = sodium.from_string("uid:user_123|app:v1|slot:password");
+ * const { masterKey, wrapped } = await generateMasterKeyWithPassword(
+ *   "secret-password",
+ *   {
+ *     opslimit: sodium.crypto_pwhash_OPSLIMIT_MODERATE,
+ *     memlimit: sodium.crypto_pwhash_MEMLIMIT_MODERATE,
+ *   },
+ *   aad
+ * );
+ */
+export declare function generateMasterKeyWithPassword(password: string, opts?: PasswordKdfOptions, aad?: Uint8Array): Promise<{
+    masterKey: Uint8Array;
+    wrapped: PasswordWrappedKeyV1;
+}>;
+/**
+ * Bungkus master key menggunakan key turunan dari password.
+ *
+ * @param masterKey - Master key 32-byte.
+ * @param password - Password pengguna.
+ * @param opts - Opsi KDF.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Payload master key yang dibungkus.
+ *
+ * @example
+ * const wrapped = await wrapMasterKeyWithPassword(masterKey, "secret");
+ */
+export declare function wrapMasterKeyWithPassword(masterKey: Uint8Array, password: string, opts?: PasswordKdfOptions, aad?: Uint8Array): Promise<PasswordWrappedKeyV1>;
+/**
+ * Buka master key menggunakan key turunan dari password.
+ *
+ * @param password - Password pengguna.
+ * @param wrapped - Payload master key yang dibungkus.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes master key.
+ *
+ * @example
+ * const masterKey = await unwrapMasterKeyWithPassword("secret", wrapped);
+ */
+export declare function unwrapMasterKeyWithPassword(password: string, wrapped: PasswordWrappedKeyV1, aad?: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=master-key.d.ts.map

package/dist/crypto/master-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"master-key.d.ts","sourceRoot":"","sources":["../../src/crypto/master-key.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAI5D;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,UAAU,CAAC,CAG7D;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAsB,6BAA6B,CACjD,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,kBAAkB,EACzB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC;IAAE,SAAS,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,oBAAoB,CAAA;CAAE,CAAC,CASnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,yBAAyB,CAC7C,SAAS,EAAE,UAAU,EACrB,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,kBAAkB,EACzB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,oBAAoB,CAAC,CAG/B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAErB"}

package/dist/crypto/master-key.js

@@ -0,0 +1,79 @@
+import sodium from "libsodium-wrappers-sumo";
+import { assertByteLength } from "../utils/bytes.js";
+import { unwrapKeyWithPassword, wrapKeyWithPassword } from "./password-kdf.js";
+// Domain: master key lifecycle (generate/derive/wrap/unwrap).
+/**
+ * Generate master key 32-byte secara acak.
+ *
+ * @returns Bytes master key.
+ *
+ * @example
+ * const masterKey = await generateMasterKey();
+ */
+export async function generateMasterKey() {
+    await sodium.ready;
+    return sodium.randombytes_buf(32);
+}
+/**
+ * Generate master key baru lalu bungkus (wrap) dengan password.
+ *
+ * @param password - String password pengguna yang dipakai untuk KDF.
+ * @param opts - Opsi KDF.
+ * @param opts.opslimit - Jumlah operasi KDF (Argon2). Semakin besar -> semakin lama proses derivasi,
+ *   lebih tahan brute-force.
+ * @param opts.memlimit - Batas memori KDF. Semakin besar -> lebih sulit diserang GPU/ASIC,
+ *   tapi lebih berat di device.
+ * @param opts.salt - Salt KDF (32 bytes). Jika tidak diberikan, dibuat acak otomatis.
+ * @param aad - Data tambahan yang diikat ke ciphertext (integritas) tapi tidak dienkripsi.
+ *   Contoh: userId, appVersion, slot.
+ * @returns Object berisi `masterKey` dan `wrapped`.
+ *
+ * Catatan: `nonce` untuk encrypt dibuat otomatis di wrapKeyWithPassword, tidak diisi manual.
+ *
+ * @example
+ * const aad = sodium.from_string("uid:user_123|app:v1|slot:password");
+ * const { masterKey, wrapped } = await generateMasterKeyWithPassword(
+ *   "secret-password",
+ *   {
+ *     opslimit: sodium.crypto_pwhash_OPSLIMIT_MODERATE,
+ *     memlimit: sodium.crypto_pwhash_MEMLIMIT_MODERATE,
+ *   },
+ *   aad
+ * );
+ */
+export async function generateMasterKeyWithPassword(password, opts, aad) {
+    const masterKey = await generateMasterKey();
+    const wrapped = await wrapMasterKeyWithPassword(masterKey, password, opts, aad);
+    return { masterKey, wrapped };
+}
+/**
+ * Bungkus master key menggunakan key turunan dari password.
+ *
+ * @param masterKey - Master key 32-byte.
+ * @param password - Password pengguna.
+ * @param opts - Opsi KDF.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Payload master key yang dibungkus.
+ *
+ * @example
+ * const wrapped = await wrapMasterKeyWithPassword(masterKey, "secret");
+ */
+export async function wrapMasterKeyWithPassword(masterKey, password, opts, aad) {
+    assertByteLength("masterKey", masterKey, 32);
+    return wrapKeyWithPassword(masterKey, password, opts, aad);
+}
+/**
+ * Buka master key menggunakan key turunan dari password.
+ *
+ * @param password - Password pengguna.
+ * @param wrapped - Payload master key yang dibungkus.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes master key.
+ *
+ * @example
+ * const masterKey = await unwrapMasterKeyWithPassword("secret", wrapped);
+ */
+export async function unwrapMasterKeyWithPassword(password, wrapped, aad) {
+    return unwrapKeyWithPassword(password, wrapped, aad);
+}
+//# sourceMappingURL=master-key.js.map

package/dist/crypto/master-key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"master-key.js","sourceRoot":"","sources":["../../src/crypto/master-key.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,yBAAyB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAGrD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE/E,8DAA8D;AAC9D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB;IACrC,MAAM,MAAM,CAAC,KAAK,CAAC;IACnB,OAAO,MAAM,CAAC,eAAe,CAAC,EAAE,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,CAAC,KAAK,UAAU,6BAA6B,CACjD,QAAgB,EAChB,IAAyB,EACzB,GAAgB;IAEhB,MAAM,SAAS,GAAG,MAAM,iBAAiB,EAAE,CAAC;IAC5C,MAAM,OAAO,GAAG,MAAM,yBAAyB,CAC7C,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,GAAG,CACJ,CAAC;IACF,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,SAAqB,EACrB,QAAgB,EAChB,IAAyB,EACzB,GAAgB;IAEhB,gBAAgB,CAAC,WAAW,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;IAC7C,OAAO,mBAAmB,CAAC,SAAS,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC;AAC7D,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,QAAgB,EAChB,OAA6B,EAC7B,GAAgB;IAEhB,OAAO,qBAAqB,CAAC,QAAQ,EAAE,OAAO,EAAE,GAAG,CAAC,CAAC;AACvD,CAAC"}

package/dist/crypto/password-kdf.d.ts

@@ -0,0 +1,49 @@
+import type { PasswordKdfParamsV1, PasswordWrappedKeyV1 } from "../types.js";
+export interface PasswordKdfOptions {
+    opslimit?: number;
+    memlimit?: number;
+    salt?: Uint8Array;
+}
+/**
+ * Derivasi key 32-byte dari password menggunakan Argon2.
+ *
+ * @param password - Password pengguna.
+ * @param opts - Opsi KDF.
+ * @param opts.opslimit - Batas operasi KDF.
+ * @param opts.memlimit - Batas memori KDF.
+ * @param opts.salt - Salt KDF (32 bytes). Random jika tidak diisi.
+ * @returns Key hasil derivasi dan parameter KDF untuk disimpan.
+ *
+ * @example
+ * const { key, kdf } = await deriveKeyFromPassword("secret");
+ */
+export declare function deriveKeyFromPassword(password: string, opts?: PasswordKdfOptions): Promise<{
+    key: Uint8Array;
+    kdf: PasswordKdfParamsV1;
+}>;
+/**
+ * Bungkus (wrap) key menggunakan key turunan dari password.
+ *
+ * @param key - Key 32-byte yang akan dibungkus.
+ * @param password - Password pengguna.
+ * @param opts - Opsi KDF.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Payload key yang sudah dibungkus.
+ *
+ * @example
+ * const wrapped = await wrapKeyWithPassword(key, "secret");
+ */
+export declare function wrapKeyWithPassword(key: Uint8Array, password: string, opts?: PasswordKdfOptions, aad?: Uint8Array): Promise<PasswordWrappedKeyV1>;
+/**
+ * Buka (unwrap) key menggunakan key turunan dari password.
+ *
+ * @param password - Password pengguna.
+ * @param wrapped - Payload key yang dibungkus.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes key hasil unwrap.
+ *
+ * @example
+ * const key = await unwrapKeyWithPassword("secret", wrapped);
+ */
+export declare function unwrapKeyWithPassword(password: string, wrapped: PasswordWrappedKeyV1, aad?: Uint8Array): Promise<Uint8Array>;
+//# sourceMappingURL=password-kdf.d.ts.map

package/dist/crypto/password-kdf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-kdf.d.ts","sourceRoot":"","sources":["../../src/crypto/password-kdf.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAG7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,UAAU,CAAC;CACnB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,kBAAkB,GACxB,OAAO,CAAC;IAAE,GAAG,EAAE,UAAU,CAAC;IAAC,GAAG,EAAE,mBAAmB,CAAA;CAAE,CAAC,CA4BxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,UAAU,EACf,QAAQ,EAAE,MAAM,EAChB,IAAI,CAAC,EAAE,kBAAkB,EACzB,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,oBAAoB,CAAC,CAyB/B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,oBAAoB,EAC7B,GAAG,CAAC,EAAE,UAAU,GACf,OAAO,CAAC,UAAU,CAAC,CAkCrB"}

package/dist/crypto/password-kdf.js

@@ -0,0 +1,93 @@
+import sodium from "libsodium-wrappers-sumo";
+import { assertByteLength } from "../utils/bytes.js";
+import { decodeBase64, encodeBase64 } from "../utils/encoding.js";
+/**
+ * Derivasi key 32-byte dari password menggunakan Argon2.
+ *
+ * @param password - Password pengguna.
+ * @param opts - Opsi KDF.
+ * @param opts.opslimit - Batas operasi KDF.
+ * @param opts.memlimit - Batas memori KDF.
+ * @param opts.salt - Salt KDF (32 bytes). Random jika tidak diisi.
+ * @returns Key hasil derivasi dan parameter KDF untuk disimpan.
+ *
+ * @example
+ * const { key, kdf } = await deriveKeyFromPassword("secret");
+ */
+export async function deriveKeyFromPassword(password, opts) {
+    await sodium.ready;
+    const opslimit = opts?.opslimit ?? sodium.crypto_pwhash_OPSLIMIT_MODERATE;
+    const memlimit = opts?.memlimit ?? sodium.crypto_pwhash_MEMLIMIT_MODERATE;
+    const salt = opts?.salt ?? sodium.randombytes_buf(sodium.crypto_pwhash_SALTBYTES);
+    assertByteLength("salt", salt, sodium.crypto_pwhash_SALTBYTES);
+    const key = sodium.crypto_pwhash(32, password, salt, opslimit, memlimit, sodium.crypto_pwhash_ALG_DEFAULT);
+    return {
+        key,
+        kdf: {
+            v: 1,
+            salt: encodeBase64(salt),
+            opslimit,
+            memlimit,
+        },
+    };
+}
+/**
+ * Bungkus (wrap) key menggunakan key turunan dari password.
+ *
+ * @param key - Key 32-byte yang akan dibungkus.
+ * @param password - Password pengguna.
+ * @param opts - Opsi KDF.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Payload key yang sudah dibungkus.
+ *
+ * @example
+ * const wrapped = await wrapKeyWithPassword(key, "secret");
+ */
+export async function wrapKeyWithPassword(key, password, opts, aad) {
+    await sodium.ready;
+    assertByteLength("key", key, 32);
+    const { key: wrapKey, kdf } = await deriveKeyFromPassword(password, opts);
+    const nonce = sodium.randombytes_buf(sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    const ct = sodium.crypto_aead_xchacha20poly1305_ietf_encrypt(key, aad ?? null, null, nonce, wrapKey);
+    sodium.memzero(wrapKey);
+    return {
+        v: 1,
+        kdf,
+        nonce: encodeBase64(nonce),
+        ct: encodeBase64(ct),
+    };
+}
+/**
+ * Buka (unwrap) key menggunakan key turunan dari password.
+ *
+ * @param password - Password pengguna.
+ * @param wrapped - Payload key yang dibungkus.
+ * @param aad - Additional authenticated data (opsional).
+ * @returns Bytes key hasil unwrap.
+ *
+ * @example
+ * const key = await unwrapKeyWithPassword("secret", wrapped);
+ */
+export async function unwrapKeyWithPassword(password, wrapped, aad) {
+    await sodium.ready;
+    const salt = decodeBase64(wrapped.kdf.salt);
+    assertByteLength("salt", salt, sodium.crypto_pwhash_SALTBYTES);
+    const { key: wrapKey } = await deriveKeyFromPassword(password, {
+        salt,
+        opslimit: wrapped.kdf.opslimit,
+        memlimit: wrapped.kdf.memlimit,
+    });
+    const nonce = decodeBase64(wrapped.nonce);
+    assertByteLength("nonce", nonce, sodium.crypto_aead_xchacha20poly1305_ietf_NPUBBYTES);
+    const ct = decodeBase64(wrapped.ct);
+    try {
+        return sodium.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ct, aad ?? null, nonce, wrapKey);
+    }
+    catch {
+        throw new Error("Gagal membuka key: ciphertext/AAD/keys tidak valid");
+    }
+    finally {
+        sodium.memzero(wrapKey);
+    }
+}
+//# sourceMappingURL=password-kdf.js.map

package/dist/crypto/password-kdf.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"password-kdf.js","sourceRoot":"","sources":["../../src/crypto/password-kdf.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,yBAAyB,CAAC;AAC7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAUlE;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgB,EAChB,IAAyB;IAEzB,MAAM,MAAM,CAAC,KAAK,CAAC;IAEnB,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,MAAM,CAAC,+BAA+B,CAAC;IAC1E,MAAM,QAAQ,GAAG,IAAI,EAAE,QAAQ,IAAI,MAAM,CAAC,+BAA+B,CAAC;IAC1E,MAAM,IAAI,GACR,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC,eAAe,CAAC,MAAM,CAAC,uBAAuB,CAAC,CAAC;IAEvE,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,uBAAuB,CAAC,CAAC;IAE/D,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAC9B,EAAE,EACF,QAAQ,EACR,IAAI,EACJ,QAAQ,EACR,QAAQ,EACR,MAAM,CAAC,yBAAyB,CACjC,CAAC;IAEF,OAAO;QACL,GAAG;QACH,GAAG,EAAE;YACH,CAAC,EAAE,CAAC;YACJ,IAAI,EAAE,YAAY,CAAC,IAAI,CAAC;YACxB,QAAQ;YACR,QAAQ;SACT;KACF,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,GAAe,EACf,QAAgB,EAChB,IAAyB,EACzB,GAAgB;IAEhB,MAAM,MAAM,CAAC,KAAK,CAAC;IACnB,gBAAgB,CAAC,KAAK,EAAE,GAAG,EAAE,EAAE,CAAC,CAAC;IAEjC,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,GAAG,MAAM,qBAAqB,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,MAAM,CAAC,eAAe,CAClC,MAAM,CAAC,4CAA4C,CACpD,CAAC;IAEF,MAAM,EAAE,GAAG,MAAM,CAAC,0CAA0C,CAC1D,GAAG,EACH,GAAG,IAAI,IAAI,EACX,IAAI,EACJ,KAAK,EACL,OAAO,CACR,CAAC;IAEF,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAExB,OAAO;QACL,CAAC,EAAE,CAAC;QACJ,GAAG;QACH,KAAK,EAAE,YAAY,CAAC,KAAK,CAAC;QAC1B,EAAE,EAAE,YAAY,CAAC,EAAE,CAAC;KACrB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,qBAAqB,CACzC,QAAgB,EAChB,OAA6B,EAC7B,GAAgB;IAEhB,MAAM,MAAM,CAAC,KAAK,CAAC;IAEnB,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC5C,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,uBAAuB,CAAC,CAAC;IAE/D,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,MAAM,qBAAqB,CAAC,QAAQ,EAAE;QAC7D,IAAI;QACJ,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ;QAC9B,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,QAAQ;KAC/B,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IAC1C,gBAAgB,CACd,OAAO,EACP,KAAK,EACL,MAAM,CAAC,4CAA4C,CACpD,CAAC;IAEF,MAAM,EAAE,GAAG,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAEpC,IAAI,CAAC;QACH,OAAO,MAAM,CAAC,0CAA0C,CACtD,IAAI,EACJ,EAAE,EACF,GAAG,IAAI,IAAI,EACX,KAAK,EACL,OAAO,CACR,CAAC;IACJ,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC,CAAC;IACxE,CAAC;YAAS,CAAC;QACT,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;IAC1B,CAAC;AACH,CAAC"}