feat(core): explicit double-submit validation via doubleSubmitToken

docs/src/content/docs/(core)/api-reference/server/api/refreshUserInfo.mdx

@@ -24,11 +24,12 @@ const output = await api.refreshUserInfo("github", {
 
 ### RefreshUserInfoAPIOptions
 
-| Option        | Type      | Default   | Description                                               |
-| ------------- | --------- | --------- | --------------------------------------------------------- |
-| request       | `Request` | undefined | The request object from the server-side context.          |
-| headers       | `Headers` | undefined | The headers object from the server-side context.          |
-| skipCSRFCheck | `boolean` | `false`   | Whether to skip CSRF token verification for this request. |
+| Option            | Type      | Default   | Description                                                                                                   |
+| ----------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| request           | `Request` | undefined | The request object from the server-side context.                                                              |
+| headers           | `Headers` | undefined | The headers object from the server-side context.                                                              |
+| ~~skipCSRFCheck~~ | `boolean` | `false`   | ~~Deprecated~~. This option has been replaced by `doubleSubmitToken` and will be removed in a future release. |
+| doubleSubmitToken | `string`  | undefined | Optional CSRF token used to explicitly enable Double-Submit Cookie validation for server-side API functions.  |
 
 <Callout type="info">
   At least one of `request` or `headers` is required to construct the incoming URL and validate redirect URLs.
@@ -43,7 +44,15 @@ const output = await api.refreshUserInfo("github", {
 ## Behavior
 
 - The method uses the provider's existing access token to call its `userInfo` endpoint, then normalizes the response through the provider's `profile` function into a `User` object, and returns the updated session.
-- CSRF protection is verified by default. Set `skipCSRFCheck: true` only if you're enforcing CSRF protection at a different layer (e.g. a framework-level middleware) — disabling it here without an equivalent safeguard reintroduces the vulnerability it protects against.
+- The `doubleSubmitToken` option enables Double-Submit Cookie validation when calling Aura Auth server-side API functions. By default, API functions execute in a trusted server environment, where browser-based CSRF attacks are not possible because requests originate from server-side code rather than from a user's browser. For that reason, Aura Auth performs the standard CSRF validation but skips the additional Double-Submit Cookie verification.
+
+  This option is intended for advanced scenarios where server-side requests should enforce the same CSRF guarantees as browser-initiated requests.
+
+  <Callout>
+    Providing `doubleSubmitToken` does not replace or disable CSRF protection. It enables the additional Double-Submit Cookie
+    validation on top of the standard CSRF checks already performed by Aura Auth.
+  </Callout>
+
 - If the refresh fails (invalid or expired access token, or the provider request fails), `session` resolves to `null` and `success` is `false`.
 
 ## Usage
@@ -81,8 +90,22 @@ console.log("refreshed session:", session)
 ```ts title="skip-csrf.ts" lineNumbers
 import { api } from "@/lib/auth"
 
+const { success, session } = await api.refreshUserInfo("github", {
+  headers: {
+    "x-csrf-token": getCSRFTokenFromRequest(),
+  },
+  request: getRequest(),
+  skipCSRFCheck: false,
+})
+```
+
+### Enable Double-Submit Cookie CSRF protection
+
+```ts title="double-submit.ts" lineNumbers
+import { api } from "@/lib/auth"
+
 const { success, session } = await api.refreshUserInfo("github", {
   request: getRequest(),
-  skipCSRFCheck: true, // only if enforced elsewhere — see the warning above
+  doubleSubmitToken: getDoubleSubmitTokenFromRequest(),
 })
 ```

docs/src/content/docs/(core)/api-reference/server/api/revokeToken.mdx

@@ -35,11 +35,12 @@ const output = await api.revokeToken("github", {
 
 ### RevokeTokenAPIOptions
 
-| Option        | Type      | Default   | Description                                               |
-| ------------- | --------- | --------- | --------------------------------------------------------- |
-| request       | `Request` | undefined | The request object from the server-side context.          |
-| headers       | `Headers` | undefined | The headers object from the server-side context.          |
-| skipCSRFCheck | `boolean` | `false`   | Whether to skip CSRF token verification for this request. |
+| Option            | Type      | Default   | Description                                                                                                   |
+| ----------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| request           | `Request` | undefined | The request object from the server-side context.                                                              |
+| headers           | `Headers` | undefined | The headers object from the server-side context.                                                              |
+| ~~skipCSRFCheck~~ | `boolean` | `false`   | ~~Deprecated~~. This option has been replaced by `doubleSubmitToken` and will be removed in a future release. |
+| doubleSubmitToken | `string`  | undefined | Optional CSRF token used to explicitly enable Double-Submit Cookie validation for server-side API functions.  |
 
 <Callout type="info">
   At least one of `request` or `headers` is required to construct the incoming URL and validate redirect URLs.
@@ -54,7 +55,15 @@ const output = await api.revokeToken("github", {
 ## Behavior
 
 - Revocation success depends entirely on the provider's `revokeToken` endpoint configuration and whether the provider supports token revocation at all. If it doesn't, this method returns `success: false`.
-- CSRF protection is verified by default. Set `skipCSRFCheck: true` only if you're enforcing CSRF protection at a different layer (e.g. a framework-level middleware) — disabling it here without an equivalent safeguard reintroduces the vulnerability it protects against.
+- The `doubleSubmitToken` option enables Double-Submit Cookie validation when calling Aura Auth server-side API functions. By default, API functions execute in a trusted server environment, where browser-based CSRF attacks are not possible because requests originate from server-side code rather than from a user's browser. For that reason, Aura Auth performs the standard CSRF validation but skips the additional Double-Submit Cookie verification.
+
+  This option is intended for advanced scenarios where server-side requests should enforce the same CSRF guarantees as browser-initiated requests.
+
+  <Callout>
+    Providing `doubleSubmitToken` does not replace or disable CSRF protection. It enables the additional Double-Submit Cookie
+    validation on top of the standard CSRF checks already performed by Aura Auth.
+  </Callout>
+
 - If revocation fails (no active token for the provider, or the provider rejects the request), `success` is `false`.
 
 ## Usage
@@ -88,8 +97,22 @@ if (!success) {
 ```ts title="skip-csrf.ts" lineNumbers
 import { api } from "@/lib/auth"
 
+const { success } = await api.revokeToken("github", {
+  headers: {
+    "x-csrf-token": getCSRFTokenFromRequest(),
+  },
+  request: getRequest(),
+  skipCSRFCheck: false, // only if enforced elsewhere — see the warning above
+})
+```
+
+### Enable Double-Submit Cookie CSRF protection
+
+```ts title="double-submit.ts" lineNumbers
+import { api } from "@/lib/auth"
+
 const { success } = await api.revokeToken("github", {
   request: getRequest(),
-  skipCSRFCheck: true, // only if enforced elsewhere — see the warning above
+  doubleSubmitToken: getDoubleSubmitTokenFromRequest(),
 })
 ```

docs/src/content/docs/(core)/api-reference/server/api/signInCredentials.mdx

@@ -28,14 +28,15 @@ const output = await api.signInCredentials({
 
 ### SignInCredentialsAPIOptions
 
-| Option        | Type                 | Default   | Description                                                                                         |
-| ------------- | -------------------- | --------- | --------------------------------------------------------------------------------------------------- |
-| payload       | `CredentialsPayload` | —         | The credentials for the sign-in attempt. Required — without it there's nothing to authenticate.     |
-| request       | `Request`            | undefined | The request object from the server-side context.                                                    |
-| headers       | `Headers`            | undefined | The headers object from the server-side context.                                                    |
-| redirect      | `boolean`            | `true`    | Whether to redirect via the `Location` header (`true`) or return the result as an object (`false`). |
-| redirectTo    | `string`             | undefined | The URL to redirect to after a successful sign-in.                                                  |
-| skipCSRFCheck | `boolean`            | `false`   | Whether to skip CSRF token verification for this request.                                           |
+| Option            | Type                 | Default   | Description                                                                                                   |
+| ----------------- | -------------------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| payload           | `CredentialsPayload` | —         | The credentials for the sign-in attempt. Required — without it there's nothing to authenticate.               |
+| request           | `Request`            | undefined | The request object from the server-side context.                                                              |
+| headers           | `Headers`            | undefined | The headers object from the server-side context.                                                              |
+| redirect          | `boolean`            | `true`    | Whether to redirect via the `Location` header (`true`) or return the result as an object (`false`).           |
+| redirectTo        | `string`             | undefined | The URL to redirect to after a successful sign-in.                                                            |
+| ~~skipCSRFCheck~~ | `boolean`            | `false`   | ~~Deprecated~~. This option has been replaced by `doubleSubmitToken` and will be removed in a future release. |
+| doubleSubmitToken | `string`             | undefined | Optional CSRF token used to explicitly enable Double-Submit Cookie validation for server-side API functions.  |
 
 <Callout type="info">
   At least one of `request` or `headers` is required to construct the incoming URL and validate redirect URLs.
@@ -50,7 +51,15 @@ const output = await api.signInCredentials({
 ## Behavior
 
 - Sign-in success depends entirely on your configured [`credentials.authorize`](/docs/api-reference/server/createAuth#credentials) function, which validates the submitted credentials and returns the `User` object (or `null` if invalid).
-- CSRF protection is verified by default. Set `skipCSRFCheck: true` only if you're enforcing CSRF protection at a different layer (e.g. a framework-level middleware) — disabling it here without an equivalent safeguard reintroduces the vulnerability it protects against.
+- The `doubleSubmitToken` option enables Double-Submit Cookie validation when calling Aura Auth server-side API functions. By default, API functions execute in a trusted server environment, where browser-based CSRF attacks are not possible because requests originate from server-side code rather than from a user's browser. For that reason, Aura Auth performs the standard CSRF validation but skips the additional Double-Submit Cookie verification.
+
+  This option is intended for advanced scenarios where server-side requests should enforce the same CSRF guarantees as browser-initiated requests.
+
+  <Callout>
+    Providing `doubleSubmitToken` does not replace or disable CSRF protection. It enables the additional Double-Submit Cookie
+    validation on top of the standard CSRF checks already performed by Aura Auth.
+  </Callout>
+
 - The return value depends on the `redirect` option:
   - **`redirect: true`** (default) — redirects to `redirectTo` (or the default post-login URL) via the `Location` header.
   - **`redirect: false`** — resolves to an object with `redirectURL`, `redirect: false`, and `success`, letting you handle navigation yourself.
@@ -117,9 +126,9 @@ if (output.success) {
 }
 ```
 
-### Delegating CSRF protection to a different layer
+### Enable Double-Submit Cookie CSRF protection
 
-```ts title="skip-csrf.ts" lineNumbers
+```ts title="double-submit.ts" lineNumbers
 import { api } from "@/lib/auth"
 
 const output = await api.signInCredentials({
@@ -128,6 +137,6 @@ const output = await api.signInCredentials({
     password: "password",
   },
   request: getRequest(),
-  skipCSRFCheck: true, // only if enforced elsewhere — see the warning above
+  doubleSubmitToken: getDoubleSubmitTokenFromRequest(),
 })
 ```

docs/src/content/docs/(core)/api-reference/server/api/signOut.mdx

@@ -24,19 +24,14 @@ const output = await api.signOut({
 
 ### SignOutAPIOptions
 
-| Option        | Type      | Default   | Description                                                                                         |
-| ------------- | --------- | --------- | --------------------------------------------------------------------------------------------------- |
-| request       | `Request` | undefined | The request object from the server-side context.                                                    |
-| headers       | `Headers` | undefined | The headers object from the server-side context.                                                    |
-| redirect      | `boolean` | `true`    | Whether to redirect via the `Location` header (`true`) or return the result as an object (`false`). |
-| redirectTo    | `string`  | undefined | The URL to redirect to after sign-out completes.                                                    |
-| skipCSRFCheck | `boolean` | `false`   | Whether to skip CSRF token verification for this request. See the [warning](#behavior) below.       |
-
-<Callout type="info">
-  At least one of `request` or `headers` is required to construct the incoming URL and validate redirect URLs. Per the [`POST
-  /auth/signOut` handler](/docs/api-reference/server/handlers#post-authsignout), a valid CSRF token must also be present (as a
-  cookie and, at the HTTP layer, the `X-CSRF-Token` header) unless `skipCSRFCheck` is set.
-</Callout>
+| Option            | Type      | Default   | Description                                                                                                   |
+| ----------------- | --------- | --------- | ------------------------------------------------------------------------------------------------------------- |
+| request           | `Request` | undefined | The request object from the server-side context.                                                              |
+| headers           | `Headers` | undefined | The headers object from the server-side context.                                                              |
+| redirect          | `boolean` | `true`    | Whether to redirect via the `Location` header (`true`) or return the result as an object (`false`).           |
+| redirectTo        | `string`  | undefined | The URL to redirect to after sign-out completes.                                                              |
+| ~~skipCSRFCheck~~ | `boolean` | `false`   | ~~Deprecated~~. This option has been replaced by `doubleSubmitToken` and will be removed in a future release. |
+| doubleSubmitToken | `string`  | undefined | Optional CSRF token used to explicitly enable Double-Submit Cookie validation for server-side API functions.  |
 
 ### Returns
 
@@ -46,7 +41,15 @@ const output = await api.signOut({
 
 ## Behavior
 
-- CSRF protection is verified by default, matching the [`signOut` HTTP handler](/docs/api-reference/server/handlers#post-authsignout)'s double-submit cookie check. Set `skipCSRFCheck: true` only if CSRF is enforced at a different layer.
+- The `doubleSubmitToken` option enables Double-Submit Cookie validation when calling Aura Auth server-side API functions. By default, API functions execute in a trusted server environment, where browser-based CSRF attacks are not possible because requests originate from server-side code rather than from a user's browser. For that reason, Aura Auth performs the standard CSRF validation but skips the additional Double-Submit Cookie verification.
+
+  This option is intended for advanced scenarios where server-side requests should enforce the same CSRF guarantees as browser-initiated requests.
+
+  <Callout>
+    Providing `doubleSubmitToken` does not replace or disable CSRF protection. It enables the additional Double-Submit Cookie
+    validation on top of the standard CSRF checks already performed by Aura Auth.
+  </Callout>
+
 - The return value depends on the `redirect` option:
   - **`redirect: true`** (default) — redirects to `redirectTo` (or the default post-sign-out URL) via the `Location` header.
   - **`redirect: false`** — resolves to an object with `redirectURL`, `redirect: false`, and `success`, letting you handle navigation yourself.
@@ -79,3 +82,15 @@ if (output.success) {
   redirect(output.redirectURL)
 }
 ```
+
+### Enable Double-Submit Cookie CSRF protection
+
+```ts title="double-submit.ts" lineNumbers
+import { api } from "@/lib/auth"
+
+const output = await api.signOut({
+  headers: getHeaders(),
+  redirectTo: "/login",
+  doubleSubmitToken: getDoubleSubmitTokenFromRequest(),
+})
+```