@omega.js/manager 0.1.0

package/dist/services/analytics/lib/tiktok-auth.js

@@ -0,0 +1,153 @@
+/**
+ * TikTok pixel authorization (#448, Ian 2026-08-21) — the ONE pass that puts
+ * a TikTok Events API token in a brand's hands, as an instance of the shared
+ * setup contract (#608, lib/service-input.js): ask when needed, never demand
+ * a standing key.
+ *
+ * Meta's token is minted in a dashboard and pasted, so it rides the generic
+ * paste lane. TikTok's is minted by an OAuth exchange, so its acquire is its
+ * own flow — and the app secret is a MINT-TIME credential, not a standing one:
+ *
+ *   1. the app id is public config (`analytics.providers.tiktok.appId`);
+ *   2. the app secret is pasted ONCE, masked, and never persisted anywhere;
+ *   3. the portal authorization is OFFERED (Enter-gated open, house rule: ask
+ *      permission, never auto-open) and the `auth_code` it lands is pasted back;
+ *   4. the exchange runs inline;
+ *   5. ONLY the long-lived TIKTOK_ACCESS_TOKEN reaches the brand .env — the
+ *      name @omega.js/backend reads.
+ *
+ * A re-authorization asks for the secret again (a company-level home for it is
+ * #446). Nothing here ever fails a walk: a headless run, a declined gate, an
+ * empty paste, or a rejected exchange all return false, and the caller keeps
+ * its warned where-to-get guidance.
+ */
+const chalk = require('chalk').default;
+
+const { writeEnvValue } = require('../../../lib/env-secret.js');
+const { canPrompt } = require('../../../lib/run-gates.js');
+const { confirmSetup, resolveConfigValue } = require('../../../lib/config-flow.js');
+const { exchangeAuthCode, TIKTOK_APP_URL, TIKTOK_APPS_URL, TIKTOK_AUTH_BASE, isAuthUrlFor, parseAuthCode } = require('./tiktok-api.js');
+
+/**
+ * Put a long-lived TikTok access token in the environment, walking the portal
+ * authorization when the run can ask.
+ *
+ * @param {Object} context - Handler context ({ brandRoot, brandConfig, options };
+ *   `tiktokExchange` is the test seam that replaces the live exchange).
+ * @param {Object} spec - The TikTok pixel spec (envVar, label, key).
+ * @param {Object} [options]
+ * @param {boolean} [options.gate] - false = the caller already ran the
+ *   Provide / Skip / Disable gate for this provider.
+ * @param {Object} [options.prompt] - Test seam over devkit/prompt members.
+ * @returns {Promise<boolean>} Whether the token is now in process.env.
+ */
+async function acquireTikTokToken(context, spec, options = {}) {
+  const { brandRoot, brandConfig, options: runOptions = {} } = context;
+
+  if (process.env[spec.envVar]) {
+    return true;
+  }
+
+  if (!canPrompt(runOptions)) {
+    return false;
+  }
+
+  const provider = brandConfig.analytics?.providers?.[spec.key] || {};
+
+  // Whether this flow's Provide / Skip / Disable gate has already been opened.
+  let gated = options.gate === false;
+
+  let appId = provider.appId;
+  if (!appId) {
+    // The app id is the developer app's — public config, so it is ASKED for
+    // right here (#635) rather than warned about, and the mint continues into
+    // the same pass on the id just entered.
+    console.log(`      ${chalk.dim('Create a TikTok developer app, then copy its App ID from the app\'s Basic Information')}`);
+    appId = await resolveConfigValue(context, {
+      path: `analytics.providers.${spec.key}.appId`,
+      label: 'TikTok developer app id',
+      instructions: [
+        '1. The next step opens the TikTok developer portal',
+        '2. Create (or open) the app, then paste back its App ID',
+        `3. The authorization and the exchange run here and only the long-lived token is saved (${chalk.cyan(spec.envVar)})`,
+      ],
+      entry: { url: TIKTOK_APPS_URL, message: 'Paste the TikTok developer app id:' },
+      disablePath: `analytics.providers.${spec.key}`,
+      ...(gated ? { gate: false } : {}),
+    });
+    if (!appId) {
+      // Skipped, disabled, or headless — the caller keeps its guidance
+      return false;
+    }
+    // That ask WAS this flow's gate: asking again for the same setup would
+    // put the same question twice in one pass.
+    gated = true;
+  }
+
+  if (!gated) {
+    const action = await confirmSetup(context, {
+      label: spec.label,
+      instructions: [
+        '1. The next step opens your app\'s page in the TikTok developer portal: paste its secret, then its "Advertiser authorization URL"',
+        '2. That URL opens next: approve the advertiser account, then paste back the redirect URL (it carries the auth_code)',
+        `3. The exchange runs here and only the long-lived token is saved (${chalk.cyan(spec.envVar)})`,
+      ],
+      disablePath: `analytics.providers.${spec.key}`,
+    });
+    if (action !== 'yes') {
+      return false;
+    }
+  }
+
+  const prompt = { ...require('../../../vendor/devkit/prompt.js'), ...options.prompt };
+
+  // The app page shows the "Advertiser authorization URL" TikTok built for the
+  // app (app id, state, and the redirect URI configured ON the app). The secret
+  // lives there too, so the page opens FIRST; the link is pasted back here, so
+  // it is never wrong and never stored (Ian 2026-08-27).
+  await prompt.pressEnterToOpen(
+    TIKTOK_APP_URL(appId),
+    `the ${spec.label} app page`,
+  );
+
+  // Mint-time only: masked, held in a local, never written to .env or config
+  const secret = (await prompt.password({ message: 'TikTok app secret (used once, never saved):' }) || '').trim();
+  if (!secret) {
+    return false;
+  }
+
+  const authUrl = (await prompt.input({ message: 'Paste the "Advertiser authorization URL" from the app page:' }) || '').trim();
+  if (!authUrl) {
+    return false;
+  }
+  if (!isAuthUrlFor(authUrl, appId)) {
+    console.log(`      ${chalk.yellow('⚠')} That is not the authorization URL for app ${chalk.cyan(appId)} ${chalk.dim(`(expected ${TIKTOK_AUTH_BASE}?app_id=${appId}&…)`)}`);
+    return false;
+  }
+
+  await prompt.pressEnterToOpen(authUrl, `the ${spec.label} authorization portal`);
+
+  const authCode = parseAuthCode((await prompt.input({ message: 'Paste the redirect URL (or just the auth_code):' }) || '').trim());
+  if (!authCode) {
+    return false;
+  }
+
+  const exchange = context.tiktokExchange || ((params) => exchangeAuthCode(params));
+
+  let token;
+  try {
+    token = await exchange({ appId, secret, authCode });
+  } catch (error) {
+    // A rejected exchange is a normal outcome of a stale/mistyped code — the
+    // caller's guidance stands and the manage walk continues
+    console.log(`      ${chalk.yellow('⚠')} TikTok token exchange failed${chalk.dim(`: ${error.message}`)}`);
+    return false;
+  }
+
+  writeEnvValue(brandRoot, spec.envVar, token);
+  process.env[spec.envVar] = token;
+  console.log(`      ${chalk.green('✓')} ${spec.envVar} minted and saved to the brand .env`);
+  return true;
+}
+
+module.exports = { acquireTikTokToken };

