feat: Add sign in and auto link account to sso

Author: aXenDeveloper

apps/web/content/docs/dev/events/built-in-events.mdx

@@ -38,7 +38,7 @@ core event as for one of your own.
 
 ## Core events (`@vitnode/core`)
 
-Six names, all declared in `VitNodeEvents` in
+Seven names, all declared in `VitNodeEvents` in
 `packages/vitnode/src/api/models/events.ts`. Every one of them fires **after**
 the write it describes has committed.
 
@@ -47,6 +47,7 @@ the write it describes has committed.
 | `user.created` | `{ userId, email, name, emailVerified }` | A user row is inserted - public sign-up, AdminCP creation, or SSO sign-up |
 | `user.updated` | `{ userId, email, name }`                | A user is edited in the AdminCP (profile fields and/or role assignments)  |
 | `user.deleted` | `{ userId, email }`                      | Never - the name is declared for plugins, core has no deletion flow       |
+| `user.sso.linked` | `{ userId, email, providerId }`       | A visitor proves an existing account is theirs with its password and an SSO identity is linked to it |
 | `role.created` | `{ roleId }`                             | A role is created in the AdminCP                                          |
 | `role.updated` | `{ roleId }`                             | A role is edited in the AdminCP                                           |
 | `role.deleted` | `{ roleId }`                             | A role is deleted in the AdminCP                                          |
@@ -74,7 +75,7 @@ AdminCP, and the first sign-in through an [SSO provider](/docs/dev/sso).
     },
     emailVerified: {
       description:
-        'Whether the account starts verified. True for the very first user in an installation (the root account) and whenever no email adapter is configured, because nothing could send a verification mail.',
+        'Whether the account starts verified. True for the very first user in an installation (the root account), whenever no email adapter is configured (nothing could send a verification mail), and for every account created through an SSO provider, which has already verified the address.',
       type: 'boolean',
     },
   }}
@@ -125,6 +126,35 @@ name, name code) and/or role assignments. The payload carries the user's
 list), invalidate a plugin-owned cache keyed by user, or audit-log the staff
 edit using the envelope's `actor`.
 
+</Accordion>
+<Accordion title="user.sso.linked">
+
+Emitted by `SSOModel.link` after the `core_users_sso` row is committed - the
+moment a social identity that arrived with an already-registered email is tied
+to that account. It does not fire on the first sign-in through a provider (that
+is a `user.created`) or on a later sign-in through an identity that is already
+linked.
+
+<TypeTable
+  type={{
+    userId: {
+      description: 'Id of the account the identity was linked to.',
+      type: 'number',
+    },
+    email: {
+      description: "The account's email - the address the provider and the account had in common.",
+      type: 'string',
+    },
+    providerId: {
+      description: "The adapter's id, e.g. 'google' or 'facebook'.",
+      type: 'string',
+    },
+  }}
+/>
+
+**A listener would** notify the account owner that a new sign-in method was
+added, or audit-log the link with the envelope's `actor`.
+
 </Accordion>
 <Accordion title="user.deleted (declared, never emitted)">
 

apps/web/content/docs/dev/sso/custom-adapter.mdx

