@omega.js/manager 0.1.0

package/dist/lib/google-auth.js

@@ -0,0 +1,495 @@
+/**
+ * Google OAuth2 client — omega-manager's shared Google auth handler, ported.
+ * Handles token storage, refresh, and the one-time browser authorization flow
+ * (localhost callback server; interactive runs gate the browser open behind
+ * Enter — the house rule — with the printed URL as the always-there fallback).
+ *
+ * ONE Google identity for the whole manager (legacy parity): every service
+ * authorizes GOOGLE_SCOPES — the union of everything the manager touches —
+ * against ONE token store, so the operator consents ONCE. The store records
+ * which scopes it was granted; a cached token missing any requested scope
+ * re-consents once instead of 403ing forever (adding a service = one re-ask).
+ *
+ * Credentials come from GOOGLE_CLIENT_ID + GOOGLE_CLIENT_SECRET in the brand
+ * .env; tokens cache to the brand's gitignored .omega/auth/ directory.
+ */
+const { createServer } = require('node:http');
+const { emitKeypressEvents } = require('node:readline');
+const { dirname, join } = require('node:path');
+const fs = require('node:fs');
+const chalk = require('chalk').default;
+
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+const GOOGLE_AUTH_URL = 'https://accounts.google.com/o/oauth2/v2/auth';
+
+// The manager's full Google surface. Firebase Management + Cloud Platform
+// (IAM, Billing, Service Usage), userinfo.email (consent-screen supportEmail
+// defaults to the AUTHORIZING user — #29), Search Console + site
+// verification, GA4 admin, AdSense (read-only).
+const GOOGLE_SCOPES = [
+  'https://www.googleapis.com/auth/firebase',
+  'https://www.googleapis.com/auth/cloud-platform',
+  'https://www.googleapis.com/auth/cloud-billing',
+  'https://www.googleapis.com/auth/userinfo.email',
+  'https://www.googleapis.com/auth/webmasters',
+  'https://www.googleapis.com/auth/siteverification',
+  'https://www.googleapis.com/auth/analytics.edit',
+  'https://www.googleapis.com/auth/adsense.readonly',
+];
+
+// A headless consent gate is a PENDING HUMAN STEP, not a failure (#228): the
+// throw carries this code so the walk classes it by code — never by sniffing
+// the message — and steps the operation aside into the run summary's ⚑ list
+// instead of failing a service (and, downstream, a whole `omega dev` boot).
+const CONSENT_REQUIRED = 'OMEGA_CONSENT_REQUIRED';
+
+// How long a printed consent url stays clickable (the loopback listener's life)
+const AUTH_WINDOW_MS = 300000;
+
+// How often the open flow reprints its url (see startAuthUrlReprint)
+const AUTH_REPRINT_MS = 60000;
+
+// This run's consent sessions, keyed by (client id, token store, scopes).
+// Every service shares the token store, so a run that starts with an empty
+// one would otherwise open a NEW browser flow per service, each minting a
+// fresh loopback url and killing the previous listener (#56: three urls in
+// six minutes, and the human was still reading the first). Concurrent and
+// later callers join the session already open, or the one that already
+// failed; a session that SUCCEEDS drops out (its tokens are in the shared
+// store from then on, so nothing reaches here until a token goes bad, and
+// that case deserves a real re-consent).
+const authSessions = new Map();
+
+/** The ONE brand-local token store every Google service shares. */
+function googleTokenStorePath(brandRoot) {
+  return join(brandRoot, '.omega', 'auth', 'google-tokens.json');
+}
+
+/**
+ * Keep the LIVE consent url in view: reprint it on a stable line every
+ * intervalMs until the flow settles (#56). A run's other output scrolls the
+ * url away, and a human reading the log clicks the first link they see, which
+ * by then belongs to a dead listener.
+ *
+ * @param {string} url - The url the open flow is waiting on
+ * @param {Object} [options] - intervalMs, expiresAt (ms epoch), log (sink)
+ * @returns {Function} stop - Clears the timer; call on settle.
+ */
+function startAuthUrlReprint(url, options = {}) {
+  const intervalMs = options.intervalMs || AUTH_REPRINT_MS;
+  const log = options.log || console.log;
+  const { expiresAt } = options;
+
+  const timer = setInterval(() => {
+    const minutesLeft = expiresAt ? Math.max(0, Math.ceil((expiresAt - Date.now()) / 60000)) : null;
+    log('');
+    log(`  ${chalk.dim('→')} Still waiting for Google consent${minutesLeft === null ? '' : ` (~${minutesLeft} min left)`}. This is the live url; any earlier one is dead:`);
+    log(`  ${chalk.cyan(url)}`);
+  }, intervalMs);
+  // Never hold the event loop open on the reprint alone (the loopback server
+  // is what keeps a waiting run alive)
+  timer.unref();
+
+  return () => clearInterval(timer);
+}
+
+class GoogleOAuth2Client {
+  constructor(options = {}) {
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.scopes = options.scopes || [];
+    this.tokenStorePath = options.tokenStorePath || null;
+
+    this.accessToken = null;
+    this.refreshToken = null;
+    this.tokenExpiry = null;
+  }
+
+  loadStoredTokens() {
+    if (!this.tokenStorePath || !fs.existsSync(this.tokenStorePath)) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(fs.readFileSync(this.tokenStorePath, 'utf8'));
+    } catch {
+      return null;
+    }
+  }
+
+  saveTokens(tokens) {
+    if (!this.tokenStorePath) {
+      return;
+    }
+
+    // Owner-only dir + file — the store holds a cloud-platform-scoped refresh token
+    fs.mkdirSync(dirname(this.tokenStorePath), { recursive: true, mode: 0o700 });
+    // Record the granted scopes — getAccessToken() uses them to decide
+    // whether a cached token can serve a client or needs one re-consent.
+    // MERGE over the existing store: refresh-path saves carry only the token
+    // triple and must not drop sidecar fields (account_email).
+    const existing = this.loadStoredTokens() || {};
+    fs.writeFileSync(this.tokenStorePath, JSON.stringify({ ...existing, ...tokens, scopes: this.scopes }, null, 2), { mode: 0o600 });
+    // mode on mkdir/writeFileSync only applies at creation — tighten pre-existing paths too
+    fs.chmodSync(dirname(this.tokenStorePath), 0o700);
+    fs.chmodSync(this.tokenStorePath, 0o600);
+  }
+
+  /**
+   * Best-effort: which Google account these tokens act as. Cached in the
+   * token store (account_email) after the first userinfo lookup — the
+   * userinfo.email scope is part of GOOGLE_SCOPES. Returns null when
+   * unknowable; diagnostics must never throw over the error they decorate.
+   */
+  async getAccountEmail() {
+    const stored = this.loadStoredTokens();
+    if (stored?.account_email) {
+      return stored.account_email;
+    }
+    try {
+      const token = this.accessToken || await this.getAccessToken();
+      const response = await fetch('https://www.googleapis.com/oauth2/v2/userinfo', {
+        headers: { Authorization: `Bearer ${token}` },
+      });
+      const data = await response.json();
+      if (data.email) {
+        this.saveTokens({ account_email: data.email });
+      }
+      return data.email || null;
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Get a valid access token (from cache, refresh, or new auth)
+   */
+  async getAccessToken() {
+    const storedTokens = this.loadStoredTokens();
+
+    // A cached token only counts when it was granted every scope this client
+    // needs — otherwise API calls 403 with no re-consent trigger. Stores from
+    // before scope tracking (no `scopes` array) are treated as insufficient:
+    // one union re-consent upgrades them.
+    const grantedScopes = Array.isArray(storedTokens?.scopes) ? storedTokens.scopes : [];
+    const scopesSufficient = this.scopes.every((scope) => grantedScopes.includes(scope));
+
+    if (storedTokens && scopesSufficient) {
+      this.accessToken = storedTokens.access_token;
+      this.refreshToken = storedTokens.refresh_token;
+      this.tokenExpiry = storedTokens.expiry;
+    } else if (storedTokens) {
+      console.log(`  ${chalk.dim('→')} Cached Google token is missing newly required scopes — one re-consent upgrades it`);
+    }
+
+    // Return cached token if still valid (with 5 min buffer)
+    if (this.accessToken && this.tokenExpiry && Date.now() < this.tokenExpiry - 300000) {
+      return this.accessToken;
+    }
+
+    if (this.refreshToken) {
+      try {
+        return await this.refreshAccessToken();
+      } catch {
+        console.log(`  ${chalk.yellow('⚠')} ${chalk.yellow('Token refresh failed, need to re-authenticate')}`);
+      }
+    }
+
+    return await this.authorizeOnce();
+  }
+
+  /**
+   * Join this run's consent session for these credentials, or open it (#56).
+   * One session per run: see the authSessions comment above.
+   */
+  authorizeOnce() {
+    const key = [this.clientId, this.tokenStorePath, this.scopes.join(' ')].join('|');
+    const open = authSessions.get(key);
+
+    if (open) {
+      return open;
+    }
+
+    const session = this.performOAuth2Flow();
+    authSessions.set(key, session);
+    // Release the slot on success only; the caller's own await owns the
+    // rejection, so the catch here just keeps this branch from surfacing one.
+    session.then(() => authSessions.delete(key)).catch(() => {});
+
+    return session;
+  }
+
+  async refreshAccessToken() {
+    const response = await fetch(GOOGLE_TOKEN_URL, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+      },
+      body: new URLSearchParams({
+        client_id: this.clientId,
+        client_secret: this.clientSecret,
+        refresh_token: this.refreshToken,
+        grant_type: 'refresh_token',
+      }),
+    });
+
+    const data = await response.json();
+
+    if (data.error) {
+      throw new Error(`Token refresh failed: ${data.error_description || data.error}`);
+    }
+
+    this.accessToken = data.access_token;
+    this.tokenExpiry = Date.now() + (data.expires_in * 1000);
+
+    this.saveTokens({
+      access_token: this.accessToken,
+      refresh_token: this.refreshToken,
+      expiry: this.tokenExpiry,
+    });
+
+    return this.accessToken;
+  }
+
+  /**
+   * Perform the full OAuth2 authorization flow: print the auth URL, receive
+   * the callback on a temporary localhost server, exchange the code.
+   */
+  async performOAuth2Flow() {
+    // Headless runs (pipeline, cron, background shells) must never open a
+    // consent flow or camp on the 5-minute callback wait — fail fast with
+    // the seeding instruction instead. stdout-TTY still counts as "a human
+    // is watching" (#25), but OMEGA_NON_INTERACTIVE=1 beats everything.
+    const { isInteractive } = require('../vendor/devkit/prompt.js');
+    if (process.env.OMEGA_NON_INTERACTIVE === '1' || (!isInteractive() && !process.stdout.isTTY)) {
+      const error = new Error(`Google consent required (scopes: ${this.scopes.join(', ')}) — run the service once interactively to grant it; headless runs work from the cached token after that`);
+      error.code = CONSENT_REQUIRED;
+      throw error;
+    }
+
+    // The Enter-gate keypress listener must tear down however the flow
+    // settles (Enter pressed, URL clicked directly, timeout, error) — a
+    // pending listener holds stdin and zombies the process at exit. The
+    // url reprint tears down on the same settle.
+    let disarm = null;
+    let stopReprint = null;
+
+    const flow = new Promise((resolve, reject) => {
+      // RFC 8252 §7.3 loopback: bind an EPHEMERAL port (listen(0)) and read
+      // the real one at listen time — Google's desktop-app client type
+      // accepts any localhost port, so nothing pins 9876 (which anything
+      // else could be holding; N7 removes fixed dev ports). `redirectUri`
+      // is assigned in the listen callback, before the server is reachable,
+      // so the request handler never sees it null.
+      let redirectUri = null;
+
+      const server = createServer(async (req, res) => {
+        const reqUrl = new URL(req.url, 'http://localhost');
+
+        if (reqUrl.pathname !== '/callback') {
+          res.writeHead(404);
+          res.end('Not found');
+          return;
+        }
+
+        const code = reqUrl.searchParams.get('code');
+        const error = reqUrl.searchParams.get('error');
+
+        if (error) {
+          res.writeHead(400);
+          res.end(`Authorization failed: ${error}`);
+          server.close();
+          reject(new Error(`Authorization failed: ${error}`));
+          return;
+        }
+
+        if (!code) {
+          res.writeHead(400);
+          res.end('No authorization code received');
+          server.close();
+          reject(new Error('No authorization code received'));
+          return;
+        }
+
+        try {
+          const tokenResponse = await fetch(GOOGLE_TOKEN_URL, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/x-www-form-urlencoded',
+            },
+            body: new URLSearchParams({
+              client_id: this.clientId,
+              client_secret: this.clientSecret,
+              code,
+              grant_type: 'authorization_code',
+              redirect_uri: redirectUri,
+            }),
+          });
+
+          const tokenData = await tokenResponse.json();
+
+          if (tokenData.error) {
+            throw new Error(`Token exchange failed: ${tokenData.error_description || tokenData.error}`);
+          }
+
+          this.accessToken = tokenData.access_token;
+          this.refreshToken = tokenData.refresh_token;
+          this.tokenExpiry = Date.now() + (tokenData.expires_in * 1000);
+
+          this.saveTokens({
+            access_token: this.accessToken,
+            refresh_token: this.refreshToken,
+            expiry: this.tokenExpiry,
+            // A full re-consent may be a DIFFERENT Google account — the
+            // cached identity is unknown until the next userinfo lookup
+            account_email: null,
+          });
+
+          res.writeHead(200, { 'Content-Type': 'text/html' });
+          res.end('<html><body><h1>Authentication successful!</h1><p>You can close this window.</p></body></html>');
+          server.close();
+          resolve(this.accessToken);
+        } catch (err) {
+          res.writeHead(500);
+          res.end(`Error: ${err.message}`);
+          server.close();
+          reject(err);
+        }
+      });
+
+      server.listen(0, () => {
+        const port = server.address().port;
+        redirectUri = `http://localhost:${port}/callback`;
+
+        const authUrl = new URL(GOOGLE_AUTH_URL);
+        authUrl.searchParams.set('client_id', this.clientId);
+        authUrl.searchParams.set('redirect_uri', redirectUri);
+        authUrl.searchParams.set('response_type', 'code');
+        authUrl.searchParams.set('scope', this.scopes.join(' '));
+        authUrl.searchParams.set('access_type', 'offline');
+        authUrl.searchParams.set('prompt', 'consent');
+
+        console.log('');
+        console.log(`  ${chalk.dim('→')} Google authentication required:`);
+        console.log(`  ${chalk.cyan(authUrl.toString())}`);
+
+        const { isInteractive: interactiveNow, openInBrowser } = require('../vendor/devkit/prompt.js');
+        if (interactiveNow()) {
+          // House rule (cp101d): browser opens are gated behind Enter. Raw
+          // keypress instead of a prompt — the consent can also complete via
+          // a clicked URL, and the listener tears down on settle.
+          disarm = this._armEnterToOpen(authUrl.toString());
+        } else if (process.stdout.isTTY && openInBrowser(authUrl.toString())) {
+          // stdout-TTY with piped stdin (npu wrapper, tee — #25): a human is
+          // watching but nobody can press Enter, so auto-open remains.
+          console.log(`  ${chalk.dim('→')} Opening your browser... (use the URL above if nothing appears)`);
+        }
+        console.log('');
+
+        stopReprint = startAuthUrlReprint(authUrl.toString(), { expiresAt: Date.now() + AUTH_WINDOW_MS });
+      });
+
+      // Timeout after 5 minutes (was 2 — humans relaying URLs need slack,
+      // #25). unref + clear on settle: a finished flow must never hold the
+      // event loop (a live run idled minutes after its summary — the zombie
+      // timer from a SUCCESSFUL auth).
+      const timeout = setTimeout(() => {
+        server.close();
+        reject(new Error('Authentication timed out'));
+      }, AUTH_WINDOW_MS);
+      timeout.unref();
+      server.on('close', () => clearTimeout(timeout));
+    });
+
+    return flow.finally(() => {
+      if (disarm) {
+        disarm();
+      }
+      if (stopReprint) {
+        stopReprint();
+      }
+    });
+  }
+
+  /**
+   * "Press Enter to open" on a raw keypress listener rather than a prompt:
+   * the consent flow can settle without Enter ever being pressed (clicked
+   * URL, timeout, error), and an abandoned prompt would pin stdin open.
+   *
+   * @returns {Function} disarm - Restores the input stream; call on settle.
+   */
+  _armEnterToOpen(url) {
+    const { getPromptStreams, openInBrowser } = require('../vendor/devkit/prompt.js');
+    const { input, output } = getPromptStreams();
+    output.write(`  ${chalk.dim('→')} Press ${chalk.bold('Enter')} to open the Google consent page in your browser...\n`);
+
+    emitKeypressEvents(input);
+    input.setRawMode?.(true);
+    input.resume();
+
+    let opened = false;
+    const handler = (ch, key) => {
+      if (key?.ctrl && key?.name === 'c') {
+        process.exit();
+      }
+      if (key?.name === 'return' && !opened) {
+        opened = true;
+        openInBrowser(url);
+        output.write(`  ${chalk.dim('→')} Opening your browser... (use the URL above if nothing appears)\n`);
+      }
+    };
+    input.on('keypress', handler);
+
+    return () => {
+      input.removeListener('keypress', handler);
+      input.setRawMode?.(false);
+      input.pause();
+    };
+  }
+
+  /**
+   * Make an authenticated request to any Google API
+   */
+  async makeRequest(url, options = {}) {
+    const token = await this.getAccessToken();
+
+    const response = await fetch(url, {
+      ...options,
+      headers: {
+        'Authorization': `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+      },
+    });
+
+    // Some endpoints return empty body on success (204)
+    if (response.status === 204 || response.headers.get('content-length') === '0') {
+      return { success: true };
+    }
+
+    const data = await response.json();
+
+    if (!response.ok) {
+      const errorMessage = data.error?.message || JSON.stringify(data);
+      let message = `Google API Error: ${errorMessage}`;
+      // Permission failures are an IDENTITY seam, not a transient fault
+      // (found live 2026-07-19: the manage identity had no role on a
+      // hand-minted project and the raw 403 diagnosed nothing) — name the
+      // acting account and both remedies right in the error.
+      if (response.status === 403 || data.error?.status === 'PERMISSION_DENIED') {
+        const email = await this.getAccountEmail();
+        const project = url.match(/\/projects\/([a-zA-Z0-9-]+)/)?.[1];
+        message += `\n      → acting Google identity: ${email || 'unknown'}${this.tokenStorePath ? ` (token store: ${this.tokenStorePath})` : ''}`;
+        message += `\n      → grant it access${project ? ` — a project owner runs: gcloud projects add-iam-policy-binding ${project} --member=user:${email || '<email>'} --role=roles/owner` : ''} — or delete the token store and rerun interactively to consent as an owning account`;
+      }
+      const error = new Error(message);
+      error.details = data.error?.details || null;
+      error.status = data.error?.status || response.status;
+      throw error;
+    }
+
+    return data;
+  }
+}
+
+module.exports = { GoogleOAuth2Client, GOOGLE_SCOPES, googleTokenStorePath, startAuthUrlReprint, CONSENT_REQUIRED };

package/dist/lib/google-token.js

@@ -0,0 +1,66 @@
+/**
+ * Google service-account access tokens — the RS256 JWT-bearer grant shared
+ * by every Google REST surface the manager talks to (Firestore via
+ * firestore-rest.js, Firebase Auth admin via the account service). Each
+ * surface needs its own OAuth scope, so callers create one provider per
+ * (service account, scope) pair; the token is cached until shortly before
+ * expiry.
+ */
+const { signJwt } = require('./jwt.js');
+
+const GOOGLE_TOKEN_URL = 'https://oauth2.googleapis.com/token';
+
+/**
+ * Create a cached access-token provider for a service account + scope.
+ *
+ * @param {Object} serviceAccount - Parsed service-account JSON (client_email, private_key)
+ * @param {string} scope - OAuth scope, e.g. 'https://www.googleapis.com/auth/datastore'
+ * @returns {{ getAccessToken: () => Promise<string> }}
+ */
+function createTokenProvider(serviceAccount, scope) {
+  let accessToken = null;
+  let tokenExpiry = 0;
+
+  return {
+    async getAccessToken() {
+      if (accessToken && Date.now() < tokenExpiry - 60000) {
+        return accessToken;
+      }
+
+      const now = Math.floor(Date.now() / 1000);
+      const assertion = signJwt(
+        { alg: 'RS256', typ: 'JWT' },
+        {
+          iss: serviceAccount.client_email,
+          scope,
+          aud: GOOGLE_TOKEN_URL,
+          iat: now,
+          exp: now + 3600,
+        },
+        serviceAccount.private_key,
+      );
+
+      const response = await fetch(GOOGLE_TOKEN_URL, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+        body: new URLSearchParams({
+          grant_type: 'urn:ietf:params:oauth:grant-type:jwt-bearer',
+          assertion,
+        }),
+      });
+
+      const data = await response.json();
+
+      if (data.error) {
+        throw new Error(`Service-account auth failed: ${data.error_description || data.error}`);
+      }
+
+      accessToken = data.access_token;
+      tokenExpiry = Date.now() + (data.expires_in * 1000);
+
+      return accessToken;
+    },
+  };
+}
+
+module.exports = { createTokenProvider, GOOGLE_TOKEN_URL };

package/dist/lib/jwt.js

@@ -0,0 +1,31 @@
+/**
+ * Minimal JWT signing over node:crypto — no jsonwebtoken dependency. Two
+ * consumers: the Firestore REST client (RS256 service-account bearer
+ * grants) and the App Store Connect client (ES256 with a `kid` header).
+ * ES256 signatures must use the raw JOSE r||s format, not ASN.1/DER —
+ * hence the ieee-p1363 dsaEncoding (ignored for RSA keys, so it's safe
+ * to set unconditionally).
+ */
+const { createSign } = require('node:crypto');
+
+/**
+ * Sign a compact JWT.
+ *
+ * @param {Object} header - JOSE header ({ alg, typ, kid? })
+ * @param {Object} payload - JWT claims
+ * @param {string} privateKey - PEM private key (RSA for RS256, EC P-256 for ES256)
+ * @returns {string} - Compact JWT (header.payload.signature)
+ */
+function signJwt(header, payload, privateKey) {
+  const encodedHeader = Buffer.from(JSON.stringify(header)).toString('base64url');
+  const encodedPayload = Buffer.from(JSON.stringify(payload)).toString('base64url');
+  const signingInput = `${encodedHeader}.${encodedPayload}`;
+
+  const signer = createSign('SHA256');
+  signer.update(signingInput);
+  const signature = signer.sign({ key: privateKey, dsaEncoding: 'ieee-p1363' }, 'base64url');
+
+  return `${signingInput}.${signature}`;
+}
+
+module.exports = { signJwt };

package/dist/lib/legacy-oauth.js

@@ -0,0 +1,59 @@
+/**
+ * The one-time legacy OAuth-secret conversion, run at PORT time
+ * ([#501](https://github.com/Omega-JS-Stack/omega/issues/501)).
+ *
+ * omega-manager kept the brand's Google OAuth client in `oauth.json` with the
+ * keys `{ googleClientId, googleClientSecret }`. OMEGA's home is
+ * `.omega/secrets/google-oauth.json` with `{ clientId, clientSecret }`
+ * (services/cloud/ensure/authentication.js), so a hand-carried legacy file sat
+ * inert beside it — the client only became real again once a live `omega
+ * manage` re-derived it from Firebase.
+ *
+ * Per the standing ruling (Ian 2026-08-21) no framework run dual-reads an old
+ * shape: onboarding CONVERTS the carried file once and removes it, and the
+ * authentication service never learns the legacy filename or key names.
+ */
+const { join } = require('node:path');
+const jetpack = require('fs-jetpack');
+
+const LEGACY_FILE = 'oauth.json';
+const CANONICAL_FILE = 'google-oauth.json';
+
+/**
+ * Convert a carried legacy `oauth.json` into the canonical
+ * `google-oauth.json`, then delete the legacy file (the conversion is
+ * one-time, so a rerun finds nothing and reports a clean no-op).
+ *
+ * @param {string} brandRoot - The brand root directory.
+ * @returns {{ converted: boolean, reason?: string }} `reason` names why a
+ *   present legacy file was left alone.
+ */
+function convertLegacyOAuthSecret(brandRoot) {
+  const secretsDir = join(brandRoot, '.omega', 'secrets');
+  const legacyPath = join(secretsDir, LEGACY_FILE);
+
+  if (!jetpack.exists(legacyPath)) {
+    return { converted: false };
+  }
+
+  if (jetpack.exists(join(secretsDir, CANONICAL_FILE))) {
+    return { converted: false, reason: `${CANONICAL_FILE} already exists — ${LEGACY_FILE} left for you to compare and delete` };
+  }
+
+  // A hand-carried file is external input: an unreadable or unrecognized one
+  // is reported, never guessed at
+  const legacy = jetpack.read(legacyPath, 'json');
+  if (!legacy?.googleClientId || !legacy?.googleClientSecret) {
+    return { converted: false, reason: `${LEGACY_FILE} carries no googleClientId/googleClientSecret pair` };
+  }
+
+  jetpack.write(join(secretsDir, CANONICAL_FILE), {
+    clientId: legacy.googleClientId,
+    clientSecret: legacy.googleClientSecret,
+  });
+  jetpack.remove(legacyPath);
+
+  return { converted: true };
+}
+
+module.exports = { convertLegacyOAuthSecret };