auth0-deploy-cli 9.0.0-beta.1 → 9.0.0

package/AGENTS.md

@@ -1,358 +1,3 @@
-# AGENTS.md
+# AI Agent Guidelines for auth0-deploy-cli
 
-## Project Overview
-
-The Auth0 Deploy CLI is a TypeScript-based tool for managing Auth0 tenant configurations through bidirectional sync (export/import) operations. It supports both YAML and directory formats with dynamic keyword replacement for multi-environment workflows.
-
-**Key Capabilities:**
-
-- Export Auth0 tenant configurations to local files (YAML or directory structure)
-- Import configurations from local files to Auth0 tenants
-- Keyword replacement for multi-environment deployments
-- Resource-specific handlers for 30+ Auth0 resource types
-
-## Setup Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Build TypeScript to JavaScript
-npm run build
-
-# Build in watch mode during development
-npm run dev
-
-# Run unit tests
-npm test
-
-# Run E2E tests (requires Auth0 tenant)
-npm run test:e2e:node-module
-npm run test:e2e:cli
-
-# Run linter
-npm run lint
-```
-
-## Development Workflow
-
-### Local Development Commands
-
-Common operations for working with the CLI:
-
-```bash
-# Export tenant configuration to local/
-npm run build && node lib/index.js export -c config-dev.json -f directory -o ./local/
-
-# Import configuration
-npm run build && node lib/index.js import -c config-dev.json -i ./local/tenant.json
-
-# Export as YAML
-npm run build && node lib/index.js export -c config-dev.json -f yaml -o ./local-export/
-
-# Import from YAML
-npm run build && node lib/index.js import -c config-dev.json -i ./local-export/tenant.yaml
-```
-
-### Build Process
-
-- Source TypeScript files live in `src/`
-- Compiled JavaScript output goes to `lib/` (published to npm)
-- Always run `npm run build` before testing CLI changes
-- Use `npm run dev` for watch mode during active development
-
-### File Structure
-
-```text
-src/                                # TypeScript source
-├── index.ts                        # CLI entry point
-├── commands/                       # import.ts, export.ts
-├── tools/                          # Core logic (deploy.ts, calculateChanges.ts)
-│   └── auth0/                      # Auth0 API integration
-│       ├── handlers/               # 30+ resource-specific handlers
-│       └── schema/                 # JSON validation schemas
-└── context/                        # Format parsers (yaml/, directory/)
-
-test/                               # Test suite mirrors src/
-├── tools/auth0/handlers/          # Handler unit tests
-├── context/                        # Context parser tests
-└── e2e/                           # End-to-end tests
-```
-
-## Code Style & Conventions
-
-### TypeScript Standards
-
-- Use strict TypeScript configuration (`tsconfig.json`)
-- Define types in `src/types.ts` for shared interfaces
-- Follow existing patterns for handler implementations
-- Use proper async/await patterns, avoid callbacks
-
-### Handler Implementation Pattern
-
-Every resource handler in `src/tools/auth0/handlers/` must implement:
-
-```typescript
-class ResourceHandler {
-  validate(); // Schema validation using AJV
-  processChanges(); // CRUD operations with API calls
-  calcChanges(); // Determine create/update/delete ops
-  dump(); // Format for export
-  getType(); // Fetch from Auth0 API
-}
-```
-
-### Configuration Management
-
-- All environment variables prefixed with `AUTH0_`
-- Config priority: CLI args → env vars → config files → defaults
-- Support both direct values and JSON serialization for complex types
-
-### Error Handling
-
-- Use `ValidationError` class from `src/tools/validationError.ts`
-- Provide clear, actionable error messages
-- Preserve context when bubbling errors up
-- Validate early before making API calls
-
-## Testing Instructions
-
-### Running Tests
-
-```bash
-# Unit tests only (fast)
-npm test
-
-# E2E tests as node module
-npm run test:e2e:node-module
-
-# E2E tests as CLI (requires real tenant credentials)
-npm run test:e2e:cli
-```
-
-### Test Structure
-
-- Unit tests mirror `src/` directory structure in `test/`
-- Use `.test.js` or `.test.ts` extensions
-- Handler tests use sinon stubs for Auth0 clients
-- Context tests use temporary directories with fixtures
-- E2E tests require real Auth0 tenant (configured via env vars)
-
-### Writing Handler Tests
-
-Pattern for testing resource handlers:
-
-```javascript
-const mockClient = {
-  resource: {
-    getAll: sinon.stub(),
-    create: sinon.stub(),
-    update: sinon.stub(),
-    delete: sinon.stub(),
-  },
-};
-
-const mockConfig = (key) => {
-  const config = {
-    AUTH0_ALLOW_DELETE: true,
-    AUTH0_EXCLUDED: [],
-  };
-  return config[key];
-};
-```
-
-### Test Coverage Requirements
-
-- Add tests for any new handlers or features
-- Test both success and error paths
-- Check resource identifier mapping logic
-- Test keyword replacement in context parsers
-
-### Running Specific Tests
-
-```bash
-# Run specific test file
-npm test -- test/tools/auth0/handlers/clients.test.js
-
-# Run tests matching pattern
-npm test -- --grep "should validate clients"
-```
-
-## Common Development Tasks
-
-### Adding a New Resource Handler
-
-1. Create handler in `src/tools/auth0/handlers/<resource>.ts`
-2. Implement all required methods (validate, processChanges, dump, etc.)
-3. Add resource type to `src/tools/constants.ts`
-4. Create JSON schema in `src/tools/auth0/schema/`
-5. Write unit tests in `test/tools/auth0/handlers/<resource>.test.js`
-6. Add E2E test coverage if applicable
-7. Update documentation in `docs/resource-specific-documentation.md`
-
-### Working with Context Parsers
-
-- **DirectoryContext** (`src/context/directory/`): Loads nested JSON files
-- **YAMLContext** (`src/context/yaml/`): Parses single YAML file
-- Both support keyword patterns: `@@KEY@@` (JSON-stringified) and `##KEY##` (literal)
-- Test with fixtures in `test/context/{directory,yaml}/`
-
-### Configuration Testing
-
-- Mock config functions return expected values for each key
-- Test resource exclusion with `AUTH0_EXCLUDED` and `AUTH0_EXCLUDED_*` patterns
-- Test property exclusion with `EXCLUDED_PROPS` and `INCLUDED_PROPS`
-- Verify keyword replacement mappings work correctly
-
-## Pull Request Guidelines
-
-### Before Committing
-
-```bash
-# Always run before commit
-npm run build
-npm test
-npm run lint
-```
-
-### PR Checklist
-
-- [ ] All tests pass locally
-- [ ] New code has corresponding tests
-- [ ] TypeScript compiles without errors
-- [ ] Updated relevant documentation in `docs/`
-- [ ] Added entry to `CHANGELOG.md` if user-facing change
-- [ ] Tested with both YAML and directory formats if applicable
-- [ ] Checked backward compatibility
-
-### Checklist for Every Feature or Fix
-
-#### Completion
-
-- [ ] Change is complete and matches the intended feature or fix
-- [ ] TypeScript compiles and tests pass locally
-
-#### Format and behavior
-
-- [ ] Works for both YAML and directory flows when the resource supports both
-- [ ] Keyword preservation still works as expected
-- [ ] Sorted-key output stays stable; no unintended order changes were introduced
-- [ ] Exported configs do not rely on IDs by default; resources should link by names where possible
-
-#### Safety and compatibility
-
-- [ ] Dry-run output is correct and non-destructive
-- [ ] Unit tests cover the changed path and any important edge cases
-- [ ] Backward compatibility was checked and no existing behavior was unintentionally broken
-
-### Commit Message Format
-
-Follow conventional commits style:
-
-- `feat: add support for new resource type`
-- `fix: resolve table formatting issue`
-- `docs: update handler implementation guide`
-- `test: add coverage for keyword replacement`
-- `refactor: simplify change calculation logic`
-
-## Security Considerations
-
-### API Credentials
-
-- Never commit Auth0 credentials or API keys
-- Config files with credentials should be gitignored
-- Use environment variables for sensitive data
-- Example configs use `.json.example` suffix
-
-### Validation & Safety
-
-- All resources validated against JSON schemas before processing
-- Delete operations require explicit `AUTH0_ALLOW_DELETE=true`
-- Resource identifiers properly sanitized before API calls
-
-### Testing with Real Tenants
-
-- Use dedicated development tenants for E2E tests
-- Never run E2E tests against production tenants
-- Credentials stored in environment variables only
-- Clean up test resources after test runs
-
-## Debugging Tips
-
-### Enable Debug Logging
-
-```bash
-export AUTH0_DEBUG=true
-npm run build && node lib/index.js import -c config.json
-```
-
-### Common Issues
-
-- **Build errors**: Check `tsconfig.json` and ensure all imports resolve
-- **Handler not found**: Verify resource added to `src/tools/constants.ts`
-- **Schema validation fails**: Check JSON schema in `src/tools/auth0/schema/`
-- **Keyword replacement not working**: Verify mappings in config and context parser
-
-### Useful Commands
-
-```bash
-# Check compiled output
-cat lib/index.js
-
-# Test CLI directly
-node lib/index.js export -c config.json --output_folder ./test-output
-
-# Run with verbose errors
-NODE_ENV=development npm test
-
-# Check Auth0 API pagination
-AUTH0_DEBUG=true npm run test:e2e:node-module
-```
-
-## Architecture Notes
-
-### Request Flow
-
-1. **CLI Entry** (`src/index.ts`) → Command routing
-2. **Commands** (`src/commands/import.ts`) → Load config and context
-3. **Deploy** (`src/tools/deploy.ts`) → Orchestrate deployment
-4. **Handlers** (`src/tools/auth0/handlers/*`) → Resource-specific logic
-5. **Auth0 Client** (`src/tools/auth0/client.ts`) → Management API calls
-
-### Change Calculation
-
-- Compare local assets (from YAML/directory) with remote state (from API)
-- Use resource identifiers (name, id, etc.) to match resources
-- Determine CREATE (new), UPDATE (changed), DELETE (removed) operations
-- Respect exclusion patterns and allow-delete config
-
-## Additional Resources
-
-- **Full documentation**: See `docs/` directory
-- **Examples**: Check `examples/yaml/` and `examples/directory/`
-- **Contributing**: Read `CONTRIBUTING.md`
-- **Migration guide**: See `docs/v8_MIGRATION_GUIDE.md`
-- **Issue templates**: `.github/ISSUE_TEMPLATE/`
-
-## Quick Reference
-
-### Environment Variables
-
-```bash
-AUTH0_DOMAIN                        # Tenant domain
-AUTH0_CLIENT_ID                     # Client ID
-AUTH0_CLIENT_SECRET                 # Client secret
-AUTH0_ALLOW_DELETE=true             # Enable deletions
-AUTH0_KEYWORD_REPLACE_MAPPINGS      # JSON mapping for replacements
-AUTH0_EXCLUDED                      # Array of resources to exclude
-AUTH0_DEBUG=true                    # Verbose logging
-```
-
-### Key Files to Know
-
-- `src/tools/deploy.ts` - Main deployment orchestrator
-- `src/tools/calculateChanges.ts` - Change detection logic
-- `src/tools/constants.ts` - Supported resource types
-- `src/configFactory.ts` - Configuration management
-- `src/types.ts` - TypeScript type definitions
-- `test/utils.js` - Test helper functions
+@./CLAUDE.md for all coding guidelines, commands, project structure, code style, testing conventions, and boundaries.

