@mutmutco/installer-launcher 1.3.0 → 1.4.0

package/README.md

@@ -57,6 +57,50 @@ Only `login` (and the login half of `install`) opens a browser:
 The product dir defaults to `~/.<product>/` on mac/linux and `%LOCALAPPDATA%\<product>` on
 Windows, and holds `tokens.json` (0600), `state.json`, and `payload/`.
 
+## Noninteractive session API
+
+`@mutmutco/installer-launcher/session` is a plain ESM entry with TypeScript definitions;
+importing it does not start the CLI or load a baked product config.
+
+```ts
+import { getAccessToken, LoginRequiredError } from '@mutmutco/installer-launcher/session';
+
+try {
+  const accessToken = await getAccessToken({
+    product: 'example-product',
+    host: 'https://gate.example.com',
+    loginKind: 'github', // explicit; use 'google' for a Google product gate
+    signal: AbortSignal.timeout(40_000), // shared with the caller's entire attempt
+  });
+  // Use accessToken for authenticated requests; never log it.
+} catch (error) {
+  if (error instanceof LoginRequiredError) {
+    // Ask the caller to sign in using its normal product login flow.
+  } else {
+    throw error; // transport, timeout, cancellation, storage or lock failure
+  }
+}
+```
+
+All three identity options are required; no host/product/protocol is inferred. The API
+reuses the machine's gate session and returns only its access token. Tokens within 60 seconds
+of expiry are refreshed and persisted using the launcher's private store. It never opens a
+browser, invokes `gh`, starts device authentication, or exposes the token-file format.
+Missing/unusable sessions and permanent refresh rejection (GitHub gate 403; Google OAuth 400/401/403, e.g. expired or revoked grants) throw `LoginRequiredError`; a release
+resource's `ForbiddenError` instead means revoked release access and is not this error.
+Network and non-403 HTTP failures propagate without erasing the session.
+
+Optional `dir` overrides `LAUNCHER_DIR`, then the usual platform product directory applies.
+Optional `fetch` injects a transport for tests and must honor the supplied AbortSignal.
+`timeoutMs` defaults to 10,000 and must be a positive integer at most 40,000. Its signal is
+composed with `signal` and any transport input signal; cancellation is checked before
+persisting or clearing refreshed tokens. For a 40-second attempt / 120-second overall staging
+budget, pass the caller's attempt signal and keep the auth timeout inside that budget.
+
+Calls take the existing installation lock and fail rather than queue behind another owner.
+This protects callers using that lock, not all concurrent token writers: existing login paths
+can release it before authentication. Do not assume cross-process refresh coalescing.
+
 ## Config
 
 `config/product.template.json` per product:
@@ -245,7 +289,7 @@ atomically only after convergence succeeds. On failure or interrupted startup it
 consumer rollback before allowing another install or forwarding. Failed rollback stays pending.
 A crash after shared commit completes the receipt instead of reverting the committed product.
 Host registration is not atomic: failures can leave host references to retained candidates.
-Candidates are deliberately retained until product-owned reference evidence can permit cleanup.
+After a committed promotion the launcher removes candidate folders `state.json` no longer references (the active one is kept; symlinks and junctions are skipped; a failed delete is logged). A failed activation keeps its candidate.
 An orphan lock-recovery guard fails closed and needs operator diagnosis.
 
 For already-shipped old launchers, copy the exact file exported by

package/dist/launcher.js

@@ -6,7 +6,7 @@ import { randomUUID as randomUUID4 } from "node:crypto";
 
 // src/acquisition.ts
 import { createHash as createHash3, randomUUID as randomUUID3 } from "node:crypto";
-import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4, unlinkSync, realpathSync as realpathSync2 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync4, readFileSync as readFileSync4, writeFileSync as writeFileSync4, unlinkSync, realpathSync as realpathSync2, readdirSync, lstatSync, rmSync as rmSync4 } from "node:fs";
 import { join as join4, resolve, relative as relative2, isAbsolute as isAbsolute2, dirname as dirname2 } from "node:path";
 
 // src/runtime.ts
