@draftlab/auth 0.15.0 → 0.16.0

package/dist/provider/apple.d.mts

@@ -1,111 +0,0 @@
-import { Provider } from "./provider.mjs";
-import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
-
-//#region src/provider/apple.d.ts
-
-/**
- * Configuration options for Apple OAuth 2.0 provider.
- * Extends the base OAuth 2.0 configuration with Apple-specific documentation.
- */
-interface AppleConfig extends Oauth2WrappedConfig {
-  /**
-   * Apple Service ID (app identifier for your Sign in with Apple implementation).
-   * Get this from your Apple Developer account when creating a Service ID.
-   *
-   * @example
-   * ```ts
-   * {
-   *   clientID: "com.example.app.signin"
-   * }
-   * ```
-   */
-  readonly clientID: string;
-  /**
-   * Apple client secret (JWT token signed with your private key).
-   * This is different from other providers - Apple requires a JWT token
-   * generated from your private key.
-   *
-   * @example
-   * ```ts
-   * {
-   *   clientSecret: process.env.APPLE_CLIENT_SECRET
-   * }
-   * ```
-   */
-  readonly clientSecret: string;
-  /**
-   * Apple OAuth scopes to request access for.
-   * Apple only supports "name" and "email" scopes.
-   *
-   * Important: Apple only provides user data (name, email) on the FIRST authorization.
-   * Subsequent authorizations won't include this data.
-   *
-   * @example
-   * ```ts
-   * {
-   *   scopes: ["name", "email"]
-   * }
-   * ```
-   */
-  readonly scopes: string[];
-}
-/**
- * Creates an Apple OAuth 2.0 authentication provider.
- * Allows users to authenticate using their Apple accounts.
- *
- * @param config - Apple OAuth 2.0 configuration
- * @returns OAuth 2.0 provider configured for Apple
- *
- * @example
- * ```ts
- * // Basic Apple authentication
- * const basicApple = AppleProvider({
- *   clientID: process.env.APPLE_CLIENT_ID,
- *   clientSecret: process.env.APPLE_CLIENT_SECRET
- * })
- *
- * // Apple with name and email scopes
- * const appleWithScopes = AppleProvider({
- *   clientID: process.env.APPLE_CLIENT_ID,
- *   clientSecret: process.env.APPLE_CLIENT_SECRET,
- *   scopes: ["name", "email"]
- * })
- *
- * // Using the tokens and id_token
- * export default issuer({
- *   providers: { apple: appleWithScopes },
- *   success: async (ctx, value) => {
- *     if (value.provider === "apple") {
- *       // Apple returns user data in the initial authorization response
- *       // You need to decode the id_token to extract user information
- *
- *       // The id_token contains:
- *       // - sub: unique Apple user identifier
- *       // - email: user email (only on first authorization)
- *       // - email_verified: whether email is verified
- *       // - is_private_email: whether user used private relay
- *
- *       // Decode and verify the id_token using jose:
- *       // const verified = await jwtVerify(value.tokenset.id, jwks)
- *       // const user = verified.payload
- *
- *       return ctx.subject("user", {
- *         appleId: user.sub,
- *         email: user.email,
- *         emailVerified: user.email_verified,
- *         isPrivateEmail: user.is_private_email
- *       })
- *     }
- *   }
- * })
- * ```
- *
- * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
- * - Development: `http://localhost:3000/auth/apple/callback`
- * - Production: `https://yourapp.com/auth/apple/callback`
- *
- * Register this URL in your Apple Developer Portal.
- */
-declare const AppleProvider: (config: AppleConfig) => Provider<Oauth2UserData>;
-//#endregion
-export { AppleConfig, AppleProvider };

package/dist/provider/apple.mjs

