message-cp 0.0.0-stage → 0.1.0

package/dist/client-metadata.js

@@ -0,0 +1,167 @@
+import { Resolver } from "node:dns";
+import { request as httpsRequest } from "node:https";
+import { BlockList, isIP } from "node:net";
+// Fetches an OAuth Client ID Metadata Document for the authorization endpoint of `serve --public-url`. The URL is one a
+// stranger chose, so the address check is the boundary against server-side request forgery: the connection may go only
+// to a public address, checked on the address the connection resolves and uses, not on a separate lookup made first, and
+// again on the socket once it connects. The name is resolved by a resolver of the fetch's own, whose queries run on the
+// event loop rather than in libuv's thread pool and are cancelled when the fetch ends, so no lookup outlives the fetch
+// (and its slot in the authorization endpoint's cap) or holds up the thread pool's other work. Nothing of the incoming request is sent, no redirect is followed, and the answer
+// is cut off at a size and a deadline. Nothing here logs anything.
+/** How long a fetch may take, from the request to the last byte, as a webhook delivery may. */
+export const METADATA_TIMEOUT_MS = 5000;
+/** The largest document read, the size the Client ID Metadata Document draft recommends; a larger one is refused. */
+export const MAX_METADATA_BYTES = 5 * 1024;
+/** A fetch refused or failed. Its message is fixed text that never quotes the URL or the answer. */
+export class MetadataFetchError extends Error {
+}
+// Every range that is not a public unicast address: in IPv4 loopback, private, link-local (169.254.169.254 among them),
+// carrier-grade NAT, unspecified, documentation, benchmarking, multicast and reserved. In IPv6 only global unicast
+// (2000::/3) is allowed, which leaves out loopback, unspecified, unique-local, link-local, multicast and the IPv4-mapped,
+// -compatible and -translated forms; within it the ranges that embed an IPv4 address (NAT64, 6to4 and Teredo) and the
+// documentation ones are refused whole rather than unpacked.
+// Kept apart by family: an IPv6 rule such as ::ffff:0:0/96 would otherwise match every IPv4 address.
+const blocked = { ipv4: new BlockList(), ipv6: new BlockList() };
+for (const [net, prefix] of [
+    ["0.0.0.0", 8],
+    ["10.0.0.0", 8],
+    ["100.64.0.0", 10],
+    ["127.0.0.0", 8],
+    ["169.254.0.0", 16],
+    ["172.16.0.0", 12],
+    ["192.0.0.0", 24],
+    ["192.0.2.0", 24],
+    ["192.168.0.0", 16],
+    ["198.18.0.0", 15],
+    ["198.51.100.0", 24],
+    ["203.0.113.0", 24],
+    ["224.0.0.0", 4],
+    ["240.0.0.0", 4],
+]) {
+    blocked.ipv4.addSubnet(net, prefix, "ipv4");
+}
+for (const [net, prefix] of [
+    ["2001::", 32],
+    ["2001:db8::", 32],
+    ["2002::", 16],
+    ["3fff::", 20],
+]) {
+    blocked.ipv6.addSubnet(net, prefix, "ipv6");
+}
+const globalUnicast = new BlockList();
+globalUnicast.addSubnet("2000::", 3, "ipv6");
+/** Whether `address`, an IP address as a resolver or socket reports it, is a public unicast address. */
+export function isPublicAddress(address) {
+    const family = address === undefined ? 0 : isIP(address);
+    if (family === 0)
+        return false;
+    try {
+        if (family === 4)
+            return !blocked.ipv4.check(address, "ipv4");
+        return globalUnicast.check(address, "ipv6") && !blocked.ipv6.check(address, "ipv6");
+    }
+    catch {
+        return false;
+    }
+}
+const refused = () => new MetadataFetchError("The address is not a public one.");
+/**
+ * Fetches the document at `url`, an https URL `checkMetadataUrl` in oauth.ts accepted, and answers it parsed as JSON. It
+ * sends only `Accept: application/json` (and the `Host` and `Connection` headers Node adds); it rejects with
+ * `MetadataFetchError` for a host that is or resolves to an address that is not public, an answer other than 200
+ * (a redirect included), one over MAX_METADATA_BYTES or not JSON, a connection that fails, or past METADATA_TIMEOUT_MS.
+ * There is no cache: the authorization endpoint fetches once for each request whose `client_id` passes
+ * `checkMetadataUrl`, before checking its other parameters, with at most `maxSessions` fetches at once.
+ */
+export function fetchClientMetadata(url, options = {}) {
+    const allowed = options.allowed ?? isPublicAddress;
+    const target = new URL(url);
+    const host = target.hostname.replace(/^\[(.*)\]$/, "$1");
+    // A literal address is connected to without a lookup, so it is checked here.
+    if (isIP(host) !== 0 && !allowed(host))
+        return Promise.reject(refused());
+    const timeoutMs = options.timeoutMs ?? METADATA_TIMEOUT_MS;
+    const resolver = options.resolver ?? new Resolver({ timeout: timeoutMs, tries: 1 });
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const finish = () => {
+            settled = true;
+            clearTimeout(deadline);
+            resolver.cancel();
+        };
+        const fail = (err) => {
+            if (settled)
+                return;
+            finish();
+            req.destroy();
+            reject(err instanceof MetadataFetchError ? err : new MetadataFetchError("The document could not be fetched."));
+        };
+        // The connection's own lookup: the addresses it returns are the ones it connects to, and any that is not public
+        // refuses the whole name. It asks for the families the connection takes, and fails only when every query does.
+        const lookup = (hostname, lookupOptions, callback) => {
+            const family = Number(String(lookupOptions.family ?? 0).replace(/^IPv/, "")) || 0;
+            const queries = [4, 6]
+                .filter((f) => family === 0 || family === f)
+                .map((f) => new Promise((done, failed) => resolver[f === 4 ? "resolve4" : "resolve6"](hostname, (err, found) => err ? failed(err) : done(found.map((address) => ({ address, family: f }))))));
+            void Promise.allSettled(queries).then((results) => {
+                const addresses = results.flatMap((r) => (r.status === "fulfilled" ? r.value : []));
+                if (addresses.length === 0) {
+                    const failure = results.find((r) => r.status === "rejected");
+                    return callback(failure ? failure.reason : refused());
+                }
+                if (!addresses.every((a) => allowed(a.address)))
+                    return callback(refused());
+                if (lookupOptions.all)
+                    return callback(null, addresses);
+                callback(null, addresses[0].address, addresses[0].family);
+            });
+        };
+        const req = (options.request ?? httpsRequest)({
+            host,
+            port: target.port || undefined,
+            path: target.pathname,
+            method: "GET",
+            headers: { Accept: "application/json" },
+            agent: false,
+            lookup: lookup,
+        });
+        const deadline = setTimeout(() => fail(new MetadataFetchError("The document took too long.")), timeoutMs);
+        // Checked again on the socket once it connects, before the HTTP request is sent (TLS has begun its handshake by then).
+        req.on("socket", (socket) => {
+            socket.once("connect", () => {
+                if (!allowed(socket.remoteAddress))
+                    fail(refused());
+            });
+        });
+        req.on("error", fail);
+        req.on("response", (res) => {
+            if (res.statusCode !== 200)
+                return fail(new MetadataFetchError("The document could not be fetched."));
+            if (Number(res.headers["content-length"]) > MAX_METADATA_BYTES)
+                return fail(new MetadataFetchError("The document is too large."));
+            const chunks = [];
+            let size = 0;
+            res.on("data", (chunk) => {
+                size += chunk.length;
+                if (size > MAX_METADATA_BYTES)
+                    return fail(new MetadataFetchError("The document is too large."));
+                chunks.push(chunk);
+            });
+            res.on("error", fail);
+            res.on("end", () => {
+                if (settled)
+                    return;
+                let doc;
+                try {
+                    doc = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+                }
+                catch {
+                    return fail(new MetadataFetchError("The document is not JSON."));
+                }
+                finish();
+                resolve(doc);
+            });
+        });
+        req.end();
+    });
+}

