auth0-deploy-cli 8.30.0 → 8.31.0

package/.circleci/config.yml

@@ -6,7 +6,7 @@ orbs:
 jobs:
   e2e_test_as_node_module:
     docker:
-      - image: cimg/node:22.12.0
+      - image: cimg/node:22.19.0
     working_directory: ~/repo
     steps:
       - checkout
@@ -15,7 +15,7 @@ jobs:
 
   e2e_test_as_cli:
     docker:
-      - image: cimg/node:22.12.0
+      - image: cimg/node:22.19.0
     working_directory: ~/repo
     steps:
       - checkout
@@ -45,21 +45,31 @@ jobs:
       - run: npm run test:coverage
       - persist_to_workspace:
           root: ~/repo
-          paths: .
+          paths:
+            - .
       - codecov/upload
 
   does_typescript_compile:
     docker:
-      - image: cimg/node:22.12.0
+      - image: cimg/node:22.19.0
     working_directory: ~/repo
     steps:
       - checkout
       - run: npm i
       - run: npx tsc --noEmit
 
+  does_format_pass:
+    docker:
+      - image: cimg/node:22.19.0
+    working_directory: ~/repo
+    steps:
+      - checkout
+      - run: npm i
+      - run: npm run format:check
+
   does_lint_pass:
     docker:
-      - image: cimg/node:22.12.0
+      - image: cimg/node:22.19.0
     working_directory: ~/repo
     steps:
       - checkout
@@ -83,6 +93,8 @@ workflows:
     jobs:
       - does_typescript_compile:
           name: Does Typescript compile?
+      - does_format_pass:
+          name: Does format pass?
       - does_lint_pass:
           name: Does lint pass?
       - unit_test:

package/AGENTS.md

@@ -63,7 +63,7 @@ npm run build && node lib/index.js import -c config-dev.json -i ./local-export/t
 
 ### File Structure
 
-```
+```text
 src/                                # TypeScript source
 ├── index.ts                        # CLI entry point
 ├── commands/                       # import.ts, export.ts
@@ -225,6 +225,26 @@ npm run lint
 - [ ] 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:

