refactoring policy redaction check and warning

Author: EMaher

.squad/agents/apimexpert/history.md

@@ -116,3 +116,17 @@ When comparing a *link-imported* API (e.g. Petstore via `swagger-link`/`openapi-
 
 Round-trip comparison harness (`tests/integration/all-resource-types`) normalizes both via `RepresentationSchemaRefIgnoredProperties` and `ParameterIgnoredProperties`. Symptom if not stripped: every operation shows a `properties.request/responses/templateParameters` DIFF present-on-one-side-only.
 
+### 2026-07-01: Overriding a policy to clear a redacted secret — possible but rarely the right fix
+
+**Question that comes up:** when the extract-time secret redactor leaves `*** REDACTED ***` inline in a policy, can you clear the publish pre-flight guard by *overriding the policy* instead of fixing the source?
+
+**Answer: yes, technically — but it's almost never the intended path.**
+
+- All five policy types are wired into the override system (`src/services/override-merger.ts`): `ServicePolicy → policies`, `PolicyFragment → policyFragments` (direct); `ApiPolicy → apis.<api>.policies`, `ProductPolicy → products.<product>.policies` (child); `ApiOperationPolicy → apis.<api>.operations.<op>.policies` (grandchild).
+- The publish payload for a policy is `{ properties: { value, format } }`, and `applyOverrides` deep-merges `properties`, so an override supplying `properties.value` replaces the policy XML wholesale.
+- The pre-flight guard (`src/services/secret-redaction-guard.ts`) applies overrides **before** scanning for the marker — by design — so a policy override that yields clean content passes the check.
+
+**Why it's the wrong tool for redacted secrets:**
+- The marker is inserted **inline** inside the XML (e.g. inside a `set-header` `<value>`), but overrides are **whole-value** replacements of `properties.value` — there is no inline/sub-string patch. You'd have to paste the entire policy XML (with the real secret) into a committed override file, re-introducing the plaintext secret that redaction removed.
+- Intended remediation: change the **source** policy to reference a named value (`{{my-secret}}`) so redaction never triggers, then supply the secret via a named-value override or Key Vault reference. The docs' "Gotcha: Redacted secrets" section (`docs/guides/environment-overrides.md`) only covers named values — there is no documented "override a redacted policy" workflow, reflecting this.
+

src/services/api-extractor.ts

@@ -14,7 +14,7 @@ import { ResourceType, RESOURCE_TYPE_METADATA } from '../models/resource-types.j
 import { FilterConfig } from '../models/config.js';
 import { shouldIncludeResource } from './filter-service.js';
 import { extractResourceType, ExtractedResource } from './resource-extractor.js';
-import { redactPolicySecrets, warnPolicySecretRedactions } from './secret-redactor.js';
+import { redactAndWarnPolicySecrets } from './secret-redactor.js';
 import { logger } from '../lib/logger.js';
 import { buildResourceLabel } from '../lib/resource-uri.js';
 import { getNamePart } from '../lib/resource-path.js';
@@ -364,8 +364,7 @@ async function extractApiPolicy(
   const policyContent = properties?.value as string | undefined;
 
   if (policyContent) {
-    const { redactedContent, findings } = redactPolicySecrets(policyContent);
-    warnPolicySecretRedactions(policyDescriptor, findings);
+    const redactedContent = redactAndWarnPolicySecrets(policyDescriptor, policyContent);
     await store.writeContent(
       outputDir,
       policyDescriptor,
@@ -423,8 +422,7 @@ async function extractApiOperations(
     const policyContent = properties?.value as string | undefined;
 
     if (policyContent) {
-      const { redactedContent, findings } = redactPolicySecrets(policyContent);
-      warnPolicySecretRedactions(opPolicyDescriptor, findings);
+      const redactedContent = redactAndWarnPolicySecrets(opPolicyDescriptor, policyContent);
       await store.writeContent(outputDir, opPolicyDescriptor, redactedContent, 'policy');
       operationPolicies.push({
         descriptor: opPolicyDescriptor,
@@ -536,8 +534,7 @@ async function extractGraphQLResolvers(
     const policyContent = props?.value as string | undefined;
 
     if (policyContent) {
-      const { redactedContent, findings } = redactPolicySecrets(policyContent);
-      warnPolicySecretRedactions(resolverPolicyDescriptor, findings);
+      const redactedContent = redactAndWarnPolicySecrets(resolverPolicyDescriptor, policyContent);
       await store.writeContent(outputDir, resolverPolicyDescriptor, redactedContent, 'policy');
       resolverPolicies.push({
         descriptor: resolverPolicyDescriptor,

src/services/extract-service.ts

@@ -29,7 +29,7 @@ import { extractWorkspaces, WorkspaceExtractionResult } from './workspace-extrac
 import {
   findTransitiveDependencies,
 } from './transitive-resolver.js';
-import { redactPolicySecrets, warnPolicySecretRedactions } from './secret-redactor.js';
+import { redactAndWarnPolicySecrets } from './secret-redactor.js';
 import { logger } from '../lib/logger.js';
 import { buildResourceLabel } from '../lib/resource-uri.js';
 import { EXIT_SUCCESS, EXIT_PARTIAL, EXIT_FATAL } from '../lib/exit-codes.js';
@@ -402,8 +402,7 @@ async function extractServicePolicy(
   const policyContent = properties?.value as string | undefined;
 
   if (policyContent) {
-    const { redactedContent, findings } = redactPolicySecrets(policyContent);
-    warnPolicySecretRedactions(descriptor, findings);
+    const redactedContent = redactAndWarnPolicySecrets(descriptor, policyContent);
     await store.writeContent(outputDir, descriptor, redactedContent, 'policy');
     result.totalExtracted++;
     result.extractedDescriptors.push(descriptor);

src/services/product-extractor.ts

@@ -11,7 +11,7 @@ import { ApimServiceContext, AssociationEntry, ResourceDescriptor } from '../mod
 import { ResourceType, RESOURCE_TYPE_METADATA } from '../models/resource-types.js';
 import { FilterConfig } from '../models/config.js';
 import { extractResourceName } from './resource-extractor.js';
-import { redactPolicySecrets, warnPolicySecretRedactions } from './secret-redactor.js';
+import { redactAndWarnPolicySecrets } from './secret-redactor.js';
 import { logger } from '../lib/logger.js';
 import { getNamePart } from '../lib/resource-path.js';
 import { isWorkspaceScope, extractNameFromLink, extractLinkTarget } from '../lib/workspace-link.js';
@@ -216,8 +216,7 @@ async function extractProductPolicy(
   const policyContent = properties?.value as string | undefined;
 
   if (policyContent) {
-    const { redactedContent, findings } = redactPolicySecrets(policyContent);
-    warnPolicySecretRedactions(policyDescriptor, findings);
+    const redactedContent = redactAndWarnPolicySecrets(policyDescriptor, policyContent);
     await store.writeContent(outputDir, policyDescriptor, redactedContent, 'policy');
     logger.debug(`Extracted policy for product "${getNamePart(productDescriptor.nameParts, 0)}"`);
     return redactedContent;

src/services/secret-redactor.ts

@@ -250,10 +250,26 @@ export function redactPolicySecrets(
   };
 }
 
+/**
+ * Redact inline literal secrets in policy XML content and emit a warning log
+ * for every finding. This is the entry point services should use so that
+ * redaction and warning always happen together; the underlying
+ * {@link redactPolicySecrets} (pure, exported) and `warnPolicySecretRedactions`
+ * (private) helpers stay separate for testability.
+ */
+export function redactAndWarnPolicySecrets(
+  descriptor: ResourceDescriptor,
+  policyContent: string
+): string {
+  const { redactedContent, findings } = redactPolicySecrets(policyContent);
+  warnPolicySecretRedactions(descriptor, findings);
+  return redactedContent;
+}
+
 /**
  * Emit warning logs for policy secret redaction findings.
  */
-export function warnPolicySecretRedactions(
+function warnPolicySecretRedactions(
   descriptor: ResourceDescriptor,
   findings: PolicySecretFinding[]
 ): void {