fix(classic): normalize config-profile payloads for the Classic API's non-spec XML handling (PI-827)

[neilmartin83]

Problem

pro classic-macos-config-profiles apply --mobileconfig-file X.mobileconfig failed with an opaque HTTP 409 "Unable to update the database" whenever the mobileconfig contained any XML entity in a string value. Since plists must encode & and <, any profile with & or < in a value could not be uploaded — Setup Manager profiles, Santa CEL rules, CIS content, URLs with query strings. Backup round-trips (GET XML piped back into apply) failed identically. Signed and binary mobileconfigs produced malformed requests.

The server model (every clause wire-verified against two Jamf Pro 11.x tenants)

1. Validation: the Classic API entity-decodes submitted <payloads> content once and 409s when the result contains a bare & or <. Spec-correct raw CDATA is therefore rejected for any plist containing &/< — escape-once is the only submittable wire form for such profiles. (A raw-first/retry-on-409 design was implemented and reverted in this branch's history once probes proved this.)
2. Storage is per-payload-type (proven with a mixed profile — one wire body, two treatments): fragments of types the server re-renders (com.apple.ManagedClient.preferences custom settings including dict keys, com.apple.notificationsettings) are entity-decoded once — the escape stores them byte-exact. Every other payload type (TCC, direct com.apple.loginwindow, all mobile device payloads) is stored verbatim, keeping an extra entity layer — values with &/< there cannot be stored faithfully by any client, matching PI-827's history that Jamf's own exports can't be re-uploaded intact.

Fix (generator templates + internal/profileconvert)

• normalizeClassicProfilePayloadsForSend — final body transform before every profile send: recover the true plist (text-form/backup input decoded once), guard ]]>, escape every & once, wrap in a single CDATA section.
• verifyClassicProfileStored — after every successful write, GET the stored payload and semantically compare against the submitted plist (profileconvert.DiffPayloadValues: parse-based, masks server-rewritten Payload* metadata, tolerates the server's edge-whitespace trim). Server-side corruption surfaces as a stderr warning naming the exact dotted paths (e.g. PayloadContent[3].LoginwindowText) instead of passing silently.
• Input handling (injectClassicFileFields): CMS-signed mobileconfigs auto-extract their inner plist (smallstep/pkcs7) with a note — the signature can't survive this API anyway; binary plists convert to XML; embedded CDATA sections are rewritten textually (stripCDATASections — not a plist re-serialise, which drops trailing whitespace in CDATA text).

Verification

Live on both tenants: all five reserved characters × every legal representation (raw/named entity/decimal/hex refs), literal entity text, entity-bearing dict keys, embedded CDATA sections, CEL expressions, signed profiles, binary plists, GET→apply round-trips. MCX-family content stores byte-exact with zero warnings through create/update/apply; the server-unfixable combinations (mobile + typed macOS payloads with &/< in values) create with deterministic warnings naming the affected values. On-device verification of decoded values via System Settings.

Full analysis: docs/solutions/conventions/classic-profile-payload-ampersand-escaping-2026-07-30.md

🤖 Generated with Claude Code