mf
Repositories Projects Packages

@mf/crypto (0.1.0)

Published 2026-07-20 06:36:28 +00:00 by lucky

Installation

@mf:registry=
npm install @mf/crypto@0.1.0
"@mf/crypto": "0.1.0"

About this package

@mf/crypto — крипто-ядро клиента (TS-порт)

TS-порт Go-референса крипто-ядра (профиль MODERN, ADR-0001). Вся криптография продукта живёт на клиенте (ADR-0002); Go-реализация в pkg/ — референс, фиксирующий wire-формат, этот пакет обязан воспроизводить его бит-в-бит.

Слои (зеркалят Go-пакеты)

TS-модуль Go-референс Что делает
src/envelope.ts pkg/envelope wire-формат конверта: `MF
src/provider.ts pkg/cryptoprovider интерфейс профилей + реестр
src/modern.ts pkg/cryptoprovider/modern XChaCha20-Poly1305, sealed box (X25519+HKDF), Ed25519, BLAKE2b-256, HKDF-SHA-256, Argon2id
src/keyring.ts pkg/keyring иерархия unlockers→UMK→identity→GK→DEK, доменные AAD mf/<domain>/v1|<context>
src/stream.ts pkg/stream чанковый AEAD-контейнер для больших файлов (push-API update()/final())
src/shamir.ts pkg/shamir Shamir t-of-n в GF(2^8) для social recovery (§8.2)
src/mnemonic.ts pkg/mnemonic recovery-фраза: BIP39-кодирование 256 бит ↔ 24 слова, rk = HKDF(entropy) (§8.1)

src/wordlist-en.ts генерируется из pkg/mnemonic/wordlist/english.txt (официальный BIP39, единый источник с Go): node scripts/gen-wordlist.cjs.

Зависимости и почему такие

  • libsodium-wrappers (WASM): AEAD, X25519, Ed25519, BLAKE2b.
  • @noble/hashes: HKDF-SHA-256 и Argon2id. Не libsodium, потому что crypto_pwhash поддерживает только parallelism=1, а дефолт продукта — threads: 4 (см. DEFAULT_PASSWORD_PARAMS); HKDF в libsodium отсутствует.
  • ESM-сборка libsodium-wrappers 0.7.x битая — нужен алиас на CJS-сборку (см. vitest.config.ts; бандлеру клиента понадобится такой же).

Использование

import { Keyring, Profile, ready } from "@mf/crypto";

await ready; // инициализация WASM — обязательна до любой операции
const kr = new Keyring(Profile.Modern);

Тесты и контракт совместимости

npm test          # или: make test-ts из корня

Три уровня гарантий совместимости с Go:

  1. test/vectors.test.ts — примитивы бит-в-бит по pkg/cryptoprovider/modern/testdata/vectors.json (единый источник, читается напрямую).
  2. test/interop.test.ts Go→TS — расшифровка полной иерархии ключей из test/fixtures/go-interop.json (генерируется make interop).
  3. test/interop.test.ts TS→Go — TS шифрует иерархию, go run ./tools/tsinterop -check расшифровывает (тест пропускается, если Go недоступен).

Регенерация фикстуры после осознанного изменения wire-формата: make interop.

Dependencies

Dependencies

ID Version
@noble/hashes ^1.5.0
libsodium-wrappers ^0.7.15

Development Dependencies

ID Version
@types/libsodium-wrappers ^0.7.14
@types/node ^22.0.0
typescript ^5.6.0
vitest ^2.1.0
Details
npm
2026-07-20 06:36:28 +00:00
62
latest
37 KiB
Assets (1)
crypto-0.1.0.tgz 37 KiB
Versions (1) View all
0.1.0 2026-07-20