@draftlab/auth 0.5.0 → 0.6.0

package/dist/provider/twitch.d.mts

@@ -0,0 +1,102 @@
+import { Provider } from "./provider.mjs";
+import { Oauth2UserData, Oauth2WrappedConfig } from "./oauth2.mjs";
+
+//#region src/provider/twitch.d.ts
+
+/**
+ * Configuration options for Twitch OAuth 2.0 provider.
+ * Extends the base OAuth 2.0 configuration with Twitch-specific documentation.
+ */
+interface TwitchConfig extends Oauth2WrappedConfig {
+  /**
+   * Twitch application client ID.
+   * Get this from your Twitch Console at https://dev.twitch.tv/console
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientID: "abcdef123456"
+   * }
+   * ```
+   */
+  readonly clientID: string;
+  /**
+   * Twitch application client secret.
+   * Keep this secure and never expose it to client-side code.
+   *
+   * @example
+   * ```ts
+   * {
+   *   clientSecret: process.env.TWITCH_CLIENT_SECRET
+   * }
+   * ```
+   */
+  readonly clientSecret: string;
+  /**
+   * Twitch OAuth scopes to request access for.
+   * Determines what data and actions your app can access.
+   *
+   * @example
+   * ```ts
+   * {
+   *   scopes: [
+   *     "user:read:email",           // Access user email
+   *     "user:read:subscriptions"    // View subscriptions
+   *   ]
+   * }
+   * ```
+   */
+  readonly scopes: string[];
+}
+/**
+ * Creates a Twitch OAuth 2.0 authentication provider.
+ * Allows users to authenticate using their Twitch accounts.
+ *
+ * @param config - Twitch OAuth 2.0 configuration
+ * @returns OAuth 2.0 provider configured for Twitch
+ *
+ * @example
+ * ```ts
+ * // Basic Twitch authentication
+ * const basicTwitch = TwitchProvider({
+ *   clientID: process.env.TWITCH_CLIENT_ID,
+ *   clientSecret: process.env.TWITCH_CLIENT_SECRET
+ * })
+ *
+ * // Twitch with email scope
+ * const twitchWithEmail = TwitchProvider({
+ *   clientID: process.env.TWITCH_CLIENT_ID,
+ *   clientSecret: process.env.TWITCH_CLIENT_SECRET,
+ *   scopes: ["user:read:email"]
+ * })
+ *
+ * // Using the access token to fetch user data
+ * export default issuer({
+ *   providers: { twitch: twitchWithEmail },
+ *   success: async (ctx, value) => {
+ *     if (value.provider === "twitch") {
+ *       const token = value.tokenset.access
+ *
+ *       const userRes = await fetch('https://api.twitch.tv/helix/users', {
+ *         headers: {
+ *           'Authorization': `Bearer ${token}`,
+ *           'Client-ID': process.env.TWITCH_CLIENT_ID
+ *         }
+ *       })
+ *       const { data } = await userRes.json()
+ *       const user = data[0]
+ *
+ *       return ctx.subject("user", {
+ *         twitchId: user.id,
+ *         login: user.login,
+ *         email: user.email,
+ *         displayName: user.display_name
+ *       })
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare const TwitchProvider: (config: TwitchConfig) => Provider<Oauth2UserData>;
+//#endregion
+export { TwitchConfig, TwitchProvider };

package/dist/provider/twitch.mjs

@@ -0,0 +1,118 @@
+import { Oauth2Provider } from "./oauth2.mjs";
+
+//#region src/provider/twitch.ts
+/**
+* Twitch authentication provider for Draft Auth.
+* Implements OAuth 2.0 flow for authenticating users with their Twitch accounts.
+*
+* ## Quick Setup
+*
+* ```ts
+* import { TwitchProvider } from "@draftlab/auth/provider/twitch"
+*
+* export default issuer({
+*   providers: {
+*     twitch: TwitchProvider({
+*       clientID: process.env.TWITCH_CLIENT_ID,
+*       clientSecret: process.env.TWITCH_CLIENT_SECRET,
+*       scopes: ["user:read:email"]
+*     })
+*   }
+* })
+* ```
+*
+* ## Common Scopes
+*
+* - `user:read:email` - Access user's email address
+* - `user:read:subscriptions` - View user subscriptions
+* - `user:read:follows` - View user's follows
+* - `channel:read:subscriptions` - View channel subscribers
+* - `analytics:read:games` - View game analytics
+* - `bits:read` - View bits information
+*
+* ## User Data Access
+*
+* ```ts
+* success: async (ctx, value) => {
+*   if (value.provider === "twitch") {
+*     const accessToken = value.tokenset.access
+*
+*     // Fetch user information
+*     const userResponse = await fetch('https://api.twitch.tv/helix/users', {
+*       headers: {
+*         'Authorization': `Bearer ${accessToken}`,
+*         'Client-ID': process.env.TWITCH_CLIENT_ID
+*       }
+*     })
+*     const { data } = await userResponse.json()
+*     const user = data[0]
+*
+*     // User info available: id, login, display_name, email, profile_image_url
+*   }
+* }
+* ```
+*
+* @packageDocumentation
+*/
+/**
+* Creates a Twitch OAuth 2.0 authentication provider.
+* Allows users to authenticate using their Twitch accounts.
+*
+* @param config - Twitch OAuth 2.0 configuration
+* @returns OAuth 2.0 provider configured for Twitch
+*
+* @example
+* ```ts
+* // Basic Twitch authentication
+* const basicTwitch = TwitchProvider({
+*   clientID: process.env.TWITCH_CLIENT_ID,
+*   clientSecret: process.env.TWITCH_CLIENT_SECRET
+* })
+*
+* // Twitch with email scope
+* const twitchWithEmail = TwitchProvider({
+*   clientID: process.env.TWITCH_CLIENT_ID,
+*   clientSecret: process.env.TWITCH_CLIENT_SECRET,
+*   scopes: ["user:read:email"]
+* })
+*
+* // Using the access token to fetch user data
+* export default issuer({
+*   providers: { twitch: twitchWithEmail },
+*   success: async (ctx, value) => {
+*     if (value.provider === "twitch") {
+*       const token = value.tokenset.access
+*
+*       const userRes = await fetch('https://api.twitch.tv/helix/users', {
+*         headers: {
+*           'Authorization': `Bearer ${token}`,
+*           'Client-ID': process.env.TWITCH_CLIENT_ID
+*         }
+*       })
+*       const { data } = await userRes.json()
+*       const user = data[0]
+*
+*       return ctx.subject("user", {
+*         twitchId: user.id,
+*         login: user.login,
+*         email: user.email,
+*         displayName: user.display_name
+*       })
+*     }
+*   }
+* })
+* ```
+*/
+const TwitchProvider = (config) => {
+	return Oauth2Provider({
+		...config,
+		type: "twitch",
+		endpoint: {
+			authorization: "https://id.twitch.tv/oauth2/authorize",
+			token: "https://id.twitch.tv/oauth2/token"
+		}
+	});
+};
+
+//#endregion
+export { TwitchProvider };