package/CHANGELOG.md

@@ -7,11 +7,112 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [9.0.0-beta.1] - 2026-07-02
+## [9.0.0] - 2026-09-18
 
-### Security
+### Changed
+
+- **⚠️ Breaking changes:**
+  - **Config file handlers (import): path traversal is now a hard error.** A file reference that resolves outside the config directory now aborts the import with an error instead of logging a deprecation warning (the warning shipped in 8.43.0 and 8.44.0). This applies to every file-backed field in both directory and YAML formats: action `code`, rule/hook `script`, database `customScripts`, client `custom_login_page`, connection/email-template/branding `body`, prompt partials, and flow/form bodies. Move any out-of-tree references (`../` relative paths or absolute paths) inside your config directory. Blocked references fail with `Path traversal blocked: "<input>" resolves to "<resolved>" which is outside the config directory "<root>".` before any Management API call. `a0deploy export` is unaffected. [#1498]
+  - **`AUTH0_DOMAIN` environment variable: must now be a bare host.** The `node-auth0` v7 upgrade validates the domain more strictly and rejects values that include a scheme or a trailing slash (for example `https://tenant.auth0.com/`); use a bare host such as `tenant.us.auth0.com`. This Management-API-only release also moves token acquisition to the SDK's managed auth, which auto-refreshes tokens during long-running import/export runs while preserving the previous fail-fast behavior on bad credentials. See the [node-auth0 v7 migration guide](https://github.com/auth0/node-auth0/blob/master/v7_MIGRATION_GUIDE.md). [#1491]
+
+### Added
+
+- Add handlers for MFA advanced factor configuration (phone/email OTP and Guardian settings). [#1497]
+- Add support for the `post-credential-validation` action trigger. [#1494]
+- Add anonymous sessions support to tenant, clients, and resource servers. [#1496]
+- Support `enforce_permission_ceiling` and `enforce_self_assignment_restriction` on `my_organization_configuration` (EA). [#1495]
+- Support tenants without the `riskAssessment` and `guardianPolicies` entitlement by handling `insufficient_entitlement` 403 responses gracefully instead of failing the run. [#1493]
+
+### Fixed
+
+- Surface the real API error on `tokenExchangeProfiles` 403 responses. [#1492]
+- Honor `kid` and other credential fields on `private_key_jwt`/mTLS credential creation. [#1489]
+- Apply `AUTH0_INCLUDED_CONNECTIONS` on export. [#1442]
+- Prevent client grant loss and duplication in directory-format exports. [#1473]
+
+## [8.45.0] - 2026-09-09
+
+### Added
+
+- Support `b2b_integration_configuration` for Enterprise Connect (EA). [#1486]
+- Add `networkACLKeys` handler for HMAC signature key management. [#1480]
+- Support `match_all` in network ACL rules for unconditional block/allow. [#1483]
+- Add `otp_settings` support for database connections. [#1481]
+
+### Fixed
+
+- Prevent export crash when a handler has no identifiers during keyword preservation. [#1487]
+- Catch `feature_not_enabled` via `err.body.errorCode` and 400 status in organizations handler. [#1482]
+- Prevent false `enabled_clients` diff in database dry-run. [#1479]
+
+## [8.44.0] - 2026-08-26
+
+### Added
+
+- Support `third_party_client_access` and `cross_app_access_resource_app` on clients and connections. [#1471]
+
+### Fixed
+
+- Warn on path traversal in file references and fix double-path resolution in YAML connections handler. [#1477]
+- Strip `form_submission_mode` and `form_submission_behavior` from `bruteForceProtection` on export and import. [#1476]
+- Include empty credentials for custom phone provider on import and export to prevent 400 errors. [#1474]
+- Preserve keyword placeholder strings for all email provider credentials. [#1470]
+- Preserve `idpinitiated.enabled:false` on SAML connection export instead of emitting `undefined_clientId`. [#1465]
+- Apply 429 backoff to organization connection writes to prevent rate-limit failures. [#1464]
+- Resolve dry-run reporting bugs across multiple asset types. [#1462]
+- Skip organization PATCH when no top-level properties have changed. [#1461]
+- Sort `attackProtection` arrays on export to prevent spurious diffs. [#1460]
+
+## [8.43.0] - 2026-08-12
+
+### Added
+
+- Add org-to-app entitlement (EA) support for organizations. [#1454]
+- Support full group metadata for Google Workspace directory sync (GA). [#1456]
+
+### Fixed
+
+- Create phone templates on import instead of skipping when they have no ID. [#1457]
+- Address path traversal vulnerability and false warnings in config file handlers. [#1449]
+- Exclude org-scoped roles from tenant export by filtering `type='tenant'`. [#1453]
+- Strip read-only field from roles to fix export/import round-trip. [#1445]
+
+## [8.42.0] - 2026-07-30
+
+### Added
+
+- Add UL identifier input support for themes and tenant settings. [#1433]
+- Add `token_vault_privileged_access` support for clients. [#1430]
+- Add `auth0_managed` field support for network ACLs (Curated Blocklists - EA). [#1435]
+- Add Cross App Access (XAA) resource app support for connections and clients. [#1431]
+- Add `cross_app_access_requesting_app` support for connections (EA). [#1422]
+
+### Fixed
+
+- Prevent dry-run crash on `clientAuthCredentials` handler. [#1438]
+- Resolve spurious dry-run diffs for rules, themes, and hooks. [#1437]
+- Strip unresolved placeholders on deploy instead of throwing. [#1436]
+- Handle 403 entitlement errors for bot detection and captcha on export. [#1434]
+- Warn and skip deprecated guardian phone provider on 403 during import. [#1429]
+- Add `use_scope_descriptions_for_consent` to allowed tenant flags. [#1428]
+
+## [8.41.0] - 2026-07-16
+
+### Added
+
+- Add `third_party_client_access` support for organizations. [#1421]
+
+## [8.40.0] - 2026-07-09
+
+### Added
+
+- Add client credential lifecycle management for Private Key JWT and mTLS authentication methods. [#1417]
+- Add Rate Limit Policies (EA) support. [#1395]
+
+### Fixed
 
-- Prevent path traversal attacks in config file handlers for directory and YAML contexts. [#1418]
+- Preserve `false` value for `default_head_tags_disabled` in screen renderer update. [#1416]
+- Skip destination update for action event streams as the destination type cannot be changed after creation. [#1425]
 
 ## [8.39.0] - 2026-06-30
 
@@ -1848,6 +1949,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#1389]: https://github.com/auth0/auth0-deploy-cli/issues/1389
 [#1391]: https://github.com/auth0/auth0-deploy-cli/issues/1391
 [#1392]: https://github.com/auth0/auth0-deploy-cli/issues/1392
+[#1395]: https://github.com/auth0/auth0-deploy-cli/issues/1395
 [#1396]: https://github.com/auth0/auth0-deploy-cli/issues/1396
 [#1398]: https://github.com/auth0/auth0-deploy-cli/issues/1398
 [#1400]: https://github.com/auth0/auth0-deploy-cli/issues/1400
@@ -1860,9 +1962,63 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#1409]: https://github.com/auth0/auth0-deploy-cli/issues/1409
 [#1411]: https://github.com/auth0/auth0-deploy-cli/issues/1411
 [#1412]: https://github.com/auth0/auth0-deploy-cli/issues/1412
-[#1418]: https://github.com/auth0/auth0-deploy-cli/issues/1418
-[Unreleased]: https://github.com/auth0/auth0-deploy-cli/compare/v9.0.0-beta.1...HEAD
-[9.0.0-beta.1]: https://github.com/auth0/auth0-deploy-cli/compare/v8.39.0...v9.0.0-beta.1
+[#1416]: https://github.com/auth0/auth0-deploy-cli/issues/1416
+[#1417]: https://github.com/auth0/auth0-deploy-cli/issues/1417
+[#1421]: https://github.com/auth0/auth0-deploy-cli/issues/1421
+[#1422]: https://github.com/auth0/auth0-deploy-cli/issues/1422
+[#1425]: https://github.com/auth0/auth0-deploy-cli/issues/1425
+[#1428]: https://github.com/auth0/auth0-deploy-cli/issues/1428
+[#1429]: https://github.com/auth0/auth0-deploy-cli/issues/1429
+[#1430]: https://github.com/auth0/auth0-deploy-cli/issues/1430
+[#1431]: https://github.com/auth0/auth0-deploy-cli/issues/1431
+[#1433]: https://github.com/auth0/auth0-deploy-cli/issues/1433
+[#1434]: https://github.com/auth0/auth0-deploy-cli/issues/1434
+[#1435]: https://github.com/auth0/auth0-deploy-cli/issues/1435
+[#1436]: https://github.com/auth0/auth0-deploy-cli/issues/1436
+[#1437]: https://github.com/auth0/auth0-deploy-cli/issues/1437
+[#1438]: https://github.com/auth0/auth0-deploy-cli/issues/1438
+[#1442]: https://github.com/auth0/auth0-deploy-cli/issues/1442
+[#1445]: https://github.com/auth0/auth0-deploy-cli/issues/1445
+[#1449]: https://github.com/auth0/auth0-deploy-cli/issues/1449
+[#1453]: https://github.com/auth0/auth0-deploy-cli/issues/1453
+[#1454]: https://github.com/auth0/auth0-deploy-cli/issues/1454
+[#1456]: https://github.com/auth0/auth0-deploy-cli/issues/1456
+[#1457]: https://github.com/auth0/auth0-deploy-cli/issues/1457
+[#1460]: https://github.com/auth0/auth0-deploy-cli/issues/1460
+[#1461]: https://github.com/auth0/auth0-deploy-cli/issues/1461
+[#1462]: https://github.com/auth0/auth0-deploy-cli/issues/1462
+[#1464]: https://github.com/auth0/auth0-deploy-cli/issues/1464
+[#1465]: https://github.com/auth0/auth0-deploy-cli/issues/1465
+[#1470]: https://github.com/auth0/auth0-deploy-cli/issues/1470
+[#1471]: https://github.com/auth0/auth0-deploy-cli/issues/1471
+[#1473]: https://github.com/auth0/auth0-deploy-cli/issues/1473
+[#1474]: https://github.com/auth0/auth0-deploy-cli/issues/1474
+[#1476]: https://github.com/auth0/auth0-deploy-cli/issues/1476
+[#1477]: https://github.com/auth0/auth0-deploy-cli/issues/1477
+[#1479]: https://github.com/auth0/auth0-deploy-cli/issues/1479
+[#1480]: https://github.com/auth0/auth0-deploy-cli/issues/1480
+[#1481]: https://github.com/auth0/auth0-deploy-cli/issues/1481
+[#1482]: https://github.com/auth0/auth0-deploy-cli/issues/1482
+[#1483]: https://github.com/auth0/auth0-deploy-cli/issues/1483
+[#1486]: https://github.com/auth0/auth0-deploy-cli/issues/1486
+[#1487]: https://github.com/auth0/auth0-deploy-cli/issues/1487
+[#1489]: https://github.com/auth0/auth0-deploy-cli/issues/1489
+[#1491]: https://github.com/auth0/auth0-deploy-cli/issues/1491
+[#1492]: https://github.com/auth0/auth0-deploy-cli/issues/1492
+[#1493]: https://github.com/auth0/auth0-deploy-cli/issues/1493
+[#1494]: https://github.com/auth0/auth0-deploy-cli/issues/1494
+[#1495]: https://github.com/auth0/auth0-deploy-cli/issues/1495
+[#1496]: https://github.com/auth0/auth0-deploy-cli/issues/1496
+[#1497]: https://github.com/auth0/auth0-deploy-cli/issues/1497
+[#1498]: https://github.com/auth0/auth0-deploy-cli/issues/1498
+[Unreleased]: https://github.com/auth0/auth0-deploy-cli/compare/v9.0.0...HEAD
+[9.0.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.45.0...v9.0.0
+[8.45.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.44.0...v8.45.0
+[8.44.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.43.0...v8.44.0
+[8.43.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.42.0...v8.43.0
+[8.42.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.41.0...v8.42.0
+[8.41.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.40.0...v8.41.0
+[8.40.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.39.0...v8.40.0
 [8.39.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.38.0...v8.39.0
 [8.38.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.37.0...v8.38.0
 [8.37.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.36.0...v8.37.0