Add codex2api as a protocol-first OAuth source

This keeps the existing CPA, SUB2API, and contribution flows intact
while introducing codex2api as a separate source that plugs into
Step 7 and Step 10 through backend APIs instead of page DOM.

The sidepanel now exposes codex2api settings, preserves the built-in
local default through placeholder-only UI, and accepts user-provided
public admin URLs. Step 7 now treats missing or invalid management
secrets as terminal config errors so the flow stops instead of retrying
needlessly.

Constraint: New source must be additive and must not break existing CPA/SUB2API/contribution paths
Rejected: Drive codex2api through admin page button clicks | too brittle against frontend DOM changes
Rejected: Reuse contribution mode as a source surface | violates existing panelMode/runtime-mode boundary
Confidence: high
Scope-risk: moderate
Reversibility: clean
Directive: Keep codex2api on the protocol path unless its API becomes insufficient; do not add a panel content script without proving the protocol path cannot work
Tested: npm test; targeted codex2api/auth retry loops repeated 40 times; full suite repeated 5 times
Not-tested: Real browser run against a live codex2api instance with a real Admin Secret and OpenAI authorization

tests/background-account-history-settings.test.js

@@ -50,6 +50,7 @@ function extractFunction(name) {
 
 test('background account history settings are normalized independently from hotmail service mode', () => {
   const bundle = [
+    extractFunction('normalizeCodex2ApiUrl'),
     extractFunction('normalizeHotmailLocalBaseUrl'),
     extractFunction('normalizeAccountRunHistoryHelperBaseUrl'),
     extractFunction('normalizeVerificationResendCount'),
@@ -60,6 +61,7 @@ test('background account history settings are normalized independently from hotm
 const DEFAULT_HOTMAIL_LOCAL_BASE_URL = 'http://127.0.0.1:17373';
 const DEFAULT_ACCOUNT_RUN_HISTORY_HELPER_BASE_URL = DEFAULT_HOTMAIL_LOCAL_BASE_URL;
 const DEFAULT_HOTMAIL_REMOTE_BASE_URL = '';
+const DEFAULT_CODEX2API_URL = 'http://localhost:8080/admin/accounts';
 const DEFAULT_VERIFICATION_RESEND_COUNT = 4;
 const DEFAULT_SUB2API_PROXY_NAME = '';
 const HOTMAIL_SERVICE_MODE_REMOTE = 'remote';
@@ -70,7 +72,7 @@ const PERSISTED_SETTING_DEFAULTS = {
   autoStepDelaySeconds: null,
   mailProvider: '163',
 };
-function normalizePanelMode(value) { return value === 'sub2api' ? 'sub2api' : 'cpa'; }
+function normalizePanelMode(value) { return value === 'sub2api' ? 'sub2api' : (value === 'codex2api' ? 'codex2api' : 'cpa'); }
 function normalizeLocalCpaStep9Mode(value) { return value === 'bypass' ? 'bypass' : 'submit'; }
 function normalizeAutoRunFallbackThreadIntervalMinutes(value) { return Number(value) || 0; }
 function normalizeAutoRunDelayMinutes(value) { return Number(value) || 30; }
@@ -118,4 +120,16 @@ return {
     api.normalizePersistentSettingValue('sub2apiDefaultProxyName', ' proxy-a '),
     'proxy-a'
   );
+  assert.equal(
+    api.normalizePersistentSettingValue('codex2apiUrl', 'localhost:8080/admin'),
+    'http://localhost:8080/admin/accounts'
+  );
+  assert.equal(
+    api.normalizePersistentSettingValue('codex2apiUrl', 'https://codex-admin.example.com/'),
+    'https://codex-admin.example.com/admin/accounts'
+  );
+  assert.equal(
+    api.normalizePersistentSettingValue('codex2apiAdminKey', ' secret-key '),
+    'secret-key'
+  );
 });

tests/background-contribution-mode.test.js

@@ -536,7 +536,7 @@ return { refreshOAuthUrlBeforeStep6 };
   delete globalThis.LOG_PREFIX;
 });
 
-test('refreshOAuthUrlBeforeStep6 logs the normal CPA/SUB2API path explicitly when contributionMode=false', async () => {
+test('refreshOAuthUrlBeforeStep6 logs the normal CPA/SUB2API/Codex2API path explicitly when contributionMode=false', async () => {
   const bundle = extractFunction(backgroundSource, 'refreshOAuthUrlBeforeStep6');
   const calls = [];
 
@@ -574,7 +574,7 @@ return { refreshOAuthUrlBeforeStep6 };
 
   assert.equal(oauthUrl, 'https://panel.example.com/oauth');
   assert.deepStrictEqual(calls, [
-    { type: 'log', message: '步骤 7：contributionMode=false，走普通 CPA / SUB2API 链路（当前面板：SUB2API），正在刷新 OAuth 登录地址...' },
+    { type: 'log', message: '步骤 7：contributionMode=false，走普通 CPA / SUB2API / Codex2API 链路（当前面板：SUB2API），正在刷新 OAuth 登录地址...' },
     { type: 'panel' },
     {
       type: 'step',

tests/background-navigation-utils-module.test.js

@@ -15,3 +15,23 @@ test('navigation utils module exposes a factory', () => {
 
   assert.equal(typeof api?.createNavigationUtils, 'function');
 });
+
+test('navigation utils support codex2api mode and url normalization', () => {
+  const source = fs.readFileSync('background/navigation-utils.js', 'utf8');
+  const globalScope = {};
+
+  const api = new Function('self', `${source}; return self.MultiPageBackgroundNavigationUtils;`)(globalScope);
+  const utils = api.createNavigationUtils({
+    DEFAULT_CODEX2API_URL: 'http://localhost:8080/admin/accounts',
+    DEFAULT_SUB2API_URL: 'https://sub.example.com/admin/accounts',
+    normalizeLocalCpaStep9Mode: (value) => value,
+  });
+
+  assert.equal(utils.normalizeCodex2ApiUrl('localhost:8080/admin'), 'http://localhost:8080/admin/accounts');
+  assert.equal(
+    utils.normalizeCodex2ApiUrl('https://codex-admin.example.com/'),
+    'https://codex-admin.example.com/admin/accounts'
+  );
+  assert.equal(utils.getPanelMode({ panelMode: 'codex2api' }), 'codex2api');
+  assert.equal(utils.getPanelModeLabel('codex2api'), 'Codex2API');
+});

tests/background-panel-bridge-module.test.js

@@ -21,3 +21,53 @@ test('panel bridge requests oauth url with step 7 log label payload', () => {
   assert.match(source, /logStep:\s*7/);
   assert.doesNotMatch(source, /logStep:\s*6/);
 });
+
+test('panel bridge can request codex2api oauth url via protocol', async () => {
+  const source = fs.readFileSync('background/panel-bridge.js', 'utf8');
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url, options = {}) => {
+      assert.equal(url, 'http://localhost:8080/api/admin/oauth/generate-auth-url');
+      assert.equal(options.method, 'POST');
+      assert.equal(options.headers['X-Admin-Key'], 'admin-secret');
+      return {
+        ok: true,
+        json: async () => ({
+          auth_url: 'https://auth.openai.com/authorize?state=oauth-state',
+          session_id: 'session-123',
+        }),
+      };
+  };
+
+  try {
+    const api = new Function('self', `${source}; return self.MultiPageBackgroundPanelBridge;`)({});
+    const bridge = api.createPanelBridge({
+      addLog: async () => {},
+      chrome: {},
+      closeConflictingTabsForSource: async () => {},
+      ensureContentScriptReadyOnTab: async () => {},
+      getPanelMode: () => 'codex2api',
+      normalizeCodex2ApiUrl: (value) => value ? `http://${value.replace(/^https?:\/\//, '')}`.replace(/\/admin$/, '/admin/accounts') : 'http://localhost:8080/admin/accounts',
+      normalizeSub2ApiUrl: (value) => value,
+      rememberSourceLastUrl: async () => {},
+      sendToContentScript: async () => ({}),
+      sendToContentScriptResilient: async () => ({}),
+      waitForTabUrlFamily: async () => null,
+      DEFAULT_SUB2API_GROUP_NAME: 'codex',
+      SUB2API_STEP1_RESPONSE_TIMEOUT_MS: 90000,
+    });
+
+    const result = await bridge.requestOAuthUrlFromPanel({
+      panelMode: 'codex2api',
+      codex2apiUrl: 'localhost:8080/admin',
+      codex2apiAdminKey: 'admin-secret',
+    }, { logLabel: '步骤 7' });
+
+    assert.deepStrictEqual(result, {
+      oauthUrl: 'https://auth.openai.com/authorize?state=oauth-state',
+      codex2apiSessionId: 'session-123',
+      codex2apiOAuthState: 'oauth-state',
+    });
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

tests/background-platform-verify-codex2api.test.js

@@ -0,0 +1,81 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const test = require('node:test');
+
+test('platform verify module supports codex2api protocol callback exchange', async () => {
+  const source = fs.readFileSync('background/steps/platform-verify.js', 'utf8');
+  const originalFetch = globalThis.fetch;
+  globalThis.fetch = async (url, options = {}) => {
+      assert.equal(url, 'http://localhost:8080/api/admin/oauth/exchange-code');
+      assert.equal(options.method, 'POST');
+      assert.equal(options.headers['X-Admin-Key'], 'admin-secret');
+      assert.deepStrictEqual(JSON.parse(options.body), {
+        session_id: 'session-123',
+        code: 'callback-code',
+        state: 'oauth-state',
+      });
+      return {
+        ok: true,
+        json: async () => ({
+          message: 'OAuth 账号 flow@example.com 添加成功',
+          id: 42,
+          email: 'flow@example.com',
+          plan_type: 'pro',
+        }),
+      };
+  };
+
+  try {
+    const api = new Function('self', `${source}; return self.MultiPageBackgroundStep10;`)({});
+    const completed = [];
+    const logs = [];
+    const executor = api.createStep10Executor({
+      addLog: async (message, level = 'info') => {
+        logs.push({ message, level });
+      },
+      chrome: {},
+      closeConflictingTabsForSource: async () => {},
+      completeStepFromBackground: async (step, payload) => {
+        completed.push({ step, payload });
+      },
+      ensureContentScriptReadyOnTab: async () => {},
+      getPanelMode: () => 'codex2api',
+      getTabId: async () => 0,
+      isLocalhostOAuthCallbackUrl: (value) => String(value || '').includes('/auth/callback?code='),
+      isTabAlive: async () => false,
+      normalizeCodex2ApiUrl: () => 'http://localhost:8080/admin/accounts',
+      normalizeSub2ApiUrl: (value) => value,
+      rememberSourceLastUrl: async () => {},
+      reuseOrCreateTab: async () => 0,
+      sendToContentScript: async () => ({}),
+      sendToContentScriptResilient: async () => ({}),
+      shouldBypassStep9ForLocalCpa: () => false,
+      SUB2API_STEP9_RESPONSE_TIMEOUT_MS: 120000,
+    });
+
+    await executor.executeStep10({
+      panelMode: 'codex2api',
+      localhostUrl: 'http://localhost:1455/auth/callback?code=callback-code&state=oauth-state',
+      codex2apiUrl: 'http://localhost:8080/admin/accounts',
+      codex2apiAdminKey: 'admin-secret',
+      codex2apiSessionId: 'session-123',
+      codex2apiOAuthState: 'oauth-state',
+    });
+
+    assert.deepStrictEqual(logs, [
+      { message: '步骤 10：正在向 Codex2API 提交回调并创建账号...', level: 'info' },
+      { message: '步骤 10：OAuth 账号 flow@example.com 添加成功', level: 'ok' },
+    ]);
+    assert.deepStrictEqual(completed, [
+      {
+        step: 10,
+        payload: {
+          localhostUrl: 'http://localhost:1455/auth/callback?code=callback-code&state=oauth-state',
+          verifiedStatus: 'OAuth 账号 flow@example.com 添加成功',
+        },
+      },
+    ]);
+  } finally {
+    globalThis.fetch = originalFetch;
+  }
+});

tests/background-step6-retry-limit.test.js

@@ -177,3 +177,88 @@ test('step 7 starts a new oauth timeout window for each refreshed oauth url', as
     },
   ]);
 });
+
+test('step 7 stops immediately when management secret is missing', async () => {
+  const source = fs.readFileSync('background/steps/oauth-login.js', 'utf8');
+  const globalScope = {};
+  const api = new Function('self', `${source}; return self.MultiPageBackgroundStep7;`)(globalScope);
+
+  const events = {
+    refreshCalls: 0,
+    sendCalls: 0,
+    logs: [],
+  };
+
+  const executor = api.createStep7Executor({
+    addLog: async (message, level = 'info') => {
+      events.logs.push({ message, level });
+    },
+    completeStepFromBackground: async () => {},
+    getErrorMessage: (error) => error?.message || String(error || ''),
+    getLoginAuthStateLabel: (state) => state || 'unknown',
+    getState: async () => ({ email: 'user@example.com', password: 'secret' }),
+    isStep6RecoverableResult: (result) => result?.step6Outcome === 'recoverable',
+    isStep6SuccessResult: (result) => result?.step6Outcome === 'success',
+    refreshOAuthUrlBeforeStep6: async () => {
+      events.refreshCalls += 1;
+      throw new Error('尚未配置 Codex2API 管理密钥，请先在侧边栏填写。');
+    },
+    reuseOrCreateTab: async () => {},
+    sendToContentScriptResilient: async () => {
+      events.sendCalls += 1;
+      return { step6Outcome: 'success' };
+    },
+    STEP6_MAX_ATTEMPTS: 3,
+    throwIfStopped: () => {},
+  });
+
+  await assert.rejects(
+    () => executor.executeStep7({ email: 'user@example.com', password: 'secret' }),
+    /管理密钥/
+  );
+
+  assert.equal(events.refreshCalls, 1);
+  assert.equal(events.sendCalls, 0);
+  assert.ok(events.logs.some(({ message }) => /管理密钥缺失或错误，不再重试，当前流程停止/.test(message)));
+  assert.ok(!events.logs.some(({ message }) => /准备重试/.test(message)));
+});
+
+test('step 7 stops immediately when management secret is invalid', async () => {
+  const source = fs.readFileSync('background/steps/oauth-login.js', 'utf8');
+  const globalScope = {};
+  const api = new Function('self', `${source}; return self.MultiPageBackgroundStep7;`)(globalScope);
+
+  const events = {
+    refreshCalls: 0,
+    logs: [],
+  };
+
+  const executor = api.createStep7Executor({
+    addLog: async (message, level = 'info') => {
+      events.logs.push({ message, level });
+    },
+    completeStepFromBackground: async () => {},
+    getErrorMessage: (error) => error?.message || String(error || ''),
+    getLoginAuthStateLabel: (state) => state || 'unknown',
+    getState: async () => ({ email: 'user@example.com', password: 'secret' }),
+    isStep6RecoverableResult: (result) => result?.step6Outcome === 'recoverable',
+    isStep6SuccessResult: (result) => result?.step6Outcome === 'success',
+    refreshOAuthUrlBeforeStep6: async () => {
+      events.refreshCalls += 1;
+      throw new Error('Codex2API 请求失败（HTTP 401）。X-Admin-Key 无效或未授权。');
+    },
+    reuseOrCreateTab: async () => {},
+    sendToContentScriptResilient: async () => ({ step6Outcome: 'success' }),
+    STEP6_MAX_ATTEMPTS: 3,
+    throwIfStopped: () => {},
+  });
+
+  await assert.rejects(
+    () => executor.executeStep7({ email: 'user@example.com', password: 'secret' }),
+    /401|未授权|无效/
+  );
+
+  assert.equal(events.refreshCalls, 1);
+  assert.ok(events.logs.some(({ message }) => /管理密钥缺失或错误，不再重试，当前流程停止/.test(message)));
+  assert.ok(!events.logs.some(({ message }) => /准备重试/.test(message)));
+});

tests/sidepanel-contribution-mode.test.js

@@ -135,6 +135,8 @@ const inputSub2ApiEmail = { value: 'user@example.com' };
 const inputSub2ApiPassword = { value: 'sub-secret' };
 const inputSub2ApiGroup = { value: ' codex ' };
 const inputSub2ApiDefaultProxy = { value: ' proxy-a ' };
+const inputCodex2ApiUrl = { value: 'http://localhost:8080/admin/accounts' };
+const inputCodex2ApiAdminKey = { value: 'codex-admin-secret' };
 const inputPassword = { value: 'Secret123!' };
 const selectMailProvider = { value: '163' };
 const selectEmailGenerator = { value: 'duck' };
@@ -196,6 +198,8 @@ return {
   assert.equal(normalPayload.customPassword, 'Secret123!');
   assert.equal(normalPayload.accountRunHistoryTextEnabled, true);
   assert.equal(normalPayload.accountRunHistoryHelperBaseUrl, 'http://127.0.0.1:17373');
+  assert.equal(normalPayload.codex2apiUrl, 'http://localhost:8080/admin/accounts');
+  assert.equal(normalPayload.codex2apiAdminKey, 'codex-admin-secret');
 });
 
 test('contribution mode manager enters mode, starts main auto flow, polls contribution status, and exits cleanly', async () => {
@@ -264,6 +268,8 @@ test('contribution mode manager enters mode, starts main auto flow, polls contri
     rowSub2ApiGroup: createElement(),
     rowSub2ApiPassword: createElement(),
     rowSub2ApiUrl: createElement(),
+    rowCodex2ApiUrl: createElement(),
+    rowCodex2ApiAdminKey: createElement(),
     rowVpsPassword: createElement(),
     rowVpsUrl: createElement(),
     selectPanelMode: createElement({ value: 'sub2api' }),
@@ -414,6 +420,8 @@ test('contribution mode manager enters mode, starts main auto flow, polls contri
   assert.equal(dom.contributionModeSummary.textContent.length > 0, true);
   assert.equal(dom.btnContributionMode.classList.contains('is-active'), true);
   assert.equal(dom.rowVpsUrl.classList.contains('is-contribution-hidden'), true);
+  assert.equal(dom.rowCodex2ApiUrl.classList.contains('is-contribution-hidden'), true);
+  assert.equal(dom.rowCodex2ApiAdminKey.classList.contains('is-contribution-hidden'), true);
   assert.ok(closeConfigMenuCount >= 1);
   assert.ok(closeAccountRecordsCount >= 1);
   assert.ok(updatePanelModeCount >= 1);