factoryhub 0.1.0 → 0.1.1

package/packages/engine/lib/credentials.mjs

@@ -0,0 +1,121 @@
+// Where the factoryhub CLI and SDK keep personal access tokens.
+//
+//   FACTORYHUB_TOKEN                                      wins when it is set
+//   ${XDG_CONFIG_HOME:-~/.config}/factoryhub/credentials.json   otherwise
+//
+// The file maps each hub address to the token `factoryhub login` stored for
+// it, with the token's name, scopes, expiry and origin: "device" for a token
+// this computer received by device login, "pasted" for one the person passed
+// in. On macOS and Linux only the person may read it (mode 0600, in a 0700
+// folder), and a file others can read is refused, as ssh refuses a readable
+// key. On Windows no permissions are set: the file is as private as the
+// person's user folder. Nothing here prints or logs a token.
+//
+// FACTORYHUB_TOKEN goes only to the production hub, or to the hub named in
+// FACTORYHUB_BASE_URL: a --base-url pointing elsewhere does not receive it.
+import { readFile, writeFile, rename, mkdir, chmod, stat, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import { DEFAULT_HUB, TOKEN_PATTERN } from './hub.mjs';
+
+export const TOKEN_ENV = 'FACTORYHUB_TOKEN';
+export { TOKEN_PATTERN };
+const POSIX = process.platform !== 'win32';
+
+/** How private the credentials file is on this computer, for messages. */
+export const PRIVACY = POSIX
+  ? 'readable only by you (mode 0600)'
+  : 'protected only by your Windows user folder\'s permissions: factoryhub does not set file permissions on Windows';
+
+/** The credentials file for this environment. */
+export function credentialsPath(env = process.env) {
+  const config = env.XDG_CONFIG_HOME || join(env.HOME || env.USERPROFILE || homedir(), '.config');
+  return join(config, 'factoryhub', 'credentials.json');
+}
+
+async function readAll(env) {
+  const path = credentialsPath(env);
+  let info;
+  try { info = await stat(path); } catch (error) {
+    if (error.code === 'ENOENT') return {};
+    throw error;
+  }
+  if (POSIX && (info.mode & 0o077)) throw new Error(`${path} can be read by other users of this computer, so factoryhub will not use it. Run "chmod 600 ${path}" and try again.`);
+  let parsed;
+  try { parsed = JSON.parse(await readFile(path, 'utf8')); } catch {
+    throw new Error(`${path} is not valid JSON. Delete it and run "factoryhub login" again.`);
+  }
+  return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : {};
+}
+
+async function writeAll(env, all) {
+  const path = credentialsPath(env);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  // Written beside the file and renamed over it, so a crash never leaves half
+  // a file, and created 0600 so the token is never readable by others.
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    await writeFile(temporary, `${JSON.stringify(all, null, 2)}\n`, { mode: 0o600, flag: 'wx' });
+    if (POSIX) await chmod(temporary, 0o600);
+    await rename(temporary, path);
+  } catch (error) {
+    await rm(temporary, { force: true });
+    throw error;
+  }
+}
+
+/** The stored record for one hub, or null. */
+export async function storedCredential(base, env = process.env) {
+  const record = (await readAll(env))[base];
+  return record && typeof record.token === 'string' ? record : null;
+}
+
+/**
+ * Stores the token `login` received for one hub, replacing any earlier one.
+ * `record.origin` is "device" for a token received by device login on this
+ * computer, "pasted" for one passed in; only a "device" token is ever revoked
+ * when a later login replaces it.
+ */
+export async function saveCredential(base, record, env = process.env) {
+  if (!TOKEN_PATTERN.test(record?.token || '')) throw new Error('That is not a factoryhub personal access token.');
+  if (!['device', 'pasted'].includes(record.origin)) throw new Error('A stored token needs its origin: "device" or "pasted".');
+  const all = await readAll(env);
+  all[base] = { ...record, saved: new Date().toISOString() };
+  await writeAll(env, all);
+  return credentialsPath(env);
+}
+
+/** Forgets the token stored for one hub. True when there was one. */
+export async function deleteCredential(base, env = process.env) {
+  const all = await readAll(env);
+  if (!all[base]) return false;
+  delete all[base];
+  if (Object.keys(all).length) await writeAll(env, all);
+  else await rm(credentialsPath(env), { force: true });
+  return true;
+}
+
+/** The same hub address, written either way: no trailing slash. */
+const sameBase = (a, b) => Boolean(a && b) && String(a).replace(/\/+$/, '') === String(b).replace(/\/+$/, '');
+
+/** Whether FACTORYHUB_TOKEN may be sent to `base`: production, or the hub FACTORYHUB_BASE_URL names. */
+export function envTokenGoesTo(base, env = process.env) {
+  return sameBase(base, DEFAULT_HUB) || sameBase(base, env.FACTORYHUB_BASE_URL);
+}
+
+/**
+ * The token to send to one hub: FACTORYHUB_TOKEN, else the stored one.
+ * FACTORYHUB_TOKEN is used only for production or the hub FACTORYHUB_BASE_URL
+ * names; for any other hub it is left out and `warning` says so.
+ * Returns { token, source: 'env' | 'file' | null, record, expired, warning }.
+ */
+export async function resolveToken(base, env = process.env, now = Date.now()) {
+  const fromEnv = (env[TOKEN_ENV] || '').trim();
+  let warning = null;
+  if (fromEnv && envTokenGoesTo(base, env)) return { token: fromEnv, source: 'env', record: null, expired: false, warning };
+  if (fromEnv) warning = `FACTORYHUB_TOKEN was not sent to ${String(base).replace(/\/+$/, '')}: it goes only to ${DEFAULT_HUB} or to the address in FACTORYHUB_BASE_URL.`;
+  const record = await storedCredential(base, env);
+  if (!record) return { token: null, source: null, record: null, expired: false, warning };
+  const expired = Boolean(record.expires) && Date.parse(record.expires) <= now;
+  return { token: expired ? null : record.token, source: 'file', record, expired, warning };
+}

