@toloka-platform/sdk 0.2.1 → 0.3.0

package/src/cli/browser-login.ts

@@ -0,0 +1,265 @@
+import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import type { AddressInfo } from "node:net";
+import { assertCli, TolokaCliError } from "./cli-error";
+import type { CliEnvironment } from "./credentials";
+import {
+  requestTokens,
+  TokenRequestError,
+} from "./keycloak";
+import type { BrowserLoginProvider, TokenResponse } from "./keycloak";
+import { signInPage, statusPage } from "./sign-in-page";
+import { PLAIN_STYLE } from "./style";
+import type { Style } from "./style";
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const LAUNCH_GRACE_MS = 2_000;
+const CALLBACK_PATH = "/callback";
+
+export const createPkcePair = (): { readonly verifier: string; readonly challenge: string } => {
+  const verifier = randomBytes(32).toString("base64url");
+  const challenge = createHash("sha256").update(verifier).digest("base64url");
+  return { verifier, challenge };
+};
+
+export const authorizationUrl = (request: {
+  readonly provider: BrowserLoginProvider;
+  readonly redirectUri: string;
+  readonly state: string;
+  readonly codeChallenge: string;
+  readonly identityProviderHint?: string;
+}): string => {
+  const url = new URL(request.provider.authorizationEndpoint);
+  url.searchParams.set("client_id", request.provider.clientId);
+  url.searchParams.set("redirect_uri", request.redirectUri);
+  url.searchParams.set("response_type", "code");
+  url.searchParams.set("scope", "openid");
+  url.searchParams.set("state", request.state);
+  url.searchParams.set("code_challenge", request.codeChallenge);
+  url.searchParams.set("code_challenge_method", "S256");
+  if (request.identityProviderHint !== undefined) {
+    url.searchParams.set("kc_idp_hint", request.identityProviderHint);
+  }
+  return url.toString();
+};
+
+export type BrowserLauncher = (url: string) => Promise<boolean>;
+
+const launcherCommand = (
+  environment: CliEnvironment,
+  platform: NodeJS.Platform,
+): readonly [string, ...string[]] => {
+  const configured = environment.BROWSER?.trim();
+  if (configured !== undefined && configured.length > 0) return [configured];
+  if (platform === "darwin") return ["open"];
+  if (platform === "win32") return ["rundll32", "url.dll,FileProtocolHandler"];
+  return ["xdg-open"];
+};
+
+const launchSystemBrowser = (url: string, environment: CliEnvironment): Promise<boolean> =>
+  new Promise((resolve) => {
+    const [command, ...prefix] = launcherCommand(environment, process.platform);
+    const child = spawn(command, [...prefix, url], { detached: true, stdio: "ignore" });
+    const settle = (launched: boolean) => {
+      clearTimeout(grace);
+      child.unref();
+      resolve(launched);
+    };
+    const grace = setTimeout(() => settle(true), LAUNCH_GRACE_MS);
+    child.once("error", () => settle(false));
+    child.once("exit", (code) => settle(code === 0));
+  });
+
+const RETRY_HINT = {
+  description: "Run toloka login again and finish the sign-in in the tab it opens.",
+};
+
+export type LoopbackServer = {
+  readonly origin: string;
+  readonly redirectUri: string;
+  readonly authorizationCode: Promise<string>;
+  readonly close: () => void;
+};
+
+export const startLoopbackServer = async (
+  state: string,
+  timeoutMs: number,
+  chooser?: (redirectUri: string) => string,
+): Promise<LoopbackServer> => {
+  const { promise, resolve, reject } = Promise.withResolvers<string>();
+  let host = "";
+  let redirectUri = "";
+  const server = createServer((request, response) => {
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+    const reply = (status: number, html: string) => {
+      response.writeHead(status, {
+        "Content-Type": "text/html; charset=utf-8",
+        "Cache-Control": "no-store",
+        Connection: "close",
+      });
+      response.end(html);
+    };
+    if (request.headers.host !== host) {
+      reply(400, statusPage("Unexpected address", "This page is only served on the loopback address the Toloka CLI opened."));
+      return;
+    }
+    if (url.pathname === "/" && chooser !== undefined) {
+      reply(200, chooser(redirectUri));
+      return;
+    }
+    if (url.pathname !== CALLBACK_PATH) {
+      reply(404, statusPage("Not found", "This address only serves the Toloka CLI sign-in."));
+      return;
+    }
+    if (url.searchParams.get("state") !== state) {
+      reply(400, statusPage("Sign-in mismatch", "This response belongs to another sign-in attempt."));
+      return;
+    }
+    const error = url.searchParams.get("error");
+    if (error !== null) {
+      const description = url.searchParams.get("error_description") ?? error;
+      reply(400, statusPage("Sign-in failed", description));
+      reject(
+        new TolokaCliError(`The browser sign-in was not completed: ${description}`, {
+          hint: RETRY_HINT,
+        }),
+      );
+      return;
+    }
+    const code = url.searchParams.get("code");
+    if (code === null || code.length === 0) {
+      reply(400, statusPage("Sign-in failed", "The response carried no authorization code."));
+      reject(
+        new TolokaCliError("The browser returned no authorization code.", { hint: RETRY_HINT }),
+      );
+      return;
+    }
+    reply(200, statusPage("You are signed in", "You can close this tab and return to the terminal."));
+    resolve(code);
+  });
+
+  await new Promise<void>((ready, failed) => {
+    server.once("error", failed);
+    server.listen(0, "127.0.0.1", () => ready());
+  });
+  const { port } = server.address() as AddressInfo;
+  host = `127.0.0.1:${port}`;
+  const origin = `http://${host}`;
+  redirectUri = `${origin}${CALLBACK_PATH}`;
+  const minutes = Math.max(1, Math.round(timeoutMs / 60_000));
+  const timer = setTimeout(() => {
+    reject(
+      new TolokaCliError(
+        `Timed out after ${minutes} minute${minutes === 1 ? "" : "s"} waiting for the browser sign-in.`,
+        { hint: RETRY_HINT },
+      ),
+    );
+  }, timeoutMs);
+  const close = () => {
+    clearTimeout(timer);
+    server.close();
+    server.closeIdleConnections();
+  };
+  promise.then(close, close);
+
+  return { origin, redirectUri, authorizationCode: promise, close };
+};
+
+export type BrowserLoginRequest = {
+  readonly provider: BrowserLoginProvider;
+  readonly openBrowser: boolean;
+  readonly requireBrowser?: boolean;
+  readonly registrationUrl?: string;
+  readonly style?: Style;
+  readonly write: (text: string) => void;
+};
+
+export type BrowserLoginDependencies = {
+  readonly environment?: CliEnvironment;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly launchBrowser?: BrowserLauncher;
+  readonly timeoutMs?: number;
+};
+
+export type BrowserLoginFlow = (
+  request: BrowserLoginRequest,
+  dependencies?: BrowserLoginDependencies,
+) => Promise<TokenResponse>;
+
+const openSignIn = async (
+  request: BrowserLoginRequest,
+  url: string,
+  dependencies: BrowserLoginDependencies,
+): Promise<void> => {
+  const launch =
+    dependencies.launchBrowser ??
+    ((target: string) => launchSystemBrowser(target, dependencies.environment ?? process.env));
+  const launched = request.openBrowser && (await launch(url));
+  assertCli(
+    launched || request.requireBrowser !== true,
+    "No browser could be opened and there is no terminal to fall back to.",
+    {
+      hint: {
+        description:
+          "Run toloka login where a browser is available, pass --no-browser to get a link you can open elsewhere, or pipe an API key to toloka login --api-key-stdin.",
+      },
+    },
+  );
+  const style = request.style ?? PLAIN_STYLE;
+  request.write(
+    launched
+      ? style.dim(
+          "Waiting for the sign-in to finish in your browser... If no browser opened, run toloka login --no-browser to get a link.",
+        )
+      : `Open this link in your browser to sign in:\n\n  ${style.cyan(url)}\n\n${style.dim("Waiting for the sign-in to finish...")}`,
+  );
+};
+
+export const loginWithBrowser: BrowserLoginFlow = async (request, dependencies = {}) => {
+  const pkce = createPkcePair();
+  const state = randomBytes(16).toString("base64url");
+  const authorizationUrlFor = (redirectUri: string, hint: string | undefined) =>
+    authorizationUrl({
+      provider: request.provider,
+      redirectUri,
+      state,
+      codeChallenge: pkce.challenge,
+      ...(hint === undefined ? {} : { identityProviderHint: hint }),
+    });
+  const server = await startLoopbackServer(
+    state,
+    dependencies.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    (redirectUri) =>
+      signInPage(
+        request.provider.identityProviders,
+        (hint) => authorizationUrlFor(redirectUri, hint),
+        request.registrationUrl,
+      ),
+  );
+
+  try {
+    await openSignIn(request, `${server.origin}/`, dependencies);
+    const code = await server.authorizationCode;
+    return await requestTokens(
+      request.provider,
+      {
+        grant_type: "authorization_code",
+        code,
+        redirect_uri: server.redirectUri,
+        code_verifier: pkce.verifier,
+      },
+      dependencies.fetch,
+    );
+  } catch (error) {
+    if (error instanceof TokenRequestError) {
+      throw new TolokaCliError(`The login service rejected the browser sign-in: ${error.message}`, {
+        hint: RETRY_HINT,
+        cause: error,
+      });
+    }
+    throw error;
+  } finally {
+    server.close();
+  }
+};

