handshake-auth 0.1.0 → 0.2.0

package/ReadMe.md

@@ -2,8 +2,6 @@
 
 Lightweight, storage-agnostic authentication for Express.js.
 
-> **Work in Progress** - This library is under active development and not yet ready for production use.
-
 ## Overview
 
 Handshake Auth is a lightweight authentication library that follows the strategy pattern similar to Passport.js, but without requiring a database connection. You provide callbacks for all storage operations (Inversion of Control), giving you complete control over how accounts are stored and retrieved.
@@ -14,13 +12,47 @@ Handshake Auth is a lightweight authentication library that follows the strategy
 
 The library handles the "handshakes" and "proofs" without demanding a seat at your database table. After successful authentication, you receive an Account object and decide what to do with it.
 
+## Why Handshake Auth?
+
+### vs Passport.js
+
+Passport is the de facto standard but shows its age:
+
+| Passport.js | Handshake Auth |
+|-------------|----------------|
+| Middleware hides control flow (magic redirects) | Explicit control flow (you call `authenticate()`, you handle the result) |
+| Sessions are the assumed default | Session-agnostic (works with `cookie-session`, no server-side state) |
+| `serializeUser`/`deserializeUser` are global singletons | Callbacks are per-instance, not global |
+| Callback-based API (`done(err, user, info)`) | `async`/`await` throughout |
+| OAuth flows are opaque | OAuth phases are explicit and visible |
+| Hundreds of strategies with inconsistent quality | Small, auditable codebase with built-in strategies |
+
+### vs better-auth
+
+better-auth is feature-rich but opinionated:
+
+| better-auth | Handshake Auth |
+|-------------|----------------|
+| **Requires database connection** | **No database connection** - you provide callbacks |
+| Creates and manages auth tables | You own your schema |
+| All-in-one (sessions, email verification, etc.) | Auth only - does one thing well |
+| Great for rapid prototyping | Full control over persistence |
+
+### The Sweet Spot
+
+If you want Passport's flexibility with modern ergonomics, without better-auth's database coupling, Handshake Auth is for you.
+
 ## Features
 
 - **Storage-agnostic** - You provide callbacks, you own your data
 - **Express-only** - Focused on Express.js with `cookie-session`
 - **TypeScript-first** - Full type safety with generics
 - **Modern** - async/await throughout, ESM-first
-- **Strategies included** - Password, Magic Link, Google OAuth, GitHub OAuth
+- **Strategies included:**
+  - Password (simple password-only for self-hosted apps)
+  - Username/Password (traditional email + password)
+  - Magic Link (passwordless via email)
+  - OAuth: Google, GitHub, Discord, Microsoft, Twitter/X
 
 ## Installation
 
