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

package/CLAUDE.md

@@ -1,3 +1,139 @@
-# For project context see
+# AI Agent Guidelines for auth0-deploy-cli
 
-- [AGENTS.md](./AGENTS.md)
+## Your Role
+
+You are a TypeScript CLI engineer maintaining auth0-deploy-cli — a bidirectional sync tool for Auth0 tenant configurations. You write resource handlers, context parsers, and change-detection logic.
+
+---
+
+## Project Structure
+
+```
+auth0-deploy-cli/
+├── src/                           # TypeScript source
+│   ├── index.ts                   # CLI entry point (export + import commands)
+│   ├── commands/                  # import.ts, export.ts — command wiring
+│   ├── configFactory.ts           # Configuration loading and validation
+│   ├── types.ts                   # Shared TypeScript interfaces
+│   ├── context/
+│   │   ├── directory/             # Directory-format parser + keyword replacement
+│   │   └── yaml/                  # YAML-format parser + keyword replacement
+│   └── tools/
+│       ├── deploy.ts              # Main deployment orchestrator
+│       ├── calculateChanges.ts    # Change detection (create / update / delete)
+│       ├── constants.ts           # Supported resource type registry
+│       ├── validationError.ts     # ValidationError class
+│       └── auth0/
+│           ├── client.ts          # Management API client wrapper
+│           ├── handlers/          # 49 resource-specific handlers (schemas embedded per handler)
+│           └── schema.ts          # AJV schema aggregator (compiled from handler schemas)
+├── test/                          # Mirrors src/
+│   ├── tools/auth0/handlers/      # Handler unit tests
+│   ├── context/                   # Context parser tests
+│   └── e2e/                       # E2E tests (require real Auth0 tenant)
+├── examples/
+│   ├── directory/                 # Sample directory-format config
+│   └── yaml/                      # Sample YAML-format config
+├── docs/                          # Extended documentation
+├── .circleci/config.yml           # CI: lint → unit tests → publish
+└── package.json                   # npm scripts and dependencies
+```
+
+---
+
+## Boundaries
+
+### ✅ Always Do
+
+- Run `npm run build && npm test && npm run lint` before committing
+- Make surgical changes — touch only what the request requires; do not refactor or reformat adjacent code that isn't broken
+- Support both YAML and directory context formats when implementing or changing resource handling
+- Preserve `@@KEY@@` (JSON-stringified / array values) and `##KEY##` (literal string) keyword replacement in every new field that flows through export/import
+- Strip write-only fields (secrets, key material) on export; exclude read-only API-generated fields (`created_at`, `updated_at`, `id`, `fingerprint`) from create/update payloads
+- Use `name` (or a stable name-like field) as the primary entry in a handler's `identifiers[]` array — never solely an auto-generated UUID `id`
+- Place new handlers in `@order()` after all their dependencies
+- Add unit tests for new logic; test both the happy path and error paths
+- Update `README.md` and `examples/` in the same PR when changing CLI commands, flags, output formats, or supported resource types
+
+### ⚠️ Ask First
+
+- Any breaking change — never break backward compatibility on your own initiative; stop and ask first
+- Adding or bumping dependencies in `package.json`
+- Modifying public CLI commands, subcommands, or flag names
+- Changes to `.circleci/config.yml`
+- Modifying keyword replacement logic or the export/import schema
+- Running E2E tests — they hit a real Auth0 tenant and can mutate resources (see [references/testing.md](references/testing.md))
+- **EA / entitlement-gated features**: Before marking complete — document every code path you could not test end-to-end, spell out the exact API shape assumptions your code relies on, verify that the list endpoint returns the fields read from `this.existing`, and create a follow-up ticket to re-verify once entitlement is available
+
+### 🚫 Never Do
+
+- Commit secrets, API keys, Auth0 credentials, or PEM keys
+- Mutate state on the dry-run path — `processChanges()` must be a complete no-op during dry run on every affected path
+- Use an auto-generated UUID as the sole entry in `identifiers[]`; always include `name` as the primary matching key
+- Log or export write-only fields (secrets, key material, tokens)
+- Add `additionalProperties: false` to a schema for an EA-gated object without confirming the full API response shape from a real tenant response
+- Modify `node_modules/`, `lib/`, or other build-output directories by hand
+
+---
+
+## Security Considerations
+
+- Auth0 credentials (`AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`) are never committed; `config*.json` and `.env` are gitignored
+- Write-only fields (secrets, signing keys, PEM material) are stripped on export and never written to disk
+- Delete operations require explicit `AUTH0_ALLOW_DELETE=true`; absent this flag, the handler silently skips deletes
+- Resource identifiers are sanitized before use in API calls
+- No telemetry in this repo — deploy-cli delegates all Auth0 API calls to the `auth0` npm SDK, which handles its own telemetry
+
+---
+
+> The sections below are **reference** — each keeps a one-line anchor inline and offloads its body to `references/*.md`.
+
+## Commands
+
+```bash
+npm run build       # compile TypeScript → lib/
+npm test            # unit tests (safe — no credentials required)
+npm run lint        # eslint + kacl changelog lint
+```
+
+See [references/commands.md](references/commands.md) for the full command reference including E2E tests, watch mode, and direct CLI invocation. Read when you need to build, test, or run the CLI.
+
+---
+
+## Testing
+
+Unit tests (`npm test`) are safe — no credentials required. E2E tests require a real Auth0 tenant; ask before running (see Boundaries).
+
+See [references/testing.md](references/testing.md) for test conventions, sinon mock patterns, handler test scaffolding, and E2E requirements. Read when writing or debugging tests.
+
+---
+
+## Code Style
+
+Single quotes, semicolons required, `no-unused-vars` — all three fail CI via ESLint (`eslint.config.js`). TypeScript strict mode is off; do not enable without asking first.
+
+See [references/code-style.md](references/code-style.md) for naming conventions, handler implementation patterns, and good/bad examples. Read when adding a new handler or context parser.
+
+---
+
+## Git Workflow
+
+Conventional Commits (`feat:`, `fix:`, `docs:`, `refactor:`, `test:`). Branch naming: `DXCDT-XXXX` (Jira ticket number).
+
+See [references/git-workflow.md](references/git-workflow.md) for PR conventions and the full PR review checklist. Read before creating or reviewing a PR.
+
+---
+
+## Common Pitfalls
+
+See [references/pitfalls.md](references/pitfalls.md). Read before implementing a new handler or touching keyword replacement, dry-run, EA-gated features, or the export/import roundtrip.
+
+---
+
+## Docs Update Rules
+
+`README.md` — present. `EXAMPLES.md` — missing (create when adding a new integration pattern or command example). `examples/` — present (yaml/ and directory/ samples).
+
+> Update `README.md` and `examples/` in the same PR when changing CLI commands, flags, output formats, or supported resource types. Do not defer.
+
+See [references/docs-update.md](references/docs-update.md) for the full tracked-docs inventory and code-to-docs mapping table. Read when adding or changing commands, flags, or resource types.

