alexandr 0.2.2 → 0.3.1

package/src/app/reach.js

@@ -0,0 +1,100 @@
+// Reaching the linked workspace's kernel from this laptop — the two lines every
+// `alexandr app` verb that talks to a running box needs, in one place.
+//
+// The CP is the single identity authority (account-required-runtimes.md): a
+// workspace token is minted per command, five-minute TTL, presented as a bearer.
+// A LOCAL-TRUST box (`ALEXANDR_LOCAL_TRUST=1`, the dev source-run kernel) has no
+// CP and nothing to present — a different lane, not a degraded one.
+//
+// ⚠ Lifted from `deploy.js`'s auth block rather than exported from it: that verb
+// owns a build and a packer beside its auth, and importing it to reach a URL
+// would drag `@alexandr/app-build` into a command that writes one HTTP request.
+
+import { fail } from "../util.js";
+import { EXIT } from "../exit.js";
+import { isLocalTrust, readAuth, authUsable } from "./store.js";
+import { ensureWorkspaceToken } from "./token.js";
+import { requireLink } from "./dev.js";
+
+/**
+ * The base URL of the linked workspace and the header to present, or exit with
+ * the reason. Never returns a partial answer.
+ */
+export async function reachWorkspace(project) {
+  const link = requireLink(project);
+  let authorization = null;
+  let runtimeUrl = link.instanceUrl;
+
+  if (!isLocalTrust(link)) {
+    const session = readAuth();
+    if (!authUsable(session, link.cpUrl)) {
+      fail("Your account session has expired. Run `alexandr app link --relink`.", EXIT.GENERAL);
+    }
+    const minted = await ensureWorkspaceToken(link, session, { project, force: true });
+    if (!minted.ok) {
+      if (minted.pending) {
+        fail(`The workspace is ${minted.status} — start it, then try again.`, EXIT.NO_INSTANCE);
+      }
+      fail(`Couldn't get a workspace token: ${minted.error}`, EXIT.GENERAL);
+    }
+    authorization = `Bearer ${minted.token}`;
+    runtimeUrl = minted.url || runtimeUrl;
+  }
+
+  if (!runtimeUrl) {
+    fail("The linked workspace has no URL yet. Start it, then try again.", EXIT.NO_INSTANCE);
+  }
+  return { url: runtimeUrl.replace(/\/+$/, ""), authorization, link };
+}
+
+/** The headers for a reached workspace — `authorization` only when there is one. */
+export const headersFor = (authorization, json = false) => ({
+  ...(json ? { "content-type": "application/json" } : {}),
+  ...(authorization ? { authorization } : {}),
+});
+
+/**
+ * PUT json → `{ data }` / `{ error, status }`, the shape `postJson`/`getJson`
+ * already answer in (consent.js). Written here because the runtime's own JSON
+ * helpers stop at GET and POST.
+ *
+ * ⚠ THE BODY IS WHERE A VALUE GOES. Everything this CLI sends to
+ * `/_kernel/secrets/...` rides here, never in the path and never in a query —
+ * a path is logged by every proxy in front of the box; a body is not.
+ */
+export async function putJson(url, body, headers = {}) {
+  try {
+    const res = await fetch(url, {
+      method: "PUT",
+      headers: { "content-type": "application/json", ...headers },
+      body: JSON.stringify(body),
+    });
+    const data = await res.json().catch(() => null);
+    if (!res.ok) {
+      const detail = typeof data?.error === "string" && data.error ? ` — ${data.error}` : "";
+      return { error: `HTTP ${res.status}${detail}`, status: res.status };
+    }
+    return data == null ? { error: "malformed response" } : { data };
+  } catch (e) {
+    return { error: `couldn't reach ${safeOrigin(url)}: ${e?.message ?? e}` };
+  }
+}
+
+function safeOrigin(url) {
+  try {
+    return new URL(url).origin;
+  } catch {
+    return url;
+  }
+}
+
+/**
+ * The slot-name grammar, transcribed from the secrets engine's `SECRET_NAME_RE`
+ * (`os/kernel/packages/secrets/src/contract.ts`) so a typo is refused here, with
+ * the rule spelled out, rather than as a 400 from the far end.
+ */
+export const SECRET_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
+/** An app id is a slug — the same shape the kernel mints and the path segment
+ *  this CLI builds, so a bad one cannot escape the path it is encoded into. */
+export const APP_ID_RE = /^[a-z0-9][a-z0-9-]{0,63}$/;

