feat: add developer documentation as new Antora module

antora.yml

@@ -4,6 +4,7 @@ version: 'next'
 start_page: ROOT:index.adoc
 nav:
 - modules/ROOT/partials/nav.adoc
+- modules/developer/partials/nav.adoc
 
 asciidoc:
   attributes:

modules/developer/pages/apis/grpc_apis/index.adoc

@@ -0,0 +1,54 @@
+= gRPC
+:toc: right
+:toclevels: 3
+
+
+== _R_emote    _P_rocedure    _C_alls
+
+link:https://grpc.io[gRPC] is a modern open source high performance Remote Procedure Call (RPC) framework that can run in any environment. It can efficiently connect services in and across data centers with pluggable support for load balancing, tracing, health checking and authentication. It is also applicable in last mile of distributed computing to connect devices, mobile applications and browsers to backend services.
+
+== Advantages of gRPC
+
+=== {{< icon "gauge-high" >}} &nbsp; Performance
+
+gRPC uses http/2 by default and is faster than REST. When using protocol buffers for encoding, the information comes on and off the wire much faster than JSON. Latency is an important factor in distributed systems. JSON encoding creates a noticeable factor of latency. For distributed systems and high data loads, gRPC can actually make an important difference. Other than that, gRPC supports multiple calls via the same channel and the connections are bidirectional. A single connection can transmit requests and responses at the same time. gRPC keeps connections open to reuse the same connection again which prevents latency and saves bandwidth.
+
+<--->
+=== {{< icon "helmet-safety" >}} &nbsp; Robustness
+
+gRPC empowers better relationships between clients and servers. The rules of communication are strictly enforced. That is not the case in REST calls, where the client and the server can send and receive anything they like and hopefully the other end understands what to do with it. In gRPC, to make changes to the communication, both client and server need to change accordingly. This prevents mistakes specially in microservice architectures.
+
+=== {{< icon "magnifying-glass-plus" >}} &nbsp; Debuggability
+
+gRPC requests are re-using the same context and can be tracked or traced across multiple service boundaries.
+This helps to identify slow calls and see what is causing delays. It is possible to cancel requests which cancels
+them on all involved services.
+
+<--->
+=== {{< icon "boxes-stacked" >}} &nbsp; Microservices
+
+gRPC has been evolving and has become the best option for communication between microservices because of its unmatched
+performance and its polyglot nature. One of the biggest strengths of microservices is the freedom of programming
+languages and technologies. By using gRPC we can leverage all the advantages of strictly enforced communication
+standards combined with freedom of choice between different programming languages - whichever would fit best.
+
+
+// SHORTCODE: {{< hint type=info title="gRPC Advantages" >}}
+
+- http/2
+- protocol buffers
+- reusable connections
+- multi language support
+// SHORTCODE: {{< /hint >}}
+
+== CS3 APIs
+
+image::ocis/cs3org.png[]
+
+The link:https://github.com/cs3org/cs3apis[CS3 APIs] connect storages and application providers.
+
+The CS3 APIs follow Google and Uber API design guidelines, specially on error handling and naming convention. You can read more about these
+guidelines at https://cloud.google.com/apis/design/ and https://github.com/uber/prototool/blob/dev/style/README.md.
+
+The CS3 APIs use link:https://github.com/protocolbuffers/protobuf[Protocol Buffers version 3 (proto3)] as their
+Interface Definition Language (IDL) to define the API interface and the structure of the payload messages.

modules/developer/pages/apis/http/authorization.adoc

