@omega.js/manager 0.1.0

package/dist/services/campaigns/index.js

@@ -0,0 +1,79 @@
+/**
+ * Campaigns service (SendGrid provider) — the brand's email-marketing infrastructure: domain
+ * authentication (DKIM/SPF CNAMEs written via Cloudflare), link branding for
+ * the emailurl host (validated, then the CNAME flips proxied), a verified sender
+ * for Single Sends, the brand's marketing list, the unsubscribe groups
+ * @omega.js/backend sends through, @omega.js/backend's custom fields and
+ * segments (from @omega.js/backend's SSOT), and the account-global Event
+ * Webhook pointed at the parent @omega.js/backend's forwarder.
+ *
+ * Runs after cloudflare (the zone must exist for the DKIM records). The
+ * whole service reconciles one SendGrid account per brand-or-company — the
+ * groups/fields/segments/webhook operations converge to the same result when
+ * sibling brands share the account.
+ *
+ * Auth: SENDGRID_API_KEY in the brand .env; the event-webhook operation
+ * additionally needs OMEGA_WEBHOOK_KEY, which the setup MINTS through the
+ * shared contract (it is OMEGA's own key, #635). No API key → clean skip.
+ */
+const { chosenProvider } = require('../../vendor/config/index.js');
+
+const { serviceInputSpec } = require('../../config.js');
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { requestServiceInput } = require('../../lib/service-input.js');
+const { CloudflareAPI } = require('../edge/lib/cloudflare-api.js');
+const { getApexDomain } = require('../../lib/domain-utils.js');
+const { SendGridAPI } = require('./lib/sendgrid-api.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const campaigns = context.brandConfig.marketing?.campaigns || {};
+
+    if (campaigns.enabled === false) {
+      return { skip: true, reason: 'marketing.campaigns.enabled = false' };
+    }
+
+    // The vendor is a KEY under marketing.campaigns.providers (#425) — no
+    // entry means none chosen and this service skips.
+    const provider = chosenProvider(campaigns.providers);
+    if (!provider) {
+      return { skip: true, reason: 'no marketing.campaigns.providers entry' };
+    }
+    if (provider !== 'sendgrid') {
+      return { skip: true, reason: `marketing.campaigns.providers.${provider} is not a known email-marketing provider` };
+    }
+
+    const domain = (context.brandConfig.brand?.url || '').replace(/^https?:\/\//, '').replace(/\/$/, '');
+    if (!domain) {
+      return { skip: true, reason: 'no brand.url configured' };
+    }
+
+    if (!context.sendgridApi) {
+      const gate = await requestServiceInput(context, serviceInputSpec('campaigns', { names: ['SENDGRID_API_KEY'] }));
+      if (gate) return gate;
+    }
+
+    // The webhook key is OMEGA's OWN (#635): the shared helper mints it in
+    // place when this service runs before the workspace one did, so the
+    // webhook operation can read it unconditionally.
+    const webhookKeyGate = await requestServiceInput(context, serviceInputSpec('campaigns', { names: ['OMEGA_WEBHOOK_KEY'] }));
+    if (webhookKeyGate) return webhookKeyGate;
+
+    // Tests inject fake clients via context.sendgridApi / context.cloudflareApi.
+    // Cloudflare is only needed while the domain still has to be DNS-verified
+    // (and for the link-branding proxy flip); without a token the domain-auth
+    // operation prints the records to add manually and link-branding prints the
+    // manual flip.
+    return {
+      sendgridApi: context.sendgridApi || new SendGridAPI(),
+      cloudflareApi: context.cloudflareApi
+        || (process.env.CLOUDFLARE_TOKEN ? new CloudflareAPI() : null),
+      domain,
+      apexDomain: getApexDomain(domain),
+      // A subdomain project's apex records belong to the PARENT brand's walk
+      // (the same line the edge service draws) — link-branding skips on it.
+      isSubdomainProject: domain !== getApexDomain(domain),
+    };
+  },
+});

package/dist/services/campaigns/lib/dns-sync.js

