Pairing

import { randomBytes, createHash } from "node:crypto";

const b64url = (b: Buffer) =>
  b.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");

// Step 1. Keep the verifier and the state in memory until the exchange. Never log the verifier.
const verifier = b64url(randomBytes(32));
const challenge = b64url(createHash("sha256").update(verifier).digest());
const state = b64url(randomBytes(16));

// Step 2. Open the deep link. The parameters are on the URL scheme page.
const params = new URLSearchParams({
  client: "My Editor on macbook-pro",
  challenge,
  redirect: "http://127.0.0.1:7391/callback",
  response_mode: "query",
  state,
  scopes: "readWrite",
});
await openUrl(`tablepro://integrations/pair?${params}`); // however your host opens a URL

// Step 3. Your callback receives ?code=<uuid>&state=<state>, or ?error=access_denied when the user says no.
// 23508 is the default port. Make it a setting: if the port is taken, the server binds another one,
// and the Status row in Settings > MCP shows the port in use.
export async function exchange(callback: URL, port = 23508): Promise<string> {
  const query = callback.searchParams;
  if (query.get("state") !== state) throw new Error("pairing state mismatch");
  const code = query.get("code");
  if (!code) throw new Error(`pairing refused: ${query.get("error")}`);

  const res = await fetch(`http://127.0.0.1:${port}/v1/integrations/exchange`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ code, code_verifier: verifier }),
  });
  if (!res.ok) throw new Error(`pairing failed: ${res.status}`);

  const { token, scope } = await res.json(); // scope: what the user granted, see Scopes
  return token; // Step 4. Straight into the Keychain, never a plain file.
}

{ "token": "tp_…", "scope": "connections:display resources:read tools:read" }