Account Sign-in and Cloud Switches (S0) Implementation Plan¶

// electron/src/main/account/cloud-config.test.ts
import { expect, it } from 'vitest';
import { cloudOrigins, resolveCloudEnvironment } from './cloud-config';

it('packaged builds are locked to production whatever the env var says', () => {
  expect(resolveCloudEnvironment({ packaged: true, requested: 'local' }).name).toBe('prod');
});

it('developer builds honour VOICESTUDIO_CLOUD_ENV and default to dev', () => {
  expect(resolveCloudEnvironment({ packaged: false, requested: 'local' }).issuer).toBe(
    'http://127.0.0.1:3000/identity/realms/vssaas',
  );
  expect(resolveCloudEnvironment({ packaged: false }).name).toBe('dev');
  expect(resolveCloudEnvironment({ packaged: false, requested: 'bogus' }).name).toBe('dev');
});

it('uses the open-source public client everywhere', () => {
  for (const requested of ['prod', 'dev', 'local'])
    expect(resolveCloudEnvironment({ packaged: false, requested }).clientId).toBe(
      'voicestudio-desktop-oss',
    );
});

it('lists exactly the origins the app may contact', () => {
  expect([...cloudOrigins(resolveCloudEnvironment({ packaged: true }))].sort()).toEqual([
    'https://appapi.voicestudio.sh',
    'https://voicestudio.sh',
  ]);
});

// electron/src/main/account/cloud-config.ts
/** VoiceStudio Cloud endpoints (vssaas desktop-app-guide §1). One block per environment. */
export type CloudEnvName = 'prod' | 'dev' | 'local';

export interface CloudEnvironment {
  name: CloudEnvName;
  issuer: string;
  accountApi: string;
  syncApi: string;
  signedInPage: string;
  clientId: string;
}

const CLIENT_ID = 'voicestudio-desktop-oss';

const ENVIRONMENTS: Record<CloudEnvName, Omit<CloudEnvironment, 'name' | 'clientId'>> = {
  prod: {
    issuer: 'https://voicestudio.sh/identity/realms/vssaas',
    accountApi: 'https://appapi.voicestudio.sh/v1/account',
    syncApi: 'https://appapi.voicestudio.sh/v1/sync',
    signedInPage: 'https://app.voicestudio.sh/app/desktop-signed-in',
  },
  dev: {
    issuer: 'https://dev.voicestudio.sh/identity/realms/vssaas',
    accountApi: 'https://dev-appapi.voicestudio.sh/v1/account',
    syncApi: 'https://dev-appapi.voicestudio.sh/v1/sync',
    signedInPage: 'https://dev-app.voicestudio.sh/app/desktop-signed-in',
  },
  local: {
    issuer: 'http://127.0.0.1:3000/identity/realms/vssaas',
    accountApi: 'http://127.0.0.1:8080/v1/account',
    syncApi: 'http://127.0.0.1:8090/v1/sync',
    signedInPage: 'http://127.0.0.1:3000/app/desktop-signed-in',
  },
};

export function resolveCloudEnvironment(opts: {
  packaged: boolean;
  requested?: string;
}): CloudEnvironment {
  const requested = opts.requested as CloudEnvName | undefined;
  const name: CloudEnvName = opts.packaged
    ? 'prod'
    : requested && requested in ENVIRONMENTS
      ? requested
      : 'dev';
  return { name, clientId: CLIENT_ID, ...ENVIRONMENTS[name] };
}

/** Sync origins join in S1; S0 talks only to the issuer and the account API. */
export function cloudOrigins(env: CloudEnvironment): Set<string> {
  return new Set([new URL(env.issuer).origin, new URL(env.accountApi).origin]);
}

/** Off in release builds until the vssaas production API launches. */
export function cloudAccountsAvailable(): boolean {
  return typeof __CLOUD_ACCOUNTS__ === 'boolean' && __CLOUD_ACCOUNTS__;
}

  // VoiceStudio Cloud sign-in ships dark until the vssaas production API is live.
  __CLOUD_ACCOUNTS__: JSON.stringify(
    process.env.VOICESTUDIO_CLOUD_ACCOUNTS === '1' || process.env.NODE_ENV === 'development',
  ),

git add electron/src/main/account/cloud-config.ts electron/src/main/account/cloud-config.test.ts electron/electron.vite.config.ts electron/src/main/env.d.ts
git commit -m "feat(account): cloud environment config and build flag"

