@adonisjs/ally 5.1.0 → 6.0.0-next.0

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

@@ -1,6 +1,6 @@
 import {
   __export
-} from "./chunk-PZ5AY32C.js";
+} from "./chunk-MLKGABMK.js";
 
 // src/errors.ts
 var errors_exports = {};
@@ -8,7 +8,7 @@ __export(errors_exports, {
   E_OAUTH_MISSING_CODE: () => E_OAUTH_MISSING_CODE,
   E_OAUTH_STATE_MISMATCH: () => E_OAUTH_STATE_MISMATCH
 });
-import { createError } from "@poppinss/utils";
+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",
@@ -26,21 +26,44 @@ var RedirectRequest = class extends UrlBuilder {
   #scopesTransformer;
   #scopeParamName;
   #scopeSeparator;
+  /**
+   * @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 ',')
+   */
   constructor(baseUrl, scopeParamName, scopeSeparator) {
     super(baseUrl);
     this.#scopeParamName = scopeParamName;
     this.#scopeSeparator = scopeSeparator;
   }
   /**
-   * Register a custom function to transform scopes. Exposed for drivers
-   * to implement.
+   * Register a custom function to transform scopes before they are
+   * added to the authorization URL. This is useful for providers that
+   * require scope prefixes or transformations.
+   *
+   * @param callback - Function that transforms the scopes array
+   *
+   * @example
+   * ```ts
+   * request.transformScopes((scopes) => {
+   *   return scopes.map(scope => `https://provider.com/auth/${scope}`)
+   * })
+   * ```
    */
   transformScopes(callback) {
     this.#scopesTransformer = callback;
     return this;
   }
   /**
-   * Define an array of scopes.
+   * Define the scopes to request during authorization. This replaces
+   * any previously set scopes.
+   *
+   * @param scopes - Array of scope strings to request
+   *
+   * @example
+   * ```ts
+   * request.scopes(['user:email', 'read:org'])
+   * ```
    */
   scopes(scopes) {
     if (typeof this.#scopesTransformer === "function") {
@@ -50,7 +73,17 @@ var RedirectRequest = class extends UrlBuilder {
     return this;
   }
   /**
-   * Merge to existing scopes
+   * Merge additional scopes with any existing scopes. This is useful
+   * for adding scopes without replacing the default ones.
+   *
+   * @param scopes - Array of scope strings to merge
+   *
+   * @example
+   * ```ts
+   * request
+   *   .scopes(['user:email'])
+   *   .mergeScopes(['read:org'])
+   * ```
    */
   mergeScopes(scopes) {
     if (typeof this.#scopesTransformer === "function") {
@@ -66,7 +99,12 @@ var RedirectRequest = class extends UrlBuilder {
     return this;
   }
   /**
-   * Clear existing scopes
+   * Clear all existing scopes from the authorization request.
+   *
+   * @example
+   * ```ts
+   * request.clearScopes().scopes(['user'])
+   * ```
    */
   clearScopes() {
     this.clearParam(this.#scopeParamName);
@@ -80,4 +118,3 @@ export {
   errors_exports,
   RedirectRequest
 };
-//# sourceMappingURL=chunk-N72DEJC2.js.map

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

@@ -2,49 +2,58 @@ import {
   E_OAUTH_MISSING_CODE,
   E_OAUTH_STATE_MISMATCH,
   RedirectRequest
-} from "./chunk-N72DEJC2.js";
+} from "./chunk-KSJ4CFTC.js";
 
 // src/abstract_drivers/oauth1.ts
-import { Exception } from "@poppinss/utils";
+import { Exception } from "@adonisjs/core/exceptions";
 import { Oauth1Client } from "@poppinss/oauth-client/oauth1";
 var Oauth1Driver = class extends Oauth1Client {
+  /**
+   * @param ctx - The current HTTP context
+   * @param config - OAuth1 driver configuration
+   */
   constructor(ctx, config) {
     super(config);
     this.ctx = ctx;
     this.config = config;
   }
   /**
-   * 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
    */
   oauthTokenCookieValue;
   oauthSecretCookieValue;
   /**
-   * The cookie name for storing the secret
+   * The cookie name for storing the OAuth token secret.
+   * Automatically derived from the token cookie name.
    */
   get oauthSecretCookieName() {
     return `${this.oauthTokenCookieName}_secret`;
   }
   /**
-   * 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
    */
   urlBuilder(url) {
     return new RedirectRequest(url, this.scopeParamName, this.scopesSeparator);
   }
   /**
-   * 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 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.
    *
-   * :::::
-   * NOTE
-   * :::::
-   *
-   * This child class must call this method inside the constructor.
+   * @example
+   * ```ts
+   * constructor(ctx: HttpContext, config: DriverConfig) {
+   *   super(ctx, config)
+   *   this.loadState()
+   * }
+   * ```
    */
   loadState() {
     this.oauthTokenCookieValue = this.ctx.request.encryptedCookie(this.oauthTokenCookieName);
@@ -53,7 +62,7 @@ var Oauth1Driver = class extends Oauth1Client {
     this.ctx.response.clearCookie(this.oauthSecretCookieName);
   }
   /**
-   * Persists the token (aka state) inside the cookie
+   * Stores the OAuth token in an encrypted cookie for later use
    */
   #persistToken(token) {
     this.ctx.response.encryptedCookie(this.oauthTokenCookieName, token, {
@@ -62,7 +71,7 @@ var Oauth1Driver = class extends Oauth1Client {
     });
   }
   /**
-   * Persists the secret inside the cookie
+   * Stores the OAuth token secret in an encrypted cookie for later use
    */
   #persistSecret(secret) {
     this.ctx.response.encryptedCookie(this.oauthSecretCookieName, secret, {
@@ -71,19 +80,37 @@ var Oauth1Driver = class extends Oauth1Client {
     });
   }
   /**
-   * 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() {
     throw new Exception("OAuth1 does not support stateless authorization");
   }
   /**
-   * 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()
+   * ```
    */
   async redirectUrl(callback) {
     return this.getRedirectUrl(callback);
   }
   /**
-   * 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()
+   * ```
    */
   async redirect(callback) {
     const { token, secret } = await this.getRequestToken();
@@ -98,19 +125,21 @@ var Oauth1Driver = class extends Oauth1Client {
     this.ctx.response.redirect(url);
   }
   /**
-   * Find if there is a state mismatch
+   * Check if the OAuth token from the callback matches the token
+   * stored in the cookie.
    */
   stateMisMatch() {
     return this.oauthTokenCookieValue !== this.ctx.request.input(this.oauthTokenParamName);
   }
   /**
-   * Find if there is an error post redirect
+   * Check if an error was returned by the OAuth provider.
    */
   hasError() {
     return !!this.getError();
   }
   /**
-   * 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() {
     const error = this.ctx.request.input(this.errorParamName);
@@ -123,19 +152,28 @@ var Oauth1Driver = class extends Oauth1Client {
     return null;
   }
   /**
-   * Returns the "oauth_verifier" token
+   * Get the OAuth verifier from the callback request.
    */
   getCode() {
     return this.ctx.request.input(this.oauthTokenVerifierName, null);
   }
   /**
-   * Find it the code exists
+   * Check if the OAuth verifier is present in the callback request.
    */
   hasCode() {
     return !!this.getCode();
   }
   /**
-   * 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()
+   * ```
    */
   async accessToken(callback) {
     if (this.hasError()) {
@@ -155,7 +193,7 @@ var Oauth1Driver = class extends Oauth1Client {
     );
   }
   /**
-   * Not applicable with Oauth1
+   * Not applicable with OAuth1. Use `userFromTokenAndSecret` instead.
    */
   async userFromToken() {
     throw new Exception(
@@ -167,4 +205,3 @@ var Oauth1Driver = class extends Oauth1Client {
 export {
   Oauth1Driver
 };
-//# sourceMappingURL=chunk-VHORNQLN.js.map

package/build/{chunk-PZ5AY32C.js → chunk-MLKGABMK.js}

@@ -7,4 +7,3 @@ var __export = (target, all) => {
 export {
   __export
 };
-//# sourceMappingURL=chunk-PZ5AY32C.js.map

package/build/{chunk-NZT2DLWM.js → chunk-SZ4YJCVU.js}

@@ -1,6 +1,10 @@
 // src/ally_manager.ts
-import { RuntimeException } from "@poppinss/utils";
+import { RuntimeException } from "@adonisjs/core/exceptions";
 var AllyManager = class {
+  /**
+   * @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;
@@ -8,7 +12,16 @@ var AllyManager = class {
   #ctx;
   #driversCache = /* @__PURE__ */ new Map();
   /**
-   * 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(provider) {
     if (this.#driversCache.has(provider)) {
@@ -31,4 +44,3 @@ var AllyManager = class {
 export {
   AllyManager
 };
-//# sourceMappingURL=chunk-NZT2DLWM.js.map

package/build/chunk-WM3V3APX.js

@@ -0,0 +1,210 @@
+import {
+  E_OAUTH_MISSING_CODE,
+  E_OAUTH_STATE_MISMATCH,
+  RedirectRequest
+} from "./chunk-KSJ4CFTC.js";
+
+// src/abstract_drivers/oauth2.ts
+import { Exception } from "@adonisjs/core/exceptions";
+import { Oauth2Client } from "@poppinss/oauth-client/oauth2";
+var Oauth2Driver = class extends Oauth2Client {
+  /**
+   * @param ctx - The current HTTP context
+   * @param config - OAuth2 driver configuration
+   */
+  constructor(ctx, config) {
+    super(config);
+    this.ctx = ctx;
+    this.config = config;
+  }
+  /**
+   * Whether the authorization process is stateless. When true,
+   * state verification via cookies is disabled.
+   */
+  isStateless = false;
+  /**
+   * OAuth protocol version identifier
+   */
+  version = "oauth2";
+  /**
+   * Cached state value read from the cookie
+   */
+  stateCookieValue;
+  /**
+   * Creates a URL builder instance for constructing authorization URLs
+   * with scope support.
+   *
+   * @param url - The base authorization URL
+   */
+  urlBuilder(url) {
+    return new RedirectRequest(url, this.scopeParamName, this.scopesSeparator);
+  }
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * constructor(ctx: HttpContext, config: DriverConfig) {
+   *   super(ctx, config)
+   *   this.loadState()
+   * }
+   * ```
+   */
+  loadState() {
+    if (this.isStateless) {
+      return;
+    }
+    this.stateCookieValue = this.ctx.request.encryptedCookie(this.stateCookieName);
+    this.ctx.response.clearCookie(this.stateCookieName);
+  }
+  /**
+   * Stores the CSRF state in an encrypted cookie for later verification
+   */
+  #persistState() {
+    if (this.isStateless) {
+      return;
+    }
+    const state = this.getState();
+    this.ctx.response.encryptedCookie(this.stateCookieName, state, {
+      sameSite: false,
+      httpOnly: true
+    });
+    return state;
+  }
+  /**
+   * 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.isStateless = true;
+    return this;
+  }
+  /**
+   * 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'])
+   * })
+   * ```
+   */
+  async redirectUrl(callback) {
+    const url = this.getRedirectUrl(callback);
+    return url;
+  }
+  /**
+   * 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')
+   * })
+   * ```
+   */
+  async redirect(callback) {
+    const url = await this.redirectUrl((request) => {
+      const state = this.#persistState();
+      state && request.param(this.stateParamName, state);
+      if (typeof callback === "function") {
+        callback(request);
+      }
+    });
+    this.ctx.response.redirect(url);
+  }
+  /**
+   * Check if the state parameter from the callback matches the state
+   * stored in the cookie. Returns false in stateless mode.
+   */
+  stateMisMatch() {
+    if (this.isStateless) {
+      return false;
+    }
+    return this.stateCookieValue !== this.ctx.request.input(this.stateParamName);
+  }
+  /**
+   * Check if an error was returned by the OAuth provider.
+   */
+  hasError() {
+    return !!this.getError();
+  }
+  /**
+   * 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() {
+    const error = this.ctx.request.input(this.errorParamName);
+    if (error) {
+      return error;
+    }
+    if (!this.hasCode()) {
+      return "unknown_error";
+    }
+    return null;
+  }
+  /**
+   * Get the authorization code from the callback request.
+   */
+  getCode() {
+    return this.ctx.request.input(this.codeParamName, null);
+  }
+  /**
+   * Check if the authorization code is present in the callback request.
+   */
+  hasCode() {
+    return !!this.getCode();
+  }
+  /**
+   * 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()
+   * ```
+   */
+  async accessToken(callback) {
+    if (this.hasError()) {
+      throw new E_OAUTH_MISSING_CODE([this.codeParamName]);
+    }
+    if (this.stateMisMatch()) {
+      throw new E_OAUTH_STATE_MISMATCH();
+    }
+    return this.getAccessToken((request) => {
+      request.field(this.codeParamName, this.getCode());
+      if (typeof callback === "function") {
+        callback(request);
+      }
+    });
+  }
+  /**
+   * Not applicable with OAuth2. Use `userFromToken` instead.
+   */
+  async userFromTokenAndSecret() {
+    throw new Exception(
+      '"userFromTokenAndSecret" is not applicable with Oauth2. Use "userFromToken" instead'
+    );
+  }
+};
+
+export {
+  Oauth2Driver
+};

package/build/index.d.ts

@@ -1,9 +1,9 @@
 export { HttpClient as ApiRequest } from '@poppinss/oauth-client';
-export * as errors from './src/errors.js';
-export { configure } from './configure.js';
-export { stubsRoot } from './stubs/main.js';
-export { AllyManager } from './src/ally_manager.js';
-export { defineConfig, services } from './src/define_config.js';
-export { RedirectRequest } from './src/redirect_request.js';
-export { Oauth1Driver } from './src/abstract_drivers/oauth1.js';
-export { Oauth2Driver } from './src/abstract_drivers/oauth2.js';
+export * as errors from './src/errors.ts';
+export { configure } from './configure.ts';
+export { stubsRoot } from './stubs/main.ts';
+export { AllyManager } from './src/ally_manager.ts';
+export { defineConfig, services } from './src/define_config.ts';
+export { RedirectRequest } from './src/redirect_request.ts';
+export { Oauth1Driver } from './src/abstract_drivers/oauth1.ts';
+export { Oauth2Driver } from './src/abstract_drivers/oauth2.ts';

package/build/index.js

@@ -1,24 +1,23 @@
 import {
   Oauth1Driver
-} from "./chunk-VHORNQLN.js";
+} from "./chunk-KWRXS6EG.js";
 import {
   AllyManager
-} from "./chunk-NZT2DLWM.js";
+} from "./chunk-SZ4YJCVU.js";
 import {
   Oauth2Driver
-} from "./chunk-GWAQFMNS.js";
+} from "./chunk-WM3V3APX.js";
 import {
   RedirectRequest,
   errors_exports
-} from "./chunk-N72DEJC2.js";
-import "./chunk-PZ5AY32C.js";
+} from "./chunk-KSJ4CFTC.js";
+import "./chunk-MLKGABMK.js";
 
 // index.ts
 import { HttpClient } from "@poppinss/oauth-client";
 
 // stubs/main.ts
-import { getDirname } from "@poppinss/utils";
-var stubsRoot = getDirname(import.meta.url);
+var stubsRoot = import.meta.dirname;
 
 // configure.ts
 var AVAILABLE_PROVIDERS = [
@@ -156,4 +155,3 @@ export {
   services,
   stubsRoot
 };
-//# sourceMappingURL=index.js.map

package/build/providers/ally_provider.d.ts

@@ -1,5 +1,5 @@
 import type { ApplicationService } from '@adonisjs/core/types';
-import type { AllyService } from '../src/types.js';
+import type { AllyService } from '../src/types.ts';
 declare module '@adonisjs/core/http' {
     interface HttpContext {
         ally: AllyService;

package/build/providers/ally_provider.js

@@ -1,12 +1,12 @@
 import {
   AllyManager
-} from "../chunk-NZT2DLWM.js";
-import "../chunk-PZ5AY32C.js";
+} from "../chunk-SZ4YJCVU.js";
+import "../chunk-MLKGABMK.js";
 
 // providers/ally_provider.ts
 import { configProvider } from "@adonisjs/core";
 import { HttpContext } from "@adonisjs/core/http";
-import { RuntimeException } from "@poppinss/utils";
+import { RuntimeException } from "@adonisjs/core/exceptions";
 var AllyProvider = class {
   constructor(app) {
     this.app = app;
@@ -31,4 +31,3 @@ var AllyProvider = class {
 export {
   AllyProvider as default
 };
-//# sourceMappingURL=ally_provider.js.map