Auth docs

modus/authentication.mdx

@@ -2,3 +2,73 @@
 title: Authentication
 description: ""
 ---
+
+Modus supports authentication via the `Authorization` header in HTTP requests. You can use the
+`Authorization` header to pass a bearer JSON Web Token (JWT) to your Modus app. The token
+authenticates the user and authorize access to resources.
+
+## Setting verification keys
+
+To verify the token, you must pass the public keys via environment variables to modus, using the
+`MODUS_PEMS` environment variable. The value of the `MODUS_PEMS` environment variable should be a
+JSON object with the public keys as key-value pairs. This way, Modus can deserialize this into a map
+of public keys, and use them to verify the token.
+
+This is an example of how to set the `MODUS_PEMS` environment variable:
+
+```bash
+export MODUS_PEMS='{\"key1\":\"-----BEGIN PUBLIC KEY-----\\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAwJ9z1z1z1z1z1z\\n-----END PUBLIC KEY-----\"}'
+```
+
+## Verifying tokens
+
+To verify the token, Modus uses the public keys passed via the `MODUS_PEMS` environment variable. If
+the token is verifiable with any of the verification keys provided, Modus decodes the JWT token and
+pass the decoded claims as an environment variable, allowing access through host functions.
+
+## Accessing claims
+
+To access the decoded claims, you can use the `getJWTClaims()` function, available in both Golang
+and AssemblyScript. The function allows the user to pass in a class to deserialize the claims into,
+and returns an instance of the class with the claims.
+
+This is an example of how to use the `getJWTClaims()` function in AssemblyScript:
+
+```ts AssemblyScript
+import { auth } from "@hypermode/modus-sdk-as"
+
+@json
+export class ExampleClaims {
+  public sub!: string
+  public exp!: i64
+  public iat!: i64
+}
+
+export function getClaims(): ExampleClaims {
+  return auth.getJWTClaims<ExampleClaims>()
+}
+```
+
+This is an example of how to use the `getJWTClaims()` function in Golang:
+
+```go
+package main
+
+import (
+    "github.com/hypermodeinc/modus/sdk/go/pkg/auth"
+)
+
+type ExampleClaims struct {
+    Sub string `json:"sub"`
+    Exp int64  `json:"exp"`
+    Iat int64  `json:"iat"`
+}
+
+func GetClaims() (*ExampleClaims, error) {
+    return auth.GetJWTClaims[*ExampleClaims]()
+}
+
+```
+
+This allows users to access the claims in the token and use them to authenticate and authorize users
+in their Modus app.

styles/config/vocabularies/general/accept.txt

@@ -53,4 +53,5 @@ triaging
 upsert
 URL|url
 urql
-UUID
+UUID
+[Dd]eserialize