@adminide-stack/marketplace-module-server

Extension Marketplace Server

This module handles the extension marketplace functionality, including extension registry management, installation lifecycle, and publisher actions.

Extension Lifecycle Management

Overview

Publishers should generally not be able to completely unregister extensions that users have already installed, but there are nuanced approaches to handle extension lifecycle scenarios while balancing publisher needs, user expectations, and platform security.

Recommended Approach: Soft Deprecation vs Hard Removal

1. Publisher Actions Available

// In extensionRegistry collection
{
  "_id": ObjectId("67c2c30f860196612c58b082"),
  "extensionID": "stackflow1/builder-extension",
  "publisher": "stackflow1",
  "status": "active", // active, deprecated, suspended, removed
  "deprecation": {
    "isDeprecated": false,
    "deprecatedAt": null,
    "reason": null, // "security", "maintenance", "replaced", "violation"
    "replacementExtension": null, // Alternative extension ID
    "endOfLifeDate": null, // When it will stop working
    "migrationGuide": null // URL to migration instructions
  },
  "publisherActions": {
    "canDeprecate": true,
    "canSuspendNewInstalls": true,
    "canRemoveFromMarketplace": true,
    "canForceUninstall": false // Requires admin approval
  },
  "versions": [
    {
      "version": "1.0.0",
      "status": "active", // active, deprecated, yanked, security-hold
      "yankedAt": null,
      "yankedReason": null
    }
  ]
}

2. Enhanced installedExtensions with Lifecycle Management

// In installedExtensions collection
{
  "_id": ObjectId("67c2c30f860196612c58b080"),
  "tenantId": "default",
  "registryRef": ObjectId("67c2c30f860196612c58b082"),
  "extensionID": "stackflow1/builder-extension",
  "installedVersion": "1.0.0",
  "status": "installed", // installed, deprecated-installed, suspended, orphaned
  "lifecycle": {
    "registryStatus": "active", // Cached from registry
    "isOrphaned": false, // True if extension removed from registry
    "deprecationWarningShown": false,
    "autoUpdateBlocked": false,
    "lastRegistryCheck": ISODate("2025-03-01T11:00:00.000+0000")
  },
  "policies": {
    "allowOrphanedExecution": true, // Admin policy
    "requireSecurityUpdates": true,
    "autoRemoveDeprecated": false,
    "deprecationGracePeriod": 90 // days
  }
}

Publisher Actions and Their Effects

1. Deprecate Extension (Recommended)

// Publisher action: Deprecate
db.extensionRegistry.updateOne(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'deprecated',
            deprecation: {
                isDeprecated: true,
                deprecatedAt: new Date(),
                reason: 'maintenance',
                replacementExtension: 'stackflow1/builder-v2',
                endOfLifeDate: new Date(Date.now() + 365 * 24 * 60 * 60 * 1000), // 1 year
                migrationGuide: 'https://docs.example.com/migration-guide',
            },
        },
    },
);

// Effect on installed extensions: Still works, but users get warnings
db.installedExtensions.updateMany(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'deprecated-installed',
            'lifecycle.registryStatus': 'deprecated',
        },
    },
);

2. Suspend New Installations

// Publisher action: Suspend new installs (existing continue to work)
db.extensionRegistry.updateOne(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'suspended',
            suspension: {
                suspendedAt: new Date(),
                reason: 'security-review',
                allowExistingInstalls: true,
                estimatedResolution: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000),
            },
        },
    },
);

3. Remove from Marketplace (Registry remains for installed extensions)

// Publisher action: Remove from marketplace but keep registry entry
db.extensionRegistry.updateOne(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'removed',
            marketplaceVisibility: 'hidden',
            removal: {
                removedAt: new Date(),
                reason: 'discontinued',
                keepForInstalledUsers: true,
            },
        },
    },
);

