@draftlab/auth 0.4.0 → 0.5.0

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/{google.d.ts → google.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/google.d.ts
 

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

@@ -1,7 +1,51 @@
-import { Oauth2Provider } from "./oauth2.js";
+import { Oauth2Provider } from "./oauth2.mjs";
 
 //#region src/provider/google.ts
 /**
+* Google OAuth 2.0 authentication provider for Draft Auth.
+* Provides access tokens for calling Google APIs on behalf of users.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { GoogleProvider } from "@draftlab/auth/provider/google"
+*
+* export default issuer({
+*   providers: {
+*     google: GoogleProvider({
+*       clientID: process.env.GOOGLE_CLIENT_ID,
+*       clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+*       scopes: ["profile", "email", "https://www.googleapis.com/auth/calendar.readonly"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Configuration Options
+*
+* - Access tokens for Google API calls
+* - Refresh tokens for long-lived access
+* - Support for offline access
+* - Custom scopes for specific Google services
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "google") {
+*     // Access token for API calls: value.tokenset.access
+*     // Refresh token (if requested): value.tokenset.refresh
+*     // Use the access token to call Google APIs
+*     const response = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+*       headers: { Authorization: `Bearer ${value.tokenset.access}` }
+*     })
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates a Google OAuth 2.0 authentication provider.
 * Use this when you need access tokens to call Google APIs on behalf of the user.
 *

package/dist/provider/{linkedin.d.ts → linkedin.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/linkedin.d.ts
 

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

@@ -1,7 +1,63 @@
-import { Oauth2Provider } from "./oauth2.js";
+import { Oauth2Provider } from "./oauth2.mjs";
 
 //#region src/provider/linkedin.ts
 /**
+* LinkedIn OAuth 2.0 authentication provider for Draft Auth.
+* Provides access tokens for calling LinkedIn APIs on behalf of users.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { LinkedInProvider } from "@draftlab/auth/provider/linkedin"
+*
+* export default issuer({
+*   providers: {
+*     linkedin: LinkedInProvider({
+*       clientID: process.env.LINKEDIN_CLIENT_ID,
+*       clientSecret: process.env.LINKEDIN_CLIENT_SECRET,
+*       scopes: ["r_liteprofile", "r_emailaddress", "w_member_social"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Common Scopes
+*
+* - `r_liteprofile` - Access to basic profile information
+* - `r_emailaddress` - Access to user's email address
+* - `r_basicprofile` - Access to full profile information (deprecated)
+* - `w_member_social` - Share content on behalf of user
+* - `r_organization_social` - Access to organization social content
+* - `rw_organization_admin` - Manage organization pages
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "linkedin") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user profile
+*     const profileResponse = await fetch('https://api.linkedin.com/v2/people/~', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const profile = await profileResponse.json()
+*
+*     // Fetch user email (requires r_emailaddress scope)
+*     const emailResponse = await fetch('https://api.linkedin.com/v2/emailAddress?q=members&projection=(elements*(handle~))', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const emailData = await emailResponse.json()
+*
+*     // User info: profile.localizedFirstName + profile.localizedLastName
+*     // Email: emailData.elements[0]['handle~'].emailAddress
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates a LinkedIn OAuth 2.0 authentication provider.
 * Use this when you need access tokens to call LinkedIn APIs on behalf of the user.
 *

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

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

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

@@ -1,4 +1,4 @@
-import { generateUnbiasedDigits, timingSafeCompare } from "../random.js";
+import { generateUnbiasedDigits, timingSafeCompare } from "../random.mjs";
 
 //#region src/provider/magiclink.ts
 /**
@@ -41,8 +41,7 @@ const MagicLinkProvider = (config) => {
 				const action = formData.get("action")?.toString();
 				if (action === "request" || action === "resend") {
 					const token = generateToken();
-					const formEntries = Object.fromEntries(formData);
-					const { action: _,...claims } = formEntries;
+					const { action: _, ...claims } = Object.fromEntries(formData);
 					const baseUrl = new URL(c.request.url).origin;
 					const magicUrl = new URL(`/auth/${ctx.name}/verify`, baseUrl);
 					magicUrl.searchParams.set("token", token);
@@ -69,13 +68,12 @@ const MagicLinkProvider = (config) => {
 				if (!timingSafeCompare(storedState.token, token)) return transition(c, { type: "start" }, void 0, { type: "invalid_link" });
 				const urlClaims = {};
 				for (const [key, value] of url.searchParams) if (key !== "token" && value) urlClaims[key] = value;
-				const claimsMatch = Object.keys(storedState.claims).every((key) => {
+				if (!Object.keys(storedState.claims).every((key) => {
 					const urlValue = urlClaims[key];
 					const storedValue = storedState.claims[key];
 					if (!urlValue || !storedValue) return false;
 					return timingSafeCompare(storedValue, urlValue);
-				});
-				if (!claimsMatch) return transition(c, { type: "start" }, void 0, { type: "invalid_link" });
+				})) return transition(c, { type: "start" }, void 0, { type: "invalid_link" });
 				await ctx.unset(c, "provider");
 				return await ctx.success(c, { claims: storedState.claims });
 			});

package/dist/provider/{microsoft.d.ts → microsoft.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/microsoft.d.ts
 

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

@@ -1,7 +1,74 @@
-import { Oauth2Provider } from "./oauth2.js";
+import { Oauth2Provider } from "./oauth2.mjs";
 
 //#region src/provider/microsoft.ts
 /**
+* Microsoft OAuth 2.0 authentication provider for Draft Auth.
+* Supports Microsoft personal accounts, work accounts, and Azure AD.
+* Provides access tokens for calling Microsoft Graph APIs on behalf of users.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { MicrosoftProvider } from "@draftlab/auth/provider/microsoft"
+*
+* export default issuer({
+*   providers: {
+*     microsoft: MicrosoftProvider({
+*       tenant: "common", // or specific tenant ID
+*       clientID: process.env.MICROSOFT_CLIENT_ID,
+*       clientSecret: process.env.MICROSOFT_CLIENT_SECRET,
+*       scopes: ["openid", "profile", "email", "User.Read"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Tenant Configuration
+*
+* - `common` - Both personal and work/school accounts
+* - `organizations` - Work/school accounts only
+* - `consumers` - Personal Microsoft accounts only
+* - `{tenant-id}` - Specific Azure AD tenant only
+*
+* ## Common Scopes
+*
+* - `openid` - Basic OpenID Connect sign-in
+* - `profile` - User's basic profile information
+* - `email` - User's email address
+* - `User.Read` - Read user's profile via Microsoft Graph
+* - `Mail.Read` - Read user's mail
+* - `Calendars.Read` - Read user's calendars
+* - `Files.Read` - Read user's files in OneDrive
+* - `Sites.Read.All` - Read SharePoint sites
+* - `Directory.Read.All` - Read directory data (requires admin consent)
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "microsoft") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user profile via Microsoft Graph
+*     const userResponse = await fetch('https://graph.microsoft.com/v1.0/me', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const user = await userResponse.json()
+*
+*     // Fetch user photo (requires User.Read scope)
+*     const photoResponse = await fetch('https://graph.microsoft.com/v1.0/me/photo/$value', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const photoBlob = await photoResponse.blob()
+*
+*     // User info: user.displayName, user.mail, user.userPrincipalName
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
 * Creates a Microsoft OAuth 2.0 authentication provider.
 * Use this when you need access tokens to call Microsoft Graph APIs on behalf of the user.
 *

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

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

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

@@ -1,7 +1,7 @@
-import { getRelativeUrl } from "../util.js";
-import { OauthError } from "../error.js";
-import { generatePKCE } from "../pkce.js";
-import { generateSecureToken, timingSafeCompare } from "../random.js";
+import { getRelativeUrl } from "../util.mjs";
+import { OauthError } from "../error.mjs";
+import { generatePKCE } from "../pkce.mjs";
+import { generateSecureToken, timingSafeCompare } from "../random.mjs";
 
 //#region src/provider/oauth2.ts
 /**

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

@@ -1,4 +1,4 @@
-import { Provider } from "./provider.js";
+import { Provider } from "./provider.mjs";
 import { AuthenticatorSelectionCriteria, AuthenticatorTransportFuture, Base64URLString, CredentialDeviceType } from "@simplewebauthn/server";
 
 //#region src/provider/passkey.d.ts

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

@@ -1,4 +1,4 @@
-import { Storage } from "../storage/storage.js";
+import { Storage } from "../storage/storage.mjs";
 import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthenticationResponse, verifyRegistrationResponse } from "@simplewebauthn/server";
 
 //#region src/provider/passkey.ts
@@ -12,8 +12,7 @@ import { generateAuthenticationOptions, generateRegistrationOptions, verifyAuthe
 const uint8ArrayToBase64Url = (bytes) => {
 	let str = "";
 	for (const charCode of bytes) str += String.fromCharCode(charCode);
-	const base64String = btoa(str);
-	return base64String.replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
+	return btoa(str).replace(/\+/g, "-").replace(/\//g, "_").replace(/=/g, "");
 };
 /**
 * Converts a Base64URL encoded string back to a Uint8Array.
@@ -150,8 +149,7 @@ const PasskeyProvider = (config) => {
 				const username = c.query("username") || userId;
 				let user = await getStoredUserById(userId);
 				if (config.userCanRegisterPasskey) {
-					const isAllowed = await config.userCanRegisterPasskey(userId, c.request);
-					if (!isAllowed) return c.json({ error: copy.error_user_not_allowed }, { status: 403 });
+					if (!await config.userCanRegisterPasskey(userId, c.request)) return c.json({ error: copy.error_user_not_allowed }, { status: 403 });
 				}
 				if (!user) {
 					user = {
@@ -252,14 +250,12 @@ const PasskeyProvider = (config) => {
 				if (!rpID) return c.json({ error: "RP ID for authentication is required." }, { status: 400 });
 				const userForAuth = await getStoredUserById(userId);
 				if (!userForAuth) return c.json({ error: "User not found for authentication." }, { status: 404 });
-				const userPasskeys = await getStoredUserPasskeys(userForAuth.id);
-				const allowCredentialsList = userPasskeys.map((pk) => ({
-					id: pk.id,
-					transports: pk.transports
-				}));
 				const authOptions = await generateAuthenticationOptions({
 					rpID,
-					allowCredentials: allowCredentialsList,
+					allowCredentials: (await getStoredUserPasskeys(userForAuth.id)).map((pk) => ({
+						id: pk.id,
+						transports: pk.transports
+					})),
 					userVerification: authenticatorSelection?.userVerification ?? "preferred",
 					timeout
 				});
@@ -290,7 +286,7 @@ const PasskeyProvider = (config) => {
 				if (!publicKey || typeof counter !== "number" || !transports) return c.json({ error: "Passkey not found for authentication." }, { status: 400 });
 				const challenge = authOptions.challenge;
 				if (!challenge) return c.json({ error: "Authentication challenge not found." }, { status: 400 });
-				const verification = await verifyAuthenticationResponse({
+				const { verified, authenticationInfo } = await verifyAuthenticationResponse({
 					response: body,
 					expectedChallenge: challenge,
 					expectedOrigin: origin || "",
@@ -302,7 +298,6 @@ const PasskeyProvider = (config) => {
 						transports
 					}
 				});
-				const { verified, authenticationInfo } = verification;
 				if (verified) {
 					await updateStoredPasskeyCounter(user.id, passkey.id, authenticationInfo.newCounter);
 					return ctx.success(c, {

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

@@ -1,4 +1,4 @@
-import { Provider } from "./provider.js";
+import { Provider } from "./provider.mjs";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 
 //#region src/provider/password.d.ts