@adonisjs/ally 6.0.0-next.0 → 6.1.0

package/build/src/drivers/twitter_x.js

@@ -0,0 +1,169 @@
+import {
+  Oauth2Driver
+} from "../../chunk-46TOMXWK.js";
+import "../../chunk-NK6X76EQ.js";
+import "../../chunk-6BP2DK5A.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,39 @@
 /**
  * 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;
 /**
  * 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 (args?: any, options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;
+/**
+ * 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) => import("@adonisjs/core/exceptions").Exception;
+/**
+ * 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_LOCAL_SIGNUP_DISALLOWED: new (args: [string], options?: ErrorOptions) => import("@adonisjs/core/exceptions").Exception;

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'])

package/build/src/types.d.ts

@@ -8,9 +8,34 @@ export type { Oauth1RequestToken };
 export type { ApiRequestContract };
 export type { Oauth2ClientConfig as Oauth2DriverConfig };
 export type { Oauth1ClientConfig as Oauth1DriverConfig };
+/**
+ * Allowed high-level intents when using a provider through `AllyManager`.
+ *
+ * @example
+ * ```ts
+ * ally.use('github', { intent: 'signup' })
+ * ```
+ */
+export type AllyManagerIntent = 'signup' | 'login' | 'link';
+/**
+ * Options accepted by `AllyManager.use`.
+ */
+export type AllyManagerUseOptions = {
+    /**
+     * The interaction intent associated with the provider usage.
+     */
+    intent?: AllyManagerIntent;
+};
 /**
  * Issue: https://github.com/Microsoft/TypeScript/issues/29729
  * Solution: https://github.com/sindresorhus/type-fest/blob/main/source/literal-union.d.ts
+ *
+ * Allows known literal values while still accepting arbitrary strings.
+ *
+ * @example
+ * ```ts
+ * const scopes: LiteralStringUnion<'email' | 'profile'>[] = ['email']
+ * ```
  */
 export type LiteralStringUnion<LiteralType> = LiteralType | (string & {
     _?: never;
@@ -18,92 +43,172 @@ export type LiteralStringUnion<LiteralType> = LiteralType | (string & {
 /**
  * Extension of oauth-client redirect request with support
  * for defining scopes as first class citizen
+ *
+ * @typeParam Scopes - The known set of supported scopes for the provider.
  */
 export interface RedirectRequestContract<Scopes extends string = string> extends ClientRequestContract {
     /**
      * Define a callback to transform scopes before they are defined
      * as a param
+     *
+     * @param callback - Callback used to transform scope values before serialization.
+     * @returns The current redirect request instance.
      */
     transformScopes(callback: (scopes: LiteralStringUnion<Scopes>[]) => string[]): this;
     /**
      * Define the scopes for authorization
+     *
+     * @param scopes - The scopes to serialize on the request.
+     * @returns The current redirect request instance.
      */
     scopes(scopes: LiteralStringUnion<Scopes>[]): this;
     /**
      * Merge to existing pre-defined scopes
+     *
+     * @param scopes - Additional scopes to merge with the existing list.
+     * @returns The current redirect request instance.
      */
     mergeScopes(scopes: LiteralStringUnion<Scopes>[]): this;
     /**
      * Clear existing scopes
+     *
+     * @returns The current redirect request instance.
      */
     clearScopes(): this;
 }
 /**
  * The user fetched from the oauth provider.
+ *
+ * @typeParam Token - The access token shape returned by the provider.
  */
 export interface AllyUserContract<Token extends Oauth2AccessToken | Oauth1AccessToken> {
+    /**
+     * Unique user identifier returned by the provider.
+     */
     id: string;
+    /**
+     * Provider-specific nickname or username.
+     */
     nickName: string;
+    /**
+     * Display name returned by the provider.
+     */
     name: string;
+    /**
+     * Primary email address returned by the provider, when available.
+     */
     email: string | null;
+    /**
+     * Email verification state as inferred from the provider payload.
+     */
     emailVerificationState: 'verified' | 'unverified' | 'unsupported';
+    /**
+     * URL to the user's avatar, when available.
+     */
     avatarUrl: string | null;
+    /**
+     * Access token information associated with the user payload.
+     */
     token: Token;
+    /**
+     * Original provider response body.
+     */
     original: any;
 }
 /**
  * Every driver should implement this contract
+ *
+ * @typeParam Token - The token shape returned by the driver.
+ * @typeParam Scopes - The supported authorization scopes for the driver.
  */
 export interface AllyDriverContract<Token extends Oauth2AccessToken | Oauth1AccessToken, Scopes extends string> {
+    /**
+     * OAuth protocol version supported by the driver.
+     */
     version: 'oauth1' | 'oauth2';
+    /**
+     * Driver configuration. Drivers may expose their config publicly so
+     * the manager can inspect runtime capabilities.
+     */
+    config?: any;
     /**
      * Perform stateless authentication. Only applicable for Oauth2 clients
+     *
+     * @returns The current driver instance.
      */
     stateless(): this;
     /**
      * Redirect user for authorization
+     *
+     * @param callback - Optional callback used to customize the redirect request.
+     * @returns A promise that resolves after the redirect response is prepared.
      */
     redirect(callback?: (request: RedirectRequestContract<Scopes>) => void): Promise<void>;
     /**
      * Get redirect url. You must manage the state yourself when redirecting
      * manually
+     *
+     * @param callback - Optional callback used to customize the redirect request.
+     * @returns A promise resolving to the computed redirect URL.
      */
     redirectUrl(callback?: (request: RedirectRequestContract<Scopes>) => void): Promise<string>;
     /**
      * Find if the current request has authorization code or oauth token
+     *
+     * @returns `true` when the current request contains an authorization code or token.
      */
     hasCode(): boolean;
     /**
      * Get the current request authorization code or oauth token. Returns
      * null if there no code
+     *
+     * @returns The current authorization code or token value.
      */
     getCode(): string | null;
     /**
      * Find if the current error code is for access denied
+     *
+     * @returns `true` when the provider reported an access-denied response.
      */
     accessDenied(): boolean;
     /**
      * Find if there is a state mismatch
+     *
+     * @returns `true` when the request state does not match the stored state.
      */
     stateMisMatch(): boolean;
     /**
      * Find if there is an error post redirect
+     *
+     * @returns `true` when the callback request contains a provider error.
      */
     hasError(): boolean;
     /**
      * Get the post redirect error
+     *
+     * @returns The provider error code or message, when present.
      */
     getError(): string | null;
     /**
      * Get access token
+     *
+     * @param callback - Optional callback used to customize the token request.
+     * @returns A promise resolving to the access token payload.
      */
     accessToken(callback?: (request: ApiRequestContract) => void): Promise<Token>;
     /**
      * Returns details for the authorized user
+     *
+     * @param callback - Optional callback used to customize downstream API requests.
+     * @returns A promise resolving to the authenticated user profile.
      */
     user(callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<Token>>;
     /**
      * Finds the user by access token. Applicable with "Oauth2" only
+     *
+     * @param token - The access token to use.
+     * @param callback - Optional callback used to customize downstream API requests.
+     * @returns A promise resolving to the authenticated user profile.
      */
     userFromToken(token: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
@@ -111,6 +216,11 @@ export interface AllyDriverContract<Token extends Oauth2AccessToken | Oauth1Acce
     }>>;
     /**
      * Finds the user by access token. Applicable with "Oauth1" only
+     *
+     * @param token - The OAuth1 token to use.
+     * @param secret - The OAuth1 token secret to use.
+     * @param callback - Optional callback used to customize downstream API requests.
+     * @returns A promise resolving to the authenticated user profile.
      */
     userFromTokenAndSecret(token: string, secret: string, callback?: (request: ApiRequestContract) => void): Promise<AllyUserContract<{
         token: string;
@@ -120,6 +230,9 @@ export interface AllyDriverContract<Token extends Oauth2AccessToken | Oauth1Acce
 /**
  * The manager driver factory method is called by the AllyManager to create
  * an instance of a driver during an HTTP request
+ *
+ * @param ctx - The current HTTP context.
+ * @returns A social authentication driver instance.
  */
 export type AllyManagerDriverFactory = (ctx: HttpContext) => AllyDriverContract<any, any>;
 /**
@@ -147,6 +260,7 @@ export type DiscordToken = {
  * Extra options available for Discord
  */
 export type DiscordDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
     userInfoUrl?: string;
     scopes?: LiteralStringUnion<DiscordScopes>[];
     prompt?: 'consent' | 'none';
@@ -176,6 +290,7 @@ export type GithubToken = {
  * Extra options available for Github
  */
 export type GithubDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
     login?: string;
     scopes?: LiteralStringUnion<GithubScopes>[];
     allowSignup?: boolean;
@@ -200,8 +315,33 @@ export type TwitterToken = {
  * Extra options available for twitter
  */
 export type TwitterDriverConfig = Oauth1ClientConfig & {
+    disallowLocalSignup?: boolean;
     userInfoUrl?: string;
 };
+/**
+ * ----------------------------------------
+ * Twitter X driver
+ * ----------------------------------------
+ */
+/**
+ * Common X OAuth2 scopes.
+ * https://docs.x.com/fundamentals/authentication/oauth-2.0/user-access-token
+ */
+export type TwitterXScopes = 'tweet.read' | 'tweet.write' | 'tweet.moderate.write' | 'users.email' | 'users.read' | 'follows.read' | 'follows.write' | 'offline.access' | 'space.read' | 'mute.read' | 'mute.write' | 'like.read' | 'like.write' | 'list.read' | 'list.write' | 'block.read' | 'block.write' | 'bookmark.read' | 'bookmark.write' | 'dm.read' | 'dm.write' | 'media.write';
+/**
+ * Shape of the X access token
+ */
+export type TwitterXToken = Oauth2AccessToken & {
+    scope: string;
+};
+/**
+ * Extra options available for X
+ */
+export type TwitterXDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
+    userInfoUrl?: string;
+    scopes?: LiteralStringUnion<TwitterXScopes>[];
+};
 /**
  * ----------------------------------------
  * Google driver
@@ -230,6 +370,7 @@ export type GoogleToken = Oauth2AccessToken & {
  * https://developers.google.com/identity/protocols/oauth2/openid-connect#re-consent
  */
 export type GoogleDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
     userInfoUrl?: string;
     /**
      * Can be configured at runtime
@@ -266,6 +407,7 @@ export type LinkedInToken = {
  * https://docs.microsoft.com/en-us/linkedin/shared/authentication/authorization-code-flow?context=linkedin%2Fcontext&tabs=HTTPS#step-2-request-an-authorization-code
  */
 export type LinkedInDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
     userInfoUrl?: string;
     userEmailUrl?: string;
     /**
@@ -297,6 +439,7 @@ export type LinkedInOpenidConnectScopes = 'openid' | 'profile' | 'email';
  * The configuration accepted by the driver implementation.
  */
 export type LinkedInOpenidConnectDriverConfig = {
+    disallowLocalSignup?: boolean;
     clientId: string;
     clientSecret: string;
     callbackUrl: string;
@@ -338,6 +481,7 @@ export type FacebookToken = {
  * https://developers.facebook.com/docs/facebook-login/manually-build-a-login-flow
  */
 export type FacebookDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
     userInfoUrl?: string;
     /**
      * Can be configured at runtime
@@ -371,6 +515,7 @@ export type SpotifyToken = {
  * Extra options available for Spotify
  */
 export type SpotifyDriverConfig = Oauth2ClientConfig & {
+    disallowLocalSignup?: boolean;
     scopes?: LiteralStringUnion<SpotifyScopes>[];
     showDialog?: boolean;
 };
@@ -383,6 +528,11 @@ export type SpotifyDriverConfig = Oauth2ClientConfig & {
  */
 export interface SocialProviders {
 }
+/**
+ * Infer the configured social providers from an Ally config provider.
+ *
+ * @typeParam T - The Ally config provider to inspect.
+ */
 export type InferSocialProviders<T extends ConfigProvider<Record<string, AllyManagerDriverFactory>>> = Awaited<ReturnType<T['resolver']>>;
 /**
  * Ally service is shared with the HTTP context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adonisjs/ally",
-  "version": "6.0.0-next.0",
+  "version": "6.1.0",
   "description": "Social authentication provider for AdonisJS",
   "type": "module",
   "main": "build/index.js",
@@ -21,7 +21,7 @@
   },
   "scripts": {
     "pretest": "npm run lint",
-    "test": "c8 npm run quick:test",
+    "test": "npm run quick:test",
     "lint": "eslint",
     "format": "prettier --write .",
     "typecheck": "tsc --noEmit",
@@ -39,33 +39,39 @@
     "quick:test": "cross-env NODE_DEBUG=\"adonisjs:ally\" node --enable-source-maps --import=@poppinss/ts-exec bin/test.ts"
   },
   "devDependencies": {
-    "@adonisjs/assembler": "^8.0.0-next.14",
-    "@adonisjs/core": "^7.0.0-next.8",
-    "@adonisjs/eslint-config": "^3.0.0-next.4",
+    "@adonisjs/assembler": "^8.4.0",
+    "@adonisjs/core": "^7.3.0",
+    "@adonisjs/eslint-config": "^3.0.0",
     "@adonisjs/prettier-config": "^1.4.5",
-    "@adonisjs/tsconfig": "^2.0.0-next.3",
-    "@japa/assert": "^4.1.1",
-    "@japa/expect-type": "^2.0.3",
-    "@japa/file-system": "^2.3.2",
-    "@japa/runner": "^4.4.0",
-    "@poppinss/ts-exec": "^1.4.1",
-    "@release-it/conventional-changelog": "^10.0.1",
-    "@types/node": "^24.10.0",
-    "c8": "^10.1.3",
+    "@adonisjs/tsconfig": "^2.0.0",
+    "@japa/assert": "^4.2.0",
+    "@japa/expect-type": "^2.0.4",
+    "@japa/file-system": "^3.0.0",
+    "@japa/runner": "^5.3.0",
+    "@poppinss/ts-exec": "^1.4.4",
+    "@release-it/conventional-changelog": "^10.0.6",
+    "@types/node": "^25.5.2",
+    "c8": "^11.0.0",
     "copyfiles": "^2.4.1",
     "cross-env": "^10.1.0",
     "del-cli": "^7.0.0",
-    "eslint": "^9.39.0",
-    "prettier": "^3.6.2",
-    "release-it": "^19.0.5",
-    "tsup": "^8.5.0",
-    "typescript": "^5.9.3"
+    "eslint": "^10.2.0",
+    "prettier": "^3.8.1",
+    "release-it": "^19.2.4",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2"
   },
   "dependencies": {
-    "@poppinss/oauth-client": "^7.0.1"
+    "@poppinss/oauth-client": "^7.2.0"
   },
   "peerDependencies": {
-    "@adonisjs/core": "^7.0.0-next.8"
+    "@adonisjs/core": "^7.0.0-next.8 || ^7.0.0",
+    "@adonisjs/assembler": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@adonisjs/assembler": {
+      "optional": true
+    }
   },
   "homepage": "https://github.com/adonisjs/ally#readme",
   "repository": {

package/build/chunk-MLKGABMK.js

@@ -1,9 +0,0 @@
-var __defProp = Object.defineProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-
-export {
-  __export
-};