Qortal-Nextcloud-Integration/docs/master-goals.md

# Master Goals And Delivery Plan

## North Star

Deliver a production-safe Qortal integration layer for Nextcloud that:

1. lets admins onboard existing Nextcloud users into Qortal,
2. enables Qortal-based sign-in via OIDC,
3. gives users guided linking/onboarding prompts (in-app + email),
4. provides a controlled path to use Q-Apps from inside Nextcloud.

## Goal Breakdown

## Goal 1: Admin-driven Qortal account enablement

Primary outcome:

- Admin can select users/groups and trigger Qortal onboarding.

Required capabilities:

- User selection UI in `qortal_integration`.
- Trigger actions:
  - `create new Qortal account`
  - `link existing Qortal account`
- Store linkage state:
  - `not_started`
  - `invited`
  - `linked`
  - `blocked`

Acceptance criteria:

- Admin can trigger onboarding for one user and for bulk users by group.
- System records invitation timestamp and status per user.
- Re-triggering onboarding is idempotent and auditable.

## Goal 2: Qortal-based authentication (OIDC)

Primary outcome:

- User can sign into Nextcloud using Qortal ownership proof.

Required capabilities:

- Broker OIDC endpoints implemented:
  - `/.well-known/openid-configuration`
  - `/authorize`
  - `/token`
  - `/userinfo`
  - `/jwks`
- Signed nonce challenge flow against External Auth API.
- Stable identity mapping (`sub` -> Nextcloud user ID).
- Policy modes:
  - auto-provision
  - link-only
  - strict pre-provision

Acceptance criteria:

- Browser login completes end-to-end with Nextcloud `user_oidc`.
- Existing user linking works without duplicate account creation.
- Failed ownership proof returns deterministic OIDC errors.

## Goal 3: User prompting and guided onboarding

Primary outcome:

- Users receive clear prompts to create or link Qortal identity when enabled by admin.

Required capabilities:

- In-app prompt:
  - banner/modal in Nextcloud session for eligible users.
- Email notification:
  - secure onboarding link with TTL and single-use token.
- User flow page:
  - choose `create` vs `link existing`.
  - show progress and error states.

Acceptance criteria:

- Admin can choose prompt channels:
  - in-app only
  - email only
  - both
- Prompt dismiss/snooze behavior is stored and respected.
- All prompt/link actions are logged for audit.

## Goal 4: Q-Apps access from Nextcloud

Primary outcome:

- Users can launch approved Q-Apps via Nextcloud without breaking trust boundaries.

Required capabilities:

- App catalog in Nextcloud admin:
  - approved Q-Apps
  - per-group access rules
- Launch strategy:
  - Phase 1: embedded gateway proxy (same-origin) with read-only Q-Apps.
  - Phase 2: optional signed context handoff for interactive features.
- Session/context handoff:
  - short-lived signed launch token from broker.

Acceptance criteria:

- Admin can allow/deny Q-Apps by group.
- User can open allowed Q-App from Nextcloud and receive identity context.
- Access attempts are auditable.

## Architecture Boundaries

## Nextcloud app (`qortal_integration`)

Responsibilities:

- Admin UI and policy management.
- User onboarding prompts and routing.
- Audit/event visibility.

Non-responsibilities:

- Wallet secret storage.
- Transaction signing.

## Broker service (`qortal-oidc-broker`)

Responsibilities:

- OIDC provider logic.
- Nextcloud provisioning bridge.
- External Auth integration.
- Signed launch tokens for Q-App handoff.

## Qortal External Auth API

Responsibilities:

- Wallet lifecycle.
- Signature/approval operations.
- Qortal request execution.

#### Potentially also a direct Qortal API?

- This may be necessary for RENDER calls and creation of certain tx types.
- Auth API only handles authenticated requests, doesn’t handle viewing/rendering etc.

## Proposed Data Model (Broker + App)

Core entities:

- `identity_mapping`
  - `nextcloud_user_id`
  - `qortal_address`
  - `wallet_id` (optional)
  - `status`
  - `linked_at`
- `onboarding_campaign`
  - `id`
  - `created_by_admin`
  - `target_scope` (users/groups)
  - `channels` (in_app/email)
  - `created_at`
- `onboarding_event`
  - `campaign_id`
  - `nextcloud_user_id`
  - `event_type`
  - `metadata`
  - `created_at`
- `qapp_policy`
  - `qapp_id`
  - `enabled`
  - `allowed_groups`
  - `updated_at`

## Delivery Phases

## Phase A: Foundation hardening

Scope:

- Move in-memory mapping to Postgres.
- Complete OIDC endpoint implementation.
- Add audit logging baseline.

Exit criteria:

- Deterministic identity mapping and reliable OIDC login.

## Phase B: Admin onboarding operations

Scope:

- Bulk user/group onboarding actions.
- Status dashboard and retry controls.

Exit criteria:

- Admin can run and monitor onboarding campaigns.

## Phase C: User prompts and self-service linking

Scope:

- In-app prompts.
- Email onboarding links.
- User self-service create/link page.

Exit criteria:

- End users can complete onboarding with minimal admin intervention.

## Phase D: Q-App launch platform

Scope:

- Approved Q-App catalog.
- Signed launch tokens.
- Group-based authorization.

Exit criteria:

- At least one Q-App launched from Nextcloud with secure context handoff.

## Security Rules

- Never store plaintext wallet secrets in Nextcloud or broker DB.
- Use short-lived, single-use tokens for onboarding and app launch links.
- Keep all sensitive operations server-side; clients only receive scoped tokens.
- Sign all identity and launch assertions; include `aud`, `exp`, `nonce`.
- Log security-relevant events with immutable timestamps.

## Immediate Next Build Order

1. Add admin campaign model + invite trigger API.
2. Add in-app prompt + onboarding link UX.
3. Add first approved Q-App launch flow (link-out mode).