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

package/README.md

@@ -113,9 +113,9 @@ with:
   monitor-id: 1e2f3a4b-monitor-id
 ```
 
-Repo-sync supports public mocks for anonymous validation. An explicit `mock-url` must match one mock in the resolved workspace and reference the expected baseline collection and environment. Discovered and newly created mocks pass the same live visibility check. Private mocks, responses without a recognized visibility field, stale URLs, and identity mismatches fail before `mock-url` is emitted; repo-sync never places a Postman API key in a collection or environment to make a private mock callable.
+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.
 
-For manual collection validation against that public mock, opt in to a dedicated Postman environment:
+For manual collection validation against the resolved mock, opt in to a dedicated Postman environment:
 
 ```yaml
 with:
@@ -155,7 +155,8 @@ with:
 | `release-label` | Optional release label used for versioned naming. | no |  |
 | `monitor-id` | Existing smoke monitor ID. When set, the action validates and reuses this monitor instead of creating a new one. | no |  |
 | `mock-url` | Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one. | no |  |
-| `mock-environment-enabled` | Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection. | no | `false` |
+| `mock-visibility` | Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync. | no | `public` |
+| `mock-environment-enabled` | Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential. | no | `false` |
 | `monitor-cron` | Cron expression for monitor scheduling (e.g. '0 */6 * * *'). When empty, the monitor is created disabled and triggered to run once per workflow invocation (and once on every subsequent run). | no | `""` |
 | `environments-json` | JSON array of environment slugs to create or update. | no | `["prod"]` |
 | `git-provider` | Git provider override ('github', 'gitlab', 'bitbucket', 'azure-devops'). Auto-detected from environment when omitted. | no |  |
@@ -203,6 +204,8 @@ with:
 | `environment-sync-status` | Whether environment sync succeeded, was skipped, or failed. |
 | `environment-uids-json` | JSON map of environment slug to Postman environment uid. |
 | `mock-url` | Created or reused mock server URL. |
+| `mock-visibility` | Authoritatively observed mock visibility: public or private. |
+| `mock-auth-required` | Whether the collection runner must supply postmanPrivateMockApiKey at runtime. |
 | `mock-environment-uid` | Dedicated manual-validation environment UID when mock-environment-enabled succeeds. |
 | `mock-environment-status` | Whether the optional manual-validation mock environment succeeded, was skipped, or failed. |
 | `monitor-id` | Created or reused smoke monitor ID. |

package/action.yml

@@ -57,8 +57,12 @@ inputs:
   mock-url:
     description: Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.
     required: false
+  mock-visibility:
+    description: Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync.
+    required: false
+    default: public
   mock-environment-enabled:
-    description: Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.
+    description: Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential.
     required: false
     default: "false"
   monitor-cron:
@@ -204,6 +208,10 @@ outputs:
     description: JSON map of environment slug to Postman environment uid.
   mock-url:
     description: Created or reused mock server URL.
+  mock-visibility:
+    description: "Authoritatively observed mock visibility: public or private."
+  mock-auth-required:
+    description: Whether the collection runner must supply postmanPrivateMockApiKey at runtime.
   mock-environment-uid:
     description: Dedicated manual-validation environment UID when mock-environment-enabled succeeds.
   mock-environment-status:

package/dist/action.cjs

@@ -136660,8 +136660,14 @@ var postmanRepoSyncActionContract = {
       description: "Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.",
       required: false
     },
+    "mock-visibility": {
+      description: "Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync.",
+      required: false,
+      default: "public",
+      allowedValues: ["public", "private"]
+    },
     "mock-environment-enabled": {
-      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.",
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential.",
       required: false,
       default: "false"
     },
@@ -136858,6 +136864,12 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "mock-visibility": {
+      description: "Authoritatively observed mock visibility: public or private."
+    },
+    "mock-auth-required": {
+      description: "Whether the collection runner must supply postmanPrivateMockApiKey at runtime."
+    },
     "mock-environment-uid": {
       description: "Dedicated manual-validation environment UID when mock-environment-enabled succeeds."
     },
@@ -136958,19 +136970,30 @@ var MockContractError = class extends Error {
     this.name = "MockContractError";
   }
 };
