PSA/ee/docs/extension-system/security_signing.md

Extension Security & Signing

This document specifies the v2-only signing, provenance, and isolation model for Enterprise extension bundles. All extensions are published and installed as signed, content-addressed artifacts. Verification is enforced during publish/install and again at load/serve time. Execution occurs out-of-process in the Runner with strict capability and resource policies.

Key integration points:

• Registry v2 for versions, manifests, content hashes, and signatures: ExtensionRegistryServiceV2
• Gateway route that proxies extension HTTP calls to Runner: server/src/app/api/ext/[extensionId]/[[...path]]/route.ts
• UI delivery served by Runner at ${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...], with iframe initialization via buildExtUiSrc() and bootstrapIframe()

Principles

• No tenant code runs inside the host app process
• All code executes out-of-process in the Runner under strict limits
• Bundles are immutable, content-addressed (sha256:…) and signed; verified on install and on load
• Capabilities, egress, and quotas are enforced by the Gateway and Runner

Signed, Content-Addressed Bundles

• Compute SHA256 over the canonical bundle (manifest, WASM, assets)
• Store artifacts in object storage under sha256/<hash> paths
• Persist a detached signature alongside registry metadata
• Registry records content_hash, signature, publisher identity, and optional SBOM reference
• Example content hash format: sha256:012345...abcd

Trust & Verification

• Trust bundle configured via SIGNING_TRUST_BUNDLE (PEM), containing accepted publisher certificates/keys
• Verification points:
  1. On publish/install in Registry
  2. On load/serve by the Runner (defense in depth)
• Verification steps:
  • Resolve and load trust anchors
  • Validate signature over the canonical digest for content_hash
  • Reject on mismatch, untrusted signer, or invalid chain

Gateway Policies

• All extension HTTP calls go through /api/ext/[extensionId]/[[...path]]
• Gateway resolves tenant install/version and matches the manifest endpoint
• Enforcement at the edge:
  • Request/response size caps (e.g., 5–10 MB)
  • Timeouts via EXT_GATEWAY_TIMEOUT_MS
  • Header allowlist (strip end-user authorization; inject service-level headers)
  • Per-tenant rate limits and request normalization
• The Gateway proxies to Runner POST /v1/execute and maps responses using a safe header allowlist

Reference route scaffold: server/src/app/api/ext/[extensionId]/[[...path]]/route.ts

Runner Isolation

• Runtime: Wasmtime with pooling allocator and epoch-based timeouts
• Limits: memory/time/fuel per invocation; concurrency caps per tenant/extension
• Capability-scoped Host APIs (alga.*):
  • http.fetch with egress allowlist (EXT_EGRESS_ALLOWLIST)
  • storage.kv with tenant/extension scoping
  • secrets.get via brokered access; plaintext minimized
  • log and metrics with structured output and cardinality control
• Response policy: safe header allowlist (content-type, safe cache-control, custom x-ext-*); disallow set-cookie

UI security:

• Static UI served by Runner at ${RUNNER_PUBLIC_BASE}/ext-ui/{extensionId}/{content_hash}/[...]
• Iframe sandbox defaults and origin validation in host bootstrap:
  • buildExtUiSrc()
  • bootstrapIframe()

Quotas & Observability

• Quotas per tenant/extension:
  • Concurrency, rate limits, memory/time/fuel bounds
• Observability:
  • Structured execution logs with correlation IDs (request/tenant/extension/version/content_hash)
  • Metrics (Runner and Gateway):
    • Invocation duration, memory usage, fuel, egress bytes, error counts, timeouts
• Data model alignment (examples):
  • extension_execution_log, extension_quota_usage

Environment & Configuration

• Gateway:
  • RUNNER_BASE_URL — internal URL used to call Runner POST /v1/execute
  • EXT_GATEWAY_TIMEOUT_MS — default timeout for gateway→runner calls
• Runner:
  • RUNNER_PUBLIC_BASE — public origin used to serve ext-ui assets
  • SIGNING_TRUST_BUNDLE — trust anchors (PEM) for signature verification
  • EXT_EGRESS_ALLOWLIST — permitted hostnames for alga.http.fetch
• Storage:
  • Content-addressed root/prefix for bundle artifacts (e.g., MinIO/S3)

Failure Modes & Error Mapping

• Signature/Integrity errors:
  • Registry/Runner reject install/load; mark version invalid or serve 502 with safe error
• Timeout/Quota exceeded:
  • Map to 504/429 as appropriate; include x-request-id
• Unsupported capability or endpoint mismatch:
  • 403 for capability denial; 404 for endpoint not in manifest
• Oversized payloads or headers:
  • 413 for size limit exceeded; 400 for malformed

References

• Manifest v2
• API Routing Guide
• Registry Implementation
• Gateway route: server/src/app/api/ext/[extensionId]/[[...path]]/route.ts
• Iframe bootstrap: buildExtUiSrc(), bootstrapIframe()
• Registry service scaffold: ExtensionRegistryServiceV2