@@ -1,164 +0,0 @@
-import { Oauth2Provider } from "./oauth2.mjs";
-
-//#region src/provider/apple.ts
-/**
-* Apple authentication provider for Draft Auth.
-* Implements OAuth 2.0 flow for authenticating users with their Apple accounts.
-*
-* ## Quick Setup
-*
-* ```ts
-* import { AppleProvider } from "@draftlab/auth/provider/apple"
-*
-* export default issuer({
-*   basePath: "/auth", // Important for callback URL
-*   providers: {
-*     apple: AppleProvider({
-*       clientID: process.env.APPLE_CLIENT_ID,
-*       clientSecret: process.env.APPLE_CLIENT_SECRET,
-*       scopes: ["name", "email"]
-*     })
-*   }
-* })
-* ```
-*
-* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
-* - Development: `http://localhost:3000/auth/apple/callback`
-* - Production: `https://yourapp.com/auth/apple/callback`
-*
-* Register this URL in your Apple Developer Portal.
-*
-* ## Setup Instructions
-*
-* ### 1. Create App ID
-* - Go to [Apple Developer](https://developer.apple.com)
-* - Create a new App ID with "Sign in with Apple" capability
-*
-* ### 2. Create Service ID
-* - Create a new Service ID (this is your clientID)
-* - Configure "Sign in with Apple"
-* - Add your redirect URI
-*
-* ### 3. Create Private Key
-* - Create a private key for "Sign in with Apple"
-* - Download the .p8 file (this is used to create your clientSecret)
-*
-* ## Client Secret Generation
-*
-* Apple requires a JWT token as the client secret. You'll need:
-* - Key ID from the private key
-* - Team ID from your Apple Developer account
-* - Private key (.p8 file)
-*
-* Use a library to generate the JWT (valid for ~15 minutes):
-*
-* ```ts
-* import { SignJWT } from "jose"
-*
-* const secret = await new SignJWT({
-*   iss: "YOUR_TEAM_ID",
-*   aud: "https://appleid.apple.com",
-*   sub: process.env.APPLE_CLIENT_ID,
-*   iat: Math.floor(Date.now() / 1000),
-*   exp: Math.floor(Date.now() / 1000) + 15 * 60
-* })
-*   .setProtectedHeader({ alg: "ES256", kid: "YOUR_KEY_ID" })
-*   .sign(privateKey)
-* ```
-*
-* ## Common Scopes
-*
-* - `name` - Access user's name (first and last name)
-* - `email` - Access user's email address
-*
-* Note: Apple only returns user data on the first authorization. Subsequent authorizations won't include name/email.
-*
-* ## User Data Access
-*
-* ```ts
-* success: async (ctx, value) => {
-*   if (value.provider === "apple") {
-*     const accessToken = value.tokenset.access
-*
-*     // Apple doesn't provide a userinfo endpoint
-*     // User data is returned in the authorization response
-*     // You need to parse the id_token JWT to get user info
-*
-*     // For subsequent logins without name/email, use the subject (user_id)
-*     // from the ID token to identify the user
-*   }
-* }
-* ```
-*
-* @packageDocumentation
-*/
-/**
-* Creates an Apple OAuth 2.0 authentication provider.
-* Allows users to authenticate using their Apple accounts.
-*
-* @param config - Apple OAuth 2.0 configuration
-* @returns OAuth 2.0 provider configured for Apple
-*
-* @example
-* ```ts
-* // Basic Apple authentication
-* const basicApple = AppleProvider({
-*   clientID: process.env.APPLE_CLIENT_ID,
-*   clientSecret: process.env.APPLE_CLIENT_SECRET
-* })
-*
-* // Apple with name and email scopes
-* const appleWithScopes = AppleProvider({
-*   clientID: process.env.APPLE_CLIENT_ID,
-*   clientSecret: process.env.APPLE_CLIENT_SECRET,
-*   scopes: ["name", "email"]
-* })
-*
-* // Using the tokens and id_token
-* export default issuer({
-*   providers: { apple: appleWithScopes },
-*   success: async (ctx, value) => {
-*     if (value.provider === "apple") {
-*       // Apple returns user data in the initial authorization response
-*       // You need to decode the id_token to extract user information
-*
-*       // The id_token contains:
-*       // - sub: unique Apple user identifier
-*       // - email: user email (only on first authorization)
-*       // - email_verified: whether email is verified
-*       // - is_private_email: whether user used private relay
-*
-*       // Decode and verify the id_token using jose:
-*       // const verified = await jwtVerify(value.tokenset.id, jwks)
-*       // const user = verified.payload
-*
-*       return ctx.subject("user", {
-*         appleId: user.sub,
-*         email: user.email,
-*         emailVerified: user.email_verified,
-*         isPrivateEmail: user.is_private_email
-*       })
-*     }
-*   }
-* })
-* ```
-*
-* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
-* - Development: `http://localhost:3000/auth/apple/callback`
-* - Production: `https://yourapp.com/auth/apple/callback`
-*
-* Register this URL in your Apple Developer Portal.
-*/
-const AppleProvider = (config) => {
-	return Oauth2Provider({
-		...config,
-		type: "apple",
-		endpoint: {
-			authorization: "https://appleid.apple.com/auth/authorize",
-			token: "https://appleid.apple.com/auth/token"
-		}
-	});
-};
-
-//#endregion
-export { AppleProvider };

