@postman-cse/onboarding-repo-sync 2.3.0 → 2.4.0

package/README.md

@@ -113,7 +113,17 @@ with:
   monitor-id: 1e2f3a4b-monitor-id
 ```
 
-Repo-sync defaults to public mocks for anonymous validation. Set `mock-visibility: private` for teams that prohibit public mocks. Explicit, discovered, and newly created mocks must match the requested visibility and the expected baseline collection/environment; unknown visibility, stale URLs, and identity mismatches fail before `mock-url` is emitted. For private mocks, repo-sync emits `mock-auth-required: true` and installs a secret-free request hook in the smoke and contract collections. The runner must supply its PMAK as the transient `postmanPrivateMockApiKey` variable. Repo-sync never writes that credential to a collection, environment, output, or repository artifact.
+Repo-sync defaults to public mocks for anonymous validation. Set `mock-visibility: private` for teams that prohibit public mocks. Explicit, discovered, and newly created mocks must match the requested visibility and the expected baseline collection/environment; unknown visibility, stale URLs, and identity mismatches fail before `mock-url` is emitted.
+
+For private mocks, repo-sync emits `mock-auth-required: true` and installs a secret-free request hook in the smoke and contract collections. The hook reads the transient `postmanPrivateMockApiKey` variable and sends it as `x-api-key`, and only to `*.mock.pstmn.io` hosts, so it stays inert on runs that target a real environment. Repo-sync never writes that credential to a collection, environment, output, or repository artifact.
+
+Where that variable comes from depends on who is running the collection:
+
+- **Generated CI** supplies it automatically from the `POSTMAN_API_KEY` secret repo-sync already provisions for `postman login`. No extra secret and no workflow edit.
+- **Manual runs in the Postman app** use the `<project> - Mock` environment, which carries `postmanPrivateMockApiKey` as an empty secret-typed variable. Paste a key with access to the mock. Requires `mock-environment-enabled: true`.
+- **A runner you wire yourself** reads `mock-auth-required` and passes the variable however that system handles secrets.
+
+A request to a private mock with no key set logs a console warning naming the variable, so a `401` explains its own fix.
 
 For manual collection validation against the resolved mock, opt in to a dedicated Postman environment:
 

package/dist/action.cjs

@@ -134252,6 +134252,7 @@ function resolvePostmanEndpointProfile(stack, region = "us") {
 // src/lib/ci-workflow-template.ts
 var DEFAULT_POSTMAN_CLI_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliInstallUrl;
 var DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliWindowsInstallUrl;
+var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
 function validateHttpsInstallUrl(url) {
   const safeUrlPattern = /^https:\/\/[A-Za-z0-9.-]+\/[A-Za-z0-9._~/?=&%-]+$/;
   if (!safeUrlPattern.test(url)) {
@@ -134283,9 +134284,9 @@ function renderCiWorkflowTemplate(options = {}) {
   const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
   const installUrl = validateHttpsInstallUrl(rawUrl);
   const postmanRegion = resolvePostmanRegion(options.postmanRegion);
-  return buildCiWorkflowLines(installUrl, postmanRegion).join("\n");
+  return buildCiWorkflowLines(installUrl, postmanRegion, options.privateMockAuth === true).join("\n");
 }
-function buildCiWorkflowLines(installUrl, postmanRegion) {
+function buildCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "name: CI/CD Pipeline",
     "on:",
@@ -134352,6 +134353,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     '            -e "$POSTMAN_ENVIRONMENT_UID"',
     "            --report-events",
     `            --env-var "CI_ENVIRONMENT=\${{ vars.CI_ENVIRONMENT || 'Production' }}")`,
+    ...privateMockAuth ? ['            CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=${{ secrets.POSTMAN_API_KEY }}")'] : [],
     '          if [ -f "$RUNNER_TEMP/postman-ssl/client.crt" ]; then',
     '            CMD+=(--ssl-client-cert "$RUNNER_TEMP/postman-ssl/client.crt"',
     '              --ssl-client-key "$RUNNER_TEMP/postman-ssl/client.key")',
@@ -134371,6 +134373,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     '            -e "$POSTMAN_ENVIRONMENT_UID"',
     "            --report-events",
     `            --env-var "CI_ENVIRONMENT=\${{ vars.CI_ENVIRONMENT || 'Production' }}")`,
+    ...privateMockAuth ? ['            CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=${{ secrets.POSTMAN_API_KEY }}")'] : [],
     '          if [ -f "$RUNNER_TEMP/postman-ssl/client.crt" ]; then',
     '            CMD+=(--ssl-client-cert "$RUNNER_TEMP/postman-ssl/client.crt"',
     '              --ssl-client-key "$RUNNER_TEMP/postman-ssl/client.key")',
@@ -134386,7 +134389,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
   ];
 }
 var CI_WORKFLOW_TEMPLATE = renderCiWorkflowTemplate();
-function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName) {
+function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName, privateMockAuth) {
   return [
     "  - pwsh: |",
     "      $ErrorActionPreference = 'Stop'",
@@ -134398,6 +134401,7 @@ function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentNam
     "      $ciEnvironment = Resolve-AdoOptional $env:CI_ENVIRONMENT",
     "      if ([string]::IsNullOrWhiteSpace($ciEnvironment)) { $ciEnvironment = 'Production' }",
     `      $arguments = @('collection', 'run', $collectionUid, '-e', $env:POSTMAN_ENVIRONMENT_UID, '--report-events', '--env-var', "CI_ENVIRONMENT=$ciEnvironment")`,
+    ...privateMockAuth ? [`      $arguments += @('--env-var', "${PRIVATE_MOCK_AUTH_VARIABLE}=$env:POSTMAN_API_KEY")`] : [],
     "      $sslRoot = Join-Path $env:AGENT_TEMPDIRECTORY 'postman-ssl'",
     "      $clientCert = Join-Path $sslRoot 'client.crt'",
     "      $clientKey = Join-Path $sslRoot 'client.key'",
@@ -134419,10 +134423,11 @@ function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentNam
     `      ${collectionEnvironmentName}: $(${collectionEnvironmentName})`,
     "      POSTMAN_ENVIRONMENT_UID: $(POSTMAN_ENVIRONMENT_UID)",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
-    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)"
+    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : []
   ];
 }
-function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
+function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "trigger:",
     "  branches:",
@@ -134507,12 +134512,12 @@ function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
     "      POSTMAN_SSL_CLIENT_CERT_B64: $(POSTMAN_SSL_CLIENT_CERT_B64)",
     "      POSTMAN_SSL_CLIENT_KEY_B64: $(POSTMAN_SSL_CLIENT_KEY_B64)",
     "      POSTMAN_SSL_EXTRA_CA_CERTS_B64: $(POSTMAN_SSL_EXTRA_CA_CERTS_B64)",
-    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID"),
-    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID"),
+    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID", privateMockAuth),
+    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID", privateMockAuth),
     ""
   ];
 }
-function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
+function buildAdoCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "trigger:",
     "  branches:",
@@ -134589,6 +134594,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     '        -e "$POSTMAN_ENVIRONMENT_UID"',
     "        --report-events",
     '        --env-var "CI_ENVIRONMENT=${CI_ENVIRONMENT:-Production}")',
+    ...privateMockAuth ? ['        CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=$POSTMAN_API_KEY")'] : [],
     '      if [ -f "$(Agent.TempDirectory)/postman-ssl/client.crt" ]; then',
     '        CMD+=(--ssl-client-cert "$(Agent.TempDirectory)/postman-ssl/client.crt"',
     '          --ssl-client-key "$(Agent.TempDirectory)/postman-ssl/client.key")',
@@ -134604,6 +134610,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     "    env:",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
     "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : [],
     "  - script: |",
     "      normalize_azure_optional_var() {",
     '        local name="$1"',
@@ -134620,6 +134627,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     '        -e "$POSTMAN_ENVIRONMENT_UID"',
     "        --report-events",
     '        --env-var "CI_ENVIRONMENT=${CI_ENVIRONMENT:-Production}")',
+    ...privateMockAuth ? ['        CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=$POSTMAN_API_KEY")'] : [],
     '      if [ -f "$(Agent.TempDirectory)/postman-ssl/client.crt" ]; then',
     '        CMD+=(--ssl-client-cert "$(Agent.TempDirectory)/postman-ssl/client.crt"',
     '          --ssl-client-key "$(Agent.TempDirectory)/postman-ssl/client.key")',
@@ -134635,6 +134643,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     "    env:",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
     "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : [],
     ""
   ];
 }
@@ -134696,7 +134705,8 @@ function getCiWorkflowTemplate(provider, options = {}) {
     const rawUrl = runnerOs === "windows" ? String(options.postmanCliWindowsInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL : String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
     const postmanRegion = resolvePostmanRegion(options.postmanRegion);
     const installUrl = validateHttpsInstallUrl(rawUrl);
-    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) : buildAdoCiWorkflowLines(installUrl, postmanRegion)).join("\n");
+    const privateMockAuth = options.privateMockAuth === true;
+    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) : buildAdoCiWorkflowLines(installUrl, postmanRegion, privateMockAuth)).join("\n");
   }
   return renderCiWorkflowTemplate(options);
 }
@@ -136984,16 +136994,39 @@ function requireMockVisibility(mock, requested) {
   }
   return mock;
 }
-var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
-var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
+var PRIVATE_MOCK_AUTH_MARKER_PREFIX = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_MARKER = `${PRIVATE_MOCK_AUTH_MARKER_PREFIX}-v2`;
+var PRIVATE_MOCK_AUTH_VARIABLE2 = "postmanPrivateMockApiKey";
 var PRIVATE_MOCK_AUTH_SCRIPT = [
   `// ${PRIVATE_MOCK_AUTH_MARKER}`,
