@throng/cli 0.1.1 → 0.1.2

package/README.md

@@ -15,6 +15,7 @@ throng org list        List your organisations
 throng org use <slug-or-id>
                        Choose the organisation later commands act in
 throng api [-f file]   Run a GraphQL document and print the data as JSON
+throng proxy           Serve a local endpoint for a GraphQL GUI, credentials added
 ```
 
 `api` reads the document from `-f <file>`, or from stdin when `-f` is absent
@@ -29,6 +30,54 @@ Revocation is best-effort: if the server cannot be reached, logout warns on stde
 and still forgets the credentials locally. `auth status` asks the server who you
 are; if it cannot, it reports what is stored locally and says the user is unknown.
 
+### `throng proxy`
+
+Point a GraphQL GUI at a local endpoint and it can query the API without ever
+holding a token:
+
+```
+throng proxy
+```
+
+That serves `http://127.0.0.1:7979/api/graphql` — the same path as the real
+endpoint, so only the origin differs — and forwards each request with
+`authorization` and `x-throng-organisation` added. Set the one header it prints:
+
+```
+x-throng-proxy-key: <printed on start>
+```
+
+Responses come back untouched, status and body alike: a client needs the server's
+own errors, not this proxy's opinion of them. The access token is refreshed as
+needed, so a long session never stops working, and the stored organisation is
+re-read per request — `throng org use` takes effect without a restart.
+
+It runs in the foreground until interrupted. There is no daemon, so an
+authenticated endpoint cannot outlive the terminal that opened it.
+
+| Option | Meaning |
+| --- | --- |
+| `-p, --port <number>` | Port to listen on. Default `7979`. |
+| `--new-key` | Replace the stored key before starting. |
+| `--no-key` | Accept requests without the key. See below. |
+
+The key lives at `~/.config/throng/proxy-key`, mode `0600`, and is stable so a
+client needs it only once. It is a file of its own rather than a field in the
+credentials: it is not a credential for any host, and keeping it separate keeps
+it clear of the lock and rotation rules that protect refresh tokens.
+
+**The key and CORS are coupled deliberately.** A custom request header forces a
+cross-origin caller through a preflight, so with a key required the proxy can
+safely echo the origin — which is what lets a browser-based client work where the
+real endpoint cannot. With `--no-key` it sends no CORS headers at all, because
+"reachable without a key" and "readable by any page you visit" must never both be
+true; only non-browser clients can use that mode.
+
+Requests are refused unless they arrive on loopback with a loopback `Host` (a
+foreign `Host` is how DNS rebinding arrives), as a `POST` to `/api/graphql`.
+
+Subscriptions are not proxied; this is HTTP only.
+
 ### Global options
 
 | Option | Meaning |

package/dist/commands/proxy.js

