@adonisjs/ally 6.0.0 → 6.2.0

package/build/chunk-TSIMPJ6I.js

@@ -0,0 +1,119 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/errors.ts
+var errors_exports = {};
+__export(errors_exports, {
+  E_LOCAL_SIGNUP_DISALLOWED: () => E_LOCAL_SIGNUP_DISALLOWED,
+  E_OAUTH_MISSING_CODE: () => E_OAUTH_MISSING_CODE,
+  E_OAUTH_STATE_MISMATCH: () => E_OAUTH_STATE_MISMATCH,
+  E_UNKNOWN_ALLY_PROVIDER: () => E_UNKNOWN_ALLY_PROVIDER,
+  HttpResponseException: () => HttpResponseException
+});
+import { Exception } from "@adonisjs/core/exceptions";
+var HttpResponseException = class extends Exception {
+  /**
+   * Returns the message to be sent in the HTTP response.
+   * Feel free to override this method and return a custom
+   * response.
+   */
+  getResponseMessage(error, ctx) {
+    if ("i18n" in ctx) {
+      return ctx.i18n.t(error.identifier, {}, error.message);
+    }
+    return error.message;
+  }
+  /**
+   * Converts exception to an HTTP response
+   */
+  async handle(error, ctx) {
+    const message = this.getResponseMessage(error, ctx);
+    switch (ctx.request.accepts(["html", "application/vnd.api+json", "json"])) {
+      case "html":
+      case null:
+        if (ctx.session) {
+          ctx.session.flash("error", message);
+          ctx.session.flashErrors({ [error.code]: message });
+          ctx.response.redirect().back();
+        } else {
+          ctx.response.status(error.status).send(message);
+        }
+        break;
+      case "json":
+        ctx.response.status(error.status).send({
+          errors: [
+            {
+              message
+            }
+          ]
+        });
+        break;
+      case "application/vnd.api+json":
+        ctx.response.status(error.status).send({
+          errors: [
+            {
+              code: error.code,
+              title: message
+            }
+          ]
+        });
+        break;
+    }
+  }
+};
+var E_OAUTH_MISSING_CODE = class extends HttpResponseException {
+  static status = 500;
+  static code = "E_OAUTH_MISSING_CODE";
+  /**
+   * Translation identifier. Can be customized
+   */
+  identifier = "errors.E_OAUTH_MISSING_CODE";
+  constructor(args, options) {
+    super(
+      `Cannot request access token. Redirect request is missing the "${args[0]}" param`,
+      options
+    );
+  }
+};
+var E_OAUTH_STATE_MISMATCH = class extends HttpResponseException {
+  static status = 400;
+  static code = "E_OAUTH_STATE_MISMATCH";
+  static message = "Unable to verify re-redirect state";
+  /**
+   * Translation identifier. Can be customized
+   */
+  identifier = "errors.E_OAUTH_STATE_MISMATCH";
+};
+var E_UNKNOWN_ALLY_PROVIDER = class extends HttpResponseException {
+  static status = 404;
+  static code = "E_UNKNOWN_ALLY_PROVIDER";
+  /**
+   * Translation identifier. Can be customized
+   */
+  identifier = "errors.E_UNKNOWN_ALLY_PROVIDER";
+  constructor(args, options) {
+    super(`Unknown authentication provider "${args[0]}"`, options);
+  }
+};
+var E_LOCAL_SIGNUP_DISALLOWED = class extends HttpResponseException {
+  static status = 403;
+  static code = "E_LOCAL_SIGNUP_DISALLOWED";
+  /**
+   * Translation identifier. Can be customized
+   */
+  identifier = "errors.E_LOCAL_SIGNUP_DISALLOWED";
+  constructor(args, options) {
+    super(`Cannot signup using "${args[0]}". Local signup is disabled for this provider`, options);
+  }
+};
+
+export {
+  E_OAUTH_MISSING_CODE,
+  E_OAUTH_STATE_MISMATCH,
+  E_UNKNOWN_ALLY_PROVIDER,
+  E_LOCAL_SIGNUP_DISALLOWED,
+  errors_exports
+};

package/build/index.js

