flyer-crawler.projectium.com/docs/adr/0048-authentication-strategy.md

ADR-048: Authentication Strategy

Date: 2026-01-09

Status: Accepted (Fully Implemented)

Implemented: 2026-01-09 (Local auth + JWT), 2026-01-26 (OAuth enabled)

Context

The application requires a secure authentication system that supports both traditional email/password login and social OAuth providers (Google, GitHub). The system must handle user sessions, token refresh, account security (lockout after failed attempts), and integrate seamlessly with the existing Express middleware pipeline.

All authentication methods are now fully implemented: Local authentication (email/password), JWT tokens, and OAuth (Google + GitHub). OAuth strategies use conditional registration - they activate automatically when the corresponding environment variables are configured.

Decision

We will implement a stateless JWT-based authentication system with the following components:

1. Local Authentication: Email/password login with bcrypt hashing.
2. OAuth Authentication: Google and GitHub OAuth 2.0 (conditionally enabled via environment variables).
3. JWT Access Tokens: Short-lived tokens (15 minutes) for API authentication.
4. Refresh Tokens: Long-lived tokens (7 days) stored in HTTP-only cookies.
5. Account Security: Lockout after 5 failed login attempts for 15 minutes.

Design Principles

• Stateless Sessions: No server-side session storage; JWT contains all auth state.
• Defense in Depth: Multiple security layers (rate limiting, lockout, secure cookies).
• Graceful OAuth Degradation: OAuth is optional; system works with local auth only.
• OAuth User Flexibility: OAuth users have password_hash = NULL in database.

Current Implementation Status

Component	Status	Notes
Local Authentication	Enabled	Email/password with bcrypt (salt rounds = 10)
JWT Access Tokens	Enabled	15-minute expiry, Authorization: Bearer header
Refresh Tokens	Enabled	7-day expiry, HTTP-only cookie
Account Lockout	Enabled	5 failed attempts, 15-minute lockout
Password Reset	Enabled	Email-based token flow
Google OAuth	Enabled	Requires GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET env vars
GitHub OAuth	Enabled	Requires GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET env vars
OAuth Routes	Enabled	/api/auth/google, /api/auth/github + callbacks
OAuth Frontend UI	Enabled	Login buttons in AuthView.tsx

Implementation Details

Authentication Flow

┌─────────────────────────────────────────────────────────────────────┐
│                     AUTHENTICATION FLOW                              │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐      │
│  │  Login   │───>│ Passport │───>│   JWT    │───>│ Protected│      │
│  │ Request  │    │  Local   │    │  Token   │    │  Routes  │      │
│  └──────────┘    └──────────┘    └──────────┘    └──────────┘      │
│       │                                  │              │           │
│       │         ┌──────────┐             │              │           │
│       └────────>│  OAuth   │─────────────┘              │           │
│                 │ Provider │                            │           │
│                 └──────────┘                            │           │
│                                                         │           │
│  ┌──────────┐    ┌──────────┐                          │           │
│  │ Refresh  │───>│  New     │<─────────────────────────┘           │
│  │  Token   │    │  JWT     │   (when access token expires)        │
│  └──────────┘    └──────────┘                                      │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

Local Strategy (Enabled)

Located in src/routes/passport.routes.ts:

passport.use(
  new LocalStrategy(
    { usernameField: 'email', passReqToCallback: true },
    async (req, email, password, done) => {
      // 1. Find user with profile by email
      const userprofile = await db.userRepo.findUserWithProfileByEmail(email, req.log);

      // 2. Check account lockout
      if (userprofile.failed_login_attempts >= MAX_FAILED_ATTEMPTS) {
        // Check if lockout period has passed
      }

      // 3. Verify password with bcrypt
      const isMatch = await bcrypt.compare(password, userprofile.password_hash);

      // 4. On success, reset failed attempts and return user
      // 5. On failure, increment failed attempts
    },
  ),
);

Security Features:

• Bcrypt password hashing with salt rounds = 10
• Account lockout after 5 failed attempts
• 15-minute lockout duration
• Failed attempt tracking persists across lockout refreshes
• Activity logging for failed login attempts

JWT Strategy (Enabled)

const jwtOptions = {
  jwtFromRequest: ExtractJwt.fromAuthHeaderAsBearerToken(),
  secretOrKey: JWT_SECRET,
};

passport.use(
  new JwtStrategy(jwtOptions, async (jwt_payload, done) => {
    const userProfile = await db.userRepo.findUserProfileById(jwt_payload.user_id);
    if (userProfile) {
      return done(null, userProfile);
    }
    return done(null, false);
  }),
);

Token Configuration:

• Access token: 15 minutes expiry
• Refresh token: 7 days expiry, 64-byte random hex
• Refresh token stored in HTTP-only cookie with secure flag in production

OAuth Strategies (Conditionally Enabled)

OAuth strategies are fully implemented and activate automatically when the corresponding environment variables are set. The strategies use conditional registration to gracefully handle missing credentials.

Google OAuth

Located in src/config/passport.ts (lines 167-235):

