@rightkit/release 0.3.0 → 0.4.1

package/ios-testflight.mjs

@@ -0,0 +1,266 @@
+// TestFlight distribution through the App Store Connect API: wait for one EXACT build to finish processing, assign it to beta
+// groups, and (HeardRight parity) put it into external beta review when an external group is selected. A port of HeardRight's
+// scripts/testflight-distribute.py to Node, with the JWT signed in-process from the Keychain key (signAppleApiJwtWithKey)
+// instead of shelling out to openssl on a .p8 file. No App Store submission happens here: the only review object created is
+// the TestFlight beta app review submission, and only when `submitExternalBetaReview` is true.
+//
+// Everything external is injected (`fetchImpl`, `sleep`, `monotonic`, `now`) so tests run no network and no real wait.
+import { signAppleApiJwtWithKey } from "./apple-profile-renew.mjs";
+
+export const ASC_API = "https://api.appstoreconnect.apple.com";
+const FAILED_PROCESSING_STATES = new Set(["FAILED", "INVALID"]);
+const EXTERNAL_REVIEW_PENDING_OR_READY = new Set(["WAITING_FOR_BETA_REVIEW", "IN_BETA_REVIEW", "READY_FOR_BETA_TESTING", "IN_BETA_TESTING", "BETA_APPROVED"]);
+const ACCEPTED_REVIEW_STATES = new Set(["WAITING_FOR_REVIEW", "IN_REVIEW", "APPROVED"]);
+
+export class TestFlightError extends Error {
+  constructor(code, message) { super(message); this.name = "TestFlightError"; this.code = code; }
+}
+const fail = (code, message) => { throw new TestFlightError(code, message); };
+const text = (value) => String(value ?? "");
+
+// Apple's limit is 20 minutes; stay well under it (1080 s at most) and renew one minute before expiry, so a 30 minute wait never
+// uses a stale token.
+export const MAX_JWT_LIFETIME_SECONDS = 1080;
+export function createTokenProvider({ privateKey, keyId, issuer, now = () => new Date(), lifetimeSeconds = MAX_JWT_LIFETIME_SECONDS, sign = signAppleApiJwtWithKey }) {
+  if (!Number.isInteger(lifetimeSeconds) || lifetimeSeconds < 120 || lifetimeSeconds > MAX_JWT_LIFETIME_SECONDS) fail("TESTFLIGHT_CONFIG_INVALID", `the JWT lifetime must be 120..${MAX_JWT_LIFETIME_SECONDS} seconds`);
+  let token = "";
+  let expiresAt = 0;
+  return {
+    get() {
+      const current = now();
+      const seconds = Math.floor(current.getTime() / 1000);
+      if (token && seconds < expiresAt - 60) return token;
+      token = sign(privateKey, { keyId, issuer }, current, { lifetimeSeconds });
+      expiresAt = seconds + lifetimeSeconds;
+      return token;
+    },
+  };
+}
+
+// ---- bounded retry of idempotent calls ----------------------------------------------------------------------------
+export const RETRY_DEFAULTS = Object.freeze({ attempts: 5, baseMs: 1000, maxBackoffMs: 30_000, maxRetryAfterMs: 120_000 });
+const IDEMPOTENT = new Set(["GET", "HEAD", "PUT", "PATCH", "DELETE"]);
+
+/** Seconds or an HTTP date in a Retry-After header, as milliseconds (undefined when absent or unreadable). */
+export function parseRetryAfter(value, nowMs = Date.now()) {
+  const raw = String(value ?? "").trim();
+  if (!raw) return undefined;
+  if (/^\d+$/.test(raw)) return Number(raw) * 1000;
+  const date = Date.parse(raw);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - nowMs);
+}
+export const retryableStatus = (status) => status === 429 || (status >= 500 && status <= 599);
+
+/** Delay before retry number `attempt` (0-based): Retry-After when given (capped), else exponential backoff (capped). */
+export function retryDelayMs(attempt, retryAfterMs, { baseMs, maxBackoffMs, maxRetryAfterMs } = RETRY_DEFAULTS) {
+  if (retryAfterMs !== undefined) return Math.min(retryAfterMs, maxRetryAfterMs);
+  return Math.min(baseMs * 2 ** attempt, maxBackoffMs);
+}
+
+export function createAscClient({ tokenProvider, fetchImpl = globalThis.fetch, apiBase = ASC_API, timeoutMs = 30_000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), retry = RETRY_DEFAULTS, now = () => Date.now() }) {
+  const base = new URL(apiBase);
+  // Only idempotent calls (GET, PATCH, PUT, DELETE) are retried, on a network error, 429 or 5xx, honouring Retry-After. A POST is never
+  // retried: a create that reached Apple but lost its answer must be looked up, not repeated.
+  const request = async (method, pathOrUrl, body, { retries = IDEMPOTENT.has(method) ? retry.attempts - 1 : 0 } = {}) => {
+    const url = new URL(pathOrUrl, base);
+    if (url.origin !== base.origin || !url.pathname.startsWith("/v1/")) fail("TESTFLIGHT_API_INVALID", "an App Store Connect URL is outside the API origin");
+    for (let attempt = 0; ; attempt += 1) {
+      let response;
+      try {
+        response = await fetchImpl(url.href, {
+          method,
+          headers: { Authorization: `Bearer ${tokenProvider.get()}`, Accept: "application/json", ...(body === undefined ? {} : { "Content-Type": "application/json" }) },
+          ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+          redirect: "error",
+          signal: AbortSignal.timeout(timeoutMs),
+        });
+      } catch {
+        if (attempt < retries) { await sleep(retryDelayMs(attempt, undefined, retry)); continue; }
+        fail("TESTFLIGHT_API_FAILED", `App Store Connect ${method} ${url.pathname} request failed`);
+      }
+      if (!response.ok) {
+        if (attempt < retries && retryableStatus(response.status)) {
+          await sleep(retryDelayMs(attempt, parseRetryAfter(response.headers?.get?.("retry-after"), now()), retry));
+          continue;
+        }
+        let detail = "";
+        try {
+          const payload = await response.json();
+          detail = (payload?.errors ?? []).map((item) => text(item.detail || item.title)).join("; ");
+        } catch { /* no body */ }
+        detail = detail.replace(/Bearer\s+\S+/gi, "Bearer [redacted]").replace(/\s+/g, " ").slice(0, 400);
+        fail("TESTFLIGHT_API_FAILED", `App Store Connect ${method} ${url.pathname} failed with HTTP ${response.status}${detail ? `: ${detail}` : ""}`);
+      }
+      if (response.status === 204) return {};
+      let payload;
+      try { payload = await response.json(); } catch { return {}; }
+      return payload ?? {};
+    }
+  };
+  const getAll = async (pathOrUrl) => {
+    const items = [];
+    const visited = new Set();
+    let next = pathOrUrl;
+    while (next) {
+      if (visited.has(next) || visited.size >= 100) fail("TESTFLIGHT_API_INVALID", "invalid or excessive App Store Connect pagination");
+      visited.add(next);
+      const payload = await request("GET", next);
+      if (!Array.isArray(payload.data)) fail("TESTFLIGHT_API_INVALID", "an App Store Connect collection response was not a list");
+      items.push(...payload.data);
+      next = payload.links?.next;
+    }
+    return items;
+  };
+  return { request, getAll };
+}
+
+const groupName = (group) => text(group?.attributes?.name || group?.id);
+const isInternal = (group) => Boolean(group?.attributes?.isInternalGroup);
+
+export function normalizeGroupSelection(groups) {
+  // No implicit policy: the app says "all" or names its groups.
+  if (groups === "all") return "all";
+  if (Array.isArray(groups) && groups.length && groups.every((name) => typeof name === "string" && name.trim())) return [...new Set(groups.map((name) => name.trim()))];
+  return fail("TESTFLIGHT_CONFIG_INVALID", 'groups is required: "all" or a non-empty list of beta group names');
+}
+
+/**
+ * Wait for the exact build, assign it to the selected beta groups (re-read until the assignment converges), and handle
+ * external beta review. Returns the evidence object (no secret in it).
+ */
+export async function distributeToTestFlight({
+  client, appId, marketingVersion, buildNumber, groups, submitExternalBetaReview = false,
+  pollIntervalMs = 20_000, timeoutMs = 30 * 60_000, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  monotonic = () => performance.now(), log = () => {},
+}) {
+  if (!/^\d+$/.test(text(appId))) fail("TESTFLIGHT_CONFIG_INVALID", "appId must be the numeric App Store Connect app id");
+  if (!text(marketingVersion) || !text(buildNumber)) fail("TESTFLIGHT_CONFIG_INVALID", "the marketing version and the build number are required");
+  const selection = normalizeGroupSelection(groups);
+  const deadline = monotonic() + timeoutMs;
+  const wait = async (reason) => {
+    if (monotonic() >= deadline) fail("TESTFLIGHT_TIMEOUT", `timed out waiting for ${reason}`);
+    await sleep(pollIntervalMs);
+  };
+  const identity = `${marketingVersion} (${buildNumber})`;
+
+  const candidates = async () => {
+    const query = new URLSearchParams({ "filter[app]": text(appId), "filter[version]": text(buildNumber), include: "preReleaseVersion", limit: "200" });
+    const payload = await client.request("GET", `/v1/builds?${query}`);
+    const releases = new Map((payload.included ?? []).filter((item) => item.type === "preReleaseVersions").map((item) => [item.id, text(item.attributes?.version)]));
+    return (payload.data ?? []).filter((build) => text(build.attributes?.version) === text(buildNumber)
+      && releases.get(build.relationships?.preReleaseVersion?.data?.id) === text(marketingVersion));
+  };
+  const waitForBuild = async () => {
+    for (;;) {
+      const matches = await candidates();
+      if (matches.length > 1) fail("TESTFLIGHT_AMBIGUOUS_BUILD", `the exact build identity is ambiguous in App Store Connect: ${matches.map((item) => item.id).join(", ")}`);
+      if (!matches.length) { await wait(`build ${identity} to appear`); continue; }
+      const state = text(matches[0].attributes?.processingState);
+      if (state === "VALID") return matches[0];
+      if (FAILED_PROCESSING_STATES.has(state)) fail("TESTFLIGHT_PROCESSING_FAILED", `build ${identity} processing failed: ${state}`);
+      await wait(`build ${identity} processing`);
+    }
+  };
+
+  const listGroups = async () => {
+    const all = await client.getAll(`/v1/apps/${appId}/betaGroups?limit=200`);
+    if (!all.length) fail("TESTFLIGHT_NO_GROUPS", `app ${appId} has no TestFlight beta groups`);
+    if (selection === "all") return all;
+    const missing = selection.filter((name) => !all.some((group) => groupName(group) === name));
+    if (missing.length) fail("TESTFLIGHT_GROUP_MISSING", `beta group(s) not found for app ${appId}: ${missing.join(", ")}`);
+    return all.filter((group) => selection.includes(groupName(group)));
+  };
+  const hasBuild = async (groupId, buildId) => (await client.getAll(`/v1/betaGroups/${groupId}/relationships/builds?limit=200`)).some((item) => text(item.id) === buildId);
+  const assignedIds = async (buildId, list) => {
+    const ids = new Set();
+    for (const group of list) if (await hasBuild(text(group.id), buildId)) ids.add(text(group.id));
+    return ids;
+  };
+
+  const build = await waitForBuild();
+  const buildId = text(build.id);
+  log(`TestFlight: build ${identity} is VALID (${buildId})`);
+
+  // An internal group with access to all builds gets every build by itself, and App Store Connect refuses to assign one
+  // (HTTP 422 "Cannot add internal group to a build", live run 2026-10-19), so it is not assigned and counts as holding the build.
+  const automatic = (group) => isInternal(group) && group.attributes?.hasAccessToAllBuilds === true;
+  for (const group of await listGroups()) {
+    if (automatic(group)) log(`TestFlight: internal group ${groupName(group)} receives every build (access to all builds)`);
+  }
+  let converged = false;
+  for (let attempt = 0; attempt < 3 && !converged; attempt += 1) {
+    const list = (await listGroups()).filter((group) => !automatic(group));
+    const assigned = await assignedIds(buildId, list);
+    const missing = list.filter((group) => !assigned.has(text(group.id)));
+    if (!missing.length) { converged = true; break; }
+    for (const group of missing) {
+      try {
+        await client.request("POST", `/v1/betaGroups/${group.id}/relationships/builds`, { data: [{ type: "builds", id: buildId }] });
+      } catch (error) {
+        if (!(await hasBuild(text(group.id), buildId))) fail("TESTFLIGHT_ASSIGN_FAILED", `could not assign build ${identity} to beta group ${groupName(group)}: ${error.message}`);
+      }
+    }
+  }
+  const finalGroups = (await listGroups()).filter((group) => !automatic(group));
+  const finalAssigned = await assignedIds(buildId, finalGroups);
+  const unassigned = finalGroups.filter((group) => !finalAssigned.has(text(group.id)));
+  if (unassigned.length) fail("TESTFLIGHT_ASSIGN_FAILED", `build assignment did not converge for beta groups: ${unassigned.map(groupName).join(", ")}`);
+
+  const reviewSubmissions = async () => client.getAll(`/v1/betaAppReviewSubmissions?${new URLSearchParams({ "filter[build]": buildId, limit: "200" })}`);
+  const betaDetail = async () => {
+    const payload = await client.request("GET", `/v1/builds/${buildId}/buildBetaDetail`);
+    if (!payload.data || typeof payload.data !== "object") fail("TESTFLIGHT_API_INVALID", "App Store Connect returned no build beta detail");
+    return payload.data;
+  };
+  const stateSet = (submissions) => new Set(submissions.map((item) => text(item.attributes?.betaReviewState)));
+  const ensureExternalReview = async () => {
+    for (;;) {
+      let detail = await betaDetail();
+      const state = text(detail.attributes?.externalBuildState);
+      let submissions = await reviewSubmissions();
+      let states = stateSet(submissions);
+      if ([...states].some((item) => ACCEPTED_REVIEW_STATES.has(item))) return { detail, submissions };
+      if (submissions.length) fail("TESTFLIGHT_REVIEW_STATE", `external beta review is not pending or approved: ${[...states].sort().join(", ") || "UNKNOWN"}`);
+      if (EXTERNAL_REVIEW_PENDING_OR_READY.has(state)) return { detail, submissions };
+      if (state === "READY_FOR_BETA_SUBMISSION") {
+        await client.request("POST", "/v1/betaAppReviewSubmissions", { data: { type: "betaAppReviewSubmissions", relationships: { build: { data: { type: "builds", id: buildId } } } } });
+        submissions = await reviewSubmissions();
+        if (!submissions.length) fail("TESTFLIGHT_REVIEW_STATE", "the external beta review submission was not visible after creation");
+        states = stateSet(submissions);
+        if (![...states].some((item) => ACCEPTED_REVIEW_STATES.has(item))) fail("TESTFLIGHT_REVIEW_STATE", `the external beta review submission has an invalid state: ${[...states].sort().join(", ") || "UNKNOWN"}`);
+        detail = await betaDetail();
+        return { detail, submissions };
+      }
+      if (state === "PROCESSING" || state === "") { await wait("the external TestFlight state"); continue; }
+      return fail("TESTFLIGHT_REVIEW_STATE", `build cannot enter external TestFlight review: ${state}`);
+    }
+  };
+
+  let detail = null;
+  let submissions = [];
+  if (submitExternalBetaReview && finalGroups.some((group) => !isInternal(group))) ({ detail, submissions } = await ensureExternalReview());
+
+  return {
+    appId: text(appId),
+    marketingVersion: text(marketingVersion),
+    buildNumber: text(buildNumber),
+    buildId,
+    processingState: "VALID",
+    groupSelection: selection,
+    groups: finalGroups.map((group) => ({ id: text(group.id), name: groupName(group), internal: isInternal(group), assigned: finalAssigned.has(text(group.id)) })),
+    externalBuildState: detail ? text(detail.attributes?.externalBuildState) : null,
+    betaReviewSubmissionIds: submissions.map((item) => text(item.id)),
+    betaReviewStates: submissions.map((item) => text(item.attributes?.betaReviewState)),
+  };
+}
+
+/** The API plan printed by a dry run (pure data, no secret). */
+export function testflightPlan({ appId, marketingVersion, buildNumber, groups, submitExternalBetaReview }) {
+  const selection = normalizeGroupSelection(groups);
+  return [
+    { id: "builds.wait", method: "GET", url: `${ASC_API}/v1/builds?filter[app]=${appId}&filter[version]=${buildNumber}&include=preReleaseVersion`, note: `poll until ${marketingVersion} (${buildNumber}) is VALID` },
+    { id: "betaGroups.list", method: "GET", url: `${ASC_API}/v1/apps/${appId}/betaGroups`, note: selection === "all" ? "every beta group" : `groups: ${selection.join(", ")}` },
+    { id: "betaGroups.assign", method: "POST", url: `${ASC_API}/v1/betaGroups/<groupId>/relationships/builds`, note: "only for groups that do not hold the build yet; re-read until converged" },
+    ...(submitExternalBetaReview ? [{ id: "betaAppReviewSubmissions.create", method: "POST", url: `${ASC_API}/v1/betaAppReviewSubmissions`, note: "only when an external group is selected and the build is READY_FOR_BETA_SUBMISSION" }] : []),
+  ];
+}