-  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE}');`,
-  "var privateMockHost = String(pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '');",
-  "if (privateMockApiKey && /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost)) {",
+  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE2}');`,
+  "var privateMockHostValue = pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '';",
+  "var privateMockHost = Array.isArray(privateMockHostValue) ? privateMockHostValue.join('.') : String(privateMockHostValue);",
+  "var isPrivateMockHost = /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost);",
+  "if (isPrivateMockHost && privateMockApiKey) {",
   "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "} else if (isPrivateMockHost) {",
+  `  console.warn('This mock server is private. Set the ${PRIVATE_MOCK_AUTH_VARIABLE2} variable to a Postman API key with access to it, or the request returns 401.');`,
   "}"
 ].join("\n");
+function stripPrivateMockAuthBlocks(code) {
+  if (!code.includes(PRIVATE_MOCK_AUTH_MARKER_PREFIX)) return code.trim();
+  const lines = code.split("\n");
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (line.includes(PRIVATE_MOCK_AUTH_MARKER_PREFIX)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping) {
+      if (/^\s*(?:(?:var|if)\s|\}\selse\sif\s|\}|pm\.request|console\.warn)/.test(line)) continue;
+      skipping = false;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n").trim();
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137591,8 +137624,9 @@ var PostmanGatewayAssetsClient = class {
       const item = this.asRecord(response?.data) ?? listedItem;
       const scripts = Array.isArray(item.scripts) ? item.scripts.filter((entry) => Boolean(this.asRecord(entry))) : [];
       const before = scripts.find((script) => String(script.type ?? "") === "beforeRequest");
-      if (String(before?.code ?? "").includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
-      const code = [String(before?.code ?? "").trim(), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
+      const existingCode = String(before?.code ?? "");
+      if (existingCode.includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
+      const code = [stripPrivateMockAuthBlocks(existingCode), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
       const nextScripts = [
         ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
         { type: "beforeRequest", code, language: "text/javascript" }
@@ -138928,9 +138962,13 @@ function assertBranchAssetIds(inputs, decision, branchOwnedIds = process.env.POS
     );
   }
 }
-function buildEnvironmentValues(envName, baseUrl) {
+function buildEnvironmentValues(envName, baseUrl, options = {}) {
   return [
     { key: "baseUrl", value: baseUrl, type: "default" },
+    // A private mock refuses anonymous calls, so the manual-validation environment
+    // carries a named, empty, secret-typed slot for the caller's own key. Repo-sync
+    // never writes a value here; the developer pastes one in the Postman app.
+    ...options.privateMockAuth ? [{ key: PRIVATE_MOCK_AUTH_VARIABLE2, value: "", type: "secret" }] : [],
     { key: "CI", value: "false", type: "default" },
     { key: "RESPONSE_TIME_THRESHOLD", value: "2000", type: "default" },
     { key: "AWS_ACCESS_KEY_ID", value: "", type: "secret" },
@@ -139377,12 +139415,12 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
   }
   return envUids;
 }
-async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl) {
+async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl, privateMockAuth) {
   if (!inputs.mockEnvironmentEnabled || !inputs.workspaceId || !mockUrl) {
     return "";
   }
   const displayName = `${assetProjectName} - Mock`;
-  const values = buildEnvironmentValues("mock", mockUrl);
+  const values = buildEnvironmentValues("mock", mockUrl, { privateMockAuth });
   const mask = resolveRepoSyncMasker(dependencies);
   try {
     const discovered = await dependencies.postman.findEnvironmentByName(
@@ -140111,14 +140149,16 @@ function renderCiWorkflow(inputs) {
       postmanCliInstallUrl: inputs.postmanCliInstallUrl,
       postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
       runnerOs: inputs.ciRunnerOs,
-      postmanRegion: inputs.postmanRegion
+      postmanRegion: inputs.postmanRegion,
+      privateMockAuth: inputs.mockVisibility === "private"
     });
   }
   return renderCiWorkflowTemplate({
     postmanCliInstallUrl: inputs.postmanCliInstallUrl,
     postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
     runnerOs: inputs.ciRunnerOs,
-    postmanRegion: inputs.postmanRegion
+    postmanRegion: inputs.postmanRegion,
+    privateMockAuth: inputs.mockVisibility === "private"
   });
 }
 function createRepoSummary(outputs, envUids, pushed) {
@@ -140473,18 +140513,26 @@ async function runRepoSyncInner(inputs, dependencies) {
             "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
           );
         }
+        const configured = [];
         for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
           if (collectionUid) {
             await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+            configured.push(collectionUid);
           }
         }
+        if (configured.length > 0) {
+          (dependencies.core.notice ?? dependencies.core.info)(
+            `Private mock: installed a request hook on ${configured.length} collection(s) that sends the ${PRIVATE_MOCK_AUTH_VARIABLE2} variable as x-api-key, and only to *.mock.pstmn.io hosts. The generated CI workflow supplies it from the POSTMAN_API_KEY secret. For manual runs in the Postman app, set that variable to a key with access to the mock. No key is stored in the collection, environment, outputs, or repository.`
+          );
+        }
       }
       if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
         const mockEnvironmentUid = await upsertMockEnvironment(
           inputs,
           dependencies,
           assetProjectName,
-          resolvedMockUrl
+          resolvedMockUrl,
+          resolvedMockVisibility === "private"
         );
         outputs["mock-environment-uid"] = mockEnvironmentUid;
         outputs["mock-environment-status"] = mockEnvironmentUid ? "success" : "failed";
@@ -140950,6 +140998,7 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     // uid (the gateway services key access off it, exactly like the public REST
     // API); the bare model id 403s "request access from the collection editor".
     createMock: gatewayAssets.createMock.bind(gatewayAssets),
+    configurePrivateMockRuntimeAuth: gatewayAssets.configurePrivateMockRuntimeAuth.bind(gatewayAssets),
     listMocks: gatewayAssets.listMocks.bind(gatewayAssets),
     mockExists: gatewayAssets.mockExists.bind(gatewayAssets),
     findMockByCollection: gatewayAssets.findMockByCollection.bind(gatewayAssets),

package/dist/cli.cjs

@@ -132357,6 +132357,7 @@ function resolvePostmanEndpointProfile(stack, region = "us") {
 // src/lib/ci-workflow-template.ts
 var DEFAULT_POSTMAN_CLI_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliInstallUrl;
 var DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliWindowsInstallUrl;
+var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
 function validateHttpsInstallUrl(url) {
   const safeUrlPattern = /^https:\/\/[A-Za-z0-9.-]+\/[A-Za-z0-9._~/?=&%-]+$/;
   if (!safeUrlPattern.test(url)) {
@@ -132388,9 +132389,9 @@ function renderCiWorkflowTemplate(options = {}) {
   const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
   const installUrl = validateHttpsInstallUrl(rawUrl);
   const postmanRegion = resolvePostmanRegion(options.postmanRegion);
-  return buildCiWorkflowLines(installUrl, postmanRegion).join("\n");
+  return buildCiWorkflowLines(installUrl, postmanRegion, options.privateMockAuth === true).join("\n");
 }
-function buildCiWorkflowLines(installUrl, postmanRegion) {
+function buildCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "name: CI/CD Pipeline",
     "on:",
@@ -132457,6 +132458,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     '            -e "$POSTMAN_ENVIRONMENT_UID"',
     "            --report-events",
     `            --env-var "CI_ENVIRONMENT=\${{ vars.CI_ENVIRONMENT || 'Production' }}")`,
+    ...privateMockAuth ? ['            CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=${{ secrets.POSTMAN_API_KEY }}")'] : [],
     '          if [ -f "$RUNNER_TEMP/postman-ssl/client.crt" ]; then',
     '            CMD+=(--ssl-client-cert "$RUNNER_TEMP/postman-ssl/client.crt"',
     '              --ssl-client-key "$RUNNER_TEMP/postman-ssl/client.key")',
@@ -132476,6 +132478,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     '            -e "$POSTMAN_ENVIRONMENT_UID"',
     "            --report-events",
     `            --env-var "CI_ENVIRONMENT=\${{ vars.CI_ENVIRONMENT || 'Production' }}")`,
+    ...privateMockAuth ? ['            CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=${{ secrets.POSTMAN_API_KEY }}")'] : [],
     '          if [ -f "$RUNNER_TEMP/postman-ssl/client.crt" ]; then',
     '            CMD+=(--ssl-client-cert "$RUNNER_TEMP/postman-ssl/client.crt"',
     '              --ssl-client-key "$RUNNER_TEMP/postman-ssl/client.key")',
@@ -132491,7 +132494,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
   ];
 }
 var CI_WORKFLOW_TEMPLATE = renderCiWorkflowTemplate();
-function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName) {
+function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName, privateMockAuth) {
   return [
     "  - pwsh: |",
     "      $ErrorActionPreference = 'Stop'",
@@ -132503,6 +132506,7 @@ function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentNam
     "      $ciEnvironment = Resolve-AdoOptional $env:CI_ENVIRONMENT",
     "      if ([string]::IsNullOrWhiteSpace($ciEnvironment)) { $ciEnvironment = 'Production' }",
     `      $arguments = @('collection', 'run', $collectionUid, '-e', $env:POSTMAN_ENVIRONMENT_UID, '--report-events', '--env-var', "CI_ENVIRONMENT=$ciEnvironment")`,
+    ...privateMockAuth ? [`      $arguments += @('--env-var', "${PRIVATE_MOCK_AUTH_VARIABLE}=$env:POSTMAN_API_KEY")`] : [],
     "      $sslRoot = Join-Path $env:AGENT_TEMPDIRECTORY 'postman-ssl'",
     "      $clientCert = Join-Path $sslRoot 'client.crt'",
     "      $clientKey = Join-Path $sslRoot 'client.key'",
@@ -132524,10 +132528,11 @@ function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentNam
     `      ${collectionEnvironmentName}: $(${collectionEnvironmentName})`,
     "      POSTMAN_ENVIRONMENT_UID: $(POSTMAN_ENVIRONMENT_UID)",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
-    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)"
+    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : []
   ];
 }
-function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
+function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "trigger:",
     "  branches:",
@@ -132612,12 +132617,12 @@ function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
     "      POSTMAN_SSL_CLIENT_CERT_B64: $(POSTMAN_SSL_CLIENT_CERT_B64)",
     "      POSTMAN_SSL_CLIENT_KEY_B64: $(POSTMAN_SSL_CLIENT_KEY_B64)",
     "      POSTMAN_SSL_EXTRA_CA_CERTS_B64: $(POSTMAN_SSL_EXTRA_CA_CERTS_B64)",
-    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID"),
-    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID"),
+    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID", privateMockAuth),
+    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID", privateMockAuth),
     ""
   ];
 }
