gowalk-cicd 1.0.183 → 1.0.185

package/README.md

@@ -25,6 +25,8 @@ Writes three core things into your repo:
 
 It also writes:
 
+- `.github/workflows/apple-upload-recovery.yml` — explicit verification-only recovery for a retained iOS upload;
+  it checks the original producer and Apple build before completing that deployment, without rebuilding or uploading
 - `.github/workflows/mobile-candidate.yml` — shipping binaries for ready task PRs
   (dispatch-only while candidate artifacts are off)
 - `.github/workflows/warm-android-cache.yml` — only while Android candidates are enabled: after this
@@ -1225,7 +1227,17 @@ commits completed part transfers with `uploaded: true`, following Apple's
 The IPA endpoint rejected an optional `sourceFileChecksums` SHA_256 object even though
 the generic schema lists that algorithm; the uploader no longer sends that attribute.
 A completed file is reused only when its content-derived filename and size match, and
-any returned file checksum is verified.
+any nonnull returned whole-file checksum is verified. An explicit
+`sourceFileChecksums.file: null` means that the optional whole-file checksum is absent;
+a composite checksum does not substitute for a whole-IPA digest.
+New receipts retain locally computed SHA-256 and
+MD5 so Apple's returned checksum can be compared with the exact transferred bytes.
+
+An upload summary can remain `PROCESSING` after Apple exposes a valid eligible build.
+Completion then requires the unique matching iOS build, marketing version, app and bundle,
+alongside the completed upload asset and matching checksum. A missing, pending, failed or
+ambiguous build remains unconfirmed. The receipt retains `upload_resource_state` separately
+from the verified completion state.
 
 A failed upload emits the typed `apple_build_upload_failed` error annotation with schema
 `gowalk-cicd/apple-build-upload-failed.v2`: `category` (`ipa_invalid`,
@@ -1235,13 +1247,17 @@ A failed upload emits the typed `apple_build_upload_failed` error annotation wit
 the receipt's own identifiers (`cfBundleVersion`, `upload_id`, `file_id`, `state`,
 `provider_status`, `provider_code`, `provider_pointer`). Exception text is never
 published. The job also retains the exact exported IPA as `apple-ipa-<run>-<attempt>`
-(7 days) so a continuation can complete that same upload identity instead of rebuilding
+(7 days), copied without byte changes to the safe archive member `app.ipa`, so punctuation
+in the exported filename cannot block retention. A continuation can complete that upload instead of rebuilding
 different bytes under the same number. Build numbers come from `/builds`,
 `/preReleaseVersions` **and** `/apps/{id}/buildUploads`, so an unfinished or refused
 reservation is never reused; delete such a reservation only after reading it back.
 