package/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [8.31.0] - 2026-04-10
+
+### Added
+
+- Add support for `is_default` on `customDomains`. [#1330]
+- Add `AUTH0_EXPORT_ORDERED` config property and `--export_ordered` flag for stable exports. [#1335]
+
+### Fixed
+
+- Fix `clientGrants` matching when multiple grants share the same `client_id` and `audience`. [#1341]
+
 ## [8.30.0] - 2026-04-02
 
 ### Added
@@ -1710,7 +1721,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 [#1340]: https://github.com/auth0/auth0-deploy-cli/issues/1340
 [#1342]: https://github.com/auth0/auth0-deploy-cli/issues/1342
 [#1343]: https://github.com/auth0/auth0-deploy-cli/issues/1343
-[Unreleased]: https://github.com/auth0/auth0-deploy-cli/compare/v8.30.0...HEAD
+[Unreleased]: https://github.com/auth0/auth0-deploy-cli/compare/v8.31.0...HEAD
+[8.31.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.30.0...v8.31.0
 [8.30.0]: https://github.com/auth0/auth0-deploy-cli/compare/v8.29.3...v8.30.0
 [8.29.3]: https://github.com/auth0/auth0-deploy-cli/compare/v8.29.2...v8.29.3
 [8.29.2]: https://github.com/auth0/auth0-deploy-cli/compare/v8.29.1...v8.29.2

package/CLAUDE.md

@@ -0,0 +1,3 @@
+# For project context see
+
+- [AGENTS.md](./AGENTS.md)

package/lib/args.d.ts

@@ -16,6 +16,7 @@ type ExportSpecificParams = {
     format: 'yaml' | 'directory';
     output_folder: string;
     export_ids?: boolean;
+    export_ordered?: boolean;
 };
 export type ExportParams = ExportSpecificParams & SharedParams;
 export type ImportParams = ImportSpecificParams & SharedParams;

package/lib/args.js

@@ -83,6 +83,11 @@ function getParams() {
             type: 'boolean',
             default: false,
         },
+        export_ordered: {
+            alias: 's',
+            describe: 'Order keys in exported JSON files for consistent diffs.',
+            type: 'boolean',
+        },
     })
         .example('$0 export -c config.json -f yaml -o path/to/export', 'Dump Auth0 config to folder in YAML format')
         .example('$0 export -c config.json -f directory -o path/to/export', 'Dump Auth0 config to folder in directory format')

package/lib/commands/export.js

@@ -11,7 +11,7 @@ const logger_1 = __importDefault(require("../logger"));
 const utils_1 = require("../utils");
 const index_1 = require("../context/index");
 async function exportCMD(params) {
-    const { output_folder: outputFolder, base_path: basePath, config_file: configFile, config: configObj, export_ids: exportIds, secret: clientSecret, env: shouldInheritEnv = false, experimental_ea: experimentalEA, } = params;
+    const { output_folder: outputFolder, base_path: basePath, config_file: configFile, config: configObj, export_ids: exportIds, export_ordered: exportOrdered, secret: clientSecret, env: shouldInheritEnv = false, experimental_ea: experimentalEA, } = params;
     if (shouldInheritEnv) {
         nconf_1.default.env().use('memory');
     }
@@ -32,6 +32,10 @@ async function exportCMD(params) {
     if (exportIds) {
         overrides.AUTH0_EXPORT_IDENTIFIERS = exportIds;
     }
+    // Allow passed in export_ordered to override the configured one
+    if (exportOrdered) {
+        overrides.AUTH0_EXPORT_ORDERED = exportOrdered;
+    }
     // Overrides AUTH0_INCLUDE_EXPERIMENTAL_EA is experimental_ea passed in command line
     if (experimentalEA) {
         overrides.AUTH0_EXPERIMENTAL_EA = experimentalEA;

package/lib/context/directory/handlers/actions.js

@@ -99,8 +99,7 @@ async function dump(context) {
         // Dump template metadata
         const name = (0, utils_1.sanitize)(action.name);
         const actionFile = path_1.default.join(actionsFolder, `${name}.json`);
-        logger_1.default.info(`Writing ${actionFile}`);
-        fs_extra_1.default.writeFileSync(actionFile, JSON.stringify(mapToAction(context.filePath, action, includeIdentifiers), null, 2));
+        (0, utils_1.dumpJSON)(actionFile, mapToAction(context.filePath, action, includeIdentifiers));
     });
 }
 const actionsHandler = {

package/lib/context/directory/handlers/triggers.js

@@ -7,7 +7,6 @@ const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const tools_1 = require("../../../tools");
 const utils_1 = require("../../../utils");
-const logger_1 = __importDefault(require("../../../logger"));
 function parse(context) {
     const triggersFolder = path_1.default.join(context.filePath, tools_1.constants.TRIGGERS_DIRECTORY);
     if (!(0, utils_1.existsMustBeDir)(triggersFolder))
@@ -29,8 +28,7 @@ async function dump(context) {
     const triggersFolder = path_1.default.join(context.filePath, tools_1.constants.TRIGGERS_DIRECTORY);
     fs_extra_1.default.ensureDirSync(triggersFolder);
     const triggerFile = path_1.default.join(triggersFolder, 'triggers.json');
-    logger_1.default.info(`Writing ${triggerFile}`);
-    fs_extra_1.default.writeFileSync(triggerFile, JSON.stringify(triggers, null, 2));
+    (0, utils_1.dumpJSON)(triggerFile, triggers);
 }
 const triggersHandler = {
     parse,

package/lib/context/yaml/index.js

@@ -183,7 +183,8 @@ class YAMLContext {
             cleaned = (0, utils_1.stripIdentifiers)(auth0, cleaned);
         }
         // Write YAML File
-        const raw = js_yaml_1.default.dump(cleaned);
+        const exportOrdered = Boolean(this.config.AUTH0_EXPORT_ORDERED);
+        const raw = js_yaml_1.default.dump(cleaned, { sortKeys: exportOrdered });
         logger_1.default.info(`Writing ${this.configFile}`);
         fs_extra_1.default.writeFileSync(this.configFile, raw);
     }

package/lib/tools/auth0/handlers/clientGrants.js

@@ -84,7 +84,9 @@ class ClientGrantsHandler extends default_1.default {
             type: 'clientGrants',
             id: 'id',
             // @ts-ignore because not sure why two-dimensional array passed in
-            identifiers: ['id', ['client_id', 'audience']],
+            // Try ['client_id', 'audience', 'subject_type'] first; falls through to
+            // ['client_id', 'audience'] when subject_type is null (falsy).
+            identifiers: ['id', ['client_id', 'audience', 'subject_type'], ['client_id', 'audience']],
             stripUpdateFields: ['audience', 'client_id', 'subject_type', 'is_system'],
         });
     }
@@ -155,6 +157,31 @@ class ClientGrantsHandler extends default_1.default {
             ...assets,
             clientGrants: formatted,
         });
+        // subject_type is immutable (in stripUpdateFields). Grants matched via the
+        // ['client_id', 'audience'] fallback with a mismatched subject_type must become
+        // DELETE + CREATE, not UPDATE, so the tenant converges to the desired state.
+        const subjectTypeMismatches = update.filter((localGrant) => {
+            // Only flag when local explicitly specifies subject_type (backward compat).
+            if (localGrant.subject_type === undefined)
+                return false;
+            const remoteGrant = (this.existing || []).find((e) => e.id === localGrant.id);
+            return (remoteGrant && (remoteGrant.subject_type ?? null) !== (localGrant.subject_type ?? null));
+        });
+        const adjustedUpdate = update.filter((u) => !subjectTypeMismatches.includes(u));
+        const adjustedDel = [
+            ...del,
+            ...subjectTypeMismatches
+                .map((u) => (this.existing || []).find((e) => e.id === u.id))
+                .filter((e) => e !== undefined),
+        ];
+        const adjustedCreate = [
+            ...create,
+            ...subjectTypeMismatches
+                .map((u) => formatted.find((f) => f.client_id === u.client_id &&
+                f.audience === u.audience &&
+                (f.subject_type ?? null) === (u.subject_type ?? null)))
+                .filter((g) => g !== undefined),
+        ];
         const filterGrants = (list) => {
             let filtered = list;
             // Filter out the current client (Auth0 Management API client)
@@ -174,11 +201,11 @@ class ClientGrantsHandler extends default_1.default {
         };
         const changes = {
             // @ts-ignore because this expects `client_id` and that's not yet typed on Asset
-            del: filterGrants(del),
+            del: filterGrants(adjustedDel),
             // @ts-ignore because this expects `client_id` and that's not yet typed on Asset
-            update: filterGrants(update),
+            update: filterGrants(adjustedUpdate),
             // @ts-ignore because this expects `client_id` and that's not yet typed on Asset
-            create: filterGrants(create),
+            create: filterGrants(adjustedCreate),
             // @ts-ignore because this expects `client_id` and that's not yet typed on Asset
             conflicts: filterGrants(conflicts),
         };

package/lib/tools/auth0/handlers/connections.d.ts

@@ -19,7 +19,6 @@ export declare const schema: {
                 properties: {
                     dpop_signing_alg: {
                         type: string;
-                        enum: ("ES256" | "Ed25519")[];
                     };
                 };
             };

package/lib/tools/auth0/handlers/connections.js

@@ -56,7 +56,6 @@ const connectionOptionsSchema = {
     properties: {
         dpop_signing_alg: {
             type: 'string',
-            enum: Object.values(auth0_1.Management.ConnectionDpopSigningAlgEnum),
         },
     },
 };

package/lib/tools/auth0/handlers/customDomains.d.ts

@@ -50,6 +50,10 @@ export declare const schema: {
                 type: string[];
                 description: string;
             };
+            is_default: {
+                type: string;
+                description: string;
+            };
         };
         required: string[];
     };
@@ -60,6 +64,7 @@ export default class CustomDomainsHadnler extends DefaultAPIHandler {
     constructor(config: DefaultAPIHandler);
     objString(item: Asset): string;
     getType(): Promise<Asset | null>;
+    validate(assets: Assets): Promise<void>;
     processChanges(assets: Assets): Promise<void>;
 }
 export {};

package/lib/tools/auth0/handlers/customDomains.js

@@ -44,6 +44,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.schema = void 0;
 const default_1 = __importStar(require("./default"));
+const validationError_1 = __importDefault(require("../../validationError"));
 const logger_1 = __importDefault(require("../../../logger"));
 exports.schema = {
     type: 'array',
@@ -81,6 +82,10 @@ exports.schema = {
                 type: ['string'],
                 description: 'Relying Party ID (rpId) to be used for Passkeys on this custom domain. If not provided or set to null, the full domain will be used.',
             },
+            is_default: {
+                type: 'boolean',
+                description: 'Whether this custom domain is the default domain used for email notifications.',
+            },
         },
         required: ['domain', 'type'],
     },
@@ -136,6 +141,16 @@ class CustomDomainsHadnler extends default_1.default {
             throw err;
         }
     }
+    async validate(assets) {
+        await super.validate(assets);
+        const { customDomains } = assets;
+        if (!customDomains)
+            return;
+        const defaultDomains = customDomains.filter((d) => d.is_default === true);
+        if (defaultDomains.length > 1) {
+            throw new validationError_1.default(`Only one custom domain can be set as default (is_default: true), but found ${defaultDomains.length}: ${defaultDomains.map((d) => d.domain).join(', ')}`);
+        }
+    }
     async processChanges(assets) {
         const { customDomains } = assets;
         if (!customDomains)
@@ -149,6 +164,17 @@ class CustomDomainsHadnler extends default_1.default {
         }
         const changes = await this.calcChanges(assets);
         await super.processChanges(assets, changes);
+        // If a domain is marked as is_default, set it as the tenant's default custom domain.
+        const defaultDomain = customDomains.find((d) => d.is_default === true);
+        if (defaultDomain) {
+            try {
+                await this.client.customDomains.setDefault({ domain: defaultDomain.domain });
+                logger_1.default.info(`Set default custom domain: ${defaultDomain.domain}`);
+            }
+            catch (err) {
+                throw new Error(`Problem setting default custom domain ${defaultDomain.domain}\n${err}`);
+            }
+        }
     }
 }
 exports.default = CustomDomainsHadnler;

package/lib/tools/auth0/handlers/tenant.js

@@ -198,6 +198,11 @@ class TenantHandler extends default_1.default {
                 delete updatedTenant.flags;
             }
         }