package/src/app/rollback.js

@@ -0,0 +1,72 @@
+// `alexandr app rollback` — put the linked workspace back on the release before
+// this one.
+//
+// The terminal door to `POST /_kernel/store/rollback` (app-system-stage-3.md
+// WP-N). A rollback is a RENAME: the previous release is still on the volume, so
+// this works on a box whose catalog is unreachable — which is exactly the box a
+// bad update leaves behind. No network beyond the one request.
+//
+// ⚠⚠ THE DATA DOES NOT ROLL BACK. Migrations are forward-only, so the app comes
+// back at N-1 while its database stays at N's layout. Every surface offering
+// this has to say so BEFORE it acts, and this one prints the sentence above the
+// request rather than beside the result — a warning shown after the fact is a
+// post-mortem, not a warning.
+//
+// ⚠ A 409 here is NOT the answer a 409 to `update` is. "Nothing newer to install"
+// leaves the box where the developer wanted it; "nothing to go back to" leaves it
+// on the release they are trying to escape — so this one exits non-zero.
+
+import { bold, cyan, dim, fail, log, ok, step, warn } from "../util.js";
+import { EXIT } from "../exit.js";
+import { headersFor, reachWorkspace } from "./reach.js";
+import { postKernelJson, projectFor, resolveAppId } from "./update.js";
+
+export const ROLLBACK_HELP = `${bold("alexandr app rollback")} — put the linked workspace back on the previous release
+
+${bold("USAGE")}
+  alexandr app rollback [--app <id>] [--dir <path>]
+
+${bold("OPTIONS")}
+  --app <id>    The app to roll back, when it isn't the one in this folder
+  --dir <path>  The app folder, when it isn't the current one
+
+${dim("Switches back to the release the box still keeps. Your data keeps the newer layout — only additive changes are safe across a rollback. Needs the os.apps.manage permission in that workspace.")}`;
+
+/**
+ * THE sentence. Verbatim, once, in one place — the app page's Versions section
+ * says the same thing, and two surfaces phrasing a data-loss caveat differently
+ * is how one of them ends up phrasing it wrongly.
+ */
+export const ROLLBACK_WARNING =
+  "Your data keeps the newer layout — only additive changes are safe across a rollback.";
+
+export async function appRollback(flags, project) {
+  // ⚠ `--help` before anything that can exit — see the note in publish.js.
+  if (flags.help || flags.h) return void log(ROLLBACK_HELP);
+  const dir = project ?? projectFor(flags);
+  const chosen = resolveAppId(flags, dir);
+  if (chosen.error) fail(chosen.error, EXIT.USAGE);
+  const id = chosen.id;
+
+  const { url, authorization } = await reachWorkspace(dir);
+  // Said BEFORE the request, so it is a warning rather than a post-mortem.
+  warn(ROLLBACK_WARNING);
+  step(`Rolling ${bold(id)} back in ${cyan(url)}…`);
+  const res = await postKernelJson(`${url}/_kernel/store/rollback`, { id }, headersFor(authorization, true));
+
+  if (!res.ok) {
+    if (res.status === 403) {
+      fail(
+        `The workspace refused it (403) — changing which version an app runs needs the 'os.apps.manage' permission in that workspace. ${res.error ?? ""}`.trim(),
+        EXIT.GENERAL,
+      );
+    }
+    if (res.status === 409) {
+      fail(res.error || `no earlier release of ${id} is retained`, EXIT.GENERAL);
+    }
+    fail(`Couldn't roll ${id} back: ${res.error}`, EXIT.GENERAL);
+  }
+
+  const { version, previous } = res.data ?? {};
+  ok(`${bold(id)} is back on ${bold(version ?? "its previous release")}${previous ? dim(` (was ${previous})`) : ""}`);
+}

