@hogsend/cli 0.18.0 → 0.20.0

package/src/__tests__/loopback.test.ts

@@ -0,0 +1,159 @@
+import { createServer as createNetServer, type Server } from "node:net";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  LoopbackError,
+  type LoopbackServer,
+  startLoopbackServer,
+} from "../lib/loopback.js";
+
+/**
+ * Real node:http servers throughout — production passes LOOPBACK_PORTS, but
+ * tests inject `ports: [0]` for ephemeral binds so CI never collides.
+ */
+
+const STATE = "S";
+const loopbacks: LoopbackServer[] = [];
+const blockers: Server[] = [];
+
+afterEach(async () => {
+  for (const server of loopbacks.splice(0)) {
+    await server.close();
+  }
+  for (const server of blockers.splice(0)) {
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  }
+});
+
+async function start(ports: readonly number[] = [0], state = STATE) {
+  const server = await startLoopbackServer({ ports, state });
+  loopbacks.push(server);
+  return server;
+}
+
+/** Bind a throwaway TCP server to occupy an ephemeral port. */
+function occupyPort(): Promise<{ port: number; server: Server }> {
+  return new Promise((resolve) => {
+    const server = createNetServer();
+    server.listen({ host: "127.0.0.1", port: 0 }, () => {
+      const address = server.address();
+      const port =
+        address !== null && typeof address === "object" ? address.port : 0;
+      blockers.push(server);
+      resolve({ port, server });
+    });
+  });
+}
+
+const expectLoopbackRejection = async (
+  promise: Promise<unknown>,
+  reason: string,
+) => {
+  await expect(promise).rejects.toSatisfy((err: unknown) => {
+    expect(err).toBeInstanceOf(LoopbackError);
+    expect((err as LoopbackError).reason).toBe(reason);
+    return true;
+  });
+};
+
+describe("startLoopbackServer", () => {
+  it("happy path: success page + resolved code", async () => {
+    const server = await start();
+    const wait = server.waitForCallback();
+
+    const res = await fetch(`${server.redirectUri}?code=abc&state=${STATE}`);
+    expect(res.status).toBe(200);
+    expect(await res.text()).toContain("Connected");
+
+    await expect(wait).resolves.toEqual({ code: "abc" });
+  });
+
+  it("rejects state_mismatch with HTTP 400", async () => {
+    const server = await start();
+    // Attach the rejection handler BEFORE triggering the callback, so the
+    // rejection is never momentarily unhandled.
+    const assertion = expectLoopbackRejection(
+      server.waitForCallback(),
+      "state_mismatch",
+    );
+
+    const res = await fetch(`${server.redirectUri}?code=abc&state=WRONG`);
+    expect(res.status).toBe(400);
+
+    await assertion;
+  });
+
+  it("rejects consent_denied on error=access_denied", async () => {
+    const server = await start();
+    const assertion = expectLoopbackRejection(
+      server.waitForCallback(),
+      "consent_denied",
+    );
+
+    const res = await fetch(
+      `${server.redirectUri}?error=access_denied&state=${STATE}`,
+    );
+    expect(res.status).toBe(200);
+
+    await assertion;
+  });
+
+  it("404s wrong paths and keeps the wait pending", async () => {
+    const server = await start();
+    const wait = server.waitForCallback();
+
+    const res = await fetch(`http://127.0.0.1:${server.port}/nope`);
+    expect(res.status).toBe(404);
+
+    // Still pending: a sentinel wins the race.
+    const pending = await Promise.race([
+      wait.then(() => "settled"),
+      new Promise((resolve) => setTimeout(() => resolve("pending"), 50)),
+    ]);
+    expect(pending).toBe("pending");
+
+    // Settle it for cleanup symmetry.
+    await fetch(`${server.redirectUri}?code=abc&state=${STATE}`);
+    await expect(wait).resolves.toEqual({ code: "abc" });
+  });
+
+  it("falls back to the next port when the first is busy", async () => {
+    const { port } = await occupyPort();
+    const server = await start([port, 0]);
+    expect(server.port).not.toBe(port);
+    expect(server.port).toBeGreaterThan(0);
+  });
+
+  it("rejects ports_busy listing the ports when all are taken", async () => {
+    const { port } = await occupyPort();
+    await expect(
+      startLoopbackServer({ ports: [port], state: STATE }),
+    ).rejects.toSatisfy((err: unknown) => {
+      expect(err).toBeInstanceOf(LoopbackError);
+      expect((err as LoopbackError).reason).toBe("ports_busy");
+      expect((err as LoopbackError).message).toContain(String(port));
+      return true;
+    });
+  });
+
+  it("times out when no callback arrives", async () => {
+    const server = await start();
+    await expectLoopbackRejection(
+      server.waitForCallback({ timeoutMs: 20 }),
+      "timeout",
+    );
+  });
+
+  it("first answer wins — later requests get a 410", async () => {
+    const server = await start();
+    const wait = server.waitForCallback();
+
+    const first = await fetch(`${server.redirectUri}?code=abc&state=${STATE}`);
+    expect(first.status).toBe(200);
+    await expect(wait).resolves.toEqual({ code: "abc" });
+
+    const second = await fetch(
+      `${server.redirectUri}?code=later&state=${STATE}`,
+    );
+    expect(second.status).toBe(410);
+  });
+});

