Add credential grouping to prevent mixing creds from different sources

OAuth (clientId/clientSecret) and Basic auth (username/password) credentials
are now treated as atomic groups. If any field in a group is set by a
higher-priority source, all fields in that group from lower-priority sources
are skipped. This prevents accidentally mixing credentials that don't belong
together.

Author: clavery

docs/guide/configuration.md

@@ -161,6 +161,20 @@ Configuration is resolved with the following precedence (highest to lowest):
 Plugins can add custom configuration sources like secret managers or environment-specific files. See [Extending the CLI](./extending) for details.
 :::
 
+### Credential Grouping
+
+To prevent mixing credentials from different sources, certain fields are treated as atomic groups:
+
+- **OAuth**: `clientId` and `clientSecret`
+- **Basic Auth**: `username` and `password`
+
+If any field in a group is set by a higher-priority source, all fields in that group from lower-priority sources are ignored. This ensures credential pairs always come from the same source.
+
+**Example:**
+- dw.json provides `clientId` only
+- A plugin provides `clientSecret`
+- Result: Only `clientId` is used; the plugin's `clientSecret` is ignored to prevent mismatched credentials
+
 ::: warning Hostname Mismatch Protection
 When you explicitly specify a hostname that differs from the `dw.json` hostname, the CLI ignores all other values from `dw.json` and only uses your explicit overrides. This prevents accidentally using credentials from one instance with a different server.
 :::

docs/guide/extending.md

@@ -56,6 +56,10 @@ Configuration is resolved with the following precedence:
 
 Each source fills in missing values - it doesn't override values from higher-priority sources.
 
+::: warning Credential Grouping
+OAuth credentials (`clientId`/`clientSecret`) and Basic auth credentials (`username`/`password`) are treated as atomic groups. If any field in a group is already set by a higher-priority source, all fields in that group from your source will be ignored. Ensure your source provides complete credential pairs, or that higher-priority sources don't partially define the same credentials.
+:::
+
 ### Example: Custom Config Source Plugin
 
 The SDK includes an example plugin that loads configuration from `.env.b2c` files:

packages/b2c-tooling-sdk/src/config/resolver.ts

@@ -25,6 +25,50 @@ import type {
 } from './types.js';
 import {ResolvedConfigImpl} from './resolved-config.js';
 
