159 lines
6.9 KiB
Markdown
159 lines
6.9 KiB
Markdown
# Plan: Settings Integrity and Controls Reorganization
|
|
|
|
## Objective
|
|
Create a single coherent configuration model for Security, Commands, and Tasks so UI labels, enforcement behavior, docs, and navigation all match actual runtime behavior.
|
|
|
|
## Current Integrity Findings
|
|
|
|
### 1) Scope Registry and Enforcement Are Out of Sync
|
|
- Gateway command routes enforce scopes that are not exposed in Fine-Grained Security Scopes:
|
|
- `gateway.contacts`
|
|
- `gateway.help`
|
|
- `gateway.whoami`
|
|
- Fine-Grained Security Scopes currently expose only:
|
|
- `gateway.tasks`, `gateway.approval`, `tasks.submit`, `tasks.commands`, `command.bp`, `command.codex`, `command.claude`
|
|
- Result: users cannot configure all enforced gateway capabilities from the UI.
|
|
|
|
### 2) “Require Trusted Fingerprint” Semantics Are Incorrect
|
|
- UI and labels imply trust-list based enforcement.
|
|
- Runtime policy enforcement checks `UserXmppOmemoState.latest_client_key` equality, not `UserXmppOmemoTrustedKey` trust records.
|
|
- Result: behavior is “match latest observed key,” not “require trusted fingerprint.”
|
|
|
|
### 3) Command Surfaces Are Split Across Inconsistent Places
|
|
- Command Routing UI create flow exposes command slugs: `bp`, `codex`.
|
|
- Runtime command engine auto-bootstraps `claude` profile and bindings.
|
|
- Security scopes include `command.claude`, but Command Routing create UI does not.
|
|
- Result: commands are partially configurable depending on entrypoint.
|
|
|
|
### 4) Task and Command Control Planes Interlock Implicitly, Not Explicitly
|
|
- Task settings contain provider approval routing (Codex/Claude approver service/identifier).
|
|
- Security permissions contain policy gates (`tasks.*`, `command.*`, `gateway.*`).
|
|
- Command Routing controls profile/binding/variant policy.
|
|
- These are tightly coupled but not represented as one layered model in UI/docs.
|
|
|
|
### 5) Settings Shell Coverage Is Incomplete
|
|
- Shared settings hierarchy nav is context-processor driven and route-name based.
|
|
- Settings routes missing from modules/general/security group coverage include:
|
|
- `codex_settings`
|
|
- `codex_approval`
|
|
- `translation_preview`
|
|
- Result: some settings pages can miss expected local tabs/title context.
|
|
|
|
### 6) Documentation Drift
|
|
- Undocumented or under-documented features now in production behavior:
|
|
- Fine-Grained Security Scopes + Global Scope Override
|
|
- OMEMO trust management and per-direction encryption toggles
|
|
- Business Plan Inbox under Settings Modules
|
|
- Potentially misleading documentation:
|
|
- Security wording implies trusted-key enforcement that is not implemented.
|
|
|
|
## Reorganization Principles
|
|
1. One capability registry, reused by:
|
|
- Security Permissions UI
|
|
- command/task/gateway dispatch
|
|
- documentation generation
|
|
2. One settings-shell contract for every `/settings/*` page:
|
|
- title
|
|
- category tabs
|
|
- breadcrumb
|
|
3. Explicit layered model:
|
|
- Layer A: transport encryption/security
|
|
- Layer B: capability permissions (scope policy)
|
|
- Layer C: feature configuration (tasks/commands/providers)
|
|
4. No hardcoded duplicated scope lists in multiple files.
|
|
|
|
## Target Information Architecture
|
|
|
|
### Security
|
|
- `Encryption`: OMEMO transport controls + trust management.
|
|
- `Permissions`: Fine-Grained Security Scopes (capability policy only).
|
|
- `2FA`: account factor settings.
|
|
|
|
### Modules
|
|
- `Commands`: command profiles, bindings, variant policies.
|
|
- `Tasks`: extraction/defaults/overrides/provider pipelines.
|
|
- `Translation`: translation bridge settings.
|
|
- `Availability`: adapter availability controls.
|
|
- `Business Plans`: inbox/editor for generated artifacts.
|
|
|
|
### General
|
|
- `Notifications`
|
|
- `System`
|
|
- `Accessibility`
|
|
|
|
### AI
|
|
- `Models`
|
|
- `Traces`
|
|
|
|
## Phased Execution Plan
|
|
|
|
## Phase 1: Canonical Capability Registry
|
|
1. Add a central capability registry module (single source of truth):
|
|
- key
|
|
- label
|
|
- description
|
|
- group (`gateway`, `tasks`, `commands`, `agentic`, etc.)
|
|
- owning feature page URL
|
|
2. Migrate SecurityPage scope rendering to this registry.
|
|
3. Migrate gateway/command/task dispatchers to reference registry keys.
|
|
4. Add automated integrity test:
|
|
- every enforced scope key must exist in registry
|
|
- every registry key marked user-configurable must appear in Permissions UI
|
|
|
|
## Phase 2: Trusted Key Enforcement Correction
|
|
1. Define authoritative trust policy behavior:
|
|
- `require_trusted_fingerprint` must validate against `UserXmppOmemoTrustedKey`.
|
|
2. Preserve backwards compatibility via migration path:
|
|
- existing latest-key behavior can be temporarily represented as an optional fallback mode.
|
|
3. Update labels/help to match exact behavior.
|
|
4. Add tests:
|
|
- trusted key allows
|
|
- untrusted key denies
|
|
- unknown key denies
|
|
|
|
## Phase 3: Commands/Tasks Control Plane Alignment
|
|
1. Unify command surface definitions:
|
|
- Command Routing create/edit options include all supported command slugs (`bp`, `codex`, `claude`).
|
|
2. Add explicit cross-links:
|
|
- Tasks settings references Command Routing and Permissions scopes directly.
|
|
- Command Routing references Permissions scopes affecting each profile.
|
|
3. Introduce capability-impact preview panel:
|
|
- for each command/task action, show effective allow/deny by scope and channel.
|
|
|
|
## Phase 4: Settings Shell Normalization
|
|
1. Replace route-name allowlists in `settings_hierarchy_nav` with category mapping table.
|
|
2. Ensure all `/settings/*` pages declare category + tab metadata.
|
|
3. Include missing routes (`codex_settings`, `codex_approval`, `translation_preview`) in shell.
|
|
4. Add test to fail when a `/settings/*` route lacks shell metadata.
|
|
|
|
## Phase 5: Documentation Synchronization
|
|
1. Add a settings matrix doc generated (or validated) from the capability registry:
|
|
- capability key
|
|
- UI location
|
|
- enforced by code path
|
|
2. Update `README.md` and `INSTALL.md` security/modules sections.
|
|
3. Add "policy semantics" section clarifying:
|
|
- encryption-required vs per-scope OMEMO requirements
|
|
- trusted key behavior
|
|
- global override precedence
|
|
|
|
## Acceptance Criteria
|
|
- Every enforced scope is user-visible/configurable (or intentionally internal and documented).
|
|
- “Require Trusted Fingerprint” enforcement uses trust records, not only latest observed key.
|
|
- Command Routing and runtime-supported command slugs are aligned.
|
|
- All `/settings/*` pages show consistent settings shell navigation.
|
|
- Security/tasks/commands docs reflect real behavior and pass integrity checks.
|
|
|
|
## Risks and Mitigations
|
|
- Risk: policy behavior change blocks existing workflows.
|
|
- Mitigation: add compatibility flag and staged rollout.
|
|
- Risk: registry migration introduces missing scope mappings.
|
|
- Mitigation: integrity test that compares runtime-enforced keys vs registry.
|
|
- Risk: UI complexity increase.
|
|
- Mitigation: keep layered model with concise, context-aware summaries.
|
|
|
|
## Implementation Notes
|
|
- Keep migration incremental; avoid big-bang rewrite.
|
|
- Prioritize Phase 1 + Phase 2 first, because they are correctness and security semantics issues.
|
|
- Do not add new transport-specific branches; keep service-agnostic evaluation path in policy engine.
|