package/src/__tests__/oauth.test.ts

@@ -0,0 +1,230 @@
+import { describe, expect, it } from "vitest";
+import {
+  buildAuthorizeUrl,
+  computeChallenge,
+  discoverOAuthServer,
+  exchangeCode,
+  generatePkce,
+  generateState,
+  POSTHOG_CLIENT_ID,
+  POSTHOG_SCOPES,
+} from "../lib/oauth.js";
+
+const BASE64URL_RE = /^[A-Za-z0-9_-]+$/;
+
+/** Minimal recording fetch fake (mirrors hatchet-token.test.ts's pattern). */
+function fakeFetch(
+  respond: (url: string, init?: RequestInit) => Response | Promise<Response>,
+): { fetchImpl: typeof fetch; calls: { url: string; init?: RequestInit }[] } {
+  const calls: { url: string; init?: RequestInit }[] = [];
+  const fetchImpl = (async (input: unknown, init?: RequestInit) => {
+    const url = String(input);
+    calls.push({ url, init });
+    return respond(url, init);
+  }) as typeof fetch;
+  return { fetchImpl, calls };
+}
+
+const json = (body: unknown, status = 200) =>
+  new Response(JSON.stringify(body), {
+    status,
+    headers: { "content-type": "application/json" },
+  });
+
+describe("computeChallenge", () => {
+  it("matches the RFC 7636 appendix B vector", () => {
+    expect(
+      computeChallenge("dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk"),
+    ).toBe("E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM");
+  });
+});
+
+describe("generatePkce", () => {
+  it("emits a 43-char base64url verifier with a matching S256 challenge", () => {
+    const pkce = generatePkce();
+    expect(pkce.verifier).toHaveLength(43);
+    expect(pkce.verifier).toMatch(BASE64URL_RE);
+    expect(pkce.verifier).not.toContain("=");
+    expect(pkce.challenge).toBe(computeChallenge(pkce.verifier));
+    expect(pkce.method).toBe("S256");
+  });
+
+  it("two calls differ", () => {
+    expect(generatePkce().verifier).not.toBe(generatePkce().verifier);
+  });
+});
+
+describe("generateState", () => {
+  it("is unique and base64url across 100 calls", () => {
+    const states = Array.from({ length: 100 }, () => generateState());
+    expect(new Set(states).size).toBe(100);
+    for (const state of states) {
+      expect(state).toMatch(BASE64URL_RE);
+    }
+  });
+});
+
+describe("buildAuthorizeUrl", () => {
+  const base = {
+    authorizationEndpoint: "https://eu.posthog.com/oauth/authorize/",
+    clientId: POSTHOG_CLIENT_ID,
+    redirectUri: "http://127.0.0.1:8423/callback",
+    scope: POSTHOG_SCOPES,
+    state: "st4te",
+    pkce: {
+      verifier: "v".repeat(43),
+      challenge: "ch4llenge",
+      method: "S256" as const,
+    },
+  };
+
+  it("sets every OAuth param and never a client_secret", () => {
+    const url = new URL(
+      buildAuthorizeUrl({ ...base, requiredAccessLevel: "team" }),
+    );
+    expect(url.origin + url.pathname).toBe(
+      "https://eu.posthog.com/oauth/authorize/",
+    );
+    expect(url.searchParams.get("response_type")).toBe("code");
+    expect(url.searchParams.get("client_id")).toBe(POSTHOG_CLIENT_ID);
+    expect(url.searchParams.get("redirect_uri")).toBe(base.redirectUri);
+    expect(url.searchParams.get("scope")).toBe(POSTHOG_SCOPES);
+    expect(url.searchParams.get("state")).toBe("st4te");
+    expect(url.searchParams.get("code_challenge")).toBe("ch4llenge");
+    expect(url.searchParams.get("code_challenge_method")).toBe("S256");
+    expect(url.searchParams.get("required_access_level")).toBe("team");
+    expect(url.searchParams.has("client_secret")).toBe(false);
+  });
+
+  it("omits required_access_level when not provided", () => {
+    const url = new URL(buildAuthorizeUrl(base));
+    expect(url.searchParams.has("required_access_level")).toBe(false);
+  });
+});
+
+describe("discoverOAuthServer", () => {
+  const DOC = {
+    issuer: "https://eu.posthog.com",
+    authorization_endpoint: "https://eu.posthog.com/oauth/authorize/",
+    token_endpoint: "https://eu.posthog.com/oauth/token/",
+  };
+
+  it("requests the RFC 8414 well-known path and returns ok metadata", async () => {
+    const { fetchImpl, calls } = fakeFetch(() => json(DOC));
+    const result = await discoverOAuthServer({
+      privateHost: "https://eu.posthog.com",
+      fetchImpl,
+    });
+    expect(calls[0]?.url).toBe(
+      "https://eu.posthog.com/.well-known/oauth-authorization-server",
+    );
+    expect(result).toEqual({ status: "ok", metadata: DOC });
+  });
+
+  it("maps 404 and 410 to unsupported", async () => {
+    for (const status of [404, 410]) {
+      const { fetchImpl } = fakeFetch(() => new Response("nope", { status }));
+      const result = await discoverOAuthServer({
+        privateHost: "https://ph.selfhosted.example",
+        fetchImpl,
+      });
+      expect(result).toEqual({ status: "unsupported" });
+    }
+  });
+
+  it("flags a 200 missing token_endpoint as malformed", async () => {
+    const { fetchImpl } = fakeFetch(() =>
+      json({
+        issuer: DOC.issuer,
+        authorization_endpoint: DOC.authorization_endpoint,
+      }),
+    );
+    const result = await discoverOAuthServer({
+      privateHost: "https://eu.posthog.com",
+      fetchImpl,
+    });
+    expect(result.status).toBe("error");
+    if (result.status === "error") {
+      expect(result.message).toContain("malformed");
+    }
+  });
+
+  it("never throws on transport failure", async () => {
+    const fetchImpl = (async () => {
+      throw new Error("getaddrinfo ENOTFOUND");
+    }) as unknown as typeof fetch;
+    const result = await discoverOAuthServer({
+      privateHost: "https://eu.posthog.com",
+      fetchImpl,
+    });
+    expect(result.status).toBe("error");
+    if (result.status === "error") {
+      expect(result.message).toContain("ENOTFOUND");
+    }
+  });
+});
+
+describe("exchangeCode", () => {
+  const OPTS = {
+    tokenEndpoint: "https://eu.posthog.com/oauth/token/",
+    clientId: POSTHOG_CLIENT_ID,
+    code: "auth-code-abc",
+    codeVerifier: "verifier-xyz",
+    redirectUri: "http://127.0.0.1:8423/callback",
+  };
+  const TOKENS = {
+    access_token: "pha_fixture",
+    refresh_token: "phr_fixture",
+    token_type: "Bearer",
+    expires_in: 36_000,
+    scope: POSTHOG_SCOPES,
+    scoped_teams: [123],
+    scoped_organizations: [],
+  };
+
+  it("POSTs exactly the five form params with no client_secret / auth header", async () => {
+    const { fetchImpl, calls } = fakeFetch(() => json(TOKENS));
+    const result = await exchangeCode({ ...OPTS, fetchImpl });
+
+    const call = calls[0];
+    expect(call?.init?.method).toBe("POST");
+    const headers = call?.init?.headers as Record<string, string>;
+    expect(headers.Authorization).toBeUndefined();
+
+    const body = new URLSearchParams(String(call?.init?.body));
+    expect(Object.fromEntries(body.entries())).toEqual({
+      grant_type: "authorization_code",
+      code: "auth-code-abc",
+      redirect_uri: OPTS.redirectUri,
+      client_id: POSTHOG_CLIENT_ID,
+      code_verifier: "verifier-xyz",
+    });
+    expect(body.has("client_secret")).toBe(false);
+
+    expect(result).toEqual(TOKENS);
+  });
+
+  it("throws with the status (never the code/verifier) on a 400", async () => {
+    const { fetchImpl } = fakeFetch(() =>
+      json({ error: "invalid_grant" }, 400),
+    );
+    await expect(exchangeCode({ ...OPTS, fetchImpl })).rejects.toSatisfy(
+      (err: unknown) => {
+        const message = (err as Error).message;
+        expect(message).toContain("400");
+        expect(message).toContain("invalid_grant");
+        expect(message).not.toContain("auth-code-abc");
+        expect(message).not.toContain("verifier-xyz");
+        return true;
+      },
+    );
+  });
+
+  it("throws when a 200 omits refresh_token", async () => {
+    const { refresh_token: _omitted, ...withoutRefresh } = TOKENS;
+    const { fetchImpl } = fakeFetch(() => json(withoutRefresh));
+    await expect(exchangeCode({ ...OPTS, fetchImpl })).rejects.toThrow(
+      /missing refresh_token/,
+    );
+  });
+});

