@adonisjs/ally 6.0.0 → 6.2.0

package/build/src/drivers/twitter.js

@@ -1,8 +1,8 @@
 import {
   Oauth1Driver
-} from "../../chunk-KWRXS6EG.js";
-import "../../chunk-KSJ4CFTC.js";
-import "../../chunk-MLKGABMK.js";
+} from "../../chunk-4QTU45GZ.js";
+import "../../chunk-NK6X76EQ.js";
+import "../../chunk-TSIMPJ6I.js";
 
 // src/drivers/twitter.ts
 var TwitterDriver = class extends Oauth1Driver {
@@ -16,9 +16,23 @@ var TwitterDriver = class extends Oauth1Driver {
     this.config = config;
     this.loadState();
   }
+  ctx;
+  config;
+  /**
+   * Twitter request-token endpoint URL.
+   */
   requestTokenUrl = "https://api.twitter.com/oauth/request_token";
+  /**
+   * Twitter authorization endpoint URL.
+   */
   authorizeUrl = "https://api.twitter.com/oauth/authenticate";
+  /**
+   * Twitter access-token endpoint URL.
+   */
   accessTokenUrl = "https://api.twitter.com/oauth/access_token";
+  /**
+   * Twitter profile endpoint URL.
+   */
   userInfoUrl = "https://api.twitter.com/1.1/account/verify_credentials.json";
   /**
    * The query string param name for the error.
@@ -46,6 +60,9 @@ var TwitterDriver = class extends Oauth1Driver {
    * Twitter doesn't support scopes
    */
   scopeParamName = "";
+  /**
+   * Scope separator placeholder maintained for OAuth1 compatibility.
+   */
   scopesSeparator = " ";
   /**
    * Fetches the authenticated user's profile information from the Twitter API.
@@ -119,6 +136,8 @@ var TwitterDriver = class extends Oauth1Driver {
   /**
    * Check if the error from the callback indicates that the user
    * denied authorization.
+   *
+   * @returns `true` when the request contains the denial marker.
    */
   accessDenied() {
     return this.ctx.request.input("denied");

package/build/src/drivers/twitter_x.d.ts

@@ -0,0 +1,137 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { HttpClient } from '@poppinss/oauth-client';
+import type { TwitterXToken, TwitterXScopes, ApiRequestContract, TwitterXDriverConfig, RedirectRequestContract } from '../types.ts';
+import { Oauth2Driver } from '../abstract_drivers/oauth2.ts';
+/**
+ * X OAuth2 driver for authenticating users via the OAuth 2.0 authorization
+ * code flow with PKCE.
+ */
+export declare class TwitterXDriver extends Oauth2Driver<TwitterXToken, TwitterXScopes> {
+    config: TwitterXDriverConfig;
+    /**
+     * X token endpoint URL.
+     */
+    protected accessTokenUrl: string;
+    /**
+     * X authorization endpoint URL.
+     */
+    protected authorizeUrl: string;
+    /**
+     * X user profile endpoint URL.
+     */
+    protected userInfoUrl: string;
+    /**
+     * The param name for the authorization code
+     */
+    protected codeParamName: string;
+    /**
+     * The param name for the error
+     */
+    protected errorParamName: string;
+    /**
+     * Cookie name for storing the "twitter_x_oauth_state"
+     */
+    protected stateCookieName: string;
+    /**
+     * Cookie name for storing the PKCE code verifier
+     */
+    protected codeVerifierCookieName: string;
+    /**
+     * Parameter name to be used for sending and receiving the state from X
+     */
+    protected stateParamName: string;
+    /**
+     * Parameter name for defining the scopes
+     */
+    protected scopeParamName: string;
+    /**
+     * Scopes separator
+     */
+    protected scopesSeparator: string;
+    /**
+     * Create a new X driver instance.
+     *
+     * @param ctx - The current HTTP context.
+     * @param config - X driver configuration.
+     */
+    constructor(ctx: HttpContext, config: TwitterXDriverConfig);
+    /**
+     * Configures the redirect request with X-specific requirements.
+     *
+     * @param request - The redirect request to configure.
+     */
+    protected configureRedirectRequest(request: RedirectRequestContract<TwitterXScopes>): void;
+    /**
+     * Configures the token request with the PKCE verifier and the Basic auth
+     * header required for confidential X clients.
+     *
+     * @param request - The token request to configure.
+     */
+    protected configureAccessTokenRequest(request: ApiRequestContract): void;
+    /**
+     * Creates an authenticated request for X API calls.
+     *
+     * @param url - The API endpoint URL.
+     * @param token - The access token to send.
+     * @returns A configured HTTP client instance.
+     */
+    protected getAuthenticatedRequest(url: string, token: string): HttpClient;
+    /**
+     * Fetches the authenticated user's profile from /2/users/me.
+     *
+     * @param token - The access token to use.
+     * @param includeConfirmedEmail - Whether to request the confirmed email field.
+     * @param callback - Optional callback to customize the API request.
+     */
+    protected getUserInfo(token: string, includeConfirmedEmail: boolean, callback?: (request: ApiRequestContract) => void): Promise<{
+        id: any;
+        nickName: any;
+        name: any;
+        email: any;
+        emailVerificationState: "unsupported";
+        avatarUrl: any;
+        original: any;
+    }>;
+    /**
+     * Check if the error from the callback indicates that the user denied
+     * authorization.
+     *
+     * @returns `true` when the provider reported an access-denied error.
+     */
+    accessDenied(): boolean;
+    /**
+     * Fetches the authenticated user using the authorization code from the
+     * callback request.
+     *
+     * @param callback - Optional callback to customize the API request.
+     */
+    user(callback?: (request: ApiRequestContract) => void): Promise<{
+        token: TwitterXToken;
+        id: any;
+        nickName: any;
+        name: any;
+        email: any;
+        emailVerificationState: "unsupported";
+        avatarUrl: any;
+        original: any;
+    }>;
+    /**
+     * Fetches the user profile using an existing access token.
+     *
+     * @param token - The access token to use.
+     * @param callback - Optional callback to customize the API request.
+     */
+    userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<{
+        token: {
+            token: string;
+            type: "bearer";
+        };
+        id: any;
+        nickName: any;
+        name: any;
+        email: any;
+        emailVerificationState: "unsupported";
+        avatarUrl: any;
+        original: any;
+    }>;
+}

package/build/src/drivers/twitter_x.js

@@ -0,0 +1,169 @@
+import {
+  Oauth2Driver
+} from "../../chunk-7V2EH7U6.js";
+import "../../chunk-NK6X76EQ.js";
+import "../../chunk-TSIMPJ6I.js";
+
+// src/drivers/twitter_x.ts
+var TwitterXDriver = class extends Oauth2Driver {
+  /**
+   * Create a new X driver instance.
+   *
+   * @param ctx - The current HTTP context.
+   * @param config - X driver configuration.
+   */
+  constructor(ctx, config) {
+    super(ctx, config);
+    this.config = config;
+    this.loadState();
+  }
+  config;
+  /**
+   * X token endpoint URL.
+   */
+  accessTokenUrl = "https://api.x.com/2/oauth2/token";
+  /**
+   * X authorization endpoint URL.
+   */
+  authorizeUrl = "https://x.com/i/oauth2/authorize";
+  /**
+   * X user profile endpoint URL.
+   */
+  userInfoUrl = "https://api.x.com/2/users/me";
+  /**
+   * The param name for the authorization code
+   */
+  codeParamName = "code";
+  /**
+   * The param name for the error
+   */
+  errorParamName = "error";
+  /**
+   * Cookie name for storing the "twitter_x_oauth_state"
+   */
+  stateCookieName = "twitter_x_oauth_state";
+  /**
+   * Cookie name for storing the PKCE code verifier
+   */
+  codeVerifierCookieName = "twitter_x_oauth_code_verifier";
+  /**
+   * Parameter name to be used for sending and receiving the state from X
+   */
+  stateParamName = "state";
+  /**
+   * Parameter name for defining the scopes
+   */
+  scopeParamName = "scope";
+  /**
+   * Scopes separator
+   */
+  scopesSeparator = " ";
+  /**
+   * Configures the redirect request with X-specific requirements.
+   *
+   * @param request - The redirect request to configure.
+   */
+  configureRedirectRequest(request) {
+    request.scopes(this.config.scopes || ["tweet.read", "users.read", "users.email"]);
+    request.param("response_type", "code");
+  }
+  /**
+   * Configures the token request with the PKCE verifier and the Basic auth
+   * header required for confidential X clients.
+   *
+   * @param request - The token request to configure.
+   */
+  configureAccessTokenRequest(request) {
+    const credentials = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString(
+      "base64"
+    );
+    request.header("Authorization", `Basic ${credentials}`);
+    request.clearField("client_id");
+    request.clearField("client_secret");
+  }
+  /**
+   * Creates an authenticated request for X API calls.
+   *
+   * @param url - The API endpoint URL.
+   * @param token - The access token to send.
+   * @returns A configured HTTP client instance.
+   */
+  getAuthenticatedRequest(url, token) {
+    const request = this.httpClient(url);
+    request.header("Authorization", `Bearer ${token}`);
+    request.header("Accept", "application/json");
+    request.parseAs("json");
+    return request;
+  }
+  /**
+   * Fetches the authenticated user's profile from /2/users/me.
+   *
+   * @param token - The access token to use.
+   * @param includeConfirmedEmail - Whether to request the confirmed email field.
+   * @param callback - Optional callback to customize the API request.
+   */
+  async getUserInfo(token, includeConfirmedEmail, callback) {
+    const request = this.getAuthenticatedRequest(this.config.userInfoUrl || this.userInfoUrl, token);
+    request.param(
+      "user.fields",
+      includeConfirmedEmail ? "profile_image_url,confirmed_email" : "profile_image_url"
+    );
+    if (typeof callback === "function") {
+      callback(request);
+    }
+    const body = await request.get();
+    const user = body.data;
+    return {
+      id: user.id,
+      nickName: user.username,
+      name: user.name ?? user.username,
+      email: user.confirmed_email ?? null,
+      emailVerificationState: "unsupported",
+      avatarUrl: user.profile_image_url ?? null,
+      original: body
+    };
+  }
+  /**
+   * Check if the error from the callback indicates that the user denied
+   * authorization.
+   *
+   * @returns `true` when the provider reported an access-denied error.
+   */
+  accessDenied() {
+    const error = this.getError();
+    if (!error) {
+      return false;
+    }
+    return error === "access_denied";
+  }
+  /**
+   * Fetches the authenticated user using the authorization code from the
+   * callback request.
+   *
+   * @param callback - Optional callback to customize the API request.
+   */
+  async user(callback) {
+    const token = await this.accessToken(callback);
+    const user = await this.getUserInfo(token.token, token.scope.includes("users.email"), callback);
+    return {
+      ...user,
+      token
+    };
+  }
+  /**
+   * Fetches the user profile using an existing access token.
+   *
+   * @param token - The access token to use.
+   * @param callback - Optional callback to customize the API request.
+   */
+  async userFromToken(token, callback) {
+    const user = await this.getUserInfo(token, false, callback);
+    return {
+      ...user,
+      token: { token, type: "bearer" }
+    };
+  }
+};
+export {
+  TwitterXDriver
+};

package/build/src/errors.d.ts

@@ -1,10 +1,198 @@
+import { Exception } from '@adonisjs/core/exceptions';
+import { type HttpContext } from '@adonisjs/core/http';
+/**
+ * Base exception that self-handles by content-negotiating the
+ * HTTP response (HTML with session flash, JSON, JSONAPI)
+ * and supporting i18n translation.
+ */
+export declare abstract class HttpResponseException extends Exception {
+    abstract identifier: string;
+    /**
+     * Returns the message to be sent in the HTTP response.
+     * Feel free to override this method and return a custom
+     * response.
+     */
+    getResponseMessage(error: this, ctx: HttpContext): string;
+    /**
+     * Converts exception to an HTTP response
+     */
+    handle(error: this, ctx: HttpContext): Promise<void>;
+}
 /**
  * Error thrown when the OAuth redirect is missing the required
  * authorization code or token parameter.
+ *
+ * @example
+ * ```ts
+ * throw new errors.E_OAUTH_MISSING_CODE(['code'])
+ * ```
  */
-export declare const E_OAUTH_MISSING_CODE: new (args: [string], options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;
+export declare const E_OAUTH_MISSING_CODE: {
+    new (args: [string], options?: ErrorOptions): {
+        /**
+         * Translation identifier. Can be customized
+         */
+        identifier: string;
+        /**
+         * Returns the message to be sent in the HTTP response.
+         * Feel free to override this method and return a custom
+         * response.
+         */
+        getResponseMessage(error: /*elided*/ any, ctx: HttpContext): string;
+        /**
+         * Converts exception to an HTTP response
+         */
+        handle(error: /*elided*/ any, ctx: HttpContext): Promise<void>;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    status: number;
+    code: string;
+    help?: string;
+    message?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
 /**
  * Error thrown when the OAuth state parameter does not match
  * the expected value, indicating a potential CSRF attack.
+ *
+ * @example
+ * ```ts
+ * throw new errors.E_OAUTH_STATE_MISMATCH()
+ * ```
+ */
+export declare const E_OAUTH_STATE_MISMATCH: {
+    new (message?: string, options?: ErrorOptions & {
+        code?: string;
+        status?: number;
+    }): {
+        /**
+         * Translation identifier. Can be customized
+         */
+        identifier: string;
+        /**
+         * Returns the message to be sent in the HTTP response.
+         * Feel free to override this method and return a custom
+         * response.
+         */
+        getResponseMessage(error: /*elided*/ any, ctx: HttpContext): string;
+        /**
+         * Converts exception to an HTTP response
+         */
+        handle(error: /*elided*/ any, ctx: HttpContext): Promise<void>;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    status: number;
+    code: string;
+    message: string;
+    help?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * Error thrown when attempting to use an unknown Ally provider.
+ *
+ * @example
+ * ```ts
+ * throw new errors.E_UNKNOWN_ALLY_PROVIDER(['github'])
+ * ```
+ */
+export declare const E_UNKNOWN_ALLY_PROVIDER: {
+    new (args: [string], options?: ErrorOptions): {
+        /**
+         * Translation identifier. Can be customized
+         */
+        identifier: string;
+        /**
+         * Returns the message to be sent in the HTTP response.
+         * Feel free to override this method and return a custom
+         * response.
+         */
+        getResponseMessage(error: /*elided*/ any, ctx: HttpContext): string;
+        /**
+         * Converts exception to an HTTP response
+         */
+        handle(error: /*elided*/ any, ctx: HttpContext): Promise<void>;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    status: number;
+    code: string;
+    help?: string;
+    message?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};
+/**
+ * Error thrown when a provider is used for signup but local signup
+ * is disabled for it.
+ *
+ * @example
+ * ```ts
+ * throw new errors.E_LOCAL_SIGNUP_DISALLOWED(['github'])
+ * ```
  */
-export declare const E_OAUTH_STATE_MISMATCH: new (args?: any, options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;
+export declare const E_LOCAL_SIGNUP_DISALLOWED: {
+    new (args: [string], options?: ErrorOptions): {
+        /**
+         * Translation identifier. Can be customized
+         */
+        identifier: string;
+        /**
+         * Returns the message to be sent in the HTTP response.
+         * Feel free to override this method and return a custom
+         * response.
+         */
+        getResponseMessage(error: /*elided*/ any, ctx: HttpContext): string;
+        /**
+         * Converts exception to an HTTP response
+         */
+        handle(error: /*elided*/ any, ctx: HttpContext): Promise<void>;
+        name: string;
+        help?: string;
+        code?: string;
+        status: number;
+        toString(): string;
+        get [Symbol.toStringTag](): string;
+        message: string;
+        stack?: string;
+        cause?: unknown;
+    };
+    status: number;
+    code: string;
+    help?: string;
+    message?: string;
+    isError(error: unknown): error is Error;
+    captureStackTrace(targetObject: object, constructorOpt?: Function): void;
+    prepareStackTrace(err: Error, stackTraces: NodeJS.CallSite[]): any;
+    stackTraceLimit: number;
+};

package/build/src/redirect_request.d.ts

@@ -8,6 +8,8 @@ import { type LiteralStringUnion } from './types.ts';
 export declare class RedirectRequest<Scopes extends string> extends UrlBuilder {
     #private;
     /**
+     * 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 ',')
@@ -19,6 +21,7 @@ export declare class RedirectRequest<Scopes extends string> extends UrlBuilder {
      * require scope prefixes or transformations.
      *
      * @param callback - Function that transforms the scopes array
+     * @returns The current redirect request instance.
      *
      * @example
      * ```ts
@@ -33,6 +36,7 @@ export declare class RedirectRequest<Scopes extends string> extends UrlBuilder {
      * any previously set scopes.
      *
      * @param scopes - Array of scope strings to request
+     * @returns The current redirect request instance.
      *
      * @example
      * ```ts
@@ -45,6 +49,7 @@ export declare class RedirectRequest<Scopes extends string> 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
@@ -57,6 +62,8 @@ export declare class RedirectRequest<Scopes extends string> extends UrlBuilder {
     /**
      * Clear all existing scopes from the authorization request.
      *
+     * @returns The current redirect request instance.
+     *
      * @example
      * ```ts
      * request.clearScopes().scopes(['user'])