284313f908
Some checks are pending
Bidi Control Character Guard / bidi-control-guard (push) Waiting to run
Circular Dependency Check / Check for new circular dependencies (push) Waiting to run
Citus Migration Smoke / Combined migrations on single-node Citus (push) Waiting to run
E2E Fresh Install Tests / fresh-install-e2e (push) Waiting to run
ext-v2 guardrails / Run ext-v2 guard and ESLint (push) Waiting to run
Integration Tests / Check for relevant changes (push) Waiting to run
Integration Tests / ${{ (github.event_name == 'schedule' || github.event.inputs.suite == 'full') && 'Full integration suite' || 'Tier-1 integration subset' }} (push) Blocked by required conditions
Mobile checks / Mobile lint + typecheck (push) Waiting to run
Mobile checks / Mobile unit tests (push) Waiting to run
Mobile checks / Mobile dependency audit (report) (push) Waiting to run
Mobile checks / Mobile reproducibility checks (push) Waiting to run
Secrets guard (env backups) / Ensure no tracked env backup files (push) Waiting to run
Temporal Readiness / fast-readiness (push) Waiting to run
Temporal Readiness / docker-parity (push) Waiting to run
TypeScript Type Check / Nx affected typecheck (push) Waiting to run
Unit Tests / Skipped-test budget (push) Waiting to run
Unit Tests / Nx affected unit tests (push) Waiting to run
Unit Tests / Server unit coverage (informational) (push) Waiting to run
Validate Tenant Management Schema / Check for relevant changes (push) Waiting to run
Validate Tenant Management Schema / Validate Tenant Management Schema (push) Blocked by required conditions
EE Workflows Build Guard / ee-workflows-build-guard (push) Waiting to run
Excluded: .git, node_modules, secrets/, compose.env, assemblyscript tgz Source: /opt/alga-psa on psa.joliet.tech
64 lines
3.6 KiB
Markdown
64 lines
3.6 KiB
Markdown
# Comprehensive Extension System Analysis Report (Enterprise v2)
|
||
|
||
Date: Aug 2025
|
||
|
||
This report describes the Enterprise v2 extension architecture and the design decisions behind it. The system prioritizes multi‑tenant isolation, signed and content‑addressed artifacts, a strict API Gateway, and iframe‑only UI hosted by the Runner.
|
||
|
||
## Executive Summary
|
||
|
||
The v2 model provides:
|
||
- Out‑of‑process execution in a dedicated Runner (Rust + Wasmtime) with resource limits and capability‑scoped host APIs
|
||
- Signed, content‑addressed bundles stored in object storage and verified at install and load time
|
||
- A Next.js API Gateway at `/api/ext/[extensionId]/[[...path]]` (manifest endpoints advisory) that proxies to Runner `POST /v1/execute` with strict header/size/time policies
|
||
- UI delivered exclusively via sandboxed iframes; static assets are served by the Runner at `${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]`
|
||
|
||
These choices materially improve isolation, provenance, security, and operability.
|
||
|
||
## Target Architecture
|
||
|
||
- Runner (Rust + Wasmtime)
|
||
- Pooling allocator, epoch timeouts, memory caps, optional fuel
|
||
- Capability‑scoped host APIs: storage, http egress, secrets, logging, metrics
|
||
- Static UI hosting by content hash at `${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]`
|
||
- Execute endpoint: `POST /v1/execute`
|
||
- Registry & Bundles
|
||
- Tables: `extension_registry`, `extension_version`, `extension_bundle`, `tenant_extension_install`, `extension_event_subscription`, `extension_execution_log`, `extension_quota_usage`
|
||
- Version metadata includes `content_hash`, signatures, runtime, optional precompiled artifacts
|
||
- Gateway (Next.js)
|
||
- Route: `/api/ext/[extensionId]/[[...path]]`
|
||
- Resolves tenant install → version → manifest endpoint
|
||
- Normalizes request and proxies to Runner `POST /v1/execute`
|
||
- UI Delivery (Runner‑hosted)
|
||
- Immutable static assets at `${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]`
|
||
- Host constructs iframe src via [buildExtUiSrc()](../../../server/src/lib/extensions/ui/iframeBridge.ts:38) and bootstraps via [bootstrapIframe()](../../../server/src/lib/extensions/ui/iframeBridge.ts:45)
|
||
|
||
## Data Model (Initial)
|
||
|
||
- `extension_registry`, `extension_version`, `extension_bundle`
|
||
- `tenant_extension_install`, `extension_event_subscription`
|
||
- `extension_execution_log`, `extension_quota_usage`
|
||
|
||
See: [registry_implementation.md](registry_implementation.md) and [manifest_schema.md](manifest_schema.md)
|
||
|
||
## Security and Policy
|
||
|
||
- No tenant code executes in the core app process
|
||
- Signed, content‑addressed bundles (sha256:…) with verification against a trust bundle
|
||
- Capability‑based host APIs; deny‑by‑default egress with allowlists
|
||
- Gateway header allowlists and size/time limits; Runner response header allowlists
|
||
- Sandboxed iframe UI; origin validation aligned with `RUNNER_PUBLIC_BASE`
|
||
|
||
## Observability
|
||
|
||
- Structured execution logs with correlation IDs (request/tenant/extension/version/content_hash)
|
||
- Metrics for invocation duration, memory, fuel, egress bytes, and errors
|
||
|
||
## References
|
||
|
||
- [API Routing Guide](api-routing-guide.md)
|
||
- [Security & Signing](security_signing.md)
|
||
- [Overview](overview.md)
|
||
- Gateway route scaffold: [server/src/app/api/ext/[extensionId]/[[...path]]/route.ts](../../../server/src/app/api/ext/%5BextensionId%5D/%5B%5B...path%5D%5D/route.ts)
|
||
- Iframe bootstrap and src builder: [server/src/lib/extensions/ui/iframeBridge.ts](../../../server/src/lib/extensions/ui/iframeBridge.ts:38)
|
||
- Registry service scaffold: [ExtensionRegistryServiceV2](ee/server/src/lib/extensions/registry-v2.ts:48)
|