@@ -31,7 +63,7 @@ npm install handshake-auth
 ## Basic Usage
 
 ```typescript
-import { Handshake, PasswordStrategy } from 'handshake-auth';
+import { Handshake, UsernamePasswordStrategy } from 'handshake-auth';
 
 // Define your account type
 interface Account {
@@ -52,11 +84,11 @@ const hs = new Handshake<Account>({
   },
 });
 
-// Register the password strategy
-hs.use(new PasswordStrategy());
+// Register the username-password strategy
+hs.use(new UsernamePasswordStrategy());
 
 // Authenticate
-const result = await hs.authenticate('password', 'user@example.com', 'their-password');
+const result = await hs.authenticate('username-password', 'user@example.com', 'their-password');
 
 if (result.account) {
   // Authentication successful
@@ -76,11 +108,12 @@ import express from 'express';
 import cookieSession from 'cookie-session';
 import {
   Handshake,
-  PasswordStrategy,
+  UsernamePasswordStrategy,
   handshakeMiddleware,
   login,
   logout,
-  isLoggedIn,
+  requireAuth,
+  requireGuest,
 } from 'handshake-auth';
 
 const app = express();
@@ -98,7 +131,7 @@ const hs = new Handshake<Account>({
   findAccount: async (email) => db.accounts.findByEmail(email),
   verifyPassword: async (account, password) => bcrypt.compare(password, account.passwordHash),
 });
-hs.use(new PasswordStrategy());
+hs.use(new UsernamePasswordStrategy());
 
 // Add middleware (attaches authenticate helper to req)
 app.use(handshakeMiddleware(hs));
@@ -106,7 +139,7 @@ app.use(handshakeMiddleware(hs));
 // Login route
 app.post('/login', async (req, res) => {
   const { email, password } = req.body;
-  const result = await hs.authenticate('password', email, password);
+  const result = await hs.authenticate('username-password', email, password);
 
   if (result.account) {
     login(req, result.account);
@@ -122,15 +155,196 @@ app.post('/logout', (req, res) => {
   res.json({ success: true });
 });
 
-// Protected route
-app.get('/me', (req, res) => {
-  if (!isLoggedIn(req)) {
-    return res.status(401).json({ error: 'Not logged in' });
-  }
+// Protected route (API style - returns 401 JSON if not authenticated)
+app.get('/api/me', requireAuth(), (req, res) => {
   res.json({ accountId: req.session?.accountId });
 });
+
+// Protected route (Web style - redirects to /login if not authenticated)
+app.get('/dashboard', requireAuth({ redirectTo: '/login' }), (req, res) => {
+  res.send('Welcome to your dashboard!');
+});
+
+// Guest-only route (redirects to /dashboard if already logged in)
+app.get('/login', requireGuest({ redirectTo: '/dashboard' }), (req, res) => {
+  res.send('<form>...</form>');
+});
+```
+
+## Magic Link Authentication
+
+Passwordless authentication via email:
+
+```typescript
+import { Handshake, useMagicLink, login } from 'handshake-auth';
+
+// In-memory token storage (use a database in production)
+const tokens = new Map<string, { email: string; expiresAt: Date }>();
+
+const hs = new Handshake<Account>({
+  findAccount: async (email) => db.accounts.findByEmail(email),
+  storeMagicToken: async (email, token, expiresAt) => {
+    tokens.set(token, { email, expiresAt });
+  },
+  verifyMagicToken: async (token) => {
+    const record = tokens.get(token);
+    if (!record || record.expiresAt < new Date()) return null;
+    tokens.delete(token); // One-time use
+    return { email: record.email };
+  },
+});
+
+// Register magic link strategy
+useMagicLink(hs, {
+  baseUrl: 'http://localhost:3000',
+  sendMagicLink: async (email, token, url) => {
+    // Send email with the magic link URL
+    console.log(`Magic link for ${email}: ${url}`);
+  },
+});
+
+// Request magic link
+app.post('/auth/magic', async (req, res) => {
+  const result = await hs.authenticate('magic:send', req.body.email);
+  if (!result.error) {
+    res.json({ message: 'Check your email!' });
+  } else {
+    res.status(400).json({ error: result.error });
+  }
+});
+
+// Verify magic link
+app.get('/auth/magic/callback', async (req, res) => {
+  const result = await hs.authenticate('magic:verify', req.query.token);
+  if (result.account) {
+    login(req, result.account);
+    res.redirect('/dashboard');
+  } else {
+    res.status(401).send('Invalid or expired link');
+  }
+});
+```
+
+## OAuth Authentication
+
+Handshake Auth supports OAuth providers with a simple, consistent API:
+
+```typescript
+import {
+  Handshake,
+  GoogleStrategy,
+  GitHubStrategy,
+  DiscordStrategy,
+  MicrosoftStrategy,
+  TwitterXStrategy,
+  login,
+} from 'handshake-auth';
+
+const hs = new Handshake<Account>({
+  findAccount: async (email) => db.accounts.findByEmail(email),
+  findOrCreateFromOAuth: async (provider, profile) => {
+    // Find existing account or create new one
+    let account = await db.accounts.findByProviderId(provider, profile.id);
+    if (!account) {
+      account = await db.accounts.create({
+        email: profile.email,
+        name: profile.name,
+        provider,
+        providerId: profile.id,
+      });
+    }
+    return account;
+  },
+});
+
+// Register OAuth strategies (only the ones you need)
+if (process.env.GOOGLE_CLIENT_ID) {
+  hs.use(new GoogleStrategy({
+    clientId: process.env.GOOGLE_CLIENT_ID,
+    clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
+    redirectUri: 'http://localhost:3000/auth/google/callback',
+  }));
+}
+
+if (process.env.GITHUB_CLIENT_ID) {
+  hs.use(new GitHubStrategy({
+    clientId: process.env.GITHUB_CLIENT_ID,
+    clientSecret: process.env.GITHUB_CLIENT_SECRET!,
+    redirectUri: 'http://localhost:3000/auth/github/callback',
+  }));
+}
+
+// Generic OAuth routes
+app.get('/auth/:provider', async (req, res) => {
+  const result = await hs.authenticate(req.params.provider, req, res, 'redirect');
+  if ('redirectUrl' in result) {
+    res.redirect(result.redirectUrl);
+  } else {
+    res.status(400).send(result.error);
+  }
+});
+
+app.get('/auth/:provider/callback', async (req, res) => {
+  const result = await hs.authenticate(req.params.provider, req, res, 'callback');
+  if (result.account) {
+    login(req, result.account);
+    res.redirect('/dashboard');
+  } else {
+    res.status(401).send(result.error);
+  }
+});
+```
+
+### Supported OAuth Providers
+
+| Provider | Strategy | Notes |
+|----------|----------|-------|
+| Google | `GoogleStrategy` | OpenID Connect |
+| GitHub | `GitHubStrategy` | Fetches email from `/user/emails` if needed |
+| Discord | `DiscordStrategy` | Standard OAuth2 |
+| Microsoft | `MicrosoftStrategy` | Supports tenant configuration |
+| Twitter/X | `TwitterXStrategy` | OAuth 2.0 with PKCE (no email provided) |
+
+## Documentation
+
+For detailed documentation, see the [docs/](./docs/) folder:
+
+- **[API Reference](./docs/api.md)** - Handshake class and core types
+- **[Express Middleware](./docs/middleware.md)** - Middleware functions, route guards, session helpers
+- **Strategies:**
+  - [Password](./docs/strategies/password.md) - Simple password-only authentication
+  - [Username/Password](./docs/strategies/username-password.md) - Email/username + password
+  - [Magic Link](./docs/strategies/magic-link.md) - Passwordless email authentication
+  - [Google](./docs/strategies/google.md) - Google OAuth
+  - [GitHub](./docs/strategies/github.md) - GitHub OAuth
+  - [Discord](./docs/strategies/discord.md) - Discord OAuth
+  - [Microsoft](./docs/strategies/microsoft.md) - Microsoft OAuth
+  - [Twitter/X](./docs/strategies/twitter-x.md) - Twitter/X OAuth
+
+## Example Application
+
+See the [examples/express-app](./examples/express-app) directory for a complete working example with all authentication strategies.
+
+```bash
+cd examples/express-app
+npm install
+cp .env.example .env
+npm run dev
 ```
 