@@ -617,6 +617,28 @@ async function recoverAcquisition(dir, run2, env) {
   else if (existsSync5(statePath(dir))) unlinkSync(statePath(dir));
   unlinkSync(pendingPath(dir));
 }
+function reapCandidates(dir) {
+  const keep = readState(dir)?.acquired?.candidate;
+  if (!keep) return;
+  const base = join4(dir, "candidates");
+  let names;
+  try {
+    names = readdirSync(base);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name === keep || !/^[a-zA-Z0-9_-]+$/.test(name)) continue;
+    try {
+      const path = join4(base, name);
+      const info = lstatSync(path);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      rmSync4(path, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`launcher: could not remove old candidate ${name}: ${error.message}`);
+    }
+  }
+}
 async function installAcquisition(dir, candidate, version, acquisition, options) {
   if (!acquisition.platforms.includes(`${process.platform}-${process.arch}`)) throw new Error("this product does not support this platform");
   const root = candidateRoot(dir, candidate);
@@ -673,11 +695,12 @@ async function installAcquisition(dir, candidate, version, acquisition, options)
     throw error;
   }
   unlinkSync(pendingPath(dir));
+  reapCandidates(dir);
 }
 
 // src/index.ts
 import { spawn as spawn2, spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync8, readFileSync as readFileSync8, statSync as statSync2, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, rmdirSync, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync6, writeFileSync as writeFileSync8 } from "node:fs";
+import { existsSync as existsSync8, readFileSync as readFileSync8, statSync as statSync2, mkdtempSync as mkdtempSync2, unlinkSync as unlinkSync2, rmdirSync, mkdirSync as mkdirSync6, renameSync as renameSync5, rmSync as rmSync7, writeFileSync as writeFileSync8 } from "node:fs";
 import { tmpdir as tmpdir4 } from "node:os";
 import { dirname as dirname4, join as join7, resolve as resolve3 } from "node:path";
 import { isSea } from "node:sea";
