handshake-auth 0.1.0 → 0.2.0

package/dist/strategies/oauth-base.d.ts

@@ -0,0 +1,162 @@
+import type { Request, Response } from 'express';
+import type { AuthResult, Strategy, HandshakeCallbacks, OAuthProfile } from '../types.js';
+/**
+ * Configuration for OAuth providers.
+ */
+export interface OAuthConfig {
+    /**
+     * Strategy name (e.g., 'google', 'github', 'discord')
+     */
+    name: string;
+    /**
+     * OAuth client ID from the provider
+     */
+    clientId: string;
+    /**
+     * OAuth client secret from the provider
+     */
+    clientSecret: string;
+    /**
+     * URL for the provider's authorization endpoint
+     */
+    authorizeUrl: string;
+    /**
+     * URL for the provider's token endpoint
+     */
+    tokenUrl: string;
+    /**
+     * URL for fetching user profile information
+     */
+    userInfoUrl: string;
+    /**
+     * OAuth scopes to request
+     */
+    scopes: string[];
+    /**
+     * Your callback URL that the provider will redirect to
+     */
+    redirectUri: string;
+    /**
+     * Cookie name for storing OAuth state (CSRF protection)
+     * @default 'oauth_state'
+     */
+    stateCookieName?: string;
+    /**
+     * Additional authorization parameters to send
+     */
+    authorizationParams?: Record<string, string>;
+}
+/**
+ * Result from the redirect phase of OAuth authentication.
+ */
+export interface OAuthRedirectResult {
+    redirectUrl: string;
+}
+/**
+ * Token response from OAuth provider.
+ */
+export interface OAuthTokenResponse {
+    access_token: string;
+    token_type: string;
+    expires_in?: number;
+    refresh_token?: string;
+    scope?: string;
+}
+/**
+ * Combined result type for OAuth authentication.
+ * Can be either a redirect URL (for initiation) or an auth result (for callback).
+ */
+export type OAuthAuthResult<TAccount> = AuthResult<TAccount> | OAuthRedirectResult;
+/**
+ * Base class for OAuth2 authentication strategies.
+ *
+ * This class implements the standard OAuth2 authorization code flow:
+ * 1. **Redirect phase**: Generate state, build authorization URL, return redirect
+ * 2. **Callback phase**: Verify state, exchange code for token, fetch profile
+ *
+ * Subclasses should extend this and implement `mapProfile` to transform
+ * the provider's profile response into a standard OAuthProfile.
+ *
+ * @example
+ * ```typescript
+ * class GoogleStrategy<TAccount> extends OAuthStrategy<TAccount> {
+ *   constructor(options: GoogleOptions) {
+ *     super({
+ *       name: 'google',
+ *       authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+ *       tokenUrl: 'https://oauth2.googleapis.com/token',
+ *       userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+ *       scopes: ['openid', 'email', 'profile'],
+ *       ...options,
+ *     });
+ *   }
+ *
+ *   protected mapProfile(data: unknown): OAuthProfile {
+ *     const profile = data as GoogleProfile;
+ *     return {
+ *       id: profile.sub,
+ *       email: profile.email ?? null,
+ *       name: profile.name ?? null,
+ *       picture: profile.picture ?? null,
+ *       raw: profile,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export declare abstract class OAuthStrategy<TAccount> implements Strategy<TAccount> {
+    readonly name: string;
+    protected readonly clientId: string;
+    protected readonly clientSecret: string;
+    protected readonly authorizeUrl: string;
+    protected readonly tokenUrl: string;
+    protected readonly userInfoUrl: string;
+    protected readonly scopes: string[];
+    protected readonly redirectUri: string;
+    protected readonly stateCookieName: string;
+    protected readonly authorizationParams: Record<string, string>;
+    constructor(config: OAuthConfig);
+    /**
+     * Authenticate using OAuth.
+     *
+     * @param callbacks - Handshake callbacks (findOrCreateFromOAuth is used)
+     * @param args - [req, res, phase] where phase is 'redirect' or 'callback'
+     * @returns Either a redirect URL or an auth result
+     */
+    authenticate(callbacks: HandshakeCallbacks<TAccount>, ...args: unknown[]): Promise<AuthResult<TAccount>>;
+    /**
+     * Handle the redirect phase: generate state and return authorization URL.
+     */
+    protected handleRedirect(_req: Request, res: Response): AuthResult<TAccount> & OAuthRedirectResult;
+    /**
+     * Handle the callback phase: verify state, exchange code, fetch profile.
+     */
+    protected handleCallback(callbacks: HandshakeCallbacks<TAccount>, req: Request, res: Response): Promise<AuthResult<TAccount>>;
+    /**
+     * Exchange authorization code for access token.
+     */
+    protected exchangeCodeForToken(code: string): Promise<OAuthTokenResponse | {
+        error: string;
+    }>;
+    /**
+     * Fetch user profile from the provider.
+     * Subclasses can override this for providers with non-standard profile endpoints.
+     */
+    protected fetchUserProfile(accessToken: string): Promise<OAuthProfile | {
+        error: string;
+    }>;
+    /**
+     * Map the provider's profile response to a standard OAuthProfile.
+     * Subclasses must implement this to handle provider-specific profile formats.
+     *
+     * @param data - Raw profile data from the provider
+     * @param accessToken - Access token (some providers need this for additional API calls)
+     * @returns Standardized OAuthProfile
+     */
+    protected abstract mapProfile(data: unknown, accessToken: string): OAuthProfile | Promise<OAuthProfile>;
+}
+/**
+ * Type guard to check if a result is an OAuth redirect result.
+ */
+export declare function isOAuthRedirect<TAccount>(result: AuthResult<TAccount> | OAuthRedirectResult): result is OAuthRedirectResult & AuthResult<TAccount>;
+//# sourceMappingURL=oauth-base.d.ts.map

