@omega.js/manager 0.1.0

package/dist/services/captcha/index.js

@@ -0,0 +1,78 @@
+/**
+ * Captcha service (`captcha.providers.recaptcha`) — validates the brand's
+ * OWN classic reCAPTCHA keys (de-ITW: every brand mints its own key in its
+ * own GCP project — never a company-shared key; interactive runs ASK for the
+ * keys via the cp114 paste flow, pointing at the GCP reCAPTCHA console).
+ *
+ * Classic reCAPTCHA has no key-management API, so the key's domain list
+ * can't be reconciled; this service proves what it can (the secret key
+ * in .env is valid, via the documented siteverify endpoint) and prints the
+ * console link + domains for the manual half. Interactive runs open the
+ * console and confirm the domain list once, stamping config (#434).
+ *
+ * It also owns the ORPHAN-SECRET warning (#507): the secret in .env without
+ * `captcha.providers.recaptcha.siteKey` in config — see the guard below. The
+ * reverse direction is the env schema's shared `requiredWhen` rule (#626).
+ *
+ * Auth: RECAPTCHA_SITE_KEY + RECAPTCHA_SECRET_KEY in the brand .env.
+ * Missing keys → interactive runs ask; non-interactive runs skip with guidance.
+ */
+const chalk = require('chalk').default;
+
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { RecaptchaAPI } = require('./lib/recaptcha-api.js');
+const { recaptchaConsoleUrl } = require('./lib/console-url.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const recaptchaConfig = context.brandConfig.captcha?.providers?.recaptcha || {};
+
+    if (recaptchaConfig.enabled === false) {
+      return { skip: true, reason: 'captcha.providers.recaptcha.enabled = false' };
+    }
+
+    // The ORPHAN SECRET half (#507): RECAPTCHA_SECRET_KEY set with no
+    // captcha.providers.recaptcha.siteKey in config is a silent 403 on every
+    // protected POST — the backend enforces verification the moment the secret
+    // exists, and the client has no key to mint a token with (the playground's
+    // live checkout, 2026-08-22). This service is the ONE place that sees both
+    // halves, so it still says this direction out loud.
+    //
+    // The REVERSE direction — a site key requiring its secret — is the env
+    // schema's `requiredWhen` rule now
+    // ([#626](https://github.com/Omega-JS-Stack/omega/issues/626)): warned
+    // brand-wide by the workspace env-rules op, and refused by a production
+    // backend boot. Neither half = the sanctioned unkeyed brand (#17), which
+    // stays green and skips below.
+    const configuredSiteKey = recaptchaConfig.siteKey || null;
+    const configuredSecret = process.env.RECAPTCHA_SECRET_KEY || null;
+    if (configuredSecret && !configuredSiteKey) {
+      console.log(`      ${chalk.yellow('⚠')} RECAPTCHA_SECRET_KEY is set but captcha.providers.recaptcha.siteKey is missing from config — the client sends an empty token and every protected POST 403s. Paste the site key into config/omega.json5: ${recaptchaConsoleUrl(context.brandConfig, configuredSiteKey)}`);
+    }
+
+    const url = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '');
+    if (!url) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    // The site key is handler data (console link, domain guidance), not just
+    // auth — both keys must come from the .env even when tests inject the api
+    // De-ITW: the ask points at the GCP reCAPTCHA console (the brand's OWN
+    // project) via the registry entries — the paste flow is the ONLY path to
+    // a key; no default value exists anywhere
+    const gate = await requestServiceInput(context, serviceInputSpec('captcha'));
+    if (gate) return gate;
+    const siteKey = process.env.RECAPTCHA_SITE_KEY;
+    const secretKey = process.env.RECAPTCHA_SECRET_KEY;
+
+    // Tests inject a fake client via context.recaptchaApi
+    return {
+      recaptchaApi: context.recaptchaApi || new RecaptchaAPI({ secretKey }),
+      siteKey,
+      domain: url,
+    };
+  },
+});

