@manta-eu/auth 0.1.8 → 0.1.10

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.`),
+  });
+}

package/src/default-deployment.ts

@@ -0,0 +1,15 @@
+// hiremanta.com production, which every SDK entry point targets unless its caller names another deployment.
+export const defaultDeployment = {
+  apiUrl: "https://app.hiremanta.com",
+  keycloakUrl: "https://auth.hiremanta.com",
+  keycloakRealm: "hiremanta-com",
+} as const;
+
+export type Realm = { baseUrl?: string; realm?: string };
+
+export function realmOrDefault(target: Realm = {}): { baseUrl: string; realm: string } {
+  return {
+    baseUrl: (target.baseUrl ?? defaultDeployment.keycloakUrl).replace(/\/+$/, ""),
+    realm: target.realm ?? defaultDeployment.keycloakRealm,
+  };
+}

package/src/device-login.ts

@@ -0,0 +1,181 @@
+import { createHash, randomBytes } from "node:crypto";
+import { type FetchLike, formRequest, isTransientStatus, postTo, readJson } from "./http.js";
+import { tokenEndpoint } from "./token.js";
+
+export type PublicClient = {
+  baseUrl: string;
+  realm: string;
+  clientId: string;
+};
+
+export type DeviceLogin = {
+  deviceCode: string;
+  userCode: string;
+  verificationUri: string;
+  intervalMs: number;
+  expiresInMs: number;
+  codeVerifier: string;
+};
+
+export type PkcePair = { verifier: string; challenge: string };
+
+export type Sleep = (ms: number) => Promise<void>;
+
+const deviceCodeGrant = "urn:ietf:params:oauth:grant-type:device_code";
+
+// RFC 8628 says to add this much whenever the server answers slow_down.
+const slowDownStepMs = 5_000;
+
+const defaultIntervalMs = 5_000;
+
+// RFC 8628 makes expires_in optional, and Keycloak sends ten minutes.
+const defaultExpiresInMs = 600_000;
+
+const sleepFor: Sleep = (ms) => new Promise((done) => setTimeout(done, ms));
+
+export function deviceAuthEndpoint(baseUrl: string, realm: string): string {
+  return `${baseUrl}/realms/${realm}/protocol/openid-connect/auth/device`;
+}
+
+// A public client holds no secret, so PKCE is what ties the token request back to this process.
+export function createPkcePair(): PkcePair {
+  const verifier = randomBytes(32).toString("base64url");
+
+  return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+
+type DeviceLoginResponse = {
+  device_code?: string;
+  user_code?: string;
+  verification_uri?: string;
+  verification_uri_complete?: string;
+  interval?: number;
+  expires_in?: number;
+};
+
+function readDeviceLogin(body: DeviceLoginResponse, endpoint: string, codeVerifier: string): DeviceLogin {
+  const deviceCode = body.device_code;
+  const userCode = body.user_code;
+  const verificationUri = body.verification_uri_complete ?? body.verification_uri;
+
+  if (!deviceCode || !userCode || !verificationUri) {
+    throw new Error(`the device login response from ${endpoint} is incomplete.`);
+  }
+
+  return {
+    deviceCode,
+    userCode,
+    verificationUri,
+    intervalMs: body.interval ? body.interval * 1000 : defaultIntervalMs,
+    expiresInMs: body.expires_in ? body.expires_in * 1000 : defaultExpiresInMs,
+    codeVerifier,
+  };
+}
+
+// No secret lives on the machine: a developer needs nothing beyond a browser login.
+export async function startDeviceLogin(
+  client: PublicClient,
+  fetchImpl: FetchLike = fetch,
+  pkce: PkcePair = createPkcePair(),
+  scope?: string,
+): Promise<DeviceLogin> {
+  const endpoint = deviceAuthEndpoint(client.baseUrl, client.realm);
+  const request = formRequest({
+    client_id: client.clientId,
+    code_challenge: pkce.challenge,
+    code_challenge_method: "S256",
+    ...(scope ? { scope } : {}),
+  });
+  const response = await postTo(endpoint, request, fetchImpl);
+
+  if (!response.ok) {
+    throw new Error(
+      `${endpoint} refused the device login with status ${response.status}. ` +
+        `Check that the client ${client.clientId} is public and allows the OAuth device flow.`,
+    );
+  }
+
+  return readDeviceLogin(await readJson<DeviceLoginResponse>(response, endpoint), endpoint, pkce.verifier);
+}
+
+function deviceLoginFailure(error: string | undefined, status: number): Error | undefined {
+  if (error === "authorization_pending" || error === "slow_down") return undefined;
+  if (error === "access_denied") return new Error("the login was refused in the browser.");
+  if (error === "expired_token") return new Error("the login code expired. Run the command again.");
+
+  return new Error(`the device login failed with "${error ?? status}".`);
+}
+
+function deviceTokenRequest(client: PublicClient, deviceCode: string, codeVerifier: string): RequestInit {
+  return formRequest({
+    grant_type: deviceCodeGrant,
+    device_code: deviceCode,
+    client_id: client.clientId,
+    code_verifier: codeVerifier,
+  });
+}
+
+export type DeviceTokens = { accessToken: string; refreshToken?: string };
+
+export async function pollForDeviceTokens(
+  client: PublicClient,
+  {
+    deviceCode,
+    codeVerifier,
+    intervalMs = defaultIntervalMs,
+    expiresInMs = defaultExpiresInMs,
+  }: Pick<DeviceLogin, "deviceCode" | "codeVerifier"> & { intervalMs?: number; expiresInMs?: number },
+  {
+    fetchImpl = fetch,
+    sleep = sleepFor,
+    clock = Date.now,
+  }: { fetchImpl?: FetchLike; sleep?: Sleep; clock?: () => number } = {},
+): Promise<DeviceTokens> {
+  const endpoint = tokenEndpoint(client.baseUrl, client.realm);
+  const request = deviceTokenRequest(client, deviceCode, codeVerifier);
+  const deadline = clock() + expiresInMs;
+  let wait = intervalMs;
+
+  for (;;) {
+    // Keycloak answers authorization_pending for ever if nobody opens the link.
+    if (clock() >= deadline) throw new Error("nobody approved the login in time. Run it again.");
+
+    const response = await postTo(endpoint, request, fetchImpl);
+    const body = await readJson<{ access_token?: string; refresh_token?: string; error?: string }>(response, endpoint);
+
+    if (response.ok && body.access_token) {
+      return { accessToken: body.access_token, ...(body.refresh_token ? { refreshToken: body.refresh_token } : {}) };
+    }
+
+    const failure = deviceLoginFailure(body.error, response.status);
+    if (failure) throw failure;
+
+    if (body.error === "slow_down") wait += slowDownStepMs;
+
+    await sleep(wait);
+  }
+}
+
+// A refresh token outlives many access tokens, so a long run renews without a second browser login.
+export async function refreshAccessToken(
+  client: PublicClient,
+  refreshToken: string,
+  fetchImpl: FetchLike = fetch,
+): Promise<DeviceTokens | undefined> {
+  const endpoint = tokenEndpoint(client.baseUrl, client.realm);
+  const request = formRequest({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: client.clientId });
+  const response = await postTo(endpoint, request, fetchImpl);
+
+  // A refused refresh token is terminal and earns a new login; an overloaded Keycloak must not cost one.
+  if (isTransientStatus(response.status)) {
+    throw new Error(`${endpoint} could not renew the token (status ${response.status}).`);
+  }
+
+  if (!response.ok) return undefined;
+
+  const body = await readJson<{ access_token?: string; refresh_token?: string }>(response, endpoint);
+
+  if (!body.access_token) return undefined;
+
+  return { accessToken: body.access_token, refreshToken: body.refresh_token ?? refreshToken };
+}