factoryhub 0.1.0 → 0.1.1

package/packages/engine/lib/hub.mjs

@@ -1,54 +1,279 @@
-// A client for the public read API of the factoryhub site.
+// A client for the factoryhub site.
 //
+// Public reads, no account:
 //   GET {base}/api/factories     the published catalogue
 //   GET {base}/f/{id}.json       one factory as a transfer bundle, each file with its SHA-256
 //
+// The developer API, /api/v1, with a personal access token (fhpat_…) sent as
+// `Authorization: Bearer`. `GET /api/v1` describes it; the routes used here:
+//   GET    /api/v1/me                          who the token acts for
+//   DELETE /api/v1/me/token                    revoke this token (logout)
+//   POST   /api/v1/factories                   push files as a private factory   factories:write
+//   GET    /api/v1/factories/{id}/bundle       pull a transfer bundle            (factories:read widens)
+//   POST   /api/v1/factories/{id}/publish      publish                           factories:publish (opt-in)
+//   GET    /api/v1/me/runs                     the account's runs                runs:read
+//   POST   /api/v1/runs                        start a hosted run                runs:start
+//   GET    /api/v1/runs/{id}?after&offset      follow one                        runs:read
+//   POST   /api/v1/runs/{id}/decision          decide a waiting step             runs:decide (opt-in)
+//
+// Device login (RFC 8628) gets a token without pasting one: start at
+// /oauth/device_authorization, the person approves on /device, and polling
+// /oauth/token hands the token over once.
+//
 // While the site is in private preview it answers only requests that carry
 // the preview access key in the `x-hub-access-key` header. Everyone else
-// gets 404. Set FACTORYHUB_ACCESS_KEY to send it.
-import { fromEnvelope } from '../src/factory-engine.mjs';
+// gets 404. Set FACTORYHUB_ACCESS_KEY to send it. A token alone does not
+// pass the preview.
+//
+// A token is only ever sent in the Authorization header. It never appears in
+// an address, an error message or anything this module prints. A token that
+// is not shaped like one is refused before any request.
+//
+// Redirects are followed only within the hub's own origin. A redirect to any
+// other origin, or from https to http, is refused, so neither the token nor
+// the preview key ever reaches another site.
+//
+// Answers are read as a stream and refused once they pass a size cap, before
+// the whole body is read, whatever its content encoding.
+import { fromEnvelope, bundleHash } from '../src/factory-engine.mjs';
 import { matches } from './catalog.mjs';
+import { hasControl } from './text.mjs';
 
 export const DEFAULT_HUB = 'https://factory.mindburn.org';
 export const ACCESS_HEADER = 'x-hub-access-key';
+export const DEVICE_GRANT = 'urn:ietf:params:oauth:grant-type:device_code';
+export const TOKEN_PATTERN = /^fhpat_[A-Za-z0-9_-]{43}$/;
+/** Every scope a personal access token can hold. The last two are opt-in. */
+export const SCOPES = ['factories:read', 'factories:write', 'runs:start', 'runs:read', 'factories:publish', 'runs:decide'];
+export const OPT_IN_SCOPES = ['factories:publish', 'runs:decide'];
 const ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** A factory id as the hub makes them; also safe as part of a file name. */