@@ -0,0 +1,59 @@
+import { getOrgId } from "../oauth/session.js";
+import { DEFAULT_PROXY_PORT, PROXY_KEY_HEADER, readOrCreateProxyKey, rotateProxyKey, startProxy, waitForInterrupt, } from "../proxy.js";
+import { info } from "../output.js";
+/**
+ * `throng proxy`: serve a loopback GraphQL endpoint that adds the credentials.
+ *
+ * Point a GraphQL GUI at the printed URL and it can query the API without ever
+ * holding a token. Runs in the foreground until interrupted; there is no daemon,
+ * so an authenticated endpoint cannot outlive the terminal that opened it.
+ */
+export function registerProxy(program, ctx) {
+    program
+        .command("proxy")
+        .description("Serve a local GraphQL endpoint that injects your credentials, for a GraphQL GUI")
+        .option("-p, --port <number>", `port to listen on (default: ${DEFAULT_PROXY_PORT})`)
+        .option("--no-key", "accept requests without the proxy key (see the warning it prints)")
+        .option("--new-key", "replace the stored proxy key before starting")
+        .action(async (opts, command) => {
+        const { host, org } = ctx();
+        let port = DEFAULT_PROXY_PORT;
+        if (opts.port !== undefined) {
+            port = Number(opts.port);
+            if (!Number.isInteger(port) || port < 1 || port > 65535) {
+                return command.error(`error: --port must be a whole number between 1 and 65535`, { exitCode: 2 });
+            }
+        }
+        const key = opts.key ? (opts.newKey ? await rotateProxyKey() : await readOrCreateProxyKey()) : undefined;
+        let proxy;
+        try {
+            proxy = await startProxy({ host, port, key, orgId: org });
+        }
+        catch (cause) {
+            const code = cause.code;
+            if (code === "EADDRINUSE") {
+                return command.error(`error: port ${port} is already in use. Pass --port to pick another.`, { exitCode: 1 });
+            }
+            throw cause;
+        }
+        const selectedOrg = org ?? (await getOrgId(host));
+        info(`Proxying ${proxy.url} -> ${host}/api/graphql`);
+        info(`Organisation: ${selectedOrg ?? "none selected — run `throng org use <slug-or-id>`"}`);
+        if (key) {
+            info("");
+            info("Set this header in your GraphQL client:");
+            info(`  ${PROXY_KEY_HEADER}: ${key}`);
+        }
+        else {
+            info("");
+            info("WARNING: running without a key. Any program on this machine can issue");
+            info("authenticated requests through this proxy while it is running. Browsers are");
+            info("still blocked, because no CORS headers are sent in this mode.");
+        }
+        info("");
+        info("Press Ctrl-C to stop.");
+        await waitForInterrupt();
+        await proxy.close();
+        info("Proxy stopped.");
+    });
+}

package/dist/credentials.js

@@ -14,6 +14,17 @@ export const LOCK_TIMEOUT_MS = 30_000;
 export class LockTimeoutError extends Error {
     name = "LockTimeoutError";
 }
