@irtio/cli 0.5.2 → 0.7.0

package/dist/chunk-WFMRNGO5.js

@@ -0,0 +1,481 @@
+// ../store/src/static.ts
+var STATIC_LIMITS = {
+  /** Bytes per file. Big enough for a wasm build or a texture atlas; a video does not belong. */
+  maxFileBytes: 32 * 1024 * 1024,
+  /** Files per deploy. */
+  maxFiles: 2e3,
+  /** Total bytes per deploy. */
+  maxTotalBytes: 256 * 1024 * 1024
+};
+function staticPathProblem(path2) {
+  if (path2.length === 0 || path2.length > 512) return "path must be 1-512 characters";
+  if (path2.startsWith("/")) return "path must be relative (no leading slash)";
+  if (path2.includes("\\")) return "path must use forward slashes";
+  if (/[\x00-\x1f\x7f]/.test(path2)) return "path must not contain control characters";
+  for (const segment of path2.split("/")) {
+    if (segment === "" || segment === "." || segment === "..") {
+      return "path segments must be non-empty and not . or ..";
+    }
+  }
+  return void 0;
+}
+
+// ../store/src/disk.ts
+import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from "fs/promises";
+import * as path from "path";
+var DiskStore = class {
+  constructor(dir) {
+    this.dir = dir;
+  }
+  dir;
+  fileFor(key) {
+    if (!/^[A-Za-z0-9_.@/-]+$/.test(key) || key.includes("..")) {
+      throw new Error(`invalid object store key ${JSON.stringify(key)}`);
+    }
+    return path.join(this.dir, `${key}.snap`);
+  }
+  async put(key, bytes) {
+    const file = this.fileFor(key);
+    await mkdir(path.dirname(file), { recursive: true });
+    const tmp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+    await writeFile(tmp, bytes);
+    for (let attempt = 0; ; attempt++) {
+      try {
+        await rename(tmp, file);
+        return;
+      } catch (err) {
+        const code = err.code;
+        if ((code === "EPERM" || code === "EBUSY") && attempt < 10) {
+          await new Promise((resolve) => setTimeout(resolve, 5 * (attempt + 1)));
+          continue;
+        }
+        throw err;
+      }
+    }
+  }
+  async get(key) {
+    try {
+      return new Uint8Array(await readFile(this.fileFor(key)));
+    } catch (err) {
+      if (err.code === "ENOENT") return void 0;
+      throw err;
+    }
+  }
+  async delete(key) {
+    await rm(this.fileFor(key), { force: true });
+  }
+  async list(prefix) {
+    const out = [];
+    const walk = async (dir, rel) => {
+      let entries;
+      try {
+        entries = await readdir(dir, { withFileTypes: true });
+      } catch (err) {
+        if (err.code === "ENOENT") return;
+        throw err;
+      }
+      for (const e of entries) {
+        const r = rel ? `${rel}/${e.name}` : e.name;
+        if (e.isDirectory()) await walk(path.join(dir, e.name), r);
+        else if (e.name.endsWith(".snap")) out.push(r.slice(0, -".snap".length));
+      }
+    };
+    await walk(this.dir, "");
+    return out.filter((k) => k.startsWith(prefix)).sort();
+  }
+  async sizes(prefix) {
+    const keys = await this.list(prefix);
+    const out = [];
+    for (const key of keys) {
+      try {
+        const st = await stat(this.fileFor(key));
+        out.push({ key, size: st.size, lastModified: Math.floor(st.mtimeMs) });
+      } catch (err) {
+        if (err.code === "ENOENT") continue;
+        throw err;
+      }
+    }
+    return out;
+  }
+};
+
+// ../store/src/kv.ts
+var KV_LIMITS = {
+  /** Max UTF-8 bytes in one value. */
+  valueBytes: 16 * 1024,
+  /** Max UTF-8 bytes in one key. */
+  keyBytes: 256,
+  /** Max UTF-8 bytes in one player id. */
+  playerIdBytes: 256,
+  /** Max distinct keys one player may hold within one project. */
+  keysPerPlayer: 128,
+  /** Max rows one project may hold across all its players. */
+  rowsPerProject: 1e6
+};
+var PLAYER_ISSUER_RE = /^[a-z0-9._-]{1,64}$/;
+var KV_ERRORS = {
+  badKey: "E_KV_BAD_KEY",
+  badPlayer: "E_KV_BAD_PLAYER",
+  valueTooLarge: "E_KV_VALUE_TOO_LARGE",
+  tooManyKeys: "E_KV_TOO_MANY_KEYS",
+  projectFull: "E_KV_PROJECT_FULL",
+  forbidden: "E_KV_FORBIDDEN",
+  unavailable: "E_KV_UNAVAILABLE"
+};
+
+// ../store/src/identity.ts
+import {
+  createHash,
+  createHmac,
+  createPublicKey,
+  generateKeyPairSync,
+  sign,
+  verify
+} from "crypto";
+var IRT_IDENTITY_ISSUER = "irt";
+var ASSERTION_TYP = "IRTA";
+var ASSERTION_ALG = "EdDSA";
+var ASSERTION_TTL_MS = 5 * 6e4;
+var ASSERTION_CLOCK_SKEW_MS = 6e4;
+var SUB_RE = /^[\x21-\x7e]{1,128}$/;
+function verifyAssertion(keys, token, projectId, now = Date.now()) {
+  const malformed = (reason) => ({
+    ok: false,
+    code: "E_TOKEN_MALFORMED",
+    reason
+  });
+  if (keys.length === 0) {
+    return {
+      ok: false,
+      code: "E_ASSERTION_UNVERIFIABLE",
+      reason: "this tenant holds no platform identity key yet"
+    };
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3) return malformed("not three dot-separated segments");
+  const [headerB64, payloadB64, signatureB64] = parts;
+  let header;
+  let claims;
+  try {
+    header = JSON.parse(Buffer.from(headerB64, "base64url").toString("utf8"));
+    claims = JSON.parse(Buffer.from(payloadB64, "base64url").toString("utf8"));
+  } catch {
+    return malformed("header or payload is not base64url JSON");
+  }
+  if (header.typ !== ASSERTION_TYP) return malformed(`typ must be ${ASSERTION_TYP}`);
+  if (claims.iss !== IRT_IDENTITY_ISSUER) return malformed(`iss must be ${IRT_IDENTITY_ISSUER}`);
+  if (typeof claims.sub !== "string" || !SUB_RE.test(claims.sub)) {
+    return malformed("sub is required: 1-128 printable ASCII characters, no spaces");
+  }
+  if (typeof claims.aud !== "string") return malformed("aud (the project id) is required");
+  if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) {
+    return malformed("exp (unix seconds) is required");
+  }
+  if (claims.aud !== projectId) {
+    return { ok: false, code: "E_TOKEN_WRONG_PROJECT", reason: "aud is another project" };
+  }
+  if (header.alg !== ASSERTION_ALG) {
+    return { ok: false, code: "E_TOKEN_BAD_ALG", reason: String(header.alg) };
+  }
+  const signed = Buffer.from(`${headerB64}.${payloadB64}`, "utf8");
+  let signature;
+  try {
+    signature = Buffer.from(signatureB64, "base64url");
+  } catch {
+    return malformed("signature is not base64url");
+  }
+  const kid = typeof header.kid === "string" ? header.kid : void 0;
+  const candidates = kid !== void 0 ? keys.filter((k) => k.kid === kid) : [];
+  const tried = candidates.length > 0 ? candidates : keys;
+  let matched;
+  for (const key of tried) {
+    let ok = false;
+    try {
+      ok = verify(null, signed, key.publicKeyPem, signature);
+    } catch {
+      ok = false;
+    }
+    if (ok) {
+      matched = key;
+      break;
+    }
+  }
+  if (!matched) return { ok: false, code: "E_TOKEN_INVALID", reason: "signature mismatch" };
+  const expMs = claims.exp * 1e3;
+  if (expMs + ASSERTION_CLOCK_SKEW_MS <= now) {
+    return { ok: false, code: "E_TOKEN_EXPIRED", reason: "exp is in the past" };
+  }
+  if (typeof claims.iat === "number" && Number.isFinite(claims.iat) && claims.iat * 1e3 - ASSERTION_CLOCK_SKEW_MS > now) {
+    return { ok: false, code: "E_TOKEN_EXPIRED", reason: "iat is in the future" };
+  }
+  return {
+    ok: true,
+    sub: claims.sub,
+    playerId: `${IRT_IDENTITY_ISSUER}:${claims.sub}`,
+    kid: matched.kid,
+    expMs
+  };
+}
+function parseIdentityKeys(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+  const raw = value.keys;
+  if (!Array.isArray(raw)) return void 0;
+  const out = [];
+  for (const entry of raw) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const k = entry;
+    if (typeof k.kid !== "string" || k.kid === "") continue;
+    if (typeof k.publicKeyPem !== "string" || !k.publicKeyPem.includes("BEGIN PUBLIC KEY")) {
+      continue;
+    }
+    out.push({ kid: k.kid, publicKeyPem: k.publicKeyPem });
+  }
+  return out.slice(0, 2);
+}
+
+// ../store/src/leaderboard.ts
+var LEADERBOARD_ERRORS = {
+  badBoard: "E_LB_BAD_BOARD",
+  badScore: "E_LB_BAD_SCORE",
+  badPlayer: "E_LB_BAD_PLAYER",
+  notInRoom: "E_LB_NOT_IN_ROOM",
+  projectFull: "E_LB_PROJECT_FULL",
+  unavailable: "E_LB_UNAVAILABLE",
+  /** D62-a: a `top` cursor that is not a cursor for the board and direction it arrived on. Its
+   *  own code because the only thing to do about it is start again from the first page, which no
+   *  other code in this table implies. */
+  badCursor: "E_LB_BAD_CURSOR",
+  // ---- M6 lane B: boards (D69) ----
+  /** A `?period=` that is not shaped like a period key. */
+  badPeriod: "E_LB_BAD_PERIOD",
+  /** A bucket name that breaks the board-name rules it shares. */
+  badBucket: "E_LB_BAD_BUCKET",
+  /** A bucketed board read or written without a bucket. Refused rather than merged or defaulted:
+   *  a read that silently answered every cohort at once would be a ranking nobody asked for. */
+  bucketRequired: "E_LB_BUCKET_REQUIRED",
+  /** A bucket on a board that declares none. Refused rather than ignored, because a submit whose
+   *  bucket was quietly dropped would put a cohort's scores on the wrong ranking. */
+  noBuckets: "E_LB_NO_BUCKETS"
+};
+
+// ../store/src/rating.ts
+var RATING_LIMITS = {
+  /** Max players named in one report. A report is one rating period and decomposes into pairs,
+   *  so the work is quadratic in this number; 64 is `MAX_QUEUE_SIZE`, which is the largest party
+   *  any queue may declare and therefore the largest honest report a matched room can make. */
+  maxResults: 64,
+  /** Max UTF-8 bytes in a queue name. Matches the queue-name shape below. */
+  queueBytes: 32,
+  /** Max UTF-8 bytes in a player id. The leaderboard's number, for the same column shape. */
+  playerIdBytes: 256,
+  /** Max distinct rating rows one project may hold across all its queues. */
+  rowsPerProject: 1e6,
+  /** `place` is a 1-based finishing position. Ties are equal places, so places need not be dense
+   *  and need not start at 1 — only be whole, positive and inside a party's plausible size. */
+  maxPlace: 64,
+  /** The bounds a game-supplied rating (`ratings.set`) must sit inside. Wide enough for any
+   *  scale a game might use, narrow enough that a NaN or an infinity cannot be stored. */
+  minRating: -1e6,
+  maxRating: 1e6,
+  /** Deviation is a standard error on the same scale, so it is positive and bounded. */
+  minDeviation: 1,
+  maxDeviation: 1e3
+};
+var RATING_QUEUE_NAME_RE = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+var RATING_ERRORS = {
+  badQueue: "E_RATING_BAD_QUEUE",
+  badResults: "E_RATING_BAD_RESULTS",
+  badPlayer: "E_RATING_BAD_PLAYER",
+  badRating: "E_RATING_BAD_RATING",
+  notInRoom: "E_RATING_NOT_IN_ROOM",
+  projectFull: "E_RATING_PROJECT_FULL",
+  unavailable: "E_RATING_UNAVAILABLE"
+};
+function ratingQueueProblem(queue) {
+  if (typeof queue !== "string" || queue.length === 0) {
+    return { code: RATING_ERRORS.badQueue, message: "queue must be a non-empty string" };
+  }
+  if (!RATING_QUEUE_NAME_RE.test(queue)) {
+    return {
+      code: RATING_ERRORS.badQueue,
+      message: `queue must be 1-32 characters of a-z 0-9 . _ - and start with a letter or digit (got ${JSON.stringify(queue)})`
+    };
+  }
+  return void 0;
+}
+function ratingResultsProblem(results) {
+  if (!Array.isArray(results)) {
+    return { code: RATING_ERRORS.badResults, message: "results must be an array" };
+  }
+  if (results.length < 2) {
+    return {
+      code: RATING_ERRORS.badResults,
+      message: "a result needs at least two players; a rating is a comparison"
+    };
+  }
+  if (results.length > RATING_LIMITS.maxResults) {
+    return {
+      code: RATING_ERRORS.badResults,
+      message: `a report may name at most ${RATING_LIMITS.maxResults} players`
+    };
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const raw of results) {
+    if (typeof raw !== "object" || raw === null) {
+      return { code: RATING_ERRORS.badResults, message: "each result must be an object" };
+    }
+    const { playerId, place } = raw;
+    const bad = ratingPlayerProblem(playerId);
+    if (bad) return bad;
+    if (typeof place !== "number" || !Number.isInteger(place)) {
+      return {
+        code: RATING_ERRORS.badResults,
+        message: "place must be a whole number, 1 for first (ties share a place)"
+      };
+    }
+    if (place < 1 || place > RATING_LIMITS.maxPlace) {
+      return {
+        code: RATING_ERRORS.badResults,
+        message: `place must be between 1 and ${RATING_LIMITS.maxPlace}`
+      };
+    }
+    if (seen.has(playerId)) {
+      return {
+        code: RATING_ERRORS.badResults,
+        message: `${JSON.stringify(playerId)} appears twice; a player cannot play themselves`
+      };
+    }
+    seen.add(playerId);
+  }
+  return void 0;
+}
+function ratingPlayerProblem(playerId) {
+  if (typeof playerId !== "string" || playerId.length === 0) {
+    return { code: RATING_ERRORS.badPlayer, message: "playerId must be a non-empty string" };
+  }
+  if (new TextEncoder().encode(playerId).length > RATING_LIMITS.playerIdBytes) {
+    return {
+      code: RATING_ERRORS.badPlayer,
+      message: `playerId must be at most ${RATING_LIMITS.playerIdBytes} bytes`
+    };
+  }
+  return void 0;
+}
+function ratingValueProblem(value) {
+  if (typeof value !== "object" || value === null) {
+    return { code: RATING_ERRORS.badRating, message: "a rating must be an object" };
+  }
+  const { rating, deviation } = value;
+  if (typeof rating !== "number" || !Number.isFinite(rating)) {
+    return { code: RATING_ERRORS.badRating, message: "rating must be a finite number" };
+  }
+  if (rating < RATING_LIMITS.minRating || rating > RATING_LIMITS.maxRating) {
+    return {
+      code: RATING_ERRORS.badRating,
+      message: `rating must be between ${RATING_LIMITS.minRating} and ${RATING_LIMITS.maxRating}`
+    };
+  }
+  if (deviation !== void 0) {
+    if (typeof deviation !== "number" || !Number.isFinite(deviation)) {
+      return { code: RATING_ERRORS.badRating, message: "deviation must be a finite number" };
+    }
+    if (deviation < RATING_LIMITS.minDeviation || deviation > RATING_LIMITS.maxDeviation) {
+      return {
+        code: RATING_ERRORS.badRating,
+        message: `deviation must be between ${RATING_LIMITS.minDeviation} and ${RATING_LIMITS.maxDeviation}`
+      };
+    }
+  }
+  return void 0;
+}
+
+// ../store/src/saves.ts
+var SAVES_SEGMENT = "/saves/";
+var SAVE_ID_TIME_DIGITS = 17;
+var DEFAULT_SAVE_RETAIN = 10;
+var PRE_MIGRATION_SAVE_ID = "premigrate";
+function mintSaveId(nowMs, rand) {
+  const t = Math.max(0, Math.floor(nowMs));
+  const suffix = (Math.floor(Math.abs(rand)) & 65535).toString(16).padStart(4, "0");
+  return `${String(t).padStart(SAVE_ID_TIME_DIGITS, "0")}-${suffix}`;
+}
+function saveIdCreatedAt(saveId) {
+  if (saveId.length !== SAVE_ID_TIME_DIGITS + 5) return void 0;
+  if (saveId[SAVE_ID_TIME_DIGITS] !== "-") return void 0;
+  const time = saveId.slice(0, SAVE_ID_TIME_DIGITS);
+  if (!/^[0-9]+$/.test(time)) return void 0;
+  if (!/^[0-9a-f]{4}$/.test(saveId.slice(SAVE_ID_TIME_DIGITS + 1))) return void 0;
+  return Number(time);
+}
+function savesPrefix(liveKey) {
+  return `${liveKey}${SAVES_SEGMENT}`;
+}
+function saveKey(liveKey, saveId) {
+  return `${savesPrefix(liveKey)}${saveId}`;
+}
+function saveIdOf(liveKey, key) {
+  const prefix = savesPrefix(liveKey);
+  if (!key.startsWith(prefix)) return void 0;
+  const rest = key.slice(prefix.length);
+  if (rest === "" || rest.includes("/")) return void 0;
+  return rest;
+}
+async function listSaves(store, liveKey) {
+  const keys = await store.list(savesPrefix(liveKey));
+  const out = [];
+  for (const key of keys) {
+    const saveId = saveIdOf(liveKey, key);
+    if (saveId === void 0) continue;
+    const createdAt = saveIdCreatedAt(saveId);
+    if (createdAt === void 0) continue;
+    out.push({ saveId, key, createdAt });
+  }
+  out.sort((a, b) => a.saveId < b.saveId ? 1 : a.saveId > b.saveId ? -1 : 0);
+  return out;
+}
+function selectForPruning(saves, retain) {
+  const keep = Number.isFinite(retain) ? Math.max(1, Math.floor(retain)) : 1;
+  return saves.length <= keep ? [] : saves.slice(keep);
+}
+async function pruneSaves(store, saves, retain, log) {
+  const doomed = selectForPruning(saves, retain);
+  let deleted = 0;
+  for (const save of doomed) {
+    try {
+      await store.delete(save.key);
+      deleted++;
+    } catch (err) {
+      log("warn", `save retention: could not delete ${save.key}`, err);
+    }
+  }
+  return deleted;
+}
+
+// ../store/src/s3.ts
+import { createHash as createHash3 } from "crypto";
+
+// ../store/src/sigv4.ts
+import { createHash as createHash2, createHmac as createHmac2 } from "crypto";
+
+export {
+  PLAYER_ISSUER_RE,
+  KV_ERRORS,
+  IRT_IDENTITY_ISSUER,
+  verifyAssertion,
+  parseIdentityKeys,
+  LEADERBOARD_ERRORS,
+  RATING_ERRORS,
+  ratingQueueProblem,
+  ratingResultsProblem,
+  ratingPlayerProblem,
+  ratingValueProblem,
+  DEFAULT_SAVE_RETAIN,
+  PRE_MIGRATION_SAVE_ID,
+  mintSaveId,
+  saveKey,
+  listSaves,
+  pruneSaves,
+  STATIC_LIMITS,
+  staticPathProblem,
+  DiskStore
+};