-function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
+function buildAdoCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "trigger:",
     "  branches:",
@@ -132694,6 +132699,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     '        -e "$POSTMAN_ENVIRONMENT_UID"',
     "        --report-events",
     '        --env-var "CI_ENVIRONMENT=${CI_ENVIRONMENT:-Production}")',
+    ...privateMockAuth ? ['        CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=$POSTMAN_API_KEY")'] : [],
     '      if [ -f "$(Agent.TempDirectory)/postman-ssl/client.crt" ]; then',
     '        CMD+=(--ssl-client-cert "$(Agent.TempDirectory)/postman-ssl/client.crt"',
     '          --ssl-client-key "$(Agent.TempDirectory)/postman-ssl/client.key")',
@@ -132709,6 +132715,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     "    env:",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
     "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : [],
     "  - script: |",
     "      normalize_azure_optional_var() {",
     '        local name="$1"',
@@ -132725,6 +132732,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     '        -e "$POSTMAN_ENVIRONMENT_UID"',
     "        --report-events",
     '        --env-var "CI_ENVIRONMENT=${CI_ENVIRONMENT:-Production}")',
+    ...privateMockAuth ? ['        CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=$POSTMAN_API_KEY")'] : [],
     '      if [ -f "$(Agent.TempDirectory)/postman-ssl/client.crt" ]; then',
     '        CMD+=(--ssl-client-cert "$(Agent.TempDirectory)/postman-ssl/client.crt"',
     '          --ssl-client-key "$(Agent.TempDirectory)/postman-ssl/client.key")',