+## What This Library Does NOT Do
+
+- **No account management** - No account model, no persistence, no database integrations
+- **No session management** - Uses `cookie-session` but doesn't manage server-side sessions
+- **No route ownership** - No automatic `/login`, `/callback`, or `/logout` routes
+- **No email sending** - Magic links require user-supplied delivery
+- **No UI** - No forms, no opinionated UX
+
+## ChangeLog
+
+- **0.2.0** - All strategies implemented (Password, Username/Password, Magic Link, Google, GitHub, Discord, Microsoft, Twitter/X), Express middleware with route guards, comprehensive documentation
+- **0.1.0** - Initial development release
+
 ## License
 
 ISC

package/dist/index.d.ts

@@ -1,6 +1,22 @@
 export type { AuthResult, Strategy, HandshakeCallbacks, HandshakeOptions, OAuthProfile, } from './types.js';
 export { Handshake } from './handshake.js';
 export { PasswordStrategy } from './strategies/index.js';
-export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, } from './middleware/index.js';
-export type { HandshakeSession, RequestWithAuth } from './middleware/index.js';
+export type { PasswordStrategyOptions } from './strategies/index.js';
+export { UsernamePasswordStrategy } from './strategies/index.js';
+export { MagicLinkStrategy, MagicLinkSendStrategy, MagicLinkVerifyStrategy, useMagicLink, } from './strategies/index.js';
+export type { MagicLinkOptions, MagicLinkSendResult } from './strategies/index.js';
+export { OAuthStrategy, isOAuthRedirect } from './strategies/index.js';
+export type { OAuthConfig, OAuthRedirectResult, OAuthTokenResponse, OAuthAuthResult, } from './strategies/index.js';
+export { GoogleStrategy } from './strategies/index.js';
+export type { GoogleProfile, GoogleStrategyOptions } from './strategies/index.js';
+export { GitHubStrategy } from './strategies/index.js';
+export type { GitHubProfile, GitHubEmail, GitHubStrategyOptions } from './strategies/index.js';
+export { DiscordStrategy } from './strategies/index.js';
+export type { DiscordProfile, DiscordStrategyOptions } from './strategies/index.js';
+export { MicrosoftStrategy } from './strategies/index.js';
+export type { MicrosoftProfile, MicrosoftTenant, MicrosoftStrategyOptions } from './strategies/index.js';
+export { TwitterXStrategy } from './strategies/index.js';
+export type { TwitterXProfile, TwitterXStrategyOptions } from './strategies/index.js';
+export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, requireAuth, requireGuest, } from './middleware/index.js';
+export type { HandshakeSession, RequestWithAuth, RequireAuthOptions, RequireGuestOptions, } from './middleware/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,GACpB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,UAAU,EACV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,YAAY,GACb,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAG3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AAGnF,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACvE,YAAY,EACV,WAAW,EACX,mBAAmB,EACnB,kBAAkB,EAClB,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAG/B,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAElF,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE/F,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,uBAAuB,CAAC;AAEpF,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAC1D,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AAEzG,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,YAAY,EAAE,eAAe,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAC;AAGtF,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,YAAY,GACb,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}

