@omega.js/manager 0.1.0

package/dist/services/certificates/index.js

@@ -0,0 +1,225 @@
+/**
+ * Certificates service — Apple signing certificates, bundle IDs, and
+ * provisioning profiles for brands with desktop/mobile targets, reconciled
+ * via the App Store Connect API.
+ *
+ * Signing home: ONE Apple account signs everything a company ships, so a
+ * company-managed brand (`.omega/company.json` marker → context.companyRoot)
+ * shares the COMPANY workspace's signing tree; a standalone brand (the
+ * playground today — no parent yet) keeps it brand-local, and the material
+ * simply moves to the company root when one is born. Layout under the
+ * gitignored {companyRoot||brandRoot}/.omega/certificates/apple/:
+ *   AuthKey_*.p8                           (App Store Connect API key — the interactive rescue files it from Downloads)
+ *   certificates/{TYPE}.cer + .p12         (downloaded/created + exported)
+ *   csr/{TYPE}/{private.key,request.csr}   (PRESERVED — the issued cert is paired with this key)
+ *   profiles/{BRAND_ID}/{TYPE}/{PLATFORM}.mobileprovision  (per-brand — profiles bind one bundle ID)
+ *
+ * De-ITW'd from omega-manager: certs lived in the company instance's shared
+ * .output/_shared/ tree (one set for all brands) and the bundle-ID prefix
+ * was hardcoded to the company — the port keeps everything brand-local and
+ * reads certificates.providers.apple.bundleIdPrefix from config. The interactive
+ * rescue for portal-only certs is restored and upgraded (Ian 2026-07-14,
+ * lib/manual-walkthrough.js): the pipeline stages the CSR itself — legacy
+ * sent users to Keychain Access — opens the portal create page Enter-gated,
+ * and watches Downloads for the issued .cer; non-interactive runs keep
+ * printed guidance + converge-on-rerun. The --force-recreate CLI flag was
+ * not ported (delete the local .cer to force a re-download; expired certs
+ * recreate automatically).
+ *
+ * Env (brand .env): APPLE_API_ISSUER, APPLE_API_KEY_ID, APPLE_TEAM_ID
+ * required; CSC_KEY_PASSWORD auto-generated + persisted to the brand .env
+ * on first real run (never rotate it — that orphans existing .p12 files);
+ * APPLE_KEYCHAIN_PASSWORD optional (suppresses macOS keychain prompts).
+ */
+const { join } = require('node:path');
+const { homedir } = require('node:os');
+const { randomBytes } = require('node:crypto');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+const { openBrowserAndPoll } = require('../../vendor/devkit/flows.js');
+
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { canPrompt } = require('../../lib/run-gates.js');
+const { writeEnvValue } = require('../../lib/env-secret.js');
+const { createAppleClient } = require('./lib/apple-api.js');
+const { importP12Files } = require('./lib/keychain.js');
+
+const APPSTORE_KEYS_URL = 'https://appstoreconnect.apple.com/access/api';
+
+/**
+ * Find the user-placed App Store Connect API key (AuthKey_*.p8) in the
+ * brand's Apple dir. Auto-detected by prefix so no path config is needed.
+ *
+ * @param {string} appleDir - {brandRoot}/.omega/certificates/apple
+ * @returns {string|null} - Absolute path to the .p8, or null
+ */
+function findAuthKey(appleDir) {
+  if (!jetpack.exists(appleDir)) {
+    return null;
+  }
+  const p8Files = jetpack.find(appleDir, { matching: 'AuthKey_*.p8', recursive: false });
+  return p8Files[0] || null;
+}
+
+/**
+ * Generate a random CSC_KEY_PASSWORD and persist it to the signing root's
+ * .env (the company workspace when company-managed — shared .p12s need the
+ * ONE shared password, and the env chain loads the company .env under every
+ * sibling brand's — else the brand root).
+ *
+ * .p12 files MUST carry a real password — modern macOS rejects
+ * empty-password .p12 in `security import` ("MAC verification failed").
+ * The value is meaningless to the user; it just has to stay stable, so it
+ * is written back to .env for every future run (and for CI signing).
+ *
+ * @param {string} signingRoot - The signing tree's owning root (its .env is the target)
+ * @returns {string} - The generated password
+ */
+function ensureCertPassword(signingRoot) {
+  const password = randomBytes(24).toString('base64url');
+  writeEnvValue(signingRoot, 'CSC_KEY_PASSWORD', password);
+  console.log(`      ${chalk.green('✓')} Generated CSC_KEY_PASSWORD and saved to the signing root's .env`);
+
+  return password;
+}
+
+/**
+ * Interactive rescue for a missing App Store Connect API key. The .p8
+ * downloads ONCE (Apple never re-serves it), so the walkthrough opens the
+ * keys page Enter-gated and watches Downloads for a fresh AuthKey_*.p8,
+ * filing it into the signing tree. Non-interactive runs keep the skip +
+ * guidance contract.
+ */
+async function rescueAuthKey(appleDir, downloadsDir = join(homedir(), 'Downloads')) {
+  const startedAt = Date.now();
+
+  const result = await openBrowserAndPoll({
+    url: APPSTORE_KEYS_URL,
+    promptMessage: [
+      'An App Store Connect API key is needed (Users and Access → Integrations):',
+      `          1. Generate an API key with the ${chalk.bold('Admin')} role — or download an existing one (each .p8 downloads ONCE)`,
+      '          2. I\'ll detect the AuthKey_*.p8 in Downloads and file it into the signing tree',
+    ].join('\n'),
+    label: 'the App Store Connect API keys page',
+    waitMessage: 'Waiting for the AuthKey_*.p8 download',
+    intervalMs: 3000,
+    check: async () => {
+      for (const name of jetpack.list(downloadsDir) || []) {
+        if (!/^AuthKey_[A-Z0-9]+\.p8$/.test(name)) {
+          continue;
+        }
+        const modified = jetpack.inspect(join(downloadsDir, name), { times: true })?.modifyTime;
+        if (!modified || modified.getTime() < startedAt) {
+          continue;
+        }
+        jetpack.move(join(downloadsDir, name), join(appleDir, name));
+        return { done: true, result: name };
+      }
+      return { done: false };
+    },
+  });
+
+  if (result.success) {
+    console.log(`      ${chalk.green('✓')} Filed ${chalk.cyan(result.result)} into ${chalk.gray(appleDir)}`);
+    return findAuthKey(appleDir);
+  }
+
+  return null;
+}
+
+/**
+ * Resolve the App Store Connect credentials from the environment + the
+ * signing tree. Returns { skip, reason } when anything is missing — except
+ * a missing .p8 on an interactive run, which gets the download rescue.
+ */
+async function resolveAppleSecrets(context, appleDir, signingRoot) {
+  const dryRun = context.options?.dryRun || false;
+
+  // The shared setup contract (#608): an interactive run walks the App Store
+  // Connect keys page and takes the three ids right here; a headless one steps
+  // aside loudly, and "disable" retires the service for this brand.
+  const gate = await requestServiceInput(context, serviceInputSpec('certificates'));
+  if (gate) {
+    return gate;
+  }
+
+  const issuerId = process.env.APPLE_API_ISSUER;
+  const keyId = process.env.APPLE_API_KEY_ID;
+  const teamId = process.env.APPLE_TEAM_ID;
+
+  let privateKeyPath = findAuthKey(appleDir);
+  if (!privateKeyPath && canPrompt(context.options)) {
+    privateKeyPath = await rescueAuthKey(appleDir, context.downloadsDir);
+  }
+  if (!privateKeyPath) {
+    return {
+      skip: true,
+      reason: `no App Store Connect API key found — download the .p8 from ${APPSTORE_KEYS_URL} and save it as AuthKey_<KEYID>.p8 in ${appleDir}`,
+    };
+  }
+
+  let certificatePassword = process.env.CSC_KEY_PASSWORD || '';
+  if (!certificatePassword) {
+    if (dryRun) {
+      console.log(`      ${chalk.cyan('[DRY RUN]')} Would generate CSC_KEY_PASSWORD and save it to the signing root's .env`);
+    } else {
+      certificatePassword = ensureCertPassword(signingRoot);
+      process.env.CSC_KEY_PASSWORD = certificatePassword;
+    }
+  }
+
+  return {
+    secrets: {
+      issuerId,
+      keyId,
+      teamId,
+      privateKeyPath,
+      certificatePassword,
+      keychainPassword: process.env.APPLE_KEYCHAIN_PASSWORD || null,
+    },
+  };
+}
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const config = context.brandConfig.certificates;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'certificates.enabled = false' };
+    }
+
+    const targets = context.brandConfig.targets || {};
+    if (!targets.desktop && !targets.mobile) {
+      return { skip: true, reason: 'no desktop or mobile target' };
+    }
+
+    // One Apple account signs everything a company ships — company-managed
+    // brands share the company workspace's signing tree; standalone brands
+    // keep it brand-local (and the material moves when a company is born)
+    const signingRoot = context.companyRoot || context.brandRoot;
+    const appleDir = join(signingRoot, '.omega', 'certificates', 'apple');
+
+    // Tests inject a fake client + secrets via context
+    let appleClient = context.appleClient;
+    let appleSecrets = context.appleSecrets;
+    if (!appleClient) {
+      const resolved = await resolveAppleSecrets(context, appleDir, signingRoot);
+      if (resolved.skip) {
+        return resolved;
+      }
+      appleSecrets = resolved.secrets;
+      appleClient = createAppleClient(appleSecrets);
+    }
+
+    return {
+      appleClient,
+      appleSecrets,
+      appleDir,
+      // Tests inject a recorder so the real macOS keychain is never touched
+      keychainImport: context.keychainImport || importP12Files,
+    };
+  },
+});

