From 832b7e92f98d9bc3391cf6c6cc9d471df3a7a1cf Mon Sep 17 00:00:00 2001 From: fyears <1142836+fyears@users.noreply.github.com> Date: Fri, 11 Mar 2022 23:07:19 +0800 Subject: [PATCH] add doc for cors --- README.md | 14 +++--- docs/browser_env.md | 2 +- docs/browser_env_cors.md | 16 +------ docs/s3_cors_configure.md | 2 + docs/services_connectable_or_not.md | 70 +++++++++++++++-------------- 5 files changed, 50 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 2f252fb..0eeefcd 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,9 @@ Additionally, the plugin author may occasionally visit Obsidian official forum a ### S3 - Prepare your S3 (-compatible) service information: [endpoint, region](https://docs.aws.amazon.com/general/latest/gr/s3.html), [access key id, secret access key](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/getting-your-credentials.html), bucket name. The bucket should be empty and solely for syncing a vault. -- Configure (enable) [CORS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html) for requests from `app://obsidian.md` and `capacitor://localhost` and `http://localhost`. Full example is [here](./docs/s3_cors_configure.md). It's unfortunately required, because the plugin sends requests from a browser-like envirement. And those addresses are tested and found on desktop and ios and android. +- About CORS: + - If you are using Obsidian >= 0.13.25, you can skip this CORS part. + - If you are using Obsidian < 0.13.25, you need to configure (enable) [CORS](https://docs.aws.amazon.com/AmazonS3/latest/userguide/enabling-cors-examples.html) for requests from `app://obsidian.md` and `capacitor://localhost` and `http://localhost`. Full example is [here](./docs/s3_cors_configure.md). It's unfortunately required, because the plugin sends requests from a browser-like envirement. And those addresses are tested and found on desktop and ios and android. - Download and enable this plugin. - Enter your information to the settings of this plugin. - If you want to enable end-to-end encryption, also set a password in settings. If you do not specify a password, the files and folders are synced in plain, original content to the cloud. @@ -88,10 +90,12 @@ Additionally, the plugin author may occasionally visit Obsidian official forum a ### webdav - **webdav support is considered experimental.** -- Currently only supports BASIC authorization method. -- Currently webdav server has to be enabled CORS for requests from `app://obsidian.md` and `capacitor://localhost` and `http://localhost`, **AND** all webdav HTTP methods, **AND** all webdav headers. These are required, because Obsidian mobile works like a browser and mobile plugins are limited by CORS policies. - - Popular software NextCloud, OwnCloud, `rclone serve webdav` do **NOT** enable CORS by default. If you are using any of them, you should evaluate the risk, and find a way to enable CORS, before using this plugin. - - The plugin is tested successfully under python package [`wsgidav` (version 4.0)](https://github.com/mar10/wsgidav). See [this issue](https://github.com/mar10/wsgidav/issues/239) for some details. +- About CORS: + - If you are using Obsidian >= 0.13.25, you can skip this CORS part. + - If you are using Obsidian < 0.13.25: + - The webdav server has to be enabled CORS for requests from `app://obsidian.md` and `capacitor://localhost` and `http://localhost`, **AND** all webdav HTTP methods, **AND** all webdav headers. These are required, because Obsidian mobile works like a browser and mobile plugins are limited by CORS policies unless under a upgraded Obsidian version. + - Popular software NextCloud, OwnCloud, `rclone serve webdav` do **NOT** enable CORS by default. If you are using any of them, you should evaluate the risk, and find a way to enable CORS, before using this plugin, or use a upgraded Obsidian version. + - The plugin is tested successfully under python package [`wsgidav` (version 4.0)](https://github.com/mar10/wsgidav). See [this issue](https://github.com/mar10/wsgidav/issues/239) for some details. - Your data would be synced to a `${vaultName}` sub folder on your webdav server. - Password-based end-to-end encryption is also supported. But please be aware that **the vault name itself is not encrypted**. diff --git a/docs/browser_env.md b/docs/browser_env.md index f0c40eb..f7d2ccd 100644 --- a/docs/browser_env.md +++ b/docs/browser_env.md @@ -6,7 +6,7 @@ Technically, the plugin (or any plugin?) runs in the js environment provided by Then some limitations are applied: -1. [The CORS policy.](./browser_env_cors.md) +1. [The CORS issue (solved in the new Obsidian version).](./browser_env_cors.md) 2. [No Node.js environment.](./browser_env_no_nodejs.md) 3. If the cloud service uses OAuth flow, it needs to support PKCE. More details are [here](./browser_env_oauth2_pkce.md). 4. [No background running after Obsidian is closes.](./browser_env_no_background_after_closing.md) diff --git a/docs/browser_env_cors.md b/docs/browser_env_cors.md index 548ba4c..559ab7c 100644 --- a/docs/browser_env_cors.md +++ b/docs/browser_env_cors.md @@ -4,18 +4,6 @@ The plugin is developed for the browser environment. The "fake" browser behind t [MDN has a doc about CORS.](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) -To solve the issue, we have some options: +From Obsidian version >= insider 0.13.25, Obsidian [provides a new API `requiestUrl`](https://forum.obsidian.md/t/obsidian-release-v0-13-25-insider-build/32701), that allows the plugin to fully bypass the CORS issue. As of Mar 2022, the latest public-released Obsidian desktop has supported this API, but the Obsidian mobile still stays in insider. -1. The server side needs to return the header `Access-Control-Allow-Origin` allowing the origins `app://obsidian.md` and `capacitor://localhost` and `http://localhost`. Sometimes in the future, the header `Access-Control-Expose-Headers` with some values being set might be also needed. - - [Here is an example configuration for Amazon S3.](./s3_cors_configure.md) - - However, some cloud services do not allow configuring or exposing these headers. (Notably most public WebDAV services.) - - It's of course possible if the users build the services by themselves. - -2. Obsidian implements and exposes a new api helping developers to bypass the CORS policy. - - Currently (as of Feb 2022), an api `request()` indeed exists, but it only deals with text-like data, and does not support binary data or response headers reading yet. - - Because this plugin allows uploading and downloading binary data, so a more feature-rich api is needed. +For using this plugin in Obsidian version < 0.13.25, we need to configure the server side to return the header `Access-Control-Allow-Origin` allowing the origins `app://obsidian.md` and `capacitor://localhost` and `http://localhost`. Here is an example [configuration for Amazon S3](./s3_cors_configure.md). diff --git a/docs/s3_cors_configure.md b/docs/s3_cors_configure.md index 428f015..1c6a95f 100644 --- a/docs/s3_cors_configure.md +++ b/docs/s3_cors_configure.md @@ -1,5 +1,7 @@ # How To Configure S3 CORS Rules +If you are using the latest version of this plugin AND Obsidian >= 0.13.25, you do not need to configure it any more. If you are using Obsidian < 0.13.25, you are required to configure the rules as following. + Thanks to [@NAL100 in the Discussion](https://github.com/fyears/remotely-save/discussions/28). Please try this config: diff --git a/docs/services_connectable_or_not.md b/docs/services_connectable_or_not.md index 9d120ba..eab2bc3 100644 --- a/docs/services_connectable_or_not.md +++ b/docs/services_connectable_or_not.md @@ -2,39 +2,41 @@ Here is an overview of the connectability ("connectable" or "not connectable" or "in the plan" or "never") to some services by this plugin. +The plugin works under the browser environment in Obsidian, so CORS is an issue. Obsidian starts to provide a rich API `requestUrl` for version >= 0.13.25 to bypass the CORS issue. But if the users are still using an older version of Obsidian, they need to configure CORS on server. + The list is for information purposes only. -| Service | Connectable | by S3 | by WebDAV | by other protocol | More Info | -| ------------------------------------------------------------------------------------- | ----------- | ----- | --------- | ----------------- | ------------------------------------------------------------ | -| Amazon S3 | Yes | Yes | | | [CORS config needed.](./s3_cors_configure.md) | -| Tencent Cloud - Cloud Object Storage (COS) 腾讯云对象存储 | Yes | Yes | | | CORS config needed. | -| Alibaba Cloud - Object Storage Service 阿里云对象存储 | Yes | Yes | | | CORS config needed. | -| Backblaze B2 Cloud Storage | No | No | | | Its CORS rules doesn't allow no-http(s) origins. | -| [Wasabi](https://wasabi.com) | ? | ? | | | | -| [filebase](https://filebase.com/) | Yes | Yes | | | CORS config needed. | -| QingStor 青云 | ? | ? | | | | -| [MinIO](https://min.io/) | ? | ? | | | | -| [WsgiDAV](https://github.com/mar10/wsgidav) | Yes | | Yes | | CORS rules can be set. | -| [Nginx `ngx_http_dav_module`](http://nginx.org/en/docs/http/ngx_http_dav_module.html) | ? | | ? | | Should be possible? | -| NextCloud | No? | | No? | | No CORS config by default. | -| OwnCloud | No? | | No? | | No CORS config by default. | -| Seafile | ? | | ? | | | -| `rclone serve webdav` | No | | No | | No CORS support. | -| [Nutstore 坚果云](https://www.jianguoyun.com/) | No | | No | | No CORS support. | -| [TeraCLOUD](https://teracloud.jp/en/) | No | | No | | No CORS support. | -| Dropbox | Yes | | | Yes | | -| OneDrive for personal | Yes | | | Yes | | -| OneDrive for Business | In the plan | | | ? | | -| Google Drive | In the plan | | | ? | | -| [Box](https://www.box.com/) | ? | | | ? | May be possible but needs further development. | -| Google Cloud Storage | ? | | | ? | May be possible but needs further development. | -| Microsoft Azure Blob Storage | ? | | | ? | May be possible but needs further development. | -| [OpenStack Storage (Swift)](https://github.com/openstack/swift) | ? | | | ? | May be possible but needs further development. | -| https://put.io/ | ? | | | ? | | -| Yandex Disk | ? | | | ? | | -| FTP / FTPS | Never | | | No | Technically never possible to be implemented. | -| SFTP | Never | | | No | Technically never possible to be implemented. | -| Jottacloud | No | | | No | It seems that no open api is available. | -| Mega | Never | | | No | No js api is available. | -| Git | Never | | | No | Technically very hard, if not impossible, to be implemented. | -| | | | | | | +| Service | Connectable | by S3 | by WebDAV | by other protocol | can bypass CORS issue in Obsidian>=0.13.25 | need CORS config in Obsidian<0.13.25 | +| ------------------------------------------------------------------------------------- | ----------- | ----- | --------- | ---------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------ | +| Amazon S3 | Yes | Yes | | | Yes | [CORS config needed.](./s3_cors_configure.md) | +| Tencent Cloud - Cloud Object Storage (COS) 腾讯云对象存储 | Yes | Yes | | | Yes | CORS config needed. | +| Alibaba Cloud - Object Storage Service 阿里云对象存储 | Yes | Yes | | | Yes | CORS config needed. | +| Backblaze B2 Cloud Storage | Yes | Yes | | | Yes | Its CORS rules doesn't allow no-http(s) origins. | +| [Wasabi](https://wasabi.com) | ? | ? | | | | | +| [filebase](https://filebase.com/) | Yes | Yes | | | Yes | CORS config needed. | +| QingStor 青云 | ? | ? | | | | | +| [MinIO](https://min.io/) | ? | ? | | | | | +| [WsgiDAV](https://github.com/mar10/wsgidav) | Yes | | Yes | | Yes | CORS rules can be set. | +| [Nginx `ngx_http_dav_module`](http://nginx.org/en/docs/http/ngx_http_dav_module.html) | Yes? | | Yes? | | Yes? | ? | +| NextCloud | Yes? | | Yes? | | Yes? | No CORS config by default. | +| OwnCloud | Yes? | | Yes? | | Yes? | No CORS config by default. | +| Seafile | Yes? | | Yes? | | Yes? | | +| `rclone serve webdav` | Yes | | Yes | | Yes | No CORS support. | +| [Nutstore 坚果云](https://www.jianguoyun.com/) | Yes | | Yes | | Yes | No CORS support. | +| [TeraCLOUD](https://teracloud.jp/en/) | Yes | | Yes | | Yes | No CORS support. | +| Dropbox | Yes | | | Yes | | | +| OneDrive for personal | Yes | | | Yes | | | +| OneDrive for Business | In the plan | | | ? | | | +| Google Drive | In the plan | | | ? | | | +| [Box](https://www.box.com/) | ? | | | May be possible but needs further development. | | | +| Google Cloud Storage | ? | | | May be possible but needs further development. | | | +| Microsoft Azure Blob Storage | ? | | | May be possible but needs further development. | | | +| [OpenStack Storage (Swift)](https://github.com/openstack/swift) | ? | | | May be possible but needs further development. | | | +| https://put.io/ | ? | | | ? | | | +| Yandex Disk | ? | | | ? | | | +| FTP / FTPS | Never | | | Technically never possible to be implemented. | | | +| SFTP | Never | | | Technically never possible to be implemented. | | | +| Jottacloud | No | | | No. It seems that no open api is available. | | | +| Mega | Never | | | No. No js api is available. | | | +| Git | Never | | | No. Technically very hard, if not impossible, to be implemented. | | | +| | | | | | | |