package/dist/services/captcha/lib/console-url.js

@@ -0,0 +1,45 @@
+/**
+ * The reCAPTCHA console deep-link (#444) — the ONE place the guidance URL is
+ * built, shared by the setup's half-key guard (#507) and the site-key ensure
+ * handler's printed guidance.
+ */
+
+/**
+ * The project hosting the key. captcha.providers.recaptcha.project only exists
+ * to point at a project that ISN'T the brand's own (a key minted elsewhere);
+ * with no override the key lives in the brand's cloud project, whose ONE home
+ * is cloud.config.projectId (#23) — resolved config already carries the
+ * company/brand merge.
+ *
+ * @param {object} brandConfig - Resolved brand config.
+ * @returns {string|null} Project id, or null when no layer names one.
+ */
+function resolveProject(brandConfig) {
+  return brandConfig.captcha?.providers?.recaptcha?.project
+    || brandConfig.cloud?.config?.projectId
+    || null;
+}
+
+/**
+ * Deep-link to the key's settings page.
+ *
+ * omega-manager hardcoded the company GCP project here; the project resolves
+ * from config now, so the deep link builds by default. Only a project unknown
+ * at EVERY layer (or an unknown site key) falls back to the classic admin
+ * console, which lists your keys (it deep-links by internal numeric ID, not
+ * site key, so no key in the URL).
+ *
+ * @param {object} brandConfig - Resolved brand config.
+ * @param {string|null} siteKey - The key to deep-link, when known.
+ * @returns {string} Console URL.
+ */
+function recaptchaConsoleUrl(brandConfig, siteKey) {
+  const project = resolveProject(brandConfig);
+
+  if (project && siteKey) {
+    return `https://console.cloud.google.com/security/recaptcha/${siteKey}/overview?from=keysList&project=${project}`;
+  }
+  return 'https://www.google.com/recaptcha/admin';
+}
+
+module.exports = { recaptchaConsoleUrl };

package/dist/services/captcha/lib/recaptcha-api.js

@@ -0,0 +1,36 @@
+/**
+ * Classic reCAPTCHA client. Classic reCAPTCHA has no key-management API —
+ * the only documented endpoint is siteverify, which doubles as a secret-key
+ * validity check: verifying a throwaway token answers invalid-input-response
+ * for a good secret and invalid-input-secret for a bad one.
+ */
+
+const VERIFY_URL = 'https://www.google.com/recaptcha/api/siteverify';
+
+class RecaptchaAPI {
+  constructor({ secretKey = process.env.RECAPTCHA_SECRET_KEY } = {}) {
+    this.secretKey = secretKey;
+  }
+
+  /**
+   * Verify a response token against the secret key.
+   *
+   * @param {string} response - The reCAPTCHA response token to verify
+   * @returns {Promise<Object>} - Parsed siteverify JSON ({ success, 'error-codes' })
+   */
+  async verify(response) {
+    const res = await fetch(VERIFY_URL, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams({ secret: this.secretKey, response }),
+    });
+
+    if (!res.ok) {
+      throw new Error(`reCAPTCHA siteverify failed: HTTP ${res.status}`);
+    }
+
+    return await res.json();
+  }
+}
+
+module.exports = { RecaptchaAPI };

package/dist/services/certificates/ensure/api-key.js

@@ -0,0 +1,22 @@
+/**
+ * Sanity checkpoint — the App Store Connect client was built in setup();
+ * this prints what's configured so the run log shows which Apple account
+ * the downstream operations act on.
+ */
+const chalk = require('chalk').default;
+const { catchAgreements } = require('../lib/apple-api.js');
+
+module.exports = catchAgreements(async (context) => {
+  const { appleClient, appleSecrets } = context;
+
+  if (!appleClient || !appleSecrets) {
+    return { status: 'error', error: 'App Store Connect client not initialized' };
+  }
+
+  console.log(`      ${chalk.green('✓')} API client ready`);
+  console.log(`        ${chalk.dim(`Issuer: ${appleSecrets.issuerId}`)}`);
+  console.log(`        ${chalk.dim(`Team:   ${appleSecrets.teamId}`)}`);
+  console.log(`        ${chalk.dim(`Key:    ${appleSecrets.keyId}`)}`);
+
+  return {};
+});

