Capabilities and Security

Capabilities And Security

Forsetti treats capability declarations as runtime policy inputs, not documentation-only metadata. Manifests declare requested capabilities and runtime requirements. Compatibility policy evaluates requested capabilities. Module contexts, requirement validation, default-role lookup, and UI contribution validation enforce the resulting permissions.

Capability Decision Flow

flowchart TD
    Manifest["Module manifest\ncapabilitiesRequested"]
    Policy["ICapabilityPolicy"]
    Report["CompatibilityReport"]
    Context["ForsettiContext\nscoped to module"]
    Provider["CapabilityScopedServiceProvider"]
    UI["UI contribution validation"]
    Roles["Default role catalog"]
    Module["Active module"]

    Manifest --> Policy
    Policy --> Report
    Report --> Context
    Context --> Provider
    Context --> UI
    Manifest --> Roles
    Provider --> Module
    UI --> Module
    Roles --> Module

Loading

Policy Layer

ICapabilityPolicy evaluates each requested capability for a module ID:

Type	Behavior
AllowAllCapabilityPolicy	Allows all requested capabilities. Useful for tests and simple hosts.
FixedCapabilityPolicy	Allows only capabilities in a configured set.

Hosts can provide their own ICapabilityPolicy implementation to bind capability decisions to product policy.

Scoped Service Access

Modules receive a ForsettiContext scoped to their module ID and granted capabilities. Service resolution passes through CapabilityScopedServiceProvider.

Service Interface	Required Capability
INetworkingService	networking
IStorageService	storage
ISecureStorageService	secure_storage
IFileExportService	file_export
ITelemetryService	telemetry

If a known governed service is requested without its capability, resolution returns no service and logs a warning.

Schema 1.1 I/O requirements also map kinds such as shared_database, authentication, diagnostics, api, and security to capability and default-role validation. Those roles must be supplied by the host when a manifest marks them required.

Module Communication Rules

Modules communicate through ForsettiContext::sendModuleMessage(). The context assigns the source module ID; callers cannot spoof another module's identity.

sequenceDiagram
    participant A as Source module
    participant Context as Scoped ForsettiContext
    participant Guard as ModuleCommunicationGuard
    participant Bus as EventBus
    participant B as Target module

    A->>Context: sendModuleMessage(target, type, payload)
    Context->>Guard: validate(source from context, target, type)
    Guard-->>Context: ok
    Context->>Context: remove payload sourceModuleID
    Context->>Bus: publish event
    Bus->>B: handler receives event

Loading

The default guard rejects:

• Empty source module IDs.
• Empty target module IDs.
• Self-messaging.
• forsetti.internal.* event namespaces.
• Module messaging from an unscoped context.

Framework events use publishFrameworkEvent() and are intentionally source-neutral.

Source Identity Protection

The event payload is sanitized so a caller-provided sourceModuleID field cannot override the framework-owned ForsettiEvent::sourceModuleID.

Field	Owner
ForsettiEvent::sourceModuleID	Framework-scoped context
Payload key named sourceModuleID	Removed during module message publishing

UI Contribution Capability Enforcement

Contribution	Required Capability
Toolbar items	toolbar_items
Toolbar overlay action	routing_overlay
Toolbar publish-event action	event_publishing
View injections	view_injection
Overlay schema	routing_overlay
Theme mask	Recognized as ui_theme_mask, but reserved for policy-approved framework presentation state.

Schema 1.1 UI contribution IDs must be declared in runtimeRequirements.ui. Toolbar item IDs, view IDs, slot IDs, route IDs, and pointer IDs are rejected when a module contributes undeclared identifiers.

Platform Adapter Hardening

Adapter	Protection
WinHttpNetworkingService	Rejects unsupported schemes and unsafe header values.
RegistryStorageService	Uses HKCU-backed storage and validates value names.
DpapiSecureStorageService	Protects bytes with Windows DPAPI and validates value names.
LocalFileExportService	Constrains writes to the configured export directory and sanitizes filenames.

Security Boundary Summary

flowchart LR
    Module["Module code"]
    Context["Scoped context"]
    Services["Capability-scoped services"]
    Bus["Framework event bus"]
    Surface["UI surface manager"]

    Module --> Context
    Context --> Services
    Context --> Bus
    Module --> Surface

    Services -. denied without capability .-> Module
    Bus -. rejects spoofed or reserved message .-> Module
    Surface -. strips reserved theme mask .-> Module

Loading

Capabilities do not replace entitlement checks. A module must be both compatible and entitled before activation.