@@ -1,17 +1,18 @@
 import {
   Oauth1Driver
-} from "./chunk-KWRXS6EG.js";
+} from "./chunk-4QTU45GZ.js";
 import {
   AllyManager
-} from "./chunk-SZ4YJCVU.js";
+} from "./chunk-ISWHUP4Q.js";
 import {
   Oauth2Driver
-} from "./chunk-WM3V3APX.js";
+} from "./chunk-7V2EH7U6.js";
+import {
+  RedirectRequest
+} from "./chunk-NK6X76EQ.js";
 import {
-  RedirectRequest,
   errors_exports
-} from "./chunk-KSJ4CFTC.js";
-import "./chunk-MLKGABMK.js";
+} from "./chunk-TSIMPJ6I.js";
 
 // index.ts
 import { HttpClient } from "@poppinss/oauth-client";
@@ -21,14 +22,19 @@ var stubsRoot = import.meta.dirname;
 
 // configure.ts
 var AVAILABLE_PROVIDERS = [
-  "discord",
-  "facebook",
-  "github",
-  "google",
-  "linkedin",
-  "linkedinOpenidConnect",
-  "spotify",
-  "twitter"
+  { name: "discord", message: "Discord", envPrefix: "DISCORD" },
+  { name: "facebook", message: "Facebook", envPrefix: "FACEBOOK" },
+  { name: "github", message: "GitHub", envPrefix: "GITHUB" },
+  { name: "google", message: "Google", envPrefix: "GOOGLE" },
+  { name: "linkedin", message: "LinkedIn", envPrefix: "LINKEDIN" },
+  {
+    name: "linkedinOpenidConnect",
+    message: "LinkedIn (OpenID Connect)",
+    envPrefix: "LINKEDIN_OC"
+  },
+  { name: "spotify", message: "Spotify", envPrefix: "SPOTIFY" },
+  { name: "twitter", message: "Twitter", envPrefix: "TWITTER" },
+  { name: "twitterX", message: "Twitter X (OAuth2)", envPrefix: "TWITTER_X" }
 ];
 async function configure(command) {
   let selectedProviders = command.parsedFlags.providers;
@@ -43,17 +49,20 @@ async function configure(command) {
       }
     );
   }
-  let providers = typeof selectedProviders === "string" ? [selectedProviders] : selectedProviders;
-  const unknownProvider = providers.find((provider) => !AVAILABLE_PROVIDERS.includes(provider));
+  const providerNames = typeof selectedProviders === "string" ? [selectedProviders] : selectedProviders;
+  const unknownProvider = providerNames.find(
+    (name) => !AVAILABLE_PROVIDERS.some((p) => p.name === name)
+  );
   if (unknownProvider) {
     command.exitCode = 1;
     command.logger.error(`Invalid social provider "${unknownProvider}"`);
     return;
   }
