@draftlab/auth 0.4.1 → 0.6.0

package/dist/plugin/{types.d.ts → types.d.mts}

@@ -1,4 +1,4 @@
-import { StorageAdapter } from "../storage/storage.js";
+import { StorageAdapter } from "../storage/storage.mjs";
 import { RouterContext } from "@draftlab/auth-router/types";
 
 //#region src/plugin/types.d.ts

package/dist/provider/apple.d.mts

@@ -0,0 +1,105 @@
+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
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const AppleProvider: (config: AppleConfig) => Provider<Oauth2UserData>;
+//#endregion
+export { AppleConfig, AppleProvider };

package/dist/provider/apple.mjs

@@ -0,0 +1,151 @@
+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({
+*   providers: {
+*     apple: AppleProvider({
+*       clientID: process.env.APPLE_CLIENT_ID,
+*       clientSecret: process.env.APPLE_CLIENT_SECRET,
+*       scopes: ["name", "email"]
+*     })
+*   }
+* })
+* ```
+*
+* ## 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
+*       })
+*     }
+*   }
+* })
+* ```
+*/
+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.ts → code.d.mts}

@@ -1,4 +1,4 @@
-import { Provider } from "./provider.js";
+import { Provider } from "./provider.mjs";
 
 //#region src/provider/code.d.ts
 

package/dist/provider/{code.js → code.mjs}

