@manta-eu/auth 0.1.9 → 0.2.0

package/src/auth-commands.ts

@@ -0,0 +1,239 @@
+import type { Command } from "commander";
+import { browserLogin, loginScope } from "./browser-login.js";
+import { hasLocalBrowser, openInBrowser } from "./browser.js";
+import { type CredentialStore, defaultCredentialStore } from "./credential-store.js";
+import { defaultDeployment } from "./default-deployment.js";
+import {
+  createPkcePair,
+  type DeviceTokens,
+  pollForDeviceTokens,
+  type PublicClient,
+  startDeviceLogin,
+} from "./device-login.js";
+import { describeError, type FetchLike, formRequest, postTo } from "./http.js";
+import { saveLogin, storedLoginTokenSource } from "./stored-login.js";
+import { accessTokenUsername, type RenewableTokenSource } from "./token.js";
+
+export type ClientOptions = { keycloakUrl: string; keycloakRealm: string; clientId?: string };
+
+export function cliClientId(realm: string): string {
+  return `${realm}-cli`;
+}
+
+// The confidential client a CI job authenticates with through MANTA_CLIENT_SECRET.
+export const ciClientId = "manta-codegen";
+
+export const clientIdHelp = `Keycloak client id (default: <realm>-cli, or ${ciClientId} with MANTA_CLIENT_SECRET)`;
+
+export type LoginOptions = { useDeviceCode?: boolean };
+
+export function publicClientFrom({ keycloakUrl, keycloakRealm, clientId }: ClientOptions): PublicClient {
+  return {
+    baseUrl: keycloakUrl.replace(/\/+$/, ""),
+    realm: keycloakRealm,
+    clientId: clientId ?? cliClientId(keycloakRealm),
+  };
+}
+
+function warnAs(label: string): (message: string) => void {
+  return (message) => console.error(`${label}: ${message}`);
+}
+
+function where(client: PublicClient): string {
+  return `${client.realm} at ${client.baseUrl}`;
+}
+
+export async function interactiveLogin(
+  client: PublicClient,
+  {
+    label,
+    useDeviceCode = false,
+    fetchImpl = fetch,
+  }: { label: string; useDeviceCode?: boolean; fetchImpl?: FetchLike },
+): Promise<DeviceTokens> {
+  const localBrowser = hasLocalBrowser();
+
+  if (useDeviceCode || !localBrowser) {
+    const login = await startDeviceLogin(client, fetchImpl, createPkcePair(), loginScope);
+
+    console.error(`${label}: open ${login.verificationUri} and enter the code ${login.userCode}`);
+    if (localBrowser) openInBrowser(login.verificationUri);
+
+    return pollForDeviceTokens(client, login, { fetchImpl });
+  }
+
+  return browserLogin(client, {
+    fetchImpl,
+    openUrl: (url) => {
+      console.error(`${label}: log in with the browser that opened. If none did, open ${url}`);
+      openInBrowser(url);
+    },
+  });
+}
+
+export function reportLogin(label: string, client: PublicClient, tokens: DeviceTokens, saved: boolean): void {
+  const username = accessTokenUsername(tokens.accessToken);
+
+  console.error(`${label}: logged in to ${where(client)}${username ? ` as ${username}` : ""}`);
+  if (!saved) console.error(`${label}: Keycloak sent no refresh token, so the next run logs in again.`);
+}
+
+export function notLoggedIn(label: string, client: PublicClient): Error {
+  const flags = [
+    client.baseUrl === defaultDeployment.keycloakUrl ? "" : ` --keycloak-url ${client.baseUrl}`,
+    client.realm === defaultDeployment.keycloakRealm ? "" : ` --keycloak-realm ${client.realm}`,
+    client.clientId === cliClientId(client.realm) ? "" : ` --client-id ${client.clientId}`,
+  ].join("");
+
+  return new Error(`not logged in to ${where(client)}. Run: ${label} login${flags}`);
+}
+
+// A run without a terminal cannot answer a browser, so it names the command to run instead of waiting.
+export function userTokenSource(
+  client: PublicClient,
+  {
+    label,
+    useDeviceCode,
+    store = defaultCredentialStore({ warn: warnAs(label) }),
+    interactive = Boolean(process.stdin.isTTY),
+    fetchImpl = fetch,
+  }: {
+    label: string;
+    useDeviceCode?: boolean;
+    store?: CredentialStore;
+    interactive?: boolean;
+    fetchImpl?: FetchLike;
+  },
+): RenewableTokenSource {
+  return storedLoginTokenSource({
+    client,
+    store,
+    fetchImpl,
+    warn: warnAs(label),
+    login: async () => {
+      if (!interactive) throw notLoggedIn(label, client);
+
+      const tokens = await interactiveLogin(client, { label, useDeviceCode, fetchImpl });
+      reportLogin(label, client, tokens, Boolean(tokens.refreshToken));
+
+      return tokens;
+    },
+  });
+}
+
+export function revocationEndpoint(baseUrl: string, realm: string): string {
+  return `${baseUrl}/realms/${realm}/protocol/openid-connect/revoke`;
+}
+
+// Revoking the refresh token ends its offline session in Keycloak, not just this machine's copy.
+export async function revokeRefreshToken(
+  client: PublicClient,
+  refreshToken: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<boolean> {
+  const request = formRequest({ token: refreshToken, token_type_hint: "refresh_token", client_id: client.clientId });
+
+  try {
+    return (await postTo(revocationEndpoint(client.baseUrl, client.realm), request, fetchImpl)).ok;
+  } catch {
+    return false;
+  }
+}
+
+export async function logIn(
+  client: PublicClient,
+  {
+    label,
+    useDeviceCode,
+    store,
+    fetchImpl = fetch,
+  }: { label: string; useDeviceCode?: boolean; store: CredentialStore; fetchImpl?: FetchLike },
+): Promise<void> {
+  const tokens = await interactiveLogin(client, { label, useDeviceCode, fetchImpl });
+
+  reportLogin(label, client, tokens, await saveLogin(store, client, tokens));
+}
+
+// The local copy goes even when Keycloak is unreachable, since a login the user asked to end must not linger here.
+export async function logOut(
+  client: PublicClient,
+  { label, store, fetchImpl = fetch }: { label: string; store: CredentialStore; fetchImpl?: FetchLike },
+): Promise<void> {
+  const stored = await store.read(client);
+
+  if (!stored) {
+    console.error(`${label}: not logged in to ${where(client)}`);
+    return;
+  }
+
+  const revoked = await revokeRefreshToken(client, stored.refreshToken, fetchImpl);
+  await store.remove(client);
+
+  console.error(
+    revoked
+      ? `${label}: logged out of ${where(client)}`
+      : `${label}: deleted the stored login for ${where(client)}, but Keycloak did not confirm the revocation.`,
+  );
+}
+
+// Reads the store only, so it answers offline; the next run finds out whether Keycloak still accepts the login.
+export async function loginStatus(
+  client: PublicClient,
+  { store }: { store: CredentialStore },
+): Promise<{ loggedIn: boolean; line: string }> {
+  const stored = await store.read(client);
+
+  if (!stored) return { loggedIn: false, line: `not logged in to ${where(client)}` };
+
+  return { loggedIn: true, line: `logged in to ${where(client)}${stored.username ? ` as ${stored.username}` : ""}` };
+}
+
+function clientCommand(program: Command, name: string, description: string): Command {
+  return program
+    .command(name)
+    .description(description)
+    .option("--keycloak-url <url>", "Keycloak base URL", defaultDeployment.keycloakUrl)
+    .option("--keycloak-realm <realm>", "Keycloak realm", defaultDeployment.keycloakRealm)
+    .option("--client-id <id>", "Keycloak client id (default: <realm>-cli)");
+}
+
+async function reportingFailure(label: string, action: () => Promise<void>): Promise<void> {
+  try {
+    await action();
+  } catch (error) {
+    console.error(`${label}: ${describeError(error)}`);
+    process.exitCode = 1;
+  }
+}
+
+// Both CLIs register the same commands over the same store, so one login serves both.
+export function registerAuthCommands(
+  program: Command,
+  {
+    label,
+    store = defaultCredentialStore({ warn: warnAs(label) }),
+    fetchImpl = fetch,
+  }: { label: string; store?: CredentialStore; fetchImpl?: FetchLike },
+): void {
+  clientCommand(program, "login", "log in once; later runs renew the stored login without a browser")
+    .option("--use-device-code", "log in with a one-time code instead of a browser redirect, e.g. over SSH")
+    .action((options: ClientOptions & LoginOptions) =>
+      reportingFailure(label, () =>
+        logIn(publicClientFrom(options), { label, useDeviceCode: options.useDeviceCode, store, fetchImpl }),
+      ),
+    );
+
+  clientCommand(program, "logout", "revoke the stored login at Keycloak and delete it").action(
+    (options: ClientOptions) =>
+      reportingFailure(label, () => logOut(publicClientFrom(options), { label, store, fetchImpl })),
+  );
+
+  clientCommand(program, "status", "show whether a login is stored").action((options: ClientOptions) =>
+    reportingFailure(label, async () => {
+      const { loggedIn, line } = await loginStatus(publicClientFrom(options), { store });
+
+      console.log(line);
+      if (!loggedIn) process.exitCode = 1;
+    }),
+  );
+}

package/src/browser-login.ts

@@ -0,0 +1,203 @@
+import { randomBytes } from "node:crypto";
+import { createServer, type Server } from "node:http";
+import type { AddressInfo } from "node:net";
+import { createPkcePair, type DeviceTokens, type PkcePair, type PublicClient } from "./device-login.js";
+import { type FetchLike, formRequest, postTo, readJson } from "./http.js";
+import { tokenEndpoint } from "./token.js";
+
+// offline_access makes the refresh token outlive the browser session: it lasts while it is used.
+export const loginScope = "openid offline_access";
+
+const callbackPath = "/callback";
+
+const defaultTimeoutMs = 300_000;
+
+export function authorizationEndpoint(baseUrl: string, realm: string): string {
+  return `${baseUrl}/realms/${realm}/protocol/openid-connect/auth`;
+}
+
+export function authorizationUrl(
+  client: PublicClient,
+  { redirectUri, state, challenge, scope }: { redirectUri: string; state: string; challenge: string; scope: string },
+): string {
+  const url = new URL(authorizationEndpoint(client.baseUrl, client.realm));
+
+  url.search = new URLSearchParams({
+    client_id: client.clientId,
+    response_type: "code",
+    redirect_uri: redirectUri,
+    scope,
+    state,
+    code_challenge: challenge,
+    code_challenge_method: "S256",
+  }).toString();
+
+  return url.toString();
+}
+
+function page(title: string, message: string): string {
+  return (
+    `<!doctype html><html lang="en"><head><meta charset="utf-8"><title>${title}</title></head>` +
+    `<body style="font-family: system-ui, sans-serif; max-width: 32rem; margin: 20vh auto; text-align: center">` +
+    `<h1 style="font-size: 1.25rem">${title}</h1><p>${message}</p></body></html>`
+  );
+}
+
+function callbackFailure(error: string, description: string | null): Error {
+  return error === "access_denied"
+    ? new Error("the login was refused in the browser.")
+    : new Error(`the browser login failed with "${description ?? error}".`);
+}
+
+type PendingCallback = { redirectUri: string; code: Promise<string>; close: () => void };
+
+// Keycloak matches a 127.0.0.1 redirect URI whatever its port, so the OS picks a free one.
+export async function listenForCallback(state: string, timeoutMs: number = defaultTimeoutMs): Promise<PendingCallback> {
+  let settle: { resolve: (code: string) => void; reject: (error: Error) => void } | undefined;
+  const code = new Promise<string>((resolve, reject) => (settle = { resolve, reject }));
+
+  // A timeout can fire after the caller stopped waiting; that must not surface as an unhandled rejection.
+  code.catch(() => undefined);
+
+  const server: Server = createServer((request, response) => {
+    const url = new URL(request.url ?? "/", "http://127.0.0.1");
+
+    if (url.pathname !== callbackPath) {
+      response.writeHead(404).end();
+      return;
+    }
+
+    const answer = (status: number, title: string, message: string) =>
+      response.writeHead(status, { "content-type": "text/html; charset=utf-8" }).end(page(title, message));
+
+    // A page on another origin can load this URL too; only the state this process sent proves the answer.
+    if (url.searchParams.get("state") !== state) {
+      answer(400, "Login failed", "This login link does not belong to the command that is waiting. Run it again.");
+      return;
+    }
+
+    const error = url.searchParams.get("error");
+    const received = url.searchParams.get("code");
+
+    if (error || !received) {
+      answer(400, "Login failed", "Return to your terminal for the details.");
+      settle?.reject(callbackFailure(error ?? "missing_code", url.searchParams.get("error_description")));
+      return;
+    }
+
+    answer(200, "Logged in to Manta", "You can close this tab and return to your terminal.");
+    settle?.resolve(received);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      server.off("error", reject);
+      resolve();
+    });
+  }).catch((cause: unknown) => {
+    throw new Error("cannot listen on 127.0.0.1 for the browser login. Use --use-device-code.", {
+      cause,
+    });
+  });
+
+  const timer = setTimeout(
+    () => settle?.reject(new Error("nobody finished the login in time. Run it again.")),
+    timeoutMs,
+  );
+  const { port } = server.address() as AddressInfo;
+
+  return {
+    redirectUri: `http://127.0.0.1:${port}${callbackPath}`,
+    code,
+    close: () => {
+      clearTimeout(timer);
+      server.close();
+    },
+  };
+}
+
+export async function exchangeCode(
+  client: PublicClient,
+  { code, redirectUri, verifier }: { code: string; redirectUri: string; verifier: string },
+  fetchImpl: FetchLike = fetch,
+): Promise<DeviceTokens> {
+  const endpoint = tokenEndpoint(client.baseUrl, client.realm);
+  const request = formRequest({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: client.clientId,
+    code_verifier: verifier,
+  });
+  const response = await postTo(endpoint, request, fetchImpl);
+  const body = await readJson<{ access_token?: string; refresh_token?: string; error_description?: string }>(
+    response,
+    endpoint,
+  );
+
+  if (!response.ok || !body.access_token) {
+    throw new Error(
+      `${endpoint} refused the login with status ${response.status}. ${body.error_description ?? ""}`.trim(),
+    );
+  }
+
+  return { accessToken: body.access_token, ...(body.refresh_token ? { refreshToken: body.refresh_token } : {}) };
+}
+
+// Keycloak answers an unknown client or redirect URI with its own error page, never with a redirect back here.
+export async function checkAuthorizationRequest(
+  client: PublicClient,
+  url: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<void> {
+  const response = await postTo(url, { method: "GET", redirect: "manual" }, fetchImpl);
+  await response.body?.cancel().catch(() => undefined);
+
+  if (response.status >= 400) {
+    throw new Error(
+      `Keycloak refused to start the login with status ${response.status}. ` +
+        `Check that realm ${client.realm} at ${client.baseUrl} has the client ${client.clientId}.`,
+    );
+  }
+}
+
+// The authorization code flow with PKCE and a loopback redirect (RFC 8252), as Claude Code and the AWS CLI log in.
+export async function browserLogin(
+  client: PublicClient,
+  {
+    openUrl,
+    fetchImpl = fetch,
+    scope = loginScope,
+    timeoutMs = defaultTimeoutMs,
+    pkce = createPkcePair(),
+    state = randomBytes(16).toString("base64url"),
+  }: {
+    openUrl: (url: string) => void;
+    fetchImpl?: FetchLike;
+    scope?: string;
+    timeoutMs?: number;
+    pkce?: PkcePair;
+    state?: string;
+  },
+): Promise<DeviceTokens> {
+  const callback = await listenForCallback(state, timeoutMs);
+
+  try {
+    const url = authorizationUrl(client, {
+      redirectUri: callback.redirectUri,
+      state,
+      challenge: pkce.challenge,
+      scope,
+    });
+
+    await checkAuthorizationRequest(client, url, fetchImpl);
+    openUrl(url);
+
+    const code = await callback.code;
+
+    return await exchangeCode(client, { code, redirectUri: callback.redirectUri, verifier: pkce.verifier }, fetchImpl);
+  } finally {
+    callback.close();
+  }
+}

package/src/browser.ts

@@ -0,0 +1,32 @@
+import { spawn } from "node:child_process";
+
+export function hasLocalBrowser(
+  env: Record<string, string | undefined> = process.env,
+  platform: string = process.platform,
+): boolean {
+  if (env.SSH_CONNECTION || env.SSH_CLIENT || env.SSH_TTY) return false;
+  if (platform === "linux") return Boolean(env.DISPLAY || env.WAYLAND_DISPLAY);
+
+  return true;
+}
+
+export function browserCommand(url: string, platform: string = process.platform): [string, string[]] {
+  if (platform === "darwin") return ["open", [url]];
+  if (platform === "win32") return ["rundll32", ["url.dll,FileProtocolHandler", url]];
+
+  return ["xdg-open", [url]];
+}
+
+// Best effort: the URL is always printed too, so a browser that fails to open costs nothing.
+export function openInBrowser(url: string, platform: string = process.platform): void {
+  const [command, args] = browserCommand(url, platform);
+
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+
+    child.on("error", () => undefined);
+    child.unref();
+  } catch {
+    return;
+  }
+}

