@draftlab/auth 0.8.0 → 0.10.0

package/dist/client.mjs

@@ -201,7 +201,10 @@ const createClient = (input) => {
 		},
 		async verify(subjects, token, options) {
 			try {
-				const jwtResult = await jwtVerify(token, await getJWKS(), { issuer });
+				const jwtResult = await jwtVerify(token, await getJWKS(), {
+					issuer: options?.issuer ?? issuer,
+					...options?.audience && { audience: options.audience }
+				});
 				const validated = await subjects[jwtResult.payload.type]?.["~standard"].validate(jwtResult.payload.properties);
 				if (!validated?.issues && jwtResult.payload.mode === "access") return {
 					success: true,

package/dist/core.d.mts

@@ -6,6 +6,7 @@ import { StorageAdapter } from "./storage/storage.mjs";
 import { Plugin } from "./plugin/types.mjs";
 import { Provider } from "./provider/provider.mjs";
 import { Theme } from "./themes/theme.mjs";
+import { AuthorizationState } from "./types.mjs";
 import { Router } from "@draftlab/auth-router";
 
 //#region src/core.d.ts
@@ -27,26 +28,6 @@ interface OnSuccessResponder<T$1 extends {
     subject?: string;
   }): Promise<Response>;
 }
-/**
- * Authorization state for OAuth 2.0 flows.
- */
-interface AuthorizationState {
-  /** OAuth redirect URI */
-  redirect_uri: string;
-  /** OAuth response type */
-  response_type: string;
-  /** OAuth state parameter for CSRF protection */
-  state: string;
-  /** OAuth client identifier */
-  client_id: string;
-  /** OAuth audience parameter */
-  audience: string;
-  /** PKCE challenge data for code verification */
-  pkce?: {
-    challenge: string;
-    method: "S256";
-  };
-}
 /**
  * Main issuer input configuration interface.
  */
@@ -129,4 +110,4 @@ declare const issuer: <Providers extends Record<string, Provider<unknown>>, Subj
   };
 }>;
 //#endregion
-export { AuthorizationState, OnSuccessResponder, issuer };
+export { OnSuccessResponder, issuer };

package/dist/core.mjs

@@ -139,7 +139,8 @@ const issuer = (input) => {
 				clientID: value.clientID,
 				subject: value.subject,
 				ttl: value.ttl,
-				nextToken: generateSecureToken()
+				nextToken: generateSecureToken(),
+				timeUsed: value.timeUsed
 			};
 			const refreshKey = [
 				"oauth:refresh",
@@ -231,6 +232,7 @@ const issuer = (input) => {
 					subject,
 					redirectURI: authorization.redirect_uri,
 					clientID: authorization.client_id,
+					scopes: authorization.scopes,
 					pkce: authorization.pkce,
 					ttl: {
 						access: subjectOpts?.ttl?.access ?? ttlAccess,
@@ -492,13 +494,51 @@ const issuer = (input) => {
 			credentials: false
 		})],
 		handler: async (c) => {
-			const token = (await c.formData()).get("token")?.toString();
+			const form = await c.formData();
+			const token = form.get("token")?.toString();
+			const tokenTypeHint = form.get("token_type_hint")?.toString();
 			if (!token) {
 				const error$1 = new OauthError("invalid_request", "Missing token parameter");
 				return c.json(error$1.toJSON(), { status: 400 });
 			}
 			try {
-				const expiresAt = Date.now() + ttlRefresh * 1e3;
+				if (tokenTypeHint === "refresh_token") {
+					const splits$1 = token.split(":");
+					const tokenPart$1 = splits$1.pop();
+					if (tokenPart$1 && splits$1.length > 0) {
+						const key = [
+							"oauth:refresh",
+							splits$1.join(":"),
+							tokenPart$1
+						];
+						if (await Storage.get(storage, key)) {
+							await Storage.remove(storage, key);
+							const expiresAt$1 = Date.now() + ttlRefreshRetention * 1e3;
+							await Revocation.revoke(storage, token, expiresAt$1);
+							return c.json({});
+						}
+					}
+				} else if (tokenTypeHint === "access_token") {
+					const expiresAt$1 = Date.now() + ttlAccess * 1e3;
+					await Revocation.revoke(storage, token, expiresAt$1);
+					return c.json({});
+				}
+				const splits = token.split(":");
+				const tokenPart = splits.pop();
+				if (tokenPart && splits.length > 0) {
+					const key = [
+						"oauth:refresh",
+						splits.join(":"),
+						tokenPart
+					];
+					if (await Storage.get(storage, key)) {
+						await Storage.remove(storage, key);
+						const expiresAt$1 = Date.now() + ttlRefreshRetention * 1e3;
+						await Revocation.revoke(storage, token, expiresAt$1);
+						return c.json({});
+					}
+				}
+				const expiresAt = Date.now() + ttlAccess * 1e3;
 				await Revocation.revoke(storage, token, expiresAt);
 				return c.json({});
 			} catch (_err) {
@@ -526,6 +566,7 @@ const issuer = (input) => {
 			client_id,
 			audience,
 			scope,
+			scopes: scope ? scope.split(" ").filter(Boolean) : void 0,
 			...code_challenge && code_challenge_method && { pkce: {
 				challenge: code_challenge,
 				method: code_challenge_method

package/dist/provider/apple.d.mts

@@ -99,6 +99,12 @@ interface AppleConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **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

package/dist/provider/apple.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     apple: AppleProvider({
 *       clientID: process.env.APPLE_CLIENT_ID,
 *       clientSecret: process.env.APPLE_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **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
@@ -135,6 +142,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **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({

package/dist/provider/discord.d.mts

@@ -134,6 +134,12 @@ interface DiscordConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/discord/callback`
+ * - Production: `https://yourapp.com/auth/discord/callback`
+ *
+ * Register this URL in your Discord Developer Portal.
  */
 declare const DiscordProvider: (config: DiscordConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/discord.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     discord: DiscordProvider({
 *       clientID: process.env.DISCORD_CLIENT_ID,
 *       clientSecret: process.env.DISCORD_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/discord/callback`
+* - Production: `https://yourapp.com/auth/discord/callback`
+*
+* Register this URL in your Discord Developer Portal.
+*
 * ## Common Scopes
 *
 * - `identify` - Access to user's basic account information
@@ -127,6 +134,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/discord/callback`
+* - Production: `https://yourapp.com/auth/discord/callback`
+*
+* Register this URL in your Discord Developer Portal.
 */
 const DiscordProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/facebook.d.mts

@@ -130,6 +130,12 @@ interface FacebookConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/facebook/callback`
+ * - Production: `https://yourapp.com/auth/facebook/callback`
+ *
+ * Register this URL in your Facebook App Dashboard.
  */
 declare const FacebookProvider: (config: FacebookConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/facebook.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     facebook: FacebookProvider({
 *       clientID: process.env.FACEBOOK_APP_ID,
 *       clientSecret: process.env.FACEBOOK_APP_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/facebook/callback`
+* - Production: `https://yourapp.com/auth/facebook/callback`
+*
+* Register this URL in your Facebook App Dashboard.
+*
 * ## Configuration Options
 *
 * - Access tokens for Facebook Graph API calls
@@ -121,6 +128,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/facebook/callback`
+* - Production: `https://yourapp.com/auth/facebook/callback`
+*
+* Register this URL in your Facebook App Dashboard.
 */
 const FacebookProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/github.mjs

@@ -11,6 +11,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * import { GithubProvider } from "@draftlab/auth/provider/github"
 *
 * export default issuer({
+*   basePath: "/auth", // Important for callback URL
 *   providers: {
 *     github: GithubProvider({
 *       clientID: process.env.GITHUB_CLIENT_ID,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/github/callback`
+* - Production: `https://yourapp.com/auth/github/callback`
+*
+* Register this URL in your GitHub App/OAuth App settings.
+*
 * ## GitHub App vs OAuth App
 *
 * This provider works with both GitHub OAuth Apps and GitHub Apps:

package/dist/provider/gitlab.d.mts

@@ -94,6 +94,12 @@ interface GitlabConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/gitlab/callback`
+ * - Production: `https://yourapp.com/auth/gitlab/callback`
+ *
+ * Register this URL in your GitLab Application settings.
  */
 declare const GitlabProvider: (config: GitlabConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/gitlab.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     gitlab: GitlabProvider({
 *       clientID: process.env.GITLAB_CLIENT_ID,
 *       clientSecret: process.env.GITLAB_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/gitlab/callback`
+* - Production: `https://yourapp.com/auth/gitlab/callback`
+*
+* Register this URL in your GitLab Application settings.
+*
 * ## Common Scopes
 *
 * - `read_user` - Access user profile
@@ -47,6 +54,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/gitlab/callback`
+* - Production: `https://yourapp.com/auth/gitlab/callback`
+*
+* Register this URL in your GitLab Application settings.
+*
 * ## User Data Access
 *
 * ```ts
@@ -112,6 +125,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/gitlab/callback`
+* - Production: `https://yourapp.com/auth/gitlab/callback`
+*
+* Register this URL in your GitLab Application settings.
 */
 const GitlabProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/google.mjs

@@ -11,6 +11,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * import { GoogleProvider } from "@draftlab/auth/provider/google"
 *
 * export default issuer({
+*   basePath: "/auth", // Important for callback URL
 *   providers: {
 *     google: GoogleProvider({
 *       clientID: process.env.GOOGLE_CLIENT_ID,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/google/callback`
+* - Production: `https://yourapp.com/auth/google/callback`
+*
+* Register this URL in your Google Cloud Console OAuth 2.0 credentials.
+*
 * ## Configuration Options
 *
 * - Access tokens for Google API calls

package/dist/provider/linkedin.d.mts

@@ -120,6 +120,12 @@ interface LinkedInConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/linkedin/callback`
+ * - Production: `https://yourapp.com/auth/linkedin/callback`
+ *
+ * Register this URL in your LinkedIn Developer Portal.
  */
 declare const LinkedInProvider: (config: LinkedInConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/linkedin.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     linkedin: LinkedInProvider({
 *       clientID: process.env.LINKEDIN_CLIENT_ID,
 *       clientSecret: process.env.LINKEDIN_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/linkedin/callback`
+* - Production: `https://yourapp.com/auth/linkedin/callback`
+*
+* Register this URL in your LinkedIn Developer Portal.
+*
 * ## Common Scopes
 *
 * - `r_liteprofile` - Access to basic profile information
@@ -113,6 +120,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/linkedin/callback`
+* - Production: `https://yourapp.com/auth/linkedin/callback`
+*
+* Register this URL in your LinkedIn Developer Portal.
 */
 const LinkedInProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/microsoft.d.mts

@@ -166,6 +166,12 @@ interface MicrosoftConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/microsoft/callback`
+ * - Production: `https://yourapp.com/auth/microsoft/callback`
+ *
+ * Register this URL in your Azure Portal App Registration.
  */
 declare const MicrosoftProvider: (config: MicrosoftConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/microsoft.mjs

@@ -13,6 +13,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     microsoft: MicrosoftProvider({
 *       tenant: "common", // or specific tenant ID
 *       clientID: process.env.MICROSOFT_CLIENT_ID,
@@ -23,6 +24,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/microsoft/callback`
+* - Production: `https://yourapp.com/auth/microsoft/callback`
+*
+* Register this URL in your Azure Portal App Registration.
+*
 * ## Tenant Configuration
 *
 * - `common` - Both personal and work/school accounts
@@ -148,6 +155,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/microsoft/callback`
+* - Production: `https://yourapp.com/auth/microsoft/callback`
+*
+* Register this URL in your Azure Portal App Registration.
 */
 const MicrosoftProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/oauth2.mjs

@@ -2,6 +2,7 @@ import { getRelativeUrl } from "../util.mjs";
 import { OauthError } from "../error.mjs";
 import { generatePKCE } from "../pkce.mjs";
 import { generateSecureToken, timingSafeCompare } from "../random.mjs";
+import { createRemoteJWKSet, jwtVerify } from "jose";
 
 //#region src/provider/oauth2.ts
 /**
@@ -70,6 +71,15 @@ const Oauth2Provider = (config) => {
 			if (!response.ok) throw new Error(`Token request failed with status ${response.status}`);
 			const tokenData = await response.json();
 			if (tokenData.error) throw new OauthError(tokenData.error, tokenData.error_description || "");
+			if (tokenData.id_token && config.endpoint.jwks) try {
+				const jwks = createRemoteJWKSet(new URL(config.endpoint.jwks));
+				await jwtVerify(tokenData.id_token, jwks, {
+					issuer: config.endpoint.authorization.split("/").slice(0, 3).join("/"),
+					clockTolerance: 60
+				});
+			} catch (error) {
+				throw new OauthError("invalid_request", `ID token validation failed: ${error instanceof Error ? error.message : "Unknown error"}`);
+			}
 			return await ctx.success(c, {
 				clientID: config.clientID,
 				tokenset: {

package/dist/provider/reddit.d.mts

@@ -95,6 +95,12 @@ interface RedditConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/reddit/callback`
+ * - Production: `https://yourapp.com/auth/reddit/callback`
+ *
+ * Register this URL in your Reddit App Preferences.
  */
 declare const RedditProvider: (config: RedditConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/reddit.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     reddit: RedditProvider({
 *       clientID: process.env.REDDIT_CLIENT_ID,
 *       clientSecret: process.env.REDDIT_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/reddit/callback`
+* - Production: `https://yourapp.com/auth/reddit/callback`
+*
+* Register this URL in your Reddit App Preferences.
+*
 * ## Common Scopes
 *
 * - `identity` - Access user's identity information
@@ -98,6 +105,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/reddit/callback`
+* - Production: `https://yourapp.com/auth/reddit/callback`
+*
+* Register this URL in your Reddit App Preferences.
 */
 const RedditProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/slack.d.mts

@@ -102,6 +102,12 @@ interface SlackConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/slack/callback`
+ * - Production: `https://yourapp.com/auth/slack/callback`
+ *
+ * Register this URL in your Slack App settings.
  */
 declare const SlackProvider: (config: SlackConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/slack.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     slack: SlackProvider({
 *       clientID: process.env.SLACK_CLIENT_ID,
 *       clientSecret: process.env.SLACK_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/slack/callback`
+* - Production: `https://yourapp.com/auth/slack/callback`
+*
+* Register this URL in your Slack App settings.
+*
 * ## Common Scopes
 *
 * - `users:read` - Access to user profiles
@@ -109,6 +116,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/slack/callback`
+* - Production: `https://yourapp.com/auth/slack/callback`
+*
+* Register this URL in your Slack App settings.
 */
 const SlackProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/spotify.d.mts

@@ -101,6 +101,12 @@ interface SpotifyConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/spotify/callback`
+ * - Production: `https://yourapp.com/auth/spotify/callback`
+ *
+ * Register this URL in your Spotify Developer Dashboard.
  */
 declare const SpotifyProvider: (config: SpotifyConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/spotify.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     spotify: SpotifyProvider({
 *       clientID: process.env.SPOTIFY_CLIENT_ID,
 *       clientSecret: process.env.SPOTIFY_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/spotify/callback`
+* - Production: `https://yourapp.com/auth/spotify/callback`
+*
+* Register this URL in your Spotify Developer Dashboard.
+*
 * ## Common Scopes
 *
 * - `user-read-private` - Access user's private data
@@ -106,6 +113,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/spotify/callback`
+* - Production: `https://yourapp.com/auth/spotify/callback`
+*
+* Register this URL in your Spotify Developer Dashboard.
 */
 const SpotifyProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/twitch.d.mts

@@ -96,6 +96,12 @@ interface TwitchConfig extends Oauth2WrappedConfig {
  *   }
  * })
  * ```
+ *
+ * **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+ * - Development: `http://localhost:3000/auth/twitch/callback`
+ * - Production: `https://yourapp.com/auth/twitch/callback`
+ *
+ * Register this URL in your Twitch Developer Console.
  */
 declare const TwitchProvider: (config: TwitchConfig) => Provider<Oauth2UserData>;
 //#endregion

package/dist/provider/twitch.mjs

@@ -12,6 +12,7 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *
 * export default issuer({
 *   providers: {
+*   basePath: "/auth", // Important for callback URL
 *     twitch: TwitchProvider({
 *       clientID: process.env.TWITCH_CLIENT_ID,
 *       clientSecret: process.env.TWITCH_CLIENT_SECRET,
@@ -21,6 +22,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 * })
 * ```
 *
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/twitch/callback`
+* - Production: `https://yourapp.com/auth/twitch/callback`
+*
+* Register this URL in your Twitch Developer Console.
+*
 * ## Common Scopes
 *
 * - `user:read:email` - Access user's email address
@@ -102,6 +109,12 @@ import { Oauth2Provider } from "./oauth2.mjs";
 *   }
 * })
 * ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Development: `http://localhost:3000/auth/twitch/callback`
+* - Production: `https://yourapp.com/auth/twitch/callback`
+*
+* Register this URL in your Twitch Developer Console.
 */
 const TwitchProvider = (config) => {
 	return Oauth2Provider({

package/dist/provider/vercel.d.mts

@@ -0,0 +1,177 @@
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
+
+//#region src/provider/vercel.d.ts
+
+/**
+ * Configuration options for Vercel OAuth 2.0 + OpenID Connect provider.
+ * Extends the base OAuth 2.0 configuration with Vercel-specific documentation.
+ */
+interface VercelConfig extends Oauth2WrappedConfig {
+  /**
+   * Vercel OAuth App client ID.
+   * Found in your Vercel App settings under the Authentication tab.
+   *
+   * To create an app:
+   * 1. Go to Team Settings → Apps → Create
+   * 2. Configure app details and callback URLs
+   * 3. Copy the Client ID from the Authentication tab
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "oac_abc123xyz789" // Vercel OAuth App Client ID
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * Vercel OAuth App client secret.
+   * Generated in your Vercel App settings under the Authentication tab.
+   * Keep this secure and never expose it to client-side code.
+   *
+   * To generate:
+   * 1. Go to your app's Authentication tab
+   * 2. Click "Generate Client Secret"
+   * 3. Copy and store securely (shown only once)
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.VERCEL_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * OpenID Connect scopes to request.
+   * Controls what user information is included in the ID Token.
+   *
+   * Available scopes (must be enabled in Vercel App dashboard first):
+   * - `openid`: Required for ID Token issuance
+   * - `email`: User's email address
+   * - `profile`: Name, username, and avatar
+   * - `offline_access`: Refresh token for long-lived access (optional)
+   *
+   * **Important**: Enable scopes in: Vercel App → Permissions page
+   *
+   * @example
+   * ```ts
+   * {
+   *   // Basic scopes (usually sufficient)
+   *   scopes: ["openid", "email", "profile"]
+   *
+   *   // With refresh token support (enable offline_access in dashboard first)
+   *   scopes: ["openid", "email", "profile", "offline_access"]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+  /**
+   * Additional query parameters for Vercel OAuth authorization.
+   * Useful for customizing the authorization flow.
+   *
+   * @example
+   * ```ts
+   * {
+   *   query: {
+   *     prompt: "consent"  // Force consent screen every time
+   *   }
+   * }
+   * ```
+   */
+  readonly query?: Record<string, string>;
+}
+/**
+ * Creates a Vercel OAuth 2.0 + OpenID Connect authentication provider.
+ * Implements "Sign in with Vercel" for user authentication.
+ *
+ * This provider uses the standard OAuth 2.0 Authorization Code Grant flow
+ * with PKCE (Proof Key for Code Exchange) for enhanced security.
+ *
+ * @param config - Vercel OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for Vercel
+ *
+ * @example
+ * ```ts
+ * // Basic Vercel authentication (email + profile)
+ * const basicVercel = VercelProvider({
+ *   clientID: process.env.VERCEL_CLIENT_ID,
+ *   clientSecret: process.env.VERCEL_CLIENT_SECRET,
+ *   scopes: ["openid", "email", "profile"]
+ * })
+ *
+ * // Vercel with refresh token support
+ * const vercelWithRefresh = VercelProvider({
+ *   clientID: process.env.VERCEL_CLIENT_ID,
+ *   clientSecret: process.env.VERCEL_CLIENT_SECRET,
+ *   scopes: ["openid", "email", "profile", "offline_access"]
+ * })
+ *
+ * // Minimal setup (only user ID in ID Token)
+ * const minimalVercel = VercelProvider({
+ *   clientID: process.env.VERCEL_CLIENT_ID,
+ *   clientSecret: process.env.VERCEL_CLIENT_SECRET,
+ *   scopes: ["openid"] // Only sub claim in ID Token
+ * })
+ *
+ * // Using the tokens in your app
+ * export default issuer({
+ *   providers: { vercel: vercelWithRefresh },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "vercel") {
+ *       const idToken = value.tokenset.raw.id_token as string | undefined
+ *       const accessToken = value.tokenset.access
+ *       const refreshToken = value.tokenset.refresh
+ *
+ *       if (idToken) {
+ *         // Decode ID Token to access user claims
+ *         // (Already validated by oauth2.ts - signature, issuer, audience, exp)
+ *         const claims = JSON.parse(
+ *           Buffer.from(idToken.split('.')[1], 'base64').toString()
+ *         )
+ *
+ *         // Claims available (depending on scopes):
+ *         // - sub: Vercel user ID (always present)
+ *         // - email: user@example.com (if email scope)
+ *         // - name: "John Doe" (if profile scope)
+ *         // - picture: "https://..." (if profile scope)
+ *         // - preferred_username: "johndoe" (if profile scope)
+ *
+ *         // Optionally call Vercel API for more data
+ *         const userRes = await fetch('https://api.vercel.com/v2/user', {
+ *           headers: { Authorization: `Bearer ${accessToken}` }
+ *         })
+ *         const user = await userRes.json()
+ *
+ *         // Get user's teams
+ *         const teamsRes = await fetch('https://api.vercel.com/v2/teams', {
+ *           headers: { Authorization: `Bearer ${accessToken}` }
+ *         })
+ *         const teams = await teamsRes.json()
+ *
+ *         return ctx.subject("user", {
+ *           vercelId: claims.sub,
+ *           email: claims.email,
+ *           name: claims.name,
+ *           username: claims.preferred_username,
+ *           avatar: claims.picture,
+ *           teamCount: teams.teams?.length || 0
+ *         })
+ *       }
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @remarks
+ * - Requires creating a Vercel App in Team Settings → Apps
+ * - PKCE is enabled by default for enhanced security
+ * - ID Token is automatically validated (signature, issuer, audience, expiration)
+ * - Access tokens expire after 1 hour
+ * - Refresh tokens rotate on each use and last 30 days
+ * - The `openid` scope is required for ID Token issuance
+ */
+declare const VercelProvider: (config: VercelConfig) => Provider<Oauth2UserData>;
+//#endregion
+export { VercelConfig, VercelProvider };

package/dist/provider/vercel.mjs

@@ -0,0 +1,230 @@
+import { Oauth2Provider } from "./oauth2.mjs";
+
+//#region src/provider/vercel.ts
+/**
+* Vercel OAuth 2.0 + OpenID Connect authentication provider for Draft Auth.
+* Implements "Sign in with Vercel" for user authentication.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { VercelProvider } from "@draftlab/auth/provider/vercel"
+*
+* export default issuer({
+*   basePath: "/auth", // Important for callback URL
+*   providers: {
+*     vercel: VercelProvider({
+*       clientID: process.env.VERCEL_CLIENT_ID,
+*       clientSecret: process.env.VERCEL_CLIENT_SECRET,
+*       scopes: ["openid", "email", "profile"]
+*     })
+*   }
+* })
+* ```
+*
+* **Callback URL Pattern**: `{baseURL}{basePath}/{provider}/callback`
+* - Example: `http://localhost:3000/auth/vercel/callback`
+* - Production: `https://yourapp.com/auth/vercel/callback`
+*
+* ## Creating a Vercel App
+*
+* Before using this provider, create a Vercel App in your dashboard:
+*
+* 1. Go to **Team Settings** → **Apps** → **Create**
+* 2. Fill in app name, description, and logo
+* 3. Add **Authorization Callback URLs**:
+*    - Development: `http://localhost:3000/auth/vercel/callback`
+*    - Production: `https://yourapp.com/auth/vercel/callback`
+*    - Pattern: `{baseURL}{basePath}/{provider}/callback`
+* 4. Configure **Scopes** in the app's Permissions page:
+*    - ✅ openid (Required)
+*    - ✅ email
+*    - ✅ profile
+*    - ✅ offline_access (optional, for refresh tokens)
+* 5. Generate a **Client Secret** in the Authentication tab
+* 6. Copy the **Client ID** and **Client Secret**
+*
+* **Important**: You must enable the scopes in the Vercel App dashboard before requesting them!
+*
+* ## Available Scopes
+*
+* - `openid` - **Required**. Enables ID Token issuance for user identification
+* - `email` - Access user's email address in ID Token
+* - `profile` - Access user's name, username, and avatar in ID Token
+* - `offline_access` - Issue a Refresh Token for long-lived access (30 days)
+*
+* ## Tokens Returned
+*
+* - **ID Token**: Signed JWT with user identity claims (verified automatically)
+* - **Access Token**: Bearer token for Vercel API calls (1 hour duration)
+* - **Refresh Token**: Rotates on each use (30 days, requires offline_access scope)
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "vercel") {
+*     // ID Token is automatically validated (signature, issuer, audience, expiration)
+*     const idToken = value.tokenset.raw.id_token as string | undefined
+*     const accessToken = value.tokenset.access
+*     const refreshToken = value.tokenset.refresh
+*
+*     // Decode ID Token to access user claims
+*     if (idToken) {
+*       const claims = JSON.parse(
+*         Buffer.from(idToken.split('.')[1], 'base64').toString()
+*       )
+*
+*       // Claims available (depending on scopes):
+*       // - sub: Unique Vercel user ID (always present)
+*       // - email: User's email (if email scope granted)
+*       // - name: User's full name (if profile scope granted)
+*       // - picture: Avatar URL (if profile scope granted)
+*       // - preferred_username: Vercel username (if profile scope granted)
+*
+*       return ctx.subject("user", {
+*         email: claims.email || claims.sub
+*       })
+*     }
+*   }
+* }
+* ```
+*
+* ## Calling Vercel API
+*
+* Use the access token to call Vercel's REST API:
+*
+* ```ts
+* // Get user information
+* const userRes = await fetch('https://api.vercel.com/v2/user', {
+*   headers: { Authorization: `Bearer ${accessToken}` }
+* })
+*
+* // Get user's teams
+* const teamsRes = await fetch('https://api.vercel.com/v2/teams', {
+*   headers: { Authorization: `Bearer ${accessToken}` }
+* })
+*
+* // Get projects (requires appropriate permissions)
+* const projectsRes = await fetch('https://api.vercel.com/v9/projects', {
+*   headers: { Authorization: `Bearer ${accessToken}` }
+* })
+* ```
+*
+* ## Consent Page
+*
+* The first time a user signs in, Vercel shows a consent page with:
+* - Your app's name and logo
+* - Requested scopes and permissions
+* - Allow/Cancel buttons
+*
+* If the user grants access, they're redirected back with an authorization code.
+* If they cancel, they're redirected with an error parameter.
+*
+* @packageDocumentation
+*/
+/**
+* Creates a Vercel OAuth 2.0 + OpenID Connect authentication provider.
+* Implements "Sign in with Vercel" for user authentication.
+*
+* This provider uses the standard OAuth 2.0 Authorization Code Grant flow
+* with PKCE (Proof Key for Code Exchange) for enhanced security.
+*
+* @param config - Vercel OAuth 2.0 configuration
+* @returns OAuth 2.0 provider configured for Vercel
+*
+* @example
+* ```ts
+* // Basic Vercel authentication (email + profile)
+* const basicVercel = VercelProvider({
+*   clientID: process.env.VERCEL_CLIENT_ID,
+*   clientSecret: process.env.VERCEL_CLIENT_SECRET,
+*   scopes: ["openid", "email", "profile"]
+* })
+*
+* // Vercel with refresh token support
+* const vercelWithRefresh = VercelProvider({
+*   clientID: process.env.VERCEL_CLIENT_ID,
+*   clientSecret: process.env.VERCEL_CLIENT_SECRET,
+*   scopes: ["openid", "email", "profile", "offline_access"]
+* })
+*
+* // Minimal setup (only user ID in ID Token)
+* const minimalVercel = VercelProvider({
+*   clientID: process.env.VERCEL_CLIENT_ID,
+*   clientSecret: process.env.VERCEL_CLIENT_SECRET,
+*   scopes: ["openid"] // Only sub claim in ID Token
+* })
+*
+* // Using the tokens in your app
+* export default issuer({
+*   providers: { vercel: vercelWithRefresh },
+*   success: async (ctx, value) => {
+*     if (value.provider === "vercel") {
+*       const idToken = value.tokenset.raw.id_token as string | undefined
+*       const accessToken = value.tokenset.access
+*       const refreshToken = value.tokenset.refresh
+*
+*       if (idToken) {
+*         // Decode ID Token to access user claims
+*         // (Already validated by oauth2.ts - signature, issuer, audience, exp)
+*         const claims = JSON.parse(
+*           Buffer.from(idToken.split('.')[1], 'base64').toString()
+*         )
+*
+*         // Claims available (depending on scopes):
+*         // - sub: Vercel user ID (always present)
+*         // - email: user@example.com (if email scope)
+*         // - name: "John Doe" (if profile scope)
+*         // - picture: "https://..." (if profile scope)
+*         // - preferred_username: "johndoe" (if profile scope)
+*
+*         // Optionally call Vercel API for more data
+*         const userRes = await fetch('https://api.vercel.com/v2/user', {
+*           headers: { Authorization: `Bearer ${accessToken}` }
+*         })
+*         const user = await userRes.json()
+*
+*         // Get user's teams
+*         const teamsRes = await fetch('https://api.vercel.com/v2/teams', {
+*           headers: { Authorization: `Bearer ${accessToken}` }
+*         })
+*         const teams = await teamsRes.json()
+*
+*         return ctx.subject("user", {
+*           vercelId: claims.sub,
+*           email: claims.email,
+*           name: claims.name,
+*           username: claims.preferred_username,
+*           avatar: claims.picture,
+*           teamCount: teams.teams?.length || 0
+*         })
+*       }
+*     }
+*   }
+* })
+* ```
+*
+* @remarks
+* - Requires creating a Vercel App in Team Settings → Apps
+* - PKCE is enabled by default for enhanced security
+* - ID Token is automatically validated (signature, issuer, audience, expiration)
+* - Access tokens expire after 1 hour
+* - Refresh tokens rotate on each use and last 30 days
+* - The `openid` scope is required for ID Token issuance
+*/
+const VercelProvider = (config) => {
+	return Oauth2Provider({
+		...config,
+		type: "vercel",
+		endpoint: {
+			authorization: "https://vercel.com/oauth/authorize",
+			token: "https://api.vercel.com/login/oauth/token",
+			jwks: "https://vercel.com/.well-known/jwks.json"
+		},
+		pkce: true
+	});
+};
+
+//#endregion
+export { VercelProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftlab/auth",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Core implementation for @draftlab/auth",
   "author": "Matheus Pergoli",
@@ -39,7 +39,7 @@
   "devDependencies": {
     "@types/node": "^24.10.1",
     "@types/qrcode": "^1.5.6",
-    "tsdown": "^0.16.6",
+    "tsdown": "^0.16.8",
     "typescript": "^5.9.3",
     "@draftlab/tsconfig": "0.1.0"
   },
@@ -63,7 +63,7 @@
     "preact": "^10.27.2",
     "preact-render-to-string": "^6.6.3",
     "qrcode": "^1.5.4",
-    "@draftlab/auth-router": "0.1.0"
+    "@draftlab/auth-router": "0.3.0"
   },
   "engines": {
     "node": ">=18"