+/**
+ * `${XDG_CONFIG_HOME:-~/.config}/throng`, where everything this CLI stores lives.
+ *
+ * A path helper, not credential access: other modules may use it to find a
+ * sibling file of their own. Reading or writing the credentials themselves
+ * still belongs to `oauth/session.ts` alone.
+ */
+export function configDir(env = process.env) {
+    const configHome = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
+    return join(configHome, "throng");
+}
 /**
  * `${XDG_CONFIG_HOME:-~/.config}/throng/credentials.json`.
  *
@@ -21,8 +32,7 @@ export class LockTimeoutError extends Error {
  * never at module load, so a changed environment is always honoured.
  */
 export function credentialsPath(env = process.env) {
-    const configHome = env.XDG_CONFIG_HOME || join(env.HOME || homedir(), ".config");
-    return join(configHome, "throng", "credentials.json");
+    return join(configDir(env), "credentials.json");
 }
 function lockPathFor(file) {
     return `${file}.lock`;

package/dist/index.js

@@ -7,6 +7,7 @@ import { Command, CommanderError } from "commander";
 import { registerApi } from "./commands/api.js";
 import { registerAuth } from "./commands/auth.js";
 import { registerOrg } from "./commands/org.js";
+import { registerProxy } from "./commands/proxy.js";
 import { registerToken } from "./commands/token.js";
 import { resolveHost } from "./config.js";
 import { AuthRequiredError } from "./errors.js";
@@ -61,6 +62,7 @@ export function buildProgram(deps = {}) {
     registerToken(program, ctx);
     registerOrg(program, ctx);
     registerApi(program, ctx);
+    registerProxy(program, ctx);
     return { program, exitCode: () => resolved?.exitCode ?? 0 };
 }
 /** Run the CLI and return its exit code. Never throws and never exits the process. */

package/dist/proxy.js

@@ -0,0 +1,235 @@
+import { randomBytes, timingSafeEqual } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { configDir } from "./credentials.js";
+import { AuthRequiredError } from "./errors.js";
+import { getAccessToken, getOrgId } from "./oauth/session.js";
+/** Mirrors the real endpoint's path, so the proxy URL differs only in origin. */
+export const PROXY_PATH = "/api/graphql";
+export const PROXY_KEY_HEADER = "x-throng-proxy-key";
+export const DEFAULT_PROXY_PORT = 7979;
+/** Matches the GraphQL client's own ceiling; a query may legitimately run long. */
+const UPSTREAM_TIMEOUT_MS = 60_000;
+/** `${XDG_CONFIG_HOME:-~/.config}/throng/proxy-key`. */
+export function proxyKeyPath(env = process.env) {
+    return join(configDir(env), "proxy-key");
+}
+async function writeKey(env) {
+    const key = randomBytes(32).toString("base64url");
+    await mkdir(configDir(env), { recursive: true, mode: 0o700 });
+    await writeFile(proxyKeyPath(env), `${key}\n`, { mode: 0o600 });
+    return key;
+}
+/**
+ * The stored proxy key, created on first use.
+ *
+ * Deliberately a file of its own rather than a field in the credentials: it is
+ * not a credential for any host, and keeping it out of that file keeps it clear
+ * of the lock and the rotation rules that protect refresh tokens.
+ */
+export async function readOrCreateProxyKey(env = process.env) {
+    try {
+        const stored = (await readFile(proxyKeyPath(env), "utf8")).trim();
+        if (stored.length > 0)
+            return stored;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return writeKey(env);
+}
+/** Replace the stored key, invalidating any client still sending the old one. */
+export async function rotateProxyKey(env = process.env) {
+    return writeKey(env);
+}
+function equalKeys(provided, expected) {
+    const a = Buffer.from(provided);
+    const b = Buffer.from(expected);
+    // timingSafeEqual throws on a length mismatch, which is itself observable;
+    // the length check first keeps the comparison total.
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/** A `Host` naming anything but loopback means the request was rebound to us. */
+function hostIsLoopback(header, port) {
+    if (header === undefined)
+        return false;
+    const expected = [`127.0.0.1:${port}`, `localhost:${port}`, `[::1]:${port}`];
+    return expected.includes(header.toLowerCase());
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    return Buffer.concat(chunks);
+}
+/**
+ * A loopback GraphQL proxy that adds the credentials a client cannot.
+ *
+ * It exists so a GraphQL GUI can talk to the API without ever holding a token:
+ * the client sends an ordinary unauthenticated POST, and this injects
+ * `authorization` and `x-throng-organisation` on the way out. Responses pass
+ * back untouched — status, body and content type — because a client needs the
+ * server's own errors, not this proxy's opinion of them.
+ *
+ * **The key and CORS are coupled on purpose.** A custom request header forces a
+ * cross-origin caller through a preflight, so with a key required we can safely
+ * echo the origin and let a browser-based client work. With no key, echoing an
+ * origin would let any page the user visits read authenticated responses, so no
+ * CORS headers are sent at all and only non-browser clients can use it.
+ */
+export async function startProxy(opts) {
+    const { host, port = DEFAULT_PROXY_PORT, key, orgId } = opts;
+    const log = opts.log ?? ((message) => void process.stderr.write(`${message}\n`));
+    const requireKey = key !== undefined && key.length > 0;
+    let boundPort = port;
+    const server = createServer((req, res) => {
+        void handle(req, res).catch(() => {
+            // A handler must never reject into the server's error event.
+            if (!res.headersSent)
+                res.writeHead(500, { "content-type": "text/plain; charset=utf-8" });
+            res.end("Proxy error");
+        });
+    });
+    const corsHeaders = (req) => {
+        if (!requireKey)
+            return {};
+        const origin = req.headers.origin;
+        return {
+            "access-control-allow-origin": typeof origin === "string" && origin.length > 0 ? origin : "*",
+            vary: "origin",
+        };
+    };
+    async function handle(req, res) {
+        const reply = (status, text, extra = {}) => {
+            res.writeHead(status, {
+                "content-type": "text/plain; charset=utf-8",
+                "x-content-type-options": "nosniff",
+                ...extra,
+            });
+            res.end(text);
+        };
+        // A malformed request target makes `new URL` throw; that must not escape.
+        let url;
+        try {
+            url = new URL(req.url ?? "/", "http://127.0.0.1");
+        }
+        catch {
+            reply(400, "Bad request");
+            return;
+        }
+        if (url.pathname !== PROXY_PATH) {
+            reply(404, "Not found");
+            return;
+        }
+        if (!hostIsLoopback(req.headers.host, boundPort)) {
+            reply(403, "Forbidden");
+            return;
+        }
+        if (req.method === "OPTIONS") {
+            if (!requireKey) {
+                reply(204, "");
+                return;
+            }
+            res.writeHead(204, {
+                ...corsHeaders(req),
+                "access-control-allow-methods": "POST, OPTIONS",
+                "access-control-allow-headers": `content-type, ${PROXY_KEY_HEADER}`,
+                "access-control-max-age": "600",
+            });
+            res.end();
+            return;
+        }
+        if (req.method !== "POST") {
+            reply(405, "Method not allowed", { allow: "POST, OPTIONS" });
+            return;
+        }
+        if (requireKey) {
+            const provided = req.headers[PROXY_KEY_HEADER];
+            if (typeof provided !== "string" || !equalKeys(provided, key)) {
+                // Never name the expected value, and never hint at its length.
+                reply(401, `Missing or invalid ${PROXY_KEY_HEADER}`, corsHeaders(req));
+                return;
+            }
+        }
+        const body = await readBody(req);
+        let token;
+        try {
+            token = await getAccessToken(host);
+        }
+        catch (err) {
+            const message = err instanceof AuthRequiredError ? err.message : "Could not obtain an access token";
+            log(`proxy: ${message}`);
+            reply(401, message, corsHeaders(req));
+            return;
+        }
+        const org = orgId ?? (await getOrgId(host));
+        const headers = {
+            authorization: `Bearer ${token}`,
+            "content-type": req.headers["content-type"] ?? "application/json",
+            accept: "application/json",
+        };
+        if (org !== undefined)
+            headers["x-throng-organisation"] = org;
+        let upstream;
+        try {
+            upstream = await fetch(`${host}${PROXY_PATH}`, {
+                method: "POST",
+                headers,
+                // Bytes, not a re-serialised string: whatever the client sent is what the
+                // API sees. The copy is deliberate — `BodyInit` wants a `Uint8Array` over
+                // a plain `ArrayBuffer`, and a `Buffer`'s is only `ArrayBufferLike`.
+                // GraphQL documents are small enough for that to cost nothing.
+                body: new Uint8Array(body),
+                signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            const reason = err instanceof Error && err.name === "TimeoutError" ? "timed out" : "could not be reached";
+            log(`proxy: ${host} ${reason}`);
+            reply(502, `Upstream ${reason}`, corsHeaders(req));
+            return;
+        }
+        const text = await upstream.text();
+        if (upstream.status === 403 && text.includes("ORGANISATION_ACCESS_DENIED")) {
+            // Forwarded as-is: a background server silently rewriting the stored org
+            // would be worse than a visible error the user can act on.
+            log("proxy: the selected organisation was refused. Run `throng org use <slug-or-id>` to choose another.");
+        }
+        res.writeHead(upstream.status, {
+            "content-type": upstream.headers.get("content-type") ?? "application/json",
+            "x-content-type-options": "nosniff",
+            ...corsHeaders(req),
+        });
+        res.end(text);
+    }
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.removeListener("error", reject);
+            resolve();
+        });
+    });
+    const addr = server.address();
+    if (addr === null || typeof addr === "string")
+        throw new Error("proxy did not bind a TCP port");
+    boundPort = addr.port;
+    return {
+        port: boundPort,
+        address: addr.address,
+        url: `http://127.0.0.1:${boundPort}${PROXY_PATH}`,
+        close: () => new Promise((resolve) => {
+            server.closeAllConnections();
+            server.close(() => resolve());
+        }),
+    };
+}
+/** Keep a started proxy running until the process is interrupted. */
+export function waitForInterrupt() {
+    return new Promise((resolve) => {
+        const stop = () => resolve();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@throng/cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Command-line client for Throng",
   "license": "UNLICENSED",
   "repository": {