package/src/commands/connect.ts

@@ -0,0 +1,149 @@
+import { parseArgs } from "node:util";
+import { confirm } from "@clack/prompts";
+import { openBrowser } from "../lib/browser.js";
+import {
+  ConnectError,
+  type ConnectFlowDeps,
+  runConnectPosthog,
+} from "../lib/connect-flow.js";
+import { startLoopbackServer } from "../lib/loopback.js";
+import { discoverOAuthServer, exchangeCode } from "../lib/oauth.js";
+import { color } from "../lib/output.js";
+import { bail } from "../lib/prompt.js";
+import type { Command, CommandContext } from "./types.js";
+
+const usage = `hogsend connect <provider> [--provision-only] [--no-provision] [--no-browser] [--json]
+
+Connect this Hogsend instance to an analytics provider via OAuth. Providers:
+
+  posthog    Authorize Hogsend against your PostHog region (PKCE, loopback
+             callback on 127.0.0.1), store the refresh token on the instance,
+             then provision the PostHog -> Hogsend event loop (a PostHog
+             destination posting to /v1/webhooks/posthog).
+
+The browser consent must happen on THIS machine (the OAuth callback lands on
+127.0.0.1). The target instance can be anywhere — point --url at it and run
+this command from your laptop, not from an SSH session on the server.
+
+Options:
+  --provision-only   Skip OAuth; (re-)provision the event loop using the
+                     already-stored credential.
+  --no-provision     Stop after storing the credential.
+  --no-browser       Don't spawn a browser; just print the authorize URL.
+  --url, --admin-key, --json, -h, --help   Global flags as usual.
+
+Exit code: 0 when a credential is stored (even if provisioning was skipped),
+1 otherwise.`;
+
+async function run(ctx: CommandContext): Promise<void> {
+  const { values, positionals } = parseArgs({
+    args: ctx.argv,
+    allowPositionals: true,
+    strict: false,
+    options: {
+      "provision-only": { type: "boolean", default: false },
+      "no-provision": { type: "boolean", default: false },
+      "no-browser": { type: "boolean", default: false },
+      help: { type: "boolean", short: "h", default: false },
+    },
+  });
+
+  if (values.help) {
+    ctx.out.log(usage);
+    return;
+  }
+
+  const provider = positionals[0];
+  if (!provider) {
+    ctx.out.fail("missing provider — try: hogsend connect posthog");
+  }
+  if (provider !== "posthog") {
+    ctx.out.fail(`unknown provider "${provider}" — supported: posthog`);
+  }
+
+  if (values["provision-only"] && values["no-provision"]) {
+    ctx.out.fail("--provision-only and --no-provision are mutually exclusive");
+  }
+
+  // The PUT carries the OAuth tokens — warn when they'd ride plain http to a
+  // non-local instance.
+  try {
+    const target = new URL(ctx.cfg.baseUrl);
+    if (
+      target.protocol === "http:" &&
+      target.hostname !== "localhost" &&
+      target.hostname !== "127.0.0.1"
+    ) {
+      ctx.out.log(
+        color.yellow(
+          `warning: ${ctx.cfg.baseUrl} is plain http — OAuth tokens will ` +
+            "be sent to it unencrypted; use https for remote instances.",
+        ),
+      );
+    }
+  } catch {
+    // unparseable base URL — the HTTP client will surface it
+  }
+
+  ctx.out.intro(`${color.bgMagenta(color.black(" hogsend "))} connect`);
+
+  const deps: ConnectFlowDeps = {
+    http: ctx.http,
+    out: ctx.out,
+    interactive: ctx.out.interactive,
+    discover: discoverOAuthServer,
+    startLoopback: startLoopbackServer,
+    exchangeCode,
+    openBrowser,
+    confirm: async (message) => bail(await confirm({ message })),
+    now: () => new Date(),
+  };
+
+  try {
+    const result = await runConnectPosthog(deps, {
+      provisionOnly: Boolean(values["provision-only"]),
+      noProvision: Boolean(values["no-provision"]),
+      noBrowser: Boolean(values["no-browser"]),
+    });
+
+    if (ctx.json) {
+      // One document; ConnectResult carries no token material by invariant.
+      ctx.out.json({ ok: true, ...result });
+      return;
+    }
+    ctx.out.outro(
+      color.green(
+        `connect: posthog ${
+          result.verdict === "connected"
+            ? "connected"
+            : "connected (loop not provisioned)"
+        }`,
+      ),
+    );
+  } catch (error) {
+    if (error instanceof ConnectError) {
+      if (ctx.json) {
+        ctx.out.json({
+          ok: false,
+          verdict: error.verdict,
+          error: error.message,
+          hint: error.hint,
+        });
+        process.exit(1);
+      }
+      ctx.out.note(
+        error.hint ? `${error.message}\n\n${error.hint}` : error.message,
+      );
+      ctx.out.outro(color.red(`connect: ${error.verdict}`));
+      process.exit(1);
+    }
+    throw error; // router renders unexpected errors
+  }
+}
+
+export const connectCommand: Command = {
+  name: "connect",
+  summary: "Connect an analytics provider via OAuth (posthog)",
+  usage,
+  run,
+};