@@ -0,0 +1,81 @@
+/**
+ * Diff-sync a SendGrid record set into the brand's Cloudflare apex zone — the
+ * ONE writer both whitelabel operations share (domain authentication's DKIM
+ * CNAMEs, link branding's two link CNAMEs).
+ *
+ * Exact match = untouched, wrong content = patched, missing = created. Every
+ * record lands UNPROXIED: SendGrid validates each of them by resolving the
+ * host as a plain CNAME, and a proxied record answers with Cloudflare's own
+ * addresses instead. No Cloudflare token (or no zone yet) prints the records
+ * to add by hand, so a manual fix converges on the rerun.
+ */
+const chalk = require('chalk').default;
+
+/**
+ * @param {object|null} cloudflareApi - The Cloudflare client (null without a token)
+ * @param {string} apexDomain - The zone the records belong to
+ * @param {Array<{ key: string, record: object }>} records - SendGrid's own
+ *   record set, each entry keyed by the name SendGrid gives it
+ * @returns {Promise<boolean>} - true when records were written via Cloudflare,
+ *   false when they were printed for manual addition
+ */
+async function syncDnsRecords(cloudflareApi, apexDomain, records) {
+  if (!cloudflareApi) {
+    console.log(`      ${chalk.yellow('⚠')} No CLOUDFLARE_TOKEN — add these records manually, then rerun:`);
+    logManualRecords(records);
+    return false;
+  }
+
+  const zone = await cloudflareApi.getZoneByName(apexDomain);
+  if (!zone) {
+    console.log(`      ${chalk.yellow('⚠')} No Cloudflare zone for ${chalk.cyan(apexDomain)} — add these records manually (or rerun once the cloudflare service creates the zone):`);
+    logManualRecords(records);
+    return false;
+  }
+
+  const existing = await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records?type=CNAME&per_page=100`, { method: 'GET' });
+  const existingRecords = existing.result || [];
+
+  for (const { key, record } of records) {
+    const type = record.type.toUpperCase();
+    const name = record.host;
+    const content = record.data;
+
+    const match = existingRecords.find((r) => r.type === type && r.name === name);
+
+    if (match && match.content === content) {
+      console.log(`      ${chalk.dim('→')} ${chalk.dim(key)}: ${chalk.cyan(name)} already in place`);
+      continue;
+    }
+
+    if (match) {
+      await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records/${match.id}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ type, name, content, ttl: 1, proxied: false }),
+      });
+      console.log(`      ${chalk.yellow('↻')} ${chalk.dim(key)}: updated ${chalk.cyan(name)}`);
+      continue;
+    }
+
+    await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records`, {
+      method: 'POST',
+      body: JSON.stringify({ type, name, content, ttl: 1, proxied: false, comment: `SendGrid ${key}` }),
+    });
+    console.log(`      ${chalk.green('✓')} ${chalk.dim(key)}: created ${chalk.cyan(name)}`);
+  }
+
+  return true;
+}
+
+function logManualRecords(records) {
+  for (const { record } of records) {
+    console.log(`        ${chalk.cyan(record.type.toUpperCase())} ${record.host} → ${record.data}`);
+  }
+}
+
+/** The manualRecords shape a warned return carries when nothing was written. */
+function manualRecordList(records) {
+  return records.map(({ record }) => ({ type: record.type.toUpperCase(), name: record.host, content: record.data }));
+}
+
+module.exports = { syncDnsRecords, manualRecordList };

package/dist/services/campaigns/lib/segment-query.js

