domma-cms 0.55.1 → 0.69.3

package/server/services/pluginEntitlement.js

@@ -0,0 +1,171 @@
+/**
+ * Entitlement verification - may this plugin run here?
+ *
+ * Only asked of a plugin declaring `closedSource: true`. A plugin the user wrote
+ * has no entitlement, needs none, and must never be asked for one: the gate keys
+ * on a flag WE set on OUR paid plugins, so the free builder is untouched by all
+ * of this.
+ *
+ * The two commercial models expire in completely different ways, and getting it
+ * backwards is the mistake with real consequences:
+ *
+ *   rental     a managed site pays monthly. Past its term plus grace, it stops.
+ *   perpetual  bought outright. It NEVER stops. What lapses is support and
+ *              updates - so a customer who paid a large sum once and declined
+ *              the renewal keeps what they bought, forever, offline.
+ *
+ * A wildcard entitlement (`slug: "*"`) satisfies any slug. That is how an owner
+ * instance works: the manager is where plugins are written, so a plugin being
+ * built today has no slug in any ledger and a per-slug entitlement could not
+ * name it.
+ *
+ * @module server/services/pluginEntitlement
+ */
+import {createPublicKey, verify as cryptoVerify} from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import {trustedKey} from './pluginInstaller.js';
+
+/**
+ * Canonical JSON: keys sorted at every depth, no whitespace, undefined dropped.
+ *
+ * A deliberate verbatim copy of the signer's, in dcms-marketplace's
+ * scripts/entitlement.js. The signature is over bytes, and a verifier that
+ * disagrees by one space rejects everything for a reason nobody can see. It is
+ * duplicated rather than shared because the signer is not, and must not be, a
+ * dependency of the CMS.
+ *
+ * @param   {unknown} value
+ * @returns {string}
+ */
+export function canonicalise(value) {
+    if (Array.isArray(value)) {
+        return '[' + value.map(canonicalise).join(',') + ']';
+    }
+    if (value && typeof value === 'object') {
+        const keys = Object.keys(value).filter(k => value[k] !== undefined).sort();
+        return '{' + keys.map(k => JSON.stringify(k) + ':' + canonicalise(value[k])).join(',') + '}';
+    }
+    return JSON.stringify(value);
+}
+
+/** Does this entitlement cover the named plugin? */
+export function coversSlug(entitlement, slug) {
+    return entitlement?.slug === '*' || entitlement?.slug === slug;
+}
+
+/**
+ * Find the entitlement covering a plugin.
+ *
+ * Two places, in order:
+ *
+ *   1. `plugins/<slug>/.entitlement.json` - what an envelope carried in. One
+ *      plugin, one licence, sitting beside the thing it licenses.
+ *   2. `config/entitlements/*.json` - INSTANCE level. This is where an owner
+ *      wildcard lives, and it has to be here rather than in a plugin directory:
+ *      a wildcard filed under one plugin would cover that plugin only, which
+ *      defeats the whole point of it.
+ *
+ * A per-plugin file wins. It is the more specific claim, and it is the one a
+ * renewal writes.
+ *
+ * @param   {string} slug
+ * @returns {object|null}
+ */
+export function readEntitlement(slug) {
+    const own = path.join(path.resolve('plugins'), slug, '.entitlement.json');
+    try {
+        return JSON.parse(fs.readFileSync(own, 'utf8'));
+    } catch { /* fall through to the instance level */ }
+
+    const dir = path.resolve('config', 'entitlements');
+    let names;
+    try {
+        names = fs.readdirSync(dir).filter(n => n.endsWith('.json')).sort();
+    } catch {
+        return null;
+    }
+    for (const name of names) {
+        try {
+            const e = JSON.parse(fs.readFileSync(path.join(dir, name), 'utf8'));
+            if (coversSlug(e, slug)) return e;
+        } catch { /* a malformed file is not an entitlement */ }
+    }
+    return null;
+}
+
+/**
+ * Classify a plugin's entitlement.
+ *
+ * Returns one of:
+ *   'valid'          load it
+ *   'grace'          load it, and say so - a rental just past its term
+ *   'support-ended'  load it - a perpetual licence whose updates have stopped
+ *   'expired'        do NOT load - a rental past its grace period
+ *   'unlicensed'     do NOT load - absent, malformed, or not signed by us
+ *
+ * @param   {string} slug
+ * @param   {object|null} [entitlement] - injectable for testing
+ * @param   {Date}   [now]
+ * @returns {{state: string, reason: string, entitlement: object|null}}
+ */
+export function classifyEntitlement(slug, entitlement = readEntitlement(slug), now = new Date()) {
+    if (!entitlement) {
+        return {state: 'unlicensed', reason: 'no entitlement file', entitlement: null};
+    }
+    if (!coversSlug(entitlement, slug)) {
+        return {state: 'unlicensed', reason: `entitlement is for "${entitlement.slug}"`, entitlement};
+    }
+
+    const pem = trustedKey(entitlement.keyId);
+    if (!pem) {
+        return {state: 'unlicensed', reason: `unknown signing key "${entitlement.keyId}"`, entitlement};
+    }
+
+    const {signature, ...rest} = entitlement;
+    let ok = false;
+    try {
+        ok = cryptoVerify(null, Buffer.from(canonicalise(rest), 'utf8'),
+            createPublicKey(pem), Buffer.from(String(signature), 'base64'));
+    } catch {
+        ok = false;
+    }
+    if (!ok) return {state: 'unlicensed', reason: 'signature does not verify', entitlement};
+
+    const ms = now.getTime();
+    const graceMs = (Number(entitlement.gracePeriodDays) || 0) * 86_400_000;
+
+    if (entitlement.model === 'rental') {
+        const end = Date.parse(entitlement.expiresAt);
+        if (!Number.isFinite(end)) {
+            return {state: 'unlicensed', reason: 'rental with no expiry', entitlement};
+        }
+        if (ms <= end) return {state: 'valid', reason: '', entitlement};
+        if (ms <= end + graceMs) return {state: 'grace', reason: 'rental term ended', entitlement};
+        return {state: 'expired', reason: 'rental term and grace period ended', entitlement};
+    }
+
+    // Perpetual. Support may have lapsed; the licence has not, and never will.
+    const support = Date.parse(entitlement.supportExpiresAt);
+    if (Number.isFinite(support) && ms > support) {
+        return {state: 'support-ended', reason: 'support and updates ended', entitlement};
+    }
+    return {state: 'valid', reason: '', entitlement};
+}
+
+/** The states that let a plugin load. */
+const LOADABLE = new Set(['valid', 'grace', 'support-ended']);
+
+/**
+ * May this plugin load?
+ *
+ * @param   {object} manifest
+ * @returns {{allowed: boolean, state: string, reason: string}}
+ */
+export function mayLoad(manifest) {
+    if (manifest?.closedSource !== true) {
+        return {allowed: true, state: 'not-required', reason: ''};
+    }
+    const {state, reason} = classifyEntitlement(manifest.name);
+    return {allowed: LOADABLE.has(state), state, reason};
+}

