@revealui/auth 0.2.1 → 0.3.0

package/dist/server/mfa.d.ts

@@ -0,0 +1,87 @@
+/**
+ * MFA/2FA — TOTP-based Multi-Factor Authentication
+ *
+ * Uses the timing-safe TOTP implementation from @revealui/core/security/auth.
+ * Backup codes are bcrypt-hashed for storage (one-time use, consumed on verify).
+ */
+export interface MFAConfig {
+    /** Number of backup codes to generate (default: 8) */
+    backupCodeCount: number;
+    /** Length of each backup code in bytes (default: 5, produces 10 hex chars) */
+    backupCodeLength: number;
+    /** Issuer name shown in authenticator apps */
+    issuer: string;
+}
+export declare function configureMFA(overrides: Partial<MFAConfig>): void;
+export declare function resetMFAConfig(): void;
+export interface MFASetupResult {
+    success: boolean;
+    /** Base32-encoded TOTP secret (show once) */
+    secret?: string;
+    /** otpauth:// URI for QR code */
+    uri?: string;
+    /** Plaintext backup codes (show once) */
+    backupCodes?: string[];
+    error?: string;
+}
+/**
+ * Initiate MFA setup for a user.
+ * Generates a TOTP secret and backup codes. The user must verify with a TOTP
+ * code before MFA is activated (see `verifyMFASetup`).
+ */
+export declare function initiateMFASetup(userId: string, email: string): Promise<MFASetupResult>;
+/**
+ * Verify MFA setup by confirming the user's authenticator app works.
+ * This activates MFA on the account.
+ */
+export declare function verifyMFASetup(userId: string, code: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Verify a TOTP code during login (step 2 of MFA login flow).
+ */
+export declare function verifyMFACode(userId: string, code: string): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Verify a backup code (one-time use). Consumes the code on success.
+ */
+export declare function verifyBackupCode(userId: string, code: string): Promise<{
+    success: boolean;
+    remainingCodes?: number;
+    error?: string;
+}>;
+/**
+ * Regenerate backup codes (requires active MFA).
+ */
+export declare function regenerateBackupCodes(userId: string): Promise<{
+    success: boolean;
+    backupCodes?: string[];
+    error?: string;
+}>;
+/**
+ * Discriminated union for MFA disable re-authentication proof.
+ * - `password`: traditional password confirmation
+ * - `passkey`: WebAuthn assertion already verified by the API route
+ */
+export type MFADisableProof = {
+    method: 'password';
+    password: string;
+} | {
+    method: 'passkey';
+    verified: true;
+};
+/**
+ * Disable MFA on a user account. Requires re-authentication proof.
+ */
+export declare function disableMFA(userId: string, proof: MFADisableProof): Promise<{
+    success: boolean;
+    error?: string;
+}>;
+/**
+ * Check if a user has MFA enabled.
+ */
+export declare function isMFAEnabled(userId: string): Promise<boolean>;
+//# sourceMappingURL=mfa.d.ts.map

package/dist/server/mfa.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mfa.d.ts","sourceRoot":"","sources":["../../src/server/mfa.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAaH,MAAM,WAAW,SAAS;IACxB,sDAAsD;IACtD,eAAe,EAAE,MAAM,CAAC;IACxB,8EAA8E;IAC9E,gBAAgB,EAAE,MAAM,CAAC;IACzB,8CAA8C;IAC9C,MAAM,EAAE,MAAM,CAAC;CAChB;AAUD,wBAAgB,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,SAAS,CAAC,GAAG,IAAI,CAEhE;AAED,wBAAgB,cAAc,IAAI,IAAI,CAErC;AA2CD,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,yCAAyC;IACzC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAuC7F;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAsC/C;AAED;;GAEG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAmB/C;AAED;;GAEG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAuCxE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAwBvE;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,QAAQ,EAAE,IAAI,CAAA;CAAE,CAAC;AAE1C;;GAEG;AACH,wBAAsB,UAAU,CAC9B,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,eAAe,GACrB,OAAO,CAAC;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CA+C/C;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAUnE"}

package/dist/server/mfa.js

@@ -0,0 +1,263 @@
+/**
+ * MFA/2FA — TOTP-based Multi-Factor Authentication
+ *
+ * Uses the timing-safe TOTP implementation from @revealui/core/security/auth.
+ * Backup codes are bcrypt-hashed for storage (one-time use, consumed on verify).
+ */
+import { randomBytes } from 'node:crypto';
+import { TwoFactorAuth } from '@revealui/core/security';
+import { getClient } from '@revealui/db/client';
+import { users } from '@revealui/db/schema';
+import bcrypt from 'bcryptjs';
+import { eq } from 'drizzle-orm';
+const DEFAULT_MFA_CONFIG = {
+    backupCodeCount: 8,
+    backupCodeLength: 5,
+    issuer: 'RevealUI',
+};
+let config = { ...DEFAULT_MFA_CONFIG };
+export function configureMFA(overrides) {
+    config = { ...DEFAULT_MFA_CONFIG, ...overrides };
+}
+export function resetMFAConfig() {
+    config = { ...DEFAULT_MFA_CONFIG };
+}
+// =============================================================================
+// Backup Code Generation
+// =============================================================================
+/**
+ * Generate a set of plaintext backup codes.
+ * Returns both the plaintext codes (to show the user once) and bcrypt hashes (to store).
+ */
+async function generateBackupCodes() {
+    const plaintext = [];
+    const hashed = [];
+    for (let i = 0; i < config.backupCodeCount; i++) {
+        const code = randomBytes(config.backupCodeLength).toString('hex');
+        plaintext.push(code);
+        hashed.push(await bcrypt.hash(code, 10));
+    }
+    return { plaintext, hashed };
+}
+// =============================================================================
+// TOTP Provisioning URI
+// =============================================================================
+/**
+ * Build an otpauth:// URI for QR code generation in authenticator apps.
+ */
+function buildProvisioningUri(secret, email) {
+    const issuer = encodeURIComponent(config.issuer);
+    const account = encodeURIComponent(email);
+    return `otpauth://totp/${issuer}:${account}?secret=${secret}&issuer=${issuer}&algorithm=SHA1&digits=6&period=30`;
+}
+/**
+ * Initiate MFA setup for a user.
+ * Generates a TOTP secret and backup codes. The user must verify with a TOTP
+ * code before MFA is activated (see `verifyMFASetup`).
+ */
+export async function initiateMFASetup(userId, email) {
+    const db = getClient();
+    // Check if MFA is already enabled
+    const [user] = await db
+        .select({ mfaEnabled: users.mfaEnabled })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (!user) {
+        return { success: false, error: 'User not found' };
+    }
+    if (user.mfaEnabled) {
+        return { success: false, error: 'MFA is already enabled' };
+    }
+    // Generate TOTP secret and backup codes
+    const secret = TwoFactorAuth.generateSecret();
+    const { plaintext, hashed } = await generateBackupCodes();
+    const uri = buildProvisioningUri(secret, email);
+    // Store secret and backup codes (MFA stays disabled until verified)
+    await db
+        .update(users)
+        .set({
+        mfaSecret: secret,
+        mfaBackupCodes: hashed,
+        updatedAt: new Date(),
+    })
+        .where(eq(users.id, userId));
+    return {
+        success: true,
+        secret,
+        uri,
+        backupCodes: plaintext,
+    };
+}
+/**
+ * Verify MFA setup by confirming the user's authenticator app works.
+ * This activates MFA on the account.
+ */
+export async function verifyMFASetup(userId, code) {
+    const db = getClient();
+    const [user] = await db
+        .select({ mfaSecret: users.mfaSecret, mfaEnabled: users.mfaEnabled })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (!user) {
+        return { success: false, error: 'User not found' };
+    }
+    if (user.mfaEnabled) {
+        return { success: false, error: 'MFA is already enabled' };
+    }
+    if (!user.mfaSecret) {
+        return { success: false, error: 'MFA setup not initiated' };
+    }
+    // Verify the TOTP code against the stored secret
+    const valid = TwoFactorAuth.verifyCode(user.mfaSecret, code);
+    if (!valid) {
+        return { success: false, error: 'Invalid verification code' };
+    }
+    // Activate MFA
+    await db
+        .update(users)
+        .set({
+        mfaEnabled: true,
+        mfaVerifiedAt: new Date(),
+        updatedAt: new Date(),
+    })
+        .where(eq(users.id, userId));
+    return { success: true };
+}
+/**
+ * Verify a TOTP code during login (step 2 of MFA login flow).
+ */
+export async function verifyMFACode(userId, code) {
+    const db = getClient();
+    const [user] = await db
+        .select({ mfaSecret: users.mfaSecret, mfaEnabled: users.mfaEnabled })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (!(user?.mfaEnabled && user.mfaSecret)) {
+        return { success: false, error: 'MFA not enabled' };
+    }
+    const valid = TwoFactorAuth.verifyCode(user.mfaSecret, code);
+    if (!valid) {
+        return { success: false, error: 'Invalid code' };
+    }
+    return { success: true };
+}
+/**
+ * Verify a backup code (one-time use). Consumes the code on success.
+ */
+export async function verifyBackupCode(userId, code) {
+    const db = getClient();
+    const [user] = await db
+        .select({ mfaBackupCodes: users.mfaBackupCodes, mfaEnabled: users.mfaEnabled })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (!user?.mfaEnabled) {
+        return { success: false, error: 'MFA not enabled' };
+    }
+    const storedCodes = (user.mfaBackupCodes ?? []);
+    if (storedCodes.length === 0) {
+        return { success: false, error: 'No backup codes available' };
+    }
+    // Find and consume the matching backup code
+    for (let i = 0; i < storedCodes.length; i++) {
+        const storedCode = storedCodes[i];
+        if (!storedCode)
+            continue;
+        const matches = await bcrypt.compare(code, storedCode);
+        if (matches) {
+            // Remove the consumed code
+            const remaining = [...storedCodes.slice(0, i), ...storedCodes.slice(i + 1)];
+            await db
+                .update(users)
+                .set({
+                mfaBackupCodes: remaining,
+                updatedAt: new Date(),
+            })
+                .where(eq(users.id, userId));
+            return { success: true, remainingCodes: remaining.length };
+        }
+    }
+    return { success: false, error: 'Invalid backup code' };
+}
+/**
+ * Regenerate backup codes (requires active MFA).
+ */
+export async function regenerateBackupCodes(userId) {
+    const db = getClient();
+    const [user] = await db
+        .select({ mfaEnabled: users.mfaEnabled })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (!user?.mfaEnabled) {
+        return { success: false, error: 'MFA not enabled' };
+    }
+    const { plaintext, hashed } = await generateBackupCodes();
+    await db
+        .update(users)
+        .set({
+        mfaBackupCodes: hashed,
+        updatedAt: new Date(),
+    })
+        .where(eq(users.id, userId));
+    return { success: true, backupCodes: plaintext };
+}
+/**
+ * Disable MFA on a user account. Requires re-authentication proof.
+ */
+export async function disableMFA(userId, proof) {
+    const db = getClient();
+    const [user] = await db
+        .select({
+        mfaEnabled: users.mfaEnabled,
+        password: users.password,
+    })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    if (!user) {
+        return { success: false, error: 'User not found' };
+    }
+    if (!user.mfaEnabled) {
+        return { success: false, error: 'MFA is not enabled' };
+    }
+    // Verify re-authentication proof
+    if (proof.method === 'password') {
+        if (!user.password) {
+            return { success: false, error: 'Password verification required' };
+        }
+        const passwordValid = await bcrypt.compare(proof.password, user.password);
+        if (!passwordValid) {
+            return { success: false, error: 'Invalid password' };
+        }
+    }
+    // For passkey proof, the API route has already performed the WebAuthn assertion —
+    // the `verified: true` flag is trusted as a server-side signal.
+    // Clear all MFA data
+    await db
+        .update(users)
+        .set({
+        mfaEnabled: false,
+        mfaSecret: null,
+        mfaBackupCodes: null,
+        mfaVerifiedAt: null,
+        updatedAt: new Date(),
+    })
+        .where(eq(users.id, userId));
+    return { success: true };
+}
+/**
+ * Check if a user has MFA enabled.
+ */
+export async function isMFAEnabled(userId) {
+    const db = getClient();
+    const [user] = await db
+        .select({ mfaEnabled: users.mfaEnabled })
+        .from(users)
+        .where(eq(users.id, userId))
+        .limit(1);
+    return user?.mfaEnabled ?? false;
+}

package/dist/server/oauth.d.ts

@@ -46,4 +46,41 @@ export declare function fetchProviderUser(provider: string, accessToken: string)
  * 5. Insert oauth_accounts row
  */
 export declare function upsertOAuthUser(provider: string, providerUser: ProviderUser): Promise<User>;
+/**
+ * Link an OAuth provider to an existing authenticated user.
+ *
+ * Unlike upsertOAuthUser(), this function requires the caller to be
+ * authenticated and explicitly requests the link. This is safe because
+ * the user has already proven ownership of the local account via their
+ * session.
+ *
+ * @param userId - The authenticated user's ID (from session)
+ * @param provider - OAuth provider name
+ * @param providerUser - Profile returned by the OAuth provider
+ * @returns The linked user
+ * @throws Error if the provider account is already linked to a different user
+ */
+export declare function linkOAuthAccount(userId: string, provider: string, providerUser: ProviderUser): Promise<User>;
+/**
+ * Unlink an OAuth provider from a user's account.
+ *
+ * Safety: refuses to unlink the last auth method (if user has no password
+ * and this is their only OAuth link, unlinking would lock them out).
+ *
+ * @param userId - The authenticated user's ID
+ * @param provider - The provider to unlink
+ * @throws Error if unlinking would leave the user with no authentication method
+ */
+export declare function unlinkOAuthAccount(userId: string, provider: string): Promise<void>;
+/**
+ * Get all linked OAuth providers for a user.
+ *
+ * @param userId - The user's ID
+ * @returns Array of linked provider info (provider name, email, avatar)
+ */
+export declare function getLinkedProviders(userId: string): Promise<Array<{
+    provider: string;
+    providerEmail: string | null;
+    providerName: string | null;
+}>>;
 //# sourceMappingURL=oauth.d.ts.map

package/dist/server/oauth.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/server/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAMvC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;IACpB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CACzB;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAaxC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA2CjD;AAwBD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASzF;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA4FjG"}
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../src/server/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAOH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAMxC,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAMD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,CAaxC;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAChC,WAAW,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GACrC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAgDjD;AAwBD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CASzF;AAED,wBAAsB,YAAY,CAChC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,MAAM,CAAC,CAQjB;AAED,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,WAAW,EAAE,MAAM,GAClB,OAAO,CAAC,YAAY,CAAC,CAQvB;AAMD;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA6FjG;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,gBAAgB,CACpC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,YAAY,GACzB,OAAO,CAAC,IAAI,CAAC,CAiEf;AAED;;;;;;;;;GASG;AACH,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCxF;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,KAAK,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC,CAajG"}

package/dist/server/oauth.js

@@ -49,9 +49,11 @@ export function verifyOAuthState(state, cookieValue) {
         return null;
     const storedState = cookieValue.substring(0, dotIdx);
     const storedHmac = cookieValue.substring(dotIdx + 1);
-    // State from query param must match what's in the cookie
-    if (storedState !== state)
+    // State from query param must match what's in the cookie (timing-safe)
+    if (storedState.length !== state.length ||
+        !crypto.timingSafeEqual(Buffer.from(storedState), Buffer.from(state))) {
         return null;
+    }
     const secret = process.env.REVEALUI_SECRET;
     if (!secret) {
         throw new Error('REVEALUI_SECRET is required for OAuth state verification. ' +
@@ -175,7 +177,8 @@ export async function upsertOAuthUser(provider, providerUser) {
     // If an account with this email already exists but was not linked via OAuth,
     // reject the login. Auto-linking is an account takeover vector: an attacker
     // who controls a provider email instantly owns the existing account.
-    // Explicit linking (from an authenticated session) is a future feature.
+    // Users must link providers explicitly from an authenticated session
+    // via linkOAuthAccount().
     let userId;
     let isNewUser = false;
     if (providerUser.email) {
@@ -221,3 +224,132 @@ export async function upsertOAuthUser(provider, providerUser) {
         throw new Error('Failed to fetch upserted OAuth user');
     return user;
 }
+// =============================================================================
+// Explicit Account Linking
+// =============================================================================
+/**
+ * Link an OAuth provider to an existing authenticated user.
+ *
+ * Unlike upsertOAuthUser(), this function requires the caller to be
+ * authenticated and explicitly requests the link. This is safe because
+ * the user has already proven ownership of the local account via their
+ * session.
+ *
+ * @param userId - The authenticated user's ID (from session)
+ * @param provider - OAuth provider name
+ * @param providerUser - Profile returned by the OAuth provider
+ * @returns The linked user
+ * @throws Error if the provider account is already linked to a different user
+ */
+export async function linkOAuthAccount(userId, provider, providerUser) {
+    const db = getClient();
+    // 1. Check if this provider identity is already linked to ANY user
+    const [existingLink] = await db
+        .select()
+        .from(oauthAccounts)
+        .where(and(eq(oauthAccounts.provider, provider), eq(oauthAccounts.providerUserId, providerUser.id)))
+        .limit(1);
+    if (existingLink) {
+        if (existingLink.userId === userId) {
+            // Already linked to this user — refresh metadata and return
+            await db
+                .update(oauthAccounts)
+                .set({
+                providerEmail: providerUser.email,
+                providerName: providerUser.name,
+                providerAvatarUrl: providerUser.avatarUrl,
+                updatedAt: new Date(),
+            })
+                .where(eq(oauthAccounts.id, existingLink.id));
+            const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+            if (!user)
+                throw new Error('Authenticated user not found in database');
+            return user;
+        }
+        // Linked to a different user — cannot steal the identity
+        throw new Error('This provider account is already linked to another user. Unlink it from the other account first.');
+    }
+    // 2. Check the authenticated user exists
+    const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!user)
+        throw new Error('Authenticated user not found in database');
+    // 3. Check if this user already has a link for this provider (different provider account)
+    const [existingProviderLink] = await db
+        .select()
+        .from(oauthAccounts)
+        .where(and(eq(oauthAccounts.userId, userId), eq(oauthAccounts.provider, provider)))
+        .limit(1);
+    if (existingProviderLink) {
+        throw new Error(`You already have a ${provider} account linked. Unlink it first to connect a different one.`);
+    }
+    // 4. Create the link
+    await db.insert(oauthAccounts).values({
+        id: crypto.randomUUID(),
+        userId,
+        provider,
+        providerUserId: providerUser.id,
+        providerEmail: providerUser.email,
+        providerName: providerUser.name,
+        providerAvatarUrl: providerUser.avatarUrl,
+    });
+    logger.info(`Linked ${provider} account to user ${userId}`);
+    return user;
+}
+/**
+ * Unlink an OAuth provider from a user's account.
+ *
+ * Safety: refuses to unlink the last auth method (if user has no password
+ * and this is their only OAuth link, unlinking would lock them out).
+ *
+ * @param userId - The authenticated user's ID
+ * @param provider - The provider to unlink
+ * @throws Error if unlinking would leave the user with no authentication method
+ */
+export async function unlinkOAuthAccount(userId, provider) {
+    const db = getClient();
+    // 1. Find the link to remove
+    const [link] = await db
+        .select()
+        .from(oauthAccounts)
+        .where(and(eq(oauthAccounts.userId, userId), eq(oauthAccounts.provider, provider)))
+        .limit(1);
+    if (!link) {
+        throw new Error(`No ${provider} account is linked to your account`);
+    }
+    // 2. Safety check: ensure user won't be locked out
+    const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!user)
+        throw new Error('User not found');
+    const allLinks = await db
+        .select({ id: oauthAccounts.id })
+        .from(oauthAccounts)
+        .where(eq(oauthAccounts.userId, userId));
+    const hasPassword = !!user.password;
+    const otherLinksCount = allLinks.length - 1;
+    if (!hasPassword && otherLinksCount === 0) {
+        throw new Error('Cannot unlink your only sign-in method. Set a password first, or link another provider.');
+    }
+    // 3. Delete the link
+    await db
+        .delete(oauthAccounts)
+        .where(and(eq(oauthAccounts.userId, userId), eq(oauthAccounts.provider, provider)));
+    logger.info(`Unlinked ${provider} account from user ${userId}`);
+}
+/**
+ * Get all linked OAuth providers for a user.
+ *
+ * @param userId - The user's ID
+ * @returns Array of linked provider info (provider name, email, avatar)
+ */
+export async function getLinkedProviders(userId) {
+    const db = getClient();
+    const links = await db
+        .select({
+        provider: oauthAccounts.provider,
+        providerEmail: oauthAccounts.providerEmail,
+        providerName: oauthAccounts.providerName,
+    })
+        .from(oauthAccounts)
+        .where(eq(oauthAccounts.userId, userId));
+    return links;
+}