@@ -132740,6 +132748,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     "    env:",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
     "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : [],
     ""
   ];
 }
@@ -132801,7 +132810,8 @@ function getCiWorkflowTemplate(provider, options = {}) {
     const rawUrl = runnerOs === "windows" ? String(options.postmanCliWindowsInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL : String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
     const postmanRegion = resolvePostmanRegion(options.postmanRegion);
     const installUrl = validateHttpsInstallUrl(rawUrl);
-    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) : buildAdoCiWorkflowLines(installUrl, postmanRegion)).join("\n");
+    const privateMockAuth = options.privateMockAuth === true;
+    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) : buildAdoCiWorkflowLines(installUrl, postmanRegion, privateMockAuth)).join("\n");
   }
   return renderCiWorkflowTemplate(options);
 }
@@ -135089,16 +135099,39 @@ function requireMockVisibility(mock, requested) {
   }
   return mock;
 }
-var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
-var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
+var PRIVATE_MOCK_AUTH_MARKER_PREFIX = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_MARKER = `${PRIVATE_MOCK_AUTH_MARKER_PREFIX}-v2`;
+var PRIVATE_MOCK_AUTH_VARIABLE2 = "postmanPrivateMockApiKey";
 var PRIVATE_MOCK_AUTH_SCRIPT = [
   `// ${PRIVATE_MOCK_AUTH_MARKER}`,
-  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE}');`,
-  "var privateMockHost = String(pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '');",
-  "if (privateMockApiKey && /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost)) {",
+  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE2}');`,
+  "var privateMockHostValue = pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '';",
+  "var privateMockHost = Array.isArray(privateMockHostValue) ? privateMockHostValue.join('.') : String(privateMockHostValue);",
+  "var isPrivateMockHost = /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost);",
+  "if (isPrivateMockHost && privateMockApiKey) {",
   "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "} else if (isPrivateMockHost) {",
+  `  console.warn('This mock server is private. Set the ${PRIVATE_MOCK_AUTH_VARIABLE2} variable to a Postman API key with access to it, or the request returns 401.');`,
   "}"
 ].join("\n");
