@omega.js/manager 0.1.0

package/dist/services/cloud/ensure/hosting.js

@@ -0,0 +1,398 @@
+/**
+ * Ensure Firebase Hosting serves the brand's API domains.
+ *
+ * The default hosting site ({projectId}) gets api.{domain} (Cloud Functions'
+ * public endpoint via Firebase Hosting rewrites; a brand whose api domain
+ * fronts a dedicated non-Firebase backend routes /omega through the
+ * cloudflare omega-api-proxy worker instead). ONE api domain, shared by every
+ * web instance the brand runs (#588). The main domain is NOT added — the
+ * website hosts elsewhere (GitHub Pages).
+ *
+ * Per domain, one reconciliation pass:
+ *   verified  → ensure the Cloudflare CNAME has the right proxy state:
+ *               proxied when the zone's TLS coverage reaches the name.
+ *               Universal SSL (every plan) covers the apex + one label;
+ *               deeper names (api.{sub}.{zone} — subdomain projects) ask
+ *               the zone what paid coverage it ACTUALLY has (Total TLS,
+ *               Advanced certificate packs — plans differ per brand).
+ *               Uncovered names stay DNS-only and Firebase serves the
+ *               certificate instead
+ *   pending   → write Firebase's required DNS records (TXT ownership/ACME +
+ *               unproxied CNAME); interactive runs then poll until Firebase
+ *               verifies (writing any NEW records it demands mid-poll — the
+ *               ACME challenge appears once ownership passes) and finish by
+ *               setting the CNAME's final proxy state; non-interactive/dry
+ *               runs report state, warned — rerun converges
+ *   deleted   → undelete, then treat as pending
+ *   missing   → create, then treat as pending
+ *
+ * DNS writes go through Cloudflare (context.cloudflareApi). No token → the
+ * required records are printed instead and the operation warns.
+ */
+const chalk = require('chalk').default;
+const { pollWithSpinner } = require('../../../vendor/devkit/flows.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+
+module.exports = async function ensureHosting(context) {
+  const { firebaseApi: api, cloudflareApi, brandConfig, projectId, domain, apexDomain, isSubdomainProject, options = {} } = context;
+
+  if (brandConfig.cloud?.apiSubdomain === false) {
+    console.log(chalk.dim('      ⊘ API subdomain disabled in config, skipping'));
+    return {};
+  }
+
+  // Cloudflare zone for DNS writes (apex zone covers subdomain projects)
+  const zone = cloudflareApi ? await cloudflareApi.getZoneByName(apexDomain) : null;
+  if (cloudflareApi && !zone) {
+    console.log(`      ${chalk.yellow('⚠')} No Cloudflare zone found for ${chalk.cyan(apexDomain)}`);
+    return { status: 'warned', reason: 'no Cloudflare zone for the apex domain', output: { hosting: { note: 'no Cloudflare zone' } } };
+  }
+
+  // API domains to ensure. For subdomain projects (app.brand.com) the DNS
+  // record names stay relative to the apex zone (api.app, not api).
+  const subdomainPrefix = isSubdomainProject ? domain.replace(`.${apexDomain}`, '') : '';
+  const apiDomains = [{
+    fullDomain: `api.${domain}`,
+    recordName: subdomainPrefix ? `api.${subdomainPrefix}` : 'api',
+  }];
+
+  // === Hosting site ===
+  const sites = await api.listHostingSites(projectId);
+  let site = sites.find((s) => s.name?.includes(projectId));
+
+  if (site) {
+    console.log(`      ${chalk.green('✓')} Site exists: ${chalk.cyan(projectId)}`);
+  } else if (options.dryRun) {
+    return dryRunPlan(`create hosting site ${projectId}`, { output: { hosting: { planned: 'create-site' } } });
+  } else {
+    console.log('      Creating hosting site...');
+    try {
+      site = await api.createHostingSite(projectId, projectId);
+      console.log(`      ${chalk.green('✓')} Created site: ${chalk.cyan(projectId)}`);
+    } catch (error) {
+      if (!error.message?.includes('already exists')) {
+        console.log(`      ${chalk.yellow('⚠')} Could not create site${chalk.dim(`: ${error.message}`)}`);
+        return { status: 'warned', reason: 'could not create the hosting site', output: { hosting: { error: error.message } } };
+      }
+      console.log(`      ${chalk.green('✓')} Site exists: ${chalk.cyan(projectId)}`);
+    }
+  }
+
+  // === Custom domains (one pass each) ===
+  const results = [];
+  for (const apiDomain of apiDomains) {
+    results.push(await ensureApiDomain(context, zone, apiDomain));
+  }
+
+  const pending = results.filter((r) => r.status !== 'verified');
+  return {
+    status: pending.length > 0 ? 'warned' : 'success',
+    ...(pending.length > 0 ? { reason: `${pending.length} API domain(s) not verified yet` } : {}),
+    state: { hosting: { siteId: projectId, domains: results } },
+  };
+};
+
+// ─── TLS coverage (proxy eligibility) ────────────────────────────────────────
+
+/**
+ * TLS certificate-host matching: an exact host matches itself; a wildcard
+ * (`*.X`) covers exactly ONE label below X — standard certificate semantics,
+ * a wildcard never spans two levels.
+ */
+function certHostMatches(certHost, fullDomain) {
+  if (certHost === fullDomain) {
+    return true;
+  }
+  if (!certHost.startsWith('*.')) {
+    return false;
+  }
+  const base = certHost.slice(2);
+  return fullDomain.endsWith(`.${base}`)
+    && !fullDomain.slice(0, -(base.length + 1)).includes('.');
+}
+
+/**
+ * Cloudflare Universal SSL (every plan, free included) covers the apex and
+ * ONE label below it (*.zone) — never deeper.
+ */
+function universalSslCovers(fullDomain, zoneName) {
+  return fullDomain === zoneName || certHostMatches(`*.${zoneName}`, fullDomain);
+}
+
+/**
+ * Whether the zone can terminate TLS for fullDomain at the proxy. Universal
+ * SSL answers statically; deeper names (api.playground.zone) ask the zone
+ * what coverage it ACTUALLY has — plans differ per brand: Total TLS mints a
+ * certificate for every proxied hostname, and Advanced certificate packs can
+ * carry deeper wildcards. Lookup failures fall back to not-covered — a
+ * DNS-only record works on every plan, a wrongly-proxied one never does.
+ *
+ * @returns {{ covered: boolean, via: string|null }}
+ */
+async function zoneTlsCoverage(cloudflareApi, zone, fullDomain) {
+  if (universalSslCovers(fullDomain, zone.name)) {
+    return { covered: true, via: 'universal' };
+  }
+
+  try {
+    const data = await cloudflareApi.makeRequest(`/zones/${zone.id}/acm/total_tls`);
+    if (data.result?.enabled) {
+      return { covered: true, via: 'Total TLS' };
+    }
+  } catch {
+    // No ACM entitlement — the endpoint rejects on free zones
+  }
+
+  try {
+    const data = await cloudflareApi.makeRequest(`/zones/${zone.id}/ssl/certificate_packs`);
+    const packs = Array.isArray(data.result) ? data.result : [];
+    const pack = packs.find((p) => p.status === 'active'
+      && (p.hosts || []).some((host) => certHostMatches(host, fullDomain)));
+    if (pack) {
+      return { covered: true, via: `the ${pack.type} certificate pack` };
+    }
+  } catch {
+    // Coverage unknown — treat as uncovered
+  }
+
+  return { covered: false, via: null };
+}
+
+/**
+ * One reconciliation pass over a single API domain.
+ */
+async function ensureApiDomain(context, zone, apiDomain) {
+  const { firebaseApi: api, cloudflareApi, projectId, apexDomain, options = {} } = context;
+  const { fullDomain, recordName } = apiDomain;
+
+  // Can the proxy terminate TLS for this name? (No Cloudflare client → moot;
+  // the DNS helpers only print manual instructions.)
+  const tls = zone
+    ? await zoneTlsCoverage(cloudflareApi, zone, fullDomain)
+    : { covered: true, via: null };
+
+  let status = await api.checkDomainStatus(projectId, projectId, fullDomain);
+
+  // Fully verified — just make sure the CNAME has the right proxy state
+  if (status.verified) {
+    console.log(`      ${chalk.green('✓')} Domain verified: ${chalk.cyan(fullDomain)}`);
+    if (!tls.covered) {
+      console.log(`      ${chalk.dim(`No certificate covers ${fullDomain} at the proxy (Universal SSL stops at *.${zone.name}; no Total TLS or deeper cert pack on this zone) — CNAME stays DNS-only, Firebase serves the certificate`)}`);
+    } else if (tls.via && tls.via !== 'universal') {
+      console.log(`      ${chalk.dim(`${fullDomain} is deeper than *.${zone.name} but ${tls.via} covers it — proxying`)}`);
+    }
+    await ensureCname(context, zone, recordName, { proxied: tls.covered, tlsCovered: tls.covered });
+    return { domain: fullDomain, status: 'verified' };
+  }
+
+  // Soft-deleted → undelete; missing → create. Both then converge as pending.
+  if (!status.exists) {
+    if (options.dryRun) {
+      return dryRunPlan(`${status.deleted ? 'restore' : 'add'} domain ${fullDomain}`, { domain: fullDomain, status: 'planned' });
+    }
+
+    try {
+      if (status.deleted) {
+        console.log(`      Restoring deleted domain: ${chalk.cyan(fullDomain)}...`);
+        const claim = await api.undeleteCustomDomain(projectId, projectId, fullDomain);
+        console.log(`      ${chalk.green('✓')} Restored domain${claim?.pending ? chalk.dim(' (claim pending DNS verification)') : ''}`);
+      } else {
+        console.log(`      Adding domain: ${chalk.cyan(fullDomain)}...`);
+        // A claim still running is pending DNS verification, a normal state (#56)
+        const claim = await api.createCustomDomain(projectId, projectId, fullDomain);
+        console.log(`      ${chalk.green('✓')} Added domain to Firebase${claim?.pending ? chalk.dim(' (claim pending DNS verification)') : ''}`);
+      }
+    } catch (error) {
+      if (!error.message?.includes('already exists')) {
+        console.log(`      ${chalk.yellow('⚠')} Could not add domain${chalk.dim(`: ${error.message}`)}`);
+        return { domain: fullDomain, status: 'error', error: error.message };
+      }
+    }
+
+    status = await api.checkDomainStatus(projectId, projectId, fullDomain);
+  } else {
+    console.log(`      ${chalk.yellow('⏳')} Domain pending: ${chalk.cyan(fullDomain)} ${chalk.dim(`(${status.ownershipState || 'ownership pending'}, ${status.hostState || 'host pending'})`)}`);
+  }
+
+  // Write the DNS records Firebase requires (TXT ownership + ACME challenge;
+  // A/AAAA skipped — the CNAME to {projectId}.web.app replaces them)
+  await ensureFirebaseDnsRecords(context, zone, status.requiredDnsUpdates, recordName);
+  await ensureCname(context, zone, recordName, { proxied: false, tlsCovered: tls.covered });
+
+  // Interactive runs wait for Firebase to verify (DNS propagation)
+  if (canPrompt(options)) {
+    const verified = await waitForVerification(context, zone, fullDomain, recordName, status);
+    if (verified) {
+      console.log(`      ${chalk.green('✓')} Domain verified: ${chalk.cyan(fullDomain)}`);
+      await ensureCname(context, zone, recordName, { proxied: tls.covered, tlsCovered: tls.covered });
+      return { domain: fullDomain, status: 'verified' };
+    }
+  }
+
+  console.log(`      ${chalk.dim('→')} Rerun after DNS propagates — verification converges on a later pass`);
+  return { domain: fullDomain, status: 'pending' };
+}
+
+/**
+ * Poll Firebase until the domain verifies. Firebase can demand NEW DNS
+ * records mid-verification (the ACME challenge appears once ownership
+ * passes) — those are written as they show up.
+ *
+ * @returns {boolean} - Whether the domain reached verified
+ */
+async function waitForVerification(context, zone, fullDomain, recordName, initialStatus) {
+  const { firebaseApi: api, projectId } = context;
+  let lastStates = '';
+  let lastDnsUpdateCount = (initialStatus.requiredDnsUpdates || []).length;
+
+  const result = await pollWithSpinner({
+    check: async () => {
+      const status = await api.checkDomainStatus(projectId, projectId, fullDomain);
+
+      if (status.verified) {
+        return { done: true };
+      }
+
+      const dnsUpdates = status.requiredDnsUpdates || [];
+      if (dnsUpdates.length > 0 && dnsUpdates.length !== lastDnsUpdateCount) {
+        console.log(`        ${chalk.dim('→')} Firebase requires new DNS records — writing...`);
+        await ensureFirebaseDnsRecords(context, zone, dnsUpdates, recordName);
+        lastDnsUpdateCount = dnsUpdates.length;
+      }
+
+      const states = `${status.ownershipState || 'ownership pending'}, ${status.hostState || 'host pending'}${status.certState ? `, ${status.certState}` : ''}`;
+      if (states !== lastStates) {
+        console.log(`        ${chalk.dim(`→ ${states}`)}`);
+        lastStates = states;
+      }
+
+      return { done: false };
+    },
+    intervalMs: 5000,
+    message: 'Waiting for DNS propagation',
+    indent: '        ',
+  });
+
+  return result.success;
+}
+
+// ─── Cloudflare DNS helpers (via the zone-scoped REST endpoints) ─────────────
+
+async function findDnsRecord(cloudflareApi, zoneId, name, type) {
+  const data = await cloudflareApi.makeRequest(`/zones/${zoneId}/dns_records?type=${type}&name=${encodeURIComponent(name)}`);
+  return data.result?.[0] || null;
+}
+
+/**
+ * Write Firebase's requiredDnsUpdates into the zone (skipping A/AAAA).
+ * Without a Cloudflare client the records are printed for manual setup.
+ */
+async function ensureFirebaseDnsRecords(context, zone, requiredDnsUpdates, recordName) {
+  const { cloudflareApi, apexDomain, options = {} } = context;
+  const updates = Array.isArray(requiredDnsUpdates) ? requiredDnsUpdates : [];
+
+  for (const update of updates) {
+    const { domainName } = update;
+    const records = update.desired?.records || [];
+
+    for (const record of records) {
+      const { type, rdata } = record;
+
+      if (type === 'A' || type === 'AAAA') {
+        continue;
+      }
+
+      if (!cloudflareApi) {
+        console.log(`        ${chalk.yellow('→')} Set manually: ${chalk.cyan(type)} ${chalk.cyan(domainName)} → ${rdata}`);
+        continue;
+      }
+
+      if (options.dryRun) {
+        console.log(`        ${chalk.dim(`⊘ Dry run — would ensure ${type} ${domainName}`)}`);
+        continue;
+      }
+
+      const comment = type === 'TXT' && domainName.includes('_acme-challenge')
+        ? 'Firebase SSL certificate verification'
+        : 'Firebase Hosting';
+
+      try {
+        const existing = await findDnsRecord(cloudflareApi, zone.id, domainName, type);
+
+        if (existing) {
+          if (existing.content !== rdata) {
+            await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records/${existing.id}`, {
+              method: 'PATCH',
+              body: JSON.stringify({ content: rdata, comment, ttl: 60 }),
+            });
+            console.log(`        ${chalk.green('✓')} Updated ${chalk.cyan(type)}: ${chalk.cyan(domainName)}`);
+          }
+        } else {
+          const name = domainName === apexDomain ? apexDomain : domainName.replace(`.${apexDomain}`, '');
+          await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records`, {
+            method: 'POST',
+            body: JSON.stringify({ type, name, content: rdata, comment, ttl: 60 }),
+          });
+          console.log(`        ${chalk.green('✓')} Created ${chalk.cyan(type)}: ${chalk.cyan(domainName)}`);
+        }
+      } catch (error) {
+        console.log(`        ${chalk.yellow('⚠')} ${chalk.cyan(type)} record error for ${chalk.cyan(domainName)}${chalk.dim(`: ${error.message}`)}`);
+      }
+    }
+  }
+}
+
+/**
+ * Ensure the CNAME to {projectId}.web.app exists with the desired proxy state
+ * (unproxied while verification is pending, proxied once verified).
+ */
+async function ensureCname(context, zone, recordName, { proxied, tlsCovered = true }) {
+  const { cloudflareApi, projectId, apexDomain, options = {} } = context;
+  const cnameTarget = `${projectId}.web.app`;
+  const fullRecordName = `${recordName}.${apexDomain}`;
+
+  if (!cloudflareApi) {
+    console.log(`        ${chalk.yellow('→')} Set manually: ${chalk.cyan('CNAME')} ${chalk.cyan(fullRecordName)} → ${cnameTarget}`);
+    return;
+  }
+
+  try {
+    const existing = await findDnsRecord(cloudflareApi, zone.id, fullRecordName, 'CNAME');
+
+    // Never un-proxy a working record (verify-cycle flapping) — EXCEPT when
+    // the zone's TLS coverage can't reach the name, where proxied can never
+    // complete a handshake and the record must come back down to DNS-only.
+    const needsUpdate = existing
+      && (existing.content !== cnameTarget
+        || (proxied === true && existing.proxied === false)
+        || (proxied === false && existing.proxied === true && !tlsCovered));
+
+    if (existing && !needsUpdate) {
+      return;
+    }
+
+    if (options.dryRun) {
+      console.log(`        ${chalk.dim(`⊘ Dry run — would ${existing ? 'update' : 'create'} CNAME ${fullRecordName} → ${cnameTarget}`)}`);
+      return;
+    }
+
+    if (existing) {
+      await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records/${existing.id}`, {
+        method: 'PATCH',
+        body: JSON.stringify({ content: cnameTarget, comment: 'Firebase Hosting', ttl: 60, proxied }),
+      });
+      console.log(`        ${chalk.green('✓')} Updated CNAME: ${chalk.cyan(recordName)} → ${chalk.cyan(cnameTarget)} ${chalk.dim(`(proxied: ${proxied})`)}`);
+    } else {
+      await cloudflareApi.makeRequest(`/zones/${zone.id}/dns_records`, {
+        method: 'POST',
+        body: JSON.stringify({ type: 'CNAME', name: recordName, content: cnameTarget, comment: 'Firebase Hosting', ttl: 60, proxied }),
+      });
+      console.log(`        ${chalk.green('✓')} Created CNAME: ${chalk.cyan(recordName)} → ${chalk.cyan(cnameTarget)} ${chalk.dim(`(proxied: ${proxied})`)}`);
+    }
+  } catch (error) {
+    console.log(`        ${chalk.yellow('⚠')} CNAME error for ${chalk.cyan(recordName)}${chalk.dim(`: ${error.message}`)}`);
+  }
+}
+
+module.exports.universalSslCovers = universalSslCovers;
+module.exports.certHostMatches = certHostMatches;

package/dist/services/cloud/ensure/oauth-consent.js

@@ -0,0 +1,248 @@
+/**
+ * Ensure the OAuth consent screen (IAP brand) exists: application title +
+ * support email (required for Google sign-in).
+ *
+ * No OAuth clients here — IAP-created clients are locked (no redirect URIs);
+ * Firebase auto-creates the client when Google sign-in is enabled.
+ *
+ * Google only accepts a supportEmail the AUTHORIZING USER owns (their own
+ * email or a Google Group they manage) — anything else is "Request contains
+ * an invalid argument" (friction #29; the old support@{domain} default could
+ * never work). `cloud.supportEmail` in config wins (the Google-Group
+ * case); the default is the authenticated user's own email via the
+ * userinfo.email scope. Neither available → warn with guidance, never send
+ * a doomed value.
+ *
+ * The screen's AUDIENCE is a manage-time STOPPER (#667): Internal means only
+ * the owning org's Workspace users may sign in, which is `Error 403:
+ * org_internal` for every Gmail account, and Google gives NO API write for
+ * it (proven live: PATCH is a 404, the create's orgInternalOnly is
+ * output-only, and an API-made brand is born Internal). So an interactive
+ * run STOPS on it — open the console page and poll until it flips — instead
+ * of attempting a write that cannot exist.
+ *
+ * The screen's BRANDING page (logo, home/privacy/terms links, authorized
+ * domains) has no API either, and nothing here can reconcile it — so the run
+ * NAMES it as a manual step with the one line that matters (#696).
+ */
+const chalk = require('chalk').default;
+const { openBrowserAndPoll } = require('../../../vendor/devkit/flows.js');
+const { canPrompt, dryRunPlan } = require('../../../lib/run-gates.js');
+const { confirmSetup, readTriState } = require('../../../lib/config-flow.js');
+
+// Where the gate's disable outcome lands the tri-state `false` (#608/#33).
+// The AUDIENCE opts out on its own — a brand that accepts an org-only sign-in
+// still wants every other cloud operation, so this is never cloud.enabled.
+const AUDIENCE_PATH = 'cloud.consentAudience';
+
+// The step-aside reason the run summary's warned breakdown reads (#643)
+const INTERNAL_REASON = 'consent audience is Internal — Google sign-in fails outside the org';
+
+// The console flip is a handful of clicks — poll faster than the 10s default
+const AUDIENCE_POLL_MS = 5000;
+
+/** The console page that owns the audience switch (the only path there is). */
+function audienceUrl(projectId) {
+  return `https://console.cloud.google.com/auth/audience?project=${projectId}`;
+}
+
+/**
+ * Name the consent screen's BRANDING page as a manual step (#696).
+ *
+ * The logo, the home/privacy/terms links and the authorized domains have no
+ * API at all — so the walk cannot reconcile them, and by the automation ruling
+ * (#693) what cannot be automated gets NAMED instead of going unmentioned.
+ * The one-line checklist is the part that decides whether it is safe to touch
+ * the page mid-launch: a logo upload is the only entry that costs anything.
+ *
+ * @param {string} projectId - The GCP project the consent screen belongs to.
+ */
+function logBrandingManualStep(projectId) {
+  console.log(`      ${chalk.dim('→')} Branding is manual (no API): ${chalk.cyan(`https://console.cloud.google.com/auth/branding?project=${projectId}`)}`);
+  console.log(`      ${chalk.dim('→')} ${chalk.dim("Links + authorized domains are safe anytime; a LOGO upload starts Google's verification review for External apps")}`);
+}
+
+/**
+ * Read the audience off the brand; Internal is a stopper, not a write.
+ *
+ * Interactive: the uniform three-outcome gate — Yes opens the console
+ * audience page and polls the brand read until `orgInternalOnly` flips,
+ * Skip (and `s` at the poll) warns and asks again next run, Disable lands
+ * `cloud.consentAudience: false` and nothing ever asks again.
+ * Non-interactive: the warn + the console URL, as before.
+ *
+ * @param {object} context - The handler context (firebaseApi, brandConfig,
+ *   brandRoot, projectId, options).
+ * @param {object} brand - The IAP brand resource just read or created.
+ * @returns {Promise<{audience: string, status?: string, reason?: string}>} The resulting audience.
+ */
+async function ensureExternalAudience(context, brand) {
+  const { firebaseApi: api, brandConfig, projectId, options = {} } = context;
+
+  if (brand.orgInternalOnly !== true) {
+    console.log(`      ${chalk.green('✓')} Consent audience: ${chalk.cyan('External')}`);
+    return { audience: 'External' };
+  }
+
+  // Recorded opt-out (#33): the brand said Internal is fine — never ask,
+  // never warn again, just say why nothing happened
+  if (readTriState(brandConfig, AUDIENCE_PATH).optedOut) {
+    console.log(`      ${chalk.dim(`⊘ Consent audience: Internal — ${AUDIENCE_PATH}: false (delete the line in omega.json5 to be asked again)`)}`);
+    return { audience: 'Internal' };
+  }
+
+  if (options.dryRun) {
+    dryRunPlan('stop for the Internal → External consent-audience flip in the console');
+    return { audience: 'Internal' };
+  }
+
+  const url = audienceUrl(projectId);
+
+  if (canPrompt(options)) {
+    const action = await confirmSetup(context, {
+      label: 'Consent audience (External)',
+      instructions: [
+        `${chalk.cyan(projectId)}'s consent screen is Internal — every Gmail account gets Error 403: org_internal`,
+        'Google has no API for the flip: the console switch is the only path there is',
+      ],
+      disablePath: AUDIENCE_PATH,
+    });
+
+    // Disable landed `false` (and said so) — this run is done with the audience
+    if (action === 'disable') {
+      return { audience: 'Internal' };
+    }
+
+    if (action === 'yes') {
+      const result = await openBrowserAndPoll({
+        url,
+        label: 'the consent audience page',
+        promptMessage: `Switch ${chalk.cyan(projectId)}'s audience to External (Audience → Publish app).`,
+        waitMessage: 'Waiting for the consent audience to flip to External',
+        check: async () => {
+          const [fresh] = await api.listBrands(projectId);
+          return fresh && fresh.orgInternalOnly !== true ? { done: true, result: fresh } : { done: false };
+        },
+        intervalMs: AUDIENCE_POLL_MS,
+      });
+
+      if (result.success) {
+        console.log(`      ${chalk.green('✓')} Consent audience: ${chalk.cyan('External')}`);
+        return { audience: 'External' };
+      }
+    }
+  }
+
+  console.log(`      ${chalk.yellow('⚠')} ${chalk.cyan(projectId)}'s consent audience is Internal — Google sign-in fails outside the org`);
+  console.log(`      ${chalk.dim('→')} Switch it to External: ${chalk.cyan(url)}`);
+  return { audience: 'Internal', status: 'warned', reason: INTERNAL_REASON };
+}
+
+/**
+ * Reconcile an existing brand's audience and report the screen as it stands.
+ * The handler return for every path that READ the brand off the account.
+ *
+ * @param {object} context - The handler context.
+ * @param {object} brand - The existing IAP brand resource.
+ * @returns {Promise<object>} The handler return ({ status?, state }).
+ */
+async function reportExistingBrand(context, brand) {
+  const audience = await ensureExternalAudience(context, brand);
+
+  logBrandingManualStep(context.projectId);
+
+  return {
+    ...(audience.status ? { status: audience.status, reason: audience.reason } : {}),
+    state: {
+      oauthConsent: {
+        brandName: brand.name,
+        applicationTitle: brand.applicationTitle,
+        supportEmail: brand.supportEmail,
+        audience: audience.audience,
+      },
+    },
+  };
+}
+
+module.exports = async function ensureOAuthConsent(context) {
+  const { firebaseApi: api, brandConfig, projectId, options = {} } = context;
+  const brandName = brandConfig.brand?.name;
+
+  // === READ ===
+  const existingBrands = await api.listBrands(projectId);
+
+  if (existingBrands.length > 0) {
+    console.log(`      ${chalk.green('✓')} OAuth consent screen exists`);
+
+    return reportExistingBrand(context, existingBrands[0]);
+  }
+
+  // === WRITE ===
+  if (options.dryRun) {
+    const planned = brandConfig.cloud?.supportEmail || "(authorizing user's email)";
+    return dryRunPlan(`create OAuth consent screen (${brandName}, ${planned})`, { output: { oauthConsent: { planned: 'create' } } });
+  }
+
+  const supportEmail = brandConfig.cloud?.supportEmail
+    || await api.getAuthenticatedEmail();
+
+  if (!supportEmail) {
+    console.log(`      ${chalk.yellow('⚠')} No usable support email — Google only accepts one the authorizing user OWNS`);
+    console.log(`      ${chalk.dim('→')} Re-auth to grant the email scope (delete .omega/auth/google-tokens.json and rerun), or set cloud.supportEmail to a Google Group you own`);
+    return { status: 'warned', reason: 'no ownable support email — re-auth for the email scope or set cloud.supportEmail', output: { oauthConsent: { note: 'no ownable supportEmail available' } } };
+  }
+
+  console.log('      Creating OAuth consent screen...');
+  try {
+    const brand = await api.createBrand(projectId, brandName, supportEmail);
+    console.log(`      ${chalk.green('✓')} Created OAuth consent screen`);
+    console.log(`        ${chalk.dim('→')} Application: ${chalk.cyan(brandName)}`);
+    console.log(`        ${chalk.dim('→')} Support email: ${chalk.cyan(supportEmail)}`);
+
+    // An API-made brand is born INTERNAL, always (#667, proven live): the
+    // audience is READ off the new brand and taken through the same stopper
+    // as any other, never assumed
+    const audience = await ensureExternalAudience(context, brand);
+
+    logBrandingManualStep(projectId);
+
+    return {
+      ...(audience.status ? { status: audience.status, reason: audience.reason } : {}),
+      state: {
+        oauthConsent: {
+          brandName: brand.name,
+          applicationTitle: brandName,
+          supportEmail,
+          audience: audience.audience,
+        },
+      },
+    };
+  } catch (error) {
+    if (error.message?.includes('already exists')) {
+      console.log(`      ${chalk.green('✓')} OAuth consent screen already exists`);
+
+      // The list above missed it (IAP's list lags a create by another run, or
+      // a concurrent one won): read it back so this run still reconciles the
+      // audience and reports the screen, instead of saying nothing about it
+      const [existing] = await api.listBrands(projectId);
+      if (!existing) {
+        return {};
+      }
+
+      return reportExistingBrand(context, existing);
+    }
+
+    // Brand creation is ORG-ONLY (#667, proven live): an org-less project
+    // answers 400 "Project must belong to an organization". A known cause
+    // gets named, never the generic could-not-create line
+    if (error.message?.includes('must belong to an organization')) {
+      console.log(`      ${chalk.yellow('⚠')} ${chalk.cyan(projectId)} belongs to no organization — Google only creates a consent screen in an org-owned project`);
+      console.log(`      ${chalk.dim('→')} Create it by hand: ${chalk.cyan(`https://console.cloud.google.com/apis/credentials/consent?project=${projectId}`)}`);
+      return { status: 'warned', reason: 'the project belongs to no organization — create the consent screen in the console', output: { oauthConsent: { note: 'org-less project — brand creation is org-only' } } };
+    }
+
+    console.log(`      ${chalk.yellow('⚠')} Could not create OAuth consent screen${chalk.dim(`: ${error.message}`)}`);
+    console.log(`      ${chalk.dim('→')} Configure manually: ${chalk.cyan(`https://console.cloud.google.com/apis/credentials/consent?project=${projectId}`)}`);
+    return { status: 'warned', reason: 'could not create the OAuth consent screen', output: { oauthConsent: { error: error.message } } };
+  }
+};