package/dist/services/assets/ensure/logo-gen.js

@@ -0,0 +1,68 @@
+/**
+ * Generate the wordmark and combomark SVGs from the brandmark + brand
+ * name + brand.font — text rendered as path outlines via opentype.js, so
+ * the output SVGs are self-contained. Generation is missing-only: an
+ * existing (possibly hand-tuned) wordmark or combomark is never
+ * overwritten.
+ *
+ * `brand.font` names a font file (without extension) resolved from the
+ * brand repo's `assets/fonts/` or the system font dirs. No font
+ * configured → nothing to generate with, noted and moved past (a brand
+ * with hand-made logo files never needs one). Configured but not found →
+ * error, the config intent failed.
+ */
+const { join } = require('node:path');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const { loadFont } = require('../lib/font-loader.js');
+const { generateWordmark, generateCombomark } = require('../lib/svg-logo-generator.js');
+
+module.exports = async function ensureLogoGen(context) {
+  const { brandConfig, brandRoot, logoDir, brandmarkPath, options } = context;
+  const dryRun = options?.dryRun || false;
+
+  const brandName = brandConfig.brand.name;
+  const fontName = brandConfig.brand.font;
+
+  const wordmarkPath = join(logoDir, 'wordmark.svg');
+  const combomarkPath = join(logoDir, 'combomark.svg');
+
+  const missing = [
+    ['wordmark', wordmarkPath],
+    ['combomark', combomarkPath],
+  ].filter(([, path]) => !jetpack.exists(path));
+
+  if (missing.length === 0) {
+    console.log(`      ${chalk.green('✓')} Logo sources ${chalk.dim('(wordmark + combomark)')} in sync`);
+    return { output: { logos: { synced: true } } };
+  }
+
+  if (!fontName) {
+    console.log(`      ${chalk.dim(`⊘ No brand.font configured — ${missing.map(([name]) => name).join(' + ')} not generated (set brand.font + a font file in assets/fonts/, or add the SVGs by hand)`)}`);
+    return { output: { logos: { skipped: 'no brand.font' } } };
+  }
+
+  if (dryRun) {
+    console.log(`      ${chalk.yellow('[DRY RUN]')} Would generate ${missing.map(([name]) => chalk.cyan(`${name}.svg`)).join(' + ')}`);
+    return { output: { logos: { planned: missing.map(([name]) => name) } } };
+  }
+
+  const font = loadFont(fontName, brandRoot);
+  if (!font) {
+    console.log(`      ${chalk.red('✗')} Font ${chalk.cyan(fontName)} not found in ${chalk.dim('assets/fonts/')} or the system font dirs`);
+    return { status: 'error', error: `font "${fontName}" not found` };
+  }
+
+  const generated = [];
+
+  for (const [name, path] of missing) {
+    const svg = name === 'wordmark'
+      ? generateWordmark(brandName, font)
+      : generateCombomark(brandName, jetpack.read(brandmarkPath), font);
+    jetpack.write(path, svg);
+    console.log(`      ${chalk.green('✓')} Generated ${chalk.cyan(`${name}.svg`)}`);
+    generated.push(name);
+  }
+
+  return { output: { logos: { generated } } };
+};

