@draftlab/auth 0.14.0 → 0.15.1

package/dist/provider/oauth2.mjs

@@ -6,6 +6,63 @@ import { createRemoteJWKSet, jwtVerify } from "jose";
 
 //#region src/provider/oauth2.ts
 /**
+* OAuth 2.0 authentication provider for Draft Auth.
+* Implements the Authorization Code Grant flow with optional PKCE support.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { Oauth2Provider } from "@draftlab/auth/provider/oauth2"
+*
+* export default issuer({
+*   providers: {
+*     github: 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"]
+*     }),
+*     discord: Oauth2Provider({
+*       clientID: process.env.DISCORD_CLIENT_ID,
+*       clientSecret: process.env.DISCORD_CLIENT_SECRET,
+*       endpoint: {
+*         authorization: "https://discord.com/api/oauth2/authorize",
+*         token: "https://discord.com/api/oauth2/token"
+*       },
+*       scopes: ["identify", "email"],
+*       pkce: true // Required by some providers
+*     })
+*   }
+* })
+* ```
+*
+* ## Features
+*
+* - **Authorization Code Grant**: Secure server-side OAuth 2.0 flow
+* - **PKCE Support**: Optional Proof Key for Code Exchange for enhanced security
+* - **Flexible Endpoints**: Configure custom authorization and token endpoints
+* - **Custom Parameters**: Support for provider-specific authorization parameters
+*
+* ## User Data
+*
+* The provider returns access tokens:
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "oauth2") {
+*     // Access token for API calls: value.tokenset.access
+*     // Refresh token (if provided): value.tokenset.refresh
+*     // Client ID used: value.clientID
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates an OAuth 2.0 authentication provider.
 * Implements the Authorization Code Grant flow with optional PKCE support.
 *

package/dist/provider/passkey.d.mts

@@ -2,7 +2,6 @@ import { Provider } from "./provider.mjs";
 import { AuthenticatorSelectionCriteria, AuthenticatorTransportFuture, Base64URLString, CredentialDeviceType } from "@simplewebauthn/server";
 
 //#region src/provider/passkey.d.ts
-
 /**
  * User model for passkey authentication.
  * Contains the core user data needed for WebAuthn operations.
@@ -41,44 +40,44 @@ declare const DEFAULT_COPY: {
  */
 interface PasskeyProviderConfig {
   /**
-   * Custom authorization handler that generates the UI for authorization.
-   */
+       * Custom authorization handler that generates the UI for authorization.
+       */
   authorize: (req: Request) => Promise<Response>;
   /**
-   * Custom registration handler that generates the UI for registration.
-   */
+       * Custom registration handler that generates the UI for registration.
+       */
   register: (req: Request) => Promise<Response>;
   /**
-   * The human-readable name of the relying party (your application).
-   */
+       * The human-readable name of the relying party (your application).
+       */
   rpName: string;
   /**
-   * The ID of the relying party, typically the domain name without protocol.
-   */
+       * The ID of the relying party, typically the domain name without protocol.
+       */
   rpID?: string;
   /**
-   * The origin URL(s) that are allowed to initiate WebAuthn ceremonies.
-   */
+       * The origin URL(s) that are allowed to initiate WebAuthn ceremonies.
+       */
   origin?: string | string[];
   /**
-   * Optional function to check if a user is allowed to register a passkey.
-   */
+       * Optional function to check if a user is allowed to register a passkey.
+       */
   userCanRegisterPasskey?: (userId: string, req: Request) => Promise<boolean>;
   /**
-   * Optional WebAuthn authenticator selection criteria.
-   */
+       * Optional WebAuthn authenticator selection criteria.
+       */
   authenticatorSelection?: AuthenticatorSelectionCriteria;
   /**
-   * Optional attestation type.
-   */
+       * Optional attestation type.
+       */
   attestationType?: "none" | "direct" | "enterprise";
   /**
-   * Optional timeout for challenges in milliseconds.
-   */
+       * Optional timeout for challenges in milliseconds.
+       */
   timeout?: number;
   /**
-   * Custom copy texts for error messages and UI elements.
-   */
+       * Custom copy texts for error messages and UI elements.
+       */
   copy?: Partial<typeof DEFAULT_COPY>;
 }
 /**

package/dist/provider/password.d.mts

@@ -2,7 +2,6 @@ import { Provider } from "./provider.mjs";
 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.
@@ -69,19 +68,19 @@ import { StandardSchemaV1 } from "@standard-schema/spec";
  */
 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
