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

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

@@ -46,6 +46,7 @@ exports.schema = void 0;
 const logger_1 = __importDefault(require("../../../logger"));
 const default_1 = __importStar(require("./default"));
 const utils_1 = require("../../utils");
+const calculateDryRunChanges_1 = require("../../calculateDryRunChanges");
 /**
  * Schema
  */
@@ -251,6 +252,41 @@ exports.schema = {
                 pattern: '^[^<>]*$',
                 type: 'string',
             },
+            identifiers: {
+                additionalProperties: false,
+                description: 'Identifier display settings on the theme. Requires the `universal_login_theme_identifiers` feature flag to be enabled on the tenant.',
+                properties: {
+                    login_display: {
+                        description: 'Login display mode',
+                        enum: ['separate', 'unified'],
+                        type: 'string',
+                    },
+                    otp_autocomplete: {
+                        description: 'Whether OTP autocomplete is enabled',
+                        type: 'boolean',
+                    },
+                    phone_display: {
+                        additionalProperties: false,
+                        description: 'Phone number display settings',
+                        properties: {
+                            formatting: {
+                                description: 'Phone number formatting style',
+                                enum: ['international', 'regional'],
+                                type: 'string',
+                            },
+                            masking: {
+                                description: 'Phone number masking strategy',
+                                enum: ['hide_country_code', 'mask_digits', 'show_all'],
+                                type: 'string',
+                            },
+                        },
+                        required: ['formatting', 'masking'],
+                        type: 'object',
+                    },
+                },
+                required: ['login_display', 'otp_autocomplete', 'phone_display'],
+                type: 'object',
+            },
             fonts: {
                 additionalProperties: false,
                 properties: {
@@ -470,6 +506,34 @@ class ThemesHandler extends default_1.default {
     objString(theme) {
         return theme.displayName || JSON.stringify(theme);
     }
+    async dryRunChanges(assets) {
+        const { themes } = assets;
+        if (!themes) {
+            return { del: [], create: [], conflicts: [], update: [] };
+        }
+        const existing = await this.getType();
+        // getType() returns null when Universal Login customizations are not enabled
+        // on the tenant (the 400 "no-code not enabled" path in getThemes).
+        if (existing === null) {
+            return { del: [], create: [], conflicts: [], update: [] };
+        }
+        // Themes are singletons — at most one per tenant. If the local theme has no
+        // themeId (stripped during export when --export_ids is not set), backfill it
+        // from the remote so the matcher can find a match without requiring --export_ids.
+        const normalizedThemes = themes.map((theme) => {
+            if (!theme.themeId && existing.length > 0 && existing[0].themeId) {
+                return { ...theme, themeId: existing[0].themeId };
+            }
+            return theme;
+        });
+        return (0, calculateDryRunChanges_1.calculateDryRunChanges)({
+            type: this.type,
+            assets: normalizedThemes,
+            existing,
+            identifiers: this.identifiers,
+            ignoreDryRunFields: this.getEffectiveIgnoreDryRunFields(),
+        });
+    }
     async getType() {
         if (!this.existing) {
             this.existing = await this.getThemes();

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

@@ -138,7 +138,9 @@ class TokenExchangeProfilesHandler extends default_1.default {
         }
         catch (err) {
             if (err.statusCode === 403) {
-                logger_1.default.warn('Token Exchange Profiles feature is not available on this tenant. Please contact Auth0 support to enable this feature.');
+                logger_1.default.warn(`Cannot retrieve tokenExchangeProfiles: ${err.message}. ` +
+                    `Verify the M2M application has the 'read:token_exchange_profiles' scope and ` +
+                    `your subscription plan includes Token Exchange Profiles.`);
                 return [];
             }
             throw err;

package/lib/tools/auth0/index.js

@@ -11,13 +11,10 @@ const promise_pool_executor_1 = require("promise-pool-executor");
 const client_1 = __importDefault(require("./client"));
 const schema_1 = __importDefault(require("./schema"));
 const handlers_1 = __importDefault(require("./handlers"));
-// Cache the compiled AJV validator to avoid recompiling the schema on every validate() call.
-// Schema compilation is expensive (~5s) due to the complexity of the combined resource schema.
-const ajv = new ajv_1.default({ useDefaults: true, nullable: true });
-const validateSchema = ajv.compile(schema_1.default);
 const calculateDryRunChanges_1 = require("../calculateDryRunChanges");
 const utils_1 = require("../../utils");
 const utils_2 = require("../utils");
+const logger_1 = __importDefault(require("../../logger"));
 /**
  * Sorts handlers by their @order decorator metadata for a given stage.
  * Handlers are sorted in ascending order (lower values execute first).
@@ -109,12 +106,13 @@ class Auth0 {
         }
     }
     async validate() {
+        const ajv = new ajv_1.default({ useDefaults: true, nullable: true });
         const nonNullAssets = Object.keys(this.assets)
             .filter((k) => this.assets[k] != null)
             .reduce((a, k) => ({ ...a, [k]: this.assets[k] }), {});
-        const valid = validateSchema(nonNullAssets);
+        const valid = ajv.validate(schema_1.default, nonNullAssets);
         if (!valid) {
-            throw new Error(`Schema validation failed loading ${JSON.stringify(validateSchema.errors, null, 4)}`);
+            throw new Error(`Schema validation failed loading ${JSON.stringify(ajv.errors, null, 4)}`);
         }
         await this.runStage('validate');
     }
@@ -148,6 +146,14 @@ class Auth0 {
             data: this.handlers,
             generator: (handler) => (async () => {
                 try {
+                    // Every handler in the dry-run loop is expected to implement dryRunChanges.
+                    // Guard against non-conforming handlers (e.g. deploy-only handlers that don't
+                    // extend the base APIHandler) so a missing method skips the handler instead of
+                    // crashing the whole dry run. Logged loudly so an omitted preview is visible.
+                    if (typeof handler.dryRunChanges !== 'function') {
+                        logger_1.default.warn(`Handler "${handler.type}" does not implement dryRunChanges; skipping it in the dry-run preview. Changes for this resource will still be applied during a real import.`);
+                        return;
+                    }
                     const detailedChanges = [];
                     let created = 0;
                     let updated = 0;

package/lib/tools/calculateDryRunChanges.js

@@ -108,6 +108,13 @@ function normalizeArrayValues(values) {
         .map((value) => normalizeValue(value))
         .sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
 }
+/**
+ * Serializes a value to a human-readable string for use in diff messages.
+ * Objects and arrays are JSON-stringified to avoid "[object Object]" output.
+ */
+function formatDiffValue(value) {
+    return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+}
 /**
  * Writes the accumulated diff log to a JSON file on disk.
  * Useful for CI pipelines that want a machine-readable dry-run report.
@@ -179,7 +186,7 @@ function getObjectDifferences(localObj, remoteObj, keyObjPath = '', resourceType
                         differences.push(...nestedDifferences);
                     }
                     else if (item !== normalizedRemoteValue[index]) {
-                        const message = `Array item difference at [${currentPath}[${index}]]: local:${item} vs remote:${normalizedRemoteValue[index]}`;
+                        const message = `Array item difference at [${currentPath}[${index}]]: local:${formatDiffValue(item)} vs remote:${formatDiffValue(normalizedRemoteValue[index])}`;
                         differences.push(message);
                     }
                 });
@@ -204,13 +211,10 @@ function getObjectDifferences(localObj, remoteObj, keyObjPath = '', resourceType
             differences.push(...nestedDifferences);
             return;
         }
-        // Compare primitive values — omit array indices from path to reduce log noise
+        // Compare primitive values
         if (localValue !== remoteValue) {
-            let arrayPathRegex = new RegExp(/\[\d+\]/g);
-            if (!arrayPathRegex.test(currentPath)) {
-                const message = `Value difference for [${currentPath}]: local:${localValue} vs remote:${remoteValue}`;
-                differences.push(message);
-            }
+            const message = `Value difference for [${currentPath}]: local:${localValue} vs remote:${remoteValue}`;
+            differences.push(message);
         }
     });
     return differences;
@@ -242,7 +246,7 @@ function calculateDryRunChanges({ type, assets, existing, identifiers = ['id', '
     const create = [];
     const conflicts = [];
     const localAssets = (Array.isArray(assets) ? [...assets] : [assets]).map((asset) => type === 'tenant' ? normalizeTenantForDryRun(asset) : asset);
-    const remoteAssets = (Array.isArray(existing) ? [...existing] : [existing]).map((asset) => (type === 'tenant' ? normalizeTenantForDryRun(asset) : asset));
+    const remoteAssets = (Array.isArray(existing) ? [...existing] : existing ? [existing] : []).map((asset) => (type === 'tenant' ? normalizeTenantForDryRun(asset) : asset));
     // Helper: returns true if a local and remote asset share at least one identifier value
     const assetsMatch = (localAsset, remoteAsset) => identifiers.some((id) => {
         if (Array.isArray(id)) {

package/lib/tools/constants.d.ts

@@ -86,10 +86,12 @@ declare const constants: {
     FLOWS_VAULT_DIRECTORY: string;
     SELF_SERVICE_PROFILE_DIRECTORY: string;
     NETWORK_ACLS_DIRECTORY: string;
+    NETWORK_ACL_KEYS_DIRECTORY: string;
     USER_ATTRIBUTE_PROFILES_DIRECTORY: string;
     CONNECTION_PROFILES_DIRECTORY: string;
     TOKEN_EXCHANGE_PROFILES_DIRECTORY: string;
     SUPPLEMENTAL_SIGNALS_DIRECTORY: string;
+    RATE_LIMIT_POLICIES_DIRECTORY: string;
     EVENT_STREAMS_DIRECTORY: string;
 };
 export default constants;

package/lib/tools/constants.js

@@ -68,6 +68,7 @@ const constants = {
         'custom-token-exchange',
         'login-post-identifier',
         'signup-post-identifier',
+        'post-credential-validation',
     ],
     EMAIL_TEMPLATES_DIRECTORY: 'emails',
     EMAIL_VERIFY,
@@ -216,10 +217,12 @@ const constants = {
     FLOWS_VAULT_DIRECTORY: 'flow-vault-connections',
     SELF_SERVICE_PROFILE_DIRECTORY: 'self-service-profiles',
     NETWORK_ACLS_DIRECTORY: 'network-acls',
+    NETWORK_ACL_KEYS_DIRECTORY: 'network-acl-keys',
     USER_ATTRIBUTE_PROFILES_DIRECTORY: 'user-attribute-profiles',
     CONNECTION_PROFILES_DIRECTORY: 'connection-profiles',
     TOKEN_EXCHANGE_PROFILES_DIRECTORY: 'token-exchange-profiles',
     SUPPLEMENTAL_SIGNALS_DIRECTORY: 'supplemental-signals',
+    RATE_LIMIT_POLICIES_DIRECTORY: 'rate-limit-policies',
     EVENT_STREAMS_DIRECTORY: 'event-streams',
 };
 exports.default = constants;

package/lib/tools/utils.d.ts

@@ -27,6 +27,7 @@ export declare function areArraysEquals(x: any[], y: any[]): boolean;
 export declare const obfuscateSensitiveValues: (data: Asset | Asset[] | null, sensitiveFieldsToObfuscate: string[]) => Asset | Asset[] | null;
 export declare const validateNoUnresolvedPlaceholders: (data: Asset | null, resourceType: string, resourceName: string) => Asset | null;
 export declare const stripObfuscatedFieldsFromPayload: (data: Asset | Asset[] | null, obfuscatedFields: string[]) => Asset | Asset[] | null;
+export declare const stripUnresolvedPlaceholders: (data: Asset | null, resourceType: string, resourceName: string) => Asset | null;
 export declare const detectInsufficientScopeError: <T>(fn: Function) => Promise<{
     hadSufficientScopes: true;
     data: T;
@@ -41,6 +42,8 @@ export declare const isDeprecatedError: (err: {
     message: string;
     statusCode: number;
 }) => boolean;
+export declare const isFeatureUnavailableError: (err: any) => boolean;
+export declare const isInsufficientEntitlementError: (err: unknown) => boolean;
 export declare const isForbiddenFeatureError: (err: any, type: any) => boolean;
 export declare function maskSecretAtPath({ resourceTypeName, maskedKeyName, maskOnObj, keyJsonPath, }: {
     resourceTypeName: string;

package/lib/tools/utils.js

@@ -36,7 +36,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.shouldExcludeThirdPartyClients = exports.isForbiddenFeatureError = exports.isDeprecatedError = exports.detectInsufficientScopeError = exports.stripObfuscatedFieldsFromPayload = exports.validateNoUnresolvedPlaceholders = exports.obfuscateSensitiveValues = exports.keywordReplaceStringRegExp = exports.keywordReplaceArrayRegExp = void 0;
+exports.shouldExcludeThirdPartyClients = exports.isForbiddenFeatureError = exports.isInsufficientEntitlementError = exports.isFeatureUnavailableError = exports.isDeprecatedError = exports.detectInsufficientScopeError = exports.stripUnresolvedPlaceholders = exports.stripObfuscatedFieldsFromPayload = exports.validateNoUnresolvedPlaceholders = exports.obfuscateSensitiveValues = exports.keywordReplaceStringRegExp = exports.keywordReplaceArrayRegExp = void 0;
 exports.keywordArrayReplace = keywordArrayReplace;
 exports.keywordStringReplace = keywordStringReplace;
 exports.keywordReplace = keywordReplace;
@@ -309,6 +309,24 @@ const stripObfuscatedFieldsFromPayload = (data, obfuscatedFields) => {
     return newAsset;
 };
 exports.stripObfuscatedFieldsFromPayload = stripObfuscatedFieldsFromPayload;
+// Strips unresolved ##...## / @@...@@ placeholders before sending to Auth0.
+// Keyword replacement runs first; any remaining placeholder means no mapping was
+// provided. The field is dropped so Auth0 preserves its existing value.
+const stripUnresolvedPlaceholders = (data, resourceType, resourceName) => {
+    if (data === null)
+        return data;
+    const unresolved = collectUnresolvedPlaceholders(data);
+    if (unresolved.length === 0)
+        return data;
+    const newAsset = { ...data };
+    unresolved.forEach(({ path, value }) => {
+        logger_1.default.warn(`Stripping unresolved placeholder for ${resourceType} "${resourceName}" field "${path}": ${value}. ` +
+            `To use this value, define ${value.replace(/^##|##$|^@@|@@$/g, '')} in AUTH0_KEYWORD_REPLACE_MAPPINGS. The existing value on Auth0 will be preserved.`);
+        dot_prop_1.default.delete(newAsset, path);
+    });
+    return newAsset;
+};
+exports.stripUnresolvedPlaceholders = stripUnresolvedPlaceholders;
 const detectInsufficientScopeError = async (fn) => {
     try {
         const data = await fn();
@@ -340,9 +358,30 @@ const isDeprecatedError = (err) => {
     return !!(err.statusCode === 403 || err.message?.includes('deprecated feature'));
 };
 exports.isDeprecatedError = isDeprecatedError;
+const isFeatureUnavailableError = (err) => {
+    // A 404 indicates an older Management API version where the endpoint is not available.
+    // 403s (feature explicitly disabled) are handled by isForbiddenFeatureError.
+    return err.statusCode === 404;
+};
+exports.isFeatureUnavailableError = isFeatureUnavailableError;
+const isInsufficientEntitlementError = (err) => {
+    if (!err || typeof err !== 'object')
+        return false;
+    const e = err;
+    if (e.statusCode !== 403)
+        return false;
+    const body = e.body;
+    return body?.errorCode === 'insufficient_entitlement';
+};
+exports.isInsufficientEntitlementError = isInsufficientEntitlementError;
 const isForbiddenFeatureError = (err, type) => {
     if (err.statusCode === 403) {
-        logger_1.default.warn(`${err.message};${err.errorCode ?? ''} - Skipping ${type}`);
+        // The SDK error's top-level `message` is the full serialized response body; the clean,
+        // human-readable message and errorCode live on the response body itself.
+        const body = err.originalError?.response?.body ?? {};
+        const message = body.message ?? err.message;
+        const errorCode = body.errorCode ?? err.errorCode ?? '';
+        logger_1.default.warn(`${message}${errorCode ? ` (${errorCode})` : ''} - Skipping ${type}`);
         return true;
     }
     return false;

package/lib/types.d.ts

@@ -16,11 +16,13 @@ import { SsProfileWithCustomText } from './tools/auth0/handlers/selfServiceProfi
 import { PhoneProvider } from './tools/auth0/handlers/phoneProvider';
 import { PhoneTemplate } from './tools/auth0/handlers/phoneTemplates';
 import { NetworkACL } from './tools/auth0/handlers/networkACLs';
+import { NetworkAclKey } from './tools/auth0/handlers/networkACLKeys';
 import { UserAttributeProfile } from './tools/auth0/handlers/userAttributeProfiles';
 import { AttackProtection } from './tools/auth0/handlers/attackProtection';
 import { TokenExchangeProfile } from './tools/auth0/handlers/tokenExchangeProfiles';
 import { RiskAssessment } from './tools/auth0/handlers/riskAssessment';
 import { SupplementalSignals } from './tools/auth0/handlers/supplementalSignals';
+import { RateLimitPolicy } from './tools/auth0/handlers/rateLimitPolicies';
 import { EventStream } from './tools/auth0/handlers/eventStreams';
 type SharedPaginationParams = {
     checkpoint?: boolean;
@@ -30,6 +32,7 @@ type SharedPaginationParams = {
     include_totals?: boolean;
     id?: string;
     strategy?: Management.ConnectionStrategyEnum[];
+    type?: Management.RoleTypeEnum;
 };
 export type CheckpointPaginationParams = SharedPaginationParams & {
     from?: string;
@@ -127,6 +130,9 @@ export type Assets = Partial<{
         message_types: Asset[];
     } | null;
     guardianPhoneFactorSelectedProvider: Asset | null;
+    guardianPhoneFactorSettings: Asset | null;
+    guardianEmailFactorSettings: Asset | null;
+    guardianSettings: Asset | null;
     guardianPolicies: {
         policies: string[];
     } | null;
@@ -154,11 +160,13 @@ export type Assets = Partial<{
     flows: Flow[] | null;
     flowVaultConnections: FlowVaultConnection[] | null;
     selfServiceProfiles: SsProfileWithCustomText[] | null;
+    networkACLKeys: NetworkAclKey[] | null;
     networkACLs: NetworkACL[] | null;
     userAttributeProfiles: UserAttributeProfile[] | null;
     userAttributeProfilesWithId: UserAttributeProfile[] | null;
     connectionProfiles: Asset[] | null;
     tokenExchangeProfiles: TokenExchangeProfile[] | null;
+    rateLimitPolicies: RateLimitPolicy[] | null;
     eventStreams: EventStream[] | null;
 }>;
 export type CalculatedChanges = {
@@ -180,7 +188,7 @@ export type DetailedDryRunChanges = {
         changes: DetailedDryRunChange[];
     };
 };
-export type AssetTypes = 'rules' | 'rulesConfigs' | 'hooks' | 'pages' | 'databases' | 'clientGrants' | 'resourceServers' | 'clients' | 'connections' | 'tenant' | 'emailProvider' | 'emailTemplates' | 'guardianFactors' | 'guardianFactorProviders' | 'guardianFactorTemplates' | 'guardianPhoneFactorMessageTypes' | 'guardianPhoneFactorSelectedProvider' | 'guardianPolicies' | 'roles' | 'actions' | 'actionModules' | 'organizations' | 'triggers' | 'attackProtection' | 'riskAssessment' | 'branding' | 'phoneProviders' | 'phoneTemplates' | 'logStreams' | 'prompts' | 'customDomains' | 'themes' | 'forms' | 'flows' | 'flowVaultConnections' | 'selfServiceProfiles' | 'networkACLs' | 'userAttributeProfiles' | 'connectionProfiles' | 'tokenExchangeProfiles' | 'supplementalSignals' | 'eventStreams';
+export type AssetTypes = 'rules' | 'rulesConfigs' | 'hooks' | 'pages' | 'databases' | 'clientGrants' | 'resourceServers' | 'clients' | 'connections' | 'tenant' | 'emailProvider' | 'emailTemplates' | 'guardianFactors' | 'guardianFactorProviders' | 'guardianFactorTemplates' | 'guardianPhoneFactorMessageTypes' | 'guardianPhoneFactorSelectedProvider' | 'guardianPhoneFactorSettings' | 'guardianEmailFactorSettings' | 'guardianSettings' | 'guardianPolicies' | 'roles' | 'actions' | 'actionModules' | 'organizations' | 'triggers' | 'attackProtection' | 'riskAssessment' | 'branding' | 'phoneProviders' | 'phoneTemplates' | 'logStreams' | 'prompts' | 'customDomains' | 'themes' | 'forms' | 'flows' | 'flowVaultConnections' | 'selfServiceProfiles' | 'networkACLKeys' | 'networkACLs' | 'userAttributeProfiles' | 'connectionProfiles' | 'tokenExchangeProfiles' | 'supplementalSignals' | 'rateLimitPolicies' | 'eventStreams' | 'clientAuthCredentials';
 export type KeywordMappings = {
     [key: string]: (string | number)[] | string | number;
 };

package/lib/utils.d.ts

@@ -52,4 +52,10 @@ export declare const getFormattedOptions: (connection: any, clients: any) => {
 } | {
     options?: undefined;
 };
+/**
+ * Asserts that `resolvedPath` is inside `configRoot`.
+ * Throws a hard error on path traversal attempts so there is a single,
+ * canonical enforcement point across all handlers.
+ */
+export declare function assertInsideConfigRoot(input: string, resolvedPath: string, configRoot: string): void;
 export {};

package/lib/utils.js

@@ -23,6 +23,7 @@ exports.convertClientIdToName = convertClientIdToName;
 exports.hasKeywordMarkers = hasKeywordMarkers;
 exports.mapClientID2NameSorted = mapClientID2NameSorted;
 exports.nomalizedYAMLPath = nomalizedYAMLPath;
+exports.assertInsideConfigRoot = assertInsideConfigRoot;
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const nconf_1 = __importDefault(require("nconf"));
@@ -301,12 +302,15 @@ exports.decodeBase64ToCertString = decodeBase64ToCertString;
 // Format connection options by converting client IDs to client names for SAML connections
 const getFormattedOptions = (connection, clients) => {
     try {
+        const { idpinitiated } = connection.options;
         return {
             options: {
                 ...connection.options,
                 idpinitiated: {
-                    ...connection.options.idpinitiated,
-                    client_id: convertClientIdToName(connection.options.idpinitiated.client_id, clients),
+                    ...idpinitiated,
+                    ...(idpinitiated.client_id && {
+                        client_id: convertClientIdToName(idpinitiated.client_id, clients),
+                    }),
                 },
             },
         };
@@ -316,3 +320,14 @@ const getFormattedOptions = (connection, clients) => {
     }
 };
 exports.getFormattedOptions = getFormattedOptions;
+/**
+ * Asserts that `resolvedPath` is inside `configRoot`.
+ * Throws a hard error on path traversal attempts so there is a single,
+ * canonical enforcement point across all handlers.
+ */
+function assertInsideConfigRoot(input, resolvedPath, configRoot) {
+    if (!resolvedPath.startsWith(configRoot + path_1.default.sep)) {
+        throw new Error(`Path traversal blocked: "${input}" resolves to "${resolvedPath}" which is outside the config directory "${configRoot}". ` +
+            `Move the file inside your config directory.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auth0-deploy-cli",
-  "version": "9.0.0-beta.2",
+  "version": "9.0.0",
   "description": "A command line tool for deploying updates to your Auth0 tenant",
   "main": "lib/index.js",
   "bin": {
@@ -35,7 +35,7 @@
   "dependencies": {
     "@clack/prompts": "1.4.0",
     "ajv": "^6.12.6",
-    "auth0": "^5.13.0",
+    "auth0": "^7.2.0",
     "chalk": "5.6.2",
     "dot-prop": "^5.3.0",
     "fs-extra": "^10.1.0",

package/references/code-style.md

@@ -0,0 +1,133 @@
+# Code Style Reference — auth0-deploy-cli
+
+## Naming Conventions
+
+| Element              | Convention       | Example                             |
+| -------------------- | ---------------- | ----------------------------------- |
+| Source files         | camelCase        | `clients.ts`, `attackProtection.ts` |
+| Classes              | PascalCase       | `ClientsHandler`, `YAMLContext`     |
+| Methods / variables  | camelCase        | `processChanges`, `calcChanges`     |
+| Constants / env vars | UPPER_SNAKE_CASE | `AUTH0_ALLOW_DELETE`                |
+| Test files           | `<name>.test.js` | `clients.test.js`                   |
+
+## Handler Implementation Pattern
+
+Every resource handler in `src/tools/auth0/handlers/` must implement four methods:
+
+```typescript
+class ResourceHandler extends DefaultHandler {
+  // Fetch current state from Auth0 API
+  async getType(): Promise<Asset[]> { ... }
+
+  // Determine create / update / delete operations
+  async calcChanges(assets: Assets): Promise<Changes> { ... }
+
+  // Execute CRUD operations — must be a no-op in dry run
+  async processChanges(assets: Assets, changes: Changes): Promise<void> { ... }
+
+  // Validate assets before processing; base class provides a default
+  async validate(assets: Assets): Promise<void> { ... }
+}
+```
+
+> `dump()` / export formatting is handled by `YAMLContext` and `DirectoryContext`, not by handlers.
+
+Register the handler in `src/tools/constants.ts`. Handler schemas are defined inline in the handler file and aggregated by `src/tools/auth0/schema.ts`.
+
+## Identifiers
+
+```typescript
+// ✅ Stable name-based identifier (passed as constructor option to super())
+super({ ...options, identifiers: ['name'] });
+
+// ✅ ID alongside name (when the API uses both for matching)
+super({ ...options, identifiers: ['client_id', 'name'] });
+
+// 🚫 Never — sole auto-generated UUID breaks cross-tenant portability
+super({ ...options, identifiers: ['id'] });
+```
+
+## Keyword Replacement
+
+```yaml
+# @@KEY@@ — JSON-stringified (arrays, objects, booleans, numbers)
+allowed_clients: @@ALLOWED_CLIENTS@@
+
+# ##KEY## — literal string substitution (plain strings only)
+name: "##APP_NAME##"
+```
+
+Both patterns must be preserved in every new field that flows through export/import. Mixing them up causes silent corruption — a `##KEY##` around a JSON array produces invalid YAML.
+
+## Good vs Bad Handler Example
+
+**✅ Good — follows the pattern, respects dry-run and ALLOW_DELETE:**
+
+```typescript
+async processChanges(assets: Assets, changes: Changes): Promise<void> {
+  if (this.config('AUTH0_ALLOW_DELETE')) {
+    await Promise.all(changes.delete.map((r) => this.client.resource.delete({ id: r.id })));
+  }
+  await Promise.all(changes.create.map((r) => this.client.resource.create(r)));
+  await Promise.all(changes.update.map((r) => this.client.resource.update({ id: r.id }, r)));
+}
+```
+
+**❌ Bad — logs a secret, missing ALLOW_DELETE guard:**
+
+```typescript
+async processChanges(assets: Assets, changes: Changes): Promise<void> {
+  console.log('client_secret:', assets.clients[0].client_secret); // never log secrets
+  // missing AUTH0_ALLOW_DELETE check — deletes happen unconditionally
+  await Promise.all(changes.delete.map((r) => this.client.clients.delete({ client_id: r.client_id })));
+}
+```
+
+## @order() Decorator
+
+Handlers run in dependency order. Set `@order(N)` so that handlers whose resources are depended upon by others run first:
+
+```typescript
+@order(30)  // runs after Connections (20) and before Rules (40)
+export default class ClientsHandler extends DefaultHandler { ... }
+```
+
+Wrong order causes 404s or constraint errors mid-deploy.
+
+## Adding a New Resource Handler
+
+1. Create handler in `src/tools/auth0/handlers/<resource>.ts`
+2. Extend `DefaultHandler` and implement all four methods (`getType`, `calcChanges`, `processChanges`, `validate`)
+3. Add the resource type constant to `src/tools/constants.ts`
+4. Define the JSON schema inline in the handler; it is aggregated by `src/tools/auth0/schema.ts`
+5. Write unit tests in `test/tools/auth0/handlers/<resource>.test.js`
+6. Add E2E test coverage if applicable (or document why it's not possible)
+7. Update `docs/resource-specific-documentation.md` and `examples/` to demonstrate the new resource
+
+## Context Parser Details
+
+- **DirectoryContext** (`src/context/directory/`): loads each resource type from separate nested JSON files
+- **YAMLContext** (`src/context/yaml/`): parses a single `tenant.yaml` file with all resources inline
+- Both support `@@KEY@@` and `##KEY##` keyword substitution
+- Context tests use temporary directories with fixtures in `test/context/{directory,yaml}/`
+
+## Configuration and Error Handling
+
+**Config priority order:** CLI args → env vars → config files → defaults
+
+**Error handling conventions:**
+
+- Use `ValidationError` from `src/tools/validationError.ts` for all validation failures
+- Validate early, before making API calls
+- Preserve context when bubbling errors up the call stack
+- Provide clear, actionable error messages
+
+## Architecture: Request Flow
+
+```
+src/index.ts            CLI entry — routes export / import commands
+src/commands/           import.ts, export.ts — load config and context
+src/tools/deploy.ts     Orchestrate deployment across all handlers
+src/tools/auth0/handlers/*  Resource-specific getType / calcChanges / processChanges
+src/tools/auth0/client.ts   Management API calls via the auth0 npm SDK
+```