+function stripPrivateMockAuthBlocks(code) {
+  if (!code.includes(PRIVATE_MOCK_AUTH_MARKER_PREFIX)) return code.trim();
+  const lines = code.split("\n");
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (line.includes(PRIVATE_MOCK_AUTH_MARKER_PREFIX)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping) {
+      if (/^\s*(?:(?:var|if)\s|\}\selse\sif\s|\}|pm\.request|console\.warn)/.test(line)) continue;
+      skipping = false;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n").trim();
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -135696,8 +135729,9 @@ var PostmanGatewayAssetsClient = class {
       const item = this.asRecord(response?.data) ?? listedItem;
       const scripts = Array.isArray(item.scripts) ? item.scripts.filter((entry) => Boolean(this.asRecord(entry))) : [];
       const before = scripts.find((script) => String(script.type ?? "") === "beforeRequest");
-      if (String(before?.code ?? "").includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
-      const code = [String(before?.code ?? "").trim(), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
+      const existingCode = String(before?.code ?? "");
+      if (existingCode.includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
+      const code = [stripPrivateMockAuthBlocks(existingCode), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
       const nextScripts = [
         ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
         { type: "beforeRequest", code, language: "text/javascript" }
@@ -136978,9 +137012,13 @@ function assertBranchAssetIds(inputs, decision, branchOwnedIds = process.env.POS
     );
   }
 }
-function buildEnvironmentValues(envName, baseUrl) {
+function buildEnvironmentValues(envName, baseUrl, options = {}) {
   return [
     { key: "baseUrl", value: baseUrl, type: "default" },
+    // A private mock refuses anonymous calls, so the manual-validation environment
+    // carries a named, empty, secret-typed slot for the caller's own key. Repo-sync
+    // never writes a value here; the developer pastes one in the Postman app.
+    ...options.privateMockAuth ? [{ key: PRIVATE_MOCK_AUTH_VARIABLE2, value: "", type: "secret" }] : [],
     { key: "CI", value: "false", type: "default" },
     { key: "RESPONSE_TIME_THRESHOLD", value: "2000", type: "default" },
     { key: "AWS_ACCESS_KEY_ID", value: "", type: "secret" },
@@ -137285,12 +137323,12 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
   }
   return envUids;
 }
-async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl) {
+async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl, privateMockAuth) {
   if (!inputs.mockEnvironmentEnabled || !inputs.workspaceId || !mockUrl) {
     return "";
   }
   const displayName = `${assetProjectName} - Mock`;
-  const values = buildEnvironmentValues("mock", mockUrl);
+  const values = buildEnvironmentValues("mock", mockUrl, { privateMockAuth });
   const mask = resolveRepoSyncMasker(dependencies);
   try {
     const discovered = await dependencies.postman.findEnvironmentByName(
@@ -138019,14 +138057,16 @@ function renderCiWorkflow(inputs) {
       postmanCliInstallUrl: inputs.postmanCliInstallUrl,
       postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
       runnerOs: inputs.ciRunnerOs,
-      postmanRegion: inputs.postmanRegion
+      postmanRegion: inputs.postmanRegion,
+      privateMockAuth: inputs.mockVisibility === "private"
     });
   }
   return renderCiWorkflowTemplate({
     postmanCliInstallUrl: inputs.postmanCliInstallUrl,
     postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
     runnerOs: inputs.ciRunnerOs,
-    postmanRegion: inputs.postmanRegion
+    postmanRegion: inputs.postmanRegion,
+    privateMockAuth: inputs.mockVisibility === "private"
   });
 }
 function createRepoSummary(outputs, envUids, pushed) {
@@ -138381,18 +138421,26 @@ async function runRepoSyncInner(inputs, dependencies) {
             "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
           );
         }
+        const configured = [];
         for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
           if (collectionUid) {
             await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+            configured.push(collectionUid);
           }
         }
+        if (configured.length > 0) {
+          (dependencies.core.notice ?? dependencies.core.info)(
+            `Private mock: installed a request hook on ${configured.length} collection(s) that sends the ${PRIVATE_MOCK_AUTH_VARIABLE2} variable as x-api-key, and only to *.mock.pstmn.io hosts. The generated CI workflow supplies it from the POSTMAN_API_KEY secret. For manual runs in the Postman app, set that variable to a key with access to the mock. No key is stored in the collection, environment, outputs, or repository.`
+          );
+        }
       }
       if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
         const mockEnvironmentUid = await upsertMockEnvironment(
           inputs,
           dependencies,
           assetProjectName,
-          resolvedMockUrl
+          resolvedMockUrl,
+          resolvedMockVisibility === "private"
         );
         outputs["mock-environment-uid"] = mockEnvironmentUid;
         outputs["mock-environment-status"] = mockEnvironmentUid ? "success" : "failed";
@@ -138858,6 +138906,7 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     // uid (the gateway services key access off it, exactly like the public REST
     // API); the bare model id 403s "request access from the collection editor".
     createMock: gatewayAssets.createMock.bind(gatewayAssets),
+    configurePrivateMockRuntimeAuth: gatewayAssets.configurePrivateMockRuntimeAuth.bind(gatewayAssets),
     listMocks: gatewayAssets.listMocks.bind(gatewayAssets),
     mockExists: gatewayAssets.mockExists.bind(gatewayAssets),
     findMockByCollection: gatewayAssets.findMockByCollection.bind(gatewayAssets),
@@ -139400,6 +139449,9 @@ var ConsoleReporter = class {
   info(message) {
     console.error(message);
   }
+  notice(message) {
+    console.error(`notice: ${message}`);
+  }
   warning(message) {
     console.error(`warning: ${message}`);
   }

package/dist/index.cjs

@@ -134274,6 +134274,7 @@ function resolvePostmanEndpointProfile(stack, region = "us") {
 // src/lib/ci-workflow-template.ts
 var DEFAULT_POSTMAN_CLI_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliInstallUrl;
 var DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL = POSTMAN_ENDPOINT_PROFILES.prod.cliWindowsInstallUrl;
+var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
 function validateHttpsInstallUrl(url) {
   const safeUrlPattern = /^https:\/\/[A-Za-z0-9.-]+\/[A-Za-z0-9._~/?=&%-]+$/;
   if (!safeUrlPattern.test(url)) {
@@ -134305,9 +134306,9 @@ function renderCiWorkflowTemplate(options = {}) {
   const rawUrl = String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
   const installUrl = validateHttpsInstallUrl(rawUrl);
   const postmanRegion = resolvePostmanRegion(options.postmanRegion);
-  return buildCiWorkflowLines(installUrl, postmanRegion).join("\n");
+  return buildCiWorkflowLines(installUrl, postmanRegion, options.privateMockAuth === true).join("\n");
 }
-function buildCiWorkflowLines(installUrl, postmanRegion) {
+function buildCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "name: CI/CD Pipeline",
     "on:",
@@ -134374,6 +134375,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     '            -e "$POSTMAN_ENVIRONMENT_UID"',
     "            --report-events",
     `            --env-var "CI_ENVIRONMENT=\${{ vars.CI_ENVIRONMENT || 'Production' }}")`,
+    ...privateMockAuth ? ['            CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=${{ secrets.POSTMAN_API_KEY }}")'] : [],
     '          if [ -f "$RUNNER_TEMP/postman-ssl/client.crt" ]; then',
     '            CMD+=(--ssl-client-cert "$RUNNER_TEMP/postman-ssl/client.crt"',
     '              --ssl-client-key "$RUNNER_TEMP/postman-ssl/client.key")',
@@ -134393,6 +134395,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
     '            -e "$POSTMAN_ENVIRONMENT_UID"',
     "            --report-events",
     `            --env-var "CI_ENVIRONMENT=\${{ vars.CI_ENVIRONMENT || 'Production' }}")`,
+    ...privateMockAuth ? ['            CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=${{ secrets.POSTMAN_API_KEY }}")'] : [],
     '          if [ -f "$RUNNER_TEMP/postman-ssl/client.crt" ]; then',
     '            CMD+=(--ssl-client-cert "$RUNNER_TEMP/postman-ssl/client.crt"',
     '              --ssl-client-key "$RUNNER_TEMP/postman-ssl/client.key")',
@@ -134408,7 +134411,7 @@ function buildCiWorkflowLines(installUrl, postmanRegion) {
   ];
 }
 var CI_WORKFLOW_TEMPLATE = renderCiWorkflowTemplate();
-function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName) {
+function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentName, privateMockAuth) {
   return [
     "  - pwsh: |",
     "      $ErrorActionPreference = 'Stop'",
@@ -134420,6 +134423,7 @@ function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentNam
     "      $ciEnvironment = Resolve-AdoOptional $env:CI_ENVIRONMENT",
     "      if ([string]::IsNullOrWhiteSpace($ciEnvironment)) { $ciEnvironment = 'Production' }",
     `      $arguments = @('collection', 'run', $collectionUid, '-e', $env:POSTMAN_ENVIRONMENT_UID, '--report-events', '--env-var', "CI_ENVIRONMENT=$ciEnvironment")`,
+    ...privateMockAuth ? [`      $arguments += @('--env-var', "${PRIVATE_MOCK_AUTH_VARIABLE}=$env:POSTMAN_API_KEY")`] : [],
     "      $sslRoot = Join-Path $env:AGENT_TEMPDIRECTORY 'postman-ssl'",
     "      $clientCert = Join-Path $sslRoot 'client.crt'",
     "      $clientKey = Join-Path $sslRoot 'client.key'",
@@ -134441,10 +134445,11 @@ function buildAdoWindowsCollectionRunLines(displayName, collectionEnvironmentNam
     `      ${collectionEnvironmentName}: $(${collectionEnvironmentName})`,
     "      POSTMAN_ENVIRONMENT_UID: $(POSTMAN_ENVIRONMENT_UID)",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
-    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)"
+    "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : []
   ];
 }
-function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
+function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "trigger:",
     "  branches:",
@@ -134529,12 +134534,12 @@ function buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) {
     "      POSTMAN_SSL_CLIENT_CERT_B64: $(POSTMAN_SSL_CLIENT_CERT_B64)",
     "      POSTMAN_SSL_CLIENT_KEY_B64: $(POSTMAN_SSL_CLIENT_KEY_B64)",
     "      POSTMAN_SSL_EXTRA_CA_CERTS_B64: $(POSTMAN_SSL_EXTRA_CA_CERTS_B64)",
-    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID"),
-    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID"),
+    ...buildAdoWindowsCollectionRunLines("Run Smoke Tests", "POSTMAN_SMOKE_COLLECTION_UID", privateMockAuth),
+    ...buildAdoWindowsCollectionRunLines("Run Contract Tests", "POSTMAN_CONTRACT_COLLECTION_UID", privateMockAuth),
     ""
   ];
 }
-function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
+function buildAdoCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) {
   return [
     "trigger:",
     "  branches:",
@@ -134611,6 +134616,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     '        -e "$POSTMAN_ENVIRONMENT_UID"',
     "        --report-events",
     '        --env-var "CI_ENVIRONMENT=${CI_ENVIRONMENT:-Production}")',
+    ...privateMockAuth ? ['        CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=$POSTMAN_API_KEY")'] : [],
     '      if [ -f "$(Agent.TempDirectory)/postman-ssl/client.crt" ]; then',
     '        CMD+=(--ssl-client-cert "$(Agent.TempDirectory)/postman-ssl/client.crt"',
     '          --ssl-client-key "$(Agent.TempDirectory)/postman-ssl/client.key")',
@@ -134626,6 +134632,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     "    env:",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
     "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : [],
     "  - script: |",
     "      normalize_azure_optional_var() {",
     '        local name="$1"',
@@ -134642,6 +134649,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     '        -e "$POSTMAN_ENVIRONMENT_UID"',
     "        --report-events",
     '        --env-var "CI_ENVIRONMENT=${CI_ENVIRONMENT:-Production}")',
+    ...privateMockAuth ? ['        CMD+=(--env-var "' + PRIVATE_MOCK_AUTH_VARIABLE + '=$POSTMAN_API_KEY")'] : [],
     '      if [ -f "$(Agent.TempDirectory)/postman-ssl/client.crt" ]; then',
     '        CMD+=(--ssl-client-cert "$(Agent.TempDirectory)/postman-ssl/client.crt"',
     '          --ssl-client-key "$(Agent.TempDirectory)/postman-ssl/client.key")',
@@ -134657,6 +134665,7 @@ function buildAdoCiWorkflowLines(installUrl, postmanRegion) {
     "    env:",
     "      CI_ENVIRONMENT: $(CI_ENVIRONMENT)",
     "      POSTMAN_SSL_CLIENT_PASSPHRASE: $(POSTMAN_SSL_CLIENT_PASSPHRASE)",
+    ...privateMockAuth ? ["      POSTMAN_API_KEY: $(POSTMAN_API_KEY)"] : [],
     ""
   ];
 }
@@ -134718,7 +134727,8 @@ function getCiWorkflowTemplate(provider, options = {}) {
     const rawUrl = runnerOs === "windows" ? String(options.postmanCliWindowsInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_WINDOWS_INSTALL_URL : String(options.postmanCliInstallUrl || "").trim() || DEFAULT_POSTMAN_CLI_INSTALL_URL;
     const postmanRegion = resolvePostmanRegion(options.postmanRegion);
     const installUrl = validateHttpsInstallUrl(rawUrl);
-    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion) : buildAdoCiWorkflowLines(installUrl, postmanRegion)).join("\n");
+    const privateMockAuth = options.privateMockAuth === true;
+    return (runnerOs === "windows" ? buildAdoWindowsCiWorkflowLines(installUrl, postmanRegion, privateMockAuth) : buildAdoCiWorkflowLines(installUrl, postmanRegion, privateMockAuth)).join("\n");
   }
   return renderCiWorkflowTemplate(options);
 }
@@ -137006,16 +137016,39 @@ function requireMockVisibility(mock, requested) {
   }
   return mock;
 }