-   */
+       * 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
-   */
+       * 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>;
 }
 /**
@@ -89,158 +88,158 @@ interface PasswordHasher<T> {
  */
 interface PasswordConfig {
   /**
-   * Length of verification codes sent to users.
-   * @internal
-   * @default 6
-   */
+       * Length of verification codes sent to users.
+       * @internal
+       * @default 6
+       */
   readonly length?: number;
   /**
-   * Password hashing implementation to use.
-   * @internal
-   * @default ScryptHasher()
-   */
+       * 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' }
-   *   })
-   * }
-   * ```
-   */
+       * 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))
-   *   }
-   * }
-   * ```
-   */
+       * 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))
-   *   }
-   * }
-   * ```
-   */
+       * 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.
-   *
-   * The context parameter indicates why the code is being sent:
-   * - "register": User is registering for the first time
-   * - "register:resend": User requested to resend registration code
-   * - "reset": User is resetting their password
-   * - "reset:resend": User requested to resend password reset code
-   *
-   * @param email - The recipient's email address
-   * @param code - The verification code to send
-   * @param context - The context of why the code is being sent
-   * @returns Promise that resolves when email is sent
-   *
-   * @example
-   * ```ts
-   * sendCode: async (email, code, context) => {
-   *   const templates = {
-   *     "register": {
-   *       subject: "Welcome! Verify your email",
-   *       body: `Welcome! Your verification code is: ${code}`
-   *     },
-   *     "register:resend": {
-   *       subject: "Your verification code (resent)",
-   *       body: `Here's your code again: ${code}`
-   *     },
-   *     "reset": {
-   *       subject: "Reset your password",
-   *       body: `Your password reset code is: ${code}`
-   *     },
-   *     "reset:resend": {
-   *       subject: "Password reset code (resent)",
-   *       body: `Here's your reset code again: ${code}`
-   *     }
-   *   }
-   *
-   *   const template = templates[context]
-   *   await emailService.send({
-   *     to: email,
-   *     subject: template.subject,
-   *     text: template.body
-   *   })
-   * }
-   * ```
-   */
+       * Callback for sending verification codes to users via email.
+       * Implement this to integrate with your email service provider.
+       *
+       * The context parameter indicates why the code is being sent:
+       * - "register": User is registering for the first time
+       * - "register:resend": User requested to resend registration code
+       * - "reset": User is resetting their password
+       * - "reset:resend": User requested to resend password reset code
+       *
+       * @param email - The recipient's email address
+       * @param code - The verification code to send
+       * @param context - The context of why the code is being sent
+       * @returns Promise that resolves when email is sent
+       *
+       * @example
+       * ```ts
+       * sendCode: async (email, code, context) => {
+       *   const templates = {
+       *     "register": {
+       *       subject: "Welcome! Verify your email",
+       *       body: `Welcome! Your verification code is: ${code}`
+       *     },
+       *     "register:resend": {
+       *       subject: "Your verification code (resent)",
+       *       body: `Here's your code again: ${code}`
+       *     },
+       *     "reset": {
+       *       subject: "Reset your password",
+       *       body: `Your password reset code is: ${code}`
+       *     },
+       *     "reset:resend": {
+       *       subject: "Password reset code (resent)",
+       *       body: `Here's your reset code again: ${code}`
+       *     }
+       *   }
+       *
+       *   const template = templates[context]
+       *   await emailService.send({
+       *     to: email,
+       *     subject: template.subject,
+       *     text: template.body
+       *   })
+       * }
+       * ```
+       */
   sendCode: (email: string, code: string, context: "register" | "register:resend" | "reset" | "reset:resend") => 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")
-   * )
-   * ```
-   */
+       * 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);
 }
 /**
@@ -248,95 +247,68 @@ interface PasswordConfig {
  * The registration process moves through these states sequentially.
  */
 type PasswordRegisterState = {
-  /** Initial state: user enters email and password */
-  readonly type: "start";
+  /** 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) */
+  /** 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 verification code entered is incorrect */readonly type: "invalid_code";
 } | {
-  /** The email address is already registered */
-  readonly type: "email_taken";
+  /** The email address is already registered */readonly type: "email_taken";
 } | {
-  /** The email address format is invalid */
-  readonly type: "invalid_email";
+  /** The email address format is invalid */readonly type: "invalid_email";
 } | {
-  /** The password does not meet requirements */
-  readonly type: "invalid_password";
+  /** The password does not meet requirements */readonly type: "invalid_password";
 } | {
-  /** Password and confirmation password don't match */
-  readonly type: "password_mismatch";
+  /** Password and confirmation password don't match */readonly type: "password_mismatch";
 } | {
-  /** Custom validation error from validatePassword callback */
-  readonly type: "validation_error";
+  /** 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 */
+  /** 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 */
+  /** 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 */
+  /** 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 email address format is invalid */readonly type: "invalid_email";
 } | {
-  /** The verification code entered is incorrect */
-  readonly type: "invalid_code";
+  /** The verification code entered is incorrect */readonly type: "invalid_code";
 } | {
-  /** The new password does not meet requirements */
-  readonly type: "invalid_password";
+  /** The new password does not meet requirements */readonly type: "invalid_password";
 } | {
-  /** New password and confirmation don't match */
-  readonly type: "password_mismatch";
+  /** New password and confirmation don't match */readonly type: "password_mismatch";
 } | {
-  /** Custom validation error from validatePassword callback */
-  readonly type: "validation_error";
+  /** 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 email address format is invalid */readonly type: "invalid_email";
 } | {
-  /** The password is incorrect or email not found */
-  readonly type: "invalid_password";
+  /** The password is incorrect or email not found */readonly type: "invalid_password";
 };
 /**
  * User data returned by successful password authentication.