@adonisjs/ally 5.1.0 → 6.0.0-next.0

package/build/src/abstract_drivers/oauth1.d.ts

@@ -1,145 +1,211 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import { Oauth1Client } from '@poppinss/oauth-client/oauth1';
-import { AllyUserContract, Oauth1AccessToken, Oauth1DriverConfig, ApiRequestContract, AllyDriverContract, RedirectRequestContract } from '../types.js';
-import { RedirectRequest } from '../redirect_request.js';
+import { type AllyUserContract, type Oauth1AccessToken, type Oauth1DriverConfig, type ApiRequestContract, type AllyDriverContract, type RedirectRequestContract } from '../types.ts';
+import { RedirectRequest } from '../redirect_request.ts';
 /**
- * Abstract implementation for an Oauth1 driver
+ * Abstract base class for implementing OAuth1 social authentication drivers.
+ * Extends the OAuth1 client to provide AdonisJS-specific functionality like
+ * token management via cookies and integration with HTTP context.
+ *
+ * @example
+ * ```ts
+ * export class CustomDriver extends Oauth1Driver<CustomToken, CustomScopes> {
+ *   protected oauthTokenCookieName = 'custom_oauth_token'
+ *   protected oauthTokenParamName = 'oauth_token'
+ *   protected oauthTokenVerifierName = 'oauth_verifier'
+ *   protected errorParamName = 'error'
+ *   protected requestTokenUrl = 'https://provider.com/oauth/request_token'
+ *   protected authorizeUrl = 'https://provider.com/oauth/authorize'
+ *   protected accessTokenUrl = 'https://provider.com/oauth/access_token'
+ *   protected scopeParamName = ''
+ *   protected scopesSeparator = ' '
+ *
+ *   async user() {
+ *     // Implementation
+ *   }
+ * }
+ * ```
  */
 export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scopes extends string> extends Oauth1Client<Token> implements AllyDriverContract<Token, Scopes> {
     #private;
     protected ctx: HttpContext;
     config: Oauth1DriverConfig;
     /**
-     * The cookie name for storing the "oauth_token". Must be unique for your
-     * driver. One option is to prefix the driver name. For example:
-     * `twitter_oauth_token`
+     * The cookie name for storing the OAuth token. Must be unique for
+     * your driver to avoid conflicts. For example: `twitter_oauth_token`
      */
     protected abstract oauthTokenCookieName: string;
     /**
-     * Name of the "oauth_token" param. This is the query string value post
-     * authorization redirect
+     * The query parameter name for the OAuth token returned after
+     * authorization redirect. This is typically 'oauth_token'.
      */
     protected abstract oauthTokenParamName: string;
     /**
-     * Name of the "oauth_verifier" param. This is the query string value post
-     * authorization redirect
+     * The query parameter name for the OAuth verifier returned after
+     * authorization redirect. This is typically 'oauth_verifier'.
      */
     protected abstract oauthTokenVerifierName: string;
     /**
-     * The parameter name from which to fetch the error message or error code
-     * post redirect.
-     *
-     * You must check the auth provider docs to find it
+     * The query parameter name for error messages returned by the provider
+     * after authorization redirect.
      */
     protected abstract errorParamName: string;
     /**
-     * Request token URL for the auth provider. The initial set of tokens
-     * are generated from this url
+     * The OAuth provider's endpoint for obtaining a request token.
+     * This is the first step in the OAuth1 flow.
      */
     protected abstract requestTokenUrl: string;
     /**
-     * Authorization URL for the auth provider. The user will be redirected
-     * to this URL
+     * The OAuth provider's authorization URL where users are redirected
+     * to grant permissions.
      */
     protected abstract authorizeUrl: string;
     /**
-     * The URL to hit to get an access token
+     * The OAuth provider's endpoint for exchanging the request token
+     * and verifier for an access token.
      */
     protected abstract accessTokenUrl: string;
     /**
-     * The query param name for defining the Authorization scopes.
-     * Mostly it is `scope`. Leave to empty string when scopes
-     * are not applicable
+     * The query parameter name for defining authorization scopes.
+     * Leave as empty string if scopes are not supported by the provider.
      */
     protected abstract scopeParamName: string;
     /**
-     * The identifier for joining multiple scopes. Mostly it is a space.
+     * The separator character for joining multiple scopes. This is
+     * typically a space ' '.
      */
     protected abstract scopesSeparator: string;
     /**
-     * Returns details for the authorized user
+     * Fetch the user details from the OAuth provider using the
+     * authorization from the current request.
+     *
+     * @param callback - Optional callback to customize the API request
      */
     abstract user(callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<Token>>;
     /**
-     * Finds the user by access token
+     * Fetch user details using an existing access token and secret.
+     * This is the OAuth1 equivalent of `userFromToken`.
+     *
+     * @param token - The access token
+     * @param secret - The token secret
+     * @param callback - Optional callback to customize the API request
      */
     abstract userFromTokenAndSecret(token: string, secret: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
         secret: string;
     }>>;
     /**
-     * Find if the current error code is for access denied
+     * Check if the current error indicates that the user denied access.
+     * Different providers use different error codes for access denial.
      */
     abstract accessDenied(): boolean;
     /**
-     * Oauth client version
+     * OAuth protocol version identifier
      */
     version: "oauth1";
     /**
-     * The value of "oauth_token" and "oauth_secret" from the cookies
+     * Cached OAuth token and secret values read from cookies
      */
     protected oauthTokenCookieValue?: string;
     protected oauthSecretCookieValue?: string;
     /**
-     * The cookie name for storing the secret
+     * The cookie name for storing the OAuth token secret.
+     * Automatically derived from the token cookie name.
      */
     protected get oauthSecretCookieName(): string;
+    /**
+     * @param ctx - The current HTTP context
+     * @param config - OAuth1 driver configuration
+     */
     constructor(ctx: HttpContext, config: Oauth1DriverConfig);
     /**
-     * The Oauth1Client will use the instance returned from this method to
-     * build the redirect url
+     * Creates a URL builder instance for constructing authorization URLs
+     * with scope support.
+     *
+     * @param url - The base authorization URL
      */
     protected urlBuilder(url: string): RedirectRequest<string>;
     /**
-     * Loads the value of state from the cookie and removes it right
-     * away. We read the cookie value and clear it during the
-     * current request lifecycle.
-     *
-     * :::::
-     * NOTE
-     * :::::
+     * Loads the OAuth token and secret from encrypted cookies and immediately
+     * clears the cookies. This must be called by child classes in their
+     * constructor to enable token verification.
      *
-     * This child class must call this method inside the constructor.
+     * @example
+     * ```ts
+     * constructor(ctx: HttpContext, config: DriverConfig) {
+     *   super(ctx, config)
+     *   this.loadState()
+     * }
+     * ```
      */
     protected loadState(): void;
     /**
-     * Perform stateless authentication. Only applicable for Oauth1 client
+     * OAuth1 does not support stateless authentication due to the
+     * three-legged authentication flow requiring token persistence.
      */
     stateless(): never;
     /**
-     * Returns the redirect URL for the request.
+     * Get the authorization redirect URL without performing the redirect.
+     * Useful when you need to manually handle the redirect or use the URL
+     * in a different context.
+     *
+     * @param callback - Optional callback to customize the redirect request
+     *
+     * @example
+     * ```ts
+     * const url = await ally.use('twitter').redirectUrl()
+     * ```
      */
     redirectUrl(callback?: (request: RedirectRequestContract<Scopes>) => void): Promise<string>;
     /**
-     * Redirect user for authorization.
+     * Redirect the user to the OAuth provider's authorization page.
+     * The request token is automatically obtained and stored in cookies.
+     *
+     * @param callback - Optional callback to customize the redirect request
+     *
+     * @example
+     * ```ts
+     * await ally.use('twitter').redirect()
+     * ```
      */
     redirect(callback?: (request: RedirectRequestContract<Scopes>) => void): Promise<void>;
     /**
-     * Find if there is a state mismatch
+     * Check if the OAuth token from the callback matches the token
+     * stored in the cookie.
      */
     stateMisMatch(): boolean;
     /**
-     * Find if there is an error post redirect
+     * Check if an error was returned by the OAuth provider.
      */
     hasError(): boolean;
     /**
-     * Get the post redirect error
+     * Get the error code or message returned by the OAuth provider.
+     * Returns 'unknown_error' if no verifier is present and no error was specified.
      */
     getError(): string | null;
     /**
-     * Returns the "oauth_verifier" token
+     * Get the OAuth verifier from the callback request.
      */
     getCode(): string | null;
     /**
-     * Find it the code exists
+     * Check if the OAuth verifier is present in the callback request.
      */
     hasCode(): boolean;
     /**
-     * Get access token
+     * Exchange the request token and verifier for an access token.
+     * This method validates the token and checks for errors before
+     * making the request.
+     *
+     * @param callback - Optional callback to customize the token request
+     *
+     * @example
+     * ```ts
+     * const token = await ally.use('twitter').accessToken()
+     * ```
      */
     accessToken(callback?: (request: ApiRequestContract) => void): Promise<Token>;
     /**
-     * Not applicable with Oauth1
+     * Not applicable with OAuth1. Use `userFromTokenAndSecret` instead.
      */
     userFromToken(): Promise<never>;
 }

package/build/src/abstract_drivers/oauth2.d.ts

@@ -1,142 +1,213 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import { Oauth2Client } from '@poppinss/oauth-client/oauth2';
-import { AllyUserContract, Oauth2AccessToken, Oauth2DriverConfig, ApiRequestContract, AllyDriverContract, RedirectRequestContract } from '../types.js';
-import { RedirectRequest } from '../redirect_request.js';
+import { type AllyUserContract, type Oauth2AccessToken, type Oauth2DriverConfig, type ApiRequestContract, type AllyDriverContract, type RedirectRequestContract } from '../types.ts';
+import { RedirectRequest } from '../redirect_request.ts';
 /**
- * Abstract implementation for an Oauth2 driver
+ * Abstract base class for implementing OAuth2 social authentication drivers.
+ * Extends the OAuth2 client to provide AdonisJS-specific functionality like
+ * CSRF protection, state management, and integration with HTTP context.
+ *
+ * @example
+ * ```ts
+ * export class CustomDriver extends Oauth2Driver<CustomToken, CustomScopes> {
+ *   protected stateCookieName = 'custom_oauth_state'
+ *   protected stateParamName = 'state'
+ *   protected errorParamName = 'error'
+ *   protected codeParamName = 'code'
+ *   protected authorizeUrl = 'https://provider.com/oauth/authorize'
+ *   protected accessTokenUrl = 'https://provider.com/oauth/token'
+ *   protected scopeParamName = 'scope'
+ *   protected scopesSeparator = ' '
+ *
+ *   async user() {
+ *     // Implementation
+ *   }
+ * }
+ * ```
  */
 export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scopes extends string> extends Oauth2Client<Token> implements AllyDriverContract<Token, Scopes> {
     #private;
     protected ctx: HttpContext;
     config: Oauth2DriverConfig;
     /**
-     * Is the authorization process stateless?
+     * Whether the authorization process is stateless. When true,
+     * state verification via cookies is disabled.
      */
     protected isStateless: boolean;
     /**
-     * The cookie name for storing the CSRF token. Must be unique for your
-     * driver. One option is to prefix the driver name. For example:
-     * `gh_oauth_state`
+     * The cookie name for storing the CSRF state token. Must be unique
+     * for your driver to avoid conflicts. For example: `gh_oauth_state`
      */
     protected abstract stateCookieName: string;
     /**
-     * The parameter in which to send the state to the oauth provider. The same
-     * input is used to retrieve the state post redirect as well.
-     *
-     * You must check the auth provider docs to find it
+     * The query parameter name for sending the state to the OAuth provider.
+     * This is typically 'state' but varies by provider. Check the provider's
+     * OAuth documentation.
      */
     protected abstract stateParamName: string;
     /**
-     * The parameter name from which to fetch the error message or error code
-     * post redirect.
-     *
-     * You must check the auth provider docs to find it
+     * The query parameter name for error messages returned by the provider
+     * after authorization redirect. This is typically 'error'.
      */
     protected abstract errorParamName: string;
     /**
-     * The parameter name from which to fetch the authorization code. It is usually
-     * named as "code".
-     *
-     * You must check the auth provider docs to find it
+     * The query parameter name for the authorization code returned by the
+     * provider. This is typically 'code'.
      */
     protected abstract codeParamName: string;
     /**
-     * Authorization URL for the auth provider. The user will be redirected
-     * to this URL
+     * The OAuth provider's authorization URL where users are redirected
+     * to grant permissions.
      */
     protected abstract authorizeUrl: string;
     /**
-     * The URL to hit to get an access token
+     * The OAuth provider's endpoint for exchanging the authorization code
+     * for an access token.
      */
     protected abstract accessTokenUrl: string;
     /**
-     * The query param name for defining the Authorization scopes.
-     * Mostly it is `scope`
+     * The query parameter name for defining authorization scopes.
+     * This is typically 'scope'.
      */
     protected abstract scopeParamName: string;
     /**
-     * The identifier for joining multiple scopes. Mostly it is a space.
+     * The separator character for joining multiple scopes. This is
+     * typically a space ' ' or comma ','.
      */
     protected abstract scopesSeparator: string;
     /**
-     * Returns details for the authorized user
+     * Fetch the user details from the OAuth provider using the
+     * authorization code from the current request.
+     *
+     * @param callback - Optional callback to customize the API request
      */
     abstract user(callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<Token>>;
     /**
-     * Finds the user by access token
+     * Fetch user details using an existing access token. Useful for
+     * verifying tokens or fetching user info for already authenticated users.
+     *
+     * @param token - The access token
+     * @param callback - Optional callback to customize the API request
      */
     abstract userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
         type: 'bearer';
     }>>;
     /**
-     * Find if the current error code is for access denied
+     * Check if the current error indicates that the user denied access.
+     * Different providers use different error codes for access denial.
      */
     abstract accessDenied(): boolean;
     /**
-     * Oauth client version
+     * OAuth protocol version identifier
      */
     version: "oauth2";
     /**
-     * The value of state read from the cookies.
+     * Cached state value read from the cookie
      */
     protected stateCookieValue?: string;
+    /**
+     * @param ctx - The current HTTP context
+     * @param config - OAuth2 driver configuration
+     */
     constructor(ctx: HttpContext, config: Oauth2DriverConfig);
     /**
-     * The Oauth2Client will use the instance returned from this method to
-     * build the redirect url
+     * Creates a URL builder instance for constructing authorization URLs
+     * with scope support.
+     *
+     * @param url - The base authorization URL
      */
     protected urlBuilder(url: string): RedirectRequest<string>;
     /**
-     * Loads the value of state from the cookie and removes it right
-     * away. We read the cookie value and clear it during the
-     * current request lifecycle.
+     * Loads the state value from the encrypted cookie and immediately clears
+     * the cookie. This must be called by child classes in their constructor
+     * to enable CSRF protection.
      *
-     * :::::
-     * NOTE
-     * :::::
-     *
-     * This child class must call this method inside the constructor.
+     * @example
+     * ```ts
+     * constructor(ctx: HttpContext, config: DriverConfig) {
+     *   super(ctx, config)
+     *   this.loadState()
+     * }
+     * ```
      */
     protected loadState(): void;
     /**
-     * Perform stateless authentication. Only applicable for Oauth2 client
+     * Enable stateless authentication by disabling CSRF state verification.
+     * Only use this in scenarios where state verification is not required.
+     *
+     * @example
+     * ```ts
+     * await ally.use('github').stateless().redirect()
+     * ```
      */
     stateless(): this;
     /**
-     * Returns the redirect URL for the request.
+     * Get the authorization redirect URL without performing the redirect.
+     * Useful when you need to manually handle the redirect or use the URL
+     * in a different context.
+     *
+     * @param callback - Optional callback to customize the redirect request
+     *
+     * @example
+     * ```ts
+     * const url = await ally.use('github').redirectUrl((request) => {
+     *   request.scopes(['user:email'])
+     * })
+     * ```
      */
     redirectUrl(callback?: (request: RedirectRequestContract<Scopes>) => void): Promise<string>;
     /**
-     * Redirect user for authorization.
+     * Redirect the user to the OAuth provider's authorization page.
+     * The state parameter is automatically set for CSRF protection.
+     *
+     * @param callback - Optional callback to customize the redirect request
+     *
+     * @example
+     * ```ts
+     * await ally.use('github').redirect((request) => {
+     *   request.scopes(['user:email', 'read:org'])
+     *   request.param('allow_signup', 'false')
+     * })
+     * ```
      */
     redirect(callback?: (request: RedirectRequestContract<Scopes>) => void): Promise<void>;
     /**
-     * Find if there is a state mismatch
+     * Check if the state parameter from the callback matches the state
+     * stored in the cookie. Returns false in stateless mode.
      */
     stateMisMatch(): boolean;
     /**
-     * Find if there is an error post redirect
+     * Check if an error was returned by the OAuth provider.
      */
     hasError(): boolean;
     /**
-     * Get the post redirect error
+     * Get the error code or message returned by the OAuth provider.
+     * Returns 'unknown_error' if no code is present and no error was specified.
      */
     getError(): string | null;
     /**
-     * Returns the authorization code
+     * Get the authorization code from the callback request.
      */
     getCode(): string | null;
     /**
-     * Find it the code exists
+     * Check if the authorization code is present in the callback request.
      */
     hasCode(): boolean;
     /**
-     * Get access token
+     * Exchange the authorization code for an access token. This method
+     * validates the state and checks for errors before making the request.
+     *
+     * @param callback - Optional callback to customize the token request
+     *
+     * @example
+     * ```ts
+     * const token = await ally.use('github').accessToken()
+     * ```
      */
     accessToken(callback?: (request: ApiRequestContract) => void): Promise<Token>;
     /**
-     * Not applicable with Oauth2
+     * Not applicable with OAuth2. Use `userFromToken` instead.
      */
     userFromTokenAndSecret(): Promise<never>;
 }

package/build/src/ally_manager.d.ts

@@ -1,15 +1,42 @@
 import type { HttpContext } from '@adonisjs/core/http';
-import type { AllyManagerDriverFactory } from './types.js';
+import type { AllyManagerDriverFactory } from './types.ts';
 /**
- * AllyManager is used to create instances of a social drivers during an
- * HTTP request. The drivers are cached during the lifecycle of a request.
+ * AllyManager is used to create and manage social authentication driver
+ * instances during an HTTP request. The drivers are cached during the
+ * lifecycle of a request to avoid creating duplicate instances.
+ *
+ * @example
+ * ```ts
+ * router.get('/github/redirect', ({ ally }) => {
+ *   return ally.use('github').redirect()
+ * })
+ *
+ * router.get('/github/callback', async ({ ally }) => {
+ *   const github = ally.use('github')
+ *   const user = await github.user()
+ *   return user
+ * })
+ * ```
  */
 export declare class AllyManager<KnownSocialProviders extends Record<string, AllyManagerDriverFactory>> {
     #private;
     config: KnownSocialProviders;
+    /**
+     * @param config - Map of provider names to driver factory functions
+     * @param ctx - The current HTTP context
+     */
     constructor(config: KnownSocialProviders, ctx: HttpContext);
     /**
-     * Returns the driver instance of a social provider
+     * Get a driver instance for the specified social provider. The driver
+     * instance is cached for the duration of the HTTP request.
+     *
+     * @param provider - The name of the social provider (e.g., 'github', 'google')
+     *
+     * @example
+     * ```ts
+     * const github = ally.use('github')
+     * await github.redirect()
+     * ```
      */
     use<SocialProvider extends keyof KnownSocialProviders>(provider: SocialProvider): ReturnType<KnownSocialProviders[SocialProvider]>;
 }

package/build/src/debug.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Debug logger for the Ally package. Set the NODE_DEBUG environment
+ * variable to "adonisjs:ally" to enable debug logs.
+ *
+ * @example
+ * ```sh
+ * NODE_DEBUG=adonisjs:ally node your-app.js
+ * ```
+ */
 declare const _default: import("util").DebugLogger;
 export default _default;

package/build/src/define_config.d.ts

@@ -1,14 +1,14 @@
 import type { HttpContext } from '@adonisjs/core/http';
 import type { ConfigProvider } from '@adonisjs/core/types';
-import type { GoogleDriver } from './drivers/google.js';
-import type { GithubDriver } from './drivers/github.js';
-import type { SpotifyDriver } from './drivers/spotify.js';
-import type { TwitterDriver } from './drivers/twitter.js';
-import type { DiscordDriver } from './drivers/discord.js';
-import type { FacebookDriver } from './drivers/facebook.js';
-import type { LinkedInDriver } from './drivers/linked_in.js';
-import type { LinkedInOpenidConnectDriver } from './drivers/linked_in_openid_connect.js';
-import type { GoogleDriverConfig, GithubDriverConfig, SpotifyDriverConfig, DiscordDriverConfig, TwitterDriverConfig, LinkedInDriverConfig, LinkedInOpenidConnectDriverConfig, FacebookDriverConfig, AllyManagerDriverFactory } from './types.js';
+import type { GoogleDriver } from './drivers/google.ts';
+import type { GithubDriver } from './drivers/github.ts';
+import type { SpotifyDriver } from './drivers/spotify.ts';
+import type { TwitterDriver } from './drivers/twitter.ts';
+import type { DiscordDriver } from './drivers/discord.ts';
+import type { FacebookDriver } from './drivers/facebook.ts';
+import type { LinkedInDriver } from './drivers/linked_in.ts';
+import type { LinkedInOpenidConnectDriver } from './drivers/linked_in_openid_connect.ts';
+import type { GoogleDriverConfig, GithubDriverConfig, SpotifyDriverConfig, DiscordDriverConfig, TwitterDriverConfig, LinkedInDriverConfig, LinkedInOpenidConnectDriverConfig, FacebookDriverConfig, AllyManagerDriverFactory } from './types.ts';
 /**
  * Shape of config after it has been resolved from
  * the config provider
@@ -17,11 +17,45 @@ type ResolvedConfig<KnownSocialProviders extends Record<string, AllyManagerDrive
     [K in keyof KnownSocialProviders]: KnownSocialProviders[K] extends ConfigProvider<infer A> ? A : KnownSocialProviders[K];
 };
 /**
- * Define config for the ally
+ * Define configuration for Ally social authentication providers.
+ * This function accepts a map of provider names to their factory
+ * functions or config providers.
+ *
+ * @param config - An object mapping provider names to driver factories
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   github: services.github({
+ *     clientId: env.get('GITHUB_CLIENT_ID'),
+ *     clientSecret: env.get('GITHUB_CLIENT_SECRET'),
+ *     callbackUrl: 'http://localhost:3333/github/callback'
+ *   }),
+ *   google: services.google({
+ *     clientId: env.get('GOOGLE_CLIENT_ID'),
+ *     clientSecret: env.get('GOOGLE_CLIENT_SECRET'),
+ *     callbackUrl: 'http://localhost:3333/google/callback'
+ *   })
+ * })
+ * ```
  */
 export declare function defineConfig<KnownSocialProviders extends Record<string, AllyManagerDriverFactory | ConfigProvider<AllyManagerDriverFactory>>>(config: KnownSocialProviders): ConfigProvider<ResolvedConfig<KnownSocialProviders>>;
 /**
- * Helpers to configure social auth services
+ * Pre-configured helpers for setting up built-in social authentication
+ * providers. Each method accepts provider-specific configuration and
+ * returns a config provider that lazily loads and instantiates the driver.
+ *
+ * @example
+ * ```ts
+ * export default defineConfig({
+ *   github: services.github({
+ *     clientId: env.get('GITHUB_CLIENT_ID'),
+ *     clientSecret: env.get('GITHUB_CLIENT_SECRET'),
+ *     callbackUrl: 'http://localhost:3333/github/callback',
+ *     scopes: ['user', 'user:email']
+ *   })
+ * })
+ * ```
  */
 export declare const services: {
     discord: (config: DiscordDriverConfig) => ConfigProvider<(ctx: HttpContext) => DiscordDriver>;