@revealui/auth 0.2.0 → 0.2.1

package/README.md

@@ -1,21 +1,17 @@
 # @revealui/auth
 
-**Status:** 🟡 Active Development | ⚠️ NOT Production Ready
-
-See [Project Status](../../docs/PROJECT_STATUS.md) for framework readiness.
-
-Authentication system for RevealUI - database-backed sessions with Better Auth patterns.
-
-> **⚠️ Security Note:** Auth implementation exists but requires independent security audit before production use.
+Session-based authentication for RevealUI — database-backed sessions, rate limiting, brute force protection, and password reset.
 
 ## Features
 
-- ✅ Database-backed sessions (PostgreSQL/NeonDB)
-- ✅ Secure token handling (SHA-256 hashing, HTTP-only cookies)
-- ✅ CSRF protection (SameSite cookies)
-- ✅ Type-safe (TypeScript)
-- ✅ Framework agnostic (Next.js, TanStack Start)
-- ✅ React hooks for client-side usage
+- **Database Sessions** — PostgreSQL/NeonDB-backed sessions with SHA-256 token hashing
+- **Secure Cookies** — HTTP-only, SameSite, secure flag, cross-subdomain support
+- **Rate Limiting** — Configurable per-endpoint rate limits stored in database
+- **Brute Force Protection** — Progressive lockout on failed sign-in attempts
+- **Password Reset** — Token-based password reset flow with email integration
+- **Password Validation** — Strength requirements and common password checks
+- **React Hooks** — Client-side session management (`useSession`, `useSignIn`, `useSignOut`)
+- **Framework Agnostic** — Works with Next.js, Hono, and other Node.js frameworks
 
 ## Installation
 
@@ -25,36 +21,34 @@ pnpm add @revealui/auth
 
 ## Usage
 
-### Server-side (Next.js API Routes)
+### Server-Side
 
 ```typescript
-import { getSession } from '@revealui/auth/server'
-import { type NextRequest, NextResponse } from 'next/server'
+import { getSession, signIn, signOut, createSession } from '@revealui/auth/server'
 
-export async function GET(request: NextRequest) {
-  const session = await getSession(request.headers)
-  
-  if (!session) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
+// Validate session from request headers
+const session = await getSession(request.headers)
 
-  return NextResponse.json({ user: session.user })
-}
+// Sign in with email/password
+const result = await signIn({ email, password })
+
+// Sign out (invalidate session)
+await signOut(sessionToken)
 ```
 
-### Client-side (React Hooks)
+### Client-Side (React)
 
 ```typescript
 'use client'
 import { useSession, useSignIn, useSignOut } from '@revealui/auth/react'
 
-function MyComponent() {
+function AuthComponent() {
   const { data: session, isLoading } = useSession()
   const { signIn } = useSignIn()
   const { signOut } = useSignOut()
 
   if (isLoading) return <div>Loading...</div>
-  if (!session) return <div>Not signed in</div>
+  if (!session) return <button onClick={() => signIn({ email, password })}>Sign In</button>
 
   return (
     <div>
@@ -65,13 +59,43 @@ function MyComponent() {
 }
 ```
 
-## API Routes
+## Exports
+
+| Subpath | Contents |
+|---------|----------|
+| `@revealui/auth/server` | Server-side auth (session CRUD, sign in/out, rate limiting, brute force) |
+| `@revealui/auth/client` | Client-side utilities |
+| `@revealui/auth/react` | React hooks (`useSession`, `useSignIn`, `useSignOut`) |
+
+## Security
+
+- Passwords hashed with bcrypt
+- Session tokens hashed with SHA-256 before storage
+- HTTP-only cookies prevent XSS token theft
+- SameSite cookie attribute prevents CSRF
+- Rate limiting prevents abuse (configurable per endpoint)
+- Brute force protection with progressive lockout
+- Cookie domain supports cross-subdomain auth (e.g. `.revealui.com`)
+
+## Development
+
+```bash
+# Build
+pnpm build
+
+# Type check
+pnpm typecheck
+
+# Run tests
+pnpm test
+```
+
+## Related
 