-function requirePublicMock(mock) {
-  if (mock.visibility === "private") {
+function requireMockVisibility(mock, requested) {
+  if (mock.visibility === "unknown") {
     throw new MockContractError(
-      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is callable.`
     );
   }
-  if (mock.visibility !== "public") {
+  if (mock.visibility !== requested) {
+    const code = requested === "public" ? "MOCK_NOT_PUBLIC" : "MOCK_NOT_PRIVATE";
     throw new MockContractError(
-      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+      `${code}: Mock ${mock.uid} is ${mock.visibility}, but mock-visibility requires ${requested}. Change the mock visibility in Postman or set mock-visibility to ${mock.visibility}.`
     );
   }
   return mock;
 }
+var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_VARIABLE = "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)) {",
+  "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "}"
+].join("\n");
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137478,22 +137501,22 @@ var PostmanGatewayAssetsClient = class {
     return data?.collection ?? null;
   }
   // --- mocks (service: mock) ---
-  async createMock(workspaceId, name, collectionUid, environmentUid) {
+  async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "public") {
     const ws = workspaceId || this.workspaceId;
     const mockName = String(name ?? "").trim();
     const collection = String(collectionUid ?? "").trim();
     const environment = String(environmentUid ?? "").trim();
-    const flightKey = `mock:${ws}:${collection}:${environment}:${mockName}`;
+    const flightKey = `mock:${ws}:${collection}:${environment}:${requestedVisibility}:${mockName}`;
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        const reusable = requirePublicMock(existing);
-        return { uid: reusable.uid, url: reusable.mockUrl };
+        const reusable = requireMockVisibility(existing, requestedVisibility);
+        return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
       }
       const body = {
         name: mockName,
         collection,
-        private: false,
+        private: requestedVisibility === "private",
         ...environment ? { environment } : {}
       };
       const send2 = (fallback) => this.gateway.requestJson(
@@ -137511,12 +137534,14 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const created = requirePublicMock(
-          this.decodeMockRecord(record, "Mock create")
+        const created = requireMockVisibility(
+          this.decodeMockRecord(record, "Mock create"),
+          requestedVisibility
         );
         return {
           uid: created.uid,
-          url: created.mockUrl
+          url: created.mockUrl,
+          visibility: requestedVisibility
         };
       };
       try {
@@ -137527,8 +137552,8 @@ var PostmanGatewayAssetsClient = class {
           error2
         );
         if (adopted) {
-          const reusable = requirePublicMock(adopted);
-          return { uid: reusable.uid, url: reusable.mockUrl };
+          const reusable = requireMockVisibility(adopted, requestedVisibility);
+          return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -137538,6 +137563,51 @@ var PostmanGatewayAssetsClient = class {
       }
     });
   }
+  /**
+   * Add a secret-free runtime hook to every HTTP request in a collection. The
+   * PMAK value is supplied only by the runner as a transient variable; this
+   * method persists the variable name and header wiring, never the credential.
+   */
+  async configurePrivateMockRuntimeAuth(collectionUid) {
+    const cid = String(collectionUid ?? "").trim();
+    if (!cid) return 0;
+    const listed = await this.gateway.requestJson({
+      service: "collection",
+      method: "get",
+      path: `/v3/collections/${cid}/items/`
+    });
+    const items = Array.isArray(listed?.data) ? listed.data : [];
+    let patched = 0;
+    for (const listedItem of items) {
+      if (String(listedItem.$kind ?? "") !== "http-request") continue;
+      const itemId = String(listedItem.id ?? "").trim();
+      if (!itemId) continue;
+      const response = await this.gateway.requestJson({
+        service: "collection",
+        method: "get",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" }
+      });
+      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 nextScripts = [
+        ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
+        { type: "beforeRequest", code, language: "text/javascript" }
+      ];
+      await this.gateway.requestJson({
+        service: "collection",
+        method: "patch",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" },
+        body: [{ op: "add", path: "/scripts", value: nextScripts }]
+      });
+      patched += 1;
+    }
+    return patched;
+  }
   async listMocks() {
     const response = await this.gateway.requestJson({
       service: "mock",
@@ -138552,7 +138622,7 @@ function normalizeMockUrl(value, source) {
   url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
   return url.toString();
 }
-function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+function resolveExplicitMock(mocks, explicitUrl, collectionUid, environmentUid, requestedVisibility) {
   const normalized = normalizeMockUrl(explicitUrl, "mock-url");
   const matches = mocks.filter(
     (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
@@ -138578,7 +138648,7 @@ function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmen
       `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
     );
   }
-  return requirePublicMock(match);
+  return requireMockVisibility(match, requestedVisibility);
 }
 function shouldRetryMockCreate(error2) {
   if (error2 instanceof MockContractError) return false;
@@ -138690,6 +138760,15 @@ function parseCredentialPreflight(value) {
     `Unsupported credential-preflight "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseMockVisibility(value) {
+  const definition = postmanRepoSyncActionContract.inputs["mock-visibility"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "public");
+  if (allowed.includes(normalized)) return normalized;
+  throw new Error(
+    `Unsupported mock-visibility "${normalized}". Supported values: ${allowed.join(", ")}`
+  );
+}
 function parseBranchStrategy(value) {
   const definition = postmanRepoSyncActionContract.inputs["branch-strategy"];
   const allowed = definition.allowedValues ?? [];
@@ -138796,6 +138875,7 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput2("org-mode", env), false),
     monitorId: getInput2("monitor-id", env),
     mockUrl: getInput2("mock-url", env),
+    mockVisibility: parseMockVisibility(getInput2("mock-visibility", env)),
     mockEnvironmentEnabled: parseBooleanInput(getInput2("mock-environment-enabled", env), false),
     monitorCron: getInput2("monitor-cron", env),
     sslClientCert: getInput2("ssl-client-cert", env),
@@ -139023,6 +139103,8 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-visibility": "",
+    "mock-auth-required": "false",
     "mock-environment-uid": "",
     "mock-environment-status": "skipped",
     "monitor-id": "",
@@ -139092,6 +139174,7 @@ function readActionInputs(actionCore) {
     INPUT_ORG_MODE: readInput(actionCore, "org-mode"),
     INPUT_MONITOR_ID: readInput(actionCore, "monitor-id"),
     INPUT_MOCK_URL: readInput(actionCore, "mock-url"),
+    INPUT_MOCK_VISIBILITY: readInput(actionCore, "mock-visibility"),
     INPUT_MOCK_ENVIRONMENT_ENABLED: readInput(actionCore, "mock-environment-enabled"),
     INPUT_MONITOR_CRON: readInput(actionCore, "monitor-cron"),
     INPUT_SSL_CLIENT_CERT: sslClientCert,
@@ -140045,7 +140128,9 @@ function createRepoSummary(outputs, envUids, pushed) {
     environmentSyncStatus: outputs["environment-sync-status"],
     mockEnvironmentStatus: outputs["mock-environment-status"],
     mockEnvironmentUid: outputs["mock-environment-uid"],
+    mockAuthRequired: outputs["mock-auth-required"] === "true",
     mockUrl: outputs["mock-url"],
+    mockVisibility: outputs["mock-visibility"],
     monitorId: outputs["monitor-id"],
     pushed,
     resolvedCurrentRef: outputs["resolved-current-ref"],
@@ -140273,6 +140358,7 @@ async function runRepoSyncInner(inputs, dependencies) {
     const mockEnvUid = envUids.dev || envUids.prod || Object.values(envUids)[0];
     if (mockEnvUid) {
       let resolvedMockUrl = "";
+      let resolvedMockVisibility = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
         let mocks;
@@ -140290,12 +140376,15 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error2 }
           );
         }
-        resolvedMockUrl = resolveExplicitPublicMock(
+        const resolved = resolveExplicitMock(
           mocks,
           inputs.mockUrl,
           inputs.baselineCollectionId,
-          mockEnvUid
-        ).mockUrl;
+          mockEnvUid,
+          inputs.mockVisibility
+        );
+        resolvedMockUrl = resolved.mockUrl;
+        resolvedMockVisibility = resolved.visibility;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
@@ -140319,7 +140408,9 @@ async function runRepoSyncInner(inputs, dependencies) {
           );
         }
         if (discovered) {
-          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          const resolved = requireMockVisibility(discovered, inputs.mockVisibility);
+          resolvedMockUrl = resolved.mockUrl;
+          resolvedMockVisibility = resolved.visibility;
           dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
         }
       }
@@ -140332,7 +140423,8 @@ async function runRepoSyncInner(inputs, dependencies) {
               inputs.workspaceId,
               mockName,
               inputs.baselineCollectionId,
-              mockEnvUid
+              mockEnvUid,
+              inputs.mockVisibility
             ),
             {
               maxAttempts: 3,
@@ -140354,6 +140446,7 @@ async function runRepoSyncInner(inputs, dependencies) {
             }
           );
           resolvedMockUrl = mock.url;
+          resolvedMockVisibility = mock.visibility ?? inputs.mockVisibility;
           dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
         } catch (error2) {
           throw new Error(
@@ -140369,7 +140462,23 @@ async function runRepoSyncInner(inputs, dependencies) {
         }
       }
       outputs["mock-url"] = resolvedMockUrl;
+      outputs["mock-visibility"] = resolvedMockVisibility;
+      outputs["mock-auth-required"] = String(resolvedMockVisibility === "private");
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      dependencies.core.setOutput("mock-visibility", resolvedMockVisibility);
+      dependencies.core.setOutput("mock-auth-required", outputs["mock-auth-required"]);
+      if (resolvedMockVisibility === "private") {
+        if (!dependencies.postman.configurePrivateMockRuntimeAuth) {
+          throw new Error(
+            "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
+          );
+        }
+        for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
+          if (collectionUid) {
+            await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+          }
+        }
+      }
       if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
         const mockEnvironmentUid = await upsertMockEnvironment(
           inputs,

package/dist/cli.cjs

@@ -134765,8 +134765,14 @@ var postmanRepoSyncActionContract = {
       description: "Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.",
       required: false
     },
+    "mock-visibility": {
+      description: "Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync.",
+      required: false,
+      default: "public",
+      allowedValues: ["public", "private"]
+    },
     "mock-environment-enabled": {
-      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.",
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential.",
       required: false,
       default: "false"
     },
@@ -134963,6 +134969,12 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "mock-visibility": {
+      description: "Authoritatively observed mock visibility: public or private."
+    },
+    "mock-auth-required": {
+      description: "Whether the collection runner must supply postmanPrivateMockApiKey at runtime."
+    },
     "mock-environment-uid": {
       description: "Dedicated manual-validation environment UID when mock-environment-enabled succeeds."
     },
@@ -135063,19 +135075,30 @@ var MockContractError = class extends Error {
     this.name = "MockContractError";
   }
 };
-function requirePublicMock(mock) {
-  if (mock.visibility === "private") {
+function requireMockVisibility(mock, requested) {
+  if (mock.visibility === "unknown") {
     throw new MockContractError(
-      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is callable.`
     );
   }
-  if (mock.visibility !== "public") {
+  if (mock.visibility !== requested) {
+    const code = requested === "public" ? "MOCK_NOT_PUBLIC" : "MOCK_NOT_PRIVATE";
     throw new MockContractError(
-      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+      `${code}: Mock ${mock.uid} is ${mock.visibility}, but mock-visibility requires ${requested}. Change the mock visibility in Postman or set mock-visibility to ${mock.visibility}.`
     );
   }
   return mock;
 }
+var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_VARIABLE = "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)) {",
+  "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "}"
+].join("\n");
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -135583,22 +135606,22 @@ var PostmanGatewayAssetsClient = class {
     return data?.collection ?? null;
   }
   // --- mocks (service: mock) ---
