@vaultsandbox/client 0.5.0

package/dist/crypto/constants.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Centralized cryptographic constants for the VaultSandbox client
+ */
+/**
+ * HKDF context string used for key derivation
+ * This context ensures that derived keys are bound to this specific application and version
+ */
+export declare const HKDF_CONTEXT = "vaultsandbox:email:v1";
+/**
+ * ML-DSA-65 (Dilithium3) public key size in bytes
+ * This is the standard size for ML-DSA-65 public keys
+ */
+export declare const MLDSA65_PUBLIC_KEY_SIZE = 1952;

package/dist/crypto/constants.js

@@ -0,0 +1,14 @@
+/**
+ * Centralized cryptographic constants for the VaultSandbox client
+ */
+/**
+ * HKDF context string used for key derivation
+ * This context ensures that derived keys are bound to this specific application and version
+ */
+export const HKDF_CONTEXT = 'vaultsandbox:email:v1';
+/**
+ * ML-DSA-65 (Dilithium3) public key size in bytes
+ * This is the standard size for ML-DSA-65 public keys
+ */
+export const MLDSA65_PUBLIC_KEY_SIZE = 1952;
+//# sourceMappingURL=constants.js.map

package/dist/crypto/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../../src/crypto/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC;AAEpD;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,CAAC"}

package/dist/crypto/decrypt.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Email decryption using ML-KEM-768 + AES-256-GCM with HKDF-SHA-512
+ * Based on working reference implementation
+ */
+import type { Keypair, EncryptedData } from '../types/index.js';
+/**
+ * Decrypts an encrypted payload using the complete reference implementation flow
+ *
+ * @param encryptedData - The encrypted data from the server
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted plaintext as a Uint8Array
+ * @throws DecryptionError if decryption fails
+ */
+export declare function decrypt(encryptedData: EncryptedData, keypair: Keypair): Promise<Uint8Array>;
+/**
+ * Decrypts and parses email metadata
+ *
+ * @param encryptedData - The encrypted metadata
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted metadata as a parsed JSON object
+ * @throws DecryptionError if decryption or parsing fails
+ */
+export declare function decryptMetadata<T = unknown>(encryptedData: EncryptedData, keypair: Keypair): Promise<T>;
+/**
+ * Decrypts and parses email body (parsed content)
+ *
+ * @param encryptedData - The encrypted parsed content
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted parsed content as a JSON object
+ * @throws DecryptionError if decryption or parsing fails
+ */
+export declare function decryptParsed<T = unknown>(encryptedData: EncryptedData, keypair: Keypair): Promise<T>;
+/**
+ * Decrypts raw email source
+ *
+ * @param encryptedData - The encrypted raw email
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted raw email as a string
+ * @throws DecryptionError if decryption fails
+ */
+export declare function decryptRaw(encryptedData: EncryptedData, keypair: Keypair): Promise<string>;

package/dist/crypto/decrypt.js