+export const FACTORY_ID = /^[a-z0-9][a-z0-9-]{0,89}$/;
+const RUN_ID = /^[A-Za-z0-9_-]{16,40}$/;
+/** The largest answer read from the hub, in bytes after decoding. */
+export const MAX_ANSWER_BYTES = 8 * 1024 * 1024;
+const MAX_REDIRECTS = 3;
+const LOCAL_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]']);
+/** Device login polling bounds, in seconds (RFC 8628 section 3.5). */
+export const POLL_MIN_SECONDS = 5;
+export const POLL_MAX_SECONDS = 60;
+const MAX_CODE_SECONDS = 3600;
 
 export class HubError extends Error {
-  constructor(message, { status, preview = false } = {}) {
+  constructor(message, { status, code, preview = false, scope = null, retryAfter = null, details = null } = {}) {
     super(message);
     this.status = status;
+    this.code = code || null;
     this.preview = preview;
+    this.scope = scope;
+    this.retryAfter = retryAfter;
+    this.details = details;
+  }
+}
+
+const scopeFrom = (header) => /scope="([^"]*)"/.exec(header || '')?.[1]?.split(/\s+/).filter(Boolean) || null;
+const enc = encodeURIComponent;
+
+/**
+ * The hub address, checked: https, or http to this machine only. Throws a
+ * usage HubError otherwise, so no token or key is ever sent in the clear.
+ */
+export function checkedBase(value) {
+  const base = String(value || DEFAULT_HUB).replace(/\/+$/, '');
+  let url;
+  try { url = new URL(base); } catch { throw new HubError(`"${base}" is not a web address.`, { code: 'usage' }); }
+  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && LOCAL_HOSTS.has(url.hostname))) {
+    throw new HubError(`${base} is not an https address. factoryhub sends tokens and keys only over https (or http to this machine).`, { code: 'usage' });
+  }
+  if (url.username || url.password || url.search || url.hash) throw new HubError(`${base} must be a plain address, with no user name, query or fragment.`, { code: 'usage' });
+  return base;
+}
+
+/** Reads a response body as text, refusing it once it passes `limit` bytes. */
+export async function readCapped(response, limit = MAX_ANSWER_BYTES) {
+  const declared = Number(response.headers?.get?.('content-length'));
+  if (Number.isFinite(declared) && declared > limit) {
+    await response.body?.cancel?.().catch(() => {});
+    return { tooLarge: true, text: '' };
+  }
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    return new TextEncoder().encode(text).byteLength > limit ? { tooLarge: true, text: '' } : { tooLarge: false, text };
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let size = 0;
+  let text = '';
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > limit) {
+      await reader.cancel().catch(() => {});
+      return { tooLarge: true, text: '' };
+    }
+    text += decoder.decode(value, { stream: true });
   }
+  return { tooLarge: false, text: text + decoder.decode() };
 }
 
