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 loaded by the core.
• Implemented as a LogosProviderBase subclass — Qt plugin glue and dispatch are generated by logos-cpp-generator from the impl header at build time.
• 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; LogosAPI* is delivered to the impl via LogosProviderBase::onInit.

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 impl class CapabilityModuleImpl inherits LogosProviderBase and exposes a single primary method via the LOGOS_METHOD marker (the framework discovers it from the header at build time):

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.

Events are emitted via LogosProviderBase::emitEvent(name, data). The module currently emits none.

4. Implementation

4.1 Module Structure

logos-capability-module/
├── src/
│   ├── capability_module_impl.{h,cpp}   # LogosProviderBase subclass; LOGOS_METHOD requestModule
│   └── capability_module_loader.h       # Qt plugin loader (Q_PLUGIN_METADATA → metadata.json)
├── tests/                               # Unit tests via logos-test-framework
│   ├── CMakeLists.txt
│   ├── main.cpp
│   └── test_capability_module.cpp
├── metadata.json                        # interface: provider; nix.* build config
├── flake.nix                            # mkLogosModule call
├── CMakeLists.txt                       # logos_module() call
└── docs/                                # This document

The Qt glue file generated_code/logos_provider_dispatch.cpp (containing callMethod / getMethods for the impl) is produced at build time by logos-cpp-generator --provider-header and is not checked in.

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:

• name: capability_module
• version: semantic version string
• description: describes token brokering/coordination
• author: module author/maintainer
• type: core
• interface: provider — selects the LogosProviderBase + LOGOS_METHOD codegen path
• capabilities: typically includes module_coordination, permission_management
• dependencies: usually none (bundled with core)
• nix: build configuration consumed by logos-module-builder (packages, external_libraries, cmake flags)