Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(push-v2): Document silent delete-multiple push notification #2089

Merged
merged 2 commits into from
Oct 29, 2024
Merged

docs(push-v2): Document silent delete-multiple push notification #2089

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
127ce4d
docs(push-v2): Document silent delete-multiple push notification
provokateurin Oct 28, 2024
55eaba3
docs: Reformat tables
nickvergessen Oct 29, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 64 additions & 48 deletions docs/push-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@

> Why is push-notifications.nextcloud.com necessary?

The Nextcloud mobile apps from the Google Playstore and Apple App Store are signed with Nextcloud developer keys or certificates.
The Nextcloud mobile apps from the Google Play and Apple App Store are signed with Nextcloud developer keys or certificates.
Push notifications sent to those devices need to be signed with a generated push key or certificate from the same developer account.
The keys and certificates can not be shipped with the Nextcloud server as otherwise everyone would have our developer key and could manipulate releases or push to any random Nextcloud device.
The Firebase Cloud Messaging (Google) and Apple Push Notification Service are not made for something like a federated project like Nextcloud and still assume there is a single entity behind them like with all the other services.
Expand Down Expand Up @@ -110,41 +110,41 @@ In order to find out if notifications support push on the server you can run a r

The server replies with the following status codes:

| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | No further action by the device required |
| 201 | Push token was created/updated and **needs to be sent to the `Proxy`** |
| Status code | Meaning |
|-------------|----------------------------------------------------------------------------------------------------------------------------------------------------|
| 200 | No further action by the device required |
| 201 | Push token was created/updated and **needs to be sent to the `Proxy`** |
| 400 | Invalid device public key; device does not use a token to authenticate; the push token hash is invalid formatted; the proxy server URL is invalid; |
| 401 | Device is not logged in |
| 401 | Device is not logged in |



#### Body in case of success

In case of `200` and `201` the reply has more information in the body:

| Key | Type | |
| ---------------- | ------------ | ---------------------------------------- |
| Key | Type | |
|------------------|--------------|--------------------------------------------------------|
| publicKey | string (512) | rsa2048 public key of the user account on the instance |
| deviceIdentifier | string (128) | unique identifier encrypted with the users private key |
| signature | string (512) | base64 encoded signature of the deviceIdentifier |
| signature | string (512) | base64 encoded signature of the deviceIdentifier |



#### Body in case of an error

In case of `400` the following `message` can appear in the body:

| Error | Description |
| ------------------------ | ---------------------------------------- |
| `INVALID_PUSHTOKEN_HASH` | The hash of the push token was not a valid `sha512` hash. |
| Error | Description |
|--------------------------|--------------------------------------------------------------------------------------------------------------|
| `INVALID_PUSHTOKEN_HASH` | The hash of the push token was not a valid `sha512` hash. |
| `INVALID_SESSION_TOKEN` | The authentication token of the request could not be identified. Check whether a password was used to login. |
| `INVALID_DEVICE_KEY` | The device key does not match the one registered to the provided session token. |
| `INVALID_PROXY_SERVER` | The proxy server was not a valid https URL. |
| `INVALID_DEVICE_KEY` | The device key does not match the one registered to the provided session token. |
| `INVALID_PROXY_SERVER` | The proxy server was not a valid https URL. |



## Unsubcribing at the Nextcloud server
## Unsubscribing at the Nextcloud server

When an account is removed from a device, the device should unregister on the server. Otherwise the server sends unnecessary push notifications and might be blocked because of spam.

Expand All @@ -162,21 +162,21 @@ DELETE /ocs/v2.php/apps/notifications/api/v2/push

The server replies with the following status codes:

| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was not registered on the server |
| Status code | Meaning |
|-------------|---------------------------------------------------------------------|
| 200 | Push token was not registered on the server |
| 202 | Push token was deleted and **needs to be deleted from the `Proxy`** |
| 400 | Device does not use a token to authenticate |
| 401 | Device is not logged in |
| 400 | Device does not use a token to authenticate |
| 401 | Device is not logged in |



#### Body in case of an error

In case of `400` the following `message` can appear in the body:

| Error | Description |
| ----------------------- | ---------------------------------------- |
| Error | Description |
|-------------------------|------------------------------------------------------------------|
| `INVALID_SESSION_TOKEN` | The authentication token of the request could not be identified. |