package/dist/index.js

@@ -2,6 +2,16 @@
 export { Handshake } from './handshake.js';
 // Strategies
 export { PasswordStrategy } from './strategies/index.js';
+export { UsernamePasswordStrategy } from './strategies/index.js';
+export { MagicLinkStrategy, MagicLinkSendStrategy, MagicLinkVerifyStrategy, useMagicLink, } from './strategies/index.js';
+// OAuth base
+export { OAuthStrategy, isOAuthRedirect } from './strategies/index.js';
+// OAuth providers
+export { GoogleStrategy } from './strategies/index.js';
+export { GitHubStrategy } from './strategies/index.js';
+export { DiscordStrategy } from './strategies/index.js';
+export { MicrosoftStrategy } from './strategies/index.js';
+export { TwitterXStrategy } from './strategies/index.js';
 // Express middleware
-export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, } from './middleware/index.js';
+export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, requireAuth, requireGuest, } from './middleware/index.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,aAAa;AACb,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,qBAAqB;AACrB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,GACpB,MAAM,uBAAuB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,aAAa;AACb,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAE3C,aAAa;AACb,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,GACb,MAAM,uBAAuB,CAAC;AAG/B,aAAa;AACb,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAQvE,kBAAkB;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,uBAAuB,CAAC;AAG1D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAGzD,qBAAqB;AACrB,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,YAAY,GACb,MAAM,uBAAuB,CAAC"}

package/dist/middleware/express.d.ts

@@ -74,4 +74,71 @@ export declare function getSessionAccountId(req: Request): string | undefined;
 export interface RequestWithAuth<TAccount> extends Request {
     authenticate: (strategyName: string, ...args: unknown[]) => Promise<AuthResult<TAccount>>;
 }
