domma-cms 1.6.60 → 1.7.1

package/docs/superpowers/specs/plans/2026-04-08-plugin-monetisation-split.md

@@ -0,0 +1,242 @@
+# Domma CMS - Plugin Monetisation Split
+
+## Context
+
+Domma CMS (public, distributable via npm) and Domma CMS Manager (private console
+for registration, management, and licensing) currently have a **one-way integration**:
+the manager can push notifications into a CMS instance via `requireManager`
+(HMAC-verified `MANAGER_SECRET`), but the CMS never calls out to the manager.
+
+Plugin development today happens entirely inside `domma-cms`, meaning every plugin
+- including commercial-quality ones - is shipped source-open to anyone who
+`npm install`s the package. That's fine for core plugins but wrong for anything
+we want to monetise.
+
+The goal: formalise a tiered plugin model so core plugins stay free and open in
+`domma-cms`, and paid plugins live privately in `domma-cms-manager` and are
+fetched on demand by licensed CMS instances via a signed registry.
+
+## Current plugin audit
+
+Based on an LOC + scope audit of `plugins/` on 2026-04-08:
+
+| Slug           | LOC  | Recommended tier | Reasoning |
+|----------------|------|------------------|-----------|
+| garage         | 1398 | **MONETISE** - extract first | UK-specific, wraps DVLA API, vertical. Should never have been in the public repo. |
+| calendar       | 2549 | **MONETISE** - confirmed | Recurrence + RSVP + iCal - commercial-grade, comparable to Events Calendar Pro. No live installs to break. |
+| messages       | 1762 | **MONETISE** - confirmed | Real-time 1:1/group chat is unusual for a CMS base. No live installs to break. |
+| docs           | 1506 | **MONETISE** | Document editor + version history overlaps with paid workspace products. |
+| site-search    | 1405 | **UNCERTAIN** | Borderline - keep CORE for launch; sell "SEO Pro" separately later. |
+| theme-switcher | 717  | **UNCERTAIN** | Cosmetic, Domma-branded - keep CORE. |
+| form-builder   | 510  | **SPLIT** - confirmed | Basic form experience (field definitions, submissions, `[form]` shortcode) stays free in core. Visual drag-and-drop "Form Builder Pro" (conditional logic, multi-step, file uploads, webhooks) goes premium. Delete current stub from public repo. |
+| blog           | 2087 | **CORE** | Canonical CMS feature. |
+| contacts       | 1344 | **CORE** | Standard PIM essential. |
+| todo           | 738  | **CORE** | Lightweight essential. |
+| notes          | 616  | **CORE** | Lightweight essential. |
+| analytics      | 243  | **CORE** | Trivial page-hit counter - sell "Analytics Pro" separately. |
+| demo-viewer    | 102  | **CORE** | Marketing shortcode for Domma itself. |
+
+**Headline finding**: ~7.2k LOC of monetisation candidates. `garage` is the most
+urgent to extract - it's both vertical (UK) and wraps an external paid/rate-limited
+API (DVLA).
+
+## Recommended split
+
+### In `domma-cms` (public repo, forever free)
+
+- Core plugins: `blog`, `contacts`, `todo`, `notes`, `analytics`, `demo-viewer`,
+  `site-search`, `theme-switcher`
+- **Basic forms**: form definitions, submissions, `[form slug="..."]` shortcode - the
+  primitive already exists (`content/forms/`, `server/services/forms.js`). No builder UI,
+  no drag-drop, no conditional logic.
+- `_template/` + `scripts/create-plugin.js`
+- The **plugin loader + lifecycle** (`server/services/plugins.js`)
+- The **plugin installer + manager client** (code that fetches paid plugins),
+  so any licensed customer can install paid plugins without extra setup
+
+### In `domma-cms-manager` (private repo, paid)
+
+- Author paid plugins inside a private `plugins/` directory mirroring the same
+  shape as the public repo's `_template/`
+- **Plugin registry** table: slug → versions → price → entitlements
+- **Signed package builder** - bundle + sign on push
+- **Authenticated download endpoint** - `/api/plugins/install/<slug>` that
+  returns a signed tar.gz when the caller presents a valid licence token
+- **Signing key** - held by the manager only, hardware-backed ideally
+
+## Architecture: installer & manager client
+
+Two new services added to **`domma-cms`** so any installed instance can fetch
+paid plugins once its owner has entitlements.
+
+### `server/services/managerClient.js` - outbound HMAC client
+
+Mirror of the inbound `managerAuth.js` shape.
+
+```js
+/**
+ * Client for outbound calls from domma-cms → domma-cms-manager.
+ * Reads MANAGER_URL and INSTANCE_SECRET from env; never hard-codes the manager URL.
+ */
+
+export async function registerInstance(fingerprint) {
+    // POST {MANAGER_URL}/api/instances/register
+    // Body: { fingerprint, cmsVersion, hostname }
+    // Headers: X-Instance-Token: HMAC(INSTANCE_SECRET, fingerprint)
+    // Returns: { licenseToken, instanceId }
+}
+
+export async function fetchCatalogue(licenseToken) {
+    // GET {MANAGER_URL}/api/plugins/catalogue
+    // Headers: Authorization: Bearer <licenseToken>
+    // Returns: [{ slug, version, displayName, description, price, entitled }]
+}
+
+export async function fetchPluginBundle(slug, version, licenseToken) {
+    // GET {MANAGER_URL}/api/plugins/install/<slug>/<version>
+    // Headers: Authorization: Bearer <licenseToken>
+    // Returns: { tarball: Buffer, signature: string, publicKeyId: string }
+}
+
+export async function heartbeat(licenseToken, installedSlugs) {
+    // POST {MANAGER_URL}/api/instances/heartbeat
+    // Body: { installedSlugs, versions }
+    // Used for revocation + usage analytics (opt-in)
+}
+```
+
+**Environment variables** added to `.env`:
+- `MANAGER_URL` - base URL of the manager (no trailing slash)
+- `INSTANCE_SECRET` - 32-byte hex string generated at first run by `scripts/setup.js`
+- Existing `MANAGER_SECRET` stays for inbound push notifications - two separate secrets
+
+### `server/services/pluginInstaller.js` - verify + extract + lifecycle
+
+```js
+/**
+ * Installs a plugin bundle fetched from the manager.
+ * Verifies the signature against a pinned public key before extracting.
+ */
+
+import { verify as verifySignature } from 'crypto';
+
+// Pinned public keys (baked into the CMS release, rotated via version bumps)
+const TRUSTED_KEYS = {
+    'manager-2026': '-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----'
+};
+
+export async function installPlugin(slug, { tarball, signature, publicKeyId }) {
+    // 1. Verify signature
+    const pubKey = TRUSTED_KEYS[publicKeyId];
+    if (!pubKey) throw new Error(`Unknown public key: ${publicKeyId}`);
+    const ok = verifySignature('sha256', tarball, pubKey, Buffer.from(signature, 'base64'));
+    if (!ok) throw new Error('Plugin signature invalid - refusing to install');
+
+    // 2. Refuse path traversal - tar entries must stay under plugins/<slug>/
+    // 3. Extract to plugins/<slug>/ (reject if target already exists)
+    // 4. Validate manifest via discoverPlugins() → must load cleanly
+    // 5. Update config/plugins.json with { enabled: false, settings: {} }
+    // 6. Run onEnable lifecycle hook via runLifecycleHook(slug, 'onEnable', fastify)
+    // 7. Log install + version to instances_log.json (audit trail)
+}
+
+export async function uninstallPlugin(slug) {
+    // 1. Run onDisable lifecycle hook
+    // 2. Remove plugins/<slug>/ directory
+    // 3. Remove entry from config/plugins.json
+    // 4. Log uninstall
+}
+```
+
+### Admin UI addition
+
+Extend the existing `admin/js/views/plugins.js` with a **"Marketplace"** tab:
+
+- Lists the manager catalogue via `GET /api/plugins/marketplace` (new route that
+  proxies `managerClient.fetchCatalogue()`)
+- "Install" button on entitled plugins → `POST /api/plugins/marketplace/install`
+  which wraps `pluginInstaller.installPlugin()`
+- "Uninstall" button on installed plugins from the manager
+- Hides entirely if `MANAGER_URL` is unset
+
+## Extraction workflow (for paid plugins already in public repo)
+
+For each plugin to extract (`garage`, `docs`, and - pending Darryl's call -
+`calendar`, `messages`):
+
+1. **Copy the directory** into `domma-cms-manager`'s private plugins dir
+2. **Rewrite git history in `domma-cms`**: `git filter-repo --path plugins/<slug>/ --invert-paths` on a fresh clone, force-push to a `plugins-removed` branch. This is the only git operation that requires user confirmation.
+3. **Delete from the current tree**: `git rm -r plugins/<slug>/`
+4. **Remove from `config/plugins.json`** if present
+5. **Release a minor version bump** of `domma-cms` (0.11.x → 0.12.0) noting
+   the plugin removal in the CHANGELOG
+6. **Verify**: run `npm run build` + existing Calendar/Messages manual test
+   smoke check; check that no core code references the removed plugin slug
+
+**Important**: step 2 is history rewriting and will require a co-ordinated
+force-push. Do not run it without explicit confirmation. Until then, the
+source of extracted plugins remains visible in git history even after removal
+from `HEAD` - treat the extraction as mitigation, not cure.
+
+## Critical files
+
+**Create (in `domma-cms`):**
+- `server/services/managerClient.js` - outbound HMAC client
+- `server/services/pluginInstaller.js` - verify + extract + lifecycle
+- `server/routes/api/plugin-marketplace.js` - `/api/plugins/marketplace` routes
+- `admin/js/views/plugin-marketplace.js` - Marketplace tab view
+- `scripts/gen-instance-secret.js` - generates `INSTANCE_SECRET` on first setup
+
+**Edit (in `domma-cms`):**
+- `scripts/setup.js` - generate `INSTANCE_SECRET` during setup
+- `admin/js/views/plugins.js` - wire in Marketplace tab
+- `server/server.js` - register `/api/plugins/marketplace` routes
+- `.env.example` - document `MANAGER_URL`, `INSTANCE_SECRET`
+- `config/plugins.json` - extracted plugins removed
+
+**Create (in `domma-cms-manager`):**
+- Private `plugins/` directory mirroring the `_template/` shape
+- Build pipeline: test → minify → tar.gz → sign → upload to blob store
+- `/api/instances/register`, `/api/instances/heartbeat` routes
+- `/api/plugins/catalogue`, `/api/plugins/install/:slug/:version` routes
+- Customer entitlements table (schema TBD in manager's own plan)
+
+## Decisions (all confirmed 2026-04-08)
+
+1. ✅ **Calendar** - **MONETISE**. No live installs to break.
+2. ✅ **Messages** - **MONETISE**. No live installs to break.
+3. ✅ **`form-builder` stub** - **SPLIT**. Basic form experience (definitions, submissions,
+   `[form]` shortcode) stays free. Visual drag-and-drop "Form Builder Pro" goes premium
+   in manager. Delete the current stub from the public repo.
+4. ✅ **Public key rotation** - pinned-by-version for v1.
+5. ✅ **Entitlement cache TTL** - 30 days offline.
+6. ✅ **Telemetry / heartbeat** - opt-in, disabled by default.
+
+## Verification
+
+After installer plumbing lands in `domma-cms`:
+
+1. Unset `MANAGER_URL` → Marketplace tab hidden, rest of admin unaffected.
+2. Set `MANAGER_URL` to a stub server returning fixture data → Marketplace tab
+   shows fixture plugins.
+3. Install a test plugin via stub - verify signature rejection path: tamper with
+   the tarball by one byte and confirm install fails loudly.
+4. Install a test plugin with valid signature - verify `plugins/<slug>/` appears,
+   `config/plugins.json` updated, `onEnable` hook ran.
+5. Uninstall - verify directory removed, `onDisable` ran, `config/plugins.json`
+   cleaned up.
+6. Existing core plugins (`blog`, `notes`, etc.) remain unaffected throughout.
+
+After extraction of paid plugins from public repo:
+
+7. `git log -- plugins/garage/` returns nothing after history rewrite.
+8. Fresh clone of public repo has no `plugins/garage/` directory.
+9. `_publish/` build succeeds with no references to extracted plugins.
+
+## Out of scope for this plan
+
+- **Manager-side implementation** - the private repo has its own planning track
+- **Payment processing** - Stripe integration, invoicing, dunning etc. all live in manager
+- **Customer dashboard for manager** - manager's own admin UI
+- **Auto-update of installed paid plugins** - v1 = manual click, auto-update is v2
+- **Rewriting existing inbound `managerAuth.js`** - stays as-is, it's orthogonal