@@ -66,7 +66,8 @@ export const GitHubSSOApiPlugin = ({
       const emailRes = await fetch("https://api.github.com/user/emails", { headers })
       const emails: Array<{ email: string; primary: boolean; verified: boolean }> =
         await emailRes.json()
-      const primaryEmail = emails.find((e) => e.primary && e.verified)?.email ?? user.email
+      const primaryEmail = emails.find((e) => e.primary && e.verified)?.email
+      if (!primaryEmail) throw new Error("GitHub account has no verified email")
 
       return {
         id: String(user.id),
@@ -134,7 +135,7 @@ A **GitHub** login button automatically renders on `/login` and `/register`, and
       type: "(code: string) => Promise<{ access_token: string; token_type: string }>",
     },
     fetchUser: {
-      description: "Fetches user profile (id, email, username, avatarUrl).",
+      description: "Fetches user profile (id, email, username, avatarUrl). Return only an email the provider has verified - VitNode treats it as confirmed and will mark a matching unconfirmed account verified. The built-in adapters reject unverified addresses with a 400.",
       required: true,
       type: "(token: TokenResponse) => Promise<SSOUser>",
     },

apps/web/content/docs/dev/sso/index.mdx

@@ -81,9 +81,39 @@ For example: `https://your-domain.com/login/sso/google`.
 
 When a user signs in via SSO:
 1. **Known Identity**: The provider account was linked before, so the user is signed straight into it.
-2. **Existing Email Match**: An account already uses that address, so the request is refused with `409`. A social login can never take over an account someone else registered with a password.
+2. **Existing Email Match**: An account already uses that address. The visitor is asked for that account's password; once it checks out, the provider identity is linked to the account and they are signed in. From then on that provider signs them straight in (case 1). A social login can never take over an account on its own - the password is what proves ownership.
 3. **New Visitor**: A new user is created with their social display name, email, and avatar.
 
+### SSO confirms the email
+
+A provider only hands VitNode an address it has verified itself (the built-in
+adapters refuse anything else), so a social sign-in doubles as email
+confirmation:
+
+- a **new visitor** starts out with `emailVerified: true`, even when an email
+  adapter is configured and password sign-ups would have to confirm first;
+- a **known identity** or a **freshly linked** account whose address is still
+  unconfirmed is marked confirmed - provided the address the provider returned
+  is the one on the account. An account whose email was changed since the link
+  was made is left alone.
+
+### Linking an existing account
+
+The callback answers `409` with a short-lived, signed **link offer** - the
+account's email, whether it has a password, and a token good for ten minutes.
+The login page turns that into a "Connect *Provider* to your account" form: the
+email is shown read-only, the visitor types their password, and
+`POST /users/sso/{providerId}/link` verifies both before it writes the
+`core_users_sso` row and mints a session. The token carries the provider account
+id, so nothing about *which* identity gets linked is taken from the browser.
+
+An account created by another provider has no password to confirm with. When an
+email adapter is configured the form offers **Set a password** (the ordinary
+reset flow) and asks them to try the provider again afterwards; without one it
+points back to the login page.
+
+Every successful link emits [`user.sso.linked`](/docs/dev/events/built-in-events).
+
 The address the provider returns is matched in its canonical form, so a Google account that reports `jan.kowalski@gmail.com` finds the member who registered as `jankowalski@gmail.com` instead of quietly becoming a second account. See [One Mailbox, One Account](/docs/dev/advanced/auth#one-mailbox-one-account).
 
 ## Learn More

apps/web/src/lib/auth.ts

@@ -7,11 +7,13 @@ import {
   signOutInputSchema,
   signUpInputSchema,
   ssoCallbackInputSchema,
+  ssoLinkInputSchema,
   ssoStartInputSchema,
 } from '@vitnode/core/tanstack/auth'
 import {
   changePasswordFromResetOnApi,
   completeSsoOnApi,
+  linkSsoOnApi,
   readSessionOnApi,
   requestPasswordResetOnApi,
   signInOnApi,
@@ -40,6 +42,10 @@ export const completeSsoFn = createServerFn({ method: 'POST' })
   .validator(ssoCallbackInputSchema)
   .handler(async ({ data }) => await completeSsoOnApi(data))
 
+export const linkSsoFn = createServerFn({ method: 'POST' })
+  .validator(ssoLinkInputSchema)
+  .handler(async ({ data }) => await linkSsoOnApi(data))
+
 export const signUpFn = createServerFn({ method: 'POST' })
   .validator(signUpInputSchema)
   .handler(async ({ data }) => await signUpOnApi(data))
@@ -56,6 +62,7 @@ setAuthTransport({
   changePasswordFromReset: async (input) =>
     await changePasswordFromResetFn({ data: input }),
   completeSso: async (input) => await completeSsoFn({ data: input }),
+  linkSso: async (input) => await linkSsoFn({ data: input }),
   readSession: async () => await readSessionFn(),
   requestPasswordReset: async (input) =>
     await requestPasswordResetFn({ data: input }),

packages/create-vitnode-app/copy-of-vitnode-app/root/src/lib/auth.ts

@@ -7,11 +7,13 @@ import {
   signOutInputSchema,
   signUpInputSchema,
   ssoCallbackInputSchema,
+  ssoLinkInputSchema,
   ssoStartInputSchema,
 } from "@vitnode/core/tanstack/auth";
 import {
   changePasswordFromResetOnApi,
   completeSsoOnApi,
+  linkSsoOnApi,
   readSessionOnApi,
   requestPasswordResetOnApi,
   signInOnApi,
@@ -40,6 +42,10 @@ export const completeSsoFn = createServerFn({ method: "POST" })
   .validator(ssoCallbackInputSchema)
   .handler(async ({ data }) => await completeSsoOnApi(data));
 
+export const linkSsoFn = createServerFn({ method: "POST" })
+  .validator(ssoLinkInputSchema)
+  .handler(async ({ data }) => await linkSsoOnApi(data));
+
 export const signUpFn = createServerFn({ method: "POST" })
   .validator(signUpInputSchema)
   .handler(async ({ data }) => await signUpOnApi(data));
@@ -56,6 +62,7 @@ setAuthTransport({
   changePasswordFromReset: async input =>
     await changePasswordFromResetFn({ data: input }),
   completeSso: async input => await completeSsoFn({ data: input }),
+  linkSso: async input => await linkSsoFn({ data: input }),
   readSession: async () => await readSessionFn(),
   requestPasswordReset: async input =>
     await requestPasswordResetFn({ data: input }),

packages/vitnode/src/api/lib/server-secret.ts

@@ -0,0 +1,66 @@
+import type { Context } from "hono";
+
+import { eq } from "drizzle-orm";
+import crypto from "node:crypto";
+
+import { core_secrets } from "@/database/secrets";
+
+type SecretsDatabase = Omit<Context["var"]["db"], "$client">;
+
+const KEY_BYTES = 32;
+
+const generate = (): string => crypto.randomBytes(KEY_BYTES).toString("base64");
+
+const read = async (
+  db: SecretsDatabase,
+  name: string,
+): Promise<string | undefined> => {
+  const [row] = await db
+    .select({ value: core_secrets.value })
+    .from(core_secrets)
+    .where(eq(core_secrets.name, name))
+    .limit(1);
+
+  return row?.value;
+};
+
+const readOrCreate = async (
+  db: SecretsDatabase,
+  name: string,
+): Promise<string> => {
+  const existing = await read(db, name);
+  if (existing !== undefined) return existing;
+
+  const [inserted] = await db
+    .insert(core_secrets)
+    .values({ name, value: generate() })
+    .onConflictDoNothing()
+    .returning({ value: core_secrets.value });
+  if (inserted) return inserted.value;
+
+  const winner = await read(db, name);
+  if (winner !== undefined) return winner;
+
+  throw new Error(`Could not read or create the "${name}" server secret.`);
+};
+
+const cached = new Map<string, Promise<string>>();
+
+export const ensureServerSecret = async (
+  db: SecretsDatabase,
+  name: string,
+): Promise<string> => {
+  const pending =
+    cached.get(name) ??
+    readOrCreate(db, name).catch((error: unknown) => {
+      cached.delete(name);
+      throw error;
+    });
+  cached.set(name, pending);
+
+  return await pending;
+};
+
+export const resetServerSecrets = (): void => {
+  cached.clear();
+};

packages/vitnode/src/api/lib/sso-email-confirmation.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, it } from "vitest";
+
+import { ssoConfirmsEmail } from "./sso-email-confirmation";
+
+describe("whether an SSO sign-in confirms the account's email", () => {
+  it("confirms an unverified address the provider just vouched for", () => {
+    expect(
+      ssoConfirmsEmail({
+        accountEmail: "jan@example.com",
+        emailVerified: false,
+        providerEmail: "jan@example.com",
+      }),
+    ).toBe(true);
+  });
+
+  it("matches the address the way sign-in does, canonical form included", () => {
+    expect(
+      ssoConfirmsEmail({
+        accountEmail: "jankowalski@gmail.com",
+        emailVerified: false,
+        providerEmail: "Jan.Kowalski@gmail.com",
+      }),
+    ).toBe(true);
+  });
+
+  it("leaves a verified account alone", () => {
+    expect(
+      ssoConfirmsEmail({
+        accountEmail: "jan@example.com",
+        emailVerified: true,
+        providerEmail: "jan@example.com",
+      }),
+    ).toBe(false);
+  });
+
+  it("does not confirm an address the provider did not return", () => {
+    expect(
+      ssoConfirmsEmail({
+        accountEmail: "old@example.com",
+        emailVerified: false,
+        providerEmail: "new@example.com",
+      }),
+    ).toBe(false);
+  });
+});

packages/vitnode/src/api/lib/sso-email-confirmation.ts

@@ -0,0 +1,12 @@
+import { emailAliases } from "./user-email-lookup";
+
+export const ssoConfirmsEmail = ({
+  accountEmail,
+  emailVerified,
+  providerEmail,
+}: {
+  accountEmail: string;
+  emailVerified: boolean;
+  providerEmail: string;
+}): boolean =>
+  !emailVerified && emailAliases(providerEmail).includes(accountEmail);

packages/vitnode/src/api/models/events.ts

@@ -28,6 +28,11 @@ export interface VitNodeEvents {
     email: string;
     userId: number;
   };
+  "user.sso.linked": {
+    email: string;
+    providerId: string;
+    userId: number;
+  };
   "user.updated": {
     email: string;
     name: string;