+/**
+ * Options for requireAuth middleware.
+ */
+export interface RequireAuthOptions {
+    /**
+     * URL to redirect to if not authenticated.
+     * If not provided, returns 401 JSON response.
+     * @example '/login'
+     */
+    redirectTo?: string;
+}
+/**
+ * Options for requireGuest middleware.
+ */
+export interface RequireGuestOptions {
+    /**
+     * URL to redirect to if already authenticated.
+     * If not provided, returns 403 JSON response.
+     * @example '/dashboard'
+     */
+    redirectTo?: string;
+}
+/**
+ * Route guard middleware that requires authentication.
+ * Use this to protect routes that should only be accessible to logged-in users.
+ *
+ * @param options - Configuration options
+ * @param options.redirectTo - URL to redirect to if not authenticated (for web apps)
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // API style - returns 401 JSON if not authenticated
+ * app.get('/api/profile', requireAuth(), (req, res) => {
+ *   res.json({ accountId: req.session.accountId });
+ * });
+ *
+ * // Web style - redirects to login page if not authenticated
+ * app.get('/dashboard', requireAuth({ redirectTo: '/login' }), (req, res) => {
+ *   res.render('dashboard');
+ * });
+ * ```
+ */
+export declare function requireAuth(options?: RequireAuthOptions): (req: Request, res: Response, next: NextFunction) => void;
+/**
+ * Route guard middleware that requires the user to be a guest (not logged in).
+ * Use this to protect routes that should only be accessible to non-authenticated users,
+ * such as login and registration pages.
+ *
+ * @param options - Configuration options
+ * @param options.redirectTo - URL to redirect to if already authenticated (for web apps)
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // API style - returns 403 JSON if already authenticated
+ * app.post('/api/login', requireGuest(), (req, res) => {
+ *   // Handle login
+ * });
+ *
+ * // Web style - redirects to dashboard if already logged in
+ * app.get('/login', requireGuest({ redirectTo: '/dashboard' }), (req, res) => {
+ *   res.render('login');
+ * });
+ * ```
+ */
+export declare function requireGuest(options?: RequireGuestOptions): (req: Request, res: Response, next: NextFunction) => void;
 //# sourceMappingURL=express.d.ts.map

package/dist/middleware/express.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,CAAC,QAAQ,CAAC,IAC3D,KAAK,OAAO,EAAE,MAAM,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAWhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,QAAQ,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnD,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,QAAQ,GAChB,IAAI,CAKN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,CAAE,SAAQ,OAAO;IACxD,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC3F"}
+{"version":3,"file":"express.d.ts","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAC/D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACjD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,EAAE,EAAE,SAAS,CAAC,QAAQ,CAAC,IAC3D,KAAK,OAAO,EAAE,MAAM,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAWhE;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,KAAK,CAAC,QAAQ,SAAS;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,EACnD,GAAG,EAAE,OAAO,EACZ,OAAO,EAAE,QAAQ,GAChB,IAAI,CAKN;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,MAAM,CAAC,GAAG,EAAE,OAAO,GAAG,IAAI,CAEzC;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAEhD;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED;;GAEG;AACH,MAAM,WAAW,eAAe,CAAC,QAAQ,CAAE,SAAQ,OAAO;IACxD,YAAY,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,CAAC;CAC3F;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,kBAAkB,IAC9C,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAS/D;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,CAAC,OAAO,CAAC,EAAE,mBAAmB,IAChD,KAAK,OAAO,EAAE,KAAK,QAAQ,EAAE,MAAM,YAAY,KAAG,IAAI,CAS/D"}

package/dist/middleware/express.js