@@ -0,0 +1,138 @@
+/**
+ * @omega.js/backend segment conditions → SendGrid query_dsl (the SQL-like segment query
+ * language). Pure functions, ported behavior-for-behavior from omega-manager
+ * — the generated SQL is compared against live segments for staleness, so
+ * any change here re-syncs every segment on the next run.
+ */
+const { BACKEND_FIELDS_MAP } = require('../../../lib/backend-marketing.js');
+
+/**
+ * Convert a @omega.js/backend field condition to a WHERE clause fragment. Custom fields
+ * are referenced by name (double-quoted) in query_dsl, not by internal ID.
+ */
+function fieldConditionToWhere(condition) {
+  const fieldDef = BACKEND_FIELDS_MAP[condition.field];
+  if (!fieldDef) {
+    throw new Error(`Unknown field "${condition.field}" in segment condition`);
+  }
+
+  const col = `"${condition.field}"`;
+
+  switch (condition.op) {
+    case '==':
+      return `${col} = '${condition.value}'`;
+    case '!=':
+      return `${col} != '${condition.value}'`;
+    case 'within': {
+      const days = parseInt(condition.value, 10);
+      return `${col} > timestampadd(day, -${days}, CURRENT_TIMESTAMP)`;
+    }
+    case 'not_within': {
+      const days = parseInt(condition.value, 10);
+      return `${col} <= timestampadd(day, -${days}, CURRENT_TIMESTAMP)`;
+    }
+    default:
+      throw new Error(`Unsupported field condition op "${condition.op}"`);
+  }
+}
+
+/** Contact conditions use built-in contact_data columns (email, first_name, …). */
+function contactConditionToWhere(condition) {
+  switch (condition.op) {
+    case 'email_is':
+      return `email = '${condition.value}'`;
+    case 'email_like':
+      return `email LIKE '${condition.value}'`;
+    default:
+      throw new Error(`Unsupported contact condition op "${condition.op}"`);
+  }
+}
+
+function conditionToWhere(condition) {
+  if (condition.type === 'engagement') {
+    return null; // Handled separately in buildQueryDsl
+  }
+  if (condition.type === 'contact') {
+    return contactConditionToWhere(condition);
+  }
+  return fieldConditionToWhere(condition);
+}
+
+/**
+ * Build a complete query_dsl from @omega.js/backend segment conditions. Engagement
+ * conditions need event_data (JOIN or subqueries); field/contact conditions
+ * query contact_data directly.
+ */
+function buildQueryDsl(conditions, logic) {
+  const engagementConditions = conditions.filter((c) => c.type === 'engagement');
+  const nonEngagementConditions = conditions.filter((c) => c.type !== 'engagement');
+  const joiner = logic === 'or' ? ' OR ' : ' AND ';
+
+  const fieldWhereParts = nonEngagementConditions.map((c) => conditionToWhere(c)).filter(Boolean);
+
+  // No engagement — simple contact_data query
+  if (engagementConditions.length === 0) {
+    const whereClause = fieldWhereParts.length > 0
+      ? ` WHERE ${fieldWhereParts.join(joiner)}`
+      : '';
+    return `SELECT contact_id, updated_at FROM contact_data${whereClause}`;
+  }
+
+  // Positive engagement (opened_or_clicked) uses a JOIN
+  const positiveEngagement = engagementConditions.find((c) => c.op === 'opened_or_clicked');
+  if (positiveEngagement) {
+    const days = parseInt(positiveEngagement.value, 10);
+    const threshold = `timestampadd(day, -${days}, CURRENT_TIMESTAMP)`;
+    const engWhere = `(e.event_type = 'open' OR e.event_type = 'click') AND e.timestamp > ${threshold}`;
+    const allWhere = [...fieldWhereParts, engWhere];
+    return `SELECT c.contact_id, c.updated_at FROM contact_data c`
+      + ` JOIN event_data e ON c.contact_id = e.contact_id`
+      + ` WHERE ${allWhere.join(joiner)}`;
+  }
+
+  // Negative/count engagement conditions use subqueries (combinable)
+  const engagementWhereParts = engagementConditions.map((engagement) => {
+    switch (engagement.op) {
+      case 'not_opened': {
+        const days = parseInt(engagement.value, 10);
+        const threshold = `timestampadd(day, -${days}, CURRENT_TIMESTAMP)`;
+        return `contact_id NOT IN (`
+          + `SELECT contact_id FROM event_data WHERE event_type = 'open' AND timestamp > ${threshold}`
+          + `)`;
+      }
+      case 'not_opened_or_clicked': {
+        const days = parseInt(engagement.value, 10);
+        const threshold = `timestampadd(day, -${days}, CURRENT_TIMESTAMP)`;
+        return `contact_id NOT IN (`
+          + `SELECT contact_id FROM event_data WHERE (event_type = 'open' OR event_type = 'click') AND timestamp > ${threshold}`
+          + `)`;
+      }
+      case 'received_gte': {
+        // SendGrid has no GROUP BY / HAVING — approximate >=N delivered events
+        // by requiring one in each of N distinct time windows. The window size
+        // comes from the sibling time-based engagement condition's period.
+        const minCount = parseInt(engagement.value, 10);
+        const timeEng = engagementConditions.find((c) => c.op !== 'received_gte');
+        const totalDays = timeEng ? parseInt(timeEng.value, 10) : 180;
+        const windowSize = Math.floor(totalDays / minCount);
+
+        return '(' + Array.from({ length: minCount }, (_, i) => {
+          const start = i * windowSize;
+          const end = (i + 1) * windowSize;
+          return `contact_id IN (`
+            + `SELECT contact_id FROM event_data WHERE event_type = 'delivered'`
+            + ` AND timestamp > timestampadd(day, -${end}, CURRENT_TIMESTAMP)`
+            + ` AND timestamp <= timestampadd(day, -${start}, CURRENT_TIMESTAMP)`
+            + `)`;
+        }).join(' AND ') + ')';
+      }
+      default:
+        throw new Error(`Unsupported engagement op "${engagement.op}"`);
+    }
+  });
+
+  const allWhere = [...fieldWhereParts, ...engagementWhereParts];
+  return `SELECT contact_id, updated_at FROM contact_data WHERE ${allWhere.join(joiner)}`;
+}
+
+module.exports = { buildQueryDsl };

