fix(natively-key): stop parking a user on a model their key cannot reach

CredentialsManager.setNativelyApiKey() auto-promotes the default model (and
STT) to 'natively' and SAVES before anything has checked the key works. When
the server then refused the key, the failure branch only console.log'd: no
revert, no UI. The user pasted a key, saw "saved", and sat on an endpoint
that rejects every request — which is how a 2.8.7 win32 user ended up unable
to get any answer at all.

set-natively-api-key now acts on the keyRejected verdict from the premium
LicenseManager (bumped here): it undoes the promotion, re-syncs LLMHelper and
the UI, rebuilds the STT pipeline if that moved too, and returns
{ success:false, error } instead of the unconditional { success:true } it
returned even for a key that authenticates nowhere. The settings panel
already renders `error` on a failed save, so the server's real reason reaches
the user without a renderer change.

Only the 4xx branch does any of this. A standard-plan key still
authenticates against /v1/chat — PRO_PLANS gates only /v1/pro/verify — and a
5xx or network verdict says nothing about the key, so neither may tear down
working state.

The revert keys on the CURRENT value being 'natively', not on a pre-call
snapshot: re-saving a key that was already stored leaves the snapshot reading
'natively' too, so restoring it would restore the broken state. It touches
nothing else, so a deliberately chosen model is not collateral.

The key itself is retained. A lapsed subscription should not require
re-pasting on renewal, but the UI reports failure because the key does not
currently work.

Also makes withStubbedFetch in LicenseNativeModuleAbsent a faithful Response
double by giving it `ok`. A double that omits it silently misreports a 200 to
any code that reads the field.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BibR1zU9YXQgzT8Ty18yTY

Author: Hardening v2.7

electron/ipcHandlers.ts

