Author: ObjectStack Core Team Created: 2026-06-01 Status: Design Specification Decisions: ADR-0025 (server/runtime plugins), ADR-0026 (client UI plugins) Companion to:
marketplace-publishing.md(metadata-package / App flow)
- 1. Scope & Relationship to the App Marketplace
- 2. The Three Distribution Layers
- 3. What Belongs in the Contribution Catalog
- 4. Artifact Format
- 5. Build → Sign → Publish
- 6. Install & Load
- 7. Trust & Isolation Tiers
- 8. Security Model
- 9. Versioning & Lifecycle
- 10. Worked Examples
- 11. Open Questions
This document operationalizes how code-bearing contributions (plugins with
executable code + npm dependencies, and client UI plugins) are built, signed,
distributed, and loaded. It is the supply-side companion to
marketplace-publishing.md, which covers the
consumer-facing App flow (metadata packages).
Audience boundary (ADR-0019). The consumer Marketplace lists only Apps
(type: app; isConsumerInstallable). Plugins, drivers, UI extensions, themes,
agents, and other internal contributions are never browsed or installed by an
end consumer. They reach a tenant by exactly two routes:
- Bundled inside an App — the App author composes them as build-time
dependencies (
plugins: [...]indefineStack), and the consumer installs the App as one atomic unit. - Operator-provisioned — a platform operator/admin installs them into a runtime/environment out-of-band (drivers, auth providers, connectors, observability exporters).
Accordingly there are two catalogs over one backbone:
| Consumer App Marketplace | Developer/Operator Contribution Catalog | |
|---|---|---|
| Lists | type: app only |
plugin/driver/ui/server/agent/… |
| Who installs | Any tenant user | App authors (compose) / operators (provision) |
| Surface | Console "App Marketplace" | CLI os plugin … + operator/dev tooling |
| Backbone | shared sys_* registry, signing, artifact storage |
same |
This design specifies the contribution catalog + backbone. It does not open a self-serve consumer-facing code marketplace — that remains the gated bet ADR-0019 §Out-of-scope parks, whose load-bearing wall (L2 sandbox + permission enforcer) is precisely what §7–§8 here build and harden.
The "metadata vs code" split is really a spectrum (ADR-0025 §3.10). Choosing a layer is a single question: does it need to execute code / reach an external system?
| Layer | Form | Trust decision at install | Channel | Doc |
|---|---|---|---|---|
| L0 — declarative | objects/views/flows/dashboards/permissions/themes/translations JSON | none (it is data) | JSON hot-register | marketplace-publishing.md |
| L1 — declarative + sandboxed script | JSON carrying L1 expressions / L2 ScriptBody (validations, formulas, small automations) |
"scripts allowed" only; runs in the existing QuickJS sandbox | JSON flow — no .osplugin |
this doc §7 (T1) |
| L2 — code plugin | npm deps + host APIs (drivers, connectors, AI, auth, …) | explicit permission consent + signature | .osplugin |
this doc |
Design consequence: most "custom logic" is L1 and never touches the heavy code-plugin pipeline. Reserve L2 (and this document's machinery) for contributions that genuinely carry dependencies or reach the host/network.
A scenario-driven catalog, with the recommended layer/tier for each. (Items
already present in packages/plugins/* are marked ✅.)
| Category | Examples | Layer | Tier | Notes |
|---|---|---|---|---|
| Data-source drivers | MongoDB ✅, SQL ✅, SQLite-WASM ✅, ClickHouse, Redis, S3 | L2 | T0 | Implements the storage protocol; holds a client/pool. Operator-provisioned. |
| Connectors / integrations | Salesforce, Stripe, Slack, Twilio, SAP, Shopify, GitHub, DocuSign, WeCom/DingTalk | L2 (declarative sub-path) | T0 internal / T2 third-party | OpenAPI/MCP-describable ones are declarative (ADR-0023/0024); only custom-auth/pagination/streaming fall to code. Secrets via KV (ADR-0007). |
| AI / ML extensions | LLM providers, Embedder ✅, vector stores, RAG backends ✅, reranker, OCR/speech, agent tools | L2 | T0/T2 | Network + service permissions; agent tools may run T1. |
| Identity / auth | SAML/OIDC SSO ✅, SCIM, LDAP, MFA | L2 | T0 | First-party/verified; deep host hooks. Operator-provisioned. |
| Automation / channels / notifications | record-change ✅ & schedule ✅ triggers, Webhooks ✅, FCM/APNs, SMS, email ✅, bidirectional channels | L2 (+ some L1) | T0/T2 | Small rules are L1; channel adapters are L2. |
| Governance / observability | audit ✅, RBAC/RLS ✅, org-scoping ✅, masking/DLP, backup, OTel/Datadog/Sentry exporters | L2 | T0 | First-party/verified; compose with RLS (§8). |
| Protocol / server surfaces | HTTP/GraphQL/gRPC gateway ✅ (hono), MCP server ✅, REST | L2 | T0 | Operator-provisioned. |
| Business rules / formulas | validation packs, computed-field libs, approval conditions, field dependencies | L1 | T1 | Ride the JSON flow + sandbox; no .osplugin. |
| Vertical apps & templates | CRM, PM, HRM, ITSM, dashboards, report/theme/translation/permission packs | L0 | — | Consumer Apps / declarative packages — not this catalog. |
| Client UI extensions | field renderers (signature, map, barcode), view types (org-chart, timeline, map), widgets | UI (ADR-0026) | U0/U1 | Browser bundle; bundled in an App or operator-provisioned. |
Best fit for the .osplugin L2 pipeline: drivers, connectors, AI extensions,
auth providers, notification/channel adapters, observability exporters, server
surfaces — each is bounded code + deps + a clear capability/permission surface
that maps cleanly onto the manifest's capabilities/permissions and the tiers.
Deliberately NOT code plugins: vertical apps/templates/themes (L0) and
validation/formula logic (L1) — making these .osplugin artifacts would be
over-engineering.
A tar.gz:
<id>-<version>.osplugin
├── objectstack.plugin.json # compiled manifest (below)
├── dist/ # pre-built ESM bundle (tsup); @objectstack/* externalized
├── assets/ README LICENSE icon
└── SIGNATURE # detached signature + publisher cert chain
Compiled manifest adds four blocks to the existing ObjectStackManifest:
engines (protocol + platform ranges), runtime (node|sandbox|worker),
packaging (bundled, the one strategy and the default — §4.3), permissions (services/hooks/network/fs
- RLS data scopes), and
integrity(per-file hashes).
Same .osplugin envelope, but type: ui, dist is a browser ESM
bundle default-exporting a register(host) function, and the manifest carries a
ui block (entry, shared singletons, extends extension points) plus
client-scoped permissions (data read/write via SDK, network → CSP, navigation).
Note (2026-09-23, #16140). This document originally spelled the UI plugin package type
ui-plugin. The closed set of plugin types (CORE_PLUGIN_TYPES,packages/spec/src/kernel/plugin.zod.ts) adoptedui, and bothManifestSchemaandPluginSchemarefuseui-plugin; this section and worked example C in §10 useui.
- Bundled — the one strategy, and the default.
os plugin buildinlines every dependency the entry imports intodist/index.mjs, so install is unpack + verify with no npm or toolchain at install time:os plugin installand the boot-time loader importdist/index.mjsas packed, and the artifact carries neitherpackage.jsonnor a lockfile.@objectstack/*is externalized as a host-provided peer-dep singleton (bundling it forks the engine — duplicate registries / brokeninstanceof/ double Zod validation). A native (.node) addon is refused by name at build, before any artifact is written.
Note (2026-10-29, #27679). This section used to list a second, opt-in strategy,
manifest-deps, which shippedpackage.json+ a lockfile for an install-timepnpm install. Nothing ever ran that install, so an artifact built with it could not load the dependencies it left out. It is retired (ADR-0025 v2 §3.3):PluginPackagingSchema(packages/spec/src/kernel/manifest.zod.ts) acceptsbundledalone and refusespackaging: 'manifest-deps'by name with its migration prescription (delete the key), andos plugin buildno longer forks on the value. A plugin that needs a native addon or a very large dependency is a fresh ADR-0025 M3 decision, not a strategy here. §4.1, §5, §6 and §8 name no second strategy.
os plugin build → os plugin sign → os plugin publish
- build — run
tsup(externalize@objectstack/*); validate the manifest (Zod + the newpermissionsschema); gate on protocol/engine compatibility; compute per-fileintegrity; emit<id>-<version>.osplugin. - sign — sign with the publisher key (
PluginMetadata.signature); may be server-side at publish. - publish — extends
os package publish:POST /cloud/plugins→ ensure asys_pluginrow (reverse-domain id, owner org).POST /cloud/plugins/:id/versions→ upload the.ospluginblob to object storage; store manifest/permissions/integrity/signature/engines/size/SBOM insys_plugin_version(status: pending_review → published).- Server gates: schema validation; secret/malware/known-vuln scan;
permission audit (sensitive permissions → human review); publish-time
tier enforcement (an unverified publisher cannot ship
runtime: 'node'); marketplace counter-signs with the platform key on approval. - Listed in the contribution catalog (not the consumer App Marketplace), with a "contains code" badge and a permission-disclosure screen.
Install is a deliberate, permissioned action performed by a developer (composing an App) or an operator (provisioning a runtime):
resolve → compat check → permission consent → download+verify → materialize → register → load
- Resolve
id@version(or latest matching the engine/protocol range) → manifest, download URL, signature, declared permissions, dependency closure. - Compatibility (protocol-first). Verify the host provides each
capabilities.implements[].protocolat a compatible version; thenengines.platform/engines.protocolas a secondary guard. Topologically order plugin→pluginrequires; fetch deps. - Permission consent. Present declared permissions (services / hooks / fs /
network hosts / RLS data scopes / extension points). The granted set is
persisted and enforced by
PluginPermissionEnforcer. Secret-typed config fields are wired to the KV secret store (ADR-0007) — never stored in the artifact. - Download + verify. Verify signature (publisher + marketplace keys) and each
file against
integrity; reject on mismatch. - Materialize. Unpack to
<OS_HOME>/plugins/<env>/<id>/<version>/. No dependency install runs here: the bundle is imported as packed (§4.3). - Register. Write
sys_plugin_installation(env_id, plugin_id, version_id, granted_permissions incl. RLS scopes, status, is_preview). Persist to a local store so installs survive restarts (the ADR-0016 §9.7 disable-state pattern). - Load + activate. On boot (or hot, when
hotReloadable), the loader scans installed plugins, dynamic-imports the entry, wrapsPluginContextwith the enforcer scoped to the granted set, and runsinit → startin dependency order.contributesmetadata is hot-registered like a pure-element package.
Local-first parity. os plugin install ./x.osplugin (and a Studio upload for
operators) hit a marketplace/install-local-style endpoint (inline artifact,
register-before-persist per ADR-0016 §9.3). Local artifacts need no cloud account;
signature is still verified (or --trust-unsigned for dev).
UI plugins (ADR-0026 §3.5). No on-disk Node materialize — the browser bundle
is served to the SPA and registered into the ObjectUI extension registry at console
boot; sys_plugin_installation records enabled UI plugins + client grants.
Server/runtime (ADR-0025 §3.6), default-deny:
| Tier | runtime |
Load | For | Mechanism |
|---|---|---|---|---|
| T0 Trusted | node |
in-process dynamic import |
first-party / verified / enterprise-signed | full PluginContext, capability-gated |
| T1 Sandboxed | sandbox |
QuickJS-WASM (quickjs-runner.ts) |
pure-logic plugins (hooks/formulas/transforms) — also the L1 layer | no Node API; only gated ctx.api/crypto/log |
| T2 Out-of-process | worker |
worker/child-process/WASM + RPC | untrusted 3rd-party needing richer APIs | crash/timeout/memory isolation |
T0 is opt-in, not default. In-process = arbitrary code in the host process = the platform's biggest risk surface; it is reserved for verified publishers and enforced at publish. Unverified third-party plugins default to T1/T2.
Client UI (ADR-0026 §3.3): U0 in-app module (verified; shared React/design-
system singletons) vs U1 iframe sandbox (third-party default; postMessage
RPC + per-plugin CSP, no allow-same-origin).
Reuses existing components, adds two compositions:
- Signing. Publisher signs; marketplace counter-signs on approval; host ships trusted roots; verify chain at install and load.
- Permissions + RLS. The coarse service/hook/file/network gate
(
PluginPermissionEnforcer) is composed with object/field-level security (plugin-security/RLS): data-affecting grants reference RLS scopes, so a connector authorized foraccountreads still cannot exceed field-level RLS. All denials logged. (ADR-0025 §3.10 #4.) - Secrets.
configurationsecret fields → KV secret store (ADR-0007) via secret-refs; the artifact never carries credentials; the plugin reads them throughPluginContextgated by the network/service permission. - Supply chain. Per-file integrity; server-side secret/vuln scans; SBOM on
the version row; no install-time package manager at all (bundled only,
§4.3), so no dependency's
postinstallever runs. - Server-authoritative UI data. UI plugins read/write only via the client SDK
under the user's session → every access re-checked by server RLS; manifest
permissions.datais a UI hint/guard, not the boundary. U1 iframes cannot read host cookies/tokens. - Reversible disable. Reuse package enable/disable + disable-state-store (ADR-0016 §9.5/§9.7).
Parallel to packages: sys_plugin (identity) / sys_plugin_version (immutable
semver, checksum, signature, permissions, engines, SBOM, blob pointer) /
sys_plugin_installation (env ↔ version, granted permissions, is_preview).
- Compatibility gated protocol-first (§6 step 2). Support deprecate/yank.
- Update = install the new version side-by-side, swap the installation pointer. If the new version widens permissions (services, hooks, network hosts, or RLS scopes), require re-consent before activation.
- Disable stops loading code + unregisters contributions on next boot; reversible and non-destructive.
A. ClickHouse driver (operator-provisioned, T0).
type: driver, runtime: node, implements storage.protocol.v1, permissions: { network: ['clickhouse.internal'] }, secret DSN via KV. Operator runs
os plugin install, consents to the network grant, the driver registers into the
driver registry on boot. Never in the consumer Marketplace.
B. Stripe connector bundled into a "Billing" App (T0 internal).
App author composes @acme/connector-stripe (.osplugin) as a build-time
dependency; the connector's permissions (network api.stripe.com, RLS write on
invoice) surface in the App's permission-disclosure screen. The consumer installs
the App; the connector rides inside it. Stripe API key → KV secret-ref at App
install.
C. Community "fancy gauge" widget (UI, U1 default).
type: ui, runtime: ui, unverified publisher → U1 iframe only, CSP
connect-src empty, data via scoped SDK (RLS-gated). Bundled into whatever App's
dashboard uses it, or operator-enabled org-wide.
D. A validation pack (L1, no .osplugin).
A "VAT number format" check ships as JSON with an L2 ScriptBody; installs via the
normal JSON package flow, runs in the QuickJS sandbox (T1). No signing, no
permission prompt, no artifact.
- Key management & rotation for publisher and host root keys.
- Permission-widening UX on update — auto-disable until re-consent vs. run on old grant.
- T2 RPC surface — the minimal host-service contract an out-of-process plugin gets, mediated by the enforcer.
- Cross-plugin dependency conflicts (diamond/version) at install time.
- UI U0 sharing — module federation vs. native import-map for React/design- system singletons.
- When (if ever) to open the self-serve consumer code marketplace — the ADR-0019 gated bet, contingent on proving §7–§8 hardness.
End of Document