lsh-framework 3.1.6 → 3.1.8

package/dist/lib/saas-billing.js

@@ -154,7 +154,22 @@ export class BillingService {
         }
     }
     /**
-     * Verify webhook signature
+     * Verify Stripe webhook signature and parse event payload.
+     *
+     * In production, this should use Stripe's signature verification:
+     * ```typescript
+     * const event = stripe.webhooks.constructEvent(
+     *   payload, signature, this.stripeWebhookSecret
+     * );
+     * ```
+     *
+     * Current implementation parses JSON without verification (TODO: implement proper verification).
+     *
+     * @param payload - Raw webhook body as string
+     * @param _signature - Stripe-Signature header value (not yet used)
+     * @returns Parsed Stripe event object
+     * @throws Error if payload is not valid JSON
+     * @see https://stripe.com/docs/webhooks/signatures
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe event structure
     verifyWebhookSignature(payload, _signature) {
@@ -168,7 +183,16 @@ export class BillingService {
         }
     }
     /**
-     * Handle checkout completed
+     * Handle Stripe checkout.session.completed webhook event.
+     *
+     * Called when a customer completes checkout. The actual subscription
+     * creation is handled by the customer.subscription.created event.
+     *
+     * Extracts organization_id from session.metadata to link the checkout
+     * to the correct organization.
+     *
+     * @param session - Stripe checkout session object
+     * @see StripeCheckoutSession in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe checkout session object
     async handleCheckoutCompleted(session) {
@@ -181,7 +205,20 @@ export class BillingService {
         console.log(`Checkout completed for organization ${organizationId}`);
     }
     /**
-     * Handle subscription updated
+     * Handle Stripe customer.subscription.created/updated webhook events.
+     *
+     * Creates or updates subscription record in database and syncs tier
+     * to the organization. Key operations:
+     * 1. Extracts organization_id from subscription.metadata
+     * 2. Determines tier from price ID (maps Stripe price → 'free' | 'pro' | 'enterprise')
+     * 3. Upserts subscription record with all billing details
+     * 4. Updates organization's subscription_tier and subscription_status
+     * 5. Logs audit event
+     *
+     * Timestamps from Stripe are Unix timestamps (seconds), converted to ISO strings.
+     *
+     * @param subscription - Stripe subscription object
+     * @see StripeSubscriptionEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe subscription object
     async handleSubscriptionUpdated(subscription) {
@@ -235,7 +272,17 @@ export class BillingService {
         });
     }
     /**
-     * Handle subscription deleted
+     * Handle Stripe customer.subscription.deleted webhook event.
+     *
+     * Called when a subscription is canceled (immediate or at period end).
+     * Operations:
+     * 1. Marks subscription as 'canceled' with canceled_at timestamp
+     * 2. Downgrades organization to 'free' tier
+     * 3. Updates organization subscription_status to 'canceled'
+     * 4. Logs audit event
+     *
+     * @param subscription - Stripe subscription object
+     * @see StripeSubscriptionEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe subscription object
     async handleSubscriptionDeleted(subscription) {
@@ -268,7 +315,15 @@ export class BillingService {
         });
     }
     /**
-     * Handle invoice paid
+     * Handle Stripe invoice.paid webhook event.
+     *
+     * Records successful payment in the invoices table. Extracts organization_id
+     * from invoice.subscription_metadata (set during checkout).
+     *
+     * Amounts are in cents (e.g., 1000 = $10.00). Currency is uppercased.
+     *
+     * @param invoice - Stripe invoice object
+     * @see StripeInvoiceEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe invoice object
     async handleInvoicePaid(invoice) {
@@ -291,7 +346,16 @@ export class BillingService {
         }, { onConflict: 'stripe_invoice_id' });
     }
     /**
-     * Handle invoice payment failed
+     * Handle Stripe invoice.payment_failed webhook event.
+     *
+     * Called when payment fails (declined card, insufficient funds, etc.).
+     * Updates organization subscription_status to 'past_due' and logs audit event.
+     *
+     * Note: Does not immediately downgrade tier. Stripe will retry payment
+     * according to your dunning settings. Downgrade happens on subscription.deleted.
+     *
+     * @param invoice - Stripe invoice object
+     * @see StripeInvoiceEvent in database-types.ts for partial type
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Stripe invoice object
     async handleInvoicePaymentFailed(invoice) {
@@ -358,7 +422,26 @@ export class BillingService {
         return (data || []).map(this.mapDbInvoiceToInvoice);
     }
     /**
-     * Map database subscription to Subscription type
+     * Transform Supabase subscription record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `organization_id` → `organizationId`
+     * - `stripe_subscription_id` → `stripeSubscriptionId` (Stripe sub_xxx ID)
+     * - `stripe_price_id` → `stripePriceId` (Stripe price_xxx ID)
+     * - `stripe_product_id` → `stripeProductId` (Stripe prod_xxx ID)
+     * - `tier` → `tier` (SubscriptionTier: 'free' | 'pro' | 'enterprise')
+     * - `status` → `status` (SubscriptionStatus)
+     * - `current_period_start` → `currentPeriodStart` (nullable Date)
+     * - `current_period_end` → `currentPeriodEnd` (nullable Date)
+     * - `cancel_at_period_end` → `cancelAtPeriodEnd` (boolean)
+     * - `trial_start` → `trialStart` (nullable Date)
+     * - `trial_end` → `trialEnd` (nullable Date)
+     * - `canceled_at` → `canceledAt` (nullable Date)
+     *
+     * @param dbSub - Supabase record from 'subscriptions' table
+     * @returns Domain Subscription object
+     * @see DbSubscriptionRecord in database-types.ts for input shape
+     * @see Subscription in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbSubscriptionToSubscription(dbSub) {
@@ -383,7 +466,22 @@ export class BillingService {
         };
     }
     /**
-     * Map database invoice to Invoice type
+     * Transform Supabase invoice record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `organization_id` → `organizationId`
+     * - `stripe_invoice_id` → `stripeInvoiceId` (Stripe in_xxx ID)
+     * - `amount_due` → `amountDue` (in cents, e.g., 1000 = $10.00)
+     * - `amount_paid` → `amountPaid` (in cents)
+     * - `invoice_date` → `invoiceDate` (Date)
+     * - `due_date` → `dueDate` (nullable Date)
+     * - `paid_at` → `paidAt` (nullable Date)
+     * - `invoice_pdf_url` → `invoicePdfUrl` (Stripe-hosted PDF URL)
+     *
+     * @param dbInvoice - Supabase record from 'invoices' table
+     * @returns Domain Invoice object
+     * @see DbInvoiceRecord in database-types.ts for input shape
+     * @see Invoice in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbInvoiceToInvoice(dbInvoice) {

package/dist/lib/saas-organizations.js

@@ -331,7 +331,22 @@ export class OrganizationService {
         }
     }
     /**
-     * Map database org to Organization type
+     * Transform Supabase organization record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `created_at` (ISO string) → `createdAt` (Date)
+     * - `subscription_tier` (string) → `subscriptionTier` (SubscriptionTier type)
+     * - `subscription_status` (string) → `subscriptionStatus` (SubscriptionStatus type)
+     * - `stripe_customer_id` → `stripeCustomerId`
+     * - `subscription_expires_at` → `subscriptionExpiresAt` (nullable Date)
+     * - `deleted_at` → `deletedAt` (nullable Date, for soft delete filtering)
+     *
+     * Settings are passed through as-is (JSONB column).
+     *
+     * @param dbOrg - Supabase record from 'organizations' table
+     * @returns Domain Organization object with validated types
+     * @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) {
@@ -352,7 +367,20 @@ export class OrganizationService {
         };
     }
     /**
-     * Map database member to OrganizationMember type
+     * Transform Supabase organization member record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `organization_id` → `organizationId`
+     * - `user_id` → `userId`
+     * - `role` (string) → `role` (OrganizationRole type)
+     * - `invited_by` → `invitedBy` (nullable, FK to users.id)
+     * - `invited_at` (ISO string) → `invitedAt` (Date)
+     * - `accepted_at` (ISO string) → `acceptedAt` (nullable Date)
+     *
+     * @param dbMember - Supabase record from 'organization_members' table
+     * @returns Domain OrganizationMember object
+     * @see DbOrganizationMemberRecord in database-types.ts for input shape
+     * @see OrganizationMember in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbMemberToMember(dbMember) {
@@ -369,7 +397,24 @@ export class OrganizationService {
         };
     }
     /**
-     * Map database member detailed to OrganizationMemberDetailed type
+     * Transform Supabase organization member detailed view record to domain model.
+     *
+     * This mapper handles records from the 'organization_members_detailed' view,
+     * which joins organization_members with users and organizations tables.
+     *
+     * Maps all OrganizationMember fields plus:
+     * - `email` (from users table)
+     * - `first_name` → `firstName` (from users table)
+     * - `last_name` → `lastName` (from users table)
+     * - `avatar_url` → `avatarUrl` (from users table)
+     * - `last_login_at` → `lastLoginAt` (from users table, nullable Date)
+     * - `organization_name` → `organizationName` (from organizations table)
+     * - `organization_slug` → `organizationSlug` (from organizations table)
+     *
+     * @param dbMember - Supabase record from 'organization_members_detailed' view
+     * @returns Domain OrganizationMemberDetailed object
+     * @see DbOrganizationMemberDetailedRecord in database-types.ts for input shape
+     * @see OrganizationMemberDetailed in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row with joined user data
     mapDbMemberDetailedToMemberDetailed(dbMember) {
@@ -560,7 +605,19 @@ export class TeamService {
         return data || [];
     }
     /**
-     * Map database team to Team type
+     * Transform Supabase team record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `organization_id` → `organizationId`
+     * - `encryption_key_id` → `encryptionKeyId` (FK to active team encryption key)
+     * - `created_at` (ISO string) → `createdAt` (Date)
+     * - `updated_at` (ISO string) → `updatedAt` (Date)
+     * - `deleted_at` (ISO string) → `deletedAt` (nullable Date, for soft delete)
+     *
+     * @param dbTeam - Supabase record from 'teams' table
+     * @returns Domain Team object
+     * @see DbTeamRecord in database-types.ts for input shape
+     * @see Team in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbTeamToTeam(dbTeam) {
@@ -577,7 +634,19 @@ export class TeamService {
         };
     }
     /**
-     * Map database team member to TeamMember type
+     * Transform Supabase team member record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `team_id` → `teamId`
+     * - `user_id` → `userId`
+     * - `role` (string) → `role` (TeamRole type: 'admin' | 'member' | 'viewer')
+     * - `created_at` (ISO string) → `createdAt` (Date)
+     * - `updated_at` (ISO string) → `updatedAt` (Date)
+     *
+     * @param dbMember - Supabase record from 'team_members' table
+     * @returns Domain TeamMember object
+     * @see DbTeamMemberRecord in database-types.ts for input shape
+     * @see TeamMember in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbTeamMemberToTeamMember(dbMember) {

package/dist/lib/saas-secrets.js

@@ -341,7 +341,14 @@ export class SecretsService {
         }
     }
     /**
-     * Helper to get team
+     * Helper to get team record from database.
+     *
+     * Fetches raw team record from 'teams' table. Used internally to get
+     * organization_id for audit logging and tier limit checks.
+     *
+     * @param teamId - UUID of team to fetch
+     * @returns Raw Supabase team record or null if not found
+     * @see DbTeamRecord in database-types.ts for return shape
      */
     async getTeamById(teamId) {
         const { data } = await this.supabase
@@ -352,7 +359,28 @@ export class SecretsService {
         return data;
     }
     /**
-     * Map database secret to Secret type
+     * Transform Supabase secret record to domain model.
+     *
+     * Maps database snake_case columns to TypeScript camelCase properties:
+     * - `team_id` → `teamId`
+     * - `encrypted_value` → `encryptedValue` (AES-256 encrypted)
+     * - `encryption_key_id` → `encryptionKeyId` (FK to team's encryption key)
+     * - `last_rotated_at` → `lastRotatedAt` (nullable Date)
+     * - `rotation_interval_days` → `rotationIntervalDays` (nullable number)
+     * - `created_by` → `createdBy` (FK to users.id)
+     * - `updated_by` → `updatedBy` (FK to users.id)
+     * - `deleted_by` → `deletedBy` (FK to users.id, for soft delete audit)
+     *
+     * Special handling:
+     * - `tags`: Parses JSON string to string[] if stored as string, passes through if already array
+     *
+     * Note: The `encryptedValue` field contains the encrypted secret. Use
+     * `encryptionService.decryptForTeam()` to decrypt it when needed.
+     *
+     * @param dbSecret - Supabase record from 'secrets' table
+     * @returns Domain Secret object with parsed tags
+     * @see DbSecretRecord in database-types.ts for input shape
+     * @see Secret in saas-types.ts for output shape
      */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- DB row type varies by schema
     mapDbSecretToSecret(dbSecret) {

package/dist/services/secrets/secrets.js

@@ -458,6 +458,7 @@ API_KEY=
         .option('--export', 'Output in export format for shell evaluation (alias for --format export)')
         .option('--format <type>', 'Output format: env, json, yaml, toml, export', 'env')
         .option('--exact', 'Require exact key match (disable fuzzy matching)')
+        .option('--no-mask', 'Show full values in fuzzy match results')
         .action(async (key, options) => {
         try {
             const manager = new SecretsManager({ globalMode: options.global });
@@ -546,11 +547,13 @@ API_KEY=
             // Multiple matches - show all matches for user to choose
             console.error(`🔍 Found ${matches.length} matches for '${key}':\n`);
             for (const match of matches) {
-                // Mask value for display
-                const maskedValue = match.value.length > 4
-                    ? match.value.substring(0, 4) + '*'.repeat(Math.min(match.value.length - 4, 10))
-                    : '****';
-                console.error(`  ${match.key}=${maskedValue}`);
+                // Mask value for display unless --no-mask is set
+                const displayValue = options.mask === false
+                    ? match.value
+                    : (match.value.length > 4
+                        ? match.value.substring(0, 4) + '*'.repeat(Math.min(match.value.length - 4, 10))
+                        : '****');
+                console.error(`  ${match.key}=${displayValue}`);
             }
             console.error('');
             console.error('💡 Please specify the exact key name or use one of:');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lsh-framework",
-  "version": "3.1.6",
+  "version": "3.1.8",
   "description": "Simple, cross-platform encrypted secrets manager with automatic sync, IPFS audit logs, and multi-environment support. Just run lsh sync and start managing your secrets.",
   "main": "dist/app.js",
   "bin": {
@@ -65,13 +65,14 @@
   "dependencies": {
     "@storacha/client": "^1.8.18",
     "@supabase/supabase-js": "^2.57.4",
-    "bcrypt": "^5.1.1",
+    "@types/proper-lockfile": "^4.1.4",
+    "bcrypt": "^6.0.0",
     "chalk": "^5.3.0",
     "chokidar": "^5.0.0",
     "commander": "^14.0.2",
     "cors": "^2.8.5",
     "dotenv": "^17.2.3",
-    "express": "^4.18.2",
+    "express": "^4.22.1",
     "express-rate-limit": "^8.2.1",
     "glob": "^13.0.0",
     "inquirer": "^9.2.12",
@@ -80,6 +81,7 @@
     "node-cron": "^4.2.1",
     "ora": "^9.0.0",
     "pg": "^8.16.3",
+    "proper-lockfile": "^4.1.2",
     "smol-toml": "^1.3.1",
     "uuid": "^13.0.0"
   },
@@ -90,7 +92,7 @@
     "@types/jest": "^30.0.0",
     "@types/js-yaml": "^4.0.9",
     "@types/jsonwebtoken": "^9.0.5",
-    "@types/node": "^20.12.7",
+    "@types/node": "^20.19.27",
     "@typescript-eslint/eslint-plugin": "^8.44.1",
     "@typescript-eslint/parser": "^8.44.1",
     "eslint": "^9.36.0",