Authorization Flows

/**
 * Build authorization URL for user redirect
 * @param config - Configuration instance
 * @param parameters - Authorization request parameters
 * @returns URL for user-agent redirect
 */
function buildAuthorizationUrl(
  config: Configuration,
  parameters: URLSearchParams | Record<string, string>
): URL;

import * as client from "openid-client";

// Basic authorization URL with PKCE
const codeVerifier = client.randomPKCECodeVerifier();
const codeChallenge = await client.calculatePKCECodeChallenge(codeVerifier);

const authUrl = client.buildAuthorizationUrl(config, {
  redirect_uri: "https://example.com/callback",
  scope: "openid email profile",
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
  state: client.randomState(),
  nonce: client.randomNonce()
});

// Authorization URL with additional parameters
const authUrl = client.buildAuthorizationUrl(config, {
  redirect_uri: "https://example.com/callback",
  scope: "openid email profile",
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
  state: "random-state-value",
  nonce: "random-nonce-value",
  prompt: "consent",
  max_age: "3600",
  login_hint: "user@example.com",
  ui_locales: "en es"
});

/**
 * Execute Authorization Code Grant flow
 * @param config - Configuration instance
 * @param currentUrl - Current URL or Request with authorization response
 * @param checks - Validation checks (PKCE, state, nonce)
 * @param tokenEndpointParameters - Additional token endpoint parameters
 * @param options - Grant options (DPoP, etc.)
 * @returns Promise resolving to token response with helpers
 */
function authorizationCodeGrant(
  config: Configuration,
  currentUrl: URL | Request,
  checks?: AuthorizationCodeGrantChecks,
  tokenEndpointParameters?: URLSearchParams | Record<string, string>,
  options?: AuthorizationCodeGrantOptions
): Promise<TokenEndpointResponse & TokenEndpointResponseHelpers>;

import * as client from "openid-client";

// Basic authorization code grant with PKCE
const tokens = await client.authorizationCodeGrant(
  config,
  new URL(callbackUrl), // URL with ?code=... parameters
  {
    pkceCodeVerifier: codeVerifier,
    expectedState: expectedState,
    expectedNonce: expectedNonce
  }
);

// Using Request object (server-side)
const tokens = await client.authorizationCodeGrant(
  config,
  request, // Express/HTTP request object
  {
    pkceCodeVerifier: codeVerifier,
    expectedState: expectedState
  }
);

// With additional token endpoint parameters
const tokens = await client.authorizationCodeGrant(
  config,
  currentUrl,
  { pkceCodeVerifier: codeVerifier },
  { 
    resource: "https://api.example.com", // resource indicator
    audience: "https://api.example.com"
  }
);

// Access token information
console.log("Access Token:", tokens.access_token);
console.log("Token Type:", tokens.token_type);
console.log("Expires In:", tokens.expiresIn()); // helper method
console.log("ID Token Claims:", tokens.claims()); // helper method

/**
 * Build authorization URL with JWT Authorization Request
 * @param config - Configuration instance  
 * @param parameters - Authorization request parameters (will be signed)
 * @param signingKey - Private key for signing the request JWT
 * @param options - JWT modification options
 * @returns Promise resolving to authorization URL
 */
function buildAuthorizationUrlWithJAR(
  config: Configuration,
  parameters: URLSearchParams | Record<string, string>,
  signingKey: CryptoKey | PrivateKey,
  options?: ModifyAssertionOptions
): Promise<URL>;

import * as client from "openid-client";

// JAR with private key
const privateKey = await crypto.subtle.generateKey(
  { name: "ECDSA", namedCurve: "P-256" },
  true,
  ["sign"]
);

const authUrl = await client.buildAuthorizationUrlWithJAR(
  config,
  {
    redirect_uri: "https://example.com/callback",
    scope: "openid email profile",
    code_challenge: codeChallenge,
    code_challenge_method: "S256",
    state: "secure-state",
    nonce: "secure-nonce"
  },
  privateKey.privateKey
);