@@ -7030,6 +7030,10 @@ export function initializeIpcHandlers(appState: AppState): void {
   const PRICING_CACHE_TTL_MS = 5 * 60_000;
 
   safeHandle('set-natively-api-key', async (_, apiKey: string) => {
+    // Set when the server REFUSES the key, so the handler can report the real
+    // reason instead of the unconditional { success: true } it used to return
+    // even for a key that authenticates nowhere.
+    let keyRejection: { error?: string } | null = null;
     try {
       const { CredentialsManager } = require('./services/CredentialsManager');
       const cm = CredentialsManager.getInstance();
@@ -7112,6 +7116,39 @@ export function initializeIpcHandlers(appState: AppState): void {
               '[IPC] set-natively-api-key: Pro inactive —',
               result.error,
             );
+          } else if (result.keyRejected) {
+            // The server REFUSED the key (4xx): it authenticates nowhere,
+            // /v1/chat included (both go through validateKey). By this point
+            // CredentialsManager.setNativelyApiKey has ALREADY auto-promoted the
+            // default model — and possibly the STT provider — to 'natively' and
+            // saved, so leaving it here parks the user on an endpoint that
+            // rejects every request, with nothing but a console line to say why.
+            // Undo the promotion and hand the server's own reason to the settings
+            // UI, which already renders `error` when a save reports failure.
+            //
+            // Only the 4xx branch does this. A standard-plan key ('no Pro') still
+            // authenticates against /v1/chat — the server gates only
+            // /v1/pro/verify on PRO_PLANS — and a 5xx/network verdict says
+            // nothing about the key, so neither may tear down working state.
+            console.warn(
+              '[IPC] set-natively-api-key: key REFUSED by server —',
+              result.code,
+              result.error,
+            );
+            const reverted = cm.revertNativelyAutoDefaults('Natively key refused by server');
+            if (reverted.defaultModel) {
+              const revertedProviders = [
+                ...(cm.getCurlProviders() || []),
+                ...(cm.getCustomProviders() || []),
+              ];
+              llmHelper.setModel(reverted.defaultModel, revertedProviders);
+              appState.sendModelChanged(reverted.defaultModel);
+            }
+            if (reverted.sttProvider) {
+              await appState.reconfigureSttProvider();
+            }
+            broadcastCredentialsChanged();
+            keyRejection = { error: result.error };
           } else {
             console.log('[IPC] set-natively-api-key: Pro not activated —', result.error);
           }
@@ -7149,7 +7186,9 @@ export function initializeIpcHandlers(appState: AppState): void {
         }
       }
 
-      return { success: true };
+      return keyRejection
+        ? { success: false, error: keyRejection.error }
+        : { success: true };
     } catch (error: any) {
       console.error('Error saving Natively API key:', error);
       return { success: false, error: error.message };

electron/services/CredentialsManager.ts

@@ -1185,6 +1185,50 @@ export class CredentialsManager {
         console.log(`[CredentialsManager] Default Model set to: ${model}`);
     }
 
+    /**
+     * Undo the auto-promotions setNativelyApiKey() performs when a key is stored.
+     * Mutates only; the caller saves.
+     *
+     * Returns what actually changed so a caller can re-sync the runtime (LLMHelper
+     * model, STT pipeline) instead of guessing.
+     */
+    private applyNativelyAutoDefaultRevert(reason: string): { defaultModel?: string; sttProvider?: string } {
+        const changed: { defaultModel?: string; sttProvider?: string } = {};
+        if (this.credentials.defaultModel === 'natively') {
+            this.credentials.defaultModel = 'gemini-3.1-flash-lite';
+            changed.defaultModel = this.credentials.defaultModel;
+            console.log(`[CredentialsManager] ${reason} — reset default model to Gemini Flash-Lite`);
+        }
+        if (this.credentials.sttProvider === 'natively') {
+            this.credentials.sttProvider = 'none';
+            changed.sttProvider = 'none';
+            console.log(`[CredentialsManager] ${reason} — reset STT provider to none`);
+        }
+        return changed;
+    }
+
+    /**
+     * Public revert, for when a stored key turns out NOT to authenticate.
+     *
+     * setNativelyApiKey() promotes the default model (and STT) to 'natively' and
+     * saves BEFORE anything has checked that the key works. When the server then
+     * refuses the key, the user is left routed at an endpoint that rejects them —
+     * silently, because the failure branch only logged. This is how that caller
+     * undoes the promotion.
+     *
+     * Deliberately keyed on the CURRENT value being 'natively' rather than on a
+     * pre-call snapshot: re-saving a key that was already stored leaves the
+     * snapshot reading 'natively' too, so restoring it would restore the broken
+     * state. Falling back to the same safe defaults the key-cleared path uses
+     * always lands somewhere that can actually serve a request.
+     */
+    public revertNativelyAutoDefaults(reason: string): { defaultModel?: string; sttProvider?: string } {
+        if (this.refuseWriteWhileDegraded('revert natively auto defaults')) return {};
+        const changed = this.applyNativelyAutoDefaultRevert(reason);
+        if (changed.defaultModel || changed.sttProvider) this.saveCredentials();
+        return changed;
+    }
+
     public setNativelyApiKey(key: string): void {
         if (this.refuseWriteWhileDegraded('set natively api key')) return;
         const trimmed = key.trim();
@@ -1225,14 +1269,7 @@ export class CredentialsManager {
             }
         } else {
             // Key cleared — revert natively-auto-set defaults back to safe fallbacks
-            if (this.credentials.defaultModel === 'natively') {
-                this.credentials.defaultModel = 'gemini-3.1-flash-lite';
-                console.log('[CredentialsManager] Natively key cleared — reset default model to Gemini Flash-Lite');
-            }
-            if (this.credentials.sttProvider === 'natively') {
-                this.credentials.sttProvider = 'none';
-                console.log('[CredentialsManager] Natively key cleared — reset STT provider to none');
-            }
+            this.applyNativelyAutoDefaultRevert('Natively key cleared');
         }
 
         this.saveCredentials();

electron/services/__tests__/LicenseKeyRejectionVerdicts2026_08_27.test.mjs

@@ -0,0 +1,208 @@
+// activateWithApiKey must tell three different failures apart.
+//
+// From a 2026-08-27 win32 user report: the log read
+//   [LicenseManager] activateWithApiKey: plan has no Pro — undefined
+//   [IPC] set-natively-api-key: Pro not activated — Your plan does not include Natively Pro.
+// The user was NOT on a free plan. natively-api's /v1/pro/verify (server.js:5716)
+// always emits `plan` on its success path (`auth.user.plan || 'standard'`), so a
+// genuine standard-plan user logs "— standard". `undefined` can only come from
+// the !auth.ok branch, which returns {ok:false, error} with NO plan field. The
+// server had REFUSED the key; the old `if (!data.ok || !data.has_pro)` read that
+// body as a plan verdict, discarded the server's actual reason (and its
+// account-specific `message`), and reported a wrong, unactionable cause.
+//
+// The distinction matters beyond the message. /v1/chat authenticates through the
+// same validateKey and has NO plan gate — PRO_PLANS is referenced only by
+// /v1/pro/verify — so:
+//   - refused key (4xx)  → authenticates nowhere; the caller must undo any
+//                          auto-promotion it made on the strength of this key
+//   - no Pro    (200)    → chat still works; app state must NOT change
+//   - 5xx / bad body     → no verdict at all; app state must NOT change
+import { test, describe, before, after, beforeEach } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import Module, { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const USER_DATA = fs.mkdtempSync(path.join(os.tmpdir(), 'natively-license-verdict-'));
+process.env.NATIVELY_TEST_USERDATA = USER_DATA;
+const LICENSE_PATH = path.join(USER_DATA, 'license.enc');
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const electronStub = path.join(HERE, '__electron_license_stub.mjs');
+const nativeStub = path.join(HERE, '__native_module_stub.cjs');
+createRequire(import.meta.url)(nativeStub);
+
+const originalResolve = Module._resolveFilename;
+Module._resolveFilename = function (request, ...rest) {
+  if (request === 'electron') return electronStub;
+  if (typeof request === 'string' && request.endsWith('.node')) return nativeStub;
+  return originalResolve.call(this, request, ...rest);
+};
+
+const { LicenseManager } = await import(
+  '../../../dist-electron/premium/electron/services/LicenseManager.js'
+);
+
+after(() => {
+  Module._resolveFilename = originalResolve;
+  globalThis.fetch = originalFetch;
+  fs.rmSync(USER_DATA, { recursive: true, force: true });
+});
+
+function freshManager() {
+  delete globalThis.__nativelyLicenseManagerV1__;
+  LicenseManager.instance = undefined;
+  return LicenseManager.getInstance();
+}
+
+const originalFetch = globalThis.fetch;
+
+/** Duck-typed Response: activateWithApiKey reads only ok/status/json(). */
+function reply(status, body, { jsonThrows = false } = {}) {
+  globalThis.fetch = async () => ({
+    ok: status >= 200 && status < 300,
+    status,
+    json: async () => {
+      if (jsonThrows) throw new SyntaxError('Unexpected token < in JSON at position 0');
+      return body;
+    },
+  });
+}
+
+beforeEach(() => {
+  // No stored license → perpetualLicenseGuard passes and the network path runs.
+  fs.rmSync(LICENSE_PATH, { force: true });
+});
+
+before(() => {
+  assert.equal(
+    typeof freshManager().activateWithApiKey,
+    'function',
+    'precondition failed: compiled LicenseManager did not load',
+  );
+});
+
+describe('4xx — the server refused the key', () => {
+  test('an inactive subscription surfaces the SERVER\'s own next step', async () => {
+    reply(403, { ok: false, error: 'subscription_inactive', message: 'Renew at natively.software/api' });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_lapsed');
+
+    assert.equal(r.success, false);
+    assert.equal(r.keyRejected, true, 'a 4xx refusal must be distinguishable from a plan verdict');
+    assert.equal(r.code, 'subscription_inactive');
+    assert.equal(r.status, 403);
+    assert.equal(
+      r.error,
+      'Renew at natively.software/api',
+      "the server's account-specific message is the only source that knows the next step — it must not be replaced",
+    );
+    assert.notEqual(
+      r.error,
+      'Your plan does not include Natively Pro.',
+      'this is the exact misreport from the 2026-08-27 user log',
+    );
+  });
+
+  test('a refusal with no server message still names an actionable cause', async () => {
+    reply(401, { ok: false, error: 'key_not_found' });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_ghost');
+
+    assert.equal(r.keyRejected, true);
+    assert.equal(r.code, 'key_not_found');
+    assert.match(r.error, /not recognised/i, 'the user must learn the KEY was rejected, not their plan');
+  });
+
+  test('a rate-limited refusal reports the retry window', async () => {
+    reply(429, { ok: false, error: 'identity_blocked', retry_after: 42 });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_blocked');
+
+    assert.equal(r.keyRejected, true);
+    assert.match(r.error, /42/, 'retry_after is the only actionable detail on a 429');
+  });
+});
+
+describe('200 — the key authenticates, the plan simply has no Pro', () => {
+  test('a standard plan is NOT a rejected key', async () => {
+    reply(200, { ok: true, has_pro: false, plan: 'standard' });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_standard');
+
+    assert.equal(r.success, false);
+    assert.ok(
+      !r.keyRejected,
+      'CRITICAL: a standard-plan key authenticates against /v1/chat (the server gates only /v1/pro/verify on PRO_PLANS). Marking it rejected would tear down a WORKING configuration.',
+    );
+    assert.equal(r.error, 'Your plan does not include Natively Pro.');
+  });
+});
+
+describe('no verdict — nothing may be torn down', () => {
+  test('a 5xx is transient, not a statement about the key', async () => {
+    reply(503, { error: 'upstream_unavailable' });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_valid');
+
+    assert.equal(r.success, false);
+    assert.ok(!r.keyRejected, 'an outage must never be reported as a bad key');
+    assert.equal(r.status, 503);
+  });
+
+  test('an HTML error page (json() throws) is transient, not "could not reach server"', async () => {
+    // A proxy answering 502 with HTML used to throw out of res.json() into the
+    // outer catch and be reported as a network failure — wrong for a server that
+    // answered, and it hid the status.
+    reply(502, null, { jsonThrows: true });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_valid');
+
+    assert.ok(!r.keyRejected);
+    assert.equal(r.status, 502, 'the status must survive a body that will not parse');
+  });
+
+  test('a 2xx with an unexpected body is not read as a plan verdict', async () => {
+    reply(200, { unexpected: true });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_valid');
+
+    assert.equal(r.success, false);
+    assert.ok(!r.keyRejected, 'refuse to guess in either direction on a malformed body');
+    assert.notEqual(r.error, 'Your plan does not include Natively Pro.');
+  });
+});
+
+describe('robustness of the success test itself', () => {
+  test('a Response-like object with no `ok` property is judged by status, not by the missing field', async () => {
+    // This is a real regression, not a hypothetical: the first cut of this fix
+    // read `res.ok`, and the existing LicenseNativeModule*.test.mjs doubles
+    // return { status, json } with no `ok`. An absent property is falsy, so a
+    // plain 200 was read as a 4xx — a VALID pro key reported as refused, which
+    // would then tear down the user's working configuration. Response.ok is
+    // defined as status in [200,299]; derive it, never read it.
+    globalThis.fetch = async () => ({
+      status: 200,
+      json: async () => ({ ok: true, has_pro: true, plan: 'ultra' }),
+    });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_pro');
+
+    assert.ok(!r.keyRejected, 'a 200 with no `ok` field on the Response must never read as a refused key');
+    assert.equal(r.success, true);
+  });
+});
+
+describe('positive control', () => {
+  test('a pro plan still activates (the happy path is not collateral damage)', async () => {
+    reply(200, { ok: true, has_pro: true, plan: 'pro' });
+
+    const r = await freshManager().activateWithApiKey('natively_sk_pro');
+
+    assert.equal(r.success, true, 'a genuine pro key must still activate');
+    assert.ok(!r.keyRejected);
+  });
+});

electron/services/__tests__/LicenseNativeModuleAbsent.test.mjs

@@ -96,7 +96,10 @@ const PRO_VERIFY_OK = { status: 200, body: { ok: true, has_pro: true, plan: 'ult
  */
 async function withStubbedFetch({ status, body }, fn) {
   const previous = globalThis.fetch;
-  globalThis.fetch = async () => ({ status, json: async () => body });
+  // `ok` included so the double is a faithful Response: it is defined as
+  // status in [200,299], and a double that omits it silently misreports a
+  // 200 as a failure to any code that reads it.
+  globalThis.fetch = async () => ({ ok: status >= 200 && status < 300, status, json: async () => body });
   try {
     return await fn();
   } finally {