-var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
-var PRIVATE_MOCK_AUTH_VARIABLE = "postmanPrivateMockApiKey";
+var PRIVATE_MOCK_AUTH_MARKER_PREFIX = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_MARKER = `${PRIVATE_MOCK_AUTH_MARKER_PREFIX}-v2`;
+var PRIVATE_MOCK_AUTH_VARIABLE2 = "postmanPrivateMockApiKey";
 var PRIVATE_MOCK_AUTH_SCRIPT = [
   `// ${PRIVATE_MOCK_AUTH_MARKER}`,
-  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE}');`,
-  "var privateMockHost = String(pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '');",
-  "if (privateMockApiKey && /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost)) {",
+  `var privateMockApiKey = pm.variables.get('${PRIVATE_MOCK_AUTH_VARIABLE2}');`,
+  "var privateMockHostValue = pm.request.url && pm.request.url.getHost ? pm.request.url.getHost() : '';",
+  "var privateMockHost = Array.isArray(privateMockHostValue) ? privateMockHostValue.join('.') : String(privateMockHostValue);",
+  "var isPrivateMockHost = /(^|\\.)mock\\.pstmn\\.io$/i.test(privateMockHost);",
+  "if (isPrivateMockHost && privateMockApiKey) {",
   "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "} else if (isPrivateMockHost) {",
+  `  console.warn('This mock server is private. Set the ${PRIVATE_MOCK_AUTH_VARIABLE2} variable to a Postman API key with access to it, or the request returns 401.');`,
   "}"
 ].join("\n");
