domma-cms 0.66.0 → 0.69.3

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/pluginInstaller.js

@@ -15,7 +15,9 @@ import fs from 'fs/promises';
 import path from 'path';
 import zlib from 'zlib';
 import {fileURLToPath} from 'url';
-import {discoverPlugins} from './plugins.js';
+import {getConfig} from '../config.js';
+import {discoverPlugins, validatePluginDir} from './plugins.js';
+import {allowInGitignore, manifestContentPaths, pluginContentRules} from './siteGitignore.js';
 
 // ---------------------------------------------------------------------------
 // Paths
@@ -27,26 +29,100 @@ const CONFIG_PATH = path.join(ROOT, 'config', 'plugins.json');
 const AUDIT_LOG   = path.join(ROOT, 'content', 'instances_log.json');
 
 // ---------------------------------------------------------------------------
-// Trusted public keys - rotate by adding new keyId + bumping CMS version
-// Private key counterpart: domma-cms-manager/config/keys/plugin-signing-2026.pem
+// Trusted public keys
+//
+// Ed25519. Rotation is pinned by CMS version: a release trusts the keys listed
+// here and nothing else, so a bundle signed by a key this version has never
+// heard of is refused by keyId before its signature is even checked.
+//
+// `manager-2026` was REMOVED rather than retained. Its private half could not be
+// found, and a key we cannot find is not one we know to be destroyed - leaving
+// its public half here would mean anyone who does have it can sign a bundle
+// every CMS accepts as ours, permanently. Nothing had ever been signed with it,
+// so there was no artifact to stay compatible with.
+//
+// Private counterpart: generated 2026-09-22, held off-repo. See the marketplace
+// design's Signing keys section for custody.
 // ---------------------------------------------------------------------------
 
 const TRUSTED_KEYS = {
-    'manager-2026': `-----BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEArmEogar77p4RwljMgEsi
-zSJRXIvRe8LDNzHvoez9gOu0SYUd2O8nsDOiLohsPxhH5+c8eXdBOkH+1y1O5QaN
-TmZTRGrRR0NrxhPVTT7trtJIiXH4IwgwWgzYVmCKOdKqX4wj2JwGbiPE57ubOBKE
-4T66OUIZmezSYYkhPmWAUCWmCX9KxL6czbMtNZYIn9U2O04imD/VtBieB4xCZy0P
-U9vE3Uz4bcjLjjo70+oWXtAuudlLUiMREJKcT6J72CZSW6rzuR1+NDJsh4q5C6jd
-e+B83PU+WiFxNwoHHJ91myEY4vDDWDDYV8G+sS/4QzBOgL9StwwvQzBuriWKjl8J
-eQIDAQAB
+    'marketplace-1': `-----BEGIN PUBLIC KEY-----
+MCowBQYDK2VwAyEAkgYWv0IckLy2lCeNoaNot++KMJLpJa6FTd6RW0sH2zg=
 -----END PUBLIC KEY-----`
 };
 
+/**
+ * Does this site refuse anything the marketplace has not signed?
+ *
+ * Default false, because a CMS whose own scaffolder produces unsigned plugins
+ * cannot refuse unsigned plugins without refusing its user's own work. A fleet
+ * site should set it true: everything it receives arrives by push-copy, and
+ * nothing legitimate is ever uploaded there.
+ *
+ * @returns {boolean}
+ */
+function requireSignedPlugins() {
+    try {
+        return getConfig('server')?.requireSignedPlugins === true;
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * One trusted public key by id, or null.
+ *
+ * Entitlement verification needs the same keys bundle installation does, and a
+ * second copy of them would be a second thing to rotate.
+ *
+ * @param   {string} keyId
+ * @returns {string|null} PEM
+ */
+export function trustedKey(keyId) {
+    return TRUSTED_KEYS[keyId] ?? null;
+}
+
+/**
+ * The keyIds this CMS version trusts.
+ *
+ * Exported so the contract is testable without exposing key material: a release
+ * trusting a key it should not, or having lost the one it should, is the kind of
+ * mistake that is invisible until a bundle is refused in the field.
+ *
+ * @returns {string[]}
+ */
+export function trustedKeyIds() {
+    return Object.keys(TRUSTED_KEYS);
+}
+
 // ---------------------------------------------------------------------------
 // Internal helpers
 // ---------------------------------------------------------------------------
 
+/**
+ * Compare two dotted version strings. -1, 0 or 1.
+ *
+ * Deliberately not semver-complete: it compares numeric segments and ignores
+ * pre-release tags. Plugin versions here are plain x.y.z, and pulling in a
+ * semver dependency to compare three integers would be the worse trade. A
+ * segment that is not a number sorts as 0, so a nonsense version loses to a
+ * real one rather than throwing.
+ *
+ * @param   {string} a
+ * @param   {string} b
+ * @returns {number}
+ */
+export function compareVersions(a, b) {
+    const parse = v => String(v ?? '').split('.').map(x => parseInt(x, 10) || 0);
+    const av = parse(a);
+    const bv = parse(b);
+    for (let i = 0; i < Math.max(av.length, bv.length); i++) {
+        const d = (av[i] ?? 0) - (bv[i] ?? 0);
+        if (d !== 0) return d > 0 ? 1 : -1;
+    }
+    return 0;
+}
+
 /**
  * Append a single record to the audit log, creating the file if absent.
  *
@@ -167,33 +243,61 @@ async function extractTar(tarBuffer, slug, destDir) {
  *   6. Run onEnable lifecycle hook (warn-only on failure)
  *   7. Append install record to audit log
  *
+ * A bundle from the marketplace is signed. One exported from a running CMS
+ * cannot be - the signing key is offline and never on a customer's host - so an
+ * UNSIGNED bundle is accepted only when the caller has explicitly said so and
+ * the site has not set `requireSignedPlugins`. A bundle carrying a signature
+ * that does not verify is always refused: a broken signature means tampering,
+ * never "unsigned".
+ *
  * @param {string} slug
- * @param {{ tarball: Buffer, signature: string, publicKeyId: string }} options
+ * @param {{ tarball: Buffer, signature?: string|null, publicKeyId?: string|null,
+ *           allowUnsigned?: boolean, entitlement?: object|null,
+ *           allowUpgrade?: boolean, allowDowngrade?: boolean }} options
  * @returns {Promise<void>}
+ * @returns {Promise<{slug: string, action: string, from: string|null, version: string}>}
  * @throws {Error} If signature is invalid, slug is already installed, or manifest validation fails
  */
-export async function installPlugin(slug, { tarball, signature, publicKeyId }) {
+/**
+ * A distributed plugin is ignored by the site's .gitignore, but one that keeps
+ * what users AUTHOR inside its own folder (plugin.json `contentPaths`) must
+ * have those folders tracked, or the site repo silently loses that work.
+ */
+function trackPluginContent(slug, manifest) {
+    const rules = manifestContentPaths(manifest).flatMap(rel => pluginContentRules(slug, rel));
+    if (rules.length) allowInGitignore(ROOT, rules);
+}
+
+export async function installPlugin(slug, { tarball, signature, publicKeyId, allowUnsigned = false, entitlement = null, allowUpgrade = false, allowDowngrade = false }) {
     if (!/^[a-z0-9][a-z0-9-_]{0,63}$/.test(slug)) {
         throw new Error(`Invalid plugin slug: ${slug}`);
     }
 
-    // Step 1 - Verify signature
-    const pubKeyPem = TRUSTED_KEYS[publicKeyId];
-    if (!pubKeyPem) {
-        throw new Error(`Unknown public key: ${publicKeyId}`);
+    // Step 1 - Verify signature, or establish that there is deliberately none.
+    const unsigned = !signature;
+    if (unsigned) {
+        if (!allowUnsigned) {
+            throw new Error('This plugin is unsigned. Installing it runs its code on this server, so it has to be confirmed.');
+        }
+        if (requireSignedPlugins()) {
+            throw new Error('This site accepts signed plugins only (server.json: requireSignedPlugins).');
+        }
     }
 
-    if (pubKeyPem.includes('PLACEHOLDER')) {
-        throw new Error(`pluginInstaller: TRUSTED_KEYS['${publicKeyId}'] is a placeholder - not usable for verification`);
+    const pubKeyPem = unsigned ? null : TRUSTED_KEYS[publicKeyId];
+    if (!unsigned && !pubKeyPem) {
+        throw new Error(`Unknown public key: ${publicKeyId}`);
     }
 
-    const signatureBuffer = Buffer.from(signature, 'base64');
-    const valid = crypto.verify('sha256', tarball, pubKeyPem, signatureBuffer);
-    if (!valid) {
+    const signatureBuffer = unsigned ? null : Buffer.from(signature, 'base64');
+    // Ed25519 takes no digest argument - the algorithm is implied by the key.
+    // Passing one throws ERR_OSSL_INVALID_DIGEST rather than degrading quietly,
+    // which is the property that makes a half-finished edit here fail loudly.
+    if (!unsigned && !crypto.verify(null, tarball, pubKeyPem, signatureBuffer)) {
         throw new Error('Plugin signature invalid - refusing to install');
     }
 
-    // Step 2 - Reject if already installed
+    // Step 2 - Already installed? Either refuse, or upgrade in place.
     const destDir = path.join(PLUGINS_DIR, slug);
     let alreadyExists = false;
     try {
@@ -202,9 +306,12 @@ export async function installPlugin(slug, { tarball, signature, publicKeyId }) {
     } catch {
         // Not present - proceed
     }
-    if (alreadyExists) {
+    if (alreadyExists && !allowUpgrade) {
         throw new Error(`Plugin already installed: ${slug}`);
     }
+    if (alreadyExists) {
+        return upgradePlugin(slug, {tarball, unsigned, entitlement, allowDowngrade});
+    }
 
     // Step 3 - Decompress + extract
     await fs.mkdir(destDir, { recursive: true });
@@ -243,13 +350,126 @@ export async function installPlugin(slug, { tarball, signature, publicKeyId }) {
         console.warn(`[pluginInstaller] onEnable hook for "${slug}" failed: ${err.message}`);
     }
 
-    // Step 7 - Audit log
+    // Step 7 - Entitlement, if the envelope carried one. Written beside the
+    // plugin so it travels with it and a renewal is a file drop.
+    if (entitlement) {
+        await fs.writeFile(path.join(destDir, '.entitlement.json'),
+            JSON.stringify(entitlement, null, 2) + '\n', 'utf8');
+    }
+
+    // Step 8 - Audit log. An unsigned install is recorded as such: it is the one
+    // that was a judgement call rather than a verified fact.
     await writeAuditLog({
-        action: 'install',
+        action: unsigned ? 'install:unsigned' : 'install',
         slug,
         version: manifest.version,
         timestamp: new Date().toISOString()
     });
+
+    trackPluginContent(slug, manifest);
+
+    return {slug, action: 'install', from: null, version: manifest.version};
+}
+
+/**
+ * Upgrade a plugin already installed.
+ *
+ * The order is the whole point. Extract and validate the NEW version before the
+ * old one is disturbed, so a broken upgrade is refused with the working
+ * installation still in place. Only then swap, and only then delete the backup.
+ *
+ * Runtime `data/` moves across rather than being replaced: it belongs to the
+ * site, not to the version. A plugin that kept its notes in data/ and lost them
+ * on every update would be worse than one that could not update at all.
+ *
+ * On any failure after the swap begins, the previous directory goes back. The
+ * one state this must never produce is "neither version installed".
+ *
+ * @param   {string} slug
+ * @param   {{tarball: Buffer, unsigned: boolean, entitlement: object|null, allowDowngrade: boolean}} opts
+ * @returns {Promise<{slug: string, action: string, from: string|null, version: string}>}
+ */
+async function upgradePlugin(slug, {tarball, unsigned, entitlement, allowDowngrade}) {
+    const destDir  = path.join(PLUGINS_DIR, slug);
+    const incoming = path.join(PLUGINS_DIR, `.${slug}.incoming`);
+    const backup   = path.join(PLUGINS_DIR, `.${slug}.backup`);
+
+    const current = await validatePluginDir(destDir, slug);
+
+    // 1. Extract the new version somewhere harmless.
+    await fs.rm(incoming, {recursive: true, force: true});
+    await fs.mkdir(incoming, {recursive: true});
+    try {
+        await extractTar(zlib.gunzipSync(tarball), slug, incoming);
+    } catch (err) {
+        await fs.rm(incoming, {recursive: true, force: true});
+        throw err;
+    }
+
+    // 2. Validate it BEFORE anything is disturbed.
+    const next = await validatePluginDir(incoming, slug);
+    if (!next.ok) {
+        await fs.rm(incoming, {recursive: true, force: true});
+        throw new Error(`Refusing to upgrade ${slug}: the new version is ${next.reason}`);
+    }
+
+    const from = current.manifest?.version;
+    const to = next.manifest.version;
+    if (current.ok && compareVersions(to, from) < 0 && !allowDowngrade) {
+        await fs.rm(incoming, {recursive: true, force: true});
+        throw new Error(`Refusing to downgrade ${slug} from ${from} to ${to}.`);
+    }
+
+    // 3. Carry the site's data across.
+    const dataDir = path.join(destDir, 'data');
+    let hasData = false;
+    try {
+        await fs.access(dataDir);
+        hasData = true;
+    } catch { /* nothing to carry */ }
+    if (hasData) {
+        await fs.rm(path.join(incoming, 'data'), {recursive: true, force: true});
+        await fs.cp(dataDir, path.join(incoming, 'data'), {recursive: true});
+    }
+    // The entitlement belongs to the installation, not the version - a renewal
+    // dropped in yesterday must survive today's update.
+    const entFile = path.join(destDir, '.entitlement.json');
+    let carriedEntitlement = null;
+    try {
+        carriedEntitlement = await fs.readFile(entFile, 'utf8');
+    } catch { /* none */ }
+
+    // 4. Swap. From here a failure must put the old version back.
+    await fs.rm(backup, {recursive: true, force: true});
+    await fs.rename(destDir, backup);
+    try {
+        await fs.rename(incoming, destDir);
+    } catch (err) {
+        await fs.rename(backup, destDir).catch(() => {});
+        await fs.rm(incoming, {recursive: true, force: true});
+        throw new Error(`Upgrade of ${slug} failed and the previous version was restored: ${err.message}`);
+    }
+
+    if (entitlement) {
+        await fs.writeFile(path.join(destDir, '.entitlement.json'),
+            JSON.stringify(entitlement, null, 2) + '\n', 'utf8');
+    } else if (carriedEntitlement !== null) {
+        await fs.writeFile(path.join(destDir, '.entitlement.json'), carriedEntitlement, 'utf8');
+    }
+
+    await fs.rm(backup, {recursive: true, force: true});
+
+    await writeAuditLog({
+        action: unsigned ? 'upgrade:unsigned' : 'upgrade',
+        slug,
+        from: from ?? null,
+        version: to,
+        timestamp: new Date().toISOString()
+    });
+
+    trackPluginContent(slug, next.manifest);
+
+    return {slug, action: 'upgrade', from: from ?? null, version: to};
 }
 
 /**

package/server/services/pluginScaffold.js

@@ -11,6 +11,7 @@
  */
 import fs from 'fs/promises';
 import path from 'path';
+import {allowInGitignore, sitePluginRules} from './siteGitignore.js';
 
 const PLUGINS_DIR = path.resolve('plugins');
 const TEMPLATE_DIR = path.join(PLUGINS_DIR, '_template');
@@ -132,5 +133,9 @@ export async function scaffoldPlugin(input) {
         await fs.writeFile(manifestPath, JSON.stringify(manifest, null, 2) + '\n', 'utf8');
     }
 
+    // A plugin written here is the site's own code, not the updater's, so it
+    // belongs in the site repo. The allowlist ignores plugins/* by default.
+    allowInGitignore(path.dirname(PLUGINS_DIR), sitePluginRules(slug));
+
     return { name: slug, files };
 }