<commit_before># Doctypes

`io.cozy.konnectors` gives their desiderata for an account

```json
{
  "fields": {
    "account": {
      "doctype": "io.cozy.accounts",
      "account_type": "maif",
      "scope": "openid profile offline_access",
    },
  },

}
```

`io.cozy.accounts` contains authentication information for an account,
as well as the associated scope

```json
{
    "name" : "<NAME>",
    "account_type": "maif",
    "status": "connected",
    "oauth": {
      "access_token": "<PASSWORD>",
      "refresh_token": "<PASSWORD>",
      "scope": "openid profile offline_access"
    }
}
```

`io.cozy.account_types` contains the oauth configuration

```json
{
  "_id":"service.example",
  "grant_mode": "authorization_code",
  "client_id": "the registered client id",
  "client_secret": "client_secret is necessary for server-flow",
  "auth_endpoint": "https://service.example/auth",
  "token_endpoint":  "https://api.service.example/token"
}
```

io.cozy.account_types should not accessible by applications. They will be loaded into the stack by infra and will be configurable through config files for self-hosters.

# Reminder OAuth flow

**Service** is the website from which konnector aims to retrieve informations.
**Stack** is the cozy stack

Oauth is divided in 3 steps
- Client Registration: the client application (the Stack) needs to be registered with the Service.
- Obtaining & Refreshing Authorization: all the steps from client_id to access_token, the Stack will handle those
- Using the access_token: Ideally, the konnector should only concern itself with this part; it receives an access_token and uses it.


# Client Registration

Before beginning the Grant process, most Services require the application to be registered with a defined redirect_uri.

**TL:DR** Lot of options, which we will choose from when actually implementing konnectors using them.

## Manually

Most services requires an human developer to create the client manually and define its redirect_uri. However each instance has its own domain, so for these services, we will need to :

**A. Register a "proxy" client**, which is a static page performing redirections as needed, as was done for Facebook events in v2 konnectors. We will register a well known cozy domain, like `oauth-proxy.cozy.io` and registers it with all providers.
The use and risks associated with this domain should be made clear to the user.

**B. Register each Stack** with a redirect_uri on the main stack domain, if we go this way, the register_uri below moves from `bob.cozy.rocks/accounts/redirect` to `_cozy_oauth.cozy.rocks/redirect` and the domain wil be prepended to the state.
This is feasible at cozy scale, but requires more knowledge and work for self-hosters.

## Dynamic Registration Protocol

