docs: General improvements on the docs based on community feedback (serverpod#381)

Author: marcelomendoncasoares

docs/06-concepts/10-modules.md

@@ -2,32 +2,30 @@
 
 Serverpod is built around the concept of modules. A Serverpod module is similar to a Dart package but contains both server, client, and Flutter code. A module contains its own namespace for endpoints and methods to minimize the risk of conflicts.
 
-Examples of modules are the `serverpod_auth` module and the `serverpod_chat` module, which both are maintained by the Serverpod team.
+Examples of modules are the `serverpod_auth_core` and `serverpod_auth_idp` modules, which both are maintained by the Serverpod team.
 
 ## Adding a module to your project
 
 ### Server setup
 
 To add a module to your project, you must include the server and client/Flutter packages in your project's `pubspec.yaml` files.
 
-For example, to add the `serverpod_auth` module to your project, you need to add `serverpod_auth_server` to your server's `pubspec.yaml`:
+For example, to add the `serverpod_auth_idp` module to your project, you need to add `serverpod_auth_idp_server` to your server's `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  serverpod_auth_server: ^1.x.x
+  serverpod_auth_idp_server: ^3.x.x
 ```
 
 :::info
-
-Make sure to replace `1.x.x` with the Serverpod version you are using. Serverpod uses the same version number for all official packages. If you use the same version, you will be sure that everything works together.
-
+Make sure to replace `3.x.x` with the Serverpod version you are using. Serverpod uses the same version number for all official packages. If you use the same version, you will be sure that everything works together.
 :::
 
-In your `config/generator.yaml` you can optionally add the `serverpod_auth` module and give it a `nickname`. The nickname will determine how you reference the module from the client. If the module isn't added in the `generator.yaml`, the default nickname for the module will be used.
+In your `config/generator.yaml` you can optionally add the `serverpod_auth_idp` module and give it a `nickname`. The nickname will determine how you reference the module from the client. If the module isn't added in the `generator.yaml`, the default nickname for the module will be used.
 
 ```yaml
 modules:
-  serverpod_auth:
+  serverpod_auth_idp:
     nickname: auth
 ```
 
@@ -51,7 +49,7 @@ In your client's `pubspec.yaml`, you will need to add the generated client code
 
 ```yaml
 dependencies:
-  serverpod_auth_client: ^1.x.x
+  serverpod_auth_idp_client: ^3.x.x
 ```
 
 ### Flutter app setup
@@ -60,19 +58,20 @@ In your Flutter app, add the corresponding dart or Flutter package(s) to your `p
 
 ```yaml
 dependencies:
-  serverpod_auth_shared_flutter: ^1.x.x
-  serverpod_auth_google_flutter: ^1.x.x
-  serverpod_auth_apple_flutter: ^1.x.x
+  serverpod_auth_idp_flutter: ^3.x.x
 ```
 
 ## Referencing a module
 
-It can be useful to reference serializable objects in other modules from the YAML-files in your models. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
+It can be useful to reference serializable objects in other modules from the YAML-files in your models. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the `serverpod_auth_idp` package.
 
 ```yaml
 class: MyClass
 fields:
-  userInfo: module:auth:UserInfo
+  # Using the full module name
+  userInfo: module:serverpod_auth_idp:AuthUser
+  # Or using the nickname
+  userInfo: module:auth:AuthUser
 ```
 
 ## Creating custom modules
@@ -92,7 +91,5 @@ $ flutter create --template package my_module_flutter
 In your Flutter package, you most likely want to import the client libraries created by `serverpod create`.
 
 :::info
-
 Most modules will need a set of database tables to function. When naming the tables, you should use the module name as a prefix to the table name to avoid any conflicts. For instance, the Serverpod tables are prefixed with `serverpod_`.
-
 :::

docs/06-concepts/11-authentication/01-setup.md

@@ -4,7 +4,7 @@ Serverpod comes with built-in user management and authentication. It is possible
 
 The list of identity providers is continuously growing and new providers are added as they are developed. If you want to contribute a new provider, please consider [contributing](/contribute) your code. See the [identity providers configuration](#identity-providers-configuration) section for details on all available providers.
 
-![Sign-in with Serverpod](/img/authentication/sign-in-widget.png)
+![Sign-in with Serverpod](/img/authentication/sign-in-widget-device.png)
 
 ## Installing the auth module
 

docs/06-concepts/11-authentication/03-working-with-users.md

@@ -1,6 +1,6 @@
 # Working with users
 
-The authentication module provides conventient ways to work with your authenticated users and their related profile data.
+The authentication module provides convenient ways to work with your authenticated users and their related profile data.
 
 ## Authenticated users
 
@@ -40,6 +40,30 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my
 
 For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation.
 
+### Setting a default user image
+
+When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object.
+
+```dart
+  pod.initializeAuthServices(
+    userProfileConfig: UserProfileConfig(
+      // NOTE: The `userImageGenerator` parameter is optional and defaults to
+      // the value below - which generates Gmail-style images. You can change
+      // this parameter to generate any kind of placeholder image. The function
+      // will be called when invoking the `setDefaultUserImage` method.
+      userImageGenerator: defaultUserImageGenerator,
+      onAfterUserProfileCreated:
+          (session, userProfile, {required transaction}) async {
+            await AuthServices.instance.userProfiles.setDefaultUserImage(
+              session,
+              userProfile.authUserId,
+              transaction: transaction,
+            );
+          },
+    ),
+  ...
+  );
+```
 
 ## Attaching additional information
 
@@ -59,6 +83,11 @@ indexes:
     unique: true
 ```
 
+:::tip
+When referencing module classes in your model files, you can use a nickname for the module instead of the full module name. See the [modules documentation](../modules) for more information.
+:::
+
+
 The model above creates a relation to the `AuthUser` table and ensures that each user can only have one `MyDomainData` object. The `onDelete=Cascade` ensures that when the `AuthUser` is deleted, the `MyDomainData` object is also deleted.
 
 This makes it easy to query the additional information later based on the user's `authId`.

docs/06-concepts/11-authentication/04-providers/01-email/02-configuration.md

@@ -67,6 +67,25 @@ final emailIdpConfig = EmailIdpConfigFromPasswords(
 Remember to configure the `verificationCodeConfig` parameter on the `EmailSignInWidget` to match the length of the verification code you generate. Otherwise, users will never be able to enter the verification code correctly. See the [customizing the UI section](./customizing-the-ui) for more details.
 :::
 
+#### Bypassing verification code in development
+
+To simplify testing, it is possible to bypass the verification code by using a custom verification code generator that always returns the same code. This can be configured only for the development run mode as below:
+
+```dart
+pod.initializeAuthServices(
+  tokenManagerBuilders: [
+    JwtConfigFromPasswords(),
+  ],
+  identityProviderBuilders: [
+    EmailIdpConfigFromPasswords(
+      registrationVerificationCodeGenerator: pod.runMode == 'development'
+          ? () => 'aaaaaaaa' // Be sure to match the length used in production.
+          : defaultVerificationCodeGenerator,
+    ),
+  ],
+);
+```
+
 ### Reacting to events
 
 Beyond the `sendRegistrationVerificationCode` and `sendPasswordResetVerificationCode` callbacks to send verification codes to the user, there are a few callbacks that can be used to react to events, such as `onAfterAccountCreated` and `onPasswordResetCompleted`. These can be useful for sending emails to the user to communicate the successful operation.

docs/06-concepts/11-authentication/04-providers/02-google/02-configuration.md

@@ -100,3 +100,25 @@ final googleIdpConfig = GoogleIdpConfigFromPasswords(
   },
 );
 ```
+
+### Lightweight Sign-In on the Flutter app
+
+Lightweight sign-in is a feature that attempts to authenticate users previously logged in with Google automatically with minimal or no user interaction. When enabled, the Google authentication controller will try to sign in users seamlessly using platform-specific lightweight authentication methods. This feature is enabled by default, but can be disabled from the `GoogleSignInWidget` or `GoogleAuthController`.
+
+```dart
+GoogleSignInWidget(
+  client: client,
+  attemptLightweightSignIn: false, // Disable lightweight sign-in
+  onAuthenticated: () {
+    // User was automatically signed in
+  },
+)
+```
+
+:::info
+If lightweight sign-in fails (e.g., no previous session exists or the user dismisses the prompt), the user can still use the regular sign-in button to authenticate manually.
+:::
+
+:::note
+The lightweight sign-in attempt happens automatically when the controller is initialized, typically at app launch. If successful, users will be signed in without any additional interaction.
+:::

docs/08-upgrading/01-upgrade-to-three.md

@@ -241,6 +241,30 @@ class MyEndpoint extends Endpoint {
 
 Serverpod 3.0 includes several changes to the authentication system that improve type safety and performance.
 
+### Custom authentication handlers
+
+In the new authentication system, the default authentication header has changed from `Basic` to `Bearer` - which is now officially supported. This introduced a change for custom `AuthenticationHandler` implementations: the `token` parameter will now receive the token unwrapped from the `Bearer` prefix - just as it does for `Basic` tokens.
+
+If your application relies on the default `authenticationHandler` function, no change is required. Only custom implementations that previously implemented `Bearer` authentication will need to be updated to expect the unwrapped token.
+
+Another change when using custom authentication handlers is that tokens without scheme prefix are no longer supported by default to enforce HTTP header standards. The preferred fix is to wrap the token with the `Bearer` prefix, but this will invalidate existing tokens. If you are you are using a custom authentication handler in production and need to keep the old behavior, you can set the `validateHeaders` parameter to `false` in your `production.yaml` config file.
+
+```yaml
+apiServer:
+  ...
+
+insightsServer:
+  ...
+
+webServer:
+  ...
+
+validateHeaders: false # <-- Add this line
+
+sessionLogs:
+  consoleEnabled: false
+```
+
 ### AuthenticationInfo changes
 
 The `AuthenticationInfo` class has been updated:

static/img/authentication/sign-in-widget-device.png

@@ -2,32 +2,30 @@
 
 Serverpod is built around the concept of modules. A Serverpod module is similar to a Dart package but contains both server, client, and Flutter code. A module contains its own namespace for endpoints and methods to minimize the risk of conflicts.
 
-Examples of modules are the `serverpod_auth` module and the `serverpod_chat` module, which both are maintained by the Serverpod team.
+Examples of modules are the `serverpod_auth_core` and `serverpod_auth_idp` modules, which both are maintained by the Serverpod team.
 
 ## Adding a module to your project
 
 ### Server setup
 
 To add a module to your project, you must include the server and client/Flutter packages in your project's `pubspec.yaml` files.
 
-For example, to add the `serverpod_auth` module to your project, you need to add `serverpod_auth_server` to your server's `pubspec.yaml`:
+For example, to add the `serverpod_auth_idp` module to your project, you need to add `serverpod_auth_idp_server` to your server's `pubspec.yaml`:
 
 ```yaml
 dependencies:
-  serverpod_auth_server: ^1.x.x
+  serverpod_auth_idp_server: ^3.x.x
 ```
 
 :::info
-
-Make sure to replace `1.x.x` with the Serverpod version you are using. Serverpod uses the same version number for all official packages. If you use the same version, you will be sure that everything works together.
-
+Make sure to replace `3.x.x` with the Serverpod version you are using. Serverpod uses the same version number for all official packages. If you use the same version, you will be sure that everything works together.
 :::
 
-In your `config/generator.yaml` you can optionally add the `serverpod_auth` module and give it a `nickname`. The nickname will determine how you reference the module from the client. If the module isn't added in the `generator.yaml`, the default nickname for the module will be used.
+In your `config/generator.yaml` you can optionally add the `serverpod_auth_idp` module and give it a `nickname`. The nickname will determine how you reference the module from the client. If the module isn't added in the `generator.yaml`, the default nickname for the module will be used.
 
 ```yaml
 modules:
-  serverpod_auth:
+  serverpod_auth_idp:
     nickname: auth
 ```
 
@@ -51,7 +49,7 @@ In your client's `pubspec.yaml`, you will need to add the generated client code
 
 ```yaml
 dependencies:
-  serverpod_auth_client: ^1.x.x
+  serverpod_auth_idp_client: ^3.x.x
 ```
 
 ### Flutter app setup
@@ -60,19 +58,20 @@ In your Flutter app, add the corresponding dart or Flutter package(s) to your `p
 
 ```yaml
 dependencies:
-  serverpod_auth_shared_flutter: ^1.x.x
-  serverpod_auth_google_flutter: ^1.x.x
-  serverpod_auth_apple_flutter: ^1.x.x
+  serverpod_auth_idp_flutter: ^3.x.x
 ```
 
 ## Referencing a module
 
-It can be useful to reference serializable objects in other modules from the YAML-files in your models. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the auth package.
+It can be useful to reference serializable objects in other modules from the YAML-files in your models. You do this by adding the module prefix, followed by the nickname of the package. For instance, this is how you reference a serializable class in the `serverpod_auth_idp` package.
 
 ```yaml
 class: MyClass
 fields:
-  userInfo: module:auth:UserInfo
+  # Using the full module name
+  userInfo: module:serverpod_auth_idp:AuthUser
+  # Or using the nickname
+  userInfo: module:auth:AuthUser
 ```
 
 ## Creating custom modules
@@ -92,7 +91,5 @@ $ flutter create --template package my_module_flutter
 In your Flutter package, you most likely want to import the client libraries created by `serverpod create`.
 
 :::info
-
 Most modules will need a set of database tables to function. When naming the tables, you should use the module name as a prefix to the table name to avoid any conflicts. For instance, the Serverpod tables are prefixed with `serverpod_`.
-
 :::

versioned_docs/version-3.0.0/06-concepts/10-modules.md

@@ -4,7 +4,7 @@ Serverpod comes with built-in user management and authentication. It is possible
 
 The list of identity providers is continuously growing and new providers are added as they are developed. If you want to contribute a new provider, please consider [contributing](/contribute) your code. See the [identity providers configuration](#identity-providers-configuration) section for details on all available providers.
 
-![Sign-in with Serverpod](/img/authentication/sign-in-widget.png)
+![Sign-in with Serverpod](/img/authentication/sign-in-widget-device.png)
 
 ## Installing the auth module
 
@@ -60,6 +60,14 @@ void run(List<String> args) async {
 }
 ```
 
+Then, extend the abstract endpoint for refreshing JWT tokens to expose it on the server:
+
+```dart
+import 'package:serverpod_auth_idp_server/core.dart' as core;
+
+class RefreshJwtTokensEndpoint extends core.RefreshJwtTokensEndpoint {}
+```
+
 ### Token Manager Configuration
 
 The authentication system uses token managers to handle authentication tokens. You need to configure at least one token manager to be used as the primary token manager. Additional token managers can be configured to be used for validation and management operations.

versioned_docs/version-3.0.0/06-concepts/11-authentication/01-setup.md

@@ -1,6 +1,6 @@
 # Working with users
 
-The authentication module provides conventient ways to work with your authenticated users and their related profile data.
+The authentication module provides convenient ways to work with your authenticated users and their related profile data.
 
 ## Authenticated users
 
@@ -40,6 +40,30 @@ await AuthServices.instance.userProfiles.changeFullName(session, authUserId, 'my
 
 For the full list of operations, see the [UserProfiles](https://pub.dev/documentation/serverpod_auth_core_server/latest/serverpod_auth_core_server/UserProfiles-class.html) class documentation.
 
+### Setting a default user image
+
+When logging in from some providers, the user image is automatically fetched and set as the user's profile picture - such as with Google Sign In. However, when an image is not found or the provider does not expose the picture, it is possible to set a default user image using the `UserProfileConfig` object.
+
+```dart
+  pod.initializeAuthServices(
+    userProfileConfig: UserProfileConfig(
+      // NOTE: The `userImageGenerator` parameter is optional and defaults to
+      // the value below - which generates Gmail-style images. You can change
+      // this parameter to generate any kind of placeholder image. The function
+      // will be called when invoking the `setDefaultUserImage` method.
+      userImageGenerator: defaultUserImageGenerator,
+      onAfterUserProfileCreated:
+          (session, userProfile, {required transaction}) async {
+            await AuthServices.instance.userProfiles.setDefaultUserImage(
+              session,
+              userProfile.authUserId,
+              transaction: transaction,
+            );
+          },
+    ),
+  ...
+  );
+```
 
 ## Attaching additional information
 
@@ -59,6 +83,11 @@ indexes:
     unique: true
 ```
 
+:::tip
+When referencing module classes in your model files, you can use a nickname for the module instead of the full module name. See the [modules documentation](../modules) for more information.
+:::
+
+
 The model above creates a relation to the `AuthUser` table and ensures that each user can only have one `MyDomainData` object. The `onDelete=Cascade` ensures that when the `AuthUser` is deleted, the `MyDomainData` object is also deleted.
 
 This makes it easy to query the additional information later based on the user's `authId`.