// electron/src/main/account/cloud-switches.test.ts
import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { expect, it, vi } from 'vitest';
import { CloudSwitchStore } from './cloud-switches';

const file = () => join(mkdtempSync(join(tmpdir(), 'vs-switch-')), 'cloud-switches.json');

it('starts with everything off and unprompted', () => {
  expect(new CloudSwitchStore(file()).get()).toEqual({
    accountEnabled: false,
    syncEnabled: false,
    prompted: false,
  });
});

it('a corrupt file reads as all off', () => {
  const path = file();
  writeFileSync(path, '{"accountEnabled": tr');
  expect(new CloudSwitchStore(path).get().accountEnabled).toBe(false);
});

it('persists across instances (restart)', () => {
  const path = file();
  new CloudSwitchStore(path).set({ accountEnabled: true, syncEnabled: true, prompted: true });
  expect(new CloudSwitchStore(path).get()).toEqual({
    accountEnabled: true,
    syncEnabled: true,
    prompted: true,
  });
  expect(JSON.parse(readFileSync(path, 'utf8')).syncEnabled).toBe(true);
});

it('sync cannot be on while account features are off', () => {
  const store = new CloudSwitchStore(file());
  expect(store.set({ syncEnabled: true }).syncEnabled).toBe(false);
  store.set({ accountEnabled: true, syncEnabled: true });
  expect(store.set({ accountEnabled: false })).toMatchObject({
    accountEnabled: false,
    syncEnabled: false,
  });
});

it('notifies subscribers with the previous value', () => {
  const store = new CloudSwitchStore(file());
  const cb = vi.fn();
  store.subscribe(cb);
  store.set({ accountEnabled: true });
  expect(cb).toHaveBeenCalledWith(
    expect.objectContaining({ accountEnabled: true }),
    expect.objectContaining({ accountEnabled: false }),
  );
});

// electron/src/main/account/cloud-activity.test.ts
import { expect, it, vi } from 'vitest';
import { CloudActivity, CloudDisabledError } from './cloud-activity';

const origins = new Set(['https://voicestudio.sh']);

it('refuses every request while switched off, without touching the network', async () => {
  const fetchImpl = vi.fn();
  const activity = new CloudActivity({ isAllowed: () => false, origins, fetchImpl });
  await expect(activity.fetch('https://voicestudio.sh/x')).rejects.toBeInstanceOf(
    CloudDisabledError,
  );
  expect(fetchImpl).not.toHaveBeenCalled();
});

it('refuses origins outside the configured environment', async () => {
  const fetchImpl = vi.fn();
  const activity = new CloudActivity({ isAllowed: () => true, origins, fetchImpl });
  await expect(activity.fetch('https://evil.example/x')).rejects.toThrow(/origin/);
  expect(fetchImpl).not.toHaveBeenCalled();
});

it('stopAll aborts in-flight requests, cancels timers and runs stop hooks', async () => {
  let seen: AbortSignal | undefined;
  const fetchImpl = vi.fn(
    (_url: string, init: RequestInit) =>
      new Promise<Response>((_resolve, reject) => {
        seen = init.signal!;
        init.signal!.addEventListener('abort', () => reject(init.signal!.reason));
      }),
  );
  const activity = new CloudActivity({ isAllowed: () => true, origins, fetchImpl });
  const timer = vi.fn();
  const hook = vi.fn();
  vi.useFakeTimers();
  activity.setTimeout(timer, 1000);
  activity.onStop(hook);
  const pending = activity.fetch('https://voicestudio.sh/x');
  activity.stopAll();
  await expect(pending).rejects.toBeTruthy();
  vi.advanceTimersByTime(5000);
  vi.useRealTimers();
  expect(seen?.aborted).toBe(true);
  expect(timer).not.toHaveBeenCalled();
  expect(hook).toHaveBeenCalledOnce();
});

it('allows exactly one final call after stopAll (the revocation)', async () => {
  const fetchImpl = vi.fn(async () => new Response('{}'));
  let allowed = true;
  const activity = new CloudActivity({ isAllowed: () => allowed, origins, fetchImpl });
  allowed = false;
  activity.stopAll();
  await activity.fetch('https://voicestudio.sh/revoke', {}, { final: true });
  await expect(
    activity.fetch('https://voicestudio.sh/revoke', {}, { final: true }),
  ).rejects.toBeInstanceOf(CloudDisabledError);
  expect(fetchImpl).toHaveBeenCalledOnce();
});