-- `GET /api/auth/session` - Get current session
-- `POST /api/auth/sign-in` - Sign in with email/password
-- `POST /api/auth/sign-up` - Create new account
-- `POST /api/auth/sign-out` - Sign out
+- [Core Package](../core/README.md) — CMS engine (uses auth for access control)
+- [DB Package](../db/README.md) — Database schema (sessions, users, rate_limits tables)
+- [Auth Guide](../../docs/AUTH.md) — Architecture, usage patterns, and security design
 
-## Documentation
+## License
 
-See [Auth System Design](../../docs/reference/auth/AUTH_SYSTEM_DESIGN.md) for comprehensive documentation.
+MIT

package/dist/react/useSignUp.d.ts

@@ -8,6 +8,7 @@ export interface SignUpInput {
     email: string;
     password: string;
     name: string;
+    tosAccepted: true;
 }
 export interface UseSignUpResult {
     signUp: (input: SignUpInput) => Promise<{

package/dist/react/useSignUp.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useSignUp.d.ts","sourceRoot":"","sources":["../../src/react/useSignUp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAiBvC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1F,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,eAAe,CAoD3C"}
+{"version":3,"file":"useSignUp.d.ts","sourceRoot":"","sources":["../../src/react/useSignUp.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AAiBvC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,IAAI,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,OAAO,CAAC;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,IAAI,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1F,SAAS,EAAE,OAAO,CAAA;IAClB,KAAK,EAAE,KAAK,GAAG,IAAI,CAAA;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,SAAS,IAAI,eAAe,CAoD3C"}

package/dist/server/auth.d.ts

@@ -40,5 +40,7 @@ export declare function isSignupAllowed(email: string): boolean;
 export declare function signUp(email: string, password: string, name: string, options?: {
     userAgent?: string;
     ipAddress?: string;
+    tosAcceptedAt?: Date;
+    tosVersion?: string;
 }): Promise<SignUpResult>;
 //# sourceMappingURL=auth.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAQ,MAAM,aAAa,CAAA;AAMnE;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GACA,OAAO,CAAC,YAAY,CAAC,CAwHvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAiBtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GACA,OAAO,CAAC,YAAY,CAAC,CAgIvB"}
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../../src/server/auth.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAQH,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAQ,MAAM,aAAa,CAAA;AAMnE;;;;;;;GAOG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB,GACA,OAAO,CAAC,YAAY,CAAC,CAwHvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAiBtD;AAED;;;;;;;;GAQG;AACH,wBAAsB,MAAM,CAC1B,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IACR,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,IAAI,CAAA;IACpB,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB,GACA,OAAO,CAAC,YAAY,CAAC,CAkJvB"}

package/dist/server/auth.js

@@ -3,6 +3,7 @@
  *
  * Sign in and sign up functionality with password hashing.
  */
+import { createHash, randomBytes } from 'node:crypto';
 import { logger } from '@revealui/core/observability/logger';
 import { getClient } from '@revealui/db/client';
 import { users } from '@revealui/db/schema';
@@ -238,6 +239,14 @@ export async function signUp(email, password, name, options) {
                 error: 'Failed to process password',
             };
         }
+        // Generate email verification token.
+        // Store the SHA-256 hash in the DB; send the raw token in the email link.
+        // A DB breach cannot be used to verify arbitrary emails without the raw token.
+        const rawEmailVerificationToken = randomBytes(32).toString('hex');
+        const emailVerificationToken = createHash('sha256')
+            .update(rawEmailVerificationToken)
+            .digest('hex');
+        const emailVerificationTokenExpiresAt = new Date(Date.now() + 24 * 60 * 60 * 1000); // 24h
         // Create user
         let user;
         try {
@@ -248,6 +257,11 @@ export async function signUp(email, password, name, options) {
                 email,
                 name,
                 password: hashedPassword,
+                emailVerified: false,
+                emailVerificationToken,
+                emailVerificationTokenExpiresAt,
+                tosAcceptedAt: options?.tosAcceptedAt ?? null,
+                tosVersion: options?.tosVersion ?? null,
             })
                 .returning();
             user = result[0];
@@ -281,9 +295,12 @@ export async function signUp(email, password, name, options) {
                 error: 'Failed to create session',
             };
         }
+        // Return the raw (unhashed) token so the caller can include it in the
+        // verification email link. The DB holds only the hash.
+        const userWithRawToken = { ...user, emailVerificationToken: rawEmailVerificationToken };
         return {
             success: true,
-            user,
+            user: userWithRawToken,
             sessionToken: token,
         };
     }

