@mutmutco/installer-launcher 1.3.1 → 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:

package/dist/launcher.js

@@ -2011,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 {
@@ -2026,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;
@@ -2049,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;
@@ -2259,7 +2263,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.3.1" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.4.0" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);

package/dist/launcher.sea.cjs

@@ -2044,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 {
@@ -2059,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;
@@ -2082,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;
@@ -2292,7 +2296,7 @@ async function refreshLauncher(target, options = {}) {
 }
 
 // src/index.ts
-var LAUNCHER_VERSION = true ? "1.3.1" : readVersionFromPackage();
+var LAUNCHER_VERSION = true ? "1.4.0" : readVersionFromPackage();
 function defaultPrint(message) {
   process.stdout.write(`${message}
 `);

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.1",
+  "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",