{"id":16638,"library":"leo-auth","title":"Leo Auth SDK","description":"The `leo-auth` SDK provides authentication utilities primarily for the LeoPlatform ecosystem, facilitating secure interactions with platform services. Currently stable at version 4.0.5, with ongoing development and recent pre-releases like `4.0.7-awsv3` indicating a continuous, albeit not rapid, release cadence. Key differentiators include its tight integration with AWS services, notably upgrading to AWS SDK v3 in the 4.x series, which offers modernized client configurations and improved performance. The SDK also incorporates security enhancements such as moving off TLSv1, and features like context overrides and `cognitoIdentityId` proxy for AWS key callers, indicating a focus on robust, cloud-native authentication flows. It is built to support Node.js environments and interacts with common authentication patterns for cloud applications.","status":"active","version":"4.0.5","language":"javascript","source_language":"en","source_url":"https://github.com/LeoPlatform/auth-sdk","tags":["javascript"],"install":[{"cmd":"npm install leo-auth","lang":"bash","label":"npm"},{"cmd":"yarn add leo-auth","lang":"bash","label":"yarn"},{"cmd":"pnpm add leo-auth","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const Auth = require('leo-auth');","symbol":"Auth","correct":"import { Auth } from 'leo-auth';"},{"note":"Configuration utilities are typically named exports. Avoid importing from internal or non-public paths.","wrong":"import configureAuth from 'leo-auth/configure';","symbol":"configureAuth","correct":"import { configureAuth } from 'leo-auth';"},{"note":"Specific error types are useful for robust error handling and are usually named exports. The library ships with TypeScript types.","symbol":"AuthError","correct":"import { AuthError } from 'leo-auth';"}],"quickstart":{"code":"import { Auth } from 'leo-auth';\n\ninterface AuthConfig {\n  clientId: string;\n  identityPoolId: string;\n  userPoolId: string;\n  region: string;\n}\n\n// Load configuration from environment variables for security and flexibility\nconst authConfig: AuthConfig = {\n  clientId: process.env.LEO_AUTH_CLIENT_ID ?? '',\n  identityPoolId: process.env.LEO_AUTH_IDENTITY_POOL_ID ?? '',\n  userPoolId: process.env.LEO_AUTH_USER_POOL_ID ?? '',\n  region: process.env.AWS_REGION ?? 'us-east-1'\n};\n\nif (!authConfig.clientId || !authConfig.identityPoolId || !authConfig.userPoolId) {\n  console.error('Missing LEO_AUTH_CLIENT_ID, LEO_AUTH_IDENTITY_POOL_ID, or LEO_AUTH_USER_POOL_ID environment variables.');\n  process.exit(1);\n}\n\nasync function initializeAndAuthenticate() {\n  try {\n    // Initialize the Auth SDK with your platform-specific configuration\n    const auth = new Auth(authConfig);\n    console.log('Leo Auth SDK initialized successfully.');\n\n    // Example: Attempt a simple guest/unauthenticated authentication\n    // Replace with actual login flow (e.g., cognito username/password, SAML) for real use cases\n    const credentials = await auth.getGuestCredentials();\n    console.log('Successfully obtained guest credentials.');\n    console.log('Access Key ID:', credentials.accessKeyId);\n    console.log('Secret Access Key:', credentials.secretAccessKey ? '******' : 'N/A');\n    console.log('Session Token:', credentials.sessionToken ? '******' : 'N/A');\n\n    // In a real application, you would now use these credentials\n    // to make signed requests to other LeoPlatform or AWS services.\n\n  } catch (error) {\n    console.error('Authentication failed:', error);\n    if (error instanceof Error) {\n      console.error('Error message:', error.message);\n    }\n    process.exit(1);\n  }\n}\n\ninitializeAndAuthenticate();","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=4.0.7-awsv3"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"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.","cause":"Attempting to import `leo-auth` using CommonJS `require()` syntax in an ES Module context.","error":"ReferenceError: require is not defined"},{"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.","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.","error":"TypeError: (0, _clientCognitoIdentity.CognitoIdentityClient) is not a constructor"}],"ecosystem":"npm"}