gt 2.21.5 → 2.22.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # gtx-cli
 
+## 2.22.0
+
+### Minor Changes
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`5382de5`](https://github.com/generaltranslation/gt/commit/5382de503a626beb394e01cad92882b78c2a0aa8) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - Add `gt api-key create --name <name> --permission <permissions...>`. It creates an API key for the configured project (`--project-id`, `gt.config.json`, or `GT_PROJECT_ID`) as the signed-in user or with an explicit `--api-key`/`GT_API_KEY`, and prints the new key to stdout exactly once while all other output (project ID, warnings, errors) goes to stderr, so `gt api-key create ... > key.txt` captures only the key; it never writes `.env` files. Both the name and at least one permission are required, permissions must be from the project API key permission set (for example `project:translations:generate`), and the server grants the requested set all-or-nothing.
+
+  Remove `gt auth`, which opened the dashboard wizard to save a project ID and development key to `.env.local`. Use `gt init` for that instead: it signs you in, picks or creates the project, and saves the same variables without the browser wizard. The CLI no longer calls the deprecated wizard session routes; `gt api` can still reach every route.
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`87fa5b1`](https://github.com/generaltranslation/gt/commit/87fa5b17cc2dcd265bc96ab77259e4bc4a6c987f) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - `gt auth` and the `gt init` wizard no longer ask for a key type; `-t/--key-type` is removed. There is one kind of project API key, and its permissions are checked by the server. The wizard now saves only the project ID and the framework-prefixed `GT_DEV_API_KEY` that enables hot reload and runtime translation in development; it no longer writes `GT_API_KEY`, which belongs in your hosting environment (production runtime translation) or CI secrets, and both commands print that guidance. `gt init` signs you in (`gt login`) first when no API key is configured, so the CLI translates as you. On the `GT` and `GTRuntime` constructors, `devApiKey` is deprecated in favor of `apiKey`.
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`c734b08`](https://github.com/generaltranslation/gt/commit/c734b084f0a50d1b2787c86ec790403f88803650) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - Add `gt login`, `gt logout`, and `gt whoami`. Login uses openid-client with the seeded public `gt-cli` client, S256 PKCE and a loopback callback against the General Translation dashboard. When `--no-browser` is set or the loopback listener cannot bind, login uses device authorization with a displayed verification code. Device polling and retries follow openid-client policy (not blanket network/all-5xx retries). Signed identity tokens are validated before saving per-server credentials in `$XDG_STATE_HOME/gt/credentials.json` (default `~/.local/state/gt/credentials.json`, 0600); refresh preserves the validated account identity. Obsolete pre-release logins require `gt login` again without resetting other servers' entries. Login requests a token for the project's configured `baseUrl` (`GT_API_URL` overrides), records that resource with the credentials, and the CLI refuses to send a login issued for a different API instead of letting the server reject it. The API client and core request path accept a refreshable user-token provider, used only when no API key is configured — an explicit API key always wins. The former development-key rejection is gone; every `gtx-` key is just a key with its own permissions.
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`052d499`](https://github.com/generaltranslation/gt/commit/052d499556f3dcf7c6801d2ba91399783608e70b) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - `gt init` sets up development credentials without the dashboard wizard. After signing in (or with an explicit `GT_API_KEY`), it lists the projects you can access and lets you pick one, or creates a new project in an organization where you can create projects. It then mints a development key limited to `project:translations:generate` and saves the project ID and that key to `.env.local` under the names your framework expects (for example `NEXT_PUBLIC_`, `VITE_`, `GATSBY_`, `REACT_APP_`, `REDWOOD_ENV_`). Existing `.env.local` lines, comments, and any `GT_API_KEY` are preserved; rerunning replaces only those two variables. A project ID already in `gt.config.json` or the environment is used directly, and setup is skipped when a runtime key for it is already configured. `--config` and `--src` now reach the config written by `gt init`. The shared API adapter gains paginated `listProjects` and `listOrgs` plus `createProjectApiKey`.
+
+### Patch Changes
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`78e3a57`](https://github.com/generaltranslation/gt/commit/78e3a57c19caffe8fbce2e9bc74e573071d662e8) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - Expose diagnostics through the public `generaltranslation/diagnostics` subpath and fail fast with a diagnostic when an unsupported model provider would otherwise be forwarded and rejected by the server. Migrate the CLI to the diagnostics subpath and API version export, and report invalid model-provider settings with the validation diagnostic.
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`370c31f`](https://github.com/generaltranslation/gt/commit/370c31f975cd1d2bfa9609ea1827c2900f812665) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - Adopt the enriched OpenAPI contract types for runtime translations, download metadata, and action types.
+
+- [#2331](https://github.com/generaltranslation/gt/pull/2331) [`f6d1bae`](https://github.com/generaltranslation/gt/commit/f6d1bae8489ef37377bd45ec27f60e05e1f152d3) Thanks [@fernando-aviles](https://github.com/fernando-aviles)! - Mintlify presets now translate footer and navbar text (`header`, `label`) in per-language navigation entries, and the `mintlify` preset localizes group `root` pages.
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`08e6d82`](https://github.com/generaltranslation/gt/commit/08e6d82df8f02045f43bfcc87b35e9a4ae4a9f69) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - Expose successful job-poll responses through an `onPoll` hook. Route CLI font and wizard requests through the generated SDK, use the shared sequential job poller, and remove the retired hand-written HTTP client implementations.
+
+- [#2205](https://github.com/generaltranslation/gt/pull/2205) [`abc7fea`](https://github.com/generaltranslation/gt/commit/abc7feaeb8be41709178d34db550d7af36c809af) Thanks [@chenxin-yan](https://github.com/chenxin-yan)! - Consolidate CLI and Sanity request construction on the shared core API adapter, which now owns `createProject` and exposes raw project-info and job-status loaders for compatibility facades.
+
+- Updated dependencies [[`87fa5b1`](https://github.com/generaltranslation/gt/commit/87fa5b17cc2dcd265bc96ab77259e4bc4a6c987f), [`78e3a57`](https://github.com/generaltranslation/gt/commit/78e3a57c19caffe8fbce2e9bc74e573071d662e8), [`0e87e42`](https://github.com/generaltranslation/gt/commit/0e87e42ac5d93a1c9ee1f5993d074d4c9a4ae387), [`370c31f`](https://github.com/generaltranslation/gt/commit/370c31f975cd1d2bfa9609ea1827c2900f812665), [`c734b08`](https://github.com/generaltranslation/gt/commit/c734b084f0a50d1b2787c86ec790403f88803650), [`322e927`](https://github.com/generaltranslation/gt/commit/322e9279b7efb17faf220e626a5a3696efc5d863), [`052d499`](https://github.com/generaltranslation/gt/commit/052d499556f3dcf7c6801d2ba91399783608e70b), [`d5649a4`](https://github.com/generaltranslation/gt/commit/d5649a4d9711c3f752a1706348398935bf44e8e1), [`abc7fea`](https://github.com/generaltranslation/gt/commit/abc7feaeb8be41709178d34db550d7af36c809af)]:
+  - generaltranslation@9.5.0
+  - @generaltranslation/python-extractor@0.2.54
+  - @generaltranslation/supported-locales@2.1.34
+  - @generaltranslation/vue-extractor@0.1.14
+
 ## 2.21.5
 
 ### Patch Changes

package/dist/api/collectUserEditDiffs.js

@@ -13,8 +13,8 @@ import { extractYaml } from "../formats/yaml/extractYaml.js";
 import { randomUUID } from "node:crypto";
 import * as path$1 from "node:path";
 import * as fs$1 from "node:fs";
-import { isBinaryFileFormat } from "generaltranslation/types";
 import os from "node:os";
+import { isBinaryFileFormat } from "generaltranslation/types";
 //#region src/api/collectUserEditDiffs.ts
 /**
 * The bytes a file's pipeline content stands for: binary formats carry base64,

package/dist/auth/callbackPage.d.ts

@@ -0,0 +1 @@
+export declare function renderCallbackPage(): string;

package/dist/auth/callbackPage.js

@@ -0,0 +1,77 @@
+//#region src/auth/callbackPage.ts
+const STYLES = `
+  :root {
+    color-scheme: light dark;
+    --background: #fff;
+    --foreground: #09090b;
+    --muted-foreground: #71717a;
+    --success: #1cca5b;
+  }
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --background: #09090b;
+      --foreground: #fafafa;
+      --muted-foreground: #a1a1aa;
+      --success: #387836;
+    }
+  }
+  * { box-sizing: border-box; margin: 0; }
+  html, body { height: 100%; }
+  body {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    padding: 48px 24px;
+    background: var(--background);
+    color: var(--foreground);
+    font: 14px/20px Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+    -webkit-font-smoothing: antialiased;
+  }
+  main {
+    width: 100%;
+    max-width: 400px;
+    text-align: center;
+  }
+  svg {
+    display: block;
+    width: 48px;
+    height: 48px;
+    margin: 0 auto 16px;
+  }
+  .success { color: var(--success); }
+  h1 {
+    font-size: 18px;
+    line-height: 28px;
+    font-weight: 600;
+    letter-spacing: -0.01em;
+    margin-bottom: 8px;
+  }
+  p { color: var(--muted-foreground); }
+`;
+const page = {
+	title: "Sign-in response received",
+	icon: "<svg class=\"success\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"m9 12 2 2 4-4\"/></svg>",
+	body: "Return to your terminal to check whether sign in completed. You can close this window."
+};
+function renderCallbackPage() {
+	return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${page.title}</title>
+<style>${STYLES}</style>
+</head>
+<body>
+<main>
+${page.icon}
+<h1>${page.title}</h1>
+<p>${page.body}</p>
+</main>
+</body>
+</html>`;
+}
+//#endregion
+export { renderCallbackPage };
+
+//# sourceMappingURL=callbackPage.js.map

package/dist/auth/callbackPage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"callbackPage.js","names":[],"sources":["../../src/auth/callbackPage.ts"],"sourcesContent":["// Mirrors the terminal state of the dashboard's device-approval screen\n// (gt-cloud apps/dashboard/.../signin/device/_components/DeviceApproval.tsx):\n// a 48px lucide status icon, 18px semibold heading, 14px muted body, centered\n// in a 400px column. Tokens are copied from gt-cloud packages/ui shared.css\n// because this page is served from 127.0.0.1 with no external assets.\nconst STYLES = `\n  :root {\n    color-scheme: light dark;\n    --background: #fff;\n    --foreground: #09090b;\n    --muted-foreground: #71717a;\n    --success: #1cca5b;\n  }\n  @media (prefers-color-scheme: dark) {\n    :root {\n      --background: #09090b;\n      --foreground: #fafafa;\n      --muted-foreground: #a1a1aa;\n      --success: #387836;\n    }\n  }\n  * { box-sizing: border-box; margin: 0; }\n  html, body { height: 100%; }\n  body {\n    display: flex;\n    align-items: center;\n    justify-content: center;\n    padding: 48px 24px;\n    background: var(--background);\n    color: var(--foreground);\n    font: 14px/20px Inter, ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", sans-serif;\n    -webkit-font-smoothing: antialiased;\n  }\n  main {\n    width: 100%;\n    max-width: 400px;\n    text-align: center;\n  }\n  svg {\n    display: block;\n    width: 48px;\n    height: 48px;\n    margin: 0 auto 16px;\n  }\n  .success { color: var(--success); }\n  h1 {\n    font-size: 18px;\n    line-height: 28px;\n    font-weight: 600;\n    letter-spacing: -0.01em;\n    margin-bottom: 8px;\n  }\n  p { color: var(--muted-foreground); }\n`;\n\nconst CIRCLE_CHECK =\n  '<svg class=\"success\" viewBox=\"0 0 24 24\" fill=\"none\" stroke=\"currentColor\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\" aria-hidden=\"true\"><circle cx=\"12\" cy=\"12\" r=\"10\"/><path d=\"m9 12 2 2 4-4\"/></svg>';\nconst page = {\n  title: 'Sign-in response received',\n  icon: CIRCLE_CHECK,\n  body: 'Return to your terminal to check whether sign in completed. You can close this window.',\n};\n\nexport function renderCallbackPage(): string {\n  return `<!doctype html>\n<html lang=\"en\">\n<head>\n<meta charset=\"utf-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\">\n<title>${page.title}</title>\n<style>${STYLES}</style>\n</head>\n<body>\n<main>\n${page.icon}\n<h1>${page.title}</h1>\n<p>${page.body}</p>\n</main>\n</body>\n</html>`;\n}\n"],"mappings":";AAKA,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoDf,MAAM,OAAO;CACX,OAAO;CACP,MAAM;CACN,MAAM;CACP;AAED,SAAgB,qBAA6B;AAC3C,QAAO;;;;;SAKA,KAAK,MAAM;SACX,OAAO;;;;EAId,KAAK,KAAK;MACN,KAAK,MAAM;KACZ,KAAK,KAAK"}

package/dist/auth/credentialStore.d.ts

@@ -0,0 +1,15 @@
+export type OAuthTokens = {
+    accessToken: string;
+    expiresAt: number;
+    refreshToken: string;
+    /** API resource (origin href) the tokens were issued for. */
+    resource: string;
+    scope: string;
+    tokenType: string;
+    /** Subject from a validated, signature-checked ID token. */
+    subject: string;
+};
+export declare function getCredentialsPath(): string;
+export declare function readOAuthTokens(authBaseUrl: string): Promise<OAuthTokens | undefined>;
+export declare function writeOAuthTokens(tokens: OAuthTokens, authBaseUrl: string): Promise<void>;
+export declare function deleteOAuthTokens(authBaseUrl: string): Promise<void>;

package/dist/auth/credentialStore.js

@@ -0,0 +1,107 @@
+import { logger } from "../console/logger.js";
+import { UserAuthError } from "./errors.js";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { createDiagnosticMessage } from "generaltranslation/diagnostics";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+//#region src/auth/credentialStore.ts
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseStoredTokens(value) {
+	if (!isRecord(value) || typeof value.accessToken !== "string" || !value.accessToken || typeof value.subject !== "string" || !value.subject || typeof value.resource !== "string" || !value.resource || typeof value.expiresAt !== "number" || !Number.isFinite(value.expiresAt) || typeof value.refreshToken !== "string" || typeof value.scope !== "string" || typeof value.tokenType !== "string" || value.tokenType.toLowerCase() !== "bearer") throw new UserAuthError("obsolete_credentials", "This stored login is obsolete or invalid and cannot be used safely", "Run `gt login` again");
+	return {
+		accessToken: value.accessToken,
+		subject: value.subject,
+		resource: value.resource,
+		expiresAt: value.expiresAt,
+		refreshToken: value.refreshToken,
+		scope: value.scope,
+		tokenType: value.tokenType
+	};
+}
+function getCredentialsPath() {
+	const stateHome = process.env.XDG_STATE_HOME;
+	return path.join(stateHome && path.isAbsolute(stateHome) ? stateHome : path.join(homedir(), ".local", "state"), "gt", "credentials.json");
+}
+async function readCredentialsFile() {
+	const credentialsPath = getCredentialsPath();
+	let contents;
+	try {
+		contents = await readFile(credentialsPath, "utf8");
+	} catch (error) {
+		if (isRecord(error) && error.code === "ENOENT") return {
+			version: 2,
+			servers: {}
+		};
+		throw error;
+	}
+	try {
+		const parsed = JSON.parse(contents);
+		if (!isRecord(parsed) || parsed.version !== 2 || !isRecord(parsed.servers)) throw new Error();
+		return {
+			version: 2,
+			servers: parsed.servers
+		};
+	} catch {
+		const backupPath = `${credentialsPath}.corrupt-${Date.now()}`;
+		await rename(credentialsPath, backupPath);
+		logger.warn(createDiagnosticMessage({
+			source: "gt",
+			severity: "Warning",
+			whatHappened: "Stored OAuth credentials were invalid and have been reset",
+			reassurance: "The unreadable file was preserved",
+			details: backupPath,
+			fix: "Run `gt login` again"
+		}));
+		return {
+			version: 2,
+			servers: {}
+		};
+	}
+}
+async function writeCredentialsFile(credentials) {
+	const credentialsPath = getCredentialsPath();
+	const directory = path.dirname(credentialsPath);
+	const temporaryPath = path.join(directory, `.credentials-${randomUUID()}.tmp`);
+	await mkdir(directory, {
+		recursive: true,
+		mode: 448
+	});
+	try {
+		await writeFile(temporaryPath, `${JSON.stringify(credentials, null, 2)}\n`, {
+			encoding: "utf8",
+			mode: 384
+		});
+		await rename(temporaryPath, credentialsPath);
+		await chmod(credentialsPath, 384);
+	} catch (error) {
+		await rm(temporaryPath, { force: true });
+		throw error;
+	}
+}
+async function setServerTokens(authBaseUrl, tokens) {
+	const credentials = await readCredentialsFile();
+	if (tokens) credentials.servers[authBaseUrl] = tokens;
+	else delete credentials.servers[authBaseUrl];
+	if (Object.keys(credentials.servers).length === 0) {
+		await rm(getCredentialsPath(), { force: true });
+		return;
+	}
+	await writeCredentialsFile(credentials);
+}
+async function readOAuthTokens(authBaseUrl) {
+	const value = (await readCredentialsFile()).servers[authBaseUrl];
+	return value === void 0 ? void 0 : parseStoredTokens(value);
+}
+async function writeOAuthTokens(tokens, authBaseUrl) {
+	await setServerTokens(authBaseUrl, tokens);
+}
+async function deleteOAuthTokens(authBaseUrl) {
+	await setServerTokens(authBaseUrl, void 0);
+}
+//#endregion
+export { deleteOAuthTokens, getCredentialsPath, readOAuthTokens, writeOAuthTokens };
+
+//# sourceMappingURL=credentialStore.js.map

package/dist/auth/credentialStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentialStore.js","names":[],"sources":["../../src/auth/credentialStore.ts"],"sourcesContent":["import { randomUUID } from 'node:crypto';\nimport {\n  chmod,\n  mkdir,\n  readFile,\n  rename,\n  rm,\n  writeFile,\n} from 'node:fs/promises';\nimport { homedir } from 'node:os';\nimport path from 'node:path';\nimport { createDiagnosticMessage } from 'generaltranslation/diagnostics';\nimport { logger } from '../console/logger.js';\nimport { UserAuthError } from './errors.js';\n\nexport type OAuthTokens = {\n  accessToken: string;\n  expiresAt: number;\n  refreshToken: string;\n  /** API resource (origin href) the tokens were issued for. */\n  resource: string;\n  scope: string;\n  tokenType: string;\n  /** Subject from a validated, signature-checked ID token. */\n  subject: string;\n};\n\ntype StoredCredentials = {\n  version: 2;\n  // Validate only the selected entry; obsolete sibling sessions must survive.\n  servers: Record<string, unknown>;\n};\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction parseStoredTokens(value: unknown): OAuthTokens {\n  if (\n    !isRecord(value) ||\n    typeof value.accessToken !== 'string' ||\n    !value.accessToken ||\n    typeof value.subject !== 'string' ||\n    !value.subject ||\n    typeof value.resource !== 'string' ||\n    !value.resource ||\n    typeof value.expiresAt !== 'number' ||\n    !Number.isFinite(value.expiresAt) ||\n    typeof value.refreshToken !== 'string' ||\n    typeof value.scope !== 'string' ||\n    typeof value.tokenType !== 'string' ||\n    value.tokenType.toLowerCase() !== 'bearer'\n  ) {\n    throw new UserAuthError(\n      'obsolete_credentials',\n      'This stored login is obsolete or invalid and cannot be used safely',\n      'Run `gt login` again'\n    );\n  }\n  return {\n    accessToken: value.accessToken,\n    subject: value.subject,\n    resource: value.resource,\n    expiresAt: value.expiresAt,\n    refreshToken: value.refreshToken,\n    scope: value.scope,\n    tokenType: value.tokenType,\n  };\n}\n\nexport function getCredentialsPath(): string {\n  // XDG Base Directory spec: relative XDG_* values are invalid and ignored.\n  const stateHome = process.env.XDG_STATE_HOME;\n  return path.join(\n    stateHome && path.isAbsolute(stateHome)\n      ? stateHome\n      : path.join(homedir(), '.local', 'state'),\n    'gt',\n    'credentials.json'\n  );\n}\n\nasync function readCredentialsFile(): Promise<StoredCredentials> {\n  const credentialsPath = getCredentialsPath();\n  let contents: string;\n  try {\n    contents = await readFile(credentialsPath, 'utf8');\n  } catch (error) {\n    if (isRecord(error) && error.code === 'ENOENT')\n      return { version: 2, servers: {} };\n    throw error;\n  }\n  try {\n    const parsed: unknown = JSON.parse(contents);\n    if (!isRecord(parsed) || parsed.version !== 2 || !isRecord(parsed.servers))\n      throw new Error();\n    return { version: 2, servers: parsed.servers };\n  } catch {\n    const backupPath = `${credentialsPath}.corrupt-${Date.now()}`;\n    await rename(credentialsPath, backupPath);\n    logger.warn(\n      createDiagnosticMessage({\n        source: 'gt',\n        severity: 'Warning',\n        whatHappened:\n          'Stored OAuth credentials were invalid and have been reset',\n        reassurance: 'The unreadable file was preserved',\n        details: backupPath,\n        fix: 'Run `gt login` again',\n      })\n    );\n    return { version: 2, servers: {} };\n  }\n}\n\nasync function writeCredentialsFile(\n  credentials: StoredCredentials\n): Promise<void> {\n  const credentialsPath = getCredentialsPath();\n  const directory = path.dirname(credentialsPath);\n  const temporaryPath = path.join(\n    directory,\n    `.credentials-${randomUUID()}.tmp`\n  );\n  await mkdir(directory, { recursive: true, mode: 0o700 });\n  try {\n    await writeFile(\n      temporaryPath,\n      `${JSON.stringify(credentials, null, 2)}\\n`,\n      { encoding: 'utf8', mode: 0o600 }\n    );\n    await rename(temporaryPath, credentialsPath);\n    await chmod(credentialsPath, 0o600);\n  } catch (error) {\n    await rm(temporaryPath, { force: true });\n    throw error;\n  }\n}\n\nasync function setServerTokens(\n  authBaseUrl: string,\n  tokens: OAuthTokens | undefined\n): Promise<void> {\n  const credentials = await readCredentialsFile();\n  if (tokens) credentials.servers[authBaseUrl] = tokens;\n  else delete credentials.servers[authBaseUrl];\n  if (Object.keys(credentials.servers).length === 0) {\n    await rm(getCredentialsPath(), { force: true });\n    return;\n  }\n  await writeCredentialsFile(credentials);\n}\n\nexport async function readOAuthTokens(\n  authBaseUrl: string\n): Promise<OAuthTokens | undefined> {\n  const value = (await readCredentialsFile()).servers[authBaseUrl];\n  return value === undefined ? undefined : parseStoredTokens(value);\n}\nexport async function writeOAuthTokens(\n  tokens: OAuthTokens,\n  authBaseUrl: string\n): Promise<void> {\n  await setServerTokens(authBaseUrl, tokens);\n}\nexport async function deleteOAuthTokens(authBaseUrl: string): Promise<void> {\n  await setServerTokens(authBaseUrl, undefined);\n}\n"],"mappings":"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"}

package/dist/auth/errors.d.ts

@@ -0,0 +1,7 @@
+export type UserAuthErrorCode = 'login_required' | 'obsolete_credentials' | 'resource_mismatch' | 'oauth';
+/** `message` is a complete `gt Error:` diagnostic; commands print it as-is. */
+export declare class UserAuthError extends Error {
+    readonly code: UserAuthErrorCode;
+    constructor(code: UserAuthErrorCode, whatHappened: string, fix?: string, details?: string);
+}
+export declare function loginRequiredError(): UserAuthError;

package/dist/auth/errors.js

@@ -0,0 +1,23 @@
+import { createDiagnosticMessage } from "generaltranslation/diagnostics";
+//#region src/auth/errors.ts
+/** `message` is a complete `gt Error:` diagnostic; commands print it as-is. */
+var UserAuthError = class extends Error {
+	constructor(code, whatHappened, fix, details) {
+		super(createDiagnosticMessage({
+			source: "gt",
+			severity: "Error",
+			whatHappened,
+			fix,
+			details
+		}));
+		this.code = code;
+		this.name = "UserAuthError";
+	}
+};
+function loginRequiredError() {
+	return new UserAuthError("login_required", "You are not signed in", "Run `gt login` to sign in");
+}
+//#endregion
+export { UserAuthError, loginRequiredError };
+
+//# sourceMappingURL=errors.js.map

package/dist/auth/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/auth/errors.ts"],"sourcesContent":["import { createDiagnosticMessage } from 'generaltranslation/diagnostics';\n\nexport type UserAuthErrorCode =\n  | 'login_required'\n  | 'obsolete_credentials'\n  | 'resource_mismatch'\n  | 'oauth';\n\n/** `message` is a complete `gt Error:` diagnostic; commands print it as-is. */\nexport class UserAuthError extends Error {\n  constructor(\n    readonly code: UserAuthErrorCode,\n    whatHappened: string,\n    fix?: string,\n    details?: string\n  ) {\n    super(\n      createDiagnosticMessage({\n        source: 'gt',\n        severity: 'Error',\n        whatHappened,\n        fix,\n        details,\n      })\n    );\n    this.name = 'UserAuthError';\n  }\n}\n\nexport function loginRequiredError(): UserAuthError {\n  return new UserAuthError(\n    'login_required',\n    'You are not signed in',\n    'Run `gt login` to sign in'\n  );\n}\n"],"mappings":";;;AASA,IAAa,gBAAb,cAAmC,MAAM;CACvC,YACE,MACA,cACA,KACA,SACA;AACA,QACE,wBAAwB;GACtB,QAAQ;GACR,UAAU;GACV;GACA;GACA;GACD,CAAC,CACH;AAbQ,OAAA,OAAA;AAcT,OAAK,OAAO;;;AAIhB,SAAgB,qBAAoC;AAClD,QAAO,IAAI,cACT,kBACA,yBACA,4BACD"}

package/dist/auth/loopback.d.ts

@@ -0,0 +1,9 @@
+export declare const LOOPBACK_CALLBACK_PATH = "/callback";
+export type LoopbackServer = {
+    /** Loopback redirect URI bound to an ephemeral port, e.g. http://127.0.0.1:53211/callback */
+    redirectUri: string;
+    /** Resolves with the raw callback parameters of the first request to the callback path. */
+    waitForCallback: (timeoutMs?: number) => Promise<URL>;
+    close: () => void;
+};
+export declare function startLoopbackServer(): Promise<LoopbackServer>;

package/dist/auth/loopback.js

@@ -0,0 +1,73 @@
+import { renderCallbackPage } from "./callbackPage.js";
+import { createDiagnosticMessage } from "generaltranslation/diagnostics";
+import { createServer } from "node:http";
+//#region src/auth/loopback.ts
+const LOOPBACK_CALLBACK_PATH = "/callback";
+const DEFAULT_CALLBACK_TIMEOUT_MS = 300 * 1e3;
+function listen(server) {
+	return new Promise((resolve, reject) => {
+		server.once("error", reject);
+		server.listen(0, "127.0.0.1", () => {
+			server.off("error", reject);
+			const address = server.address();
+			if (!address || typeof address === "string") {
+				server.close();
+				reject(new Error(createDiagnosticMessage({ whatHappened: "Could not resolve the loopback callback address" })));
+				return;
+			}
+			resolve(address.port);
+		});
+	});
+}
+async function startLoopbackServer() {
+	const server = createServer();
+	const origin = `http://127.0.0.1:${await listen(server)}`;
+	let timeout;
+	return {
+		redirectUri: `${origin}${LOOPBACK_CALLBACK_PATH}`,
+		waitForCallback(timeoutMs = DEFAULT_CALLBACK_TIMEOUT_MS) {
+			return new Promise((resolve, reject) => {
+				let settled = false;
+				timeout = setTimeout(() => {
+					settled = true;
+					server.close();
+					reject(new Error(createDiagnosticMessage({
+						whatHappened: "Timed out waiting for the browser to sign in",
+						fix: "Run `gt login` again"
+					})));
+				}, timeoutMs);
+				server.on("request", (request, response) => {
+					const target = request.url ?? "/";
+					const url = URL.canParse(target, origin) ? new URL(target, origin) : void 0;
+					if (!url || settled || request.method !== "GET" || url.origin !== origin || url.pathname !== "/callback") {
+						response.writeHead(404, {
+							"cache-control": "no-store",
+							"content-type": "text/plain; charset=utf-8"
+						});
+						response.end("Not found");
+						return;
+					}
+					settled = true;
+					clearTimeout(timeout);
+					response.writeHead(200, {
+						"cache-control": "no-store",
+						"content-security-policy": "default-src 'none'; style-src 'unsafe-inline'",
+						"content-type": "text/html; charset=utf-8",
+						"x-content-type-options": "nosniff"
+					});
+					response.end(renderCallbackPage());
+					server.close();
+					resolve(url);
+				});
+			});
+		},
+		close() {
+			clearTimeout(timeout);
+			server.close();
+		}
+	};
+}
+//#endregion
+export { LOOPBACK_CALLBACK_PATH, startLoopbackServer };
+
+//# sourceMappingURL=loopback.js.map

package/dist/auth/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","names":[],"sources":["../../src/auth/loopback.ts"],"sourcesContent":["import { createServer, type Server } from 'node:http';\nimport { createDiagnosticMessage } from 'generaltranslation/diagnostics';\nimport { renderCallbackPage } from './callbackPage.js';\n\nexport const LOOPBACK_CALLBACK_PATH = '/callback';\nconst DEFAULT_CALLBACK_TIMEOUT_MS = 5 * 60 * 1000;\n\nexport type LoopbackServer = {\n  /** Loopback redirect URI bound to an ephemeral port, e.g. http://127.0.0.1:53211/callback */\n  redirectUri: string;\n  /** Resolves with the raw callback parameters of the first request to the callback path. */\n  waitForCallback: (timeoutMs?: number) => Promise<URL>;\n  close: () => void;\n};\n\nfunction listen(server: Server): Promise<number> {\n  return new Promise((resolve, reject) => {\n    server.once('error', reject);\n    // RFC 8252 §7.3: bind the loopback interface on an ephemeral port; the\n    // authorization server matches loopback redirect URIs ignoring the port.\n    server.listen(0, '127.0.0.1', () => {\n      server.off('error', reject);\n      const address = server.address();\n      if (!address || typeof address === 'string') {\n        server.close();\n        reject(\n          new Error(\n            createDiagnosticMessage({\n              whatHappened: 'Could not resolve the loopback callback address',\n            })\n          )\n        );\n        return;\n      }\n      resolve(address.port);\n    });\n  });\n}\n\nexport async function startLoopbackServer(): Promise<LoopbackServer> {\n  const server = createServer();\n  const port = await listen(server);\n  const origin = `http://127.0.0.1:${port}`;\n  let timeout: NodeJS.Timeout | undefined;\n\n  return {\n    redirectUri: `${origin}${LOOPBACK_CALLBACK_PATH}`,\n    waitForCallback(timeoutMs = DEFAULT_CALLBACK_TIMEOUT_MS) {\n      return new Promise((resolve, reject) => {\n        let settled = false;\n        timeout = setTimeout(() => {\n          settled = true;\n          server.close();\n          reject(\n            new Error(\n              createDiagnosticMessage({\n                whatHappened: 'Timed out waiting for the browser to sign in',\n                fix: 'Run `gt login` again',\n              })\n            )\n          );\n        }, timeoutMs);\n\n        server.on('request', (request, response) => {\n          const target = request.url ?? '/';\n          const url = URL.canParse(target, origin)\n            ? new URL(target, origin)\n            : undefined;\n          if (\n            !url ||\n            settled ||\n            request.method !== 'GET' ||\n            url.origin !== origin ||\n            url.pathname !== LOOPBACK_CALLBACK_PATH\n          ) {\n            response.writeHead(404, {\n              'cache-control': 'no-store',\n              'content-type': 'text/plain; charset=utf-8',\n            });\n            response.end('Not found');\n            return;\n          }\n\n          settled = true;\n          clearTimeout(timeout);\n          response.writeHead(200, {\n            'cache-control': 'no-store',\n            'content-security-policy':\n              \"default-src 'none'; style-src 'unsafe-inline'\",\n            'content-type': 'text/html; charset=utf-8',\n            'x-content-type-options': 'nosniff',\n          });\n          response.end(renderCallbackPage());\n          server.close();\n          resolve(url);\n        });\n      });\n    },\n    close() {\n      clearTimeout(timeout);\n      server.close();\n    },\n  };\n}\n"],"mappings":";;;;AAIA,MAAa,yBAAyB;AACtC,MAAM,8BAA8B,MAAS;AAU7C,SAAS,OAAO,QAAiC;AAC/C,QAAO,IAAI,SAAS,SAAS,WAAW;AACtC,SAAO,KAAK,SAAS,OAAO;AAG5B,SAAO,OAAO,GAAG,mBAAmB;AAClC,UAAO,IAAI,SAAS,OAAO;GAC3B,MAAM,UAAU,OAAO,SAAS;AAChC,OAAI,CAAC,WAAW,OAAO,YAAY,UAAU;AAC3C,WAAO,OAAO;AACd,WACE,IAAI,MACF,wBAAwB,EACtB,cAAc,mDACf,CAAC,CACH,CACF;AACD;;AAEF,WAAQ,QAAQ,KAAK;IACrB;GACF;;AAGJ,eAAsB,sBAA+C;CACnE,MAAM,SAAS,cAAc;CAE7B,MAAM,SAAS,oBAAoB,MADhB,OAAO,OAAO;CAEjC,IAAI;AAEJ,QAAO;EACL,aAAa,GAAG,SAAS;EACzB,gBAAgB,YAAY,6BAA6B;AACvD,UAAO,IAAI,SAAS,SAAS,WAAW;IACtC,IAAI,UAAU;AACd,cAAU,iBAAiB;AACzB,eAAU;AACV,YAAO,OAAO;AACd,YACE,IAAI,MACF,wBAAwB;MACtB,cAAc;MACd,KAAK;MACN,CAAC,CACH,CACF;OACA,UAAU;AAEb,WAAO,GAAG,YAAY,SAAS,aAAa;KAC1C,MAAM,SAAS,QAAQ,OAAO;KAC9B,MAAM,MAAM,IAAI,SAAS,QAAQ,OAAO,GACpC,IAAI,IAAI,QAAQ,OAAO,GACvB,KAAA;AACJ,SACE,CAAC,OACD,WACA,QAAQ,WAAW,SACnB,IAAI,WAAW,UACf,IAAI,aAAA,aACJ;AACA,eAAS,UAAU,KAAK;OACtB,iBAAiB;OACjB,gBAAgB;OACjB,CAAC;AACF,eAAS,IAAI,YAAY;AACzB;;AAGF,eAAU;AACV,kBAAa,QAAQ;AACrB,cAAS,UAAU,KAAK;MACtB,iBAAiB;MACjB,2BACE;MACF,gBAAgB;MAChB,0BAA0B;MAC3B,CAAC;AACF,cAAS,IAAI,oBAAoB,CAAC;AAClC,YAAO,OAAO;AACd,aAAQ,IAAI;MACZ;KACF;;EAEJ,QAAQ;AACN,gBAAa,QAAQ;AACrB,UAAO,OAAO;;EAEjB"}

package/dist/auth/loopback.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/auth/oauth.d.ts

@@ -0,0 +1,39 @@
+import type { UserTokenProvider } from 'generaltranslation/api';
+import type { OAuthTokens } from './credentialStore.js';
+export type DeviceCode = {
+    userCode: string;
+    verificationUri: string;
+    verificationUriComplete?: string;
+};
+export type UserInfo = {
+    email?: string;
+    name?: string;
+    sub: string;
+};
+type OAuthRequestOptions = {
+    authBaseUrl?: string;
+    fetch?: typeof fetch;
+};
+export type UserTokenProviderOptions = OAuthRequestOptions & {
+    /** API the requests go to; must match the resource the login was issued for. */
+    baseUrl: string;
+};
+export type LoginOptions = OAuthRequestOptions & {
+    /** API the token is issued for; GT_API_URL overrides, then the public API. */
+    baseUrl?: string;
+    noBrowser?: boolean;
+    onDeviceCode?: (deviceCode: DeviceCode) => void;
+    signal?: AbortSignal;
+    onAuthorizationUrl?: (url: string) => void;
+    openBrowser?: (url: string) => Promise<unknown>;
+    timeoutMs?: number;
+};
+/** Browser S256/loopback, or device login for --no-browser and bind failure. */
+export declare function login(options?: LoginOptions): Promise<OAuthTokens>;
+/** Whether a stored login exists for this API; does not refresh or contact the server. */
+export declare function hasLogin(options: UserTokenProviderOptions): Promise<boolean>;
+/** Construction is deliberately free of auth/storage/discovery I/O. */
+export declare function createUserTokenProvider(options: UserTokenProviderOptions): UserTokenProvider;
+export declare function logout(options?: OAuthRequestOptions): Promise<void>;
+export declare function whoAmI(options?: OAuthRequestOptions): Promise<UserInfo>;
+export {};