@@ -1554,7 +1577,7 @@ var rowTitle = (row) => `${row.surface}${row.aspect ? ` ${row.aspect}` : ""}${ro
 
 // src/autoupdate.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync6, rmSync as rmSync4, writeFileSync as writeFileSync6 } from "node:fs";
+import { existsSync as existsSync6, mkdirSync as mkdirSync5, readFileSync as readFileSync6, rmSync as rmSync5, writeFileSync as writeFileSync6 } from "node:fs";
 import { tmpdir as tmpdir3 } from "node:os";
 import { join as join5 } from "node:path";
 function schedulePlatform(override) {
@@ -1649,20 +1672,20 @@ function disableSchedule(config, options = {}) {
     if (result.code !== 0 && !/cannot find|does not exist/i.test(`${result.stdout} ${result.stderr}`)) {
       throw new Error(`Could not turn auto-update off: ${firstLine(result.stdout || result.stderr) || `exit ${result.code}`}`);
     }
-    rmSync4(join5(options.stateDir ?? defaultProductDir(config.product), HIDDEN_SCRIPT), { force: true });
+    rmSync5(join5(options.stateDir ?? defaultProductDir(config.product), HIDDEN_SCRIPT), { force: true });
     return;
   }
   if (platform === "darwin") {
     const label2 = scheduleLabel(config);
     exec("launchctl", ["bootout", `gui/${process.getuid?.() ?? 501}/${label2}`]);
-    rmSync4(join5(home, "Library", "LaunchAgents", `${label2}.plist`), { force: true });
+    rmSync5(join5(home, "Library", "LaunchAgents", `${label2}.plist`), { force: true });
     return;
   }
   const label = scheduleLabel(config);
   const dir = join5(home, ".config", "systemd", "user");
   exec("systemctl", ["--user", "disable", "--now", `${label}.timer`]);
-  rmSync4(join5(dir, `${label}.service`), { force: true });
-  rmSync4(join5(dir, `${label}.timer`), { force: true });
+  rmSync5(join5(dir, `${label}.service`), { force: true });
+  rmSync5(join5(dir, `${label}.timer`), { force: true });
 }
 function querySchedule(config, options = {}) {
   const platform = schedulePlatform(options.platform);
@@ -1988,7 +2011,8 @@ async function refreshGoogleToken(host, clientId, refreshToken, fetchImpl = fetc
       client_id: clientId
     }).toString()
   });
-  if (!response.ok) return null;
+  if ([400, 401, 403].includes(response.status)) return null;
+  if (!response.ok) throw new Error(`POST ${server}/oauth/token \u2192 ${response.status}: refresh failed`);
   const tokens = await response.json();
   if (typeof tokens.access_token !== "string" || typeof tokens.expires_in !== "number") return null;
   return {
@@ -2003,13 +2027,15 @@ function page(title, body) {
 }
 
 // src/tokens.ts
-async function ensureFreshToken(config, dir, fetchImpl = fetch) {
+async function ensureFreshToken(config, dir, fetchImpl = fetch, signal) {
+  signal?.throwIfAborted();
   const stored = readTokens(dir);
   if (!stored) return null;
   if (stored.expiresAt - Date.now() > 6e4) return stored.accessToken;
   if (!stored.refreshToken) return null;
   if (config.loginKind === "github") {
     const refreshed2 = await refreshAccessToken(config, stored.refreshToken, fetchImpl);
+    signal?.throwIfAborted();
     if (!refreshed2) {
       clearTokens(dir);
       return null;
@@ -2026,6 +2052,7 @@ async function ensureFreshToken(config, dir, fetchImpl = fetch) {
     return null;
   }
   const refreshed = await refreshGoogleToken(config.host, stored.clientId, stored.refreshToken, fetchImpl);
+  signal?.throwIfAborted();
   if (!refreshed) {
     clearTokens(dir);
     return null;
@@ -2041,7 +2068,7 @@ async function ensureFreshToken(config, dir, fetchImpl = fetch) {
 
 // src/refresh.ts
 import { execFile } from "node:child_process";
-import { accessSync, chmodSync, constants, existsSync as existsSync7, lstatSync, readdirSync, readFileSync as readFileSync7, realpathSync as realpathSync3, renameSync as renameSync4, rmSync as rmSync5, statSync, writeFileSync as writeFileSync7 } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync as existsSync7, lstatSync as lstatSync2, readdirSync as readdirSync2, readFileSync as readFileSync7, realpathSync as realpathSync3, renameSync as renameSync4, rmSync as rmSync6, statSync, writeFileSync as writeFileSync7 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname as dirname3, join as join6, resolve as resolve2 } from "node:path";
 var LAUNCHER_RECORD_FILE = "launcher.json";
@@ -2157,14 +2184,14 @@ function removeStale(file) {
   const prefix = `${basename(file)}.old-`;
   let names;
   try {
-    names = readdirSync(dirname3(file));
+    names = readdirSync2(dirname3(file));
   } catch {
     return;
   }
   for (const name of names) {
     if (!name.startsWith(prefix)) continue;
     try {
-      rmSync5(join6(dirname3(file), name), { force: true });
+      rmSync6(join6(dirname3(file), name), { force: true });
     } catch {
     }
   }
@@ -2177,7 +2204,7 @@ async function refreshLauncher(target, options = {}) {
   const productDir = options.productDir ?? defaultProductDir(target.product);
   const recorded = recordedPath(productDir);
   const file = options.path ?? (recorded && existsSync7(recorded) ? recorded : installedPath(target, productDir, platform));
-  if (!existsSync7(file) || lstatSync(file).isSymbolicLink()) return null;
+  if (!existsSync7(file) || lstatSync2(file).isSymbolicLink()) return null;
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
@@ -2226,7 +2253,7 @@ async function refreshLauncher(target, options = {}) {
         if (moved && !existsSync7(file)) renameSync4(moved, file);
       } catch {
       }
-      rmSync5(next, { force: true });
+      rmSync6(next, { force: true });
       return arm("fail", from, "The launcher could not be replaced.");
     }
     return arm("ok", record.version, "");
@@ -2236,7 +2263,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.3.0" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.4.0" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);
@@ -2758,7 +2785,7 @@ async function installOrUpdateRun(config, dir, options, print, update, flags2, m
       }
       const target = join7(dir, "payload");
       mkdirSync6(dir, { recursive: true });
-      rmSync6(target, { recursive: true, force: true });
+      rmSync7(target, { recursive: true, force: true });
       renameSync5(join7(candidateDir, "payload"), target);
       writeState(dir, { version, updatedAt: (/* @__PURE__ */ new Date()).toISOString() });
       installer.phase("download", { seconds: (Date.now() - started) / 1e3 });

package/dist/launcher.sea.cjs

@@ -650,6 +650,28 @@ async function recoverAcquisition(dir, run2, env) {
   else if ((0, import_node_fs5.existsSync)(statePath(dir))) (0, import_node_fs5.unlinkSync)(statePath(dir));
   (0, import_node_fs5.unlinkSync)(pendingPath(dir));
 }
+function reapCandidates(dir) {
+  const keep = readState(dir)?.acquired?.candidate;
+  if (!keep) return;
+  const base = (0, import_node_path4.join)(dir, "candidates");
+  let names;
+  try {
+    names = (0, import_node_fs5.readdirSync)(base);
+  } catch {
+    return;
+  }
+  for (const name of names) {
+    if (name === keep || !/^[a-zA-Z0-9_-]+$/.test(name)) continue;
+    try {
+      const path = (0, import_node_path4.join)(base, name);
+      const info = (0, import_node_fs5.lstatSync)(path);
+      if (!info.isDirectory() || info.isSymbolicLink()) continue;
+      (0, import_node_fs5.rmSync)(path, { recursive: true, force: true });
+    } catch (error) {
+      console.error(`launcher: could not remove old candidate ${name}: ${error.message}`);
+    }
+  }
+}
 async function installAcquisition(dir, candidate, version, acquisition, options) {
   if (!acquisition.platforms.includes(`${process.platform}-${process.arch}`)) throw new Error("this product does not support this platform");
   const root = candidateRoot(dir, candidate);
@@ -706,6 +728,7 @@ async function installAcquisition(dir, candidate, version, acquisition, options)
     throw error;
   }
   (0, import_node_fs5.unlinkSync)(pendingPath(dir));
+  reapCandidates(dir);
 }
 
 // src/index.ts
@@ -2021,7 +2044,8 @@ async function refreshGoogleToken(host, clientId, refreshToken, fetchImpl = fetc
       client_id: clientId
     }).toString()
   });
-  if (!response.ok) return null;
+  if ([400, 401, 403].includes(response.status)) return null;
+  if (!response.ok) throw new Error(`POST ${server}/oauth/token \u2192 ${response.status}: refresh failed`);
   const tokens = await response.json();
   if (typeof tokens.access_token !== "string" || typeof tokens.expires_in !== "number") return null;
   return {
@@ -2036,13 +2060,15 @@ function page(title, body) {
 }
 
 // src/tokens.ts
-async function ensureFreshToken(config, dir, fetchImpl = fetch) {
+async function ensureFreshToken(config, dir, fetchImpl = fetch, signal) {
+  signal?.throwIfAborted();
   const stored = readTokens(dir);
   if (!stored) return null;
   if (stored.expiresAt - Date.now() > 6e4) return stored.accessToken;
   if (!stored.refreshToken) return null;
   if (config.loginKind === "github") {
     const refreshed2 = await refreshAccessToken(config, stored.refreshToken, fetchImpl);
+    signal?.throwIfAborted();
     if (!refreshed2) {
       clearTokens(dir);
       return null;
@@ -2059,6 +2085,7 @@ async function ensureFreshToken(config, dir, fetchImpl = fetch) {
     return null;
   }
   const refreshed = await refreshGoogleToken(config.host, stored.clientId, stored.refreshToken, fetchImpl);
+  signal?.throwIfAborted();
   if (!refreshed) {
     clearTokens(dir);
     return null;
@@ -2269,7 +2296,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.3.0" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.4.0" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);

package/dist/refresh.js

@@ -1,12 +1,12 @@
 // src/refresh.ts
 import { execFile } from "node:child_process";
-import { accessSync, chmodSync, constants, existsSync as existsSync2, lstatSync, readdirSync, readFileSync as readFileSync2, realpathSync as realpathSync2, renameSync, rmSync, statSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { accessSync, chmodSync, constants, existsSync as existsSync2, lstatSync as lstatSync2, readdirSync as readdirSync2, readFileSync as readFileSync2, realpathSync as realpathSync2, renameSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname as dirname2, join as join3, resolve as resolve2 } from "node:path";
 
 // src/acquisition.ts
 import { createHash as createHash2, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, realpathSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, realpathSync, readdirSync, lstatSync, rmSync } from "node:fs";
 import { join as join2, resolve, relative, isAbsolute, dirname } from "node:path";
 
 // src/download.ts
@@ -290,14 +290,14 @@ function removeStale(file) {
   const prefix = `${basename(file)}.old-`;
   let names;
   try {
-    names = readdirSync(dirname2(file));
+    names = readdirSync2(dirname2(file));
   } catch {
     return;
   }
   for (const name of names) {
     if (!name.startsWith(prefix)) continue;
     try {
-      rmSync(join3(dirname2(file), name), { force: true });
+      rmSync2(join3(dirname2(file), name), { force: true });
     } catch {
     }
   }
@@ -310,7 +310,7 @@ async function refreshLauncher(target, options = {}) {
   const productDir = options.productDir ?? defaultProductDir(target.product);
   const recorded = recordedPath(productDir);
   const file = options.path ?? (recorded && existsSync2(recorded) ? recorded : installedPath(target, productDir, platform));
-  if (!existsSync2(file) || lstatSync(file).isSymbolicLink()) return null;
+  if (!existsSync2(file) || lstatSync2(file).isSymbolicLink()) return null;
   if (!options.dryRun) removeStale(file);
   const from = await (options.readVersion ?? ((path) => runVersion(path, target.bin)))(file);
   if (!from) return null;
@@ -359,7 +359,7 @@ async function refreshLauncher(target, options = {}) {
         if (moved && !existsSync2(file)) renameSync(moved, file);
       } catch {
       }
-      rmSync(next, { force: true });
+      rmSync2(next, { force: true });
       return arm("fail", from, "The launcher could not be replaced.");
     }
     return arm("ok", record.version, "");

package/dist/session.d.ts

@@ -0,0 +1,19 @@
+export interface SessionOptions {
+    product: string;
+    host: string;
+    loginKind: 'github' | 'google';
+    /** Overrides LAUNCHER_DIR and the platform's default product directory. */
+    dir?: string;
+    /** Optional transport injection; defaults to the global fetch. */
+    fetch?: typeof fetch;
+    /** Cancellation for the caller's overall attempt. */
+    signal?: AbortSignal;
+    /** Auth budget in milliseconds: defaults to 10,000; positive and at most 40,000. */
+    timeoutMs?: number;
+}
+/** The caller must arrange sign-in; this API never starts authentication. */
+export declare class LoginRequiredError extends Error {
+    constructor();
+}
+/** Returns an existing gate access token, refreshing and persisting it when necessary. */
+export declare function getAccessToken(options: SessionOptions): Promise<string>;

package/dist/session.js

@@ -0,0 +1,236 @@
+// src/acquisition.ts
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2, unlinkSync, realpathSync, readdirSync, lstatSync, rmSync as rmSync2 } from "node:fs";
+import { join as join2, resolve, relative, isAbsolute, dirname } from "node:path";
+
+// src/store.ts
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync, renameSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+function defaultProductDir(product) {
+  if (process.platform === "win32") {
+    const base = process.env.LOCALAPPDATA ?? join(tmpdir(), "launcher-fallback");
+    return join(base, product);
+  }
+  const home = process.env.HOME ?? tmpdir();
+  return join(home, `.${product}`);
+}
+function resolveProductDir(product, explicit) {
+  return explicit ?? process.env.LAUNCHER_DIR ?? defaultProductDir(product);
+}
+function tokensPath(dir) {
+  return join(dir, "tokens.json");
+}
+function readTokens(dir) {
+  try {
+    const data = JSON.parse(readFileSync(tokensPath(dir), "utf8"));
+    if (typeof data.accessToken !== "string" || !data.accessToken) return null;
+    if (typeof data.expiresAt !== "number" || !Number.isFinite(data.expiresAt)) return null;
+    const tokens = { accessToken: data.accessToken, expiresAt: data.expiresAt };
+    if (typeof data.refreshToken === "string" && data.refreshToken) tokens.refreshToken = data.refreshToken;
+    if (typeof data.clientId === "string" && data.clientId) tokens.clientId = data.clientId;
+    return tokens;
+  } catch {
+    return null;
+  }
+}
+function writeTokens(dir, tokens) {
+  mkdirSync(dir, { recursive: true });
+  try {
+    writeFileSync(tokensPath(dir), `${JSON.stringify(tokens)}
+`, { mode: 384 });
+  } catch {
+    writeFileSync(tokensPath(dir), `${JSON.stringify(tokens)}
+`);
+  }
+}
+function clearTokens(dir) {
+  rmSync(tokensPath(dir), { force: true });
+}
+
+// src/config.ts
+import { getAsset } from "node:sea";
+
+// src/acquisition.ts
+function lockInstallation(dir) {
+  mkdirSync2(dir, { recursive: true });
+  const path = join2(dir, "installation.lock");
+  const owner = `${process.pid}:${randomUUID()}`;
+  try {
+    writeFileSync2(path, owner, { flag: "wx", mode: 384 });
+  } catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const recovery = `${path}.recovery`;
+    try {
+      writeFileSync2(recovery, owner, { flag: "wx", mode: 384, flush: true });
+    } catch {
+      throw new Error("installation lock recovery is already pending");
+    }
+    try {
+      const previous = readFileSync2(path, "utf8");
+      const pid = Number(previous.split(":")[0]);
+      if (!Number.isInteger(pid) || pid <= 0) throw new Error("installation lock is malformed; recovery required");
+      try {
+        process.kill(pid, 0);
+        throw new Error("another installer is running");
+      } catch (probe) {
+        if (probe.code !== "ESRCH") throw probe;
+      }
+      unlinkSync(path);
+      writeFileSync2(path, owner, { flag: "wx", mode: 384, flush: true });
+    } finally {
+      unlinkSync(recovery);
+    }
+  }
+  let released = false;
+  return () => {
+    if (!released && readFileSync2(path, "utf8") === owner) unlinkSync(path);
+    released = true;
+  };
+}
+
+// src/login-github.ts
+async function postJson(url, body, fetchImpl) {
+  return fetchImpl(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+}
+async function readBody(response) {
+  try {
+    return await response.text();
+  } catch {
+    return "";
+  }
+}
+function gateRefusal(method, url, status, body) {
+  const head = body.replace(/\s+/g, " ").trim().slice(0, 200);
+  return `the sign-in server refused the request \u2014 ${method} ${url} \u2192 ${status}${head ? `: ${head}` : ""}`;
+}
+async function refreshAccessToken(config, refreshToken, fetchImpl = fetch) {
+  const url = `${config.host}/gate/refresh`;
+  const response = await postJson(url, { refresh_token: refreshToken }, fetchImpl);
+  if (response.status === 403) return null;
+  if (!response.ok) {
+    throw new Error(gateRefusal("POST", url, response.status, await readBody(response)));
+  }
+  const data = await response.json();
+  if (typeof data.access_token !== "string" || typeof data.expires_in !== "number") {
+    throw new Error("the sign-in server returned a malformed refresh");
+  }
+  return {
+    accessToken: data.access_token,
+    expiresIn: data.expires_in,
+    ...typeof data.refresh_token === "string" ? { refreshToken: data.refresh_token } : {}
+  };
+}
+
+// src/login-google.ts
+async function refreshGoogleToken(host, clientId, refreshToken, fetchImpl = fetch) {
+  const server = host.replace(/\/+$/, "");
+  const response = await fetchImpl(`${server}/oauth/token`, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: clientId
+    }).toString()
+  });
+  if ([400, 401, 403].includes(response.status)) return null;
+  if (!response.ok) throw new Error(`POST ${server}/oauth/token \u2192 ${response.status}: refresh failed`);
+  const tokens = await response.json();
+  if (typeof tokens.access_token !== "string" || typeof tokens.expires_in !== "number") return null;
+  return {
+    accessToken: tokens.access_token,
+    refreshToken: typeof tokens.refresh_token === "string" ? tokens.refresh_token : refreshToken,
+    expiresIn: tokens.expires_in
+  };
+}
+
+// src/tokens.ts
+async function ensureFreshToken(config, dir, fetchImpl = fetch, signal) {
+  signal?.throwIfAborted();
+  const stored = readTokens(dir);
+  if (!stored) return null;
+  if (stored.expiresAt - Date.now() > 6e4) return stored.accessToken;
+  if (!stored.refreshToken) return null;
+  if (config.loginKind === "github") {
+    const refreshed2 = await refreshAccessToken(config, stored.refreshToken, fetchImpl);
+    signal?.throwIfAborted();
+    if (!refreshed2) {
+      clearTokens(dir);
+      return null;
+    }
+    writeTokens(dir, {
+      accessToken: refreshed2.accessToken,
+      refreshToken: refreshed2.refreshToken ?? stored.refreshToken,
+      expiresAt: Date.now() + refreshed2.expiresIn * 1e3
+    });
+    return refreshed2.accessToken;
+  }
+  if (!stored.clientId) {
+    clearTokens(dir);
+    return null;
+  }
+  const refreshed = await refreshGoogleToken(config.host, stored.clientId, stored.refreshToken, fetchImpl);
+  signal?.throwIfAborted();
+  if (!refreshed) {
+    clearTokens(dir);
+    return null;
+  }
+  writeTokens(dir, {
+    accessToken: refreshed.accessToken,
+    refreshToken: refreshed.refreshToken,
+    expiresAt: Date.now() + refreshed.expiresIn * 1e3,
+    clientId: stored.clientId
+  });
+  return refreshed.accessToken;
+}
+
+// src/session.ts
+var LoginRequiredError = class extends Error {
+  constructor() {
+    super("Product sign-in is required.");
+    this.name = "LoginRequiredError";
+  }
+};
+async function getAccessToken(options) {
+  if (!options.product || options.loginKind !== "github" && options.loginKind !== "google") {
+    throw new Error("Session options require product and loginKind (github or google).");
+  }
+  const host = new URL(options.host);
+  if (host.protocol !== "https:" && host.protocol !== "http:") {
+    throw new Error("Session host must be an http(s) URL.");
+  }
+  const timeoutMs = options.timeoutMs ?? 1e4;
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 4e4) {
+    throw new Error("Session timeoutMs must be a positive integer at most 40000.");
+  }
+  const signal = AbortSignal.any([AbortSignal.timeout(timeoutMs), ...options.signal ? [options.signal] : []]);
+  signal.throwIfAborted();
+  const transport = options.fetch ?? fetch;
+  const fetchImpl = (input, init) => {
+    const inherited = init?.signal ?? (input instanceof Request ? input.signal : void 0);
+    return transport(input, { ...init, signal: inherited ? AbortSignal.any([signal, inherited]) : signal });
+  };
+  const dir = resolveProductDir(options.product, options.dir);
+  const unlock = lockInstallation(dir);
+  try {
+    const token = await ensureFreshToken(
+      { host: options.host.replace(/\/+$/, ""), loginKind: options.loginKind },
+      dir,
+      fetchImpl,
+      signal
+    );
+    if (!token) throw new LoginRequiredError();
+    return token;
+  } finally {
+    unlock();
+  }
+}
+export {
+  LoginRequiredError,
+  getAccessToken
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutmutco/installer-launcher",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Single-executable (SEA) launcher: sign-in, gated payload fetch, self-update. One copy ships per product.",
   "type": "module",
   "license": "UNLICENSED",
@@ -14,7 +14,11 @@
   "exports": {
     ".": "./dist/launcher.js",
     "./acquisition-required": "./dist/acquisition-required.mjs",
-    "./refresh": "./dist/refresh.js"
+    "./refresh": "./dist/refresh.js",
+    "./session": {
+      "types": "./dist/session.d.ts",
+      "import": "./dist/session.js"
+    }
   },
   "files": [
     "dist",