package/dist/services/certificates/ensure/bundle-ids.js

@@ -0,0 +1,115 @@
+/**
+ * Ensure the brand's bundle ID exists with the required capabilities.
+ *
+ * Bundle ID = composeBundleId(certificates.providers.apple.bundleIdPrefix, brand.id)
+ * — reverse-DNS prefix (config; the onboard wizard derives it from the
+ * company/brand domain, and a brand without one is ASKED, #635) + the brand
+ * id with hyphens as dots, e.g.
+ * com.itwcreativeworks.omega.playground. Platforms derive from the enabled
+ * targets (desktop → MACOS, mobile → IOS) and ride the returned state for
+ * the profiles handler.
+ */
+const chalk = require('chalk').default;
+const { catchAgreements } = require('../lib/apple-api.js');
+const { composeBundleId } = require('../../../lib/bundle-id.js');
+const { resolveConfigValue } = require('../../../lib/config-flow.js');
+
+// Where the brand's identifiers live — the page a prefix is read off of
+const APPLE_PORTAL_IDENTIFIERS_URL = 'https://developer.apple.com/account/resources/identifiers/list';
+
+const {
+  listBundleIds,
+  createBundleId,
+  findBundleId,
+  listBundleIdCapabilities,
+  enableCapabilities,
+} = require('../lib/identifier-manager.js');
+
+module.exports = catchAgreements(async (context) => {
+  const { appleClient, brandConfig, brandId } = context;
+  const dryRun = context.options?.dryRun || false;
+
+  const appleConfig = brandConfig.certificates.providers?.apple || {};
+
+  // A value the brand must supply is ASKED for, not demanded (#635). The
+  // service already gated on its App Store Connect credentials, hence
+  // `gate: false`; a skip/disable/headless run steps aside warned, because a
+  // brand that never set a prefix is an unconfigured brand, not a broken one.
+  const prefix = appleConfig.bundleIdPrefix || await resolveConfigValue(context, {
+    path: 'certificates.providers.apple.bundleIdPrefix',
+    label: 'Apple bundle id prefix',
+    entry: {
+      url: APPLE_PORTAL_IDENTIFIERS_URL,
+      message: 'Apple bundle id prefix (reverse-DNS, e.g. com.yourcompany):',
+    },
+    disablePath: 'certificates.enabled',
+    gate: false,
+  });
+
+  if (!prefix) {
+    console.log(`      ${chalk.yellow('⚠')} No ${chalk.cyan('certificates.providers.apple.bundleIdPrefix')} — the bundle ID is <prefix>.<brand.id with dashes as dots>`);
+    return { status: 'warned', reason: 'no certificates.providers.apple.bundleIdPrefix', output: { bundleIds: { skipped: 'no bundleIdPrefix' } } };
+  }
+
+  const bundleIdentifier = composeBundleId(prefix, brandId);
+  const targets = brandConfig.targets || {};
+  const platforms = [
+    ...(targets.mobile ? ['IOS'] : []),
+    ...(targets.desktop ? ['MACOS'] : []),
+  ];
+  const capabilities = appleConfig.capabilities || [];
+  const brandName = brandConfig.brand?.name || brandId;
+
+  const existingBundleIds = await listBundleIds(appleClient);
+  console.log(`      ${chalk.green('✓')} Found ${existingBundleIds.length} existing bundle IDs`);
+  console.log(`      ${chalk.dim('•')} ${chalk.cyan(bundleIdentifier)} ${chalk.dim(`(${brandName})`)}`);
+
+  let record = findBundleId(existingBundleIds, bundleIdentifier);
+  let output;
+
+  if (record) {
+    console.log(`        ${chalk.green('✓')} Bundle ID exists ${chalk.dim(`(${record.attributes.platform})`)}`);
+    output = { synced: true };
+
+    if (capabilities.length > 0) {
+      const existingCaps = await listBundleIdCapabilities(appleClient, record.id);
+      const existingCapTypes = existingCaps.map((cap) => cap.attributes.capabilityType);
+      const missing = capabilities.filter((cap) => !existingCapTypes.includes(cap));
+
+      if (missing.length > 0) {
+        if (dryRun) {
+          console.log(`        ${chalk.cyan('[DRY RUN]')} Would enable: ${missing.join(', ')}`);
+          output = { planned: missing.map((cap) => `enable ${cap}`) };
+        } else {
+          const results = await enableCapabilities(appleClient, record.id, missing);
+          for (const result of results) {
+            if (result.success) {
+              console.log(`          ${chalk.green('✓')} ${result.capability}`);
+            } else {
+              console.log(`          ${chalk.yellow('⚠')} ${result.capability} — ${chalk.gray(result.error)}`);
+            }
+          }
+          output = { capabilitiesAdded: results.filter((r) => r.success).length };
+        }
+      } else {
+        console.log(`        ${chalk.dim(`✓ All ${capabilities.length} capability(ies) enabled`)}`);
+      }
+    }
+  } else {
+    if (dryRun) {
+      console.log(`        ${chalk.cyan('[DRY RUN]')} Would create ${bundleIdentifier} with ${capabilities.join(', ') || 'no capabilities'}`);
+      return { output: { bundleIds: { planned: [`create ${bundleIdentifier}`] } } };
+    }
+
+    record = await createBundleId(appleClient, bundleIdentifier, brandName, 'IOS', capabilities);
+    console.log(`        ${chalk.green('✓')} Created bundle ID`);
+    output = { created: true };
+  }
+
+  return {
+    state: {
+      bundleId: { identifier: bundleIdentifier, id: record.id, platforms },
+    },
+    output: { bundleIds: output },
+  };
+});