@@ -74,4 +74,73 @@ export function isLoggedIn(req) {
 export function getSessionAccountId(req) {
     return req.session?.accountId;
 }
+/**
+ * Route guard middleware that requires authentication.
+ * Use this to protect routes that should only be accessible to logged-in users.
+ *
+ * @param options - Configuration options
+ * @param options.redirectTo - URL to redirect to if not authenticated (for web apps)
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // API style - returns 401 JSON if not authenticated
+ * app.get('/api/profile', requireAuth(), (req, res) => {
+ *   res.json({ accountId: req.session.accountId });
+ * });
+ *
+ * // Web style - redirects to login page if not authenticated
+ * app.get('/dashboard', requireAuth({ redirectTo: '/login' }), (req, res) => {
+ *   res.render('dashboard');
+ * });
+ * ```
+ */
+export function requireAuth(options) {
+    return (req, res, next) => {
+        if (isLoggedIn(req)) {
+            next();
+        }
+        else if (options?.redirectTo) {
+            res.redirect(options.redirectTo);
+        }
+        else {
+            res.status(401).json({ error: 'Authentication required' });
+        }
+    };
+}
+/**
+ * Route guard middleware that requires the user to be a guest (not logged in).
+ * Use this to protect routes that should only be accessible to non-authenticated users,
+ * such as login and registration pages.
+ *
+ * @param options - Configuration options
+ * @param options.redirectTo - URL to redirect to if already authenticated (for web apps)
+ * @returns Express middleware function
+ *
+ * @example
+ * ```typescript
+ * // API style - returns 403 JSON if already authenticated
+ * app.post('/api/login', requireGuest(), (req, res) => {
+ *   // Handle login
+ * });
+ *
+ * // Web style - redirects to dashboard if already logged in
+ * app.get('/login', requireGuest({ redirectTo: '/dashboard' }), (req, res) => {
+ *   res.render('login');
+ * });
+ * ```
+ */
+export function requireGuest(options) {
+    return (req, res, next) => {
+        if (!isLoggedIn(req)) {
+            next();
+        }
+        else if (options?.redirectTo) {
+            res.redirect(options.redirectTo);
+        }
+        else {
+            res.status(403).json({ error: 'Already logged in' });
+        }
+    };
+}
 //# sourceMappingURL=express.js.map

package/dist/middleware/express.js.map

@@ -1 +1 @@
-{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAW,EAAuB;IACnE,OAAO,CAAC,GAAY,EAAE,IAAc,EAAE,IAAkB,EAAQ,EAAE;QAChE,wCAAwC;QACvC,GAAiC,CAAC,YAAY,GAAG,KAAK,EACrD,YAAoB,EACpB,GAAG,IAAe,EACa,EAAE;YACjC,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,CAAC,CAAC;QAEF,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,KAAK,CACnB,GAAY,EACZ,OAAiB;IAEjB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;IAC/F,CAAC;IACD,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,GAAG,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,GAAG,CAAC,OAAO,EAAE,SAA+B,CAAC;AACtD,CAAC"}
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/middleware/express.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,mBAAmB,CAAW,EAAuB;IACnE,OAAO,CAAC,GAAY,EAAE,IAAc,EAAE,IAAkB,EAAQ,EAAE;QAChE,wCAAwC;QACvC,GAAiC,CAAC,YAAY,GAAG,KAAK,EACrD,YAAoB,EACpB,GAAG,IAAe,EACa,EAAE;YACjC,OAAO,EAAE,CAAC,YAAY,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC,CAAC;QAChD,CAAC,CAAC;QAEF,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,KAAK,CACnB,GAAY,EACZ,OAAiB;IAEjB,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC;QACjB,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;IAC/F,CAAC;IACD,GAAG,CAAC,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,EAAE,CAAC;AACrC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,MAAM,CAAC,GAAY;IACjC,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;AACrB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,OAAO,GAAG,CAAC,OAAO,EAAE,SAAS,KAAK,SAAS,CAAC;AAC9C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,OAAO,GAAG,CAAC,OAAO,EAAE,SAA+B,CAAC;AACtD,CAAC;AAiCD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,WAAW,CAAC,OAA4B;IACtD,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,IAAI,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACpB,IAAI,EAAE,CAAC;QACT,CAAC;aAAM,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;YAC/B,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,yBAAyB,EAAE,CAAC,CAAC;QAC7D,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,UAAU,YAAY,CAAC,OAA6B;IACxD,OAAO,CAAC,GAAY,EAAE,GAAa,EAAE,IAAkB,EAAQ,EAAE;QAC/D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrB,IAAI,EAAE,CAAC;QACT,CAAC;aAAM,IAAI,OAAO,EAAE,UAAU,EAAE,CAAC;YAC/B,GAAG,CAAC,QAAQ,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;QACnC,CAAC;aAAM,CAAC;YACN,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,mBAAmB,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/index.d.ts

@@ -1,3 +1,3 @@
-export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, } from './express.js';
-export type { HandshakeSession, RequestWithAuth } from './express.js';
+export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, requireAuth, requireGuest, } from './express.js';
+export type { HandshakeSession, RequestWithAuth, RequireAuthOptions, RequireGuestOptions, } from './express.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC;AAEtB,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,mBAAmB,GACpB,MAAM,cAAc,CAAC"}

package/dist/middleware/index.js

