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

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