// Only register the strategy if the required environment variables are set.
if (process.env.GOOGLE_CLIENT_ID && process.env.GOOGLE_CLIENT_SECRET) {
  passport.use(
    new GoogleStrategy(
      {
        clientID: process.env.GOOGLE_CLIENT_ID,
        clientSecret: process.env.GOOGLE_CLIENT_SECRET,
        callbackURL: '/api/auth/google/callback',
        scope: ['profile', 'email'],
      },
      async (_accessToken, _refreshToken, profile, done) => {
        const email = profile.emails?.[0]?.value;
        if (!email) {
          return done(new Error('No email found in Google profile.'), false);
        }

        const existingUserProfile = await db.userRepo.findUserWithProfileByEmail(email, logger);
        if (existingUserProfile) {
          // User exists, log them in (strip sensitive fields)
          return done(null, cleanUserProfile);
        } else {
          // Create new user with null password_hash for OAuth users
          const newUserProfile = await db.userRepo.createUser(
            email,
            null,
            {
              full_name: profile.displayName,
              avatar_url: profile.photos?.[0]?.value,
            },
            logger,
          );
          return done(null, newUserProfile);
        }
      },
    ),
  );
  logger.info('[Passport] Google OAuth strategy registered.');
} else {
  logger.warn('[Passport] Google OAuth strategy NOT registered: credentials not set.');
}

GitHub OAuth

Located in src/config/passport.ts (lines 237-310):

// Only register the strategy if the required environment variables are set.
if (process.env.GITHUB_CLIENT_ID && process.env.GITHUB_CLIENT_SECRET) {
  passport.use(
    new GitHubStrategy(
      {
        clientID: process.env.GITHUB_CLIENT_ID,
        clientSecret: process.env.GITHUB_CLIENT_SECRET,
        callbackURL: '/api/auth/github/callback',
        scope: ['user:email'],
      },
      async (_accessToken, _refreshToken, profile, done) => {
        const email = profile.emails?.[0]?.value;
        if (!email) {
          return done(new Error('No public email found in GitHub profile.'), false);
        }
        // Same flow as Google OAuth - find or create user
      },
    ),
  );
  logger.info('[Passport] GitHub OAuth strategy registered.');
} else {
  logger.warn('[Passport] GitHub OAuth strategy NOT registered: credentials not set.');
}

OAuth Routes (Active)

Located in src/routes/auth.routes.ts (lines 587-609):

// Google OAuth routes
router.get('/google', passport.authenticate('google', { session: false }));
router.get(
  '/google/callback',
  passport.authenticate('google', {
    session: false,
    failureRedirect: '/?error=google_auth_failed',
  }),
  createOAuthCallbackHandler('google'),
);

// GitHub OAuth routes
router.get('/github', passport.authenticate('github', { session: false }));
router.get(
  '/github/callback',
  passport.authenticate('github', {
    session: false,
    failureRedirect: '/?error=github_auth_failed',
  }),
  createOAuthCallbackHandler('github'),
);

OAuth Callback Handler

The callback handler generates tokens and redirects to the frontend:

const createOAuthCallbackHandler = (provider: 'google' | 'github') => {
  return async (req: Request, res: Response) => {
    const userProfile = req.user as UserProfile;
    const { accessToken, refreshToken } = await authService.handleSuccessfulLogin(
      userProfile,
      req.log,
    );

    res.cookie('refreshToken', refreshToken, {
      httpOnly: true,
      secure: process.env.NODE_ENV === 'production',
      maxAge: 30 * 24 * 60 * 60 * 1000, // 30 days
    });

    // Redirect to frontend with provider-specific token param
    const tokenParam = provider === 'google' ? 'googleAuthToken' : 'githubAuthToken';
    res.redirect(`${process.env.FRONTEND_URL}/?${tokenParam}=${accessToken}`);
  };
};

Database Schema

Users Table (sql/initial_schema.sql):

CREATE TABLE public.users (
  user_id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
  email TEXT NOT NULL UNIQUE,
  password_hash TEXT,              -- NULL for OAuth-only users
  refresh_token TEXT,              -- Current refresh token
  failed_login_attempts INTEGER DEFAULT 0,
  last_failed_login TIMESTAMPTZ,
  created_at TIMESTAMPTZ DEFAULT now(),
  updated_at TIMESTAMPTZ DEFAULT now()
);

Note: There is no separate OAuth provider mapping table. OAuth users are identified by password_hash = NULL. If a user signs up via OAuth and later wants to add a password, this would require schema changes.

Authentication Middleware

Located in src/routes/passport.routes.ts:

// Require admin role
export const isAdmin = (req, res, next) => {
  if (req.user?.role === 'admin') {
    next();
  } else {
    next(new ForbiddenError('Administrator access required.'));
  }
};

// Optional auth - attach user if present, continue if not
export const optionalAuth = (req, res, next) => {
  passport.authenticate('jwt', { session: false }, (err, user) => {
    if (user) req.user = user;
    next();
  })(req, res, next);
};

// Mock auth for testing (only in NODE_ENV=test)
export const mockAuth = (req, res, next) => {
  if (process.env.NODE_ENV === 'test') {
    req.user = createMockUserProfile({ role: 'admin' });
  }
  next();
};

