@blocofy/cli 0.14.0 → 0.16.0

package/lib/loopback.mjs

@@ -0,0 +1,111 @@
+import { createServer } from "node:http";
+
+/**
+ * ADR-0014 §5.1/§5.2 (wave P4) — the browser login's loopback redirect (RFC 8252 §7.3).
+ *
+ * The CLI listens on `127.0.0.1` (or `[::1]`) on an ephemeral port and registers `http://<host>:<port>/callback`.
+ * `localhost` is refused (RFC 8252 §8.3: it may not resolve to the loopback), as the platform refuses it. Exactly one
+ * GET `/callback` is accepted; every other path is 404 and does not end the wait. The listener closes after that one
+ * callback or after the timeout (5 minutes by default). The page it answers never echoes the code.
+ */
+
+export const CALLBACK_PATH = "/callback";
+export const LOGIN_TIMEOUT_MS = 5 * 60_000;
+const HOSTS = new Set(["127.0.0.1", "::1"]);
+
+export class LoopbackError extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "LoopbackError";
+    this.code = code;
+    this.exitCode = 1;
+  }
+}
+
+/** The redirect URI for `host` + `port`, or LOGIN_LOOPBACK_REFUSED (anything but 127.0.0.1 / ::1, a port < 1024). */
+export function loopbackRedirectUri(host, port) {
+  if (!HOSTS.has(host)) {
+    throw new LoopbackError("LOGIN_LOOPBACK_REFUSED", `The login callback must listen on 127.0.0.1 or [::1], not "${host}" (localhost is not accepted: it may not resolve to this machine).`);
+  }
+  if (!Number.isInteger(port) || port < 1024 || port > 65535) {
+    throw new LoopbackError("LOGIN_LOOPBACK_REFUSED", `The login callback port must be between 1024 and 65535 (got ${port}).`);
+  }
+  return `http://${host === "::1" ? "[::1]" : host}:${port}${CALLBACK_PATH}`;
+}
+
+/** The platform's rule for the first-party client's redirect, mirrored (canonical form, exact path, no query). */
+export function isLoopbackCallback(uri) {
+  let url;
+  try {
+    url = new URL(uri);
+  } catch {
+    return false;
+  }
+  if (url.href !== uri || url.protocol !== "http:" || url.username || url.password || url.search || url.hash) return false;
+  if (url.hostname !== "127.0.0.1" && url.hostname !== "[::1]") return false;
+  const port = Number(url.port);
+  return url.pathname === CALLBACK_PATH && url.port !== "" && port >= 1024 && port <= 65535;
+}
+
+const PAGE = (ok) =>
+  `<!doctype html><html lang="tr"><meta charset="utf-8"><title>Blocofy CLI</title><body style="font-family:system-ui;margin:3rem">` +
+  (ok
+    ? "<h1>Blocofy CLI</h1><p>Tarayıcı adımı tamamlandı. Bu sekmeyi kapatıp terminale dönebilirsin.</p><p>The browser step is done; you can close this tab and return to the terminal.</p>"
+    : "<h1>Blocofy CLI</h1><p>Bu adres bir giriş yanıtı değil.</p>") +
+  "</body></html>";
+
+/**
+ * Listen on `host` (127.0.0.1 | ::1). Returns `{ redirectUri, wait(), close() }`: `wait()` resolves with the
+ * callback's URLSearchParams (the first GET /callback) or rejects LOGIN_TIMEOUT; the server is closed either way.
+ */
+export async function startLoopbackListener({ host = "127.0.0.1", timeoutMs = LOGIN_TIMEOUT_MS } = {}) {
+  if (!HOSTS.has(host)) loopbackRedirectUri(host, 1024); // throws LOGIN_LOOPBACK_REFUSED
+  let settle;
+  const result = new Promise((resolve, reject) => {
+    settle = { resolve, reject };
+  });
+  result.catch(() => {}); // observed through wait()
+  let done = false;
+  const server = createServer((req, res) => {
+    const url = new URL(req.url ?? "/", "http://loopback");
+    if (done || req.method !== "GET" || url.pathname !== CALLBACK_PATH) {
+      res.writeHead(404, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store" });
+      res.end(PAGE(false));
+      return;
+    }
+    done = true;
+    res.writeHead(200, { "content-type": "text/html; charset=utf-8", "cache-control": "no-store", connection: "close" });
+    res.end(PAGE(true));
+    finish(() => settle.resolve(url.searchParams));
+  });
+  let timer = null;
+  const finish = (fn) => {
+    clearTimeout(timer);
+    server.close();
+    server.closeAllConnections?.();
+    fn();
+  };
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, host, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+  const redirectUri = loopbackRedirectUri(host, server.address().port);
+  timer = setTimeout(() => {
+    if (done) return;
+    done = true;
+    finish(() => settle.reject(new LoopbackError("LOGIN_TIMEOUT", `No answer from the browser within ${Math.round(timeoutMs / 1000)} s; the login was not completed. Nothing was saved. Run \`blocofy login\` again.`)));
+  }, timeoutMs);
+  timer.unref?.();
+  return {
+    redirectUri,
+    wait: () => result,
+    close() {
+      if (done) return;
+      done = true;
+      finish(() => settle.reject(new LoopbackError("LOGIN_CANCELLED", "The login was cancelled.")));
+    },
+  };
+}

package/lib/media-uses.mjs

@@ -20,11 +20,13 @@
 import { fetchWithRetry } from "./http.mjs";
 
 export const API_KEY_PREFIX = "blcf_live_";
+/** ADR-0014 §3.2: a profiled API key (`theme-dev` / `review` / `service-ci` / `full`) starts with `blcf_k2_`. */
+export const API_KEY_PREFIXES = [API_KEY_PREFIX, "blcf_k2_"];
 export const DEFAULT_API_URL = "https://app.blocofy.com";
 
-/** v1 accepts ONLY a live API key. Never echo the key back in a message. */
+/** A pasted v1 API key (`blcf_live_` or `blcf_k2_`; never a CLI login token `blcf_ct_`). Never echo the key back. */
 export function isValidApiKey(key) {
-  return typeof key === "string" && key.startsWith(API_KEY_PREFIX) && key.length > API_KEY_PREFIX.length;
+  return typeof key === "string" && API_KEY_PREFIXES.some((p) => key.startsWith(p) && key.length > p.length);
 }
 
 /** A 4xx response from v1: `status` + the server's `error` object ({ code, message, details? }). */

package/lib/oauth.mjs

@@ -0,0 +1,295 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+
+import { fetchWithRetry } from "./http.mjs";
+import { isLoopbackCallback, startLoopbackListener } from "./loopback.mjs";
+
+/**
+ * ADR-0014 §5 (wave P4) — `blocofy login`: the system browser, Authorization Code + PKCE S256, loopback redirect.
+ *
+ *   1. Discovery: `GET <origin>/.well-known/oauth-authorization-server`. The issuer must be the origin itself, the
+ *      token/revocation endpoints on it; S256 and RFC 9207 `iss` must be supported (an older platform is refused).
+ *   2. Loopback listener (127.0.0.1 or [::1], ephemeral port, exact /callback), `state` and the PKCE verifier are 32
+ *      random bytes. The browser opens `/authorize?…&resource=<origin>/api/v1` (no scope: the platform pre-checks the
+ *      draft profile's). The URL carries no secret.
+ *   3. The callback must carry `iss` = the metadata issuer and our `state`; only then is its code looked at.
+ *   4. `/token` (authorization_code): the verifier + the same `resource`. Never retried (a code is single-use). The
+ *      answer must be a CLI token (`blcf_ct_`, audience `cli`).
+ *   5. Success = the canonical identity probe `GET /api/v1/ping` (site + profile + audience `cli`), not a config write.
+ * Anything that fails after the code exchange revokes the new login (best effort), so no half-made grant is left.
+ */
+
+export const CLI_CLIENT_ID = "blocofy-cli";
+export const CLI_TOKEN_PREFIX = "blcf_ct_";
+const REQUEST_TIMEOUT_MS = 10_000;
+
+export class LoginError extends Error {
+  constructor(code, message, details = {}, exitCode = 1) {
+    super(message);
+    this.name = "LoginError";
+    this.code = code;
+    this.details = details;
+    this.exitCode = exitCode;
+  }
+}
+
+const b64url = (buf) => Buffer.from(buf).toString("base64url");
+const stripSlash = (u) => String(u).replace(/\/+$/, "");
+
+export function createPkce() {
+  const verifier = b64url(randomBytes(32));
+  return { verifier, challenge: b64url(createHash("sha256").update(verifier).digest()), method: "S256" };
+}
+
+export const newState = () => b64url(randomBytes(32));
+
+const sameString = (a, b) => {
+  const x = Buffer.from(String(a ?? ""));
+  const y = Buffer.from(String(b ?? ""));
+  return x.length === y.length && timingSafeEqual(x, y);
+};
+
+/** https, or http on a loopback address (a local development platform). */
+function acceptableOrigin(origin) {
+  let u;
+  try {
+    u = new URL(origin);
+  } catch {
+    return false;
+  }
+  if (u.protocol === "https:") return true;
+  return u.protocol === "http:" && (u.hostname === "127.0.0.1" || u.hostname === "[::1]" || u.hostname === "localhost");
+}
+
+/** The resource indicator (RFC 8707) of the CLI audience. */
+export const cliResource = (origin) => `${stripSlash(origin)}/api/v1`;
+
+/** RFC 8414 discovery with the checks above. */
+export async function discoverMetadata(origin, { fetchImpl = globalThis.fetch } = {}) {
+  const base = stripSlash(origin);
+  if (!acceptableOrigin(base)) throw new LoginError("LOGIN_DISCOVERY_FAILED", `The platform address must be https:// (got ${base}). Nothing was sent.`);
+  let res;
+  try {
+    res = await fetchWithRetry(`${base}/.well-known/oauth-authorization-server`, { headers: { accept: "application/json" } }, { fetchImpl, timeoutMs: REQUEST_TIMEOUT_MS, retries: 1 });
+  } catch (error) {
+    throw new LoginError("LOGIN_DISCOVERY_FAILED", `Could not reach ${base} (${error?.name === "TimeoutError" ? "timeout" : "network error"}). Nothing was saved.`);
+  }
+  let meta = null;
+  try {
+    meta = res.ok ? await res.json() : null;
+  } catch {
+    meta = null;
+  }
+  if (!meta || typeof meta !== "object") throw new LoginError("LOGIN_DISCOVERY_FAILED", `${base} did not answer the login discovery (HTTP ${res.status}). Nothing was saved.`);
+  if (meta.issuer !== base) {
+    throw new LoginError("LOGIN_ISSUER_MISMATCH", `The platform at ${base} names another issuer (${meta.issuer}); the login was refused. Nothing was saved.`, { issuer: meta.issuer ?? null });
+  }
+  for (const key of ["authorization_endpoint", "token_endpoint", "revocation_endpoint"]) {
+    const v = meta[key];
+    if (v === undefined && key === "revocation_endpoint") continue;
+    let u;
+    try {
+      u = new URL(v);
+    } catch {
+      u = null;
+    }
+    if (!u || u.origin !== new URL(base).origin) {
+      throw new LoginError("LOGIN_ISSUER_MISMATCH", `The platform's ${key} is not on ${base}; the login was refused. Nothing was saved.`, { [key]: v ?? null });
+    }
+  }
+  if (!Array.isArray(meta.code_challenge_methods_supported) || !meta.code_challenge_methods_supported.includes("S256") || meta.authorization_response_iss_parameter_supported !== true) {
+    throw new LoginError(
+      "LOGIN_UNSUPPORTED_PLATFORM",
+      `The platform at ${base} does not support the CLI browser login yet (PKCE S256 + RFC 9207 iss). Nothing was saved. Use the advanced login: blocofy login --token (dev token) or blocofy login --api-key.`,
+    );
+  }
+  return { issuer: meta.issuer, authorization_endpoint: meta.authorization_endpoint, token_endpoint: meta.token_endpoint, revocation_endpoint: meta.revocation_endpoint ?? null };
+}
+
+export function authorizeUrl(meta, { redirectUri, challenge, state, resource, clientId = CLI_CLIENT_ID }) {
+  const u = new URL(meta.authorization_endpoint);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("client_id", clientId);
+  u.searchParams.set("redirect_uri", redirectUri);
+  u.searchParams.set("code_challenge", challenge);
+  u.searchParams.set("code_challenge_method", "S256");
+  u.searchParams.set("state", state);
+  u.searchParams.set("resource", resource);
+  return u.toString();
+}
+
+/** RFC 9207 first (also on error answers), then state, then the answer itself. Returns the code. */
+export function validateCallback(params, { issuer, state }) {
+  if (!params.has("iss") || !sameString(params.get("iss"), issuer)) {
+    throw new LoginError("LOGIN_ISS_MISMATCH", "The browser answer did not come from this platform (iss mismatch); the login was refused. Nothing was saved.");
+  }
+  if (!sameString(params.get("state"), state)) {
+    throw new LoginError("LOGIN_STATE_MISMATCH", "The browser answer does not belong to this login (state mismatch); the login was refused. Nothing was saved.");
+  }
+  const error = params.get("error");
+  if (error) {
+    throw new LoginError(
+      "LOGIN_DENIED",
+      error === "access_denied" ? "The login was not approved in the browser. Nothing was saved." : `The platform refused the login (${error}). Nothing was saved.`,
+      { error },
+    );
+  }
+  const code = params.get("code");
+  if (!code) throw new LoginError("LOGIN_DENIED", "The browser answer carried no authorization code. Nothing was saved.");
+  return code;
+}
+
+async function postForm(url, fields, { fetchImpl, timeoutMs = REQUEST_TIMEOUT_MS }) {
+  const res = await fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+    body: new URLSearchParams(fields).toString(),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  const text = await res.text().catch(() => "");
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = null;
+  }
+  return { res, json };
+}
+
+/** The code exchange. Never retried (a resend of a spent code makes the platform revoke what it issued). */
+export async function exchangeCode(meta, { code, verifier, redirectUri, resource, clientId = CLI_CLIENT_ID, fetchImpl = globalThis.fetch, now = Date.now }) {
+  let out;
+  try {
+    out = await postForm(meta.token_endpoint, { grant_type: "authorization_code", code, redirect_uri: redirectUri, client_id: clientId, code_verifier: verifier, resource }, { fetchImpl });
+  } catch (error) {
+    throw new LoginError("LOGIN_TOKEN_FAILED", `The platform did not answer the login's code exchange (${error?.name === "TimeoutError" ? "timeout" : "network error"}). Nothing was saved; run \`blocofy login\` again.`);
+  }
+  const { res, json } = out;
+  if (!res.ok || !json) {
+    throw new LoginError("LOGIN_TOKEN_FAILED", `The platform refused the login's code exchange (${json?.error ?? `HTTP ${res.status}`}). Nothing was saved; run \`blocofy login\` again.`, { error: json?.error ?? null, status: res.status });
+  }
+  const tokens = {
+    access_token: typeof json.access_token === "string" ? json.access_token : null,
+    refresh_token: typeof json.refresh_token === "string" && json.refresh_token ? json.refresh_token : null,
+    expires_at: now() + Number(json.expires_in) * 1000,
+  };
+  return { tokens, tokenType: json.token_type ?? null };
+}
+
+/**
+ * RFC 7009 revocation: `revoked` (HTTP 200 — the platform answers 200 for an unknown or already revoked token too),
+ * `refused` (another 4xx/5xx answer: NOT revoked), `unreachable` (network/timeout: NOT revoked).
+ */
+export async function revokeToken({ endpoint, token, clientId = CLI_CLIENT_ID, fetchImpl = globalThis.fetch, timeoutMs = REQUEST_TIMEOUT_MS }) {
+  try {
+    const { res } = await postForm(endpoint, { token, client_id: clientId }, { fetchImpl, timeoutMs });
+    if (res.status === 200) return { outcome: "revoked", status: 200 };
+    return { outcome: res.status >= 500 ? "unreachable" : "refused", status: res.status };
+  } catch {
+    return { outcome: "unreachable", status: null };
+  }
+}
+
+/** The canonical identity probe (`GET /api/v1/ping`) of a CLI token: site + profile + audience `cli`. */
+export async function probeIdentity(origin, accessToken, { fetchImpl = globalThis.fetch, onRetry = null } = {}) {
+  let res;
+  try {
+    res = await fetchWithRetry(`${stripSlash(origin)}/api/v1/ping`, { headers: { authorization: `Bearer ${accessToken}`, accept: "application/json" } }, { fetchImpl, timeoutMs: 15_000, onRetry });
+  } catch (error) {
+    throw new LoginError("LOGIN_IDENTITY_UNVERIFIED", `Could not confirm the new login with the platform (${error?.name === "TimeoutError" ? "timeout" : "network error"}). Nothing was saved.`);
+  }
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {
+    body = null;
+  }
+  if (!res.ok || !body || typeof body !== "object") {
+    const code = body?.error?.code ?? null;
+    throw new LoginError(code === "audience_mismatch" ? "LOGIN_AUDIENCE_MISMATCH" : "LOGIN_IDENTITY_UNVERIFIED", `The platform did not confirm the new login (${code ?? `HTTP ${res.status}`}). Nothing was saved.`, { server_code: code, status: res.status });
+  }
+  const site = body.site;
+  if (!site || typeof site !== "object" || !(typeof site.id === "string" || Number.isFinite(site.id))) {
+    throw new LoginError("LOGIN_IDENTITY_UNVERIFIED", "The platform's identity answer names no site. Nothing was saved.");
+  }
+  if (body.audience !== "cli") {
+    throw new LoginError("LOGIN_AUDIENCE_MISMATCH", `The new login is not a CLI login (audience ${body.audience ?? "missing"}); it was refused. Nothing was saved.`, { audience: body.audience ?? null });
+  }
+  const p = body.profile;
+  if (!p || typeof p !== "object" || typeof p.id !== "string") {
+    throw new LoginError("LOGIN_UNSUPPORTED_PLATFORM", "The platform does not report the login's profile (it is older than the CLI login). Nothing was saved. Use the advanced login: blocofy login --token.");
+  }
+  let devUrl = null;
+  if (typeof body.dev_endpoint === "string") {
+    try {
+      const u = new URL(body.dev_endpoint);
+      if ((u.protocol === "https:" || u.protocol === "http:") && /\/api\/dev\/?$/.test(u.pathname)) devUrl = `${u.origin}${u.pathname.replace(/\/api\/dev\/?$/, "")}`;
+    } catch {
+      devUrl = null;
+    }
+  }
+  return {
+    site: { id: site.id, slug: typeof site.slug === "string" ? site.slug : null, name: typeof site.name === "string" ? site.name : null, domain: typeof site.domain === "string" ? site.domain : null },
+    platformOrigin: typeof body.platform_origin === "string" && body.platform_origin ? body.platform_origin : null,
+    profile: { id: p.id, version: Number.isInteger(p.version) ? p.version : null, label: typeof p.label === "string" ? p.label : null },
+    audience: body.audience,
+    devUrl,
+    policyVersion: body.policy_version ?? null,
+  };
+}
+
+/**
+ * The whole browser login. `openBrowser(url)` opens the system browser (may throw: the URL is printed anyway);
+ * `print(line)` writes a progress line (stderr). Returns `{ tokens, identity, metadata }`.
+ */
+export async function runBrowserLogin({ origin, openBrowser, print = () => {}, fetchImpl = globalThis.fetch, callbackHost = "127.0.0.1", timeoutMs, onRetry = null }) {
+  const base = stripSlash(origin);
+  // The loopback rule is checked before any request (localhost refused).
+  const listenerOpts = { host: callbackHost, ...(timeoutMs ? { timeoutMs } : {}) };
+  if (callbackHost !== "127.0.0.1" && callbackHost !== "::1") await startLoopbackListener(listenerOpts); // throws
+  const metadata = await discoverMetadata(base, { fetchImpl });
+  const pkce = createPkce();
+  const state = newState();
+  const resource = cliResource(base);
+  let listener;
+  try {
+    listener = await startLoopbackListener(listenerOpts);
+  } catch (error) {
+    if (error?.code === "LOGIN_LOOPBACK_REFUSED") throw error;
+    if (callbackHost !== "127.0.0.1") throw new LoginError("LOGIN_LOOPBACK_UNAVAILABLE", `Could not listen on ${callbackHost} for the login callback. Nothing was saved.`);
+    try {
+      listener = await startLoopbackListener({ ...listenerOpts, host: "::1" }); // 127.0.0.1 unavailable: the IPv6 loopback
+    } catch {
+      throw new LoginError("LOGIN_LOOPBACK_UNAVAILABLE", "Could not listen on the loopback address for the login callback. Nothing was saved.");
+    }
+  }
+  if (!isLoopbackCallback(listener.redirectUri)) {
+    listener.close();
+    throw new LoginError("LOGIN_LOOPBACK_REFUSED", "The login callback address is not a loopback address. Nothing was saved.");
+  }
+  const url = authorizeUrl(metadata, { redirectUri: listener.redirectUri, challenge: pkce.challenge, state, resource });
+  print(url);
+  try {
+    await openBrowser(url);
+  } catch {
+    /* the URL is printed: the user opens it by hand */
+  }
+  const params = await listener.wait();
+  const code = validateCallback(params, { issuer: metadata.issuer, state });
+  const { tokens } = await exchangeCode(metadata, { code, verifier: pkce.verifier, redirectUri: listener.redirectUri, resource, fetchImpl });
+
+  const abandon = async (error) => {
+    const token = tokens.refresh_token ?? tokens.access_token;
+    if (token && metadata.revocation_endpoint) await revokeToken({ endpoint: metadata.revocation_endpoint, token, fetchImpl });
+    throw error;
+  };
+  if (!tokens.access_token || !tokens.access_token.startsWith(CLI_TOKEN_PREFIX) || !Number.isFinite(tokens.expires_at)) {
+    return abandon(new LoginError("LOGIN_AUDIENCE_MISMATCH", "The platform answered with a token that is not a CLI login token; it was not used and the new connection was revoked. Nothing was saved."));
+  }
+  let identity;
+  try {
+    identity = await probeIdentity(base, tokens.access_token, { fetchImpl, onRetry });
+  } catch (error) {
+    return abandon(error);
+  }
+  return { tokens, identity, metadata, abandon };
+}