package/dist/chunk-ZK5JLUD4.js

@@ -0,0 +1,94 @@
+// src/profile.ts
+import { diffProfiles } from "@irtio/protocol";
+import pc from "picocolors";
+var PROFILE_TOP_DEFAULT = 12;
+function rateOf(bytes, seconds) {
+  const v = seconds > 0 ? bytes / seconds : bytes;
+  const unit = seconds > 0 ? "/s" : "";
+  if (v >= 1e6) return `${(v / 1e6).toFixed(1)} MB${unit}`;
+  if (v >= 1e3) return `${(v / 1e3).toFixed(1)} kB${unit}`;
+  return `${Math.round(v)} B${unit}`;
+}
+function pct(part, whole) {
+  if (whole <= 0) return "";
+  const p = 100 * part / whole;
+  return p >= 10 ? `${Math.round(p)}%` : `${p.toFixed(1)}%`;
+}
+function formatProfileTable(window, options = {}) {
+  const top = options.top ?? PROFILE_TOP_DEFAULT;
+  const seconds = options.seconds ?? 0;
+  const per = options.per && options.per > 1 ? options.per : 1;
+  const dim = options.color === false ? (s) => s : pc.dim;
+  const rows = [...window.rows].sort((a, b) => b.out + b.in - (a.out + a.in)).filter((r) => r.out !== 0 || r.in !== 0).slice(0, top);
+  const cells = rows.map((r) => ({
+    kind: r.kind,
+    key: r.key,
+    out: rateOf(r.out / per, seconds),
+    in: rateOf(r.in / per, seconds),
+    share: pct(r.out, window.bytesOut)
+  }));
+  const totalOut = rateOf(window.bytesOut / per, seconds);
+  const totalIn = rateOf(window.bytesIn / per, seconds);
+  const w = {
+    kind: Math.max(4, ...cells.map((c) => c.kind.length)),
+    key: Math.max(3, ...cells.map((c) => c.key.length)),
+    out: Math.max(3, totalOut.length, ...cells.map((c) => c.out.length)),
+    in: Math.max(2, totalIn.length, ...cells.map((c) => c.in.length))
+  };
+  const lines = [];
+  lines.push(
+    dim(
+      `  ${"KIND".padEnd(w.kind)}  ${"KEY".padEnd(w.key)}  ${"OUT".padStart(w.out)}  ${"IN".padStart(w.in)}  SHARE`
+    )
+  );
+  if (cells.length === 0) lines.push(dim("  (nothing moved in this window)"));
+  for (const c of cells) {
+    lines.push(
+      `  ${c.kind.padEnd(w.kind)}  ${c.key.padEnd(w.key)}  ${c.out.padStart(w.out)}  ${c.in.padStart(w.in)}  ${c.share.padStart(5)}`
+    );
+  }
+  lines.push(
+    `  ${"total".padEnd(w.kind)}  ${"".padEnd(w.key)}  ${totalOut.padStart(w.out)}  ${totalIn.padStart(w.in)}`
+  );
+  if (options.against) {
+    lines.push(
+      dim(
+        `  ${options.against.label.padEnd(w.kind)}  ${"".padEnd(w.key)}  ${rateOf(options.against.out / per, seconds).padStart(w.out)}  ${rateOf(options.against.in / per, seconds).padStart(w.in)}`
+      )
+    );
+  }
+  return lines;
+}
+function profileTick(readings, previous, options = {}) {
+  const lines = [];
+  const history = /* @__PURE__ */ new Map();
+  const dim = options.color === false ? (s) => s : pc.dim;
+  for (const reading of readings) {
+    history.set(reading.id, reading);
+    if (!reading.profile) continue;
+    const before = previous.get(reading.id);
+    if (!before?.profile) continue;
+    const seconds = Math.max(0, reading.at - before.at) / 1e3;
+    if (seconds <= 0) continue;
+    const window = diffProfiles(before.profile, reading.profile);
+    lines.push(`room ${reading.id} ${dim(`\xB7 ${seconds.toFixed(1)} s window`)}`);
+    lines.push(
+      ...formatProfileTable(window, {
+        ...options,
+        seconds,
+        against: {
+          out: reading.egressBytes - before.egressBytes,
+          in: reading.ingressBytes - before.ingressBytes,
+          label: "socket"
+        }
+      })
+    );
+    lines.push("");
+  }
+  return { lines, history };
+}
+
+export {
+  formatProfileTable,
+  profileTick
+};

