@sparkvault/sdk 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,658 @@
+/**
+ * SparkVault SDK Configuration
+ */
+interface SparkVaultConfig {
+    /** Account ID for Identity operations */
+    accountId: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /**
+     * Preload Identity configuration on SDK init (default: true).
+     * When enabled, the /config call is made immediately when the SDK initializes,
+     * so verify() opens instantly without waiting for the config fetch.
+     * Set to false to defer config loading until verify() is called.
+     */
+    preloadConfig?: boolean;
+}
+interface ResolvedConfig {
+    accountId: string;
+    timeout: number;
+    apiBaseUrl: string;
+    identityBaseUrl: string;
+    preloadConfig: boolean;
+}
+
+/**
+ * Identity Module Types
+ */
+type AuthMethod = 'passkey' | 'totp_email' | 'totp_sms' | 'totp_voice' | 'magic_link' | 'sparklink' | 'google' | 'apple' | 'microsoft' | 'github' | 'facebook' | 'linkedin' | 'social_google' | 'social_apple' | 'social_microsoft' | 'social_github' | 'social_facebook' | 'social_linkedin';
+type Theme = 'light' | 'dark';
+interface VerifyOptions {
+    /** Pre-fill email address (mutually exclusive with phone) */
+    email?: string;
+    /** Pre-fill phone number in E.164 format, e.g. "+14155551234" (mutually exclusive with email) */
+    phone?: string;
+    /** Override backdrop blur setting from app config */
+    backdropBlur?: boolean;
+    /** Called when user cancels */
+    onCancel?: () => void;
+    /** Called when verification completes (before promise resolves) */
+    onSuccess?: (result: VerifyResult) => void;
+    /** Called on error (before promise rejects) */
+    onError?: (error: Error) => void;
+}
+interface RenderOptions extends VerifyOptions {
+    /** Target element to render inline UI into (required) */
+    target: HTMLElement;
+    /** Show header with branding and close button (default: true) */
+    showHeader?: boolean;
+    /** Show close button in header (default: true, requires showHeader) */
+    showCloseButton?: boolean;
+    /** Show footer with SparkVault branding (default: true) */
+    showFooter?: boolean;
+}
+interface VerifyResult {
+    /** Signed JWT token */
+    token: string;
+    /** Verified identity (email or phone) */
+    identity: string;
+    /** Type of identity verified */
+    identityType: 'email' | 'phone';
+}
+interface TokenClaims {
+    /** Issuer */
+    iss: string;
+    /** Subject (hashed identity) */
+    sub: string;
+    /** Audience (account ID for simple tokens, client ID for OIDC) */
+    aud: string;
+    /** Expiry (Unix seconds) */
+    exp: number;
+    /** Issued at (Unix seconds) */
+    iat: number;
+    /** Unique token ID for replay protection */
+    jti?: string;
+    /** Verified identity (email or phone) */
+    identity: string;
+    /** Identity type */
+    identity_type: 'email' | 'phone';
+    /** Verification timestamp (Unix seconds) */
+    verified_at: number;
+    /** Authentication method used */
+    method: string;
+}
+
+/**
+ * Identity Module
+ *
+ * Provides identity verification through a DOM-based modal interface.
+ * Supports passkey, TOTP, magic link, and social authentication.
+ */
+
+declare class IdentityModule {
+    private readonly config;
+    private readonly api;
+    private renderer;
+    constructor(config: ResolvedConfig);
+    /**
+     * Open the identity verification modal (popup).
+     * Returns when user successfully verifies their identity.
+     *
+     * @example
+     * const result = await sv.identity.pop({
+     *   email: 'user@example.com'
+     * });
+     * console.log(result.token, result.identity, result.identityType);
+     */
+    pop(options?: VerifyOptions): Promise<VerifyResult>;
+    /**
+     * Render identity verification inline within a target element.
+     * Unlike verify() which opens a modal popup, this embeds the UI
+     * directly into the specified element.
+     *
+     * @example
+     * // Render in a div
+     * const result = await sv.identity.render({
+     *   target: document.getElementById('auth-container'),
+     *   email: 'user@example.com'
+     * });
+     *
+     * @example
+     * // Render in a custom dialog without header/footer
+     * const result = await sv.identity.render({
+     *   target: dialogContentElement,
+     *   showHeader: false,
+     *   showFooter: false
+     * });
+     */
+    render(options: RenderOptions): Promise<VerifyResult>;
+    /**
+     * Verify and decode an identity token.
+     * Validates the token structure, expiry, and issuer.
+     *
+     * Note: For production use, verify the Ed25519 signature server-side
+     * using the JWKS endpoint.
+     *
+     * @example
+     * const claims = await sv.identity.verifyToken(token);
+     * console.log(claims.identity, claims.identity_type, claims.method);
+     */
+    verifyToken(token: string): Promise<TokenClaims>;
+    /**
+     * Close the identity modal if open.
+     */
+    close(): void;
+    /**
+     * @deprecated Use `pop()` instead. Will be removed in v2.0.
+     */
+    verify(options?: VerifyOptions): Promise<VerifyResult>;
+}
+
+/**
+ * Retry Utility with Exponential Backoff
+ *
+ * Per CLAUDE.md §7: Retries allowed only if idempotent, MUST use exponential backoff.
+ */
+interface RetryOptions {
+    /** Maximum number of retry attempts (default: 3) */
+    maxAttempts?: number;
+    /** Base delay in milliseconds (default: 200) */
+    baseDelayMs?: number;
+    /** Maximum delay in milliseconds (default: 5000) */
+    maxDelayMs?: number;
+    /** Jitter factor 0-1 to randomize delays (default: 0.2) */
+    jitterFactor?: number;
+    /** Function to determine if error is retryable (default: checks for network/timeout/5xx) */
+    isRetryable?: (error: unknown) => boolean;
+}
+
+/**
+ * SparkVault SDK HTTP Client
+ */
+
+interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout?: number;
+    /** Enable automatic retry with exponential backoff (per CLAUDE.md §7) */
+    retry?: boolean | RetryOptions;
+}
+interface ApiResponse<T = unknown> {
+    data: T;
+    status: number;
+    headers: Headers;
+}
+declare class HttpClient {
+    private readonly config;
+    constructor(config: ResolvedConfig);
+    request<T = unknown>(path: string, options?: RequestOptions): Promise<ApiResponse<T>>;
+    /**
+     * Execute the actual HTTP request (internal implementation)
+     */
+    private executeRequest;
+    /**
+     * Check if an error is safe to retry
+     * Per CLAUDE.md §7: Only retry on transient/network errors, not client errors
+     */
+    private isRetryableError;
+    private parseResponse;
+    private createErrorFromResponse;
+    get<T = unknown>(path: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResponse<T>>;
+    post<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>>;
+    put<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>>;
+    patch<T = unknown>(path: string, body?: unknown, options?: Omit<RequestOptions, 'method'>): Promise<ApiResponse<T>>;
+    delete<T = unknown>(path: string, options?: Omit<RequestOptions, 'method' | 'body'>): Promise<ApiResponse<T>>;
+    /**
+     * Request raw binary data (e.g., file downloads).
+     * Returns a Blob instead of parsed JSON.
+     */
+    requestRaw(path: string, options?: RequestOptions): Promise<Blob>;
+    /**
+     * Execute the actual raw HTTP request (internal implementation)
+     */
+    private executeRequestRaw;
+}
+
+/**
+ * Sparks Module Types
+ */
+interface CreateSparkOptions {
+    /** Secret payload to encrypt */
+    payload: string | Uint8Array;
+    /** Time-to-live in seconds (default: 3600) */
+    ttl?: number;
+    /** Maximum number of reads before destruction (default: 1) */
+    maxReads?: number;
+    /** Optional password protection */
+    password?: string;
+    /** Optional name/label for the spark */
+    name?: string;
+}
+interface Spark {
+    /** Spark ID */
+    id: string;
+    /** Direct URL to read the spark */
+    url: string;
+    /** Expiry timestamp (Unix seconds) */
+    expiresAt: number;
+    /** Maximum reads remaining */
+    maxReads: number;
+    /** Name/label if provided */
+    name?: string;
+}
+interface SparkPayload {
+    /** Decrypted data */
+    data: string | Uint8Array;
+    /** When the spark was read (Unix seconds) */
+    readAt: number;
+    /** Whether the spark was destroyed after reading */
+    burned: boolean;
+    /** Reads remaining (0 if burned) */
+    readsRemaining: number;
+}
+
+/**
+ * Sparks Module
+ *
+ * Create and read ephemeral encrypted secrets.
+ * Sparks are destroyed after being read (burn-on-read).
+ */
+
+declare class SparksModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Create an ephemeral encrypted secret.
+     *
+     * @example
+     * const spark = await sv.sparks.create({
+     *   payload: 'my secret data',
+     *   ttl: 3600,
+     *   maxReads: 1
+     * });
+     * console.log(spark.url);
+     */
+    create(options: CreateSparkOptions): Promise<Spark>;
+    /**
+     * Read and burn a spark.
+     * The spark is destroyed after the configured number of reads.
+     *
+     * @example
+     * const payload = await sv.sparks.read('spk_abc123');
+     * console.log(payload.data);
+     */
+    read(id: string, password?: string): Promise<SparkPayload>;
+    private validateCreateOptions;
+    private encodePayload;
+    private decodePayload;
+}
+
+/**
+ * Vaults Module Types
+ */
+interface CreateVaultOptions {
+    /** Vault name */
+    name: string;
+    /** Store VMK server-side (less secure, more convenient) */
+    hostedVmk?: boolean;
+}
+interface Vault {
+    /** Vault ID */
+    id: string;
+    /** Vault name */
+    name: string;
+    /** Vault Master Key (24 chars) - STORE SECURELY! */
+    vmk: string;
+    /** Creation timestamp (Unix seconds) */
+    createdAt: number;
+    /** Whether VMK is hosted server-side */
+    hostedVmk: boolean;
+}
+interface UnsealedVault {
+    /** Vault ID */
+    id: string;
+    /** Vault name */
+    name: string;
+    /** Vault Access Token (short-lived session) */
+    vatToken: string;
+    /** VAT expiry timestamp (Unix seconds) */
+    expiresAt: number;
+    /** Number of ingots in vault */
+    ingotCount: number;
+    /** Total storage used in bytes */
+    storageBytes: number;
+}
+interface VaultSummary {
+    /** Vault ID */
+    id: string;
+    /** Vault name */
+    name: string;
+    /** Creation timestamp (Unix seconds) */
+    createdAt: number;
+    /** Number of ingots */
+    ingotCount: number;
+    /** Total storage used in bytes */
+    storageBytes: number;
+    /** Whether VMK is hosted server-side */
+    hostedVmk: boolean;
+}
+interface Ingot {
+    /** Ingot ID */
+    id: string;
+    /** Ingot name */
+    name: string;
+    /** Content type (MIME) */
+    contentType: string;
+    /** Size in bytes */
+    size: number;
+    /** Creation timestamp (Unix seconds) */
+    createdAt: number;
+    /** Ingot type: 'standard' or 'structured' */
+    type: 'standard' | 'structured';
+}
+interface UploadIngotOptions {
+    /** File to upload */
+    file: File | Blob;
+    /** Optional name (defaults to file name) */
+    name?: string;
+    /** Content type (auto-detected if not provided) */
+    contentType?: string;
+}
+
+/**
+ * Vaults Module
+ *
+ * Create and manage encrypted vaults and ingots.
+ * Uses Triple Zero-Trust encryption (SVMK + AMK + VMK).
+ */
+
+declare class VaultsModule {
+    private readonly http;
+    constructor(_config: ResolvedConfig, http: HttpClient);
+    /**
+     * Create a new encrypted vault.
+     * IMPORTANT: Store the VMK securely - it cannot be recovered!
+     *
+     * @example
+     * const vault = await sv.vaults.create({ name: 'My Vault' });
+     * console.log('Save this VMK:', vault.vmk);
+     */
+    create(options: CreateVaultOptions): Promise<Vault>;
+    /**
+     * Unseal a vault to access its contents.
+     * Returns a short-lived Vault Access Token (VAT).
+     *
+     * @example
+     * const unsealed = await sv.vaults.unseal('vlt_abc', vmk);
+     * console.log('Ingots:', unsealed.ingotCount);
+     */
+    unseal(vaultId: string, vmk: string): Promise<UnsealedVault>;
+    /**
+     * List all vaults for the account.
+     *
+     * @example
+     * const vaults = await sv.vaults.list();
+     * vaults.forEach(v => console.log(v.name));
+     */
+    list(): Promise<VaultSummary[]>;
+    /**
+     * Delete a vault and all its ingots.
+     * This action is irreversible!
+     *
+     * @example
+     * await sv.vaults.delete('vlt_abc', vmk);
+     */
+    delete(vaultId: string, vmk: string): Promise<void>;
+    /**
+     * Upload a file as an ingot to an unsealed vault.
+     *
+     * @example
+     * const ingot = await sv.vaults.uploadIngot(unsealed, {
+     *   file: myFile,
+     *   name: 'document.pdf'
+     * });
+     */
+    uploadIngot(vault: UnsealedVault, options: UploadIngotOptions): Promise<Ingot>;
+    /**
+     * Download an ingot from an unsealed vault.
+     *
+     * @example
+     * const blob = await sv.vaults.downloadIngot(unsealed, 'ing_abc');
+     * const url = URL.createObjectURL(blob);
+     */
+    downloadIngot(vault: UnsealedVault, ingotId: string): Promise<Blob>;
+    /**
+     * List all ingots in an unsealed vault.
+     *
+     * @example
+     * const ingots = await sv.vaults.listIngots(unsealed);
+     * ingots.forEach(i => console.log(i.name, i.size));
+     */
+    listIngots(vault: UnsealedVault): Promise<Ingot[]>;
+    /**
+     * Delete an ingot from an unsealed vault.
+     *
+     * @example
+     * await sv.vaults.deleteIngot(unsealed, 'ing_abc');
+     */
+    deleteIngot(vault: UnsealedVault, ingotId: string): Promise<void>;
+    private validateCreateOptions;
+    private validateUploadOptions;
+}
+
+/**
+ * RNG Module Types
+ */
+type RNGFormat = 'hex' | 'base64' | 'base64url' | 'alphanumeric' | 'alphanumeric-mixed' | 'password' | 'numeric' | 'uuid' | 'bytes';
+interface GenerateOptions {
+    /** Number of bytes to generate (1-1024) */
+    bytes: number;
+    /** Output format (default: 'base64url') */
+    format?: RNGFormat;
+}
+interface RandomResult {
+    /** Generated random value */
+    value: string | number[];
+    /** Number of bytes generated */
+    bytes: number;
+    /** Format used */
+    format: RNGFormat;
+    /** Reference ID for billing/audit */
+    referenceId: string;
+}
+
+/**
+ * RNG Module
+ *
+ * Generate cryptographically secure random numbers.
+ * Uses hybrid entropy from AWS KMS HSM + local CSPRNG.
+ */
+
+declare class RNGModule {
+    private readonly http;
+    constructor(http: HttpClient);
+    /**
+     * Generate cryptographically secure random bytes.
+     *
+     * @example
+     * const result = await sv.rng.generate({ bytes: 32, format: 'hex' });
+     * console.log(result.value);
+     */
+    generate(options: GenerateOptions): Promise<RandomResult>;
+    /**
+     * Generate a random UUID v4.
+     *
+     * @example
+     * const uuid = await sv.rng.uuid();
+     * console.log(uuid); // 'f47ac10b-58cc-4372-a567-0e02b2c3d479'
+     */
+    uuid(): Promise<string>;
+    /**
+     * Generate a random hex string.
+     *
+     * @example
+     * const hex = await sv.rng.hex(16);
+     * console.log(hex); // '1a2b3c4d5e6f7890...'
+     */
+    hex(bytes: number): Promise<string>;
+    /**
+     * Generate a random alphanumeric string.
+     *
+     * @example
+     * const code = await sv.rng.alphanumeric(8);
+     * console.log(code); // 'A1B2C3D4'
+     */
+    alphanumeric(bytes: number): Promise<string>;
+    /**
+     * Generate a random password with special characters.
+     *
+     * @example
+     * const password = await sv.rng.password(16);
+     * console.log(password); // 'aB3$xY7!mN9@pQ2#'
+     */
+    password(bytes: number): Promise<string>;
+    private validateOptions;
+}
+
+/**
+ * SparkVault Debug Logger
+ *
+ * Conditional logging that respects debug mode setting.
+ * When debug is enabled, logs detailed information to console.
+ * When disabled (default), only fatal errors are logged.
+ */
+/**
+ * Enable or disable debug logging
+ */
+declare function setDebugMode(enabled: boolean): void;
+/**
+ * Logger object for convenient access
+ */
+declare const logger: {
+    /**
+     * Debug level - verbose details for troubleshooting
+     */
+    debug: (message: string, ...args: unknown[]) => void;
+    /**
+     * Info level - general information
+     */
+    info: (message: string, ...args: unknown[]) => void;
+    /**
+     * Warn level - warnings that don't prevent operation
+     */
+    warn: (message: string, ...args: unknown[]) => void;
+    /**
+     * Error level - always logged regardless of debug mode
+     */
+    error: (message: string, ...args: unknown[]) => void;
+    /**
+     * Group related logs together (only in debug mode)
+     */
+    group: (label: string) => void;
+    /**
+     * End a log group
+     */
+    groupEnd: () => void;
+};
+
+/**
+ * SparkVault SDK Error Types
+ */
+declare class SparkVaultError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+}
+declare class AuthenticationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class AuthorizationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class ValidationError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class NetworkError extends SparkVaultError {
+    constructor(message: string, details?: Record<string, unknown>);
+}
+declare class TimeoutError extends SparkVaultError {
+    constructor(message?: string);
+}
+declare class UserCancelledError extends SparkVaultError {
+    constructor(message?: string);
+}
+declare class PopupBlockedError extends SparkVaultError {
+    constructor();
+}
+
+/**
+ * SparkVault JavaScript SDK
+ *
+ * A unified SDK for Identity, Sparks, Vaults, and RNG.
+ *
+ * @example Auto-Init (Zero-Config)
+ * ```html
+ * <script
+ *   async
+ *   src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"
+ *   data-account-id="acc_your_account"
+ *   data-attach-selector=".js-sparkvault-auth"
+ *   data-success-url="https://example.com/auth/verify-token"
+ *   data-debug="true"
+ * ></script>
+ *
+ * <button class="js-sparkvault-auth">Login with SparkVault</button>
+ * ```
+ *
+ * @example Manual Init
+ * ```html
+ * <script src="https://cdn.sparkvault.com/sdk/v1/sparkvault.js"></script>
+ * <script>
+ *   const sv = SparkVault.init({
+ *     accountId: 'acc_your_account'
+ *   });
+ *
+ *   // Open identity verification modal
+ *   const result = await sv.identity.pop();
+ *   console.log(result.identity, result.identityType);
+ * </script>
+ * ```
+ */
+
+declare class SparkVault {
+    /** Identity verification module */
+    readonly identity: IdentityModule;
+    /** Ephemeral encrypted secrets module */
+    readonly sparks: SparksModule;
+    /** Persistent encrypted storage module */
+    readonly vaults: VaultsModule;
+    /** Cryptographic random number generation module */
+    readonly rng: RNGModule;
+    private readonly config;
+    private constructor();
+    /**
+     * Initialize the SparkVault SDK.
+     *
+     * @param config - SDK configuration
+     * @returns SparkVault instance
+     *
+     * @example
+     * const sv = SparkVault.init({
+     *   accountId: 'acc_your_account'
+     * });
+     */
+    static init(config: SparkVaultConfig): SparkVault;
+    /** Get the SDK version */
+    static get version(): string;
+}
+
+declare global {
+    interface Window {
+        SparkVault: typeof SparkVault;
+    }
+}
+
+export { AuthenticationError, AuthorizationError, NetworkError, PopupBlockedError, SparkVault, SparkVaultError, TimeoutError, UserCancelledError, ValidationError, SparkVault as default, logger, setDebugMode };
+export type { AuthMethod, CreateSparkOptions, CreateVaultOptions, GenerateOptions, Ingot, RNGFormat, RandomResult, Spark, SparkPayload, SparkVaultConfig, Theme, TokenClaims, UnsealedVault, UploadIngotOptions, Vault, VaultSummary, VerifyOptions, VerifyResult };

package/dist/logger.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SparkVault Debug Logger
+ *
+ * Conditional logging that respects debug mode setting.
+ * When debug is enabled, logs detailed information to console.
+ * When disabled (default), only fatal errors are logged.
+ */
+/**
+ * Enable or disable debug logging
+ */
+export declare function setDebugMode(enabled: boolean): void;
+/**
+ * Check if debug mode is enabled
+ */
+export declare function isDebugEnabled(): boolean;
+/**
+ * Logger object for convenient access
+ */
+export declare const logger: {
+    /**
+     * Debug level - verbose details for troubleshooting
+     */
+    debug: (message: string, ...args: unknown[]) => void;
+    /**
+     * Info level - general information
+     */
+    info: (message: string, ...args: unknown[]) => void;
+    /**
+     * Warn level - warnings that don't prevent operation
+     */
+    warn: (message: string, ...args: unknown[]) => void;
+    /**
+     * Error level - always logged regardless of debug mode
+     */
+    error: (message: string, ...args: unknown[]) => void;
+    /**
+     * Group related logs together (only in debug mode)
+     */
+    group: (label: string) => void;
+    /**
+     * End a log group
+     */
+    groupEnd: () => void;
+};
+export default logger;