webspresso 0.0.94 → 0.0.96

package/plugins/file-manager/index.js

@@ -0,0 +1,139 @@
+/**
+ * Webspresso File Manager Plugin
+ * Filesystem-first media library, directory browser and asset picker for Admin Panel.
+ * @module plugins/file-manager
+ */
+
+const path = require('path');
+const { createFileManagerApiHandlers } = require('./api-handlers');
+const { generateFileManagerComponent } = require('./admin-component');
+const { createFileManagerServices } = require('../../src/services/builtins/file-manager');
+const core = require('./core');
+const security = require('./security');
+
+/**
+ * @param {Object} [options]
+ * @param {string} [options.baseDir='./public/uploads'] - Filesystem directory to manage
+ * @param {string} [options.publicBasePath='/uploads'] - URL prefix for stored files
+ * @param {string} [options.apiPrefix='/files'] - API subpath under Admin API
+ * @param {string} [options.pageTitle='Dosya Yöneticisi'] - Title of admin page
+ * @param {string} [options.menuLabel='Dosya Yöneticisi'] - Sidebar menu label
+ * @param {number} [options.menuOrder=50] - Sidebar menu ordering
+ * @param {number} [options.maxUploadBytes=10485760] - Max upload size in bytes (10MB default)
+ * @param {number|null} [options.maxTotalStorageBytes] - Storage quota limit in bytes (optional)
+ * @param {string[]|null} [options.allowedExtensions] - Whitelist of allowed extensions
+ * @param {string[]|null} [options.allowedMimeTypes] - Whitelist of allowed MIME types
+ * @param {Record<string, string[]>|null} [options.permissions] - RBAC permissions map
+ * @param {Object} [options.security] - Security configurations
+ * @param {boolean} [options.security.validateMagicBytes=true] - Validate file signatures
+ * @param {boolean} [options.security.sanitizeSvg=true] - Sanitize SVG XSS payloads
+ * @param {boolean} [options.includePage=true] - Whether to register admin menu item & page
+ */
+function fileManagerPlugin(options = {}) {
+  const {
+    baseDir = path.join(process.cwd(), 'public', 'uploads'),
+    publicBasePath = '/uploads',
+    apiPrefix = '/files',
+    pageTitle = 'Dosya Yöneticisi',
+    menuLabel = 'Dosya Yöneticisi',
+    menuOrder = 50,
+    maxUploadBytes = 10 * 1024 * 1024,
+    maxTotalStorageBytes = null,
+    allowedExtensions = null,
+    allowedMimeTypes = null,
+    permissions = null,
+    security: securityOpts = { validateMagicBytes: true, sanitizeSvg: true },
+    includePage = true,
+  } = options;
+
+  const resolvedBaseDir = path.resolve(baseDir);
+
+  const handlers = createFileManagerApiHandlers({
+    baseDir: resolvedBaseDir,
+    publicBasePath,
+    maxUploadBytes,
+    maxTotalStorageBytes,
+    allowedExtensions,
+    allowedMimeTypes,
+    permissions,
+    security: securityOpts,
+  });
+
+  return {
+    name: 'file-manager',
+    version: '1.0.0',
+    description: 'Filesystem-first media library, directory explorer & asset picker',
+    dependencies: { 'admin-panel': '*' },
+
+    api: {
+      ...core,
+      security,
+    },
+
+    register(ctx) {
+      // Register built-in services in app service registry if available
+      if (ctx.app && ctx.app.serviceRegistry) {
+        const services = createFileManagerServices({
+          baseDir: resolvedBaseDir,
+          publicBasePath,
+        });
+        for (const [name, def] of Object.entries(services)) {
+          if (!ctx.app.serviceRegistry.has(name)) {
+            ctx.app.serviceRegistry.register(name, def);
+          }
+        }
+      }
+    },
+
+    onRoutesReady(ctx) {
+      const adminApi = ctx.usePlugin('admin-panel');
+      if (!adminApi) {
+        console.warn('[file-manager] admin-panel plugin not found, skipping Admin UI registration');
+        return;
+      }
+
+      adminApi.registerModule({
+        id: 'files',
+        pages: includePage
+          ? [{
+              id: 'files',
+              title: pageTitle,
+              path: '/files',
+              icon: 'folder',
+              component: generateFileManagerComponent({
+                apiPrefix,
+                publicBasePath,
+              }),
+            }]
+          : [],
+
+        menu: includePage
+          ? [{
+              id: 'files',
+              label: menuLabel,
+              path: '/files',
+              icon: 'folder',
+              order: menuOrder,
+            }]
+          : [],
+
+        api: {
+          prefix: apiPrefix,
+          routes: [
+            { method: 'get', path: '', handler: handlers.list },
+            { method: 'post', path: '/mkdir', handler: handlers.mkdir },
+            { method: 'post', path: '/rename', handler: handlers.rename },
+            { method: 'post', path: '/move', handler: handlers.move },
+            { method: 'post', path: '/delete', handler: handlers.delete },
+            { method: 'post', path: '/upload', handler: handlers.upload },
+          ],
+        },
+      });
+    },
+  };
+}
+
+module.exports = fileManagerPlugin;
+module.exports.fileManagerPlugin = fileManagerPlugin;
+module.exports.core = core;
+module.exports.security = security;

