chub-dev 0.1.0 → 0.1.2-beta.0

package/dist/auth0/docs/identity/javascript/DOC.md

@@ -0,0 +1,968 @@
+---
+name: identity
+description: "Auth0 JavaScript/Node.js SDK for OAuth, OIDC, and identity management in server-side applications"
+metadata:
+  languages: "javascript"
+  versions: "5.0.0"
+  updated-on: "2026-03-01"
+  source: maintainer
+  tags: "auth0,identity,oauth,oidc,authentication"
+---
+
+# Auth0 JavaScript/Node.js SDK Coding Guidelines
+
+You are an Auth0 API expert. Help me with writing code using the Auth0 SDK for JavaScript/Node.js applications.
+
+You can find the official SDK documentation here:
+https://auth0.github.io/node-auth0/
+
+## Golden Rule: Use the Correct Auth0 SDK
+
+Always use the official Auth0 Node.js SDK for server-side authentication and user management operations. This is the standard library for all Auth0 Management API and Authentication API interactions.
+
+- **Library Name:** Auth0 Node.js SDK
+- **NPM Package:** `auth0`
+- **Current Version:** 5.0.0
+- **Minimum Node.js Version:** 20.19.0+ or 22.12.0+ or 24.0.0+
+
+**Installation:**
+
+```bash
+npm install auth0
+```
+
+**Correct Usage:**
+
+```javascript
+import { ManagementClient, AuthenticationClient } from 'auth0';
+```
+
+**Incorrect:**
+- Using `auth0-js` for server-side operations (this is for browser-based apps)
+- Using unofficial or deprecated Auth0 packages
+
+## Environment Variables
+
+Set up your environment variables for Auth0:
+
+```
+AUTH0_DOMAIN=your-tenant.us.auth0.com
+AUTH0_CLIENT_ID=your_client_id
+AUTH0_CLIENT_SECRET=your_client_secret
+AUTH0_MANAGEMENT_API_TOKEN=your_management_api_token
+```
+
+## Installation and Setup
+
+Install the Auth0 SDK:
+
+```bash
+npm install auth0
+```
+
+For TypeScript projects, types are included in the package.
+
+## Initialization
+
+### ManagementClient Initialization
+
+The ManagementClient is used for administrative operations like user management, role assignment, and configuration.
+
+**Basic initialization with API token:**
+
+```javascript
+import { ManagementClient } from 'auth0';
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  token: process.env.AUTH0_MANAGEMENT_API_TOKEN,
+});
+```
+
+**Initialization with client credentials:**
+
+```javascript
+import { ManagementClient } from 'auth0';
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+```
+
+**Advanced configuration:**
+
+```javascript
+import { ManagementClient } from 'auth0';
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+  timeout: 60000, // 60 seconds
+  retry: {
+    enabled: true,
+    maxRetries: 2,
+  },
+});
+```
+
+### AuthenticationClient Initialization
+
+The AuthenticationClient handles user authentication operations like login, password reset, and token management.
+
+**Basic initialization:**
+
+```javascript
+import { AuthenticationClient } from 'auth0';
+
+const auth0 = new AuthenticationClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+});
+```
+
+**With client secret (for confidential clients):**
+
+```javascript
+import { AuthenticationClient } from 'auth0';
+
+const auth0 = new AuthenticationClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+```
+
+### UserInfoClient Initialization
+
+For retrieving user profile information using access tokens:
+
+```javascript
+import { UserInfoClient } from 'auth0';
+
+const userInfo = new UserInfoClient({
+  domain: process.env.AUTH0_DOMAIN,
+});
+```
+
+## User Management
+
+### Creating Users
+
+```javascript
+import { ManagementClient } from 'auth0';
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+
+async function createUser() {
+  const newUser = await management.users.create({
+    email: 'user@example.com',
+    password: 'SecurePassword123!',
+    connection: 'Username-Password-Authentication',
+    email_verified: false,
+    user_metadata: {
+      plan: 'premium',
+      preferences: { theme: 'dark' },
+    },
+    app_metadata: {
+      role: 'user',
+    },
+  });
+
+  console.log('User created:', newUser.user_id);
+  return newUser;
+}
+```
+
+### Getting User by ID
+
+```javascript
+async function getUser(userId) {
+  const user = await management.users.get({ id: userId });
+  console.log('User:', user);
+  return user;
+}
+```
+
+### Getting User by Email
+
+```javascript
+async function getUserByEmail(email) {
+  const users = await management.usersByEmail.get({ email });
+
+  if (users.length > 0) {
+    console.log('User found:', users[0]);
+    return users[0];
+  }
+
+  return null;
+}
+```
+
+### Updating User
+
+```javascript
+async function updateUser(userId, updates) {
+  const updatedUser = await management.users.update(
+    { id: userId },
+    {
+      email: 'newemail@example.com',
+      user_metadata: {
+        plan: 'enterprise',
+      },
+    }
+  );
+
+  return updatedUser;
+}
+```
+
+### Deleting User
+
+```javascript
+async function deleteUser(userId) {
+  await management.users.delete({ id: userId });
+  console.log('User deleted');
+}
+```
+
+### Listing Users
+
+```javascript
+async function listUsers() {
+  const users = await management.users.getAll({
+    per_page: 50,
+    page: 0,
+  });
+
+  return users;
+}
+```
+
+### Searching Users
+
+```javascript
+async function searchUsers(query) {
+  const users = await management.users.getAll({
+    q: `email:"*@example.com"`,
+    search_engine: 'v3',
+  });
+
+  return users;
+}
+```
+
+## Authentication Operations
+
+### Password Grant (Direct Login)
+
+```javascript
+import { AuthenticationClient } from 'auth0';
+
+const auth0 = new AuthenticationClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+
+async function login(username, password) {
+  const response = await auth0.oauth.passwordGrant({
+    username,
+    password,
+    audience: 'https://api.example.com',
+    scope: 'openid profile email',
+  });
+
+  console.log('Access Token:', response.access_token);
+  console.log('ID Token:', response.id_token);
+  return response;
+}
+```
+
+### Client Credentials Grant
+
+```javascript
+async function getClientCredentialsToken() {
+  const response = await auth0.oauth.clientCredentialsGrant({
+    audience: 'https://api.example.com',
+  });
+
+  console.log('Access Token:', response.access_token);
+  return response;
+}
+```
+
+### Refresh Token
+
+```javascript
+async function refreshToken(refreshToken) {
+  const response = await auth0.oauth.refreshTokenGrant({
+    refresh_token: refreshToken,
+  });
+
+  console.log('New Access Token:', response.access_token);
+  return response;
+}
+```
+
+### Password Reset
+
+```javascript
+async function requestPasswordReset(email) {
+  await auth0.database.changePassword({
+    email,
+    connection: 'Username-Password-Authentication',
+  });
+
+  console.log('Password reset email sent');
+}
+```
+
+### User Signup
+
+```javascript
+async function signup(email, password) {
+  const user = await auth0.database.signUp({
+    email,
+    password,
+    connection: 'Username-Password-Authentication',
+  });
+
+  return user;
+}
+```
+
+## Token Operations
+
+### Getting User Info from Access Token
+
+```javascript
+import { UserInfoClient } from 'auth0';
+
+const userInfo = new UserInfoClient({
+  domain: process.env.AUTH0_DOMAIN,
+});
+
+async function getUserProfile(accessToken) {
+  const profile = await userInfo.getUserInfo(accessToken);
+
+  console.log('User Profile:', profile);
+  return profile;
+}
+```
+
+### Revoking Refresh Token
+
+```javascript
+async function revokeToken(token) {
+  await auth0.oauth.revokeRefreshToken({
+    token,
+  });
+
+  console.log('Token revoked');
+}
+```
+
+## Role and Permission Management
+
+### Assigning Roles to User
+
+```javascript
+async function assignRolesToUser(userId, roleIds) {
+  await management.users.assignRoles(
+    { id: userId },
+    { roles: roleIds }
+  );
+
+  console.log('Roles assigned');
+}
+```
+
+### Getting User Roles
+
+```javascript
+async function getUserRoles(userId) {
+  const roles = await management.users.getRoles({ id: userId });
+
+  console.log('User Roles:', roles);
+  return roles;
+}
+```
+
+### Removing Roles from User
+
+```javascript
+async function removeRolesFromUser(userId, roleIds) {
+  await management.users.removeRoles(
+    { id: userId },
+    { roles: roleIds }
+  );
+
+  console.log('Roles removed');
+}
+```
+
+### Getting User Permissions
+
+```javascript
+async function getUserPermissions(userId) {
+  const permissions = await management.users.getPermissions({ id: userId });
+
+  console.log('User Permissions:', permissions);
+  return permissions;
+}
+```
+
+### Assigning Permissions to User
+
+```javascript
+async function assignPermissionsToUser(userId, permissions) {
+  await management.users.assignPermissions(
+    { id: userId },
+    {
+      permissions: [
+        { permission_name: 'read:messages', resource_server_identifier: 'https://api.example.com' },
+        { permission_name: 'write:messages', resource_server_identifier: 'https://api.example.com' },
+      ]
+    }
+  );
+
+  console.log('Permissions assigned');
+}
+```
+
+## Organization Management
+
+### Creating an Organization
+
+```javascript
+async function createOrganization(name, displayName) {
+  const org = await management.organizations.create({
+    name,
+    display_name: displayName,
+  });
+
+  return org;
+}
+```
+
+### Adding Members to Organization
+
+```javascript
+async function addMemberToOrganization(orgId, userId) {
+  await management.organizations.addMembers(
+    { id: orgId },
+    { members: [userId] }
+  );
+
+  console.log('Member added to organization');
+}
+```
+
+### Getting Organization Members
+
+```javascript
+async function getOrganizationMembers(orgId) {
+  const members = await management.organizations.getMembers({ id: orgId });
+
+  return members;
+}
+```
+
+### Assigning Roles to Organization Member
+
+```javascript
+async function assignOrgRoles(orgId, userId, roleIds) {
+  await management.organizations.addMemberRoles(
+    { id: orgId, user_id: userId },
+    { roles: roleIds }
+  );
+
+  console.log('Organization roles assigned');
+}
+```
+
+## Client Application Management
+
+### Getting All Clients
+
+```javascript
+async function getAllClients() {
+  const clients = await management.clients.getAll();
+
+  return clients;
+}
+```
+
+### Creating a Client
+
+```javascript
+async function createClient(name, type) {
+  const client = await management.clients.create({
+    name,
+    app_type: type, // 'native', 'spa', 'regular_web', 'non_interactive'
+    callbacks: ['http://localhost:3000/callback'],
+    allowed_logout_urls: ['http://localhost:3000'],
+  });
+
+  return client;
+}
+```
+
+### Updating a Client
+
+```javascript
+async function updateClient(clientId, updates) {
+  const client = await management.clients.update(
+    { client_id: clientId },
+    updates
+  );
+
+  return client;
+}
+```
+
+## Connection Management
+
+### Getting All Connections
+
+```javascript
+async function getAllConnections() {
+  const connections = await management.connections.getAll();
+
+  return connections;
+}
+```
+
+### Creating a Database Connection
+
+```javascript
+async function createDatabaseConnection(name) {
+  const connection = await management.connections.create({
+    name,
+    strategy: 'auth0',
+    enabled_clients: [process.env.AUTH0_CLIENT_ID],
+  });
+
+  return connection;
+}
+```
+
+### Getting Connection by ID
+
+```javascript
+async function getConnection(connectionId) {
+  const connection = await management.connections.get({ id: connectionId });
+
+  return connection;
+}
+```
+
+## Email Templates and Verification
+
+### Sending Email Verification
+
+```javascript
+async function sendVerificationEmail(userId) {
+  await management.jobs.verifyEmail({
+    user_id: userId,
+  });
+
+  console.log('Verification email sent');
+}
+```
+
+### Creating Email Verification Ticket
+
+```javascript
+async function createEmailVerificationTicket(userId) {
+  const ticket = await management.tickets.verifyEmail({
+    user_id: userId,
+    result_url: 'https://example.com/verified',
+  });
+
+  console.log('Verification URL:', ticket.ticket);
+  return ticket;
+}
+```
+
+### Creating Password Change Ticket
+
+```javascript
+async function createPasswordChangeTicket(userId) {
+  const ticket = await management.tickets.changePassword({
+    user_id: userId,
+    result_url: 'https://example.com/password-changed',
+  });
+
+  console.log('Password change URL:', ticket.ticket);
+  return ticket;
+}
+```
+
+## Pagination
+
+### Manual Pagination
+
+```javascript
+async function getAllUsersPaginated() {
+  let page = 0;
+  const perPage = 50;
+  let allUsers = [];
+  let hasMore = true;
+
+  while (hasMore) {
+    const users = await management.users.getAll({
+      page,
+      per_page: perPage,
+    });
+
+    allUsers = allUsers.concat(users);
+    hasMore = users.length === perPage;
+    page++;
+  }
+
+  return allUsers;
+}
+```
+
+### Using Pagination Iterator
+
+```javascript
+async function iterateAllUsers() {
+  const users = [];
+
+  for await (const user of management.users.getAll()) {
+    users.push(user);
+  }
+
+  return users;
+}
+```
+
+## Error Handling
+
+The SDK provides comprehensive error handling with ManagementError and AuthenticationError types.
+
+```javascript
+import { ManagementClient, ManagementError } from 'auth0';
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+
+async function handleErrors() {
+  try {
+    const user = await management.users.get({ id: 'invalid-id' });
+  } catch (err) {
+    if (err instanceof ManagementError) {
+      console.log('Status Code:', err.statusCode); // 404
+      console.log('Error Message:', err.message);
+      console.log('Error Body:', err.body);
+      console.log('Raw Response:', err.rawResponse);
+    } else {
+      throw err;
+    }
+  }
+}
+```
+
+### Common Error Status Codes
+
+| Status Code | Error Type | Description |
+|-------------|------------|-------------|
+| 400 | Bad Request | Invalid request parameters |
+| 401 | Unauthorized | Invalid or missing credentials |
+| 403 | Forbidden | Insufficient permissions |
+| 404 | Not Found | Resource not found |
+| 409 | Conflict | Resource already exists |
+| 429 | Too Many Requests | Rate limit exceeded |
+| 500 | Internal Server Error | Server error |
+
+## Advanced Configuration
+
+### Custom Timeout
+
+```javascript
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  token: process.env.AUTH0_MANAGEMENT_API_TOKEN,
+  timeout: 30000, // 30 seconds
+});
+```
+
+### Retry Configuration
+
+```javascript
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  token: process.env.AUTH0_MANAGEMENT_API_TOKEN,
+  retry: {
+    enabled: true,
+    maxRetries: 3,
+  },
+});
+```
+
+### Custom Headers
+
+```javascript
+async function makeRequestWithCustomHeaders() {
+  const users = await management.users.getAll({}, {
+    headers: {
+      'X-Custom-Header': 'custom-value',
+    },
+  });
+
+  return users;
+}
+```
+
+### Abort Signal (Request Cancellation)
+
+```javascript
+async function cancelableRequest() {
+  const controller = new AbortController();
+
+  // Cancel after 5 seconds
+  setTimeout(() => controller.abort(), 5000);
+
+  try {
+    const users = await management.users.getAll({}, {
+      signal: controller.signal,
+    });
+
+    return users;
+  } catch (err) {
+    if (err.name === 'AbortError') {
+      console.log('Request was cancelled');
+    }
+    throw err;
+  }
+}
+```
+
+## Logs and Monitoring
+
+### Getting Logs
+
+```javascript
+async function getLogs() {
+  const logs = await management.logs.getAll({
+    per_page: 100,
+    page: 0,
+  });
+
+  return logs;
+}
+```
+
+### Filtering Logs by Type
+
+```javascript
+async function getLoginLogs() {
+  const logs = await management.logs.getAll({
+    q: 'type:s', // 's' = successful login
+    per_page: 100,
+  });
+
+  return logs;
+}
+```
+
+### Getting Log by ID
+
+```javascript
+async function getLogById(logId) {
+  const log = await management.logs.get({ id: logId });
+
+  return log;
+}
+```
+
+## Guardian (MFA) Management
+
+### Getting Guardian Enrollments
+
+```javascript
+async function getUserMFAEnrollments(userId) {
+  const enrollments = await management.users.getGuardianEnrollments({ id: userId });
+
+  return enrollments;
+}
+```
+
+### Deleting Guardian Enrollment
+
+```javascript
+async function deleteMFAEnrollment(userId, enrollmentId) {
+  await management.guardian.deleteEnrollment({ id: enrollmentId });
+
+  console.log('MFA enrollment deleted');
+}
+```
+
+## Runtime Compatibility
+
+The Auth0 Node.js SDK v5 is compatible with:
+
+- Node.js 20.19.0+
+- Node.js 22.12.0+
+- Node.js 24.0.0+
+- Vercel Edge Functions
+- Cloudflare Workers
+- Deno
+- Bun
+- React Native
+
+## Legacy Support
+
+If you're migrating from v4.x, use the legacy exports:
+
+```javascript
+import { ManagementClient } from 'auth0/legacy';
+
+// Old v4.x configuration format
+const management = new ManagementClient({
+  domain: 'tenant.auth0.com',
+  clientId: 'CLIENT_ID',
+  clientSecret: 'CLIENT_SECRET',
+});
+```
+
+## Complete Example: User Registration and Login Flow
+
+```javascript
+import { ManagementClient, AuthenticationClient } from 'auth0';
+
+const management = new ManagementClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+
+const auth0 = new AuthenticationClient({
+  domain: process.env.AUTH0_DOMAIN,
+  clientId: process.env.AUTH0_CLIENT_ID,
+  clientSecret: process.env.AUTH0_CLIENT_SECRET,
+});
+
+async function registerAndLogin() {
+  // 1. Create a new user
+  const newUser = await management.users.create({
+    email: 'john.doe@example.com',
+    password: 'SecurePassword123!',
+    connection: 'Username-Password-Authentication',
+    user_metadata: {
+      firstName: 'John',
+      lastName: 'Doe',
+    },
+  });
+
+  console.log('User created:', newUser.user_id);
+
+  // 2. Send verification email
+  await management.jobs.verifyEmail({
+    user_id: newUser.user_id,
+  });
+
+  console.log('Verification email sent');
+
+  // 3. Login user (after email verification)
+  const loginResponse = await auth0.oauth.passwordGrant({
+    username: 'john.doe@example.com',
+    password: 'SecurePassword123!',
+    audience: 'https://api.example.com',
+    scope: 'openid profile email',
+  });
+
+  console.log('Access Token:', loginResponse.access_token);
+
+  // 4. Get user profile
+  const userInfo = new UserInfoClient({
+    domain: process.env.AUTH0_DOMAIN,
+  });
+
+  const profile = await userInfo.getUserInfo(loginResponse.access_token);
+  console.log('User Profile:', profile);
+
+  return {
+    user: newUser,
+    tokens: loginResponse,
+    profile,
+  };
+}
+```
+
+## Important Notes
+
+### Security Best Practices
+
+1. **Never expose client secrets** - Keep client secrets secure on the server side only
+2. **Use environment variables** - Store credentials in environment variables, not in code
+3. **Validate tokens** - Always validate tokens on the server side
+4. **Use HTTPS** - Always use HTTPS in production
+5. **Implement rate limiting** - Protect against brute force attacks
+6. **Rotate credentials** - Regularly rotate API tokens and client secrets
+
+### Management API Token
+
+- Management API tokens expire after 24 hours
+- Use client credentials grant for long-running applications
+- Cache tokens and refresh before expiration
+
+### Rate Limits
+
+Auth0 enforces rate limits on API requests. Handle 429 errors gracefully:
+
+```javascript
+async function retryWithBackoff(fn, maxRetries = 3) {
+  for (let i = 0; i < maxRetries; i++) {
+    try {
+      return await fn();
+    } catch (err) {
+      if (err.statusCode === 429 && i < maxRetries - 1) {
+        const waitTime = Math.pow(2, i) * 1000;
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+        continue;
+      }
+      throw err;
+    }
+  }
+}
+```
+
+### User Search Syntax
+
+Use Lucene query syntax for user searches:
+
+```javascript
+// Search by email domain
+q: 'email:"*@example.com"'
+
+// Search by metadata
+q: 'user_metadata.plan:"premium"'
+
+// Search by multiple fields
+q: 'email:"*@example.com" AND user_metadata.plan:"premium"'
+
+// Search by created date
+q: 'created_at:[2024-01-01 TO 2024-12-31]'
+```
+
+## Useful Links
+
+- Official Documentation: https://auth0.com/docs
+- SDK Reference: https://auth0.github.io/node-auth0/
+- GitHub Repository: https://github.com/auth0/node-auth0
+- Community Forum: https://community.auth0.com/
+- Auth0 Dashboard: https://manage.auth0.com/
+- API Rate Limits: https://auth0.com/docs/troubleshoot/customer-support/operational-policies/rate-limit-policy