@adonisjs/ally 6.0.0-next.0 → 6.1.0

package/README.md

@@ -5,10 +5,10 @@
 [![gh-workflow-image]][gh-workflow-url] [![npm-image]][npm-url] ![][typescript-image] [![license-image]][license-url]
 
 ## Introduction
-Social authentication provider for AdonisJS. Supports **Github**, **Google**, **Twitter**, **Facebook**, **Discord**, **Spotify**, and **LinkedIn**.
+Social authentication provider for AdonisJS. Supports **Github**, **Google**, **Twitter**, **X (Twitter OAuth2)**, **Facebook**, **Discord**, **Spotify**, and **LinkedIn**.
 
 ## Official Documentation
-The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/social-auth)
+The documentation is available on the [AdonisJS website](https://docs.adonisjs.com/guides/auth/social-authentication)
 
 ## Contributing
 One of the primary goals of AdonisJS is to have a vibrant community of users and contributors who believes in the principles of the framework.

package/build/{chunk-WM3V3APX.js → chunk-46TOMXWK.js}

@@ -1,14 +1,18 @@
 import {
-  E_OAUTH_MISSING_CODE,
-  E_OAUTH_STATE_MISMATCH,
   RedirectRequest
-} from "./chunk-KSJ4CFTC.js";
+} from "./chunk-NK6X76EQ.js";
+import {
+  E_OAUTH_MISSING_CODE,
+  E_OAUTH_STATE_MISMATCH
+} from "./chunk-6BP2DK5A.js";
 
 // src/abstract_drivers/oauth2.ts
 import { Exception } from "@adonisjs/core/exceptions";
 import { Oauth2Client } from "@poppinss/oauth-client/oauth2";
 var Oauth2Driver = class extends Oauth2Client {
   /**
+   * Create a new OAuth2 driver instance.
+   *
    * @param ctx - The current HTTP context
    * @param config - OAuth2 driver configuration
    */
@@ -17,11 +21,18 @@ var Oauth2Driver = class extends Oauth2Client {
     this.ctx = ctx;
     this.config = config;
   }
+  ctx;
+  config;
   /**
    * Whether the authorization process is stateless. When true,
    * state verification via cookies is disabled.
    */
   isStateless = false;
+  /**
+   * The cookie name for storing the PKCE code verifier. Define this property
+   * in child classes that require PKCE.
+   */
+  codeVerifierCookieName;
   /**
    * OAuth protocol version identifier
    */
@@ -30,19 +41,33 @@ var Oauth2Driver = class extends Oauth2Client {
    * Cached state value read from the cookie
    */
   stateCookieValue;
+  /**
+   * Cached PKCE code verifier value read from the cookie via
+   * loadState
+   */
+  codeVerifierCookieValue;
   /**
    * Creates a URL builder instance for constructing authorization URLs
    * with scope support.
    *
    * @param url - The base authorization URL
+   * @returns A redirect request builder for the given URL.
    */
   urlBuilder(url) {
     return new RedirectRequest(url, this.scopeParamName, this.scopesSeparator);
   }
+  /**
+   * Find if the driver uses PKCE for the OAuth2 authorization code flow.
+   *
+   * @returns `true` when the driver has PKCE enabled.
+   */
+  #usesPkce() {
+    return !!this.codeVerifierCookieName;
+  }
   /**
    * 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
@@ -58,25 +83,50 @@ var Oauth2Driver = class extends Oauth2Client {
     }
     this.stateCookieValue = this.ctx.request.encryptedCookie(this.stateCookieName);
     this.ctx.response.clearCookie(this.stateCookieName);
+    if (this.#usesPkce()) {
+      this.codeVerifierCookieValue = this.ctx.request.encryptedCookie(this.codeVerifierCookieName);
+      this.ctx.response.clearCookie(this.codeVerifierCookieName);
+    }
   }
   /**
-   * Stores the CSRF state in an encrypted cookie for later verification
+   * 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.
    */
-  #persistState() {
-    if (this.isStateless) {
-      return;
+  getPkceCodeVerifierForRedirect() {
+    if (!this.#usesPkce()) {
+      return null;
     }
-    const state = this.getState();
-    this.ctx.response.encryptedCookie(this.stateCookieName, state, {
+    const codeVerifier = this.makeCodeVerifier();
+    this.ctx.response.encryptedCookie(this.codeVerifierCookieName, codeVerifier, {
       sameSite: false,
       httpOnly: true
     });
-    return state;
+    this.codeVerifierCookieValue = codeVerifier;
+    return codeVerifier;
+  }
+  /**
+   * 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.
+   */
+  getPkceCodeVerifierForAccessToken() {
+    if (!this.#usesPkce()) {
+      return null;
+    }
+    if (!this.codeVerifierCookieValue) {
+      throw new E_OAUTH_MISSING_CODE(["code_verifier"]);
+    }
+    return this.codeVerifierCookieValue;
   }
   /**
    * 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()
@@ -92,6 +142,7 @@ var Oauth2Driver = class extends Oauth2Client {
    * in a different context.
    *
    * @param callback - Optional callback to customize the redirect request
+   * @returns A promise resolving to the authorization URL.
    *
    * @example
    * ```ts
@@ -109,6 +160,7 @@ var Oauth2Driver = class extends Oauth2Client {
    * 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
@@ -120,8 +172,14 @@ var Oauth2Driver = class extends Oauth2Client {
    */
   async redirect(callback) {
     const url = await this.redirectUrl((request) => {
-      const state = this.#persistState();
-      state && request.param(this.stateParamName, state);
+      if (!this.isStateless) {
+        const state = this.getState();
+        this.ctx.response.encryptedCookie(this.stateCookieName, state, {
+          sameSite: false,
+          httpOnly: true
+        });
+        request.param(this.stateParamName, state);
+      }
       if (typeof callback === "function") {
         callback(request);
       }
@@ -131,15 +189,25 @@ var Oauth2Driver = class extends Oauth2Client {
   /**
    * 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() {
     if (this.isStateless) {
       return false;
     }
-    return this.stateCookieValue !== this.ctx.request.input(this.stateParamName);
+    if (this.stateCookieValue !== this.ctx.request.input(this.stateParamName)) {
+      return true;
+    }
+    if (this.#usesPkce() && !this.codeVerifierCookieValue) {
+      return true;
+    }
+    return false;
   }
   /**
    * Check if an error was returned by the OAuth provider.
+   *
+   * @returns `true` when an error exists on the callback request.
    */
   hasError() {
     return !!this.getError();
@@ -147,6 +215,8 @@ var Oauth2Driver = class extends Oauth2Client {
   /**
    * 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() {
     const error = this.ctx.request.input(this.errorParamName);
@@ -160,12 +230,16 @@ var Oauth2Driver = class extends Oauth2Client {
   }
   /**
    * Get the authorization code from the callback request.
+   *
+   * @returns The authorization code when present.
    */
   getCode() {
     return this.ctx.request.input(this.codeParamName, null);
   }
   /**
    * Check if the authorization code is present in the callback request.
+   *
+   * @returns `true` when the callback request contains an authorization code.
    */
   hasCode() {
     return !!this.getCode();
@@ -175,6 +249,7 @@ var Oauth2Driver = class extends Oauth2Client {
    * 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
@@ -197,6 +272,8 @@ var Oauth2Driver = class extends Oauth2Client {
   }
   /**
    * Not applicable with OAuth2. Use `userFromToken` instead.
+   *
+   * @returns This method never returns.
    */
   async userFromTokenAndSecret() {
     throw new Exception(

package/build/chunk-6BP2DK5A.js

@@ -0,0 +1,43 @@
+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
+});
+import { createError } from "@adonisjs/core/exceptions";
+var E_OAUTH_MISSING_CODE = createError(
+  'Cannot request access token. Redirect request is missing the "%s" param',
+  "E_OAUTH_MISSING_CODE",
+  500
+);
+var E_OAUTH_STATE_MISMATCH = createError(
+  "Unable to verify re-redirect state",
+  "E_OAUTH_STATE_MISMATCH",
+  400
+);
+var E_UNKNOWN_ALLY_PROVIDER = createError(
+  'Unknown ally provider "%s". Make sure it is registered inside the config/ally.ts file',
+  "E_UNKNOWN_ALLY_PROVIDER",
+  404
+);
+var E_LOCAL_SIGNUP_DISALLOWED = createError(
+  'Cannot use ally provider "%s" for signup. Local signup is disabled for this provider',
+  "E_LOCAL_SIGNUP_DISALLOWED",
+  403
+);
+
+export {
+  E_OAUTH_MISSING_CODE,
+  E_OAUTH_STATE_MISMATCH,
+  E_UNKNOWN_ALLY_PROVIDER,
+  E_LOCAL_SIGNUP_DISALLOWED,
+  errors_exports
+};

package/build/{chunk-KSJ4CFTC.js → chunk-NK6X76EQ.js}

@@ -1,32 +1,21 @@
-import {
-  __export
-} from "./chunk-MLKGABMK.js";
-
-// src/errors.ts
-var errors_exports = {};
-__export(errors_exports, {
-  E_OAUTH_MISSING_CODE: () => E_OAUTH_MISSING_CODE,
-  E_OAUTH_STATE_MISMATCH: () => E_OAUTH_STATE_MISMATCH
-});
-import { createError } from "@adonisjs/core/exceptions";
-var E_OAUTH_MISSING_CODE = createError(
-  'Cannot request access token. Redirect request is missing the "%s" param',
-  "E_OAUTH_MISSING_CODE",
-  500
-);
-var E_OAUTH_STATE_MISMATCH = createError(
-  "Unable to verify re-redirect state",
-  "E_OAUTH_STATE_MISMATCH",
-  400
-);
-
 // src/redirect_request.ts
 import { UrlBuilder } from "@poppinss/oauth-client";
 var RedirectRequest = class extends UrlBuilder {
+  /**
+   * Optional callback used to transform scope values before serialization.
+   */
   #scopesTransformer;
+  /**
+   * Query parameter name used to serialize the scope string.
+   */
   #scopeParamName;
+  /**
+   * Separator used when joining multiple scopes.
+   */
   #scopeSeparator;
   /**
+   * Create a redirect request builder with scope helpers.
+   *
    * @param baseUrl - The authorization URL for the OAuth provider
    * @param scopeParamName - The query parameter name for scopes (e.g., 'scope')
    * @param scopeSeparator - The character used to separate multiple scopes (e.g., ' ' or ',')
@@ -42,6 +31,7 @@ var RedirectRequest = class extends UrlBuilder {
    * require scope prefixes or transformations.
    *
    * @param callback - Function that transforms the scopes array
+   * @returns The current redirect request instance.
    *
    * @example
    * ```ts
@@ -59,6 +49,7 @@ var RedirectRequest = class extends UrlBuilder {
    * any previously set scopes.
    *
    * @param scopes - Array of scope strings to request
+   * @returns The current redirect request instance.
    *
    * @example
    * ```ts
@@ -77,6 +68,7 @@ var RedirectRequest = class extends UrlBuilder {
    * for adding scopes without replacing the default ones.
    *
    * @param scopes - Array of scope strings to merge
+   * @returns The current redirect request instance.
    *
    * @example
    * ```ts
@@ -101,6 +93,8 @@ var RedirectRequest = class extends UrlBuilder {
   /**
    * Clear all existing scopes from the authorization request.
    *
+   * @returns The current redirect request instance.
+   *
    * @example
    * ```ts
    * request.clearScopes().scopes(['user'])
@@ -113,8 +107,5 @@ var RedirectRequest = class extends UrlBuilder {
 };
 
 export {
-  E_OAUTH_MISSING_CODE,
-  E_OAUTH_STATE_MISMATCH,
-  errors_exports,
   RedirectRequest
 };

package/build/{chunk-KWRXS6EG.js → chunk-SBQAXPUK.js}

@@ -1,14 +1,18 @@
 import {
-  E_OAUTH_MISSING_CODE,
-  E_OAUTH_STATE_MISMATCH,
   RedirectRequest
-} from "./chunk-KSJ4CFTC.js";
+} from "./chunk-NK6X76EQ.js";
+import {
+  E_OAUTH_MISSING_CODE,
+  E_OAUTH_STATE_MISMATCH
+} from "./chunk-6BP2DK5A.js";
 
 // src/abstract_drivers/oauth1.ts
 import { Exception } from "@adonisjs/core/exceptions";
 import { Oauth1Client } from "@poppinss/oauth-client/oauth1";
 var Oauth1Driver = class extends Oauth1Client {
   /**
+   * Create a new OAuth1 driver instance.
+   *
    * @param ctx - The current HTTP context
    * @param config - OAuth1 driver configuration
    */
@@ -17,6 +21,8 @@ var Oauth1Driver = class extends Oauth1Client {
     this.ctx = ctx;
     this.config = config;
   }
+  ctx;
+  config;
   /**
    * OAuth protocol version identifier
    */
@@ -29,6 +35,8 @@ var Oauth1Driver = class extends Oauth1Client {
   /**
    * 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.
    */
   get oauthSecretCookieName() {
     return `${this.oauthTokenCookieName}_secret`;
@@ -38,6 +46,7 @@ var Oauth1Driver = class extends Oauth1Client {
    * with scope support.
    *
    * @param url - The base authorization URL
+   * @returns A redirect request builder for the given URL.
    */
   urlBuilder(url) {
     return new RedirectRequest(url, this.scopeParamName, this.scopesSeparator);
@@ -63,6 +72,8 @@ var Oauth1Driver = class extends Oauth1Client {
   }
   /**
    * Stores the OAuth token in an encrypted cookie for later use
+   *
+   * @param token - The request token to persist.
    */
   #persistToken(token) {
     this.ctx.response.encryptedCookie(this.oauthTokenCookieName, token, {
@@ -72,6 +83,8 @@ var Oauth1Driver = class extends Oauth1Client {
   }
   /**
    * Stores the OAuth token secret in an encrypted cookie for later use
+   *
+   * @param secret - The request token secret to persist.
    */
   #persistSecret(secret) {
     this.ctx.response.encryptedCookie(this.oauthSecretCookieName, secret, {
@@ -82,6 +95,8 @@ var Oauth1Driver = class extends Oauth1Client {
   /**
    * OAuth1 does not support stateless authentication due to the
    * three-legged authentication flow requiring token persistence.
+   *
+   * @returns This method never returns.
    */
   stateless() {
     throw new Exception("OAuth1 does not support stateless authorization");
@@ -92,6 +107,7 @@ var Oauth1Driver = class extends Oauth1Client {
    * in a different context.
    *
    * @param callback - Optional callback to customize the redirect request
+   * @returns A promise resolving to the authorization URL.
    *
    * @example
    * ```ts
@@ -106,6 +122,7 @@ var Oauth1Driver = class extends Oauth1Client {
    * 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
@@ -127,12 +144,16 @@ var Oauth1Driver = class extends Oauth1Client {
   /**
    * 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() {
     return this.oauthTokenCookieValue !== this.ctx.request.input(this.oauthTokenParamName);
   }
   /**
    * Check if an error was returned by the OAuth provider.
+   *
+   * @returns `true` when an error exists on the callback request.
    */
   hasError() {
     return !!this.getError();
@@ -140,6 +161,8 @@ var Oauth1Driver = class extends Oauth1Client {
   /**
    * 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() {
     const error = this.ctx.request.input(this.errorParamName);
@@ -153,12 +176,16 @@ var Oauth1Driver = class extends Oauth1Client {
   }
   /**
    * Get the OAuth verifier from the callback request.
+   *
+   * @returns The OAuth verifier when present.
    */
   getCode() {
     return this.ctx.request.input(this.oauthTokenVerifierName, null);
   }
   /**
    * Check if the OAuth verifier is present in the callback request.
+   *
+   * @returns `true` when the callback request contains an OAuth verifier.
    */
   hasCode() {
     return !!this.getCode();
@@ -169,6 +196,7 @@ var Oauth1Driver = class extends Oauth1Client {
    * making the request.
    *
    * @param callback - Optional callback to customize the token request
+   * @returns A promise resolving to the access token payload.
    *
    * @example
    * ```ts
@@ -194,6 +222,8 @@ var Oauth1Driver = class extends Oauth1Client {
   }
   /**
    * Not applicable with OAuth1. Use `userFromTokenAndSecret` instead.
+   *
+   * @returns This method never returns.
    */
   async userFromToken() {
     throw new Exception(

package/build/chunk-TFPW7D75.js

@@ -0,0 +1,125 @@
+import {
+  E_LOCAL_SIGNUP_DISALLOWED,
+  E_UNKNOWN_ALLY_PROVIDER
+} from "./chunk-6BP2DK5A.js";
+
+// src/ally_manager.ts
+var AllyManager = class {
+  /**
+   * Create a new Ally manager for the current request.
+   *
+   * @param config - Map of provider names to driver factory functions
+   * @param ctx - The current HTTP context
+   */
+  constructor(config, ctx) {
+    this.config = config;
+    this.#ctx = ctx;
+  }
+  config;
+  /**
+   * The current HTTP context bound to this manager instance.
+   */
+  #ctx;
+  /**
+   * Cache of instantiated providers keyed by provider name.
+   */
+  #driversCache = /* @__PURE__ */ new Map();
+  /**
+   * Find if a provider has been configured.
+   *
+   * @param provider - The provider name to check.
+   * @returns `true` when the provider exists in the manager config.
+   *
+   * @example
+   * ```ts
+   * if (ally.has(provider)) {
+   *   await ally.use(provider).redirect()
+   * }
+   * ```
+   */
+  has(provider) {
+    return provider in this.config;
+  }
+  /**
+   * Find if a provider allows local signup.
+   *
+   * @param provider - The configured provider name to inspect.
+   * @returns `true` when the provider does not opt out of local signup.
+   *
+   * @example
+   * ```ts
+   * if (ally.allowsLocalSignup('github')) {
+   *   return ally.use('github', { intent: 'signup' }).redirect()
+   * }
+   * ```
+   */
+  allowsLocalSignup(provider) {
+    if (!this.has(provider)) {
+      throw new E_UNKNOWN_ALLY_PROVIDER([provider]);
+    }
+    const driver = this.use(provider);
+    return !driver.config?.disallowLocalSignup;
+  }
+  /**
+   * Returns configured provider names.
+   *
+   * @returns An array of configured provider names.
+   *
+   * @example
+   * ```ts
+   * const providers = ally.configuredProviderNames()
+   * ```
+   */
+  configuredProviderNames() {
+    return Object.keys(this.config);
+  }
+  /**
+   * Returns provider names that allow local signup.
+   *
+   * @returns An array of configured provider names that allow signup flows.
+   *
+   * @example
+   * ```ts
+   * const signupProviders = ally.signupProviderNames()
+   * ```
+   */
+  signupProviderNames() {
+    return this.configuredProviderNames().filter((provider) => this.allowsLocalSignup(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')
+   * @param options - Additional options used to qualify the provider usage.
+   * @returns The instantiated social authentication driver.
+   *
+   * @example
+   * ```ts
+   * const github = ally.use('github')
+   * await github.redirect()
+   *
+   * const signupDriver = ally.use('github', { intent: 'signup' })
+   * await signupDriver.redirect()
+   * ```
+   */
+  use(provider, options) {
+    if (this.#driversCache.has(provider)) {
+      return this.#driversCache.get(provider);
+    }
+    if (!this.has(String(provider))) {
+      throw new E_UNKNOWN_ALLY_PROVIDER([provider]);
+    }
+    const driver = this.config[provider];
+    if (options?.intent === "signup" && !this.allowsLocalSignup(provider)) {
+      throw new E_LOCAL_SIGNUP_DISALLOWED([provider]);
+    }
+    const driverInstance = driver(this.#ctx);
+    this.#driversCache.set(provider, driverInstance);
+    return driverInstance;
+  }
+};
+
+export {
+  AllyManager
+};