Skip to content

docs(plugins): add org-level plugin governance allowlist (PR #610) #36

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
molecule-ai merged 1 commit into from
Apr 20, 2026
Merged

docs(plugins): add org-level plugin governance allowlist (PR #610) #36

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions content/docs/plugins.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -334,6 +334,44 @@ Defaults to `local://<name>` when omitted.

---

## Org-Level Plugin Governance

Tenant admins can restrict which plugins workspaces in their org are permitted to load using a per-org allowlist. When an allowlist is configured, workspaces can only install plugins explicitly listed — all other installs are blocked at load time.

### Managing the allowlist

```bash
# Allow a plugin in the org
curl -X POST http://localhost:8080/admin/orgs/{orgId}/plugins/allowlist \
-H "Authorization: Bearer <admin-token>" \
-H "Content-Type: application/json" \
-d '{"plugin_name": "molecule-audit-trail"}'

# Remove a plugin from the allowlist
curl -X DELETE http://localhost:8080/admin/orgs/{orgId}/plugins/allowlist/molecule-audit-trail \
-H "Authorization: Bearer <admin-token>"
```

Both endpoints require `AdminAuth`. `orgId` is the org's UUID (set via `MOLECULE_ORG_ID` for SaaS tenants; in self-hosted single-org mode this is the org record created at first startup).

### Behaviour when an allowlist is configured

| Scenario | Result |
|----------|--------|
| No allowlist entries for the org | All plugins are permitted (default; backward-compatible) |
| Allowlist has at least one entry | Only listed plugins may be installed; others return `403 Forbidden` |
| Plugin already installed when allowlist was created | Pre-existing installs are not removed, but the plugin cannot be re-installed if later uninstalled |

### Relationship to supply-chain pinning

The governance allowlist and supply-chain pinning (`PLUGIN_ALLOW_UNPINNED`) are independent:
- The **allowlist** controls *which* plugins workspaces can load.
- **Pinning** controls *how* plugins must be referenced (exact commit/tag, never `latest`).

Both can be active simultaneously — the most restrictive rule wins.

---

## API Reference

| Method | Path | Description |
Expand All @@ -346,3 +384,5 @@ Defaults to `local://<name>` when omitted.
| GET | `/workspaces/:id/plugins/available` | Available plugins filtered by workspace runtime |
| GET | `/workspaces/:id/plugins/compatibility?runtime=X` | Preflight runtime-change compatibility check |
| GET | `/workspaces/:id/plugins/:name/download` | Download plugin as tarball (external workspaces) |
| POST | `/admin/orgs/:orgId/plugins/allowlist` | Add a plugin to the org allowlist (AdminAuth) |
| DELETE | `/admin/orgs/:orgId/plugins/allowlist/:name` | Remove a plugin from the org allowlist (AdminAuth) |