package/dist/connect.js

@@ -0,0 +1,85 @@
+import { addToken } from "./accounts.js";
+import { registerWithIdentity, resetAgentKey, validateName } from "./agents.js";
+import { shellQuote } from "./wait.js";
+// `message-cp connect`: what a client needs to act as one agent of an account over HTTP, made in one step on the
+// server. The token and key are returned for the CLI to print once, to stdout; only their hashes are stored.
+export class ConnectError extends Error {
+}
+/**
+ * The public URL `raw` clients reach the server at, parsed with `new URL()`: https, or http only for a literal loopback
+ * address (127.x.x.x or [::1], not `localhost`), with no username, password, query or fragment, since a token is sent to
+ * it. `connect --url` and `serve --public-url` both check it here.
+ */
+export function publicUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new ConnectError(`--url is not a URL: give the server's public address, for example https://message-cp.example.com.`);
+    }
+    const loopback = /^127(\.\d{1,3}){3}$/.test(url.hostname) || url.hostname === "[::1]";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new ConnectError("--url must be https (plain http only for 127.x.x.x or [::1]): the token would cross the network in the clear.");
+    }
+    // `href` keeps an empty `?` or `#`, which `search` and `hash` report as "".
+    if (url.username || url.password || url.href.includes("?") || url.href.includes("#")) {
+        throw new ConnectError("--url must not carry a username, password, query or fragment.");
+    }
+    return url;
+}
+/** The `/mcp` endpoint for the public URL `raw`, checked by `publicUrl`. A trailing `/mcp` is the same as none. */
+export function mcpEndpoint(raw) {
+    const url = publicUrl(raw);
+    const endpoint = new URL(url.href);
+    // Set as the path, never resolved as a reference, so no path can change the host.
+    endpoint.pathname = `${url.pathname.replace(/\/+$/, "").replace(/\/mcp$/, "")}/mcp`;
+    return endpoint;
+}
+/**
+ * Makes the account's agent `name` with a new key, or, with `newKey`, gives its existing agent of that name (any case) a
+ * new key as `resetAgentKey` does, ending its sessions; then makes an agent token for the account bound to that agent. One transaction:
+ * `registerWithIdentity`, `resetAgentKey` and `addToken` run inside it as savepoints, so a failure leaves no agent, key
+ * or token behind. Refuses, changing nothing, an unknown account, an invalid name, a person's name, and an existing
+ * agent without `newKey`, since its key is stored only as a hash and cannot be shown again. The token is bound to the
+ * agent: it acts as that agent with no headers or `register`, and as no other name.
+ */
+export const connectAgent = (db, account, name, newKey) => db.transaction(() => {
+    const acct = db.prepare("SELECT id, name FROM accounts WHERE name = ?").get(account);
+    if (!acct)
+        throw new ConnectError(`No account named '${account}'.`);
+    validateName(name);
+    const live = db
+        .prepare("SELECT id, name, person FROM agents WHERE account_id = ? AND name = ? AND removed_at IS NULL")
+        .get(acct.id, name);
+    if (live?.person === 1)
+        throw new ConnectError(`The name '${live.name}' belongs to a person, not an agent.`);
+    if (live && !newKey) {
+        throw new ConnectError(`Agent '${live.name}' of account '${acct.name}' already exists. Its key is stored only as a hash, so it cannot be shown again; pass --new-key to give it a new one, which ends its current sessions.`);
+    }
+    let agent;
+    if (live)
+        agent = { ...resetAgentKey(db, acct.name, live.name), id: live.id };
+    else {
+        const { result, identity } = registerWithIdentity(db, acct.id, name);
+        agent = { id: identity.id, name: result.name, key: result.key };
+    }
+    // Bound to the agent, so the token alone acts as it, and as nothing else.
+    const token = addToken(db, acct.name, false, true, agent.id);
+    return { name: agent.name, account: acct.name, reset: live !== undefined, key: agent.key, tokenId: token.id, token: token.token };
+}).immediate();
+/** The two things `connect` prints: a `claude mcp add` command, then the same server as a JSON `mcpServers` entry. */
+export function clientSetup(endpoint, c) {
+    const headers = {
+        Authorization: `Bearer ${c.token}`,
+        "X-Message-CP-Agent": c.name,
+        "X-Message-CP-Agent-Key": c.key,
+    };
+    const command = [
+        "claude mcp add --transport http message-cp",
+        shellQuote(endpoint.href),
+        ...Object.entries(headers).map(([k, v]) => `--header ${shellQuote(`${k}: ${v}`)}`),
+    ].join(" ");
+    const json = JSON.stringify({ mcpServers: { "message-cp": { type: "http", url: endpoint.href, headers } } }, null, 2);
+    return `${command}\n\n${json}\n`;
+}