webspresso 0.0.94 → 0.0.95

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webspresso",
-  "version": "0.0.94",
+  "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/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,

package/plugins/polar/src/rate-limit.js

@@ -1,36 +1,86 @@
 'use strict';
 
-const DEFAULT_RATE_LIMITS = {
-  webhook: {
-    limit: 120,
-    windowMs: 60_000,
-    message: { error: 'Too many webhook requests' },
-  },
-  checkout: {
-    limit: 5,
-    windowMs: 60_000,
-    message: { error: 'Too many checkout attempts. Please try again later.' },
-    keyGenerator: (req) => `polar:checkout:${req.user?.id ?? req.ip}`,
-  },
-  portal: {
-    limit: 10,
-    windowMs: 60_000,
-    message: { error: 'Too many portal requests. Please try again later.' },
-    keyGenerator: (req) => `polar:portal:${req.user?.id ?? req.ip}`,
-  },
-  status: {
-    limit: 60,
-    windowMs: 60_000,
-    message: { error: 'Too many billing status requests' },
-    keyGenerator: (req) => `polar:status:${req.user?.id ?? req.ip}`,
-  },
-};
+const { loadPeer } = require('../../rate-limit/index.js');
+
+const DEFAULT_IPV6_SUBNET = 56;
+
+/**
+ * @param {Function} ipKeyGenerator
+ * @param {string} prefix
+ */
+function polarIpKey(ipKeyGenerator, prefix) {
+  return (req) => `${prefix}:${ipKeyGenerator(req.ip, DEFAULT_IPV6_SUBNET)}`;
+}
+
+/**
+ * Prefer authenticated user id; fall back to IPv6-safe IP key (express-rate-limit v8).
+ * @param {Function} ipKeyGenerator
+ * @param {string} prefix
+ */
+function polarUserOrIpKey(ipKeyGenerator, prefix) {
+  const ipKey = polarIpKey(ipKeyGenerator, prefix);
+  return (req) => (req.user?.id != null ? `${prefix}:${req.user.id}` : ipKey(req));
+}
+
+/**
+ * @param {Function} ipKeyGenerator
+ */
+function buildDefaultRateLimits(ipKeyGenerator) {
+  return {
+    webhook: {
+      limit: 120,
+      windowMs: 60_000,
+      message: { error: 'Too many webhook requests' },
+      keyGenerator: polarIpKey(ipKeyGenerator, 'polar:webhook'),
+    },
+    checkout: {
+      limit: 5,
+      windowMs: 60_000,
+      message: { error: 'Too many checkout attempts. Please try again later.' },
+      keyGenerator: polarUserOrIpKey(ipKeyGenerator, 'polar:checkout'),
+    },
+    portal: {
+      limit: 10,
+      windowMs: 60_000,
+      message: { error: 'Too many portal requests. Please try again later.' },
+      keyGenerator: polarUserOrIpKey(ipKeyGenerator, 'polar:portal'),
+    },
+    status: {
+      limit: 60,
+      windowMs: 60_000,
+      message: { error: 'Too many billing status requests' },
+      keyGenerator: polarUserOrIpKey(ipKeyGenerator, 'polar:status'),
+    },
+  };
+}
+
+/** @type {ReturnType<typeof buildDefaultRateLimits>|null} */
+let cachedDefaults = null;
+
+function loadIpKeyGenerator() {
+  try {
+    const { ipKeyGenerator } = loadPeer();
+    return ipKeyGenerator;
+  } catch {
+    return null;
+  }
+}
+
+function getDefaultRateLimits() {
+  const ipKeyGenerator = loadIpKeyGenerator();
+  if (!ipKeyGenerator) {
+    return null;
+  }
+  if (!cachedDefaults) {
+    cachedDefaults = buildDefaultRateLimits(ipKeyGenerator);
+  }
+  return cachedDefaults;
+}
 
 /**
  * Build per-route limiter middleware from rateLimitPlugin factory.
  * @param {Object} ctx - plugin onRoutesReady context
  * @param {import('./config').PolarConfig} config
- * @returns {{ webhook?: Function, checkout?: Function, portal?: Function, status?: Function }}
  */
 function resolvePolarRateLimiters(ctx, config) {
   const rlOpt = config.rateLimit;
@@ -48,6 +98,14 @@ function resolvePolarRateLimiters(ctx, config) {
     return {};
   }
 
+  const defaults = getDefaultRateLimits();
+  if (!defaults) {
+    console.warn(
+      '[polar] rateLimit is enabled but express-rate-limit >= 8 is not installed — skipping polar rate limiters'
+    );
+    return {};
+  }
+
   const overrides = rlOpt === true ? {} : (rlOpt || {});
   const routes = ['webhook', 'checkout', 'portal', 'status'];
   const out = {};
@@ -55,7 +113,7 @@ function resolvePolarRateLimiters(ctx, config) {
   for (const route of routes) {
     if (overrides[route] === false) continue;
     const opts = {
-      ...DEFAULT_RATE_LIMITS[route],
+      ...defaults[route],
       ...(typeof overrides[route] === 'object' ? overrides[route] : {}),
     };
     out[route] = factory(opts);
@@ -65,6 +123,16 @@ function resolvePolarRateLimiters(ctx, config) {
 }
 
 module.exports = {
-  DEFAULT_RATE_LIMITS,
+  loadIpKeyGenerator,
+  polarIpKey,
+  polarUserOrIpKey,
+  buildDefaultRateLimits,
+  getDefaultRateLimits,
   resolvePolarRateLimiters,
+  /** @deprecated use getDefaultRateLimits() */
+  get DEFAULT_RATE_LIMITS() {
+    return getDefaultRateLimits() || buildDefaultRateLimits(
+      loadIpKeyGenerator() || ((ip) => String(ip))
+    );
+  },
 };

package/plugins/polar/src/routes.js

@@ -5,6 +5,7 @@ const { getPolarCheckoutUrl } = require('./checkout');
 const { getPolarPortalUrl } = require('./portal');
 const { syncPolarBillingForUser } = require('./sync');
 const { userHasProTier } = require('./user-resolver');
+const { userIsPaid } = require('./billing-hooks');
 
 function resolveKnex(db) {
   return db?.knex || (typeof db?.raw === 'function' ? db : null);
@@ -81,12 +82,12 @@ function createCheckoutHandler(config) {
       if (knex) {
         const dbUser = await knex(config.userTable).where(f.id, req.user[f.id] || req.user.id).first();
         if (dbUser) user = dbUser;
-        if (config.accessToken) {
+        if (config.accessToken && config.syncBeforeCheckout) {
           user = await syncPolarBillingForUser(user, knex, config);
         }
       }
 
-      if (userHasProTier(user, config)) {
+      if (await userIsPaid(user, knex, config)) {
         const alreadyUrl = config.urls.alreadySubscribed.startsWith('http')
           ? config.urls.alreadySubscribed
           : config.urls.alreadySubscribed;

package/plugins/polar/src/urls.js

@@ -92,6 +92,7 @@ function extractCheckoutUrlFromResponse(data, sandbox = false) {
 }
 
 function polarCspDirectives(opts = {}) {
+  const self = "'self'";
   const domains = opts.domains || [
     'https://buy.polar.sh',
     'https://sandbox-buy.polar.sh',
@@ -101,8 +102,30 @@ function polarCspDirectives(opts = {}) {
     'https://sandbox-api.polar.sh',
   ];
   return {
-    formAction: domains,
-    connectSrc: domains,
+    formAction: [self, ...domains],
+    connectSrc: [self, ...domains],
+  };
+}
+
+/**
+ * Union Polar CSP sources into an existing Helmet/plugin CSP config (does not replace).
+ * @param {Object} [existing]
+ * @param {Object} [opts] - passed to polarCspDirectives
+ */
+function mergePolarCspDirectives(existing = {}, opts = {}) {
+  const polar = polarCspDirectives(opts);
+  const mergeList = (key) => {
+    const base = existing[key];
+    const items = [
+      ...(Array.isArray(base) ? base : base ? [base] : []),
+      ...polar[key],
+    ];
+    return [...new Set(items)];
+  };
+  return {
+    ...existing,
+    formAction: mergeList('formAction'),
+    connectSrc: mergeList('connectSrc'),
   };
 }
 
@@ -114,4 +137,5 @@ module.exports = {
   isValidPortalRedirectUrl,
   extractCheckoutUrlFromResponse,
   polarCspDirectives,
+  mergePolarCspDirectives,
 };

package/plugins/polar/src/user-resolver.js

@@ -113,7 +113,11 @@ async function resolveUserFromPolarData(data, knex, config) {
   const table = config.userTable;
 
   if (metadata.user_id) {
-    const user = await knex(table).where(f.id, Number(metadata.user_id)).first();
+    const uid = String(metadata.user_id).trim();
+    let user = await knex(table).where(f.id, uid).first();
+    if (!user && /^\d+$/.test(uid)) {
+      user = await knex(table).where(f.id, Number(uid)).first();
+    }
     if (user) return user;
   }
 

package/plugins/rate-limit/index.js

@@ -175,4 +175,8 @@ function rateLimitPlugin(options = {}) {
   return plugin;
 }
 
-module.exports = { rateLimitPlugin };
+module.exports = {
+  rateLimitPlugin,
+  loadPeer,
+  resolveLimiterConfig,
+};