[DIT-13378] Add ability to sign in through OAuth to Ditto CLI

[jholiga]

CLI: Add OAuth login

Overview

Adds ditto login and ditto logout so you can authenticate in a browser instead of pasting an API key.

Login uses the OAuth Authorization Code flow with PKCE. The session is saved to ~/.config/ditto next to any existing API keys.

Credential precedence:

1. DITTO_TOKEN set in environment (so as not to break CI)
2. A saved OAuth session
3. A saved API key
4. The interactive API key prompt

Other notes:

• No new dependencies — http and crypto from Node, and open, which the CLI already used.
• The config file stays readable by --legacy mode, which requires a token key on every entry and drops the whole file without one. There's a test pinning this.
• Legacy mode is untouched and still API-key only. It calls /v1/*, which isn't OAuth-enabled on the API.

Links

• Ticket: DIT-13378
• API side (test together): https://github.com/dittowords/ditto-app/pull/9286

Screenshots or videos

Screen.Recording.2026-08-03.at.4.28.43.PM.mov

Two visual surfaces worth capturing:

• The terminal output during login and logout.
• The browser page shown after approving, which says "You're logged in. You can close this tab and return to your terminal."

Test Plan

Needs joey/dit-13378-add-oauth-support-for-some-or-all-of-the-api-endpoints-and deployed to kooky. (Auth0 config already set up for kooky)

set the following in your .env file: DITTO_API_HOST, DITTO_AUTH0_DOMAIN, DITTO_AUTH0_CLIENT_ID, DITTO_AUTH0_AUDIENCE), then node esbuild.mjs.

• node bin/ditto.js login opens the browser, and approving prints "You're logged in"
• cat ~/.config/ditto shows an oauth block with both accessToken and refreshToken — a missing refreshToken means Auth0's offline access settings are wrong, and login will silently stop working in a day
• node bin/ditto.js pull succeeds without prompting for a key
• node bin/ditto.js logout prints "You're logged out", and the oauth block is gone from ~/.config/ditto
• No regression, API key: DITTO_TOKEN=<api key> node bin/ditto.js pull still works
• No regression, first run: move ~/.config/ditto aside, run node bin/ditto.js pull, and confirm the API key prompt still appears
• No regression, legacy: node bin/ditto.js pull --legacy still works with an API key
• With DITTO_TOKEN set, ditto login warns that commands will keep using the API key
• Expired session recovers cleanly: in ~/.config/ditto, set expiresAt to 1 and delete the refreshToken line, then run pull — it should say "Your Ditto session has expired. Run ditto login to log in again" rather than dropping you at the API key prompt
• npx jest passes

[JWhite30515]

Not sure what controls what access we're asking for, but wouldn't it be more accurate to say we're asking for resource access to things like projects, text items, etc?

[JWhite30515]

sort of a side nit but mind if we add a try catch block to getURLHostname, looks like the edits in this branch expose a codepath during login that hits the code that imports url package, which, depending on local node version, shows error message

Depending on user's node version, this message can bubble up and look like an error on their end (it's not, it's a code warning) (pops up when linking without established Ditto config)

AI writeup suggests just adding a try/catch to getURLHostname.ts

Fix

Three lines, in getURLHostname.ts, dropping the shadowing import:

export default function getURLHostname(hostString: string) {
  if (!hostString.includes("://")) return hostString;
  try {
    return new URL(hostString).hostname || "";
  } catch {
    return "";
  }
}

AI writeup on issue:

Is it this branch?

getURLHostname itself is pre-existing (since 5.0.0), so the branch didn't introduce the deprecated call. But the branch did change when it fires. On master, initAPIToken returned early via if (!fs.existsSync(appContext.configFile)) return collectAndSaveToken(), so with a nonexistent config you'd only hit url.parse in collectAndSaveToken.ts:24 — after you typed a key. This branch removed that early return (correctly — reading the config creates it, and bailing would skip login for first-time users), so getURLHostname now runs before the prompt and the warning lands mid-render.

So: pre-existing latent issue, newly visible in exactly the flow you were testing.

Your setup / Node version

Nothing wrong locally. It's purely your Node version:

node v20.19.5 -> silent
v24.13.0 (yours) -> warns

[JWhite30515]

just as reminder we'll need proper release note in changelog for 5.7 update: https://github.com/dittowords/cli/releases

[JWhite30515]

would this be better renamed to authToken?

[jholiga]

done!

[JWhite30515]

any reason we don't revoke the auth0 connection as well?

[jholiga]

Was trying to keep the scope tidy but a best effort attempt is a pretty small lift. I added it

[JWhite30515]

this is an AI flagged defensive nit but seems reasonable, we shouldn't try creating a session if access token is invalid:

a. Don't build a session out of a response you didn't check — loopbackFlow.ts:53:

const toSession = (data: any): OAuthSession => {
  if (typeof data?.access_token !== "string" || !data.access_token) {
    throw authError("We couldn't finish the login. The response didn't include an access token.");
  }
  return {
    accessToken: data.access_token,
    refreshToken: data.refresh_token,
    expiresAt: Date.now() + ((data.expires_in ?? DEFAULT_EXPIRY_SECONDS) - EXPIRY_MARGIN_SECONDS) * 1000,
  };
};

refreshSession then needs to treat that throw as "refresh failed" rather than letting it escape mid-pull:

try {
  return { ...toSession(response.data), refreshToken: response.data.refresh_token || refreshToken };
} catch {
  return null;
}

[jholiga]

Added!

[JWhite30515]

Suggested change

	// PKCE stands in for a client secret, which a published CLI can't keep.
	// Creates Proof Key for Code Exchange (PKCE) challenger + verifier for oauth connection
	// PKCE stands in for a client secret, which a published CLI can't keep.

[jholiga]

done!

[JWhite30515]

Another AI-ism but it recommends wrapping file in writeGlobalConfigData with chmod 600, so that only owner can read/write to the file (~/.config/ditto, which has API keys)

Take it with an AI grain of salt but might be worth for security's sake?

function writeGlobalConfigData(file: string, data: object) {
  createFileIfMissing(file);
  try {
    fs.chmodSync(file, 0o600); // Owner-only: this file holds API keys.
  } catch {
    // Best-effort; see the note in src/services/globalConfig.ts.
  }
  const existingData = readGlobalConfigData(file);
  const yamlStr = yaml.dump({ ...existingData, ...data });
  fs.writeFileSync(file, yamlStr, "utf8");
}

[JWhite30515]

Don't have the greatest low-level understanding of everything we're doing but high-level LGTM, just left some nits, we should definitely handle the warned node error for url.parse I highlighted