✨ types(hooks): AES-256-GCM und HKDF im crypto-Paket (#65)
continuous-integration/drone/push Build is passing

- SealedValue { iv, ciphertext, tag } (base64)
- encrypt/decrypt mit key, aad und encoding
- deriveKey (HKDF-SHA256) mit info, length und encoding

Refs #65
This commit is contained in:
apairon committed 2026-11-05 10:20:25 +00:00
1 parent 8f17bb7ad4
commit b80af7ae58
1 file changed
+83
Vendored
+83
View File
@@ -1771,6 +1771,16 @@ declare global {
/** Byte encodings shared by the crypto/base64 hook helpers. */
export type ByteEncoding = "hex" | "base64" | "base64url" | "bytes"
/** AES-256-GCM output of `crypto.encrypt`; all fields are base64. */
export interface SealedValue {
/** Base64-encoded random 96-bit nonce (12 bytes). */
iv: string
/** Base64-encoded ciphertext without the authentication tag. */
ciphertext: string
/** Base64-encoded 128-bit authentication tag (16 bytes). */
tag: string
}
interface CryptoPackage {
/**
* get hex of sha256 hash
@@ -1873,6 +1883,79 @@ declare global {
a: string | Int8Array,
b: string | Int8Array
): boolean
/**
* Encrypt with AES-256-GCM. A fresh random 96-bit IV is generated for
* every call; the authentication tag covers ciphertext and `aad`.
*
* `key` must be 32 bytes (use `deriveKey` or `randomBytes(32)`).
* The returned object is JSON-safe: store `iv`, `ciphertext` and `tag`
* as-is (all standard base64).
*
* @param plaintext string (UTF-8) or bytes
* @param options.key 32-byte AES-256 key
* @param options.aad optional additional authenticated data
*/
encrypt(
plaintext: string | Int8Array,
options: { key: string | Int8Array; aad?: string | Int8Array }
): SealedValue
/**
* Decrypt an AES-256-GCM value and verify its authentication tag.
*
* A wrong key, tampered ciphertext/tag or a different `aad` all fail
* with the same error, so the caller cannot learn which part was wrong.
*
* @param sealed result of `encrypt` (base64 or raw bytes per field)
* @param options.key 32-byte AES-256 key
* @param options.aad must equal the value used by `encrypt`
* @param options.encoding `utf8` (default) | `hex` | `base64` | `base64url` | `bytes`
*/
decrypt(
sealed: SealedValue,
options: { key: string | Int8Array; aad?: string | Int8Array }
): string
decrypt(
sealed: SealedValue,
options: { key: string | Int8Array; aad?: string | Int8Array; encoding: "bytes" }
): Int8Array
decrypt(
sealed: SealedValue,
options: { key: string | Int8Array; aad?: string | Int8Array; encoding: "hex" | "base64" | "base64url" }
): string
decrypt(
sealed: SealedValue,
options: { key: string | Int8Array; aad?: string | Int8Array; encoding: ByteEncoding }
): string | Int8Array
/**
* Derive a key with HKDF-SHA256 (no salt).
*
* Deterministic for the same secret and `info`, so use a stable `info`
* per purpose (`"totp"`, `"recovery"`) instead of storing derived keys.
* The secret must already be high-entropy (project secret or 32 random
* bytes) — this is a KDF, not a password hash.
*
* @param secret high-entropy secret (string = UTF-8, or bytes)
* @param options.info HKDF context, default empty
* @param options.length output bytes, 16–64 (default 32). `encrypt`/
* `decrypt` require exactly 32 bytes; use the raw output (no
* `encoding`) as `key`.
* @param options.encoding `hex` | `base64` | `base64url` | `bytes` (default `bytes`)
*/
deriveKey(
secret: string | Int8Array,
options?: { info?: string | Int8Array; length?: number }
): Int8Array
deriveKey(
secret: string | Int8Array,
options: { info?: string | Int8Array; length?: number; encoding: "hex" | "base64" | "base64url" }
): string
deriveKey(
secret: string | Int8Array,
options: { info?: string | Int8Array; length?: number; encoding: ByteEncoding }
): string | Int8Array
}
/**