-When an iOS producer was cancelled **after** both `Build and transfer iOS binary` and
-`Retain Apple verification handoff` succeeded, version 1.0.183 provides explicit recovery:
+When an iOS deployment failed or was cancelled **after** both `Build and transfer iOS binary`
+and `Retain Apple verification handoff` succeeded, version 1.0.185 provides the managed
+`apple-upload-recovery.yml` workflow. Dispatch it on the repository's default branch with the
+original `producer-run`, `producer-attempt`, `deployment-id` and `handoff-artifact-id` inputs.
+It calls the released helper with those four validated identifiers:
 
 ```bash
 node .github/actions/swift-app/scripts/apple_upload_recovery.cjs \
@@ -1288,7 +1304,8 @@ digest option: it downloads the exact original artifact, verifies GitHub's archi
 and accepts only its bounded `apple-verification.json` member. It authenticates the current
 dispatch separately from the original run, attempt, source, repository, branch and deployment.
 
-Recovery requires a terminal cancelled original run and iOS producer with those two
+Recovery requires a terminal original run: either cancelled with its cancelled iOS producer,
+or failed with a completed successful or failed iOS producer. Both paths require those two
 successful steps in order. A later completed attempt may exist; an active latest attempt
 refuses, including a retry observed immediately before writing the receipt. Fresh Apple
 readback must prove the exact completed upload and file, matching bytes, eligible `VALID`
@@ -1298,10 +1315,13 @@ and the old handoff's metadata and release notes are never replayed. Missing, ex
 mismatched evidence remains refused; do not relabel a receipt or impersonate the original
 `GITHUB_*` environment. Normal delivery still refuses cancelled producers.
 
+The managed workflow retains `apple-recovered-<recovery-run>-<recovery-attempt>` with the
+unchanged `apple-verification.json`, its `.verified.json` proof and derived `.upload-receipt.json`.
+The proof identifies the original producer and the current recovery caller separately.
 Retain the recovery proof, then rerun the **whole original deployment workflow**. Its
 upload-once admission reuses the confirmed iOS receipt and skips the iOS binary. Follow that
 new attempt and any unrelated remaining jobs to completion; recovery does not change the
-original cancelled attempt's conclusion. Read current store state for remaining submission
+original failed or cancelled attempt's conclusion. Read current store state for remaining submission
 work without changing an already accepted submission. This exceptional command adds no
 normal delivery job, polling or latency.
 

package/action/action.yml

@@ -825,17 +825,33 @@ runs:
     # A failed REST upload keeps the exact exported IPA next to its receipt, so a
     # continuation can resume or complete that same upload identity instead of
     # rebuilding different bytes under the number the receipt names.
-    - name: Retain the exported IPA for upload recovery
+    - name: Stage the exported IPA for upload recovery
+      id: ipa-recovery
       if: ${{ always() && inputs.archive == 'true' && inputs.upload == 'true'
             && (steps.upload.outcome != 'success' || inputs.defer-provider-verification == 'true') }}
+      shell: bash
+      run: |
+        shopt -s nullglob
+        ipas=("$RUNNER_TEMP"/export/*.ipa)
+        if [ "${#ipas[@]}" -ne 1 ]; then
+          echo '::error::apple_ipa_recovery_export_count_invalid'
+          exit 1
+        fi
+        retained="$RUNNER_TEMP/apple-ipa-recovery"
+        mkdir -p "$retained"
+        cp "${ipas[0]}" "$retained/app.ipa"
+        cmp -s "${ipas[0]}" "$retained/app.ipa"
+
+    - name: Retain the exported IPA for upload recovery
+      if: ${{ always() && steps.ipa-recovery.outcome == 'success' }}
       uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4
       env:
         NODE_OPTIONS: --require "${{ env.SWIFT_APP_ACTION }}/scripts/artifact_env.cjs"
       with:
         name: apple-ipa-${{ github.run_id }}-${{ github.run_attempt }}
-        path: ${{ runner.temp }}/export/*.ipa
+        path: ${{ runner.temp }}/apple-ipa-recovery/app.ipa
         compression-level: 0 # An IPA is already a ZIP; avoid duplicate compression on the Mac.
-        if-no-files-found: ignore
+        if-no-files-found: error
         retention-days: 7
 
     # The whatsNew backstop. An empty "What's New" makes a version

package/action/scripts/apple_upload_handoff.cjs

@@ -4,6 +4,7 @@ const fs = require('node:fs');
 const {createHash} = require('node:crypto');
 const {join} = require('node:path');
 const github = require('./mobile_release_api.cjs');
+const {historicalProducer, uniqueArtifact} = require('./apple_upload_handoff_history.cjs');
 const SCHEMA = 'gowalk-cicd/apple-upload-handoff.v1';
 const positive = value => Number.isSafeInteger(value) && value > 0;
 const id = value => typeof value === 'string' && /^[A-Za-z0-9-]{1,64}$/.test(value);
@@ -24,6 +25,7 @@ function validate(value) {
       !/^[a-f0-9]{64}$/.test(r.sha256 || '') || r.fileName !== `${r.sha256}.ipa` || !positive(r.fileSize)) {
     fail('handoff_receipt');
   }
+  if (r.md5 !== undefined && (typeof r.md5 !== 'string' || !/^[a-f0-9]{32}$/.test(r.md5))) fail('handoff_receipt');
   if (typeof m.enabled !== 'boolean' || typeof m.only_if_empty !== 'boolean' ||
       typeof m.notes !== 'string' || Buffer.byteLength(m.notes) > 1024 * 1024 || m.notes.includes('\0') ||
       !/^[A-Za-z0-9-]{2,35}$/.test(m.locale || '') || m.enabled && !id(m.version_id)) fail('handoff_metadata');
@@ -63,26 +65,20 @@ async function verifyProducer(value, artifactId, api = github, recoverCancelled
       run.path !== '.github/workflows/deploy.yml' || run.event !== o.event ||
       `refs/heads/${run.head_branch}` !== o.ref || run.repository?.full_name !== o.repository ||
       run.head_repository?.full_name !== o.repository) fail('producer_run');
-  if (recoverCancelled) {
-    const latest = await api.request('GET', `/actions/runs/${o.run_id}`);
-    if (run.status !== 'completed' || run.conclusion !== 'cancelled' || latest.id !== o.run_id ||
-        latest.status !== 'completed' || !positive(latest.run_attempt) || latest.run_attempt < o.run_attempt ||
-        latest.head_sha !== o.source_sha || latest.path !== run.path || latest.event !== o.event ||
-        latest.head_branch !== run.head_branch || latest.repository?.full_name !== o.repository ||
-        latest.head_repository?.full_name !== o.repository) fail('cancelled_producer_run');
-  }
+  if (recoverCancelled) await historicalProducer(o, run, api, fail);
   const result = await api.request('GET', `/actions/runs/${o.run_id}/attempts/${o.run_attempt}/jobs?per_page=100`);
   if (!Array.isArray(result.jobs) || result.jobs.length >= 100) fail('producer_jobs');
   const jobs = result.jobs.filter(job => job.name === 'iOS TestFlight' || job.name?.endsWith('/ iOS TestFlight'));
   // A later symbol-retention failure does not undo these exact completed steps.
   // The producer's original failure remains red; only Apple delivery is reconciled here.
-  const conclusions = recoverCancelled ? ['cancelled'] : ['success', 'failure'];
+  const conclusions = recoverCancelled && run.conclusion === 'cancelled' ? ['cancelled'] : ['success', 'failure'];
   if (jobs.length !== 1 || jobs[0].status !== 'completed' || !conclusions.includes(jobs[0].conclusion) ||
       jobs[0].head_sha !== o.source_sha || !transferred(jobs[0])) fail('producer_job');
   const artifact = await api.request('GET', `/actions/artifacts/${artifactId}`);
   if (artifact.id !== artifactId || artifact.expired !== false || artifact.workflow_run?.id !== o.run_id ||
       artifact.workflow_run?.head_sha !== o.source_sha ||
       artifact.name !== `apple-verification-${o.run_id}-${o.run_attempt}`) fail('producer_artifact');
+  if (recoverCancelled) await uniqueArtifact(o, artifact, api, fail);
 }
 
 async function phase(value, api = github) {

package/action/scripts/apple_upload_handoff.py

@@ -54,7 +54,10 @@ def prepare():
 def write(path, handoff, receipt):
     if receipt.get("stage") != "transferred" or "\n" in str(path) or "\r" in str(path):
         raise ValueError("apple_handoff_transfer_unconfirmed")
-    handoff = {**handoff, "receipt": {name: receipt[name] for name in FIELDS}}
+    fields = {name: receipt[name] for name in FIELDS}
+    if "md5" in receipt:
+        fields["md5"] = receipt["md5"]
+    handoff = {**handoff, "receipt": fields}
     data = (json.dumps(handoff, sort_keys=True, separators=(",", ":")) + "\n").encode()
     path.write_bytes(data)
     digest = hashlib.sha256(data).hexdigest()

package/action/scripts/apple_upload_handoff_history.cjs

@@ -0,0 +1,29 @@
+/* Recheck one terminal historical producer and its unique retained handoff. */
+'use strict';
+const positive = value => Number.isSafeInteger(value) && value > 0;
+
+async function historicalProducer(owner, run, api, fail) {
+  const latest = await api.request('GET', `/actions/runs/${owner.run_id}`);
+  const terminal = ['success', 'failure', 'cancelled', 'timed_out', 'action_required',
+    'neutral', 'skipped', 'stale', 'startup_failure'];
+  if (run.status !== 'completed' || !['cancelled', 'failure'].includes(run.conclusion) ||
+      latest.id !== owner.run_id || latest.status !== 'completed' || !terminal.includes(latest.conclusion) ||
+      !positive(latest.run_attempt) || latest.run_attempt < owner.run_attempt ||
+      latest.run_attempt === owner.run_attempt && latest.conclusion !== run.conclusion ||
+      latest.head_sha !== owner.source_sha || latest.path !== run.path || latest.event !== owner.event ||
+      latest.head_branch !== run.head_branch || latest.repository?.full_name !== owner.repository ||
+      latest.head_repository?.full_name !== owner.repository) fail('historical_producer_run');
+}
+
+async function uniqueArtifact(owner, artifact, api, fail) {
+  const result = await api.request('GET', `/actions/runs/${owner.run_id}/artifacts?per_page=100`);
+  if (!Array.isArray(result.artifacts) || result.artifacts.length >= 100 ||
+      !Number.isSafeInteger(result.total_count) || result.total_count !== result.artifacts.length) fail('producer_artifact');
+  const selected = result.artifacts.filter(row => row.name === artifact.name);
+  if (selected.length !== 1 || selected[0].id !== artifact.id || selected[0].expired !== false ||
+      selected[0].workflow_run?.id !== owner.run_id || selected[0].workflow_run?.head_sha !== owner.source_sha ||
+      !/^sha256:[a-f0-9]{64}$/.test(artifact.digest || '') || selected[0].digest !== artifact.digest ||
+      !positive(artifact.size_in_bytes) || selected[0].size_in_bytes !== artifact.size_in_bytes) fail('producer_artifact');
+}
+
+module.exports = {historicalProducer, uniqueArtifact};

package/action/scripts/apple_upload_proof.cjs

@@ -0,0 +1,117 @@
+/* Read-only proof of one transferred IPA, including Apple's separately processed build. */
+'use strict';
+const identifier = value => typeof value === 'string' && /^[A-Za-z0-9-]{1,64}$/.test(value);
+
+function entity(response, fail, code) {
+  const row = response?.data;
+  if (!row || typeof row !== 'object' || Array.isArray(row) ||
+      row.attributes !== undefined && (!row.attributes || typeof row.attributes !== 'object') ||
+      row.relationships !== undefined && (!row.relationships || typeof row.relationships !== 'object')) fail(code);
+  return row;
+}
+
+function collection(response, fail, code) {
+  const rows = response?.data, total = response?.meta?.paging?.total;
+  if (!Array.isArray(rows) || rows.some(row => !row || typeof row !== 'object' || Array.isArray(row)) ||
+      rows.length >= 200 || !response.links || typeof response.links !== 'object' ||
+      Array.isArray(response.links) || response.links.next ||
+      total !== undefined && (!Number.isSafeInteger(total) || total !== rows.length)) fail(code);
+  return rows;
+}
+
+function checksum(attributes, receipt, fail) {
+  const checksums = attributes.sourceFileChecksums;
+  if (checksums !== undefined && (!checksums || typeof checksums !== 'object' || Array.isArray(checksums))) {
+    fail('file_checksum_unverified');
+  }
+  const file = checksums?.file;
+  if (file === undefined || file === null) return;
+  const digest = file?.algorithm === 'SHA_256' ? receipt.sha256 :
+    file?.algorithm === 'MD5' ? receipt.md5 : null;
+  const width = file?.algorithm === 'SHA_256' ? 64 : 32;
+  if (typeof digest !== 'string' || !new RegExp(`^[a-f0-9]{${width}}$`).test(digest)) {
+    fail('file_checksum_unverified');
+  }
+  const values = [digest, digest.toUpperCase(), Buffer.from(digest, 'hex').toString('base64')];
+  if (!values.includes(file.hash)) fail('file_checksum_unverified');
+}
+
+async function fileProof(receipt, get, fail) {
+  const response = await get(`/buildUploads/${receipt.upload_id}/buildUploadFiles`);
+  const assets = collection(response, fail, 'file_membership').filter(row => row.attributes?.assetType === 'ASSET');
+  if (assets.length !== 1 || assets[0].id !== receipt.file_id) fail('file_membership');
+  const file = entity(await get(`/buildUploadFiles/${receipt.file_id}`), fail, 'file_unverified');
+  const attrs = file.attributes || {};
+  if (file?.id !== receipt.file_id || attrs.assetType !== 'ASSET' ||
+      attrs.fileName !== receipt.fileName || attrs.fileSize !== receipt.fileSize) fail('file_unverified');
+  if (attrs.assetDeliveryState?.state === 'FAILED' || attrs.assetDeliveryState?.errors?.length) {
+    fail('processing_failed');
+  }
+  if (attrs.assetDeliveryState?.state !== 'COMPLETE') return false;
+  checksum(attrs, receipt, fail);
+  return true;
+}
+
+async function inventoryBuild(receipt, get, fail) {
+  const query = new URLSearchParams({'filter[app]': receipt.app_id, 'filter[version]': receipt.cfBundleVersion,
+    include: 'preReleaseVersion,app', limit: '200'});
+  const response = await get(`/builds?${query}`), rows = collection(response, fail, 'build_inventory_unverified');
+  const included = response.included;
+  if (!Array.isArray(included) || included.some(row => !row || typeof row !== 'object' || Array.isArray(row))) {
+    fail('build_inventory_unverified');
+  }
+  const ids = new Set(), matches = [];
+  for (const row of rows) {
+    if (!identifier(row.id) || ids.has(row.id) || row.attributes?.version !== receipt.cfBundleVersion) {
+      fail('build_inventory_unverified');
+    }
+    ids.add(row.id);
+    const trainId = row.relationships?.preReleaseVersion?.data?.id;
+    const appId = row.relationships?.app?.data?.id;
+    const trains = included.filter(item => item.type === 'preReleaseVersions' && item.id === trainId);
+    const apps = included.filter(item => item.type === 'apps' && item.id === appId);
+    if (!identifier(trainId) || trains.length !== 1 || apps.length !== 1 || appId !== receipt.app_id ||
+        apps[0].attributes?.bundleId !== receipt.bundle_id) fail('build_inventory_unverified');
+    if (trains[0].attributes?.version === receipt.cfBundleShortVersionString &&
+        trains[0].attributes?.platform === 'IOS') matches.push(row.id);
+  }
+  if (matches.length > 1) fail('build_ambiguous');
+  return matches[0] || null;
+}
+
+async function buildProof(buildId, receipt, get, fail) {
+  const build = entity(await get(`/builds/${buildId}`), fail, 'build_unverified');
+  const attrs = build.attributes || {};
+  if (build?.id !== buildId || attrs.version !== receipt.cfBundleVersion) fail('build_unverified');
+  if (['FAILED', 'INVALID'].includes(attrs.processingState)) fail('processing_failed');
+  if (attrs.processingState === 'PROCESSING') return null;
+  if (attrs.processingState !== 'VALID' || attrs.buildAudienceType !== 'APP_STORE_ELIGIBLE') {
+    fail('build_unverified');
+  }
+  const app = entity(await get(`/builds/${buildId}/app`), fail, 'app_unverified');
+  if (app?.id !== receipt.app_id || app.attributes?.bundleId !== receipt.bundle_id) fail('app_unverified');
+  const train = entity(await get(`/builds/${buildId}/preReleaseVersion`), fail, 'train_unverified');
+  if (!identifier(train?.id) || train.attributes?.platform !== 'IOS' ||
+      train.attributes?.version !== receipt.cfBundleShortVersionString) fail('train_unverified');
+  return {build_id: buildId, app_id: app.id, version: receipt.cfBundleShortVersionString,
+    build: receipt.cfBundleVersion, upload_id: receipt.upload_id};
+}
+
+async function observe(receipt, get, fail) {
+  const upload = entity(await get(`/buildUploads/${receipt.upload_id}?include=build`), fail, 'upload_unverified');
+  const attrs = upload?.attributes || {}, state = attrs.state?.state;
+  if (upload?.id !== receipt.upload_id || attrs.platform !== 'IOS' ||
+      attrs.cfBundleVersion !== receipt.cfBundleVersion ||
+      attrs.cfBundleShortVersionString !== receipt.cfBundleShortVersionString) fail('upload_unverified');
+  if (state === 'FAILED' || attrs.state?.errors?.length) fail('processing_failed');
+  if (!['COMPLETE', 'PROCESSING'].includes(state)) return null;
+  if (!await fileProof(receipt, get, fail)) return null;
+  const relationship = upload.relationships?.build?.data;
+  if (relationship && !identifier(relationship.id)) fail('build_unverified');
+  const buildId = relationship?.id || await inventoryBuild(receipt, get, fail);
+  if (!buildId) return null;
+  const proof = await buildProof(buildId, receipt, get, fail);
+  return proof && {...proof, upload_resource_state: state};
+}
+
+module.exports = {observe};

package/action/scripts/apple_upload_proof.py

@@ -0,0 +1,159 @@
+"""Read-only exact upload/file/build proof for the legacy synchronous Python entrypoint."""
+import base64
+import re
+
+from upload_receipt import UploadError
+
+
+def refuse(code):
+    raise UploadError(code, "Apple upload completion was not independently verified")
+
+
+def entity(response, code):
+    row = response.get("data") if isinstance(response, dict) else None
+    if (not isinstance(row, dict) or not isinstance(row.get("attributes", {}), dict)
+            or not isinstance(row.get("relationships", {}), dict)):
+        refuse(code)
+    return row
+
+
+def collection(response, code):
+    if not isinstance(response, dict):
+        refuse(code)
+    rows, links = response.get("data"), response.get("links")
+    total = (response.get("meta") or {}).get("paging", {}).get("total")
+    if (not isinstance(rows, list) or any(not isinstance(row, dict)
+            or not isinstance(row.get("attributes", {}), dict)
+            or not isinstance(row.get("relationships", {}), dict) for row in rows)
+            or len(rows) >= 200 or not isinstance(links, dict) or links.get("next")
+            or total is not None and (type(total) is not int or total != len(rows))):
+        refuse(code)
+    return rows
+
+
+def checksum(attributes, receipt):
+    checksums = attributes.get("sourceFileChecksums", {})
+    if not isinstance(checksums, dict):
+        refuse("file_checksum_unverified")
+    if "file" not in checksums:
+        return
+    file = checksums["file"]
+    if file is None:
+        return
+    if not isinstance(file, dict):
+        refuse("file_checksum_unverified")
+    algorithm = file.get("algorithm")
+    digest = receipt.get("sha256") if algorithm == "SHA_256" else receipt.get("md5") if algorithm == "MD5" else None
+    width = 64 if algorithm == "SHA_256" else 32
+    if not isinstance(digest, str) or not re.fullmatch(r"[a-f0-9]{" + str(width) + "}", digest):
+        refuse("file_checksum_unverified")
+    values = (digest, digest.upper(), base64.b64encode(bytes.fromhex(digest)).decode())
+    if file.get("hash") not in values:
+        refuse("file_checksum_unverified")
+
+
+def file_proof(receipt, api):
+    response = api("GET", f"/buildUploads/{receipt['upload_id']}/buildUploadFiles")
+    assets = [row for row in collection(response, "file_membership")
+              if (row.get("attributes") or {}).get("assetType") == "ASSET"]
+    if len(assets) != 1 or assets[0].get("id") != receipt["file_id"]:
+        refuse("file_membership")
+    file = entity(api("GET", f"/buildUploadFiles/{receipt['file_id']}"), "file_unverified")
+    attrs = file.get("attributes") or {}
+    if (file.get("id") != receipt["file_id"] or attrs.get("assetType") != "ASSET"
+            or any(attrs.get(key) != receipt[key] for key in ("fileName", "fileSize"))):
+        refuse("file_unverified")
+    state = attrs.get("assetDeliveryState") or {}
+    if not isinstance(state, dict):
+        refuse("file_unverified")
+    if state.get("state") == "FAILED" or state.get("errors"):
+        refuse("processing_failed")
+    if state.get("state") != "COMPLETE":
+        return False
+    checksum(attrs, receipt)
+    return True
+
+
+def inventory_build(receipt, api):
+    response = api("GET", "/builds", params={"filter[app]": receipt["app_id"],
+                   "filter[version]": receipt["cfBundleVersion"], "include": "preReleaseVersion,app", "limit": 200})
+    rows = collection(response, "build_inventory_unverified")
+    included = response.get("included")
+    if (not isinstance(included, list) or any(not isinstance(item, dict)
+            or not isinstance(item.get("attributes", {}), dict) for item in included)):
+        refuse("build_inventory_unverified")
+    identifiers, matches = set(), []
+    for row in rows:
+        build_id = row.get("id")
+        if (not isinstance(build_id, str) or not re.fullmatch(r"[A-Za-z0-9-]{1,64}", build_id)
+                or build_id in identifiers
+                or (row.get("attributes") or {}).get("version") != receipt["cfBundleVersion"]):
+            refuse("build_inventory_unverified")
+        identifiers.add(build_id)
+        relationships = row.get("relationships") or {}
+        for name in ("preReleaseVersion", "app"):
+            link = relationships.get(name)
+            if (not isinstance(link, dict) or not isinstance(link.get("data"), dict)):
+                refuse("build_inventory_unverified")
+        train_id = ((relationships.get("preReleaseVersion") or {}).get("data") or {}).get("id")
+        app_id = ((relationships.get("app") or {}).get("data") or {}).get("id")
+        trains = [item for item in included if item.get("type") == "preReleaseVersions" and item.get("id") == train_id]
+        apps = [item for item in included if item.get("type") == "apps" and item.get("id") == app_id]
+        if (not isinstance(train_id, str) or not re.fullmatch(r"[A-Za-z0-9-]{1,64}", train_id)
+                or len(trains) != 1 or len(apps) != 1 or app_id != receipt["app_id"]
+                or (apps[0].get("attributes") or {}).get("bundleId") != receipt["bundle_id"]):
+            refuse("build_inventory_unverified")
+        attrs = trains[0].get("attributes") or {}
+        if attrs.get("version") == receipt["cfBundleShortVersionString"] and attrs.get("platform") == "IOS":
+            matches.append(build_id)
+    if len(matches) > 1:
+        refuse("build_ambiguous")
+    return matches[0] if matches else None
+
+
+def build_proof(build_id, receipt, api):
+    build = entity(api("GET", f"/builds/{build_id}"), "build_unverified")
+    attrs = build.get("attributes") or {}
+    if build.get("id") != build_id or attrs.get("version") != receipt["cfBundleVersion"]:
+        refuse("build_unverified")
+    if attrs.get("processingState") in ("FAILED", "INVALID"):
+        refuse("processing_failed")
+    if attrs.get("processingState") == "PROCESSING":
+        return None
+    if attrs.get("processingState") != "VALID" or attrs.get("buildAudienceType") != "APP_STORE_ELIGIBLE":
+        refuse("build_unverified")
+    app = entity(api("GET", f"/builds/{build_id}/app"), "app_unverified")
+    if app.get("id") != receipt["app_id"] or (app.get("attributes") or {}).get("bundleId") != receipt["bundle_id"]:
+        refuse("app_unverified")
+    train = entity(api("GET", f"/builds/{build_id}/preReleaseVersion"), "train_unverified")
+    train_attrs = train.get("attributes") or {}
+    if (not isinstance(train.get("id"), str) or not re.fullmatch(r"[A-Za-z0-9-]{1,64}", train["id"])
+            or train_attrs.get("platform") != "IOS"
+            or train_attrs.get("version") != receipt["cfBundleShortVersionString"]):
+        refuse("train_unverified")
+    return {"build_id": build_id}
+
+
+def observe(receipt, api):
+    response = api("GET", f"/buildUploads/{receipt['upload_id']}", params={"include": "build"})
+    upload = entity(response, "upload_unverified")
+    attrs = upload.get("attributes") or {}
+    state = attrs.get("state") or {}
+    if not isinstance(state, dict):
+        refuse("upload_unverified")
+    if (upload.get("id") != receipt["upload_id"] or attrs.get("platform") != "IOS"
+            or any(attrs.get(key) != receipt[key] for key in ("cfBundleVersion", "cfBundleShortVersionString"))):
+        refuse("upload_unverified")
+    if state.get("state") == "FAILED" or state.get("errors"):
+        refuse("processing_failed")
+    if state.get("state") not in ("COMPLETE", "PROCESSING") or not file_proof(receipt, api):
+        return None, state.get("state")
+    link = (upload.get("relationships") or {}).get("build")
+    if link is not None and not isinstance(link, dict):
+        refuse("build_unverified")
+    relationship = (link or {}).get("data")
+    if relationship and (not isinstance(relationship, dict) or not isinstance(relationship.get("id"), str)
+                         or not re.fullmatch(r"[A-Za-z0-9-]{1,64}", relationship["id"])):
+        refuse("build_unverified")
+    build_id = relationship["id"] if relationship else inventory_build(receipt, api)
+    return (build_proof(build_id, receipt, api) if build_id else None), state.get("state")

package/action/scripts/apple_upload_recovery.cjs

@@ -1,4 +1,4 @@
-/* Explicit Actions recovery of a cancelled producer's authenticated handoff; never upload or metadata. */
+/* Explicit Actions recovery of a terminal producer's authenticated handoff; never upload or metadata. */
 'use strict';
 const fs = require('node:fs');
 const {createHash} = require('node:crypto');
@@ -6,6 +6,7 @@ const {inflateRawSync} = require('node:zlib');
 const github = require('./mobile_release_api.cjs');
 const handoff = require('./apple_upload_handoff.cjs');
 const verifier = require('./apple_upload_verify.cjs');
+const {pinnedArtifact, evidence} = require('./apple_upload_recovery_evidence.cjs');
 const LIMIT = 2 * 1024 * 1024;
 const positive = value => Number.isSafeInteger(value) && value > 0;
 const fail = code => handoff.fail(`recovery_${code}`);
@@ -83,7 +84,8 @@ async function current(env, api) {
       run.repository?.full_name !== repository || run.head_repository?.full_name !== repository ||
       !/^\.github\/workflows\/[\w.-]+\.ya?ml$/.test(run.path || '') ||
       env.GITHUB_WORKFLOW_REF !== `${repository}/${run.path}@${env.GITHUB_REF}`) fail('caller_unverified');
-  return {run_id: runId, run_attempt: attempt, repository, ref: env.GITHUB_REF};
+  return {run_id: runId, run_attempt: attempt, repository, ref: env.GITHUB_REF,
+    source_sha: env.GITHUB_SHA, workflow_path: run.path, event: run.event};
 }
 
 async function recover({runId, attempt, deploymentId, artifactId}, dependencies = {}) {
@@ -91,7 +93,7 @@ async function recover({runId, attempt, deploymentId, artifactId}, dependencies
   const env = dependencies.env || process.env, api = dependencies.api || github;
   const caller = await current(env, api);
   if (runId === caller.run_id) fail('caller_invalid');
-  const artifact = await api.request('GET', `/actions/artifacts/${artifactId}`);
+  const artifact = structuredClone(await api.request('GET', `/actions/artifacts/${artifactId}`));
   if (artifact.id !== artifactId || artifact.expired !== false || artifact.workflow_run?.id !== runId ||
       artifact.name !== `apple-verification-${runId}-${attempt}`) fail('artifact_identity');
   const bytes = await download(artifact, env, dependencies.fetch || fetch);
@@ -101,20 +103,25 @@ async function recover({runId, attempt, deploymentId, artifactId}, dependencies
   if (owner.repository !== caller.repository || owner.ref !== caller.ref || owner.run_id !== runId ||
       owner.run_attempt !== attempt || owner.deployment_id !== deploymentId ||
       owner.source_sha !== artifact.workflow_run?.head_sha) fail('handoff_owner');
-  const result = await verifier.verify(value, artifactId, 900, {...dependencies, api, recoverCancelled: true});
-  return {...result, schema: 'gowalk-cicd/apple-upload-recovered.v1', producer_run: runId,
+  const result = await verifier.verify(value, artifactId, 900,
+    {...dependencies, api: pinnedArtifact(api, artifact), recoverCancelled: true});
+  const proof = {...result, schema: 'gowalk-cicd/apple-upload-recovered.v1', producer_run: runId,
     repository: owner.repository, producer_source_sha: owner.source_sha,
     producer_ref: owner.ref, producer_event: owner.event,
     artifact_id: artifactId, artifact_digest: artifact.digest,
     handoff_sha256: createHash('sha256').update(bytes).digest('hex'),
     ipa_sha256: value.receipt.sha256, file_id: value.receipt.file_id,
-    recovery_run: caller.run_id, recovery_attempt: caller.run_attempt};
+    recovery_run: caller.run_id, recovery_attempt: caller.run_attempt,
+    recovery_source_sha: caller.source_sha, recovery_ref: caller.ref,
+    recovery_event: caller.event, recovery_workflow_path: caller.workflow_path};
+  if (dependencies.writeEvidence === true) Object.assign(proof, evidence(bytes, value, proof, env));
+  return proof;
 }
 
 async function main() {
   if (process.argv.length !== 6) fail('arguments');
   const [runId, attempt, deploymentId, artifactId] = process.argv.slice(2).map(Number);
-  console.log(JSON.stringify(await recover({runId, attempt, deploymentId, artifactId})));
+  console.log(JSON.stringify(await recover({runId, attempt, deploymentId, artifactId}, {writeEvidence: true})));
 }
 
 if (require.main === module) main().catch(error => {

package/action/scripts/apple_upload_recovery_evidence.cjs

@@ -0,0 +1,38 @@
+/* Preserve the exact authenticated handoff and record separately owned verification evidence. */
+'use strict';
+const fs = require('node:fs');
+const {join} = require('node:path');
+const handoff = require('./apple_upload_handoff.cjs');
+const fail = code => handoff.fail(`recovery_${code}`);
+
+function pinnedArtifact(api, original) {
+  return {...api, request: async (method, path, ...args) => {
+    const result = await api.request(method, path, ...args);
+    if (path === `/actions/artifacts/${original.id}` && (result.id !== original.id ||
+        result.digest !== original.digest || result.size_in_bytes !== original.size_in_bytes ||
+        result.expired !== false || result.name !== original.name ||
+        result.workflow_run?.id !== original.workflow_run.id ||
+        result.workflow_run?.head_sha !== original.workflow_run.head_sha)) fail('artifact_changed');
+    return result;
+  }};
+}
+
+function evidence(bytes, value, proof, env) {
+  if (!env.RUNNER_TEMP || /[\r\n]/.test(env.RUNNER_TEMP)) fail('evidence_path');
+  const directory = join(env.RUNNER_TEMP, 'apple-upload-recovery');
+  fs.mkdirSync(directory, {recursive: true, mode: 0o700});
+  const original = join(directory, 'apple-verification.json');
+  const receipt = `${original}.upload-receipt.json`, verified = `${original}.verified.json`;
+  fs.writeFileSync(original, bytes, {mode: 0o600});
+  if (!fs.readFileSync(original).equals(bytes)) fail('evidence_identity');
+  fs.writeFileSync(receipt, JSON.stringify({...value.receipt, stage: 'complete', state: 'COMPLETE',
+    build_id: proof.build_id, upload_resource_state: proof.upload_resource_state,
+    processing_seconds: proof.processing_seconds}, null, 2) + '\n', {mode: 0o600});
+  fs.writeFileSync(verified, JSON.stringify(proof, null, 2) + '\n', {mode: 0o600});
+  if (env.GITHUB_OUTPUT) fs.appendFileSync(env.GITHUB_OUTPUT,
+    `verified=true\nbuild-id=${proof.build_id}\nartifact-directory=${directory}\n` +
+    `handoff-path=${original}\nreceipt-path=${receipt}\nverified-proof-path=${verified}\n`);
+  return {artifact_directory: directory, handoff_path: original, receipt_path: receipt, verified_proof_path: verified};
+}
+
+module.exports = {pinnedArtifact, evidence};

package/action/scripts/apple_upload_verify.cjs

@@ -5,6 +5,7 @@ const {parseArgs} = require('node:util');
 const {setTimeout: delay} = require('node:timers/promises');
 const github = require('./mobile_release_api.cjs');
 const apple = require('./reconcile_apple_upload.cjs');
+const provider = require('./apple_upload_proof.cjs');
 const handoff = require('./apple_upload_handoff.cjs');
 
 function credential(env = process.env) {
@@ -15,25 +16,7 @@ function credential(env = process.env) {
 }
 
 async function observe(receipt, get) {
-  const path = `/buildUploads/${receipt.upload_id}?include=build`, response = await get(path);
-  const upload = response.data, attrs = upload?.attributes || {};
-  if (upload?.id !== receipt.upload_id || attrs.cfBundleVersion !== receipt.cfBundleVersion ||
-      attrs.cfBundleShortVersionString !== receipt.cfBundleShortVersionString) handoff.fail('upload_identity');
-  if (attrs.state?.state === 'FAILED') handoff.fail('processing_failed');
-  if (attrs.state?.state !== 'COMPLETE') return null;
-  const buildId = upload.relationships?.build?.data?.id;
-  if (!/^[A-Za-z0-9-]{1,64}$/.test(buildId || '')) handoff.fail('build_identity');
-  const buildPath = `/builds/${buildId}`, build = await get(buildPath);
-  if (['FAILED', 'INVALID'].includes(build.data?.attributes?.processingState)) handoff.fail('processing_failed');
-  if (build.data?.attributes?.processingState === 'PROCESSING') return null;
-  const files = await get(`/buildUploads/${receipt.upload_id}/buildUploadFiles`);
-  const assets = files.data?.filter(row => row.attributes?.assetType === 'ASSET');
-  if (!Array.isArray(assets) || files.links?.next || assets.length !== 1 || assets[0].id !== receipt.file_id) {
-    handoff.fail('file_membership');
-  }
-  // Preserve the existing independent complete-file, VALID/eligible build and actual app readbacks.
-  return apple.verifyApple(receipt, requested => requested === path ? response :
-    requested === buildPath ? build : get(requested));
+  return provider.observe(receipt, get, handoff.fail);
 }
 
 async function verify(value, artifactId, timeout, dependencies = {}) {
@@ -71,7 +54,8 @@ async function main() {
   handoff.metadata(value);
   const receiptPath = `${positionals[0]}.upload-receipt.json`;
   fs.writeFileSync(receiptPath, JSON.stringify({...value.receipt, stage: 'complete', state: 'COMPLETE',
-    build_id: proof.build_id, processing_seconds: proof.processing_seconds}, null, 2) + '\n');
+    build_id: proof.build_id, upload_resource_state: proof.upload_resource_state,
+    processing_seconds: proof.processing_seconds}, null, 2) + '\n');
   if (/[\r\n]/.test(receiptPath)) handoff.fail('receipt_path');
   if (process.env.GITHUB_OUTPUT) fs.appendFileSync(process.env.GITHUB_OUTPUT,
     `verified=true\nbuild-id=${proof.build_id}\nproducer-attempt=${proof.producer_attempt}\n` +

package/action/scripts/reconcile_apple_upload.cjs

@@ -3,6 +3,7 @@
 const fs = require('node:fs');
 const crypto = require('node:crypto');
 const github = require('./mobile_release_api.cjs');
+const provider = require('./apple_upload_proof.cjs');
 
 const RECEIPT = 'gowalk-cicd/apple-build-upload-receipt.v1';
 const OWNER = 'gowalk-cicd/mobile-upload-owner.v1';
@@ -20,6 +21,9 @@ function readReceipt(path) {
       !/^\d+(\.\d+){1,2}$/.test(data.cfBundleShortVersionString || '') ||
       !/^[a-f0-9]{64}$/.test(data.sha256 || '') || data.fileName !== `${data.sha256}.ipa` ||
       !Number.isSafeInteger(data.fileSize) || data.fileSize <= 0) refuse('receipt_invalid');
+  if (data.md5 !== undefined && (typeof data.md5 !== 'string' || !/^[a-f0-9]{32}$/.test(data.md5))) {
+    refuse('receipt_invalid');
+  }
   return data;
 }
 
@@ -69,26 +73,9 @@ async function appleGet(path, key = {pem: process.env.ASC_KEY_P8, id: process.en
 }
 
 async function verifyApple(receipt, get = appleGet) {
-  const upload = (await get(`/buildUploads/${receipt.upload_id}?include=build`)).data;
-  const attributes = upload?.attributes || {};
-  const buildId = upload?.relationships?.build?.data?.id;
-  if (upload?.id !== receipt.upload_id || attributes.state?.state !== 'COMPLETE' ||
-      attributes.cfBundleVersion !== receipt.cfBundleVersion ||
-      attributes.cfBundleShortVersionString !== receipt.cfBundleShortVersionString ||
-      !/^[A-Za-z0-9-]{1,64}$/.test(buildId || '')) refuse('upload_unverified');
-  const file = (await get(`/buildUploadFiles/${receipt.file_id}`)).data;
-  if (file?.id !== receipt.file_id || file.attributes?.assetType !== 'ASSET' ||
-      file.attributes.fileName !== receipt.fileName ||
-      file.attributes.fileSize !== receipt.fileSize ||
-      file.attributes.assetDeliveryState?.state !== 'COMPLETE') refuse('file_unverified');
-  const build = (await get(`/builds/${buildId}`)).data;
-  if (build?.id !== buildId || build.attributes?.processingState !== 'VALID' ||
-      build.attributes?.buildAudienceType !== 'APP_STORE_ELIGIBLE' ||
-      build.attributes?.version !== receipt.cfBundleVersion) refuse('build_unverified');
-  const app = (await get(`/builds/${buildId}/app`)).data;
-  if (app?.id !== receipt.app_id || app.attributes?.bundleId !== receipt.bundle_id) refuse('app_unverified');
-  return {build_id: buildId, app_id: app.id, version: receipt.cfBundleShortVersionString,
-    build: receipt.cfBundleVersion, upload_id: receipt.upload_id};
+  const proof = await provider.observe(receipt, get, refuse);
+  if (!proof) refuse('processing_pending');
+  return proof;
 }
 
 async function reconcile(deploymentId, runId, attempt, path, api = github, get = appleGet) {

package/action/scripts/upload_build.py

@@ -18,6 +18,7 @@ import requests
 import upload_checksums
 import upload_receipt
 import apple_upload_handoff
+import apple_upload_proof
 from upload_receipt import Receipt, UploadError
 
 # Provider refusals the uploader classifies itself instead of letting the shared
@@ -53,12 +54,16 @@ def identity(ipa: Path) -> dict:
             info = plistlib.loads(archive.read(names[0]))
     except (zipfile.BadZipFile, plistlib.InvalidFileException, KeyError) as exc:
         raise UploadError("ipa_invalid", "IPA is not a readable app archive") from exc
+    sha256, md5 = hashlib.sha256(), hashlib.md5()
     with ipa.open("rb") as stream:
-        digest = hashlib.file_digest(stream, "sha256").hexdigest()
+        for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+            sha256.update(chunk)
+            md5.update(chunk)
+    digest = sha256.hexdigest()
     return {"bundle_id": str(info["CFBundleIdentifier"]),
             "cfBundleVersion": str(info["CFBundleVersion"]),
             "cfBundleShortVersionString": str(info["CFBundleShortVersionString"]),
-            "sha256": digest, "fileName": digest + ".ipa", "fileSize": ipa.stat().st_size}
+            "sha256": digest, "md5": md5.hexdigest(), "fileName": digest + ".ipa", "fileSize": ipa.stat().st_size}
 
 
 def upload_record(app_id: str, info: dict) -> dict:
@@ -176,17 +181,12 @@ def deliver(ipa: Path, report: Path, timeout: int, handoff: Path | None = None)
     processing_started = time.monotonic()
     deadline = processing_started + timeout
     while True:
-        current = api("GET", f"/buildUploads/{record['id']}", params={"include": "build"})["data"]
-        state = ((current.get("attributes") or {}).get("state") or {}).get("state")
-        build_id = (((current.get("relationships") or {}).get("build") or {}).get("data") or {}).get("id")
-        if state == "COMPLETE":
-            return receipt.update("complete", state=state, build_id=build_id,
+        proof, state = apple_upload_proof.observe(receipt.data, api)
+        if proof:
+            return receipt.update("complete", state="COMPLETE", upload_resource_state=state, **proof,
                                   processing_seconds=round(time.monotonic() - processing_started, 3))
-        receipt.update("processing", state=state, build_id=build_id,
+        receipt.update("processing", state=state,
                        processing_seconds=round(time.monotonic() - processing_started, 3))
-        if state == "FAILED":
-            raise UploadError("processing_failed",
-                              "Apple build upload failed processing; inspect the upload ID's provider errors")
         if time.monotonic() >= deadline:
             raise UploadError("processing_pending",
                               "Apple build processing is pending; reuse this upload ID on continuation")

package/docs/CONFIGURATION.md

@@ -62,7 +62,11 @@ Compose service must pass `BACKEND_PUBLIC_BASE_URL` into its container and use i
 The same named repository inputs reach the feature-branch backend preview in `deploy.yml`.
 
 The supported managed files are `deploy.yml`, `mobile-candidate.yml`,
-`warm-android-cache.yml`, `deploy-web.yml` and `deploy-backend.yml`. The installer no longer adds
+`apple-upload-recovery.yml`, `warm-android-cache.yml`, `deploy-web.yml` and `deploy-backend.yml`.
+The installer adds the dispatch-only `apple-upload-recovery.yml` when the rendered mobile
+deployment supports iOS; explicit Android-only deployment excludes it. It preserves recovery
+workflow overrides and removes only an unmodified generated copy when iOS is no longer supported.
+The installer no longer adds
 `deploy-web.yml`, and adds `warm-android-cache.yml` only while candidate artifacts are enabled
 and `mobile.platforms` is not `ios`;
 it removes such a file that is still the unmodified generated one with no overrides,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gowalk-cicd",
-  "version": "1.0.183",
+  "version": "1.0.185",
   "description": "Zero-config GitHub Actions delivery for iOS TestFlight and Android Google Play.",
   "type": "module",
   "bin": {

package/remedies.json

@@ -2,8 +2,8 @@
   {
     "schema": "gowalk-cicd/apple-build-upload-failed.v2",
     "code": "processing_pending",
-    "fixed_in": "1.0.164",
-    "remedy": "Keep the original IPA and apple-build-upload receipt. If Apple later validates the exact upload, run reconcile_apple_upload.cjs in an authorized GitHub Actions recovery job with the original deployment, run, attempt and artifact receipt. It proves the failed owner, completed file, valid build and matching app before marking the deployment uploaded. Rerun the whole original deploy workflow after the readback; never upload a second binary or hand-edit the deployment receipt."
+    "fixed_in": "1.0.184",
+    "remedy": "Keep the original IPA and apple-build-upload receipt. From 1.0.184 recovery stages unchanged bytes as app.ipa so punctuation in the export filename cannot block retention. A PROCESSING upload summary can complete only after fresh proof of its completed matching asset/checksum and unique valid eligible iOS build, exact app/bundle and marketing version. Future receipts carry local MD5 as well as SHA-256. Run reconcile_apple_upload.cjs only in an authorized Actions recovery job with the original deployment, run, attempt and retained receipt; it never uploads. Read its owner completion back, then rerun the whole original deploy workflow. Missing original bytes or checksum proof remain unverified; never invent the digest, re-upload another binary under the same number or hand-edit the owner."
   },
   {
     "schema": "gowalk-cicd/mobile-release-refused.v1",
@@ -26,8 +26,8 @@
   {
     "schema": "gowalk-cicd/mobile-release-refused.v1",
     "code": "mobile_release_upload_unconfirmed_read_back_retained_binary_before_retry",
-    "fixed_in": "1.0.183",
-    "remedy": "Preserve the original upload owner and artifacts. If an iOS producer was cancelled after both Build and transfer iOS binary and Retain Apple verification handoff succeeded, use apple_upload_recovery.cjs RUN ATTEMPT DEPLOYMENT ARTIFACT from an authorized default-branch workflow_dispatch Actions job. It downloads and authenticates the original artifact, proves the terminal original and latest run, and reads fresh Apple upload/file/build/app evidence before reconciling that deployment. It never rebuilds, uploads or replays metadata. Retain its recovery proof, then rerun the whole original deployment workflow: admission reuses the uploaded receipt without another iOS binary. The old cancellation remains historical evidence; follow the new attempt to completion. Missing or mismatched evidence still refuses."
+    "fixed_in": "1.0.185",
+    "remedy": "Preserve the original upload owner and artifacts. If the original iOS deployment failed or was cancelled after Build and transfer iOS binary and Retain Apple verification handoff succeeded in order, dispatch the managed apple-upload-recovery.yml on the default branch with original producer-run, producer-attempt, deployment-id and handoff-artifact-id. It authenticates the original artifact and unchanged handoff, terminal original and latest run, owner, and fresh Apple upload/file/build/app evidence. A null optional file checksum is absent; present whole-file checksums remain strictly verified. It never rebuilds, uploads, replays metadata or rewrites the original handoff. Retain the original handoff and derived completion proof with distinct current recovery caller, then rerun the whole original deployment: admission reuses the uploaded receipt without another iOS binary. The old failure or cancellation remains historical evidence; follow the new attempt to completion. Missing or mismatched evidence remains refused."
   },
   {
     "schema": "gowalk-cicd/mobile-release-refused.v1",

package/src/config/workflows.mjs

@@ -36,11 +36,11 @@ function render(source, normalized, file) {
 }
 
 const WARM = 'warm-android-cache.yml';
-const MANAGED = ['deploy.yml', 'mobile-candidate.yml', 'deploy-web.yml', 'deploy-backend.yml', WARM];
+const RECOVERY = 'apple-upload-recovery.yml';
+const MANAGED = ['deploy.yml', 'mobile-candidate.yml', 'deploy-web.yml', 'deploy-backend.yml', WARM, RECOVERY];
 
-// A generated file this install no longer wants (deploy-web.yml always; the warm-up without
-// candidates) is removed while it is still what the lock says was generated, with no overrides.
-// Anything customized stays and keeps upgrading.
+// Retire generated workflows only while their locked bytes are unchanged and they have no overrides.
+// App-owned customizations stay and keep upgrading when their automatic use is disabled.
 function retired(root, file, state) {
   if (state.migrating || state.config.workflows[file]?.overrides?.length) return false;
   const previous = load(root, `.github/workflows/${file}`);
@@ -87,8 +87,14 @@ export function planWorkflows(root, templateDir, files, version) {
     if (!MANAGED.includes(file)) throw new MigrationRepair('unknown_managed_workflow', CONFIG);
   }
   const removed = selected.filter(file => file === 'deploy-web.yml' && retired(root, file, state));
-  const writes = selected.filter(file => !removed.includes(file) && file !== WARM)
+  const writes = selected.filter(file => !removed.includes(file) && ![WARM, RECOVERY].includes(file))
     .map(file => upgradeWorkflow(root, file, templateDir, state));
+  const recovery = selected.includes('deploy.yml') && state.config.mobile?.platforms !== 'android';
+  if (recovery || (selected.includes(RECOVERY) && !retired(root, RECOVERY, state))) {
+    writes.push(upgradeWorkflow(root, RECOVERY, templateDir, state));
+  } else if (selected.includes(RECOVERY)) {
+    removed.push(RECOVERY);
+  }
   // Only verified candidate keys can request trusted post-release dependency priming on either OS.
   const candidates = selected.includes('mobile-candidate.yml')
     && state.config.mobile?.['candidate-artifacts'] !== false;
@@ -106,7 +112,7 @@ export function planWorkflows(root, templateDir, files, version) {
   for (const [file, entry] of Object.entries(state.config.workflows)) {
     for (const change of entry.overrides) assertReferences(change.value, file, change.path);
   }
-  writes.push(...planValidation(root, [...selected, WARM]));
+  writes.push(...planValidation(root, [...selected, WARM, RECOVERY]));
   state.lock.package = version;
   const config = state.text && equal(readYaml(state.text, CONFIG).value, state.config)
     ? state.text

package/templates/apple-upload-recovery.yml

@@ -0,0 +1,96 @@
+name: Recover Apple upload
+on:
+  workflow_dispatch:
+    inputs:
+      producer-run:
+        description: Original Mobile Deploy run ID
+        required: true
+        type: string
+      producer-attempt:
+        description: Original Mobile Deploy run attempt
+        required: true
+        type: string
+      deployment-id:
+        description: Original iOS release deployment ID
+        required: true
+        type: string
+      handoff-artifact-id:
+        description: Original Apple verification handoff artifact ID
+        required: true
+        type: string
+
+permissions:
+  contents: read
+  actions: read
+  deployments: write
+
+# Serialize the original owner update with ordinary Mobile Deploy; recovery never uploads.
+concurrency:
+  group: mobile-deploy-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  recover:
+    name: Verify the original Apple upload
+    if: >-
+      ${{ github.event_name == 'workflow_dispatch'
+          && github.ref == format('refs/heads/{0}', github.event.repository.default_branch) }}
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    env:
+      GITHUB_TOKEN: ${{ github.token }}
+      APPLE_RECOVERY_PRODUCER_RUN: ${{ inputs.producer-run }}
+      APPLE_RECOVERY_PRODUCER_ATTEMPT: ${{ inputs.producer-attempt }}
+      APPLE_RECOVERY_DEPLOYMENT_ID: ${{ inputs.deployment-id }}
+      APPLE_RECOVERY_HANDOFF_ARTIFACT_ID: ${{ inputs.handoff-artifact-id }}
+    steps:
+      - uses: actions/checkout@df4cb1c069e1874edd31b4311f1884172cec0e10 # v6
+      - name: Validate original upload identifiers
+        shell: bash
+        run: |
+          for value in "$APPLE_RECOVERY_PRODUCER_RUN" "$APPLE_RECOVERY_PRODUCER_ATTEMPT" \
+            "$APPLE_RECOVERY_DEPLOYMENT_ID" "$APPLE_RECOVERY_HANDOFF_ARTIFACT_ID"; do
+            if [[ ! "$value" =~ ^[1-9][0-9]*$ ]]; then
+              echo "::error title=apple_upload_recovery_failed::invalid_recovery_identifiers"
+              exit 1
+            fi
+          done
+      - name: Prepare Apple API access
+        env:
+          CI_ASC_KEY_P8: ${{ secrets.ASC_KEY_P8 }}
+          CI_ASC_KEY_ID: ${{ secrets.ASC_KEY_ID }}
+          CI_ASC_ISSUER_ID: ${{ secrets.ASC_ISSUER_ID }}
+        run: |
+          umask 077
+          mkdir -p creds
+          if [ -n "${CI_ASC_KEY_P8:-}" ]; then
+            : "${CI_ASC_KEY_ID:?ASC_KEY_ID secret is required with ASC_KEY_P8}"
+            : "${CI_ASC_ISSUER_ID:?ASC_ISSUER_ID secret is required with ASC_KEY_P8}"
+            printf '%s' "$CI_ASC_KEY_P8" > "creds/AuthKey_${CI_ASC_KEY_ID}_Issuer_${CI_ASC_ISSUER_ID}.p8"
+          fi
+          python3 -m pip install --quiet --break-system-packages PyJWT cryptography requests
+          PYTHONPATH=.github/actions/swift-app/scripts python3 - <<'PY'
+          import os
+          from pathlib import Path
+          from read_config import emit_credentials
+          emit_credentials(Path(os.environ['GITHUB_ENV']), Path(os.environ['GITHUB_WORKSPACE']))
+          PY
+      - name: Verify the original upload and reconcile its owner
+        id: recover
+        run: |
+          node .github/actions/swift-app/scripts/apple_upload_recovery.cjs \
+            "$APPLE_RECOVERY_PRODUCER_RUN" "$APPLE_RECOVERY_PRODUCER_ATTEMPT" \
+            "$APPLE_RECOVERY_DEPLOYMENT_ID" "$APPLE_RECOVERY_HANDOFF_ARTIFACT_ID"
+      - name: Retain verified Apple recovery proof
+        if: ${{ steps.recover.outputs.verified == 'true' }}
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        env:
+          NODE_OPTIONS: --require "${{ github.workspace }}/.github/actions/android-app/scripts/artifact_env.cjs"
+        with:
+          name: apple-recovered-${{ github.run_id }}-${{ github.run_attempt }}
+          path: |
+            ${{ runner.temp }}/apple-upload-recovery/apple-verification.json
+            ${{ runner.temp }}/apple-upload-recovery/apple-verification.json.verified.json
+            ${{ runner.temp }}/apple-upload-recovery/apple-verification.json.upload-receipt.json
+          if-no-files-found: error
+          retention-days: 7