@draftlab/auth 0.0.1

package/dist/oauth2-DtKwtl8p.d.ts

@@ -0,0 +1,176 @@
+import { Provider } from "./provider-CwWMG-1l.js";
+
+//#region src/provider/oauth2.d.ts
+
+/**
+ * Configuration options for the OAuth 2.0 provider.
+ */
+interface Oauth2Config {
+  /**
+   * Provider type identifier for internal use.
+   * @internal
+   * @default "oauth2"
+   */
+  readonly type?: string;
+  /**
+   * The client ID registered with the OAuth 2.0 provider.
+   * This public identifier is used in authorization requests.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "github-app-12345"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * The client secret for authenticating with the OAuth 2.0 provider.
+   * This private credential must be kept secure and not exposed to clients.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.OAUTH_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * OAuth 2.0 endpoint URLs for the authorization and token flows.
+   */
+  readonly endpoint: {
+    /**
+     * The authorization endpoint where users are redirected for authentication.
+     *
+     * @example "https://github.com/login/oauth/authorize"
+     */
+    readonly authorization: string;
+    /**
+     * The token endpoint for exchanging authorization codes for access tokens.
+     *
+     * @example "https://github.com/login/oauth/access_token"
+     */
+    readonly token: string;
+    /**
+     * Optional JWKS endpoint for verifying ID tokens.
+     * Required only if the provider returns ID tokens that need verification.
+     *
+     * @example "https://provider.com/.well-known/jwks.json"
+     */
+    readonly jwks?: string;
+  };
+  /**
+   * OAuth 2.0 scopes to request during authorization.
+   * Scopes define the level of access being requested.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: ["user:email", "read:user", "repo"]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+  /**
+   * Whether to use PKCE (Proof Key for Code Exchange) for enhanced security.
+   * Recommended for public clients and required by some providers.
+   *
+   * @default false
+   *
+   * @example
+   * ```ts
+   * {
+   *   pkce: true // Required for Twitter/X, recommended for mobile apps
+   * }
+   * ```
+   */
+  readonly pkce?: boolean;
+  /**
+   * Additional query parameters to include in the authorization request.
+   * Useful for provider-specific parameters or customizing the auth flow.
+   *
+   * @example
+   * ```ts
+   * {
+   *   query: {
+   *     access_type: "offline",    // Request refresh token
+   *     prompt: "consent",         // Force consent screen
+   *     hd: "mycompany.com"       // Google Workspace domain
+   *   }
+   * }
+   * ```
+   */
+  readonly query?: Record<string, string>;
+}
+/**
+ * OAuth 2.0 configuration without endpoint-specific fields.
+ * Used internally for provider wrapping.
+ * @internal
+ */
+type Oauth2WrappedConfig = Omit<Oauth2Config, "endpoint" | "name">;
+/**
+ * OAuth 2.0 token response containing access tokens and metadata.
+ * Provides a structured interface for token data with lazy property access.
+ * @internal
+ */
+interface Oauth2Token {
+  /** Access token for making authenticated API requests */
+  readonly access: string;
+  /** Refresh token for obtaining new access tokens (if provided) */
+  readonly refresh: string;
+  /** Token expiration time in seconds (if provided) */
+  readonly expiry: number;
+  /** Raw token response from the provider */
+  readonly raw: Record<string, unknown>;
+}
+/**
+ * User data returned by successful OAuth 2.0 authentication.
+ */
+interface Oauth2UserData {
+  /** Token set containing access token, refresh token, and metadata */
+  readonly tokenset: Oauth2Token;
+  /** Client ID used for this authentication */
+  readonly clientID: string;
+}
+/**
+ * Creates an OAuth 2.0 authentication provider.
+ * Implements the Authorization Code Grant flow with optional PKCE support.
+ *
+ * @param config - OAuth 2.0 provider configuration
+ * @returns Provider instance implementing OAuth 2.0 authentication
+ *
+ * @example
+ * ```ts
+ * // GitHub provider with basic configuration
+ * const githubProvider = Oauth2Provider({
+ *   clientID: process.env.GITHUB_CLIENT_ID,
+ *   clientSecret: process.env.GITHUB_CLIENT_SECRET,
+ *   endpoint: {
+ *     authorization: "https://github.com/login/oauth/authorize",
+ *     token: "https://github.com/login/oauth/access_token"
+ *   },
+ *   scopes: ["user:email", "read:user"]
+ * })
+ *
+ * // Provider with PKCE and custom parameters
+ * const customProvider = Oauth2Provider({
+ *   clientID: "my-client-id",
+ *   clientSecret: "my-client-secret",
+ *   endpoint: {
+ *     authorization: "https://provider.com/oauth/authorize",
+ *     token: "https://provider.com/oauth/token",
+ *     jwks: "https://provider.com/.well-known/jwks.json"
+ *   },
+ *   scopes: ["read", "write"],
+ *   pkce: true,
+ *   query: {
+ *     prompt: "consent",
+ *     access_type: "offline"
+ *   }
+ * })
+ * ```
+ */
+declare const Oauth2Provider: (config: Oauth2Config) => Provider<Oauth2UserData>;
+//#endregion
+export { Oauth2Config, Oauth2Provider, Oauth2Token, Oauth2UserData, Oauth2WrappedConfig };

