@everystack/auth 0.1.0 → 0.2.1

package/src/index.ts

@@ -18,9 +18,9 @@
  *   const auth = createAuthHandlers(db, { users, profiles }, jwtSecret, { mode: 'postgres' });
  *
  * With DB-backed refresh tokens (recommended for production):
- *   import { sessions } from '@everystack/auth/schema';
+ *   import { refreshTokens } from '@everystack/auth/schema';
  *
- *   const auth = createAuthHandlers(db, { users, profiles, sessions }, jwtSecret);
+ *   const auth = createAuthHandlers(db, { users, profiles, refreshTokens }, jwtSecret);
  */
 
 import { createJwt } from './jwt';
@@ -32,16 +32,46 @@ import {
   revokeAllRefreshTokens,
   TokenError,
 } from './refresh';
-import type { OAuthProvider } from './oauth';
+import type { RefreshTokenOptions } from './refresh';
+import type { OAuthProvider, OAuthUserInfo } from './oauth';
 export type { OAuthProvider, OAuthUserInfo } from './oauth';
 export { createAppleProvider, createGoogleProvider } from './oauth';
 import { createPostgresAuthHandlers } from './postgres';
 import { getRefreshFromCookies } from './cookies';
 import { authResponse, signoutResponse } from './response';
 import type { CookieConfig } from './response';
+import type { EnrichClaimsFn } from './plugin';
+export type { EnrichClaimsFn } from './plugin';
+import { validateCsrfOrigin } from './csrf';
 
 const TOKEN_EXPIRY_SEC = 3600; // 1h