-export function hubClient({ baseUrl, accessKey, env = process.env, fetchImpl = fetch } = {}) {
-  const base = String(baseUrl || env.FACTORYHUB_BASE_URL || DEFAULT_HUB).replace(/\/+$/, '');
+/**
+ * @param {object} options
+ * @param {string} [options.baseUrl]   the hub address (default FACTORYHUB_BASE_URL or DEFAULT_HUB)
+ * @param {string} [options.accessKey] the preview key (default FACTORYHUB_ACCESS_KEY)
+ * @param {string|null} [options.token] a personal access token, or null for anonymous calls
+ * @param {'env'|'file'|null} [options.tokenSource] where the token came from, for messages
+ * @param {string[]} [options.tokenScopes] the token's scopes when known, for messages
+ */
+export function hubClient({ baseUrl, accessKey, token = null, tokenSource = null, tokenScopes = null, env = process.env, fetchImpl = fetch, timeoutMs = 30000, maxBytes = MAX_ANSWER_BYTES } = {}) {
+  const base = checkedBase(baseUrl || env.FACTORYHUB_BASE_URL || DEFAULT_HUB);
+  const origin = new URL(base).origin;
   const key = accessKey ?? env.FACTORYHUB_ACCESS_KEY ?? '';
   const headers = { accept: 'application/json', ...(key ? { [ACCESS_HEADER]: key } : {}) };
+  const loginAgain = { env: 'Set FACTORYHUB_TOKEN to a valid token, or unset it and run "factoryhub login".', file: 'Run "factoryhub login" again.' }[tokenSource] || 'Check the token, or run "factoryhub login".';
+  const whose = { env: 'FACTORYHUB_TOKEN', file: 'Your saved token' }[tokenSource] || 'The token';
+  // Checked before any request, and never repeated: a value that is not a
+  // token could be anything, a password pasted by mistake included.
+  if (token !== null && token !== undefined && !TOKEN_PATTERN.test(String(token))) {
+    throw new HubError(`${whose} is not a factoryhub personal access token: they start with fhpat_ and are 49 characters long. ${loginAgain}`, { code: 'usage' });
+  }
+  if (key && hasControl(String(key))) throw new HubError('FACTORYHUB_ACCESS_KEY holds a control character, so it was not sent.', { code: 'usage' });
 
-  async function getJson(path) {
+  // One request. Returns { status, body, headers } without judging the status.
+  // Redirects are followed only inside the hub's own origin.
+  async function send(method, path, { body, form, auth = true, extra = {} } = {}) {
+    const sent = { ...headers, ...extra };
+    if (auth && token) sent.authorization = `Bearer ${token}`;
+    let payload;
+    if (form) { sent['content-type'] = 'application/x-www-form-urlencoded'; payload = new URLSearchParams(form).toString(); }
+    else if (body !== undefined) { sent['content-type'] = 'application/json'; payload = JSON.stringify(body); }
+    let url = `${base}${path}`;
     let response;
-    try {
-      response = await fetchImpl(`${base}${path}`, { headers, signal: AbortSignal.timeout(30000) });
-    } catch (error) {
-      throw new HubError(`Could not reach ${base}: ${error.message}`);
+    for (let hops = 0; ; hops += 1) {
+      try {
+        response = await fetchImpl(url, { method, headers: sent, body: payload, redirect: 'manual', signal: AbortSignal.timeout(timeoutMs) });
+      } catch (error) {
+        // The platform's message may quote a header, so only its code is shown.
+        const reason = error?.name === 'TimeoutError' ? 'it did not answer in time' : /^[A-Z_]+$/.test(String(error?.cause?.code || '')) ? error.cause.code : '';
+        throw new HubError(`Could not reach ${base}${reason ? ` (${reason})` : ''}.`, { code: 'network' });
+      }
+      if (![301, 302, 303, 307, 308].includes(response.status)) break;
+      await response.body?.cancel?.().catch(() => {});
+      let next;
+      try { next = new URL(response.headers.get('location') || '', url); } catch { next = null; }
+      if (!next || next.origin !== origin) {
+        throw new HubError(`${base}${path} redirected to ${next ? next.origin : 'an address that is not valid'}. factoryhub follows redirects only within ${origin}, so your token and preview key were not sent there.`, { status: response.status, code: 'redirect' });
+      }
+      if (hops >= MAX_REDIRECTS) throw new HubError(`${base}${path} redirected too many times.`, { status: response.status, code: 'redirect' });
+      if (method !== 'GET' && ![307, 308].includes(response.status)) throw new HubError(`${base}${path} answered a ${method} with a redirect, which factoryhub does not follow.`, { status: response.status, code: 'redirect' });
+      url = next.href;
     }
-    const text = await response.text();
+    const answer = await readCapped(response, maxBytes);
+    if (answer.tooLarge) throw new HubError(`${base}${path} answered with more than ${Math.round(maxBytes / 1048576)} MB, so the answer was not read.`, { status: response.status, code: 'too_large' });
+    const { text } = answer;
     if (response.status === 404 && /private preview/i.test(text)) {
-      throw new HubError(`${base} is in private preview and answers only with an access key. ${key ? 'The FACTORYHUB_ACCESS_KEY you set was not accepted.' : 'Set FACTORYHUB_ACCESS_KEY to the key you were given.'}`, { status: 404, preview: true });
+      throw new HubError(`${base} is in private preview and answers only with an access key. ${key ? 'The FACTORYHUB_ACCESS_KEY you set was not accepted.' : 'Set FACTORYHUB_ACCESS_KEY to the key you were given.'}`, { status: 404, preview: true, code: 'preview' });
+    }
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* judged by the caller */ }
+    return { status: response.status, ok: response.ok, body: parsed, headers: response.headers };
+  }
+
+  // The token's scopes, for a hint that keeps them: from the caller, or asked once.
+  let knownScopes = tokenScopes;
+  async function scopesNow() {
+    if (knownScopes || !token) return knownScopes || [];
+    try {
+      const me = await send('GET', '/api/v1/me');
+      knownScopes = Array.isArray(me.body?.token?.scopes) ? me.body.token.scopes : [];
+    } catch { knownScopes = []; }
+    return knownScopes;
+  }
+
+  // Turns a refusal into a sentence that says what to do next.
+  async function refusal(answer, path) {
+    const { status, body } = answer;
+    const code = typeof body?.error === 'string' ? body.error : null;
+    const said = typeof body?.message === 'string' ? body.message : null;
+    const retryAfter = Number(answer.headers.get('retry-after')) || null;
+    if (status === 401 && code === 'invalid_token') return new HubError(`${whose} was not accepted by ${base}: it expired, was revoked, or is mistyped. ${loginAgain}`, { status, code });
+    if (status === 401) return new HubError(`This needs you to be logged in to ${base}. Run "factoryhub login", or set FACTORYHUB_TOKEN.`, { status, code: code || 'unauthorized' });
+    if (status === 403 && code === 'insufficient_scope') {
+      const missing = scopeFrom(answer.headers.get('www-authenticate')) || [];
+      const want = [...new Set([...await scopesNow(), ...missing])];
+      const ask = SCOPES.filter((scope) => want.includes(scope));
+      return new HubError(`Your token does not allow this: it needs ${missing.join(' and ') || 'another scope'}. Log in again and ask for it: factoryhub login --scopes ${ask.join(',')}`, { status, code, scope: missing });
+    }
+    if (status === 429) return new HubError(`${said || `${base} is refusing more requests for now.`}${retryAfter ? ` Try again in ${Math.ceil(retryAfter / 60)} minutes.` : ''}`, { status, code: code || 'limit', retryAfter });
+    const details = body && typeof body === 'object' ? Object.fromEntries(Object.entries(body).filter(([name]) => !['error', 'message'].includes(name))) : null;
+    return new HubError(said || `${base}${path} answered with status ${status}.`, { status, code, details: details && Object.keys(details).length ? details : null });
+  }
+
+  async function call(method, path, options = {}) {
+    if (options.needsToken && !token) throw new HubError(`Log in first: run "factoryhub login", or set FACTORYHUB_TOKEN.`, { status: 401, code: 'unauthorized' });
+    const answer = await send(method, path, options);
+    if (!answer.ok) throw await refusal(answer, path);
+    if (!answer.body || typeof answer.body !== 'object') throw new HubError(`${base}${path} did not answer with JSON.`, { status: answer.status });
+    return answer.body;
+  }
+  const getJson = (path, options) => call('GET', path, options);
+
+  // Reads and checks a transfer bundle: every file against its SHA-256 and,
+  // when strict, the whole bundle against the bundle hash in the same answer.
+  // These hashes prove the files arrived as the hub answered, not who wrote
+  // them: they are not a signature. A strict read refuses a bundle it cannot
+  // check whole (no bundle hash, or files left out) unless `partial` accepts
+  // that, and says so in `unchecked`.
+  async function readBundle(id, envelope, { strict, partial = false }) {
+    const read = await fromEnvelope(envelope);
+    const problems = [...read.problems];
+    const unchecked = [];
+    const sha256 = await bundleHash(read.files);
+    if (strict) {
+      const unsigned = (envelope.files || []).filter((entry) => entry && typeof entry.sha256 !== 'string').map((entry) => entry.path);
+      if (unsigned.length) problems.push(`These files carry no SHA-256, so they cannot be checked: ${unsigned.slice(0, 5).join(', ')}`);
+      const expected = envelope.package?.sourceSha256;
+      const gaps = [];
+      if (typeof expected !== 'string' || !/^[a-f0-9]{64}$/.test(expected)) gaps.push('The hub sent no bundle hash, so the files cannot be checked as a whole.');
+      if (read.leftOut.length) gaps.push(`The bundle leaves out ${read.leftOut.length === 1 ? 'a file' : `${read.leftOut.length} files`} it names (${read.leftOut.slice(0, 5).join(', ')}), so the files cannot be checked as a whole.`);
+      if (gaps.length && !partial) problems.push(...gaps, 'Pass --partial (or { partial: true }) to accept a bundle that cannot be checked whole.');
+      else unchecked.push(...gaps);
+      if (!problems.length && !gaps.length && sha256 !== expected) problems.push('The files together do not match the bundle hash in the hub\'s answer.');
     }
-    let body = null;
-    try { body = JSON.parse(text); } catch { /* reported below */ }
-    if (!response.ok) throw new HubError(body?.message || `${base}${path} answered with status ${response.status}.`, { status: response.status });
-    if (!body || typeof body !== 'object') throw new HubError(`${base}${path} did not answer with JSON.`, { status: response.status });
-    return body;
+    if (problems.length) throw new HubError(`The bundle for ${id} did not pass its checks, so nothing was written:\n${problems.map((item) => `  - ${item}`).join('\n')}`, { code: 'bundle' });
+    return { id, files: read.files, leftOut: read.leftOut, source: envelope.source?.url || `${base}/f/${id}`, sha256, partial: unchecked.length > 0, unchecked };
   }
 
+  // A device-login path from GET /api/v1: a path on this hub, never another site.
+  const devicePath = (path, name) => {
+    let url = null;
+    if (typeof path === 'string' && path.startsWith('/') && !path.startsWith('//') && !path.includes('\\') && !hasControl(path)) {
+      try { url = new URL(`${base}${path}`); } catch { url = null; }
+    }
+    if (!url || url.origin !== origin) throw new HubError(`${base} described a device login ${name} that is not a path on ${origin}, so factoryhub will not use it.`, { code: 'device_off' });
+    return path;
+  };
+
+  const factoryId = (id) => {
+    if (!FACTORY_ID.test(String(id || ''))) throw new HubError(`"${id}" is not a factory id. Ids are lowercase letters, digits and hyphens, as in ${base}/f/<id>.`, { code: 'usage' });
+    return id;
+  };
+  const runId = (id) => {
+    if (!RUN_ID.test(String(id || ''))) throw new HubError(`"${id}" is not a run id. A run id is the last part of a run address, ${base}/r/<id>.`, { code: 'usage' });
+    return id;
+  };
+
   return {
     base,
+    origin,
+    hasToken: Boolean(token),
+    tokenSource,
+
+    // ---- public reads ----
+
     /** Every published factory in the catalogue. */
     async list() {
-      const body = await getJson('/api/factories');
+      const body = await getJson('/api/factories', { auth: false });
       if (!Array.isArray(body.factories)) throw new HubError('The catalogue answer has no factories list.');
       return body.factories;
     },
@@ -56,16 +281,143 @@ export function hubClient({ baseUrl, accessKey, env = process.env, fetchImpl = f
     async search(query) {
       return (await this.list()).filter((entry) => matches(entry, query));
     },
-    /** One factory's files, each checked against its recorded SHA-256. */
+    /** One published factory's files, each checked against its recorded SHA-256. */
     async get(id) {
       if (!ID.test(String(id || ''))) throw new HubError(`"${id}" is not a factory id. Ids are lowercase words joined by hyphens.`);
-      const envelope = await getJson(`/f/${id}.json`);
-      const read = await fromEnvelope(envelope);
-      if (read.problems.length) throw new HubError(`The bundle for ${id} did not pass its checks:\n${read.problems.map((item) => `  - ${item}`).join('\n')}`);
-      return { id, files: read.files, leftOut: read.leftOut, source: envelope.source?.url || `${base}/f/${id}` };
+      return readBundle(id, await getJson(`/f/${id}.json`, { auth: false }), { strict: false });
     },
     sourceUrl(id) {
       return `${base}/f/${id}`;
     },
+    /** The hub's published receipt keys: [{ key_id, public_key }]. */
+    async keys() {
+      const body = await getJson('/.well-known/factory-hub-keys.json', { auth: false });
+      if (!Array.isArray(body.keys)) throw new HubError('The key list has no keys.');
+      return body.keys;
+    },
+
+    // ---- the developer API ----
+
+    /** The description at GET /api/v1. */
+    describe() {
+      return getJson('/api/v1', { auth: false });
+    },
+    /** The account and token the token acts for. */
+    me() {
+      return getJson('/api/v1/me', { needsToken: true });
+    },
+    /** Revokes the token this client holds. */
+    revoke() {
+      return call('DELETE', '/api/v1/me/token', { needsToken: true });
+    },
+    /** Saves files to the account as a private factory. Nothing is published. */
+    push(files, { parent } = {}) {
+      return call('POST', '/api/v1/factories', { needsToken: true, body: { files, ...(parent ? { parent: factoryId(parent) } : {}) } });
+    },
+    /**
+     * One factory the caller can open, as checked files. A token with
+     * factories:read opens private ones. Refuses a bundle that cannot be
+     * checked whole unless `partial`.
+     */
+    async pull(id, { partial = false } = {}) {
+      factoryId(id);
+      return readBundle(id, await getJson(`/api/v1/factories/${enc(id)}/bundle`), { strict: true, partial });
+    },
+    /** Publishes one of the account's factories. */
+    publish(id, { note = '' } = {}) {
+      return call('POST', `/api/v1/factories/${enc(factoryId(id))}/publish`, { needsToken: true, body: { note } });
+    },
+    /** One factory with its inputs and steps. */
+    factory(id) {
+      return getJson(`/api/v1/factories/${enc(factoryId(id))}`);
+    },
+    /** The account's recent runs. */
+    async runs({ limit } = {}) {
+      return (await getJson(`/api/v1/me/runs${limit ? `?limit=${enc(limit)}` : ''}`, { needsToken: true })).runs;
+    },
+    /** Starts a hosted run. The same idempotency key and inputs within an hour return the same run. */
+    async startRun(id, inputs = {}, { idempotencyKey }) {
+      return (await call('POST', '/api/v1/runs', { needsToken: true, body: { factory_id: factoryId(id), inputs }, extra: { 'idempotency-key': idempotencyKey } })).run;
+    },
+    /** One run: events after `after`, the waiting step, and once done the result from `offset`. */
+    async getRun(id, { after = 0, offset = 0 } = {}) {
+      return (await getJson(`/api/v1/runs/${enc(runId(id))}?after=${enc(after)}&offset=${enc(offset)}`, { needsToken: true })).run;
+    },
+    /** Decides the step a run waits on, for the person. Needs runs:decide. */
+    decide(id, { approvalId, seenSha256, decision, note = '' }) {
+      return call('POST', `/api/v1/runs/${enc(runId(id))}/decision`, { needsToken: true, body: { approval_id: approvalId, seen_sha256: seenSha256, decision, note } });
+    },
+
+    // ---- device login ----
+
+    /** Starts a device login. `endpoints` comes from describe().auth.deviceLogin. */
+    async startDeviceLogin(endpoints, { name, scopes, days } = {}) {
+      const form = { ...(name ? { client_name: name } : {}), ...(scopes?.length ? { scope: scopes.join(' ') } : {}), ...(days ? { token_days: String(days) } : {}) };
+      const answer = await send('POST', devicePath(endpoints.start, 'start address'), { form, auth: false });
+      if (!answer.ok) throw new HubError(answer.body?.error_description || `${base}${endpoints.start} answered with status ${answer.status}.`, { status: answer.status, code: answer.body?.error || null });
+      const body = answer.body || {};
+      if (typeof body.device_code !== 'string' || typeof body.user_code !== 'string' || typeof body.verification_uri !== 'string') throw new HubError(`${base} did not start a device login.`);
+      return body;
+    },
+    /** One poll. Returns the token answer, or { error, error_description, interval }. */
+    async pollDeviceLogin(endpoints, deviceCode) {
+      const answer = await send('POST', devicePath(endpoints.token, 'token address'), { form: { grant_type: endpoints.grantType || DEVICE_GRANT, device_code: deviceCode }, auth: false });
+      if (answer.ok && typeof answer.body?.access_token === 'string') return answer.body;
+      if (answer.body && typeof answer.body.error === 'string') return answer.body;
+      throw new HubError(`${base}${endpoints.token} answered with status ${answer.status}.`, { status: answer.status });
+    },
   };
 }
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+// A positive, finite number of seconds from the hub, or 0.
+const seconds = (value) => {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? number : 0;
+};
+const pollInterval = (value) => Math.min(Math.max(value, POLL_MIN_SECONDS), POLL_MAX_SECONDS);
+
+/**
+ * Runs a device login to its end: starts it, tells the caller the code to
+ * show, and polls at the interval the hub sets until the person approves,
+ * declines or the code expires. Returns the token answer:
+ * { access_token, token_type, expires_in, scope, token: { id, name, prefix, scopes, expires } }.
+ */
+export async function deviceLogin(hub, { name, scopes, days, onCode = () => {}, sleep = wait, now = Date.now } = {}) {
+  let description;
+  try { description = await hub.describe(); } catch (error) {
+    if (error.preview) throw error;
+    description = null;
+  }
+  const endpoints = description?.auth?.deviceLogin;
+  if (!endpoints?.start || !endpoints?.token) {
+    throw new HubError(`${hub.base} does not offer login from a terminal yet. Make a token in your account settings there, then run: factoryhub login --token < token.txt`, { code: 'device_off' });
+  }
+  const started = await hub.startDeviceLogin(endpoints, { name, scopes, days });
+  const lifetime = Math.min(seconds(started.expires_in) || 900, MAX_CODE_SECONDS);
+  const deadline = now() + lifetime * 1000;
+  await onCode({ userCode: started.user_code, verificationUri: started.verification_uri, verificationUriComplete: started.verification_uri_complete || null, expiresIn: lifetime, scope: started.scope || null });
+  let interval = pollInterval(seconds(started.interval) || POLL_MIN_SECONDS);
+  let failures = 0;
+  for (;;) {
+    await sleep(interval * 1000);
+    if (now() >= deadline) throw new HubError('The code expired before it was approved. Run "factoryhub login" again.', { code: 'expired_token' });
+    let answer;
+    try { answer = await hub.pollDeviceLogin(endpoints, started.device_code); } catch (error) {
+      // A dropped connection is retried; the code stays valid until it expires.
+      if (error.code === 'network' && (failures += 1) < 3) continue;
+      throw error;
+    }
+    failures = 0;
+    if (answer.access_token) {
+      if (!TOKEN_PATTERN.test(answer.access_token)) throw new HubError(`${hub.base} answered with something that is not a personal access token.`);
+      return answer;
+    }
+    if (answer.error === 'authorization_pending') continue;
+    // RFC 8628: slow_down adds 5 seconds; a longer interval the hub names wins.
+    if (answer.error === 'slow_down') { interval = pollInterval(Math.max(interval + 5, seconds(answer.interval) || 0)); continue; }
+    if (answer.error === 'access_denied') throw new HubError(answer.error_description || 'The login was declined.', { code: 'access_denied' });
+    if (answer.error === 'expired_token') throw new HubError('The code expired before it was approved. Run "factoryhub login" again.', { code: 'expired_token' });
+    throw new HubError(answer.error_description || `The login failed: ${answer.error}.`, { code: answer.error });
+  }
+}

package/packages/engine/lib/nango.mjs

@@ -0,0 +1,157 @@
+// Experimental: a Nango agent session as a tool source. Creates a short
+// session scoped to one integration and the named tools, for one end user,
+// and hands back its MCP server. The Nango key stays in this process: the
+// MCP server gets only the session's own token, which ends with the run.
+// See https://nango.dev/docs/guides/agent-sessions.
+import { createMcpClient } from '../src/mcp-client.mjs';
+
+export const NANGO_API = 'https://api.nango.dev';
+/** How long a session lives at most. The CLI also ends it when the run ends. */
+export const NANGO_SESSION_TTL = '30m';
+
+const fail = (message, extra = {}) => Object.assign(new Error(message), extra);
+// What Nango sends is checked before it is shown or used: an error code, a
+// connect link and its expiry. Nothing else Nango writes reaches an error.
+const ERROR_CODE = /^[a-z][a-z0-9_]{0,63}$/;
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d{1,9})?Z$/;
+const LINK = /^https:\/\/[\x21-\x7e]{1,2040}$/;
+const END_TIMEOUT_MS = 3000;
+/** How long an interrupt waits for Nango to answer a session it is creating, to end it. */
+export const INTERRUPT_WAIT_MS = 1500;
+
+// Nango's own hosts: the API host and the domain it belongs to (nango.dev
+// for api.nango.dev). A session address elsewhere does not get the token.
+function onNangoHost(address, api) {
+  let host;
+  try { host = new URL(address).hostname.toLowerCase(); } catch { return false; }
+  const apiHost = new URL(api).hostname.toLowerCase();
+  const labels = apiHost.split('.');
+  const domain = labels.length > 2 ? labels.slice(1).join('.') : apiHost;
+  return host === apiHost || host === domain || host.endsWith(`.${domain}`);
+}
+
+/**
+ * Opens a Nango agent session for `integration`, allowing and listing only
+ * `tools`, with the connection tagged `end_user_id: endUserId`.
+ *
+ * Resolves to `{ connected: true, client, session_id, close }`, where
+ * `client` is an MCP client for the session's server; or, when the person
+ * has not connected that integration yet, to `{ connected: false,
+ * connect_url, expires_at }` after ending the session again.
+ *
+ * `register(closeOne)`, when given, receives a function that ends
+ * everything this call creates, before the first request is sent: the CLI
+ * runs it on Ctrl+C. If it runs while Nango is still creating the session,
+ * it waits up to `interruptWaitMs` for Nango's answer and ends the session
+ * named; an answer that comes later is ended when it comes.
+ */
+export async function openNangoSession({ apiKey, integration, tools, endUserId = 'local-dev-user', expiresIn = NANGO_SESSION_TTL, fetchImpl = fetch, baseUrl = NANGO_API, register = null, interruptWaitMs = INTERRUPT_WAIT_MS }) {
+  if (!apiKey) throw fail('NANGO_API_KEY is not set.', { usage: true });
+  if (!tools?.length) throw fail(`Name the ${integration} tools a run may use: --nango ${integration}:<tool>,<tool>.`, { usage: true });
+  const api = baseUrl.replace(/\/+$/, '');
+  const auth = { authorization: `Bearer ${apiKey}` };
+  // Registered before the first request: an interrupt, even while Nango is
+  // still creating the session, ends whatever has been created by then, and
+  // a session Nango names after an interrupt is ended as soon as it is named.
+  let interrupted = false;
+  let closeNow = null;
+  let markSettled;
+  const settled = new Promise((resolve) => { markSettled = resolve; });
+  register?.(async () => {
+    interrupted = true;
+    let timer;
+    await Promise.race([settled, new Promise((resolve) => { timer = setTimeout(resolve, interruptWaitMs); })]);
+    clearTimeout(timer);
+    await closeNow?.();
+  });
+  let data;
+  let client;
+  let ended = false;
+  // Once Nango names a session, it is ended on every path that does not use it.
+  const end = async () => {
+    if (ended || typeof data?.session_id !== 'string' || !data.session_id) return;
+    ended = true;
+    try {
+      const done = await fetchImpl(`${api}/sessions/${encodeURIComponent(data.session_id)}`, { method: 'DELETE', headers: auth, redirect: 'manual', signal: AbortSignal.timeout(END_TIMEOUT_MS) });
+      await done.body?.cancel?.().catch?.(() => {});
+    } catch { /* it expires on its own */ }
+  };
+  // Side by side, so a slow MCP DELETE never holds up ending Nango's session.
+  const closeAll = async () => { await Promise.all([client?.close(), end()]); };
+  try {
+    let response;
+    try {
+      response = await fetchImpl(`${api}/sessions`, {
+        method: 'POST',
+        headers: { ...auth, 'content-type': 'application/json' },
+        body: JSON.stringify({
+          tenant: { connections: { any: [{ tags: { end_user_id: endUserId } }] } },
+          toolset: { [integration]: { allow: { tools } } },
+          // Pinned tools are the ones the session's tools/list returns.
+          pinned_tools: { [integration]: tools },
+          // No search, generic execute or raw proxy: only the named tools. The
+          // connect tool is used by this runner alone, never offered to a model.
+          meta_tools: { nango_tool_search: false, nango_execute: false, nango_proxy: false, nango_create_connection: { enabled: true, tags: { end_user_id: endUserId } } },
+          expires_in: expiresIn,
+        }),
+        redirect: 'manual',
+        signal: AbortSignal.timeout(30000),
+      });
+    } catch {
+      throw fail(`Nango could not be reached at ${new URL(api).host}.`);
+    }
+    const body = await response.json().catch(() => ({}));
+    // The status and Nango's error code; never Nango's message, which may quote the key.
+    if (!response.ok) {
+      const code = typeof body?.error?.code === 'string' && ERROR_CODE.test(body.error.code) ? `, ${body.error.code}` : '';
+      throw fail(`Nango refused to create the session (HTTP ${response.status}${code}).`);
+    }
+    data = body?.data;
+    closeNow = end;
+    if (!data || typeof data.mcp_url !== 'string' || typeof data.session_token !== 'string' || typeof data.session_id !== 'string') {
+      await end();
+      throw fail('Nango answered without a usable session.');
+    }
+    // The session token goes only to an https address on Nango's own host.
+    if (!/^https:\/\//.test(data.mcp_url)) {
+      await end();
+      throw fail('Nango gave a session address that is not https.');
+    }
+    if (!onNangoHost(data.mcp_url, api)) {
+      await end();
+      throw fail('Nango gave a session address that is not on Nango\'s host.');
+    }
+    try { client = createMcpClient({ url: data.mcp_url, token: data.session_token, fetchImpl }); } catch (error) { await end(); throw error; }
+    closeNow = closeAll;
+  } finally {
+    markSettled();
+  }
+  if (interrupted) {
+    await closeAll();
+    throw fail('The run was interrupted while the Nango session was being created. The session was ended.');
+  }
+  if (data.toolset?.[integration]?.connected === false) {
+    // Ask the session for a link the person opens to connect the integration.
+    try {
+      const result = await client.callTool('nango_create_connection', { integration });
+      let link = result?.structuredContent;
+      if (!link?.connect_url) {
+        const text = (result?.content || []).find((block) => block?.type === 'text')?.text;
+        try { link = JSON.parse(text); } catch { link = null; }
+      }
+      if (typeof link?.connect_url !== 'string' || !LINK.test(link.connect_url)) throw fail(`${integration} is not connected in Nango for "${endUserId}", and Nango gave no usable connect link.`);
+      return { connected: false, integration, end_user_id: endUserId, connect_url: link.connect_url, expires_at: typeof link.expires_at === 'string' && TIMESTAMP.test(link.expires_at) ? link.expires_at : null };
+    } finally {
+      // Both sessions end, side by side: the MCP one and Nango's.
+      await closeAll();
+    }
+  }
+  return {
+    connected: true,
+    integration,
+    session_id: data.session_id,
+    expires_at: typeof data.expires_at === 'string' && TIMESTAMP.test(data.expires_at) ? data.expires_at : null,
+    client,
+    close: closeAll,
+  };
+}