flowsprite 0.1.0 → 0.1.4

package/dist/credentials.js

@@ -2,6 +2,7 @@ import { randomUUID } from "node:crypto";
 import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { approvePageHref, MAX_EXPIRES_IN_SECONDS, USER_CODE_RE } from "./ghLogin.js";
 export const CREDENTIALS_FILE = "credentials.json";
 const DIR_MODE = 0o700;
 const FILE_MODE = 0o600;
@@ -175,6 +176,113 @@ export function deleteCredential(env, origin, home) {
     writeStore(env, store, home);
     return true;
 }
+// ------------------------------------------------------- the pending login (C3)
+export const PENDING_LOGIN_FILE = "pending-login.json";
+export function pendingLoginPath(env, home) {
+    return join(credentialsDir(env, home), PENDING_LOGIN_FILE);
+}
+const nonEmpty = (v) => typeof v === "string" && v.length > 0;
+/**
+ * The pending login for `origin`, or null. TOLERANT like `readCredentials`: a
+ * missing, unreadable, garbled or wrong-shaped file, or one for another origin,
+ * reads as "none". An EXPIRED entry for this origin is deleted as it is read.
+ *
+ * Held to the WIRE's grammar (eecc9d6f G5): the user code is `USER_CODE_RE`'s
+ * shape and the open target must pass `approvePageHref` — exactly this origin's
+ * approve page, normalised — so a hand-edited file can make `login` print or
+ * open nothing the start route could not have sent. The interval must be finite.
+ */
+export function readPendingLogin(env, origin, now, home) {
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(pendingLoginPath(env, home), "utf8"));
+    }
+    catch {
+        return null;
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+        return null;
+    const v = parsed;
+    if (v.origin !== origin || !nonEmpty(v.deviceCode))
+        return null;
+    if (typeof v.expiresAtMs !== "number" || !Number.isFinite(v.expiresAtMs))
+        return null;
+    if (typeof v.savedAtMs !== "number" || !Number.isFinite(v.savedAtMs))
+        return null;
+    if (typeof v.interval !== "number" || !Number.isFinite(v.interval) || !(v.interval > 0))
+        return null;
+    const userCode = nonEmpty(v.userCode) ? v.userCode : null;
+    const rawTarget = nonEmpty(v.openTarget) ? v.openTarget : null;
+    if ((userCode === null) !== (rawTarget === null))
+        return null;
+    let openTarget = null;
+    if (userCode !== null) {
+        if (!USER_CODE_RE.test(userCode))
+            return null;
+        openTarget = approvePageHref(rawTarget, origin, userCode);
+        if (openTarget === null)
+            return null;
+    }
+    // H1/H6: no entry is live past min(its write, now) + a code's TTL. A savedAt
+    // LATER than now is not rejected — a backward clock step (NTP, resume from
+    // suspend) must not abandon a live, maybe already approved, code — it is read
+    // as now. So a future-dated forged file lives at most now + 900 s per read, and
+    // is ended by the poll answer anyway (`expired_token`/`invalid_*` clear it).
+    const effectiveSavedAt = Math.min(v.savedAtMs, now);
+    const expiresAtMs = Math.min(v.expiresAtMs, effectiveSavedAt + MAX_EXPIRES_IN_SECONDS * 1000);
+    if (expiresAtMs <= now) {
+        try {
+            clearPendingLogin(env, origin, home, v.deviceCode);
+        }
+        catch {
+            // An undeletable expired entry still reads as none; the next write replaces it.
+        }
+        return null;
+    }
+    return { origin, deviceCode: v.deviceCode, userCode, openTarget, expiresAtMs, savedAtMs: v.savedAtMs, interval: v.interval };
+}
+/** Throws on a write failure; the caller (`login.ts`) treats that as "not persisted", never as a failed login. */
+export function writePendingLogin(env, entry, home) {
+    const dir = credentialsDir(env, home);
+    mkdirSync(dir, { recursive: true, mode: DIR_MODE });
+    chmodSync(dir, DIR_MODE);
+    writeFileAtomic(pendingLoginPath(env, home), `${JSON.stringify(entry)}\n`, FILE_MODE);
+}
+/**
+ * Delete the pending login if it is `origin`'s — or if it cannot be read as
+ * anyone's (garbled), since nothing can resume it. Another origin's entry is
+ * left alone. `rmSync` on a symlink removes the link, never its target.
+ *
+ * eecc9d6f G2: given a `deviceCode`, ONLY an entry holding exactly that code is
+ * deleted (a garbled file is then left for the next write to replace), so a
+ * stale run that ends cannot delete the entry a NEWER run saved. `logout` calls
+ * it without one: logging out drops whatever is pending for the origin.
+ */
+// ponytail: read-then-unlink, not an atomic compare-and-delete — node builtins have
+// none across processes. The window is the microseconds between the read and the
+// `rmSync`, open only to another `flowsprite` run of the SAME user saving a newer
+// entry in exactly that gap; the loser just starts a fresh login next time. A
+// lock file (O_EXCL) around save/clear is the upgrade if that ever matters.
+export function clearPendingLogin(env, origin, home, deviceCode) {
+    const path = pendingLoginPath(env, home);
+    let stored;
+    try {
+        stored = JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return;
+        stored = null;
+    }
+    const readable = typeof stored === "object" && stored !== null && typeof stored.origin === "string";
+    if (deviceCode !== undefined) {
+        if (readable && stored.origin === origin && stored.deviceCode === deviceCode)
+            rmSync(path, { force: true });
+        return;
+    }
+    if (!readable || stored.origin === origin)
+        rmSync(path, { force: true });
+}
 /**
  * Which token this invocation uses: an explicit `--token`, else
  * `FLOWSPRITE_TOKEN`, else the credential stored for this origin. The stored one

package/dist/doctor.js

@@ -8,6 +8,14 @@ import { spawnSync } from "node:child_process";
  */
 /** The major this package declares in `engines` — one authority, read by both halves. */
 export const MIN_NODE_MAJOR = 20;