Configuring OAuth Providers

OAuth is fully implemented and activates automatically when credentials are provided. No code changes are required.

Step 1: Set Environment Variables

Add to your environment (.env.local for development, Gitea secrets for production):

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id
GOOGLE_CLIENT_SECRET=your-google-client-secret

# GitHub OAuth
GITHUB_CLIENT_ID=your-github-client-id
GITHUB_CLIENT_SECRET=your-github-client-secret

Step 2: Configure OAuth Providers

Google Cloud Console:

1. Create project at https://console.cloud.google.com/
2. Enable Google+ API
3. Create OAuth 2.0 credentials (Web Application)
4. Add authorized redirect URI:
   • Development: http://localhost:3001/api/auth/google/callback
   • Production: https://your-domain.com/api/auth/google/callback

GitHub Developer Settings:

1. Go to https://github.com/settings/developers
2. Create new OAuth App
3. Set Authorization callback URL:
   • Development: http://localhost:3001/api/auth/github/callback
   • Production: https://your-domain.com/api/auth/github/callback

Step 3: Restart the Application

After setting the environment variables, restart PM2:

podman exec -it flyer-crawler-dev pm2 restart all

The Passport configuration will automatically register the OAuth strategies when it detects the credentials. Check the logs for confirmation:

[Passport] Google OAuth strategy registered.
[Passport] GitHub OAuth strategy registered.

Frontend Integration

OAuth login buttons are implemented in src/client/pages/AuthView.tsx. The frontend:

1. Redirects users to /api/auth/google or /api/auth/github
2. Handles the callback via the useAppInitialization hook which looks for googleAuthToken or githubAuthToken query parameters
3. Stores the token and redirects to the dashboard

Known Limitations

1. No OAuth Provider ID Mapping: Users are identified by email only. If a user has accounts with different emails on Google and GitHub, they create separate accounts.

2. No Account Linking: Users cannot link multiple OAuth providers to one account.

3. No Password Addition for OAuth Users: OAuth-only users cannot add a password to enable local login.

4. No PKCE Flow: OAuth implementation uses standard flow, not PKCE (Proof Key for Code Exchange).

5. No OAuth State Parameter Validation: The commented code doesn't show explicit state parameter handling for CSRF protection (Passport may handle this internally).

6. No Refresh Token from OAuth Providers: Only email/profile data is extracted; OAuth refresh tokens are not stored for API access.

Dependencies

Installed (all available):

• passport v0.7.0
• passport-local v1.0.0
• passport-jwt v4.0.1
• passport-google-oauth20 v2.0.0
• passport-github2 v0.1.12
• bcrypt v5.x
• jsonwebtoken v9.x

Type Definitions:

• @types/passport
• @types/passport-local
• @types/passport-jwt
• @types/passport-google-oauth20
• @types/passport-github2

Consequences

Positive

• Stateless Architecture: No session storage required; scales horizontally.
• Secure by Default: HTTP-only cookies, short token expiry, bcrypt hashing.
• Account Protection: Lockout prevents brute-force attacks.
• Flexible OAuth: OAuth activates automatically when credentials are set - no code changes needed.
• Graceful Degradation: System works with local auth only when OAuth credentials are not configured.
• Full Feature Set: Both local and OAuth authentication are production-ready.

Negative

• No Account Linking: Multiple OAuth providers create separate accounts if emails differ.
• Token in URL: OAuth callback passes token in URL query parameter (visible in browser history).
• Email-Based Identity: OAuth users are identified by email only, not provider-specific IDs.

Mitigation

• Document OAuth configuration steps clearly (see ../architecture/AUTHENTICATION.md).
• Consider adding OAuth provider ID columns for future account linking.
• Consider using URL fragment (#token=) instead of query parameter for callback in future enhancement.

Key Files

File	Purpose
src/config/passport.ts	Passport strategies (local, JWT, OAuth)
src/routes/auth.routes.ts	Auth endpoints (login, register, refresh, OAuth)
src/services/authService.ts	Auth business logic
src/services/db/user.db.ts	User database operations
src/config/env.ts	Environment variable validation
src/client/pages/AuthView.tsx	Frontend login/register UI with OAuth buttons
AUTHENTICATION.md	OAuth setup guide
.env.example	Environment variable template

Related ADRs

• ADR-011 - Authorization and Access Control
• ADR-016 - API Security (rate limiting, headers)
• ADR-032 - Rate Limiting
• ADR-043 - Middleware Pipeline

Future Enhancements

1. Add OAuth Provider Mapping Table: Store googleId, githubId for account linking.
2. Implement Account Linking: Allow users to connect multiple OAuth providers.
3. Add Password to OAuth Users: Allow OAuth users to set a password for local login.
4. Implement PKCE: Add PKCE flow for enhanced OAuth security.
5. Token in Fragment: Use URL fragment for OAuth callback token instead of query parameter.
6. OAuth Token Storage: Store OAuth refresh tokens for provider API access.
7. Magic Link Login: Add passwordless email login option.
8. Additional OAuth Providers: Support for Apple, Microsoft, or other providers.