package/dist/services/certificates/ensure/certificates.js

@@ -0,0 +1,187 @@
+/**
+ * Ensure the account's signing certificates exist and are on disk. One set
+ * of certificates signs all of an Apple Developer account's apps, so this
+ * reconciles the account, not the brand.
+ *
+ * Per cert type in certificates.providers.apple.certificates:
+ *   - valid cert on the account → download the .cer if the local file is
+ *     missing (delete it to force a re-download), refresh the .p12 if stale
+ *   - no valid cert + automatable → create via CSR (reused across runs —
+ *     the private key pairs with the issued cert) + download + export
+ *   - no valid cert + manual (DEVELOPER_ID_*) → validate the local .cer;
+ *     missing/expired prints the portal URL + save path and warns (Apple
+ *     requires Account Holder login to issue these — no API path)
+ *
+ * After the loop, exported .p12 files import into the macOS login keychain
+ * (best-effort, config-listed types only, never in dry-run).
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+const { catchAgreements } = require('../lib/apple-api.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+const { runManualCertWalkthrough } = require('../lib/manual-walkthrough.js');
+
+const {
+  listCertificates,
+  downloadCertificate,
+  createCertificate,
+  getCSRContent,
+  exportToP12,
+  findValidCertificate,
+  validateManualCertificate,
+} = require('../lib/certificate-manager.js');
+
+const APPLE_PORTAL_CERTIFICATES_URL = 'https://developer.apple.com/account/resources/certificates/list';
+
+/** Trim an API cert record to the fields the later operations need. */
+function trimCert(cert) {
+  return {
+    id: cert.id,
+    certificateType: cert.attributes.certificateType,
+    expirationDate: cert.attributes.expirationDate,
+  };
+}
+
+module.exports = catchAgreements(async (context) => {
+  const { appleClient, appleSecrets, appleDir, brandConfig, keychainImport } = context;
+  const dryRun = context.options?.dryRun || false;
+
+  const appleConfig = brandConfig.certificates.providers?.apple || {};
+  const certConfigs = appleConfig.certificates || [];
+  const certificatePassword = appleSecrets.certificatePassword || '';
+
+  // List once; tolerate API failure when manual certs can still be checked
+  // locally (accounts without admin API access hit this).
+  let existingCerts;
+  try {
+    existingCerts = await listCertificates(appleClient);
+    console.log(`      ${chalk.green('✓')} Found ${existingCerts.length} existing certificates`);
+  } catch (error) {
+    if (certConfigs.some((c) => c.manual)) {
+      console.log(`      ${chalk.yellow('⚠')} Could not list certificates via API: ${chalk.gray(error.message)}`);
+      existingCerts = [];
+    } else {
+      throw error;
+    }
+  }
+
+  const certificateMap = {};
+  const planned = [];
+  let downloaded = 0;
+  let created = 0;
+  let synced = 0;
+  let manualMissing = 0;
+
+  for (const certConfig of certConfigs) {
+    const { type, manual } = certConfig;
+    const certPath = join(appleDir, 'certificates', `${type}.cer`);
+
+    console.log(`      ${chalk.dim('•')} ${chalk.cyan(type)}`);
+
+    const validCert = findValidCertificate(existingCerts, type);
+
+    if (validCert) {
+      certificateMap[type] = trimCert(validCert);
+
+      if (!jetpack.exists(certPath)) {
+        if (dryRun) {
+          console.log(`        ${chalk.cyan('[DRY RUN]')} Would download .cer + export .p12`);
+          planned.push(`download ${type}`);
+        } else {
+          await downloadCertificate(appleClient, validCert.id, certPath);
+          exportToP12(type, appleDir, certificatePassword);
+          downloaded++;
+        }
+      } else {
+        console.log(`        ${chalk.green('✓')} Valid cert exists ${chalk.dim(`(expires ${validCert.attributes.expirationDate})`)}`);
+        if (!dryRun) {
+          exportToP12(type, appleDir, certificatePassword); // no-op unless the .p12 is stale
+        }
+        synced++;
+      }
+      continue;
+    }
+
+    if (manual) {
+      let validation = validateManualCertificate(certPath);
+
+      // Interactive rescue: only the Account Holder can CREATE Developer ID
+      // certs (portal-only — no API path), but the CSR, the download, and
+      // the install are ours to automate. Non-interactive runs keep the
+      // print-and-warn + converge-on-rerun contract below.
+      if (!validation.valid && canPrompt(context.options)) {
+        const { installed } = await runManualCertWalkthrough({
+          type,
+          certPath,
+          appleDir,
+          teamId: appleSecrets.teamId,
+          ...(context.downloadsDir ? { downloadsDir: context.downloadsDir } : {}),
+        });
+        if (installed) {
+          validation = validateManualCertificate(certPath);
+        }
+      }
+
+      if (validation.valid) {
+        const expDate = validation.expirationDate.toISOString().split('T')[0];
+        console.log(`        ${chalk.green('✓')} Local file valid ${chalk.dim(`(expires ${expDate})`)}`);
+        if (!dryRun) {
+          exportToP12(type, appleDir, certificatePassword);
+        }
+        certificateMap[type] = {
+          id: 'manual',
+          certificateType: type,
+          expirationDate: validation.expirationDate.toISOString(),
+        };
+        synced++;
+      } else {
+        console.log(`        ${chalk.red('✗')} ${validation.reason} — Apple requires Account Holder login to issue this type`);
+        console.log(`        ${chalk.gray('→')} Download the .cer from ${chalk.cyan(APPLE_PORTAL_CERTIFICATES_URL)}`);
+        console.log(`        ${chalk.gray('→')} Save it to ${chalk.gray(certPath)} and re-run`);
+        manualMissing++;
+      }
+      continue;
+    }
+
+    if (dryRun) {
+      console.log(`        ${chalk.cyan('[DRY RUN]')} Would create via CSR + download + export .p12`);
+      planned.push(`create ${type}`);
+      continue;
+    }
+
+    const csrContent = getCSRContent(type, appleDir, appleSecrets.teamId);
+    const newCert = await createCertificate(appleClient, type, csrContent);
+    console.log(`        ${chalk.green('✓')} Created ${chalk.dim(`(expires ${newCert.attributes.expirationDate})`)}`);
+    await downloadCertificate(appleClient, newCert.id, certPath);
+    exportToP12(type, appleDir, certificatePassword);
+    certificateMap[type] = trimCert(newCert);
+    created++;
+  }
+
+  // Import config-listed .p12 files into the login keychain (macOS only)
+  if (!dryRun) {
+    keychainImport({
+      certificatesDir: join(appleDir, 'certificates'),
+      keychainPassword: appleSecrets.keychainPassword,
+      certificatePassword,
+      allowedTypes: certConfigs.map((c) => c.type),
+    });
+  }
+
+  const summary = dryRun
+    ? { planned }
+    : { synced, downloaded, created };
+
+  if (manualMissing > 0) {
+    console.log(`      ${chalk.yellow('⚠')} ${manualMissing} manual cert(s) missing — download from the Apple Developer portal and re-run`);
+    return {
+      state: { certificateMap },
+      output: { certificates: { ...summary, manualMissing } },
+      status: 'warned',
+      reason: `${manualMissing} manual cert(s) missing — download them from the Apple Developer portal`,
+    };
+  }
+
+  return { state: { certificateMap }, output: { certificates: summary } };
+});