it('never follows redirects', async () => {
  const fetchImpl = vi.fn(async () => new Response('{}'));
  const activity = new CloudActivity({ isAllowed: () => true, origins, fetchImpl });
  await activity.fetch('https://voicestudio.sh/x');
  expect(fetchImpl.mock.calls[0][1]).toMatchObject({ redirect: 'error' });
});

// electron/src/main/account/cloud-switches.ts
import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
import { dirname } from 'node:path';

/** Owner rule 2026-10-16: off by default; skipping setup means off; sync implies account. */
export interface CloudSwitches {
  accountEnabled: boolean;
  syncEnabled: boolean;
  prompted: boolean;
}

const OFF: CloudSwitches = { accountEnabled: false, syncEnabled: false, prompted: false };

function normalize(raw: Partial<CloudSwitches>): CloudSwitches {
  const accountEnabled = raw.accountEnabled === true;
  return {
    accountEnabled,
    syncEnabled: accountEnabled && raw.syncEnabled === true,
    prompted: raw.prompted === true,
  };
}

export class CloudSwitchStore {
  private value: CloudSwitches;
  private readonly listeners = new Set<(s: CloudSwitches, prev: CloudSwitches) => void>();

  constructor(private readonly path: string) {
    let raw: Partial<CloudSwitches> = OFF;
    try {
      raw = JSON.parse(readFileSync(path, 'utf8'));
    } catch {
      /* first run or corrupt: everything off */
    }
    this.value = normalize(raw ?? OFF);
  }

  get(): CloudSwitches {
    return { ...this.value };
  }

  set(patch: Partial<CloudSwitches>): CloudSwitches {
    const prev = this.value;
    this.value = normalize({ ...prev, ...patch });
    mkdirSync(dirname(this.path), { recursive: true, mode: 0o700 });
    const temporary = `${this.path}.${process.pid}.tmp`;
    writeFileSync(temporary, JSON.stringify(this.value), { encoding: 'utf8', mode: 0o600 });
    renameSync(temporary, this.path);
    for (const cb of this.listeners) cb(this.get(), { ...prev });
    return this.get();
  }

  subscribe(cb: (s: CloudSwitches, prev: CloudSwitches) => void): () => void {
    this.listeners.add(cb);
    return () => this.listeners.delete(cb);
  }
}

// electron/src/main/account/cloud-activity.ts
/**
 * The only door to VoiceStudio Cloud. Every request and timer goes through here,
 * so turning a switch off can stop all of them at once (owner rule 2026-10-16).
 */
export class CloudDisabledError extends Error {
  constructor() {
    super('VoiceStudio Cloud is switched off');
    this.name = 'CloudDisabledError';
  }
}

export class CloudActivity {
  private readonly controllers = new Set<AbortController>();
  private readonly timers = new Set<NodeJS.Timeout>();
  private readonly stopHooks = new Set<() => void>();
  private finalAvailable = false;
  private readonly fetchImpl: typeof fetch;

  constructor(
    private readonly opts: { isAllowed: () => boolean; origins: Set<string>; fetchImpl?: typeof fetch },
  ) {
    this.fetchImpl = opts.fetchImpl ?? fetch;
  }

  async fetch(
    url: string,
    init: RequestInit = {},
    opts: { final?: boolean; timeoutMs?: number } = {},
  ): Promise<Response> {
    if (!this.opts.isAllowed()) {
      if (!(opts.final && this.finalAvailable)) throw new CloudDisabledError();
      this.finalAvailable = false;
    }
    if (!this.opts.origins.has(new URL(url).origin))
      throw new Error('Refusing a request outside the VoiceStudio Cloud origin');
    const controller = new AbortController();
    this.controllers.add(controller);
    const timeout = setTimeout(() => controller.abort(new Error('timeout')), opts.timeoutMs ?? 30_000);
    try {
      return await this.fetchImpl(url, { ...init, redirect: 'error', signal: controller.signal });
    } finally {
      clearTimeout(timeout);
      this.controllers.delete(controller);
    }
  }

