@topolo/sdk 0.6.0 → 0.8.0

package/src/node/credential-store.test.ts

@@ -0,0 +1,337 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { readConfig, refreshCredentialIfNeeded, writeConfig } from './credential-store.js';
+import {
+  activateContext,
+  clearProfileCredential,
+  configPath,
+  contextKey,
+  credentialSourceFromConfig,
+  envVarPrefix,
+  normalizeEnvironment,
+  profileForEnvironment,
+  resolveAgentName,
+  resolveCredential,
+  resolvedProfileConfig,
+  resolveServiceUrls,
+  selectedEnvironment,
+  writeContextCredential,
+  writeProfileConfig,
+} from './credential-store.js';
+
+const originalEnv = { ...process.env };
+const originalFetch = globalThis.fetch;
+let tempDirectory: string;
+
+beforeEach(async () => {
+  tempDirectory = await mkdtemp(join(tmpdir(), 'topolo-sdk-credential-'));
+  process.env = { ...originalEnv, TOPOLO_CONFIG_PATH: join(tempDirectory, 'config.json') };
+  delete process.env.TOPOLO_API_KEY;
+  delete process.env.TOPOLO_ACCESS_TOKEN;
+  delete process.env.TOPOLO_ENV;
+  delete process.env.TOPOLO_AGENT_NAME;
+  delete process.env.TOPOLO_PRODUCTION_API_KEY;
+  delete process.env.TOPOLO_PRODUCTION_ACCESS_TOKEN;
+  delete process.env.TOPOLO_STAGING_API_KEY;
+  delete process.env.TOPOLO_STAGING_ACCESS_TOKEN;
+  for (const key of Object.keys(process.env)) {
+    if (key.startsWith('TOPOLO_SERVICE_URL_') || key.startsWith('TOPOLO_STAGING_SERVICE_URL_')) {
+      delete process.env[key];
+    }
+  }
+});
+
+describe('credential configuration primitives', () => {
+  it('normalizes environment aliases and rejects unknown values', () => {
+    expect(normalizeEnvironment(undefined)).toBe('production');
+    expect(normalizeEnvironment('  ')).toBe('production');
+    expect(normalizeEnvironment('PROD')).toBe('production');
+    expect(normalizeEnvironment('stage')).toBe('staging');
+    expect(normalizeEnvironment('stg')).toBe('staging');
+    expect(normalizeEnvironment('dev')).toBe('development');
+    expect(normalizeEnvironment('localhost')).toBe('local');
+    expect(() => normalizeEnvironment('preview')).toThrow(/Unknown Topolo environment/);
+
+    process.env.TOPOLO_ENV = 'staging';
+    expect(selectedEnvironment()).toBe('staging');
+    expect(envVarPrefix('production')).toBe('TOPOLO_PRODUCTION');
+    expect(envVarPrefix('staging')).toBe('TOPOLO_STAGING');
+    expect(envVarPrefix('development')).toBe('TOPOLO_DEVELOPMENT');
+    expect(envVarPrefix('local')).toBe('TOPOLO_LOCAL');
+  });
+
+  it('uses the explicit config path and safely reads missing or malformed config', async () => {
+    expect(configPath()).toBe(join(tempDirectory, 'config.json'));
+    expect(await readConfig()).toEqual({});
+    await import('node:fs/promises').then(({ writeFile }) => writeFile(configPath(), '{bad json'));
+    expect(await readConfig()).toEqual({});
+  });
+
+  it('merges legacy production fields with profiles and writes environment profiles', () => {
+    const config = {
+      credential: { kind: 'api_key' as const, apiKey: 'legacy' },
+      oauthClientId: 'legacy-client',
+      serviceUrls: { auth: 'https://legacy-auth', developers: 'https://legacy-dev' },
+      agentName: 'legacy-agent',
+      profiles: {
+        production: {
+          serviceUrls: { auth: 'https://profile-auth' },
+          agentName: 'profile-agent',
+        },
+        staging: { agentName: 'staging-agent' },
+      },
+    };
+    expect(profileForEnvironment(config, 'production')).toMatchObject({
+      credential: config.credential,
+      oauthClientId: 'legacy-client',
+      serviceUrls: { auth: 'https://profile-auth', developers: 'https://legacy-dev' },
+      agentName: 'profile-agent',
+    });
+    expect(profileForEnvironment(config, 'staging')).toEqual({ agentName: 'staging-agent' });
+    expect(writeProfileConfig(config, 'staging', { oauthClientId: 'new-client' }).profiles?.staging)
+      .toEqual({ agentName: 'staging-agent', oauthClientId: 'new-client' });
+  });
+
+  it('stores, activates, and clears personal and organization contexts', () => {
+    expect(contextKey('personal')).toBe('personal');
+    expect(contextKey('organization', 'org_1')).toBe('org:org_1');
+    expect(contextKey('organization')).toBe('personal');
+
+    const organization = {
+      contextType: 'organization' as const,
+      organizationId: 'org_1',
+      oauthClientId: 'context-client',
+      credential: { kind: 'access_token' as const, accessToken: 'org-token' },
+    };
+    const stored = writeContextCredential({}, 'staging', organization);
+    expect(stored.profiles?.staging).toMatchObject({
+      activeContext: 'org:org_1',
+      credential: organization.credential,
+      oauthClientId: 'context-client',
+    });
+
+    const inactive = writeContextCredential(stored, 'staging', {
+      contextType: 'personal',
+      credential: { kind: 'access_token', accessToken: 'personal-token' },
+    }, false);
+    expect(inactive.profiles?.staging?.activeContext).toBe('org:org_1');
+    const activated = activateContext(inactive, 'staging', 'personal');
+    expect(activated.profiles?.staging?.credential).toMatchObject({ accessToken: 'personal-token' });
+    expect(activateContext(activated, 'staging', 'missing')).toBe(activated);
+
+    const production = clearProfileCredential({
+      credential: { kind: 'api_key', apiKey: 'legacy' },
+      oauthClientId: 'client',
+      profiles: { production: { credential: organization.credential, oauthClientId: 'profile' } },
+    }, 'production');
+    expect(production.credential).toBeUndefined();
+    expect(production.oauthClientId).toBeUndefined();
+    expect(production.profiles?.production?.credential).toBeUndefined();
+    expect(clearProfileCredential(stored, 'staging').profiles?.staging?.credential).toBeUndefined();
+  });
+});
+
+describe('credential and service resolution', () => {
+  it('reports credential source precedence and resolves environment credentials', async () => {
+    const config = { credential: { kind: 'api_key' as const, apiKey: 'stored' } };
+    expect(credentialSourceFromConfig(config, 'production')).toBe('config-file');
+    process.env.TOPOLO_ACCESS_TOKEN = 'global-access';
+    expect(credentialSourceFromConfig(config, 'production')).toBe('env:TOPOLO_ACCESS_TOKEN');
+    expect(await resolveCredential('production')).toEqual({ kind: 'access_token', accessToken: 'global-access' });
+    process.env.TOPOLO_API_KEY = 'global-key';
+    expect(credentialSourceFromConfig(config, 'production')).toBe('env:TOPOLO_API_KEY');
+    expect(await resolveCredential('production')).toEqual({ kind: 'api_key', apiKey: 'global-key' });
+    process.env.TOPOLO_PRODUCTION_ACCESS_TOKEN = 'scoped-access';
+    expect(credentialSourceFromConfig(config, 'production')).toBe('env:TOPOLO_PRODUCTION_ACCESS_TOKEN');
+    process.env.TOPOLO_PRODUCTION_API_KEY = 'scoped-key';
+    expect(credentialSourceFromConfig(config, 'production')).toBe('env:TOPOLO_PRODUCTION_API_KEY');
+    expect(await resolveCredential('production')).toEqual({ kind: 'api_key', apiKey: 'scoped-key' });
+  });
+
+  it('falls back to stored credentials or none', async () => {
+    expect(credentialSourceFromConfig({}, 'staging')).toBe('none');
+    expect(await resolveCredential('staging')).toBeNull();
+    await writeConfig({ profiles: { staging: { credential: { kind: 'api_key', apiKey: 'stored' } } } });
+    expect(await resolveCredential('staging')).toEqual({ kind: 'api_key', apiKey: 'stored' });
+  });
+
+  it('merges defaults, config, scoped env, and global env in precedence order', () => {
+    process.env.TOPOLO_STAGING_SERVICE_URL_AUTH = 'https://scoped-auth';
+    process.env.TOPOLO_SERVICE_URL_AUTH = 'https://global-auth';
+    process.env.TOPOLO_SERVICE_URL_CUSTOM = 'https://custom';
+    expect(resolveServiceUrls({ auth: 'https://config-auth' }, 'staging')).toMatchObject({
+      auth: 'https://global-auth',
+      developers: 'https://developers.stg.topolo.us',
+      seed: 'https://seed.stg.topolo.us',
+      custom: 'https://custom',
+    });
+    delete process.env.TOPOLO_STAGING_SERVICE_URL_AUTH;
+    delete process.env.TOPOLO_SERVICE_URL_AUTH;
+    delete process.env.TOPOLO_SERVICE_URL_CUSTOM;
+    expect(resolveServiceUrls(undefined, 'local')).toBeUndefined();
+  });
+
+  it('resolves agent and complete profile settings', () => {
+    expect(resolveAgentName('config-agent')).toBe('config-agent');
+    process.env.TOPOLO_AGENT_NAME = 'env-agent';
+    expect(resolveAgentName('config-agent')).toBe('env-agent');
+    const resolved = resolvedProfileConfig({
+      profiles: {
+        staging: {
+          oauthClientId: 'client',
+          credential: { kind: 'api_key', apiKey: 'stored' },
+          agentName: 'profile-agent',
+          serviceUrls: { auth: 'https://custom-auth' },
+        },
+      },
+    }, 'staging');
+    expect(resolved).toMatchObject({
+      oauthClientId: 'client',
+      credential: { kind: 'api_key', apiKey: 'stored' },
+      agentName: 'profile-agent',
+      serviceUrls: { auth: 'https://custom-auth' },
+    });
+  });
+});
+
+afterEach(async () => {
+  process.env = { ...originalEnv };
+  globalThis.fetch = originalFetch;
+  await rm(tempDirectory, { recursive: true, force: true });
+});
+
+describe('refreshCredentialIfNeeded force mode', () => {
+  it('refreshes a stored token after a 401 even when its expiry is still in the future', async () => {
+    await writeConfig({
+      credential: {
+        kind: 'access_token',
+        accessToken: 'rejected',
+        refreshToken: 'refresh',
+        expiresAt: Math.floor(Date.now() / 1000) + 10_000,
+      },
+      oauthClientId: 'topolo-cli',
+    });
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      access_token: 'fresh',
+      token_type: 'Bearer',
+      expires_in: 3600,
+    }), { status: 200, headers: { 'Content-Type': 'application/json' } })) as unknown as typeof fetch;
+
+    const credential = await refreshCredentialIfNeeded('production', { force: true });
+
+    expect(credential).toMatchObject({ accessToken: 'fresh', refreshToken: 'refresh' });
+    expect(globalThis.fetch).toHaveBeenCalledTimes(1);
+  });
+
+  it('rotates the active context credential as well as the profile pointer', async () => {
+    await writeConfig({
+      profiles: {
+        staging: {
+          activeContext: 'org:org_a',
+          oauthClientId: 'topolo-cli',
+          credential: {
+            kind: 'access_token',
+            accessToken: 'old-a',
+            refreshToken: 'refresh-a',
+            expiresAt: 1,
+          },
+          contexts: {
+            'org:org_a': {
+              contextType: 'organization',
+              organizationId: 'org_a',
+              credential: {
+                kind: 'access_token',
+                accessToken: 'old-a',
+                refreshToken: 'refresh-a',
+                expiresAt: 1,
+              },
+            },
+            'org:org_b': {
+              contextType: 'organization',
+              organizationId: 'org_b',
+              credential: {
+                kind: 'access_token',
+                accessToken: 'untouched-b',
+                refreshToken: 'refresh-b',
+                expiresAt: 2,
+              },
+            },
+          },
+        },
+      },
+    });
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      access_token: 'fresh-a',
+      token_type: 'Bearer',
+      expires_in: 3600,
+      refresh_token: 'rotated-a',
+    }), { status: 200, headers: { 'Content-Type': 'application/json' } })) as unknown as typeof fetch;
+
+    await refreshCredentialIfNeeded('staging');
+
+    const profile = (await readConfig()).profiles?.staging;
+    expect(profile?.credential).toMatchObject({ accessToken: 'fresh-a', refreshToken: 'rotated-a' });
+    expect(profile?.contexts?.['org:org_a']?.credential).toMatchObject({
+      accessToken: 'fresh-a',
+      refreshToken: 'rotated-a',
+    });
+    expect(profile?.contexts?.['org:org_b']?.credential).toMatchObject({
+      accessToken: 'untouched-b',
+      refreshToken: 'refresh-b',
+    });
+  });
+
+  it('uses environment credentials and skips ineligible or unexpired stored credentials', async () => {
+    process.env.TOPOLO_STAGING_API_KEY = 'env-key';
+    expect(await refreshCredentialIfNeeded('staging')).toEqual({ kind: 'api_key', apiKey: 'env-key' });
+    delete process.env.TOPOLO_STAGING_API_KEY;
+    expect(await refreshCredentialIfNeeded('staging')).toBeNull();
+
+    await writeConfig({ profiles: { staging: { credential: { kind: 'api_key', apiKey: 'stored' } } } });
+    expect(await refreshCredentialIfNeeded('staging')).toEqual({ kind: 'api_key', apiKey: 'stored' });
+
+    const access = { kind: 'access_token' as const, accessToken: 'fresh', expiresAt: Math.floor(Date.now() / 1000) + 10_000 };
+    await writeConfig({ profiles: { staging: { credential: access, oauthClientId: 'client' } } });
+    expect(await refreshCredentialIfNeeded('staging')).toEqual(access);
+  });
+
+  it('returns the existing credential when refresh inputs are incomplete or exchange fails', async () => {
+    const withoutRefresh = { kind: 'access_token' as const, accessToken: 'token', expiresAt: 1 };
+    await writeConfig({ profiles: { staging: { credential: withoutRefresh, oauthClientId: 'client' } } });
+    expect(await refreshCredentialIfNeeded('staging')).toEqual(withoutRefresh);
+
+    const expired = { ...withoutRefresh, refreshToken: 'refresh' };
+    await writeConfig({ profiles: { staging: { credential: expired, oauthClientId: 'client' } } });
+    globalThis.fetch = vi.fn(async () => new Response('unavailable', { status: 503 })) as unknown as typeof fetch;
+    expect(await refreshCredentialIfNeeded('staging')).toEqual(expired);
+  });
+
+  it('persists refreshed credentials into an explicit production profile', async () => {
+    await writeConfig({
+      credential: { kind: 'api_key', apiKey: 'legacy' },
+      profiles: {
+        production: {
+          oauthClientId: 'client',
+          credential: { kind: 'access_token', accessToken: 'old', refreshToken: 'refresh', expiresAt: 1 },
+        },
+      },
+    });
+    globalThis.fetch = vi.fn(async () => new Response(JSON.stringify({
+      access_token: 'profile-fresh',
+      token_type: 'Bearer',
+      expires_in: 1200,
+      refresh_token: 'profile-refresh',
+    }), { status: 200, headers: { 'Content-Type': 'application/json' } })) as unknown as typeof fetch;
+
+    await refreshCredentialIfNeeded('production');
+
+    const config = await readConfig();
+    expect(config.credential).toEqual({ kind: 'api_key', apiKey: 'legacy' });
+    expect(config.profiles?.production?.credential).toMatchObject({
+      accessToken: 'profile-fresh',
+      refreshToken: 'profile-refresh',
+    });
+  });
+});

