Qortal-Nextcloud-Integration/docs/concept.md

Concept Plan

Objectives

• Provision Nextcloud users from Qortal identities.
• Support both existing and newly-created Nextcloud users.
• Add Qortal-backed login through OIDC without deep Nextcloud core coupling.

Program goals

1. Admins can enable Qortal onboarding for existing Nextcloud users.
2. Users can authenticate to Nextcloud with Qortal ownership proof.
3. Users receive guided prompts (in-app/email) to create or link Qortal identity.
4. Approved Q-Apps can be launched from Nextcloud with policy controls.

See docs/master-goals.md for the full delivery plan and architecture boundaries.

Architecture

Components

1. Qortal External Auth API (existing)
   • Source of truth for Qortal identity ownership proofs.
2. Qortal OIDC Broker (this repo, TypeScript)
   • OIDC provider endpoints for Nextcloud user_oidc.
   • Calls Qortal External Auth for challenge verification.
   • Uses Nextcloud Provisioning API for account create/update/link.
3. Nextcloud + user_oidc
   • Handles login UI/session.
   • Uses broker as external OpenID Connect provider.
4. Mapping store
   • qortal_address -> nextcloud_userid.
   • Persisted in broker PostgreSQL for deterministic identity mapping.
5. Q-Apps gateway proxy (Nextcloud app)
   • Embeds Q-Apps through a gateway URL.
   • Rewrites gateway assets and API calls for same-origin rendering.

Phase plan

Phase 1: Provisioning Bridge (now)

• Implement service account access to Nextcloud OCS API.
• Add endpoints:
  • POST /api/provision/upsert
  • POST /api/provision/upsert-from-wallet
  • POST /api/provision/link
  • GET /api/provision/mapping/:qortalAddress
  • GET /api/provision/mappings
• Create users when absent; map identities and return linkage metadata.

Definition of done:

• Calling broker endpoint creates a Nextcloud user and stores mapping.
• Repeated calls for same Qortal address are idempotent.

Phase 2: OIDC Login

• Implement broker endpoints:
  • /.well-known/openid-configuration
  • /authorize
  • /token
  • /userinfo
  • /jwks
• In /authorize, validate Qortal ownership by signed nonce challenge.
• Issue OIDC code/token set for Nextcloud.

Definition of done:

• Nextcloud user_oidc can redirect to broker and complete login.
• sub claim maps consistently to linked Nextcloud user.

Phase 3: Existing + New User Policies

• Configure user_oidc auto-provision mode for desired behavior.
• Support strict/pre-provision modes where required.
• Add admin endpoints/UI for manual linking and conflict handling.

Definition of done:

• Existing users can link/login without duplicate account creation.
• New users can be auto-provisioned based on policy.

Data contracts (starter)

Provision upsert request

{
  "qortalAddress": "Q...",
  "nextcloudUserId": "optional-existing-user",
  "displayName": "Optional Name",
  "email": "optional@example.com"
}

Provision upsert response

{
  "linked": true,
  "qortalAddress": "Q...",
  "nextcloudUserId": "nc_user_123",
  "created": true
}

Notes:

• Provisioning responses never return plaintext passwords.
• If user auto-creation is needed, password generation is internal-only.

Risks and mitigations

• OIDC complexity
  • Start with minimal standards-compliant broker and add claims incrementally.
• Account duplication
  • Enforce deterministic mapping and explicit conflict responses.
• Secret handling
  • Keep service credentials in env vars; rotate in deployment pipeline.
• Desktop/WebDAV compatibility
  • Document app-password strategy early for non-browser clients.