Supported provenance handling when copying a verified helper

What supported public contract should software use for com.apple.provenance when
copying an exact expected helper binary into a new, private owner-controlled
working directory for separately authorized later use?

We want to leave originals unchanged, preserve security protections, and avoid
removing, decoding or reconstructing opaque Apple attribute values. Program-byte
identity, permissions/custody and code validation are separate from this metadata
question; an attribute name or copy success is not treated as a trust decision.

Public APIs reviewed: fcopyfile with independent DATA/XATTR selection, and
xattr_flags_from_name with xattr_intent_with_flags for COPY intent. A bounded
public-constant probe returned zero property flags and the default preserve
result for both com.apple.provenance and an invented unknown name. We therefore
do not interpret that default as proof of recognition or an exemption.

Could you clarify:

  1. Which supported metadata postconditions apply to this specific copy use?
    Is source/destination raw-value equality an appropriate invariant for this
    opaque attribute, or may the OS legitimately create different destination
    metadata while preserving the intended security behavior?
  2. Which public properties or APIs can establish the intended destination state
    without parsing/removing private values or weakening OS protections?
  3. The xattr manual's named-wrapper return sentence appears inconsistent with
    its flags-based description/example. What is the supported return-polarity
    contract, and is using the flags-based function the intended interpretation?

This asks for supported semantics, not a bypass or private value format. No
paths, binaries, source, attribute values, keys, account data or logs are attached.

Public references:
https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man3/fcopyfile.3.html
https://github.com/apple-oss-distributions/copyfile/blob/main/xattr_name_with_flags.3
https://github.com/apple-oss-distributions/copyfile/blob/main/xattr_flags.h

3- The xattr manual's named-wrapper return sentence appears inconsistent with its flags-based description/example

I don’t understand this. What do you mean by “named-wrapper return sentence”?

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

Thanks, Quinn. By “named-wrapper” I meant xattr_preserve_for_intent(name, intent), rather than xattr_intent_with_flags(intent, xattr_flags_from_name(name)). That was unclear shorthand.

On rechecking the current SDK manual and Apple's public copyfile manual, both describe a nonzero result as meaning preserve; the flags-based description and example agree. I cannot substantiate the documentation-inconsistency claim from those references, so please disregard question 3. Apologies for the confusion.

Questions 1–2 remain: when copying the exact helper bytes into a new private working directory, may macOS legitimately create different destination com.apple.provenance metadata, and which supported postconditions should software check while preserving OS security and leaving opaque values untouched?

Reference: https://github.com/apple-oss-distributions/copyfile/blob/main/xattr_name_with_flags.3#L54-L65

There’s a general answer here. If an extended attribute was added by the OS but is not otherwise documented then you shouldn’t do anything based on its contents. If you copy an item with such an attribute, you can use the <xattr_flags.h> API to decide whether to copy it or not [1], but you shouldn’t make any decisions based on the content.

Share and Enjoy
—
Quinn “The Eskimo!” @ Developer Technical Support @ Apple
let myEmail = "eskimo" + "1" + "@" + "apple.com"

[1] And that in turn requires you to determine the intent of your copy, which is a very squishy concept.