@warlock.js/auth 5.15.0 → 5.17.0

package/skills/handle-login-and-logout/SKILL.md

@@ -1,165 +1,179 @@
----
-name: handle-login-and-logout
-description: 'Run the full login flow via authService.login(Model, credentials, deviceInfo?) — verify password, create access + refresh token pair, fire events. Logout via authService.logout(user, accessToken?, refreshToken?) revokes tokens. Triggers: `authService.login`, `authService.logout`, `authService.attemptLogin`, `authService.refreshTokens`, `authService.revokeAllTokens`, `authEvents`; "build a login endpoint", "POST /login controller", "logout from all devices", "verify credentials and issue tokens"; typical import `import { authService, authEvents } from "@warlock.js/auth"`. Skip: token internals — `@warlock.js/auth/manage-tokens/SKILL.md`; sign-up — `@warlock.js/auth/register-user/SKILL.md`; competing libs `passport-local`, `next-auth` credentials.'
----
-
-# Login + logout
-
-`authService` exposes the full flow. Pass the model class so the service knows which user-type to look up.
-
-## Login — `authService.login(Model, credentials, deviceInfo?)`
-
-```ts
-import { authService } from "@warlock.js/auth";
-import { type RequestHandler } from "@warlock.js/core";
-import { User } from "@/app/users/models/user.model";
-
-export const loginController: RequestHandler = async ({ request, response }) => {
-  const result = await authService.login(User, {
-    email: request.input("email"),
-    password: request.input("password"),
-  }, {
-    userAgent: request.header("user-agent"),
-    ip: request.ip,
-  });
-
-  if (!result) {
-    return response.unauthorized({ error: "Invalid credentials" });
-  }
-
-  return response.success({
-    user: result.user,
-    tokens: result.tokens,
-  });
-};
-```
-
-The returned shape:
-
-```ts
-{
-  user: T,                    // your User subclass, hydrated
-  tokens: {
-    accessToken: { token: string, expiresAt: string },
-    refreshToken?: { token: string, expiresAt: string },   // omitted if refresh tokens disabled
-  },
-}
-```
-
-Returns `null` on failure (wrong password, user not found). The service emits `login.attempt` → `login.success` or `login.failed` events as it goes — subscribe via the auth event bus if you need an audit trail.
-
-## What `credentials` looks like
-
-The shape is **arbitrary** — every key except `password` is used as a `where(...)` filter against the model. The password is verified separately via bcrypt.
-
-```ts
-// Email + password
-authService.login(User, { email: "ada@example.com", password: "..." });
-
-// Username + password
-authService.login(User, { username: "ada", password: "..." });
-
-// Phone-based OTP (where password is the OTP hash)
-authService.login(User, { phone: "+1...", password: hashedOTP });
-```
-
-For lower-level credential verification (just check, don't issue tokens), use `authService.attemptLogin(Model, credentials)` — returns the user or null without creating tokens.
-
-## Device info
-
-The optional `deviceInfo` carries metadata into the refresh token row:
-
-```ts
-authService.login(User, credentials, {
-  userAgent: request.header("user-agent"),
-  ip: request.ip,
-  deviceId: "...",          // your client-side device fingerprint
-  familyId: "...",          // pre-existing family for token rotation, usually omitted
-});
-```
-
-Useful for "show active sessions" UIs — see `authService.getActiveSessions(user)`.
-
-## Logout — `authService.logout(user, accessToken?, refreshToken?)`
-
-```ts
-import { type RequestHandler } from "@warlock.js/core";
-
-export const logoutController: RequestHandler = async ({ request, response }) => {
-  await authService.logout(
-    request.locals.user!,
-    request.authorizationValue,        // access token from the Authorization header
-    request.input("refreshToken"),     // refresh token from the request body
-  );
-
-  return response.success({ message: "Logged out" });
-};
-```
-
-The contract:
-- **Pass the access token** → that specific access-token row is deleted.
-- **Pass the refresh token** → that specific refresh-token row is revoked.
-- **Omit refresh token** → behavior depends on `config.auth.refreshToken.logoutWithoutToken`:
-  - `"revoke-all"` (default) — every refresh token for this user is revoked. Fail-safe.
-  - `"error"` — throws. Force the client to send the refresh token.
-
-The `revoke-all` default is the right call for most apps. If a client loses track of the refresh token, logout still works and the user has to log in fresh on every device.
-
-## Logout-everywhere
-
-```ts
-await authService.revokeAllTokens(user);
-// Revokes every refresh token + deletes every access token for this user.
-```
-
-Useful for "logout from all devices" buttons. Fires `token.revoked` per token + `logout.all` once.
-
-## Refresh tokens — `authService.refreshTokens(refreshTokenString, deviceInfo?)`
-
-```ts
-import { type RequestHandler } from "@warlock.js/core";
-
-export const refreshController: RequestHandler = async ({ request, response }) => {
-  const tokens = await authService.refreshTokens(
-    request.input("refreshToken"),
-    { userAgent: request.header("user-agent"), ip: request.ip },
-  );
-
-  if (!tokens) {
-    return response.unauthorized({ error: "Invalid refresh token" });
-  }
-
-  return response.success({ tokens });
-};
-```
-
-Returns a new token pair or `null` (token expired, revoked, or replay-detected). With rotation enabled (default), the old refresh token is consumed; the new pair stays in the same "family." Replay → revoke the whole family. See [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md).
-
-## Auth events
-
-`authEvents` is a type-safe event bus (over `@mongez/events`) that fires on every meaningful auth moment. Subscribe with `on` / `subscribe`, unsubscribe with `off` / `unsubscribeAll`:
-
-```ts
-import { authEvents } from "@warlock.js/auth";
-
-authEvents.on("login.success", (user, tokens, deviceInfo) => { /* audit */ });
-authEvents.on("login.failed",  (credentials, reason) => { /* alert on brute force */ });
-authEvents.on("logout",        (user) => { /* clear server-side session, if any */ });
-authEvents.on("token.refreshed", (user, newPair, oldToken) => { /* track rotation */ });
-authEvents.on("cleanup.completed", (count) => { /* metrics */ });
-```
-
-Full event list: `login.attempt`, `login.success`, `login.failed`, `logout`, `logout.all`, `logout.failsafe`, `token.created`, `token.refreshed`, `token.revoked`, `token.expired`, `token.familyRevoked`, `session.created`, `session.destroyed`, `cleanup.completed`.
-
-## Things NOT to do
-
-- Don't `authService.login(User, { password })` without other credentials — the password is the secret; the other fields are the lookup. A login with only a password is a logic bug.
-- Don't return the password hash in the response. `static toJsonColumns` on the User model should explicitly exclude it.
-- Don't store the refresh token in localStorage. Use an httpOnly secure cookie for refresh tokens; the access token can sit in memory.
-- Don't issue a new token pair without revoking the old one when rotation is enabled. `refreshTokens` does this for you — don't bypass it.
-
-## See also
-
-- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — token lifecycle, rotation, family revocation
-- [`@warlock.js/auth/register-user/SKILL.md`](@warlock.js/auth/register-user/SKILL.md) — sign-up that issues tokens after creation
-- [`@warlock.js/auth/protect-routes/SKILL.md`](@warlock.js/auth/protect-routes/SKILL.md) — where the access token gets consumed
+---
+name: handle-login-and-logout
+description: 'Run the full login flow via authService.login(Model, credentials, deviceInfo?) — verify password, create access + refresh token pair, fire events. Logout via authService.logout(user, accessToken?, refreshToken?) revokes tokens. Triggers: `authService.login`, `authService.logout`, `authService.attemptLogin`, `authService.refreshTokens`, `authService.revokeAllTokens`, `authEvents`; "build a login endpoint", "POST /login controller", "logout from all devices", "verify credentials and issue tokens"; typical import `import { authService, authEvents } from "@warlock.js/auth"`. Skip: token internals — `@warlock.js/auth/manage-tokens/SKILL.md`; sign-up — `@warlock.js/auth/register-user/SKILL.md`; competing libs `passport-local`, `next-auth` credentials.'
+---
+
+# Login + logout
+
+`authService` exposes the full flow. Pass the model class so the service knows which user-type to look up.
+
+```ts title="src/app/users/models/user/user.model.ts"
+import { Auth } from "@warlock.js/auth";
+import { RegisterModel } from "@warlock.js/cascade";
+
+@RegisterModel()
+export class User extends Auth {
+  public static table = "users";
+
+  public get userType(): string {
+    return "user";
+  }
+}
+```
+
+## Login — `authService.login(Model, credentials, deviceInfo?)`
+
+```ts
+import { authService } from "@warlock.js/auth";
+import { type RequestHandler } from "@warlock.js/core";
+import { User } from "app/users/models/user/user.model";
+
+export const loginController: RequestHandler = async ({ request, response }) => {
+  const result = await authService.login(User, {
+    email: request.input("email"),
+    password: request.input("password"),
+  }, {
+    userAgent: request.header("user-agent"),
+    ip: request.ip,
+  });
+
+  if (!result) {
+    return response.unauthorized({ error: "Invalid credentials" });
+  }
+
+  return response.success({
+    user: result.user,
+    tokens: result.tokens,
+  });
+};
+```
+
+The returned shape:
+
+```ts
+{
+  user: T,                    // your User subclass, hydrated
+  tokens: {
+    accessToken: { token: string, expiresAt: string },
+    refreshToken?: { token: string, expiresAt: string },   // omitted if refresh tokens disabled
+  },
+}
+```
+
+Returns `null` on failure (wrong password, user not found). The service emits `login.attempt` → `login.success` or `login.failed` events as it goes — subscribe via the auth event bus if you need an audit trail.
+
+## What `credentials` looks like
+
+The shape is **arbitrary** — every key except `password` is used as a `where(...)` filter against the model. The password is verified separately via bcrypt.
+
+```ts
+// Email + password
+authService.login(User, { email: "ada@example.com", password: "..." });
+
+// Username + password
+authService.login(User, { username: "ada", password: "..." });
+
+// Phone-based OTP (where password is the OTP hash)
+authService.login(User, { phone: "+1...", password: hashedOTP });
+```
+
+For lower-level credential verification (just check, don't issue tokens), use `authService.attemptLogin(Model, credentials)` — returns the user or null without creating tokens.
+
+## Device info
+
+The optional `deviceInfo` carries metadata into the refresh token row:
+
+```ts
+authService.login(User, credentials, {
+  userAgent: request.header("user-agent"),
+  ip: request.ip,
+  deviceId: "...",          // your client-side device fingerprint
+  familyId: "...",          // pre-existing family for token rotation, usually omitted
+});
+```
+
+Useful for "show active sessions" UIs — see `authService.getActiveSessions(user)`.
+
+## Logout — `authService.logout(user, accessToken?, refreshToken?)`
+
+```ts
+import { type RequestHandler } from "@warlock.js/core";
+
+export const logoutController: RequestHandler = async ({ request, response }) => {
+  await authService.logout(
+    request.locals.user!,
+    request.authorizationValue,        // access token from the Authorization header
+    request.input("refreshToken"),     // refresh token from the request body
+  );
+
+  return response.success({ message: "Logged out" });
+};
+```
+
+The contract:
+- **Pass the access token** → that specific access-token row is deleted.
+- **Pass the refresh token** → that specific refresh-token row is revoked.
+- **Omit refresh token** → behavior depends on `config.auth.refreshToken.logoutWithoutToken`:
+  - `"revoke-all"` (default) — every refresh token for this user is revoked. Fail-safe.
+  - `"error"` — throws. Force the client to send the refresh token.
+
+The `revoke-all` default is the right call for most apps. If a client loses track of the refresh token, logout still works and the user has to log in fresh on every device.
+
+## Logout-everywhere
+
+```ts
+await authService.revokeAllTokens(user);
+// Revokes every refresh token + deletes every access token for this user.
+```
+
+Useful for "logout from all devices" buttons. Fires `token.revoked` per token + `logout.all` once.
+
+## Refresh tokens — `authService.refreshTokens(refreshTokenString, deviceInfo?)`
+
+```ts
+import { type RequestHandler } from "@warlock.js/core";
+
+export const refreshController: RequestHandler = async ({ request, response }) => {
+  const tokens = await authService.refreshTokens(
+    request.input("refreshToken"),
+    { userAgent: request.header("user-agent"), ip: request.ip },
+  );
+
+  if (!tokens) {
+    return response.unauthorized({ error: "Invalid refresh token" });
+  }
+
+  return response.success({ tokens });
+};
+```
+
+Returns a new token pair or `null` (token expired, revoked, or replay-detected). With rotation enabled (default), the old refresh token is consumed; the new pair stays in the same "family." Replay → revoke the whole family. See [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md).
+
+## Auth events
+
+`authEvents` is a type-safe event bus (over `@mongez/events`) that fires on every meaningful auth moment. Subscribe with `on` / `subscribe`, unsubscribe with `off` / `unsubscribeAll`:
+
+```ts
+import { authEvents } from "@warlock.js/auth";
+
+authEvents.on("login.success", (user, tokens, deviceInfo) => { /* audit */ });
+authEvents.on("login.failed",  (credentials, reason) => { /* alert on brute force */ });
+authEvents.on("logout",        (user) => { /* clear server-side session, if any */ });
+authEvents.on("token.refreshed", (user, newPair, oldToken) => { /* track rotation */ });
+authEvents.on("cleanup.completed", (count) => { /* metrics */ });
+```
+
+Full event list: `login.attempt`, `login.success`, `login.failed`, `logout`, `logout.all`, `logout.failsafe`, `token.created`, `token.refreshed`, `token.revoked`, `token.expired`, `token.familyRevoked`, `session.created`, `session.destroyed`, `cleanup.completed`.
+
+## Things NOT to do
+
+- Don't `authService.login(User, { password })` without other credentials — the password is the secret; the other fields are the lookup. A login with only a password is a logic bug.
+- Don't return the password hash in the response. `static toJsonColumns` on the User model should explicitly exclude it.
+- Don't store the refresh token in localStorage. Use an httpOnly secure cookie for refresh tokens; the access token can sit in memory.
+- Don't issue a new token pair without revoking the old one when rotation is enabled. `refreshTokens` does this for you — don't bypass it.
+
+## See also
+
+- [`@warlock.js/auth/manage-tokens/SKILL.md`](@warlock.js/auth/manage-tokens/SKILL.md) — token lifecycle, rotation, family revocation
+- [`@warlock.js/auth/register-user/SKILL.md`](@warlock.js/auth/register-user/SKILL.md) — sign-up that issues tokens after creation
+- [`@warlock.js/auth/protect-routes/SKILL.md`](@warlock.js/auth/protect-routes/SKILL.md) — where the access token gets consumed

package/skills/login-with-providers/SKILL.md

@@ -1,9 +1,9 @@
 ---
 name: login-with-providers
-description: 'Log in without a password — Google (OIDC code + PKCE + state + nonce, id_token verified with `jose`), passkeys (WebAuthn via `@simplewebauthn/server`) and phone one-time codes (delivered through a `@warlock.js/notifications` channel). Every method ends in `authService.completeLogin(user)`, the same tokens, rows and events as password login. `startProviderLogin`, `completeProviderLogin`, `generatePasskeyRegistrationOptions`, `verifyPasskeyRegistration`, `generatePasskeyAuthenticationOptions`, `verifyPasskeyAuthentication`, `requestOtp`, `verifyOtp`, `otpRequestThrottleMiddleware`, `otpVerifyThrottleMiddleware`, `AuthProvider`. Triggers: "login with Google", "sign in with Google", "OAuth", "OIDC", "passkeys", "WebAuthn", "passwordless", "SMS code login", "WhatsApp OTP", "phone login", `warlock add auth-google`, `warlock add auth-passkeys`, `AuthProviderSdkMissingError`, `InvalidProviderCallbackError`, `ProviderEmailNotVerifiedError`, `InvalidPasskeyError`, `EC009`, `EC010`, `EC011`, `auth.providers`, `auth.passkeys`, `auth.otp`; typical import `import { completeProviderLogin, verifyOtp } from "@warlock.js/auth"`. Skip: password login — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; email tokens — `@warlock.js/auth/verify-email-and-reset-password/SKILL.md`; defining an SMS channel — `@warlock.js/notifications/define-channel/SKILL.md`.'
+description: 'Log in without a password — Google (OIDC code + PKCE + state + nonce, id_token verified with `jose`), GitHub, Discord, LinkedIn, Apple (`form_post` callback), Facebook and X, passkeys (WebAuthn via `@simplewebauthn/server`) and phone one-time codes (delivered through a `@warlock.js/notifications` channel). Every method ends in `authService.completeLogin(user)`, the same tokens, rows and events as password login. `startProviderLogin`, `completeProviderLogin`, `generatePasskeyRegistrationOptions`, `verifyPasskeyRegistration`, `generatePasskeyAuthenticationOptions`, `verifyPasskeyAuthentication`, `requestOtp`, `verifyOtp`, `otpRequestThrottleMiddleware`, `otpVerifyThrottleMiddleware`, `AuthProvider`. Triggers: "login with Google", "sign in with Google", "login with GitHub", "Sign in with Apple", "login with Discord", "login with LinkedIn", "login with Facebook", "login with X", `auth.providers.github`, "OAuth", "OIDC", "passkeys", "WebAuthn", "passwordless", "SMS code login", "WhatsApp OTP", "phone login", `warlock add auth-google`, `warlock add auth-passkeys`, `AuthProviderSdkMissingError`, `InvalidProviderCallbackError`, `ProviderEmailNotVerifiedError`, `InvalidPasskeyError`, `EC009`, `EC010`, `EC011`, `auth.providers`, `auth.passkeys`, `auth.otp`; typical import `import { completeProviderLogin, verifyOtp } from "@warlock.js/auth"`. Skip: password login — `@warlock.js/auth/handle-login-and-logout/SKILL.md`; email tokens — `@warlock.js/auth/verify-email-and-reset-password/SKILL.md`; defining an SMS channel — `@warlock.js/notifications/define-channel/SKILL.md`.'
 ---
 
-# Login with Google, passkeys, or a phone code
+# Login with an OAuth provider, passkeys, or a phone code
 
 Services only, as with password login: you write the routes. Each `verify`/`complete` call returns the same `LoginResult` as `authService.login`, so the next step is the same too:
 
@@ -19,6 +19,8 @@ authService.setAuthCookie(response, tokens.accessToken); // cookie session, or r
 | Method | Command | Installs |
 | --- | --- | --- |
 | Google | `warlock add auth-google` | `jose` |
+| Apple, LinkedIn | `warlock add auth-google` (or `npm install jose`) — there is no separate `auth-apple` / `auth-linkedin` feature yet | `jose` |
+| GitHub, Discord, Facebook, X | nothing — plain OAuth 2 over `fetch` | nothing |
 | Passkeys | `warlock add auth-passkeys` | `@simplewebauthn/server` (add `@simplewebauthn/browser` to your client bundle) |
 | Phone code | `warlock add notifications` + your own `sms`/`whatsapp` channel | nothing else. Auth ships no SMS/WhatsApp driver |
 
@@ -63,6 +65,133 @@ Client side, the button is just a link. It must be a top-level navigation, not a
 - **Linking.** An existing `provider_accounts` row (provider plus Google `sub`) always decides the user. Without one, the Google email must be verified (`email_verified: true`), or the call throws `ProviderEmailNotVerifiedError` (403, `EC010`) and nothing is linked or created. A verified email links the matching user, or creates one with `{ email, name, emailVerifiedAt: now }`.
 - Other OIDC providers: implement `AuthProvider` (`authorizationUrl(state)`, `handleCallback({ query, expected })`) and register it under `auth.providers.custom.<name>`.
 
+## GitHub, Discord, LinkedIn
+
+Same shape as Google: a config block under `auth.providers.<name>`, a GET
+route that redirects to `startProviderLogin(response, "<name>")`, and a GET
+callback that calls `completeProviderLogin(User, "<name>", request, response)`.
+
+```ts
+// src/config/auth.ts
+providers: {
+  github: {
+    clientId: env("GITHUB_CLIENT_ID"),
+    clientSecret: env("GITHUB_CLIENT_SECRET"),
+    redirectUri: `${env("APP_URL")}/auth/github/callback`,
+    // scopes: ["read:user", "user:email"],
+  },
+  discord: {
+    clientId: env("DISCORD_CLIENT_ID"),
+    clientSecret: env("DISCORD_CLIENT_SECRET"),
+    redirectUri: `${env("APP_URL")}/auth/discord/callback`,
+    // scopes: ["identify", "email"],
+  },
+  linkedin: {
+    clientId: env("LINKEDIN_CLIENT_ID"),
+    clientSecret: env("LINKEDIN_CLIENT_SECRET"),
+    redirectUri: `${env("APP_URL")}/auth/linkedin/callback`,
+    // scopes: ["openid", "profile", "email"],
+  },
+},
+```
+
+- **GitHub** — OAuth 2 + PKCE. `/user.email` is `null` unless public, so the email is read from `/user/emails`: only the address that is both **primary and verified** is used; otherwise the profile has no email and the unverified-email rule applies.
+- **Discord** — OAuth 2 + PKCE; `email` comes from `/users/@me` and counts as verified only when Discord's `verified` flag is `true`.
+- **LinkedIn** — OpenID Connect; the id_token is verified with `jose` against LinkedIn's JWKS (signature, issuer, audience, expiry, nonce). `email_verified` must be the boolean `true`.
+- Provider names resolve by own key only — `auth.providers` inherited keys such as `toString` never resolve as a provider.
+
+## Apple
+
+```ts
+// src/config/auth.ts
+providers: {
+  apple: {
+    clientId: env("APPLE_CLIENT_ID"), // the Services ID
+    teamId: env("APPLE_TEAM_ID"),
+    keyId: env("APPLE_KEY_ID"),
+    privateKey: env("APPLE_PRIVATE_KEY"), // the .p8 file's PKCS8 PEM contents
+    redirectUri: `${env("APP_URL")}/auth/apple/callback`,
+    // scopes: ["name", "email"],
+  },
+},
+```
+
+```ts
+router.get("/auth/apple", async ({ response }) =>
+  response.redirect(await startProviderLogin(response, "apple")),
+);
+
+// Apple POSTs the callback (form_post) when name/email scopes are requested —
+// this route must accept a POST body, not just a query string.
+router.post("/auth/apple/callback", async ({ request, response }) => {
+  const { tokens } = await completeProviderLogin(User, "apple", request, response);
+  authService.setAuthCookie(response, tokens.accessToken);
+  return response.redirect("/");
+});
+```
+
+- Apple has no static client secret: a fresh ES256 JWT (`iss` = team id, `sub` = client id, `aud` = Apple, `kid` = key id) is signed with your `.p8` private key on every callback.
+- The account name arrives only on the **first** authorization, as a `user` form field (`{"name":{"firstName","lastName"}}`) — save it then, since later logins never send it again.
+- The email may be a private-relay address (`@privaterelay.appleid.com`); it is still a real, working address and is accepted like any other.
+- Same rejections and linking rules as Google, through `InvalidProviderCallbackError` / `ProviderEmailNotVerifiedError`.
+- Apple's `form_post` callback is a cross-site POST, so its state cookie is written `SameSite=None; Secure` instead of the usual `Lax` — a browser drops a `Lax` cookie there. `Secure` needs HTTPS: Apple requires it in production anyway, and for local dev you need `https://` or `http://localhost` (browsers treat `localhost` as a secure context even over plain http).
+
+## Facebook
+
+```ts
+providers: {
+  facebook: {
+    clientId: env("FACEBOOK_CLIENT_ID"),
+    clientSecret: env("FACEBOOK_CLIENT_SECRET"),
+    redirectUri: `${env("APP_URL")}/auth/facebook/callback`,
+    // scopes: ["email", "public_profile"],
+  },
+},
+```
+
+```ts
+router.get("/auth/facebook", async ({ response }) =>
+  response.redirect(await startProviderLogin(response, "facebook")),
+);
+
+router.get("/auth/facebook/callback", async ({ request, response }) => {
+  const { tokens } = await completeProviderLogin(User, "facebook", request, response);
+  authService.setAuthCookie(response, tokens.accessToken);
+  return response.redirect("/");
+});
+```
+
+- Plain OAuth 2 (no `id_token`); the profile comes from Graph `/me?fields=id,name,email,picture`. Facebook only ever returns a confirmed address, so a present `email` counts as verified.
+- An app without the `email` permission granted (or a user with none on file) gets no email — the same missing/unverified path as every other provider, never an invented address.
+
+## X (Twitter)
+
+```ts
+providers: {
+  x: {
+    clientId: env("X_CLIENT_ID"),
+    clientSecret: env("X_CLIENT_SECRET"),
+    redirectUri: `${env("APP_URL")}/auth/x/callback`,
+    // scopes: ["tweet.read", "users.read"],
+  },
+},
+```
+
+```ts
+router.get("/auth/x", async ({ response }) =>
+  response.redirect(await startProviderLogin(response, "x")),
+);
+
+router.get("/auth/x/callback", async ({ request, response }) => {
+  const { tokens } = await completeProviderLogin(User, "x", request, response);
+  authService.setAuthCookie(response, tokens.accessToken);
+  return response.redirect("/");
+});
+```
+
+- OAuth 2 with PKCE, plus HTTP Basic auth (`client_id:client_secret`) at the token endpoint for the confidential client — X requires both together.
+- X's `/2/users/me` never returns an email address at all. `email` is always `undefined`; a first login therefore always needs an existing `provider_accounts` link (create one another way first) or it is rejected the same as any missing email — X gives auth no way to invent or infer one.
+
 ## Passkeys
 
 ```ts