Improve documentation related to authentication (#750)

doc-surrealdb_versioned_docs/version-latest/security/authentication.mdx

@@ -110,7 +110,7 @@ curl -X POST \
 
 <Since v="v2.0.0" />
 
-Record users represent users that are defined as a record in a database instead of through the `DEFINE USER` statement. Since these users exist as regular database records, they can have associated fields containing any information required for authentication and authorization. 
+Record users (called "scope users" before v2.0.0) represent users that are defined as a record in a database instead of through the `DEFINE USER` statement. Since these users exist as regular database records, they can have associated fields containing any information required for authentication and authorization.
 
 Thanks to this, SurrealDB is able to offer mechanisms to define your own signin and signup logic as well as custom table and field permissions for record users. This feature contributes to making SurrealDB an all-in-one BaaS (Backend-as-a-Service).
 
@@ -254,6 +254,109 @@ curl -X POST \
 
 Whenever authentication is performed with any kind of user against SurrealDB, a session is established between the client and the SurrealDB server with which the connection was established. These sessions exist only in memory on the server for the duration of the connection, whether it is a single request through the [HTTP REST API](/docs/surrealdb/integration/http) or through multiple requests in the same connection using the [WebSocket API](/docs/surrealdb/integration/rpc) and any of the [SDKs](/docs/surrealdb/integration/sdks/) that leverage it.
 
+### Parameters
+
+Certain security-related parameters are automatically set by SurrealDB in the context of a session. These parameters can be referenced in SurrealQL during authentication and authorization.
+
+#### Session
+
+The `$session` parameter contains information about the current session. This parameter is set in every SurrealDB session.
+
+In the following example, you can see the result of the `SELECT * FROM $session` query in an authenticated session for a record user using the [HTTP REST API](/docs/surrealdb/integration/http):
+
+```json
+{
+	"ac": "user",
+	"db": "test",
+	"exp": null,
+	"id": "example-client",
+	"ip": "127.0.0.1",
+	"ns": "test",
+	"or": "http://www.example.com",
+	"rd": "user:example",
+	"tk": {
+		"AC": "user",
+		"DB": "test",
+		"ID": "user:example",
+		"NS": "test",
+		"exp": 1723118226,
+		"iat": 1723114626,
+		"iss": "SurrealDB",
+		"jti": "3b3fe74a-955c-46d7-9400-363848912292",
+		"nbf": 1723114626
+	}
+}
+```
+
+On the root of the object, you will find the following fields:
+
+- `ip`: The IP address that established the connection with SurrealDB.
+- `exp`: The time at which the session will expire.
+  - Will be `NONE` or `null` when the session does not expire.
+- `ns`: The name of the currently selected namespace.
+  - Will be `NONE` or `null` when no namespace is selected.
+- `db`: The name of the currently selected database.
+  - Will be `NONE` or `null` when no database is selected.
+- `rd`: The record identifier of the currently authenticated record user.
+  - Will be `NONE` or `null` when unauthenticated or authenticated as a system user.
+- `ac`: The name of the access method that was used to authenticate.
+  - Will be `NONE` or `null` when not authenticated with an access method.
+- `or`: The value of the `Origin` header of the HTTP request.
+  - This header is usually set by browsers to identify the site that originated the request.
+- `id`: The value of the `surreal-id` header of the HTTP request.
+  - This value can be set by clients to identify their individual sessions to the server.
+- `tk`: An object containing the claims present in the authentication token used to establish the session.
+  - Will be `NONE` or `null` when not authenticated.
+
+The values stored in the session parameter can be accessed through [the `session::*` family of functions](https://surrealdb.com/docs/surrealdb/surrealql/functions/database/session).
+
+#### Token
+
+The `$token` parameter contains the claims contained in the token used to authenticate the current session. This parameter is set in every authenticated SurrealDB session.
+
+In this example, you can see the result of the `SELECT * FROM $token` query in an authenticated session for a record user:
+
+```js
+{
+	"AC": "user",
+	"DB": "test",
+	"ID": "user:example",
+	"NS": "test",
+	"exp": 1723118226,
+	"iat": 1723114626,
+	"iss": "SurrealDB",
+	"jti": "3b3fe74a-955c-46d7-9400-363848912292",
+	"nbf": 1723114626
+}
+```
+
+Whenever authentication is done directly using a token, this object will contain the claims contained in that token.
+
+When that token is issued by SurrealDB after successful authentication, the object will usually contain the following fields:
+
+- `NS`: The name of the namespace the user is authenticated in.
+  - Will be `NONE` or `null` when the user is authenticated at the root level.
+- `DB`: The name of the database the user is authenticated in.
+  - Will be `NONE` or `null` when the user is authenticated at the root or namespace level.
+- `ID`: The record identifier of the currently authenticated record user.
+  - Will not be present when not authenticated as a record user.
+- `AC`: The name of the access method that is used to authenticate.
+  - Will be `NONE` or `null` when authenticating without an access method.
+
+The following fields correspond to claims defined in the standard JWT implementation described in [RFC 7519](https://datatracker.ietf.org/doc/html/rfc7519):
+
+- `iat`: The time at which the token was issued.
+- `nbf`: The time before which the token will not be accepted to establish new authenticated sessions.
+- `exp`: The time after which the token will not be accepted to establish new authenticated sessions.
+- `jti`: A unique identifier used to reference the token.
+- `iss`: A string identifying the entity which issued the token.
+
+#### Auth
+
+The `$auth` parameter points to the record belonging to the current authenticated record user. This parameter is set only when the session is authenticated with an existing record user.
+
+When the `$auth` parameter is set, you can access any of the fields of the record corresponding to the authenticated user (e.g. `$auth.name` or `$auth.email`) via that parameter.
+
 ### Expiration
 
 Authenticated sessions remain valid for a certain duration. This duration is `NONE` by default, meaning that sessions will not expire unless otherwise specified. This duration can be customised on both the `DEFINE USER` and `DEFINE ACCESS` statements to any specific value defining the maximum duration of an authenticated session associated with that user or access method. After the defined duration, the authenticated session will expire. For example, the `DEFINE USER example DURATION FOR SESSION 1d` clause will ensure that any authenticated sessions for the `example` user will expire after a day.

doc-surrealdb_versioned_docs/version-latest/surrealql/parameters.mdx

@@ -240,6 +240,8 @@ END
 
 Represents values from the session functions as an object.
 
+You can learn more about those values from the [security parameters](../security/authentication#session) section.
+
 ```surql
 CREATE user SET 
     name = "Some User",
@@ -260,6 +262,8 @@ CREATE user SET
 
 Represents values held inside the JWT token used for the current session.
 
+You can learn more about those values from the [security parameters](../security/authentication#token) section.
+
 ```surql
 DEFINE TABLE user SCHEMAFULL
   PERMISSIONS FOR select, update, delete, create

doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/index.mdx

@@ -30,7 +30,7 @@ DEFINE ACCESS [ OVERWRITE | IF NOT EXISTS ] @name
       [ WITH JWT
         [ ALGORITHM @algorithm KEY @key | URL @url ]
         [ WITH ISSUER KEY @key ]
-  ]
+      ]
   [ AUTHENTICATE @expression ]
   [ DURATION
     [ FOR TOKEN @duration ]

doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/jwt.mdx

@@ -31,9 +31,8 @@ Bear in mind that table and field permissions only apply to [record users](/docs
 DEFINE ACCESS [ OVERWRITE | IF NOT EXISTS ] @name
   ON [ ROOT | NAMESPACE | DATABASE ]
   TYPE JWT [ ALGORITHM @algorithm KEY @key | URL @url ]
-   [ AUTHENTICATE @expression ]
+  [ AUTHENTICATE @expression ]
   [ DURATION FOR SESSION @duration ]
-  
 ```
 
 ## Verification Types

doc-surrealdb_versioned_docs/version-latest/surrealql/statements/define/access/record.mdx

@@ -27,11 +27,11 @@ DEFINE ACCESS [ IF NOT EXISTS ] @name
   ON DATABASE TYPE RECORD
     [ SIGNUP @expression ]
     [ SIGNIN @expression ]
-    [ AUTHENTICATE @expression ]
     [ WITH JWT
       [ ALGORITHM @algorithm KEY @key | URL @url ]
       [ WITH ISSUER KEY @key ]
     ]
+  [ AUTHENTICATE @expression ]
   [ DURATION
     [ FOR TOKEN @duration ]
     [ FOR SESSION @duration ]