+function stripPrivateMockAuthBlocks(code) {
+  if (!code.includes(PRIVATE_MOCK_AUTH_MARKER_PREFIX)) return code.trim();
+  const lines = code.split("\n");
+  const kept = [];
+  let skipping = false;
+  for (const line of lines) {
+    if (line.includes(PRIVATE_MOCK_AUTH_MARKER_PREFIX)) {
+      skipping = true;
+      continue;
+    }
+    if (skipping) {
+      if (/^\s*(?:(?:var|if)\s|\}\selse\sif\s|\}|pm\.request|console\.warn)/.test(line)) continue;
+      skipping = false;
+    }
+    kept.push(line);
+  }
+  return kept.join("\n").trim();
+}
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137613,8 +137646,9 @@ var PostmanGatewayAssetsClient = class {
       const item = this.asRecord(response?.data) ?? listedItem;
       const scripts = Array.isArray(item.scripts) ? item.scripts.filter((entry) => Boolean(this.asRecord(entry))) : [];
       const before = scripts.find((script) => String(script.type ?? "") === "beforeRequest");
-      if (String(before?.code ?? "").includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
-      const code = [String(before?.code ?? "").trim(), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
+      const existingCode = String(before?.code ?? "");
+      if (existingCode.includes(PRIVATE_MOCK_AUTH_MARKER)) continue;
+      const code = [stripPrivateMockAuthBlocks(existingCode), PRIVATE_MOCK_AUTH_SCRIPT].filter(Boolean).join("\n");
       const nextScripts = [
         ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
         { type: "beforeRequest", code, language: "text/javascript" }
@@ -138950,9 +138984,13 @@ function assertBranchAssetIds(inputs, decision, branchOwnedIds = process.env.POS
     );
   }
 }
-function buildEnvironmentValues(envName, baseUrl) {
+function buildEnvironmentValues(envName, baseUrl, options = {}) {
   return [
     { key: "baseUrl", value: baseUrl, type: "default" },
+    // A private mock refuses anonymous calls, so the manual-validation environment
+    // carries a named, empty, secret-typed slot for the caller's own key. Repo-sync
+    // never writes a value here; the developer pastes one in the Postman app.
+    ...options.privateMockAuth ? [{ key: PRIVATE_MOCK_AUTH_VARIABLE2, value: "", type: "secret" }] : [],
     { key: "CI", value: "false", type: "default" },
     { key: "RESPONSE_TIME_THRESHOLD", value: "2000", type: "default" },
     { key: "AWS_ACCESS_KEY_ID", value: "", type: "secret" },
@@ -139399,12 +139437,12 @@ async function upsertEnvironments(inputs, dependencies, resourcesState, assetMar
   }
   return envUids;
 }
-async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl) {
+async function upsertMockEnvironment(inputs, dependencies, assetProjectName, mockUrl, privateMockAuth) {
   if (!inputs.mockEnvironmentEnabled || !inputs.workspaceId || !mockUrl) {
     return "";
   }
   const displayName = `${assetProjectName} - Mock`;
-  const values = buildEnvironmentValues("mock", mockUrl);
+  const values = buildEnvironmentValues("mock", mockUrl, { privateMockAuth });
   const mask = resolveRepoSyncMasker(dependencies);
   try {
     const discovered = await dependencies.postman.findEnvironmentByName(
@@ -140133,14 +140171,16 @@ function renderCiWorkflow(inputs) {
       postmanCliInstallUrl: inputs.postmanCliInstallUrl,
       postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
       runnerOs: inputs.ciRunnerOs,
-      postmanRegion: inputs.postmanRegion
+      postmanRegion: inputs.postmanRegion,
+      privateMockAuth: inputs.mockVisibility === "private"
     });
   }
   return renderCiWorkflowTemplate({
     postmanCliInstallUrl: inputs.postmanCliInstallUrl,
     postmanCliWindowsInstallUrl: inputs.postmanCliWindowsInstallUrl,
     runnerOs: inputs.ciRunnerOs,
-    postmanRegion: inputs.postmanRegion
+    postmanRegion: inputs.postmanRegion,
+    privateMockAuth: inputs.mockVisibility === "private"
   });
 }
 function createRepoSummary(outputs, envUids, pushed) {
@@ -140495,18 +140535,26 @@ async function runRepoSyncInner(inputs, dependencies) {
             "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
           );
         }
+        const configured = [];
         for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
           if (collectionUid) {
             await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+            configured.push(collectionUid);
           }
         }
+        if (configured.length > 0) {
+          (dependencies.core.notice ?? dependencies.core.info)(
+            `Private mock: installed a request hook on ${configured.length} collection(s) that sends the ${PRIVATE_MOCK_AUTH_VARIABLE2} variable as x-api-key, and only to *.mock.pstmn.io hosts. The generated CI workflow supplies it from the POSTMAN_API_KEY secret. For manual runs in the Postman app, set that variable to a key with access to the mock. No key is stored in the collection, environment, outputs, or repository.`
+          );
+        }
       }
       if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
         const mockEnvironmentUid = await upsertMockEnvironment(
           inputs,
           dependencies,
           assetProjectName,
-          resolvedMockUrl
+          resolvedMockUrl,
+          resolvedMockVisibility === "private"
         );
         outputs["mock-environment-uid"] = mockEnvironmentUid;
         outputs["mock-environment-status"] = mockEnvironmentUid ? "success" : "failed";
@@ -140972,6 +141020,7 @@ function createRepoSyncDependencies(inputs, resolved, factories, options = {}) {
     // uid (the gateway services key access off it, exactly like the public REST
     // API); the bare model id 403s "request access from the collection editor".
     createMock: gatewayAssets.createMock.bind(gatewayAssets),
+    configurePrivateMockRuntimeAuth: gatewayAssets.configurePrivateMockRuntimeAuth.bind(gatewayAssets),
     listMocks: gatewayAssets.listMocks.bind(gatewayAssets),
     mockExists: gatewayAssets.mockExists.bind(gatewayAssets),
     findMockByCollection: gatewayAssets.findMockByCollection.bind(gatewayAssets),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman-cse/onboarding-repo-sync",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Postman repo sync GitHub Action.",
   "type": "module",
   "main": "dist/index.cjs",