package/src/app/signing.js

@@ -0,0 +1,175 @@
+// THE PUBLISHER IDENTITY THIS LAPTOP SIGNS WITH — the key store and the bytes.
+//
+// A release is signed by its publisher, and a publisher is an ACCOUNT or a
+// WORKSPACE (app-system-stage-3.md WP-O §1.5). The workspace case is the box's
+// own key (`os/kernel/src/apps/publisher-key.ts`); THIS file is the account
+// case: `alexandr app publish` mints one ed25519 pair per machine, keeps the
+// private half in `~/.alexandr/publisher.json` at mode 0600, and registers only
+// the public half with the control plane.
+//
+// ⚠⚠ THE PRIVATE HALF NEVER LEAVES THIS FILE'S DIRECTORY. It is never an
+// argument, never a log line, never a multipart part, never a field the CP is
+// offered. The whole point of the scheme is that a control-plane breach can
+// refuse a release but cannot forge one — a code path that uploads the private
+// key would quietly delete that property. Nothing here has one; nothing should
+// ever add one.
+
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign } from "node:crypto";
+import { resolve } from "node:path";
+import { accountDir, readJson, writeSecretJson } from "./store.js";
+
+/**
+ * THE canonical bytes a release signature covers — `${id}\n${version}\n${sha256}`, UTF-8.
+ *
+ * ⚠ THIS IS AN INLINE COPY of the one definition in
+ * `os/protocols/catalog/src/index.ts` (`canonicalReleaseBytes`), and it is a
+ * copy on purpose: this CLI is ZERO-DEPENDENCY plain Node, so it cannot import
+ * `@alexandr/catalog-protocol` — the package the control plane verifies with and
+ * the runtime re-checks with. Four parties must agree byte for byte, and if this
+ * copy drifts every signature this machine issues stops verifying, silently.
+ *
+ * ⚠ So the bytes are PINNED on both sides rather than round-tripped:
+ * `os/protocols/catalog/test/release-signing.test.ts` asserts the exact array
+ * for `("notes", "1.2.3", "abc123")`, and `test/app-publish.test.js` asserts the
+ * same array against this function. A change on either side fails a test naming
+ * the other.
+ *
+ * Why these three fields and nothing else: the sha256 already commits to every
+ * byte of the package, so binding identity + version + digest is what makes a
+ * signature non-transferable to another app, another version, another tarball.
+ */
+export function canonicalReleaseBytes(id, version, sha256) {
+  return Buffer.from(`${id}\n${version}\n${sha256}`, "utf8");
+}
+
+/** `~/.alexandr/publisher.json` — this machine's signing identity, mode 0600. */
+export function publisherKeyPath(home) {
+  return resolve(accountDir(home), "publisher.json");
+}
+
+/**
+ * `ak-<16 hex>` over the DER public key.
+ *
+ * DERIVED, never chosen: the id is a hash of the key material, so it is stable
+ * across restarts and identical for identical bytes — which is what makes
+ * re-registering after a dropped response a no-op instead of a second identity
+ * (and what makes the CP's 409 a success, not a failure — see publish.js).
+ *
+ * ⚠ The kernel's workspace key uses `wk-` with the same derivation: a different
+ * ACTOR, not a different scheme. The prefix is what tells a reader looking at a
+ * feed entry which door signed it. It must satisfy the control plane's `isKeyId`
+ * (`/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/`, `cp-core/src/app-releases.ts`), which
+ * hex plus a leading `ak-` does by construction.
+ */
+export function keyIdFor(publicKeyPem) {
+  const der = createPublicKey(publicKeyPem).export({ type: "spki", format: "der" });
+  return `ak-${createHash("sha256").update(der).digest("hex").slice(0, 16)}`;
+}
+
+/**
+ * This machine's publisher key, minting one the first time.
+ *
+ * Answers `{ record, minted }` — `minted` is what tells `publish` it must
+ * register the public half before the release POST can succeed. A record that
+ * is present but missing a half is treated as absent and replaced: half a key
+ * pair signs nothing, and refusing to publish over one would strand a developer
+ * on a file they cannot read.
+ */
+export function loadOrMintPublisherKey(home) {
+  const file = publisherKeyPath(home);
+  const stored = readJson(file);
+  if (stored?.keyId && stored?.publicKey && stored?.privateKey) {
+    return { record: stored, minted: false };
+  }
+
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+  const privateKeyPem = privateKey.export({ type: "pkcs8", format: "pem" }).toString();
+  const record = {
+    keyId: keyIdFor(publicKeyPem),
+    publicKey: publicKeyPem,
+    privateKey: privateKeyPem,
+    createdAt: new Date().toISOString(),
+    // Which control planes already hold the public half — see markRegistered.
+    registrations: {},
+  };
+  // ⚠ 0600 (best-effort on Windows, like every other credential this CLI keeps —
+  // see `writeSecretJson`). This file is the one secret `alexandr app` creates
+  // rather than receives.
+  writeSecretJson(file, record);
+  return { record, minted: true };
+}
+
+/**
+ * A publisher key handed in by the ENVIRONMENT — CI's key (app-system-stage-4.md
+ * WP-S). `ALEXANDR_PUBLISHER_KEY` holds a PKCS8 ed25519 private PEM (make one with
+ * `openssl genpkey -algorithm ed25519`); the public half and the id are derived
+ * from it, nothing is written to disk, and `registrations` is empty because a
+ * runner has no memory between jobs — the CP's 409 makes re-registering free.
+ *
+ * ⚠ Refuses anything that is not an ed25519 private key with a message that names
+ * the variable: a runner that pasted the wrong secret should read "the key", not
+ * a stack trace from `createPrivateKey`.
+ */
+export function publisherKeyFromEnv(env = process.env) {
+  const pem = env.ALEXANDR_PUBLISHER_KEY;
+  if (typeof pem !== "string" || !pem.trim()) return null;
+  let privateKey;
+  try {
+    privateKey = createPrivateKey(pem.trim().replace(/\\n/g, "\n"));
+  } catch (e) {
+    throw new Error(`ALEXANDR_PUBLISHER_KEY is not a private key PEM (${e.message})`);
+  }
+  if (privateKey.asymmetricKeyType !== "ed25519") {
+    throw new Error(`ALEXANDR_PUBLISHER_KEY must be an ed25519 key (got ${privateKey.asymmetricKeyType})`);
+  }
+  const publicKeyPem = createPublicKey(privateKey).export({ type: "spki", format: "pem" }).toString();
+  return {
+    keyId: keyIdFor(publicKeyPem),
+    publicKey: publicKeyPem,
+    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    registrations: {},
+  };
+}
+
+/**
+ * A key for THIS RUN only — the CI fallback when no `ALEXANDR_PUBLISHER_KEY` is
+ * set. Never written anywhere. Each run registers a fresh public half under the
+ * workspace, which the CP keeps (a release's signature must stay verifiable), so
+ * the caller warns and names the variable that makes runs share one key.
+ */
+export function mintEphemeralPublisherKey() {
+  const { publicKey, privateKey } = generateKeyPairSync("ed25519");
+  const publicKeyPem = publicKey.export({ type: "spki", format: "pem" }).toString();
+  return {
+    keyId: keyIdFor(publicKeyPem),
+    publicKey: publicKeyPem,
+    privateKey: privateKey.export({ type: "pkcs8", format: "pem" }).toString(),
+    registrations: {},
+  };
+}
+
+/** base64url ed25519 over the canonical bytes — the release's signature. */
+export function signRelease(privateKeyPem, id, version, sha256) {
+  return sign(null, canonicalReleaseBytes(id, version, sha256), createPrivateKey(privateKeyPem)).toString(
+    "base64url",
+  );
+}
+
+/**
+ * Remember that `cpUrl` holds this key's public half.
+ *
+ * Per CP URL, not a boolean: a laptop that publishes to a dev control plane and
+ * to production is registered with two independent key stores, and one flag
+ * would make the second publish skip the registration it still needs. Recorded
+ * only AFTER the CP said so (201 or 409) — an optimistic write would turn one
+ * failed registration into a permanent, silent 403 on every later publish.
+ */
+export function markRegistered(home, record, cpUrl) {
+  const next = {
+    ...record,
+    registrations: { ...(record.registrations ?? {}), [cpUrl]: new Date().toISOString() },
+  };
+  writeSecretJson(publisherKeyPath(home), next);
+  return next;
+}