package/server/services/pluginEnvelope.js

@@ -0,0 +1,242 @@
+/**
+ * The `.dcmsplugin` envelope - one file a plugin travels in.
+ *
+ * A gzipped tar carrying three members at the top level:
+ *
+ *   plugin.tar.gz      the plugin directory, the same bytes the catalogue ships
+ *   plugin.sig         detached Ed25519 signature over plugin.tar.gz, base64.
+ *                      OPTIONAL: an export from a running CMS cannot be signed,
+ *                      because the marketplace key is offline and never on a
+ *                      customer's host.
+ *   entitlement.json   OPTIONAL: present on a paid download, absent on an export
+ *
+ * One format for all three delivery paths - catalogue bundle, paid download, and
+ * a plain export between two installations - so every one of them enters through
+ * the same installer and gets the same traversal guard, manifest validation and
+ * cleanup on failure. A second "just unzip it" path would be the one that skips a
+ * check.
+ *
+ * Tar is written and read here rather than shelled out to, because a CMS is not
+ * guaranteed to have the binary and because `extractTar` in pluginInstaller.js
+ * deliberately strips the leading path component - correct for a plugin tarball,
+ * wrong for an envelope whose members sit at the root. The two readers answer
+ * different questions and are kept apart on purpose.
+ *
+ * @module server/services/pluginEnvelope
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import zlib from 'zlib';
+
+const BLOCK = 512;
+
+/**
+ * A ustar header for one member.
+ *
+ * Names are capped at 100 bytes, which is the format's own limit and not worth
+ * the GNU long-name extension for three fixed filenames.
+ *
+ * @param   {string} name
+ * @param   {number} size
+ * @returns {Buffer}
+ */
+function header(name, size) {
+    if (Buffer.byteLength(name) > 100) throw new Error(`envelope member name too long: ${name}`);
+    const h = Buffer.alloc(BLOCK);
+    h.write(name, 0, 100, 'utf8');
+    h.write('0000644\0', 100);                       // mode
+    h.write('0000000\0', 108);                       // uid
+    h.write('0000000\0', 116);                       // gid
+    h.write(size.toString(8).padStart(11, '0') + '\0', 124);
+    // Fixed mtime: the envelope's bytes should depend on its contents and
+    // nothing else, so the same plugin exported twice compares equal.
+    h.write('00000000000\0', 136);
+    h.write('        ', 148);                        // checksum placeholder
+    h.write('0', 156);                               // type: regular file
+    h.write('ustar\0', 257);
+    h.write('00', 263);
+
+    let sum = 0;
+    for (const b of h) sum += b;
+    h.write(sum.toString(8).padStart(6, '0') + '\0 ', 148);
+    return h;
+}
+
+/** Pad a buffer up to the next 512-byte boundary. */
+function pad(buf) {
+    const over = buf.length % BLOCK;
+    return over === 0 ? buf : Buffer.concat([buf, Buffer.alloc(BLOCK - over)]);
+}
+
+/**
+ * What never travels in an export.
+ *
+ * `data/` is the site's runtime state, not the plugin's - the same carve-out the
+ * npm package and the catalogue build both make. `CLAUDE.md` is working notes.
+ */
+export const EXPORT_EXCLUDES = new Set(['data', 'backups', 'node_modules', 'CLAUDE.md', '.DS_Store']);
+
+/**
+ * Tar a plugin directory into the shape `pluginInstaller.extractTar()` expects:
+ * every entry under a single leading component, which that parser strips.
+ *
+ * Sorted, with a fixed mtime, so the same plugin exported twice produces
+ * identical bytes - which is what lets two exports be compared at all.
+ *
+ * @param   {string}   dir      - absolute plugin directory
+ * @param   {string}   prefix   - the leading component, normally the slug
+ * @param   {{includeData?: boolean}} [opts]
+ * @returns {Promise<Buffer>} gzipped tar
+ */
+export async function tarDirectory(dir, prefix, {includeData = false} = {}) {
+    const files = [];
+    async function walk(abs, rel) {
+        const entries = await fs.readdir(abs, {withFileTypes: true});
+        for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+            const skip = EXPORT_EXCLUDES.has(e.name) && !(includeData && e.name === 'data');
+            if (skip) continue;
+            const next = rel ? `${rel}/${e.name}` : e.name;
+            // Symlinks are neither followed nor recorded: extractTar ignores them
+            // on the way in, so carrying one would only ever be a surprise.
+            if (e.isSymbolicLink()) continue;
+            if (e.isDirectory()) await walk(path.join(abs, e.name), next);
+            else if (e.isFile()) files.push([next, await fs.readFile(path.join(abs, e.name))]);
+        }
+    }
+    await walk(dir, '');
+
+    const chunks = [];
+    for (const [rel, body] of files) {
+        chunks.push(header(`${prefix}/${rel}`, body.length), pad(body));
+    }
+    chunks.push(Buffer.alloc(BLOCK * 2));
+    return zlib.gzipSync(Buffer.concat(chunks), {level: 9});
+}
+
+/**
+ * Build an envelope.
+ *
+ * @param   {{tarball: Buffer, signature?: string|null, entitlement?: object|null}} parts
+ * @returns {Buffer} gzipped tar
+ */
+export function packEnvelope({tarball, signature = null, entitlement = null}) {
+    if (!Buffer.isBuffer(tarball) || !tarball.length) {
+        throw new Error('packEnvelope: tarball is required');
+    }
+    const members = [['plugin.tar.gz', tarball]];
+    if (signature) members.push(['plugin.sig', Buffer.from(String(signature), 'utf8')]);
+    if (entitlement) {
+        members.push(['entitlement.json', Buffer.from(JSON.stringify(entitlement, null, 2) + '\n', 'utf8')]);
+    }
+
+    const chunks = [];
+    for (const [name, body] of members) {
+        chunks.push(header(name, body.length), pad(body));
+    }
+    chunks.push(Buffer.alloc(BLOCK * 2));            // end-of-archive
+    return zlib.gzipSync(Buffer.concat(chunks), {level: 9});
+}
+
+/**
+ * Read the manifest out of a plugin tarball, without extracting it.
+ *
+ * The slug an upload installs under comes from here, never from the uploaded
+ * filename: a file can be renamed by anyone, a manifest is the thing the
+ * installer then validates against what was extracted.
+ *
+ * @param   {Buffer} tarball - gzipped tar with a single leading component
+ * @returns {object|null} the parsed manifest, or null if there is not one
+ */
+export function readManifestFromTarball(tarball) {
+    let raw;
+    try {
+        raw = zlib.gunzipSync(tarball);
+    } catch {
+        return null;
+    }
+    let offset = 0;
+    let zeros = 0;
+    while (offset + BLOCK <= raw.length) {
+        const h = raw.subarray(offset, offset + BLOCK);
+        if (h.every(b => b === 0)) {
+            if (++zeros >= 2) break;
+            offset += BLOCK;
+            continue;
+        }
+        zeros = 0;
+        offset += BLOCK;
+        const nul = h.indexOf(0);
+        const name = h.subarray(0, nul === -1 ? 100 : Math.min(nul, 100)).toString('utf8');
+        const size = parseInt(h.subarray(124, 136).toString('utf8').replace(/\0/g, '').trim(), 8) || 0;
+        // `<slug>/plugin.json` and nothing deeper - a plugin.json further down
+        // the tree belongs to something else.
+        if (/^[^/]+\/plugin\.json$/.test(name)) {
+            try {
+                return JSON.parse(raw.subarray(offset, offset + size).toString('utf8'));
+            } catch {
+                return null;
+            }
+        }
+        offset += Math.ceil(size / BLOCK) * BLOCK;
+    }
+    return null;
+}
+
+/**
+ * Read an envelope.
+ *
+ * Refuses anything it does not recognise rather than guessing: an envelope is
+ * our own format, so a member we did not write is a sign the file is not what
+ * the caller thinks it is.
+ *
+ * @param   {Buffer} buffer - the .dcmsplugin file
+ * @returns {{tarball: Buffer, signature: string|null, entitlement: object|null}}
+ */
+export function readEnvelope(buffer) {
+    let raw;
+    try {
+        raw = zlib.gunzipSync(buffer);
+    } catch {
+        throw new Error('Not a .dcmsplugin file: it is not gzipped');
+    }
+
+    const found = new Map();
+    let offset = 0;
+    let zeros = 0;
+    while (offset + BLOCK <= raw.length) {
+        const h = raw.subarray(offset, offset + BLOCK);
+        if (h.every(b => b === 0)) {
+            if (++zeros >= 2) break;
+            offset += BLOCK;
+            continue;
+        }
+        zeros = 0;
+        offset += BLOCK;
+
+        const nul = h.indexOf(0);
+        const name = h.subarray(0, nul === -1 ? 100 : Math.min(nul, 100)).toString('utf8');
+        const size = parseInt(h.subarray(124, 136).toString('utf8').replace(/\0/g, '').trim(), 8) || 0;
+        // Members sit at the root - no directories, no nesting. Anything else is
+        // not an envelope we wrote.
+        if (name && !name.includes('/')) found.set(name, raw.subarray(offset, offset + size));
+        offset += Math.ceil(size / BLOCK) * BLOCK;
+    }
+
+    const tarball = found.get('plugin.tar.gz');
+    if (!tarball) throw new Error('Not a .dcmsplugin file: no plugin.tar.gz inside');
+
+    let entitlement = null;
+    if (found.has('entitlement.json')) {
+        try {
+            entitlement = JSON.parse(found.get('entitlement.json').toString('utf8'));
+        } catch {
+            throw new Error('The entitlement inside this file is not readable JSON');
+        }
+    }
+
+    return {
+        tarball: Buffer.from(tarball),
+        signature: found.has('plugin.sig') ? found.get('plugin.sig').toString('utf8').trim() : null,
+        entitlement
+    };
+}