package/README.md

@@ -8,7 +8,7 @@
 
 The Auth0 Deploy CLI is a tool that helps you manage your Auth0 tenant configuration. It integrates into your development workflows as a standalone CLI or as a node module.
 
-**Supported resource types:** actions, branding, client grants, clients (applications), connections, databases, custom domains, email templates, emails, grants, guardian, hook secrets, log streams, organizations, pages, prompts, resource servers (APIs), roles, tenant settings, themes, forms, flows, self-service profiles, network ACLs.
+**Supported resource types:** actions, branding, client grants, clients (applications), connections, databases, custom domains, email templates, emails, grants, guardian, hook secrets, log streams, organizations, pages, prompts, resource servers (APIs), roles, tenant settings, themes, forms, flows, self-service profiles, network ACLs, network ACL keys.
 
 🎢 [Highlights](#highlights) • 📚 [Documentation](#documentation) • 🚀 [Getting Started](#getting-started) • 📝 [Feedback](#feedback) • 💬 [Discussions](https://github.com/auth0/auth0-deploy-cli/discussions)
 

package/lib/context/defaults.d.ts

@@ -6,4 +6,11 @@ export declare function phoneTemplatesDefaults(phoneTemplate: any): any;
 export declare function connectionDefaults(connection: any, config?: Pick<Config, 'AUTH0_EXPORT_SECRETS'>): any;
 export declare function logStreamDefaults(logStreams: any, config?: Pick<Config, 'AUTH0_EXPORT_SECRETS'>): any;
 export declare function eventStreamDefaults(eventStreams: any[], config?: Pick<Config, 'AUTH0_EXPORT_SECRETS'>): any[];
+/**
+ * Sorts primitive arrays (e.g. `shields`, `admin_notification_frequency`) within the
+ * attackProtection subtree in place, so repeated exports produce deterministic output.
+ * These are unordered, string-typed enum sets — ordering is cosmetic. Object arrays are
+ * left as-is.
+ */
+export declare function sortAttackProtectionArrays(attackProtection: AttackProtection): AttackProtection;
 export declare function attackProtectionDefaults(attackProtection: AttackProtection, config?: Pick<Config, 'AUTH0_EXPORT_SECRETS'>): AttackProtection;

package/lib/context/defaults.js

@@ -6,6 +6,7 @@ exports.phoneTemplatesDefaults = phoneTemplatesDefaults;
 exports.connectionDefaults = connectionDefaults;
 exports.logStreamDefaults = logStreamDefaults;
 exports.eventStreamDefaults = eventStreamDefaults;
+exports.sortAttackProtectionArrays = sortAttackProtectionArrays;
 exports.attackProtectionDefaults = attackProtectionDefaults;
 const utils_1 = require("../tools/utils");
 // env vars arrive as strings, so check both forms
@@ -22,45 +23,57 @@ function emailProviderDefaults(emailProvider, config) {
     // Add placeholder for credentials as they cannot be exported
     const { name } = updated;
     if (apiKeyProviders.includes(name)) {
-        updated.credentials = {
-            api_key: `##${name.toUpperCase()}_API_KEY##`,
-            ...(updated.credentials || {}),
-        };
+        if (typeof updated.credentials !== 'string') {
+            updated.credentials = {
+                api_key: `##${name.toUpperCase()}_API_KEY##`,
+                ...(updated.credentials || {}),
+            };
+        }
     }
     if (name === 'smtp') {
-        // This is to mask smtp_user to '##SMTP_USER##'
-        if (updated.credentials && 'smtp_user' in updated.credentials) {
-            delete updated.credentials.smtp_user;
+        // If credentials is a keyword placeholder string (e.g. @@SMTP_CREDENTIALS@@), preserve it as-is.
+        // The `in` operator requires an object and would throw a TypeError on a string.
+        if (typeof updated.credentials !== 'string') {
+            // This is to mask smtp_user to '##SMTP_USER##'
+            if (updated.credentials && 'smtp_user' in updated.credentials) {
+                delete updated.credentials.smtp_user;
+            }
+            updated.credentials = {
+                smtp_host: '##SMTP_HOSTNAME##',
+                smtp_port: '##SMTP_PORT##',
+                smtp_user: '##SMTP_USER##',
+                smtp_pass: '##SMTP_PASS##',
+                ...(updated.credentials || {}),
+            };
         }
-        updated.credentials = {
-            smtp_host: '##SMTP_HOSTNAME##',
-            smtp_port: '##SMTP_PORT##',
-            smtp_user: '##SMTP_USER##',
-            smtp_pass: '##SMTP_PASS##',
-            ...(updated.credentials || {}),
-        };
     }
     if (name === 'ses') {
-        updated.credentials = {
-            accessKeyId: '##SES_ACCESS_KEY_ID##',
-            secretAccessKey: '##SES_ACCESS_SECRET_KEY##',
-            region: '##SES_AWS_REGION##',
-            ...(updated.credentials || {}),
-        };
+        if (typeof updated.credentials !== 'string') {
+            updated.credentials = {
+                accessKeyId: '##SES_ACCESS_KEY_ID##',
+                secretAccessKey: '##SES_ACCESS_SECRET_KEY##',
+                region: '##SES_AWS_REGION##',
+                ...(updated.credentials || {}),
+            };
+        }
     }
     if (name === 'azure_cs') {
-        updated.credentials = {
-            connectionString: '##AZURE_CS_CONNECTION_KEY##',
-            ...(updated.credentials || {}),
-        };
+        if (typeof updated.credentials !== 'string') {
+            updated.credentials = {
+                connectionString: '##AZURE_CS_CONNECTION_KEY##',
+                ...(updated.credentials || {}),
+            };
+        }
     }
     if (name === 'ms365') {
-        updated.credentials = {
-            tenantId: '##MS365_TENANT_ID##',
-            clientId: '##MS365_CLIENT_ID##',
-            clientSecret: '##MS365_CLIENT_SECRET##',
-            ...(updated.credentials || {}),
-        };
+        if (typeof updated.credentials !== 'string') {
+            updated.credentials = {
+                tenantId: '##MS365_TENANT_ID##',
+                clientId: '##MS365_CLIENT_ID##',
+                clientSecret: '##MS365_CLIENT_SECRET##',
+                ...(updated.credentials || {}),
+            };
+        }
     }
     return updated;
 }
@@ -87,6 +100,12 @@ function phoneProviderDefaults(phoneProvider) {
             auth_token: `##${name.toUpperCase()}_AUTH_TOKEN##`,
         };
     }
+    else if (name === 'custom') {
+        // The `custom` provider has no exportable secrets, but the API requires a
+        // `credentials` object on import even when empty. Emit an empty object so
+        // exported configs round-trip cleanly.
+        updated.credentials = {};
+    }
     return updated;
 }
 function phoneTemplatesDefaults(phoneTemplate) {
@@ -193,6 +212,31 @@ function eventStreamDefaults(eventStreams, config) {
         };
     });
 }
