feat(nextcloud): trigger endpoint for bulk migrations (#4728)

## Summary

Adds `POST /remote/nextcloud/migration` so the Settings UI can start a
Nextcloud-to-Cozy bulk migration end-to-end. The endpoint probes the
supplied credentials, upserts an `io.cozy.accounts` document with the
resolved WebDAV user ID, creates an `io.cozy.nextcloud.migrations`
tracking document in `pending` state, and publishes a
`nextcloud.migration.requested` command to the `migration` RabbitMQ
exchange. A separate service consumes the command and drives the
existing `/remote/nextcloud/:account/*` routes, writing progress back to
the tracking document so the UI can render a real-time progress bar.

Only one migration per instance can be in flight at a time; failed
migrations do not block retries.

## API

`POST /remote/nextcloud/migration` (requires `POST
io.cozy.nextcloud.migrations`)

```json
{
  "nextcloud_url": "https://nextcloud.example.com",
  "nextcloud_login": "alice",
  "nextcloud_app_password": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
  "source_path": "/",
  "target_dir": "/Nextcloud"
}
```

`source_path` and `target_dir` are optional. `source_path` defaults to
`/`. `target_dir` defaults to `/Nextcloud` and must be a clean absolute
path (validated with `path.Clean`, so `..`, double slashes, and relative
segments are rejected). `nextcloud_app_password` should be a Nextcloud
app password, not the account password.

### Error responses

| Code | When |
| ---- | ---- |
| 400 Bad Request | Required fields missing or `target_dir` is not a
clean absolute path |
| 401 Unauthorized | The Nextcloud server rejected the supplied
credentials |
| 409 Conflict | A `pending` or `running` migration already exists for
this instance |
| 500 Internal Server Error | Account upsert or tracking document
creation failed |
| 502 Bad Gateway | The Nextcloud instance is unreachable |
| 503 Service Unavailable | RabbitMQ publish failed; the tracking
document is marked `failed` before returning |

## Companion route: recursive size

`GET /remote/nextcloud/:account/size/*path` returns the recursive byte
total of a Nextcloud folder via a single PROPFIND on `oc:size`. The
migration consumer uses it as a pre-flight quota check so it knows the
true source size before starting; the previous shallow-sum estimate
could be off by several orders of magnitude on deep trees.

## RabbitMQ contract

Exchange `migration`, routing key `nextcloud.migration.requested`. The
consumer is responsible for declaring its queue and binding.

```json
{
  "migrationId": "d4e5f6a7b8c94d0ea1b2c3d4e5f6a7b8",
  "workplaceFqdn": "alice.cozy.example.com",
  "accountId": "a1b2c3d4e5f6",
  "sourcePath": "/",
  "timestamp": 1712563200
}
```

Credentials are never in the payload; they live in the
`io.cozy.accounts` document referenced by `accountId`. `target_dir` is
read by the consumer from the tracking document so legacy messages and
new ones both flow through the same path. `MessageID` is set to the
migration ID for cross-system tracing.

## Credentials probe

The OCS probe itself is not new. It already existed as a lazy fallback
behind `(nc *NextCloud).fetchUserID()`, called from `fillUserID` only
when an existing account document was missing its cached
`webdav_user_id`. In practice that path was almost never exercised, so a
latent bug sat there undetected: the probe targeted `apps/user_status`,
and any non-200 (including a 404 from a managed Nextcloud host that
strips the optional `user_status` app) was turned into
`webdav.ErrInvalidAuth`.

What this PR adds is the synchronous, user-facing path: the migration
trigger endpoint calls `FetchUserIDWithCredentials` before persisting
anything, so the probe is now on the critical path of every trigger.
That exposure turned the latent classification bug into a user-visible
401 for anyone pointing the feature at a managed Nextcloud like
`thegood.cloud`.

A follow-up commit on this branch fixes it by switching the probe to OCS
Core (`/ocs/v2.php/cloud/user`, which cannot be disabled by an admin)
and narrowing the auth-failure classification to 401/403 only, so other
non-2xx statuses bubble up with their real cause. Both code paths (the
old lazy fallback and the new synchronous call) benefit from the fix.

Validated end-to-end against a real Nextcloud instance: the probe, the
encrypted-at-rest account persistence, the tracking document, the
`/size/*path` pre-flight, the RabbitMQ publish with no credentials in
the payload, and the consumer-driven transfer all behave as documented.

Author: rezk2ll

docs/nextcloud.md

@@ -579,3 +579,138 @@ Authorization: Bearer eyJhbG...
 ```http
 HTTP/1.1 204 No Content
 ```
+
+## GET /remote/nextcloud/:account/size/*path
+
+This route returns the recursive size in bytes of a folder (or a single
+file) on the NextCloud account. It is backed by a single Depth:0 PROPFIND
+asking for the `oc:size` property that NextCloud maintains in its metadata
+table, so it runs in constant time regardless of how many files are in the
+tree. Pass the account root by using an empty `*path` (just `/size/`).
+
+The `:account` parameter is the identifier of the NextCloud `io.cozy.account`.
+
+**Note:** a permission on `GET io.cozy.files` is required to use this route.
+
+### Request (sub-folder)
+
+```http
+GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/size/Photos HTTP/1.1
+Host: cozy.example.net
+Authorization: Bearer eyJhbG...
+```
+
+### Response
+
+```http
+HTTP/1.1 200 OK
+Content-Type: application/json
+```
+
+```json
+{
+  "size": 5656463
+}
+```
+
+### Request (account root)
+
+```http
+GET /remote/nextcloud/4ab2155707bb6613a8b9463daf00381b/size/ HTTP/1.1
+Host: cozy.example.net
+Authorization: Bearer eyJhbG...
+```
+
+#### Status codes
+
+- 200 OK, with the recursive byte total of the target path
+- 401 Unauthorized, when the NextCloud credentials are rejected
+- 404 Not Found, when the account or the target path does not exist
+
+## POST /remote/nextcloud/migration
+
+This route triggers a one-shot bulk migration of a user's Nextcloud files into
+their Cozy. The Stack validates the credentials, persists an
+`io.cozy.accounts` document, creates an `io.cozy.nextcloud.migrations`
+tracking document in `pending` state, and publishes a
+`nextcloud.migration.requested` command to the `migration` RabbitMQ exchange.
+The actual transfer is performed by an external migration service that
+consumes the command and drives the existing `/remote/nextcloud/:account/*`
+routes, updating the tracking document as it progresses.
+
+Before persisting anything, the Stack probes the supplied credentials against
+the Nextcloud instance via the OCS `user_status` endpoint, so wrong passwords
+and unreachable hosts surface synchronously instead of being deferred to the
+migration service. The probe also resolves the WebDAV user ID, which is
+cached on the account document so the migration service does not need to
+re-fetch it.
+
+When an existing `io.cozy.accounts` document for the same `account_type:
+"nextcloud"` + `auth.url` + `auth.login` triplet is found, it is reused with
+its stored password and `webdav_user_id` refreshed from the request. Only one
+migration can be in flight per instance at a time: if a `pending` or `running`
+tracking document already exists, the Stack returns `409 Conflict`. Failed
+migrations do not block new attempts.
+
+**Note:** a permission on `POST io.cozy.nextcloud.migrations` is required to
+use this route.
+
+### Request
+
+```http
+POST /remote/nextcloud/migration HTTP/1.1
+Host: cozy.example.net
+Authorization: Bearer eyJhbG...
+Content-Type: application/json
+```
+
+```json
+{
+  "nextcloud_url": "https://nextcloud.example.com",
+  "nextcloud_login": "alice",
+  "nextcloud_app_password": "xxxxx-xxxxx-xxxxx-xxxxx-xxxxx",
+  "source_path": "/"
+}
+```
+
+`source_path` is optional and defaults to `/`. The `nextcloud_app_password`
+should be a Nextcloud app password, not the user's main account password.
+
+### Response
+
+```http
+HTTP/1.1 201 Created
+Content-Type: application/vnd.api+json
+```
+
+```json
+{
+  "data": {
+    "id": "d4e5f6a7b8c94d0ea1b2c3d4e5f6a7b8",
+    "type": "io.cozy.nextcloud.migrations",
+    "attributes": {
+      "status": "pending",
+      "target_dir": "/Nextcloud",
+      "progress": {
+        "files_imported": 0,
+        "files_total": 0,
+        "bytes_imported": 0,
+        "bytes_total": 0
+      },
+      "errors": [],
+      "skipped": [],
+      "started_at": null,
+      "finished_at": null
+    }
+  }
+}
+```
+
+#### Status codes
+
+- 201 Created, when the migration has been queued and the tracking document is returned
+- 401 Unauthorized, when the Nextcloud credentials are rejected by the remote host
+- 409 Conflict, when a `pending` or `running` migration already exists
+- 500 Internal Server Error, when the conflict check, account upsert, or tracking document creation fails
+- 502 Bad Gateway, when the Nextcloud instance is unreachable
+- 503 Service Unavailable, when the migration command cannot be published to RabbitMQ. The tracking document is marked `failed` before returning

docs/rabbitmq.md

@@ -134,6 +134,46 @@ rabbitmq:
 - If queue-level `dlx_name`/`dlq_name` are not specified, exchange-level defaults are used.
 - Messages that exceed the `delivery_limit` or are rejected will be sent to the DLX and routed to the DLQ.
 
+### Publishers
+
+The Stack also publishes messages to RabbitMQ. Publishers do not declare any
+queue or exchange on the Stack side: the exchange must already exist on the
+broker, and a queue must be bound by the consuming service. Publishes use the
+AMQP `mandatory` flag, so a publish to an exchange with no matching binding
+fails with `PublishReturnedError` and the caller is expected to surface the
+failure to the user.
+
+#### `auth` exchange
+
+Routing key: `user.deletion.requested`. Published from
+`POST /settings/instance/deletion/force` when a user requests permanent
+deletion of their account. The payload is the `UserDeletionRequestedMessage`
+struct in `pkg/rabbitmq/contracts.go`.
+
+#### `migration` exchange
+
+Routing key: `nextcloud.migration.requested`. Published from
+`POST /remote/nextcloud/migration` when a user starts a Nextcloud-to-Cozy
+bulk migration. The payload is the `NextcloudMigrationRequestedMessage`
+struct in `pkg/rabbitmq/contracts.go`:
+
+```json
+{
+  "migrationId": "d4e5f6a7b8c94d0ea1b2c3d4e5f6a7b8",
+  "workplaceFqdn": "alice.cozy.example.com",
+  "accountId": "a1b2c3d4e5f6",
+  "sourcePath": "/",
+  "timestamp": 1712563200
+}
+```
+
+Credentials are never in the payload: they live in the `io.cozy.accounts`
+document referenced by `accountId`. The Stack populates `MessageID` with the
+migration ID for cross-system tracing. The consuming service is responsible
+for declaring its queue, binding it to this exchange, and processing the
+messages; if no queue is bound when the Stack publishes, the user receives
+`503` and the tracking document is marked `failed`.
+
 ### Handlers
 
 Handlers implement a simple interface: