@draftlab/auth 0.5.0 → 0.6.0

package/dist/client.d.mts

@@ -252,8 +252,24 @@ interface VerifyResult<T extends SubjectSchema> {
   } }[keyof T];
 }
 /**
- * Options for UserInfo requests.
+ * Options for token revocation.
  */
+interface RevokeOptions {
+  /**
+   * Optional hint about the token type.
+   * Can be "access_token" or "refresh_token".
+   *
+   * Helps the server optimize token lookup.
+   *
+   * @example
+   * ```ts
+   * {
+   *   tokenTypeHint: "refresh_token"
+   * }
+   * ```
+   */
+  tokenTypeHint?: "access_token" | "refresh_token";
+}
 /**
  * Draft Auth client with OAuth 2.0 operations.
  */
@@ -392,6 +408,33 @@ interface Client {
    * ```
    */
   verify<T extends SubjectSchema>(subjects: T, token: string, options?: VerifyOptions): Promise<Result<VerifyResult<T>, InvalidRefreshTokenError | InvalidAccessTokenError | InvalidSubjectError>>;
+  /**
+   * Revoke a token (access or refresh token).
+   *
+   * Once revoked, the token cannot be used to access resources or refresh.
+   * Useful for implementing logout functionality.
+   *
+   * @param token - The token to revoke
+   * @param opts - Additional revocation options
+   * @returns Empty result on success
+   *
+   * @example Logout with refresh token revocation
+   * ```ts
+   * const result = await client.revoke(refreshToken, {
+   *   tokenTypeHint: "refresh_token"
+   * })
+   *
+   * if (result.success) {
+   *   // Token revoked successfully, user is logged out
+   *   clearStoredTokens()
+   *   redirectToHome()
+   * } else {
+   *   // Revocation failed, but still clear tokens on client
+   *   clearStoredTokens()
+   * }
+   * ```
+   */
+  revoke(token: string, opts?: RevokeOptions): Promise<Result<void>>;
 }
 /**
  * Create a Draft Auth client.
@@ -409,4 +452,4 @@ interface Client {
  */
 declare const createClient: (input: ClientInput) => Client;
 //#endregion
-export { AuthorizeOptions, AuthorizeResult, Challenge, Client, ClientInput, RefreshOptions, Result, Tokens, VerifyOptions, VerifyResult, WellKnown, createClient };
+export { AuthorizeOptions, AuthorizeResult, Challenge, Client, ClientInput, RefreshOptions, Result, RevokeOptions, Tokens, VerifyOptions, VerifyResult, WellKnown, createClient };

package/dist/client.mjs

@@ -245,6 +245,32 @@ const createClient = (input) => {
 					error: new InvalidAccessTokenError()
 				};
 			}
+		},
+		async revoke(token, opts) {
+			try {
+				const wk = await getIssuer();
+				const body = new URLSearchParams({
+					token,
+					...opts?.tokenTypeHint ? { token_type_hint: opts.tokenTypeHint } : {}
+				});
+				if ((await f(wk.token_endpoint.replace("/token", "/revoke"), {
+					method: "POST",
+					headers: { "Content-Type": "application/x-www-form-urlencoded" },
+					body: body.toString()
+				})).ok) return {
+					success: true,
+					data: void 0
+				};
+				return {
+					success: false,
+					error: /* @__PURE__ */ new Error("Failed to revoke token")
+				};
+			} catch (error) {
+				return {
+					success: false,
+					error
+				};
+			}
 		}
 	};
 	return client;

package/dist/core.mjs

@@ -6,6 +6,7 @@ import { generateSecureToken } from "./random.mjs";
 import { Storage } from "./storage/storage.mjs";
 import { encryptionKeys, signingKeys } from "./keys.mjs";
 import { PluginManager } from "./plugin/manager.mjs";
+import { Revocation } from "./revocation.mjs";
 import { setTheme } from "./themes/theme.mjs";
 import { Select } from "./ui/select.mjs";
 import { CompactEncrypt, SignJWT, compactDecrypt } from "jose";
@@ -384,7 +385,12 @@ const issuer = (input) => {
 					const error$1 = new OauthError("invalid_request", "Missing refresh_token");
 					return c.json(error$1.toJSON(), { status: 400 });
 				}
-				const splits = refreshToken.toString().split(":");
+				const refreshTokenStr = refreshToken.toString();
+				if (await Revocation.isRevoked(storage, refreshTokenStr)) {
+					const error$1 = new OauthError("invalid_grant", "Refresh token has been revoked");
+					return c.json(error$1.toJSON(), { status: 400 });
+				}
+				const splits = refreshTokenStr.split(":");
 				const token = splits.pop();
 				if (!token) throw new Error("Invalid refresh token format");
 				const subject = splits.join(":");
@@ -458,6 +464,31 @@ const issuer = (input) => {
 			}, { status: 400 });
 		}
 	});
+	app.post("/revoke", {
+		middleware: [cors({
+			origin: "*",
+			allowHeaders: ["Content-Type"],
+			allowMethods: ["POST"],
+			credentials: false
+		})],
+		handler: async (c) => {
+			const token = (await c.formData()).get("token")?.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;
+				await Revocation.revoke(storage, token, expiresAt);
+				return c.json({});
+			} catch (_err) {
+				return c.json({
+					error: "server_error",
+					error_description: "Token revocation failed"
+				}, { status: 500 });
+			}
+		}
+	});
 	app.get("/authorize", async (c) => {
 		const provider = c.query("provider");
 		const response_type = c.query("response_type");

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/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 };

package/dist/provider/gitlab.mjs

@@ -0,0 +1,128 @@
+import { Oauth2Provider } from "./oauth2.mjs";
+
+//#region src/provider/gitlab.ts
+/**
+* GitLab authentication provider for Draft Auth.
+* Implements OAuth 2.0 flow for authenticating users with their GitLab accounts.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { GitlabProvider } from "@draftlab/auth/provider/gitlab"
+*
+* export default issuer({
+*   providers: {
+*     gitlab: GitlabProvider({
+*       clientID: process.env.GITLAB_CLIENT_ID,
+*       clientSecret: process.env.GITLAB_CLIENT_SECRET,
+*       scopes: ["read_user", "read_api"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Common Scopes
+*
+* - `read_user` - Access user profile
+* - `read_api` - Read-access to the API
+* - `read_repository` - Access to project repositories
+* - `write_repository` - Write access to repositories
+* - `api` - Full API access
+* - `read_user_email` - Access user email
+*
+* ## Self-Hosted GitLab
+*
+* For self-hosted GitLab instances, you can override the endpoint URLs:
+*
+* ```ts
+* const selfHostedGitlab = Oauth2Provider({
+*   clientID: process.env.GITLAB_CLIENT_ID,
+*   clientSecret: process.env.GITLAB_CLIENT_SECRET,
+*   scopes: ["read_user"],
+*   type: "gitlab",
+*   endpoint: {
+*     authorization: "https://your-gitlab.com/oauth/authorize",
+*     token: "https://your-gitlab.com/oauth/token"
+*   }
+* })
+* ```
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "gitlab") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user information
+*     const userResponse = await fetch('https://gitlab.com/api/v4/user', {
+*       headers: { Authorization: `Bearer ${accessToken}` }
+*     })
+*     const user = await userResponse.json()
+*
+*     // User info: id, username, email, name, avatar_url
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* 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
+*       })
+*     }
+*   }
+* })
+* ```
+*/
+const GitlabProvider = (config) => {
+	return Oauth2Provider({
+		...config,
+		type: "gitlab",
+		endpoint: {
+			authorization: "https://gitlab.com/oauth/authorize",
+			token: "https://gitlab.com/oauth/token"
+		}
+	});
+};
+
+//#endregion
+export { GitlabProvider };