package/dist/credentials.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The CLI's on-disk credential store. One JSON file, keyed by control URL so a machine
+ * that talks to more than one control plane (a local dev instance and the real one) keeps both
+ * tokens without clobbering each other.
+ *
+ * Location: `~/.config/irtio/credentials.json` on macOS/Linux, `%APPDATA%/irtio/credentials.json`
+ * on Windows. This follows the platform's own convention for CLI config rather than XDG
+ * everywhere (`os.homedir()` alone gets the wrong answer on Windows, where `~/.config` is not a
+ * thing anyone looks for) — `%APPDATA%` is what `git`, `npm` and most Windows CLIs already use.
+ *
+ * The file is written mode 0600 (owner read/write only): it holds a bearer token that is exactly
+ * as sensitive as a password for whatever it authorizes. `chmod` runs after `writeFile` too,
+ * belt-and-suspenders against an umask or an existing file with looser permissions.
+ */
+/** One control plane's worth of stored auth. `email` is best-effort (see `login.ts`). */
+interface StoredCredential {
+    readonly token: string;
+    readonly expiresAt: string;
+    readonly email?: string;
+}
+type CredentialsFile = Record<string, StoredCredential>;
+/**
+ * `~/.config/irtio/credentials.json`, or `%APPDATA%/irtio/credentials.json` on Windows.
+ *
+ * `IRT_CREDENTIALS_FILE` overrides this outright — the seam the test suite uses so `login`'s
+ * end-to-end tests never touch the real machine's home directory.
+ */
+declare function credentialsPath(): string;
+/** Reads the whole file. Missing or corrupt ⇒ empty (a corrupt file is not fatal, just unlucky). */
+declare function readCredentials(): Promise<CredentialsFile>;
+/** Reads the stored credential for one control URL, or `undefined` if there is none. */
+declare function readCredential(controlUrl: string): Promise<StoredCredential | undefined>;
+/** Merges one control URL's credential into the file and writes it back, mode 0600. */
+declare function writeCredential(controlUrl: string, credential: StoredCredential): Promise<string>;
+/** Removes one control URL's credential (used by tests; not currently wired to a command). */
+declare function deleteCredential(controlUrl: string): Promise<void>;
+/**
+ * The production control plane, used when nothing more specific is known. Since the single-origin
+ * merge the control API lives at the apex; `control.irt.io` has DNS but no certificate, so the
+ * old default died at the TLS handshake with a bare "fetch failed".
+ */
+declare const DEFAULT_CONTROL_URL = "https://irt.io";
+/** `--url`, else `IRT_CONTROL_URL`, else the production control plane. */
+declare function resolveControlUrl(flag: string | undefined): string;
+/**
+ * `resolveControlUrl`, plus the one thing a user always means: **if you signed in somewhere, talk
+ * to that somewhere.**
+ *
+ * `irtio login --url https://example.test` stores the credential under that URL, but every later
+ * command used to default to `https://control.irt.io` and answer `not logged in` while a perfectly
+ * good credential sat in the file under a different key. Real time was lost to exactly
+ * that during testing, escaped only by reading the CLI's compiled source.
+ *
+ * So: an explicit `--url` or `IRT_CONTROL_URL` still wins, and a file holding credentials for
+ * several control planes stays ambiguous and falls back to the default (guessing between two
+ * logins would be worse than the default). But the overwhelmingly common case — exactly one
+ * stored login — now resolves to that one.
+ */
+declare function resolveControlUrlForUser(flag: string | undefined): Promise<string>;
+
+export { type CredentialsFile, DEFAULT_CONTROL_URL, type StoredCredential, credentialsPath, deleteCredential, readCredential, readCredentials, resolveControlUrl, resolveControlUrlForUser, writeCredential };

package/dist/credentials.js

@@ -0,0 +1,20 @@
+import {
+  DEFAULT_CONTROL_URL,
+  credentialsPath,
+  deleteCredential,
+  readCredential,
+  readCredentials,
+  resolveControlUrl,
+  resolveControlUrlForUser,
+  writeCredential
+} from "./chunk-UPHQM6NZ.js";
+export {
+  DEFAULT_CONTROL_URL,
+  credentialsPath,
+  deleteCredential,
+  readCredential,
+  readCredentials,
+  resolveControlUrl,
+  resolveControlUrlForUser,
+  writeCredential
+};