@@ -0,0 +1,142 @@
+= Authorization
+:toc: right
+:toclevels: 3
+
+In its default configuration, Infinite Scale supports three authentication methods as outlined on the link:https://openid.net/specs/openid-connect-core-1_0.html#rfc.section.3[OIDC official site]:
+1. Authorization Code Flow
+2. Implicit Flow
+3. Hybrid Flow
+
+For detailed information on Infinite Scale's support for OpenID Connect (OIDC), please consult the link:https://owncloud.dev/ocis/identity-provider/oidc[OIDC section].
+To authenticate a client app using OIDC, both `client_id` and `client_secret` are essential. Infinite Scale does not offer dynamic registration. The required data for the default link:https://doc.owncloud.com/server/next/admin_manual/configuration/user/oidc/oidc.html#client-ids-secrets-and-redirect-uris[ownCloud clients] can be found in the link and are availble for the following apps:
+- Desktop
+- Android
+- iOS
+
+While selecting an ownCloud client for authentication, take note of specific limitations such as the `Redirect URI`:
+
+| Source | Redirect URI |
+|------|--------|
+|Android|oc://android.owncloud.com|
+|iOS|oc://ios.owncloud.com|
+|Desktop|http://127.0.0.1 <br> http://localhost |
+
+In this example, the desktop app's `client_id` and `client_secret` are being used.
+
+[source,bash]
+----
+client_id=xdXOt13JKxym1B1QcEncf2XDkLAexMBFwiT9j6EfhhHFJhs2KM9jbjTmf8JBXE69
+client_secret=UBntmLjC2yYCeHwsyj73Uwo9TAaecAetRwMw0xYcvNL9yRdLSUi0hUAHfvCHFeFh
+----
+
+== Authorization Code Flow
+
+1. Requesting authorization
+
+   To initiate the OIDC Code Flow, you can use tools like curl and a web browser.
+   The user should be directed to a URL to authenticate and give their consent (bypassing consent is against the standard):
+
+    ```plaintext
+    https://ocis.test/signin/v1/identifier/_/authorize?client_id=client_id&scope=openid+profile+email+offline_access&response_type=code&redirect_uri=http://path-to-redirect-uri
+    ```
+
+    After a successful authentication, the browser will redirect to a URL that looks like this:
+
+    ```plaintext
+    http://path-to-redirect-uri?code=mfWsjEL0mc8gx0ftF9LFkGb__uFykaBw&scope=openid%20profile%20email%20offline_access&session_state=32b08dd...&state=
+    ```
+
+    For the next step extract the code from the URL.
+
+    In the above example,
+    the code is `mfWsjEL0mc8gx0ftF9LFkGb__uFykaBw`
+
+2. Requesting an access token
+
+   The next step in the OIDC Code Flow involves an HTTP POST request
+   to the token endpoint of the _Infinite Scale Identity Server_.
+
+    ```bash
+    curl -vk -X POST https://ocis.test/konnect/v1/token \
+    -d "grant_type=authorization_code" \
+    -d "code=3a3PTcO-WWXfN3l1mDN4u7G5PzWFxatU" \
+    -d "redirect_uri=http:path-to-redirect-uri" \
+    -d "client_id=client_id" \
+    -d "client_secret=client_secret"
+    ```
+
+   Response looks like this:
+    ```json
+    {
+    "access_token": "eyJhbGciOid...",
+    "token_type": "Bearer",
+    "id_token": "eyJhbGciOi...",
+    "refresh_token": "eyJhbGciOiJ...",
+    "expires_in": 300
+    }
+    ```
+
+3. Refreshing an access token
+
+   If the access token has expired, you can get a new one using the refresh token.
+    ```bash
+    curl -vk -X POST https://ocis.test/konnect/v1/token \
+    -d "grant_type=refresh_token" \
+    -d "refresh_token=eyJhbGciOiJ..." \
+    -d "redirect_uri=http://path-to-redirect-uri" \
+    -d "client_id=client_id" \
+    -d "client_secret=client_secret"
+    ```
+
+   Response looks like this:
+    ```json
+    {
+    "access_token": "eyJhbGciOi...",
+    "token_type": "Bearer",
+    "expires_in": 300
+    }
+    ```
+
+== Implicit Code Flow
+
+When using the implicit flow, tokens are provided in a URI fragment of the redirect URL.
+Valid values for the `response_type` request parameter are:
+
+- token
+- id_token token
+
+// SHORTCODE: {{< hint type=warning title="Important Warning" >}}
+If you are using the implicit flow, `nonce` parameter is required in the initial `/authorize` request.
+`nonce=pL3UkpAQPZ8bTMGYOmxHY/dQABin8yrqipZ7iN0PY18=`
+
+bash command to generate cryptographically random value
+[source,bash]
+----
+openssl rand -base64 32
+----
+// SHORTCODE: {{< /hint >}}
+
+The user should be directed to a URL to authenticate and give their consent (bypassing consent is against the standard):
+[source,bash]
+----
+https://ocis.test/signin/v1/identifier/_/authorize?client_id=client_id&scope=openid+profile+email+offline_access&response_type=id_token+token&redirect_uri=http://path-to-redirect-uri&nonce=pL3UkpAQPZ8bTMGYOmxHY/dQABin8yrqipZ7iN0PY18=
+ ```
+
+After a successful authentication, the browser will redirect to a URL that looks like this:
+```bash
+http://path-to-redirect-uri#access_token=eyJhbGciOiJQUzI...&expires_in=300&id_token=eyJhbGciOiJ...&scope=email%20openid%20profile&session_state=c8a1019f5e054d...&state=&token_type=Bearer
+----
+
+For the next step, extract the access_token from the URL.
+[source,bash]
+----
+access_token = 'eyJhbGciOiJQ...'
+ ```
+
+## Hybrid Flow
+The Hybrid Flow in OpenID Connect melds features from both the Implicit and Authorization Code flows. It allows clients to directly retrieve certain tokens from the Authorization Endpoint, yet also offers the option to acquire additional tokens from the Token Endpoint.
+
+The Authorization Server redirects back to the client with appropriate parameters in the response, based on the value of the response_type request parameter:
+- code token
+- code id_token
+- code id_token token