package/dist/services/certificates/ensure/profiles.js

@@ -0,0 +1,143 @@
+/**
+ * Ensure provisioning profiles exist for the brand's bundle ID × every
+ * applicable cert type/platform combo, downloading each to
+ * .omega/certificates/apple/profiles/{BRAND_ID}/{CERT_TYPE}/{PLATFORM}.mobileprovision
+ * (delete the local file to force a re-download). The brand segment matters:
+ * the signing tree is shared at companyRoot, but a profile binds ONE bundle
+ * ID — without the segment, sibling brands overwrite each other's profiles.
+ *
+ * Reads the bundle ID + certificateMap the previous handlers stashed in
+ * state. Device lists are fetched lazily — only when a development
+ * profile actually needs creating (omega-manager fetched them every run).
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+const { catchAgreements } = require('../lib/apple-api.js');
+
+const {
+  listProfiles,
+  listDevices,
+  downloadProfile,
+  createProfile,
+  findValidProfile,
+  getProfileTypeForCertType,
+  certAppliesToPlatform,
+} = require('../lib/profile-manager.js');
+
+module.exports = catchAgreements(async (context) => {
+  const { appleClient, appleDir, brandConfig, brandId, serviceData } = context;
+  const dryRun = context.options?.dryRun || false;
+
+  const bundleId = serviceData?.bundleId;
+  if (!bundleId?.id) {
+    if (dryRun) {
+      console.log(`      ${chalk.cyan('[DRY RUN]')} Bundle ID not created yet — profiles follow once it exists`);
+      return { output: { profiles: { planned: 'after bundle ID exists' } } };
+    }
+    console.log(`      ${chalk.yellow('⚠')} No bundle ID resolved — skipping`);
+    return {};
+  }
+
+  const certificateMap = serviceData?.certificateMap || {};
+  if (Object.keys(certificateMap).length === 0) {
+    console.log(`      ${chalk.yellow('⚠')} No certificates available — skipping`);
+    return {};
+  }
+
+  const profilesDir = join(appleDir, 'profiles');
+  const profileCertTypes = brandConfig.certificates.providers?.apple?.profiles || [];
+  const brandName = brandConfig.brand?.name || brandId;
+
+  const existingProfiles = await listProfiles(appleClient);
+  console.log(`      ${chalk.green('✓')} Found ${existingProfiles.length} existing profiles`);
+
+  const profileMap = {};
+  const planned = [];
+  let downloaded = 0;
+  let created = 0;
+  let synced = 0;
+  let deviceIds = null;
+
+  for (const platform of bundleId.platforms) {
+    for (const certType of profileCertTypes) {
+      if (!certAppliesToPlatform(certType, platform)) {
+        continue;
+      }
+
+      const profileType = getProfileTypeForCertType(certType);
+      if (!profileType) {
+        continue; // e.g. MAC_INSTALLER_DISTRIBUTION — no profile needed
+      }
+
+      const cert = certificateMap[certType];
+      if (!cert) {
+        console.log(`      ${chalk.yellow('⚠')} Skipping ${chalk.cyan(certType)} (${platform}) — cert not available`);
+        continue;
+      }
+
+      const profileName = `${brandName} - ${certType} (${platform})`;
+      const profileKey = `${certType.toLowerCase()}-${platform.toLowerCase()}`;
+      const profilePath = join(profilesDir, brandId, certType, `${platform}.mobileprovision`);
+
+      console.log(`      ${chalk.dim('•')} ${chalk.cyan(profileName)}`);
+
+      const validProfile = findValidProfile(existingProfiles, profileType, profileName);
+
+      if (validProfile) {
+        profileMap[profileKey] = { id: validProfile.id, expirationDate: validProfile.attributes.expirationDate };
+
+        if (!jetpack.exists(profilePath)) {
+          if (dryRun) {
+            console.log(`        ${chalk.cyan('[DRY RUN]')} Would download`);
+            planned.push(`download ${profileName}`);
+          } else {
+            await downloadProfile(appleClient, validProfile.id, profilePath);
+            downloaded++;
+          }
+        } else {
+          console.log(`        ${chalk.green('✓')} Valid profile exists ${chalk.dim(`(expires ${validProfile.attributes.expirationDate})`)}`);
+          synced++;
+        }
+        continue;
+      }
+
+      // A cert known only from its local file has no API id to link the
+      // profile to — the account's API key lacks permission to list it.
+      if (cert.id === 'manual') {
+        console.log(`        ${chalk.yellow('⚠')} Cert known only from the local file (API didn't list it) — cannot create the profile; check the API key's permissions`);
+        continue;
+      }
+
+      if (dryRun) {
+        console.log(`        ${chalk.cyan('[DRY RUN]')} Would create + download`);
+        planned.push(`create ${profileName}`);
+        continue;
+      }
+
+      // Development profiles bind devices; distribution profiles don't
+      const requiresDevices = profileType === 'IOS_APP_DEVELOPMENT' || profileType === 'MAC_APP_DEVELOPMENT';
+      if (requiresDevices && deviceIds === null) {
+        const devices = await listDevices(appleClient);
+        deviceIds = devices.map((d) => d.id);
+        console.log(`      ${chalk.green('✓')} Found ${devices.length} registered devices`);
+      }
+
+      const newProfile = await createProfile(
+        appleClient,
+        profileName,
+        profileType,
+        bundleId.id,
+        [cert.id],
+        requiresDevices ? deviceIds : [],
+      );
+      console.log(`        ${chalk.green('✓')} Created ${chalk.dim(`(expires ${newProfile.attributes.expirationDate})`)}`);
+      await downloadProfile(appleClient, newProfile.id, profilePath);
+      profileMap[profileKey] = { id: newProfile.id, expirationDate: newProfile.attributes.expirationDate };
+      created++;
+    }
+  }
+
+  const summary = dryRun ? { planned } : { synced, downloaded, created };
+  return { state: { profiles: profileMap }, output: { profiles: summary } };
+});