# 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`