package/src/app/store.js

@@ -0,0 +1,191 @@
+// Where `alexandr app` keeps its state — two files, deliberately in two places.
+//
+//   ~/.alexandr/auth.json      THE ACCOUNT session (one per machine, mode 0600)
+//   <project>/.alexandr/link.json   which workspace THIS project deploys to
+//   <project>/.alexandr/token.json  the short-lived workspace JWT, re-minted
+//
+// The split is the point. An account session is a credential — it belongs to the
+// person and their machine, never in a repo. A workspace link is a project fact
+// — a teammate cloning the repo wants their OWN link, so `.alexandr/` is
+// gitignored by the template and each developer links once. The workspace token
+// lives beside the link because it is derived from it and expires in minutes.
+//
+// Every function here is pure over an injected home/project dir, so the whole
+// credential story is testable without touching a real HOME.
+
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+
+/**
+ * The per-machine alexandr directory — `~/.alexandr`, the same one the
+ * self-host verbs already keep their global instances in (`instance.js`).
+ * `ALEXANDR_HOME` names it outright, which is how the tests get a real store
+ * without touching a real HOME.
+ */
+export function accountDir(home) {
+  if (home) return resolve(home);
+  if (process.env.ALEXANDR_HOME) return resolve(process.env.ALEXANDR_HOME);
+  return resolve(homedir(), ".alexandr");
+}
+
+/** `~/.alexandr/auth.json` — the account session this machine holds. */
+export function authPath(home) {
+  return resolve(accountDir(home), "auth.json");
+}
+
+/** `<project>/.alexandr` — the per-project link state, gitignored by the template. */
+export function projectDir(project = process.cwd()) {
+  return resolve(project, ".alexandr");
+}
+
+export function linkPath(project) {
+  return resolve(projectDir(project), "link.json");
+}
+
+export function tokenPath(project) {
+  return resolve(projectDir(project), "token.json");
+}
+
+/** Read a JSON file, or null. A corrupt file is "absent", never a crash. */
+export function readJson(file) {
+  try {
+    const raw = readFileSync(file, "utf8");
+    const parsed = JSON.parse(raw);
+    // ⚠ `JSON.parse("null")` SUCCEEDS — a null body is not a parsed record.
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write JSON, owner-only.
+ *
+ * `chmod 0600` is best-effort on purpose: on Windows the POSIX mode is a
+ * no-op and throwing there would make the CLI unusable on the platform its own
+ * scripts are written for (root CLAUDE.md, "On a WINDOWS dev box"). The file
+ * still lands under the user profile, which is the platform's own boundary.
+ */
+export function writeSecretJson(file, value) {
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+  try {
+    chmodSync(file, 0o600);
+  } catch {
+    /* Windows: no POSIX mode. */
+  }
+}
+
+// ── the account session ───────────────────────────────────────────────────────
+
+/** `{ cpUrl, token, expiresAt, client, scope }`, or null when not signed in. */
+export function readAuth(home) {
+  return readJson(authPath(home));
+}
+
+export function writeAuth(session, home) {
+  writeSecretJson(authPath(home), session);
+  return session;
+}
+
+export function clearAuth(home) {
+  rmSync(authPath(home), { force: true });
+}
+
+/**
+ * Is this stored session still usable for `cpUrl`?
+ *
+ * ⚠ The CP url is part of the answer, not a detail. A session minted against a
+ * dev control plane is worthless against production and vice versa; treating
+ * "have a token" as "signed in" is how a laptop ends up sending a dev session to
+ * api.alexandr.so and reading the 401 as a server problem.
+ */
+export function authUsable(session, cpUrl, now = Date.now()) {
+  if (!session?.token) return false;
+  if (cpUrl && session.cpUrl && session.cpUrl !== cpUrl) return false;
+  if (!session.expiresAt) return true; // an older CP answered without one
+  const expires = Date.parse(session.expiresAt);
+  return Number.isFinite(expires) ? expires > now : true;
+}
+
+// ── the project link ──────────────────────────────────────────────────────────
+
+/** `{ cpUrl, workspaceId, workspaceName, instanceId, instanceUrl, localTrust }`. */
+export function readLink(project) {
+  return readJson(linkPath(project));
+}
+
+export function writeLink(link, project) {
+  const file = linkPath(project);
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(link, null, 2) + "\n");
+  return link;
+}
+
+/** A box trusted open behind a signed-in app (`ALEXANDR_LOCAL_TRUST=1`) — no CP,
+ *  no workspace token, nothing to mint. `alexandr app link --url` writes this. */
+export function isLocalTrust(link) {
+  return Boolean(link?.localTrust || (link?.instanceUrl && !link?.workspaceId));
+}
+
+// ── the workspace token ───────────────────────────────────────────────────────
+
+/** `{ token, expiresAt }` — the cached workspace JWT for this project. */
+export function readToken(project) {
+  return readJson(tokenPath(project));
+}
+
+export function writeToken(record, project) {
+  writeSecretJson(tokenPath(project), record);
+  return record;
+}
+
+export function clearToken(project) {
+  rmSync(tokenPath(project), { force: true });
+}
+
+/** The margin before expiry at which a cached workspace token is re-minted. */
+export const REMINT_MARGIN_MS = 60_000;
+
+/**
+ * Does this cached token need replacing?
+ *
+ * ⚠ The margin is what makes `app dev` survive a long request. The CP mints a
+ * 5-minute JWT; a proxy that only re-minted ON a 401 would hand Vite a token
+ * that expires mid-flight and turn one stale second into a failed page load.
+ * Absent, tokenless and unparseable all answer "yes" — the safe direction.
+ */
+export function needsRemint(record, now = Date.now(), marginMs = REMINT_MARGIN_MS) {
+  if (!record?.token) return true;
+  const expires = Date.parse(record.expiresAt ?? "");
+  if (!Number.isFinite(expires)) return true;
+  return expires - marginMs <= now;
+}
+
+/**
+ * When a workspace JWT actually expires, read from the token itself.
+ *
+ * ⚠ `POST /workspaces/:id/token` answers with the token and NO expiry, so the
+ * only honest source is the JWT's own `exp`. A hard-coded "5 minutes from now"
+ * would be a guess that silently rots the day the CP changes the TTL. A token we
+ * cannot parse falls back to a deliberately SHORT window, so the failure mode is
+ * re-minting too often rather than using a dead token.
+ */
+export function jwtExpiry(token, now = Date.now(), fallbackMs = 60_000) {
+  try {
+    const payload = String(token).split(".")[1];
+    if (!payload) return new Date(now + fallbackMs).toISOString();
+    const json = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    const exp = Number(json?.exp);
+    if (Number.isFinite(exp) && exp > 0) return new Date(exp * 1000).toISOString();
+  } catch {
+    /* not a JWT we can read — fall through */
+  }
+  return new Date(now + fallbackMs).toISOString();
+}
+
+/** True when the project has been linked at all. */
+export function isLinked(project) {
+  return existsSync(linkPath(project));
+}

package/src/app/token.js

@@ -0,0 +1,83 @@
+// The workspace token — minting it, caching it, and keeping it fresh.
+//
+// The CP is the single identity authority: `POST /workspaces/:id/token` with the
+// account session returns an RS256 JWT whose `aud` is the instance id, with a
+// FIVE-MINUTE TTL, which the runtime verifies locally against the CP JWKS
+// (account-required-runtimes.md). The runtime owns no login, so there is nothing
+// else to present at its door.
+//
+// Five minutes is short enough that `alexandr app dev` cannot mint once and walk
+// away: it re-mints on a timer for as long as Vite runs, and the Vite proxy reads
+// the token file per request so a fresh one lands without a restart.
+//
+// ⚠ `POST /workspaces/:id/token` is mounted under CP_MANAGED=1 only. A
+// local-trust box (`ALEXANDR_LOCAL_TRUST=1`) has no CP and needs no token; that
+// is a different lane, not a degraded one — see `isLocalTrust` in ./store.js.
+
+import { postJson } from "../consent.js";
+import { jwtExpiry, needsRemint, readToken, writeToken } from "./store.js";
+
+/**
+ * Mint a fresh workspace token for `link` using the account `session`.
+ *
+ * Returns `{ ok, token, expiresAt, status, url }` or `{ ok: false, error }`. A
+ * workspace whose instance is not running yet answers with a null token and a
+ * status — a WAIT, not a failure, and the caller says so.
+ */
+export async function mintWorkspaceToken(link, session, fetchJson = postJson) {
+  const res = await fetchJson(
+    `${link.cpUrl.replace(/\/+$/, "")}/workspaces/${encodeURIComponent(link.workspaceId)}/token`,
+    {},
+    { authorization: `Bearer ${session.token}` },
+  );
+  if (res.error) return { ok: false, error: res.error };
+  const { token, status, url } = res.data ?? {};
+  if (!token) {
+    return {
+      ok: false,
+      pending: true,
+      status: status ?? "unknown",
+      url: url ?? null,
+      error: `the workspace is ${status ?? "not running"} — no token yet`,
+    };
+  }
+  return { ok: true, token, expiresAt: jwtExpiry(token), status, url: url ?? link.instanceUrl };
+}
+
+/**
+ * The token this project should be presenting right now: the cached one while it
+ * has more than a minute left, a freshly minted one otherwise.
+ *
+ * `force` skips the cache (the timer in `app dev` does not need to re-read a
+ * file it just wrote).
+ */
+export async function ensureWorkspaceToken(
+  link,
+  session,
+  { project, force = false, now = Date.now(), fetchJson = postJson } = {},
+) {
+  const cached = force ? null : readToken(project);
+  if (!needsRemint(cached, now)) return { ok: true, token: cached.token, expiresAt: cached.expiresAt, cached: true };
+
+  const minted = await mintWorkspaceToken(link, session, fetchJson);
+  if (!minted.ok) return minted;
+  writeToken({ token: minted.token, expiresAt: minted.expiresAt, workspaceId: link.workspaceId }, project);
+  return { ok: true, token: minted.token, expiresAt: minted.expiresAt, cached: false, url: minted.url };
+}
+
+/**
+ * How long to wait before the next re-mint: two thirds of the remaining life,
+ * floored at 30 s and capped at 4 minutes.
+ *
+ * ⚠ A fixed interval is the wrong shape here. Too long and the proxy serves a
+ * dead token; too short and a dev session hammers the CP for eight hours. Two
+ * thirds of the life re-mints ~3.3 minutes into a 5-minute token — comfortably
+ * inside `needsRemint`'s one-minute margin, whatever TTL the CP decides on later.
+ */
+export function nextRemintDelay(expiresAt, now = Date.now(), { minMs = 30_000, maxMs = 240_000 } = {}) {
+  const expires = Date.parse(expiresAt ?? "");
+  if (!Number.isFinite(expires)) return minMs;
+  const remaining = expires - now;
+  if (remaining <= 0) return minMs;
+  return Math.min(maxMs, Math.max(minMs, Math.floor((remaining * 2) / 3)));
+}