Qortal-Nextcloud-Integration/docs/nextcloud-admin-app.md

Nextcloud Admin App (qortal_integration)

What it does now

• Adds a new Qortal Integration admin section in Nextcloud settings.
• Stores integration settings in Nextcloud app config:
  • broker base URL
  • broker internal API token (must match broker env BROKER_INTERNAL_API_TOKEN)
  • external auth base URL + app credentials
  • external auth Qortal node URL
  • external auth node API key + mode/paths (UI enforces paths, default paths: /)
  • external auth docs URL
  • OIDC issuer / client settings
  • Nextcloud public URL (for trusted domain setup)
  • Qortal node URL + API key
  • Qortal gateway URL
  • feature toggles for QDN backups and Q-Mail
• Lets admins run a live broker connectivity check from Nextcloud UI.
• Adds setup assistant blocks for link-mode prerequisites.
• Provides setup actions to generate or run occ commands for OIDC provider setup.
• Shows setup notices when critical settings are missing.
• Includes quick-start references for Docker and VM setup scripts.
• Can register a new External Auth app ID/secret from the admin UI (with warning).
• Exposes wallet operations from admin UI:
  • list wallets visible to broker External Auth app credentials
  • create wallet (password + optional kdf threads)
  • create wallet and link to an existing Nextcloud user
• Exposes mapping operations from admin UI:
  • list mappings
  • link qortalAddress -> nextcloudUserId (optional wallet id)
  • unlink mapping by Qortal address
• Adds auto-provision guard tools:
  • allowlist Qortal addresses for auto-provision
  • generate/revoke invite tokens for gated provisioning
• Provides an invite message template for notifying existing users.
• Sends onboarding notifications to existing users (email and/or in-app) via the "Onboard Cloud Users" section.
• Provides "Invite Qortal Users to Nextcloud" messaging for auto-provisioned new accounts.
• Supports email template customization (subject + body with placeholders).
• Adds admin user search to populate notification targets.
• Supports group search and queued notification delivery via background jobs.
• Displays broker auto-provision policy with a generated env snippet for changes.
• Provides External Auth env snippet generation (broker + external auth settings).
• Saving admin settings now attempts live broker/runtime sync for External Auth base URL, app credentials, and node settings (when supported by External Auth).
  • For bundled/containerized external-auth, treat .env.devprod values as source of truth for QORTAL_AUTH_NODE_API_KEY* and recreate external_auth after changes.

Email placeholders:

• {link}: Qortal Integration personal settings link
• {invite}: invite token (blank unless enabled)
• {user}: Nextcloud user ID
• {displayName}: user display name
• Adds a personal user settings panel for self-service import + linking:
  • import wallet by seed phrase + password
  • import wallet by backup JSON + password
  • create new wallet and link
  • backup wallet JSON (download or save to Files)
  • unlink user-owned mapping
  • list linked accounts for current user
• Adds Q-Apps access configuration:
  • enable/disable Q-Apps menu
  • configure approved qortal:// app addresses
  • enable optional full Qortal browser link
  • per-app icon mode (auto thumbnail or custom URL)
  • menu entries for each approved Q-App in the top apps bar
• Provides a Q-Apps hub page (/apps/qortal_integration/qapps) for users.
• Provides a Qortal Account dashboard (/apps/qortal_integration/account) for auth validation.
• Gateway proxy support:
  • embedded rendering uses /apps/qortal_integration/gateway/...
  • optional "Allow insecure gateway TLS" toggle for self‑signed gateways
  • theme parameter (?theme=dark|light) is passed to Q‑Apps

Enable

make occ cmd="app:enable qortal_integration"

Use in UI

1. Login to Nextcloud as admin.
2. Open Administration settings.
3. Open Qortal Integration section.
4. Set broker URL and save.
5. Click Test Broker Connection.

Beta deployment note:

• Recommended topology is local-only (Nextcloud + broker + external-auth on the same trusted host/network).
• Seed and backup imports should not be enabled across untrusted remote links.
• Broker internal APIs are protected by shared token; ensure Nextcloud and broker token values match.

Current API routes (admin-only checks)

• GET /apps/qortal_integration/api/settings
• POST /apps/qortal_integration/api/settings
• GET /apps/qortal_integration/api/status
• GET /apps/qortal_integration/api/setup
• POST /apps/qortal_integration/api/setup/plan
• POST /apps/qortal_integration/api/setup/occ
• GET /apps/qortal_integration/api/wallets
• POST /apps/qortal_integration/api/wallets
• GET /apps/qortal_integration/api/mappings
• POST /apps/qortal_integration/api/mappings/link
• POST /apps/qortal_integration/api/mappings/unlink
• GET /apps/qortal_integration/api/oidc/allowlist
• POST /apps/qortal_integration/api/oidc/allowlist
• POST /apps/qortal_integration/api/oidc/allowlist/remove
• GET /apps/qortal_integration/api/oidc/invites
• POST /apps/qortal_integration/api/oidc/invites
• POST /apps/qortal_integration/api/oidc/invites/revoke
• POST /apps/qortal_integration/api/notify
• GET /apps/qortal_integration/api/users/search
• GET /apps/qortal_integration/api/groups/search
• GET /apps/qortal_integration/api/user/mappings
• POST /apps/qortal_integration/api/user/wallets
• POST /apps/qortal_integration/api/user/wallets/backup
• POST /apps/qortal_integration/api/user/import-seed-link
• POST /apps/qortal_integration/api/user/import-backup-link
• POST /apps/qortal_integration/api/user/mappings/unlink

UI routes

• GET /apps/qortal_integration/qapps
• GET /apps/qortal_integration/account

Next implementation targets

• mapping unlink/sync actions
• broker-driven wallet import/backup flows in UI
• non-admin self-service linking page (user settings)
• QDN backup and Q-Mail workflows
• Q-App launch tokens + broker handoff