+  const providers = providerNames.map((name) => AVAILABLE_PROVIDERS.find((p) => p.name === name));
   const codemods = await command.createCodemods();
   await codemods.makeUsingStub(stubsRoot, "config/ally.stub", {
     providers: providers.map((provider) => {
-      return { provider, envPrefix: provider.toUpperCase() };
+      return { provider: provider.name, envPrefix: provider.envPrefix };
     })
   });
   await codemods.updateRcFile((rcFile) => {
@@ -61,15 +70,15 @@ async function configure(command) {
   });
   await codemods.defineEnvVariables(
     providers.reduce((result, provider) => {
-      result[`${provider.toUpperCase()}_CLIENT_ID`] = "";
-      result[`${provider.toUpperCase()}_CLIENT_SECRET`] = "";
+      result[`${provider.envPrefix}_CLIENT_ID`] = "";
+      result[`${provider.envPrefix}_CLIENT_SECRET`] = "";
       return result;
     }, {})
   );
   await codemods.defineEnvValidations({
     variables: providers.reduce((result, provider) => {
-      result[`${provider.toUpperCase()}_CLIENT_ID`] = "Env.schema.string()";
-      result[`${provider.toUpperCase()}_CLIENT_SECRET`] = "Env.schema.string()";
+      result[`${provider.envPrefix}_CLIENT_ID`] = "Env.schema.string()";
+      result[`${provider.envPrefix}_CLIENT_SECRET`] = "Env.schema.string()";
       return result;
     }, {}),
     leadingComment: "Variables for configuring ally package"
@@ -94,53 +103,113 @@ function defineConfig(config) {
   });
 }
 var services = {
+  /**
+   * Create a config provider for the Discord OAuth2 driver.
+   *
+   * @param config - Discord driver configuration.
+   * @returns A lazily resolved config provider for the Discord driver.
+   */
   discord(config) {
     return configProvider.create(async () => {
       const { DiscordDriver } = await import("./src/drivers/discord.js");
       return (ctx) => new DiscordDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the Facebook OAuth2 driver.
+   *
+   * @param config - Facebook driver configuration.
+   * @returns A lazily resolved config provider for the Facebook driver.
+   */
   facebook(config) {
     return configProvider.create(async () => {
       const { FacebookDriver } = await import("./src/drivers/facebook.js");
       return (ctx) => new FacebookDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the GitHub OAuth2 driver.
+   *
+   * @param config - GitHub driver configuration.
+   * @returns A lazily resolved config provider for the GitHub driver.
+   */
   github(config) {
     return configProvider.create(async () => {
       const { GithubDriver } = await import("./src/drivers/github.js");
       return (ctx) => new GithubDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the Google OAuth2 driver.
+   *
+   * @param config - Google driver configuration.
+   * @returns A lazily resolved config provider for the Google driver.
+   */
   google(config) {
     return configProvider.create(async () => {
       const { GoogleDriver } = await import("./src/drivers/google.js");
       return (ctx) => new GoogleDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the LinkedIn OAuth2 driver.
+   *
+   * @param config - LinkedIn driver configuration.
+   * @returns A lazily resolved config provider for the LinkedIn driver.
+   */
   linkedin(config) {
     return configProvider.create(async () => {
       const { LinkedInDriver } = await import("./src/drivers/linked_in.js");
       return (ctx) => new LinkedInDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the LinkedIn OpenID Connect driver.
+   *
+   * @param config - LinkedIn OpenID Connect driver configuration.
+   * @returns A lazily resolved config provider for the LinkedIn OpenID Connect driver.
+   */
   linkedinOpenidConnect(config) {
     return configProvider.create(async () => {
       const { LinkedInOpenidConnectDriver } = await import("./src/drivers/linked_in_openid_connect.js");
       return (ctx) => new LinkedInOpenidConnectDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the Spotify OAuth2 driver.
+   *
+   * @param config - Spotify driver configuration.
+   * @returns A lazily resolved config provider for the Spotify driver.
+   */
   spotify(config) {
     return configProvider.create(async () => {
       const { SpotifyDriver } = await import("./src/drivers/spotify.js");
       return (ctx) => new SpotifyDriver(ctx, config);
     });
   },
+  /**
+   * Create a config provider for the Twitter OAuth1 driver.
+   *
+   * @param config - Twitter driver configuration.
+   * @returns A lazily resolved config provider for the Twitter driver.
+   */
   twitter(config) {
     return configProvider.create(async () => {
       const { TwitterDriver } = await import("./src/drivers/twitter.js");
       return (ctx) => new TwitterDriver(ctx, config);
     });
+  },
+  /**
+   * Create a config provider for the X OAuth2 driver.
+   *
+   * @param config - X driver configuration.
+   * @returns A lazily resolved config provider for the X driver.
+   */
+  twitterX(config) {
+    return configProvider.create(async () => {
+      const { TwitterXDriver } = await import("./src/drivers/twitter_x.js");
+      return (ctx) => new TwitterXDriver(ctx, config);
+    });
   }
 };
 export {

package/build/providers/ally_provider.d.ts

@@ -10,6 +10,16 @@ declare module '@adonisjs/core/http' {
  */
 export default class AllyProvider {
     protected app: ApplicationService;
+    /**
+     * Create a new Ally provider instance.
+     *
+     * @param app - The AdonisJS application service.
+     */
     constructor(app: ApplicationService);
+    /**
+     * Boot the provider and register the `ctx.ally` getter.
+     *
+     * @returns A promise that resolves once the provider has been booted.
+     */
     boot(): Promise<void>;
 }

package/build/providers/ally_provider.js

@@ -1,16 +1,27 @@
 import {
   AllyManager
-} from "../chunk-SZ4YJCVU.js";
-import "../chunk-MLKGABMK.js";
+} from "../chunk-ISWHUP4Q.js";
+import "../chunk-TSIMPJ6I.js";
 
 // providers/ally_provider.ts
 import { configProvider } from "@adonisjs/core";
 import { HttpContext } from "@adonisjs/core/http";
 import { RuntimeException } from "@adonisjs/core/exceptions";
 var AllyProvider = class {
+  /**
+   * Create a new Ally provider instance.
+   *
+   * @param app - The AdonisJS application service.
+   */
   constructor(app) {
     this.app = app;
   }
+  app;
+  /**
+   * Boot the provider and register the `ctx.ally` getter.
+   *
+   * @returns A promise that resolves once the provider has been booted.
+   */
   async boot() {
     const allyConfigProvider = this.app.config.get("ally");
     const config = await configProvider.resolve(this.app, allyConfigProvider);

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

@@ -80,6 +80,7 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
      * authorization from the current request.
      *
      * @param callback - Optional callback to customize the API request
+     * @returns A promise resolving to the authenticated user profile.
      */
     abstract user(callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<Token>>;
     /**
@@ -89,6 +90,7 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
      * @param token - The access token
      * @param secret - The token secret
      * @param callback - Optional callback to customize the API request
+     * @returns A promise resolving to the authenticated user profile.
      */
     abstract userFromTokenAndSecret(token: string, secret: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
@@ -97,6 +99,8 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
     /**
      * Check if the current error indicates that the user denied access.
      * Different providers use different error codes for access denial.
+     *
+     * @returns `true` when the provider reported an access-denied state.
      */
     abstract accessDenied(): boolean;
     /**
@@ -111,9 +115,13 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
     /**
      * The cookie name for storing the OAuth token secret.
      * Automatically derived from the token cookie name.
+     *
+     * @returns The cookie name used to persist the OAuth token secret.
      */
     protected get oauthSecretCookieName(): string;
     /**
+     * Create a new OAuth1 driver instance.
+     *
      * @param ctx - The current HTTP context
      * @param config - OAuth1 driver configuration
      */
@@ -123,6 +131,7 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
      * with scope support.
      *
      * @param url - The base authorization URL
+     * @returns A redirect request builder for the given URL.
      */
     protected urlBuilder(url: string): RedirectRequest<string>;
     /**
@@ -142,6 +151,8 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
     /**
      * OAuth1 does not support stateless authentication due to the
      * three-legged authentication flow requiring token persistence.
+     *
+     * @returns This method never returns.
      */
     stateless(): never;
     /**
@@ -150,6 +161,7 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
      * in a different context.
      *
      * @param callback - Optional callback to customize the redirect request
+     * @returns A promise resolving to the authorization URL.
      *
      * @example
      * ```ts
@@ -162,6 +174,7 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
      * The request token is automatically obtained and stored in cookies.
      *
      * @param callback - Optional callback to customize the redirect request
+     * @returns A promise that resolves after the redirect response is prepared.
      *
      * @example
      * ```ts
@@ -172,23 +185,33 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
     /**
      * Check if the OAuth token from the callback matches the token
      * stored in the cookie.
+     *
+     * @returns `true` when the callback token does not match the stored token.
      */
     stateMisMatch(): boolean;
     /**
      * Check if an error was returned by the OAuth provider.
+     *
+     * @returns `true` when an error exists on the callback request.
      */
     hasError(): boolean;
     /**
      * Get the error code or message returned by the OAuth provider.
      * Returns 'unknown_error' if no verifier is present and no error was specified.
+     *
+     * @returns The provider error value when present.
      */
     getError(): string | null;
     /**
      * Get the OAuth verifier from the callback request.
+     *
+     * @returns The OAuth verifier when present.
      */
     getCode(): string | null;
     /**
      * Check if the OAuth verifier is present in the callback request.
+     *
+     * @returns `true` when the callback request contains an OAuth verifier.
      */
     hasCode(): boolean;
     /**
@@ -197,6 +220,7 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
      * making the request.
      *
      * @param callback - Optional callback to customize the token request
+     * @returns A promise resolving to the access token payload.
      *
      * @example
      * ```ts
@@ -206,6 +230,8 @@ export declare abstract class Oauth1Driver<Token extends Oauth1AccessToken, Scop
     accessToken(callback?: (request: ApiRequestContract) => void): Promise<Token>;
     /**
      * Not applicable with OAuth1. Use `userFromTokenAndSecret` instead.
+     *
+     * @returns This method never returns.
      */
     userFromToken(): Promise<never>;
 }

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

@@ -39,6 +39,11 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * for your driver to avoid conflicts. For example: `gh_oauth_state`
      */
     protected abstract stateCookieName: string;
+    /**
+     * The cookie name for storing the PKCE code verifier. Define this property
+     * in child classes that require PKCE.
+     */
+    protected codeVerifierCookieName?: string;
     /**
      * The query parameter name for sending the state to the OAuth provider.
      * This is typically 'state' but varies by provider. Check the provider's
@@ -80,6 +85,7 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * authorization code from the current request.
      *
      * @param callback - Optional callback to customize the API request
+     * @returns A promise resolving to the authenticated user profile.
      */
     abstract user(callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<Token>>;
     /**
@@ -88,6 +94,7 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      *
      * @param token - The access token
      * @param callback - Optional callback to customize the API request
+     * @returns A promise resolving to the authenticated user profile.
      */
     abstract userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
@@ -96,6 +103,8 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
     /**
      * Check if the current error indicates that the user denied access.
      * Different providers use different error codes for access denial.
+     *
+     * @returns `true` when the provider reported an access-denied state.
      */
     abstract accessDenied(): boolean;
     /**
@@ -107,6 +116,13 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      */
     protected stateCookieValue?: string;
     /**
+     * Cached PKCE code verifier value read from the cookie via
+     * loadState
+     */
+    protected codeVerifierCookieValue?: string;
+    /**
+     * Create a new OAuth2 driver instance.
+     *
      * @param ctx - The current HTTP context
      * @param config - OAuth2 driver configuration
      */
@@ -116,12 +132,13 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * with scope support.
      *
      * @param url - The base authorization URL
+     * @returns A redirect request builder for the given URL.
      */
     protected urlBuilder(url: string): RedirectRequest<string>;
     /**
      * 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.
+     * the cookie. When PKCE is enabled, it also loads the PKCE code verifier.
+     * This must be called by child classes in their constructor.
      *
      * @example
      * ```ts
@@ -132,10 +149,26 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * ```
      */
     protected loadState(): void;
+    /**
+     * Returns the PKCE code verifier for building the authorization redirect.
+     * This method is expected to create and persist the verifier for later use.
+     *
+     * @returns The generated PKCE code verifier or `null` when PKCE is disabled.
+     */
+    protected getPkceCodeVerifierForRedirect(): string | null;
+    /**
+     * Returns the PKCE code verifier for the access token exchange.
+     * This method only reads the verifier that was persisted during redirect.
+     *
+     * @returns The persisted PKCE code verifier or `null` when PKCE is disabled.
+     */
+    protected getPkceCodeVerifierForAccessToken(): string | null;
     /**
      * Enable stateless authentication by disabling CSRF state verification.
      * Only use this in scenarios where state verification is not required.
      *
+     * @returns The current driver instance.
+     *
      * @example
      * ```ts
      * await ally.use('github').stateless().redirect()
@@ -148,6 +181,7 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * in a different context.
      *
      * @param callback - Optional callback to customize the redirect request
+     * @returns A promise resolving to the authorization URL.
      *
      * @example
      * ```ts
@@ -162,6 +196,7 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * The state parameter is automatically set for CSRF protection.
      *
      * @param callback - Optional callback to customize the redirect request
+     * @returns A promise that resolves after the redirect response is prepared.
      *
      * @example
      * ```ts
@@ -175,23 +210,33 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
     /**
      * Check if the state parameter from the callback matches the state
      * stored in the cookie. Returns false in stateless mode.
+     *
+     * @returns `true` when the state validation fails.
      */
     stateMisMatch(): boolean;
     /**
      * Check if an error was returned by the OAuth provider.
+     *
+     * @returns `true` when an error exists on the callback request.
      */
     hasError(): boolean;
     /**
      * Get the error code or message returned by the OAuth provider.
      * Returns 'unknown_error' if no code is present and no error was specified.
+     *
+     * @returns The provider error value when present.
      */
     getError(): string | null;
     /**
      * Get the authorization code from the callback request.
+     *
+     * @returns The authorization code when present.
      */
     getCode(): string | null;
     /**
      * Check if the authorization code is present in the callback request.
+     *
+     * @returns `true` when the callback request contains an authorization code.
      */
     hasCode(): boolean;
     /**
@@ -199,6 +244,7 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
      * validates the state and checks for errors before making the request.
      *
      * @param callback - Optional callback to customize the token request
+     * @returns A promise resolving to the access token payload.
      *
      * @example
      * ```ts
@@ -208,6 +254,8 @@ export declare abstract class Oauth2Driver<Token extends Oauth2AccessToken, Scop
     accessToken(callback?: (request: ApiRequestContract) => void): Promise<Token>;
     /**
      * Not applicable with OAuth2. Use `userFromToken` instead.
+     *
+     * @returns This method never returns.
      */
     userFromTokenAndSecret(): Promise<never>;
 }