package/dist/password-Cm0dRMwa.d.ts

@@ -0,0 +1,385 @@
+import { Provider } from "./provider-CwWMG-1l.js";
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/provider/password.d.ts
+
+/**
+ * Password-based authentication provider for Draft Auth.
+ * Supports user registration, login, and password changes with email verification.
+ *
+ * ## Quick Setup
+ *
+ * ```ts
+ * import { PasswordUI } from "@draftauth/core/ui/password"
+ * import { PasswordProvider } from "@draftauth/core/provider/password"
+ *
+ * export default issuer({
+ *   providers: {
+ *     password: PasswordProvider(
+ *       PasswordUI({
+ *         copy: {
+ *           error_email_taken: "This email is already taken."
+ *         },
+ *         sendCode: async (email, code) => {
+ *           await sendEmail(email, `Your verification code: ${code}`)
+ *         }
+ *       })
+ *     )
+ *   }
+ * })
+ * ```
+ *
+ * ## Custom UI Implementation
+ *
+ * For full control over the user interface, implement the handlers directly:
+ *
+ * ```ts
+ * PasswordProvider({
+ *   login: async (req, form, error) => {
+ *     return new Response(renderLoginPage(form, error))
+ *   },
+ *   register: async (req, state, form, error) => {
+ *     return new Response(renderRegisterPage(state, form, error))
+ *   },
+ *   change: async (req, state, form, error) => {
+ *     return new Response(renderChangePage(state, form, error))
+ *   },
+ *   sendCode: async (email, code) => {
+ *     await yourEmailService.send(email, code)
+ *   }
+ * })
+ * ```
+ *
+ * ## Features
+ *
+ * - **Email verification**: Secure registration with email confirmation codes
+ * - **Password hashing**: Built-in Scrypt and PBKDF2 support with secure defaults
+ * - **Password validation**: Configurable password strength requirements
+ * - **Password reset**: Secure password change flow with email verification
+ * - **Session management**: Automatic invalidation on password changes
+ *
+ * @packageDocumentation
+ */
+/**
+ * Password hashing interface for secure password storage.
+ * Implement this interface to use custom password hashing algorithms.
+ *
+ * @template T - The hash storage format (usually an object with hash, salt, and params)
+ * @internal
+ */
+interface PasswordHasher<T> {
+  /**
+   * Hashes a plaintext password for secure storage.
+   *
+   * @param password - The plaintext password to hash
+   * @returns Promise resolving to the hash data structure
+   */
+  hash(password: string): Promise<T>;
+  /**
+   * Verifies a plaintext password against a stored hash.
+   *
+   * @param password - The plaintext password to verify
+   * @param compare - The stored hash data to compare against
+   * @returns Promise resolving to true if password matches
+   */
+  verify(password: string, compare: T): Promise<boolean>;
+}
+/**
+ * Configuration for the password authentication provider.
+ */
+interface PasswordConfig {
+  /**
+   * Length of verification codes sent to users.
+   * @internal
+   * @default 6
+   */
+  readonly length?: number;
+  /**
+   * Password hashing implementation to use.
+   * @internal
+   * @default ScryptHasher()
+   */
+  readonly hasher?: PasswordHasher<unknown>;
+  /**
+   * Request handler for rendering the login screen.
+   * Receives the request, optional form data, and any login errors.
+   *
+   * @param req - The HTTP request object
+   * @param form - Form data from POST requests (if any)
+   * @param error - Login error to display (if any)
+   * @returns Promise resolving to the login page response
+   *
+   * @example
+   * ```ts
+   * login: async (req, form, error) => {
+   *   const html = renderLoginPage({
+   *     email: form?.get('email'),
+   *     error: error?.type
+   *   })
+   *   return new Response(html, {
+   *     headers: { 'Content-Type': 'text/html' }
+   *   })
+   * }
+   * ```
+   */
+  login: (req: Request, form?: FormData, error?: PasswordLoginError) => Promise<Response>;
+  /**
+   * Request handler for rendering the registration screen.
+   * Handles both initial registration form and email verification.
+   *
+   * @param req - The HTTP request object
+   * @param state - Current registration state (start or code verification)
+   * @param form - Form data from POST requests (if any)
+   * @param error - Registration error to display (if any)
+   * @returns Promise resolving to the registration page response
+   *
+   * @example
+   * ```ts
+   * register: async (req, state, form, error) => {
+   *   if (state.type === 'start') {
+   *     return new Response(renderRegistrationForm(error))
+   *   } else {
+   *     return new Response(renderCodeVerification(state.email, error))
+   *   }
+   * }
+   * ```
+   */
+  register: (req: Request, state: PasswordRegisterState, form?: FormData, error?: PasswordRegisterError) => Promise<Response>;
+  /**
+   * Request handler for rendering the password change screen.
+   * Handles email entry, code verification, and password update steps.
+   *
+   * @param req - The HTTP request object
+   * @param state - Current password change state
+   * @param form - Form data from POST requests (if any)
+   * @param error - Password change error to display (if any)
+   * @returns Promise resolving to the password change page response
+   *
+   * @example
+   * ```ts
+   * change: async (req, state, form, error) => {
+   *   switch (state.type) {
+   *     case 'start':
+   *       return new Response(renderEmailForm(error))
+   *     case 'code':
+   *       return new Response(renderCodeForm(state.email, error))
+   *     case 'update':
+   *       return new Response(renderPasswordForm(error))
+   *   }
+   * }
+   * ```
+   */
+  change: (req: Request, state: PasswordChangeState, form?: FormData, error?: PasswordChangeError) => Promise<Response>;
+  /**
+   * Callback for sending verification codes to users via email.
+   * Implement this to integrate with your email service provider.
+   *
+   * @param email - The recipient's email address
+   * @param code - The verification code to send
+   * @returns Promise that resolves when email is sent
+   *
+   * @example
+   * ```ts
+   * sendCode: async (email, code) => {
+   *   await emailService.send({
+   *     to: email,
+   *     subject: 'Your verification code',
+   *     text: `Your verification code is: ${code}`
+   *   })
+   * }
+   * ```
+   */
+  sendCode: (email: string, code: string) => Promise<void>;
+  /**
+   * Optional password validation function or schema.
+   * Can be either a validation function or a standard-schema validator.
+   *
+   * @param password - The password to validate
+   * @returns Error message if invalid, undefined if valid
+   *
+   * @example
+   * ```ts
+   * // Function-based validation
+   * validatePassword: (password) => {
+   *   if (password.length < 8) return "Password must be at least 8 characters"
+   *   if (!/[A-Z]/.test(password)) return "Password must contain uppercase letter"
+   *   return undefined
+   * }
+   *
+   * // Schema-based validation
+   * validatePassword: pipe(
+   *   string(),
+   *   minLength(8, "Password must be at least 8 characters"),
+   *   regex(/[A-Z]/, "Password must contain uppercase letter")
+   * )
+   * ```
+   */
+  readonly validatePassword?: StandardSchemaV1 | ((password: string) => Promise<string | undefined> | string | undefined);
+}
+/**
+ * Registration flow states that determine which UI to show.
+ * The registration process moves through these states sequentially.
+ */
+type PasswordRegisterState = {
+  /** Initial state: user enters email and password */
+  readonly type: "start";
+} | {
+  /** Code verification state: user enters emailed verification code */
+  readonly type: "code";
+  /** The verification code sent to the user */
+  readonly code: string;
+  /** The user's email address */
+  readonly email: string;
+  /** The hashed password (ready for storage) */
+  readonly password: unknown;
+};
+/**
+ * Possible errors during user registration.
+ */
+type PasswordRegisterError = {
+  /** The verification code entered is incorrect */
+  readonly type: "invalid_code";
+} | {
+  /** The email address is already registered */
+  readonly type: "email_taken";
+} | {
+  /** The email address format is invalid */
+  readonly type: "invalid_email";
+} | {
+  /** The password does not meet requirements */
+  readonly type: "invalid_password";
+} | {
+  /** Password and confirmation password don't match */
+  readonly type: "password_mismatch";
+} | {
+  /** Custom validation error from validatePassword callback */
+  readonly type: "validation_error";
+  readonly message?: string;
+};
+/**
+ * Password change flow states that determine which UI to show.
+ */
+type PasswordChangeState = {
+  /** Initial state: user enters their email address */
+  readonly type: "start";
+  /** URL to redirect to after successful password change */
+  readonly redirect: string;
+} | {
+  /** Code verification state: user enters emailed verification code */
+  readonly type: "code";
+  /** The verification code sent to the user */
+  readonly code: string;
+  /** The user's email address */
+  readonly email: string;
+  /** URL to redirect to after completion */
+  readonly redirect: string;
+} | {
+  /** Password update state: user enters new password */
+  readonly type: "update";
+  /** URL to redirect to after completion */
+  readonly redirect: string;
+  /** The verified email address */
+  readonly email: string;
+};
+/**
+ * Possible errors during password changes.
+ */
+type PasswordChangeError = {
+  /** The email address format is invalid */
+  readonly type: "invalid_email";
+} | {
+  /** The verification code entered is incorrect */
+  readonly type: "invalid_code";
+} | {
+  /** The new password does not meet requirements */
+  readonly type: "invalid_password";
+} | {
+  /** New password and confirmation don't match */
+  readonly type: "password_mismatch";
+} | {
+  /** Custom validation error from validatePassword callback */
+  readonly type: "validation_error";
+  readonly message: string;
+};
+/**
+ * Possible errors during login attempts.
+ */
+type PasswordLoginError = {
+  /** The email address format is invalid */
+  readonly type: "invalid_email";
+} | {
+  /** The password is incorrect or email not found */
+  readonly type: "invalid_password";
+};
+/**
+ * User data returned by successful password authentication.
+ */
+interface PasswordUserData {
+  /** The authenticated user's email address */
+  readonly email: string;
+}
+/**
+ * Creates a password authentication provider with email verification.
+ * Implements secure registration, login, and password change flows.
+ *
+ * @param config - Provider configuration including UI handlers and email service
+ * @returns Provider instance implementing password authentication
+ *
+ * @example
+ * ```ts
+ * const provider = PasswordProvider({
+ *   login: async (req, form, error) => {
+ *     return new Response(renderLogin(form, error))
+ *   },
+ *   register: async (req, state, form, error) => {
+ *     return new Response(renderRegister(state, form, error))
+ *   },
+ *   change: async (req, state, form, error) => {
+ *     return new Response(renderChange(state, form, error))
+ *   },
+ *   sendCode: async (email, code) => {
+ *     await emailService.send(email, `Code: ${code}`)
+ *   },
+ *   validatePassword: (pwd) => {
+ *     return pwd.length >= 8 ? undefined : "Too short"
+ *   }
+ * })
+ * ```
+ */
+declare const PasswordProvider: (config: PasswordConfig) => Provider<PasswordUserData>;
+/**
+ * PBKDF2 password hasher with configurable iterations.
+ * Good choice for compatibility but slower than Scrypt.
+ *
+ * @param opts - Configuration options
+ * @returns Password hasher using PBKDF2 algorithm
+ * @internal
+ */
+declare const PBKDF2Hasher: (opts?: {
+  iterations?: number;
+}) => PasswordHasher<{
+  hash: string;
+  salt: string;
+  iterations: number;
+}>;
+/**
+ * Scrypt password hasher with secure defaults.
+ * Recommended choice for new applications due to memory-hard properties.
+ *
+ * @param opts - Scrypt parameters (N, r, p)
+ * @returns Password hasher using Scrypt algorithm
+ * @internal
+ */
+declare const ScryptHasher: (opts?: {
+  N?: number;
+  r?: number;
+  p?: number;
+}) => PasswordHasher<{
+  hash: string;
+  salt: string;
+  N: number;
+  r: number;
+  p: number;
+}>;
+//#endregion
+export { PBKDF2Hasher, PasswordChangeError, PasswordChangeState, PasswordConfig, PasswordHasher, PasswordLoginError, PasswordProvider, PasswordRegisterError, PasswordRegisterState, PasswordUserData, ScryptHasher };