package/dist/services/certificates/lib/apple-api.js

@@ -0,0 +1,183 @@
+/**
+ * App Store Connect API client — ES256 JWT auth over node:crypto + global
+ * fetch (omega-manager used jsonwebtoken + wonderful-fetch; the port needs
+ * neither). Exposes request() (JSON, throws on non-2xx with Apple's error
+ * text) and paginate() (follows links.next).
+ *
+ * Apple's "agreements expired" 403 gets a printed fix-it (accept the
+ * pending agreements at the developer site) — omega-manager auto-opened
+ * the browser; the port prints the URL and stays non-interactive.
+ */
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const { signJwt } = require('../../../lib/jwt.js');
+
+const API_BASE = 'https://api.appstoreconnect.apple.com/v1';
+
+// Universal Apple Developer landing — pending agreements surface here as a
+// banner (the per-team agreement URL is unique per developer account).
+const APPLE_AGREEMENTS_URL = 'https://developer.apple.com/account/';
+
+const TOKEN_TTL_SECONDS = 20 * 60; // Apple max — 20 minutes
+const TOKEN_REFRESH_BUFFER_SECONDS = 5 * 60; // Refresh 5 min before expiry
+
+// Print the agreements guidance once per process — multiple API calls
+// hitting the same 403 shouldn't repeat it.
+let agreementsNoticePrinted = false;
+
+/**
+ * Detect Apple's "agreements expired" 403 from an error message. Matches
+ * BOTH the error code and the human title — live 2026-07-14: the message
+ * carried only title+detail (no code) and the code-only detector missed it,
+ * so the first certificates exercise errored raw instead of warning.
+ */
+function isAgreementsError(errorMessage) {
+  return /FORBIDDEN\.REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED|required agreement is missing or has expired/i.test(errorMessage || '');
+}
+
+/**
+ * Wrap an ensure operation so Apple's agreements 403 downgrades to a WARNED
+ * result with the fix-it guidance — a pending agreement is a human-gated
+ * prerequisite (the AdSense-approval pattern), not a service failure.
+ * Anything else rethrows untouched.
+ */
+function catchAgreements(operation) {
+  const warnedResult = () => {
+    printAgreementsNotice();
+    return {
+      status: 'warned',
+      reason: 'Apple Developer agreements need acceptance',
+      output: {
+        agreements: 'pending',
+        warning: `Apple Developer agreements need acceptance — visit ${APPLE_AGREEMENTS_URL} (Paid Apps / Free Apps / Program License), then re-run`,
+      },
+    };
+  };
+
+  return async function agreementsGuarded(context) {
+    let result;
+    try {
+      result = await operation(context);
+    } catch (error) {
+      if (!isAgreementsError(error?.message)) {
+        throw error;
+      }
+      return warnedResult();
+    }
+
+    // The ensures also catch internally and RETURN error statuses — an
+    // agreements 403 must downgrade on that path too
+    if (result?.status === 'error' && isAgreementsError(result.error)) {
+      return warnedResult();
+    }
+
+    return result;
+  };
+}
+
+function printAgreementsNotice() {
+  if (agreementsNoticePrinted) {
+    return;
+  }
+  agreementsNoticePrinted = true;
+  console.log('');
+  console.log(`      ${chalk.yellow('⚠')} ${chalk.bold('Apple Developer Program agreements need to be accepted')}`);
+  console.log(`      ${chalk.gray('→')} Visit ${chalk.cyan(APPLE_AGREEMENTS_URL)}, accept all pending agreements (Paid Apps, Free Apps, Developer Program License), then re-run`);
+  console.log('');
+}
+
+/**
+ * Build an authenticated App Store Connect client.
+ *
+ * @param {Object} secrets - { issuerId, keyId, privateKeyPath }
+ * @returns {{ request: Function, paginate: Function }}
+ */
+function createAppleClient(secrets) {
+  const privateKey = jetpack.read(secrets.privateKeyPath);
+  if (!privateKey) {
+    throw new Error(`Failed to read App Store Connect private key from ${secrets.privateKeyPath}`);
+  }
+
+  let cachedToken = null;
+  let tokenExpiresAt = 0;
+
+  function getToken() {
+    const now = Math.floor(Date.now() / 1000);
+    if (!cachedToken || now >= tokenExpiresAt - TOKEN_REFRESH_BUFFER_SECONDS) {
+      cachedToken = signJwt(
+        { alg: 'ES256', kid: secrets.keyId, typ: 'JWT' },
+        { iss: secrets.issuerId, iat: now, exp: now + TOKEN_TTL_SECONDS, aud: 'appstoreconnect-v1' },
+        privateKey,
+      );
+      tokenExpiresAt = now + TOKEN_TTL_SECONDS;
+    }
+    return cachedToken;
+  }
+
+  /**
+   * JSON request to the App Store Connect API. Returns the parsed body
+   * (null for 204/allowed-404). Throws with Apple's error text otherwise.
+   *
+   * @param {string} url - Full URL
+   * @param {Object} [options] - { method, body, allow404 }
+   */
+  async function request(url, options = {}) {
+    const { method = 'GET', body, allow404 = false } = options;
+
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Authorization: `Bearer ${getToken()}`,
+        'Content-Type': 'application/json',
+      },
+      body: body || undefined,
+      signal: AbortSignal.timeout(60000),
+    });
+
+    if (response.status === 404 && allow404) {
+      return null;
+    }
+    if (response.status === 204) {
+      return null;
+    }
+
+    const data = await response.json().catch(() => null);
+
+    if (!response.ok) {
+      // Keep Apple's error CODE in the message — detectors and humans both
+      // need it (title+detail alone hid REQUIRED_AGREEMENTS_MISSING_OR_EXPIRED)
+      const message = (data?.errors || [])
+        .map((e) => `${e.code ? `[${e.code}] ` : ''}${e.title}: ${e.detail || ''}`.trim())
+        .join('; ')
+        || `HTTP ${response.status}`;
+
+      if (isAgreementsError(message)) {
+        printAgreementsNotice();
+      }
+
+      throw new Error(`Apple API request failed (${method} ${url}): ${message}`);
+    }
+
+    return data;
+  }
+
+  /**
+   * Paginated GET — follows `links.next` until exhausted and returns the
+   * concatenated `data` array.
+   */
+  async function paginate(url) {
+    let all = [];
+    let nextUrl = url;
+    while (nextUrl) {
+      const data = await request(nextUrl);
+      all = all.concat(data?.data || []);
+      nextUrl = data?.links?.next || null;
+    }
+    return all;
+  }
+
+  return { request, paginate };
+}
+
+module.exports = { API_BASE, createAppleClient, isAgreementsError, catchAgreements };

