lsh-framework 3.1.6 → 3.1.8

package/dist/lib/ipfs-secrets-storage.js

@@ -3,6 +3,7 @@
  * Stores encrypted secrets on IPFS using Storacha (formerly web3.storage)
  */
 import * as fs from 'fs';
+import * as fsPromises from 'fs/promises';
 import * as path from 'path';
 import * as os from 'os';
 import * as crypto from 'crypto';
@@ -30,12 +31,19 @@ export class IPFSSecretsStorage {
         const lshDir = path.join(homeDir, '.lsh');
         this.cacheDir = path.join(lshDir, 'secrets-cache');
         this.metadataPath = path.join(lshDir, 'secrets-metadata.json');
+        // Initialize metadata - will be loaded on first use
+        this.metadata = {};
+    }
+    /**
+     * Initialize async parts
+     */
+    async initialize() {
         // Ensure directories exist
         if (!fs.existsSync(this.cacheDir)) {
             fs.mkdirSync(this.cacheDir, { recursive: true });
         }
         // Load metadata
-        this.metadata = this.loadMetadata();
+        this.metadata = await this.loadMetadataAsync();
     }
     /**
      * Store secrets on IPFS
@@ -59,7 +67,7 @@ export class IPFSSecretsStorage {
                 encrypted: true,
             };
             this.metadata[this.getMetadataKey(gitRepo, environment)] = metadata;
-            this.saveMetadata();
+            await this.saveMetadata();
             logger.info(`📦 Stored ${secrets.length} secrets on IPFS: ${cid}`);
             logger.info(`   Environment: ${environment}`);
             if (gitRepo) {
@@ -132,7 +140,7 @@ export class IPFSSecretsStorage {
                                 encrypted: true,
                             };
                             this.metadata[metadataKey] = metadata;
-                            this.saveMetadata();
+                            await this.saveMetadata();
                         }
                     }
                 }
@@ -162,7 +170,7 @@ export class IPFSSecretsStorage {
                                 timestamp: new Date().toISOString(),
                             };
                             this.metadata[metadataKey] = metadata;
-                            this.saveMetadata();
+                            await this.saveMetadata();
                         }
                     }
                 }
@@ -236,20 +244,24 @@ export class IPFSSecretsStorage {
         return Object.values(this.metadata);
     }
     /**
-     * Delete secrets for environment
+     * Delete local cached secrets for an environment
      */