package/src/credential-store.ts

@@ -0,0 +1,225 @@
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { PublicClient } from "./device-login.js";
+import { describeError } from "./http.js";
+
+// Only the refresh token is kept: an access token lives five minutes, so a run mints its own.
+export type StoredLogin = { refreshToken: string; username?: string; savedAt?: number };
+
+export type CredentialStore = {
+  read: (client: PublicClient) => Promise<StoredLogin | undefined>;
+  write: (client: PublicClient, login: StoredLogin) => Promise<void>;
+  remove: (client: PublicClient) => Promise<void>;
+};
+
+// One entry per Keycloak, realm and client, so staging, production and another realm never share a login.
+export function loginKeyId({ baseUrl, realm, clientId }: PublicClient): string {
+  return `${baseUrl.replace(/\/+$/, "")} ${realm} ${clientId}`;
+}
+
+export function configDir(env: Record<string, string | undefined> = process.env): string {
+  return env.MANTA_CONFIG_DIR || join(homedir(), ".manta");
+}
+
+export function credentialsFilePath(env: Record<string, string | undefined> = process.env): string {
+  return join(configDir(env), "credentials.json");
+}
+
+function isStoredLogin(value: unknown): value is StoredLogin {
+  if (typeof value !== "object" || value === null) return false;
+
+  const { refreshToken, username, savedAt } = value as Record<string, unknown>;
+
+  return (
+    typeof refreshToken === "string" &&
+    (username === undefined || typeof username === "string") &&
+    (savedAt === undefined || typeof savedAt === "number")
+  );
+}
+
+type CredentialsFile = { logins: Record<string, StoredLogin> };
+
+function isMissingFile(error: unknown): boolean {
+  return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
+}
+
+async function readCredentialsFile(path: string): Promise<CredentialsFile> {
+  let text: string;
+
+  try {
+    text = await readFile(path, "utf8");
+  } catch (error) {
+    if (isMissingFile(error)) return { logins: {} };
+    throw error;
+  }
+
+  // Rewriting a file it could not read would drop every other login in it.
+  const unreadable = new Error(`${path} is not a credentials file. Delete it and log in again.`);
+  let parsed: unknown;
+
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw unreadable;
+  }
+
+  const logins = (parsed as { logins?: unknown } | null)?.logins;
+  if (typeof logins !== "object" || logins === null) throw unreadable;
+
+  return {
+    logins: Object.fromEntries(
+      Object.entries(logins).filter((entry): entry is [string, StoredLogin] => isStoredLogin(entry[1])),
+    ),
+  };
+}
+
+// Written to a sibling and renamed, so a crash never leaves half a file behind.
+async function writeCredentialsFile(path: string, file: CredentialsFile): Promise<void> {
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+
+  const sibling = `${path}.${randomBytes(6).toString("hex")}.tmp`;
+
+  await writeFile(sibling, `${JSON.stringify(file, null, 2)}\n`, { mode: 0o600 });
+  await rename(sibling, path);
+}
+
+// Mode 0600 on macOS and Linux; on Windows the user profile's own permissions restrict it.
+export function fileCredentialStore(path: string = credentialsFilePath()): CredentialStore {
+  return {
+    async read(client) {
+      return (await readCredentialsFile(path)).logins[loginKeyId(client)];
+    },
+    async write(client, login) {
+      const file = await readCredentialsFile(path);
+
+      await writeCredentialsFile(path, { logins: { ...file.logins, [loginKeyId(client)]: login } });
+    },
+    async remove(client) {
+      const file = await readCredentialsFile(path);
+      const id = loginKeyId(client);
+
+      if (!(id in file.logins)) return;
+
+      const { [id]: _removed, ...rest } = file.logins;
+      await writeCredentialsFile(path, { logins: rest });
+    },
+  };
+}
+
+export type SecurityResult = { code: number; stdout: string };
+
+export type RunSecurity = (args: string[], stdin?: string) => Promise<SecurityResult>;
+
+export const keychainService = "manta-cli";
+
+export const runSecurity: RunSecurity = (args, stdin) =>
+  new Promise((resolve) => {
+    const child = spawn("security", args, { stdio: ["pipe", "pipe", "ignore"] });
+    let stdout = "";
+
+    child.stdout.on("data", (chunk: Buffer) => (stdout += chunk.toString("utf8")));
+    child.on("error", () => resolve({ code: -1, stdout: "" }));
+    child.on("close", (code) => resolve({ code: code ?? -1, stdout }));
+    child.stdin.end(stdin ?? "");
+  });
+
+function keychainAccount(client: PublicClient): string {
+  const account = loginKeyId(client);
+
+  // `security -i` splits its input like a shell, so a quote would end the account early.
+  if (/["\\\n]/.test(account)) throw new Error(`cannot store a login for ${account} in the Keychain.`);
+
+  return account;
+}
+
+function decodeKeychainSecret(stdout: string): StoredLogin | undefined {
+  try {
+    const parsed: unknown = JSON.parse(Buffer.from(stdout.trim(), "base64").toString("utf8"));
+
+    return isStoredLogin(parsed) ? parsed : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+// The secret goes in on stdin through `security -i`, never as an argument other processes can list.
+export function keychainCredentialStore(run: RunSecurity = runSecurity): CredentialStore {
+  async function read(client: PublicClient): Promise<StoredLogin | undefined> {
+    const found = await run(["find-generic-password", "-s", keychainService, "-a", keychainAccount(client), "-w"]);
+
+    return found.code === 0 ? decodeKeychainSecret(found.stdout) : undefined;
+  }
+
+  return {
+    read,
+    async write(client, login) {
+      const secret = Buffer.from(JSON.stringify(login)).toString("base64");
+      const command = `add-generic-password -U -s ${keychainService} -a "${keychainAccount(client)}" -w ${secret}\n`;
+
+      await run(["-i"], command);
+
+      // `security -i` does not report a failed inner command in its exit code, so the write is read back.
+      if ((await read(client))?.refreshToken !== login.refreshToken) {
+        throw new Error("the Keychain refused the login.");
+      }
+    },
+    async remove(client) {
+      await run(["delete-generic-password", "-s", keychainService, "-a", keychainAccount(client)]);
+    },
+  };
+}
+
+// The Keychain refuses a write while locked, e.g. over SSH, or past `security -i`'s ~4 KB line, so the file takes over.
+export function keychainWithFileFallback(
+  keychain: CredentialStore,
+  file: CredentialStore,
+  { clock = Date.now, warn = () => undefined }: { clock?: () => number; warn?: (reason: string) => void } = {},
+): CredentialStore {
+  return {
+    async read(client) {
+      const [fromFile, fromKeychain] = await Promise.all([
+        file.read(client).catch(() => undefined),
+        keychain.read(client).catch(() => undefined),
+      ]);
+
+      // Either copy can be stale: the Keychain's after it refused a write, the file's after a failed remove.
+      return (fromKeychain?.savedAt ?? 0) > (fromFile?.savedAt ?? 0) ? fromKeychain : (fromFile ?? fromKeychain);
+    },
+    async write(client, login) {
+      const stamped = { ...login, savedAt: clock() };
+
+      try {
+        await keychain.write(client, stamped);
+      } catch (error) {
+        const movesToFile = !(await file.read(client).catch(() => undefined));
+
+        await file.write(client, stamped);
+        if (movesToFile) warn(describeError(error));
+        return;
+      }
+
+      await file.remove(client).catch(() => undefined);
+    },
+    async remove(client) {
+      await keychain.remove(client).catch(() => undefined);
+      await file.remove(client);
+    },
+  };
+}
+
+export function defaultCredentialStore({
+  platform = process.platform,
+  warn = console.error,
+}: { platform?: string; warn?: (message: string) => void } = {}): CredentialStore {
+  const path = credentialsFilePath();
+  const file = fileCredentialStore(path);
+
+  if (platform !== "darwin") return file;
+
+  return keychainWithFileFallback(keychainCredentialStore(), file, {
+    warn: (reason) => warn(`${reason} Stored it in ${path} instead.`),
+  });
+}