package/dist/revocation.d.mts

@@ -0,0 +1,55 @@
+import { StorageAdapter } from "./storage/storage.mjs";
+
+//#region src/revocation.d.ts
+
+/**
+ * Data stored for a revoked token.
+ * Tracks when the token was revoked and when it naturally expires.
+ */
+interface RevocationRecord {
+  /** Timestamp when the token was revoked (milliseconds) */
+  revokedAt: number;
+  /** Timestamp when the token naturally expires (milliseconds) */
+  expiresAt: number;
+}
+/**
+ * Token revocation manager.
+ * Provides methods to revoke tokens and check if a token has been revoked.
+ */
+declare const Revocation: {
+  /**
+   * Revokes a token, preventing it from being used even if not yet expired.
+   *
+   * @param storage - Storage adapter to use
+   * @param token - The token to revoke (access or refresh token)
+   * @param expiresAt - When the token naturally expires (milliseconds since epoch)
+   * @returns Promise that resolves when revocation is stored
+   *
+   * @example
+   * ```ts
+   * // Revoke a refresh token on logout
+   * await Revocation.revoke(storage, refreshToken, expiresAt)
+   * ```
+   */
+  readonly revoke: (storage: StorageAdapter, token: string, expiresAt: number) => Promise<void>;
+  /**
+   * Checks if a token has been revoked.
+   * Returns false if token is not in revocation list (never revoked or already expired).
+   *
+   * @param storage - Storage adapter to use
+   * @param token - The token to check
+   * @returns Promise resolving to true if token is revoked, false otherwise
+   *
+   * @example
+   * ```ts
+   * // Check if token was revoked before using it
+   * const isRevoked = await Revocation.isRevoked(storage, accessToken)
+   * if (isRevoked) {
+   *   throw new InvalidAccessTokenError()
+   * }
+   * ```
+   */
+  readonly isRevoked: (storage: StorageAdapter, token: string) => Promise<boolean>;
+};
+//#endregion
+export { Revocation, RevocationRecord };

package/dist/revocation.mjs

@@ -0,0 +1,63 @@
+import { Storage } from "./storage/storage.mjs";
+import { createHash } from "node:crypto";
+
+//#region src/revocation.ts
+/**
+* Token revocation management for Draft Auth.
+* Handles blacklisting of revoked tokens to prevent their use.
+*
+* ## Overview
+*
+* Revocation allows users to invalidate specific tokens before their natural expiration.
+* This is essential for logout functionality and security in case of token compromise.
+*
+* ## Storage Structure
+*
+* Revoked tokens are stored with their expiration time to allow automatic cleanup:
+* ```
+* revocation:token:{tokenHash} → { revokedAt: timestamp, expiresAt: timestamp }
+* ```
+*
+* ## Security Considerations
+*
+* - Revoked tokens are checked on every use
+* - Storage automatically cleans up expired revocations
+* - Hash tokens for storage to reduce memory usage
+* - Use constant-time comparison for hash verification
+*
+* @packageDocumentation
+*/
+/**
+* Hashes a token for storage.
+* Uses SHA-256 to reduce storage size and prevent exposure of full token value.
+*
+* @param token - The token to hash
+* @returns SHA-256 hash of the token
+*
+* @internal
+*/
+const hashToken = (token) => {
+	return createHash("sha256").update(token).digest("hex");
+};
+/**
+* Token revocation manager.
+* Provides methods to revoke tokens and check if a token has been revoked.
+*/
+const Revocation = {
+	revoke: async (storage, token, expiresAt) => {
+		const key = ["revocation:token", hashToken(token)];
+		const record = {
+			revokedAt: Date.now(),
+			expiresAt
+		};
+		const ttlSeconds = Math.ceil((expiresAt - Date.now()) / 1e3);
+		await Storage.set(storage, key, record, Math.max(1, ttlSeconds));
+	},
+	isRevoked: async (storage, token) => {
+		const key = ["revocation:token", hashToken(token)];
+		return !!await Storage.get(storage, key);
+	}
+};
+
+//#endregion
+export { Revocation };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftlab/auth",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "Core implementation for @draftlab/auth",
   "author": "Matheus Pergoli",