From b80af7ae583fd67506f9549d5ead3e6accb3677a Mon Sep 17 00:00:00 2001 From: Sebastian Frank Date: Thu, 5 Nov 2026 10:20:25 +0000 Subject: [PATCH] =?UTF-8?q?=E2=9C=A8=20types(hooks):=20AES-256-GCM=20und?= =?UTF-8?q?=20HKDF=20im=20crypto-Paket=20(#65)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - SealedValue { iv, ciphertext, tag } (base64) - encrypt/decrypt mit key, aad und encoding - deriveKey (HKDF-SHA256) mit info, length und encoding Refs #65 --- index.d.ts | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 83 insertions(+) diff --git a/index.d.ts b/index.d.ts index 04f1e05..dd2d48b 100644 --- a/index.d.ts +++ b/index.d.ts @@ -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 } /**