package/src/cli/browser-session.ts

@@ -0,0 +1,244 @@
+import { randomUUID } from "node:crypto";
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { TolokaCliError } from "./cli-error";
+import { preparePrivateFilePath } from "./credentials";
+import type { CliEnvironment } from "./credentials";
+import { browserLoginProviderFor, requestTokens, TokenRequestError } from "./keycloak";
+import type { BrowserLoginProvider, TokenResponse } from "./keycloak";
+
+export type BrowserSession = {
+  readonly version: 1;
+  readonly issuer: string;
+  readonly client_id: string;
+  readonly token_endpoint: string;
+  readonly access_token: string;
+  readonly access_token_expires_at: number;
+  readonly refresh_token: string;
+  readonly refresh_token_expires_at: number;
+  readonly scope: string;
+  readonly obtained_at: number;
+};
+
+export type BrowserLogin = {
+  readonly provider: BrowserLoginProvider;
+  readonly session: BrowserSession;
+  readonly path: string;
+};
+
+const ACCESS_TOKEN_LEEWAY_SECONDS = 60;
+
+export const unixSeconds = (): number => Math.floor(Date.now() / 1000);
+
+const browserSessionsDirectory = (environment: CliEnvironment): string =>
+  environment.TOLOKA_CLI_CREDENTIALS_DIR ??
+  (environment.TOLOKA_CREDENTIALS_FILE === undefined
+    ? join(environment.HOME ?? homedir(), ".toloka", "cli", "credentials")
+    : join(dirname(environment.TOLOKA_CREDENTIALS_FILE), "browser-sessions"));
+
+export const browserSessionPath = (
+  provider: BrowserLoginProvider,
+  environment: CliEnvironment = process.env,
+): string =>
+  join(
+    browserSessionsDirectory(environment),
+    provider.authHost,
+    provider.realm,
+    `${provider.clientId}.json`,
+  );
+
+export const browserSessionFromTokens = (
+  provider: BrowserLoginProvider,
+  tokens: TokenResponse,
+  obtainedAt: number = unixSeconds(),
+): BrowserSession => ({
+  version: 1,
+  issuer: provider.issuer,
+  client_id: provider.clientId,
+  token_endpoint: provider.tokenEndpoint,
+  access_token: tokens.access_token,
+  access_token_expires_at: obtainedAt + tokens.expires_in,
+  refresh_token: tokens.refresh_token,
+  refresh_token_expires_at:
+    tokens.refresh_expires_in > 0 ? obtainedAt + tokens.refresh_expires_in : 0,
+  scope: tokens.scope,
+  obtained_at: obtainedAt,
+});
+
+const readField = (payload: unknown, key: string): unknown =>
+  typeof payload === "object" && payload !== null ? Reflect.get(payload, key) : undefined;
+
+const nonEmptyString = (value: unknown): value is string =>
+  typeof value === "string" && value.length > 0;
+
+const finiteNumber = (value: unknown): value is number =>
+  typeof value === "number" && Number.isFinite(value);
+
+const asBrowserSession = (
+  payload: unknown,
+  provider: BrowserLoginProvider,
+): BrowserSession | undefined => {
+  if (readField(payload, "version") !== 1) return undefined;
+  const issuer = readField(payload, "issuer");
+  const clientId = readField(payload, "client_id");
+  if (issuer !== provider.issuer || clientId !== provider.clientId) return undefined;
+  const tokenEndpoint = readField(payload, "token_endpoint");
+  const accessToken = readField(payload, "access_token");
+  const accessTokenExpiresAt = readField(payload, "access_token_expires_at");
+  const refreshToken = readField(payload, "refresh_token");
+  const refreshTokenExpiresAt = readField(payload, "refresh_token_expires_at");
+  const scope = readField(payload, "scope");
+  const obtainedAt = readField(payload, "obtained_at");
+  if (!nonEmptyString(tokenEndpoint) || !nonEmptyString(accessToken)) return undefined;
+  if (!nonEmptyString(refreshToken) || typeof scope !== "string") return undefined;
+  if (!finiteNumber(accessTokenExpiresAt) || !finiteNumber(refreshTokenExpiresAt)) return undefined;
+  if (!finiteNumber(obtainedAt)) return undefined;
+  return {
+    version: 1,
+    issuer,
+    client_id: clientId,
+    token_endpoint: tokenEndpoint,
+    access_token: accessToken,
+    access_token_expires_at: accessTokenExpiresAt,
+    refresh_token: refreshToken,
+    refresh_token_expires_at: refreshTokenExpiresAt,
+    scope,
+    obtained_at: obtainedAt,
+  };
+};
+
+export async function readBrowserSession(
+  provider: BrowserLoginProvider,
+  environment: CliEnvironment = process.env,
+): Promise<BrowserSession | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(browserSessionPath(provider, environment), "utf8");
+  } catch {
+    return undefined;
+  }
+  try {
+    return asBrowserSession(JSON.parse(raw), provider);
+  } catch {
+    return undefined;
+  }
+}
+
+export async function writeBrowserSession(
+  session: BrowserSession,
+  provider: BrowserLoginProvider,
+  environment: CliEnvironment = process.env,
+): Promise<string> {
+  const path = browserSessionPath(provider, environment);
+  await preparePrivateFilePath(path);
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(session, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+  return path;
+}
+
+export async function removeBrowserSession(
+  provider: BrowserLoginProvider,
+  environment: CliEnvironment = process.env,
+): Promise<string | undefined> {
+  const path = browserSessionPath(provider, environment);
+  try {
+    await rm(path);
+    return path;
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") return undefined;
+    throw error;
+  }
+}
+
+export async function findBrowserLogin(
+  baseUrl: string,
+  environment: CliEnvironment = process.env,
+): Promise<BrowserLogin | undefined> {
+  const provider = browserLoginProviderFor(baseUrl);
+  if (provider === undefined) return undefined;
+  const session = await readBrowserSession(provider, environment);
+  if (session === undefined) return undefined;
+  return { provider, session, path: browserSessionPath(provider, environment) };
+}
+
+const isAccessTokenFresh = (session: BrowserSession, now: number): boolean =>
+  session.access_token_expires_at - ACCESS_TOKEN_LEEWAY_SECONDS > now;
+
+export const isRefreshTokenExpired = (
+  session: BrowserSession,
+  now: number = unixSeconds(),
+): boolean => session.refresh_token_expires_at > 0 && session.refresh_token_expires_at <= now;
+
+export class BrowserLoginExpiredError extends TolokaCliError {
+  constructor(baseUrl: string, cause?: unknown) {
+    super(`Your browser login for ${baseUrl} has expired.`, {
+      hint: { description: "Run toloka login to sign in again." },
+      ...(cause === undefined ? {} : { cause }),
+    });
+    this.name = "BrowserLoginExpiredError";
+  }
+}
+
+export const createBrowserSessionAuth = ({
+  provider,
+  baseUrl,
+  environment = process.env,
+  fetch: fetchImplementation = globalThis.fetch,
+  now = unixSeconds,
+}: {
+  readonly provider: BrowserLoginProvider;
+  readonly baseUrl: string;
+  readonly environment?: CliEnvironment;
+  readonly fetch?: typeof globalThis.fetch;
+  readonly now?: () => number;
+}): (() => Promise<string>) => {
+  let pending: Promise<string> | undefined;
+
+  const refresh = async (session: BrowserSession): Promise<BrowserSession> => {
+    if (isRefreshTokenExpired(session, now())) throw new BrowserLoginExpiredError(baseUrl);
+    let tokens: TokenResponse;
+    try {
+      tokens = await requestTokens(
+        provider,
+        { grant_type: "refresh_token", refresh_token: session.refresh_token },
+        fetchImplementation,
+      );
+    } catch (error) {
+      if (error instanceof TokenRequestError && error.oauthError === "invalid_grant") {
+        throw new BrowserLoginExpiredError(baseUrl, error);
+      }
+      const reason = error instanceof Error ? error.message : String(error);
+      throw new TolokaCliError(`Could not renew your browser login for ${baseUrl}: ${reason}`, {
+        hint: { description: "Check network access and retry; run toloka login if it keeps failing." },
+        cause: error,
+      });
+    }
+    const renewed = browserSessionFromTokens(provider, tokens, now());
+    await writeBrowserSession(renewed, provider, environment);
+    return renewed;
+  };
+
+  const resolve = async (): Promise<string> => {
+    const session = await readBrowserSession(provider, environment);
+    if (session === undefined) {
+      throw new TolokaCliError(`Not logged in to ${baseUrl}.`, {
+        hint: { description: "Run toloka login." },
+      });
+    }
+    return (isAccessTokenFresh(session, now()) ? session : await refresh(session)).access_token;
+  };
+
+  return () => {
+    pending ??= resolve().finally(() => {
+      pending = undefined;
+    });
+    return pending;
+  };
+};

package/src/cli/commands/auth.ts

@@ -1,56 +1,66 @@
 import type { Command } from "commander";
-import { createClient } from "../../client";
 import { authStatus, login, logout } from "../auth";
 import {
   identifyClientUser,
+  resolveClient,
   resolveSelectedProject,
   resolveSourceRoot,
   type CommandHost,
 } from "../context";
 import { findCommandCredentials, readStoredCredentials } from "../credentials";
-import { resolveTolokaConfig } from "../config";
 import { readTolokaState } from "../../state";
 
+type LoginCommandOptions = {
+  readonly apiKeyStdin: boolean;
+  readonly browser?: boolean;
+};
+
 export const registerAuthCommands = (program: Command, host: CommandHost): void => {
   const { context, exitCode, globals } = host;
 
   program
     .command("login")
-    .description("store an API key for this machine after verifying it")
-    .option("--api-key-stdin", "read the API key from standard input instead of prompting", false)
-    .action(async (options: { apiKeyStdin: boolean }) => {
+    .description("sign in through your browser, or store an API key, after verifying access")
+    .option("--browser", "sign in through your browser without asking; pick the provider on the page it opens")
+    .option("--no-browser", "the same, but print the sign-in link instead of opening a browser")
+    .option("--api-key-stdin", "store an API key read from standard input instead", false)
+    .action(async (options: LoginCommandOptions) => {
       const apiKey = options.apiKeyStdin ? (await context.io.readStdin()).trim() : globals().apiKey;
       const injectedClient = context.injectedClient;
       const result = await login({
         ...(apiKey === undefined ? {} : { apiKey }),
+        ...(options.browser === undefined ? {} : { browser: options.browser }),
         ...(globals().baseUrl === undefined ? {} : { baseUrl: globals().baseUrl }),
         ...(context.io.prompt === undefined ? {} : { prompt: context.io.prompt }),
+        ...(context.io.choose === undefined ? {} : { choose: context.io.choose }),
         ...(injectedClient === undefined ? {} : { probe: () => injectedClient }),
+        ...(context.browserLogin === undefined ? {} : { browserLogin: context.browserLogin }),
+        ...(context.io.style === undefined ? {} : { style: context.io.style }),
         write: context.io.stdout,
         environment: context.environment,
       });
       context.io.stdout(result.output);
       try {
         const stored = await readStoredCredentials(context.environment);
-        if (stored === undefined) return;
-        const client = context.injectedClient ?? createClient(stored);
+        const { client } = await resolveClient(globals(), context, undefined, stored);
         await identifyClientUser(client, context.analytics);
       } catch {}
     });
 
   program
     .command("logout")
-    .description("remove stored credentials from this machine")
+    .description("remove stored credentials from this machine and end the browser login")
     .action(async () => {
-      const result = await logout(context.environment);
+      const baseUrl = globals().baseUrl;
+      const result = await logout(context.environment, baseUrl === undefined ? {} : { baseUrl });
       context.io.stdout(result.output);
     });
 
   program
     .command("auth-status")
     .alias("whoami")
-    .description("show which platform and key the CLI would use")
-    .option("--show-token", "print the API key instead of masking it", false)
+    .description("show which platform and login the CLI would use")
+    .option("--show-token", "print the API key or access token instead of masking it", false)
     .action(async (options: { showToken: boolean }) => {
       const flags = globals();
       const credentialLookup = await findCommandCredentials(
@@ -79,10 +89,7 @@ export const registerAuthCommands = (program: Command, host: CommandHost): void
         return;
       }
       try {
-        const config = resolveTolokaConfig(flags, state, context.environment, stored);
-        const client =
-          context.injectedClient ??
-          createClient({ apiKey: config.apiKey, baseUrl: config.baseUrl });
+        const { client } = await resolveClient(flags, context, state, stored);
         await identifyClientUser(client, context.analytics);
       } catch {}
     });

package/src/cli/commands/project.ts

@@ -1,7 +1,7 @@
 import type { Command } from "commander";
-import { createClient } from "../../client";
 import {
   identifyClientUser,
+  resolveClient,
   positiveInteger,
   readCommandCredentials,
   resolveContext,
@@ -42,7 +42,7 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     .action(async (alias?: string, projectId?: string) => {
       const flags = globals();
       const found = await requireStoredCredentials(context.environment);
-      const client = context.injectedClient ?? createClient(found.credentials);
+      const { client } = await resolveClient(flags, context, undefined, found.credentials);
       await addProject({
         environment: context.environment,
         flags,
@@ -147,7 +147,7 @@ export const registerProjectCommands = (program: Command, host: CommandHost): vo
     ) => {
       const flags = globals();
       const found = await requireStoredCredentials(context.environment);
-      const client = context.injectedClient ?? createClient(found.credentials);
+      const { client } = await resolveClient(flags, context, undefined, found.credentials);
       const sourceRoot = await resolveSourceRoot(flags, context.io);
       await createProject({
         environment: context.environment,