@velora-cms/server 0.11.0

package/dist/marketplace/install-from-marketplace.js

@@ -0,0 +1,581 @@
+import { existsSync, readFileSync } from "node:fs";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { extractArtifact } from "@velora-cms/plugin-package";
+import { hasClientBundle } from "@velora-cms/plugin-sdk/manifest";
+import { installPackageTarball } from "../plugins/install-package-tarball.js";
+import { removePluginPackages } from "../plugins/plugin-package-store.js";
+import { PluginDependencyError, PluginIncompatibleError, PluginInstallError, } from "../plugins/plugin-registry-service.js";
+import { seedTemplateSampleContent } from "../plugins/seed-template-content.js";
+import { checkPackageIdentity, resolveSidecarPath, trustTierFor, verifyPackage } from "../plugins/verify-package.js";
+import { loadTrustedKeys } from "../plugins/trusted-keys.js";
+import { getSiteDomain } from "../config/site.js";
+import { pluginAssetsRemoteUrl } from "../routes/plugin-assets.js";
+import { MarketplaceNotFoundError, downloadPackage, downloadSignature, fetchListing, validateLicenseUpstream } from "./marketplace-client.js";
+import { installBundleMembers } from "./install-bundle-members.js";
+/** Duck-typed on `.code`, not `instanceof Prisma.PrismaClientKnownRequestError`
+ * — same reasoning as routes/users.ts's own duplicate-email handling:
+ * `prisma` (db/prisma.ts) is loaded dynamically per VELORA_PRISMA_CLIENT_DIR
+ * (multi-dialect client generation), so the error thrown by that runtime's
+ * client is a *different* module instance than any statically imported
+ * `@prisma/client`, and `instanceof` across that boundary always returns
+ * false. `code` is a stable string on the wire regardless of which client
+ * instance threw it. */
+function isUniqueConstraintViolation(error) {
+    return typeof error === "object" && error !== null && "code" in error && error.code === "P2002";
+}
+/** Reads manifest.json's declared id/version out of a downloaded tarball
+ * WITHOUT running any part of the real install — used only to bind what
+ * was actually downloaded to what the caller REQUESTED, before
+ * installPackageTarball (or even downloadSignature) ever runs. See the
+ * call site's comment for why this matters. Extracts into its own
+ * disposable subdirectory via the same, already-reviewed extractArtifact()
+ * the real install path uses internally — never a hand-rolled read of an
+ * untrusted archive. Throws on a genuinely malformed/corrupt archive or a
+ * missing/malformed manifest.json, exactly mirroring
+ * installPackageTarball's own extraction-failure behavior, so both land on
+ * the same catch-all + cleanup + rethrow path below. */
+async function peekPackageIdentity(tarballPath, peekDir) {
+    const extracted = await extractArtifact(tarballPath, peekDir);
+    if (!extracted.ok) {
+        throw new Error(`Package could not be extracted: ${extracted.reason}`);
+    }
+    const manifestPath = join(peekDir, "manifest.json");
+    if (!existsSync(manifestPath)) {
+        throw new Error("No manifest.json found in the downloaded package — not a velora-plugin built package");
+    }
+    const summary = JSON.parse(readFileSync(manifestPath, "utf8"));
+    if (!summary.id || !summary.version) {
+        throw new Error("manifest.json in the downloaded package is missing id/version");
+    }
+    // S152: the member list rides the signed artifact's manifest.json
+    // (write-manifest-json.ts passes bare string entries through verbatim).
+    // Read here — after the caller's trust gate has verified the tarball —
+    // so "resolve members before installing anything" is possible at all.
+    const bundledPlugins = Array.isArray(summary.contributions?.bundledPlugins)
+        ? summary.contributions.bundledPlugins.filter((entry) => typeof entry === "string")
+        : undefined;
+    return { id: summary.id, version: summary.version, type: summary.type, bundledPlugins };
+}
+/** The same "(reason) — message — nothing was installed" wording for both
+ * verification-failure sites below (the pre-install gate and its
+ * post-install belt-and-braces twin) — factored out so the two can never
+ * drift into different phrasing for what is, by construction, the same
+ * verdict. */
+function describeVerificationFailure(pluginId, version, verification) {
+    const reason = verification.status === "failed" ? verification.reason : verification.status;
+    const detail = verification.status === "failed" ? ` — ${verification.message}` : "";
+    return `Signature verification failed for "${pluginId}"@${version} (${reason})${detail} — nothing was installed`;
+}
+/** Best-effort teardown for a marketplace install that must not leave
+ * partial state behind. Shared by the post-install trust-tier
+ * belt-and-braces check and the catch-all below (an UNEXPECTED throw —
+ * e.g. a plugin's own onActivate() blowing up mid-install;
+ * PluginRegistryService's own activate() doc comment anticipates hooks
+ * throwing).
+ *
+ * `outcome` is installPackageTarball's own RegisterLocalPluginResult
+ * (undefined when it never returned at all — install() threw before
+ * reaching that point). This is BOTH the H2 fix and the M4 fix from the
+ * S138 hardening review, because they turn out to be the same missing
+ * piece of information:
+ *
+ * - H2: an "installed" outcome means THIS call's own
+ *   PluginRegistryService.install() created the row — migrations applied,
+ *   document types created, onInstall run, and (per registerLocalPlugin)
+ *   activate() run too. The real inverse of all of that is
+ *   PluginRegistryService.uninstall(), not a hand-rolled partial teardown
+ *   — the old version of this function only ever deleted the registry
+ *   row, leaving PluginMigrationRecord/PluginDocumentType rows (and the
+ *   document types themselves) behind, which permanently 500'd every
+ *   later reinstall attempt via a P2002 inside install()'s own migration
+ *   loop. uninstall() rolls all of that back in the correct LIFO order.
+ *   confirmStructuredDataCleanup: true because this is an orphan teardown
+ *   of a moments-old failed install, not a user-facing uninstall with
+ *   real accumulated content to protect behind a confirmation prompt.
+ * - M4: an "activated" or "already-active" outcome means a CONCURRENT
+ *   request's install() created the row instead — registerLocalPlugin's
+ *   own tolerant merge path, taken when this call's registration attempt
+ *   observed an already-existing row for a pluginId step 1's own
+ *   findUnique had, moments earlier, confirmed did not exist yet. None of
+ *   the registry row, the in-process manifest attachment, or the
+ *   package-store copy belongs to THIS request in that case — tearing any
+ *   of it down would delete the winner's legitimate install, not undo
+ *   this request's own (nonexistent) one.
+ * - undefined means install() threw before ever reaching its own
+ *   create() call (PluginIncompatibleError, PluginDependencyError, a
+ *   manifest-validation PluginInstallError, or install()'s own internal
+ *   migration/onInstall rollback already ran) — no row exists for this
+ *   pluginId under any of those, from this request or a concurrent one,
+ *   so the manifest-detach + package-store cleanup below is always safe.
+ *
+ * Each step gets its OWN try/catch and only warns/logs on failure — a
+ * cleanup failure must never mask whatever real error is already
+ * propagating (or, on the trust-tier path, prevent the 422 response from
+ * being sent). */
+async function cleanupOrphanedInstall(deps, pluginId, outcome) {
+    if (outcome === "activated" || outcome === "already-active") {
+        console.warn(`[install-from-marketplace] skipping cleanup for "${pluginId}" — a concurrent install already owns its registry row (outcome: "${outcome}"); nothing here belongs to this request`);
+        return;
+    }
+    if (outcome === "installed") {
+        try {
+            await deps.registry.uninstall(pluginId, { confirmStructuredDataCleanup: true });
+        }
+        catch (error) {
+            console.error(`[install-from-marketplace] failed to fully uninstall "${pluginId}" during cleanup — it may be left partially registered and need manual removal`, error);
+        }
+    }
+    else {
+        try {
+            deps.registry.detachManifest(pluginId);
+        }
+        catch (error) {
+            console.warn(`[install-from-marketplace] failed to detach the in-process manifest for "${pluginId}" during cleanup`, error);
+        }
+        try {
+            await deps.prisma.pluginRegistry.deleteMany({ where: { pluginId } });
+        }
+        catch (error) {
+            console.error(`[install-from-marketplace] failed to delete the registry row for "${pluginId}" during cleanup — it may be orphaned and need manual removal`, error);
+        }
+    }
+    // Windows file-lock reality (per this module's own test suite): a sync
+    // rmSync immediately after the just-imported server/plugin.js's dynamic
+    // import can race a held handle, so this always runs last and never
+    // blocks the DB-side cleanup above on its own success.
+    try {
+        removePluginPackages(pluginId);
+    }
+    catch (error) {
+        console.warn(`[install-from-marketplace] failed to remove the stored package for "${pluginId}" during cleanup`, error);
+    }
+}
+export async function installFromMarketplace(deps, input) {
+    const { prisma, registry, marketplaceBaseUrl, adapter } = deps;
+    const { pluginId, version, licenseKey, installedBy } = input;
+    // Step 1: already installed — a plain DB lookup, no network at all, so
+    // this is always the cheapest possible rejection. This check has an
+    // inherent TOCTOU gap against a second, concurrent install of the same
+    // pluginId (closed below, at the actual write, not here — see the
+    // isUniqueConstraintViolation branch).
+    const existingRow = await prisma.pluginRegistry.findUnique({ where: { pluginId } });
+    if (existingRow) {
+        return { ok: false, failure: { code: "already-installed", message: `Plugin "${pluginId}" is already installed` } };
+    }
+    // Step 2: the listing (and the requested version within it) must exist
+    // upstream before anything else is checked or downloaded.
+    let listing;
+    try {
+        listing = (await fetchListing(marketplaceBaseUrl, pluginId));
+    }
+    catch (error) {
+        if (error instanceof MarketplaceNotFoundError) {
+            return { ok: false, failure: { code: "not-found", message: error.message } };
+        }
+        throw error;
+    }
+    const matchedVersion = (listing.versions ?? []).some((v) => v.version === version);
+    if (!matchedVersion) {
+        return {
+            ok: false,
+            failure: { code: "not-found", message: `No published version "${version}" for plugin "${pluginId}"` },
+        };
+    }
+    // Step 3: paid plugins gate on a validated license BEFORE a single
+    // package byte is downloaded. siteDomain is hoisted to function scope
+    // so step 6 (the license row) reuses the exact value validated here
+    // rather than re-reading the env a second time.
+    let siteDomain;
+    if (listing.priceCents > 0) {
+        if (!licenseKey) {
+            return {
+                ok: false,
+                failure: { code: "license-required", message: `Plugin "${pluginId}" is a paid plugin — a license key is required` },
+            };
+        }
+        siteDomain = getSiteDomain();
+        if (!siteDomain) {
+            return {
+                ok: false,
+                failure: {
+                    code: "site-domain-missing",
+                    message: "VELORA_SITE_DOMAIN must be configured before installing a paid plugin — the license binds to this instance's declared domain on first validation, and installing without it would burn that one-shot binding on a meaningless value",
+                },
+            };
+        }
+        const verdict = await validateLicenseUpstream(marketplaceBaseUrl, { key: licenseKey, pluginId, domain: siteDomain });
+        if (verdict.status !== "valid") {
+            return {
+                ok: false,
+                failure: {
+                    code: "license-rejected",
+                    message: `License rejected for "${pluginId}" (${verdict.status}): ${verdict.reason ?? "no reason given"}`,
+                },
+            };
+        }
+    }
+    // Steps 4-5: download into a disposable temp directory and hand the
+    // tarball to the existing verify+install pipeline. Cleaned in the
+    // finally below regardless of outcome. Tracks which RegisterLocalPluginResult
+    // (if any) installPackageTarball reports, so cleanupOrphanedInstall knows
+    // whether THIS request created the row it might need to tear down (see
+    // that function's own doc comment — this is the H2/M4 fix).
+    const tempDir = await mkdtemp(join(tmpdir(), "velora-install-"));
+    let installOutcome;
+    try {
+        const tarballPath = join(tempDir, "package.tar.gz");
+        // M1: a MarketplaceNotFoundError here (the listing named a version
+        // whose artifact route is missing — a real upstream data-consistency
+        // failure, not a client bug) must map to the same 404 the listing
+        // fetch above already gets. Nothing has been extracted, registered, or
+        // stored yet at this point, so there is nothing for cleanupOrphanedInstall
+        // to undo — a plain early return is enough.
+        try {
+            await downloadPackage(marketplaceBaseUrl, pluginId, version, tarballPath);
+        }
+        catch (error) {
+            if (error instanceof MarketplaceNotFoundError) {
+                return { ok: false, failure: { code: "not-found", message: error.message } };
+            }
+            throw error;
+        }
+        // S152: declared here — in the OUTER try's body, above the inner try
+        // below — rather than inside that inner try, because the inner try's
+        // own catch (the P2002 / typed-refusal / rethrow handling further
+        // down) needs to read and call these too. A `let`/`const` declared
+        // inside a try block is not visible from that try's own catch block
+        // (they are sibling scopes, not parent/child) — only a declaration in
+        // an enclosing scope is visible from both.
+        let bundleMembers;
+        // S152: any failure AFTER the members are in must take them back out
+        // (the atomic-set invariant), including their ownership rows if the
+        // createMany below already ran.
+        const rollbackBundleMembers = async () => {
+            if (!bundleMembers || bundleMembers.installedIds.length === 0)
+                return;
+            for (const memberId of [...bundleMembers.installedIds].reverse()) {
+                await cleanupOrphanedInstall(deps, memberId, "installed");
+            }
+            try {
+                await prisma.pluginBundleMember.deleteMany({ where: { bundlePluginId: pluginId } });
+            }
+            catch (error) {
+                console.error(`[install-from-marketplace] failed to delete bundle ownership rows for "${pluginId}" during cleanup`, error);
+            }
+        };
+        try {
+            // Identity binding, before anything is registered. installPackageTarball's
+            // own checkPackageIdentity only cross-checks the SIGNATURE ENVELOPE
+            // against the tarball's OWN manifest.json — it has no idea what
+            // pluginId/version THIS request actually asked for. A marketplace
+            // whose /packages/:pluginId/:version route serves the wrong artifact
+            // (a bug, or a compromised/misconfigured upstream) could otherwise
+            // have its own, internally self-consistent signature verify
+            // "verified" while installing a completely different plugin than
+            // what was requested — and since the registry row lands under the
+            // MANIFEST's id, not the requested one, a cleanup keyed only on the
+            // requested id would miss it entirely. Peeking the manifest here,
+            // before installPackageTarball (or even downloadSignature) ever
+            // runs, means a mismatch is refused before any registration side
+            // effect exists at all — nothing to clean up under either id,
+            // because nothing was ever installed under either id.
+            const actualIdentity = await peekPackageIdentity(tarballPath, join(tempDir, "identity-peek"));
+            if (actualIdentity.id !== pluginId || actualIdentity.version !== version) {
+                return {
+                    ok: false,
+                    failure: {
+                        code: "verification-failed",
+                        message: `Requested "${pluginId}"@${version} but the downloaded package identifies itself as "${actualIdentity.id}"@${actualIdentity.version} — refusing to install a mismatched package`,
+                    },
+                };
+            }
+            const signatureText = await downloadSignature(marketplaceBaseUrl, pluginId, version);
+            const sidecarPath = resolveSidecarPath(tarballPath);
+            if (signatureText !== null) {
+                // resolveSidecarPath's convention: `<tarballPath>.sig`, right next
+                // to the artifact. installPackageTarball's own default sidecar
+                // resolution (when no options.sidecarPath is passed below) looks
+                // for exactly this path via existsSync, so writing here is all
+                // that's needed to hand it the signature.
+                await writeFile(sidecarPath, signatureText);
+            }
+            // C1 (S138 hardening review): the trust gate, computed and enforced
+            // HERE — before installPackageTarball, and therefore before a single
+            // line of the package's code has run. Previously this same verdict
+            // was only checked AFTER installPackageTarball had already copied
+            // the package into the managed store, `import()`ed its
+            // server/plugin.js (executing its top-level code), and run its
+            // migrations/onInstall/onActivate — a tampered or unsigned package
+            // was refused only once it had already executed once. That inverted
+            // this module's own documented spine ("download -> identity check ->
+            // verify -> register") and the spec's Decision 2 ("a marketplace
+            // install BLOCKS on failed verification").
+            //
+            // This reuses verifyPackage + checkPackageIdentity — the exact same
+            // functions installPackageTarball calls internally — against the
+            // exact same inputs (tarballPath, sidecarPath, loadTrustedKeys()) it
+            // will use a few lines below, plus actualIdentity from the identity
+            // peek above (already extracted, so this costs one extra
+            // hashTarball and nothing else — no second extraction). Because the
+            // inputs are identical and verifyPackage is a pure function of them,
+            // installPackageTarball's own internal recomputation is guaranteed
+            // to reach the same verdict; it is kept anyway as a second,
+            // belt-and-braces gate (see the comment where it's checked below)
+            // rather than trusted blindly.
+            const preVerification = checkPackageIdentity(await verifyPackage(tarballPath, existsSync(sidecarPath) ? sidecarPath : null, loadTrustedKeys()), actualIdentity.id, actualIdentity.version);
+            if (trustTierFor(preVerification) !== "verified") {
+                // Nothing has been imported, registered, or copied into the
+                // managed store yet — installPackageTarball has not been called —
+                // so there is nothing for cleanupOrphanedInstall to undo. This IS
+                // "refuse before execution," not "execute then refuse."
+                return {
+                    ok: false,
+                    failure: { code: "verification-failed", message: describeVerificationFailure(pluginId, version, preVerification) },
+                };
+            }
+            // S152: bundle fan-out — members first, bundle last. Runs only after
+            // the bundle's own artifact is downloaded, identity-bound, and
+            // signature-verified (the member list is READ from that verified
+            // artifact), and before the bundle itself is registered, so a bundle
+            // registry row existing always means the full set is in place.
+            // installBundleMembers guarantees that on any non-ok return or throw
+            // it has already rolled back every member it installed.
+            if (actualIdentity.type === "bundle") {
+                if (input.refuseBundleType) {
+                    return {
+                        ok: false,
+                        failure: {
+                            code: "install-refused",
+                            message: `"${pluginId}" is itself a bundle — nested bundles are not supported as bundle members`,
+                        },
+                    };
+                }
+                const result = await installBundleMembers({
+                    fetchMemberListing: (memberId) => fetchListing(marketplaceBaseUrl, memberId),
+                    installOne: (memberInput) => installFromMarketplace(deps, { ...memberInput, refuseBundleType: true }),
+                    // A member's install ended fully registered AND active
+                    // (registerLocalPlugin always activates), so its real inverse is
+                    // the same "installed"-outcome cleanup the single-plugin path
+                    // already uses: registry.uninstall with structured cleanup
+                    // confirmed (moments-old data, nothing to protect) plus
+                    // package-store removal.
+                    rollbackOne: (memberId) => cleanupOrphanedInstall(deps, memberId, "installed"),
+                }, { bundleId: pluginId, memberIds: actualIdentity.bundledPlugins ?? [], installedBy });
+                if (!result.ok) {
+                    return result;
+                }
+                bundleMembers = result;
+            }
+            const setRemoteUrl = async (id, url) => {
+                await prisma.pluginRegistry.update({ where: { pluginId: id }, data: { remoteUrl: url } });
+            };
+            const syncManifestFields = async (id, fields) => {
+                await prisma.pluginRegistry.update({ where: { pluginId: id }, data: fields });
+            };
+            const setPackagePath = async (id, packagePath) => {
+                await prisma.pluginRegistry.update({ where: { pluginId: id }, data: { packagePath } });
+            };
+            // remoteUrl: the S143 plugin-assets mount serves the stored copy of
+            // this exact package, so the row points there — server-relative (see
+            // pluginAssetsRemoteUrl's doc comment for why not absolute). Safe to
+            // compute from the REQUESTED id/version: the identity peek above
+            // already proved the package's manifest matches them, and
+            // installBuiltPackage stores under the manifest's own id/version.
+            // The RegisterLocalPluginResult half of the return ("installed" |
+            // "activated" | "already-active") IS captured here (into
+            // installOutcome, declared above the outer try) — cleanupOrphanedInstall
+            // needs it to tell "this request's own install()" apart from "a
+            // concurrent request's install() that won the race against step 1's
+            // own check," which registerLocalPlugin's tolerant `existing` merge
+            // path takes silently rather than throwing (see cleanupOrphanedInstall's
+            // doc comment for the full reasoning — this is the M4 fix).
+            // S144: only client-bearing types get a plugin-assets remoteUrl —
+            // a theme/template/bundle package has no remoteEntry.js, and a URL
+            // pointing at a 404 would make the admin loader log a load failure
+            // for every view-less plugin on every boot. Empty string = the
+            // loader's existing "nothing to load" contract. The peeked type is
+            // unvalidated here, which is fine: it only picks a URL; the full
+            // manifest validation still runs inside the install.
+            const remoteUrl = actualIdentity.type && !hasClientBundle(actualIdentity.type)
+                ? ""
+                : pluginAssetsRemoteUrl(pluginId, version);
+            const { outcome, verification } = await installPackageTarball(registry, tarballPath, remoteUrl, setRemoteUrl, syncManifestFields, setPackagePath);
+            installOutcome = outcome;
+            // Belt-and-braces twin of the pre-install gate above, not the primary
+            // gate — C1's fix moved the REAL trust decision ahead of
+            // installPackageTarball, using the identical tarballPath/sidecarPath/
+            // trustedKeys inputs, so this recomputation (done internally by
+            // installPackageTarball) is expected to always agree and this branch
+            // should be unreachable in practice. It stays rather than being
+            // deleted: if a future change ever lets the two diverge (a trusted-key
+            // reload mid-request, a code path inserted between the two that
+            // touches the sidecar), this is what still stops an unverified
+            // package from being left installed instead of silently trusting the
+            // earlier check forever. installOutcome (just captured above) tells
+            // cleanupOrphanedInstall whether this request actually owns what
+            // needs undoing.
+            if (trustTierFor(verification) !== "verified") {
+                await cleanupOrphanedInstall(deps, pluginId, installOutcome);
+                await rollbackBundleMembers();
+                return {
+                    ok: false,
+                    failure: { code: "verification-failed", message: describeVerificationFailure(pluginId, version, verification) },
+                };
+            }
+            // Step 6: paid plugins get their license persisted only once the
+            // install has actually succeeded and verified.
+            const licensed = listing.priceCents > 0;
+            if (licensed) {
+                await prisma.pluginLicense.upsert({
+                    where: { pluginId },
+                    create: { pluginId, key: licenseKey, boundDomain: siteDomain, status: "valid", lastValidatedAt: new Date() },
+                    update: { key: licenseKey, boundDomain: siteDomain, status: "valid", lastReason: null, lastValidatedAt: new Date() },
+                });
+            }
+            // Step 7: attaching the manifest again here would be redundant, not
+            // missing. registerLocalPlugin's `!existing` branch (always taken
+            // here, since step 1 already proved no row existed) calls
+            // PluginRegistryService.install(), which itself does
+            // `this.manifests.set(plugin.id, plugin)` before returning — the
+            // manifest is already attached in THIS process by the time
+            // installPackageTarball resolves. app.pluginRegistry.getManifest(id)
+            // answers immediately, no restart and no extra call needed.
+            // Step 7.5 (Session 149, Task 2): seed a template plugin's sample
+            // content, but ONLY when this request's own call actually created
+            // the row (installOutcome === "installed") — "activated"/
+            // "already-active" mean a concurrent request owns the install, same
+            // reasoning cleanupOrphanedInstall's doc comment already spells out
+            // for those two outcomes. D1's "never from inside
+            // PluginRegistryService.install()" is honored: this runs entirely
+            // outside it, after installPackageTarball has already returned.
+            // packagePath was just persisted by setPackagePath above (installBuiltPackage
+            // always calls it before returning), so a fresh read gets the exact
+            // stored directory seedTemplateSampleContent needs. Wrapped in its
+            // own try/catch as a belt-and-braces guard on top of the seeder's
+            // own internal non-fatal handling — D2 requires this install to
+            // stand no matter what happens here.
+            if (installOutcome === "installed") {
+                try {
+                    const row = await prisma.pluginRegistry.findUnique({ where: { pluginId } });
+                    if (row?.packagePath) {
+                        const seedResult = await seedTemplateSampleContent({ prisma, adapter }, pluginId, row.packagePath, installedBy);
+                        if (typeof seedResult === "object") {
+                            console.log(`[install-from-marketplace] seeded ${seedResult.created} sample content node(s) for "${pluginId}"`);
+                        }
+                        else if (seedResult !== "none") {
+                            console.log(`[install-from-marketplace] sample content seeding for "${pluginId}": ${seedResult}`);
+                        }
+                    }
+                }
+                catch (error) {
+                    console.error(`[install-from-marketplace] sample content seeding for "${pluginId}" failed — the install stands`, error);
+                }
+            }
+            // S152: ownership rows LAST — written only once the bundle's own row
+            // exists and everything else has succeeded, so a rolled-back install
+            // can never leave ownership rows behind. Only members THIS operation
+            // installed get a row (skip-don't-claim); position preserves install
+            // order for the uninstall cascade's reverse walk.
+            if (bundleMembers && bundleMembers.installedIds.length > 0) {
+                await prisma.pluginBundleMember.createMany({
+                    data: bundleMembers.installedIds.map((memberPluginId, index) => ({
+                        bundlePluginId: pluginId,
+                        memberPluginId,
+                        position: index,
+                    })),
+                });
+            }
+            return {
+                ok: true,
+                pluginId,
+                version,
+                trustTier: "verified",
+                licensed,
+                ...(bundleMembers ? { members: bundleMembers.members } : {}),
+            };
+        }
+        catch (error) {
+            // A second, concurrent install of the SAME never-before-installed
+            // plugin can both pass step 1's findUnique (neither sees the
+            // other's row yet) and then race PluginRegistryService.install()'s
+            // own prisma.pluginRegistry.create() — the loser's create() throws a
+            // unique-constraint violation on pluginId. That is not a partial
+            // failure to unwind: the loser's own install() never reached
+            // `this.manifests.set(...)` (it only runs AFTER create() succeeds),
+            // so nothing of THIS call's making was ever attached, activated, or
+            // registered. storePackage() did already run (installBuiltPackage
+            // copies into the managed store before calling install()), but that
+            // copy is byte-identical to the winner's — both installs are
+            // extracting the SAME downloaded tarball — so there is nothing of
+            // ours to undo, only the winner's legitimate install to leave
+            // completely alone. Report it exactly like the ordinary
+            // already-installed case.
+            //
+            // S152: this branch deliberately does NOT roll bundle members back.
+            // On P2002 a CONCURRENT request owns the bundle row, and that
+            // winner's own fan-out saw our already-installed members as
+            // pre-existing skips (skip-don't-claim) — tearing ours down here
+            // would break the winner's set out from under it. The members stay
+            // installed but unowned, exactly as if they pre-existed: a benign,
+            // documented residual mirroring cleanupOrphanedInstall's own M4 skip.
+            //
+            // The `installOutcome !== "installed"` guard matters because P2002
+            // is not exclusively the create-race described above: once THIS
+            // request's own registerLocalPlugin has already returned "installed",
+            // two LATER statements inside this same try can also throw P2002 —
+            // the pluginLicense.upsert (a concurrent license write) and the
+            // S152 pluginBundleMember.createMany (unique on [bundlePluginId,
+            // memberPluginId], which a stale ownership row can violate if a
+            // prior cleanup's own deleteMany failed and was swallowed). Neither
+            // of those is the concurrent-install race: this request DID create
+            // the registry row, so returning "already-installed" here would
+            // leave a fully-installed, active plugin/bundle behind with no
+            // ownership rows and no rollback. Only fall onto the early return
+            // when this request never won its own create — i.e. installOutcome
+            // is not "installed" — otherwise fall through to the cleanup path
+            // below, exactly like any other unexpected failure.
+            if (isUniqueConstraintViolation(error) && installOutcome !== "installed") {
+                return { ok: false, failure: { code: "already-installed", message: `Plugin "${pluginId}" is already installed` } };
+            }
+            // Anything else — a plugin's onActivate() throwing, a corrupt
+            // archive the identity peek didn't already catch, a DB error on the
+            // license upsert, or any other genuinely unexpected failure — may
+            // have left the plugin partially registered/attached/stored. Restore
+            // state before letting the error propagate; the route's own handler
+            // still turns an unmapped throw into a 500, but only AFTER this
+            // completes. installOutcome is undefined here whenever install()
+            // itself threw one of the three typed refusals mapped just below (all
+            // three fire from inside install(), before installPackageTarball ever
+            // returns) — cleanupOrphanedInstall treats that the same as "nothing
+            // exists to protect," which is correct for all three (see its own doc
+            // comment).
+            await cleanupOrphanedInstall(deps, pluginId, installOutcome);
+            await rollbackBundleMembers();
+            // M2 (S138 hardening review): PluginRegistryService.install()'s own
+            // typed refusals, previously unmapped and left to fall through to the
+            // generic rethrow below — which the route's handler turns into a bare
+            // 500, even though each of these is a well-understood, well-messaged
+            // refusal rather than a server bug. See the InstallFailure union's own
+            // comment for why "incompatible"/"install-refused" get 422 and
+            // "dependency-missing" gets 409. Checked most-specific-subclass-first
+            // since PluginIncompatibleError and PluginDependencyError both extend
+            // the base PluginInstallError.
+            if (error instanceof PluginIncompatibleError) {
+                return { ok: false, failure: { code: "incompatible", message: error.message } };
+            }
+            if (error instanceof PluginDependencyError) {
+                return { ok: false, failure: { code: "dependency-missing", message: error.message } };
+            }
+            if (error instanceof PluginInstallError) {
+                return { ok: false, failure: { code: "install-refused", message: error.message } };
+            }
+            throw error;
+        }
+    }
+    finally {
+        // Step 8.
+        await rm(tempDir, { recursive: true, force: true });
+    }
+}

