# Qortal External Auth Integration

This repo now includes a broker client for the Qortal External Auth API.

## API docs

- Local docs URL: `http://localhost:3191/docs/static/index.html`
- OpenAPI JSON: `http://localhost:3191/docs/json`

## Broker environment

Set these in `.env` (or `.env.postgres` / `.env.devprod`):

```bash
BROKER_INTERNAL_API_TOKEN=<random-secret>
BROKER_CORS_ALLOWED_ORIGINS=https://cloud.example.com
QORTAL_EXTERNAL_AUTH_BASE_URL=http://gateway.docker.internal:3191
QORTAL_EXTERNAL_AUTH_APP_ID=<your-app-id>
QORTAL_EXTERNAL_AUTH_APP_SECRET=<your-app-secret>
```

Notes:

- `gateway.docker.internal` works from Docker containers to host services in this setup.
- If you run the bundled External Auth container (profile `external-auth`), set:
  - `QORTAL_EXTERNAL_AUTH_BASE_URL=http://external_auth:3191`
- You can also register the External Auth app from the Nextcloud admin UI
  (Qortal Integration → External Auth Configuration). After updating env files,
  restart the broker container so it picks up the new credentials.
- Broker internal APIs (`/api/qortal/*`, `/api/provision/*`, `/api/oidc/*`) require
  `X-Broker-Internal-Token: <BROKER_INTERNAL_API_TOKEN>` when called directly.

## Register app credentials

```bash
curl -sS -X POST http://localhost:3191/apps/register \
  -H "Content-Type: application/json" \
  -d '{"name":"qortal-nextcloud-integration"}'
```

Response shape:

```json
{
  "appId": "...",
  "appSecret": "..."
}
```

## Broker endpoints that use External Auth

- `GET /api/qortal/health`
  - Checks connectivity to External Auth `/health`.
- `GET /api/qortal/wallets`
  - Uses app credentials -> session token -> `/wallets`.
- `POST /api/qortal/wallets`
  - Uses app credentials -> session token -> `/wallet/create`.
  - Request body:
    - `password` (required)
    - `kdfThreads` (optional)
- `POST /api/qortal/wallets/backup`
  - Uses app credentials -> session token -> `/wallet/backup`.
  - Request body:
    - `walletId` (required)
    - `password` (required)
  - Returns backup JSON for download or storage in Nextcloud Files.
- `POST /api/provision/upsert-from-wallet`
  - Body requires `walletId`.
  - Broker resolves wallet metadata via `/wallet/{id}`, then provisions/links by `address0`.
- `POST /api/provision/import-seed-link`
  - Body requires:
    - `seedPhrase`
    - `password`
    - `nextcloudUserId`
  - Imports wallet through External Auth `/wallet/import-seed`, then links imported `address0` to the requested Nextcloud user.
- `POST /api/provision/import-backup-link`
  - Body requires:
    - `backup` (or `backupJson`)
    - `password`
    - `nextcloudUserId`
  - Imports wallet through External Auth `/wallet/import-backup`, then links imported `address0` to the requested Nextcloud user.
- `GET /api/provision/mappings/by-nextcloud/:nextcloudUserId`
  - Lists mapping records for a specific Nextcloud user.
- `POST /api/provision/unlink`
  - Removes mapping by `qortalAddress` (optionally constrained by `nextcloudUserId`).
- `GET /authorize` + `POST /authorize`
  - OIDC login flow now requires wallet import to prove ownership:
    - seed phrase + password, or
    - backup JSON + password
  - Optional `qortal_address` must match the imported wallet address.

Example wallet-based provisioning call:

```bash
curl -sS http://localhost:3000/api/provision/upsert-from-wallet \
  -H "X-Broker-Internal-Token: ${BROKER_INTERNAL_API_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"walletId":"<WALLET_ID>","displayName":"Qortal User"}'
```