  setTimeout(fn: () => void, ms: number): void {
    if (!this.opts.isAllowed()) return;
    const timer = setTimeout(() => {
      this.timers.delete(timer);
      if (this.opts.isAllowed()) fn();
    }, ms);
    this.timers.add(timer);
  }

  onStop(fn: () => void): () => void {
    this.stopHooks.add(fn);
    return () => this.stopHooks.delete(fn);
  }

  /** Abort everything now. One `final` request (the revocation) stays possible. */
  stopAll(): void {
    for (const c of this.controllers) c.abort(new CloudDisabledError());
    this.controllers.clear();
    for (const t of this.timers) clearTimeout(t);
    this.timers.clear();
    for (const hook of [...this.stopHooks]) hook();
    this.finalAvailable = true;
  }
}

git add electron/src/main/account/cloud-switches.* electron/src/main/account/cloud-activity.*
git commit -m "feat(account): persisted cloud switches and a single activity gate"

// electron/src/main/account/oidc.test.ts
import { createHash } from 'node:crypto';
import { expect, it, vi } from 'vitest';
import { CloudActivity } from './cloud-activity';
import { cloudOrigins, resolveCloudEnvironment } from './cloud-config';
import { InvalidGrantError, OidcClient, TransientAuthError, base64url, createPkce } from './oidc';

const env = resolveCloudEnvironment({ packaged: true });
const discovery = {
  issuer: env.issuer,
  authorization_endpoint: `${env.issuer}/protocol/openid-connect/auth`,
  token_endpoint: `${env.issuer}/protocol/openid-connect/token`,
  revocation_endpoint: `${env.issuer}/protocol/openid-connect/revoke`,
};
const json = (body: unknown, status = 200) =>
  new Response(JSON.stringify(body), { status, headers: { 'content-type': 'application/json' } });
const client = (fetchImpl: typeof fetch, now = () => 0) =>
  new OidcClient(
    env,
    new CloudActivity({ isAllowed: () => true, origins: cloudOrigins(env), fetchImpl }),
    now,
  );

it('PKCE challenge is base64url(SHA-256(verifier)) with spec lengths', () => {
  const p = createPkce();
  expect(p.challenge).toBe(base64url(createHash('sha256').update(p.verifier).digest()));
  expect(Buffer.from(p.verifier, 'base64url')).toHaveLength(64);
  expect(Buffer.from(p.state, 'base64url')).toHaveLength(32);
  expect(p.verifier).not.toMatch(/[+/=]/);
});

it('refuses a discovery document for another issuer', async () => {
  const c = client(vi.fn(async () => json({ ...discovery, issuer: 'https://evil.example' })));
  await expect(c.discover()).rejects.toThrow(/issuer/);
});

it('caches discovery for 24 hours', async () => {
  let t = 0;
  const fetchImpl = vi.fn(async () => json(discovery));
  const c = client(fetchImpl, () => t);
  await c.discover();
  t = 23 * 3600_000;
  await c.discover();
  expect(fetchImpl).toHaveBeenCalledTimes(1);
  t = 25 * 3600_000;
  await c.discover();
  expect(fetchImpl).toHaveBeenCalledTimes(2);
});

it('builds the authorize URL from the contract', () => {
  const url = new URL(
    client(vi.fn()).authorizeUrl(discovery, 'http://127.0.0.1:5000/callback', {
      state: 's',
      challenge: 'c',
    }),
  );
  expect(Object.fromEntries(url.searchParams)).toEqual({
    client_id: 'voicestudio-desktop-oss',
    response_type: 'code',
    redirect_uri: 'http://127.0.0.1:5000/callback',
    scope: 'openid offline_access',
    state: 's',
    code_challenge: 'c',
    code_challenge_method: 'S256',
  });
});

it('rejects a token response without offline_access', async () => {
  const fetchImpl = vi.fn(async (u: string) =>
    u.endsWith('openid-configuration')
      ? json(discovery)
      : json({ access_token: 'a', refresh_token: 'r', expires_in: 300, scope: 'openid' }),
  );
  await expect(client(fetchImpl).exchangeCode('c', 'http://127.0.0.1:1/callback', 'v')).rejects.toThrow(
    /offline_access/,
  );
});

