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](#1-overview-and-goals)
- [2. Architecture](#2-architecture)
  - [2.1 Role in Logos](#21-role-in-logos)
  - [2.2 Tokens and Authentication](#22-tokens-and-authentication)
- [3. API Description](#3-api-description)
  - [3.1 Capability Module Interface](#31-capability-module-interface)
- [4. Implementation](#4-implementation)
  - [4.1 Module Structure](#41-module-structure)
  - [4.2 Responsibilities](#42-responsibilities)
  - [4.3 Token Flow](#43-token-flow)
- [5. Usage](#5-usage)
  - [5.1 Remote API Usage](#51-remote-api-usage)
  - [5.2 Metadata](#52-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`):

```cpp
// 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)