@appweaver/create-weaver-app 1.2.1 → 1.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appweaver/create-weaver-app",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "description": "Appweaver - the backend framework for AI-first development (@create-weaver-app)",
   "author": "Luka Matosevic",
   "license": "MIT",
@@ -25,7 +25,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">= 20"
+    "node": ">= 22"
   },
   "scripts": {
     "create-weaver-app": "node ./dist/create-weaver-app.js"

package/skill/SKILL.md

@@ -35,7 +35,7 @@ The basic file structure of the Appweaver project:
 - `test/e2e/` - the end-to-end tests root directory
 - `test/unit/` - the unit tests root directory
 - `.env` - override the central configuration (optional)
-- `.env.{env}` - override the central configuration for specific envirnment (optional)
+- `.env.{env}` - override the central configuration for a specific environment (optional)
 - `appweaver.json` - central library configuration file
 - `appweaver.{env}.json` - environment specific configuration files that override the central configuration
 - `Dockerfile` - the dockerfile used for building a docker image for deploying the application
@@ -414,8 +414,8 @@ await injectService('Post').query({}, 1, 50, {
 
 A hidden, virtual, or array scalar field, a field of a to-many relation, or a relation the action does not include is
 rejected with a `400` error. Sort inputs are typed by `QuerySort<T>` from `@appweaver/common`, with a `<Model>Sort`
-alias emitted per model, and validated over HTTP against a generated `<Model>QuerySort` JSON schema. The default is
-`-createdAt,id`. See [resources.md](./references/resources.md) for the full rules.
+alias emitted per model and validated over HTTP against a generated `<Model>QuerySort` JSON schema. The default is
+`-createdAt,id`.
 
 ### Aggregating
 
@@ -436,9 +436,9 @@ additional queries, skipped for the periods holding no record.
 
 Any other field (string, boolean, enum, JSON, array, hidden, virtual, or a relation), an operator its type does not
 support, an empty selection, or a `dateField` that is not a date field is rejected with a `400` error. Selections are
-typed by `AggregateSelect<T>` from `@appweaver/common`, with a `<Model>Aggregate` alias emitted per model, and
-validated over HTTP against a generated `<Model>AggregateSelect` JSON schema. The response stays untyped JSON, since
-its shape follows the selection.
+typed by `AggregateSelect<T>` from `@appweaver/common`, with a `<Model>Aggregate` alias emitted per model, and validated
+over HTTP against a generated `<Model>AggregateSelect` JSON schema. The response stays untyped JSON, since its shape
+follows the selection.
 
 ### Registering a custom route
 

package/skill/references/client.md

@@ -73,13 +73,18 @@ Reads an OpenAPI v3 schema and generates TypeScript types and a typed client cla
    `@maxLength`, `@minimum`, `@maximum`, `@pattern`, `@format`).
 3. Deduplicates union types and extracts inline schemas to named exported types, including the ones carrying a
    description (i.e. `PostQuerySort`).
-4. Hoists the enums the schema repeats inline into a single shared enum each, so every sortable field of every resource
-   shares one `SortDirection` rather than declaring an `asc | desc` enum of its own.
-5. Classifies all API paths into route groups: resources, auth, account, health, files, and custom.
-6. Emits a typed client class extending `FetchClient<Paths>` with a getter for each route group. Resources with
+4. Hoists the schemas the document repeats inline into a shared definition each, so the generated types declare them
+   once and reference them everywhere else. This covers the enums (every sortable field of every resource shares one
+   `SortDirection` rather than declaring an `asc | desc` enum of its own) and the value a filterable field accepts
+   (`QueryFilterValue`, built from the plain `QueryFilterScalar`), while every property keeps its own description.
+5. Emits every enum as a constant object plus a type alias of its values, so both the member (`SortDirection.asc`) and
+   the plain literal (`'asc'`) are accepted wherever the enum is used. When the types are written to a declaration file
+   (`.d.ts`), the constant is declared rather than initialized, since such a file carries no runtime values.
+6. Classifies all API paths into route groups: resources, auth, account, health, files, and custom.
+7. Emits a typed client class extending `FetchClient<Paths>` with a getter for each route group. Resources with
    unsupported operations are excluded at compile time using `Omit`.
-7. Formats all output with Prettier.
-8. Writes files with an autogenerated header comment.
+8. Formats all output with Prettier.
+9. Writes files with an autogenerated header comment.
 
 **Examples:**
 
@@ -146,6 +151,35 @@ const sort: PostQuerySort = { createdAt: SortDirection.desc, title: SortDirectio
 const posts = await client.post.query({ sort, page: 1, size: 20 });
 ```
 
+Enums are generated as a constant object together with a type alias of its values, so the members and the raw literals
+are interchangeable and no import is needed for the literal form:
+
+```ts
+export const SortDirection = { asc: 'asc', desc: 'desc' } as const;
+export type SortDirection = (typeof SortDirection)[keyof typeof SortDirection];
+
+// Both are valid and equally type safe
+const byMember: PostQuerySort = { createdAt: SortDirection.desc };
+const byLiteral: PostQuerySort = { createdAt: 'desc' };
+```
+
+The value a filterable field accepts is declared once as well, rather than being spelled out again for every field of
+every resource. A scalar field references `QueryFilterValue`, and a relation field adds the filter of the related
+resource to the plain values it accepts:
+
+```ts
+export type QueryFilterScalar = string | number | boolean | null;
+export type QueryFilterValue = QueryFilterScalar | QueryFilterScalar[] | QueryCondition;
+
+export type PostQueryFilter = {
+  /** @description Filter by the title field */
+  title?: QueryFilterValue;
+  /** @description Filter by the author relation, matching an id, a list of ids, or a nested User filter */
+  author?: QueryFilterScalar | QueryFilterScalar[] | UserQueryFilter | UserQueryFilter[];
+  // ...
+};
+```
+
 ### Client file
 
 ```ts

package/skill/references/configuration.md

@@ -256,11 +256,12 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 
 #### OAuth2 general
 
-| Property                               | Type    | Default  | Description                                                                                                                       |
-|----------------------------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `SECURITY_OAUTH2_STATE_TTL`            | integer | `600000` | OAuth2 state parameter TTL in milliseconds (default 10 min).                                                                      |
-| `SECURITY_OAUTH2_REGISTRATION_ENABLED` | boolean | `true`   | Allow registering new users via OAuth2 login. When `false`, only already existing users (matched by email) can log in via OAuth2. |
-| `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED` | boolean | `false`  | Download the user's avatar from the OAuth2 provider during registration and pass it as `avatarFile` to `registrationData`.        |
+| Property                                                 | Type    | Default  | Description                                                                                                                        |
+|----------------------------------------------------------|---------|----------|------------------------------------------------------------------------------------------------------------------------------------|
+| `SECURITY_OAUTH2_STATE_TTL`                              | integer | `600000` | OAuth2 state parameter TTL in milliseconds (default 10 min).                                                                       |
+| `SECURITY_OAUTH2_REGISTRATION_ENABLED`                   | boolean | `true`   | Allow registering new users via OAuth2 login. When `false`, only already existing users (matched by email) can log in via OAuth2.  |
+| `SECURITY_OAUTH2_FETCH_AVATAR_ENABLED`                   | boolean | `false`  | Download the user's avatar from the OAuth2 provider during registration and pass it as `avatarFile` to `registrationData`.         |
+| `SECURITY_OAUTH2_CONNECTED_ACCOUNTS_KEEP_DATABASE_TABLE` | boolean | `false`  | Keep the `ConnectedAccount` table even when every OAuth2 provider is disabled, so the links are not dropped by the next migration. |
 
 #### OAuth2 Google
 
@@ -280,6 +281,72 @@ The config object is frozen with `Object.freeze()` after loading to prevent runt
 | `SECURITY_OAUTH2_FACEBOOK_CLIENT_SECRET` | string? | -                                 | Facebook OAuth2 client secret.   |
 | `SECURITY_OAUTH2_FACEBOOK_USER_INFO_URL` | string  | `'https://graph.facebook.com/me'` | Facebook user info endpoint.     |
 
+#### OAuth2 X (Twitter)
+
+The app must be granted the email permission in the X developer portal, otherwise X refuses to return the
+`confirmed_email` field and every login is rejected.
+
+| Property                          | Type    | Default                          | Description                                                            |
+|-----------------------------------|---------|----------------------------------|------------------------------------------------------------------------|
+| `SECURITY_OAUTH2_X_ENABLED`       | boolean | `false`                          | Enable X OAuth2 provider. The flow always uses PKCE, which X requires. |
+| `SECURITY_OAUTH2_X_CLIENT_ID`     | string? | -                                | X OAuth2 client ID.                                                    |
+| `SECURITY_OAUTH2_X_CLIENT_SECRET` | string? | -                                | X OAuth2 client secret.                                                |
+| `SECURITY_OAUTH2_X_USER_INFO_URL` | string  | `'https://api.x.com/2/users/me'` | X user info endpoint.                                                  |
+
+#### OAuth2 GitHub
+
+| Property                               | Type    | Default                         | Description                    |
+|----------------------------------------|---------|---------------------------------|--------------------------------|
+| `SECURITY_OAUTH2_GITHUB_ENABLED`       | boolean | `false`                         | Enable GitHub OAuth2 provider. |
+| `SECURITY_OAUTH2_GITHUB_CLIENT_ID`     | string? | -                               | GitHub OAuth2 client ID.       |
+| `SECURITY_OAUTH2_GITHUB_CLIENT_SECRET` | string? | -                               | GitHub OAuth2 client secret.   |
+| `SECURITY_OAUTH2_GITHUB_USER_INFO_URL` | string  | `'https://api.github.com/user'` | GitHub user info endpoint.     |
+
+#### OAuth2 GitLab
+
+| Property                               | Type    | Default                            | Description                                                                                 |
+|----------------------------------------|---------|------------------------------------|---------------------------------------------------------------------------------------------|
+| `SECURITY_OAUTH2_GITLAB_ENABLED`       | boolean | `false`                            | Enable GitLab OAuth2 provider.                                                              |
+| `SECURITY_OAUTH2_GITLAB_CLIENT_ID`     | string? | -                                  | GitLab OAuth2 client ID.                                                                    |
+| `SECURITY_OAUTH2_GITLAB_CLIENT_SECRET` | string? | -                                  | GitLab OAuth2 client secret.                                                                |
+| `SECURITY_OAUTH2_GITLAB_BASE_URL`      | string  | `'https://gitlab.com'`             | Instance base URL for the authorize and token endpoints. Change it for self-managed GitLab. |
+| `SECURITY_OAUTH2_GITLAB_USER_INFO_URL` | string  | `'https://gitlab.com/api/v4/user'` | GitLab user info endpoint.                                                                  |
+
+#### OAuth2 LinkedIn
+
+| Property                                 | Type    | Default                                  | Description                      |
+|------------------------------------------|---------|------------------------------------------|----------------------------------|
+| `SECURITY_OAUTH2_LINKEDIN_ENABLED`       | boolean | `false`                                  | Enable LinkedIn OAuth2 provider. |
+| `SECURITY_OAUTH2_LINKEDIN_CLIENT_ID`     | string? | -                                        | LinkedIn OAuth2 client ID.       |
+| `SECURITY_OAUTH2_LINKEDIN_CLIENT_SECRET` | string? | -                                        | LinkedIn OAuth2 client secret.   |
+| `SECURITY_OAUTH2_LINKEDIN_USER_INFO_URL` | string  | `'https://api.linkedin.com/v2/userinfo'` | LinkedIn user info endpoint.     |
+
+#### OAuth2 Apple
+
+Apple expects the client secret to be a short-lived ES256 JWT: either set `SECURITY_OAUTH2_APPLE_CLIENT_SECRET` to one
+you generated yourself, or provide the team ID, key ID and `.p8` private key and let the framework sign one at startup.
+
+| Property                                         | Type    | Default    | Description                                                                                      |
+|--------------------------------------------------|---------|------------|--------------------------------------------------------------------------------------------------|
+| `SECURITY_OAUTH2_APPLE_ENABLED`                  | boolean | `false`    | Enable Apple OAuth2 provider.                                                                    |
+| `SECURITY_OAUTH2_APPLE_CLIENT_ID`                | string? | -          | Apple OAuth2 client ID (the Services ID identifier, e.g. `com.example.service`).                 |
+| `SECURITY_OAUTH2_APPLE_CLIENT_SECRET`            | string? | -          | Pre-generated client secret JWT. Takes precedence over the signing key settings below.           |
+| `SECURITY_OAUTH2_APPLE_TEAM_ID`                  | string? | -          | Apple developer team ID.                                                                         |
+| `SECURITY_OAUTH2_APPLE_KEY_ID`                   | string? | -          | Identifier of the `.p8` signing key.                                                             |
+| `SECURITY_OAUTH2_APPLE_PRIVATE_KEY`              | string? | -          | Contents of the `.p8` private key (PEM). Escaped `\n` sequences are restored.                    |
+| `SECURITY_OAUTH2_APPLE_PRIVATE_KEY_PATH`         | string? | -          | Path to the `.p8` private key file. Used when the inline key is not set.                         |
+| `SECURITY_OAUTH2_APPLE_CLIENT_SECRET_EXPIRES_IN` | integer | `15552000` | Lifetime in seconds of the generated secret. Apple rejects anything above `15777000` (6 months). |
+
+#### OAuth2 Microsoft
+
+| Property                                  | Type    | Default                                 | Description                                                                                              |
+|-------------------------------------------|---------|-----------------------------------------|----------------------------------------------------------------------------------------------------------|
+| `SECURITY_OAUTH2_MICROSOFT_ENABLED`       | boolean | `false`                                 | Enable Microsoft OAuth2 provider.                                                                        |
+| `SECURITY_OAUTH2_MICROSOFT_CLIENT_ID`     | string? | -                                       | Microsoft OAuth2 client ID (the Entra ID application ID).                                                |
+| `SECURITY_OAUTH2_MICROSOFT_CLIENT_SECRET` | string? | -                                       | Microsoft OAuth2 client secret.                                                                          |
+| `SECURITY_OAUTH2_MICROSOFT_TENANT`        | string  | `'common'`                              | Tenant used in the authorize and token endpoints: a tenant ID, `common`, `organizations` or `consumers`. |
+| `SECURITY_OAUTH2_MICROSOFT_USER_INFO_URL` | string  | `'https://graph.microsoft.com/v1.0/me'` | Microsoft Graph user info endpoint.                                                                      |
+
 #### OAuth2 Custom (OpenID Connect)
 
 | Property                               | Type    | Default | Description                                     |

package/skill/references/security.md

@@ -73,7 +73,7 @@ if `SECURITY_JWT_SECRET` is set.
 ```json
 {
   "scope": "auth | refresh | 2fa",
-  "source": "password | oauth2Google | oauth2Facebook | oauth2Custom | apiKey | basic",
+  "source": "password | apiKey | basic | oauth2Google | oauth2Facebook | oauth2X | oauth2Github | oauth2Gitlab | oauth2Linkedin | oauth2Apple | oauth2Microsoft | oauth2Custom",
   "username": "User email (e.g. admin@example.com)",
   "sub": "User ID (e.g. 123)",
   "iat": "Issued at timestamp (e.g. 1774623924234)"
@@ -187,8 +187,8 @@ Default delimiter is `AK`, so a key looks like: `42AKa1b2c3d4e5f6...`
 
 ## OAuth2 authentication
 
-Appweaver supports OAuth2 login with Google, Facebook, and a custom OpenID Connect provider. All OAuth2 providers follow
-the same flow pattern.
+Appweaver supports OAuth2 login with Google, Facebook, X, GitHub, GitLab, LinkedIn, Apple, Microsoft, and a custom
+OpenID Connect provider. All of them are built from the same `createOAuth2Plugin` factory and follow the same flow.
 
 ### OAuth2 flow
 
@@ -217,140 +217,74 @@ the same flow pattern.
 9. Server finds the user by email and invokes the optional checkOAuth2User callback
    (aborts with an error when the callback returns a string or an Error).
    New users are registered unless SECURITY_OAUTH2_REGISTRATION_ENABLED=false
-10. Server generates an authentication OTT
+10. Server generates an authentication OTT, flagging it when the password has to be confirmed
 11. Server redirects to the original URL with the token:
-    -> https://myapp.com/dashboard?token={ott}
-
-12. Client exchanges the OTT for JWT tokens:
-    POST /auth/exchange-token { token: "{ott}" }
+    -> https://myapp.com/dashboard?token={ott}[&passwordRequired=true]
+12. Client exchanges the OTT for JWT tokens, adding the password when it was asked for:
+    POST /auth/exchange-token { token: "{ott}", password: "..." }
     -> { accessToken, refreshToken }
+13. Server records the provider account in the ConnectedAccount table
 ```
 
-### Google OAuth2
-
-**Configuration:**
-
-```json
-{
-  "config": {
-    "security": {
-      "oauth2": {
-        "google": {
-          "enabled": true,
-          "clientId": "your-google-client-id",
-          "clientSecret": "your-google-client-secret"
-        }
-      }
-    }
-  }
-}
-```
-
-Or via environment variables:
-
-```env
-SECURITY_OAUTH2_GOOGLE_ENABLED=true
-SECURITY_OAUTH2_GOOGLE_CLIENT_ID=your-google-client-id
-SECURITY_OAUTH2_GOOGLE_CLIENT_SECRET=your-google-client-secret
-```
-
-**Routes:**
-
-| Method | Path                          | Description                                                              |
-|--------|-------------------------------|--------------------------------------------------------------------------|
-| `GET`  | `/auth/login/google`          | Redirect to Google consent screen. Query: `redirectToUrl`.               |
-| `GET`  | `/auth/login/google/callback` | Google callback. Exchanges code, creates/finds user, redirects with OTT. |
-
-**Scopes**: `profile`, `email`
-
-**User info extracted**: `email`, `given_name` (firstName), `family_name` (lastName), `picture` (avatarUrl)
-
-**Google Cloud Console setup:**
-
-1. Create OAuth 2.0 credentials in the Google Cloud Console
-2. Set the authorized redirect URI to: `{APP_HOSTNAME}{SERVER_API_PREFIX}/auth/login/google/callback`
-   (e.g. `https://api.myapp.com/api/auth/login/google/callback`)
-
-### Facebook OAuth2
-
-**Configuration:**
-
-```json
-{
-  "config": {
-    "security": {
-      "oauth2": {
-        "facebook": {
-          "enabled": true,
-          "clientId": "your-facebook-app-id",
-          "clientSecret": "your-facebook-app-secret"
-        }
-      }
-    }
-  }
-}
-```
-
-Or via environment variables:
-
-```env
-SECURITY_OAUTH2_FACEBOOK_ENABLED=true
-SECURITY_OAUTH2_FACEBOOK_CLIENT_ID=your-facebook-app-id
-SECURITY_OAUTH2_FACEBOOK_CLIENT_SECRET=your-facebook-app-secret
-```
-
-**Routes:**
-
-| Method | Path                            | Description                                                                |
-|--------|---------------------------------|----------------------------------------------------------------------------|
-| `GET`  | `/auth/login/facebook`          | Redirect to Facebook login. Query: `redirectToUrl`.                        |
-| `GET`  | `/auth/login/facebook/callback` | Facebook callback. Exchanges code, creates/finds user, redirects with OTT. |
-
-**Scopes**: `public_profile`, `email`
-
-**User info extracted**: `email`, `name` (split into firstName/lastName), `picture` (avatarUrl)
-
-**Facebook Developer Console setup:**
-
-1. Create an app in the Facebook Developer Console
-2. Add Facebook Login product
-3. Set the valid OAuth redirect URI to: `{APP_HOSTNAME}{SERVER_API_PREFIX}/auth/login/facebook/callback`
-
-### Custom OAuth2 (OpenID Connect)
-
-For any OpenID Connect-compatible provider (Keycloak, Auth0, etc.).
-
-**Configuration:**
-
-```json
-{
-  "config": {
-    "security": {
-      "oauth2": {
-        "custom": {
-          "enabled": true,
-          "clientId": "your-client-id",
-          "clientSecret": "your-client-secret",
-          "issuer": "https://keycloak.example.com/realms/myrealm"
-        }
-      }
-    }
-  }
-}
-```
-
-**Routes:**
-
-| Method | Path                          | Description                                          |
-|--------|-------------------------------|------------------------------------------------------|
-| `GET`  | `/auth/login/custom`          | Redirect to custom provider. Query: `redirectToUrl`. |
-| `GET`  | `/auth/login/custom/callback` | Custom provider callback.                            |
-
-**Scopes**: `openid`, `profile`, `email`
-
-**User info endpoint**: `{issuer}/protocol/openid-connect/userinfo`
-
-**Standard claims expected**: `sub`, `email`, `given_name`, `family_name`, `picture` (optional, avatarUrl)
+### Providers
+
+Every provider is disabled by default and enabled with `SECURITY_OAUTH2_<NAME>_ENABLED` plus `_CLIENT_ID` and
+`_CLIENT_SECRET` (JSON: `security.oauth2.<name>`). Enabling one registers `GET /auth/login/<name>` and
+`/auth/login/<name>/callback`. Register the callback URL `{APP_HOSTNAME}{SERVER_API_PREFIX}/auth/login/<name>/callback`
+with the provider.
+
+| `<name>`    | Scopes                                    | User info source                            |
+|-------------|-------------------------------------------|---------------------------------------------|
+| `google`    | `profile`, `email`                        | `googleapis.com/oauth2/v2/userinfo`         |
+| `facebook`  | `public_profile`, `email`                 | `graph.facebook.com/me`                     |
+| `x`         | `users.read`, `tweet.read`                | `api.x.com/2/users/me`                      |
+| `github`    | `read:user`, `user:email`                 | `api.github.com/user`                       |
+| `gitlab`    | `read_user`                               | `gitlab.com/api/v4/user`                    |
+| `linkedin`  | `openid`, `profile`, `email`              | `api.linkedin.com/v2/userinfo`              |
+| `apple`     | `name`, `email`                           | the `id_token` (no endpoint)                |
+| `microsoft` | `openid`, `profile`, `email`, `User.Read` | `graph.microsoft.com/v1.0/me`               |
+| `custom`    | `openid`, `profile`, `email`              | `{issuer}/protocol/openid-connect/userinfo` |
+
+### Provider anomalies
+
+- **X only releases the email address to approved apps.** The `confirmed_email` field is requested explicitly, but X
+  serves it solely to apps granted the email permission in the developer portal — without it the call fails and the
+  login is rejected with a 403.
+- **Apple's callback is a `POST`** (`response_mode=form_post`), the identity comes from the `id_token`, and the client
+  secret is an ES256 JWT signed at startup from `teamId`/`keyId`/the `.p8` key — expiring after
+  `clientSecretExpiresIn` seconds, so a longer-running process needs a restart. Set `clientSecret` directly to use your
+  own. The name is sent **only on the first authorization**; later logins yield empty `firstName`/`lastName`.
+- **GitHub** falls back to `/user/emails` for the primary-verified address when the profile email is private and rejects
+  accounts with no verified address.
+- **GitLab** self-managed instances need `SECURITY_OAUTH2_GITLAB_BASE_URL` and `_USER_INFO_URL`.
+- **Microsoft** uses `SECURITY_OAUTH2_MICROSOFT_TENANT` (default `common`) in its endpoints, and its Graph photo is an
+  authenticated binary, so it arrives as `avatarFile` instead of `avatarUrl`.
+- **Custom** targets any OpenID Connect provider (Keycloak, Auth0, …) and needs `issuer` instead of preset endpoints.
+
+### Account takeover protection
+
+An OAuth2 sign-in matches an existing user by email, so a provider account carrying someone else's address must not by
+itself unlock a password-protected account. The first time a provider is linked to a user that has a `passwordHash`, the
+redirect carries `&passwordRequired=true` and `POST /auth/exchange-token` rejects the token unless
+`{ token, password }` is sent. The one-time token is spent either way, so a wrong password means restarting the flow.
+
+Confirmation happens once: the pairing is stored in `ConnectedAccount` and later sign-ins pass through. Users without a
+password, and users being registered by the current sign-in, are never asked. There is no flag to switch this off — the
+check only ever fires where skipping it would hand the account over. Without a `ConnectedAccount` table there is nowhere
+to record the confirmation, so the password is asked on every sign-in instead.
+
+A local `verifiedEmail: false` does not block the sign-in — the provider vouches for the address and the password
+confirms the account, which together prove more than local verification would. The address is marked verified once the
+exchange succeeds.
+
+### Connected accounts
+
+`ConnectedAccount` pairs a provider account with a local user: `provider`, `providerAccountId`, `scope`, `lastLoginAt`
+(`createdAt` holds the link date) and a relation to the auth model, indexed on `[provider, providerAccountId]`. A
+provider account belongs to one user only — relinking it elsewhere fails with a 403.
+
+The table exists when any OAuth2 provider is enabled; `SECURITY_OAUTH2_CONNECTED_ACCOUNTS_KEEP_DATABASE_TABLE=true`
+keeps it after disabling OAuth2, like `SECURITY_API_KEY_KEEP_DATABASE_TABLE` does for API keys.
 
 ### OAuth2 registration control and hooks