@@ -1,4 +1,4 @@
-import { generateUnbiasedDigits, timingSafeCompare } from "../random.js";
+import { generateUnbiasedDigits, timingSafeCompare } from "../random.mjs";
 
 //#region src/provider/code.ts
 /**
@@ -130,8 +130,7 @@ const CodeProvider = (config) => {
 				const action = formData.get("action")?.toString();
 				if (action === "request" || action === "resend") {
 					const code = generateCode();
-					const formEntries = Object.fromEntries(formData);
-					const { action: _,...claims } = formEntries;
+					const { action: _, ...claims } = Object.fromEntries(formData);
 					const sendError = await config.sendCode(claims, code);
 					if (sendError) return transition(c, { type: "start" }, formData, sendError);
 					return transition(c, {

package/dist/provider/{discord.d.ts → discord.d.mts}

@@ -1,5 +1,5 @@
-import { Provider } from "./provider.js";
-import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.js";
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
 
 //#region src/provider/discord.d.ts
 

package/dist/provider/{discord.js → discord.mjs}

@@ -1,7 +1,65 @@
-import { Oauth2Provider } from "./oauth2.js";
+import { Oauth2Provider } from "./oauth2.mjs";
 
 //#region src/provider/discord.ts
 /**
+* Discord OAuth 2.0 authentication provider for Draft Auth.
+* Provides access tokens for calling Discord APIs on behalf of users.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { DiscordProvider } from "@draftlab/auth/provider/discord"
+*
+* export default issuer({
+*   providers: {
+*     discord: DiscordProvider({
+*       clientID: process.env.DISCORD_CLIENT_ID,
+*       clientSecret: process.env.DISCORD_CLIENT_SECRET,
+*       scopes: ["identify", "email", "guilds"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Common Scopes
+*
+* - `identify` - Access to user's basic account information
+* - `email` - Access to user's email address
+* - `guilds` - Access to user's guilds (servers)
+* - `guilds.join` - Ability to join user to guilds
+* - `gdm.join` - Ability to join user to group DMs
+* - `connections` - Access to user's connections (Steam, YouTube, etc.)
+* - `guilds.members.read` - Read guild member information
+* - `bot` - For bot applications (requires additional setup)
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "discord") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user information
+*     const userResponse = await fetch('https://discord.com/api/users/@me', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const user = await userResponse.json()
+*
+*     // Fetch user guilds (requires guilds scope)
+*     const guildsResponse = await fetch('https://discord.com/api/users/@me/guilds', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const guilds = await guildsResponse.json()
+*
+*     // User info: user.username + user.discriminator
+*     // Avatar: `https://cdn.discordapp.com/avatars/${user.id}/${user.avatar}.png`
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates a Discord OAuth 2.0 authentication provider.
 * Use this when you need access tokens to call Discord APIs on behalf of the user.
 *

package/dist/provider/{facebook.d.ts → facebook.d.mts}

@@ -1,5 +1,5 @@
-import { Provider } from "./provider.js";
-import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.js";
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
 
 //#region src/provider/facebook.d.ts
 

package/dist/provider/{facebook.js → facebook.mjs}

@@ -1,7 +1,63 @@
-import { Oauth2Provider } from "./oauth2.js";
+import { Oauth2Provider } from "./oauth2.mjs";
 
 //#region src/provider/facebook.ts
 /**
+* Facebook OAuth 2.0 authentication provider for Draft Auth.
+* Provides access tokens for calling Facebook Graph API on behalf of users.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { FacebookProvider } from "@draftlab/auth/provider/facebook"
+*
+* export default issuer({
+*   providers: {
+*     facebook: FacebookProvider({
+*       clientID: process.env.FACEBOOK_APP_ID,
+*       clientSecret: process.env.FACEBOOK_APP_SECRET,
+*       scopes: ["email", "public_profile", "user_friends"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Configuration Options
+*
+* - Access tokens for Facebook Graph API calls
+* - Support for various Facebook permissions
+* - Access to user data, posts, friends, etc.
+*
+* ## Common Facebook Permissions
+*
+* - `public_profile` - Basic profile information (name, picture, etc.)
+* - `email` - User's email address
+* - `user_friends` - List of user's friends who also use your app
+* - `user_posts` - User's posts on their timeline
+* - `user_photos` - User's photos and albums
+* - `pages_read_engagement` - Read engagement data for Pages
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "facebook") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user profile from Graph API
+*     const profileResponse = await fetch(
+*       `https://graph.facebook.com/me?fields=id,name,email,picture&access_token=${accessToken}`
+*     )
+*     const profile = await profileResponse.json()
+*
+*     // User info: `${profile.name} (${profile.email})`
+*     // Facebook ID: profile.id
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates a Facebook OAuth 2.0 authentication provider.
 * Use this when you need access tokens to call Facebook Graph API on behalf of the user.
 *

package/dist/provider/{github.d.ts → github.d.mts}

@@ -1,5 +1,5 @@
-import { Provider } from "./provider.js";
-import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.js";
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
 
 //#region src/provider/github.d.ts
 

package/dist/provider/{github.js → github.mjs}

@@ -1,7 +1,85 @@
-import { Oauth2Provider } from "./oauth2.js";
+import { Oauth2Provider } from "./oauth2.mjs";
 
 //#region src/provider/github.ts
 /**
+* GitHub authentication provider for Draft Auth.
+* Implements OAuth 2.0 flow for authenticating users with their GitHub accounts.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { GithubProvider } from "@draftlab/auth/provider/github"
+*
+* export default issuer({
+*   providers: {
+*     github: GithubProvider({
+*       clientID: process.env.GITHUB_CLIENT_ID,
+*       clientSecret: process.env.GITHUB_CLIENT_SECRET,
+*       scopes: ["user:email", "read:user"]
+*     })
+*   }
+* })
+* ```
+*
+* ## GitHub App vs OAuth App
+*
+* This provider works with both GitHub OAuth Apps and GitHub Apps:
+*
+* ### OAuth App (Recommended for user authentication)
+* ```ts
+* GithubProvider({
+*   clientID: "your-oauth-app-client-id",
+*   clientSecret: "your-oauth-app-client-secret",
+*   scopes: ["user:email", "read:user"]
+* })
+* ```
+*
+* ### GitHub App (For organization-level integrations)
+* ```ts
+* GithubProvider({
+*   clientID: "your-github-app-client-id",
+*   clientSecret: "your-github-app-client-secret",
+*   scopes: ["user:email", "read:user", "repo"]
+* })
+* ```
+*
+* ## Common Scopes
+*
+* - `user:email` - Access user's email addresses
+* - `read:user` - Read user profile information
+* - `repo` - Access public and private repositories
+* - `public_repo` - Access public repositories only
+* - `read:org` - Read organization membership
+* - `gist` - Create and update gists
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "github") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user information
+*     const userResponse = await fetch('https://api.github.com/user', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const user = await userResponse.json()
+*
+*     // Fetch user emails (requires user:email scope)
+*     const emailsResponse = await fetch('https://api.github.com/user/emails', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const emails = await emailsResponse.json()
+*
+*     // User info: `${user.login} (${user.name})`
+*     // Primary email: emails.find(e => e.primary)?.email
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates a GitHub OAuth 2.0 authentication provider.
 * Supports both GitHub OAuth Apps and GitHub Apps for user authentication.
 *

package/dist/provider/gitlab.d.mts

@@ -0,0 +1,100 @@
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
+
+//#region src/provider/gitlab.d.ts
+
+/**
+ * Configuration options for GitLab OAuth 2.0 provider.
+ * Extends the base OAuth 2.0 configuration with GitLab-specific documentation.
+ */
+interface GitlabConfig extends Oauth2WrappedConfig {
+  /**
+   * GitLab application client ID.
+   * Get this from your GitLab application settings.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "abcdef123456"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * GitLab application client secret.
+   * Keep this secure and never expose it to client-side code.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.GITLAB_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * GitLab OAuth scopes to request access for.
+   * Determines what data and actions your app can access.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: [
+   *     "read_user",        // Access user profile
+   *     "read_api",         // Read-access to API
+   *     "read_repository"   // Access repositories
+   *   ]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+}
+/**
+ * Creates a GitLab OAuth 2.0 authentication provider.
+ * Allows users to authenticate using their GitLab accounts (gitlab.com or self-hosted).
+ *
+ * @param config - GitLab OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for GitLab
+ *
+ * @example
+ * ```ts
+ * // Basic GitLab.com authentication
+ * const basicGitlab = GitlabProvider({
+ *   clientID: process.env.GITLAB_CLIENT_ID,
+ *   clientSecret: process.env.GITLAB_CLIENT_SECRET
+ * })
+ *
+ * // GitLab with read access
+ * const gitlabWithRead = GitlabProvider({
+ *   clientID: process.env.GITLAB_CLIENT_ID,
+ *   clientSecret: process.env.GITLAB_CLIENT_SECRET,
+ *   scopes: ["read_user", "read_api"]
+ * })
+ *
+ * // Using the access token to fetch user data
+ * export default issuer({
+ *   providers: { gitlab: gitlabWithRead },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "gitlab") {
+ *       const token = value.tokenset.access
+ *
+ *       const userRes = await fetch('https://gitlab.com/api/v4/user', {
+ *         headers: { Authorization: `Bearer ${token}` }
+ *       })
+ *       const user = await userRes.json()
+ *
+ *       return ctx.subject("user", {
+ *         gitlabId: user.id,
+ *         username: user.username,
+ *         email: user.email,
+ *         name: user.name,
+ *         avatar: user.avatar_url
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const GitlabProvider: (config: GitlabConfig) => Provider<Oauth2UserData>;
+//#endregion
+export { GitlabConfig, GitlabProvider };