package/dist/strategies/oauth-base.d.ts.map

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

package/dist/strategies/oauth-base.js

@@ -0,0 +1,243 @@
+import { randomBytes } from 'crypto';
+/**
+ * Base class for OAuth2 authentication strategies.
+ *
+ * This class implements the standard OAuth2 authorization code flow:
+ * 1. **Redirect phase**: Generate state, build authorization URL, return redirect
+ * 2. **Callback phase**: Verify state, exchange code for token, fetch profile
+ *
+ * Subclasses should extend this and implement `mapProfile` to transform
+ * the provider's profile response into a standard OAuthProfile.
+ *
+ * @example
+ * ```typescript
+ * class GoogleStrategy<TAccount> extends OAuthStrategy<TAccount> {
+ *   constructor(options: GoogleOptions) {
+ *     super({
+ *       name: 'google',
+ *       authorizeUrl: 'https://accounts.google.com/o/oauth2/v2/auth',
+ *       tokenUrl: 'https://oauth2.googleapis.com/token',
+ *       userInfoUrl: 'https://openidconnect.googleapis.com/v1/userinfo',
+ *       scopes: ['openid', 'email', 'profile'],
+ *       ...options,
+ *     });
+ *   }
+ *
+ *   protected mapProfile(data: unknown): OAuthProfile {
+ *     const profile = data as GoogleProfile;
+ *     return {
+ *       id: profile.sub,
+ *       email: profile.email ?? null,
+ *       name: profile.name ?? null,
+ *       picture: profile.picture ?? null,
+ *       raw: profile,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export class OAuthStrategy {
+    name;
+    clientId;
+    clientSecret;
+    authorizeUrl;
+    tokenUrl;
+    userInfoUrl;
+    scopes;
+    redirectUri;
+    stateCookieName;
+    authorizationParams;
+    constructor(config) {
+        this.name = config.name;
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.authorizeUrl = config.authorizeUrl;
+        this.tokenUrl = config.tokenUrl;
+        this.userInfoUrl = config.userInfoUrl;
+        this.scopes = config.scopes;
+        this.redirectUri = config.redirectUri;
+        this.stateCookieName = config.stateCookieName ?? 'oauth_state';
+        this.authorizationParams = config.authorizationParams ?? {};
+    }
+    /**
+     * Authenticate using OAuth.
+     *
+     * @param callbacks - Handshake callbacks (findOrCreateFromOAuth is used)
+     * @param args - [req, res, phase] where phase is 'redirect' or 'callback'
+     * @returns Either a redirect URL or an auth result
+     */
+    async authenticate(callbacks, ...args) {
+        const [req, res, phase] = args;
+        if (phase === 'redirect') {
+            return this.handleRedirect(req, res);
+        }
+        else if (phase === 'callback') {
+            return this.handleCallback(callbacks, req, res);
+        }
+        else {
+            return {
+                account: null,
+                error: `Invalid OAuth phase: ${phase}. Use 'redirect' or 'callback'`,
+            };
+        }
+    }
+    /**
+     * Handle the redirect phase: generate state and return authorization URL.
+     */
+    handleRedirect(_req, res) {
+        // Generate random state for CSRF protection
+        const state = randomBytes(32).toString('hex');
+        // Store state in a cookie (will be verified on callback)
+        // Using httpOnly and sameSite for security
+        res.cookie(this.stateCookieName, state, {
+            httpOnly: true,
+            secure: process.env.NODE_ENV === 'production',
+            sameSite: 'lax',
+            maxAge: 10 * 60 * 1000, // 10 minutes
+        });
+        // Build authorization URL
+        const params = new URLSearchParams({
+            client_id: this.clientId,
+            redirect_uri: this.redirectUri,
+            response_type: 'code',
+            scope: this.scopes.join(' '),
+            state,
+            ...this.authorizationParams,
+        });
+        const redirectUrl = `${this.authorizeUrl}?${params.toString()}`;
+        // Return special result with redirect URL
+        // The caller should check for redirectUrl and redirect
+        return {
+            account: null,
+            redirectUrl,
+        };
+    }
+    /**
+     * Handle the callback phase: verify state, exchange code, fetch profile.
+     */
+    async handleCallback(callbacks, req, res) {
+        // Get state and code from query params
+        const { state: returnedState, code, error, error_description } = req.query;
+        // Check for OAuth error response
+        if (error) {
+            return {
+                account: null,
+                error: error_description || error,
+            };
+        }
+        // Verify state matches what we stored in the cookie
+        const storedState = req.cookies?.[this.stateCookieName];
+        // Clear the state cookie
+        res.clearCookie(this.stateCookieName);
+        if (!storedState || storedState !== returnedState) {
+            return {
+                account: null,
+                error: 'Invalid OAuth state. Possible CSRF attack or expired session.',
+            };
+        }
+        if (!code) {
+            return {
+                account: null,
+                error: 'No authorization code received',
+            };
+        }
+        // Exchange code for token
+        const tokenResult = await this.exchangeCodeForToken(code);
+        if ('error' in tokenResult) {
+            return {
+                account: null,
+                error: tokenResult.error,
+            };
+        }
+        // Fetch user profile
+        const profileResult = await this.fetchUserProfile(tokenResult.access_token);
+        if ('error' in profileResult) {
+            return {
+                account: null,
+                error: profileResult.error,
+            };
+        }
+        // Check for required callback
+        if (!callbacks.findOrCreateFromOAuth) {
+            return {
+                account: null,
+                error: 'findOrCreateFromOAuth callback is required for OAuth strategies',
+            };
+        }
+        // Let the application handle account creation/lookup
+        const account = await callbacks.findOrCreateFromOAuth(this.name, profileResult);
+        return {
+            account,
+            strategy: this.name,
+        };
+    }
+    /**
+     * Exchange authorization code for access token.
+     */
+    async exchangeCodeForToken(code) {
+        try {
+            const params = new URLSearchParams({
+                client_id: this.clientId,
+                client_secret: this.clientSecret,
+                code,
+                grant_type: 'authorization_code',
+                redirect_uri: this.redirectUri,
+            });
+            const response = await fetch(this.tokenUrl, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Accept: 'application/json',
+                },
+                body: params.toString(),
+            });
+            if (!response.ok) {
+                const errorData = await response.json().catch(() => ({}));
+                return {
+                    error: errorData.error_description ||
+                        errorData.error ||
+                        `Token exchange failed: ${response.status}`,
+                };
+            }
+            return (await response.json());
+        }
+        catch (err) {
+            return {
+                error: `Token exchange failed: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+    /**
+     * Fetch user profile from the provider.
+     * Subclasses can override this for providers with non-standard profile endpoints.
+     */
+    async fetchUserProfile(accessToken) {
+        try {
+            const response = await fetch(this.userInfoUrl, {
+                headers: {
+                    Authorization: `Bearer ${accessToken}`,
+                    Accept: 'application/json',
+                },
+            });
+            if (!response.ok) {
+                return {
+                    error: `Failed to fetch user profile: ${response.status}`,
+                };
+            }
+            const data = await response.json();
+            return this.mapProfile(data, accessToken);
+        }
+        catch (err) {
+            return {
+                error: `Failed to fetch user profile: ${err instanceof Error ? err.message : 'Unknown error'}`,
+            };
+        }
+    }
+}
+/**
+ * Type guard to check if a result is an OAuth redirect result.
+ */
+export function isOAuthRedirect(result) {
+    return 'redirectUrl' in result;
+}
+//# sourceMappingURL=oauth-base.js.map

package/dist/strategies/oauth-base.js.map

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

package/dist/strategies/password.d.ts

@@ -1,17 +1,80 @@
 import type { AuthResult, Strategy, HandshakeCallbacks } from '../types.js';
 /**
- * Password authentication strategy.
+ * Options for the simple password strategy.
+ */
+export interface PasswordStrategyOptions {
+    /**
+     * Callback to verify the password.
+     * You handle how the password is verified (e.g., compare to env var, bcrypt hash).
+     *
+     * @param password - The password to verify
+     * @returns true if valid, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Simple env var comparison
+     * verifyPassword: async (password) => password === process.env.APP_PASSWORD
+     *
+     * // Bcrypt comparison against hashed env var
+     * verifyPassword: async (password) => bcrypt.compare(password, process.env.APP_PASSWORD_HASH)
+     * ```
+     */
+    verifyPassword: (password: string) => Promise<boolean> | boolean;
+}
+/**
+ * Simple password-only authentication strategy.
+ *
+ * Authenticates with just a password (no username/email). Useful for:
+ * - Self-hosted apps with a single admin password
+ * - Simple internal tools not exposed to the internet
+ * - Quick prototyping
+ *
+ * The strategy doesn't use findAccount since there's no user lookup -
+ * it just verifies the password. On success, it returns a minimal account
+ * object that you provide.
+ *
+ * @example
+ * ```typescript
+ * // Simple password check against env var
+ * hs.use(new PasswordStrategy({
+ *   verifyPassword: async (password) => password === process.env.ADMIN_PASSWORD,
+ * }));
+ *
+ * // With bcrypt
+ * hs.use(new PasswordStrategy({
+ *   verifyPassword: async (password) => {
+ *     return bcrypt.compare(password, process.env.ADMIN_PASSWORD_HASH!);
+ *   },
+ * }));
+ *
+ * // In your login route
+ * app.post('/login', async (req, res) => {
+ *   const result = await hs.authenticate('password', req.body.password);
+ *   if (result.account) {
+ *     login(req, result.account);
+ *     res.redirect('/dashboard');
+ *   } else {
+ *     res.status(401).send('Invalid password');
+ *   }
+ * });
+ * ```
  *
- * Authenticates users with an identifier (e.g., email) and password.
- * Uses the findAccount and verifyPassword callbacks from Handshake.
+ * @example HTML form
+ * ```html
+ * <form method="POST" action="/login">
+ *   <input name="password" type="password" placeholder="Password" required />
+ *   <button type="submit">Login</button>
+ * </form>
+ * ```
  */
 export declare class PasswordStrategy<TAccount> implements Strategy<TAccount> {
     readonly name = "password";
+    private readonly verifyPassword;
+    constructor(options: PasswordStrategyOptions);
     /**
-     * Authenticate with identifier and password.
+     * Authenticate with password only.
      *
-     * @param callbacks - Handshake callbacks (findAccount, verifyPassword)
-     * @param identifier - The account identifier (e.g., email)
+     * @param callbacks - Handshake callbacks (not used by this strategy)
      * @param password - The password to verify
      * @returns Authentication result with account or error
      */

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

@@ -1 +1 @@
-{"version":3,"file":"password.d.ts","sourceRoot":"","sources":["../../src/strategies/password.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE5E;;;;;GAKG;AACH,qBAAa,gBAAgB,CAAC,QAAQ,CAAE,YAAW,QAAQ,CAAC,QAAQ,CAAC;IACnE,QAAQ,CAAC,IAAI,cAAc;IAE3B;;;;;;;OAOG;IACG,YAAY,CAChB,SAAS,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACvC,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;CAgCjC"}
+{"version":3,"file":"password.d.ts","sourceRoot":"","sources":["../../src/strategies/password.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAE5E;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;;;;;;;;;;;;;OAeG;IACH,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,CAAC;CAClE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,qBAAa,gBAAgB,CAAC,QAAQ,CAAE,YAAW,QAAQ,CAAC,QAAQ,CAAC;IACnE,QAAQ,CAAC,IAAI,cAAc;IAE3B,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA4C;gBAE/D,OAAO,EAAE,uBAAuB;IAI5C;;;;;;OAMG;IACG,YAAY,CAChB,SAAS,EAAE,kBAAkB,CAAC,QAAQ,CAAC,EACvC,GAAG,IAAI,EAAE,OAAO,EAAE,GACjB,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC;CAsCjC"}

package/dist/strategies/password.js

@@ -1,41 +1,90 @@
 /**
- * Password authentication strategy.
+ * Simple password-only authentication strategy.
  *
- * Authenticates users with an identifier (e.g., email) and password.
- * Uses the findAccount and verifyPassword callbacks from Handshake.
+ * Authenticates with just a password (no username/email). Useful for:
+ * - Self-hosted apps with a single admin password
+ * - Simple internal tools not exposed to the internet
+ * - Quick prototyping
+ *
+ * The strategy doesn't use findAccount since there's no user lookup -
+ * it just verifies the password. On success, it returns a minimal account
+ * object that you provide.
+ *
+ * @example
+ * ```typescript
+ * // Simple password check against env var
+ * hs.use(new PasswordStrategy({
+ *   verifyPassword: async (password) => password === process.env.ADMIN_PASSWORD,
+ * }));
+ *
+ * // With bcrypt
+ * hs.use(new PasswordStrategy({
+ *   verifyPassword: async (password) => {
+ *     return bcrypt.compare(password, process.env.ADMIN_PASSWORD_HASH!);
+ *   },
+ * }));
+ *
+ * // In your login route
+ * app.post('/login', async (req, res) => {
+ *   const result = await hs.authenticate('password', req.body.password);
+ *   if (result.account) {
+ *     login(req, result.account);
+ *     res.redirect('/dashboard');
+ *   } else {
+ *     res.status(401).send('Invalid password');
+ *   }
+ * });
+ * ```
+ *
+ * @example HTML form
+ * ```html
+ * <form method="POST" action="/login">
+ *   <input name="password" type="password" placeholder="Password" required />
+ *   <button type="submit">Login</button>
+ * </form>
+ * ```
  */
 export class PasswordStrategy {
     name = 'password';
+    verifyPassword;
+    constructor(options) {
+        this.verifyPassword = options.verifyPassword;
+    }
     /**
-     * Authenticate with identifier and password.
+     * Authenticate with password only.
      *
-     * @param callbacks - Handshake callbacks (findAccount, verifyPassword)
-     * @param identifier - The account identifier (e.g., email)
+     * @param callbacks - Handshake callbacks (not used by this strategy)
      * @param password - The password to verify
      * @returns Authentication result with account or error
      */
     async authenticate(callbacks, ...args) {
-        const [identifier, password] = args;
-        if (!identifier || !password) {
-            return { account: null, error: 'Identifier and password are required' };
+        const [password] = args;
+        if (!password) {
+            return { account: null, error: 'Password is required' };
         }
-        if (!callbacks.verifyPassword) {
-            return { account: null, error: 'verifyPassword callback is required for password strategy' };
+        // Verify the password using the provided callback
+        const isValid = await this.verifyPassword(password);
+        if (!isValid) {
+            return { account: null, error: 'Invalid password' };
         }
-        // Find the account
-        const account = await callbacks.findAccount(identifier);
-        // Always call verifyPassword even if account is null to prevent timing attacks.
-        // The verifyPassword callback should handle null accounts appropriately
-        // (e.g., by doing a dummy comparison that takes the same time).
-        // However, since the callback signature requires an account, we'll check first
-        // and rely on the overall operation timing being similar.
-        if (!account) {
-            return { account: null, error: 'Invalid credentials' };
+        // For password-only auth, we don't have a real account from the database.
+        // The user needs to provide a findAccount callback or we return a placeholder.
+        // Let's check if findAccount can find an account with a special identifier.
+        // Or we can just return a generic "authenticated" account.
+        // Try to find a default account (e.g., "admin" or the first account)
+        // If no findAccount provided or it returns null, create a minimal account marker
+        let account = null;
+        try {
+            // Try to get the default/admin account
+            account = await callbacks.findAccount('admin');
         }
-        // Verify the password
-        const isValid = await callbacks.verifyPassword(account, password);
-        if (!isValid) {
-            return { account: null, error: 'Invalid credentials' };
+        catch {
+            // findAccount might not be suitable for this use case
+        }
+        if (!account) {
+            // Return a minimal marker that indicates authentication succeeded
+            // The user can check for this in their app
+            account = { id: 'password-auth', authenticated: true };
         }
         return { account, strategy: this.name };
     }

package/dist/strategies/password.js.map

@@ -1 +1 @@
-{"version":3,"file":"password.js","sourceRoot":"","sources":["../../src/strategies/password.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAG,UAAU,CAAC;IAE3B;;;;;;;OAOG;IACH,KAAK,CAAC,YAAY,CAChB,SAAuC,EACvC,GAAG,IAAe;QAElB,MAAM,CAAC,UAAU,EAAE,QAAQ,CAAC,GAAG,IAAwB,CAAC;QAExD,IAAI,CAAC,UAAU,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC7B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,sCAAsC,EAAE,CAAC;QAC1E,CAAC;QAED,IAAI,CAAC,SAAS,CAAC,cAAc,EAAE,CAAC;YAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,2DAA2D,EAAE,CAAC;QAC/F,CAAC;QAED,mBAAmB;QACnB,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC;QAExD,gFAAgF;QAChF,wEAAwE;QACxE,gEAAgE;QAChE,+EAA+E;QAC/E,0DAA0D;QAC1D,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;QACzD,CAAC;QAED,sBAAsB;QACtB,MAAM,OAAO,GAAG,MAAM,SAAS,CAAC,cAAc,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;QAElE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,qBAAqB,EAAE,CAAC;QACzD,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;CACF"}
+{"version":3,"file":"password.js","sourceRoot":"","sources":["../../src/strategies/password.ts"],"names":[],"mappings":"AAyBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6CG;AACH,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAG,UAAU,CAAC;IAEV,cAAc,CAA4C;IAE3E,YAAY,OAAgC;QAC1C,IAAI,CAAC,cAAc,GAAG,OAAO,CAAC,cAAc,CAAC;IAC/C,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,YAAY,CAChB,SAAuC,EACvC,GAAG,IAAe;QAElB,MAAM,CAAC,QAAQ,CAAC,GAAG,IAAgB,CAAC;QAEpC,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,sBAAsB,EAAE,CAAC;QAC1D,CAAC;QAED,kDAAkD;QAClD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QAEpD,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC;QACtD,CAAC;QAED,0EAA0E;QAC1E,+EAA+E;QAC/E,4EAA4E;QAC5E,2DAA2D;QAE3D,qEAAqE;QACrE,iFAAiF;QACjF,IAAI,OAAO,GAAoB,IAAI,CAAC;QAEpC,IAAI,CAAC;YACH,uCAAuC;YACvC,OAAO,GAAG,MAAM,SAAS,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACjD,CAAC;QAAC,MAAM,CAAC;YACP,sDAAsD;QACxD,CAAC;QAED,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,kEAAkE;YAClE,2CAA2C;YAC3C,OAAO,GAAG,EAAE,EAAE,EAAE,eAAe,EAAE,aAAa,EAAE,IAAI,EAAyB,CAAC;QAChF,CAAC;QAED,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IAC1C,CAAC;CACF"}