+/**
+ * THE FAIL SET (card eecc9d6f N16): node too old, endpoint unreachable, no
+ * credential or a refused one. `sf`/`gh` absence is a NOTE, never a failure —
+ * neither is needed for the browser road.
+ */
+export function doctorOk(report) {
+    return report.nodeOk && report.endpointReachable && report.hasCredential && !report.credentialRefused;
+}
 export function nodeMajor(version) {
     const m = /^v?(\d+)\./.exec(version);
     return m ? Number(m[1]) : 0;
@@ -17,9 +25,15 @@ export function formatDoctor(report) {
     return [
         `${mark(report.nodeOk)} node ${report.nodeVersion} (needs >= ${MIN_NODE_MAJOR})`,
         `${mark(report.endpointReachable)} endpoint ${report.endpoint} — ${report.endpointDetail}`,
-        `${mark(report.hasCredential)} credential for ${report.endpoint} ${report.hasCredential ? "found" : "not found — run `flowsprite login`"} (${report.credentialsPath})`,
-        `${report.sfOnPath ? "ok  " : "note"} sf on PATH: ${report.sfOnPath ? "yes" : "no (only needed for Salesforce CLI work)"}`,
-        `${report.ghOnPath ? "ok  " : "note"} gh on PATH: ${report.ghOnPath ? "yes" : "no (only needed for GitHub CLI work)"}`,
+        !report.hasCredential
+            ? `FAIL credential for ${report.endpoint} not found (${report.credentialsPath}) — run \`flowsprite setup\` (logging in is its step 1), or \`flowsprite login\` alone`
+            : report.credentialRefused
+                ? `FAIL credential for ${report.endpoint} refused by the endpoint (HTTP 401) — run \`flowsprite login\` for a new one`
+                : `ok   credential for ${report.endpoint} found (${report.credentialSource === "stored" || report.credentialSource === null
+                    ? report.credentialsPath
+                    : `from ${report.credentialSource}, not stored`})`,
+        `${report.sfOnPath ? "ok  " : "note"} sf on PATH: ${report.sfOnPath ? "yes" : "no — needed for 'connect salesforce --from-sf-cli'. Install: npm install -g @salesforce/cli (macOS: brew install --cask salesforce-cli); then sf org login web --alias <name>."}`,
+        `${report.ghOnPath ? "ok  " : "note"} gh on PATH: ${report.ghOnPath ? "yes" : "no — needed for a no-browser 'login'. Install: gh (e.g. brew install gh); then gh auth login -s user:email."}`,
     ];
 }
 /**

package/dist/ghLogin.js

@@ -0,0 +1,180 @@
+/**
+ * FLO-517 — the pure half of `flowsprite login`'s gh road: what `gh auth token`
+ * printed is read BY SHAPE, and what `POST /api/cli/bootstrap/github` answered is
+ * classified BY SHAPE, before either value reaches a sink. This module imports
+ * nothing, so the classification can be pinned without a harness.
+ *
+ * THE INVARIANTS. Every field of the door's answer that this CLI will STORE,
+ * PRINT or OPEN is held to the grammar of whoever mints it, and anything else is
+ * `stop server_error`: a 200's token is the minter's `fp_` grammar (a door that
+ * echoed the gh bearer back would otherwise be stored as a credential), its ids
+ * are Clerk's `org_`/`user_` grammars and its endpoint is exactly this origin's
+ * `/api/mcp`; a 409's open target is exactly this origin's approve page
+ * (`/cli/auth`, no userinfo, no hash, at most `?code=<the payload's user_code>`)
+ * so a bearer cannot fit into a URL the CLI prints or hands to `openUrl`; the
+ * server's `remediation` is never carried — every sentence the CLI prints is a
+ * fixed local string.
+ */
+/**
+ * A GitHub token in running text: gh's own prefixes at a WORD BOUNDARY with a
+ * minimum suffix, so `highs_score` and a bare `ghs_` never match (spec gate C7 —
+ * an unanchored `ghs_[A-Za-z0-9_]+` matched inside `highs_score`). Real tokens
+ * are 40+ characters; the minimums are floors, not the grammar.
+ */
+export const GH_TOKEN_RE = /\b(?:(?:gho|ghp|ghu|ghs|ghr)_[A-Za-z0-9_]{16,}|github_pat_[A-Za-z0-9_]{20,})/;
+/** The bearer grammar the door itself enforces (`lib/cliBootstrapGithub.ts`, 401 outside it). */
+const GH_BEARER_RE = /^[A-Za-z0-9_]{20,255}$/;
+/**
+ * The token `gh auth token` printed, or null when there is no usable one: the
+ * command must have exited 0 and printed EXACTLY ONE line of bearer shape.
+ *
+ * A `ghs_` prefix is refused HERE, locally: `gh auth token` returns
+ * `GH_TOKEN`/`GITHUB_TOKEN` from the environment ahead of any stored login
+ * (measured gh 2.99.0), so in GitHub Actions it yields the job's installation
+ * token, which is not a user and cannot answer `GET /user` (UNVERIFIED: GitHub
+ * answers 403 for it, which the door reports as 502 `github_unavailable`, not
+ * a 401). Whatever the door would say, refusing it locally keeps CI on the
+ * browser road it had, at no request.
+ */
+export function readGhToken(outcome) {
+    if (outcome.status !== 0)
+        return null;
+    const text = (outcome.stdout ?? "").trim();
+    if (text.length === 0 || /[\r\n]/.test(text))
+        return null;
+    if (!GH_BEARER_RE.test(text) || text.startsWith("ghs_"))
+        return null;
+    return text;
+}
+/** A Flowsprite token as the minter emits it (`generateRawToken`, `convex/lib/mcpCrypto.ts`): the prefix and EXACTLY 32 suffix characters. */
+const FLOWSPRITE_TOKEN_RE = /^fp_(?:user|live)_[A-Za-z0-9_-]{32}$/;
+/** Clerk's id grammars — the door copies `org_id`/`user_id` from Clerk. */
+const ORG_ID_RE = /^org_[A-Za-z0-9]+$/;
+const USER_ID_RE = /^user_[A-Za-z0-9]+$/;
+const DEVICE_CODE_RE = /^[0-9a-f]{64}$/;
+/** The user code's shape on BOTH roads and in `pending-login.json` (eecc9d6f G1/G5). */
+export const USER_CODE_RE = /^[A-Z]{4}-[A-Z]{4}$/;
+/** The approve page's path on the endpoint; the only thing a 409 may ask the CLI to open. */
+const APPROVE_PATH = "/cli/auth";
+/** The device-code TTL the endpoint documents (`expires_in: 900`) — and the ceiling. */
+export const MAX_EXPIRES_IN_SECONDS = 900;
+/**
+ * `expires_in` as the loop may trust it: a number this CLI reads off a response,
+ * and the loop's termination is the only thing between a bad value and a
+ * terminal that polls for a year. Anything larger than the documented TTL is a
+ * mistake or a hostile endpoint, and anything non-positive would end the loop
+ * before a single poll — both fold to the documented value. ONE rule for both
+ * roads: `/api/cli/auth/start` (`login.ts`) and the bootstrap door (below).
+ */
+export function clampExpiresIn(claimed) {
+    return typeof claimed === "number" && Number.isFinite(claimed) && claimed > 0
+        ? Math.min(MAX_EXPIRES_IN_SECONDS, Math.max(1, claimed))
+        : MAX_EXPIRES_IN_SECONDS;
+}
+/**
+ * The poll interval as the loop may trust it — ONE rule for both roads and the
+ * resumed `pending-login.json` (eecc9d6f G3): a finite positive number, else the
+ * documented 5; never below 1 s (a tiny value is a busy loop) and never above
+ * `maxSeconds`, the code's remaining lifetime (a huge value would sleep past it).
+ */
+export function intervalSeconds(claimed, maxSeconds = MAX_EXPIRES_IN_SECONDS) {
+    const base = typeof claimed === "number" && Number.isFinite(claimed) && claimed > 0 ? Math.max(1, claimed) : 5;
+    return Math.max(1, Math.min(base, maxSeconds));
+}
+const STOP_CODES = new Set([
+    "in_progress",
+    "rate_limited",
+    "github_token_invalid",
+    "no_verified_email",
+    "noreply_email",
+    "invalid_request",
+    "invalid_argument",
+    "suspended",
+    "revoked",
+    "ambiguous_grant",
+    "github_unavailable",
+    "clerk_unavailable",
+    "server_misconfigured",
+    "server_error",
+]);
+const STOP_SERVER_ERROR = { kind: "stop", code: "server_error" };
+/**
+ * The approve page this endpoint's 409 may ask the CLI to open, as the ONE string
+ * the CLI will print and hand to `openUrl` — or null. The raw server string is
+ * parsed, held field by field (the ORIGIN is exactly `origin`, host-anchored,
+ * never a prefix test; no userinfo; the path is `/cli/auth`; no fragment; the
+ * query is empty or exactly one `code` equal to the payload's own `userCode`),
+ * and then what is RETURNED is the NORMALISED `href`, never the raw string: the
+ * WHATWG parser removes dot segments, so `<origin>/gho_<token>/../cli/auth`
+ * parses to a pathname of `/cli/auth` while the raw string still carries the
+ * bearer (fix round 2 F6). The href is asserted to be one of the two exact
+ * forms, so nothing else can ever reach a sink.
+ */
+export function approvePageHref(target, origin, userCode) {
+    if (typeof target !== "string")
+        return null;
+    let url;
+    try {
+        url = new URL(target);
+    }
+    catch {
+        return null;
+    }
+    if (url.origin !== origin || url.username !== "" || url.password !== "")
+        return null;
+    if (url.pathname !== APPROVE_PATH || url.hash !== "")
+        return null;
+    const params = [...url.searchParams.entries()];
+    if (params.length !== 0 && !(params.length === 1 && params[0][0] === "code" && params[0][1] === userCode))
+        return null;
+    const plain = `${origin}${APPROVE_PATH}`;
+    const withCode = `${plain}?code=${userCode}`;
+    return url.href === plain || url.href === withCode ? url.href : null;
+}
+/**
+ * One of four kinds for the door's answer. `origin` is the endpoint the request
+ * went to, so a 409's open target can be held to it.
+ */
+export function classifyBootstrapAnswer(status, body, origin) {
+    if (status === 200) {
+        const { token, org_id: orgId, user_id: userId, mcp_endpoint: mcpEndpoint } = body;
+        if (typeof token !== "string" ||
+            !FLOWSPRITE_TOKEN_RE.test(token) ||
+            typeof orgId !== "string" ||
+            !ORG_ID_RE.test(orgId) ||
+            typeof userId !== "string" ||
+            !USER_ID_RE.test(userId) ||
+            mcpEndpoint !== `${origin}/api/mcp`) {
+            return STOP_SERVER_ERROR;
+        }
+        return { kind: "token", token, orgId, userId, mcpEndpoint };
+    }
+    const deviceCode = body.device_code;
+    const expiresIn = clampExpiresIn(body.expires_in);
+    const interval = intervalSeconds(body.interval, expiresIn);
+    if (status === 202) {
+        if (typeof deviceCode !== "string" || !DEVICE_CODE_RE.test(deviceCode))
+            return STOP_SERVER_ERROR;
+        return { kind: "poll", deviceCode, expiresIn, interval };
+    }
+    if (status === 409 && (body.error === "browser_required" || body.error === "github_scope_missing")) {
+        const userCode = body.user_code;
+        if (typeof deviceCode !== "string" ||
+            !DEVICE_CODE_RE.test(deviceCode) ||
+            typeof userCode !== "string" ||
+            !USER_CODE_RE.test(userCode)) {
+            return STOP_SERVER_ERROR;
+        }
+        const openTarget = approvePageHref(body.verification_uri_complete ?? body.verification_uri, origin, userCode);
+        if (openTarget === null)
+            return STOP_SERVER_ERROR;
+        return { kind: "browser", reason: body.error, deviceCode, userCode, openTarget, expiresIn, interval };
+    }
+    const code = body.error;
+    if (typeof code !== "string" || !STOP_CODES.has(code))
+        return STOP_SERVER_ERROR;
+    const retryAfter = body.retry_after;
+    return code === "in_progress" && typeof retryAfter === "number" && retryAfter > 0
+        ? { kind: "stop", code, retryAfter }
+        : { kind: "stop", code: code };
+}