@athsra/crypto

athsra core crypto primitives — Argon2id KDF + AES-256-GCM authenticated encryption. Worker + CLI 양쪽에서 동일 결과 보장 (WebCrypto + @noble/hashes).

E2EE secret manager athsra 의 cryptographic 기반.

설치

bun add @athsra/crypto

사용

import {
  deriveKey,
  encrypt,
  decrypt,
  randomSalt,
  randomNonce,
  toBase64,
  fromBase64,
  DEFAULT_KDF,
  type SecretEnvelope,
} from '@athsra/crypto';

// 1. Argon2id KDF (m=64MB, t=3, p=1, OWASP 2024+ 권고)
const password = 'master-password';
const salt = randomSalt();              // 16 bytes random
const key = deriveKey(password, salt);  // 32 bytes (AES-256 key)

// 2. AES-256-GCM encrypt
const blob = await encrypt(key, 'plaintext');
// blob = { ciphertext: Uint8Array, nonce: Uint8Array }

// 3. SecretEnvelope wire format (Worker R2 + CLI 호환)
const envelope: SecretEnvelope = {
  version: 1,
  alg: 'aes-256-gcm',
  kdf: 'argon2id',
  kdf_params: DEFAULT_KDF,
  salt: toBase64(salt),
  nonce: toBase64(blob.nonce),
  ciphertext: toBase64(blob.ciphertext),
  version_id: `v${Date.now()}`,
  updated_at: new Date().toISOString(),
};

// 4. Decrypt (다른 머신 / 시점)
const sameKey = deriveKey(password, fromBase64(envelope.salt));
const plain = await decrypt(sameKey, {
  ciphertext: fromBase64(envelope.ciphertext),
  nonce: fromBase64(envelope.nonce),
});
// plain === 'plaintext'

API

| Export | 설명 | |---|---| | deriveKey(password, salt) | Argon2id (m=64MB, t=3, p=1) → 32 bytes | | encrypt(key, plaintext) | AES-256-GCM → { ciphertext, nonce } (auth tag 포함) | | decrypt(key, blob) | auth tag 검증 후 plaintext. 실패 시 throw | | randomSalt() / randomNonce() | crypto.getRandomValues 16 / 12 bytes | | toBase64(uint8) / fromBase64(str) | wire encoding | | DEFAULT_KDF | { m: 65536, t: 3, p: 1 } | | SecretEnvelope (type) | wire format spec |

의존성

• @noble/hashes — Argon2id (paulmillr audited, 0 deps, Cure53 부분 audit)
• WebCrypto SubtleCrypto — AES-256-GCM (native, NIST SP 800-38D / FIPS 140-2 approved)

호환성

Worker (Cloudflare Workers / V8 isolate) + Bun + Node.js 18+ 모두 동일 결과. 같은 (password, salt) → 같은 key (deterministic).

License

MIT — see LICENSE-MIT.