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).