// JAR with assertion modification
const authUrl = await client.buildAuthorizationUrlWithJAR(
  config,
  parameters,
  privateKey.privateKey,
  {
    [client.modifyAssertion]: (header, payload) => {
      // Modify JWT before signing
      header.custom = "value";
      payload.custom_claim = "custom_value";
    }
  }
);

/**
 * Build authorization URL with Pushed Authorization Request
 * @param config - Configuration instance
 * @param parameters - Authorization request parameters (will be pushed)
 * @param options - PAR options (DPoP, etc.)
 * @returns Promise resolving to authorization URL with request_uri
 */
function buildAuthorizationUrlWithPAR(
  config: Configuration,
  parameters: URLSearchParams | Record<string, string>,
  options?: DPoPOptions
): Promise<URL>;

import * as client from "openid-client";

// Basic PAR usage
const authUrl = await client.buildAuthorizationUrlWithPAR(config, {
  redirect_uri: "https://example.com/callback",
  scope: "openid email profile",
  code_challenge: codeChallenge,
  code_challenge_method: "S256",
  state: "secure-state",
  nonce: "secure-nonce"
});

// JAR + PAR combination for maximum security
const { searchParams } = await client.buildAuthorizationUrlWithJAR(
  config,
  {
    redirect_uri: "https://example.com/callback",
    scope: "openid email profile",
    code_challenge: codeChallenge,
    code_challenge_method: "S256"
  },
  privateKey
);

const authUrl = await client.buildAuthorizationUrlWithPAR(config, searchParams);

/**
 * Validate implicit authentication response
 * @param config - Configuration instance
 * @param currentUrl - Current URL or Request with implicit response
 * @param expectedNonce - Expected nonce value
 * @param checks - Additional validation checks
 * @returns Promise resolving to ID Token claims
 */
function implicitAuthentication(
  config: Configuration,
  currentUrl: URL | Request,
  expectedNonce: string,
  checks?: ImplicitAuthenticationResponseChecks
): Promise<IDToken>;

import * as client from "openid-client";

// Validate implicit flow response
const idTokenClaims = await client.implicitAuthentication(
  config,
  new URL(location.href), // browser environment
  expectedNonce,
  {
    expectedState: expectedState,
    maxAge: 3600
  }
);

console.log("User ID:", idTokenClaims.sub);
console.log("Email:", idTokenClaims.email);

/**
 * Build end session URL for logout
 * @param config - Configuration instance
 * @param parameters - Logout parameters
 * @returns URL for logout redirect
 */
function buildEndSessionUrl(
  config: Configuration,
  parameters?: URLSearchParams | Record<string, string>
): URL;

import * as client from "openid-client";

// Basic logout URL
const logoutUrl = client.buildEndSessionUrl(config, {
  id_token_hint: idToken,
  post_logout_redirect_uri: "https://example.com/logout"
});

// Logout without redirect
const logoutUrl = client.buildEndSessionUrl(config, {
  id_token_hint: idToken
});

interface AuthorizationCodeGrantChecks {
  /** Expected nonce value for ID Token validation */
  expectedNonce?: string;
  /** Expected state value for CSRF protection */
  expectedState?: string | typeof skipStateCheck;
  /** Require ID Token in response */
  idTokenExpected?: boolean;
  /** Maximum age for auth_time claim validation */
  maxAge?: number;
  /** PKCE code verifier for code challenge validation */
  pkceCodeVerifier?: string;
}

interface ImplicitAuthenticationResponseChecks extends Pick<AuthorizationCodeGrantChecks, 'expectedState' | 'maxAge'> {
}

interface AuthorizationCodeGrantOptions extends DPoPOptions {
}

/**
 * Generate random PKCE code verifier
 * @returns Random code verifier string
 */
function randomPKCECodeVerifier(): string;

/**
 * Calculate PKCE code challenge using S256 method
 * @param codeVerifier - Code verifier to hash
 * @returns Promise resolving to base64url-encoded SHA256 hash
 */
function calculatePKCECodeChallenge(codeVerifier: string): Promise<string>;

/**
 * Generate random state value for CSRF protection
 * @returns Random state string
 */
function randomState(): string;

/**
 * Generate random nonce value for replay protection  
 * @returns Random nonce string
 */
function randomNonce(): string;