package/dist/provider/code.d.mts

@@ -1,228 +0,0 @@
-import { Provider } from "./provider.mjs";
-
-//#region src/provider/code.d.ts
-
-/**
- * Configuration options for the PIN code authentication provider.
- *
- * @template Claims - Type of claims collected during authentication (email, phone, etc.)
- */
-interface CodeProviderConfig<Claims extends Record<string, string> = Record<string, string>> {
-  /**
-   * The length of the generated PIN code.
-   * Common values are 4, 6, or 8 digits.
-   *
-   * @default 6
-   *
-   * @example
-   * ```ts
-   * {
-   *   length: 4 // 4-digit PIN for easier entry
-   * }
-   * ```
-   */
-  readonly length?: number;
-  /**
-   * Request handler for rendering the authentication UI.
-   * Handles both the initial claim collection and PIN code entry screens.
-   *
-   * @param req - The HTTP request object
-   * @param state - Current authentication state (start or code verification)
-   * @param form - Form data from POST requests (if any)
-   * @param error - Authentication error to display (if any)
-   * @returns Promise resolving to the authentication page response
-   *
-   * @example
-   * ```ts
-   * request: async (req, state, form, error) => {
-   *   if (state.type === 'start') {
-   *     return new Response(renderClaimForm(form, error))
-   *   } else {
-   *     return new Response(renderCodeForm(state.claims.email, error))
-   *   }
-   * }
-   * ```
-   */
-  request: (req: Request, state: CodeProviderState, form?: FormData, error?: CodeProviderError) => Promise<Response>;
-  /**
-   * Callback for sending PIN codes to users via their preferred method.
-   * Should handle delivery via email, SMS, or other communication channels.
-   *
-   * @param claims - User claims containing contact information
-   * @param code - The generated PIN code to send
-   * @returns Promise resolving to undefined on success, or error object on failure
-   *
-   * @example
-   * ```ts
-   * sendCode: async (claims, code) => {
-   *   try {
-   *     if (claims.email) {
-   *       await emailService.send({
-   *         to: claims.email,
-   *         subject: 'Your verification code',
-   *         text: `Your PIN code is: ${code}`
-   *       })
-   *     } else if (claims.phone) {
-   *       await smsService.send(claims.phone, `PIN: ${code}`)
-   *     } else {
-   *       return {
-   *         type: "invalid_claim",
-   *         key: "email",
-   *         value: "Email or phone number is required"
-   *       }
-   *     }
-   *   } catch (error) {
-   *     return {
-   *       type: "invalid_claim",
-   *       key: "delivery",
-   *       value: "Failed to send code"
-   *     }
-   *   }
-   * }
-   * ```
-   */
-  sendCode: (claims: Claims, code: string) => Promise<CodeProviderError | undefined>;
-}
-/**
- * Authentication flow states for the PIN code provider.
- * The provider transitions between these states during authentication.
- */
-type CodeProviderState = {
-  /** Initial state: user enters their claims (email, phone, etc.) */
-  readonly type: "start";
-} | {
-  /** Code verification state: user enters the PIN code */
-  readonly type: "code";
-  /** Whether this is a code resend request */
-  readonly resend?: boolean;
-  /** The generated PIN code for verification */
-  readonly code: string;
-  /** User claims collected during the start phase */
-  readonly claims: Record<string, string>;
-};
-/**
- * Possible errors during PIN code authentication.
- */
-type CodeProviderError = {
-  /** The entered PIN code is incorrect */
-  readonly type: "invalid_code";
-} | {
-  /** A user claim is invalid or missing */
-  readonly type: "invalid_claim";
-  /** The claim field that failed validation */
-  readonly key: string;
-  /** The invalid value or error description */
-  readonly value: string;
-};
-/**
- * User data returned by successful PIN code authentication.
- *
- * @template Claims - Type of claims collected during authentication
- */
-interface CodeUserData<Claims extends Record<string, string> = Record<string, string>> {
-  /** The verified claims collected during authentication */
-  readonly claims: Claims;
-}
-/**
- * Creates a PIN code authentication provider.
- * Implements a flexible claim-based authentication flow with PIN verification.
- *
- * @template Claims - Type of claims to collect (email, phone, username, etc.)
- * @param config - PIN code provider configuration
- * @returns Provider instance implementing PIN code authentication
- *
- * @example
- * ```ts
- * // Email-based PIN authentication
- * const emailCodeProvider = CodeProvider<{ email: string }>({
- *   length: 6,
- *   request: async (req, state, form, error) => {
- *     if (state.type === 'start') {
- *       return new Response(renderEmailForm(form?.get('email'), error))
- *     } else {
- *       return new Response(renderPinForm(state.claims.email, error, state.resend))
- *     }
- *   },
- *   sendCode: async (claims, code) => {
- *     if (!claims.email || !isValidEmail(claims.email)) {
- *       return {
- *         type: "invalid_claim",
- *         key: "email",
- *         value: "Invalid email address"
- *       }
- *     }
- *
- *     try {
- *       await emailService.send(claims.email, `Your verification code: ${code}`)
- *     } catch {
- *       return {
- *         type: "invalid_claim",
- *         key: "delivery",
- *         value: "Failed to send code"
- *       }
- *     }
- *   }
- * })
- *
- * // Multi-channel PIN authentication (email or phone)
- * const flexibleCodeProvider = CodeProvider<{ email?: string; phone?: string }>({
- *   length: 4,
- *   request: async (req, state, form, error) => {
- *     if (state.type === 'start') {
- *       return new Response(renderContactForm(form, error))
- *     } else {
- *       const contact = state.claims.email || state.claims.phone
- *       return new Response(renderPinForm(contact, error))
- *     }
- *   },
- *   sendCode: async (claims, code) => {
- *     try {
- *       if (claims.email) {
- *         await emailService.send(claims.email, `PIN: ${code}`)
- *       } else if (claims.phone) {
- *         await smsService.send(claims.phone, `PIN: ${code}`)
- *       } else {
- *         return {
- *           type: "invalid_claim",
- *           key: "email",
- *           value: "Provide either email or phone number"
- *         }
- *       }
- *     } catch {
- *       return {
- *         type: "invalid_claim",
- *         key: "delivery",
- *         value: "Failed to send code"
- *       }
- *     }
- *   }
- * })
- *
- * // Usage in issuer
- * export default issuer({
- *   providers: {
- *     email: emailCodeProvider,
- *     flexible: flexibleCodeProvider
- *   },
- *   success: async (ctx, value) => {
- *     if (value.provider === "code") {
- *       const email = value.claims.email
- *       const phone = value.claims.phone
- *
- *       // Look up or create user based on verified claims
- *       const userId = await findOrCreateUser({ email, phone })
- *
- *       return ctx.subject("user", { userId, email, phone })
- *     }
- *   }
- * })
- * ```
- */
-declare const CodeProvider: <Claims extends Record<string, string> = Record<string, string>>(config: CodeProviderConfig<Claims>) => Provider<CodeUserData<Claims>>;
-/**
- * Type helper for CodeProvider configuration options.
- * @internal
- */
-type CodeProviderOptions = Parameters<typeof CodeProvider>[0];
-//#endregion
-export { CodeProvider, CodeProviderConfig, CodeProviderError, CodeProviderOptions, CodeProviderState, CodeUserData };