✨ types(hooks): AES-256-GCM und HKDF im crypto-Paket (#65)
continuous-integration/drone/push Build is passing
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:
1 parent
8f17bb7ad4
commit
b80af7ae58
1 file changed
+83
Vendored
+83
@@ -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
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
Reference in new issue
Block a user