@topolo/sdk 0.7.0 → 0.8.1

package/src/node/credential-store.ts

@@ -1,378 +0,0 @@
-import { mkdir, readFile, writeFile, chmod } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
-import { homedir, platform } from 'node:os';
-import { dirname, join } from 'node:path';
-import { TopoloOAuth } from '../oauth.js';
-import type { TopoloCredential } from '../auth.js';
-
-/**
- * Node-only credential store shared by the `topolo` CLI and `@topolo/mcp`.
- *
- * Both need to read (and refresh) the credential that `topolo auth login`
- * writes to `$XDG_CONFIG_HOME/topolo/config.json`. This lives in a Node-only
- * subpath (`@topolo/sdk/node`) so the isomorphic SDK core never imports
- * `node:fs` — importing this module in a browser/worker bundle is a mistake.
- *
- * The CLI re-exports every symbol here from `packages/topolo-cli/src/config.ts`
- * so existing call sites are unchanged; the MCP imports it directly to fall
- * back to the on-disk credential when no `TOPOLO_*` env credential is set.
- */
-
-export const TOPOLO_ENVIRONMENTS = ['production', 'staging', 'development', 'local'] as const;
-export type TopoloEnvironment = (typeof TOPOLO_ENVIRONMENTS)[number];
-
-export interface TopoloConfig {
-  credential?: TopoloCredential;
-  /** OAuth client_id used for the most recent login — needed to refresh the access token. */
-  oauthClientId?: string;
-  /** Per-service URL overrides — written when user runs `topolo config set-url`. */
-  serviceUrls?: Record<string, string>;
-  /** Optional agent label propagated as `X-Topolo-Agent`. */
-  agentName?: string;
-  /** Environment-scoped profiles. Legacy top-level fields are treated as production. */
-  profiles?: Partial<Record<TopoloEnvironment, TopoloEnvironmentProfile>>;
-}
-
-export interface TopoloEnvironmentProfile {
-  credential?: TopoloCredential;
-  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';
-}
-
-/**
- * Default service URLs per environment. `local` has no baked defaults — a
- * local dev loop points services at ad-hoc ports, so it is driven entirely by
- * `TOPOLO_LOCAL_SERVICE_URL_*` / `TOPOLO_SERVICE_URL_*` overrides.
- */
-export const ENVIRONMENT_DEFAULT_SERVICE_URLS: Record<
-  TopoloEnvironment,
-  Record<string, string>
-> = {
-  production: {
-    developers: 'https://developers.topolo.app',
-  },
-  staging: {
-    auth: 'https://auth.stg.topolo.us',
-    developers: 'https://developers.stg.topolo.us',
-    seed: 'https://seed.stg.topolo.us',
-  },
-  development: {
-    auth: 'https://auth.topolo.dev',
-    developers: 'https://developers.topolo.dev',
-  },
-  local: {},
-};
-
-export function configPath(): string {
-  const override = process.env.TOPOLO_CONFIG_PATH;
-  if (override) return override;
-  const base = process.env.XDG_CONFIG_HOME
-    || (platform() === 'win32'
-      ? join(homedir(), 'AppData', 'Roaming')
-      : join(homedir(), '.config'));
-  return join(base, 'topolo', 'config.json');
-}
-
-export async function readConfig(): Promise<TopoloConfig> {
-  const path = configPath();
-  if (!existsSync(path)) return {};
-  try {
-    const raw = await readFile(path, 'utf8');
-    return JSON.parse(raw) as TopoloConfig;
-  } catch {
-    return {};
-  }
-}
-
-export async function writeConfig(config: TopoloConfig): Promise<void> {
-  const path = configPath();
-  await mkdir(dirname(path), { recursive: true });
-  await writeFile(path, JSON.stringify(config, null, 2) + '\n', 'utf8');
-  if (platform() !== 'win32') {
-    try {
-      await chmod(path, 0o600);
-    } catch {
-      /* non-fatal */
-    }
-  }
-}
-
-export function normalizeEnvironment(value: string | undefined): TopoloEnvironment {
-  const normalized = (value ?? 'production').trim().toLowerCase();
-  if (normalized === '' || normalized === 'production' || normalized === 'prod') {
-    return 'production';
-  }
-  if (normalized === 'staging' || normalized === 'stage' || normalized === 'stg') {
-    return 'staging';
-  }
-  if (normalized === 'development' || normalized === 'dev') {
-    return 'development';
-  }
-  if (normalized === 'local' || normalized === 'localhost') {
-    return 'local';
-  }
-  throw new Error(
-    `Unknown Topolo environment "${value}". Expected production, staging, development, or local.`,
-  );
-}
-
-export function selectedEnvironment(): TopoloEnvironment {
-  return normalizeEnvironment(process.env.TOPOLO_ENV);
-}
-
-export function envVarPrefix(environment: TopoloEnvironment): string {
-  if (environment === 'production') return 'TOPOLO_PRODUCTION';
-  if (environment === 'staging') return 'TOPOLO_STAGING';
-  if (environment === 'development') return 'TOPOLO_DEVELOPMENT';
-  return 'TOPOLO_LOCAL';
-}
-
-export function profileForEnvironment(
-  config: TopoloConfig,
-  environment: TopoloEnvironment = selectedEnvironment(),
-): TopoloEnvironmentProfile {
-  const profile = config.profiles?.[environment] ?? {};
-  if (environment === 'production') {
-    return {
-      credential: config.credential,
-      oauthClientId: config.oauthClientId,
-      ...profile,
-      serviceUrls: {
-        ...(config.serviceUrls ?? {}),
-        ...(profile.serviceUrls ?? {}),
-      },
-      agentName: profile.agentName ?? config.agentName,
-    };
-  }
-  return profile;
-}
-
-export function writeProfileConfig(
-  config: TopoloConfig,
-  environment: TopoloEnvironment,
-  profile: TopoloEnvironmentProfile,
-): TopoloConfig {
-  const profiles = { ...(config.profiles ?? {}) };
-  profiles[environment] = {
-    ...(profiles[environment] ?? {}),
-    ...profile,
-  };
-  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,
-): TopoloConfig {
-  const next = { ...config };
-  if (environment === 'production') {
-    delete next.credential;
-    delete next.oauthClientId;
-  }
-  const profiles = { ...(config.profiles ?? {}) };
-  const profile = { ...(profiles[environment] ?? {}) };
-  delete profile.credential;
-  delete profile.oauthClientId;
-  profiles[environment] = profile;
-  return { ...next, profiles };
-}
-
-export function credentialSourceFromConfig(
-  config: TopoloConfig,
-  environment: TopoloEnvironment = selectedEnvironment(),
-): string {
-  const prefix = envVarPrefix(environment);
-  if (process.env[`${prefix}_API_KEY`]) return `env:${prefix}_API_KEY`;
-  if (process.env[`${prefix}_ACCESS_TOKEN`]) return `env:${prefix}_ACCESS_TOKEN`;
-  if (process.env.TOPOLO_API_KEY) return 'env:TOPOLO_API_KEY';
-  if (process.env.TOPOLO_ACCESS_TOKEN) return 'env:TOPOLO_ACCESS_TOKEN';
-  return profileForEnvironment(config, environment).credential ? 'config-file' : 'none';
-}
-
-/**
- * Resolve credentials with env-var precedence over on-disk config.
- * Env vars are what agents set in their environment; config is what
- * interactive users get after running `topolo auth login`.
- */
-export async function resolveCredential(
-  environment: TopoloEnvironment = selectedEnvironment(),
-): Promise<TopoloCredential | null> {
-  const prefix = envVarPrefix(environment);
-  const apiKey = process.env[`${prefix}_API_KEY`] ?? process.env.TOPOLO_API_KEY;
-  if (apiKey) return { kind: 'api_key', apiKey };
-
-  const accessToken = process.env[`${prefix}_ACCESS_TOKEN`] ?? process.env.TOPOLO_ACCESS_TOKEN;
-  if (accessToken) return { kind: 'access_token', accessToken };
-
-  const config = await readConfig();
-  return profileForEnvironment(config, environment).credential ?? null;
-}
-
-/**
- * If the stored access_token is expired (or within the skew window) and a
- * refresh_token + oauthClientId are present, exchange the refresh_token for a
- * new pair and persist. On any failure returns the existing (stale) credential
- * so the next API call fails naturally with auth_error — we don't nuke the
- * user's config on a transient network blip.
- */
-const REFRESH_SKEW_SECONDS = 60;
-
-export async function refreshCredentialIfNeeded(
-  environment: TopoloEnvironment = selectedEnvironment(),
-): Promise<TopoloCredential | null> {
-  const prefix = envVarPrefix(environment);
-  if (
-    process.env[`${prefix}_API_KEY`]
-    || process.env[`${prefix}_ACCESS_TOKEN`]
-    || process.env.TOPOLO_API_KEY
-    || process.env.TOPOLO_ACCESS_TOKEN
-  ) {
-    return resolveCredential(environment);
-  }
-
-  const config = await readConfig();
-  const profile = profileForEnvironment(config, environment);
-  const cred = profile.credential;
-  if (!cred || cred.kind !== 'access_token') return cred ?? null;
-  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;
-
-  try {
-    const oauth = new TopoloOAuth({
-      serviceUrls: resolveServiceUrls(profile.serviceUrls, environment) as Partial<
-        Record<'auth' | 'crm', string>
-      >,
-    });
-    const tokens = await oauth.refreshToken({
-      clientId: profile.oauthClientId,
-      refreshToken: cred.refreshToken,
-    });
-    const refreshed: TopoloCredential = {
-      kind: 'access_token',
-      accessToken: tokens.access_token,
-      ...(tokens.refresh_token
-        ? { refreshToken: tokens.refresh_token }
-        : { refreshToken: cred.refreshToken }),
-      expiresAt: Math.floor(Date.now() / 1000) + tokens.expires_in,
-    };
-    await writeConfig(
-      environment === 'production' && !config.profiles?.production
-        ? { ...config, credential: refreshed }
-        : writeProfileConfig(config, environment, { credential: refreshed }),
-    );
-    return refreshed;
-  } catch {
-    return cred;
-  }
-}
-
-export function resolveAgentName(configAgentName?: string): string | undefined {
-  return process.env.TOPOLO_AGENT_NAME ?? configAgentName;
-}
-
-export function resolveServiceUrls(
-  configUrls?: Record<string, string>,
-  environment: TopoloEnvironment = selectedEnvironment(),
-): Record<string, string> | undefined {
-  const merged: Record<string, string> = {
-    ...ENVIRONMENT_DEFAULT_SERVICE_URLS[environment],
-    ...(configUrls ?? {}),
-  };
-
-  // Env wins. Pull env-specific and global service URL vars that might be set.
-  const prefix = `${envVarPrefix(environment)}_SERVICE_URL_`;
-  for (const [k, v] of Object.entries(process.env)) {
-    if (k.startsWith(prefix) && v) {
-      merged[k.slice(prefix.length).toLowerCase()] = v;
-    }
-  }
-  for (const [k, v] of Object.entries(process.env)) {
-    if (k.startsWith('TOPOLO_SERVICE_URL_') && v) {
-      merged[k.slice('TOPOLO_SERVICE_URL_'.length).toLowerCase()] = v;
-    }
-  }
-  return Object.keys(merged).length > 0 ? merged : undefined;
-}
-
-export function resolvedProfileConfig(
-  config: TopoloConfig,
-  environment: TopoloEnvironment = selectedEnvironment(),
-): TopoloEnvironmentProfile {
-  const profile = profileForEnvironment(config, environment);
-  return {
-    credential: profile.credential,
-    oauthClientId: profile.oauthClientId,
-    agentName: profile.agentName,
-    serviceUrls: resolveServiceUrls(profile.serviceUrls, environment),
-  };
-}

