@gnufoo/envlp 0.1.1

package/envlp_wasm.d.ts

@@ -0,0 +1,323 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/**
+ * Returns the key size in bytes (32 = 256 bits).
+ */
+export function KEY_SIZE(): number;
+
+/**
+ * Returns the nonce size in bytes (24 = 192 bits).
+ */
+export function NONCE_SIZE(): number;
+
+/**
+ * Returns the current envelope format version.
+ *
+ * Per AAED spec, current version is 1.
+ */
+export function SPEC_VERSION(): number;
+
+/**
+ * Returns the authentication tag size in bytes (16 = 128 bits).
+ */
+export function TAG_SIZE(): number;
+
+/**
+ * Checks if bytes start with the envelope magic prefix.
+ *
+ * Magic bytes are `0x454E5601` ("ENV" + version byte).
+ * This can be used for quick format detection without full CBOR parsing.
+ *
+ * # Arguments
+ *
+ * * `bytes` - Bytes to check (Uint8Array)
+ *
+ * # Returns
+ *
+ * `true` if bytes start with magic prefix, `false` otherwise.
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const envelope = seal(key, plaintext, aad, "my-key");
+ * console.log(hasMagicPrefix(envelope)); // true
+ *
+ * const noMagic = seal(key, plaintext, aad, "my-key", true, false);
+ * console.log(hasMagicPrefix(noMagic)); // false
+ * ```
+ */
+export function hasMagicPrefix(bytes: Uint8Array): boolean;
+
+/**
+ * Inspects envelope metadata without decryption.
+ *
+ * Returns information about the envelope that can be extracted without
+ * decryption. Useful for logging, debugging, and routing decisions
+ * (e.g., selecting the correct key based on key_id).
+ *
+ * # Arguments
+ *
+ * * `envelope_bytes` - CBOR-encoded envelope (Uint8Array)
+ *
+ * # Returns
+ *
+ * JavaScript object with envelope metadata:
+ * - `version`: Envelope format version (number)
+ * - `algorithm`: Algorithm name (string, e.g., "XChaCha20Poly1305")
+ * - `algorithmId`: Algorithm ID (number, 1=XChaCha20, 2=GCM-SIV, 3=GCM)
+ * - `keyId`: Key identifier from header (string)
+ * - `nonceHex`: Nonce as hexadecimal string
+ * - `ciphertextLen`: Ciphertext length in bytes (number)
+ * - `hasAad`: Whether AAD is included in envelope (boolean)
+ * - `aadLen`: AAD length in bytes (number or null)
+ * - `isWrappedMode`: Whether envelope uses wrapped mode (boolean)
+ *
+ * # Errors
+ *
+ * Throws a JavaScript error if envelope parsing fails.
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const meta = inspect(envelope);
+ * console.log(`Key: ${meta.keyId}, Algorithm: ${meta.algorithm}`);
+ * if (meta.hasAad) {
+ *   console.log(`AAD size: ${meta.aadLen} bytes`);
+ * }
+ * ```
+ */
+export function inspect(envelope_bytes: Uint8Array): any;
+
+/**
+ * Generates a new 256-bit encryption key.
+ *
+ * Uses a cryptographically secure random number generator.
+ *
+ * # Returns
+ *
+ * A 32-byte `Uint8Array` containing the random key.
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const key = keygen();
+ * console.log(key.length); // 32
+ * ```
+ */
+export function keygen(): Uint8Array;
+
+/**
+ * Returns the magic bytes as Uint8Array.
+ *
+ * Magic bytes are `0x454E5601` ("ENV" + version byte) for format detection.
+ */
+export function magicBytes(): Uint8Array;
+
+/**
+ * Decrypts an envelope using reconstructed AAD.
+ *
+ * Use this when AAD was not included in the envelope (reconstructed mode).
+ * The provided AAD JSON will be canonicalized before verification.
+ *
+ * # Arguments
+ *
+ * * `key` - 256-bit decryption key (Uint8Array, 32 bytes)
+ * * `envelope_bytes` - CBOR-encoded envelope (Uint8Array)
+ * * `aad_json` - AAD as JSON string (must match AAD used during encryption)
+ *
+ * # Returns
+ *
+ * Decrypted plaintext as `Uint8Array`.
+ *
+ * # Errors
+ *
+ * Throws a JavaScript error with message "DECRYPTION_FAILED" for ANY failure.
+ *
+ * # Warning
+ *
+ * Reconstructed AAD requires bit-perfect reproduction of all context values.
+ * Unicode normalization differences between systems can cause decryption to fail.
+ * Use transmitted AAD for cross-platform deployments.
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const key = keygen();
+ * const aad = '{"v":1,"tenant":"org","resource":"res","purpose":"enc"}';
+ *
+ * // Seal without AAD in envelope
+ * const envelope = seal(key, plaintext, aad, "my-key", false, true);
+ *
+ * // Reconstruct AAD at decryption time
+ * const decrypted = openReconstructed(key, envelope, aad);
+ * ```
+ */
+export function openReconstructed(key: Uint8Array, envelope_bytes: Uint8Array, aad_json: string): Uint8Array;
+
+/**
+ * Decrypts an envelope using transmitted AAD.
+ *
+ * This is the common case where AAD is stored in the envelope.
+ *
+ * # Arguments
+ *
+ * * `key` - 256-bit decryption key (Uint8Array, 32 bytes)
+ * * `envelope_bytes` - CBOR-encoded envelope (Uint8Array)
+ *
+ * # Returns
+ *
+ * Decrypted plaintext as `Uint8Array`.
+ *
+ * # Errors
+ *
+ * Throws a JavaScript error with message "DECRYPTION_FAILED" for ANY failure:
+ * - Invalid envelope format
+ * - No transmitted AAD in envelope
+ * - Wrong key
+ * - Corrupted ciphertext
+ * - Mismatched AAD
+ *
+ * Per AAED spec Section 10, errors are intentionally generic to prevent
+ * information leakage.
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const key = keygen();
+ * const envelope = seal(key, plaintext, aad, "my-key");
+ *
+ * const decrypted = openTransmitted(key, envelope);
+ * console.log(new TextDecoder().decode(decrypted));
+ * ```
+ */
+export function openTransmitted(key: Uint8Array, envelope_bytes: Uint8Array): Uint8Array;
+
+/**
+ * Encrypts plaintext into an envelope.
+ *
+ * # Arguments
+ *
+ * * `key` - 256-bit encryption key (Uint8Array, 32 bytes)
+ * * `plaintext` - Data to encrypt (Uint8Array)
+ * * `aad_json` - AAD as JSON string (will be canonicalized via canaad)
+ * * `key_id` - Key identifier string for the envelope header
+ * * `include_aad` - Whether to include AAD in envelope (default: true)
+ * * `emit_magic` - Whether to emit magic bytes prefix (default: true)
+ *
+ * # Returns
+ *
+ * Envelope as `Uint8Array` (CBOR-encoded, optionally with magic prefix).
+ *
+ * # Errors
+ *
+ * Throws a JavaScript error if:
+ * - Key size is invalid (must be 32 bytes)
+ * - AAD JSON canonicalization fails
+ * - Key ID exceeds 256 bytes
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const key = keygen();
+ * const plaintext = new TextEncoder().encode("Hello, World!");
+ * const aad = '{"v":1,"tenant":"org","resource":"res","purpose":"enc"}';
+ *
+ * // Default options (include AAD, emit magic)
+ * const envelope = seal(key, plaintext, aad, "my-key");
+ *
+ * // Without AAD in envelope (reconstructed mode)
+ * const envelope2 = seal(key, plaintext, aad, "my-key", false, true);
+ * ```
+ */
+export function seal(key: Uint8Array, plaintext: Uint8Array, aad_json: string, key_id: string, include_aad?: boolean | null, emit_magic?: boolean | null): Uint8Array;
+
+/**
+ * Validates envelope structure without decryption.
+ *
+ * Checks structural integrity, not cryptographic validity. This is useful
+ * for fail-fast validation before attempting expensive operations.
+ *
+ * # Checks Performed
+ *
+ * - Envelope version is supported
+ * - Algorithm is known
+ * - AES-256-GCM has wrapped mode requirement
+ * - Ciphertext is at least tag size
+ *
+ * # Arguments
+ *
+ * * `envelope_bytes` - CBOR-encoded envelope (Uint8Array)
+ *
+ * # Returns
+ *
+ * JavaScript object with validation result:
+ * - `valid`: Whether the envelope passed all checks (boolean)
+ * - `errors`: Array of error messages (string[])
+ *
+ * # Example (JavaScript)
+ *
+ * ```javascript
+ * const result = validate(envelope);
+ * if (result.valid) {
+ *   console.log("Envelope is valid");
+ * } else {
+ *   console.error("Validation errors:", result.errors);
+ * }
+ * ```
+ */
+export function validate(envelope_bytes: Uint8Array): any;
+
+/**
+ * Returns the library version.
+ */
+export function version(): string;
+
+export type InitInput = RequestInfo | URL | Response | BufferSource | WebAssembly.Module;
+
+export interface InitOutput {
+    readonly memory: WebAssembly.Memory;
+    readonly KEY_SIZE: () => number;
+    readonly NONCE_SIZE: () => number;
+    readonly SPEC_VERSION: () => number;
+    readonly TAG_SIZE: () => number;
+    readonly hasMagicPrefix: (a: number, b: number) => number;
+    readonly inspect: (a: number, b: number) => [number, number, number];
+    readonly keygen: () => [number, number];
+    readonly magicBytes: () => [number, number];
+    readonly openReconstructed: (a: number, b: number, c: number, d: number, e: number, f: number) => [number, number, number, number];
+    readonly openTransmitted: (a: number, b: number, c: number, d: number) => [number, number, number, number];
+    readonly seal: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number, j: number) => [number, number, number, number];
+    readonly validate: (a: number, b: number) => [number, number, number];
+    readonly version: () => [number, number];
+    readonly __wbindgen_exn_store: (a: number) => void;
+    readonly __externref_table_alloc: () => number;
+    readonly __wbindgen_externrefs: WebAssembly.Table;
+    readonly __wbindgen_malloc: (a: number, b: number) => number;
+    readonly __externref_table_dealloc: (a: number) => void;
+    readonly __wbindgen_free: (a: number, b: number, c: number) => void;
+    readonly __wbindgen_realloc: (a: number, b: number, c: number, d: number) => number;
+    readonly __wbindgen_start: () => void;
+}
+
+export type SyncInitInput = BufferSource | WebAssembly.Module;
+
+/**
+ * Instantiates the given `module`, which can either be bytes or
+ * a precompiled `WebAssembly.Module`.
+ *
+ * @param {{ module: SyncInitInput }} module - Passing `SyncInitInput` directly is deprecated.
+ *
+ * @returns {InitOutput}
+ */
+export function initSync(module: { module: SyncInitInput } | SyncInitInput): InitOutput;
+
+/**
+ * If `module_or_path` is {RequestInfo} or {URL}, makes a request and
+ * for everything else, calls `WebAssembly.instantiate` directly.
+ *
+ * @param {{ module_or_path: InitInput | Promise<InitInput> }} module_or_path - Passing `InitInput` directly is deprecated.
+ *
+ * @returns {Promise<InitOutput>}
+ */
+export default function __wbg_init (module_or_path?: { module_or_path: InitInput | Promise<InitInput> } | InitInput | Promise<InitInput>): Promise<InitOutput>;