@revealui/auth 0.2.0 → 0.3.0

package/dist/server/oauth.js

@@ -0,0 +1,355 @@
+/**
+ * OAuth Core — State Management + User Upsert
+ *
+ * CSRF state: signed cookie using HMAC-SHA256 over a base64url payload.
+ * Provider dispatch: routes to Google / GitHub / Vercel provider modules.
+ * User upsert: links OAuth identities to local users via oauth_accounts table.
+ */
+import crypto from 'node:crypto';
+import { logger } from '@revealui/core/observability/logger';
+import { getClient } from '@revealui/db/client';
+import { oauthAccounts, users } from '@revealui/db/schema';
+import { and, eq } from 'drizzle-orm';
+import { OAuthAccountConflictError } from './errors.js';
+import * as github from './providers/github.js';
+import * as google from './providers/google.js';
+import * as vercel from './providers/vercel.js';
+// =============================================================================
+// CSRF State
+// =============================================================================
+/**
+ * Generate a signed OAuth state token.
+ *
+ * State encodes provider + redirectTo + nonce as base64url JSON.
+ * Cookie value is `<state>.<hmac>` — the HMAC is over the state string
+ * using REVEALUI_SECRET, providing CSRF protection without a DB table.
+ */
+export function generateOAuthState(provider, redirectTo) {
+    const nonce = crypto.randomBytes(16).toString('hex');
+    const payload = JSON.stringify({ provider, redirectTo, nonce });
+    const state = Buffer.from(payload).toString('base64url');
+    const secret = process.env.REVEALUI_SECRET;
+    if (!secret) {
+        throw new Error('REVEALUI_SECRET is required for OAuth state signing. ' +
+            'Set it in your environment variables.');
+    }
+    const hmac = crypto.createHmac('sha256', secret).update(state).digest('hex');
+    return { state, cookieValue: `${state}.${hmac}` };
+}
+/**
+ * Verify a signed OAuth state token from the callback.
+ *
+ * Returns the decoded provider + redirectTo if valid, null otherwise.
+ */
+export function verifyOAuthState(state, cookieValue) {
+    if (!(state && cookieValue))
+        return null;
+    const dotIdx = cookieValue.lastIndexOf('.');
+    if (dotIdx === -1)
+        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 (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. ' +
+            'Set it in your environment variables.');
+    }
+    const expectedHmac = crypto.createHmac('sha256', secret).update(state).digest('hex');
+    // Both are hex-encoded SHA-256 HMACs — must be exactly 64 hex characters.
+    // Reject wrong-length inputs immediately; do NOT pad (padding enables forged matches
+    // where a short storedHmac is zero-padded to collide with the expected hash).
+    if (storedHmac.length !== 64 || expectedHmac.length !== 64)
+        return null;
+    try {
+        if (!crypto.timingSafeEqual(Buffer.from(storedHmac, 'hex'), Buffer.from(expectedHmac, 'hex'))) {
+            return null;
+        }
+    }
+    catch {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(Buffer.from(state, 'base64url').toString());
+        return { provider: parsed.provider, redirectTo: parsed.redirectTo };
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// Provider Dispatch
+// =============================================================================
+const PROVIDERS = ['google', 'github', 'vercel'];
+function isProvider(p) {
+    return PROVIDERS.includes(p);
+}
+function getClientId(provider) {
+    const map = {
+        google: process.env.GOOGLE_CLIENT_ID,
+        github: process.env.GITHUB_CLIENT_ID,
+        vercel: process.env.VERCEL_CLIENT_ID,
+    };
+    const id = map[provider];
+    if (!id)
+        throw new Error(`Missing client ID for provider: ${provider}`);
+    return id;
+}
+export function buildAuthUrl(provider, redirectUri, state) {
+    if (!isProvider(provider))
+        throw new Error(`Unknown provider: ${provider}`);
+    const clientId = getClientId(provider);
+    const builders = {
+        google: google.buildAuthUrl,
+        github: github.buildAuthUrl,
+        vercel: vercel.buildAuthUrl,
+    };
+    return builders[provider](clientId, redirectUri, state);
+}
+export async function exchangeCode(provider, code, redirectUri) {
+    if (!isProvider(provider))
+        throw new Error(`Unknown provider: ${provider}`);
+    const exchangers = {
+        google: google.exchangeCode,
+        github: github.exchangeCode,
+        vercel: vercel.exchangeCode,
+    };
+    return exchangers[provider](code, redirectUri);
+}
+export async function fetchProviderUser(provider, accessToken) {
+    if (!isProvider(provider))
+        throw new Error(`Unknown provider: ${provider}`);
+    const fetchers = {
+        google: google.fetchUser,
+        github: github.fetchUser,
+        vercel: vercel.fetchUser,
+    };
+    return fetchers[provider](accessToken);
+}
+// =============================================================================
+// User Upsert
+// =============================================================================
+/**
+ * Find or create a local user for the given OAuth identity.
+ *
+ * Flow:
+ * 1. Look up oauth_accounts by (provider, providerUserId) → get userId
+ * 2. If found: refresh metadata + return user
+ * 3. If not found: check users by email → link if match
+ * 4. If no match: create new user (role: 'admin', no password)
+ * 5. Insert oauth_accounts row
+ */
+export async function upsertOAuthUser(provider, providerUser) {
+    const db = getClient();
+    // 1. Check for existing linked account
+    const [existingAccount] = await db
+        .select()
+        .from(oauthAccounts)
+        .where(and(eq(oauthAccounts.provider, provider), eq(oauthAccounts.providerUserId, providerUser.id)))
+        .limit(1);
+    if (existingAccount) {
+        // Refresh provider metadata (name/email/avatar may have changed)
+        await db
+            .update(oauthAccounts)
+            .set({
+            providerEmail: providerUser.email,
+            providerName: providerUser.name,
+            providerAvatarUrl: providerUser.avatarUrl,
+            updatedAt: new Date(),
+        })
+            .where(eq(oauthAccounts.id, existingAccount.id));
+        const [user] = await db
+            .select()
+            .from(users)
+            .where(eq(users.id, existingAccount.userId))
+            .limit(1);
+        if (!user) {
+            logger.error(`oauth_accounts row ${existingAccount.id} references missing user ${existingAccount.userId}`);
+            throw new Error('OAuth account references a deleted user');
+        }
+        return user;
+    }
+    // 2. Check for existing user by email — BLOCK auto-linking
+    // 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.
+    // Users must link providers explicitly from an authenticated session
+    // via linkOAuthAccount().
+    let userId;
+    let isNewUser = false;
+    if (providerUser.email) {
+        const [existingUser] = await db
+            .select()
+            .from(users)
+            .where(eq(users.email, providerUser.email))
+            .limit(1);
+        if (existingUser) {
+            throw new OAuthAccountConflictError(providerUser.email);
+        }
+        isNewUser = true;
+        userId = crypto.randomUUID();
+    }
+    else {
+        isNewUser = true;
+        userId = crypto.randomUUID();
+    }
+    // 3. Create user if none found
+    if (isNewUser) {
+        await db.insert(users).values({
+            id: userId,
+            name: providerUser.name,
+            email: providerUser.email,
+            avatarUrl: providerUser.avatarUrl,
+            password: null,
+            role: 'user',
+            status: 'active',
+        });
+    }
+    // 4. Insert oauth_accounts link
+    await db.insert(oauthAccounts).values({
+        id: crypto.randomUUID(),
+        userId,
+        provider,
+        providerUserId: providerUser.id,
+        providerEmail: providerUser.email,
+        providerName: providerUser.name,
+        providerAvatarUrl: providerUser.avatarUrl,
+    });
+    const [user] = await db.select().from(users).where(eq(users.id, userId)).limit(1);
+    if (!user)
+        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;
+}

package/dist/server/passkey.d.ts

@@ -0,0 +1,132 @@
+/**
+ * WebAuthn Passkey Module
+ *
+ * Implements passkey registration, authentication, and management using
+ * @simplewebauthn/server v13. Passkeys enable passwordless authentication
+ * via biometrics, security keys, or platform authenticators.
+ *
+ * @see https://simplewebauthn.dev/
+ */
+import type { AuthenticationResponseJSON, PublicKeyCredentialCreationOptionsJSON, PublicKeyCredentialRequestOptionsJSON, RegistrationResponseJSON, VerifiedRegistrationResponse, WebAuthnCredential } from '@simplewebauthn/server';
+export interface PasskeyConfig {
+    /** Maximum passkeys per user (default: 10) */
+    maxPasskeysPerUser: number;
+    /** Challenge TTL in ms (default: 5 minutes) */
+    challengeTtlMs: number;
+    /** Relying Party ID — domain name (default: 'localhost') */
+    rpId: string;
+    /** Relying Party name — user-visible (default: 'RevealUI') */
+    rpName: string;
+    /** Expected origin(s) for verification (default: 'http://localhost:4000') */
+    origin: string | string[];
+}
+export declare function configurePasskey(overrides: Partial<PasskeyConfig>): void;
+export declare function resetPasskeyConfig(): void;
+/**
+ * Generate WebAuthn registration options for a user.
+ *
+ * The returned object should be passed to the browser's navigator.credentials.create().
+ * The challenge is embedded in the options and should be stored server-side
+ * for verification.
+ *
+ * @param userId - User's database ID
+ * @param userEmail - User's email (used as userName in WebAuthn)
+ * @param existingCredentialIds - Credential IDs to exclude (prevent re-registration)
+ */
+export declare function generateRegistrationChallenge(userId: string, userEmail: string, existingCredentialIds?: string[]): Promise<PublicKeyCredentialCreationOptionsJSON>;
+/**
+ * Verify a WebAuthn registration response from the browser.
+ *
+ * @param response - The RegistrationResponseJSON from the browser
+ * @param expectedChallenge - The challenge from generateRegistrationChallenge
+ * @param expectedOrigin - Override origin (defaults to config.origin)
+ * @returns Verified registration data including credential info
+ * @throws If verification fails
+ */
+export declare function verifyRegistration(response: RegistrationResponseJSON, expectedChallenge: string, expectedOrigin?: string | string[]): Promise<VerifiedRegistrationResponse>;
+/**
+ * Store a verified passkey credential in the database.
+ *
+ * Enforces the per-user passkey limit before insertion.
+ *
+ * @param userId - User's database ID
+ * @param credential - Verified credential from verifyRegistration
+ * @param deviceName - Optional user-friendly name (e.g., "MacBook Pro Touch ID")
+ * @returns The stored passkey record
+ */
+export declare function storePasskey(userId: string, credential: {
+    id: string;
+    publicKey: Uint8Array;
+    counter: number;
+    transports?: string[];
+    aaguid?: string;
+    backedUp?: boolean;
+}, deviceName?: string): Promise<{
+    id: string;
+    userId: string;
+    credentialId: string;
+    deviceName: string | null;
+    createdAt: Date;
+}>;
+/**
+ * Generate WebAuthn authentication options.
+ *
+ * The returned object should be passed to the browser's navigator.credentials.get().
+ *
+ * @param allowCredentials - Optional list of credential IDs to allow
+ */
+export declare function generateAuthenticationChallenge(allowCredentials?: {
+    id: string;
+    transports?: string[];
+}[]): Promise<PublicKeyCredentialRequestOptionsJSON>;
+/**
+ * Verify a WebAuthn authentication response and update the credential counter.
+ *
+ * @param response - The AuthenticationResponseJSON from the browser
+ * @param credential - The stored credential (id, publicKey, counter)
+ * @param expectedChallenge - The challenge from generateAuthenticationChallenge
+ * @param expectedOrigin - Override origin (defaults to config.origin)
+ * @returns Verification result with new counter value
+ */
+export declare function verifyAuthentication(response: AuthenticationResponseJSON, credential: WebAuthnCredential, expectedChallenge: string, expectedOrigin?: string | string[]): Promise<{
+    verified: boolean;
+    newCounter: number;
+}>;
+/**
+ * List all passkeys for a user (safe for client — excludes publicKey and counter).
+ */
+export declare function listPasskeys(userId: string): Promise<{
+    id: string;
+    credentialId: string;
+    deviceName: string | null;
+    backedUp: boolean;
+    createdAt: Date;
+    lastUsedAt: Date | null;
+}[]>;
+/**
+ * Delete a passkey. Blocks deletion if it's the user's last sign-in method.
+ *
+ * @param userId - User's database ID
+ * @param passkeyId - The passkey record ID to delete
+ * @throws If this is the user's only sign-in method
+ */
+export declare function deletePasskey(userId: string, passkeyId: string): Promise<void>;
+/**
+ * Rename a passkey's device name.
+ *
+ * @param userId - User's database ID
+ * @param passkeyId - The passkey record ID to rename
+ * @param name - New friendly name
+ */
+export declare function renamePasskey(userId: string, passkeyId: string, name: string): Promise<void>;
+/**
+ * Count a user's sign-in credentials (passkeys + password).
+ *
+ * @param userId - User's database ID
+ * @returns Passkey count and whether user has a password set
+ */
+export declare function countUserCredentials(userId: string): Promise<{
+    passkeyCount: number;
+    hasPassword: boolean;
+}>;
+//# sourceMappingURL=passkey.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"passkey.d.ts","sourceRoot":"","sources":["../../src/server/passkey.ts"],"names":[],"mappings":"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"}