+/**
+ * Credential groups that must come from the same source.
+ *
+ * When merging configuration, if any field in a group is already set by a
+ * higher-priority source, all fields in that group from lower-priority
+ * sources are skipped. This prevents mixing credentials that don't belong together.
+ */
+const CREDENTIAL_GROUPS: (keyof NormalizedConfig)[][] = [
+  ['clientId', 'clientSecret'],
+  ['username', 'password'],
+];
+
+/**
+ * Get the set of credential groups that are already claimed in the config.
+ *
+ * A group is "claimed" if any of its fields are set.
+ *
+ * @param config - The current configuration
+ * @returns Set of group indices that are claimed
+ */
+function getClaimedCredentialGroups(config: NormalizedConfig): Set<number> {
+  const claimed = new Set<number>();
+  for (let i = 0; i < CREDENTIAL_GROUPS.length; i++) {
+    const group = CREDENTIAL_GROUPS[i];
+    if (group.some((f) => config[f] !== undefined)) {
+      claimed.add(i);
+    }
+  }
+  return claimed;
+}
+
+/**
+ * Check if a field belongs to a credential group in the claimed set.
+ *
+ * @param field - The field name to check
+ * @param claimedGroups - Set of group indices that are already claimed
+ * @returns true if the field's credential group is claimed
+ */
+function isFieldInClaimedGroup(field: string, claimedGroups: Set<number>): boolean {
+  const groupIndex = CREDENTIAL_GROUPS.findIndex((g) => g.includes(field as keyof NormalizedConfig));
+  if (groupIndex === -1) return false;
+  return claimedGroups.has(groupIndex);
+}
+
 /**
  * Resolves configuration from multiple sources with consistent behavior.
  *
@@ -123,11 +167,22 @@ export class ConfigResolver {
             fieldsContributed,
           });
 
+          // Capture which credential groups are already claimed BEFORE processing this source
+          // This allows a single source to provide complete credential pairs
+          const claimedGroups = getClaimedCredentialGroups(baseConfig);
+
           // Merge: source values fill in gaps (don't override existing values)
           for (const [key, value] of Object.entries(sourceConfig)) {
-            if (value !== undefined && baseConfig[key as keyof NormalizedConfig] === undefined) {
-              (baseConfig as Record<string, unknown>)[key] = value;
+            if (value === undefined) continue;
+            if (baseConfig[key as keyof NormalizedConfig] !== undefined) continue;
+
+            // Skip if this field's credential group was already claimed by a higher-priority source
+            // This prevents mixing credentials from different sources
+            if (isFieldInClaimedGroup(key, claimedGroups)) {
+              continue;
             }
+
+            (baseConfig as Record<string, unknown>)[key] = value;
           }
         }
       }

packages/b2c-tooling-sdk/test/config/resolver.test.ts

@@ -171,6 +171,109 @@ describe('config/resolver', () => {
       });
     });
 
+    describe('credential grouping', () => {
+      it('does not mix clientId and clientSecret from different sources', () => {
+        const source1 = new MockSource('first', {clientId: 'first-client'});
+        const source2 = new MockSource('second', {clientSecret: 'second-secret'});
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        expect(config.clientId).to.equal('first-client');
+        expect(config.clientSecret).to.be.undefined; // Not mixed from source2
+      });
+
+      it('does not mix username and password from different sources', () => {
+        const source1 = new MockSource('first', {username: 'user1'});
+        const source2 = new MockSource('second', {password: 'pass2'});
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        expect(config.username).to.equal('user1');
+        expect(config.password).to.be.undefined; // Not mixed from source2
+      });
+
+      it('allows complete credential pairs from same source', () => {
+        const source1 = new MockSource('first', {hostname: 'example.com'});
+        const source2 = new MockSource('second', {
+          clientId: 'client',
+          clientSecret: 'secret',
+        });
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        expect(config.hostname).to.equal('example.com');
+        expect(config.clientId).to.equal('client');
+        expect(config.clientSecret).to.equal('secret');
+      });
+
+      it('allows non-grouped fields to merge normally', () => {
+        const source1 = new MockSource('first', {clientId: 'client'});
+        const source2 = new MockSource('second', {
+          hostname: 'example.com',
+          codeVersion: 'v1',
+        });
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        expect(config.clientId).to.equal('client');
+        expect(config.hostname).to.equal('example.com');
+        expect(config.codeVersion).to.equal('v1');
+      });
+
+      it('blocks both oauth fields when clientId is claimed', () => {
+        const source1 = new MockSource('first', {clientId: 'first-client'});
+        const source2 = new MockSource('second', {
+          clientId: 'second-client',
+          clientSecret: 'second-secret',
+        });
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        expect(config.clientId).to.equal('first-client');
+        expect(config.clientSecret).to.be.undefined; // Blocked due to group claim
+      });
+
+      it('blocks both basic auth fields when username is claimed', () => {
+        const source1 = new MockSource('first', {username: 'first-user'});
+        const source2 = new MockSource('second', {
+          username: 'second-user',
+          password: 'second-pass',
+        });
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        expect(config.username).to.equal('first-user');
+        expect(config.password).to.be.undefined; // Blocked due to group claim
+      });
+
+      it('allows independent credential groups to come from different sources', () => {
+        const source1 = new MockSource('first', {
+          clientId: 'oauth-client',
+          clientSecret: 'oauth-secret',
+        });
+        const source2 = new MockSource('second', {
+          username: 'basic-user',
+          password: 'basic-pass',
+        });
+        const resolver = new ConfigResolver([source1, source2]);
+
+        const {config} = resolver.resolve();
+
+        // OAuth from source1
+        expect(config.clientId).to.equal('oauth-client');
+        expect(config.clientSecret).to.equal('oauth-secret');
+        // Basic from source2
+        expect(config.username).to.equal('basic-user');
+        expect(config.password).to.equal('basic-pass');
+      });
+    });
+
     describe('createAuthCredentials', () => {
       it('creates auth credentials from resolved config', () => {
         const source = new MockSource('test', {