package/src/node/credential-store.ts

@@ -38,6 +38,34 @@ export interface TopoloEnvironmentProfile {
   oauthClientId?: string;
   serviceUrls?: Record<string, string>;
   agentName?: string;
+  /**
+   * The context (`personal` or `org:<orgId>`) whose credential is currently
+   * active. `credential` above always mirrors `contexts[activeContext]`, so
+   * credential resolution + the MCP keep working unchanged while `contexts`
+   * lets the CLI hold and switch between multiple org/personal contexts.
+   */
+  activeContext?: string;
+  contexts?: Record<string, TopoloContextCredential>;
+}
+
+/** A signed-in context — personal, or a specific organization. */
+export interface TopoloContextCredential {
+  contextType: 'personal' | 'organization';
+  organizationId?: string;
+  organizationSlug?: string;
+  organizationName?: string;
+  credential?: TopoloCredential;
+  oauthClientId?: string;
+}
+
+/** Stable key for a context within a profile's `contexts` map. */
+export function contextKey(
+  contextType: 'personal' | 'organization',
+  organizationId?: string | null,
+): string {
+  return contextType === 'organization' && organizationId
+    ? `org:${organizationId}`
+    : 'personal';
 }
 
 /**
@@ -161,6 +189,45 @@ export function writeProfileConfig(
   return { ...config, profiles };
 }
 
+/**
+ * Store a context's credential in the profile's `contexts` map. When
+ * `makeActive` (default), also point the profile's active credential at it so
+ * credential resolution + the MCP use this context.
+ */
+export function writeContextCredential(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+  ctx: TopoloContextCredential,
+  makeActive = true,
+): TopoloConfig {
+  const key = contextKey(ctx.contextType, ctx.organizationId);
+  const profile = profileForEnvironment(config, environment);
+  const contexts = { ...(profile.contexts ?? {}), [key]: ctx };
+  const next: TopoloEnvironmentProfile = { contexts };
+  if (makeActive) {
+    next.activeContext = key;
+    next.credential = ctx.credential;
+    next.oauthClientId = ctx.oauthClientId ?? profile.oauthClientId;
+  }
+  return writeProfileConfig(config, environment, next);
+}
+
+/** Point the profile's active credential at an already-stored context. */
+export function activateContext(
+  config: TopoloConfig,
+  environment: TopoloEnvironment,
+  key: string,
+): TopoloConfig {
+  const profile = profileForEnvironment(config, environment);
+  const ctx = profile.contexts?.[key];
+  if (!ctx) return config;
+  return writeProfileConfig(config, environment, {
+    activeContext: key,
+    credential: ctx.credential,
+    oauthClientId: ctx.oauthClientId ?? profile.oauthClientId,
+  });
+}
+
 export function clearProfileCredential(
   config: TopoloConfig,
   environment: TopoloEnvironment,
@@ -220,6 +287,7 @@ const REFRESH_SKEW_SECONDS = 60;
 
 export async function refreshCredentialIfNeeded(
   environment: TopoloEnvironment = selectedEnvironment(),
+  options: { force?: boolean } = {},
 ): Promise<TopoloCredential | null> {
   const prefix = envVarPrefix(environment);
   if (
@@ -238,7 +306,7 @@ export async function refreshCredentialIfNeeded(
   if (!cred.refreshToken || !cred.expiresAt || !profile.oauthClientId) return cred;
 
   const now = Math.floor(Date.now() / 1000);
-  if (cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
+  if (!options.force && cred.expiresAt - REFRESH_SKEW_SECONDS > now) return cred;
 
   try {
     const oauth = new TopoloOAuth({
@@ -258,11 +326,24 @@ export async function refreshCredentialIfNeeded(
         : { refreshToken: cred.refreshToken }),
       expiresAt: Math.floor(Date.now() / 1000) + tokens.expires_in,
     };
-    await writeConfig(
-      environment === 'production' && !config.profiles?.production
+    const activeContext = profile.activeContext;
+    const activeEntry = activeContext ? profile.contexts?.[activeContext] : undefined;
+    const updated = activeContext && activeEntry
+      ? writeProfileConfig(config, environment, {
+          credential: refreshed,
+          contexts: {
+            ...(profile.contexts ?? {}),
+            [activeContext]: {
+              ...activeEntry,
+              credential: refreshed,
+              oauthClientId: activeEntry.oauthClientId ?? profile.oauthClientId,
+            },
+          },
+        })
+      : environment === 'production' && !config.profiles?.production
         ? { ...config, credential: refreshed }
-        : writeProfileConfig(config, environment, { credential: refreshed }),
-    );
+        : writeProfileConfig(config, environment, { credential: refreshed });
+    await writeConfig(updated);
     return refreshed;
   } catch {
     return cred;