Defines how third-party or internal extensions register capabilities, declare permissions, isolate failures, and upgrade without breaking the host application core.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Extend the host through manifest-driven plugins that declare capabilities and permissions before load. The host enforces isolation so extension failures disable the extension, not the core product. Upgrades are semver-gated with automatic rollback when health checks fail after deployment.
Scope
- Extension manifest schema, capability types, and permission declarations.
- Load-time validation, user consent, and runtime isolation boundaries.
- Health probing, failure thresholds, and disable versus crash behavior.
- Upgrade, rollback, and host API compatibility guarantees.
Outside this block
- Marketplace billing and revenue share.
- Full sandbox hypervisor design for untrusted native code.
- Feature flag infrastructure (see related feature-flags block).
Contract
- Runtime calls require declared permissions; undeclared access attempts fail closed at runtime and are audited.
- Load-time manifest schema validation rejects packages with missing required fields before code executes.
- Host api_surface_version v1 maps to semver range >=1.0.0 <2.0.0 for compatibility checks.
- User-consent permissions block activation until an authorized admin approves the listed scope.
- Consecutive health failures beyond the profile threshold disable the extension while the host remains available.
- API compatibility ranges in the manifest must match the host published API surface version rules.
- Signed packages are required when verification_required is true. The host verifies the declared package digest and publisher key id against its configured trust store, including key expiry and revocation status; unknown, expired, revoked, mismatched, or invalid signatures block installation before code load.
Implementation guidance
- Validate manifests in CI for internal extensions and at install time for third-party packages.
- Keep publisher trust anchors outside plugin-controlled content. Version the host trust store, refresh revocation information under a fail-closed freshness policy, and bind the signature to the canonical package digest plus manifest identity and version.
- Run extensions in isolated workers with memory and CPU caps from the manifest.
- Expose host APIs through a stable versioned surface; document breaking changes within the profile notice window.
- Log capability invocations with extension id, permission used, and calling workspace id for audit.
- Publish a compatibility matrix alongside host API releases so publishers can test proactively.
Failure handling and safeguards
- On extension timeout, abort the invocation and count toward failure threshold without blocking unrelated hooks.
- Roll back to the last healthy version automatically when post-upgrade probes fail.
- Quarantine extensions with repeated permission violations pending publisher review and host security sign-off.
- If revocation status or the required trust-store version cannot be established, reject new installation or upgrade; do not accept a key merely because its identifier appears in the plugin manifest.
Verification and operations
- Monitor extension crash rate, disable events, and permission denial counts.
- Test compatibility matrix across host API versions in staging before marketplace publication.
- Audit installed extensions quarterly for stale permissions.
- Re-evaluate installed packages when a publisher key is revoked and disable affected packages according to the incident profile.
The executable-looking examples in this package are fixtures and acceptance contracts. Validate package structure before adoption; then implement and execute the scenarios in the target repository.
Adoption assumptions
- Resource limits, thresholds, and sample extension id in
example.yamlandplugin-manifest.yamlare profile choices, not universal defaults. - Teams must provision signature trust anchors, key rotation and revocation feeds, and consent UX in their platform policies; the sample identifiers are fixtures only.
References
- No external normative source is required; this package defines an extension host contract.