A few services allows client to register programaticaly through the Dynamic Client Registration Protocol [RFC7591](https://tools.ietf.org/html/rfc7591), we should allow the Stack to register using this protocol when we first need to implement a Konnector connecting to such a Service.

## No redirect_url enforcement

A few services allows to specify arbitrary redirect_url without registering beforehand as a client.


# Authorization Grant flows

## webserver flow (Authorization Code Grant)

A. In SettingsApp give a link

```html
  <a href="https://bob.cozy.rocks/accounts/service-name/start? (url)
      scope=photos&
      state=1234zyx">
```

**NOTE** the scope may depends on other fields being configured (checkboxes), this will be described in json in the konnectors manifest. The format will be determined upon implementation.

**NOTE** To limit bandwith and risk of state corruption, SettingsApp should save its state under a random key into localStorage, the key is then passed as the state in this query.

B. Service let the user login, allow or deny scope
Then redirect to
```http
https://bob.cozy.rocks/accounts/service-name/redirect? (url)
  code=AUTH_CODE_HERE&
  state=1234zyx
```

C. The Stack does Server side
```http
POST https://api.service.example/token
Content-Type:
  grant_type=authorization_code&
  code=AUTH_CODE_HERE&
  redirect_uri=https://bob.cozy.rocks/accounts/service-name/redirect&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET
```

D. The Service responds (server side) with (json)
```json
{<commit_msg>Fix some typos in the OAuth for konnectors doc<commit_after># Doctypes

`io.cozy.konnectors` gives their desiderata for an account

```json
{
  "fields": {
    "account": {
      "doctype": "io.cozy.accounts",
      "account_type": "maif",
      "scope": "openid profile offline_access",
    },
  },

}
```

`io.cozy.accounts` contains authentication information for an account,
as well as the associated scope

```json
{
    "name" : "<NAME>",
    "account_type": "maif",
    "status": "connected",
    "oauth": {
      "access_token": "<PASSWORD>",
      "refresh_token": "<PASSWORD>",
      "scope": "openid profile offline_access"
    }
}
```

`io.cozy.account_types` contains the oauth configuration

```json
{
  "_id": "service.example",
  "grant_mode": "authorization_code",
  "client_id": "the registered client id",
  "client_secret": "client_secret is necessary for server-flow",
  "auth_endpoint": "https://service.example/auth",
  "token_endpoint":  "https://api.service.example/token"
}
```

io.cozy.account_types should not be accessible to the applications. They will be loaded into the stack by infra and will be configurable through config files for self-hosters.

# Reminder OAuth flow

**Service** is the website from which konnector aims to retrieve informations.
**Stack** is the cozy stack

Oauth is divided in 3 steps
- Client Registration: the client application (the Stack) needs to be registered with the Service.
- Obtaining & Refreshing Authorization: all the steps from client_id to access_token, the Stack will handle those
- Using the access_token: Ideally, the konnector should only concern itself with this part; it receives an access_token and uses it.


# Client Registration

Before beginning the Grant process, most Services require the application to be registered with a defined redirect_uri.

**TL:DR** Lot of options, which we will choose from when actually implementing konnectors using them.

## Manually

Most services requires a human developer to create the client manually and define its redirect_uri. However each instance has its own domain, so for these services, we will need to:

**A. Register a "proxy" client**, which is a static page performing redirections as needed, as was done for Facebook events in v2 konnectors. We will register a well known cozy domain, like `oauth-proxy.cozy.io` and registers it with all providers.
The use and risks associated with this domain should be made clear to the user.

**B. Register each Stack** with a redirect_uri on the main stack domain, if we go this way, the register_uri below moves from `bob.cozy.rocks/accounts/redirect` to `_cozy_oauth.cozy.rocks/redirect` and the domain will be prepended to the state.
This is feasible at cozy scale, but requires more knowledge and work for self-hosters.

## Dynamic Registration Protocol

A few services allows client to register programaticaly through the Dynamic Client Registration Protocol [RFC7591](https://tools.ietf.org/html/rfc7591), we should allow the Stack to register using this protocol when we first need to implement a Konnector connecting to such a Service.

## No redirect_url enforcement

A few services allows to specify arbitrary redirect_url without registering beforehand as a client.


# Authorization Grant flows

## webserver flow (Authorization Code Grant)

A. In SettingsApp give a link

```html
  <a href="https://bob.cozy.rocks/accounts/service-name/start? (url)
      scope=photos&
      state=1234zyx">
```

**NOTE** the scope may depends on other fields being configured (checkboxes), this will be described in json in the konnectors manifest. The format will be determined upon implementation.

**NOTE** To limit bandwidth and risk of state corruption, SettingsApp should save its state under a random key into localStorage, the key is then passed as the state in this query.

B. Service let the user login, allow or deny scope
Then redirect to
```http
https://bob.cozy.rocks/accounts/service-name/redirect? (url)
  code=AUTH_CODE_HERE&
  state=1234zyx
```

C. The Stack does Server side
```http
POST https://api.service.example/token
Content-Type:
  grant_type=authorization_code&
  code=AUTH_CODE_HERE&
  redirect_uri=https://bob.cozy.rocks/accounts/service-name/redirect&
  client_id=CLIENT_ID&
  client_secret=CLIENT_SECRET
```

D. The Service responds (server side) with (json)
```json
{
{'fraction_non_alphanumeric': 0.08815744044193809, 'fraction_numerical': 0.004143169524686385, 'mean_word_length': 4.489576753000632, 'pattern_counts': {'":': 34, '<': 11, '<?xml version=': 0, '>': 11, 'https://': 14, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 2, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1517424', 'n_tokens_mistral': 2515, 'n_tokens_neox': 2416, 'n_words': 1045}