167 lines
7.7 KiB
Markdown
167 lines
7.7 KiB
Markdown
# 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
|
||
- Adds NuQloud identity provider client management:
|
||
- create and edit OIDC clients
|
||
- apply setup templates for common private apps
|
||
- disable/re-enable clients
|
||
- rotate one-time client secrets
|
||
- view identity-provider audit events
|
||
- Provides an invite message template for notifying existing users.
|
||
- Provides recovery operations for opted-in users:
|
||
- check managed recovery status by user ID,
|
||
- issue one-time recovery code,
|
||
- start emergency temporary-login reset window.
|
||
- 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
|
||
- `{cloudName}`: themed cloud name, billing company name, public host, or NuQloud fallback
|
||
- `{instanceName}`: same default value as `{cloudName}`
|
||
- 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, custom URL, or avatar from another registered name)
|
||
- app ordering controls for dashboard/qapps/header surfaces
|
||
- 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`) with:
|
||
- account status and wallet/send flows
|
||
- purchases catalog + checkout integration
|
||
- CHD announcements
|
||
- activity notifications configuration
|
||
- unconfirmed transaction visibility
|
||
- 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
|
||
- Bridge companion apps:
|
||
- Files bridge (`qortal_files_bridge`) for Files-side QDN publish/delete flows
|
||
- Talk bridge (`qortal_talk_bridge`) for Talk/Qortal mapping + relay controls
|
||
- NuQloud Scrum (`nuqloud_scrum`) for Talk-first workspace/task automation
|
||
|
||
## Enable
|
||
|
||
```bash
|
||
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`
|
||
- `GET /apps/qortal_integration/api/oidc/clients`
|
||
- `POST /apps/qortal_integration/api/oidc/clients`
|
||
- `POST /apps/qortal_integration/api/oidc/clients/{clientId}`
|
||
- `POST /apps/qortal_integration/api/oidc/clients/{clientId}/enabled`
|
||
- `POST /apps/qortal_integration/api/oidc/clients/{clientId}/rotate-secret`
|
||
- `GET /apps/qortal_integration/api/oidc/audit-events`
|
||
- `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`
|
||
- `GET /apps/qortal_integration/api/user/recovery/status`
|
||
- `POST /apps/qortal_integration/api/user/recovery/enroll`
|
||
- `POST /apps/qortal_integration/api/user/recovery/disable`
|
||
- `POST /apps/qortal_integration/api/user/recovery/reveal`
|
||
- `POST /apps/qortal_integration/api/user/recovery/emergency/complete`
|
||
- `POST /apps/qortal_integration/api/admin/recovery/code`
|
||
- `POST /apps/qortal_integration/api/admin/recovery/emergency`
|
||
- `POST /apps/qortal_integration/api/user/mappings/unlink`
|
||
|
||
## UI routes
|
||
|
||
- `GET /apps/qortal_integration/qapps`
|
||
- `GET /apps/qortal_integration/account`
|
||
|
||
## Roadmap References
|
||
|
||
- `docs/nextcloud-app-roadmap.md`
|
||
- `docs/plugin-roadmap.md`
|
||
- `docs/managed-recovery-auth.md`
|