webspresso 0.0.93 → 0.0.95

package/bin/commands/polar-migrate.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * polar:migrate — write Polar billing migration to migrations/
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { loadDbConfig } = require('../utils/db');
+const { generatePolarMigration } = require('../../plugins/polar/src/migration');
+
+function registerCommand(program) {
+  program
+    .command('polar:migrate')
+    .description('Generate idempotent Polar billing migration for users table')
+    .option('-c, --config <path>', 'Path to database config file')
+    .option('-t, --table <name>', 'User table name', 'users')
+    .option('-o, --output <path>', 'Output migration file path (default: migrations/<timestamp>_polar_billing.js)')
+    .action(async (options) => {
+      const { config, path: configPath } = loadDbConfig(options.config);
+      console.log(`\n📦 Using config: ${configPath}\n`);
+
+      const migrationDir = config.migrations?.directory || './migrations';
+      if (!fs.existsSync(migrationDir)) {
+        fs.mkdirSync(migrationDir, { recursive: true });
+        console.log(`Created directory: ${migrationDir}`);
+      }
+
+      let filepath = options.output;
+      if (!filepath) {
+        const now = new Date();
+        const timestamp = [
+          now.getFullYear(),
+          String(now.getMonth() + 1).padStart(2, '0'),
+          String(now.getDate()).padStart(2, '0'),
+          String(now.getHours()).padStart(2, '0'),
+          String(now.getMinutes()).padStart(2, '0'),
+          String(now.getSeconds()).padStart(2, '0'),
+        ].join('');
+        filepath = path.join(migrationDir, `${timestamp}_polar_billing.js`);
+      }
+
+      const content = generatePolarMigration({ tableName: options.table });
+      fs.writeFileSync(filepath, content, 'utf8');
+      console.log(`✅ Polar migration written: ${filepath}`);
+      console.log('\nNext: webspresso db:migrate\n');
+    });
+}
+
+module.exports = { registerCommand };

package/bin/webspresso.js

@@ -35,6 +35,7 @@ const { registerCommand: registerUpgrade } = require('./commands/upgrade');
 const { registerCommand: registerOrmMap } = require('./commands/orm-map');
 const { registerCommand: registerService } = require('./commands/service');
 const { registerCommand: registerMcp } = require('./commands/mcp');
+const { registerCommand: registerPolarMigrate } = require('./commands/polar-migrate');
 
 registerNew(program);
 registerPage(program);
@@ -58,6 +59,7 @@ registerUpgrade(program);
 registerOrmMap(program);
 registerService(program);
 registerMcp(program);
+registerPolarMigrate(program);
 
 // Parse arguments
 program.parse();

package/core/auth/tokens.js

@@ -69,6 +69,9 @@ function createKnexAuthTokensAdapter(db) {
       if (type) q.where({ type });
       await q.delete();
     },
+    purgeExpired: async () => {
+      return knex('auth_tokens').where('expires_at', '<', new Date()).delete();
+    },
   };
 }
 
@@ -123,6 +126,18 @@ async function consumeAuthToken(authTokensAdapter, tokenHash) {
   await authTokensAdapter.delete(tokenHash);
 }
 