Expand All @@ -202,11 +202,11 @@ POST /devices

The server replies with the following status codes:

| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was written to the database |
| 400 | Push token, public key or device identifier is malformed, the signature does not match |
| 403 | Device is not allowed to write the push token of the device identifier |
| Status code | Meaning |
|-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 200 | Push token was written to the database |
| 400 | Push token, public key or device identifier is malformed, the signature does not match |
| 403 | Device is not allowed to write the push token of the device identifier |
| 409 | In case of a conflict the device can retry with the additional field `cloudId` with the value `{{userid}}@{{serverurl}}` which allows the proxy to verify the public key and device identifier belongs to the given user on the instance |


Expand All @@ -231,10 +231,10 @@ DELETE /devices

The server replies with the following status codes:

| Status code | Meaning |
| ----------- | ---------------------------------------- |
| 200 | Push token was deleted from the database |
| 400 | Public key or device identifier is malformed |
| Status code | Meaning |
|-------------|----------------------------------------------------------------------------|
| 200 | Push token was deleted from the database |
| 400 | Public key or device identifier is malformed |
| 403 | Device identifier and device public key didn't match or could not be found |


Expand All @@ -259,9 +259,9 @@ The pushed notifications is defined by the [Firebase Cloud Messaging HTTP Protoc
}
```

| Attribute | Meaning |
| ----------- | ---------------------------------------- |
| `subject` | The subject is encrypted with the device´s *public key*. |
| Attribute | Meaning |
|-------------|----------------------------------------------------------------------------------------------|
| `subject` | The subject is encrypted with the device´s *public key*. |
| `signature` | The signature is a sha512 signature over the encrypted subject using the user´s private key. |

### Encrypted subject data
Expand All @@ -280,13 +280,13 @@ If you are missing any information necessary to parse the notification in a more
}
```

| Attribute | Meaning | Capability |
| ----------- | ---------------------------------------- |------------|
| `app` | The nextcloud app sending the notification | -|
| `subject` | The subject of the actual notification | -|
| `type` | Type of the object this notification is about | `object-data` |
| `id` | Identifier of the object this notification is about | `object-data` |
| `nid` | Numeric identifier of the notification in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |
| Attribute | Meaning | Capability |
|-----------|---------------------------------------------------------------------------------------------------------------|---------------|
| `app` | The nextcloud app sending the notification | - |
| `subject` | The subject of the actual notification | - |
| `type` | Type of the object this notification is about | `object-data` |
| `id` | Identifier of the object this notification is about | `object-data` |
| `nid` | Numeric identifier of the notification in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |


#### Silent delete notification (single)
Expand All @@ -300,12 +300,28 @@ These notifications should not be shown to the user. Instead you should delete p
}
```

| Attribute | Meaning | Capability |
| ----------- | ---------------------------------------- |------------|
| `nid` | Numeric identifier of the notification in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |
| `delete` | Delete all notifications related to `nid` | `delete` |
| Attribute | Meaning | Capability |
|-----------|---------------------------------------------------------------------------------------------------------------|---------------|
| `nid` | Numeric identifier of the notification in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |
| `delete` | Delete all notifications related to `nid` | `delete` |


#### Silent delete notifications (multiple)

These notifications should not be shown to the user. Instead you should delete pending system notifications for the respective ids

```json
{
"delete-multiple" : true,
"nids" : [1337]
}
```

| Attribute | Meaning | Capability |
|-------------------|-----------------------------------------------------------------------------------------------------------------|---------------|
| `nids` | Numeric identifiers of the notifications in order to get more information via the [OCS API](ocs-endpoint-v2.md) | `object-data` |
| `delete-multiple` | Delete all notifications related to `nids` | `delete` |

#### Silent delete notification (all)

These notifications should not be shown to the user. Instead you should delete all pending system notifications for this account
Expand All @@ -316,9 +332,9 @@ These notifications should not be shown to the user. Instead you should delete a
}
```

| Attribute | Meaning | Capability |
| ----------- | ---------------------------------------- |------------|
| `delete-all` | Delete all notifications related to this account | `delete` |
| Attribute | Meaning | Capability |
|--------------|--------------------------------------------------|------------|
| `delete-all` | Delete all notifications related to this account | `delete` |


### Verification
Expand Down