package/src/commands/doctor.ts

@@ -1,4 +1,5 @@
 import { parseArgs } from "node:util";
+import { loadDotEnv } from "../lib/config.js";
 import { isHttpError } from "../lib/http.js";
 import { color } from "../lib/output.js";
 import { skillsStaleness } from "../lib/skills.js";
@@ -22,6 +23,34 @@ function skillsNudge(ctx: CommandContext): void {
   );
 }
 
+/**
+ * Best-effort nudge: PostHog capture configured (`POSTHOG_API_KEY` in the
+ * cwd's `.env` or process env) without `POSTHOG_PERSONAL_API_KEY` means
+ * person READS are silently disabled — the phc_ project key is write-only by
+ * PostHog's design, so timezone resolution falls back to contact properties.
+ * Warn-not-fail: capture and person writes still work.
+ */
+function analyticsNudge(ctx: CommandContext): void {
+  if (ctx.json) return;
+  const dotenv = loadDotEnv(process.cwd());
+  const captureKey = process.env.POSTHOG_API_KEY ?? dotenv.POSTHOG_API_KEY;
+  const personalKey =
+    process.env.POSTHOG_PERSONAL_API_KEY ?? dotenv.POSTHOG_PERSONAL_API_KEY;
+  if (!captureKey || personalKey) return;
+  ctx.out.note(
+    [
+      "POSTHOG_API_KEY is set without POSTHOG_PERSONAL_API_KEY — person",
+      "property READS are disabled (the phc_ project key is write-only by",
+      "PostHog's design), so per-user timezone resolution falls back to",
+      "contact properties. Capture and person WRITES are unaffected.",
+      "",
+      `Fix: create a personal API key scoped ${color.cyan("person:read")} and set ${color.cyan("POSTHOG_PERSONAL_API_KEY")}.`,
+      `Docs: ${color.cyan("https://hogsend.com/docs/guides/analytics-access")}`,
+    ].join("\n"),
+    "PostHog person reads disabled",
+  );
+}
+
 const usage = `hogsend doctor [--url <baseUrl>] [--admin-key <key>] [--json]
 
 Probe a running Hogsend instance via GET /v1/health and report its health:
@@ -221,6 +250,7 @@ async function run(ctx: CommandContext): Promise<void> {
   ctx.out.note(lines.join("\n"), "Doctor");
 
   skillsNudge(ctx);
+  analyticsNudge(ctx);
 
   if (ok) {
     ctx.out.outro(color.green("doctor: ok"));

package/src/commands/index.ts

@@ -1,4 +1,5 @@
 import { campaignsCommand } from "./campaigns.js";
+import { connectCommand } from "./connect.js";
 import { contactsCommand } from "./contacts.js";
 import { devCommand } from "./dev.js";
 import { doctorCommand } from "./doctor.js";
@@ -35,6 +36,7 @@ export const commands: Command[] = [
   campaignsCommand,
   webhooksCommand,
   domainCommand,
+  connectCommand,
   hatchetCommand,
   studioCommand,
   devCommand,

package/src/commands/studio.ts

@@ -1,9 +1,9 @@
-import { spawn } from "node:child_process";
 import { createReadStream, existsSync, readFileSync, statSync } from "node:fs";
 import { createServer } from "node:http";
 import { extname, join, normalize, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
+import { openBrowser } from "../lib/browser.js";
 import { color } from "../lib/output.js";
 import { runStudioAdmin } from "./studio-admin.js";
 import type { Command, CommandContext } from "./types.js";
@@ -115,21 +115,6 @@ function indexHtml(distPath: string, baseUrl: string | undefined): string {
   return `${inject}${raw}`;
 }
 
-/** Open a URL in the OS default browser (best-effort, never throws). */
-function openBrowser(url: string): void {
-  const platform = process.platform;
-  const cmd =
-    platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
-  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
-  try {
-    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
-    child.on("error", () => {});
-    child.unref();
-  } catch {
-    // best-effort
-  }
-}
-
 async function run(ctx: CommandContext): Promise<void> {
   // Subcommand dispatch: `hogsend studio admin <create|reset|list> ...`.
   // Route before the static-server flag parsing so the admin flags are owned

package/src/lib/browser.ts

@@ -0,0 +1,17 @@
+import { spawn } from "node:child_process";
+
+/** Open a URL in the OS default browser. Best-effort: returns false instead of throwing. */
+export function openBrowser(url: string): boolean {
+  const platform = process.platform;
+  const cmd =
+    platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  try {
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}