package/dist/services/assets/index.js

@@ -0,0 +1,109 @@
+/**
+ * Assets service — the brand's derived visual collateral generated from
+ * its logo sources: wordmark/combomark SVGs from the brandmark +
+ * brand.font, color/black SVG variants + PNG size ladders, PSD templates
+ * (seeded from the company root, logo/text layers refreshed, PNGs
+ * exported), macOS/Windows app icons, social profile icons, and the web
+ * favicon set.
+ *
+ * Sources are committed brand collateral at `assets/logo/*.svg` and
+ * `assets/templates/*.psd` in the brand repo (omega-manager read
+ * `.brands/{id}/assets/`); derived files land in the gitignored
+ * `.omega/assets/` (omega-manager's `.output/{id}/assets/`). Every
+ * operation is mtime-diffed — only missing or stale outputs regenerate —
+ * which replaces omega-manager's `--onboarding` gate on the write
+ * operations (it regenerated blindly, so running every time was too
+ * expensive; it also had no dry-run guard). `--reset-assets` forces a
+ * rebuild the timestamps would skip by clearing the cache first
+ * (lib/reset.js).
+ *
+ * The brandmark is the root of every derived asset. When it's missing
+ * and MrLogo credentials are present (MRLOGO_SERVICE_ACCOUNT /
+ * MRLOGO_API_KEY / LOGO_API_ID_TOKEN — the product-service ladder,
+ * lib/brandmark-api.js; zero config options by design), the AI generation
+ * flow runs; otherwise the service skips with guidance. Not ported:
+ * omega-manager's social-images/store-images
+ * write operations — dead code whose template-name lists never matched
+ * TEMPLATE_CONFIG keys (they could never generate anything); their
+ * intended outputs are the templates operation's og-image and
+ * store/chrome exports.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+const chalk = require('chalk').default;
+const { createServiceRunner } = require('../../lib/service-runner.js');
+const { input } = require('../../vendor/devkit/prompt.js');
+const { withSpinner } = require('../../vendor/devkit/flows.js');
+const { resolveLogoAuth, generateBrandmark, MRLOGO_URL } = require('./lib/brandmark-api.js');
+const { resolveResetKinds, resetAssetsCache } = require('./lib/reset.js');
+const { canPrompt } = require('../../lib/run-gates.js');
+
+module.exports.run = createServiceRunner({
+  serviceDir: __dirname,
+  setup: async (context) => {
+    const config = context.brandConfig.assets;
+
+    if (config === false || config?.enabled === false) {
+      return { skip: true, reason: 'assets.enabled = false' };
+    }
+
+    const logoDir = join(context.brandRoot, 'assets', 'logo');
+    const brandmarkPath = join(logoDir, 'brandmark.svg');
+
+    // The brandmark is the root of every derived asset — when the brand has
+    // none and MrLogo credentials resolve (the product-service ladder:
+    // operator SA → api key → pasted ID token; setting a credential IS the
+    // consent to spend the API call), generate it. Interactive runs ask for
+    // optional art direction. Dry runs never mint.
+    if (!jetpack.exists(brandmarkPath)) {
+      if (!context.options?.dryRun) {
+        try {
+          const auth = await resolveLogoAuth({
+            brandConfig: context.brandConfig,
+            brandRoot: context.brandRoot,
+            db: context.mrlogoDb,
+            authAdmin: context.mrlogoAuthAdmin,
+            log: (line) => console.log(`    ${line}`),
+          });
+
+          if (auth) {
+            const direction = canPrompt(context.options)
+              ? (await input({ message: 'Logo prompt (press Enter to skip):', default: '' })).trim()
+              : '';
+            await withSpinner('Generating brandmark via MrLogo', () =>
+              generateBrandmark({ brandConfig: context.brandConfig, brandmarkPath, direction, token: auth.token }));
+          }
+        } catch (error) {
+          console.log(`    ${chalk.yellow('⚠')} Brandmark generation failed${chalk.dim(`: ${error.message}`)}`);
+        }
+      }
+
+      if (!jetpack.exists(brandmarkPath)) {
+        return { skip: true, reason: `no assets/logo/brandmark.svg in the brand repo (add the brand's logo source, set MRLOGO_SERVICE_ACCOUNT / MRLOGO_API_KEY / LOGO_API_ID_TOKEN in the brand .env for AI generation, or make one at ${MRLOGO_URL})` };
+      }
+    }
+
+    const outDir = join(context.brandRoot, '.omega', 'assets');
+
+    // The force refresh (#214): clear the asked kinds before the operations
+    // run, so the mtime gate below sees them missing and rebuilds them. Loud
+    // by design, because this is the one thing the service destroys and an
+    // operator who typed the flag by accident has to see what went.
+    const resetKinds = resolveResetKinds(context.options?.resetAssets);
+    if (resetKinds.length > 0) {
+      const dryRun = context.options?.dryRun || false;
+      const { removed } = resetAssetsCache({ outDir, kinds: resetKinds, dryRun });
+      const what = `${chalk.bold(resetKinds.join(' + '))} ${chalk.dim(`(${removed.length} path${removed.length === 1 ? '' : 's'} under .omega/assets/)`)}`;
+
+      console.log(dryRun
+        ? `    ${chalk.yellow('[DRY RUN]')} Would reset ${what}`
+        : `    ${chalk.yellow('↺')} Reset ${what}; regenerating below`);
+    }
+
+    return {
+      logoDir,
+      brandmarkPath,
+      outDir,
+    };
+  },
+});

package/dist/services/assets/lib/assets-config.js

@@ -0,0 +1,168 @@
+/**
+ * Assets processing rules — which logo sources produce which derived files.
+ *
+ * Sources live in the brand repo at `assets/logo/*.svg` (committed brand
+ * collateral — omega-manager read `.brands/{id}/assets/`); derived files
+ * land in `.omega/assets/` (gitignored, regenerable — omega-manager's
+ * `.output/{id}/assets/`).
+ *
+ * Logo naming conventions:
+ * - brandmark: Square icon/symbol (no text)
+ * - wordmark: Text-only logo
+ * - combomark: Icon + text combined
+ */
+
+const BRANDMARK_SIZES = [16, 32, 48, 64, 128, 256, 512, 1024, 2048];
+const WIDE_LOGO_SIZES = [128, 256, 512, 1024, 2048];
+
+/**
+ * Each logo source gets two variants — the SVG as-is (colors/gradients
+ * preserved) and an all-black conversion — exported as SVG + PNGs at all
+ * sizes.
+ */
+const PROCESSING_RULES = {
+  brandmark: {
+    source: 'assets/logo/brandmark.svg',
+    outputDir: 'logo/brandmark',
+    square: true,
+    sizes: BRANDMARK_SIZES,
+  },
+  wordmark: {
+    source: 'assets/logo/wordmark.svg',
+    outputDir: 'logo/wordmark',
+    square: false,
+    sizes: WIDE_LOGO_SIZES,
+  },
+  combomark: {
+    source: 'assets/logo/combomark.svg',
+    outputDir: 'logo/combomark',
+    square: false,
+    sizes: WIDE_LOGO_SIZES,
+  },
+};
+
+/**
+ * Social profile icons — square brandmark on a white background for
+ * profile pictures (YouTube, Twitter, …).
+ */
+const SOCIAL_ICON_CONFIG = {
+  outputDir: 'social/brandmark',
+  sizes: [512, 1024, 2048],
+  padding: 0.15, // 15% padding on each side
+  background: { r: 255, g: 255, b: 255, alpha: 1 },
+};
+
+/**
+ * PSD templates — brand-editable Photoshop sources for app icons, social
+ * images, and store promos. Each `{key}.psd` lives in the brand repo at
+ * `assets/templates/` (seeded on first run from the company root's
+ * `assets/templates/` when the brand is company-managed — omega-manager
+ * baked ITW's binaries into its own `src/defaults/`); exports land in
+ * `.omega/assets/{outputDir}/`.
+ *
+ * Layer replacement types:
+ * - logo: replace the layer canvas with the brandmark SVG
+ *   - path: slash-delimited layer path (e.g. 'Main/Logo/Logo')
+ *   - size: logo size as a fraction of canvas width (0-1)
+ *   - bounds: [left, top, right, bottom] fractions to center within (optional)
+ *   - useBlackLogo: render the pure-black brandmark variant
+ * - text: replace a text layer's content with a brandConfig value
+ *   - path: slash-delimited layer path
+ *   - value: dot-notation config path (e.g. 'brand.name')
+ *   - maxWidth: max text width as a fraction of canvas width — shrinks the
+ *     font when the value overflows
+ */
+const TEMPLATE_CONFIG = {
+  // --- App: macOS ---
+  'app-macos-icon': {
+    dimensions: [1024, 1024],
+    outputDir: 'app/macos',
+    outputName: 'icon',
+    layers: [
+      { type: 'logo', path: 'Main/Logo/Logo', size: 0.575, bounds: [0.078, 0.089, 0.922, 0.933] },
+    ],
+  },
+  'app-macos-tray': {
+    dimensions: [32, 32],
+    outputDir: 'app/macos',
+    // The desktop framework consumes this as `tray.png` and renames its dist
+    // output to `trayTemplate.png` itself (the `Template` suffix is a macOS
+    // magic marker for dark-mode auto-inversion). Native @2x size; the
+    // framework downscales the @1x sibling.
+    outputName: 'tray',
+    layers: [
+      // macOS tray template images MUST be pure black (with alpha) so the
+      // system can invert them in dark mode
+      { type: 'logo', path: 'Main/Logo/Logo', size: 1.0, useBlackLogo: true },
+    ],
+  },
+  'app-macos-dmg': {
+    dimensions: [1080, 760],
+    outputDir: 'app/macos',
+    outputName: 'dmg',
+  },
+
+  // --- App: Windows ---
+  'app-windows-icon': {
+    dimensions: [1024, 1024],
+    outputDir: 'app/windows',
+    outputName: 'icon',
+    layers: [
+      { type: 'logo', path: 'Main/Logo/Logo', size: 0.7 },
+    ],
+  },
+
+  // --- Social ---
+  'social-og-image': {
+    dimensions: [1200, 630],
+    outputDir: 'social',
+    outputName: 'og-image',
+    layers: [
+      { type: 'logo', path: 'Main/Logo/Logo', size: 0.25 },
+      { type: 'text', path: 'Main/Text/Brand Name', value: 'brand.name', maxWidth: 0.8 },
+      { type: 'text', path: 'Main/Text/Brand Tagline', value: 'brand.tagline', maxWidth: 0.7 },
+    ],
+  },
+
+  // --- Store: Chrome Web Store ---
+  'store-chrome-promo-small': {
+    dimensions: [440, 280],
+    outputDir: 'store/chrome',
+    outputName: 'promo-small',
+  },
+  'store-chrome-promo-large': {
+    dimensions: [920, 680],
+    outputDir: 'store/chrome',
+    outputName: 'promo-large',
+  },
+  'store-chrome-promo-marquee': {
+    dimensions: [1400, 560],
+    outputDir: 'store/chrome',
+    outputName: 'promo-marquee',
+  },
+};
+
+/**
+ * App icon formats per platform. The composited `icon.png` from the
+ * templates operation is the source when present, else the brandmark SVG.
+ */
+const ICON_PLATFORMS = {
+  macos: { format: 'icns' },
+  windows: { format: 'ico' },
+};
+
+/**
+ * Web favicon set.
+ */
+const FAVICON_CONFIG = {
+  outputDir: 'favicon',
+  files: [
+    { name: 'favicon-16x16.png', size: 16 },
+    { name: 'favicon-32x32.png', size: 32 },
+    { name: 'apple-touch-icon.png', size: 180 },
+    { name: 'android-chrome-192x192.png', size: 192 },
+    { name: 'android-chrome-512x512.png', size: 512 },
+  ],
+};
+
+module.exports = { PROCESSING_RULES, SOCIAL_ICON_CONFIG, TEMPLATE_CONFIG, ICON_PLATFORMS, FAVICON_CONFIG };

