@kurtbruns/kestrel 1.13.0 → 1.14.0

package/cli/credentials.mjs

@@ -0,0 +1,192 @@
+/*
+ * Where `kestrel login` keeps a person's sign-ins, and how `kestrel api` reads them back.
+ *
+ * A sign-in is the person's, not an instance repository's: it is made in their browser,
+ * through Cloudflare Access, as them, and it reaches every instance folder or none. So it
+ * lives in their user config directory, never in the folder a command runs in, where a
+ * commit or a shared worktree could carry it off: `$XDG_CONFIG_HOME/kestrel/credentials.json`,
+ * `~/.config/kestrel/credentials.json` when that is unset, or `%APPDATA%\kestrel\` on
+ * Windows. `KESTREL_CONFIG_DIR` names another directory, which the suite uses.
+ *
+ * One JSON file, keyed by the instance's origin, readable by its owner alone (0600, in a
+ * 0700 directory), written whole through a temporary file and a rename, so a reader never
+ * sees half of it. Each entry holds what the OAuth client needs to go on without the
+ * browser: the authorization server's endpoints, the client registered for this computer,
+ * the access token with its expiry, and the refresh token, which lasts as long as the
+ * Access application's grant session. A file that exists but isn't one this release can
+ * read is refused, never rewritten, since rewriting it would drop every sign-in it holds.
+ *
+ * A refresh token may be single-use, and Claude Code runs commands side by side, so a refresh
+ * happens under a lock file beside the credentials: whoever waited reads the token the other
+ * stored rather than spending the same refresh token twice. Every write to the file happens
+ * under that lock too, since a write reads the whole file and puts it back, and two at once
+ * would lose one entry's change.
+ */
+import { randomBytes } from "node:crypto";
+import {
+  chmodSync,
+  closeSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const VERSION = 1;
+
+/** The directory the sign-ins live in, from the environment as described above. */
+export function configDir(env = process.env, platform = process.platform) {
+  if (env.KESTREL_CONFIG_DIR) {
+    return env.KESTREL_CONFIG_DIR;
+  }
+  if (platform === "win32" && env.APPDATA) {
+    return join(env.APPDATA, "kestrel");
+  }
+  return join(env.XDG_CONFIG_HOME || join(homedir(), ".config"), "kestrel");
+}
+
+/** The credentials file's path. */
+export function credentialsFile(env = process.env) {
+  return join(configDir(env), "credentials.json");
+}
+
+/** Every stored sign-in, keyed by origin; empty when there is no file yet. Throws, naming
+ *  the file, when it exists and can't be read as this release's. */
+export function readSignIns(env = process.env) {
+  const file = credentialsFile(env);
+  let text;
+  try {
+    text = readFileSync(file, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") {
+      return {};
+    }
+    throw new Error(`Couldn't read the sign-ins in ${file}: ${err?.message ?? err}`);
+  }
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = undefined;
+  }
+  if (data?.version === VERSION && data.instances && typeof data.instances === "object") {
+    return data.instances;
+  }
+  throw new Error(
+    `${file} isn't a sign-ins file this release of Kestrel can read, so it was left as it is. Move it aside, then run \`npx kestrel login <url>\` again.`,
+  );
+}
+
+/** The stored sign-in for one origin, or undefined. */
+export function readSignIn(origin, env = process.env) {
+  return readSignIns(env)[origin];
+}
+
+/**
+ * Store (or, with undefined, forget) the sign-in for one origin, leaving the others. Takes
+ * the credentials lock, so call it outside `withCredentialsLock`; inside one, use
+ * `writeSignInHeld`.
+ */
+export function writeSignIn(origin, entry, env = process.env) {
+  return withCredentialsLock(() => writeSignInHeld(origin, entry, env), env);
+}
+
+/** `writeSignIn` for a caller already inside `withCredentialsLock`, which taking it again would deadlock. */
+export function writeSignInHeld(origin, entry, env = process.env) {
+  const instances = { ...readSignIns(env) };
+  if (entry === undefined) {
+    delete instances[origin];
+  } else {
+    instances[origin] = entry;
+  }
+  const dir = configDir(env);
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const file = credentialsFile(env);
+  const tmp = `${file}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ version: VERSION, instances }, null, 2)}\n`, {
+    mode: 0o600,
+  });
+  // The mode on create is masked by umask, so set it outright before the file takes its name.
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, file);
+}
+
+// How long a lock is waited for, and when one left behind by a crashed process is taken over.
+/** How long a waiter waits for the lock: past the longest a live holder takes (the token request's timeout), under the staleness rule. */
+export const LOCK_WAIT_MS = 25_000;
+/** A lock older than this is taken over; the token request's timeout stays under it, so a live holder never outlasts it. */
+export const LOCK_STALE_MS = 30_000;
+
+/**
+ * Run `fn` holding the credentials lock, so only one process refreshes at a time. A lock
+ * older than any refresh takes is a crashed process's, and is taken over. The lock file holds
+ * its owner's token, and the release removes the file only while it still holds that token,
+ * so a holder that outlived the staleness rule never deletes the lock of whoever took over.
+ */
+export async function withCredentialsLock(fn, env = process.env) {
+  mkdirSync(configDir(env), { recursive: true, mode: 0o700 });
+  const lock = `${credentialsFile(env)}.lock`;
+  const deadline = Date.now() + LOCK_WAIT_MS;
+  const token = `${process.pid}:${randomBytes(8).toString("hex")}`;
+  let held = false;
+  while (!held) {
+    try {
+      const fd = openSync(lock, "wx", 0o600);
+      try {
+        writeFileSync(fd, token);
+      } finally {
+        closeSync(fd);
+      }
+      held = true;
+    } catch (err) {
+      if (err?.code !== "EEXIST") {
+        throw err;
+      }
+      let age = 0;
+      let seen;
+      try {
+        seen = readFileSync(lock, "utf8");
+        age = Date.now() - statSync(lock).mtimeMs;
+      } catch {
+        continue; // released between the open and the read: try again
+      }
+      if (age > LOCK_STALE_MS) {
+        // Remove it only if it is still the lock we judged stale: another waiter may have
+        // taken it over since, and its fresh lock is not ours to delete.
+        let now;
+        try {
+          now = readFileSync(lock, "utf8");
+        } catch {
+          continue;
+        }
+        if (now === seen) {
+          rmSync(lock, { force: true });
+        }
+      } else if (Date.now() > deadline) {
+        throw new Error(
+          `Another kestrel command has held ${lock} for ${Math.round(LOCK_WAIT_MS / 1000)} seconds. It may still be running; try again in a minute. A lock left by a crashed command clears itself after ${Math.round(LOCK_STALE_MS / 1000)} seconds.`,
+        );
+      } else {
+        await new Promise((resolve) => setTimeout(resolve, 50));
+      }
+    }
+  }
+  try {
+    return await fn();
+  } finally {
+    let owner;
+    try {
+      owner = readFileSync(lock, "utf8");
+    } catch {
+      // already gone: nothing of ours to remove
+    }
+    if (owner === token) {
+      rmSync(lock, { force: true });
+    }
+  }
+}