+/**
+ * Sorts primitive arrays (e.g. `shields`, `admin_notification_frequency`) within the
+ * attackProtection subtree in place, so repeated exports produce deterministic output.
+ * These are unordered, string-typed enum sets — ordering is cosmetic. Object arrays are
+ * left as-is.
+ */
+function sortAttackProtectionArrays(attackProtection) {
+    const sortArraysDeep = (value) => {
+        if (Array.isArray(value)) {
+            const isPrimitiveArray = value.every((item) => item === null || typeof item !== 'object');
+            if (isPrimitiveArray) {
+                value.sort();
+            }
+            else {
+                value.forEach(sortArraysDeep);
+            }
+            return;
+        }
+        if (value && typeof value === 'object') {
+            Object.values(value).forEach(sortArraysDeep);
+        }
+    };
+    sortArraysDeep(attackProtection);
+    return attackProtection;
+}
 function attackProtectionDefaults(attackProtection, config) {
     if (isExportSecrets(config))
         return attackProtection;

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

@@ -24,10 +24,7 @@ function parse(context) {
             const normalizedCode = module.code.replace(/\\/g, '/');
             const configRoot = path_1.default.resolve(context.filePath);
             const resolvedPath = path_1.default.resolve(context.filePath, normalizedCode);
-            if (!resolvedPath.startsWith(configRoot + path_1.default.sep)) {
-                throw new Error(`Path "${module.code}" resolves to "${resolvedPath}" which is outside the config directory "${configRoot}". ` +
-                    `Move the file inside your config directory.`);
-            }
+            (0, utils_1.assertInsideConfigRoot)(module.code, resolvedPath, configRoot);
             module.code = (0, tools_1.loadFileAndReplaceKeywords)(resolvedPath, {
                 mappings: context.mappings,
                 disableKeywordReplacement: context.disableKeywordReplacement,

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

@@ -26,10 +26,7 @@ function parse(context) {
             const normalizedCode = action.code.replace(/\\/g, '/');
             const configRoot = path_1.default.resolve(context.filePath);
             const resolvedPath = path_1.default.resolve(context.filePath, normalizedCode);
-            if (!resolvedPath.startsWith(configRoot + path_1.default.sep)) {
-                throw new Error(`Path "${action.code}" resolves to "${resolvedPath}" which is outside the config directory "${configRoot}". ` +
-                    `Move the file inside your config directory.`);
-            }
+            (0, utils_1.assertInsideConfigRoot)(action.code, resolvedPath, configRoot);
             action.code = (0, tools_1.loadFileAndReplaceKeywords)(resolvedPath, {
                 mappings: context.mappings,
                 disableKeywordReplacement: context.disableKeywordReplacement,

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

@@ -17,6 +17,7 @@ function attackProtectionFiles(filePath) {
         bruteForceProtection: path_1.default.join(directory, 'brute-force-protection.json'),
         captcha: path_1.default.join(directory, 'captcha.json'),
         suspiciousIpThrottling: path_1.default.join(directory, 'suspicious-ip-throttling.json'),
+        phoneProviderProtection: path_1.default.join(directory, 'phone-provider-protection.json'),
     };
 }
 function parse(context) {
@@ -55,6 +56,12 @@ function parse(context) {
             disableKeywordReplacement: context.disableKeywordReplacement,
         });
     }
+    if ((0, utils_1.isFile)(files.phoneProviderProtection)) {
+        attackProtection.phoneProviderProtection = (0, utils_1.loadJSON)(files.phoneProviderProtection, {
+            mappings: context.mappings,
+            disableKeywordReplacement: context.disableKeywordReplacement,
+        });
+    }
     return {
         attackProtection,
     };
@@ -65,7 +72,7 @@ async function dump(context) {
         return;
     const files = attackProtectionFiles(context.filePath);
     fs_extra_1.default.ensureDirSync(files.directory);
-    const maskedAttackProtection = (0, defaults_1.attackProtectionDefaults)(attackProtection, context.config);
+    const maskedAttackProtection = (0, defaults_1.sortAttackProtectionArrays)((0, defaults_1.attackProtectionDefaults)(attackProtection, context.config));
     if (maskedAttackProtection.botDetection) {
         (0, utils_1.dumpJSON)(files.botDetection, maskedAttackProtection.botDetection);
     }
@@ -81,6 +88,9 @@ async function dump(context) {
     if (maskedAttackProtection.suspiciousIpThrottling) {
         (0, utils_1.dumpJSON)(files.suspiciousIpThrottling, maskedAttackProtection.suspiciousIpThrottling);
     }
+    if (maskedAttackProtection.phoneProviderProtection) {
+        (0, utils_1.dumpJSON)(files.phoneProviderProtection, maskedAttackProtection.phoneProviderProtection);
+    }
 }
 const attackProtectionHandler = {
     parse,

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

@@ -31,7 +31,10 @@ function parse(context) {
             disableKeywordReplacement: context.disableKeywordReplacement,
         });
         const normalizedPathArray = (0, utils_1.nomalizedYAMLPath)(definition.body);
-        definition.body = (0, tools_1.loadFileAndReplaceKeywords)(path_1.default.join(brandingTemplatesFolder, ...normalizedPathArray), {
+        const resolvedBodyFile = path_1.default.resolve(brandingTemplatesFolder, ...normalizedPathArray);
+        const configRoot = path_1.default.resolve(context.filePath);
+        (0, utils_1.assertInsideConfigRoot)(definition.body, resolvedBodyFile, configRoot);
+        definition.body = (0, tools_1.loadFileAndReplaceKeywords)(resolvedBodyFile, {
             mappings: context.mappings,
             disableKeywordReplacement: context.disableKeywordReplacement,
         });

package/lib/context/directory/handlers/clientAuthCredentials.d.ts

@@ -0,0 +1,5 @@
+import { DirectoryHandler } from '.';
+import { ParsedAsset } from '../../../types';
+type ParsedClientAuthCredentials = ParsedAsset<'clientAuthCredentials', null>;
+declare const clientAuthCredentialsHandler: DirectoryHandler<ParsedClientAuthCredentials>;
+export default clientAuthCredentialsHandler;

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

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+function parse(_context) {
+    return { clientAuthCredentials: null };
+}
+async function dump(_context) {
+    // Credentials are embedded inside each client's JSON file — nothing to dump separately.
+}
+const clientAuthCredentialsHandler = {
+    parse,
+    dump,
+};
+exports.default = clientAuthCredentialsHandler;

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

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const path_1 = __importDefault(require("path"));
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const tools_1 = require("../../../tools");
+const logger_1 = __importDefault(require("../../../logger"));
 const utils_1 = require("../../../utils");
 const client_1 = require("../../../tools/auth0/client");
 const keywordPreservation_1 = require("../../../keywordPreservation");
@@ -41,34 +42,23 @@ async function dump(context) {
         paginate: true,
         include_totals: true,
     });
-    // Filter out grants for excluded clients
-    if (excludedClientsByNames.length) {
-        const excludedClientIds = new Set(allClients
-            .filter((c) => c.name !== undefined && excludedClientsByNames.includes(c.name))
-            .map((c) => c.client_id));
-        clientGrants = clientGrants.filter((grant) => !excludedClientIds.has(grant.client_id));
-    }
-    // Convert client_id to the client name for readability
-    clientGrants.forEach((grant) => {
-        const dumpGrant = { ...grant };
-        if (context.assets.clientsOrig) {
-            dumpGrant.client_id = (0, utils_1.convertClientIdToName)(dumpGrant.client_id, context.assets.clientsOrig);
-        }
+    // Convert audience to the API name for readability
+    const apiName = (grantAudience) => {
+        if (!grantAudience)
+            return grantAudience;
+        const associatedAPI = allResourceServers.find((resourceServer) => resourceServer.identifier === grantAudience);
+        if (associatedAPI === undefined)
+            return grantAudience; // Use the audience if the API is not found
+        return associatedAPI.name; // Use the name of the API
+    };
+    // Derive the filename for a grant.
+    const nameFor = (grant) => {
         const clientName = (() => {
             const associatedClient = allClients.find((client) => client.client_id === grant.client_id);
             if (associatedClient === undefined)
                 return grant.client_id;
             return associatedClient.name;
         })();
-        // Convert audience to the API name for readability
-        const apiName = (grantAudience) => {
-            if (!grantAudience)
-                return grantAudience;
-            const associatedAPI = allResourceServers.find((resourceServer) => resourceServer.identifier === grantAudience);
-            if (associatedAPI === undefined)
-                return grantAudience; // Use the audience if the API is not found
-            return associatedAPI.name; // Use the name of the API
-        };
         // Replace keyword markers if necessary
         const clientNameNonMarker = (0, keywordPreservation_1.doesHaveKeywordMarker)(clientName, context.mappings)
             ? (0, tools_1.keywordReplace)(clientName, context.mappings)
@@ -76,14 +66,78 @@ async function dump(context) {
         const apiAudienceNonMarker = (0, keywordPreservation_1.doesHaveKeywordMarker)(grant.audience, context.mappings)
             ? (0, tools_1.keywordReplace)(grant.audience, context.mappings)
             : grant.audience;
-        // Construct the name using non-marker names
-        const name = (0, utils_1.sanitize)(`${clientNameNonMarker}-${apiName(apiAudienceNonMarker)}`);
+        // Construct the name using non-marker names. `subject_type` is part of a grant's identity
+        // (see `identifiers` in src/tools/auth0/handlers/clientGrants.ts), so it must be included:
+        // without it, grants differing only by subject type (e.g. `client` vs `user` on the same
+        // client and audience) resolve to the same filename and silently overwrite each other.
+        const baseName = `${clientNameNonMarker}-${apiName(apiAudienceNonMarker)}`;
+        return (0, utils_1.sanitize)(grant.subject_type ? `${baseName}-${grant.subject_type}` : baseName);
+    };
+    const excludedClients = allClients.filter((c) => c.name !== undefined && excludedClientsByNames.includes(c.name));
+    // Values that can stand for an excluded client in the `client_id` field of a dumped file: the
+    // client name when `clientsOrig` was available at dump time (see `convertClientIdToName` below),
+    // the raw client_id otherwise. Names come from the exclude list rather than from `allClients` so
+    // that excluding a client absent from the tenant still protects its file.
+    const excludedClientIdentities = new Set([
+        ...excludedClientsByNames,
+        ...excludedClients.map((c) => c.client_id).filter((id) => !!id),
+    ]);
+    // Whether a file this dump did not write must nonetheless survive the cleanup pass. Its name
+    // cannot answer that: the name is derived from the client name, the API name, the grant's
+    // subject_type and the current naming format, so a file written by an earlier version — or
+    // before its API was renamed — no longer matches the name `nameFor` produces today. Read the
+    // file instead, because the client identity recorded inside it does not drift.
+    const mustPreserve = (file) => {
+        if (excludedClientIdentities.size === 0)
+            return false;
+        let grant;
+        try {
+            grant = (0, utils_1.loadJSON)(file, {
+                mappings: context.mappings,
+                disableKeywordReplacement: context.disableKeywordReplacement,
+            });
+        }
+        catch (err) {
+            // Deleting a file it cannot read is not the export's call to make, and one bad file must not
+            // fail the whole export. Keep it and let `parse` report the problem on the next import.
+            logger_1.default.warn(`Keeping ${file}, it could not be read while cleaning up client grants: ${err}`);
+            return true;
+        }
+        return excludedClientIdentities.has(grant?.client_id);
+    };
+    // Track files written by this dump; everything else in the folder is a cleanup candidate.
+    const expectedFiles = new Set();
+    // Filter out grants for excluded clients
+    if (excludedClientsByNames.length) {
+        const excludedClientIds = new Set(excludedClients.map((c) => c.client_id));
+        clientGrants = clientGrants.filter((grant) => !excludedClientIds.has(grant.client_id));
+    }
+    // Convert client_id to the client name for readability
+    clientGrants.forEach((grant) => {
+        const dumpGrant = { ...grant };
+        if (context.assets.clientsOrig) {
+            dumpGrant.client_id = (0, utils_1.convertClientIdToName)(dumpGrant.client_id, context.assets.clientsOrig);
+        }
+        const name = nameFor(grant);
         // Ensure the name is not empty or invalid
         if (!name || name.trim().length === 0) {
             throw new Error(`Invalid name generated for client grant: ${JSON.stringify(grant)}`);
         }
         const grantFile = path_1.default.join(grantsFolder, `${name}.json`);
         (0, utils_1.dumpJSON)(grantFile, dumpGrant);
+        expectedFiles.add(`${name}.json`);
+    });
+    // Remove files that belong to grants no longer present (and not excluded). Without this, a grant
+    // whose filename changes is left behind under its old name and parsed back as a duplicate on the
+    // next import, and grants deleted from the tenant are silently recreated.
+    //
+    // Restricted to the `.json` files `parse` reads: anything else in the folder (a README, notes)
+    // can never come back as a grant, so it is not stale state and must not be deleted.
+    (0, utils_1.getFiles)(grantsFolder, ['.json'])
+        .filter((file) => !expectedFiles.has(path_1.default.basename(file)) && !mustPreserve(file))
+        .forEach((file) => {
+        logger_1.default.info(`Removing ${file}`);
+        fs_extra_1.default.removeSync(file);
     });
 }
 const clientGrantsHandler = {

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

@@ -20,9 +20,11 @@ function parse(context) {
             disableKeywordReplacement: context.disableKeywordReplacement,
         });
         if (client.custom_login_page) {
-            const htmlFileName = path_1.default.join(clientsFolder, client.custom_login_page);
-            if ((0, utils_1.isFile)(htmlFileName)) {
-                client.custom_login_page = (0, tools_1.loadFileAndReplaceKeywords)(htmlFileName, {
+            const configRoot = path_1.default.resolve(context.filePath);
+            const resolvedLoginPage = path_1.default.resolve(clientsFolder, client.custom_login_page);
+            if ((0, utils_1.isFile)(resolvedLoginPage)) {
+                (0, utils_1.assertInsideConfigRoot)(client.custom_login_page, resolvedLoginPage, configRoot);
+                client.custom_login_page = (0, tools_1.loadFileAndReplaceKeywords)(resolvedLoginPage, {
                     mappings: context.mappings,
                     disableKeywordReplacement: context.disableKeywordReplacement,
                 });
@@ -106,6 +108,21 @@ async function dump(context) {
                 organization_require_behavior: client.organization_require_behavior,
             };
         }
+        else {
+            // strip id-only credentials and remove client_authentication_methods entirely
+            // if no named credentials remain — an absent field is treated as deletion on deploy
+            if (client.client_authentication_methods) {
+                Object.values(client.client_authentication_methods).forEach((method) => {
+                    if (method?.credentials) {
+                        method.credentials = method.credentials.filter((c) => c.name);
+                    }
+                });
+                const hasAnyCredentials = Object.values(client.client_authentication_methods).some((method) => method?.credentials?.length > 0);
+                if (!hasAnyCredentials) {
+                    delete client.client_authentication_methods;
+                }
+            }
+        }
         (0, utils_1.dumpJSON)(clientFile, (0, utils_1.clearClientArrays)(client));
     });
 }

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

@@ -23,11 +23,13 @@ function parse(context) {
         });
         if (connection.strategy === 'email') {
             (0, utils_1.ensureProp)(connection, 'options.email.body');
-            const htmlFileName = path_1.default.join(connectionsFolder, connection.options.email.body);
-            if (!(0, utils_1.isFile)(htmlFileName)) {
-                throw new Error(`Passwordless email template purportedly located at ${htmlFileName} does not exist for connection. Ensure the existence of this file to proceed with deployment.`);
+            const configRoot = path_1.default.resolve(context.filePath);
+            const resolvedHtmlFile = path_1.default.resolve(connectionsFolder, connection.options.email.body);
+            if (!(0, utils_1.isFile)(resolvedHtmlFile)) {
+                throw new Error(`Passwordless email template purportedly located at ${resolvedHtmlFile} does not exist for connection. Ensure the existence of this file to proceed with deployment.`);
             }
-            connection.options.email.body = (0, tools_1.loadFileAndReplaceKeywords)(htmlFileName, {
+            (0, utils_1.assertInsideConfigRoot)(connection.options.email.body, resolvedHtmlFile, configRoot);
+            connection.options.email.body = (0, tools_1.loadFileAndReplaceKeywords)(resolvedHtmlFile, {
                 mappings: context.mappings,
                 disableKeywordReplacement: context.disableKeywordReplacement,
             });
@@ -49,6 +51,11 @@ async function dump(context) {
     if (excludedConnections.length) {
         connections = connections.filter((connection) => !excludedConnections.includes(connection.name));
     }
+    // Filter to included connections
+    const includedConnections = (context.assets.include && context.assets.include.connections) || [];
+    if (includedConnections.length) {
+        connections = connections.filter((connection) => includedConnections.includes(connection.name));
+    }
     const connectionsFolder = path_1.default.join(context.filePath, tools_1.constants.CONNECTIONS_DIRECTORY);
     fs_extra_1.default.ensureDirSync(connectionsFolder);
     // Track files that should remain after dump (written + excluded).
@@ -93,11 +100,18 @@ async function dump(context) {
         if (dumpedConnection.strategy === 'email')
             expectedFiles.add(`${connectionName}.html`);
     });
+    // With an include list configured, connections outside it are unmanaged, so limit pruning
+    // to the listed names rather than every file in the folder.
+    const prunableFiles = includedConnections.length
+        ? new Set(includedConnections.flatMap((name) => [`${(0, utils_1.sanitize)(name)}.json`, `${(0, utils_1.sanitize)(name)}.html`]))
+        : null;
     // Remove files that belong to connections no longer present (and not excluded)
     if (fs_extra_1.default.existsSync(connectionsFolder)) {
         for (const existing of fs_extra_1.default.readdirSync(connectionsFolder)) {
             const fullPath = path_1.default.join(connectionsFolder, existing);
-            if (fs_extra_1.default.statSync(fullPath).isFile() && !expectedFiles.has(existing)) {
+            if (fs_extra_1.default.statSync(fullPath).isFile() &&
+                !expectedFiles.has(existing) &&
+                (prunableFiles === null || prunableFiles.has(existing))) {
                 fs_extra_1.default.removeSync(fullPath);
             }
         }

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

@@ -42,10 +42,7 @@ function getDatabase(folder, configRoot, mappingOpts) {
             else {
                 const resolvedBase = path_1.default.resolve(configRoot);
                 const toLoad = path_1.default.resolve(folder, script.replace(/\\/g, '/'));
-                if (!toLoad.startsWith(resolvedBase + path_1.default.sep)) {
-                    throw new Error(`Path "${script}" resolves to "${toLoad}" which is outside the config directory "${resolvedBase}". ` +
-                        `Move the file inside your config directory.`);
-                }
+                (0, utils_1.assertInsideConfigRoot)(script, toLoad, resolvedBase);
                 database.options.customScripts[name] = (0, tools_1.loadFileAndReplaceKeywords)(toLoad, mappingOpts);
             }
         });