package/ios-upload.mjs

@@ -0,0 +1,313 @@
+// right-release iOS upload (bogusyogi/rightkit#349): a sealed, signed IPA to TestFlight, then the exact build into beta groups.
+// Build-free: it reads only the sealed release that `right-release build --platform ios` wrote. Dry run is the default (as
+// for Android): everything local is verified and the exact plan is printed; no Keychain item is read and nothing leaves the
+// machine. `--apply` uploads.
+//
+// Config (release config, top level):
+//   distribution: {
+//     provider: "app-store-connect",
+//     appId: "6806854037",                 // optional: the App Store Connect app id; when absent it is looked up from bundleId at --apply
+//     bundleId: "app.heardright.ios.native",
+//     track: "testflight",                 // the only track; there is no App Store submission
+//     groups: "all" | ["Internal Dogfood"], // REQUIRED: no implicit policy
+//     submitExternalBetaReview: false,      // default false; true creates the TestFlight beta app review submission for external groups
+//     waitTimeoutSeconds: 1800, pollIntervalSeconds: 20,
+//     credentials: { keyService?, keyIdService?, issuerService?, account? },   // Keychain service NAMES only
+//   }
+//
+// Credentials (settled decision D4: no credential sits in a file): the .p8, key id and issuer id come from the macOS login
+// Keychain (ios-asc-credentials.mjs) and live only in memory. A key path, key id, issuer or key in the config or the environment is
+// refused. The IPA is uploaded in process through the App Store Connect build-upload resources (ios-build-upload.mjs), the
+// TestFlight steps use the same in-memory ES256 JWT. No file, temp or not, ever holds the key; no altool, no Transporter.
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { assertGuiSigningSession, assertIosHost, IosHostError } from "./ios-host.mjs";
+import { acquireFileLock } from "./ios-lock.mjs";
+import {
+  IosCredentialsError, readAscCredentials, refuseIosAscEnv, resolveAscCredentialSource,
+} from "./ios-asc-credentials.mjs";
+import { buildUploadPlan, fileSource, uploadIpaToAppStoreConnect } from "./ios-build-upload.mjs";
+import { IOS_SIGNING_CONTRACT } from "./ios-package-recipe.mjs";
+import { ASC_API, createAscClient, createTokenProvider, distributeToTestFlight, normalizeGroupSelection, TestFlightError, testflightPlan } from "./ios-testflight.mjs";
+import { iosOwnershipScope } from "./ownership-scope.mjs";
+import { assertArtifactUnchanged, digestBytes, verifyPublicationRelease } from "./publication-artifacts.mjs";
+import { assertPrimaryReleaseCheckout } from "./release-invocation.mjs";
+import { assertCleanSource } from "./source-gate.mjs";
+import { targetDistribution } from "./target-distribution.mjs";
+
+export const IOS_PROVIDER = "app-store-connect";
+export const IOS_TRACK = "testflight";
+export const IOS_UPLOADED_MARKER = "verified-ios-upload.json";
+export const IOS_DISTRIBUTED_MARKER = "verified-ios-testflight.json";
+export const IOS_EVIDENCE_NAME = "ios-testflight.json";
+
+const RELEASE_ID = /^[A-Za-z0-9][A-Za-z0-9._+-]{0,159}$/;
+const TEST_SEGMENT = /^(?:dev|qa|test|debug)$/i;
+const DISTRIBUTION_KEYS = ["provider", "appId", "bundleId", "track", "groups", "submitExternalBetaReview", "waitTimeoutSeconds", "pollIntervalSeconds", "credentials"];
+const CREDENTIAL_LIKE = /key|issuer|p8|pem|secret|token|password|file|path|env/i;
+
+export class IosUploadError extends Error {
+  constructor(code, message) { super(`[${code}] ${message}`); this.name = "IosUploadError"; this.code = code; }
+}
+const refuse = (code, message) => { throw new IosUploadError(code, message); };
+
+// ---- config ------------------------------------------------------------------------------------------------------
+export function validateIosDistribution(distribution) {
+  if (!distribution || typeof distribution !== "object" || Array.isArray(distribution)) refuse("IOS_UPLOAD_CONFIG_INVALID", "release config distribution is required");
+  if (distribution.provider !== IOS_PROVIDER) refuse("IOS_UPLOAD_CONFIG_INVALID", `release config distribution.provider must be ${IOS_PROVIDER} for an iOS upload`);
+  for (const key of Object.keys(distribution)) {
+    if (DISTRIBUTION_KEYS.includes(key)) continue;
+    if (CREDENTIAL_LIKE.test(key)) refuse("IOS_ASC_CREDENTIAL_SOURCE_REFUSED", `distribution.${key} is refused: App Store Connect credentials are read only from the macOS login Keychain (distribution.credentials names the Keychain services), never from the config, a file or the environment`);
+    refuse("IOS_UPLOAD_CONFIG_INVALID", `distribution has unsupported key ${key} (allowed: ${DISTRIBUTION_KEYS.join(", ")})`);
+  }
+  // appId is optional: absent, --apply resolves it from bundleId through the App Store Connect API (resolveAscAppId).
+  const appId = distribution.appId === undefined ? null : String(distribution.appId);
+  if (appId !== null && !/^\d{5,20}$/.test(appId)) refuse("IOS_UPLOAD_CONFIG_INVALID", "distribution.appId must be the numeric App Store Connect app id (or omit it to resolve it from bundleId)");
+  const bundleId = String(distribution.bundleId ?? "");
+  if (!/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(bundleId)) refuse("IOS_UPLOAD_CONFIG_INVALID", "distribution.bundleId must be the reverse-DNS app bundle id");
+  if (TEST_SEGMENT.test(bundleId.split(".").at(-1))) refuse("IOS_UPLOAD_TEST_BUNDLE", `distribution.bundleId ${bundleId} is a dev/qa/test/debug id; those never go to TestFlight`);
+  const track = distribution.track ?? IOS_TRACK;
+  if (track !== IOS_TRACK) refuse("IOS_UPLOAD_TRACK_REFUSED", `distribution.track must be ${IOS_TRACK}; this command never submits to the App Store`);
+  let groups;
+  if (distribution.groups === undefined) refuse("IOS_UPLOAD_CONFIG_INVALID", 'distribution.groups is required: "all" or a non-empty list of beta group names (there is no implicit default)');
+  try { groups = normalizeGroupSelection(distribution.groups); } catch (error) { refuse("IOS_UPLOAD_CONFIG_INVALID", `distribution.${error.message}`); }
+  if (distribution.submitExternalBetaReview !== undefined && typeof distribution.submitExternalBetaReview !== "boolean") refuse("IOS_UPLOAD_CONFIG_INVALID", "distribution.submitExternalBetaReview must be a boolean");
+  const int = (value, label, min, max, fallback) => {
+    if (value === undefined) return fallback;
+    if (!Number.isInteger(value) || value < min || value > max) refuse("IOS_UPLOAD_CONFIG_INVALID", `distribution.${label} must be an integer ${min}..${max}`);
+    return value;
+  };
+  let credentials;
+  try { credentials = resolveAscCredentialSource(distribution.credentials, { label: "distribution.credentials" }); } catch (error) {
+    if (error instanceof IosCredentialsError) refuse(error.code, error.message);
+    throw error;
+  }
+  return {
+    appId, bundleId, track, groups,
+    submitExternalBetaReview: distribution.submitExternalBetaReview ?? false,
+    waitTimeoutSeconds: int(distribution.waitTimeoutSeconds, "waitTimeoutSeconds", 60, 7200, 1800),
+    pollIntervalSeconds: int(distribution.pollIntervalSeconds, "pollIntervalSeconds", 5, 300, 20),
+    credentials: distribution.credentials,
+    credentialServices: credentials,
+  };
+}
+
+const APP_ID_PENDING = "{appId from bundleId}";
+
+/**
+ * The App Store Connect app id for a bundle id: exactly one app whose bundleId equals it (the filter is not trusted to be exact).
+ * Read with the same in-memory JWT as the upload, so the config needs only the bundle id.
+ */
+export async function resolveAscAppId({ client, bundleId }) {
+  const apps = await client.getAll(`/v1/apps?${new URLSearchParams({ "filter[bundleId]": bundleId, limit: "200" })}`);
+  const exact = apps.filter((app) => String(app?.attributes?.bundleId ?? "") === bundleId);
+  if (exact.length !== 1) refuse("IOS_ASC_APP_NOT_FOUND", exact.length ? `${exact.length} App Store Connect apps have bundle id ${bundleId}; set distribution.appId` : `no App Store Connect app has bundle id ${bundleId}; create the app record in App Store Connect first`);
+  const id = String(exact[0].id ?? "");
+  if (!/^\d{5,20}$/.test(id)) refuse("IOS_ASC_APP_NOT_FOUND", `App Store Connect returned a non-numeric app id for ${bundleId}`);
+  return id;
+}
+
+/** The plan printed by a dry run: pure data, no secret, no Keychain read. */
+export function iosUploadPlan({ distribution, ipa, receipt }) {
+  const appId = distribution.appId ?? APP_ID_PENDING;
+  return {
+    appId,
+    ...(distribution.appId ? {} : { appIdSource: `resolved at --apply: GET ${ASC_API}/v1/apps?filter[bundleId]=${distribution.bundleId} (exactly one exact match)` }),
+    bundleId: distribution.bundleId,
+    track: distribution.track,
+    ipa: { name: ipa.name, sha256: ipa.sha256, sizeBytes: ipa.sizeBytes },
+    marketingVersion: receipt.marketingVersion,
+    buildNumber: receipt.buildNumber,
+    credentials: { source: "macOS login Keychain", services: [distribution.credentialServices.keyService, distribution.credentialServices.keyIdService, distribution.credentialServices.issuerService], account: distribution.credentialServices.account },
+    steps: [
+      ...buildUploadPlan({ appId, marketingVersion: receipt.marketingVersion, buildNumber: receipt.buildNumber, ipa }),
+      ...testflightPlan({ appId, marketingVersion: receipt.marketingVersion, buildNumber: receipt.buildNumber, groups: distribution.groups, submitExternalBetaReview: distribution.submitExternalBetaReview }),
+    ],
+  };
+}
+
+// ---- authorisation -----------------------------------------------------------------------------------------------
+const git = (cwd, args) => {
+  const result = spawnSync("git", args, { cwd, encoding: "utf8", windowsHide: true });
+  if (result.status !== 0) throw new Error(`git ${args.join(" ")} failed: ${result.stderr}`);
+  return result.stdout.trim();
+};
+
+/** Local checks only; no network, no secret. The sealed release is the only input: build-free by construction. */
+export async function authorizeIosUpload({ releaseId, configName = "right-release.config.mjs", cwd = process.cwd() }) {
+  if (!RELEASE_ID.test(releaseId ?? "")) refuse("IOS_UPLOAD_RELEASE_REQUIRED", "--release <sealed-id> is required");
+  const repoRoot = git(cwd, ["rev-parse", "--show-toplevel"]);
+  assertPrimaryReleaseCheckout(repoRoot);
+  const commit = git(repoRoot, ["rev-parse", "HEAD"]);
+  assertCleanSource({ status: git(repoRoot, ["status", "--porcelain=v1", "-z", "--untracked-files=all"]), commandId: "right-release upload" });
+  const configPath = path.resolve(cwd, configName);
+  if (!existsSync(configPath)) refuse("IOS_UPLOAD_CONFIG_INVALID", `release config is required: ${configName}`);
+  // The config is a module that runs on import: loaded only after the tree is proven clean.
+  const config = (await import(`${pathToFileURL(configPath).href}?upload=${Date.now()}`)).default;
+  const distribution = validateIosDistribution(targetDistribution(config, "ios"));
+  const sealedDir = path.join(repoRoot, ".right-release", "sealed", releaseId, "ios");
+  const appRoot = path.dirname(configPath);
+  // The IPA is verified by a streamed hash and never held in memory (streamRoles); the parts are read as byte ranges at upload time.
+  const sealed = verifyPublicationRelease({ sealedDir, repoRoot, appRoot, commit, app: config.app, version: config.version, platform: "ios", configPath, releaseId, streamRoles: ["ipa"], ownershipScope: iosOwnershipScope({ repoRoot, appRoot, target: config.targets?.ios, nativeAssembly: config.nativeAssembly }) });
+  const entries = sealed.manifest.files.filter((entry) => entry.role === "ipa");
+  if (entries.length !== 1) refuse("IOS_IPA_MISSING", "the sealed release must hold exactly one ipa entry");
+  const ipa = sealed.artifacts.get(entries[0].name);
+  // The build receipt rides in the seal; it names the version, build number, team and bundle id of exactly this IPA.
+  const receiptEntry = (sealed.manifest.signing?.receipts ?? []).map((item) => ({ item, value: tryParse(path.resolve(appRoot, item.file), item.sha256) })).find((candidate) => candidate.value?.contract === IOS_SIGNING_CONTRACT);
+  if (!receiptEntry) refuse("IOS_RECEIPT_MISSING", "the sealed release has no iOS build receipt");
+  const receipt = receiptEntry.value;
+  if (receipt.file?.sha256 !== entries[0].sha256) refuse("IOS_RECEIPT_MISMATCH", "the iOS build receipt describes a different IPA than the sealed ipa entry");
+  if (receipt.bundleId !== distribution.bundleId) refuse("IOS_RECEIPT_MISMATCH", `distribution.bundleId ${distribution.bundleId} is not the IPA's bundle id ${receipt.bundleId}`);
+  if (receipt.teamId !== sealed.manifest.signing?.teamId) refuse("IOS_RECEIPT_MISMATCH", "the iOS build receipt team id is not the team pinned in the sealed signing policy");
+  return { repoRoot, commit, sealed, sealedDir, configPath, config, distribution, ipa, entry: entries[0], receipt };
+}
+
+function tryParse(file, expectedSha256) {
+  try {
+    const bytes = readFileSync(file);
+    if (digestBytes(bytes) !== expectedSha256) return undefined;
+    return JSON.parse(bytes.toString("utf8"));
+  } catch { return undefined; }
+}
+
+// ---- the command -------------------------------------------------------------------------------------------------
+const writeJsonAtomic = (file, value) => {
+  mkdirSync(path.dirname(file), { recursive: true });
+  const temporary = `${file}.tmp-${process.pid}`;
+  writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`);
+  renameSync(temporary, file);
+};
+
+/**
+ * The journal of build uploads this vault created: {buildUploadId, buildUploadFileId, appId, version, build, ipaSha256}. It is written
+ * (atomically) right after each create POST, and an App Store Connect record is adopted only if it is listed here for the same IPA.
+ * A missing file is an empty journal; an unreadable or malformed one is an error, never an empty journal.
+ */
+export function buildUploadJournal(dir, appId) {
+  const file = path.join(dir, `ios-build-uploads.${appId}.json`);
+  const read = () => {
+    let raw;
+    try { raw = readFileSync(file, "utf8"); } catch (error) {
+      if (error?.code === "ENOENT") return [];
+      refuse("IOS_UPLOAD_JOURNAL_INVALID", `the build-upload journal ${file} is unreadable (${error?.code ?? "error"}); fix or remove it only after checking App Store Connect`);
+    }
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { parsed = undefined; }
+    if (!parsed || !Array.isArray(parsed.entries) || parsed.entries.some((entry) => !entry || typeof entry.buildUploadId !== "string" || !/^[a-f0-9]{64}$/.test(String(entry.ipaSha256)))) refuse("IOS_UPLOAD_JOURNAL_INVALID", `the build-upload journal ${file} is malformed; fix or remove it only after checking App Store Connect`);
+    return parsed.entries;
+  };
+  const record = (entry) => {
+    const entries = read().filter((item) => item.buildUploadId !== entry.buildUploadId);
+    writeJsonAtomic(file, { schema: 1, entries: [...entries, entry] });
+  };
+  return { file, read, record };
+}
+
+/** A marker may only be trusted for the very IPA, app and build number it was written for. */
+function readMarker(file, expected, label) {
+  let marker;
+  try { marker = JSON.parse(readFileSync(file, "utf8")); } catch { refuse("IOS_UPLOAD_MARKER_INVALID", `${label} marker ${file} is unreadable; inspect App Store Connect and remove it only if the build was not uploaded`); }
+  for (const [key, value] of Object.entries(expected)) {
+    if (marker?.[key] !== value) refuse("IOS_UPLOAD_MARKER_MISMATCH", `${label} marker ${file} was written for a different ${key} (${String(marker?.[key])}, now ${String(value)}); refusing to skip the upload on it`);
+  }
+  return marker;
+}
+
+export async function runIosUpload({
+  releaseId, configName, cwd = process.cwd(), apply = false, env = process.env, platform = process.platform, log = console.log,
+  fetchImpl = globalThis.fetch, authorize = authorizeIosUpload, readCredentials = readAscCredentials, run = spawnSync, detectSession,
+  acquireLock = acquireFileLock, journalDir, sleep, monotonic, now = () => new Date(),
+}) {
+  refuseIosAscEnv(env);
+  const auth = await authorize({ releaseId, configName, cwd });
+  const ipaEvidence = { name: auth.entry.name, sha256: auth.entry.sha256, sizeBytes: auth.entry.sizeBytes };
+  const plan = iosUploadPlan({ distribution: auth.distribution, ipa: ipaEvidence, receipt: auth.receipt });
+  const stateRoot = path.join(auth.repoRoot, ".right-release", "state", releaseId, "ios");
+  const uploadedMarker = path.join(stateRoot, IOS_UPLOADED_MARKER);
+  const distributedMarker = path.join(stateRoot, IOS_DISTRIBUTED_MARKER);
+  if (!apply) {
+    log(`right-release upload: dry-run (default; pass --apply to upload) ${releaseId} -> TestFlight of app ${plan.appId} (${plan.bundleId})`);
+    log(JSON.stringify(plan, null, 2));
+    return { applied: false, plan };
+  }
+  try { assertIosHost({ operation: "right-release upload --apply", platform }); } catch (error) {
+    if (error instanceof IosHostError) refuse(error.code, error.message);
+    throw error;
+  }
+  // One apply per release at a time (the same pid lock the build lane uses).
+  const lock = acquireLock(path.join(auth.repoRoot, ".right-release", "locks", `ios-upload-${releaseId}.lock.json`), `right-release upload --platform ios ${releaseId}`);
+  try {
+    // The Keychain is read only in the GUI (Aqua) session; an SSH session is refused before any read. The key is read once, lazily.
+    let ascClient;
+    const client = () => {
+      if (ascClient) return ascClient;
+      try { assertGuiSigningSession({ operation: "right-release upload --apply (login Keychain)", env, run, detect: detectSession }); } catch (error) {
+        if (error instanceof IosHostError) refuse(error.code, error.message);
+        throw error;
+      }
+      const { keyId, issuer, privateKey } = readCredentials({ credentials: auth.distribution.credentials, env, platform });
+      ascClient = createAscClient({ tokenProvider: createTokenProvider({ privateKey, keyId, issuer }), fetchImpl, ...(sleep ? { sleep } : {}) });
+      return ascClient;
+    };
+    if (!auth.distribution.appId) {
+      plan.appId = await resolveAscAppId({ client: client(), bundleId: plan.bundleId });
+      log(`right-release upload: App Store Connect app ${plan.appId} resolved from bundle id ${plan.bundleId}`);
+    }
+    const identity = { appId: plan.appId, bundleId: plan.bundleId, marketingVersion: plan.marketingVersion, buildNumber: plan.buildNumber, ipaSha256: ipaEvidence.sha256 };
+    if (existsSync(distributedMarker)) {
+      readMarker(distributedMarker, identity, "distribution");
+      log(`right-release upload: already distributed ${releaseId} to TestFlight`);
+      return { applied: false, alreadyDistributed: true, plan };
+    }
+
+    // 1. The sealed bytes are uploaded once, in process (or an existing upload is resumed); a rerun after a later failure skips straight
+    //    to the TestFlight steps, but only on a marker written for this very IPA, app and build number.
+    const waits = { ...(sleep ? { sleep } : {}), ...(monotonic ? { monotonic } : {}) };
+    if (!existsSync(uploadedMarker)) {
+      const source = fileSource(auth.ipa.file, auth.entry); // streamed hash; refuses bytes that changed since the seal
+      log(`right-release upload: uploading ${ipaEvidence.name} through the App Store Connect API (in process, no key file)`);
+      const uploaded = await uploadIpaToAppStoreConnect({
+        client: client(), appId: plan.appId, marketingVersion: plan.marketingVersion, buildNumber: plan.buildNumber, source, fileName: ipaEvidence.name, fetchImpl,
+        // Xcode's export registers an empty build upload during the build; only one created between the sealed export start (less 30 s of
+        // clock skew) and the receipt may be adopted. A receipt without exportStartedAt (sealed before it existed) adopts nothing.
+        exportWindow: auth.receipt?.exportStartedAt && auth.receipt?.builtAt ? { notBefore: new Date(Date.parse(auth.receipt.exportStartedAt) - 30_000).toISOString(), notAfter: auth.receipt.builtAt } : undefined,
+        journal: buildUploadJournal(journalDir ?? (env.RIGHT_RELEASE_VAULT_STATE_ROOT ? path.join(path.resolve(env.RIGHT_RELEASE_VAULT_STATE_ROOT), "ios-build-uploads") : path.join(auth.repoRoot, ".right-release", "state", "ios-build-uploads")), plan.appId),
+        pollIntervalMs: auth.distribution.pollIntervalSeconds * 1000, timeoutMs: auth.distribution.waitTimeoutSeconds * 1000, ...waits,
+        log: (line) => log(`right-release upload: ${line}`),
+      });
+      writeJsonAtomic(uploadedMarker, { schema: 1, releaseId, platform: "ios", provider: IOS_PROVIDER, ...identity, buildUploadId: uploaded.buildUploadId, uploadedAt: now().toISOString() });
+      log(`right-release upload: uploaded ${releaseId} ${plan.marketingVersion} (${plan.buildNumber})`);
+    } else {
+      readMarker(uploadedMarker, identity, "upload");
+      log(`right-release upload: ${releaseId} was already uploaded; continuing with TestFlight`);
+    }
+
+    // 2. TestFlight: the exact build into the beta groups.
+    const distributed = await distributeToTestFlight({
+      client: client(), appId: plan.appId, marketingVersion: plan.marketingVersion, buildNumber: plan.buildNumber, groups: auth.distribution.groups,
+      submitExternalBetaReview: auth.distribution.submitExternalBetaReview,
+      pollIntervalMs: auth.distribution.pollIntervalSeconds * 1000, timeoutMs: auth.distribution.waitTimeoutSeconds * 1000,
+      ...waits,
+      log: (line) => log(`right-release upload: ${line}`),
+    });
+    const evidence = { schema: 1, releaseId, platform: "ios", provider: IOS_PROVIDER, api: ASC_API, ipa: ipaEvidence, completedAt: now().toISOString(), testflight: distributed };
+    writeJsonAtomic(path.join(auth.repoRoot, ".right-release", "receipts", IOS_EVIDENCE_NAME), evidence);
+    writeJsonAtomic(distributedMarker, { schema: 1, releaseId, platform: "ios", ...identity, buildId: distributed.buildId, completedAt: evidence.completedAt });
+    log(`right-release upload: ${releaseId} is in TestFlight for ${distributed.groups.length} beta group(s)`);
+    return { applied: true, plan, evidence };
+  } finally { lock.release(); }
+}
+
+/** Entry used by upload-release.mjs for --platform ios. Exit code 0 on success, 1 on any refusal. */
+export async function main({ releaseId, configName, apply, dryRun }) {
+  if (apply && dryRun) { console.error("right-release upload: --apply and --dry-run are mutually exclusive"); return 2; }
+  try {
+    await runIosUpload({ releaseId, configName, apply: apply === true });
+    return 0;
+  } catch (error) {
+    console.error(`right-release upload: ${error instanceof TestFlightError ? `[${error.code}] ` : ""}${error.message}`);
+    return 1;
+  }
+}