@@ -1,2 +1,2 @@
-export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, } from './express.js';
+export { handshakeMiddleware, login, logout, isLoggedIn, getSessionAccountId, requireAuth, requireGuest, } from './express.js';
 //# sourceMappingURL=index.js.map

package/dist/middleware/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,GACpB,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/middleware/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,mBAAmB,EACnB,KAAK,EACL,MAAM,EACN,UAAU,EACV,mBAAmB,EACnB,WAAW,EACX,YAAY,GACb,MAAM,cAAc,CAAC"}

package/dist/strategies/discord.d.ts

@@ -0,0 +1,99 @@
+import type { OAuthProfile } from '../types.js';
+import { OAuthStrategy } from './oauth-base.js';
+/**
+ * Discord user profile from the /users/@me endpoint.
+ */
+export interface DiscordProfile {
+    id: string;
+    username: string;
+    discriminator: string;
+    global_name?: string | null;
+    avatar?: string | null;
+    bot?: boolean;
+    system?: boolean;
+    mfa_enabled?: boolean;
+    banner?: string | null;
+    accent_color?: number | null;
+    locale?: string;
+    verified?: boolean;
+    email?: string | null;
+    flags?: number;
+    premium_type?: number;
+    public_flags?: number;
+}
+/**
+ * Configuration options for Discord OAuth strategy.
+ */
+export interface DiscordStrategyOptions {
+    /**
+     * Discord OAuth client ID
+     */
+    clientId: string;
+    /**
+     * Discord OAuth client secret
+     */
+    clientSecret: string;
+    /**
+     * Your callback URL (must match Discord Developer Portal configuration)
+     */
+    redirectUri: string;
+    /**
+     * OAuth scopes to request
+     * @default ['identify', 'email']
+     */
+    scopes?: string[];
+}
+/**
+ * Discord OAuth2 authentication strategy.
+ *
+ * @example
+ * ```typescript
+ * const hs = new Handshake({
+ *   findAccount: async (email) => db.accounts.findByEmail(email),
+ *   findOrCreateFromOAuth: async (provider, profile) => {
+ *     let account = await db.accounts.findByProviderId(provider, profile.id);
+ *     if (!account) {
+ *       account = await db.accounts.create({
+ *         email: profile.email,
+ *         name: profile.name,
+ *         providerId: profile.id,
+ *         provider,
+ *       });
+ *     }
+ *     return account;
+ *   },
+ * });
+ *
+ * hs.use(new DiscordStrategy({
+ *   clientId: process.env.DISCORD_CLIENT_ID!,
+ *   clientSecret: process.env.DISCORD_CLIENT_SECRET!,
+ *   redirectUri: 'http://localhost:3000/auth/discord/callback',
+ * }));
+ *
+ * // Routes
+ * app.get('/auth/discord', async (req, res) => {
+ *   const result = await hs.authenticate('discord', req, res, 'redirect');
+ *   if ('redirectUrl' in result) {
+ *     res.redirect(result.redirectUrl);
+ *   }
+ * });
+ *
+ * app.get('/auth/discord/callback', async (req, res) => {
+ *   const result = await hs.authenticate('discord', req, res, 'callback');
+ *   if (result.account) {
+ *     login(req, result.account);
+ *     res.redirect('/dashboard');
+ *   } else {
+ *     res.status(401).send(result.error);
+ *   }
+ * });
+ * ```
+ */
+export declare class DiscordStrategy<TAccount> extends OAuthStrategy<TAccount> {
+    constructor(options: DiscordStrategyOptions);
+    /**
+     * Map Discord profile to standard OAuthProfile.
+     */
+    protected mapProfile(data: unknown, accessToken: string): OAuthProfile;
+}
+//# sourceMappingURL=discord.d.ts.map

package/dist/strategies/discord.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discord.d.ts","sourceRoot":"","sources":["../../src/strategies/discord.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAEhD;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,YAAY,EAAE,MAAM,CAAC;IAErB;;OAEG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,eAAe,CAAC,QAAQ,CAAE,SAAQ,aAAa,CAAC,QAAQ,CAAC;gBACxD,OAAO,EAAE,sBAAsB;IAc3C;;OAEG;IAEH,SAAS,CAAC,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,YAAY;CAqBvE"}