-  async createMock(workspaceId, name, collectionUid, environmentUid) {
+  async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "public") {
     const ws = workspaceId || this.workspaceId;
     const mockName = String(name ?? "").trim();
     const collection = String(collectionUid ?? "").trim();
     const environment = String(environmentUid ?? "").trim();
-    const flightKey = `mock:${ws}:${collection}:${environment}:${mockName}`;
+    const flightKey = `mock:${ws}:${collection}:${environment}:${requestedVisibility}:${mockName}`;
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        const reusable = requirePublicMock(existing);
-        return { uid: reusable.uid, url: reusable.mockUrl };
+        const reusable = requireMockVisibility(existing, requestedVisibility);
+        return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
       }
       const body = {
         name: mockName,
         collection,
-        private: false,
+        private: requestedVisibility === "private",
         ...environment ? { environment } : {}
       };
       const send2 = (fallback) => this.gateway.requestJson(
@@ -135616,12 +135639,14 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const created = requirePublicMock(
-          this.decodeMockRecord(record, "Mock create")
+        const created = requireMockVisibility(
+          this.decodeMockRecord(record, "Mock create"),
+          requestedVisibility
         );
         return {
           uid: created.uid,
-          url: created.mockUrl
+          url: created.mockUrl,
+          visibility: requestedVisibility
         };
       };
       try {
@@ -135632,8 +135657,8 @@ var PostmanGatewayAssetsClient = class {
           error
         );
         if (adopted) {
-          const reusable = requirePublicMock(adopted);
-          return { uid: reusable.uid, url: reusable.mockUrl };
+          const reusable = requireMockVisibility(adopted, requestedVisibility);
+          return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -135643,6 +135668,51 @@ var PostmanGatewayAssetsClient = class {
       }
     });
   }
