rmorawski/standardnotes-app-web
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

chore: update documentation

Browse Source
This commit is contained in:
Mo
2022-12-07 08:35:47 -06:00
parent 518643dc71
commit 66d08895fe
3 changed files with 49 additions and 423 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
packages/docs/docs/extensions/themes.md
View File

@@ -90,7 +90,7 @@ _Note that font and font sizes do not apply to mobile; only desktop/web._
--sn-stylekit-sans-serif-font: -apple-system, BlinkMacSystemFont, 'Segoe UI',
'Roboto', 'Oxygen', 'Ubuntu', 'Cantarell', 'Fira Sans', 'Droid Sans',
'Helvetica Neue', sans-serif;
--sn-stylekit-grey-1: #72767e;
--sn-stylekit-grey-2: #bbbec4;
--sn-stylekit-grey-3: #dfe1e4;
@@ -98,7 +98,7 @@ _Note that font and font sizes do not apply to mobile; only desktop/web._
--sn-stylekit-grey-4-opacity-variant: #bbbec43d;
--sn-stylekit-grey-5: #f4f5f7;
--sn-stylekit-grey-6: #e5e5e5;
--sn-stylekit-accessory-tint-color-1: #086dd6;
--sn-stylekit-accessory-tint-color-2: #ea6595;
--sn-stylekit-accessory-tint-color-3: #ebad00;
@@ -108,6 +108,53 @@ _Note that font and font sizes do not apply to mobile; only desktop/web._
}
```
### Optional Overrides
```css
--modal-background-color: var(--sn-stylekit-background-color);
--editor-header-bar-background-color: var(--sn-stylekit-background-color);
--editor-background-color: var(--sn-stylekit-editor-background-color);
--editor-foreground-color: var(--sn-stylekit-editor-foreground-color);
--editor-title-bar-border-bottom-color: var(--sn-stylekit-border-color);
--editor-title-input-color: var(--sn-stylekit-editor-foreground-color);
--editor-pane-background-color: var(--sn-stylekit-background-color);
--editor-pane-editor-background-color: var(--sn-stylekit-editor-background-color);
--editor-pane-editor-foreground-color: var(--sn-stylekit-editor-foreground-color);
--editor-pane-component-stack-item-background-color: var(--sn-stylekit-background-color);
--text-selection-color: var(--sn-stylekit-info-contrast-color);
--text-selection-background-color: var(--sn-stylekit-info-color);
--note-preview-progress-color: var(--sn-stylekit-info-color);
--note-preview-progress-background-color: var(--sn-stylekit-passive-color-4-opacity-variant);
--note-preview-selected-progress-color: var(--sn-stylekit-secondary-background-color);
--note-preview-selected-progress-background-color: var(--sn-stylekit-passive-color-4-opacity-variant);
--items-column-background-color: var(--sn-stylekit-background-color);
--items-column-items-background-color: var(--sn-stylekit-background-color);
--items-column-border-left-color: var(--sn-stylekit-border-color);
--items-column-border-right-color: var(--sn-stylekit-border-color);
--items-column-search-background-color: var(--sn-stylekit-contrast-background-color);
--item-cell-selected-background-color: var(--sn-stylekit-contrast-background-color);
--item-cell-selected-border-left-color: var(--sn-stylekit-info-color);
--navigation-column-background-color: var(--sn-stylekit-secondary-background-color);
--navigation-section-title-color: var(--sn-stylekit-secondary-foreground-color);
--navigation-item-text-color: var(--sn-stylekit-secondary-foreground-color);
--navigation-item-count-color: var(--sn-stylekit-neutral-color);
--navigation-item-selected-background-color: rgb(253, 253, 253);
--preferences-navigation-icon-color: var(--sn-stylekit-neutral-color);
--preferences-navigation-selected-background-color: var(--sn-stylekit-info-backdrop-color);
--dropdown-menu-radio-button-inactive-color: var(--sn-stylekit-passive-color-1);
--panel-resizer-background-color: var(--sn-stylekit-secondary-contrast-background-color);
--link-element-color: var(--sn-stylekit-info-color);
```
In order to get SN to display a dock icon for your theme (a circle in the lower right corner of the app that allows you to quickly toggle themes), add the following payload into the your ext.json file when [publishing your theme](/extensions/publishing):
```json

303
packages/docs/docs/specification/auth.md
View File