package/server/services/pluginFiles.js

@@ -7,8 +7,16 @@
  * valid names), paths are normalised and containment-checked after symlink
  * resolution, and only known text extensions are editable.
  *
- * Thrown errors carry `statusCode` (400 invalid, 404 missing, 413 too large)
- * for direct mapping in the route layer.
+ * A plugin marked `"closedSource": true` in its manifest is refused - licensed
+ * code is distributed to a site so it can RUN there, not so it can be read out
+ * of it, and the editor was handing over the server source in full. The one
+ * exception is a SUPER-ADMIN (role level 0), which on the fleet exists only on
+ * the manager: the people who publish the paid plugins are the people who need
+ * to read and edit them. Customer sites are all level 1, so nothing changes
+ * there - see the `allowLicensed` argument, set from the request's user.
+ *
+ * Thrown errors carry `statusCode` (400 invalid, 403 licensed, 404 missing,
+ * 413 too large) for direct mapping in the route layer.
  */
 import fs from 'fs/promises';
 import path from 'path';
@@ -40,7 +48,7 @@ function fail(statusCode, message) {
  * @param {string} name
  * @returns {Promise<string>} Absolute plugin directory
  */
-async function resolvePluginDir(name) {
+async function resolvePluginDir(name, allowLicensed = false) {
     if (!NAME_PATTERN.test(String(name || ''))) throw fail(400, 'Invalid plugin name.');
     const dir = path.join(PLUGINS_DIR, name);
     try {
@@ -49,9 +57,42 @@ async function resolvePluginDir(name) {
     } catch {
         throw fail(404, `Plugin "${name}" not found.`);
     }
+
+    // Every operation in this module goes through here, which is why the check
+    // lives here and not in four places that could drift apart.
+    if (!allowLicensed && await isClosedSource(dir)) {
+        throw fail(403, `"${name}" is a licensed plugin. Its source is not editable here.`);
+    }
     return dir;
 }
 
+/**
+ * Is this plugin's source off limits to the code editor?
+ *
+ * A licensed plugin is distributed to a site so it can RUN there, not so it
+ * can be read and copied - and the editor made it readable AND writable to
+ * anyone holding `plugins.develop`, which on a customer's own site is the
+ * customer. Writable is the worse half: the licence check is in that file.
+ *
+ * Declared by the plugin itself (`"closedSource": true` in plugin.json) so the
+ * flag travels with it wherever it is distributed, rather than depending on a
+ * list somewhere that a new paid plugin would have to be remembered into.
+ *
+ * A manifest that cannot be read is treated as closed. This gate failing open
+ * would publish the very thing it exists to protect.
+ *
+ * @param   {string} dir - absolute plugin directory
+ * @returns {Promise<boolean>}
+ */
+async function isClosedSource(dir) {
+    try {
+        const manifest = JSON.parse(await fs.readFile(path.join(dir, 'plugin.json'), 'utf8'));
+        return manifest.closedSource === true;
+    } catch {
+        return true;
+    }
+}
+
 /**
  * Resolve a relative file path inside the plugin dir, or throw.
  * Rejects absolute paths, traversal, hidden segments and unknown extensions.
@@ -98,8 +139,8 @@ async function resolveFilePath(pluginDir, relPath) {
  * @param {string} name
  * @returns {Promise<Array<{path: string, size: number, modified: string}>>}
  */
-export async function listPluginFiles(name) {
-    const pluginDir = await resolvePluginDir(name);
+export async function listPluginFiles(name, {allowLicensed = false} = {}) {
+    const pluginDir = await resolvePluginDir(name, allowLicensed);
     const files = [];
 
     async function walk(dir) {
@@ -132,8 +173,8 @@ export async function listPluginFiles(name) {
  * @param {string} relPath
  * @returns {Promise<{path: string, content: string}>}
  */
-export async function readPluginFile(name, relPath) {
-    const pluginDir = await resolvePluginDir(name);
+export async function readPluginFile(name, relPath, {allowLicensed = false} = {}) {
+    const pluginDir = await resolvePluginDir(name, allowLicensed);
     const abs = await resolveFilePath(pluginDir, relPath);
 
     let stat;
@@ -158,8 +199,8 @@ export async function readPluginFile(name, relPath) {
  * @param {string} content
  * @returns {Promise<{path: string, restartRequired: boolean}>}
  */
-export async function writePluginFile(name, relPath, content) {
-    const pluginDir = await resolvePluginDir(name);
+export async function writePluginFile(name, relPath, content, {allowLicensed = false} = {}) {
+    const pluginDir = await resolvePluginDir(name, allowLicensed);
     const abs = await resolveFilePath(pluginDir, relPath);
 
     if (typeof content !== 'string') throw fail(400, 'Content must be a string.');
@@ -198,8 +239,8 @@ export async function writePluginFile(name, relPath, content) {
  * @param {string} relPath
  * @returns {Promise<{path: string}>}
  */
-export async function deletePluginFile(name, relPath) {
-    const pluginDir = await resolvePluginDir(name);
+export async function deletePluginFile(name, relPath, {allowLicensed = false} = {}) {
+    const pluginDir = await resolvePluginDir(name, allowLicensed);
     const abs = await resolveFilePath(pluginDir, relPath);
     const rel = path.relative(pluginDir, abs).split(path.sep).join('/');