Leo Auth SDK

Common errors

• ReferenceError: require is not defined

  cause Attempting to import `leo-auth` using CommonJS `require()` syntax in an ES Module context.
  fix Update your import statements to use ES Module syntax: `import { Auth } from 'leo-auth';`. Ensure your `package.json` has `"type": "module"` or files use `.mjs` extension for ESM, or use a transpiler like Babel/TypeScript.

• TypeError: (0, _clientCognitoIdentity.CognitoIdentityClient) is not a constructor

  cause This error often indicates an incompatibility or incorrect usage after the AWS SDK v3 upgrade. It implies that a component expected a specific client constructor (likely from AWS SDK v2), but received a v3 equivalent, or there's a module resolution issue.
  fix Verify all AWS SDK related imports and client instantiations are updated to the v3 modular syntax (e.g., `import { CognitoIdentityClient } from '@aws-sdk/client-cognito-identity';`). Ensure `leo-auth` is the correct version for your AWS SDK setup and re-check its configuration.

Warnings

• breaking Version 4.x of `leo-auth` introduces an internal upgrade to AWS SDK v3. If your application directly interacts with AWS SDK components or has custom configurations that assume AWS SDK v2 behavior, you will need to review and update your code. AWS SDK v3 has a modular architecture and different client constructors compared to v2.
  Fix: Consult the AWS SDK for JavaScript v3 migration guide for updating AWS client initializations and API calls. Review `leo-auth` documentation for any new configuration requirements related to AWS SDK v3.
• breaking Support for `multiValueQueryStringParams` was explicitly removed in `v4.0.7-awsv3` due to a bug. If your application relies on this functionality for handling multiple query string parameters with the same name, this will no longer be supported and may lead to unexpected behavior or errors.
  Fix: Refactor your application to use single-valued query string parameters or custom logic to parse multi-valued parameters before they are processed by the `leo-auth` SDK. Check if a future patch re-introduces this feature with a fix.
• gotcha The SDK includes an 'upgrade to get off TLSv1'. While this improves security, older Node.js environments or highly restricted network configurations that only support TLSv1 might experience connectivity issues. Ensure your runtime environment supports TLSv1.2 or higher.
  Fix: Upgrade your Node.js runtime to a version that supports TLSv1.2 or higher (Node.js 12.x and above generally support this by default). Verify network proxies or firewalls are not enforcing older TLS versions.

Install

• npm install leo-auth npm
• yarn add leo-auth yarn
• pnpm add leo-auth pnpm

Imports

• Auth
  wrong:

  const Auth = require('leo-auth');

  correct:

  import { Auth } from 'leo-auth';

  The `leo-auth` SDK is designed for modern JavaScript environments, preferring ES Modules. CommonJS `require` syntax is not directly supported for top-level imports in modern Node.js module setups.
• configureAuth
  wrong:

  import configureAuth from 'leo-auth/configure';

  correct:

  import { configureAuth } from 'leo-auth';

  Configuration utilities are typically named exports. Avoid importing from internal or non-public paths.
• AuthError

  import { AuthError } from 'leo-auth';

  Specific error types are useful for robust error handling and are usually named exports. The library ships with TypeScript types.

Quickstart

This quickstart demonstrates how to initialize the `leo-auth` SDK and obtain guest credentials using environment variables for configuration. It outlines a basic setup suitable for Node.js applications interacting with the LeoPlatform's authentication mechanisms.

import { Auth } from 'leo-auth';

interface AuthConfig {
  clientId: string;
  identityPoolId: string;
  userPoolId: string;
  region: string;
}

// Load configuration from environment variables for security and flexibility
const authConfig: AuthConfig = {
  clientId: process.env.LEO_AUTH_CLIENT_ID ?? '',
  identityPoolId: process.env.LEO_AUTH_IDENTITY_POOL_ID ?? '',
  userPoolId: process.env.LEO_AUTH_USER_POOL_ID ?? '',
  region: process.env.AWS_REGION ?? 'us-east-1'
};

if (!authConfig.clientId || !authConfig.identityPoolId || !authConfig.userPoolId) {
  console.error('Missing LEO_AUTH_CLIENT_ID, LEO_AUTH_IDENTITY_POOL_ID, or LEO_AUTH_USER_POOL_ID environment variables.');
  process.exit(1);
}

async function initializeAndAuthenticate() {
  try {
    // Initialize the Auth SDK with your platform-specific configuration
    const auth = new Auth(authConfig);
    console.log('Leo Auth SDK initialized successfully.');

    // Example: Attempt a simple guest/unauthenticated authentication
    // Replace with actual login flow (e.g., cognito username/password, SAML) for real use cases
    const credentials = await auth.getGuestCredentials();
    console.log('Successfully obtained guest credentials.');
    console.log('Access Key ID:', credentials.accessKeyId);
    console.log('Secret Access Key:', credentials.secretAccessKey ? '******' : 'N/A');
    console.log('Session Token:', credentials.sessionToken ? '******' : 'N/A');

    // In a real application, you would now use these credentials
    // to make signed requests to other LeoPlatform or AWS services.

  } catch (error) {
    console.error('Authentication failed:', error);
    if (error instanceof Error) {
      console.error('Error message:', error.message);
    }
    process.exit(1);
  }
}

initializeAndAuthenticate();