@@ -0,0 +1,112 @@
+/**
+ * Email decryption using ML-KEM-768 + AES-256-GCM with HKDF-SHA-512
+ * Based on working reference implementation
+ */
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+import { fromBase64Url, ensureOwnBuffer, fromBase64 } from './utils.js';
+import { DecryptionError, SignatureVerificationError } from '../types/index.js';
+import { verifySignature } from './signature.js';
+import { deriveKey } from './keypair.js';
+import { HKDF_CONTEXT } from './constants.js';
+/**
+ * Decrypts an encrypted payload using the complete reference implementation flow
+ *
+ * @param encryptedData - The encrypted data from the server
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted plaintext as a Uint8Array
+ * @throws DecryptionError if decryption fails
+ */
+export async function decrypt(encryptedData, keypair) {
+    try {
+        // 0. SECURITY: Verify signature BEFORE decryption (prevent tampering)
+        verifySignature(encryptedData);
+        // 1. Decode all components
+        const ctKem = fromBase64Url(encryptedData.ct_kem);
+        const nonceBytes = fromBase64Url(encryptedData.nonce);
+        const aadBytes = fromBase64Url(encryptedData.aad);
+        const ciphertextBytes = fromBase64Url(encryptedData.ciphertext);
+        // 2. KEM Decapsulation to get shared secret
+        const sharedSecret = ml_kem768.decapsulate(ctKem, ensureOwnBuffer(keypair.secretKey));
+        // 3. Derive AES-256 key using HKDF-SHA-512
+        const aesKey = await deriveKey(sharedSecret, HKDF_CONTEXT, aadBytes, ctKem);
+        // 4. Decrypt with AES-256-GCM
+        // Ensure all buffers are properly aligned
+        const aesKeyClean = ensureOwnBuffer(aesKey);
+        const nonceClean = ensureOwnBuffer(nonceBytes);
+        const aadClean = ensureOwnBuffer(aadBytes);
+        const ciphertextClean = ensureOwnBuffer(ciphertextBytes);
+        // TypeScript doesn't recognize Uint8Array as BufferSource, but WebCrypto API accepts it
+        // The cast is safe because Uint8Array implements ArrayBufferView which extends BufferSource
+        const cryptoKey = await crypto.subtle.importKey('raw', aesKeyClean, { name: 'AES-GCM' }, false, ['decrypt']);
+        // TypeScript doesn't recognize Uint8Array as BufferSource, but WebCrypto API accepts it
+        // The cast is safe because Uint8Array implements ArrayBufferView which extends BufferSource
+        const plaintext = await crypto.subtle.decrypt({
+            name: 'AES-GCM',
+            iv: nonceClean,
+            additionalData: aadClean,
+            tagLength: 128, // 16 bytes
+        }, cryptoKey, ciphertextClean);
+        return new Uint8Array(plaintext);
+    }
+    catch (error) {
+        // Re-throw signature verification errors as-is (critical security failures)
+        if (error instanceof SignatureVerificationError) {
+            throw error;
+        }
+        if (error instanceof DecryptionError) {
+            throw error;
+        }
+        throw new DecryptionError(`Decryption failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Decrypts and parses email metadata
+ *
+ * @param encryptedData - The encrypted metadata
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted metadata as a parsed JSON object
+ * @throws DecryptionError if decryption or parsing fails
+ */
+export async function decryptMetadata(encryptedData, keypair) {
+    const plaintext = await decrypt(encryptedData, keypair);
+    try {
+        const jsonString = new TextDecoder().decode(plaintext);
+        return JSON.parse(jsonString);
+    }
+    catch (error) {
+        throw new DecryptionError(`Failed to parse decrypted metadata: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Decrypts and parses email body (parsed content)
+ *
+ * @param encryptedData - The encrypted parsed content
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted parsed content as a JSON object
+ * @throws DecryptionError if decryption or parsing fails
+ */
+export async function decryptParsed(encryptedData, keypair) {
+    return decryptMetadata(encryptedData, keypair);
+}
+/**
+ * Decrypts raw email source
+ *
+ * @param encryptedData - The encrypted raw email
+ * @param keypair - The recipient's keypair
+ * @returns The decrypted raw email as a string
+ * @throws DecryptionError if decryption fails
+ */
+export async function decryptRaw(encryptedData, keypair) {
+    const plaintext = await decrypt(encryptedData, keypair);
+    try {
+        // Decrypted content is a base64-encoded string
+        const base64String = new TextDecoder().decode(plaintext);
+        // Decode the base64 to get the actual raw email content
+        const rawEmailBytes = fromBase64(base64String);
+        return new TextDecoder().decode(rawEmailBytes);
+    }
+    catch (error) {
+        throw new DecryptionError(`Failed to decode decrypted raw email: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+//# sourceMappingURL=decrypt.js.map

package/dist/crypto/decrypt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decrypt.js","sourceRoot":"","sources":["../../src/crypto/decrypt.ts"],"names":[],"mappings":"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"}

package/dist/crypto/keypair.d.ts

@@ -0,0 +1,39 @@
+/**
+ * ML-KEM-768 (Kyber768) keypair generation
+ */
+import type { Keypair } from '../types/index.js';
+/**
+ * ML-KEM-768 public key size in bytes
+ */
+export declare const PUBLIC_KEY_SIZE = 1184;
+/**
+ * ML-KEM-768 secret key size in bytes
+ */
+export declare const SECRET_KEY_SIZE = 2400;
+/**
+ * Generates a new ML-KEM-768 keypair for inbox encryption
+ * Uses internal randomness - no seed required
+ *
+ * @returns A keypair containing public key, secret key, and base64url-encoded public key
+ */
+export declare function generateKeypair(): Keypair;
+/**
+ * Validates that a keypair has the correct structure and sizes
+ *
+ * @param keypair - The keypair to validate
+ * @returns True if valid, false otherwise
+ */
+export declare function validateKeypair(keypair: Keypair): boolean;
+/**
+ * Derive AES-256 key using WebCrypto's native HKDF-SHA-512
+ * Matches the reference implementation exactly
+ */
+export declare function deriveKey(ikm: Uint8Array, context: string, aad: Uint8Array, ctKem: Uint8Array): Promise<Uint8Array>;
+/**
+ * Derives a public key from a secret key in ML-KEM (Kyber)
+ * In ML-KEM, the public key is embedded in the secret key
+ *
+ * @param secretKey - The secret key bytes
+ * @returns The derived public key bytes
+ */
+export declare function derivePublicKeyFromSecret(secretKey: Uint8Array): Uint8Array;

package/dist/crypto/keypair.js

@@ -0,0 +1,109 @@
+/**
+ * ML-KEM-768 (Kyber768) keypair generation
+ */
+import { ml_kem768 } from '@noble/post-quantum/ml-kem.js';
+import { toBase64Url, fromBase64Url, ensureOwnBuffer, concatBuffers } from './utils.js';
+import { DecryptionError } from '../types/index.js';
+/**
+ * ML-KEM-768 public key size in bytes
+ */
+export const PUBLIC_KEY_SIZE = 1184;
+/**
+ * ML-KEM-768 secret key size in bytes
+ */
+export const SECRET_KEY_SIZE = 2400;
+/**
+ * Generates a new ML-KEM-768 keypair for inbox encryption
+ * Uses internal randomness - no seed required
+ *
+ * @returns A keypair containing public key, secret key, and base64url-encoded public key
+ */
+export function generateKeypair() {
+    const keypair = ml_kem768.keygen();
+    return {
+        publicKey: keypair.publicKey,
+        secretKey: keypair.secretKey,
+        publicKeyB64: toBase64Url(keypair.publicKey),
+    };
+}
+/**
+ * Validates that a keypair has the correct structure and sizes
+ *
+ * @param keypair - The keypair to validate
+ * @returns True if valid, false otherwise
+ */
+export function validateKeypair(keypair) {
+    if (!keypair.publicKey || !keypair.secretKey || !keypair.publicKeyB64) {
+        return false;
+    }
+    if (keypair.publicKey.length !== PUBLIC_KEY_SIZE) {
+        return false;
+    }
+    if (keypair.secretKey.length !== SECRET_KEY_SIZE) {
+        return false;
+    }
+    // Verify base64url encoding matches public key bytes
+    try {
+        const decodedPublicKey = fromBase64Url(keypair.publicKeyB64);
+        if (decodedPublicKey.length !== keypair.publicKey.length) {
+            return false;
+        }
+        for (let i = 0; i < decodedPublicKey.length; i++) {
+            if (decodedPublicKey[i] !== keypair.publicKey[i]) {
+                return false;
+            }
+        }
+    }
+    catch {
+        return false;
+    }
+    return true;
+}
+/**
+ * Derive AES-256 key using WebCrypto's native HKDF-SHA-512
+ * Matches the reference implementation exactly
+ */
+export async function deriveKey(ikm, context, aad, ctKem) {
+    const contextBytes = new TextEncoder().encode(context);
+    // Hash KEM ciphertext for salt
+    const saltBuffer = await crypto.subtle.digest('SHA-256', ctKem);
+    const salt = new Uint8Array(saltBuffer);
+    // Add aad_length prefix (4 bytes, big-endian)
+    const aadLength = new Uint8Array(4);
+    new DataView(aadLength.buffer).setUint32(0, aad.length, false);
+    const info = concatBuffers(contextBytes, aadLength, aad);
+    // Ensure buffers are owned (not views)
+    const ikmClean = ensureOwnBuffer(ikm);
+    const saltClean = ensureOwnBuffer(salt);
+    const infoClean = ensureOwnBuffer(info);
+    // Use WebCrypto's native HKDF with SHA-256(ctKem) salt
+    // TypeScript doesn't recognize Uint8Array as BufferSource, but WebCrypto API accepts it
+    // The cast is safe because Uint8Array implements ArrayBufferView which extends BufferSource
+    const baseKey = await crypto.subtle.importKey('raw', ikmClean, 'HKDF', false, [
+        'deriveBits',
+    ]);
+    const derivedBits = await crypto.subtle.deriveBits({
+        name: 'HKDF',
+        hash: 'SHA-512',
+        salt: saltClean,
+        // TypeScript doesn't recognize Uint8Array as BufferSource, but WebCrypto API accepts it
+        // The cast is safe because Uint8Array implements ArrayBufferView which extends BufferSource
+        info: infoClean,
+    }, baseKey, 256);
+    return ensureOwnBuffer(new Uint8Array(derivedBits));
+}
+/**
+ * Derives a public key from a secret key in ML-KEM (Kyber)
+ * In ML-KEM, the public key is embedded in the secret key
+ *
+ * @param secretKey - The secret key bytes
+ * @returns The derived public key bytes
+ */
+export function derivePublicKeyFromSecret(secretKey) {
+    if (secretKey.length !== SECRET_KEY_SIZE) {
+        throw new DecryptionError(`Cannot derive public key: secret key has invalid length ${secretKey.length}, expected ${SECRET_KEY_SIZE}`);
+    }
+    // In ML-KEM, the public key is appended to the secret key
+    return secretKey.slice(secretKey.length - PUBLIC_KEY_SIZE);
+}
+//# sourceMappingURL=keypair.js.map

package/dist/crypto/keypair.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keypair.js","sourceRoot":"","sources":["../../src/crypto/keypair.ts"],"names":[],"mappings":"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"}

package/dist/crypto/signature.d.ts

@@ -0,0 +1,28 @@
+/**
+ * ML-DSA-65 (Dilithium3) signature verification
+ * Based on working reference implementation
+ */
+import type { EncryptedData } from '../types/index.js';
+/**
+ * Verifies an ML-DSA-65 signature on encrypted data
+ * IMPORTANT: Must be called BEFORE decryption for security
+ *
+ * @param encryptedData - The encrypted data with signature
+ * @returns True if signature is valid
+ * @throws SignatureVerificationError if verification fails
+ */
+export declare function verifySignature(encryptedData: EncryptedData): boolean;
+/**
+ * Verifies a signature without throwing an error
+ *
+ * @param encryptedData - The encrypted data with signature
+ * @returns True if signature is valid, false otherwise
+ */
+export declare function verifySignatureSafe(encryptedData: EncryptedData): boolean;
+/**
+ * Validates that a server public key has the correct format and size
+ *
+ * @param serverPublicKey - The server's public key (base64url)
+ * @returns True if valid, false otherwise
+ */
+export declare function validateServerPublicKey(serverPublicKey: string): boolean;

package/dist/crypto/signature.js

@@ -0,0 +1,89 @@
+/**
+ * ML-DSA-65 (Dilithium3) signature verification
+ * Based on working reference implementation
+ */
+import { ml_dsa65 } from '@noble/post-quantum/ml-dsa.js';
+import { fromBase64Url, ensureOwnBuffer, concatBuffers } from './utils.js';
+import { SignatureVerificationError } from '../types/index.js';
+import { HKDF_CONTEXT, MLDSA65_PUBLIC_KEY_SIZE } from './constants.js';
+/**
+ * Builds the algorithm ciphersuite string from algs object
+ */
+function buildAlgsCiphersuite(algs) {
+    return `${algs.kem}:${algs.sig}:${algs.aead}:${algs.kdf}`;
+}
+/**
+ * Build transcript for signature verification
+ * This matches the server-side transcript construction exactly
+ */
+function buildTranscript(version, algsCiphersuite, ctKem, nonce, aad, ciphertext, serverSigPk, context) {
+    const versionBytes = new Uint8Array([version]);
+    const algsBytes = new TextEncoder().encode(algsCiphersuite);
+    const contextBytes = new TextEncoder().encode(context);
+    return concatBuffers(versionBytes, algsBytes, contextBytes, ctKem, nonce, aad, ciphertext, serverSigPk);
+}
+/**
+ * Verifies an ML-DSA-65 signature on encrypted data
+ * IMPORTANT: Must be called BEFORE decryption for security
+ *
+ * @param encryptedData - The encrypted data with signature
+ * @returns True if signature is valid
+ * @throws SignatureVerificationError if verification fails
+ */
+export function verifySignature(encryptedData) {
+    try {
+        // 1. Decode all components
+        const signature = fromBase64Url(encryptedData.sig);
+        const ctKem = fromBase64Url(encryptedData.ct_kem);
+        const nonceBytes = fromBase64Url(encryptedData.nonce);
+        const aadBytes = fromBase64Url(encryptedData.aad);
+        const ciphertextBytes = fromBase64Url(encryptedData.ciphertext);
+        const serverSigPk = fromBase64Url(encryptedData.server_sig_pk);
+        // 2. Build the transcript (exactly as the server did)
+        const algsCiphersuite = buildAlgsCiphersuite(encryptedData.algs);
+        const transcript = buildTranscript(encryptedData.v, algsCiphersuite, ctKem, nonceBytes, aadBytes, ciphertextBytes, serverSigPk, HKDF_CONTEXT);
+        // 3. Verify the signature
+        // Noble's ML-DSA verify signature order: (signature, message, publicKey)
+        const isValid = ml_dsa65.verify(ensureOwnBuffer(signature), ensureOwnBuffer(transcript), ensureOwnBuffer(serverSigPk));
+        if (!isValid) {
+            throw new SignatureVerificationError('SIGNATURE VERIFICATION FAILED - Data may be tampered!');
+        }
+        return true;
+    }
+    catch (error) {
+        if (error instanceof SignatureVerificationError) {
+            throw error;
+        }
+        throw new SignatureVerificationError(`Signature verification error: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Verifies a signature without throwing an error
+ *
+ * @param encryptedData - The encrypted data with signature
+ * @returns True if signature is valid, false otherwise
+ */
+export function verifySignatureSafe(encryptedData) {
+    try {
+        return verifySignature(encryptedData);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Validates that a server public key has the correct format and size
+ *
+ * @param serverPublicKey - The server's public key (base64url)
+ * @returns True if valid, false otherwise
+ */
+export function validateServerPublicKey(serverPublicKey) {
+    try {
+        const publicKey = fromBase64Url(serverPublicKey);
+        return publicKey.length === MLDSA65_PUBLIC_KEY_SIZE;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=signature.js.map

package/dist/crypto/signature.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signature.js","sourceRoot":"","sources":["../../src/crypto/signature.ts"],"names":[],"mappings":"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"}

package/dist/crypto/utils.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Crypto utilities for base64url encoding/decoding and buffer operations
+ */
+/**
+ * Converts a Uint8Array to a base64url-encoded string (no padding)
+ */
+export declare function toBase64Url(buffer: Uint8Array): string;
+/**
+ * Converts a base64url-encoded string to a Uint8Array
+ */
+export declare function fromBase64Url(base64url: string): Uint8Array;
+/**
+ * Ensures a buffer is owned (not a view) for WebCrypto compatibility.
+ * WebCrypto operations require buffers to be properly aligned and owned.
+ */
+export declare function ensureOwnBuffer(buffer: Uint8Array): Uint8Array;
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array
+ */
+export declare function concatBuffers(...buffers: Uint8Array[]): Uint8Array;
+/**
+ * Converts a Uint8Array to a standard base64-encoded string
+ */
+export declare function toBase64(buffer: Uint8Array): string;
+/**
+ * Converts a standard base64-encoded string to a Uint8Array
+ */
+export declare function fromBase64(base64: string): Uint8Array;

package/dist/crypto/utils.js

@@ -0,0 +1,60 @@
+/**
+ * Crypto utilities for base64url encoding/decoding and buffer operations
+ */
+/**
+ * Converts a Uint8Array to a base64url-encoded string (no padding)
+ */
+export function toBase64Url(buffer) {
+    const base64 = Buffer.from(buffer).toString('base64');
+    return base64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '');
+}
+/**
+ * Converts a base64url-encoded string to a Uint8Array
+ */
+export function fromBase64Url(base64url) {
+    // Add padding if needed
+    let base64 = base64url.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = base64.length % 4;
+    if (pad) {
+        base64 += '='.repeat(4 - pad);
+    }
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+}
+/**
+ * Ensures a buffer is owned (not a view) for WebCrypto compatibility.
+ * WebCrypto operations require buffers to be properly aligned and owned.
+ */
+export function ensureOwnBuffer(buffer) {
+    // Check if buffer is a view of another buffer
+    if (buffer.byteOffset !== 0 || buffer.byteLength !== buffer.buffer.byteLength) {
+        // Create a new buffer with copied data
+        return new Uint8Array(buffer);
+    }
+    return buffer;
+}
+/**
+ * Concatenates multiple Uint8Arrays into a single Uint8Array
+ */
+export function concatBuffers(...buffers) {
+    const totalLength = buffers.reduce((sum, buf) => sum + buf.length, 0);
+    const result = new Uint8Array(totalLength);
+    let offset = 0;
+    for (const buf of buffers) {
+        result.set(buf, offset);
+        offset += buf.length;
+    }
+    return result;
+}
+/**
+ * Converts a Uint8Array to a standard base64-encoded string
+ */
+export function toBase64(buffer) {
+    return Buffer.from(buffer).toString('base64');
+}
+/**
+ * Converts a standard base64-encoded string to a Uint8Array
+ */
+export function fromBase64(base64) {
+    return new Uint8Array(Buffer.from(base64, 'base64'));
+}
+//# sourceMappingURL=utils.js.map

package/dist/crypto/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/crypto/utils.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,WAAW,CAAC,MAAkB;IAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACtD,OAAO,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;AAC1E,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,SAAiB;IAC7C,wBAAwB;IACxB,IAAI,MAAM,GAAG,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAC7D,MAAM,GAAG,GAAG,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;IAC9B,IAAI,GAAG,EAAE,CAAC;QACR,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,MAAkB;IAChD,8CAA8C;IAC9C,IAAI,MAAM,CAAC,UAAU,KAAK,CAAC,IAAI,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,CAAC;QAC9E,uCAAuC;QACvC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC;IAChC,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,aAAa,CAAC,GAAG,OAAqB;IACpD,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,GAAG,GAAG,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACtE,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,WAAW,CAAC,CAAC;IAC3C,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,GAAG,IAAI,OAAO,EAAE,CAAC;QAC1B,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACxB,MAAM,IAAI,GAAG,CAAC,MAAM,CAAC;IACvB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,QAAQ,CAAC,MAAkB;IACzC,OAAO,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc;IACvC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,CAAC;AACvD,CAAC"}

package/dist/email.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Email model - represents a decrypted email with convenient accessors
+ */
+import type { IEmail, EmailData, DecryptedMetadata, DecryptedParsed, AttachmentData, AuthResults as IAuthResults, RawEmail, Keypair } from './types/index.js';
+import type { ApiClient } from './http/api-client.js';
+/**
+ * Represents a fully decrypted email, providing access to its content,
+ * attachments, and metadata.
+ */
+export declare class Email implements IEmail {
+    /** The unique identifier for the email. */
+    readonly id: string;
+    /** The sender's email address. */
+    readonly from: string;
+    /** An array of recipient email addresses. */
+    readonly to: string[];
+    /** The subject of the email. */
+    readonly subject: string;
+    /** The date and time the email was received. */
+    readonly receivedAt: Date;
+    /** A boolean indicating whether the email has been read. */
+    readonly isRead: boolean;
+    /** The plain text content of the email, or `null` if not available. */
+    readonly text: string | null;
+    /** The HTML content of the email, or `null` if not available. */
+    readonly html: string | null;
+    /** An array of attachments found in the email. */
+    readonly attachments: AttachmentData[];
+    /** An array of URLs extracted from the email's content. */
+    readonly links: string[];
+    /** An object containing the email's headers. */
+    readonly headers: Record<string, unknown>;
+    /** The email's authentication results (SPF, DKIM, DMARC). */
+    readonly authResults: IAuthResults;
+    /** Any other metadata associated with the email. */
+    readonly metadata: Record<string, unknown>;
+    private emailAddress;
+    private apiClient;
+    private keypair;
+    /**
+     * @internal
+     * Do not construct this class directly.
+     */
+    constructor(emailData: EmailData, metadata: DecryptedMetadata, parsed: DecryptedParsed | null, emailAddress: string, apiClient: ApiClient, keypair: Keypair);
+    /**
+     * Marks this email as read.
+     *
+     * @returns A promise that resolves when the email is marked as read.
+     */
+    markAsRead(): Promise<void>;
+    /**
+     * Deletes this email from the inbox.
+     *
+     * @returns A promise that resolves when the email is deleted.
+     */
+    delete(): Promise<void>;
+    /**
+     * Fetches the raw, decrypted source of the email.
+     *
+     * @returns A promise that resolves to the raw email data.
+     */
+    getRaw(): Promise<RawEmail>;
+}