package/dist/server/brute-force.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"brute-force.d.ts","sourceRoot":"","sources":["../../src/server/brute-force.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAqCD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,gBAAiC,GACxC,OAAO,CAAC,IAAI,CAAC,CAiCf;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,gBAAiC,GACxC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CA6C7E;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1E"}
+{"version":3,"file":"brute-force.d.ts","sourceRoot":"","sources":["../../src/server/brute-force.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAUH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAqCD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,gBAAiC,GACxC,OAAO,CAAC,IAAI,CAAC,CA0Cf;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAItE;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,KAAK,EAAE,MAAM,EACb,MAAM,GAAE,gBAAiC,GACxC,OAAO,CAAC;IAAE,MAAM,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,iBAAiB,EAAE,MAAM,CAAA;CAAE,CAAC,CA6C7E;AAED;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ1E"}

package/dist/server/brute-force.js

@@ -45,28 +45,37 @@ function getStorageKey(email) {
 export async function recordFailedAttempt(email, config = DEFAULT_CONFIG) {
     const storage = getStorage();
     const storageKey = getStorageKey(email);
-    const now = Date.now();
-    const entryData = await storage.get(storageKey);
-    const entry = deserializeEntry(entryData) || { count: 0, windowStart: now };
-    // Reset if lock expired
-    if (entry.lockUntil && entry.lockUntil < now) {
-        entry.count = 0;
-        entry.lockUntil = undefined;
-        entry.windowStart = now;
-    }
-    // Reset if window expired
-    if (now - entry.windowStart > config.windowMs) {
-        entry.count = 0;
-        entry.windowStart = now;
+    const updater = (entryData) => {
+        const now = Date.now();
+        const entry = deserializeEntry(entryData) || { count: 0, windowStart: now };
+        // Reset if lock expired
+        if (entry.lockUntil && entry.lockUntil < now) {
+            entry.count = 0;
+            entry.lockUntil = undefined;
+            entry.windowStart = now;
+        }
+        // Reset if window expired
+        if (now - entry.windowStart > config.windowMs) {
+            entry.count = 0;
+            entry.windowStart = now;
+        }
+        entry.count++;
+        // Lock account if threshold reached
+        if (entry.count >= config.maxAttempts) {
+            entry.lockUntil = now + config.lockDurationMs;
+        }
+        const ttlSeconds = Math.ceil(Math.max(config.windowMs, entry.lockUntil ? entry.lockUntil - now : config.windowMs) / 1000);
+        return { value: serializeEntry(entry), ttlSeconds };
+    };
+    if (storage.atomicUpdate) {
+        await storage.atomicUpdate(storageKey, updater);
     }
-    entry.count++;
-    // Lock account if threshold reached
-    if (entry.count >= config.maxAttempts) {
-        entry.lockUntil = now + config.lockDurationMs;
+    else {
+        // Fallback for storage backends that don't support atomic updates
+        const existing = await storage.get(storageKey);
+        const { value, ttlSeconds } = updater(existing);
+        await storage.set(storageKey, value, ttlSeconds);
     }
-    // Store with TTL (window duration or lock duration, whichever is longer)
-    const ttlSeconds = Math.ceil(Math.max(config.windowMs, entry.lockUntil ? entry.lockUntil - now : config.windowMs) / 1000);
-    await storage.set(storageKey, serializeEntry(entry), ttlSeconds);
 }
 /**
  * Clears failed attempts for an email (on successful login)

package/dist/server/errors.d.ts

@@ -21,4 +21,8 @@ export declare class DatabaseError extends AuthError {
 export declare class TokenError extends AuthError {
     constructor(message?: string, statusCode?: number);
 }
+export declare class OAuthAccountConflictError extends AuthError {
+    email: string;
+    constructor(email: string);
+}
 //# sourceMappingURL=errors.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/server/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,SAAU,SAAQ,KAAK;IAGzB,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,MAAM;gBAFzB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY;CAKlC;AAED,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,OAAO,GAAE,MAAwB,EAAE,UAAU,GAAE,MAAY;CAIxE;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,GAAE,MAAgC,EAAE,UAAU,GAAE,MAAY;CAIhF;AAED,qBAAa,aAAc,SAAQ,SAAS;IACnC,aAAa,CAAC,EAAE,KAAK,CAAA;gBAEhB,OAAO,GAAE,MAAyB,EAAE,aAAa,CAAC,EAAE,OAAO;CAOxE;AAED,qBAAa,UAAW,SAAQ,SAAS;gBAC3B,OAAO,GAAE,MAAsB,EAAE,UAAU,GAAE,MAAY;CAItE"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/server/errors.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,qBAAa,SAAU,SAAQ,KAAK;IAGzB,IAAI,EAAE,MAAM;IACZ,UAAU,EAAE,MAAM;gBAFzB,OAAO,EAAE,MAAM,EACR,IAAI,EAAE,MAAM,EACZ,UAAU,GAAE,MAAY;CAKlC;AAED,qBAAa,YAAa,SAAQ,SAAS;gBAC7B,OAAO,GAAE,MAAwB,EAAE,UAAU,GAAE,MAAY;CAIxE;AAED,qBAAa,mBAAoB,SAAQ,SAAS;gBACpC,OAAO,GAAE,MAAgC,EAAE,UAAU,GAAE,MAAY;CAIhF;AAED,qBAAa,aAAc,SAAQ,SAAS;IACnC,aAAa,CAAC,EAAE,KAAK,CAAA;gBAEhB,OAAO,GAAE,MAAyB,EAAE,aAAa,CAAC,EAAE,OAAO;CAOxE;AAED,qBAAa,UAAW,SAAQ,SAAS;gBAC3B,OAAO,GAAE,MAAsB,EAAE,UAAU,GAAE,MAAY;CAItE;AAED,qBAAa,yBAA0B,SAAQ,SAAS;IAC/C,KAAK,EAAE,MAAM,CAAA;gBAER,KAAK,EAAE,MAAM;CAS1B"}

package/dist/server/errors.js

@@ -41,3 +41,11 @@ export class TokenError extends AuthError {
         this.name = 'TokenError';
     }
 }
+export class OAuthAccountConflictError extends AuthError {
+    email;
+    constructor(email) {
+        super('An account with this email already exists. Sign in with your password or original provider.', 'OAUTH_ACCOUNT_CONFLICT', 409);
+        this.name = 'OAuthAccountConflictError';
+        this.email = email;
+    }
+}

package/dist/server/index.d.ts

@@ -7,7 +7,8 @@
 export type { SignInResult, SignUpResult } from '../types.js';
 export { isSignupAllowed, signIn, signUp } from './auth.js';
 export { clearFailedAttempts, getFailedAttemptCount, isAccountLocked, recordFailedAttempt, } from './brute-force.js';
-export { AuthError, AuthenticationError, DatabaseError, SessionError, TokenError, } from './errors.js';
+export { AuthError, AuthenticationError, DatabaseError, OAuthAccountConflictError, SessionError, TokenError, } from './errors.js';
+export { buildAuthUrl, exchangeCode, fetchProviderUser, generateOAuthState, type ProviderUser, upsertOAuthUser, verifyOAuthState, } from './oauth.js';
 export type { PasswordResetResult, PasswordResetToken } from './password-reset.js';
 export { generatePasswordResetToken, invalidatePasswordResetToken, resetPasswordWithToken, validatePasswordResetToken, } from './password-reset.js';
 export { meetsMinimumPasswordRequirements, validatePasswordStrength, } from './password-validation.js';

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAC3D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAClF,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,gCAAgC,EAChC,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,UAAU,GACX,MAAM,cAAc,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AAC3D,OAAO,EACL,mBAAmB,EACnB,qBAAqB,EACrB,eAAe,EACf,mBAAmB,GACpB,MAAM,kBAAkB,CAAA;AACzB,OAAO,EACL,SAAS,EACT,mBAAmB,EACnB,aAAa,EACb,yBAAyB,EACzB,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAA;AACpB,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,YAAY,EACjB,eAAe,EACf,gBAAgB,GACjB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAClF,OAAO,EACL,0BAA0B,EAC1B,4BAA4B,EAC5B,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,gCAAgC,EAChC,wBAAwB,GACzB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EACL,cAAc,EACd,kBAAkB,EAClB,cAAc,GACf,MAAM,iBAAiB,CAAA;AACxB,OAAO,EACL,aAAa,EACb,qBAAqB,EACrB,aAAa,EACb,UAAU,GACX,MAAM,cAAc,CAAA"}

package/dist/server/index.js

@@ -6,7 +6,8 @@
  */
 export { isSignupAllowed, signIn, signUp } from './auth.js';
 export { clearFailedAttempts, getFailedAttemptCount, isAccountLocked, recordFailedAttempt, } from './brute-force.js';
-export { AuthError, AuthenticationError, DatabaseError, SessionError, TokenError, } from './errors.js';
+export { AuthError, AuthenticationError, DatabaseError, OAuthAccountConflictError, SessionError, TokenError, } from './errors.js';
+export { buildAuthUrl, exchangeCode, fetchProviderUser, generateOAuthState, upsertOAuthUser, verifyOAuthState, } from './oauth.js';
 export { generatePasswordResetToken, invalidatePasswordResetToken, resetPasswordWithToken, validatePasswordResetToken, } from './password-reset.js';
 export { meetsMinimumPasswordRequirements, validatePasswordStrength, } from './password-validation.js';
 export { checkRateLimit, getRateLimitStatus, resetRateLimit, } from './rate-limit.js';

package/dist/server/oauth.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 type { User } from '../types.js';
+export interface ProviderUser {
+    id: string;
+    email: string | null;
+    name: string;
+    avatarUrl: string | null;
+}
+/**
+ * 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 declare function generateOAuthState(provider: string, redirectTo: string): {
+    state: string;
+    cookieValue: string;
+};
+/**
+ * Verify a signed OAuth state token from the callback.
+ *
+ * Returns the decoded provider + redirectTo if valid, null otherwise.
+ */
+export declare function verifyOAuthState(state: string | null | undefined, cookieValue: string | null | undefined): {
+    provider: string;
+    redirectTo: string;
+} | null;
+export declare function buildAuthUrl(provider: string, redirectUri: string, state: string): string;
+export declare function exchangeCode(provider: string, code: string, redirectUri: string): Promise<string>;
+export declare function fetchProviderUser(provider: string, accessToken: string): Promise<ProviderUser>;
+/**
+ * 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 declare function upsertOAuthUser(provider: string, providerUser: ProviderUser): Promise<User>;
+//# sourceMappingURL=oauth.d.ts.map

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

@@ -0,0 +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"}

package/dist/server/oauth.js

@@ -0,0 +1,223 @@
+/**
+ * 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
+    if (storedState !== 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.
+    // Explicit linking (from an authenticated session) is a future feature.
+    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;
+}