package/plugins/file-manager/security.js

@@ -0,0 +1,207 @@
+/**
+ * File Manager Security Subsystem — Magic byte verification, dangerous extension blocking & SVG sanitization.
+ * Zero external dependencies, ultra-high performance O(1) buffer checks.
+ * @module plugins/file-manager/security
+ */
+
+const { SecurityError, ValidationError } = require('../../core/errors');
+
+/**
+ * Universal list of dangerous/executable extensions (lowercase without dot)
+ */
+const DANGEROUS_EXTENSIONS = new Set([
+  // Scripts & Executables
+  'php', 'phtml', 'php3', 'php4', 'php5', 'php7', 'php8', 'phps', 'phar',
+  'exe', 'dll', 'so', 'dylib', 'bin', 'elf',
+  'sh', 'bash', 'zsh', 'csh', 'ksh', 'fish', 'bat', 'cmd', 'ps1', 'psm1',
+  'vbs', 'vbe', 'wsf', 'wsh', 'scr', 'cpl', 'msc', 'hta',
+  'jar', 'war', 'ear', 'class',
+  'jsp', 'jspx', 'jsw', 'jsv', 'jspf',
+  'asp', 'aspx', 'axd', 'asx', 'ashx', 'asmx',
+  'cgi', 'pl', 'pm', 'py', 'pyc', 'pyo', 'rb',
+  // System & Config files
+  'htaccess', 'htpasswd', 'ini', 'env', 'config', 'conf', 'passwd', 'shadow',
+]);
+
+/**
+ * Known magic numbers table for high-speed signature verification.
+ * Only validates when extension matches known binary format.
+ */
+const MAGIC_NUMBERS = {
+  // JPEG / JPG
+  jpg: (buf) => buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff,
+  jpeg: (buf) => buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff,
+
+  // PNG
+  png: (buf) =>
+    buf.length >= 8 &&
+    buf[0] === 0x89 &&
+    buf[1] === 0x50 &&
+    buf[2] === 0x4e &&
+    buf[3] === 0x47 &&
+    buf[4] === 0x0d &&
+    buf[5] === 0x0a &&
+    buf[6] === 0x1a &&
+    buf[7] === 0x0a,
+
+  // GIF
+  gif: (buf) =>
+    buf.length >= 6 &&
+    buf[0] === 0x47 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x38 &&
+    (buf[4] === 0x37 || buf[4] === 0x39) &&
+    buf[5] === 0x61,
+
+  // WebP: RIFF at 0..3 and WEBP at 8..11
+  webp: (buf) =>
+    buf.length >= 12 &&
+    buf[0] === 0x52 &&
+    buf[1] === 0x49 &&
+    buf[2] === 0x46 &&
+    buf[3] === 0x46 &&
+    buf[8] === 0x57 &&
+    buf[9] === 0x45 &&
+    buf[10] === 0x42 &&
+    buf[11] === 0x50,
+
+  // PDF: %PDF-
+  pdf: (buf) =>
+    buf.length >= 5 &&
+    buf[0] === 0x25 &&
+    buf[1] === 0x50 &&
+    buf[2] === 0x44 &&
+    buf[3] === 0x46 &&
+    buf[4] === 0x2d,
+
+  // ZIP (and DOCX/XLSX/PPTX)
+  zip: (buf) =>
+    buf.length >= 4 &&
+    buf[0] === 0x50 &&
+    buf[1] === 0x4b &&
+    (buf[2] === 0x03 || buf[2] === 0x05 || buf[2] === 0x07) &&
+    (buf[3] === 0x04 || buf[3] === 0x06 || buf[3] === 0x08),
+  docx: (buf) => MAGIC_NUMBERS.zip(buf),
+  xlsx: (buf) => MAGIC_NUMBERS.zip(buf),
+  pptx: (buf) => MAGIC_NUMBERS.zip(buf),
+
+  // MP3: ID3 or frame sync 0xFFE / 0xFFF
+  mp3: (buf) =>
+    (buf.length >= 3 && buf[0] === 0x49 && buf[1] === 0x44 && buf[2] === 0x33) ||
+    (buf.length >= 2 && buf[0] === 0xff && (buf[1] & 0xe0) === 0xe0),
+
+  // MP4: ....ftyp at bytes 4..7
+  mp4: (buf) =>
+    buf.length >= 8 &&
+    buf[4] === 0x66 &&
+    buf[5] === 0x74 &&
+    buf[6] === 0x79 &&
+    buf[7] === 0x70,
+};
+
+/**
+ * Validate that a filename contains no dangerous extensions or double-extension tricks.
+ * @param {string} filename
+ * @returns {string} Clean lowercase extension
+ */
+function validateSafeExtension(filename) {
+  if (!filename || typeof filename !== 'string') {
+    throw new ValidationError('Filename is required');
+  }
+
+  const cleanName = filename.toLowerCase().trim();
+  const parts = cleanName.split('.').filter(Boolean);
+
+  if (parts.length === 0) {
+    throw new ValidationError('Filename must have a valid extension');
+  }
+
+  // Check all dotted segments against dangerous extensions to block double extensions (e.g. payload.php.jpg)
+  for (let i = 1; i < parts.length; i++) {
+    const segment = parts[i];
+    if (DANGEROUS_EXTENSIONS.has(segment)) {
+      throw new SecurityError(
+        `Dangerous extension or double-extension detected: .${segment}`,
+        400
+      );
+    }
+  }
+
+  const finalExt = parts[parts.length - 1];
+  if (DANGEROUS_EXTENSIONS.has(finalExt)) {
+    throw new SecurityError(`File type .${finalExt} is forbidden for upload`, 403);
+  }
+
+  return finalExt;
+}
+
+/**
+ * Verify that the buffer's magic bytes match the claimed extension.
+ * O(1) time complexity, minimal memory overhead.
+ * @param {Buffer} buffer
+ * @param {string} ext
+ * @returns {boolean}
+ */
+function validateMagicBytes(buffer, ext) {
+  if (!buffer || !Buffer.isBuffer(buffer)) {
+    throw new ValidationError('Valid buffer is required for magic byte check');
+  }
+
+  const cleanExt = (ext || '').replace(/^\./, '').toLowerCase();
+  const validator = MAGIC_NUMBERS[cleanExt];
+
+  if (validator) {
+    const isValid = validator(buffer);
+    if (!isValid) {
+      throw new SecurityError(
+        `File signature mismatch: file content does not match expected .${cleanExt} format`,
+        400
+      );
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Sanitize SVG content against Stored XSS attacks.
+ * Strips <script>, <foreignObject>, <iframe>, <embed>, <object> and on* event handlers.
+ * @param {Buffer|string} content
+ * @returns {Buffer} Sanitized SVG buffer
+ */
+function sanitizeSvgContent(content) {
+  const str = Buffer.isBuffer(content) ? content.toString('utf8') : String(content);
+
+  // Quick check: if no dangerous keywords, return original buffer directly for maximum speed
+  if (!/<(script|foreignobject|iframe|embed|object|meta|link|style)/i.test(str) &&
+      !/\s+on[a-z]+\s*=/i.test(str) &&
+      !/javascript:/i.test(str) &&
+      !/data:text\/html/i.test(str)) {
+    return Buffer.isBuffer(content) ? content : Buffer.from(str, 'utf8');
+  }
+
+  let sanitized = str
+    // Remove script tags and content
+    .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script\s*>/gi, '')
+    // Remove dangerous containers
+    .replace(/<foreignObject\b[^<]*(?:(?!<\/foreignObject>)<[^<]*)*<\/foreignObject\s*>/gi, '')
+    .replace(/<iframe\b[^<]*(?:(?!<\/iframe>)<[^<]*)*<\/iframe\s*>/gi, '')
+    .replace(/<embed\b[^>]*>/gi, '')
+    .replace(/<object\b[^<]*(?:(?!<\/object>)<[^<]*)*<\/object\s*>/gi, '')
+    // Remove inline event handlers (onload, onclick, onerror, onmouseover, etc.)
+    .replace(/\s+on[a-zA-Z]+\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)/gi, '')
+    // Remove javascript: and data:text/html URIs in href and xlink:href
+    .replace(/(?:href|xlink:href)\s*=\s*(?:"\s*javascript:[^"]*"|'\s*javascript:[^']*')/gi, 'href=""')
+    .replace(/(?:href|xlink:href)\s*=\s*(?:"\s*data:text\/html[^"]*"|'\s*data:text\/html[^']*')/gi, 'href=""');
+
+  return Buffer.from(sanitized, 'utf8');
+}
+
+module.exports = {
+  DANGEROUS_EXTENSIONS,
+  MAGIC_NUMBERS,
+  validateSafeExtension,
+  validateMagicBytes,
+  sanitizeSvgContent,
+};

package/plugins/index.js

@@ -41,6 +41,9 @@ const {
 } = require('./realtime');
 const { mcpPlugin, createMcpServer, McpServer } = require('./mcp');
 const polarPlugin = require('./polar');
+const fileManagerPlugin = require('./file-manager');
+const { xlsxPlugin, xlsx } = require('./xlsx');
+const { csvPlugin, csv } = require('./csv');
 
 module.exports = {
   sitemapPlugin,
@@ -83,6 +86,11 @@ module.exports = {
   createMcpServer,
   McpServer,
   polarPlugin,
+  fileManagerPlugin,
+  xlsxPlugin,
+  xlsx,
+  csvPlugin,
+  csv,
 };
 
 

package/plugins/polar/CHANGELOG.md

@@ -1,5 +1,23 @@
 # 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.

package/plugins/polar/README.md

@@ -58,10 +58,19 @@ That's it — routes, webhooks, checkout, portal, and status API are auto-mounte
 | Method | Path | Auth | Behavior |
 |--------|------|------|----------|
 | POST | `/api/v1/polar/webhook` | HMAC signature | Process Polar events |
-| GET/POST | `/settings/billing/checkout` | session/JWT | Sync → Polar checkout redirect |
+| GET/POST | `/settings/billing/checkout` | session/JWT | Sync → Polar checkout redirect (see POST vs GET below) |
 | GET | `/settings/billing/portal` | session/JWT | Customer portal redirect |
 | GET | `/api/v1/billing/status` | session/JWT | Sync + JSON billing status |
 
+## Checkout: POST vs GET
+
+Both `/settings/billing/checkout` methods run the same handler:
+
+| Method | Typical use | CSP note |
+|--------|-------------|----------|
+| **POST** | `<form method="post" action="…">` | Requires `form-action 'self'` (included in `polarCspDirectives()`) |
+| **GET** | `<a href="…">Upgrade</a>` | No form submission — simpler when CSP is strict |
+
 ## Template usage
 
 ```njk
@@ -81,6 +90,7 @@ That's it — routes, webhooks, checkout, portal, and status API are auto-mounte
 const polar = polarPlugin({ db });
 polar.api.verifyPolarWebhook(raw, headers, secret);
 polar.api.syncPolarBillingForUser(user, knex);
+polar.api.syncBillingForAppUser(user, knex, { hooks }); // dashboard page-load sync
 polar.api.getPolarCheckoutUrl({ user, plan: 'pro_monthly', baseUrl });
 polar.api.handlePolarWebhookEvent(event, knex);
 polar.api.generateMigration();
@@ -118,12 +128,20 @@ polarPlugin({ db, rateLimit: { checkout: { limit: 3 } } }); // override
 
 ## Optional hooks
 
+Billing columns on `users` work out of the box. If your paid tier lives elsewhere (e.g. `subscriptions.plan_tier`), use hooks:
+
 ```js
 polarPlugin({
   db,
+  syncBeforeCheckout: false, // skip Polar API sync before redirect (default: true)
   hooks: {
+    /** Override paid check at checkout (default: users.tier vs tierMapping) */
+    async isPaidUser({ user, knex }) {
+      const sub = await knex('subscriptions').where('user_id', user.id).first();
+      return sub?.plan_tier === 'pro';
+    },
     onSubscriptionChange({ user, tier, polarStatus, subscription, knex, update }) {
-      // Custom tier logic (default: updates users.* polar columns)
+      // Sync external tables when webhooks fire
       return knex('users').where('id', user.id).update(update);
     },
   },
@@ -133,23 +151,28 @@ polarPlugin({
 });
 ```
 
+Checkout metadata sends `user_id` as a string (supports nanoid/UUID primary keys, not only integers).
+
 ## CSP (Helmet)
 
+`polarCspDirectives()` always includes `'self'` so local login/register/checkout forms keep working. Polar domains are added for hosted checkout redirects.
+
 ```js
-const { polarCspDirectives } = require('webspresso/plugins/polar/src/urls');
+const { mergePolarCspDirectives } = require('webspresso/plugins/polar/src/urls');
 
 createApp({
   helmet: {
     contentSecurityPolicy: {
-      directives: {
-        ...polarCspDirectives(),
-      },
+      directives: mergePolarCspDirectives({
+        formAction: ["'self'"],
+        scriptSrc: ["'self'"],
+      }),
     },
   },
 });
 ```
 
-Or rely on the plugin's built-in `csp` export (auto-merged by plugin manager).
+Or rely on the plugin's built-in `csp` export — the plugin manager **unions** sources per directive (does not replace your Helmet config).
 
 ## Non-goals (v1)
 

package/plugins/polar/index.js

@@ -12,6 +12,7 @@ const { verifyPolarWebhook, handlePolarWebhookEvent, createWebhookRawBodyMiddlew
 const { getPolarCheckoutUrl } = require('./src/checkout');
 const { getPolarPortalUrl } = require('./src/portal');
 const { syncPolarBillingForUser } = require('./src/sync');
+const { syncBillingForAppUser } = require('./src/billing-hooks');
 const {
   resolveUserFromPolarData,
   buildCheckoutMetadata,
@@ -24,6 +25,7 @@ const {
   isValidPortalRedirectUrl,
   extractCheckoutUrlFromResponse,
   polarCspDirectives,
+  mergePolarCspDirectives,
 } = require('./src/urls');
 const { generatePolarMigration } = require('./src/migration');
 const { polarSyncMiddleware } = require('./src/middleware');
@@ -66,6 +68,8 @@ function polarPlugin(options = {}) {
     getPolarCheckoutUrl: (params) => getPolarCheckoutUrl({ ...params, config: runtimeConfig }),
     getPolarPortalUrl: (user, baseUrl) => getPolarPortalUrl(user, baseUrl, runtimeConfig),
     syncPolarBillingForUser: (user, knex) => syncPolarBillingForUser(user, knex, runtimeConfig),
+    /** Dashboard/page-load sync — optional per-call hooks override */
+    syncBillingForAppUser: (user, knex, opts) => syncBillingForAppUser(user, knex, runtimeConfig, opts),
     handlePolarWebhookEvent: (event, knex, hooks) => handlePolarWebhookEvent(event, knex, runtimeConfig, hooks),
     resolveUserFromPolarData: (data, knex) => resolveUserFromPolarData(data, knex, runtimeConfig),
     extractCheckoutUrlFromResponse: (data) => extractCheckoutUrlFromResponse(data, runtimeConfig.sandbox),
@@ -78,6 +82,7 @@ function polarPlugin(options = {}) {
     generateMigration: (opts) => generatePolarMigration({ ...opts, fields: runtimeConfig.fields }),
     polarSyncMiddleware: (opts) => polarSyncMiddleware(runtimeConfig, opts),
     polarCspDirectives,
+    mergePolarCspDirectives,
     createWebhookRawBodyMiddleware,
     registerNunjucksFilters,
     dateLabel,
@@ -89,7 +94,7 @@ function polarPlugin(options = {}) {
 
   return {
     name: 'polar',
-    version: '1.0.0',
+    version: '1.0.1',
     description: 'Polar.sh subscription billing — checkout, portal, webhooks, and tier sync',
 
     csp: polarCspDirectives(),

package/plugins/polar/src/billing-hooks.js

@@ -0,0 +1,51 @@
+'use strict';
+
+const { userHasProTier } = require('./user-resolver');
+const { syncPolarBillingForUser } = require('./sync');
+
+/**
+ * Invoke hooks.isPaidUser — supports ({ user, knex, config }) or legacy (user, knex, config).
+ * @param {Function} hook
+ * @param {Object} user
+ * @param {Object} knex
+ * @param {import('./config').PolarConfig} config
+ */
+async function invokeIsPaidUserHook(hook, user, knex, config) {
+  const ctx = { user, knex, config };
+  // Legacy (user, knex, config) when declared with 2+ params; default is ({ user, knex, config })
+  const result = hook.length >= 2
+    ? await hook(user, knex, config)
+    : await hook(ctx);
+  return Boolean(result);
+}
+
+/**
+ * Paid-user check at checkout: hooks.isPaidUser override, else users.tier via userHasProTier.
+ */
+async function userIsPaid(user, knex, config) {
+  if (typeof config.hooks?.isPaidUser === 'function') {
+    return invokeIsPaidUserHook(config.hooks.isPaidUser, user, knex, config);
+  }
+  return userHasProTier(user, config);
+}
+
+/**
+ * App-level billing sync for dashboard loaders — merges optional hook overrides per call.
+ * @param {Object} user
+ * @param {Object} knex
+ * @param {import('./config').PolarConfig} config
+ * @param {{ hooks?: Object }} [opts]
+ */
+async function syncBillingForAppUser(user, knex, config, opts = {}) {
+  const merged = {
+    ...config,
+    hooks: { ...config.hooks, ...(opts.hooks || {}) },
+  };
+  return syncPolarBillingForUser(user, knex, merged);
+}
+
+module.exports = {
+  invokeIsPaidUserHook,
+  userIsPaid,
+  syncBillingForAppUser,
+};

package/plugins/polar/src/config.js

@@ -67,6 +67,8 @@ function resolvePolarConfig(options = {}) {
     hooks: options.hooks || {},
     requireAuth: options.requireAuth || null,
     syncMiddleware: options.syncMiddleware || null,
+    /** Sync from Polar API before checkout redirect (default true). Set false to skip. */
+    syncBeforeCheckout: options.syncBeforeCheckout !== false,
     rateLimit: options.rateLimit !== undefined ? options.rateLimit : true,
     env,
     accessToken: options.accessToken || env.POLAR_ACCESS_TOKEN || null,