package/lib/refresh.mjs

@@ -0,0 +1,244 @@
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { homedir, hostname as osHostname } from "node:os";
+import { join } from "node:path";
+
+import { CredentialsError, loadStore, markReauthRequired, readOAuthTokens, writeOAuthTokens } from "./credentials.mjs";
+
+/**
+ * ADR-0014 §5.4 (wave P4) — the CLI login's access token, refreshed single-flight.
+ *
+ * The platform's refresh tokens are single-use: a second presentation of the same token is reuse and closes the whole
+ * login (054). So a refresh is never sent twice and never retried:
+ *   - in one process: one promise per context;
+ *   - across processes: `~/.blocofy/.refresh-<context>.lock` (O_EXCL) holding `{ pid, hostname, acquired_at }`. It is
+ *     stale only when its owner on THIS host is gone (`kill(pid, 0)` → ESRCH) or it is older than 30 s; a live
+ *     holder's lock is never broken before that. The /token request times out after 10 s, far below the staleness,
+ *     so no second process can present the token while the first request is still open.
+ * Under the lock the store is read again: when another process already refreshed (≥ 60 s left) no request is made.
+ * Otherwise ONE /token request; the rotated pair is written atomically before the lock is released.
+ *
+ *   error_description "refresh_token_reused" → the context is marked `reauth_required`; no retry (the platform's
+ *       (any status)                            explicit "this refresh token is spent" signal; checked first)
+ *   invalid_grant (reuse, revoked, expired)  → the same
+ *   503 without Retry-After (presentation    → the same (fallback heuristic for platforms without the signal)
+ *       recorded, nothing minted)
+ *   503 with Retry-After, network, timeout   → REFRESH_FAILED (temporary); the login is kept; no retry here
+ */
+
+export const TOKEN_REQUEST_TIMEOUT_MS = 10_000;
+export const REFRESH_LOCK_STALE_MS = 30_000;
+export const REFRESH_MIN_VALIDITY_MS = 60_000;
+const DEFAULT_WAIT_MS = 45_000;
+const POLL_MS = 50;
+
+export class RefreshError extends CredentialsError {
+  constructor(code, message, details = {}) {
+    super(code, message, details);
+    this.name = "RefreshError";
+  }
+}
+
+const reauth = (name, why, reason = why) =>
+  new RefreshError(
+    "REAUTH_REQUIRED",
+    `The CLI login of context "${name}" can no longer be renewed (${why}). Nothing was sent. Log in again: blocofy login --context ${name}`,
+    { context: name, reason },
+  );
+
+/** The platform's explicit signal that a presented refresh token is spent (single-use, 054). */
+export const REFRESH_REUSED = "refresh_token_reused";
+
+export const refreshLockPath = (name, home = homedir()) => join(home, ".blocofy", `.refresh-${name}.lock`);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function alive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error?.code !== "ESRCH"; // EPERM: it exists, owned by someone else
+  }
+}
+
+/** Is the lock at `path` stale? Unreadable content falls back to the file's age. */
+function lockIsStale(path, now, host) {
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return { stale: false, raw: null }; // released meanwhile: just try again
+  }
+  let holder = null;
+  try {
+    holder = JSON.parse(raw);
+  } catch {
+    holder = null;
+  }
+  const acquired = holder ? Date.parse(holder.acquired_at) : NaN;
+  let age;
+  if (Number.isFinite(acquired)) age = now - acquired;
+  else {
+    try {
+      age = now - statSync(path).mtimeMs;
+    } catch {
+      return { stale: false, raw: null };
+    }
+  }
+  if (age > REFRESH_LOCK_STALE_MS) return { stale: true, raw };
+  if (holder && holder.hostname === host && Number.isInteger(holder.pid) && !alive(holder.pid)) return { stale: true, raw };
+  return { stale: false, raw };
+}
+
+/** Take the cross-process lock or throw REFRESH_BUSY after `waitMs`. Returns a release() that only removes OUR lock. */
+async function acquireLock(path, { waitMs, host, pid }) {
+  mkdirSync(join(path, ".."), { recursive: true, mode: 0o700 });
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    const mine = JSON.stringify({ pid, hostname: host, acquired_at: new Date().toISOString() });
+    try {
+      const fd = openSync(path, "wx", 0o600);
+      writeSync(fd, mine);
+      closeSync(fd);
+      return () => {
+        try {
+          if (readFileSync(path, "utf8") === mine) rmSync(path, { force: true });
+        } catch {
+          /* already gone */
+        }
+      };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+    const { stale, raw } = lockIsStale(path, Date.now(), host);
+    if (stale) {
+      // Remove only the lock we judged stale (a new holder that replaced it meanwhile is left alone).
+      try {
+        if (readFileSync(path, "utf8") === raw) rmSync(path, { force: true });
+      } catch {
+        /* gone */
+      }
+      continue;
+    }
+    if (Date.now() > deadline) {
+      throw new RefreshError("REFRESH_BUSY", `Another blocofy command is renewing this login and has not finished. Nothing was sent; try again in a moment (the lock frees itself after ${REFRESH_LOCK_STALE_MS / 1000} s).`, { lock: path });
+    }
+    await sleep(POLL_MS);
+  }
+}
+
+const fresh = (tokens, now, min) => tokens && Number.isFinite(tokens.expires_at) && tokens.expires_at - now >= min;
+
+/** One /token request (refresh_token grant). Never retried. */
+async function presentRefresh({ endpoint, refreshToken, clientId, resource, fetchImpl, timeoutMs }) {
+  const body = new URLSearchParams({ grant_type: "refresh_token", refresh_token: refreshToken, client_id: clientId, resource });
+  let res;
+  try {
+    res = await fetchImpl(endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded", accept: "application/json" },
+      body: body.toString(),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    return { kind: "unknown", reason: error?.name === "TimeoutError" ? "timeout" : "network error" };
+  }
+  const text = await res.text().catch(() => "");
+  let json = null;
+  try {
+    json = JSON.parse(text);
+  } catch {
+    json = null;
+  }
+  if (res.ok) return { kind: "ok", json };
+  if (json?.error_description === REFRESH_REUSED) return { kind: "reused" };
+  if (res.status === 400 && (json?.error === "invalid_grant" || json?.error === "invalid_target" || json?.error === "unauthorized_client")) return { kind: "refused", error: json.error };
+  if (res.status === 401 && json?.error === "invalid_client") return { kind: "refused", error: "invalid_client" };
+  if (res.status === 503 && !res.headers.get("retry-after")) return { kind: "spent" };
+  return { kind: "temporary", status: res.status };
+}
+
+const inflight = new Map();
+
+/**
+ * The DI core. `source`: `{ read() → tokens|null, write(tokens), needsReauth() → bool, markReauth() }`;
+ * `endpoint`: `{ tokenEndpoint, clientId, resource }`.
+ */
+export async function freshAccess({ name, source, endpoint, lockPath, fetchImpl = globalThis.fetch, now = Date.now, requestTimeoutMs = TOKEN_REQUEST_TIMEOUT_MS, waitMs = DEFAULT_WAIT_MS, minValidityMs = REFRESH_MIN_VALIDITY_MS, host = osHostname(), pid = process.pid }) {
+  if (source.needsReauth()) throw reauth(name, "a previous renewal was refused");
+  const first = source.read();
+  if (!first) throw reauth(name, "no saved login");
+  if (fresh(first, now(), minValidityMs)) return first.access_token;
+
+  const key = lockPath;
+  if (inflight.has(key)) return inflight.get(key);
+  const run = (async () => {
+    const release = await acquireLock(lockPath, { waitMs, host, pid });
+    try {
+      if (source.needsReauth()) throw reauth(name, "a previous renewal was refused");
+      const tokens = source.read();
+      if (!tokens) throw reauth(name, "no saved login");
+      if (fresh(tokens, now(), minValidityMs)) return tokens.access_token; // another process renewed it
+      if (!tokens.refresh_token) {
+        source.markReauth();
+        throw reauth(name, "the login has no renewal token left");
+      }
+      const r = await presentRefresh({ endpoint: endpoint.tokenEndpoint, refreshToken: tokens.refresh_token, clientId: endpoint.clientId, resource: endpoint.resource, fetchImpl, timeoutMs: requestTimeoutMs });
+      if (r.kind === "ok") {
+        const access = r.json?.access_token;
+        const expiresIn = Number(r.json?.expires_in);
+        if (typeof access !== "string" || !access.startsWith("blcf_ct_") || !Number.isFinite(expiresIn)) {
+          // The presented token is spent; what came back is not a CLI token. Never used, never retried.
+          source.markReauth();
+          throw reauth(name, "the platform answered with an unexpected token");
+        }
+        // Rotation: the new refresh token replaces the spent one. Without one the login ends at this access token.
+        const next = { access_token: access, refresh_token: typeof r.json.refresh_token === "string" && r.json.refresh_token ? r.json.refresh_token : null, expires_at: now() + expiresIn * 1000 };
+        source.write(next);
+        return access;
+      }
+      if (r.kind === "reused") {
+        source.markReauth();
+        throw reauth(name, "its renewal token was already used (refresh_token_reused)", REFRESH_REUSED);
+      }
+      if (r.kind === "refused") {
+        source.markReauth();
+        throw reauth(name, r.error === "invalid_grant" ? "it was revoked, expired, or its renewal token was used twice" : r.error);
+      }
+      if (r.kind === "spent") {
+        source.markReauth();
+        throw reauth(name, "the platform could not complete the renewal and the renewal token is spent");
+      }
+      throw new RefreshError(
+        "REFRESH_FAILED",
+        r.kind === "unknown"
+          ? `Could not renew the CLI login of context "${name}" (${r.reason}). Nothing else was sent. Try again; if the platform reports the login closed, log in again (blocofy login --context ${name}).`
+          : `The platform could not renew the CLI login of context "${name}" right now (HTTP ${r.status}). Nothing else was sent; try again in a moment.`,
+        { context: name, ...(r.status ? { status: r.status } : { reason: r.reason }) },
+      );
+    } finally {
+      release();
+    }
+  })();
+  inflight.set(key, run);
+  try {
+    return await run;
+  } finally {
+    inflight.delete(key);
+  }
+}
+
+/** The access token of a saved CLI-login context (refreshed when needed). `opts` override the DI defaults (tests). */
+export function accessTokenFor(name, opts = {}) {
+  const ctxNow = () => loadStore().contexts[name];
+  const ctx = ctxNow();
+  if (!ctx?.oauth) throw new CredentialsError("LOGIN_REQUIRED", `Context "${name}" is not a CLI login. Run \`blocofy login --context ${name}\`.`, { context: name });
+  const source = {
+    read: () => readOAuthTokens(name, ctxNow() ?? ctx),
+    write: (tokens) => writeOAuthTokens(name, ctx.oauth.secret.store, tokens),
+    needsReauth: () => (ctxNow()?.oauth?.state ?? null) === "reauth_required",
+    markReauth: () => markReauthRequired(name),
+  };
+  const endpoint = { tokenEndpoint: ctx.oauth.token_endpoint, clientId: ctx.oauth.client_id, resource: `${String(ctx.oauth.url).replace(/\/+$/, "")}/api/v1` };
+  return freshAccess({ name, source, endpoint, lockPath: refreshLockPath(name), ...opts });
+}