+  /**
+   * Add a secret-free runtime hook to every HTTP request in a collection. The
+   * PMAK value is supplied only by the runner as a transient variable; this
+   * method persists the variable name and header wiring, never the credential.
+   */
+  async configurePrivateMockRuntimeAuth(collectionUid) {
+    const cid = String(collectionUid ?? "").trim();
+    if (!cid) return 0;
+    const listed = await this.gateway.requestJson({
+      service: "collection",
+      method: "get",
+      path: `/v3/collections/${cid}/items/`
+    });
+    const items = Array.isArray(listed?.data) ? listed.data : [];
+    let patched = 0;
+    for (const listedItem of items) {
+      if (String(listedItem.$kind ?? "") !== "http-request") continue;
+      const itemId = String(listedItem.id ?? "").trim();
+      if (!itemId) continue;
+      const response = await this.gateway.requestJson({
+        service: "collection",
+        method: "get",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" }
+      });
+      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 nextScripts = [
+        ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
+        { type: "beforeRequest", code, language: "text/javascript" }
+      ];
+      await this.gateway.requestJson({
+        service: "collection",
+        method: "patch",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" },
+        body: [{ op: "add", path: "/scripts", value: nextScripts }]
+      });
+      patched += 1;
+    }
+    return patched;
+  }
   async listMocks() {
     const response = await this.gateway.requestJson({
       service: "mock",
@@ -136605,7 +136675,7 @@ function normalizeMockUrl(value, source) {
   url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
   return url.toString();
 }
-function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+function resolveExplicitMock(mocks, explicitUrl, collectionUid, environmentUid, requestedVisibility) {
   const normalized = normalizeMockUrl(explicitUrl, "mock-url");
   const matches = mocks.filter(
     (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
@@ -136631,7 +136701,7 @@ function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmen
       `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
     );
   }
-  return requirePublicMock(match);
+  return requireMockVisibility(match, requestedVisibility);
 }
 function shouldRetryMockCreate(error) {
   if (error instanceof MockContractError) return false;
@@ -136740,6 +136810,15 @@ function parseCredentialPreflight(value) {
     `Unsupported credential-preflight "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseMockVisibility(value) {
+  const definition = postmanRepoSyncActionContract.inputs["mock-visibility"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "public");
+  if (allowed.includes(normalized)) return normalized;
+  throw new Error(
+    `Unsupported mock-visibility "${normalized}". Supported values: ${allowed.join(", ")}`
+  );
+}
 function parseBranchStrategy(value) {
   const definition = postmanRepoSyncActionContract.inputs["branch-strategy"];
   const allowed = definition.allowedValues ?? [];
@@ -136846,6 +136925,7 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput("org-mode", env), false),
     monitorId: getInput("monitor-id", env),
     mockUrl: getInput("mock-url", env),
+    mockVisibility: parseMockVisibility(getInput("mock-visibility", env)),
     mockEnvironmentEnabled: parseBooleanInput(getInput("mock-environment-enabled", env), false),
     monitorCron: getInput("monitor-cron", env),
     sslClientCert: getInput("ssl-client-cert", env),
@@ -137073,6 +137153,8 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-visibility": "",
+    "mock-auth-required": "false",
     "mock-environment-uid": "",
     "mock-environment-status": "skipped",
     "monitor-id": "",
@@ -137954,7 +138036,9 @@ function createRepoSummary(outputs, envUids, pushed) {
     environmentSyncStatus: outputs["environment-sync-status"],
     mockEnvironmentStatus: outputs["mock-environment-status"],
     mockEnvironmentUid: outputs["mock-environment-uid"],
+    mockAuthRequired: outputs["mock-auth-required"] === "true",
     mockUrl: outputs["mock-url"],
+    mockVisibility: outputs["mock-visibility"],
     monitorId: outputs["monitor-id"],
     pushed,
     resolvedCurrentRef: outputs["resolved-current-ref"],
@@ -138182,6 +138266,7 @@ async function runRepoSyncInner(inputs, dependencies) {
     const mockEnvUid = envUids.dev || envUids.prod || Object.values(envUids)[0];
     if (mockEnvUid) {
       let resolvedMockUrl = "";
+      let resolvedMockVisibility = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
         let mocks;
@@ -138199,12 +138284,15 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error }
           );
         }
-        resolvedMockUrl = resolveExplicitPublicMock(
+        const resolved = resolveExplicitMock(
           mocks,
           inputs.mockUrl,
           inputs.baselineCollectionId,
-          mockEnvUid
-        ).mockUrl;
+          mockEnvUid,
+          inputs.mockVisibility
+        );
+        resolvedMockUrl = resolved.mockUrl;
+        resolvedMockVisibility = resolved.visibility;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
@@ -138228,7 +138316,9 @@ async function runRepoSyncInner(inputs, dependencies) {
           );
         }
         if (discovered) {
-          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          const resolved = requireMockVisibility(discovered, inputs.mockVisibility);
+          resolvedMockUrl = resolved.mockUrl;
+          resolvedMockVisibility = resolved.visibility;
           dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
         }
       }
@@ -138241,7 +138331,8 @@ async function runRepoSyncInner(inputs, dependencies) {
               inputs.workspaceId,
               mockName,
               inputs.baselineCollectionId,
-              mockEnvUid
+              mockEnvUid,
+              inputs.mockVisibility
             ),
             {
               maxAttempts: 3,
@@ -138263,6 +138354,7 @@ async function runRepoSyncInner(inputs, dependencies) {
             }
           );
           resolvedMockUrl = mock.url;
+          resolvedMockVisibility = mock.visibility ?? inputs.mockVisibility;
           dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
         } catch (error) {
           throw new Error(
@@ -138278,7 +138370,23 @@ async function runRepoSyncInner(inputs, dependencies) {
         }
       }
       outputs["mock-url"] = resolvedMockUrl;
+      outputs["mock-visibility"] = resolvedMockVisibility;
+      outputs["mock-auth-required"] = String(resolvedMockVisibility === "private");
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      dependencies.core.setOutput("mock-visibility", resolvedMockVisibility);
+      dependencies.core.setOutput("mock-auth-required", outputs["mock-auth-required"]);
+      if (resolvedMockVisibility === "private") {
+        if (!dependencies.postman.configurePrivateMockRuntimeAuth) {
+          throw new Error(
+            "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
+          );
+        }
+        for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
+          if (collectionUid) {
+            await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+          }
+        }
+      }
       if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
         const mockEnvironmentUid = await upsertMockEnvironment(
           inputs,
@@ -139246,6 +139354,7 @@ var CLI_INPUT_NAMES = [
   "org-mode",
   "monitor-id",
   "mock-url",
+  "mock-visibility",
   "mock-environment-enabled",
   "monitor-cron",
   "ssl-client-cert",

package/dist/index.cjs

@@ -136682,8 +136682,14 @@ var postmanRepoSyncActionContract = {
       description: "Existing mock server URL. When set, the action validates and reuses this mock instead of creating a new one.",
       required: false
     },
+    "mock-visibility": {
+      description: "Required mock access policy. Public is anonymous; private requires a runtime x-api-key supplied by the caller and is never persisted by repo-sync.",
+      required: false,
+      default: "public",
+      allowedValues: ["public", "private"]
+    },
     "mock-environment-enabled": {
-      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated public mock URL. This environment is excluded from runtime CI selection.",
+      description: "Create or update a dedicated manual-validation environment whose baseUrl is the validated mock URL. This environment is excluded from runtime CI selection and never contains a mock credential.",
       required: false,
       default: "false"
     },
@@ -136880,6 +136886,12 @@ var postmanRepoSyncActionContract = {
     "mock-url": {
       description: "Created or reused mock server URL."
     },
+    "mock-visibility": {
+      description: "Authoritatively observed mock visibility: public or private."
+    },
+    "mock-auth-required": {
+      description: "Whether the collection runner must supply postmanPrivateMockApiKey at runtime."
+    },
     "mock-environment-uid": {
       description: "Dedicated manual-validation environment UID when mock-environment-enabled succeeds."
     },
@@ -136980,19 +136992,30 @@ var MockContractError = class extends Error {
     this.name = "MockContractError";
   }
 };
-function requirePublicMock(mock) {
-  if (mock.visibility === "private") {
+function requireMockVisibility(mock, requested) {
+  if (mock.visibility === "unknown") {
     throw new MockContractError(
-      `MOCK_NOT_PUBLIC: Mock ${mock.uid} is private. Make it public in Postman or remove/rename it so repo-sync can create the canonical public mock.`
+      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is callable.`
     );
   }
-  if (mock.visibility !== "public") {
+  if (mock.visibility !== requested) {
+    const code = requested === "public" ? "MOCK_NOT_PUBLIC" : "MOCK_NOT_PRIVATE";
     throw new MockContractError(
-      `MOCK_VISIBILITY_UNKNOWN: Mock ${mock.uid} did not expose a supported visibility field. Refusing to assume it is publicly callable.`
+      `${code}: Mock ${mock.uid} is ${mock.visibility}, but mock-visibility requires ${requested}. Change the mock visibility in Postman or set mock-visibility to ${mock.visibility}.`
     );
   }
   return mock;
 }
+var PRIVATE_MOCK_AUTH_MARKER = "postman-enterprise-automation: private-mock-auth";
+var PRIVATE_MOCK_AUTH_VARIABLE = "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)) {",
+  "  pm.request.headers.upsert({ key: 'x-api-key', value: privateMockApiKey });",
+  "}"
+].join("\n");
 var MAX_CREATE_FLIGHTS = 256;
 var createFlights = /* @__PURE__ */ new Map();
 var PostmanGatewayAssetsClient = class {
@@ -137500,22 +137523,22 @@ var PostmanGatewayAssetsClient = class {
     return data?.collection ?? null;
   }
   // --- mocks (service: mock) ---
-  async createMock(workspaceId, name, collectionUid, environmentUid) {
+  async createMock(workspaceId, name, collectionUid, environmentUid, requestedVisibility = "public") {
     const ws = workspaceId || this.workspaceId;
     const mockName = String(name ?? "").trim();
     const collection = String(collectionUid ?? "").trim();
     const environment = String(environmentUid ?? "").trim();
-    const flightKey = `mock:${ws}:${collection}:${environment}:${mockName}`;
+    const flightKey = `mock:${ws}:${collection}:${environment}:${requestedVisibility}:${mockName}`;
     return this.singleFlight(flightKey, flightKey, "mock", async () => {
       const existing = await this.findMockByCollection(collection, environment, mockName);
       if (existing) {
-        const reusable = requirePublicMock(existing);
-        return { uid: reusable.uid, url: reusable.mockUrl };
+        const reusable = requireMockVisibility(existing, requestedVisibility);
+        return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
       }
       const body = {
         name: mockName,
         collection,
-        private: false,
+        private: requestedVisibility === "private",
         ...environment ? { environment } : {}
       };
       const send2 = (fallback) => this.gateway.requestJson(
@@ -137533,12 +137556,14 @@ var PostmanGatewayAssetsClient = class {
       );
       const parseMock = (response) => {
         const record = this.dataOf(response);
-        const created = requirePublicMock(
-          this.decodeMockRecord(record, "Mock create")
+        const created = requireMockVisibility(
+          this.decodeMockRecord(record, "Mock create"),
+          requestedVisibility
         );
         return {
           uid: created.uid,
-          url: created.mockUrl
+          url: created.mockUrl,
+          visibility: requestedVisibility
         };
       };
       try {
@@ -137549,8 +137574,8 @@ var PostmanGatewayAssetsClient = class {
           error2
         );
         if (adopted) {
-          const reusable = requirePublicMock(adopted);
-          return { uid: reusable.uid, url: reusable.mockUrl };
+          const reusable = requireMockVisibility(adopted, requestedVisibility);
+          return { uid: reusable.uid, url: reusable.mockUrl, visibility: requestedVisibility };
         }
         if (adopted === void 0) {
           const retried = await this.resendAbsentCreate(async () => parseMock(await send2("auto")));
@@ -137560,6 +137585,51 @@ var PostmanGatewayAssetsClient = class {
       }
     });
   }
+  /**
+   * Add a secret-free runtime hook to every HTTP request in a collection. The
+   * PMAK value is supplied only by the runner as a transient variable; this
+   * method persists the variable name and header wiring, never the credential.
+   */
+  async configurePrivateMockRuntimeAuth(collectionUid) {
+    const cid = String(collectionUid ?? "").trim();
+    if (!cid) return 0;
+    const listed = await this.gateway.requestJson({
+      service: "collection",
+      method: "get",
+      path: `/v3/collections/${cid}/items/`
+    });
+    const items = Array.isArray(listed?.data) ? listed.data : [];
+    let patched = 0;
+    for (const listedItem of items) {
+      if (String(listedItem.$kind ?? "") !== "http-request") continue;
+      const itemId = String(listedItem.id ?? "").trim();
+      if (!itemId) continue;
+      const response = await this.gateway.requestJson({
+        service: "collection",
+        method: "get",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" }
+      });
+      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 nextScripts = [
+        ...scripts.filter((script) => String(script.type ?? "") !== "beforeRequest"),
+        { type: "beforeRequest", code, language: "text/javascript" }
+      ];
+      await this.gateway.requestJson({
+        service: "collection",
+        method: "patch",
+        path: `/v3/collections/${cid}/items/${itemId}`,
+        headers: { "X-Entity-Type": "http-request" },
+        body: [{ op: "add", path: "/scripts", value: nextScripts }]
+      });
+      patched += 1;
+    }
+    return patched;
+  }
   async listMocks() {
     const response = await this.gateway.requestJson({
       service: "mock",
@@ -138574,7 +138644,7 @@ function normalizeMockUrl(value, source) {
   url.pathname = url.pathname.replace(/\/+$/g, "") || "/";
   return url.toString();
 }
-function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmentUid) {
+function resolveExplicitMock(mocks, explicitUrl, collectionUid, environmentUid, requestedVisibility) {
   const normalized = normalizeMockUrl(explicitUrl, "mock-url");
   const matches = mocks.filter(
     (mock) => normalizeMockUrl(mock.mockUrl, `mock ${mock.uid} URL`) === normalized
@@ -138600,7 +138670,7 @@ function resolveExplicitPublicMock(mocks, explicitUrl, collectionUid, environmen
       `EXPLICIT_MOCK_IDENTITY_MISMATCH: Mock ${match.uid} references environment ${match.environment || "(none)"}, expected ${environmentUid}`
     );
   }
-  return requirePublicMock(match);
+  return requireMockVisibility(match, requestedVisibility);
 }
 function shouldRetryMockCreate(error2) {
   if (error2 instanceof MockContractError) return false;
@@ -138712,6 +138782,15 @@ function parseCredentialPreflight(value) {
     `Unsupported credential-preflight "${normalized}". Supported values: ${allowed.join(", ")}`
   );
 }
+function parseMockVisibility(value) {
+  const definition = postmanRepoSyncActionContract.inputs["mock-visibility"];
+  const allowed = definition.allowedValues ?? [];
+  const normalized = String(value || "").trim() || (definition.default ?? "public");
+  if (allowed.includes(normalized)) return normalized;
+  throw new Error(
+    `Unsupported mock-visibility "${normalized}". Supported values: ${allowed.join(", ")}`
+  );
+}
 function parseBranchStrategy(value) {
   const definition = postmanRepoSyncActionContract.inputs["branch-strategy"];
   const allowed = definition.allowedValues ?? [];
@@ -138818,6 +138897,7 @@ function resolveInputs(env = process.env) {
     orgMode: parseBooleanInput(getInput2("org-mode", env), false),
     monitorId: getInput2("monitor-id", env),
     mockUrl: getInput2("mock-url", env),
+    mockVisibility: parseMockVisibility(getInput2("mock-visibility", env)),
     mockEnvironmentEnabled: parseBooleanInput(getInput2("mock-environment-enabled", env), false),
     monitorCron: getInput2("monitor-cron", env),
     sslClientCert: getInput2("ssl-client-cert", env),
@@ -139045,6 +139125,8 @@ function createOutputs(inputs) {
     "environment-sync-status": "skipped",
     "environment-uids-json": JSON.stringify(inputs.environmentUids),
     "mock-url": "",
+    "mock-visibility": "",
+    "mock-auth-required": "false",
     "mock-environment-uid": "",
     "mock-environment-status": "skipped",
     "monitor-id": "",
@@ -139114,6 +139196,7 @@ function readActionInputs(actionCore) {
     INPUT_ORG_MODE: readInput(actionCore, "org-mode"),
     INPUT_MONITOR_ID: readInput(actionCore, "monitor-id"),
     INPUT_MOCK_URL: readInput(actionCore, "mock-url"),
+    INPUT_MOCK_VISIBILITY: readInput(actionCore, "mock-visibility"),
     INPUT_MOCK_ENVIRONMENT_ENABLED: readInput(actionCore, "mock-environment-enabled"),
     INPUT_MONITOR_CRON: readInput(actionCore, "monitor-cron"),
     INPUT_SSL_CLIENT_CERT: sslClientCert,
@@ -140067,7 +140150,9 @@ function createRepoSummary(outputs, envUids, pushed) {
     environmentSyncStatus: outputs["environment-sync-status"],
     mockEnvironmentStatus: outputs["mock-environment-status"],
     mockEnvironmentUid: outputs["mock-environment-uid"],
+    mockAuthRequired: outputs["mock-auth-required"] === "true",
     mockUrl: outputs["mock-url"],
+    mockVisibility: outputs["mock-visibility"],
     monitorId: outputs["monitor-id"],
     pushed,
     resolvedCurrentRef: outputs["resolved-current-ref"],
@@ -140295,6 +140380,7 @@ async function runRepoSyncInner(inputs, dependencies) {
     const mockEnvUid = envUids.dev || envUids.prod || Object.values(envUids)[0];
     if (mockEnvUid) {
       let resolvedMockUrl = "";
+      let resolvedMockVisibility = "";
       const mockName = `${assetProjectName} Mock`;
       if (inputs.mockUrl) {
         let mocks;
@@ -140312,12 +140398,15 @@ async function runRepoSyncInner(inputs, dependencies) {
             { cause: error2 }
           );
         }
-        resolvedMockUrl = resolveExplicitPublicMock(
+        const resolved = resolveExplicitMock(
           mocks,
           inputs.mockUrl,
           inputs.baselineCollectionId,
-          mockEnvUid
-        ).mockUrl;
+          mockEnvUid,
+          inputs.mockVisibility
+        );
+        resolvedMockUrl = resolved.mockUrl;
+        resolvedMockVisibility = resolved.visibility;
         dependencies.core.info(`Reusing mock from explicit input: ${resolvedMockUrl}`);
       }
       if (!resolvedMockUrl && inputs.baselineCollectionId) {
@@ -140341,7 +140430,9 @@ async function runRepoSyncInner(inputs, dependencies) {
           );
         }
         if (discovered) {
-          resolvedMockUrl = requirePublicMock(discovered).mockUrl;
+          const resolved = requireMockVisibility(discovered, inputs.mockVisibility);
+          resolvedMockUrl = resolved.mockUrl;
+          resolvedMockVisibility = resolved.visibility;
           dependencies.core.info(`Discovered existing mock for collection ${inputs.baselineCollectionId}: ${resolvedMockUrl}`);
         }
       }
@@ -140354,7 +140445,8 @@ async function runRepoSyncInner(inputs, dependencies) {
               inputs.workspaceId,
               mockName,
               inputs.baselineCollectionId,
-              mockEnvUid
+              mockEnvUid,
+              inputs.mockVisibility
             ),
             {
               maxAttempts: 3,
@@ -140376,6 +140468,7 @@ async function runRepoSyncInner(inputs, dependencies) {
             }
           );
           resolvedMockUrl = mock.url;
+          resolvedMockVisibility = mock.visibility ?? inputs.mockVisibility;
           dependencies.core.info(`Created new mock: ${resolvedMockUrl}`);
         } catch (error2) {
           throw new Error(
@@ -140391,7 +140484,23 @@ async function runRepoSyncInner(inputs, dependencies) {
         }
       }
       outputs["mock-url"] = resolvedMockUrl;
+      outputs["mock-visibility"] = resolvedMockVisibility;
+      outputs["mock-auth-required"] = String(resolvedMockVisibility === "private");
       dependencies.core.setOutput("mock-url", resolvedMockUrl);
+      dependencies.core.setOutput("mock-visibility", resolvedMockVisibility);
+      dependencies.core.setOutput("mock-auth-required", outputs["mock-auth-required"]);
+      if (resolvedMockVisibility === "private") {
+        if (!dependencies.postman.configurePrivateMockRuntimeAuth) {
+          throw new Error(
+            "PRIVATE_MOCK_RUNTIME_AUTH_UNAVAILABLE: The Postman client cannot configure runtime x-api-key injection."
+          );
+        }
+        for (const collectionUid of [inputs.smokeCollectionId, inputs.contractCollectionId]) {
+          if (collectionUid) {
+            await dependencies.postman.configurePrivateMockRuntimeAuth(collectionUid);
+          }
+        }
+      }
       if (inputs.mockEnvironmentEnabled && isCanonicalWriter) {
         const mockEnvironmentUid = await upsertMockEnvironment(
           inputs,

package/package.json

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