logos-capability-module/docs/docs.md

Logos Capability Module Specification

note: This document is a living document describing the current state of the capability module.

Table of Contents

• 1. Overview and Goals
• 2. Architecture
  • 2.1 Role in Logos
  • 2.2 Tokens and Authentication
• 3. API Description
  • 3.1 Capability Module Interface
• 4. Implementation
  • 4.1 Module Structure
  • 4.2 Responsibilities
  • 4.3 Token Flow
• 5. Usage
  • 5.1 Remote API Usage
  • 5.2 Metadata

1. Overview and Goals

The Capability Module is the broker that coordinates authentication tokens between Logos modules. When one module wants to call another, it requests a capability token instead of bypassing auth. The capability module issues a token, informs the target module about it, and returns the token to the requester so both sides share the same secret.

2. Architecture

2.1 Role in Logos

• Runs as a standard Logos plugin implementing PluginInterface.
• Loaded early by the core (often automatically in Remote mode).
• Exposes a single RPC surface (requestModule) so other modules or apps can obtain permission to call a target module.
• Uses the SDK (LogosAPI, LogosAPIClient, TokenManager) for RPC and token storage.

2.2 Tokens and Authentication

• Qt Remote Objects provides no built-in auth. The capability module issues per-pair tokens for inter-module calls.
• Tokens are stored in the shared TokenManager keyed by module name.
• When issuing a token, the capability module uses its own client to inform the target module of the new token so that the target’s ModuleProxy can validate subsequent calls.

3. API Description

3.1 Capability Module Interface

The capability module implements CapabilityModuleInterface (and PluginInterface) with a single primary method:

Method	Purpose
requestModule(fromModuleName, moduleName) → QString	Generates a fresh token for fromModuleName to call moduleName, informs the target of the token, and returns it to the caller.

Signals:

• eventResponse(eventName, data) – present for event compatibility (currently unused by the module itself).

4. Implementation

4.1 Module Structure

logos-capability-module/
├── capability_module_plugin.h/cpp   # Plugin implementation
├── capability_module_interface.h    # Interface definition (inherits PluginInterface)
├── metadata.json                    # Plugin metadata
├── nix/                             # Nix build configs
├── scripts/                         # Helper build scripts
└── docs/                            # This document

4.2 Responsibilities

• Token issuance for inter-module calls: On requestModule, generate a UUID token for the caller/target pair.
• Inform targets of new tokens: Use LogosAPIClient::informModuleToken_module to tell the target module the new token (using the capability module’s own token for that target).
• Central coordination: Current implementation always grants requests; future versions may enforce capability/permission policies.

4.3 Token Flow

1. Caller invokes requestModule(from, target).
2. Capability module creates a UUID token.
3. It looks up its auth token for the target from TokenManager.
4. Calls informModuleToken_module on the target (via LogosAPIClient) with: capability module’s token, target module name, requester name, new token.
5. Returns the new token to the caller. Both sides now share the token for subsequent RPCs.

5. Usage

5.1 Remote API Usage

Modules or apps call the capability module via Logos RPC (e.g., using generated wrappers or LogosAPIClient):

// Using generated wrappers
LogosModules logos(api); // api is a LogosAPI* for your module/app
QString token = logos.capability_module.requestModule("chat_ui", "waku_module");

The returned token must be used by the caller when invoking methods on the target module; SDK clients attach it automatically.

5.2 Metadata

metadata.json fields include:

• name: capability_module
• version: semantic version string
• description: describes token brokering/coordination
• author: module author/maintainer
• type: core
• capabilities: typically includes module_coordination, permission_management
• dependencies: usually none (bundled with core)