@vaultsandbox/client 0.5.0

package/dist/types/index.d.ts

@@ -0,0 +1,434 @@
+/**
+ * VaultSandbox Client SDK - Type Definitions
+ */
+/**
+ * Configuration for the VaultSandboxClient.
+ */
+export interface ClientConfig {
+    /** The URL of the VaultSandbox Gateway server. */
+    url: string;
+    /** Your API key for authentication. */
+    apiKey: string;
+    /**
+     * The email delivery strategy to use.
+     * - `sse`: Use Server-Sent Events for real-time updates.
+     * - `polling`: Use traditional polling.
+     * - `auto`: Use SSE if available, otherwise fall back to polling (default).
+     */
+    strategy?: 'sse' | 'polling' | 'auto';
+    /** The base interval for polling in milliseconds (default: 2000). */
+    pollingInterval?: number;
+    /** The maximum number of retries for failed HTTP requests (default: 3). */
+    maxRetries?: number;
+    /** The initial delay in milliseconds between retries (default: 1000). */
+    retryDelay?: number;
+    /** An array of HTTP status codes that should trigger a retry. */
+    retryOn?: number[];
+    /** The initial interval in milliseconds for SSE reconnection attempts (default: 5000). */
+    sseReconnectInterval?: number;
+    /** The maximum number of SSE reconnection attempts (default: 10). */
+    sseMaxReconnectAttempts?: number;
+}
+/**
+ * Options for creating a new inbox.
+ */
+export interface CreateInboxOptions {
+    /** The time-to-live for the inbox in seconds. */
+    ttl?: number;
+    /** A specific email address to request for the inbox. */
+    emailAddress?: string;
+}
+/**
+ * Exported inbox data structure for sharing or backup purposes.
+ * Contains all necessary information to import and access an inbox.
+ */
+export interface ExportedInboxData {
+    /** The email address for this inbox */
+    emailAddress: string;
+    /** ISO timestamp when the inbox expires */
+    expiresAt: string;
+    /** Unique hash identifier for the inbox */
+    inboxHash: string;
+    /** Server's public signing key */
+    serverSigPk: string;
+    /** Base64-encoded public key */
+    publicKeyB64: string;
+    /** Base64-encoded secret key for decryption */
+    secretKeyB64: string;
+    /** ISO timestamp when the inbox was exported */
+    exportedAt: string;
+}
+/**
+ * Data returned by the server when an inbox is created.
+ * Matches the CreateInboxResponseDto from the API.
+ * @internal
+ */
+export interface InboxData {
+    /** The email address assigned to the inbox. */
+    emailAddress: string;
+    /** ISO 8601 timestamp when the inbox will expire. */
+    expiresAt: string;
+    /** Base64URL-encoded SHA-256 hash of the client KEM public key, used for SSE subscriptions and API references. */
+    inboxHash: string;
+    /** Base64URL-encoded server signing public key for verifying server signatures. */
+    serverSigPk: string;
+}
+/**
+ * The synchronization status of an inbox.
+ */
+export interface SyncStatus {
+    /** The number of emails in the inbox. */
+    emailCount: number;
+    /** A hash of the email list, used for efficient change detection. */
+    emailsHash: string;
+}
+/**
+ * Options for waiting for an email.
+ */
+export interface WaitOptions {
+    /** The maximum time to wait in milliseconds (default: 30000). */
+    timeout?: number;
+    /** The interval for polling in milliseconds (default: 2000). */
+    pollInterval?: number;
+    /** A string or regular expression to match against the email subject. */
+    subject?: string | RegExp;
+    /** A string or regular expression to match against the sender's email address. */
+    from?: string | RegExp;
+    /** A custom predicate function to filter emails. */
+    predicate?: (email: IEmail) => boolean;
+}
+/**
+ * Options for waiting for a specific number of emails.
+ */
+export interface WaitForCountOptions {
+    /** The maximum time to wait in milliseconds (default: 30000). */
+    timeout?: number;
+}
+/**
+ * Raw email data returned from the API.
+ * @internal
+ */
+export interface EmailData {
+    id: string;
+    inboxId: string;
+    receivedAt: string;
+    isRead: boolean;
+    encryptedMetadata: EncryptedData;
+    encryptedParsed?: EncryptedData;
+}
+/**
+ * The structure of encrypted data returned from the server.
+ * @internal
+ */
+export interface EncryptedData {
+    v: number;
+    ct_kem: string;
+    nonce: string;
+    aad: string;
+    ciphertext: string;
+    sig: string;
+    server_sig_pk: string;
+    algs: {
+        kem: string;
+        sig: string;
+        aead: string;
+        kdf: string;
+    };
+}
+/**
+ * Decrypted email metadata.
+ * @internal
+ */
+export interface DecryptedMetadata {
+    from: string;
+    to: string[];
+    subject: string;
+    receivedAt?: string;
+}
+/**
+ * Decrypted and parsed email content.
+ * @internal
+ */
+export interface DecryptedParsed {
+    text: string | null;
+    html: string | null;
+    headers: Record<string, unknown>;
+    attachments: AttachmentData[];
+    links?: string[];
+    authResults?: AuthResultsData;
+}
+/**
+ * Represents an email attachment.
+ */
+export interface AttachmentData {
+    /** The filename of the attachment. */
+    filename: string;
+    /** The content type of the attachment. */
+    contentType: string;
+    /** The size of the attachment in bytes. */
+    size: number;
+    /** Optional content ID for inline attachments referenced in HTML. */
+    contentId?: string;
+    /** Content disposition header value (e.g., 'attachment', 'inline'). */
+    contentDisposition?: string;
+    /** Optional checksum for verifying attachment integrity. */
+    checksum?: string;
+    /** The content of the attachment as a byte array. */
+    content?: Uint8Array;
+}
+/**
+ * Represents the raw, decrypted source of an email.
+ */
+export interface RawEmail {
+    /** The ID of the email. */
+    id: string;
+    /** The raw email content. */
+    raw: string;
+}
+/**
+ * @internal
+ */
+export interface RawEmailData {
+    id: string;
+    encryptedRaw: EncryptedData;
+}
+/**
+ * The result of an SPF (Sender Policy Framework) validation check.
+ */
+export interface SPFResult {
+    status: 'pass' | 'fail' | 'softfail' | 'neutral' | 'none' | 'temperror' | 'permerror';
+    domain?: string;
+    ip?: string;
+    info?: string;
+}
+/**
+ * The result of a DKIM (DomainKeys Identified Mail) validation check.
+ */
+export interface DKIMResult {
+    status: 'pass' | 'fail' | 'none';
+    domain?: string;
+    selector?: string;
+    info?: string;
+}
+/**
+ * The result of a DMARC (Domain-based Message Authentication, Reporting, and Conformance) validation check.
+ */
+export interface DMARCResult {
+    status: 'pass' | 'fail' | 'none';
+    policy?: 'none' | 'quarantine' | 'reject';
+    aligned?: boolean;
+    domain?: string;
+    info?: string;
+}
+/**
+ * The result of a reverse DNS validation check.
+ */
+export interface ReverseDNSResult {
+    status: 'pass' | 'fail' | 'none';
+    ip?: string;
+    hostname?: string;
+    info?: string;
+}
+/**
+ * The raw data for email authentication results.
+ */
+export interface AuthResultsData {
+    spf?: SPFResult;
+    dkim?: DKIMResult[];
+    dmarc?: DMARCResult;
+    reverseDns?: ReverseDNSResult;
+}
+/**
+ * A summary of email authentication validation.
+ */
+export interface AuthValidation {
+    /** A boolean indicating whether all checks passed. */
+    passed: boolean;
+    /** A boolean indicating whether the SPF check passed. */
+    spfPassed: boolean;
+    /** A boolean indicating whether the DKIM check passed. */
+    dkimPassed: boolean;
+    /** A boolean indicating whether the DMARC check passed. */
+    dmarcPassed: boolean;
+    /** A boolean indicating whether the reverse DNS check passed. */
+    reverseDnsPassed: boolean;
+    /** An array of strings describing any failures. */
+    failures: string[];
+}
+/**
+ * Interface for the Email class.
+ */
+export interface IEmail {
+    readonly id: string;
+    readonly from: string;
+    readonly to: string[];
+    readonly subject: string;
+    readonly receivedAt: Date;
+    readonly isRead: boolean;
+    readonly text: string | null;
+    readonly html: string | null;
+    readonly attachments: AttachmentData[];
+    readonly links: string[];
+    readonly headers: Record<string, unknown>;
+    readonly authResults: AuthResults;
+    readonly metadata: Record<string, unknown>;
+    markAsRead(): Promise<void>;
+    delete(): Promise<void>;
+    getRaw(): Promise<RawEmail>;
+}
+/**
+ * Interface for the AuthResults class.
+ */
+export interface AuthResults extends AuthResultsData {
+    validate(): AuthValidation;
+}
+/**
+ * Information about the VaultSandbox server.
+ */
+export interface ServerInfo {
+    /** Base64URL-encoded server signing public key for ML-DSA-65. */
+    serverSigPk: string;
+    /** Cryptographic algorithms supported by the server. */
+    algs: {
+        /** Key encapsulation mechanism algorithm (e.g., 'ML-KEM-768'). */
+        kem: string;
+        /** Digital signature algorithm (e.g., 'ML-DSA-65'). */
+        sig: string;
+        /** Authenticated encryption algorithm (e.g., 'AES-256-GCM'). */
+        aead: string;
+        /** Key derivation function (e.g., 'HKDF-SHA-512'). */
+        kdf: string;
+    };
+    /** Context string for the encryption scheme. */
+    context: string;
+    /** Maximum time-to-live for inboxes in seconds. */
+    maxTtl: number;
+    /** Default time-to-live for inboxes in seconds. */
+    defaultTtl: number;
+    /** Whether the server SSE console is enabled. */
+    sseConsole: boolean;
+    /** List of domains allowed for inbox creation. */
+    allowedDomains: string[];
+}
+/**
+ * Represents a subscription to an event source, such as new emails.
+ */
+export interface Subscription {
+    /** Unsubscribes from the event source and cleans up resources. */
+    unsubscribe(): void;
+}
+/**
+ * @internal
+ */
+export interface SSEConfig {
+    url: string;
+    apiKey: string;
+    reconnectInterval?: number;
+    maxReconnectAttempts?: number;
+    backoffMultiplier?: number;
+}
+/**
+ * @internal
+ */
+export interface SSEEvent {
+    inboxHash: string;
+    emailId: string;
+    emailData: EmailData;
+}
+/**
+ * @internal
+ */
+export interface SSEMessageData {
+    inboxId: string;
+    emailId: string;
+    encryptedMetadata: EncryptedData;
+}
+/**
+ * A quantum-safe keypair used for encryption and decryption.
+ * @internal
+ */
+export interface Keypair {
+    publicKey: Uint8Array;
+    secretKey: Uint8Array;
+    publicKeyB64: string;
+}
+/**
+ * @internal
+ */
+export interface DecryptionResult {
+    plaintext: Uint8Array;
+    verified: boolean;
+}
+/**
+ * Base class for all errors thrown by the VaultSandbox client.
+ */
+export declare class VaultSandboxError extends Error {
+    constructor(message: string);
+}
+/**
+ * An error thrown when the API returns a non-successful status code.
+ */
+export declare class ApiError extends VaultSandboxError {
+    statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+/**
+ * An error thrown when a network error occurs.
+ */
+export declare class NetworkError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when an operation times out.
+ */
+export declare class TimeoutError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when decryption fails.
+ */
+export declare class DecryptionError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when signature verification fails.
+ */
+export declare class SignatureVerificationError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when an inbox is not found.
+ */
+export declare class InboxNotFoundError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when an email is not found.
+ */
+export declare class EmailNotFoundError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when an SSE (Server-Sent Events) error occurs.
+ */
+export declare class SSEError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when trying to import an inbox that already exists.
+ */
+export declare class InboxAlreadyExistsError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when imported inbox data fails validation.
+ */
+export declare class InvalidImportDataError extends VaultSandboxError {
+    constructor(message: string);
+}
+/**
+ * An error thrown when a delivery strategy is not set or is invalid.
+ */
+export declare class StrategyError extends VaultSandboxError {
+    constructor(message: string);
+}

package/dist/types/index.js

@@ -0,0 +1,127 @@
+/**
+ * VaultSandbox Client SDK - Type Definitions
+ */
+// ===== Errors =====
+/**
+ * Base class for all errors thrown by the VaultSandbox client.
+ */
+export class VaultSandboxError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'VaultSandboxError';
+        Object.setPrototypeOf(this, VaultSandboxError.prototype);
+    }
+}
+/**
+ * An error thrown when the API returns a non-successful status code.
+ */
+export class ApiError extends VaultSandboxError {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = 'ApiError';
+        Object.setPrototypeOf(this, ApiError.prototype);
+    }
+}
+/**
+ * An error thrown when a network error occurs.
+ */
+export class NetworkError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'NetworkError';
+        Object.setPrototypeOf(this, NetworkError.prototype);
+    }
+}
+/**
+ * An error thrown when an operation times out.
+ */
+export class TimeoutError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'TimeoutError';
+        Object.setPrototypeOf(this, TimeoutError.prototype);
+    }
+}
+/**
+ * An error thrown when decryption fails.
+ */
+export class DecryptionError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'DecryptionError';
+        Object.setPrototypeOf(this, DecryptionError.prototype);
+    }
+}
+/**
+ * An error thrown when signature verification fails.
+ */
+export class SignatureVerificationError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'SignatureVerificationError';
+        Object.setPrototypeOf(this, SignatureVerificationError.prototype);
+    }
+}
+/**
+ * An error thrown when an inbox is not found.
+ */
+export class InboxNotFoundError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'InboxNotFoundError';
+        Object.setPrototypeOf(this, InboxNotFoundError.prototype);
+    }
+}
+/**
+ * An error thrown when an email is not found.
+ */
+export class EmailNotFoundError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'EmailNotFoundError';
+        Object.setPrototypeOf(this, EmailNotFoundError.prototype);
+    }
+}
+/**
+ * An error thrown when an SSE (Server-Sent Events) error occurs.
+ */
+export class SSEError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'SSEError';
+        Object.setPrototypeOf(this, SSEError.prototype);
+    }
+}
+/**
+ * An error thrown when trying to import an inbox that already exists.
+ */
+export class InboxAlreadyExistsError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'InboxAlreadyExistsError';
+        Object.setPrototypeOf(this, InboxAlreadyExistsError.prototype);
+    }
+}
+/**
+ * An error thrown when imported inbox data fails validation.
+ */
+export class InvalidImportDataError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidImportDataError';
+        Object.setPrototypeOf(this, InvalidImportDataError.prototype);
+    }
+}
+/**
+ * An error thrown when a delivery strategy is not set or is invalid.
+ */
+export class StrategyError extends VaultSandboxError {
+    constructor(message) {
+        super(message);
+        this.name = 'StrategyError';
+        Object.setPrototypeOf(this, StrategyError.prototype);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

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

package/dist/utils/email-utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Shared email utilities for decryption and filtering
+ */
+import type { Keypair, EmailData, IEmail, WaitOptions } from '../types/index.js';
+import type { ApiClient } from '../http/api-client.js';
+/**
+ * Decrypts an EmailData object into an Email instance.
+ * If only metadata is present, fetch the full email (including parsed content) first.
+ * IMPORTANT: Signature verification happens BEFORE decryption for security
+ */
+export declare function decryptEmailData(emailData: EmailData, keypair: Keypair, emailAddress: string, apiClient: ApiClient): Promise<IEmail>;
+/**
+ * Finds the first email matching the specified criteria
+ */
+export declare function findMatchingEmail(emails: IEmail[], options: WaitOptions): IEmail | null;
+/**
+ * Check if email matches the specified filters
+ */
+export declare function matchesFilters(email: IEmail, options: WaitOptions): boolean;

package/dist/utils/email-utils.js

@@ -0,0 +1,92 @@
+/**
+ * Shared email utilities for decryption and filtering
+ */
+import { Email } from '../email.js';
+import { decryptMetadata, decryptParsed } from '../crypto/decrypt.js';
+import { verifySignature } from '../crypto/signature.js';
+import { fromBase64 } from '../crypto/utils.js';
+/**
+ * Decrypts an EmailData object into an Email instance.
+ * If only metadata is present, fetch the full email (including parsed content) first.
+ * IMPORTANT: Signature verification happens BEFORE decryption for security
+ */
+export async function decryptEmailData(emailData, keypair, emailAddress, apiClient) {
+    const fullEmailData = emailData.encryptedParsed ? emailData : await apiClient.getEmail(emailAddress, emailData.id);
+    // Verify signature FIRST (before decryption) - signature includes server public key
+    verifySignature(fullEmailData.encryptedMetadata);
+    // Decrypt metadata
+    const metadata = await decryptMetadata(fullEmailData.encryptedMetadata, keypair);
+    // Decrypt parsed content if available
+    let parsed = null;
+    if (fullEmailData.encryptedParsed) {
+        // Verify signature for parsed content too
+        verifySignature(fullEmailData.encryptedParsed);
+        parsed = await decryptParsed(fullEmailData.encryptedParsed, keypair);
+        // Transform attachment content from base64 strings to Uint8Array
+        // The server returns attachment content as base64-encoded strings, but our type expects Uint8Array
+        if (parsed?.attachments) {
+            parsed.attachments = parsed.attachments.map((att) => {
+                // Check if content exists and is a string (base64 encoded)
+                if (att.content && typeof att.content === 'string') {
+                    return {
+                        ...att,
+                        content: fromBase64(att.content),
+                    };
+                }
+                // Content is already Uint8Array or undefined
+                return att;
+            });
+        }
+    }
+    return new Email(fullEmailData, metadata, parsed, emailAddress, apiClient, keypair);
+}
+/**
+ * Finds the first email matching the specified criteria
+ */
+export function findMatchingEmail(emails, options) {
+    for (const email of emails) {
+        if (matchesFilters(email, options)) {
+            return email;
+        }
+    }
+    return null;
+}
+/**
+ * Check if email matches the specified filters
+ */
+export function matchesFilters(email, options) {
+    // Check subject filter
+    if (options.subject) {
+        if (typeof options.subject === 'string') {
+            if (!email.subject.includes(options.subject)) {
+                return false;
+            }
+        }
+        else if (options.subject instanceof RegExp) {
+            if (!options.subject.test(email.subject)) {
+                return false;
+            }
+        }
+    }
+    // Check from filter
+    if (options.from) {
+        if (typeof options.from === 'string') {
+            if (!email.from.includes(options.from)) {
+                return false;
+            }
+        }
+        else if (options.from instanceof RegExp) {
+            if (!options.from.test(email.from)) {
+                return false;
+            }
+        }
+    }
+    // Check custom predicate
+    if (options.predicate) {
+        if (!options.predicate(email)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=email-utils.js.map

package/dist/utils/email-utils.js.map

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

package/dist/utils/sleep.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Pauses execution for a specified number of milliseconds.
+ * @param ms - The number of milliseconds to sleep.
+ * @returns A promise that resolves after the specified delay.
+ */
+export declare function sleep(ms: number): Promise<void>;