it('maps refresh errors: invalid_grant vs transient', async () => {
  const respond = (r: Response) =>
    vi.fn(async (u: string) => (u.endsWith('openid-configuration') ? json(discovery) : r));
  await expect(client(respond(json({ error: 'invalid_grant' }, 400))).refresh('r')).rejects.toBeInstanceOf(
    InvalidGrantError,
  );
  await expect(client(respond(json({}, 503))).refresh('r')).rejects.toBeInstanceOf(TransientAuthError);
});

it('sends form-encoded refresh with the public client id and no secret', async () => {
  const fetchImpl = vi.fn(async (u: string, _init?: RequestInit) =>
    u.endsWith('openid-configuration')
      ? json(discovery)
      : json({ access_token: 'a', refresh_token: 'r2', expires_in: 300, scope: 'openid offline_access' }),
  );
  await client(fetchImpl).refresh('r1');
  const body = new URLSearchParams(String(fetchImpl.mock.calls[1][1]!.body));
  expect(Object.fromEntries(body)).toEqual({
    grant_type: 'refresh_token',
    client_id: 'voicestudio-desktop-oss',
    refresh_token: 'r1',
  });
});

// electron/src/main/account/oidc.ts
import { createHash, randomBytes } from 'node:crypto';
import type { CloudActivity } from './cloud-activity';
import type { CloudEnvironment } from './cloud-config';

export interface OidcEndpoints {
  authorization_endpoint: string;
  token_endpoint: string;
  revocation_endpoint: string;
}

export interface TokenResponse {
  access_token: string;
  expires_in: number;
  refresh_token: string;
  scope: string;
}

export class InvalidGrantError extends Error {
  constructor() {
    super('The VoiceStudio Cloud session ended');
    this.name = 'InvalidGrantError';
  }
}

export class TransientAuthError extends Error {
  constructor(status?: number) {
    super(`VoiceStudio Cloud sign-in is unavailable${status ? ` (${status})` : ''}`);
    this.name = 'TransientAuthError';
  }
}

export const base64url = (buf: Buffer): string => buf.toString('base64url');
export const challengeFor = (verifier: string): string =>
  base64url(createHash('sha256').update(verifier).digest());

export function createPkce(): { state: string; verifier: string; challenge: string } {
  const verifier = base64url(randomBytes(64));
  return { state: base64url(randomBytes(32)), verifier, challenge: challengeFor(verifier) };
}

const DISCOVERY_TTL_MS = 24 * 3600_000;

export class OidcClient {
  private cached: { at: number; endpoints: OidcEndpoints } | null = null;

  constructor(
    private readonly env: CloudEnvironment,
    private readonly activity: CloudActivity,
    private readonly now: () => number = Date.now,
  ) {}

  async discover(): Promise<OidcEndpoints> {
    if (this.cached && this.now() - this.cached.at < DISCOVERY_TTL_MS) return this.cached.endpoints;
    const res = await this.activity.fetch(`${this.env.issuer}/.well-known/openid-configuration`);
    if (!res.ok) throw new TransientAuthError(res.status);
    const doc = (await res.json()) as Partial<OidcEndpoints> & { issuer?: string };
    if (doc.issuer !== this.env.issuer) throw new Error('Discovery issuer does not match');
    const endpoints = {
      authorization_endpoint: String(doc.authorization_endpoint),
      token_endpoint: String(doc.token_endpoint),
      revocation_endpoint: String(doc.revocation_endpoint),
    };
    this.cached = { at: this.now(), endpoints };
    return endpoints;
  }

  authorizeUrl(e: OidcEndpoints, redirectUri: string, p: { state: string; challenge: string }): string {
    const url = new URL(e.authorization_endpoint);
    url.search = new URLSearchParams({
      client_id: this.env.clientId,
      response_type: 'code',
      redirect_uri: redirectUri,
      scope: 'openid offline_access',
      state: p.state,
      code_challenge: p.challenge,
      code_challenge_method: 'S256',
    }).toString();
    return url.toString();
  }

  exchangeCode(code: string, redirectUri: string, verifier: string): Promise<TokenResponse> {
    return this.token({
      grant_type: 'authorization_code',
      client_id: this.env.clientId,
      code,
      redirect_uri: redirectUri,
      code_verifier: verifier,
    });
  }

  refresh(refreshToken: string): Promise<TokenResponse> {
    return this.token({
      grant_type: 'refresh_token',
      client_id: this.env.clientId,
      refresh_token: refreshToken,
    });
  }