-const REFRESH_EXPIRY_SEC = 7 * 24 * 3600; // 7d
+const REFRESH_EXPIRY_SEC = 30 * 24 * 3600; // 30d
+
+/**
+ * Dummy bcrypt hash for timing-safe user enumeration protection.
+ * When a user is not found, we still run bcrypt against this hash
+ * so response time is constant regardless of whether the email exists.
+ */
+const DUMMY_BCRYPT_HASH = '$2a$10$abcdefghijklmnopqrstuuABCDEFGHIJKLMNOPQRSTUVWXYZ012345';
+
+/**
+ * Read the password hash from a user row.
+ * Supports both default schema (encryptedPassword) and app schemas (passwordHash).
+ */
+export function getPasswordHash(user: any): string | null {
+  return user.encryptedPassword ?? user.passwordHash ?? null;
+}
+
+/**
+ * Build insert values with the correct password column name.
+ * Checks which column exists on the Drizzle table definition.
+ */
+export function withPassword(users: any, values: Record<string, any>, hash: string | null): Record<string, any> {
+  if ('encryptedPassword' in users) {
+    return { ...values, encryptedPassword: hash };
+  }
+  return { ...values, passwordHash: hash };
+}
 
 export interface TokenPayload {
   sub: string;
@@ -59,13 +89,52 @@ export interface AuthHandlers {
   revokeRefreshTokens: (userId: string) => Promise<void>;
 }
 
+/**
+ * Callbacks for OAuth user resolution. Enables apps to control where
+ * OAuth provider links are stored (their tables, their schema).
+ */
+export interface OAuthCallbacks {
+  /** Find an existing user linked to this OAuth provider + UID. */
+  findByProvider: (provider: string, providerUid: string) => Promise<{ userId: string } | null>;
+  /** Create a new user from OAuth info. Return the created user. */
+  createFromOAuth: (
+    userInfo: OAuthUserInfo,
+    provider: string,
+  ) => Promise<{
+    id: string;
+    email: string;
+    username?: string;
+    displayName?: string;
+    avatarUrl?: string;
+    role?: string;
+  }>;
+}
+
 export interface AuthOptions {
   mode?: 'node' | 'postgres';
   /** postgres.js sql client — required when mode is 'postgres' */
   sql?: any;
-  oauth?: { providers: OAuthProvider[] };
+  /** Repository ID for multi-tenant scoping. When set, refresh tokens and
+   *  device registrations are isolated per repository. */
+  repositoryId?: string;
+  oauth?: {
+    providers: OAuthProvider[];
+    /** Callback-based OAuth user resolution (recommended).
+     *  When provided, identities/credentials tables are not needed. */
+    callbacks?: OAuthCallbacks;
+    /** Optional nonce validator for web OAuth flows.
+     *  Called with the nonce from the request body and verified user info.
+     *  Return true if valid, false to reject. */
+    validateNonce?: (nonce: string, userInfo: OAuthUserInfo) => Promise<boolean>;
+  };
   /** When set, auth responses also set HttpOnly cookies. `true` uses defaults. */
   cookies?: CookieConfig;
+  /** When true, signup returns the same 200 response whether the email exists or not.
+   *  Prevents email enumeration attacks at the cost of no immediate feedback. */
+  uniformSignupResponse?: boolean;
+  /** Callback to add extra claims (client_id, aud) during token signing.
+   *  Receives base claims and the original request; returns extra claims to merge. */
+  enrichClaims?: EnrichClaimsFn;
 }
 
 export {
@@ -76,24 +145,49 @@ export {
 } from './passwords';
 import { hashPassword, verifyPassword } from './passwords';
 
+/**
+ * Extract client IP and user agent from a request for refresh token metadata.
+ * When repositoryId is provided, it's included for multi-tenant scoping.
+ */
+function extractRequestMeta(request: Request, repositoryId?: string): RefreshTokenOptions {
+  const forwarded = request.headers.get('x-forwarded-for');
+  const ipAddress = forwarded ? forwarded.split(',')[0].trim() : undefined;
+  const userAgent = request.headers.get('user-agent') ?? undefined;
+  return { repositoryId, ipAddress, userAgent };
+}
+
+/** Run CSRF origin check if cookies are configured with allowedOrigins. */
+function csrfCheck(request: Request, cookies?: CookieConfig): Response | null {
+  if (!cookies || cookies === true) return null;
+  return validateCsrfOrigin(request, cookies.allowedOrigins);
+}
+
 /**
  * Create JWT auth handlers for signup, signin, refresh, and token verification.
  *
  * When `options.mode` is `'postgres'`, delegates password hashing and JWT signing
  * to PostgreSQL functions via pgcrypto. Requires auth SQL functions from `@everystack/auth/sql`.
  *
- * When `schema.sessions` is provided, refresh tokens are stored as
- * SHA-256 hashes in auth.sessions with one-time-use rotation.
- * When omitted, refresh tokens are stateless JWTs (original behavior).
+ * When `schema.refreshTokens` is provided, refresh tokens are stored as SHA-256
+ * hashes with one-time-use rotation and reuse detection. When omitted, refresh
+ * tokens are stateless JWTs (original behavior).
  *
  * @param db - Drizzle database instance
- * @param schema - Object with `users`, `profiles`, and optional `sessions`/`credentials`/`identities` table references
+ * @param schema - Object with `users`, `profiles`, and optional `refreshTokens` table reference
  * @param jwtSecret - Secret key for JWT signing (Uint8Array)
  * @param options - Mode ('node' | 'postgres') and OAuth config
  */
 export function createAuthHandlers(
   db: any,
-  schema: { users: any; profiles: any; sessions?: any; credentials?: any; identities?: any },
+  schema: {
+    users: any;
+    profiles: any;
+    refreshTokens?: any;
+    /** Legacy OAuth tables. Use `oauth.callbacks` instead for new apps. */
+    credentials?: any;
+    /** Legacy OAuth tables. Use `oauth.callbacks` instead for new apps. */
+    identities?: any;
+  },
   jwtSecret: Uint8Array,
   options?: AuthOptions
 ): AuthHandlers {
@@ -102,6 +196,7 @@ export function createAuthHandlers(
   }
 
   const { users, profiles } = schema;
+  const refreshTable = schema.refreshTokens;
 
   const accessJwt = createJwt({
     secret: jwtSecret,
@@ -114,8 +209,15 @@ export function createAuthHandlers(
     ttlSec: REFRESH_EXPIRY_SEC,
   });
 
-  async function signToken(payload: TokenPayload): Promise<string> {
-    return accessJwt.sign(payload as unknown as Record<string, unknown>);
+  async function signToken(payload: TokenPayload, request?: Request): Promise<string> {
+    let claims: Record<string, unknown> = payload as unknown as Record<string, unknown>;
+    if (options?.enrichClaims && request) {
+      const extra = await options.enrichClaims(claims, request);
+      if (extra && Object.keys(extra).length > 0) {
+        claims = { ...claims, ...extra };
+      }
+    }
+    return accessJwt.sign(claims);
   }
 
   async function signRefreshToken(payload: { sub: string }): Promise<string> {
@@ -129,6 +231,10 @@ export function createAuthHandlers(
     },
 
     signup: async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
+      const enrichRequest = options?.enrichClaims ? request.clone() : undefined;
       const { email, password, username, displayName } = await request.json();
 
       if (!email || !password || !username || !displayName) {
@@ -144,15 +250,21 @@ export function createAuthHandlers(
         .where(eq(users.email, email))
         .limit(1);
       if (existing.length > 0) {
+        if (options?.uniformSignupResponse) {
+          return Response.json(
+            { message: 'Check your email to continue.' },
+            { status: 200 }
+          );
+        }
         return Response.json(
           { message: 'Email already registered' },
           { status: 409 }
         );
       }
 
-      const passwordHash = await hashPassword(password);
+      const hash = await hashPassword(password);
       const { user, profile } = await db.transaction(async (tx: any) => {
-        const [u] = await tx.insert(users).values({ email, passwordHash }).returning();
+        const [u] = await tx.insert(users).values(withPassword(users, { email }, hash)).returning();
         const [p] = await tx.insert(profiles).values({ id: u.id, username, displayName }).returning();
         return { user: u, profile: p };
       });
@@ -161,9 +273,10 @@ export function createAuthHandlers(
         sub: user.id,
         email: user.email,
         role: user.role ?? 'authenticated',
-      });
-      const refreshToken = schema.sessions
-        ? (await createRefreshToken(db, schema.sessions, user.id)).token
+      }, enrichRequest);
+      const meta = extractRequestMeta(request, options?.repositoryId);
+      const refreshToken = refreshTable
+        ? (await createRefreshToken(db, refreshTable, user.id, undefined, meta)).token
         : await signRefreshToken({ sub: user.id });
 
       return authResponse(
@@ -184,6 +297,10 @@ export function createAuthHandlers(
     },
 
     signin: async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
+      const enrichRequest = options?.enrichClaims ? request.clone() : undefined;
       const { email, password } = await request.json();
 
       if (!email || !password) {
@@ -198,14 +315,18 @@ export function createAuthHandlers(
         .from(users)
         .where(eq(users.email, email))
         .limit(1);
+
       if (!user) {
+        // Timing-safe: run bcrypt even when user doesn't exist
+        // so response time is constant regardless of email existence
+        await verifyPassword(password, DUMMY_BCRYPT_HASH);
         return Response.json(
           { message: 'Invalid email or password' },
           { status: 401 }
         );
       }
 
-      const valid = await verifyPassword(password, user.passwordHash);
+      const valid = await verifyPassword(password, getPasswordHash(user)!);
       if (!valid) {
         return Response.json(
           { message: 'Invalid email or password' },
@@ -223,9 +344,10 @@ export function createAuthHandlers(
         sub: user.id,
         email: user.email,
         role: user.role ?? 'authenticated',
-      });
-      const refreshToken = schema.sessions
-        ? (await createRefreshToken(db, schema.sessions, user.id)).token
+      }, enrichRequest);
+      const meta = extractRequestMeta(request, options?.repositoryId);
+      const refreshToken = refreshTable
+        ? (await createRefreshToken(db, refreshTable, user.id, undefined, meta)).token
         : await signRefreshToken({ sub: user.id });
 
       return authResponse(
@@ -246,6 +368,9 @@ export function createAuthHandlers(
     },
 
     refresh: async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
       // Read refresh token from JSON body (mobile) or cookie (web SSR)
       let refreshToken: string | undefined;
       try {
@@ -264,10 +389,14 @@ export function createAuthHandlers(
         );
       }
 
-      if (schema.sessions) {
+      if (refreshTable) {
         // DB-backed rotation path
         try {
-          const result = await rotateRefreshToken(db, schema.sessions, refreshToken);
+          const meta = extractRequestMeta(request, options?.repositoryId);
+          const result = await rotateRefreshToken(db, refreshTable, refreshToken, {
+            ipAddress: meta.ipAddress,
+            userAgent: meta.userAgent,
+          });
 
           const [user] = await db
             .select()
@@ -275,7 +404,7 @@ export function createAuthHandlers(
             .where(eq(users.id, result.userId))
             .limit(1);
           if (!user) {
-            await revokeAllRefreshTokens(db, schema.sessions, result.userId);
+            await revokeAllRefreshTokens(db, refreshTable, result.userId, options?.repositoryId);
             return Response.json({ message: 'User not found' }, { status: 401 });
           }
 
@@ -283,7 +412,7 @@ export function createAuthHandlers(
             sub: user.id,
             email: user.email,
             role: user.role ?? 'authenticated',
-          });
+          }, request);
 
           return authResponse(
             { token, refreshToken: result.token },
@@ -321,7 +450,7 @@ export function createAuthHandlers(
             sub: user.id,
             email: user.email,
             role: user.role ?? 'authenticated',
-          });
+          }, request);
           const newRefreshToken = await signRefreshToken({ sub: user.id });
 
           return authResponse(
@@ -340,14 +469,21 @@ export function createAuthHandlers(
 
     oauth: options?.oauth?.providers.length
       ? async (request: Request): Promise<Response> => {
-          if (!schema.credentials || !schema.identities) {
+          const csrfError = csrfCheck(request, options?.cookies);
+          if (csrfError) return csrfError;
+
+          const enrichRequest = options?.enrichClaims ? request.clone() : undefined;
+          const oauthCallbacks = options?.oauth?.callbacks;
+
+          // Require either callbacks or legacy tables
+          if (!oauthCallbacks && (!schema.credentials || !schema.identities)) {
             return Response.json(
-              { message: 'OAuth not configured: credentials and identities tables required in schema' },
+              { message: 'OAuth not configured: provide oauth.callbacks or credentials/identities tables' },
               { status: 500 }
             );
           }
 
-          let body: { provider?: string; token?: string };
+          let body: { provider?: string; token?: string; nonce?: string };
           try {
             body = await request.json();
           } catch {
@@ -357,7 +493,7 @@ export function createAuthHandlers(
             );
           }
 
-          const { provider: providerName, token } = body;
+          const { provider: providerName, token, nonce } = body;
           if (!providerName || !token) {
             return Response.json(
               { message: 'provider and token are required' },
@@ -383,8 +519,100 @@ export function createAuthHandlers(
             );
           }
 
-          // Look up existing OAuth credential by (type='oauth', credentialId=providerUid)
-          // Join credentials → identities to get userId
+          // Optional nonce validation for web OAuth flows
+          if (options?.oauth?.validateNonce) {
+            if (!nonce) {
+              return Response.json(
+                { message: 'Nonce is required when nonce validation is configured' },
+                { status: 400 }
+              );
+            }
+            const nonceValid = await options.oauth.validateNonce(nonce, userInfo);
+            if (!nonceValid) {
+              return Response.json(
+                { message: 'Nonce validation failed' },
+                { status: 401 }
+              );
+            }
+          }
+
+          const meta = extractRequestMeta(request, options?.repositoryId);
+
+          if (oauthCallbacks) {
+            // Callback-based path (recommended) — no identities/credentials tables needed
+            const existing = await oauthCallbacks.findByProvider(providerName, userInfo.uid);
+
+            if (existing) {
+              const [existingUser] = await db
+                .select()
+                .from(users)
+                .where(eq(users.id, existing.userId))
+                .limit(1);
+
+              const [profile] = await db
+                .select()
+                .from(profiles)
+                .where(eq(profiles.id, existing.userId))
+                .limit(1);
+
+              const accessToken = await signToken({
+                sub: existingUser.id,
+                email: existingUser.email,
+                role: existingUser.role ?? 'authenticated',
+              }, enrichRequest);
+              const refreshTokenStr = refreshTable
+                ? (await createRefreshToken(db, refreshTable, existingUser.id, undefined, meta)).token
+                : await signRefreshToken({ sub: existingUser.id });
+
+              return authResponse(
+                {
+                  token: accessToken,
+                  refreshToken: refreshTokenStr,
+                  user: {
+                    id: existingUser.id,
+                    email: existingUser.email,
+                    username: profile?.username,
+                    displayName: profile?.displayName,
+                    avatarUrl: profile?.avatarUrl,
+                    role: existingUser.role ?? 'authenticated',
+                  },
+                },
+                200,
+                options?.cookies,
+              );
+            }
+
+            // New user via callback
+            const newUser = await oauthCallbacks.createFromOAuth(userInfo, providerName);
+
+            const accessToken = await signToken({
+              sub: newUser.id,
+              email: newUser.email,
+              role: newUser.role ?? 'authenticated',
+            }, enrichRequest);
+            const refreshTokenStr = refreshTable
+              ? (await createRefreshToken(db, refreshTable, newUser.id, undefined, meta)).token
+              : await signRefreshToken({ sub: newUser.id });
+
+            return authResponse(
+              {
+                token: accessToken,
+                refreshToken: refreshTokenStr,
+                user: {
+                  id: newUser.id,
+                  email: newUser.email,
+                  username: newUser.username,
+                  displayName: newUser.displayName,
+                  avatarUrl: newUser.avatarUrl,
+                  role: newUser.role ?? 'authenticated',
+                },
+              },
+              200,
+              options?.cookies,
+            );
+          }
+
+          // Legacy path: identities + credentials tables
           const existingResults = await db
             .select({
               credentialId: schema.credentials.id,
@@ -401,7 +629,6 @@ export function createAuthHandlers(
           const existingAccount = existingResults[0];
 
           if (existingAccount) {
-            // Existing linked account — sign in the associated user
             const [existingUser] = await db
               .select()
               .from(users)
@@ -418,15 +645,15 @@ export function createAuthHandlers(
               sub: existingUser.id,
               email: existingUser.email,
               role: existingUser.role ?? 'authenticated',
-            });
-            const refreshToken = schema.sessions
-              ? (await createRefreshToken(db, schema.sessions, existingUser.id)).token
+            }, enrichRequest);
+            const refreshTokenStr = refreshTable
+              ? (await createRefreshToken(db, refreshTable, existingUser.id, undefined, meta)).token
               : await signRefreshToken({ sub: existingUser.id });
 
             return authResponse(
               {
                 token: accessToken,
-                refreshToken,
+                refreshToken: refreshTokenStr,
                 user: {
                   id: existingUser.id,
                   email: existingUser.email,
@@ -441,7 +668,7 @@ export function createAuthHandlers(
             );
           }
 
-          // New user — create account + identity + OAuth credential
+          // New user — create account + identity + OAuth credential (legacy path)
           const displayName = [userInfo.firstName, userInfo.lastName]
             .filter(Boolean)
             .join(' ') || userInfo.email.split('@')[0];
@@ -450,7 +677,7 @@ export function createAuthHandlers(
           const { user, profile } = await db.transaction(async (tx: any) => {
             const [u] = await tx
               .insert(users)
-              .values({ email: userInfo.email, passwordHash: null })
+              .values(withPassword(users, { email: userInfo.email }, null))
               .returning();
 
             const [ident] = await tx
@@ -489,15 +716,15 @@ export function createAuthHandlers(
             sub: user.id,
             email: user.email,
             role: user.role ?? 'authenticated',
-          });
-          const refreshToken = schema.sessions
-            ? (await createRefreshToken(db, schema.sessions, user.id)).token
+          }, enrichRequest);
+          const refreshTokenStr = refreshTable
+            ? (await createRefreshToken(db, refreshTable, user.id, undefined, meta)).token
             : await signRefreshToken({ sub: user.id });
 
           return authResponse(
             {
               token: accessToken,
-              refreshToken,
+              refreshToken: refreshTokenStr,
               user: {
                 id: user.id,
                 email: user.email,
@@ -513,13 +740,16 @@ export function createAuthHandlers(
         }
       : undefined,
 
-    signout: async (_request: Request): Promise<Response> => {
+    signout: async (request: Request): Promise<Response> => {
+      const csrfError = csrfCheck(request, options?.cookies);
+      if (csrfError) return csrfError;
+
       return signoutResponse(options?.cookies);
     },
 
     revokeRefreshTokens: async (userId: string): Promise<void> => {
-      if (schema.sessions) {
-        await revokeAllRefreshTokens(db, schema.sessions, userId);
+      if (refreshTable) {
+        await revokeAllRefreshTokens(db, refreshTable, userId, options?.repositoryId);
       }
     },
   };

package/src/jwt/index.ts

@@ -89,15 +89,16 @@ export function createJwt<
     if (parts.length !== 3) return null;
     const [headerB64, payloadB64, sigB64] = parts;
 
-    // Header must decode to exactly the canonical HS256 header. This rejects
-    // alg=none, alg=RS256 confusion, and any other algorithm variation.
+    // Header must specify HS256. This rejects alg=none, alg=RS256 confusion,
+    // and any other algorithm variation. typ is optional per RFC 7519 §5.1 but
+    // if present must be "JWT".
     let header: { alg?: string; typ?: string };
     try {
       header = JSON.parse(textDecode(base64urlDecode(headerB64)));
     } catch {
       return null;
     }
-    if (header.alg !== 'HS256' || header.typ !== 'JWT') return null;
+    if (header.alg !== 'HS256' || (header.typ && header.typ !== 'JWT')) return null;
 
     const expected = await hmac(secretBytes, textEncode(`${headerB64}.${payloadB64}`));
     let actual: Uint8Array;

package/src/passwords.ts

@@ -19,7 +19,7 @@
 import bcrypt from 'bcryptjs';
 
 const DEFAULT_BCRYPT_COST = 10;
-export const BCRYPT_COST = Math.max(4, Math.min(31,
+export const BCRYPT_COST = Math.max(10, Math.min(31,
   parseInt(process.env.BCRYPT_COST || '', 10) || DEFAULT_BCRYPT_COST
 ));
 export const BCRYPT_MAX_BYTES = 72;