@join-pantheon/cli 0.32.1 → 0.33.0-rc.2

package/dist/uri-handler.js

@@ -0,0 +1,335 @@
+import { spawnSync } from "node:child_process";
+import { createHmac, randomBytes, timingSafeEqual } from "node:crypto";
+import { appendFileSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join, win32 } from "node:path";
+export const URI_SCHEME = "pantheon";
+export const URI_HOSTS = ["board", "done", "explain", "details"];
+const FORMS = {
+    board: { required: [], optional: [] },
+    done: { required: ["decision", "k"], optional: ["act", "space"] },
+    explain: { required: ["decision", "k"], optional: ["act", "space"] },
+    details: { required: ["act", "k"], optional: ["decision", "space"] },
+};
+export const URI_VALUE = {
+    decision: /^o_[a-z0-9]{6,48}$/,
+    act: /^a_[A-Za-z0-9]{6,48}$/,
+    space: /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/,
+    k: /^[0-9a-f]{32}$/,
+};
+export const MAX_URI = 400;
+function canonical(host, params) {
+    return `${host}?${Object.keys(params).filter((k) => k !== "k").sort().map((k) => `${k}=${params[k]}`).join("&")}`;
+}
+export function uriCode(key, host, params) {
+    return createHmac("sha256", key).update(canonical(host, params)).digest("hex").slice(0, 32);
+}
+export function buildUri(host, params, key) {
+    const form = FORMS[host];
+    const kept = {};
+    for (const name of [...form.required, ...form.optional]) {
+        if (name === "k")
+            continue;
+        const v = params[name];
+        if (v === undefined || v === "") {
+            if (form.required.includes(name))
+                return null;
+            continue;
+        }
+        if (!URI_VALUE[name].test(v)) {
+            if (form.required.includes(name))
+                return null;
+            continue;
+        }
+        kept[name] = v;
+    }
+    if (form.required.includes("k")) {
+        if (!key)
+            return null;
+        kept.k = uriCode(key, host, kept);
+    }
+    const q = Object.entries(kept).map(([k, v]) => `${k}=${encodeURIComponent(v)}`).join("&");
+    return `${URI_SCHEME}://${host}${q ? `?${q}` : ""}`;
+}
+export function parseUri(raw) {
+    if (typeof raw !== "string" || !raw)
+        return { ok: false, why: "no link given" };
+    if (raw.length > MAX_URI)
+        return { ok: false, why: `the link is ${raw.length} characters long; a Pantheon link is under ${MAX_URI}` };
+    if (/^pantheons?:\/\/[^/?#\s]+\/[^/?#\s]+#\S+$/i.test(raw))
+        return { ok: false, why: "this looks like a team invite, not an alert's link — to join, copy the link and run in a terminal: pantheon join \"<the link>\"" };
+    if (!/^[A-Za-z0-9:/?&=%._~-]+$/.test(raw))
+        return { ok: false, why: "the link holds characters a Pantheon link never has" };
+    const m = /^pantheon:\/\/([A-Za-z]+)\/?(?:\?(.*))?$/i.exec(raw);
+    if (!m)
+        return { ok: false, why: "not a Pantheon alert link (expected pantheon://board, done, explain or details)" };
+    const host = m[1].toLowerCase();
+    if (!URI_HOSTS.includes(host))
+        return { ok: false, why: `"${m[1]}" is not something a Pantheon link can do (board, done, explain or details)` };
+    const form = FORMS[host];
+    const params = {};
+    const query = m[2];
+    if (query !== undefined && query !== "") {
+        for (const part of query.split("&")) {
+            const eq = part.indexOf("=");
+            if (eq <= 0)
+                return { ok: false, why: "a parameter in the link has no value" };
+            const name = part.slice(0, eq);
+            if (!/^[a-z]{1,16}$/.test(name))
+                return { ok: false, why: "the link has a parameter Pantheon never writes" };
+            if (![...form.required, ...form.optional].includes(name))
+                return { ok: false, why: `"${name}" is not a parameter of pantheon://${host}` };
+            if (Object.prototype.hasOwnProperty.call(params, name))
+                return { ok: false, why: `"${name}" appears twice in the link` };
+            let value;
+            try {
+                value = decodeURIComponent(part.slice(eq + 1));
+            }
+            catch {
+                return { ok: false, why: `"${name}" is not encoded correctly` };
+            }
+            if (!URI_VALUE[name].test(value))
+                return { ok: false, why: `"${name}" is not in the form Pantheon writes it` };
+            params[name] = value;
+        }
+    }
+    else if (query === "")
+        return { ok: false, why: "the link ends in an empty query" };
+    for (const r of form.required)
+        if (!(r in params))
+            return { ok: false, why: `pantheon://${host} needs "${r}"` };
+    return { ok: true, host, params };
+}
+export function verifyUri(p, key) {
+    if (!FORMS[p.host].required.includes("k"))
+        return true;
+    if (!key || !p.params.k)
+        return false;
+    const want = Buffer.from(uriCode(key, p.host, p.params), "utf8");
+    const got = Buffer.from(p.params.k, "utf8");
+    return want.length === got.length && timingSafeEqual(want, got);
+}
+export function hudActionFor(p) {
+    const { decision, act, space } = p.params;
+    const extra = { ...(space ? { space } : {}) };
+    if (p.host === "done")
+        return { action: "done", decision: decision, ...(act ? { act } : {}), ...extra };
+    if (p.host === "explain")
+        return { action: "open", decision: decision, ...(act ? { act } : {}), ...extra };
+    if (p.host === "details")
+        return { action: "details", act: act, ...(decision ? { decision } : {}), ...extra };
+    return null;
+}
+export const uriKeyPath = (home) => join(home, "uri-key");
+export function uriKey(home, create = true) {
+    const f = uriKeyPath(home);
+    const read = () => { try {
+        const k = readFileSync(f, "utf8").trim();
+        return /^[0-9a-f]{64}$/.test(k) ? k : null;
+    }
+    catch {
+        return null;
+    } };
+    const have = read();
+    if (have || !create)
+        return have;
+    try {
+        mkdirSync(home, { recursive: true });
+        writeFileSync(f, randomBytes(32).toString("hex"), { mode: 0o600, flag: "wx" });
+    }
+    catch {
+        if (!read()) {
+            try {
+                const tmp = `${f}.${randomBytes(6).toString("hex")}.tmp`;
+                writeFileSync(tmp, randomBytes(32).toString("hex"), { mode: 0o600, flag: "wx" });
+                renameSync(tmp, f);
+            }
+            catch {
+                return null;
+            }
+        }
+    }
+    return read();
+}
+export const hudActionPath = (home) => join(home, "bin", ".hud-action.json");
+export function writeHudAction(home, action) {
+    const f = hudActionPath(home);
+    mkdirSync(join(home, "bin"), { recursive: true });
+    const tmp = `${f}.${randomBytes(8).toString("hex")}.tmp`;
+    try {
+        writeFileSync(tmp, JSON.stringify(action), { mode: 0o600, flag: "wx" });
+        renameSync(tmp, f);
+    }
+    catch (e) {
+        try {
+            rmSync(tmp, { force: true });
+        }
+        catch { }
+        throw e;
+    }
+    return f;
+}
+export function logUri(home, line, now = new Date()) {
+    try {
+        mkdirSync(join(home, "logs"), { recursive: true });
+        appendFileSync(join(home, "logs", "uri.log"), `${now.toISOString()} ${line}\n`, { mode: 0o600 });
+    }
+    catch { }
+}
+export function describeUri(p) {
+    const shown = Object.entries(p.params).filter(([k]) => k !== "k").map(([k, v]) => `${k}=${v}`).join(" ");
+    return `${p.host}${shown ? ` ${shown}` : ""}`;
+}
+export async function handleUri(args, d) {
+    const now = d.now ?? (() => new Date());
+    const refuse = async (why, logged) => {
+        d.print(`Pantheon did not act on this link: ${why}`);
+        logUri(d.home, `refused ${logged}: ${why}`, now());
+        await d.pause();
+        return 2;
+    };
+    if (args.length !== 1)
+        return refuse("it expects exactly one link", `(${args.length} arguments)`);
+    if (d.wokenRun)
+        return refuse("a woken run cannot act for the person — a person has to click it", "(inside a woken run)");
+    const p = parseUri(args[0]);
+    if (!p.ok)
+        return refuse(p.why, "(a link that is not one of Pantheon's)");
+    if (!verifyUri(p, uriKey(d.home, false))) {
+        return refuse("this link was not made by Pantheon on this machine (it acts only on links from its own alerts)", describeUri(p));
+    }
+    if (p.host === "board") {
+        if (d.openBoard) {
+            let ok = false;
+            try {
+                ok = await d.openBoard();
+            }
+            catch {
+                ok = false;
+            }
+            if (ok) {
+                logUri(d.home, "board: opened", now());
+                return 0;
+            }
+            logUri(d.home, "board: could not start; showing the brief instead", now());
+        }
+        else
+            logUri(d.home, "board: this build has none; showing the brief instead", now());
+        const code = await d.runBrief();
+        await d.pause();
+        return code;
+    }
+    const action = { ...hudActionFor(p), nonce: randomBytes(16).toString("hex") };
+    try {
+        writeHudAction(d.home, action);
+    }
+    catch (e) {
+        return refuse(`could not queue the action (${e.message.split("\n")[0]})`, describeUri(p));
+    }
+    logUri(d.home, `${describeUri(p)}: queued ${action.action}`, now());
+    const code = await d.runQueued(action.nonce);
+    logUri(d.home, `${describeUri(p)}: explain --queued exited ${code}`, now());
+    if (code !== 0 || p.host === "details")
+        await d.pause();
+    return code;
+}
+export const PROTOCOL_KEY = "HKCU\\Software\\Classes\\pantheon";
+export const COMMAND_KEY = `${PROTOCOL_KEY}\\shell\\open\\command`;
+export const PANTHEON_AUMID = "JoinPantheon.Pantheon";
+export const AUMID_KEY = `HKCU\\Software\\Classes\\AppUserModelId\\${PANTHEON_AUMID}`;
+export function handlerCommand(entry, home = null) {
+    const words = [entry.command, ...entry.args];
+    if (!words.length || /\.(cmd|bat)$/i.test(entry.command))
+        return null;
+    if ([...words, ...(home ? [home] : [])].some((w) => w.includes('"') || /[\r\n%]/.test(w)))
+        return null;
+    const q = (w) => (/^[A-Za-z0-9_.:\\/-]+$/.test(w) && !/[\\/]/.test(w) ? w : `"${w}"`);
+    return `${words.map(q).join(" ")} handle-uri${home ? ` --home "${home}"` : ""} "%1"`;
+}
+export function handlerEntry(entry, flags = []) {
+    const args = entry.args[entry.args.length - 1] === "mcp" ? entry.args.slice(0, -1) : entry.args;
+    return { command: entry.command, args: [...flags.filter((f) => !args.includes(f)), ...args] };
+}
+export function parseHandleUriArgs(args, isAbsolute = (p) => win32.isAbsolute(p) || p.startsWith("/"), normalize = (p) => p) {
+    if (args[0] !== "--home")
+        return { home: null, rest: [...args] };
+    if (args.length !== 3)
+        return { error: "it expects --home <folder> and then exactly one link" };
+    const dir = args[1];
+    if (!dir || /[\r\n"%]/.test(dir) || !isAbsolute(dir) || normalize(dir) !== dir || /(^|[\\/])\.\.([\\/]|$)/.test(dir))
+        return { error: "its --home is not a full path to a folder" };
+    return { home: dir, rest: [args[2]] };
+}
+export function regDefault(stdout) {
+    for (const line of stdout.split(/\r?\n/)) {
+        const m = /^\s+\S.*?\s{2,}REG_(?:EXPAND_)?SZ(?:\s{2,}(.*))?\s*$/.exec(line);
+        if (m)
+            return (m[1] ?? "").trimEnd();
+    }
+    return null;
+}
+const isOurs = (command) => !!command && / handle-uri(?: --home "[^"%\r\n]+")? "%1"$/.test(command);
+export function registerUriHandler(command, io, icon) {
+    const now = io.reg(["query", COMMAND_KEY, "/ve"]);
+    const current = now.status === 0 ? regDefault(now.stdout) : null;
+    if (current !== null && !isOurs(current)) {
+        return { changed: false, ok: false, line: `the pantheon: links are registered to another program (${current}) — left alone, so alert buttons will not work here` };
+    }
+    if (current === command) {
+        const url = io.reg(["query", PROTOCOL_KEY, "/v", "URL Protocol"]);
+        if (url.status === 0)
+            return { changed: false, ok: true, line: "pantheon: links already open Pantheon" };
+    }
+    const adds = [
+        ["add", PROTOCOL_KEY, "/ve", "/d", "URL:Pantheon", "/f"],
+        ["add", PROTOCOL_KEY, "/v", "URL Protocol", "/d", "", "/f"],
+        ...(icon ? [["add", `${PROTOCOL_KEY}\\DefaultIcon`, "/ve", "/d", icon, "/f"]] : []),
+        ["add", COMMAND_KEY, "/ve", "/d", command, "/f"],
+        ["add", AUMID_KEY, "/v", "DisplayName", "/d", "Pantheon", "/f"],
+        ...(icon ? [["add", AUMID_KEY, "/v", "IconUri", "/d", icon, "/f"]] : []),
+    ];
+    for (const a of adds) {
+        const r = io.reg(a);
+        if (r.refused)
+            return { changed: false, ok: false, line: `pantheon: links not registered — ${r.refused}` };
+        if (r.status !== 0)
+            return { changed: true, ok: false, line: `could not register pantheon: links (reg ${a.slice(0, 2).join(" ")} exited ${r.status ?? "on a signal"})` };
+    }
+    return { changed: true, ok: true, line: `pantheon: links now open Pantheon (${PROTOCOL_KEY})` };
+}
+export function aumidRegistered(io) {
+    return io.reg(["query", AUMID_KEY, "/v", "DisplayName"]).status === 0;
+}
+export function unregisterUriHandler(io) {
+    const removed = [], left = [];
+    const now = io.reg(["query", COMMAND_KEY, "/ve"]);
+    const current = now.status === 0 ? regDefault(now.stdout) : null;
+    if (current !== null && !isOurs(current))
+        left.push(`the pantheon: link handler (${PROTOCOL_KEY}) — it belongs to another program, so it was left alone`);
+    else if (now.status === 0) {
+        const r = io.reg(["delete", PROTOCOL_KEY, "/f"]);
+        if (r.status === 0)
+            removed.push(`the pantheon: link handler (${PROTOCOL_KEY})`);
+        else
+            left.push(r.refused ? `the pantheon: link handler (${PROTOCOL_KEY}) — ${r.refused}` : `the pantheon: link handler (${PROTOCOL_KEY}) — remove it with: reg delete ${PROTOCOL_KEY} /f`);
+    }
+    if (io.reg(["query", AUMID_KEY]).status === 0) {
+        const r = io.reg(["delete", AUMID_KEY, "/f"]);
+        if (r.status === 0)
+            removed.push(`Pantheon's notification app id (${AUMID_KEY})`);
+        else
+            left.push(r.refused ? `Pantheon's notification app id — ${r.refused}` : `Pantheon's notification app id — remove it with: reg delete "${AUMID_KEY}" /f`);
+    }
+    return { removed, left };
+}
+export function realRegIo(borrowed, env = process.env) {
+    const exe = win32.join(env.SystemRoot || env.windir || "C:\\Windows", "System32", "reg.exe");
+    return {
+        reg: (args) => {
+            if (args[0] !== "query" && borrowed())
+                return { status: 1, stdout: "", refused: "this Pantheon home, HOME or USERPROFILE is not your own Windows profile (a test or a sandbox), so the registry was not changed" };
+            const r = spawnSync(exe, args, { encoding: "utf8", windowsHide: true, timeout: 10_000, stdio: ["ignore", "pipe", "pipe"] });
+            return { status: r.error ? null : r.status, stdout: r.stdout ?? "" };
+        },
+    };
+}
+//# sourceMappingURL=uri-handler.js.map