  /** Best effort; the caller deletes the stored token whatever happens. */
  async revoke(refreshToken: string): Promise<void> {
    const { revocation_endpoint } = await this.discover();
    await this.activity.fetch(
      revocation_endpoint,
      this.form({ client_id: this.env.clientId, token: refreshToken, token_type_hint: 'refresh_token' }),
      { final: true, timeoutMs: 5_000 },
    );
  }

  private form(fields: Record<string, string>): RequestInit {
    return {
      method: 'POST',
      headers: { 'content-type': 'application/x-www-form-urlencoded' },
      body: new URLSearchParams(fields).toString(),
    };
  }

  private async token(fields: Record<string, string>): Promise<TokenResponse> {
    const { token_endpoint } = await this.discover();
    let res: Response;
    try {
      res = await this.activity.fetch(token_endpoint, this.form(fields));
    } catch (error) {
      if ((error as Error).name === 'CloudDisabledError') throw error;
      throw new TransientAuthError();
    }
    const body = (await res.json().catch(() => ({}))) as Partial<TokenResponse> & { error?: string };
    if (res.status === 400 && body.error === 'invalid_grant') throw new InvalidGrantError();
    if (!res.ok) throw new TransientAuthError(res.status);
    if (!String(body.scope ?? '').split(' ').includes('offline_access'))
      throw new Error('Token response lacks offline_access');
    return body as TokenResponse;
  }
}

git add electron/src/main/account/oidc.*
git commit -m "feat(account): OIDC discovery, PKCE and token requests"

// electron/src/main/account/loopback.test.ts
import { expect, it } from 'vitest';
import { LoopbackError, startLoopback } from './loopback';

const page = 'https://app.voicestudio.sh/app/desktop-signed-in';
const hit = (uri: string, query: string) =>
  fetch(uri + query, { redirect: 'manual' }).then((r) => ({ status: r.status, location: r.headers.get('location') }));

it('binds only 127.0.0.1 on a random port', async () => {
  const lb = await startLoopback({ expectedState: 's', signedInPage: page });
  expect(lb.redirectUri).toMatch(/^http:\/\/127\.0\.0\.1:\d+\/callback$/);
  lb.close();
  await expect(lb.code).rejects.toBeInstanceOf(LoopbackError);
});

it('refuses a wrong state and keeps waiting for the right one', async () => {
  const lb = await startLoopback({ expectedState: 'good', signedInPage: page });
  expect((await hit(lb.redirectUri, '?code=x&state=bad')).status).toBe(400);
  const ok = await hit(lb.redirectUri, '?code=real&state=good');
  expect(ok).toEqual({ status: 302, location: page });
  await expect(lb.code).resolves.toBe('real');
});

it('answers 404 off the callback path', async () => {
  const lb = await startLoopback({ expectedState: 's', signedInPage: page });
  expect((await hit(lb.redirectUri.replace('/callback', '/other'), '?state=s&code=c')).status).toBe(404);
  lb.close();
  await lb.code.catch(() => {});
});

it('reports a denied sign-in', async () => {
  const lb = await startLoopback({ expectedState: 's', signedInPage: page });
  await hit(lb.redirectUri, '?error=access_denied&state=s');
  await expect(lb.code).rejects.toMatchObject({ reason: 'denied' });
});

it('times out', async () => {
  const lb = await startLoopback({ expectedState: 's', signedInPage: page, timeoutMs: 50 });
  await expect(lb.code).rejects.toMatchObject({ reason: 'timeout' });
});

it('refuses connections once closed', async () => {
  const lb = await startLoopback({ expectedState: 's', signedInPage: page });
  lb.close();
  await lb.code.catch(() => {});
  await expect(hit(lb.redirectUri, '?code=c&state=s')).rejects.toBeTruthy();
});

// electron/src/main/account/loopback.ts
import { createServer } from 'node:http';
import type { AddressInfo } from 'node:net';
import { timingSafeEqual } from 'node:crypto';

export class LoopbackError extends Error {
  constructor(readonly reason: 'denied' | 'timeout' | 'closed') {
    super(`Sign-in ${reason}`);
    this.name = 'LoopbackError';
  }
}

const sameState = (a: string, b: string) =>
  a.length === b.length && timingSafeEqual(Buffer.from(a), Buffer.from(b));

