feature(docs): Add communication pages

docs/malta.config.json

@@ -5,13 +5,19 @@
   "twitter": "@lauradotjs",
   "sidebar": [
     {
-      "title": "Use cases"
-    },
-    {
-      "title": "Credentials"
+      "title": "Communication",
+      "pages": [
+        ["Use cases", "/communication/use-cases"],
+        ["Credentials", "/communication/credentials"]
+      ]
     },
     {
-      "title": "Design"
+      "title": "Design",
+      "pages": [
+        ["Next.js SDK", "/design/sdk"],
+        ["Components", "/design/components"],
+        ["Backend", "/design/backend"]
+      ]
     },
     {
       "title": "DX Research",
@@ -26,7 +32,8 @@
     {
       "title": "Links",
       "pages": [
-        ["GitHub Repository", "https://github.com/LauraBeatris/m2m-auth"]
+        ["GitHub Repository", "https://github.com/LauraBeatris/m2m-auth"],
+        ["M2M auth with Next.js", "add-vercel-link-here"]
       ]
     }
   ]

docs/pages/communication/credentials/index.md

@@ -0,0 +1,90 @@
+---
+title: "Communication - Credentials"
+---
+
+# Credentials
+
+There are many authentication methods that can be used to communicate between machines securely. In this section, we'll focus on providing further context for each mechanism and also outlining the security considerations for each.
+
+### Table of contents
+
+- [Client Credentials grant flow in OAuth 2.0](#client-credentials-grant-flow-in-oauth-20)
+- [JWT](#jwt)
+- [OpenID Connect](#openid-connect)
+- [Security Considerations](#security-considerations)
+
+### Client Credentials grant flow in OAuth 2.0
+
+Used by clients to obtain an access token outside of the context of a user, through non-user principals. Typically used by clients to access resources about themselves rather than to access a user's resources.
+
+The client application authenticates with the authorization server using its own credentials. Upon successful authentication, the authorization server issues an access token. The client application can then use this token to make API requests to the resource server.
+
+Instead of managing those credentials in-house, it's a good practice to use a third-party service to handle authorization and manage API keys for your clients.
+
+[![Client Credentials](https://i.ibb.co/6Dzc12z/Clean-Shot-2024-04-07-at-13-22-03.png)](https://ibb.co/HG6Lx06)
+
+### JWT
+
+Regardless the authentication protocol chose for M2M communication, it'll involves JWT at some point, therefore let's do a quick recap on it.
+
+#### JWT vs API Keys
+
+| FEATURE             | JSON Web Tokens (JWTs)                            | API Keys                                  |
+|---------------------|---------------------------------------------------|-------------------------------------------|
+| Type of token       | Self-contained, verifiable JSON-based tokens with claims | Alphanumeric strings or values that must encrypted or signed for security |
+| Security            | More secure than API keys because tokens are cryptographically signed and encrypted | Less secure than JWTs because security depends on implementation for encryption, hashing and storage |
+| Access control      | Supports granular access control via claims and scopes | Supports basic access control unless implemented with additional metadata |
+| Validity            | Supports token expiration                         | Keys have to be revoked manually or rotated |
+
+#### Format
+
+- Header (JSON) [required]:
+  - `alg` - The signing algorithm used
+  - `typ` - The type of token
+- Payload (JSON) [required]:
+  - `iss` - The issuer, which uniquely identifies the party that issued the JWT
+  - `sub` - The subject, uniquely identifies the party to which the JWT relates
+  - `aud` - The audience, defines whom the JWT is suitable for
+  - `exp` - The expiration time
+  - `iat` - The time the token was issued
+  - `jti` - The unique identifier for the token
+- Signature [required]
+
+#### Base64-URL
+
+The output of the signed JWT is built on top of Base64 encoding which is URL safe.
+
+#### Private claims
+
+Defined by consumers and producers of the JWT.
+
+```json
+{
+  "profile.modify": true,
+  "catalog.service": ["read", "write", "delete"]
+}
+```
+
+#### Best Practices
+
+- Always perform algorithm verification
+- Use appropriate algorithms
+- Always perform all validations
+- Always perform cryptographic inputs
+- Pick strong keys
+- Validate all possible claims
+
+
+
+### OpenID Connect
+
+In the context of M2M auth, OIDC can be used to replace static CI/CD credentials.
+
+- Adds an identity layer to OAuth2.0
+- The ID token is in the **JWT** format, in comparison to the OAuth2 which does not impose any format for tokens.
+-
+### Security Considerations
+
+- How tokens get generated, stored, retrieved, and verified
+- Tokens format/encryption
+- Tokens rotation/expiration

docs/pages/communication/use-cases/index.md

@@ -0,0 +1,48 @@
+---
+title: "Communication - Use cases"
+---
+
+# Use cases
+
+This section outlines use cases in which applications have to support for secure and instant communication between services/machines.
+
+### Table of contents
+
+- [API Key Management](#api-key-management)
+- [Service-to-Service Tokens](#service-to-service-tokens)
+- [Authenticating services within CI/CD Pipelines](#authenticating-services-within-cicd-pipelines)
+
+### API Key Management
+
+The first scenario involves API Key Management, it behaves a bit different than Service-to-Service Tokens. When SaaS applications have their own set of APIs that need to communicate with their customer machines without using user's identity.
+
+A set of API keys are generated from the SaaS application which can then be sent from the customer's API request via a HTTP header.
+
+[![API Key Management](https://i.ibb.co/M2C7wrF/Clean-Shot-2024-04-07-at-10-37-19.png)](https://ibb.co/RvDcrfR)
+
+### Service-To-Service Tokens
+
+Service-to-service tokens are often used in more distributed systems, where microservices need to communicate with each other. It's about both authentication and authorization.
+
+In this case, we don't have a user identity that initiates the process by generating a set of API keys on an application side.
+
+The generated tokens are often JWTs, containing claims that can specify the identity of the service, the scope of access and the token's expiration time. For more details regarding the JWT structure, refer to [Credentials](../credentials/index.md)
+
+Services like [HashiCorp vault](https://www.vaultproject.io/) are often used to manage tokens for each service in a cluster.
+
+[![S2S Tokens](https://i.ibb.co/s9MQCpD/Clean-Shot-2024-04-07-at-11-14-26.png)](https://ibb.co/gZBwdbX)
+
+### Authenticating services within CI/CD Pipelines
+
+This use case involves creating a service designed for integration within CI/CD workflows. There are two options here:
+- [Recommended] OpenID Connect can be used to replace CI/CD credentials
+- [Alternative] CI/CD credentials with static API keys generated from each service
+
+#### OpenID Connect
+
+OpenID Connect can be used to replace CI/CD credentials. As a reference, [AWS](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/configuring-openid-connect-in-amazon-web-services) allows GitHub actions to access resources without needing to store credentials as secrets, through the usage of [OpenID Connect](../use-cases/index.md).
+
+The client is a cloud provider such as AWS. The end user is a job running in a CI/CD pipeline. The benefits are:
+- Infrastructure as Code (IaC) compatibility
+- Short-lived credentials
+- No need for manual credential management

docs/pages/index.md

@@ -6,6 +6,6 @@ title: "Machine to Machine Auth"
 
 Product shaping for Machine to Machine Auth, including research across various providers and authentication strategies.
 
-Machine to Machine Auth enables two distinct non-user principals (autonomous systems or agents) to grant access rights to each other instantly, without the need for user identities.
+Machine-to-machine Auth enables two distinct non-user principals (autonomous systems or agents) to grant access rights to each other instantly, without the need for user identities.
 
 *Created by [Laura Beatris](https://github.com/LauraBeatris)*

docs/pages/research/auth0/index.md

@@ -1,11 +1,11 @@
 ---
-title: "Auth0"
+title: "DX Research - Auth0"
 ---
 
 # Auth0
 
 - Uses OAuth 2.0 [Client Credentials grant flow](https://datatracker.ietf.org/doc/html/rfc6749).
-- Requires a couple of Auth0 entities: Resource Server and Application (clients).
+- Requires some Auth0 entities: Resource Server and Application (clients).
 - Clients need to be programmatically created via [Auth0 Management API](https://auth0.com/docs/api/management/v2/clients/post-clients), eg: when mapping to SASS customers.
 
 Reference: **[auth0.com/blog/using-m2m-authorization/](https://auth0.com/blog/using-m2m-authorization/)**
@@ -33,7 +33,7 @@ app.get('/api/location/geocode', requireScope('geocode:location'), function(req,
 
 Also available via [API endpoint](https://auth0.com/docs/api/management/v2/clients/post-clients).
 
-By default a Client is not authorized to access any of the Resource Servers. The next step is to authorize the client for the Resource Server and define which scopes are enabled for this client.
+By default, a client is not authorized to access any of the Resource Servers. The next step is to authorize the client for the Resource Server and define which scopes are enabled for this client.
 
 ![Authorizing client](https://raw.githubusercontent.com/auth0-samples/auth0-api-auth-samples/master/docs/media/giftdeliveries-grants.png)
 

docs/pages/research/cloudflare/index.md

@@ -1,5 +1,5 @@
 ---
-title: "Cloudflare"
+title: "DX Research - Cloudflare"
 ---
 
 # Cloudflare

docs/pages/research/planetscale/index.md

@@ -1,13 +1,15 @@
 ---
-title: "Planetscale"
+title: "DX Research - Planetscale"
 ---
 
 # Planetscale
 
-PlanetScale provides the ability to create service tokens for a PlanetScale organization via the CLI or directly in their UI.
+PlanetScale provides the ability to create service tokens for a organization via the CLI or directly in their UI.
 
 Reference: **[planetscale.com/docs/concepts/service-tokens](https://planetscale.com/docs/concepts/service-tokens#use-a-service-token-with-the-planetscale-api)**
 
 [![Service tokens](https://i.ibb.co/7tyMmpL/Clean-Shot-2024-04-06-at-15-10-47.png)](https://ibb.co/23KV4MH)
+
 [![New service token modal](https://i.ibb.co/k9DsP7p/Clean-Shot-2024-04-06-at-15-11-13.png)](https://ibb.co/MG1xJvb)
+
 [![Permissions](https://i.ibb.co/MZ5sBMv/Clean-Shot-2024-04-06-at-15-11-31.png)](https://ibb.co/YPT30pC)

docs/pages/research/propelauth/index.md

@@ -1,11 +1,11 @@
 ---
-title: "Propelauth"
+title: "DX Research - Propelauth"
 ---
 
 # Propelauth
 
 - Provides a hosted UI for creating API keys.
-- Closer to a service-to-service tokens mechanism then a OAuth flow
+- Due to the nature of the generated keys, it's closer to a service-to-service tokens mechanism than an OAuth flow with `client_id` and `client_secret`.
 - Exposes different token types: `Personal` and `Organization`
 - Doesn't support scopes for granular permissions
 

docs/pages/research/stytch/index.md

@@ -1,13 +1,13 @@
 ---
-title: "Stytch"
+title: "DX Research - Stytch"
 ---
 
 # Stytch
 
 - Uses OAuth 2.0 [Client Credentials grant flow](https://datatracker.ietf.org/doc/html/rfc6749).
 - In terms of API design, machines are represented as an `m2m_client` identity.
 - Security considerations: Exposes API endpoints to perform secret rotation.
-- Applications need to create their own wrapper on top of Stytch's token endpoint in order to be exposed for their customers (unless Stytch provides custom auth domains)
+- SaaS applications need to create their own wrapper on top of Stytch's token endpoint in order to be exposed for their customers (unless Stytch provides custom auth domains)
 
 Reference: **[stytch.com/docs/guides/m2m/authenticate-client](https://stytch.com/docs/guides/m2m/authenticate-client)**
 
@@ -30,7 +30,7 @@ curl --request POST \
 
 The API call returns `client_id` and `client_secret` credentials to be exchanged by the client to get an access token.
 
-Permissions can also be enforced by specifying `scopes` in which is going to be contained in the returned `access_token`.
+Permissions can be enforced by specifying `scopes` in which is going to be contained in the returned `access_token`.
 
 An application has to call this API endpoint in order to surface credentials for usage in other external services.