package/packages/engine/lib/hosted.mjs

@@ -0,0 +1,119 @@
+// Hosted runs on a factoryhub site, through /api/v1: follow a run's events,
+// stop where it waits for the person, and read the whole result with its
+// signed receipt. Shared by the CLI and the SDK. Nothing here decides a step:
+// a decision is sent only when the caller passes one the person made.
+import { randomUUID } from 'node:crypto';
+import { verifyReceipt, fromBase64Url } from '../src/factory-engine.mjs';
+import { DEFAULT_HUB } from './hub.mjs';
+
+/**
+ * The receipt signing keys of the production hub, pinned by the SHA-256 of
+ * the raw Ed25519 public key. A receipt from https://factory.mindburn.org
+ * verifies only against these, whatever its key endpoint answers; a new key
+ * needs a release. Read from
+ * https://factory.mindburn.org/.well-known/factory-hub-keys.json:
+ *   hub-20a58d31af55  created 2026-11-10T14:17:31.177Z
+ */
+export const PINNED_KEYS = Object.freeze({
+  [DEFAULT_HUB]: Object.freeze(['3c2acc0709aef8748b5dd8b8ea6574a4ddbdd9911096fc6b89242425f6a9e62d']),
+});
+
+/** The SHA-256 of a published key's raw public key bytes, or null when it is not one. */
+export async function keyFingerprint(key) {
+  try {
+    const raw = fromBase64Url(String(key?.public_key || ''));
+    if (raw.length !== 32) return null;
+    return [...new Uint8Array(await crypto.subtle.digest('SHA-256', raw))].map((byte) => byte.toString(16).padStart(2, '0')).join('');
+  } catch { return null; }
+}
+
+/**
+ * Checks a hosted run's receipt the way the CLI and SDK report it:
+ *   - the signature, against the pinned keys for the production hub, or
+ *     against the keys the hub at `base` publishes for any other address;
+ *   - the receipt's issuer, against the hub's host;
+ *   - with `text`, the deliverable against the hash the receipt records.
+ * `keys` are the hub's published keys; `pinned` overrides PINNED_KEYS (tests).
+ * Returns verifyReceipt's answer plus { trust, host, issuer, issuerMatches, verified }.
+ * `trust` is "pinned" or "published"; `verified` is the one answer to act on.
+ */
+export async function checkHostedReceipt(receipt, { base, keys, text, pinned = PINNED_KEYS } = {}) {
+  const url = new URL(base);
+  const host = url.host;
+  const pins = pinned[url.origin] || null;
+  let usable = Array.isArray(keys) ? keys : [];
+  if (pins) {
+    const fingerprints = await Promise.all(usable.map(keyFingerprint));
+    usable = usable.filter((_, index) => fingerprints[index] && pins.includes(fingerprints[index]));
+  }
+  const result = await verifyReceipt(receipt, usable, text);
+  if (pins && result.signed && !usable.some((key) => key.key_id === result.keyId)) {
+    result.problems = result.problems.map((problem) => (problem.startsWith('No published key with id') ? `Key ${result.keyId} is not one of the production keys pinned in this version of factoryhub.` : problem));
+  }
+  const issuer = receipt && typeof receipt === 'object' ? receipt.issuer ?? null : null;
+  const issuerMatches = issuer === host;
+  if (receipt?.kind === 'factory-run-receipt' && !issuerMatches) result.problems.push(`The receipt names its issuer as ${issuer === null ? 'nobody' : `"${issuer}"`}, not ${host}.`);
+  return { ...result, trust: pins ? 'pinned' : 'published', host, issuer, issuerMatches, verified: result.signatureValid && result.deliverableMatches !== false && issuerMatches };
+}
+
+/** One line for a person: what the receipt check found. */
+export function receiptVerdict(verification) {
+  if (verification.verified) {
+    return verification.trust === 'pinned'
+      ? `signature valid against a production key pinned in factoryhub (${verification.keyId})`
+      : `signature valid against keys published by ${verification.host}`;
+  }
+  return `not verified: ${verification.problems.join(' ') || 'unknown reason'}`;
+}
+
+/** Run states after which nothing more happens. */
+export const FINISHED = new Set(['done', 'failed', 'stopped', 'expired', 'deleted', 'cancelled', 'canceled']);
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** An Idempotency-Key for one start: the same key retried returns the same run. */
+export const newIdempotencyKey = () => `fh-${randomUUID()}`;
+
+/**
+ * Polls a run until it finishes or waits for a decision. Calls onEvent for
+ * every new event, in order. Returns the last run view.
+ */
+export async function followRun(hub, id, { onEvent = () => {}, sleep = wait, every = 2000, after = 0 } = {}) {
+  let cursor = after;
+  let shown = -1;
+  for (;;) {
+    const run = await hub.getRun(id, { after: cursor });
+    for (const event of run.events || []) {
+      if (Number.isInteger(event.i) && event.i <= shown) continue;
+      if (Number.isInteger(event.i)) shown = event.i;
+      await onEvent(event, run);
+    }
+    if (Number.isInteger(run.cursor) && run.cursor > cursor) cursor = run.cursor;
+    if (run.waiting || FINISHED.has(run.status)) return run;
+    await sleep(every);
+  }
+}
+
+const MAX_PAGES = 1000;
+
+/**
+ * The whole result of a finished run, paged in, with the receipt checked
+ * here (checkHostedReceipt), not only by the hub. Returns null when the run
+ * is not done or the hub sent no result.
+ * Returns { text, receipt, verification, review, sha256 }.
+ */
+export async function runResult(hub, id, { keys, pinned } = {}) {
+  let run = await hub.getRun(id, { offset: 0 });
+  if (run?.status !== 'done' || !run.result || typeof run.result.text !== 'string') return null;
+  const receipt = run.receipt || null;
+  let text = run.result.text;
+  for (let pages = 1; Number.isInteger(run.result.nextOffset) && run.result.nextOffset > 0; pages += 1) {
+    if (pages >= MAX_PAGES) throw new Error(`The result of run ${id} did not end after ${MAX_PAGES} pages.`);
+    run = await hub.getRun(id, { offset: run.result.nextOffset });
+    if (!run?.result || typeof run.result.text !== 'string') throw new Error(`The hub stopped sending the result of run ${id} part way.`);
+    text += run.result.text;
+  }
+  const verification = receipt
+    ? await checkHostedReceipt(receipt, { base: hub.base, keys: keys || await hub.keys(), text, pinned })
+    : { signed: false, signatureValid: false, deliverableMatches: null, keyId: null, trust: null, host: new URL(hub.base).host, issuer: null, issuerMatches: false, verified: false, problems: ['The hub sent no receipt.'] };
+  return { text, receipt, verification, review: receipt?.deliverable_review?.status || run.review || 'unknown', sha256: run.result.sha256 || null };
+}