Add CI validation helpers with explicit signature selection and owned results

include/Domito.MinCrypt.h

@@ -565,6 +565,13 @@ CiSetTrustedOriginClaimId(
 // See docs/ci-validate-file-object.md for evidence and version limitations.
 #define DOMITO_CI_VALIDATE_FLAG_BROADEN_ROOT_ACCEPTANCE 0x00000020UL
 
+// Descriptive experimental bit, not an official or isolated selector flag.
+// Participates in first-success guards in examined 22621/26100 x64 CI bodies;
+// also changes default-path policy and fallback. One 22631 TESTSIGNING-enabled
+// BthPS3 run confirms 0x20|0x80 returns its primary company signer. It is not an
+// arbitrary signer index, guaranteed primary selection, or a production default.
+#define DOMITO_CI_VALIDATE_FLAG_FIRST_SUCCESS_EXPERIMENTAL 0x00000080UL
+
 /**
 *  Given a file object, verify the signature and provide information regarding
 *   the certificates that was used for signing (the entire certificate chain)

include/Domito.h

@@ -254,6 +254,79 @@ DomitoFreePortableExecutableDigest(
     _In_ PVOID pDigestOut
 );
 
+#if (NTDDI_VERSION >= NTDDI_WIN10)
+// Native forwards caller flags unchanged. The experimental x64 mode additionally
+// sets 0x80; it stops after the first accepted candidate in examined CI builds,
+// and also changes other policy/fallback paths. Neither mode selects a publisher
+// or enumerates signatures. No root-acceptance flag is added automatically.
+typedef enum _DOMITO_CI_SIGNATURE_SELECTION
+{
+    DomitoCiSignatureSelectionNative = 0,
+    DomitoCiSignatureSelectionFirstSuccessfulExperimental = 1
+} DOMITO_CI_SIGNATURE_SELECTION;
+
+// Zero-initialize before first use. Both policies own their CI chain allocations,
+// including possible diagnostic allocations on failure. Do not copy as an owner.
+// Hash is a file digest, not a certificate thumbprint. Hash/algorithm/signing time
+// are cleared on failure; policies may retain diagnostics. Check return NTSTATUS.
+typedef struct _DOMITO_CI_VALIDATION_RESULT
+{
+    MINCRYPT_POLICY_INFO PolicyInfo;
+    MINCRYPT_POLICY_INFO TimeStampPolicyInfo;
+    LARGE_INTEGER SigningTime;
+    UINT8 Hash[MINCRYPT_MAX_HASH_LENGTH];
+    UINT32 HashSize;
+    ALG_ID HashAlgId;
+    UINT32 FileObjectValidationFlags; // Flags passed to CI export; zero for embedded helper.
+    UINT8 RequestedSigningLevel;     // File-object helper only.
+} DOMITO_CI_VALIDATION_RESULT, *PDOMITO_CI_VALIDATION_RESULT;
+
+// Safe for NULL or an empty/initialized result; resets all fields after cleanup.
+_IRQL_requires_max_(PASSIVE_LEVEL)
+EXTERN_C
+void
+DomitoFreeCiValidationResult(
+    _Inout_opt_ DOMITO_CI_VALIDATION_RESULT* Result
+);
+
+// Referenced FILE_OBJECT at PASSIVE_LEVEL; keep file bytes stable. Previous result
+// policies are released before reuse, including invalid-argument failures.
+// Supplies a fresh 64-byte hash buffer on every call. FirstSuccessfulExperimental
+// is opt-in and x64-only; other architectures return STATUS_NOT_SUPPORTED for it.
+// Only one selected signer plus its timestamp policy is returned. The caller
+// must enforce its expected certificate and intended trust policy separately.
+_Success_(return >= 0)
+_Must_inspect_result_
+_IRQL_requires_max_(PASSIVE_LEVEL)
+EXTERN_C
+NTSTATUS
+DomitoValidateFileObjectEx(
+    _In_ PFILE_OBJECT FileObject,
+    _In_ UINT32 ValidationFlags,
+    _In_ UINT8 RequestedSigningLevel,
+    _In_ DOMITO_CI_SIGNATURE_SELECTION Selection,
+    _Inout_ DOMITO_CI_VALIDATION_RESULT* Result
+);
+
+// Hash and verify the first WIN_CERTIFICATE in a stable PE buffer. Uses the
+// explicit digest helper's supported contiguous-section/EOF-certificate subset.
+// SHA-1/256/384/512 are explicit; no algorithm retry or catalog fallback occurs.
+// CI may select a nested signature under its algorithm rules: this is not a
+// universal force-primary API. Matching SHA-256 selects the company primary in
+// the tested dual-signed BthPS3 fixture. Caller still checks the returned signer.
+_Success_(return >= 0)
+_Must_inspect_result_
+_IRQL_requires_max_(PASSIVE_LEVEL)
+EXTERN_C
+NTSTATUS
+DomitoValidatePortableExecutableEmbeddedSignature(
+    _In_reads_bytes_(PeSize) const UCHAR* PeBytes,
+    _In_ ULONG PeSize,
+    _In_ ALG_ID HashAlgId,
+    _Inout_ DOMITO_CI_VALIDATION_RESULT* Result
+);
+#endif // NTDDI_VERSION >= NTDDI_WIN10
+
 #define DOMITO_CI_SOURCE_EMBEDDED 1UL
 #define DOMITO_CI_SOURCE_CATALOG  2UL