// Installed extensions become "orphaned" but continue to work
db.installedExtensions.updateMany(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'orphaned',
            'lifecycle.isOrphaned': true,
            'lifecycle.registryStatus': 'removed',
        },
    },
);

4. Emergency Removal (Admin-only, rare cases)

// Admin/Platform action only (security issues, legal violations)
db.extensionRegistry.updateOne(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'emergency-removed',
            emergencyRemoval: {
                removedAt: new Date(),
                removedBy: 'platform-admin',
                reason: 'security-vulnerability',
                forceUninstall: true,
                notificationSent: true,
            },
        },
    },
);

// Force disable all installations
db.installedExtensions.updateMany(
    { extensionID: 'stackflow1/builder-extension' },
    {
        $set: {
            status: 'force-disabled',
            'settings.systemEnabled': false,
            'settings.effectiveEnabled': false,
            'runtime.activationState': 'disabled-by-admin',
        },
    },
);

User Experience for Different Scenarios

1. Deprecated Extension

// User sees warning but extension continues to work
interface DeprecationWarning {
    type: 'deprecation';
    message: 'Builder Extension is deprecated and will stop working on March 1, 2026';
    actions: [
        { label: 'View Migration Guide'; url: 'https://docs.example.com/migration' },
        { label: 'Install Replacement'; extensionID: 'stackflow1/builder-v2' },
        { label: 'Dismiss'; action: 'dismiss' },
    ];
}

2. Suspended Extension

// User sees info but extension continues to work
interface SuspensionNotice {
    type: 'suspension';
    message: 'Builder Extension is under security review. Updates suspended temporarily.';
    estimatedResolution: '2025-03-08T00:00:00Z';
}

3. Orphaned Extension (Removed from marketplace)

// User sees warning about no more updates
interface OrphanedWarning {
    type: 'orphaned';
    message: 'Builder Extension is no longer maintained. No updates will be available.';
    actions: [
        { label: 'Find Alternatives'; action: 'browse-alternatives' },
        { label: 'Keep Using'; action: 'accept-risk' },
        { label: 'Uninstall'; action: 'uninstall' },
    ];
}

Administrative Policies

// In tenant/organization settings
{
    "extensionPolicies": {
        "orphanedExtensions": {
            "allowExecution": true,
            "showWarnings": true,
            "autoRemoveAfterDays": null
        },
        "deprecatedExtensions": {
            "allowNewActivations": true,
            "gracePeriodDays": 90,
            "forceRemovalAfterEOL": false
        },
        "suspendedExtensions": {
            "allowContinuedUse": true,
            "disableAfterDays": null
        },
        "securityPolicies": {
            "respectEmergencyDisables": true,
            "allowManualOverride": false
        }
    }
}

Query Examples

Get Extensions Needing User Attention

db.installedExtensions.aggregate([
    {
        $match: {
            tenantId: 'default',
            'lifecycle.registryStatus': { $in: ['deprecated', 'suspended', 'removed'] },
        },
    },
    {
        $lookup: {
            from: 'extensionRegistry',
            localField: 'registryRef',
            foreignField: '_id',
            as: 'registry',
        },
    },
    {
        $project: {
            extensionID: 1,
            status: 1,
            lifecycle: 1,
            deprecation: '$registry.deprecation',
            suspension: '$registry.suspension',
        },
    },
]);

Best Practices

Publishers Should:

• Use deprecation for planned discontinuation
• Provide migration guides and alternatives
• Give reasonable notice periods (6-12 months)
• Only request emergency removal for serious issues

Platform Should:

• Require admin approval for emergency removals
• Maintain registry entries for installed extensions
• Provide clear user notifications
• Allow organizational policies to override defaults

Users Should:

• Receive clear warnings about extension status changes
• Have time to migrate to alternatives
• Retain control over their installed extensions
• Be able to accept risks of using orphaned extensions

This approach balances publisher needs, user expectations, and platform security while avoiding the disruption of completely removing extensions that users depend on.