package/dist/services/assets/lib/brandmark-api.js

@@ -0,0 +1,160 @@
+/**
+ * AI brandmark generation via MrLogo (mrlogo.ai — a sibling ITW product) —
+ * the fallback when a brand has no assets/logo/brandmark.svg yet. MrLogo is
+ * OURS, so the endpoint is a product constant (like the Ghostii client's
+ * write URL) and auth rides the same credential ladder as the other product
+ * services (forms/chat/email — Ian 2026-07-14: no config options,
+ * "use an API key or service account or whatever slapform, chatsy,
+ * replyify use"):
+ *
+ *   1. MRLOGO_SERVICE_ACCOUNT (path to MrLogo's service-account JSON,
+ *      absolute or brand-root-relative) — full auto: ensures the brand's
+ *      OWN MrLogo product user (email = brand.contact.email, canonical
+ *      account shape via lib/product-create) and calls the API with that
+ *      user's api.privateKey. New users land on MrLogo's basic plan
+ *      (100 credits), plenty for brandmark generation.
+ *   2. MRLOGO_API_KEY — an existing MrLogo account's api.privateKey used
+ *      directly. Verified against the live wire contract: BEM's
+ *      authenticate() resolves a non-JWT Bearer value by querying
+ *      users.api.privateKey, and MrLogo's logos route rides that auth.
+ *   3. LOGO_API_ID_TOKEN — a pasted Firebase ID token (manual escape
+ *      hatch; ID tokens expire hourly, so the durable tiers rank first).
+ *
+ * No credentials → the assets service skips with guidance (generate at
+ * mrlogo.ai by hand and drop the SVG in assets/logo/). The API returns a
+ * monochrome SVG (preferred) or color SVG URL; the download lands at
+ * assets/logo/brandmark.svg as committed collateral.
+ */
+const { randomUUID } = require('node:crypto');
+const chalk = require('chalk').default;
+const jetpack = require('fs-jetpack');
+const { FirestoreREST, loadServiceAccount } = require('../../../lib/firestore-rest.js');
+const { createAuthAdmin } = require('../../../lib/auth-admin.js');
+const { ensureProductUser } = require('../../../lib/product-create.js');
+const { createPasswordResolver } = require('../../account/lib/resolve-password.js');
+
+// MrLogo's LIVE production route (the old-world /backend-manager path IS its
+// api). Env override is a test/staging seam, not brand config.
+const MRLOGO_API_URL = 'https://api.mrlogo.ai/backend-manager/logos';
+const MRLOGO_URL = 'https://mrlogo.ai';
+
+function apiUrl() {
+  return process.env.MRLOGO_API_URL || MRLOGO_API_URL;
+}
+
+/**
+ * Resolve the logo API's Bearer credential down the product ladder, or null
+ * when no tier is configured. The SA tier ensures the brand's own MrLogo
+ * product user and uses ITS api.privateKey — BEM auth accepts a privateKey
+ * and an ID token through the same Authorization header.
+ *
+ * @param {object} spec
+ * @param {object} spec.brandConfig - Merged brand config
+ * @param {string} spec.brandRoot - Brand root (SA paths + password channels)
+ * @param {object} [spec.db] - FirestoreREST test seam (with authAdmin)
+ * @param {object} [spec.authAdmin] - auth-admin test seam
+ * @param {function} spec.log - line logger
+ * @returns {Promise<{ token: string, source: string }|null>}
+ */
+async function resolveLogoAuth({ brandConfig, brandRoot, db, authAdmin, log }) {
+  // Tier 1 — operator SA: mint/reuse the brand's own product user
+  if (!db) {
+    const envPath = process.env.MRLOGO_SERVICE_ACCOUNT;
+    if (envPath) {
+      const serviceAccount = loadServiceAccount(envPath, brandRoot);
+      db = new FirestoreREST(serviceAccount);
+      authAdmin = createAuthAdmin(serviceAccount);
+    }
+  }
+
+  if (db && authAdmin) {
+    const brand = brandConfig.brand || {};
+    const email = brand.contact?.email;
+    if (!email) {
+      throw new Error('MRLOGO_SERVICE_ACCOUNT is set but brand.contact.email is missing — the brand\'s product user needs it');
+    }
+
+    const { uid } = await ensureProductUser({
+      db,
+      authAdmin,
+      email,
+      resolvePassword: createPasswordResolver({
+        brandRoot,
+        domain: new URL(brand.url || 'https://invalid.test').hostname,
+        brand,
+        dryRun: false,
+      }),
+      log,
+    });
+
+    const userDoc = await db.getDoc(`users/${uid}`);
+    const privateKey = userDoc?.api?.privateKey;
+    if (!privateKey) {
+      throw new Error(`MrLogo user ${email} (${uid}) has no api.privateKey in its user doc`);
+    }
+    return { token: privateKey, source: 'MRLOGO_SERVICE_ACCOUNT' };
+  }
+
+  // Tier 2 — an existing account's api.privateKey, used directly
+  if (process.env.MRLOGO_API_KEY) {
+    return { token: process.env.MRLOGO_API_KEY, source: 'MRLOGO_API_KEY' };
+  }
+
+  // Tier 3 — pasted Firebase ID token (expires hourly)
+  if (process.env.LOGO_API_ID_TOKEN) {
+    return { token: process.env.LOGO_API_ID_TOKEN, source: 'LOGO_API_ID_TOKEN' };
+  }
+
+  return null;
+}
+
+/**
+ * Generate the brandmark via the logo API and write it to brandmarkPath.
+ *
+ * @returns {boolean} whether the SVG landed
+ */
+async function generateBrandmark({ brandConfig, brandmarkPath, direction, token }) {
+  const response = await fetch(apiUrl(), {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': `Bearer ${token}`,
+    },
+    body: JSON.stringify({
+      brandName: brandConfig.brand.name,
+      mode: 'brandmark',
+      style: 'flat',
+      mood: 'professional',
+      industry: brandConfig.brand.tagline || '',
+      description: [brandConfig.brand.description || '', direction].filter(Boolean).join('. '),
+      colors: ['#000000'],
+      id: randomUUID(),
+    }),
+    signal: AbortSignal.timeout(120000),
+  });
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`logo API responded ${response.status}: ${text}`);
+  }
+
+  const result = await response.json();
+  const files = result.iteration?.files || {};
+  const svgUrl = files.monoSvg?.url || files.colorSvg?.url;
+
+  if (!svgUrl) {
+    console.log(`    ${chalk.yellow('⚠')} No SVG in the logo API response — check the provider's logs`);
+    return false;
+  }
+
+  const svgResponse = await fetch(svgUrl, { signal: AbortSignal.timeout(30000) });
+  if (!svgResponse.ok) {
+    throw new Error(`failed to download the SVG (${svgResponse.status})`);
+  }
+
+  jetpack.write(brandmarkPath, await svgResponse.text());
+  console.log(`    ${chalk.green('✓')} Generated ${chalk.cyan('assets/logo/brandmark.svg')} via MrLogo`);
+  return true;
+}
+
+module.exports = { resolveLogoAuth, generateBrandmark, MRLOGO_URL };