/** RFC 8252 loopback receiver: one /callback within the timeout, then gone. */
export async function startLoopback(opts: {
  expectedState: string;
  signedInPage: string;
  timeoutMs?: number;
}): Promise<{ redirectUri: string; code: Promise<string>; close(): void }> {
  let settle!: (result: { code?: string; error?: LoopbackError }) => void;
  const outcome = new Promise<{ code?: string; error?: LoopbackError }>((r) => (settle = r));
  let done = false;
  const server = createServer((req, res) => {
    const url = new URL(req.url ?? '/', 'http://127.0.0.1');
    if (done || req.method !== 'GET' || url.pathname !== '/callback') {
      res.writeHead(404).end();
      return;
    }
    if (!sameState(url.searchParams.get('state') ?? '', opts.expectedState)) {
      res.writeHead(400).end();
      return;
    }
    const code = url.searchParams.get('code');
    finish(url.searchParams.has('error') || !code ? { error: new LoopbackError('denied') } : { code });
    res.writeHead(302, { location: opts.signedInPage, connection: 'close' }).end();
  });
  const timer = setTimeout(() => finish({ error: new LoopbackError('timeout') }), opts.timeoutMs ?? 300_000);
  function finish(result: { code?: string; error?: LoopbackError }) {
    if (done) return;
    done = true;
    clearTimeout(timer);
    server.close();
    server.closeAllConnections?.();
    settle(result);
  }
  await new Promise<void>((resolve, reject) => {
    server.once('error', reject);
    server.listen(0, '127.0.0.1', () => resolve());
  });
  const { port } = server.address() as AddressInfo;
  return {
    redirectUri: `http://127.0.0.1:${port}/callback`,
    code: outcome.then((r) => (r.error ? Promise.reject(r.error) : (r.code as string))),
    close: () => finish({ error: new LoopbackError('closed') }),
  };
}

git add electron/src/main/account/loopback.*
git commit -m "feat(account): one-shot 127.0.0.1 OAuth callback listener"

// electron/src/main/account/token-store.test.ts
import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
import { expect, it } from 'vitest';
import { RefreshTokenStore, type SafeStorageLike } from './token-store';

const fakeSafe = (over: Partial<SafeStorageLike> = {}): SafeStorageLike => ({
  isEncryptionAvailable: () => true,
  getSelectedStorageBackend: () => 'gnome_libsecret',
  encryptString: (s) => Buffer.from(`enc:${s}`),
  decryptString: (b) => b.toString().replace(/^enc:/, ''),
  ...over,
});
const path = () => join(mkdtempSync(join(tmpdir(), 'vs-token-')), 'account.json');

it('round-trips through safeStorage and never writes the token in clear', () => {
  const p = path();
  new RefreshTokenStore(p, fakeSafe(), 'darwin').save('secret-refresh');
  expect(readFileSync(p, 'utf8')).not.toContain('secret-refresh');
  expect(new RefreshTokenStore(p, fakeSafe(), 'darwin').load()).toBe('secret-refresh');
});

it('basic_text on Linux keeps the token in memory only', () => {
  const p = path();
  const store = new RefreshTokenStore(p, fakeSafe({ getSelectedStorageBackend: () => 'basic_text' }), 'linux');
  store.save('t');
  expect(store.persistent).toBe(false);
  expect(existsSync(p)).toBe(false);
  expect(store.load()).toBe('t');
});

it('no encryption available keeps it in memory only', () => {
  const store = new RefreshTokenStore(path(), fakeSafe({ isEncryptionAvailable: () => false }), 'win32');
  expect(store.persistent).toBe(false);
});

it('a corrupt or undecryptable file loads as signed out', () => {
  const p = path();
  writeFileSync(p, '{"v":1,"token":"@@@');
  expect(new RefreshTokenStore(p, fakeSafe(), 'darwin').load()).toBeNull();
  writeFileSync(p, JSON.stringify({ v: 1, token: 'AAAA' }));
  const throwing = fakeSafe({ decryptString: () => { throw new Error('keychain changed'); } });
  expect(new RefreshTokenStore(p, throwing, 'darwin').load()).toBeNull();
});

it('clear removes the file and the memory copy', () => {
  const p = path();
  const store = new RefreshTokenStore(p, fakeSafe(), 'darwin');
  store.save('t');
  store.clear();
  expect(existsSync(p)).toBe(false);
  expect(store.load()).toBeNull();
});