# 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

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

### Provision upsert response

```json
{
  "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.