@@ -1,303 +0,0 @@
---
id: auth
title: Auth API
sidebar_label: Auth
description: Authentication portion of the Standard Notes API.
keywords:
- standard notes
- docs
- notes app
- end-to-end encryption
- sync
image: /img/logo.png
hide_title: false
hide_table_of_contents: false
---
### POST /auth
**Registers a new user**
| | | |
|-------------|---------|---------------------------------------------------------------------------------------------------------------------|
| api | `string` | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
| created | `string` | Integer timestamp representing the date the client generated the account's encryption keys. Example "1622494310383" |
| email | `string` | The account email. |
| ephemeral | `boolean` | Whether the initial session created for this account is ephemeral ("Stay signed in" unchecked). |
| identifier | `string` | Should equal the account email. |
| origination | `string` | Should equal "registration" |
| password | `string` | The server password generated by the client from the user's master password. |
| pw_nonce | `string` | The nonce generated by the client for the user's encryption key. |
| version | `string` | The protocol version the client used to generate the user's encryption key. Latest is "004". |
#### Response
```JSON
{
"session": {
"access_token": "1:457b1f4b-88c2-4328-bf32-fe7dd9431d62:WwKgTEDUoEhxECu6",
"refresh_token": "1:457b1f4b-88c2-4328-bf32-fe7dd9431d62:G-qEoZsFtoj~RLL-",
"access_expiration": 1627678312000,
"refresh_expiration": 1654051238000
},
"key_params": {
"created": "1622494310383",
"identifier": "foo@example.com",
"origination": "registration",
"pw_nonce": "d97ed41c581fe8c3e0dce7d2ee72afcb63f9f461ae875bae66e30ecf3d952900",
"version": "004"
},
"user": {
"uuid": "682f9deb-b75f-4d97-91fa-6fd82a482db1",
"email": "foo@example.com"
}
}
```
### POST /auth/sign_in
**Authenticates a user and returns a session.**
| | | |
|-------------|---------|---------------------------------------------------------------------------------------------------------------------|
| api | `string` | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
| email | `string` | The account email. |
| ephemeral | `boolean` | Whether the session created for this account is ephemeral ("Stay signed in" unchecked). |
| password | `string` | The server password generated by the client from the user's master password. |
#### Response
```JSON
{
"session": {
"access_token": "1:ee03808d-dd05-417c-9c87-d471e49bcc49:Q~-UoIpDhdtkii_t",
"refresh_token": "1:ee03808d-dd05-417c-9c87-d471e49bcc49:Jn8UWzeHx2H5nZI5",
"access_expiration": 1627678779000,
"refresh_expiration": 1654051705000
},
"key_params": {
"created": "1622494310383",
"identifier": "foo@example.com",
"origination": "registration",
"pw_nonce": "d97ed41c581fe8c3e0dce7d2ee72afcb63f9f461ae875bae66e30ecf3d952900",
"version": "004"
},
"user": {
"uuid": "682f9deb-b75f-4d97-91fa-6fd82a482db1",
"email": "foo@example.com"
}
}
```
### GET /auth/params
**Queries the parameters used for key generation for an email address. Queried before signing into an account.**
| | | |
|-------------|---------|---------------------------------------------------------------------------------------------------------------------|
| api | `string` | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
| email | `string` | The account email. |
#### Response
```JSON
{
"identifier": "foo@example.com",
"pw_nonce": "d97ed41c581fe8c3e0dce7d2ee72afcb63f9f461ae875bae66e30ecf3d952900",
"version": "004"
}
```
### POST /auth/change_pw
**Changes a user's password.**
| | | |
|-------------|---------|---------------------------------------------------------------------------------------------------------------------|
| api | `string` | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115" |
| created | `string` | Integer timestamp representing the date the client generated the account's new encryption keys. Example "1622494310383" |
| identifier | `string` | The account email. |
| origination | `string` | Should equal "password-change" |
| current_password | `string` | The old server password generated by the client from the user's master password. |
| new_password | `string` | The new server password generated by the client from the user's master password. |
| pw_nonce | `string` | The nonce generated by the client for the user's encryption key. |
| version | `string` | The protocol version the client used to generate the user's encryption key. Latest is "004". |
#### Response
```JSON
{
"session": {
"access_token": "1:27d4fd8f-b730-4e0a-afd3-1600fb466aaa:HMgmZwV5k5ePt0vj",
"refresh_token": "1:27d4fd8f-b730-4e0a-afd3-1600fb466aaa:wHuTeOB-qWGP3AE3",
"access_expiration": 1627679129000,
"refresh_expiration": 1654052055000
},
"key_params": {
"created": "1622494310383",
"identifier": "foo@example.com",
"origination": "password-change",
"pw_nonce": "be1974ff6fb1c541aa8c71fd3c66851b6492cf224b661c72daf44e0bef3096bb",
"version": "004"
},
"user": {
"uuid": "682f9deb-b75f-4d97-91fa-6fd82a482db1",
"email": "foo@example.com"
}
}
```
## Sessions
### Session Model
| Field | Type | Description |
|----------------|-----------|---------------------------------------------------|
| uuid | `string` | Unique identifier of the session |
| user_uuid | `string` | Unique identifier of the user |
| user_agent | `string` | The user agent used to create the session |
| api_version | `string` | The server API version used to create the session |
| access_token | `string` | The access token used to authenticate requests |
| refresh_token | `string` | The refresh token used to extend tokens |
| access_expiration | `datetime` | The expiration time of the access token |
| refresh_expiration | `datetime` | The expiration time of the refresh token |
| created_at | `datetime` | Date and time of creation of the session |
| updated_at | `datetime` | Last updated date and time of the session |
- Each `session` includes the API version they were created with. This way we can deny sessions for a given API version if we detect a vulnerability with that version in the future
- Sessions are created in the following cases:
- When a user signs in
- When a user registers a new account
---
### Authenticated requests
The `Authorization` request header field is used by clients to make authenticated request. `Bearer` is the only authentication scheme allowed.
The client must send the `access` token generated by the session, in the `Authorization` header. For example:
```
GET /sessions HTTP/1.1
Host: sync.standardnotes.org
Authorization: Bearer <access token>
```
---
Below is a list of endpoints related to session management:
| Method | URL | Params | Description | Successful response code |
|-----------|--------------------------|---------------------|--------------------------------------------------------|--------------------------|
|`POST` | /auth/sign_out | *None* | Terminates the current session | `204` |
|`DELETE` | /session | **uuid** | Terminates the specified session by UUID | `204` |
|`DELETE` | /sessions | *None* | Terminates all sessions, except the current one | `204` |
|`GET` | /sessions | *None* | Lists all sessions active sessions | `200` |
|`POST` | /session/token/refresh | **refresh_token** | Obtains new pair of `access_token` and `refresh_token` | `200` |
A successful request to `GET /sessions` returns the following JSON response:
```json
{
"sessions": [
{
"uuid": "xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx",
"user_agent": "<product> / <product-version> <comment>",
"api_version": "xxxxyyzz",
"current": "<boolean>",
"created_at": "2020-01-01T00:00:00.000Z"
}
...
]
}
```
#### Obtaining tokens
Tokens can be obtained every time the user performs any of the following actions:
1. When a user signs in
1. When a user registers an account
1. When the tokens are refreshed
#### Refreshing tokens
When an expired `access_token` is provided in the `Authorization` HTTP header, the following JSON response is returned:
HTTP Status Code: `498 Expired Access Token`
```json
{
"error": {
"tag": "expired-access-token",
"message": "The provided access token has expired."
}
}
```
To continue accessing resources, the `access_token` must be refreshed. That is, the current `access_token` is replaced with a new one with an extended expiration date.
To refresh an `access_token`, a valid `refresh_token` is needed. This `refresh_token` must meet the following requirements:
- It should belong to the session of the `access_token`
- It should not be expired
Since the `refresh_token` is of single-use, a new `refresh_token` is obtained when the `access_token` is refreshed.
Refreshing tokens is a process that is transparent to the user, meaning that the client will perform the requests to keep valid tokens without user intervention.
Here's how to refresh tokens:
1. Send a `POST` request to `/session/token/refresh`. The body should contain a JSON paylaod with the `refresh_token`:
```
POST /session/token/refresh HTTP/1.1
Host: sync.standardnotes.org
Authorization: Bearer <access token>
{
"refresh_token": "R_xxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx"
}
```
1. The `refresh_token` is validated on the server. Depending of the circumstances, there should be two outcomes:
1. The provided `refresh_token` is valid. If so, a new pair of tokens is generated and the following JSON response is returned:
```json
{
"token": "xxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx",
"session": {
"refresh_expiration": 1583020800,
"refresh_token": "xxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx",
}
}
```
1. The provided `refresh_token` is expired. If so, the following JSON response is returned:
HTTP Status Code: `400 Bad Request`
```json
{
"error": {
"tag": "expired-refresh-token",
"message": "The refresh token has expired."
}
}
```
User must start a new session by re-entering their credentials.
### Expiration
#### Sessions
Sessions should be terminated after a period of inactivity. This is for best security practices.
`Long-lived sessions` are a good choice for our use case, because it can build a better user experience than expiring sessions for a short idle-timeout.
- A `session` that remains inactive for `1 year` will be terminated, along with all `tokens`
#### Tokens
| Name | Type | Expiration |
|-----------|-------------|---------------|
| `access` | Short-lived | `60 days` |
| `refresh` | Long-lived | `1 year` |
- A `refresh` token is of single-use, while an `access` token can be used as long as it is not expired