+/**
+ * Purge expired auth tokens
+ * @param {Object} authTokensAdapter
+ * @returns {Promise<number>} Number of deleted rows
+ */
+async function purgeExpiredAuthTokens(authTokensAdapter) {
+  if (authTokensAdapter && typeof authTokensAdapter.purgeExpired === 'function') {
+    return authTokensAdapter.purgeExpired();
+  }
+  return 0;
+}
+
 module.exports = {
   TOKEN_TYPES,
   createAuthTokensTable,
@@ -131,5 +146,6 @@ module.exports = {
   createAuthToken,
   verifyAuthToken,
   consumeAuthToken,
+  purgeExpiredAuthTokens,
   hash,
 };

package/core/orm/cache/layer.js

@@ -9,7 +9,7 @@ const { hashKey, serializeWheres } = require('./fingerprint');
  * @param {*} knex
  */
 function isTransactionKnex(knex) {
-  return !!(knex && knex.isTransaction);
+  return !!(knex && (knex.isTransaction || typeof knex.commit === 'function'));
 }
 
 /**

package/core/orm/index.js

@@ -275,7 +275,10 @@ function createDatabase(config) {
    * @returns {Promise<*>} Result of callback
    */
   async function transaction(callback, scopeContext) {
-    return knexInstance.transaction(async (trx) => {
+    const ambientTrx = getAmbientTransaction();
+    const runner = (ambientTrx && typeof ambientTrx.transaction === 'function') ? ambientTrx : knexInstance;
+
+    return runner.transaction(async (trx) => {
       const trxContext = {
         trx,
         getRepository(modelName, sContext) {

package/core/orm/transaction.js

@@ -87,7 +87,9 @@ function createTransactionContext(trx, scopeContext) {
  * @returns {Promise<*>} Result of callback
  */
 async function runTransaction(knex, callback, scopeContext) {
-  return knex.transaction(async (trx) => {
+  const ambientTrx = getAmbientTransaction();
+  const runner = (ambientTrx && typeof ambientTrx.transaction === 'function') ? ambientTrx : knex;
+  return runner.transaction(async (trx) => {
     const ctx = createTransactionContext(trx, scopeContext);
     return runWithAmbientTransaction(trx, () => callback(ctx));
   });

package/core/ssr/stream.js

@@ -17,7 +17,9 @@ const { Readable } = require('stream');
  * @returns {Readable}
  */
 function createHtmlStream(options = {}) {
-  const { env, templatePath, context = {}, defer = {} } = options;
+  const { env, templatePath, context = {}, defer = {}, nonce: optionNonce } = options;
+  const nonce = optionNonce || context.nonce || context.cspNonce || '';
+  const scriptTag = nonce ? `<script nonce="${nonce}">` : '<script>';
 
   if (!env) {
     throw new Error('createHtmlStream requires a valid Nunjucks environment in options.env');
@@ -63,6 +65,9 @@ function createHtmlStream(options = {}) {
 
         try {
           const resolvedData = await promise;
+          if (stream.destroyed) {
+            return;
+          }
           let slotHtml = '';
           if (slotTemplate) {
             slotHtml = env.render(slotTemplate, { ...context, [key]: resolvedData });
@@ -73,7 +78,7 @@ function createHtmlStream(options = {}) {
           // Push an out-of-order streaming chunk with inline replacement script or comment
           const slotChunk = `
 <template data-stream-slot="${key}">${slotHtml}</template>
-<script>
+${scriptTag}
 (function(){
   var t = document.querySelector('template[data-stream-slot="${key}"]');
   var target = document.querySelector('[data-stream-target="${key}"]') || document.getElementById('stream-target-${key}');
@@ -83,18 +88,27 @@ function createHtmlStream(options = {}) {
   }
 })();
 </script>`;
-          stream.push(slotChunk);
+          if (!stream.destroyed) {
+            stream.push(slotChunk);
+          }
         } catch (slotErr) {
+          if (stream.destroyed) {
+            return;
+          }
           const errorChunk = `
 <template data-stream-slot="${key}">
   <!-- Slot Error (${key}): ${slotErr.message} -->
 </template>`;
-          stream.push(errorChunk);
+          if (!stream.destroyed) {
+            stream.push(errorChunk);
+          }
         }
       });
 
       await Promise.all(resolutionPromises);
-      stream.push(null); // End of stream
+      if (!stream.destroyed) {
+        stream.push(null); // End of stream
+      }
     } catch (err) {
       stream.destroy(err);
     }
@@ -122,8 +136,17 @@ function renderStream(res, templatePath, context = {}, options = {}) {
       defer = {},
       status = 200,
       flushImmediately = true,
+      nonce: optionNonce,
     } = options;
 
+    const nonce =
+      optionNonce ||
+      res?.locals?.cspNonce ||
+      res?.locals?.nonce ||
+      context?.cspNonce ||
+      context?.nonce ||
+      '';
+
     if (!env) {
       return reject(new Error('renderStream requires a valid Nunjucks environment in options.env'));
     }
@@ -145,25 +168,46 @@ function renderStream(res, templatePath, context = {}, options = {}) {
       templatePath,
       context,
       defer,
+      nonce,
     });
 
+    let finished = false;
+    const cleanup = () => {
+      if (finished) return;
+      finished = true;
+      if (!stream.destroyed) {
+        stream.destroy();
+      }
+      resolve();
+    };
+
+    res.on('close', cleanup);
+
     stream.on('data', (chunk) => {
-      res.write(chunk);
+      if (!finished && !res.writableEnded) {
+        res.write(chunk);
+      }
     });
 
     stream.on('end', () => {
-      res.end();
-      resolve();
+      if (!finished) {
+        finished = true;
+        res.end();
+        resolve();
+      }
     });
 
     stream.on('error', (err) => {
-      if (!res.headersSent) {
-        res.status(500).send('Streaming Render Error');
-      } else {
-        res.write(`<!-- Streaming Error: ${err.message} -->`);
-        res.end();
+      if (!finished) {
+        finished = true;
+        if (!res.headersSent) {
+          res.status(500).send('Streaming Render Error');
+        } else if (!res.writableEnded) {
+          res.write(`<!-- Streaming Error: ${err.message} -->`);
+          res.end();
+        }
+        reject(err);
       }
-      reject(err);
     });
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.93",
+  "version": "0.0.95",
   "description": "Minimal, production-ready SSR framework for Node.js with file-based routing, Nunjucks templating, built-in i18n, and CLI tooling",
   "main": "index.js",
   "types": "index.d.ts",
@@ -14,10 +14,21 @@
       "default": "./core/errors/index.js"
     },
     "./plugins": "./plugins/index.js",
-    "./plugins/*": "./plugins/*",
+    "./plugins/polar": "./plugins/polar/index.js",
+    "./plugins/polar/src/*": "./plugins/polar/src/*.js",
+    "./plugins/*": "./plugins/*/index.js",
     "./realtime": "./core/realtime/index.js",
-    "./core/*": "./core/*",
-    "./src/*": "./src/*",
+    "./core/auth": "./core/auth/index.js",
+    "./core/auth/*": "./core/auth/*.js",
+    "./core/errors": "./core/errors/index.js",
+    "./core/orm": "./core/orm/index.js",
+    "./core/queue": "./core/queue/index.js",
+    "./core/*.js": "./core/*.js",
+    "./core/*": "./core/*/index.js",
+    "./core/*/*.js": "./core/*/*.js",
+    "./core/*/*": "./core/*/*/index.js",
+    "./core/*/*/*.js": "./core/*/*/*.js",
+    "./src/*": "./src/*.js",
     "./views/*": "./views/*",
     "./templates/*": "./templates/*",
     "./package.json": "./package.json"

package/plugins/admin-panel/auth.js

@@ -68,6 +68,9 @@ async function verifyPassword(password, hash, compare) {
   return await compare(password, hash);
 }
 
+// Precomputed dummy bcrypt hash (cost factor 10) to mitigate timing attacks / user enumeration
+const DUMMY_HASH = '$2b$10$wKzS8Vp0qXn8mY2bQv5eUu6R.kZbN8vA8Y7o7u4d1w2x3y4z5a6b7';
+
 /**
  * Login user and set session
  * @param {Object} adminUserRepo - AdminUser repository
@@ -81,6 +84,13 @@ async function login(adminUserRepo, email, password, compare) {
   const user = await adminUserRepo.query().where('email', email).first();
   
   if (!user || !user.active) {
+    if (typeof compare === 'function') {
+      try {
+        await Promise.resolve(compare(password, DUMMY_HASH));
+      } catch {
+        // Ignore timing dummy comparison errors
+      }
+    }
     return null;
   }
 

package/plugins/content/index.js

@@ -59,12 +59,14 @@ function contentPlugin(options = {}) {
     if (!inlineEdit || !isAdminSession(req, adminPath)) {
       return html;
     }
+    const nonce = req.res?.locals?.cspNonce || req.res?.locals?.nonce || req.cspNonce || '';
+    const nonceAttr = nonce ? ` nonce="${nonce}"` : '';
     const configScript =
-      '<script>window.__WS_CONTENT__=' +
+      `<script${nonceAttr}>window.__WS_CONTENT__=` +
       JSON.stringify({ enabled: true, adminPath }) +
       ';</script>';
-    const styleTag = '<style id="ws-content-inline-css">' + INLINE_EDIT_CSS + '</style>';
-    const scriptTag = '<script id="ws-content-inline-edit">' + INLINE_EDIT_JS + '</script>';
+    const styleTag = `<style id="ws-content-inline-css"${nonceAttr}>` + INLINE_EDIT_CSS + '</style>';
+    const scriptTag = `<script id="ws-content-inline-edit"${nonceAttr}>` + INLINE_EDIT_JS + '</script>';
     const bundle = configScript + styleTag + scriptTag;
     if (html.includes('</body>')) {
       return html.replace('</body>', bundle + '</body>');

package/plugins/data-exchange/import.js

@@ -251,6 +251,13 @@ function createImportHandler(opts) {
           return res.status(400).json({ error: `Too many data rows (${objects.length}). Limit is ${maxRows}.` });
         }
 
+        const isAtomic =
+          req.query.atomic === 'true' ||
+          req.query.atomic === '1' ||
+          req.body?.atomic === 'true' ||
+          req.body?.atomic === true ||
+          opts?.atomic === true;
+
         const repo = db.getRepository(model.name);
         const summary = {
           success: true,
@@ -260,52 +267,82 @@ function createImportHandler(opts) {
           errors: [],
         };
 
-        for (const { rowNumber, data } of objects) {
-          try {
-            const payload = buildPayloadForRow(model, data, mode);
-            if (Object.keys(payload).length === 0) {
-              summary.failed++;
-              summary.errors.push({ row: rowNumber, message: 'No mappable columns' });
-              continue;
-            }
+        const runRowProcessing = async (targetRepo) => {
+          for (const { rowNumber, data } of objects) {
+            try {
+              const payload = buildPayloadForRow(model, data, mode);
+              if (Object.keys(payload).length === 0) {
+                summary.failed++;
+                const errMsg = 'No mappable columns';
+                summary.errors.push({ row: rowNumber, message: errMsg });
+                if (isAtomic) {
+                  throw new Error(`Row ${rowNumber}: ${errMsg}`);
+                }
+                continue;
+              }
 
-            if (mode === 'insert') {
-              await repo.create(payload);
-              summary.created++;
-              continue;
-            }
+              if (mode === 'insert') {
+                await targetRepo.create(payload);
+                summary.created++;
+                continue;
+              }
 
-            const keyMeta = model.columns?.get ? model.columns.get(upsertKey) : undefined;
-            let keyVal;
-            try {
-              keyVal = coerceCell(data[upsertKey], keyMeta, upsertKey);
+              const keyMeta = model.columns?.get ? model.columns.get(upsertKey) : undefined;
+              let keyVal;
+              try {
+                keyVal = coerceCell(data[upsertKey], keyMeta, upsertKey);
+              } catch (e) {
+                summary.failed++;
+                summary.errors.push({ row: rowNumber, message: e.message || 'Bad upsert key' });
+                if (isAtomic) throw e;
+                continue;
+              }
+
+              if (keyVal === undefined || keyVal === null) {
+                const insertPayload = { ...payload };
+                delete insertPayload[upsertKey];
+                await targetRepo.create(insertPayload);
+                summary.created++;
+                continue;
+              }
+
+              const existing = await targetRepo.findOne({ [upsertKey]: keyVal });
+              if (existing) {
+                const id = existing[model.primaryKey];
+                await targetRepo.update(id, payload);
+                summary.updated++;
+              } else {
+                await targetRepo.create({ ...payload, [upsertKey]: keyVal });
+                summary.created++;
+              }
             } catch (e) {
               summary.failed++;
-              summary.errors.push({ row: rowNumber, message: e.message || 'Bad upsert key' });
-              continue;
-            }
-
-            if (keyVal === undefined || keyVal === null) {
-              const insertPayload = { ...payload };
-              delete insertPayload[upsertKey];
-              await repo.create(insertPayload);
-              summary.created++;
-              continue;
+              summary.errors.push({ row: rowNumber, message: e.message || String(e) });
+              if (isAtomic) {
+                throw e;
+              }
             }
+          }
+        };
 
-            const existing = await repo.findOne({ [upsertKey]: keyVal });
-            if (existing) {
-              const id = existing[model.primaryKey];
-              await repo.update(id, payload);
-              summary.updated++;
-            } else {
-              await repo.create({ ...payload, [upsertKey]: keyVal });
-              summary.created++;
-            }
-          } catch (e) {
-            summary.failed++;
-            summary.errors.push({ row: rowNumber, message: e.message || String(e) });
+        if (isAtomic && typeof db.transaction === 'function') {
+          try {
+            await db.transaction(async (trxContext) => {
+              const trxRepo = trxContext.getRepository ? trxContext.getRepository(model.name) : repo;
+              await runRowProcessing(trxRepo);
+            });
+          } catch (txErr) {
+            return res.status(400).json({
+              success: false,
+              created: 0,
+              updated: 0,
+              failed: objects.length,
+              error: `Atomic import rolled back: ${txErr.message}`,
+              errors: summary.errors,
+            });
           }
+        } else {
+          await runRowProcessing(repo);
         }
 
         summary.success = summary.failed === 0;

package/plugins/index.js

@@ -40,6 +40,7 @@ const {
   createRedisAdapter,
 } = require('./realtime');
 const { mcpPlugin, createMcpServer, McpServer } = require('./mcp');
+const polarPlugin = require('./polar');
 
 module.exports = {
   sitemapPlugin,
@@ -81,6 +82,7 @@ module.exports = {
   mcpPlugin,
   createMcpServer,
   McpServer,
+  polarPlugin,
 };
 
 

package/plugins/mcp/transports/sse.js

@@ -44,6 +44,19 @@ function mountSseTransport(options) {
     const sessionId = crypto.randomUUID ? crypto.randomUUID() : crypto.randomBytes(16).toString('hex');
     const endpointUri = `${normalizedBase}/messages?sessionId=${sessionId}`;
 
+    let isCleanedUp = false;
+    let keepAlive = null;
+
+    const cleanup = () => {
+      if (isCleanedUp) return;
+      isCleanedUp = true;
+      if (keepAlive) {
+        clearInterval(keepAlive);
+        keepAlive = null;
+      }
+      sessions.delete(sessionId);
+    };
+
     const sessionObj = {
       id: sessionId,
       req,
@@ -54,6 +67,7 @@ function mountSseTransport(options) {
           if (typeof res.flush === 'function') res.flush();
         } catch (err) {
           console.warn(`[mcp-sse] Failed to write to session ${sessionId}:`, err.message);
+          cleanup();
         }
       },
     };
@@ -67,18 +81,21 @@ function mountSseTransport(options) {
     }
 
     // Ping interval to keep connection alive through proxies
-    const keepAlive = setInterval(() => {
+    keepAlive = setInterval(() => {
       try {
         res.write(': ping\n\n');
       } catch (e) {
-        clearInterval(keepAlive);
+        cleanup();
       }
     }, 15000);
+    if (typeof keepAlive.unref === 'function') {
+      keepAlive.unref();
+    }
 
-    req.on('close', () => {
-      clearInterval(keepAlive);
-      sessions.delete(sessionId);
-    });
+    req.on('close', cleanup);
+    res.on('close', cleanup);
+    res.on('finish', cleanup);
+    res.on('error', cleanup);
   });
 
   // 2. POST /_mcp/messages - MCP message ingestion for an active SSE session

package/plugins/polar/.env.example

@@ -0,0 +1,12 @@
+# Polar.sh billing (webspresso polar plugin)
+POLAR_ACCESS_TOKEN=polar_oat_...
+POLAR_WEBHOOK_SECRET=whsec_...
+POLAR_PRO_PRODUCT_ID=
+POLAR_ORG_SLUG=
+POLAR_SANDBOX=false
+BASE_URL=https://example.com
+
+# Optional hosted checkout fallback (https://buy.polar.sh/polar_cl_...)
+POLAR_CHECKOUT_URL=
+POLAR_PRO_PRICE_ID=
+POLAR_PRO_YEARLY_PRODUCT_ID=

package/plugins/polar/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog — `webspresso/plugins/polar`
+
+## 1.0.1 — Unreleased
+
+### Fixed
+
+- **package exports**: `webspresso/core/auth`, `webspresso/plugins/polar`, and `webspresso/plugins/polar/src/*` resolve without manual `/index.js` suffix
+- **Rate limiting**: Polar limiters use `express-rate-limit` v8 `ipKeyGenerator` (fixes production startup `ValidationError`)
+- **Webhook user lookup**: `metadata.user_id` supports nanoid/UUID string primary keys
+- **CSP**: `polarCspDirectives()` includes `'self'` in `formAction` and `connectSrc`
+
+### Added
+
+- `hooks.isPaidUser({ user, knex, config })` for external tier tables (legacy `(user, knex, config)` still supported)
+- `syncBeforeCheckout` option (default `true`)
+- `polar.api.syncBillingForAppUser(user, knex, { hooks })` for dashboard page-load sync
+- `mergePolarCspDirectives(existing)` for Helmet CSP union merge
+- Production checklist: `docs/guides/polar-production-checklist.md`
+- Integration tests: rate-limit startup, IPv6 key validation, `isPaidUser` hook
+
+## 1.0.0 — 2026-09-10
+
+First production-ready release.
+
+### Added
+
+- Zero-dependency Polar SDK (`crypto` + `fetch`): webhook verification, API client, checkout, portal, Customer State sync
+- Auto routes: webhook, checkout (GET/POST), portal, billing status JSON API
+- Idempotent migration generator + `webspresso polar:migrate` CLI
+- Configurable field mapping, tier/plan mapping, hooks (`onSubscriptionChange`)
+- Optional `polarSyncMiddleware` for page-load tier refresh
+- Nunjucks `dateLabel` filter + Date-safe `truncate` wrapper
+- CSP helper (`polarCspDirectives`) for checkout form redirects
+- Zod env schema export (`parseEnv`, `polarEnvSchema`)
+
+### Production lessons encoded
+
+| Issue | Fix |
+|-------|-----|
+| Checkout URL is often `https://polar.sh/checkout/polar_cst_*`, not only `buy.polar.sh` | `extractCheckoutUrlFromResponse` + `client_secret` builder |
+| `https://polar.sh/purchases/subscriptions` → 404 | Blocked in URL validators |
+| `subscription.created` with `incomplete` status | Fallback Customer State sync before granting Pro |
+| Metadata may not propagate to subscription | `external_customer_id` required on checkout; multi-strategy user resolver |
+| `polar_current_period_end` as Date breaks Nunjucks `truncate` | Always persist ISO strings; `dateLabel` + safe truncate |
+| Checkout "already subscribed" API error | Pre-checkout `syncPolarBillingForUser` + early redirect |
+| Webhook 401 | Standard Webhooks HMAC (`webhook-id`, `webhook-timestamp`, `whsec_` decode); document raw body requirement |
+| Sandbox vs production OAT | `POLAR_SANDBOX=true` → `sandbox-api.polar.sh` |
+| Empty metadata fields → Polar 422 | `buildCheckoutMetadata` omits blank values |
+| Portal deprecated paths | Validate `/{org}/portal` only; fallback `POST /v1/customer-sessions/` |
+
+### Migration notes for existing custom Polar integrations
+
+- Remove local `utils/polar.js` and file routes under billing/webhook paths — plugin registers equivalent routes
+- Run `webspresso polar:migrate` (or `plugin.api.generateMigration()`) once
+- Mount `createWebhookRawBodyMiddleware('/api/v1/polar/webhook')` **before** `express.json()` in custom servers for strict signature verification
+- Wire `hooks.onSubscriptionChange` if tier updates need side effects (limits, analytics, etc.)