-    async delete(environment, gitRepo) {
+    async deleteLocal(environment, gitRepo) {
         const metadataKey = this.getMetadataKey(gitRepo, environment);
         const metadata = this.metadata[metadataKey];
         if (metadata) {
             // Delete local cache
             const cachePath = path.join(this.cacheDir, `${metadata.cid}.encrypted`);
-            if (fs.existsSync(cachePath)) {
-                fs.unlinkSync(cachePath);
+            try {
+                await fsPromises.access(cachePath);
+                await fsPromises.unlink(cachePath);
+            }
+            catch {
+                // File doesn't exist, which is fine
             }
             // Remove metadata
             delete this.metadata[metadataKey];
-            this.saveMetadata();
+            await this.saveMetadata();
             logger.info(`🗑️  Deleted secrets for ${environment}`);
         }
     }
@@ -310,7 +322,10 @@ export class IPFSSecretsStorage {
      */
     async storeLocally(cid, encryptedData, _environment) {
         const cachePath = path.join(this.cacheDir, `${cid}.encrypted`);
-        fs.writeFileSync(cachePath, encryptedData, 'utf8');
+        // Ensure parent directory exists
+        await fsPromises.mkdir(this.cacheDir, { recursive: true });
+        // Write file without locking (simpler approach)
+        await fsPromises.writeFile(cachePath, encryptedData, 'utf8');
         logger.debug(`Cached secrets locally: ${cachePath}`);
     }
     /**
@@ -318,10 +333,14 @@ export class IPFSSecretsStorage {
      */
     async loadLocally(cid) {
         const cachePath = path.join(this.cacheDir, `${cid}.encrypted`);
-        if (!fs.existsSync(cachePath)) {
+        try {
+            await fsPromises.access(cachePath);
+        }
+        catch {
             return null;
         }
-        return fs.readFileSync(cachePath, 'utf8');
+        // Simple read without locking for now
+        return await fsPromises.readFile(cachePath, 'utf8');
     }
     /**
      * Get metadata key for environment
@@ -344,10 +363,31 @@ export class IPFSSecretsStorage {
             return {};
         }
     }
+    /**
+     * Load metadata from disk asynchronously
+     */
+    async loadMetadataAsync() {
+        try {
+            await fsPromises.access(this.metadataPath);
+        }
+        catch {
+            return {};
+        }
+        try {
+            const content = await fsPromises.readFile(this.metadataPath, 'utf8');
+            return JSON.parse(content);
+        }
+        catch {
+            return {};
+        }
+    }
     /**
      * Save metadata to disk
      */
-    saveMetadata() {
-        fs.writeFileSync(this.metadataPath, JSON.stringify(this.metadata, null, 2), 'utf8');
+    async saveMetadata() {
+        // Ensure parent directory exists
+        const parentDir = path.dirname(this.metadataPath);
+        await fsPromises.mkdir(parentDir, { recursive: true });
+        await fsPromises.writeFile(this.metadataPath, JSON.stringify(this.metadata, null, 2), 'utf8');
     }
 }

package/dist/lib/lsh-error.js

@@ -0,0 +1,406 @@
+/**
+ * LSH Error Handling Utilities
+ *
+ * Provides standardized error handling across the LSH codebase:
+ * - LSHError class for structured errors with codes and context
+ * - Error extraction utilities for safe error handling in catch blocks
+ * - Error code constants for consistent error identification
+ *
+ * @example
+ * ```typescript
+ * import { LSHError, ErrorCodes, extractErrorMessage } from './lsh-error.js';
+ *
+ * // Throw a structured error
+ * throw new LSHError(
+ *   ErrorCodes.SECRETS_ENCRYPTION_FAILED,
+ *   'Failed to encrypt secret',
+ *   { secretKey: 'DATABASE_URL', teamId: 'team_123' }
+ * );
+ *
+ * // Safe error extraction in catch block
+ * try {
+ *   await doSomething();
+ * } catch (error) {
+ *   console.error(extractErrorMessage(error));
+ * }
+ * ```
+ */
+// ============================================================================
+// ERROR CODES
+// ============================================================================
+/**
+ * Standardized error codes for LSH operations.
+ * Use these instead of magic strings for consistent error handling.
+ *
+ * Naming convention: CATEGORY_SPECIFIC_ERROR
+ * - AUTH_* : Authentication errors
+ * - SECRETS_* : Secrets management errors
+ * - DB_* : Database errors
+ * - DAEMON_* : Daemon/job errors
+ * - API_* : API server errors
+ * - CONFIG_* : Configuration errors
+ * - VALIDATION_* : Input validation errors
+ */
+export const ErrorCodes = {
+    // Authentication errors
+    AUTH_UNAUTHORIZED: 'AUTH_UNAUTHORIZED',
+    AUTH_INVALID_CREDENTIALS: 'AUTH_INVALID_CREDENTIALS',
+    AUTH_EMAIL_NOT_VERIFIED: 'AUTH_EMAIL_NOT_VERIFIED',
+    AUTH_EMAIL_ALREADY_EXISTS: 'AUTH_EMAIL_ALREADY_EXISTS',
+    AUTH_INVALID_TOKEN: 'AUTH_INVALID_TOKEN',
+    AUTH_TOKEN_EXPIRED: 'AUTH_TOKEN_EXPIRED',
+    AUTH_FORBIDDEN: 'AUTH_FORBIDDEN',
+    AUTH_INSUFFICIENT_PERMISSIONS: 'AUTH_INSUFFICIENT_PERMISSIONS',
+    // Secrets management errors
+    SECRETS_ENCRYPTION_FAILED: 'SECRETS_ENCRYPTION_FAILED',
+    SECRETS_DECRYPTION_FAILED: 'SECRETS_DECRYPTION_FAILED',
+    SECRETS_KEY_NOT_FOUND: 'SECRETS_KEY_NOT_FOUND',
+    SECRETS_PUSH_FAILED: 'SECRETS_PUSH_FAILED',
+    SECRETS_PULL_FAILED: 'SECRETS_PULL_FAILED',
+    SECRETS_ROTATION_FAILED: 'SECRETS_ROTATION_FAILED',
+    SECRETS_ENV_PARSE_FAILED: 'SECRETS_ENV_PARSE_FAILED',
+    SECRETS_NOT_FOUND: 'SECRETS_NOT_FOUND',
+    // Database errors
+    DB_CONNECTION_FAILED: 'DB_CONNECTION_FAILED',
+    DB_QUERY_FAILED: 'DB_QUERY_FAILED',
+    DB_NOT_FOUND: 'DB_NOT_FOUND',
+    DB_ALREADY_EXISTS: 'DB_ALREADY_EXISTS',
+    DB_CONSTRAINT_VIOLATION: 'DB_CONSTRAINT_VIOLATION',
+    DB_TIMEOUT: 'DB_TIMEOUT',
+    // Daemon errors
+    DAEMON_NOT_RUNNING: 'DAEMON_NOT_RUNNING',
+    DAEMON_ALREADY_RUNNING: 'DAEMON_ALREADY_RUNNING',
+    DAEMON_START_FAILED: 'DAEMON_START_FAILED',
+    DAEMON_STOP_FAILED: 'DAEMON_STOP_FAILED',
+    DAEMON_CONNECTION_FAILED: 'DAEMON_CONNECTION_FAILED',
+    DAEMON_IPC_ERROR: 'DAEMON_IPC_ERROR',
+    // Job errors
+    JOB_NOT_FOUND: 'JOB_NOT_FOUND',
+    JOB_ALREADY_RUNNING: 'JOB_ALREADY_RUNNING',
+    JOB_START_FAILED: 'JOB_START_FAILED',
+    JOB_STOP_FAILED: 'JOB_STOP_FAILED',
+    JOB_TIMEOUT: 'JOB_TIMEOUT',
+    JOB_INVALID_SCHEDULE: 'JOB_INVALID_SCHEDULE',
+    // API errors
+    API_NOT_CONFIGURED: 'API_NOT_CONFIGURED',
+    API_INVALID_REQUEST: 'API_INVALID_REQUEST',
+    API_RATE_LIMITED: 'API_RATE_LIMITED',
+    API_INTERNAL_ERROR: 'API_INTERNAL_ERROR',
+    API_WEBHOOK_VERIFICATION_FAILED: 'API_WEBHOOK_VERIFICATION_FAILED',
+    // Configuration errors
+    CONFIG_MISSING_ENV_VAR: 'CONFIG_MISSING_ENV_VAR',
+    CONFIG_INVALID_VALUE: 'CONFIG_INVALID_VALUE',
+    CONFIG_FILE_NOT_FOUND: 'CONFIG_FILE_NOT_FOUND',
+    CONFIG_PARSE_ERROR: 'CONFIG_PARSE_ERROR',
+    // Validation errors
+    VALIDATION_REQUIRED_FIELD: 'VALIDATION_REQUIRED_FIELD',
+    VALIDATION_INVALID_FORMAT: 'VALIDATION_INVALID_FORMAT',
+    VALIDATION_OUT_OF_RANGE: 'VALIDATION_OUT_OF_RANGE',
+    VALIDATION_COMMAND_INJECTION: 'VALIDATION_COMMAND_INJECTION',
+    // Billing errors
+    BILLING_TIER_LIMIT_EXCEEDED: 'BILLING_TIER_LIMIT_EXCEEDED',
+    BILLING_SUBSCRIPTION_REQUIRED: 'BILLING_SUBSCRIPTION_REQUIRED',
+    BILLING_PAYMENT_REQUIRED: 'BILLING_PAYMENT_REQUIRED',
+    BILLING_STRIPE_ERROR: 'BILLING_STRIPE_ERROR',
+    // Resource errors
+    RESOURCE_NOT_FOUND: 'RESOURCE_NOT_FOUND',
+    RESOURCE_ALREADY_EXISTS: 'RESOURCE_ALREADY_EXISTS',
+    RESOURCE_CONFLICT: 'RESOURCE_CONFLICT',
+    // General errors
+    INTERNAL_ERROR: 'INTERNAL_ERROR',
+    NOT_IMPLEMENTED: 'NOT_IMPLEMENTED',
+    SERVICE_UNAVAILABLE: 'SERVICE_UNAVAILABLE',
+};
+// ============================================================================
+// LSH ERROR CLASS
+// ============================================================================
+/**
+ * Structured error class for LSH operations.
+ *
+ * Features:
+ * - Error code for programmatic handling
+ * - Context object for debugging information
+ * - HTTP status code mapping for API responses
+ * - Stack trace preservation
+ * - Serialization support
+ *
+ * @example
+ * ```typescript
+ * throw new LSHError(
+ *   ErrorCodes.SECRETS_NOT_FOUND,
+ *   'Secret not found',
+ *   { secretId: 'secret_123', environment: 'production' }
+ * );
+ * ```
+ */
+export class LSHError extends Error {
+    /** Error code for programmatic handling */
+    code;
+    /** Additional context for debugging */
+    context;
+    /** HTTP status code for API responses */
+    statusCode;
+    /** Timestamp when error occurred */
+    timestamp;
+    constructor(code, message, context, statusCode) {
+        super(message);
+        this.name = 'LSHError';
+        this.code = code;
+        this.context = context;
+        this.statusCode = statusCode ?? getDefaultStatusCode(code);
+        this.timestamp = new Date();
+        // Maintain proper stack trace in V8 environments
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, LSHError);
+        }
+    }
+    /**
+     * Serialize error for logging or API response.
+     */
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            context: this.context,
+            statusCode: this.statusCode,
+            timestamp: this.timestamp.toISOString(),
+            stack: this.stack,
+        };
+    }
+    /**
+     * Create user-friendly string representation.
+     */
+    toString() {
+        const contextStr = this.context ? ` (${JSON.stringify(this.context)})` : '';
+        return `[${this.code}] ${this.message}${contextStr}`;
+    }
+}
+// ============================================================================
+// ERROR UTILITIES
+// ============================================================================
+/**
+ * Safely extract error message from unknown error type.
+ * Use this in catch blocks instead of (error as Error).message.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   console.error('Failed:', extractErrorMessage(error));
+ * }
+ * ```
+ */
+export function extractErrorMessage(error) {
+    if (error instanceof LSHError) {
+        return error.toString();
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    if (typeof error === 'string') {
+        return error;
+    }
+    if (error && typeof error === 'object' && 'message' in error) {
+        return String(error.message);
+    }
+    return String(error);
+}
+/**
+ * Safely extract error details for logging.
+ * Returns structured object with message, stack, and code if available.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await riskyOperation();
+ * } catch (error) {
+ *   logger.error('Operation failed', extractErrorDetails(error));
+ * }
+ * ```
+ */
+export function extractErrorDetails(error) {
+    if (error instanceof LSHError) {
+        return {
+            message: error.message,
+            stack: error.stack,
+            code: error.code,
+            context: error.context,
+        };
+    }
+    if (error instanceof Error) {
+        return {
+            message: error.message,
+            stack: error.stack,
+            code: error.code,
+        };
+    }
+    return {
+        message: extractErrorMessage(error),
+    };
+}
+/**
+ * Check if an error is an LSHError with a specific code.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await getSecret();
+ * } catch (error) {
+ *   if (isLSHError(error, ErrorCodes.SECRETS_NOT_FOUND)) {
+ *     // Handle not found case
+ *   }
+ *   throw error;
+ * }
+ * ```
+ */
+export function isLSHError(error, code) {
+    if (!(error instanceof LSHError))
+        return false;
+    if (code && error.code !== code)
+        return false;
+    return true;
+}
+/**
+ * Wrap an unknown error as an LSHError.
+ * Useful for ensuring consistent error types in APIs.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await externalApi.call();
+ * } catch (error) {
+ *   throw wrapAsLSHError(error, ErrorCodes.API_INTERNAL_ERROR);
+ * }
+ * ```
+ */
+export function wrapAsLSHError(error, code = ErrorCodes.INTERNAL_ERROR, context) {
+    if (error instanceof LSHError) {
+        // Add additional context if provided
+        if (context) {
+            return new LSHError(error.code, error.message, {
+                ...error.context,
+                ...context,
+            });
+        }
+        return error;
+    }
+    const message = extractErrorMessage(error);
+    const details = extractErrorDetails(error);
+    return new LSHError(code, message, {
+        ...context,
+        originalStack: details.stack,
+        originalCode: details.code,
+    });
+}
+// ============================================================================
+// HTTP STATUS CODE MAPPING
+// ============================================================================
+/**
+ * Get default HTTP status code for an error code.
+ * Used by LSHError constructor and API responses.
+ */
+function getDefaultStatusCode(code) {
+    // 400 Bad Request
+    if (code.startsWith('VALIDATION_'))
+        return 400;
+    if (code === ErrorCodes.API_INVALID_REQUEST)
+        return 400;
+    if (code === ErrorCodes.CONFIG_INVALID_VALUE)
+        return 400;
+    // 401 Unauthorized
+    if (code === ErrorCodes.AUTH_UNAUTHORIZED)
+        return 401;
+    if (code === ErrorCodes.AUTH_INVALID_CREDENTIALS)
+        return 401;
+    if (code === ErrorCodes.AUTH_INVALID_TOKEN)
+        return 401;
+    if (code === ErrorCodes.AUTH_TOKEN_EXPIRED)
+        return 401;
+    // 402 Payment Required
+    if (code === ErrorCodes.BILLING_PAYMENT_REQUIRED)
+        return 402;
+    if (code === ErrorCodes.BILLING_SUBSCRIPTION_REQUIRED)
+        return 402;
+    // 403 Forbidden
+    if (code === ErrorCodes.AUTH_FORBIDDEN)
+        return 403;
+    if (code === ErrorCodes.AUTH_INSUFFICIENT_PERMISSIONS)
+        return 403;
+    if (code === ErrorCodes.AUTH_EMAIL_NOT_VERIFIED)
+        return 403;
+    // 404 Not Found
+    if (code.endsWith('_NOT_FOUND'))
+        return 404;
+    if (code === ErrorCodes.DB_NOT_FOUND)
+        return 404;
+    // 409 Conflict
+    if (code.endsWith('_ALREADY_EXISTS'))
+        return 409;
+    if (code === ErrorCodes.RESOURCE_CONFLICT)
+        return 409;
+    if (code === ErrorCodes.DB_CONSTRAINT_VIOLATION)
+        return 409;
+    // 429 Too Many Requests
+    if (code === ErrorCodes.API_RATE_LIMITED)
+        return 429;
+    if (code === ErrorCodes.BILLING_TIER_LIMIT_EXCEEDED)
+        return 429;
+    // 501 Not Implemented
+    if (code === ErrorCodes.NOT_IMPLEMENTED)
+        return 501;
+    // 503 Service Unavailable
+    if (code === ErrorCodes.SERVICE_UNAVAILABLE)
+        return 503;
+    if (code === ErrorCodes.DB_CONNECTION_FAILED)
+        return 503;
+    // 504 Gateway Timeout
+    if (code === ErrorCodes.DB_TIMEOUT)
+        return 504;
+    if (code === ErrorCodes.JOB_TIMEOUT)
+        return 504;
+    // Default to 500 Internal Server Error
+    return 500;
+}
+// ============================================================================
+// FACTORY FUNCTIONS
+// ============================================================================
+/**
+ * Create a not found error.
+ */
+export function notFoundError(resource, id, context) {
+    const message = id ? `${resource} '${id}' not found` : `${resource} not found`;
+    return new LSHError(ErrorCodes.RESOURCE_NOT_FOUND, message, { resource, id, ...context });
+}
+/**
+ * Create an already exists error.
+ */
+export function alreadyExistsError(resource, identifier, context) {
+    const message = identifier
+        ? `${resource} '${identifier}' already exists`
+        : `${resource} already exists`;
+    return new LSHError(ErrorCodes.RESOURCE_ALREADY_EXISTS, message, {
+        resource,
+        identifier,
+        ...context,
+    });
+}
+/**
+ * Create a validation error.
+ */
+export function validationError(message, field, context) {
+    return new LSHError(ErrorCodes.VALIDATION_REQUIRED_FIELD, message, { field, ...context });
+}
+/**
+ * Create an unauthorized error.
+ */
+export function unauthorizedError(message = 'Unauthorized', context) {
+    return new LSHError(ErrorCodes.AUTH_UNAUTHORIZED, message, context);
+}
+/**
+ * Create a forbidden error.
+ */
+export function forbiddenError(message = 'Insufficient permissions', context) {
+    return new LSHError(ErrorCodes.AUTH_FORBIDDEN, message, context);
+}

package/dist/lib/saas-auth.js

@@ -378,7 +378,29 @@ export class AuthService {
         await this.supabase.from('users').update({ password_hash: newHash }).eq('id', userId);
     }
     /**
-     * Map database user to User type
+     * Transform Supabase user record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `email_verified` → `emailVerified` (boolean)
+     * - `email_verification_token` → `emailVerificationToken` (nullable string)
+     * - `email_verification_expires_at` → `emailVerificationExpiresAt` (nullable Date)
+     * - `password_hash` → `passwordHash` (nullable, null for OAuth-only users)
+     * - `oauth_provider` → `oauthProvider` ('google' | 'github' | 'microsoft' | null)
+     * - `oauth_provider_id` → `oauthProviderId` (nullable)
+     * - `first_name` → `firstName` (nullable)
+     * - `last_name` → `lastName` (nullable)
+     * - `avatar_url` → `avatarUrl` (nullable)
+     * - `last_login_at` → `lastLoginAt` (nullable Date)
+     * - `last_login_ip` → `lastLoginIp` (nullable)
+     * - `deleted_at` → `deletedAt` (nullable Date, for soft delete)
+     *
+     * Security note: passwordHash is included in domain model but should
+     * never be exposed in API responses.
+     *
+     * @param dbUser - Supabase record from 'users' table
+     * @returns Domain User object
+     * @see DbUserRecord in database-types.ts for input shape
+     * @see User in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbUserToUser(dbUser) {
@@ -404,7 +426,22 @@ export class AuthService {
         };
     }
     /**
-     * Map database organization to Organization type
+     * Transform Supabase organization record to domain model.
+     *
+     * Used when fetching user's organizations via the organization_members join.
+     * Identical mapping logic to OrganizationService.mapDbOrgToOrg().
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `stripe_customer_id` → `stripeCustomerId`
+     * - `subscription_tier` → `subscriptionTier` (SubscriptionTier type)
+     * - `subscription_status` → `subscriptionStatus` (SubscriptionStatus type)
+     * - `subscription_expires_at` → `subscriptionExpiresAt` (nullable Date)
+     * - `deleted_at` → `deletedAt` (nullable Date)
+     *
+     * @param dbOrg - Supabase record from 'organizations' table (via join)
+     * @returns Domain Organization object
+     * @see DbOrganizationRecord in database-types.ts for input shape
+     * @see Organization in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbOrgToOrg(dbOrg) {