118
packages/docs/docs/specification/sync.md
View File

@@ -1,118 +0,0 @@
---
id: sync
title: Sync API
sidebar_label: Sync
description: Specification for the Standard Notes Sync API.
keywords:
- standard notes
- docs
- notes app
- end-to-end encryption
- sync
image: /img/logo.png
hide_title: false
hide_table_of_contents: false
---
This document outlines the client-server communication of the Standard Notes ecosystem.
## Item
An `Item` is largely the only model that both clients and server are concerned wtih. The `content` field stores an encrypted object that can be anything the client needs to operate.
Relationships between items are handled by the client, and not the server, and are stored encrypted in the `content` field as `references`.
Items have the following properties:
| name | type | description |
| ------------ | ----------------------------------- | -------------------------------------------------------------------------------------------- |
| uuid | `string` (or uuid for some databases) | The unique identifier for this item. |
| content | `text` | An encrypted string generated by the client. |
| content_type | `string` | The type of data contained in the `content` field. (i.e Note, Tag, SN|Component, etc.) |
| enc_item_key | `text` | The key used to encrypt `content`, itself also encrypted. |
| deleted | `boolean` | Whether the model has been deleted. |
| created_at_timestamp | `integer` | Timestamp representing when the item was created, with microsecond precision. |
| updated_at_timestamp | `integer` | Timestamp representing when the item was updated _by the server_, with microsecond precision. |
## Content
Data generated by the client is stored in the `content` field of the `Item`. An item's `content` is "sticky" and can have any property the client chooses, as well as the following:
| name | type | description |
| ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| appData | `dictionary` | A domain based dictionary whose content must be preserved between platforms. `appData[domain]` contains data the client stores in the item. |
| references | `array` | A metadata array of other `Item` uuids this item is related to and their respective `content_type`. See sample below. |
`references` array structure:
```JSON
[
{uuid: xxxx, content_type: "Tag"},
{uuid: xxxxx, content_type: "Tag"},
]
```
## REST API
General:
1. All requests after initial authentication should be authenticated with a session token in the `Authorization` header:
```
Authorization: Bearer <access token>
```
### POST items/sync
| | | |
|-------------------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| api | `string` | The API version to use. Must not be null, otherwise oldest API version used. Latest value is "20200115". |
| compute_integrity | `boolean` | Should be false in most cases. Pass true if you plan to read the `integrity_hash` result (integrity can be optionally checked once on app launch). |
| items | `array` | An array of Items. |
| limit | `integer` | The maximum number of items to return per request. Official clients use 150. |
| sync_token | `string` | An opaque token returned by the server from a previous sync request. This lets the server know to pull in only new changes. |
| cursor_token | `string` | An opaque pagination token returned by the server from a previous multi-page sync request. Send this value back only if the server returned this value from a previous request. |
#### Response
```JSON
{
"retrieved_items": Array<Item>,
"saved_items": Array<Item>,
"conflicts": Array<Conflict>,
"sync_token": string,
"cursor_token": string?,
"integrity_hash": string?,
}
```
| | |
|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| retrieved_items | Items that are new to the client or have been modified since last sync and should be merged with local values or created locally. |
| saved_items | Items which have been successfully saved. Clients should merge *only* the resulting `updated_at_timestamp` with local values. Do not update local value of `content` from remote `saved_items` value. |
| conflicts | Items which have not been saved by the server and returned to client. |
| sync_token | An opaque token which should be sent back to server in subsequent sync request. |
| cursor_token | An opaque token which should be sent back to server in subsequent sync request (if present). |
#### Conflicts
```typescript
type Conflict = {
server_item?: Item
unsaved_item?: Item
type: 'sync_conflict' | 'uuid_conflict'
}
```
A `sync_conflict` occurs when the item the client is attempting to save has a newer change on the server. The server is able to determine this by reading the `updated_at_timestamp` value from both the incoming payload and the server payload. If the incoming payload's `updated_at_timestamp` != to the server's `updated_at_timestamp` for that item, the save is rejected and returned to client as a `sync_conflict`. These types of conflicts are not uncommon.
To resolve a `sync_conflict`, the client must choose a winner between server_item and unsaved_item then re-sync. The winning item should have its updated_at_timestamp value set to the server's value.
A `uuid_conflict` occurs when the UUID the client has choosen for an item for X user already belongs to an item for Y user. This should mostly only occur when a user registers a new account and imports a data backup from another account.
To resolve a `uuid_conflict`, change the UUID of the item attempting to be saved to a new UUID, then re-sync.
#### Deletion
To delete an item permanently, set `deleted` to `true` on the `Item` and sync. When receiving an item that is `deleted`, remove it from the local database immediately.