Qortal-Nextcloud-Integration/docs/settings-matrix.md

Settings Matrix (Admin + Personal)

This file tracks whether each visible setting is active, what it controls, and where it is enforced.

Admin Settings

Setting	Status	Effective Scope	Notes
Broker Base URL	Active	Nextcloud app + broker API calls	Required for most admin/user API actions.
Broker Internal API Token	Active	Broker internal API auth	Must match broker env BROKER_INTERNAL_API_TOKEN.
External Auth Base URL	Active	Broker runtime/env	Used by broker to call external-auth.
External Auth App ID / Secret	Active	Broker runtime/env	Required for broker-authenticated daemon calls.
External Auth Docs URL	Informational	Admin UI only	Convenience link/reference, not runtime behavior.
External Auth Node URL	Active	External-auth daemon runtime/env	Used by daemon for node API/render calls.
External Auth Node API Key	Active	External-auth daemon runtime/env	Required when node enforces X-API-KEY.
External Auth Node API Key Mode	Simplified Active	External-auth daemon runtime/env	UI now enforces paths only.
External Auth Node API Key Paths	Active	External-auth daemon runtime/env	/ sends API key for all node paths.
OIDC Issuer URL	Active	OIDC provider setup	Used in generated/applied user_oidc setup.
OIDC Client ID / Secret	Active	OIDC provider setup	Used in generated/applied user_oidc setup.
Policy Mode Override	Active	Broker OIDC policy	Admin override persisted in app settings.
Guard Override	Active	Broker OIDC policy	Admin override persisted in app settings.
Invite TTL Override	Active	Broker OIDC policy	Admin override persisted in app settings.
Redirect Allowlist Override	Active	Broker OIDC policy	Admin override persisted in app settings.
Nextcloud Public URL	Active	Setup helper + UI links	Used for setup plan and links.
Qortal Node URL	Active	Q-Apps render + node calls	Used by gateway proxy and node API usage.
Qortal Node API Key	Active	Node API calls + runtime fallback	Used directly for node calls; also runtime fallback for external-auth key sync.
Qortal Gateway URL	Active	Gateway proxy fallback	Used when direct node URL is not used.
Allow Insecure Gateway TLS	Active	Gateway proxy/node client	Disables TLS verification when enabled.
Feature QDN Backups toggle	Active	UI flow gating	Enables/disables QDN backup workflow surfaces.
Feature Q-Mail toggle	Active	UI flow gating	Enables/disables Q-Mail workflow surfaces.
Q-Apps Enabled	Active	App menu + Q-Apps UI	Controls Q-Apps availability.
Q-Apps Full Browser Enabled	Active	Q-Apps UI	Enables full browser launch card.
Q-Apps Full Browser Address	Active	Q-Apps UI	Default address for browser mode.
Q-Apps Debug Enabled	Active	Q-Apps UI	Enables debug panel by default.
Q-Apps List	Active	App menu + Q-Apps page	Approved app registry.

Personal/User Settings

Setting	Status	Effective Scope	Notes
Default Approval Policy	Active	Q-Apps approval modal defaults	Used to preselect approval behavior.
Default X Minutes	Active	Q-Apps approval modal defaults	Used with temporary type approval mode.
Default unlock for 10 min	Active	Q-Apps approval modal defaults	Prechecks unlock TTL option when wallet is locked.
Default keep unlocked for 20 min	Active	Unlock modal defaults	Prechecks unlock session duration option.
Persisted approval rules list	Active	Q-Apps permission management	Reads/stores per-user rule snapshots and revoke actions.

Removed/Simplified Controls

• External Auth Node API Key Mode=auto was removed from the Admin UI.
  • Reason: behavior was ambiguous and caused operator confusion.
  • Current behavior: Admin UI enforces paths mode and defaults path list to /.

Operational Note

For bundled/containerized external-auth, node API key should still be set in .env.devprod as:

• QORTAL_AUTH_NODE_API_KEY=...
• QORTAL_AUTH_NODE_API_KEY_MODE=paths
• QORTAL_AUTH_NODE_API_KEY_PATHS=/

The Admin UI runtime sync is best-effort and should be treated as a convenience override, not the primary source of truth for container restarts.

Broker internal API token should also be set in env for containerized setups:

• BROKER_INTERNAL_API_TOKEN=...
• Optional: BROKER_CORS_ALLOWED_ORIGINS=https://your-nextcloud-domain