package/dist/services/campaigns/lib/sendgrid-api.js

@@ -0,0 +1,287 @@
+/**
+ * SendGrid v3 API client — marketing (lists, custom fields, segments),
+ * unsubscribe groups, verified senders, domain authentication, and the
+ * account-global Event Webhook. Named-method surface so tests can fake it
+ * method-for-method.
+ *
+ * Auth: SENDGRID_API_KEY in the brand .env.
+ */
+const SENDGRID_API_BASE = 'https://api.sendgrid.com/v3';
+
+class SendGridAPI {
+  constructor(options = {}) {
+    this.apiKey = options.apiKey || process.env.SENDGRID_API_KEY;
+  }
+
+  async makeRequest(endpoint, options = {}) {
+    const response = await fetch(`${SENDGRID_API_BASE}${endpoint}`, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${this.apiKey}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    // 204 No Content / 202 Accepted come back bodyless
+    if (response.status === 204 || response.status === 202) {
+      return null;
+    }
+
+    const text = await response.text();
+    if (!text) {
+      if (!response.ok) {
+        throw new Error(`SendGrid API error (${response.status}): ${response.statusText}`);
+      }
+      return null;
+    }
+
+    const data = JSON.parse(text);
+
+    if (!response.ok) {
+      const message = data.errors?.map((e) => e.message).join(', ')
+        || data.message
+        || data.error
+        || response.statusText;
+      throw new Error(`SendGrid API error (${response.status}): ${message}`);
+    }
+
+    return data;
+  }
+
+  // ========== Marketing lists ==========
+
+  /** All marketing lists (paginated). */
+  async getLists() {
+    const allLists = [];
+    let pageToken = null;
+
+    do {
+      const params = new URLSearchParams({ page_size: '100' });
+      if (pageToken) {
+        params.set('page_token', pageToken);
+      }
+
+      const data = await this.makeRequest(`/marketing/lists?${params}`);
+      allLists.push(...(data.result || []));
+      pageToken = data._metadata?.next;
+    } while (pageToken);
+
+    return allLists;
+  }
+
+  async getListByName(name) {
+    const lists = await this.getLists();
+    return lists.find((list) => list.name === name);
+  }
+
+  async getList(listId) {
+    try {
+      return await this.makeRequest(`/marketing/lists/${listId}`);
+    } catch (error) {
+      if (error.message.includes('404')) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  async createList(name) {
+    return this.makeRequest('/marketing/lists', {
+      method: 'POST',
+      body: JSON.stringify({ name }),
+    });
+  }
+
+  // ========== Custom fields ==========
+
+  async getCustomFields() {
+    const data = await this.makeRequest('/marketing/field_definitions');
+    return data.custom_fields || [];
+  }
+
+  /** fieldType: 'Text' | 'Number' | 'Date' */
+  async createCustomField(name, fieldType) {
+    return this.makeRequest('/marketing/field_definitions', {
+      method: 'POST',
+      body: JSON.stringify({ name, field_type: fieldType }),
+    });
+  }
+
+  async deleteCustomField(fieldId) {
+    await this.makeRequest(`/marketing/field_definitions/${fieldId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  // ========== Segments (v2 API) ==========
+
+  /** All segments (paginated). The list endpoint omits query_dsl — use getSegment for detail. */
+  async getSegments() {
+    const allSegments = [];
+    let pageToken = null;
+
+    do {
+      const params = new URLSearchParams({ page_size: '50' });
+      if (pageToken) {
+        params.set('page_token', pageToken);
+      }
+
+      const data = await this.makeRequest(`/marketing/segments/2.0?${params}`);
+      allSegments.push(...(data.results || []));
+      pageToken = data._metadata?.next;
+    } while (pageToken);
+
+    return allSegments;
+  }
+
+  async getSegment(segmentId) {
+    return this.makeRequest(`/marketing/segments/2.0/${segmentId}`);
+  }
+
+  async createSegment(name, queryDsl) {
+    return this.makeRequest('/marketing/segments/2.0', {
+      method: 'POST',
+      body: JSON.stringify({ name, query_dsl: queryDsl }),
+    });
+  }
+
+  async updateSegment(segmentId, name, queryDsl) {
+    return this.makeRequest(`/marketing/segments/2.0/${segmentId}`, {
+      method: 'PATCH',
+      body: JSON.stringify({ name, query_dsl: queryDsl }),
+    });
+  }
+
+  async deleteSegment(segmentId) {
+    await this.makeRequest(`/marketing/segments/2.0/${segmentId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  // ========== Unsubscribe groups (ASM) ==========
+
+  /** Every unsubscribe group on the ACCOUNT (ids are account-scoped, not brand-scoped). */
+  async getUnsubscribeGroups() {
+    return this.makeRequest('/asm/groups');
+  }
+
+  /** description is recipient-facing — it renders on the preferences page. */
+  async createUnsubscribeGroup(name, description) {
+    return this.makeRequest('/asm/groups', {
+      method: 'POST',
+      body: JSON.stringify({ name, description, is_default: false }),
+    });
+  }
+
+  // ========== Verified senders ==========
+
+  async getVerifiedSenders() {
+    const data = await this.makeRequest('/verified_senders');
+    return data?.results || [];
+  }
+
+  /**
+   * Create a verified sender. Auto-verifies when domain authentication is
+   * valid (the domain-auth operation runs first for exactly that reason).
+   *
+   * @param {Object} sender - { nickname, fromEmail, fromName, replyToEmail, replyToName, address }
+   *   address: { street, street2, city, state, zip, country } (CAN-SPAM requires it)
+   */
+  async createVerifiedSender({ nickname, fromEmail, fromName, replyToEmail, replyToName, address }) {
+    return this.makeRequest('/verified_senders', {
+      method: 'POST',
+      body: JSON.stringify({
+        nickname,
+        from_email: fromEmail,
+        from_name: fromName,
+        reply_to: replyToEmail,
+        reply_to_name: replyToName,
+        address: address.street,
+        address2: address.street2 || '',
+        city: address.city,
+        state: address.state,
+        zip: address.zip,
+        country: address.country,
+      }),
+    });
+  }
+
+  async deleteVerifiedSender(senderId) {
+    await this.makeRequest(`/verified_senders/${senderId}`, {
+      method: 'DELETE',
+    });
+  }
+
+  // ========== Domain authentication ==========
+
+  async getAuthenticatedDomains() {
+    return this.makeRequest('/whitelabel/domains');
+  }
+
+  /** Creates the DKIM/SPF record set (automatic_security → 3 CNAMEs). */
+  async authenticateDomain(domain, subdomain = 'emailauth') {
+    return this.makeRequest('/whitelabel/domains', {
+      method: 'POST',
+      body: JSON.stringify({
+        domain,
+        subdomain,
+        automatic_security: true,
+        custom_spf: false,
+      }),
+    });
+  }
+
+  // ========== Link branding ==========
+
+  /**
+   * Every branded LINK host on the account — the `emailurl.<domain>` CNAME
+   * SendGrid rewrites transactional links through. Each entry carries its own
+   * `valid`, which is SendGrid's word on whether it has resolved the record
+   * (`{ domain, subdomain, valid, dns: { domain_cname, owner_cname } }`).
+   */
+  async getBrandedLinks() {
+    return this.makeRequest('/whitelabel/links');
+  }
+
+  /** Creates the branded link record set (two CNAMEs under `<subdomain>.`). */
+  async createBrandedLink(domain, subdomain = 'emailurl') {
+    return this.makeRequest('/whitelabel/links', {
+      method: 'POST',
+      body: JSON.stringify({
+        domain,
+        subdomain,
+        default: false,
+      }),
+    });
+  }
+
+  /** Asks SendGrid to check the DNS records for a branded link. */
+  async validateBrandedLink(linkId) {
+    return this.makeRequest(`/whitelabel/links/${linkId}/validate`, {
+      method: 'POST',
+    });
+  }
+
+  /** Asks SendGrid to check the DNS records for a domain authentication. */
+  async validateDomain(domainId) {
+    return this.makeRequest(`/whitelabel/domains/${domainId}/validate`, {
+      method: 'POST',
+    });
+  }
+
+  // ========== Event Webhook (account-global) ==========
+
+  async getEventWebhookSettings() {
+    return this.makeRequest('/user/webhooks/event/settings');
+  }
+
+  async updateEventWebhookSettings(settings) {
+    return this.makeRequest('/user/webhooks/event/settings', {
+      method: 'PATCH',
+      body: JSON.stringify(settings),
+    });
+  }
+}
+
+module.exports = { SendGridAPI };

package/dist/services/captcha/ensure/site-key.js

@@ -0,0 +1,83 @@
+/**
+ * Validate the brand's own classic reCAPTCHA keys.
+ *
+ * omega-manager only printed a checkmark outside onboarding; this port
+ * actually proves the secret: siteverify with a throwaway token answers
+ * invalid-input-response when the secret is valid and invalid-input-secret
+ * when it isn't. The key's domain list has no read API (classic reCAPTCHA),
+ * so domain membership can't be proven — interactive runs open the console
+ * and confirm once, stamping config (a confirm nothing can re-check is the
+ * one reconcile flag config keeps, #434 — same pattern as the ga-link
+ * confirm); non-interactive runs keep the printed guidance.
+ *
+ * The probe is a pure read (no assessment is created), so dry-run behaves
+ * identically to a normal run.
+ */
+const chalk = require('chalk').default;
+const { openBrowserAndPoll } = require('../../../vendor/devkit/flows.js');
+const { writeBrandConfig } = require('../../../lib/config-write.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+const { recaptchaConsoleUrl } = require('../lib/console-url.js');
+
+const CONFIRMED_PATH = 'captcha.providers.recaptcha.domainsConfirmed';
+
+// Throwaway token for the secret-validity probe — never a real assessment
+const PROBE_TOKEN = 'omega-manager-secret-validation-probe';
+
+module.exports = async function ensureSiteKey(context) {
+  const { recaptchaApi, siteKey, domain, brandConfig, options = {} } = context;
+
+  const consoleUrl = recaptchaConsoleUrl(brandConfig, siteKey);
+
+  console.log(`      ${chalk.dim('→')} Validating reCAPTCHA secret key...`);
+  const verification = await recaptchaApi.verify(PROBE_TOKEN);
+  const errorCodes = verification['error-codes'] || [];
+
+  if (errorCodes.includes('invalid-input-secret')) {
+    console.log(`      ${chalk.red('✗')} RECAPTCHA_SECRET_KEY in the brand .env is not a valid secret key`);
+    console.log(`      ${chalk.dim('→')} Key settings: ${chalk.cyan(consoleUrl)}`);
+    throw new Error('RECAPTCHA_SECRET_KEY is invalid (siteverify answered invalid-input-secret) — fix it in the brand .env');
+  }
+
+  // The bare domain only — the brand contract dropped the www twin, so
+  // recommending it would ask for a listing nothing serves
+  const domains = [domain];
+  const output = { siteKey: { secretValid: true, domains, consoleUrl } };
+
+  console.log(`      ${chalk.green('✓')} reCAPTCHA secret key is valid`);
+
+  // The domain list has no read API — a one-time interactive confirm stamps
+  // config (#434); a changed brand domain naturally re-prompts. A pre-existing
+  // stamp that also carries the www twin still covers the bare domain, so it
+  // confirms without churn and the stamp narrows to what's recommended now
+  const confirmed = brandConfig.captcha?.providers?.recaptcha?.domainsConfirmed || [];
+  if (domains.every((entry) => confirmed.includes(entry))) {
+    // Narrow a stamp that carries extras (the retired www twin); an exact
+    // match stays disk-free
+    if (confirmed.length !== domains.length) {
+      writeBrandConfig(context, { [CONFIRMED_PATH]: domains });
+    }
+    console.log(`      ${chalk.green('✓')} Domain list confirmed (${domains.join(' + ')})`);
+    return { output };
+  }
+
+  if (canPrompt(options)) {
+    const result = await openBrowserAndPoll({
+      url: consoleUrl,
+      label: 'the reCAPTCHA console',
+      promptMessage: `Add ${chalk.cyan(domains.join(' + '))} to the reCAPTCHA key's domain list.`,
+      waitMessage: 'Waiting for the domains to be saved',
+      manualOnly: true,
+      indent: '        ',
+    });
+
+    if (result.success) {
+      writeBrandConfig(context, { [CONFIRMED_PATH]: domains });
+      console.log(`      ${chalk.green('✓')} Domain list confirmed`);
+      return { output };
+    }
+  }
+
+  console.log(`      ${chalk.dim(`→ The key's domain list has no read API — ensure ${domains.join(' + ')} is listed: ${consoleUrl}`)}`);
+  return { output };
+};