package/src/oauth.test.ts

@@ -1,216 +0,0 @@
-import { describe, expect, it, vi } from 'vitest';
-import { TopoloOAuth } from './oauth.js';
-import { TopoloAuthError, TopoloHttpError } from './errors.js';
-
-function stubFetch(next: { status: number; body: unknown }) {
-  const calls: Array<{ url: string; init: RequestInit }> = [];
-  const impl = vi.fn(async (url: string, init: RequestInit) => {
-    calls.push({ url, init });
-    return new Response(JSON.stringify(next.body ?? {}), {
-      status: next.status,
-      headers: { 'Content-Type': 'application/json' },
-    });
-  });
-  return { impl: impl as unknown as typeof fetch, calls };
-}
-
-describe('TopoloOAuth.pollDeviceToken', () => {
-  it('maps authorization_pending response into TopoloAuthError(code=authorization_pending)', async () => {
-    const { impl } = stubFetch({
-      status: 400,
-      body: { error: 'authorization_pending', error_description: 'Pending user approval' },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await expect(
-      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
-    ).rejects.toMatchObject({
-      name: 'TopoloAuthError',
-      code: 'authorization_pending',
-    });
-  });
-
-  it('maps slow_down into TopoloAuthError(code=slow_down)', async () => {
-    const { impl } = stubFetch({
-      status: 400,
-      body: { error: 'slow_down', error_description: 'Back off' },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await expect(
-      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
-    ).rejects.toMatchObject({ code: 'slow_down' });
-  });
-
-  it('returns TokenResponse on 200', async () => {
-    const { impl } = stubFetch({
-      status: 200,
-      body: { access_token: 'at', token_type: 'Bearer', expires_in: 3600, refresh_token: 'rt' },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    const res = await oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' });
-    expect(res.access_token).toBe('at');
-    expect(res.refresh_token).toBe('rt');
-  });
-
-  it('wraps unknown non-OAuth failures as TopoloHttpError', async () => {
-    const { impl } = stubFetch({ status: 500, body: { unexpected: true } });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await expect(
-      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
-    ).rejects.toBeInstanceOf(TopoloHttpError);
-  });
-});
-
-describe('TopoloOAuth.refreshToken', () => {
-  it('POSTs grant_type=refresh_token with the client_id + refresh_token', async () => {
-    const { impl, calls } = stubFetch({
-      status: 200,
-      body: { access_token: 'new', token_type: 'Bearer', expires_in: 3600, refresh_token: 'new_rt' },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    const res = await oauth.refreshToken({ clientId: 'doac_x', refreshToken: 'rt_old' });
-    expect(res.access_token).toBe('new');
-    const body = new URLSearchParams(calls[0]!.init.body as string);
-    expect(body.get('grant_type')).toBe('refresh_token');
-    expect(body.get('client_id')).toBe('doac_x');
-    expect(body.get('refresh_token')).toBe('rt_old');
-  });
-
-  it('surfaces invalid_grant as TopoloAuthError', async () => {
-    const { impl } = stubFetch({
-      status: 400,
-      body: { error: 'invalid_grant', error_description: 'Refresh token revoked' },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await expect(
-      oauth.refreshToken({ clientId: 'doac_x', refreshToken: 'rt_dead' }),
-    ).rejects.toMatchObject({
-      name: 'TopoloAuthError',
-      code: 'invalid_grant',
-    });
-  });
-});
-
-describe('TopoloOAuth.requestDeviceCode', () => {
-  it('joins array scopes with a space', async () => {
-    const { impl, calls } = stubFetch({
-      status: 200,
-      body: {
-        device_code: 'dc',
-        user_code: 'ABCD-1234',
-        verification_uri: 'https://ex/dev',
-        expires_in: 600,
-        interval: 5,
-      },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await oauth.requestDeviceCode({ clientId: 'doac_x', scope: ['read', 'write'] });
-    const body = new URLSearchParams(calls[0]!.init.body as string);
-    expect(body.get('scope')).toBe('read write');
-  });
-});
-
-describe('TopoloOAuth.exchangeAuthorizationCode', () => {
-  it('POSTs grant_type=authorization_code with PKCE verifier + secret', async () => {
-    const { impl, calls } = stubFetch({
-      status: 200,
-      body: { access_token: 'at', token_type: 'Bearer', expires_in: 3600 },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    const res = await oauth.exchangeAuthorizationCode({
-      clientId: 'doac_x',
-      code: 'auth_code_1',
-      redirectUri: 'https://app/cb',
-      codeVerifier: 'verifier_1',
-      clientSecret: 'secret_1',
-    });
-    expect(res.access_token).toBe('at');
-    const body = new URLSearchParams(calls[0]!.init.body as string);
-    expect(body.get('grant_type')).toBe('authorization_code');
-    expect(body.get('code')).toBe('auth_code_1');
-    expect(body.get('redirect_uri')).toBe('https://app/cb');
-    expect(body.get('code_verifier')).toBe('verifier_1');
-    expect(body.get('client_secret')).toBe('secret_1');
-  });
-
-  it('omits optional PKCE verifier + secret when not provided', async () => {
-    const { impl, calls } = stubFetch({
-      status: 200,
-      body: { access_token: 'at', token_type: 'Bearer', expires_in: 3600 },
-    });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await oauth.exchangeAuthorizationCode({
-      clientId: 'doac_x',
-      code: 'c',
-      redirectUri: 'https://app/cb',
-    });
-    const body = new URLSearchParams(calls[0]!.init.body as string);
-    expect(body.has('code_verifier')).toBe(false);
-    expect(body.has('client_secret')).toBe(false);
-  });
-});
-
-describe('TopoloOAuth.requestDeviceCode (single scope + omitted)', () => {
-  function deviceBody() {
-    return {
-      device_code: 'dc',
-      user_code: 'X',
-      verification_uri: 'https://ex/dev',
-      expires_in: 600,
-      interval: 5,
-    };
-  }
-
-  it('passes a string scope through unchanged', async () => {
-    const { impl, calls } = stubFetch({ status: 200, body: deviceBody() });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await oauth.requestDeviceCode({ clientId: 'doac_x', scope: 'read' });
-    expect(new URLSearchParams(calls[0]!.init.body as string).get('scope')).toBe('read');
-  });
-
-  it('omits scope when not provided', async () => {
-    const { impl, calls } = stubFetch({ status: 200, body: deviceBody() });
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await oauth.requestDeviceCode({ clientId: 'doac_x' });
-    expect(new URLSearchParams(calls[0]!.init.body as string).has('scope')).toBe(false);
-  });
-});
-
-describe('TopoloOAuth #postForm content negotiation', () => {
-  it('parses a non-JSON (text/plain) successful body as a string', async () => {
-    const impl = vi.fn(async () =>
-      new Response('plain-ok', { status: 200, headers: { 'Content-Type': 'text/plain' } }),
-    ) as unknown as typeof fetch;
-    const oauth = new TopoloOAuth({ fetch: impl });
-    const res = await oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' });
-    expect(res as unknown).toBe('plain-ok');
-  });
-
-  it('wraps a non-OAuth text error body in TopoloHttpError', async () => {
-    const impl = vi.fn(async () =>
-      new Response('upstream exploded', {
-        status: 502,
-        headers: { 'Content-Type': 'text/plain' },
-      }),
-    ) as unknown as typeof fetch;
-    const oauth = new TopoloOAuth({ fetch: impl });
-    await expect(
-      oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' }),
-    ).rejects.toBeInstanceOf(TopoloHttpError);
-  });
-
-  it('normalizes a base URL that already ends with a slash', async () => {
-    const { impl, calls } = stubFetch({
-      status: 200,
-      body: { access_token: 'at', token_type: 'Bearer', expires_in: 1 },
-    });
-    const oauth = new TopoloOAuth({
-      fetch: impl,
-      serviceUrls: { auth: 'https://auth.example/' },
-    });
-    await oauth.pollDeviceToken({ clientId: 'doac_x', deviceCode: 'dc_1' });
-    expect(calls[0]!.url).toBe('https://auth.example/api/developer-oauth/token');
-  });
-});
-
-// Keep the TopoloAuthError import non-dead for type inference
-void TopoloAuthError;