package/dist/services/certificates/lib/certificate-manager.js

@@ -0,0 +1,252 @@
+/**
+ * Certificate CRUD + local key material: list/create/download signing
+ * certificates via the App Store Connect API, generate CSRs with openssl,
+ * export .cer + private key pairs to Keychain-importable .p12 files, and
+ * validate manually-downloaded .cer files.
+ *
+ * openssl notes (both verified against OpenSSL 3.x, which auto-detects
+ * DER/PEM input): Apple serves .cer files as DER; `pkcs12 -export -legacy`
+ * forces the older PBE-SHA1-3DES format because macOS `security import`
+ * rejects OpenSSL 3's default PBES2/AES-256-CBC ("MAC verification
+ * failed").
+ */
+const { execFileSync } = require('node:child_process');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+
+const { isStale } = require('../../../lib/stale.js');
+const { API_BASE } = require('./apple-api.js');
+
+/**
+ * List all certificates (paginated).
+ */
+async function listCertificates(client) {
+  return client.paginate(`${API_BASE}/certificates?limit=200`);
+}
+
+/**
+ * Download a certificate's .cer content (base64-decoded DER) to disk.
+ */
+async function downloadCertificate(client, certificateId, outputPath) {
+  const data = await client.request(`${API_BASE}/certificates/${certificateId}`);
+  const certificateContent = data?.data?.attributes?.certificateContent;
+  if (!certificateContent) {
+    throw new Error(`Certificate ${certificateId} has no certificateContent`);
+  }
+  jetpack.write(outputPath, Buffer.from(certificateContent, 'base64'));
+  console.log(`        ${chalk.green('✓')} Downloaded ${chalk.gray(outputPath)}`);
+}
+
+/**
+ * Create a new certificate by submitting a CSR.
+ */
+async function createCertificate(client, type, csrContent) {
+  const data = await client.request(`${API_BASE}/certificates`, {
+    method: 'POST',
+    body: JSON.stringify({
+      data: {
+        type: 'certificates',
+        attributes: { certificateType: type, csrContent },
+      },
+    }),
+  });
+  return data.data;
+}
+
+/**
+ * Generate a new RSA-2048 private key + CSR via openssl. Writes
+ * `private.key` and `request.csr` to outputDir; returns the cleaned CSR
+ * body (no PEM headers/newlines) ready to POST to Apple.
+ */
+function generateCSR(emailAddress, commonName, outputDir) {
+  jetpack.dir(outputDir);
+  const keyPath = `${outputDir}/private.key`;
+  const csrPath = `${outputDir}/request.csr`;
+  const subject = `/emailAddress=${emailAddress}/CN=${commonName}/C=US`;
+
+  execFileSync(
+    'openssl',
+    ['req', '-nodes', '-newkey', 'rsa:2048', '-keyout', keyPath, '-out', csrPath, '-subj', subject],
+    { stdio: 'pipe' },
+  );
+
+  return cleanCSR(jetpack.read(csrPath));
+}
+
+/**
+ * Get CSR content for a cert type, reusing an existing CSR when found.
+ *
+ * IMPORTANT: CSR private keys must be preserved across runs — they're
+ * paired with the issued certificate. Deleting a CSR private key while a
+ * matching cert is active makes the cert unusable for signing.
+ */
+function getCSRContent(type, appleDir, teamId) {
+  const csrDir = `${appleDir}/csr/${type}`;
+  const csrPath = `${csrDir}/request.csr`;
+
+  if (jetpack.exists(csrPath)) {
+    console.log(`        ${chalk.gray('ℹ')} Reusing existing CSR from ${csrPath}`);
+    return cleanCSR(jetpack.read(csrPath));
+  }
+
+  console.log(`        Generating new CSR...`);
+  return generateCSR(`${teamId}@apple.com`, `${type} Certificate`, csrDir);
+}
+
+function cleanCSR(csrContent) {
+  return csrContent
+    .replace('-----BEGIN CERTIFICATE REQUEST-----', '')
+    .replace('-----END CERTIFICATE REQUEST-----', '')
+    .replace(/\n/g, '');
+}
+
+/**
+ * Export the .cer + private.key pair to a Keychain-importable .p12.
+ *
+ * No-ops when the .cer is missing or when the .p12 is already fresher than
+ * the .cer (mtime diff — a converged brand runs zero openssl execs). A cert
+ * WITHOUT its paired key warns instead of silently skipping: that cert
+ * can't sign anything until csr/{TYPE}/private.key arrives from the machine
+ * whose CSR created it.
+ */
+function exportToP12(type, appleDir, certificatePassword = '') {
+  const certPath = `${appleDir}/certificates/${type}.cer`;
+  const keyPath = `${appleDir}/csr/${type}/private.key`;
+  const p12Path = `${appleDir}/certificates/${type}.p12`;
+
+  if (!jetpack.exists(certPath)) {
+    return;
+  }
+  if (!jetpack.exists(keyPath)) {
+    console.log(`        ${chalk.yellow('⚠')} No local private key for ${type} — .p12 not exported (copy csr/${type}/private.key from the machine that created the CSR, then re-run)`);
+    return;
+  }
+  if (!isStale(certPath, p12Path)) {
+    return;
+  }
+
+  try {
+    // -legacy: macOS `security import` requires the old PKCS12 format.
+    // Password rides an env var (-passout env:) — never argv, never a shell string.
+    execFileSync(
+      'openssl',
+      ['pkcs12', '-export', '-legacy', '-inkey', keyPath, '-in', certPath, '-out', p12Path, '-passout', 'env:OMEGA_P12_PASSWORD'],
+      { stdio: 'pipe', env: { ...process.env, OMEGA_P12_PASSWORD: certificatePassword } },
+    );
+    console.log(`        ${chalk.green('✓')} Exported .p12 ${chalk.gray(p12Path)}`);
+  } catch (error) {
+    console.log(`        ${chalk.yellow('⚠')} Failed to export .p12: ${chalk.gray(error.message)}`);
+  }
+}
+
+/**
+ * Find a non-expired certificate of the given type, preferring the one
+ * that expires furthest in the future.
+ */
+function findValidCertificate(existingCerts, type) {
+  const now = new Date();
+  const validCerts = existingCerts.filter((cert) => {
+    return cert.attributes.certificateType === type
+      && new Date(cert.attributes.expirationDate) > now;
+  });
+
+  if (validCerts.length === 0) {
+    return null;
+  }
+
+  return validCerts.sort((a, b) => {
+    return new Date(b.attributes.expirationDate) - new Date(a.attributes.expirationDate);
+  })[0];
+}
+
+/**
+ * Validate a manually-downloaded .cer via openssl (exists + not expired).
+ * Manual types (DEVELOPER_ID_*) can only be downloaded from the developer
+ * portal — the API doesn't allow creating them.
+ *
+ * @returns {{ valid: boolean, expirationDate: Date|null, reason: string|null }}
+ */
+function validateManualCertificate(certPath) {
+  if (!jetpack.exists(certPath)) {
+    return { valid: false, expirationDate: null, reason: 'file not found' };
+  }
+
+  try {
+    const endDateOutput = execFileSync(
+      'openssl',
+      ['x509', '-enddate', '-noout', '-in', certPath],
+      { encoding: 'utf8', stdio: 'pipe' },
+    ).trim();
+
+    const dateMatch = endDateOutput.match(/notAfter=(.+)/);
+    if (!dateMatch) {
+      return { valid: false, expirationDate: null, reason: 'could not parse expiration date' };
+    }
+
+    const expirationDate = new Date(dateMatch[1]);
+    if (expirationDate <= new Date()) {
+      return { valid: false, expirationDate, reason: 'expired' };
+    }
+
+    return { valid: true, expirationDate, reason: null };
+  } catch (error) {
+    return { valid: false, expirationDate: null, reason: error.message };
+  }
+}
+
+/**
+ * Common Name of a certificate's subject (openssl auto-detects DER/PEM).
+ * Apple stamps the portal type into the CN ("Developer ID Installer: Team
+ * Name (TEAMID)") — how a downloaded .cer is matched to the expected type.
+ *
+ * @returns {string|null}
+ */
+function getCertificateCommonName(certPath) {
+  try {
+    const subject = execFileSync(
+      'openssl',
+      ['x509', '-subject', '-noout', '-in', certPath],
+      { encoding: 'utf8', stdio: 'pipe' },
+    );
+    const match = subject.match(/CN\s*=\s*([^,]+)/);
+    return match ? match[1].trim() : null;
+  } catch (error) {
+    return null;
+  }
+}
+
+/**
+ * Whether the certificate's public key pairs with the private key (modulus
+ * comparison) — proof a portal-downloaded .cer was issued from the
+ * pipeline's own CSR, so the .p12 export has its pair.
+ */
+function certificateMatchesKey(certPath, keyPath) {
+  try {
+    const certModulus = execFileSync(
+      'openssl',
+      ['x509', '-modulus', '-noout', '-in', certPath],
+      { encoding: 'utf8', stdio: 'pipe' },
+    ).trim();
+    const keyModulus = execFileSync(
+      'openssl',
+      ['rsa', '-modulus', '-noout', '-in', keyPath],
+      { encoding: 'utf8', stdio: 'pipe' },
+    ).trim();
+    return certModulus.length > 0 && certModulus === keyModulus;
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = {
+  listCertificates,
+  downloadCertificate,
+  createCertificate,
+  generateCSR,
+  getCSRContent,
+  exportToP12,
+  findValidCertificate,
+  validateManualCertificate,
+  getCertificateCommonName,
+  certificateMatchesKey,
+};