package/cli/dev-api.mjs

@@ -68,12 +68,18 @@ export function ownsServer(target, reportedId) {
 /**
  * The dev server to act on and a local admin token for it, `{ base, token }`, or exit saying
  * why there is none to act on (see `chooseTarget`). `arg` is the command's port or URL
- * argument, if any; `tag` names the command, as in `npm run <tag>`.
+ * argument, if any; `tag` names the command, as in `npm run <tag>`. `kind` is the token's
+ * principal: `service` for a script, as seed and reset are, and `human` for a person working
+ * through a client, as `kestrel api` is (SPEC §11, Who acted).
  */
-export async function devTarget(arg, tag) {
+export async function devTarget(arg, tag, kind = "service") {
   const target = chooseTarget({ arg, record: readDevServer() });
+  const naming =
+    tag === "api"
+      ? "`npx kestrel api --url http://localhost:<port> …`"
+      : `\`npm run ${tag} -- <port>\``;
   const deliberately = [
-    `To act on a server deliberately, name its port: \`npm run ${tag} -- <port>\`.`,
+    `To act on a server deliberately, name its port: ${naming}.`,
     ...(process.env.PORT
       ? [
           `(PORT=${process.env.PORT} is set, but PORT doesn't name a target here: a shell can carry it unawares.)`,
@@ -88,7 +94,7 @@ export async function devTarget(arg, tag) {
       ...deliberately,
     );
   }
-  const { token, runId } = await devToken(target.base, tag);
+  const { token, runId } = await devToken(target.base, tag, kind);
   if (!ownsServer(target, runId)) {
     fail(
       tag,
@@ -101,7 +107,7 @@ export async function devTarget(arg, tag) {
     );
   }
   if (target.explicit) {
-    console.log(`[${tag}] acting on ${target.base}, as named`);
+    console.error(`[${tag}] acting on ${target.base}, as named`);
   }
   return { base: target.base, token };
 }
@@ -116,13 +122,13 @@ export function fail(tag, ...lines) {
   process.exit(1);
 }
 
-/** Mint a local admin token, a `service` principal as Claude is in production, with the run
- *  ID the server reports (undefined when it reports none), as `{ token, runId }`, or exit
- *  saying why the server can't give one. */
-async function devToken(base, tag) {
+/** Mint a local admin token for a principal of `kind`, with the run ID the server reports
+ *  (undefined when it reports none), as `{ token, runId }`, or exit saying why the server
+ *  can't give one. */
+async function devToken(base, tag, kind) {
   let res;
   try {
-    res = await fetch(`${base}/api/dev/token?kind=service`);
+    res = await fetch(`${base}/api/dev/token?kind=${kind}`);
   } catch (err) {
     fail(
       tag,

package/cli/login.mjs

@@ -0,0 +1,155 @@
+/*
+ * `kestrel login` and `kestrel logout`: sign this computer in to a deployed instance as the
+ * person at it, through Cloudflare Access's Managed OAuth, and forget that sign-in again.
+ *
+ * The person approves the sign-in in their browser, through the same Access policy the
+ * editor's sign-in passes, so Claude Code working through `kestrel api` afterwards is that
+ * person, not a token of its own (SPEC §11). The OAuth steps are cli/oauth.mjs, and where
+ * the result is kept is cli/credentials.mjs.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { signedInFetch } from "./api.mjs";
+import { credentialsFile, readSignIn, readSignIns, writeSignIn } from "./credentials.mjs";
+import {
+  authorizeUrl,
+  DEFAULT_CLIENT,
+  discover,
+  exchangeCode,
+  instanceOrigin,
+  isLoopback,
+  listenForCode,
+  PROTECTED_PATH,
+  pkcePair,
+  registerClient,
+  revokeTokens,
+  SignInError,
+  tokenFields,
+} from "./oauth.mjs";
+import { unauthorizedMove } from "./openapi.mjs";
+
+/** Open `url` in the person's browser, best effort: the URL is printed either way. */
+function openBrowser(url) {
+  const [command, args] =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", '""', url.replace(/&/g, "^&")]]
+        : ["xdg-open", [url]];
+  try {
+    const child = spawn(command, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+  } catch {
+    /* no browser to open: the printed URL still works */
+  }
+}
+
+/** Sign in to `origin`, store the result, and answer who it signed in as. */
+export async function signIn(origin, { browser }) {
+  const found = await discover(origin);
+  const stored = readSignIn(origin);
+  // A client registered for this computer is reused while its redirect can be served again,
+  // so a sign-in doesn't leave a new registration in Access each time.
+  const reuse =
+    stored?.client_id && stored.registration_endpoint === found.registration_endpoint
+      ? stored
+      : undefined;
+  const state = randomBytes(16).toString("base64url");
+  const listener = await listenForCode({
+    port: reuse ? Number(new URL(reuse.redirect_uri).port) : undefined,
+    state,
+  });
+  try {
+    const clientId =
+      reuse && reuse.redirect_uri === listener.redirectUri
+        ? reuse.client_id
+        : await registerClient(found.registration_endpoint, listener.redirectUri);
+    const entry = { ...found, client_id: clientId, redirect_uri: listener.redirectUri };
+    const { verifier, challenge } = pkcePair();
+    const url = authorizeUrl({
+      endpoint: found.authorization_endpoint,
+      clientId,
+      redirectUri: listener.redirectUri,
+      challenge,
+      state,
+      resource: found.resource,
+    });
+    console.log(`Approve the sign-in to ${origin} in your browser.`);
+    console.log(`If it didn't open, go to:\n\n  ${url}\n`);
+    if (browser) {
+      openBrowser(url);
+    }
+    const code = await listener.code;
+    const fields = tokenFields(await exchangeCode(entry, { code, verifier }));
+    await writeSignIn(origin, { ...entry, ...fields });
+  } finally {
+    listener.close();
+  }
+  const res = await signedInFetch(origin, PROTECTED_PATH, { client: DEFAULT_CLIENT });
+  const body = await res.json().catch(() => null);
+  if (!res.ok) {
+    const move = unauthorizedMove(body);
+    throw new SignInError(
+      move
+        ? `Signed in to Access, but ${origin}${PROTECTED_PATH} answered ${res.status} (${body.reason}). ${move}.`
+        : `Signed in to Access, but ${origin}${PROTECTED_PATH} answered ${res.status}${body?.message ? `: ${body.message}` : ""}.`,
+    );
+  }
+  return body?.principal;
+}
+
+/** `kestrel login <url> [--no-browser]`. */
+export async function loginCommand(argv) {
+  const browser = !argv.includes("--no-browser");
+  const urls = argv.filter((a) => a !== "--no-browser");
+  try {
+    if (urls.length !== 1) {
+      throw new SignInError("Usage: kestrel login <url> [--no-browser]");
+    }
+    const origin = instanceOrigin(urls[0]);
+    if (isLoopback(origin)) {
+      throw new SignInError(
+        "A local dev server needs no sign-in: `npx kestrel api --local …` calls it as you.",
+      );
+    }
+    const principal = await signIn(origin, { browser });
+    const who = principal?.email ?? principal?.kind ?? "someone";
+    console.log(`Signed in to ${origin} as ${who}.`);
+    console.log(
+      `Stored in ${credentialsFile()}. \`npx kestrel api GET /api/posts\` calls it as you.`,
+    );
+  } catch (err) {
+    console.error(`kestrel login: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+/** `kestrel logout [url]`: revoke and forget one sign-in, or the only one stored. */
+export async function logoutCommand(argv) {
+  try {
+    const origins = Object.keys(readSignIns());
+    const origin = argv[0] ? instanceOrigin(argv[0]) : origins.length === 1 ? origins[0] : null;
+    if (!origin) {
+      throw new SignInError(
+        origins.length
+          ? `You're signed in to ${origins.join(", ")}. Name the one to sign out of.`
+          : "You aren't signed in to any instance.",
+      );
+    }
+    const entry = readSignIn(origin);
+    if (!entry) {
+      throw new SignInError(`You aren't signed in to ${origin}.`);
+    }
+    const revoked = await revokeTokens(entry);
+    await writeSignIn(origin, undefined);
+    console.log(
+      revoked
+        ? `Signed out of ${origin}, and Access revoked the sign-in.`
+        : `Signed out of ${origin} on this computer. Access didn't confirm revoking it; it ends with the Access application's grant session.`,
+    );
+  } catch (err) {
+    console.error(`kestrel logout: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}