+        if (tenant.flags?.enable_custom_domain_in_emails !== undefined) {
+            logger_1.default.warn('The "enable_custom_domain_in_emails" tenant flag is deprecated. ' +
+                'Use the "is_default" field on customDomains to configure the default domain instead. ' +
+                'The flag will still be applied for now but will be removed in a future release.');
+        }
         if (updatedTenant && Object.keys(updatedTenant).length > 0) {
             await this.client.tenants.settings.update(updatedTenant);
             this.updated += 1;

package/lib/types.d.ts

@@ -71,6 +71,7 @@ export type Config = {
     AUTH0_RETRY_MAX_DELAY_MS?: number;
     AUTH0_KEYWORD_REPLACE_MAPPINGS?: KeywordMappings;
     AUTH0_EXPORT_IDENTIFIERS?: boolean;
+    AUTH0_EXPORT_ORDERED?: boolean;
     AUTH0_CONNECTIONS_DIRECTORY?: string;
     EXCLUDED_PROPS?: {
         [key: string]: string[];

package/lib/utils.js

@@ -24,6 +24,7 @@ exports.mapClientID2NameSorted = mapClientID2NameSorted;
 exports.nomalizedYAMLPath = nomalizedYAMLPath;
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
+const nconf_1 = __importDefault(require("nconf"));
 const sanitize_filename_1 = __importDefault(require("sanitize-filename"));
 const dot_prop_1 = __importDefault(require("dot-prop"));
 const lodash_1 = require("lodash");
@@ -69,10 +70,21 @@ function loadJSON(file, opts = {
         throw new Error(`Error parsing JSON from metadata file: ${file}, because: ${e.message}`);
     }
 }
+function orderedKeysReplacer(_key, value) {
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        return Object.fromEntries(Object.keys(obj)
+            .sort()
+            .map((k) => [k, obj[k]]));
+    }
+    return value;
+}
 function dumpJSON(file, mappings) {
     try {
         logger_1.default.info(`Writing ${file}`);
-        const jsonBody = JSON.stringify(mappings, null, 2);
+        const exportOrdered = Boolean(nconf_1.default.get('AUTH0_EXPORT_ORDERED'));
+        const replacer = exportOrdered ? orderedKeysReplacer : undefined;
+        const jsonBody = JSON.stringify(mappings, replacer, 2);
         fs_extra_1.default.writeFileSync(file, jsonBody.endsWith('\n') ? jsonBody : `${jsonBody}\n`);
     }
     catch (e) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auth0-deploy-cli",
-  "version": "8.30.0",
+  "version": "8.31.0",
   "description": "A command line tool for deploying updates to your Auth0 tenant",
   "main": "lib/index.js",
   "bin": {
@@ -9,6 +9,7 @@
   "scripts": {
     "lint:fix": "eslint --fix . && kacl lint",
     "lint": "eslint . && kacl lint",
+    "format:check": "npx prettier --check .",
     "format": "npx prettier --write .",
     "test": "ts-mocha -p tsconfig.json --recursive 'test/**/*.test*' --exclude 'test/e2e/*' --timeout 20000",
     "test:e2e:node-module": "ts-mocha -p tsconfig.json --recursive 'test/e2e/*.test*' --timeout 150000",
@@ -33,15 +34,15 @@
   "homepage": "https://github.com/auth0/auth0-deploy-cli#readme",
   "dependencies": {
     "ajv": "^6.12.6",
-    "auth0": "^5.5.0",
+    "auth0": "^5.6.0",
     "dot-prop": "^5.3.0",
     "fs-extra": "^10.1.0",
     "js-yaml": "^4.1.1",
-    "lodash": "^4.17.23",
+    "lodash": "^4.18.1",
     "mkdirp": "^1.0.4",
     "nconf": "^0.13.0",
     "promise-pool-executor": "^1.1.1",
-    "sanitize-filename": "^1.6.3",
+    "sanitize-filename": "^1.6.4",
     "undici": "^7.24.3",
     "winston": "^3.19.0",
     "yargs": "^15.4.1"
@@ -52,8 +53,8 @@
     "@types/lodash": "^4.17.24",
     "@types/mocha": "^10.0.10",
     "@types/nconf": "^0.10.7",
-    "@typescript-eslint/eslint-plugin": "^8.57.0",
-    "@typescript-eslint/parser": "^8.57.0",
+    "@typescript-eslint/eslint-plugin": "^8.58.0",
+    "@typescript-eslint/parser": "^8.58.0",
     "chai": "^4.5.0",
     "chai-as-promised": "^7.1.2",
     "eslint": "^9.39.2",