package/dist/marketplace/license-revalidation-job.d.ts

@@ -0,0 +1,38 @@
+import { type RevalidateDeps } from "./revalidate-license.js";
+/** One sweep over every plugin that has a license row. A single plugin's
+ * failure is logged and never aborts the sweep (the Session 91 precedent:
+ * one plugin must never take the others down). */
+export declare function runLicenseRevalidationPass(deps: RevalidateDeps): Promise<{
+    checked: number;
+    revoked: number;
+    failed: number;
+}>;
+/** Starts the first background timer in apps/server. Two things are
+ * non-negotiable: the handle is unref()'d so it can never hold the process
+ * open, and the caller MUST stop it on app close (app.ts registers an
+ * onClose hook) — otherwise every integration test that builds and closes
+ * an app leaves a live timer behind.
+ *
+ * Passes are intended never to overlap, but forward progress must never
+ * depend on a third-party hook actually resolving. What is ACTUALLY
+ * guaranteed (corrected from an earlier version of this comment, which
+ * claimed the wait was inherently bounded by the upstream 8s timeout
+ * alone — true of the license CHECK, but not of registry.deactivate(),
+ * which also awaits a plugin's onDeactivate hook with no timeout of its
+ * own):
+ *   - stop() always resolves within ~passTimeoutMs of being called,
+ *     regardless of whether the in-flight pass (or the hook it's stuck
+ *     in) ever finishes. If it gives up, it logs clearly that it did.
+ *   - A pass that's been "in flight" longer than passTimeoutMs is
+ *     presumed wedged, and the overlap guard stops treating it as a
+ *     reason to skip the next tick — so a hung onDeactivate hook can
+ *     disable enforcement for at most one bad tick, not for the rest of
+ *     the process's life.
+ *   - Giving up on a wedged pass does not cancel it. It keeps running in
+ *     the background and will still write whatever verdict it eventually
+ *     reaches; it just can no longer block anyone else from making
+ *     progress. */
+export declare function startLicenseRevalidation(deps: RevalidateDeps, opts?: {
+    intervalMs?: number;
+    passTimeoutMs?: number;
+}): () => Promise<void>;