@m-kopa/launchpad-cli 0.23.0

package/skills/marquee-share/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "marquee-share-skill",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Claude Code skill that uploads an AI-chat HTML artefact to Marquee, attributed to the real user via Cloudflare Access PKCE auth.",
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "bin": {
+    "marquee-share": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "bun build src/cli.ts --target node --outfile dist/cli.js",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests",
+    "test": "vitest run",
+    "marquee-share-dev": "tsx ./src/cli.ts"
+  },
+  "devDependencies": {
+    "@types/node": "22.18.10",
+    "@typescript-eslint/eslint-plugin": "8.46.4",
+    "@typescript-eslint/parser": "8.46.4",
+    "eslint": "9.39.4",
+    "tsx": "4.20.3",
+    "typescript": "5.9.3",
+    "vitest": "4.1.5"
+  }
+}

package/skills/marquee-share/src/auth/PROVENANCE.md

@@ -0,0 +1,103 @@
+# Vendored auth modules — provenance
+
+The files in this directory (`browser.ts`, `callback-server.ts`,
+`discovery.ts`, `flow.ts`, `jwt.ts`, `pkce.ts`, `registration.ts`,
+`session.ts`, `token.ts`) are a **vendored copy** of the OAuth /
+PKCE auth layer from the Launchpad CLI.
+
+## Why vendored, not depended-on
+
+`@m-kopa/launchpad-cli` is published as an executable binary
+(`bin: launchpad`). It has no library export surface — `package.json`
+ships only `dist/cli.js` plus skills, and exposes no `exports` map for
+the `auth/` modules. There is no supported way to `import` these
+modules as a dependency. A self-contained vendored copy is therefore
+the chosen mechanism: it is small, it has zero runtime dependencies
+(only Node built-ins), and it is auditable in-tree.
+
+## Source
+
+| Field | Value |
+|-------|-------|
+| Repo | `M-KOPA/launchpad-platform` |
+| Package | `packages/launchpad-cli` (`@m-kopa/launchpad-cli`) |
+| Package version | `0.9.0` |
+| Source commit | `951304e4a5c60be78bbec7b88493049f140236ff` |
+| Commit subject | `Enable Managed OAuth on the Marquee Access app (M-960 / M-962)` |
+| Source paths | `src/auth/*.ts`, `src/config.ts` |
+
+## Adaptations for Marquee
+
+The OAuth/PKCE protocol logic is **functionally identical** to the
+upstream — the Cloudflare Access Managed OAuth flow is the same flow
+Marquee's Access app exposes (verified by the M-960 gating spike).
+
+### Naming / config adaptations
+
+- **User-facing strings.** `launchpad` → `marquee` in error messages
+  and the callback-server "you can close this tab" HTML page.
+- **Dynamic-client-registration `client_name`.** `launchpad-cli` →
+  `marquee-share-skill`, so the registered public client is
+  identifiable in Cloudflare Access logs.
+- **Config defaults** (`config.ts`): `botUrl` → `resourceUrl`
+  defaulting to `https://marquee.launchpad.m-kopa.us`; session path
+  default `~/.marquee/session.json`; env overrides renamed
+  `LAUNCHPAD_*` → `MARQUEE_*`.
+- **`getValidAccessToken` pre-0.7.1 guard message** updated to refer
+  to `marquee login`.
+
+### Hardening divergences (M-960 CodeRabbit review)
+
+The following changes diverge from upstream behaviour. They were made
+in response to the CodeRabbit review of marquee PR #4 and **should be
+contributed back to `@m-kopa/launchpad-cli`** so the vendored copy can
+re-converge with upstream on the next re-sync.
+
+- **`browser.ts` — spawn-success detection.** Upstream resolves the
+  `openBrowser` promise from a `setImmediate` microtask. The vendored
+  copy instead resolves from the child process's `spawn` event (and
+  calls `child.unref()` inside that listener). The `spawn` event is
+  the idiomatic Node API: it fires only on a successful OS-level
+  spawn and is not emitted on failure, so the `error` listener still
+  owns rejection.
+- **`flow.ts` — bounded callback wait.** Upstream awaits
+  `server.result` with no timeout, so a never-arriving OAuth callback
+  (closed tab, blocked loopback, bad redirect) hangs the command
+  forever. The vendored copy races `server.result` against a
+  `CALLBACK_TIMEOUT_MS` (5 min) timeout that rejects with a
+  `LoginRequiredError`; the existing `finally` still closes the
+  callback server when the timeout fires.
+- **`session.ts` — `accessTokenExpiresAt` validation.** Upstream
+  type-checks `accessTokenExpiresAt` only (`typeof === "number"`),
+  which accepts `NaN`, `±Infinity`, and non-positive values — all of
+  which corrupt the silent-refresh expiry comparison. The vendored
+  copy additionally requires `Number.isFinite(...)` and a value `> 0`.
+- **`token.ts` — token-endpoint error body.** Upstream embeds up to
+  300 chars of the raw token-endpoint response body in the
+  `TokenError` message. A reflecting upstream/proxy could leak
+  secrets into a user-visible error that way. The vendored copy
+  surfaces only the HTTP status plus, when the body is well-formed
+  OAuth JSON, the standard `error` code (RFC 6749 §5.2) — never
+  free-form body text.
+
+The `resource` indicator (RFC 8707) is still derived at runtime from
+the protected-resource discovery document
+(`/.well-known/cloudflare-access-protected-resource/`) — pointing the
+flow at Marquee's base URL makes discovery yield Marquee's canonical
+resource automatically. No protocol value is hard-coded.
+
+## What was deliberately NOT vendored
+
+- JWT **signature verification** — there is none here, and there must
+  not be (see `marquee` repo `ANTI-PATTERNS.md`: "Do not implement
+  custom JWT verification"). `jwt.ts` is a payload-only decoder used
+  for display (`whoami`-style identity readout). The skill is an OAuth
+  *client*: it presents the token; Marquee's Pages Functions verify it.
+- Any client secret. This is a PKCE **public client**
+  (`token_endpoint_auth_method: "none"`). No secret is generated,
+  stored, or shipped.
+
+## Re-syncing
+
+If the upstream auth layer changes materially, re-vendor from a fresh
+commit and update the table above. Keep the adaptations list current.

package/skills/marquee-share/src/auth/browser.ts

@@ -0,0 +1,75 @@
+// Cross-platform default-browser opener.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/browser.ts — see
+// PROVENANCE.md. Marquee divergence: spawn-success detection uses the
+// child's `spawn` event rather than a `setImmediate` microtask.
+//
+// Why hand-rolled rather than the `open` npm package: keep the
+// supply-chain footprint of the shipped skill to zero runtime deps.
+// Three OSes, three commands; the table is short.
+//
+// On platforms where opening fails — typically headless CI — the
+// caller is responsible for printing the URL and instructions.
+// We surface that as a thrown `BrowserOpenError`.
+
+import { spawn } from "node:child_process";
+
+export class BrowserOpenError extends Error {
+  readonly code = "browser_open_error" as const;
+}
+
+/**
+ * Open `url` in the user's default browser. Resolves once the
+ * spawn succeeds; the OS opener is fire-and-forget after that.
+ *
+ * `platform` is injected for tests so the dispatch table is
+ * exercised without actually opening a browser. The default reads
+ * `process.platform`.
+ */
+export async function openBrowser(
+  url: string,
+  platform: NodeJS.Platform = process.platform,
+  spawner: typeof spawn = spawn,
+): Promise<void> {
+  const { command, args } = chooseOpener(platform, url);
+  return new Promise<void>((resolve, reject) => {
+    const child = spawner(command, args, {
+      stdio: "ignore",
+      detached: true,
+    });
+    child.once("error", (err) => {
+      reject(
+        new BrowserOpenError(
+          `could not open browser via ${command}: ${err.message}`,
+        ),
+      );
+    });
+    // The `spawn` event fires once the OS has successfully created
+    // the process; it is not emitted on a spawn failure (the `error`
+    // event handles that). Once spawned we don't care about the
+    // child's exit — the OS opener has already handed off the URL.
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
+
+export function chooseOpener(
+  platform: NodeJS.Platform,
+  url: string,
+): { command: string; args: string[] } {
+  switch (platform) {
+    case "darwin":
+      return { command: "open", args: [url] };
+    case "win32":
+      // `start ""` consumes the empty title arg; the URL is the
+      // real argument. We invoke through `cmd` so shell quoting is
+      // handled.
+      return { command: "cmd", args: ["/c", "start", "", url] };
+    default:
+      // Linux and other Unixes — xdg-open is the de-facto standard,
+      // installed by default on every common distribution.
+      return { command: "xdg-open", args: [url] };
+  }
+}

package/skills/marquee-share/src/auth/callback-server.ts

@@ -0,0 +1,171 @@
+// Local HTTP server that catches the OAuth redirect.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/callback-server.ts —
+// see PROVENANCE.md. Marquee adaptation: the "you can close this tab"
+// HTML page title says "marquee" instead of "launchpad".
+//
+// Lifecycle:
+//   1. `bindCallbackServer()` returns an OS-assigned free port + a
+//      Promise that resolves on the first valid
+//      `/callback?code=...&state=...` hit.
+//   2. The browser is opened to the authorization URL pointing at
+//      `http://127.0.0.1:<port>/callback`.
+//   3. After Cf Access + IdP, the browser hits our endpoint with the
+//      authorization code in the query string. We send a tiny "you
+//      can close this tab" HTML response and resolve the promise.
+//   4. The caller calls `close()` to free the port.
+//
+// Security notes:
+//   * We bind to `127.0.0.1` only — never a wildcard. A wildcard
+//     bind would expose the callback to the LAN, where another
+//     machine could potentially race the user's browser.
+//   * We require the OAuth `state` parameter to match the value the
+//     authorization URL sent. RFC 6749 §10.12 makes it the standard
+//     CSRF guard.
+//   * If a request comes in for any path other than `/callback` we
+//     return 404 and KEEP listening — opportunistic preview
+//     fetches (favicons, prefetchers) shouldn't tear down the flow.
+
+import {
+  createServer,
+  type IncomingMessage,
+  type Server,
+  type ServerResponse,
+} from "node:http";
+import type { AddressInfo } from "node:net";
+
+export interface CallbackResult {
+  readonly code: string;
+  readonly state: string;
+}
+
+export interface CallbackServer {
+  readonly port: number;
+  /** Resolves when the user's browser hits /callback with a valid
+   *  code + matching state. Rejects on `cancel()`. */
+  readonly result: Promise<CallbackResult>;
+  /** Tear down the listener. Idempotent. */
+  readonly close: () => Promise<void>;
+  /** Reject the pending `result` and close. */
+  readonly cancel: (reason: string) => Promise<void>;
+}
+
+export class CallbackError extends Error {
+  readonly code = "callback_error" as const;
+}
+
+/**
+ * Bind a fresh callback server. `expectedState` is the value the
+ * authorization URL will carry in `state`; the server rejects any
+ * request whose `state` differs.
+ */
+export async function bindCallbackServer(
+  expectedState: string,
+): Promise<CallbackServer> {
+  let resolveResult!: (r: CallbackResult) => void;
+  let rejectResult!: (e: Error) => void;
+  const result = new Promise<CallbackResult>((resolve, reject) => {
+    resolveResult = resolve;
+    rejectResult = reject;
+  });
+
+  const server: Server = createServer((req, res) => {
+    handleRequest(req, res, expectedState, resolveResult, rejectResult);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    server.once("error", reject);
+    // 127.0.0.1 + port 0 = OS picks a free loopback port.
+    server.listen(0, "127.0.0.1", () => resolve());
+  });
+
+  const addr = server.address() as AddressInfo | null;
+  if (addr === null || typeof addr === "string") {
+    server.close();
+    throw new CallbackError(`callback server: failed to bind`);
+  }
+
+  let closed = false;
+  const close = async (): Promise<void> => {
+    if (closed) return;
+    closed = true;
+    await new Promise<void>((resolve) => server.close(() => resolve()));
+  };
+  const cancel = async (reason: string): Promise<void> => {
+    rejectResult(new CallbackError(`callback server cancelled: ${reason}`));
+    await close();
+  };
+
+  return { port: addr.port, result, close, cancel };
+}
+
+function handleRequest(
+  req: IncomingMessage,
+  res: ServerResponse,
+  expectedState: string,
+  resolveResult: (r: CallbackResult) => void,
+  rejectResult: (e: Error) => void,
+): void {
+  const url = new URL(req.url ?? "/", "http://127.0.0.1");
+  if (url.pathname !== "/callback") {
+    res.statusCode = 404;
+    res.setHeader("content-type", "text/plain");
+    res.end("not found");
+    return;
+  }
+  const error = url.searchParams.get("error");
+  if (error !== null) {
+    const desc = url.searchParams.get("error_description") ?? "";
+    res.statusCode = 400;
+    res.setHeader("content-type", "text/html");
+    res.end(htmlPage(`Authentication failed: ${error}. ${desc}`));
+    rejectResult(
+      new CallbackError(
+        `authorization endpoint returned error=${error}: ${desc}`,
+      ),
+    );
+    return;
+  }
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+  if (code === null || state === null) {
+    res.statusCode = 400;
+    res.setHeader("content-type", "text/plain");
+    res.end("missing code or state");
+    // Don't reject the outer promise — a stray prefetch could land
+    // on /callback with no params; keep waiting for the real one.
+    return;
+  }
+  if (state !== expectedState) {
+    res.statusCode = 400;
+    res.setHeader("content-type", "text/plain");
+    res.end("state mismatch");
+    rejectResult(
+      new CallbackError(
+        `OAuth callback state mismatch — possible CSRF, aborting`,
+      ),
+    );
+    return;
+  }
+  res.statusCode = 200;
+  res.setHeader("content-type", "text/html");
+  res.end(htmlPage("Logged in. You can close this tab."));
+  resolveResult({ code, state });
+}
+
+function htmlPage(message: string): string {
+  // Tiny self-contained page; no external assets so the user's
+  // browser doesn't make network requests after the redirect.
+  return `<!doctype html>
+<html><head><meta charset="utf-8"><title>marquee</title>
+<style>body{font:16px/1.5 system-ui,sans-serif;padding:3rem;color:#222}h1{font-size:1.2rem;margin:0 0 1rem}</style>
+</head><body><h1>marquee</h1><p>${escapeHtml(message)}</p></body></html>`;
+}
+
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}

package/skills/marquee-share/src/auth/discovery.ts

@@ -0,0 +1,171 @@
+// OAuth discovery for Cloudflare Access Managed OAuth.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/discovery.ts — see
+// PROVENANCE.md. Unchanged from upstream: the discovery walk is
+// generic. Pointing it at Marquee's base URL is purely a config
+// concern (see config.ts) — this module bakes in no host.
+//
+// The skill doesn't bake the token / authorization endpoints in. It
+// reads them from two well-known URLs at login time:
+//
+//   1. `https://<resource>/.well-known/cloudflare-access-protected-resource/`
+//      → returns `{ authorization_servers: [<server>], resource }`
+//   2. `<server>/.well-known/oauth-authorization-server`
+//      → returns `{ authorization_endpoint, token_endpoint,
+//                   registration_endpoint, … }`
+//
+// We need three endpoints out of step 2:
+//   * `authorization_endpoint` — where the browser is sent
+//   * `token_endpoint` — code-for-token exchange + refresh
+//   * `registration_endpoint` — RFC 7591 dynamic client registration
+//
+// Plus the `resource` indicator (RFC 8707) from step 1.
+//
+// When `<resource>` is Marquee's base URL the step-1 doc is served by
+// Marquee's own Access app and yields Marquee's canonical resource
+// — no protocol value is hard-coded here.
+
+export interface OAuthEndpoints {
+  readonly authorizationEndpoint: string;
+  readonly tokenEndpoint: string;
+  readonly registrationEndpoint: string;
+  /**
+   * The protected resource's canonical URL (per RFC 8707 OAuth 2.0
+   * Resource Indicators). Cf Access REQUIRES this parameter on the
+   * authorization request — omitting it returns
+   * `error=invalid_target, error_description="No resource parameter
+   * found"`. Sourced from the protected-resource metadata's
+   * `resource` field; falls back to the configured base URL if the
+   * metadata omits it.
+   */
+  readonly resource: string;
+}
+
+export class DiscoveryError extends Error {
+  readonly code = "discovery_error" as const;
+}
+
+/**
+ * Walk the two-step discovery and return the endpoints. `resourceUrl`
+ * is the base of the protected app (no trailing slash) — for Marquee,
+ * `https://marquee.launchpad.m-kopa.us`. The fetcher is injected so
+ * tests don't need a network.
+ */
+export async function discoverOauthEndpoints(
+  resourceUrl: string,
+  fetcher: typeof fetch = fetch,
+): Promise<OAuthEndpoints> {
+  // Step 1: protected-resource metadata.
+  const wellKnownUrl = `${resourceUrl}/.well-known/cloudflare-access-protected-resource/`;
+  const resourceMeta = (await fetchJson(fetcher, wellKnownUrl)) as {
+    authorization_servers?: unknown;
+    resource?: unknown;
+  };
+  if (
+    !Array.isArray(resourceMeta.authorization_servers) ||
+    typeof resourceMeta.authorization_servers[0] !== "string"
+  ) {
+    throw new DiscoveryError(
+      `discovery: ${wellKnownUrl} returned no authorization_servers entry`,
+    );
+  }
+  // RFC 8707 resource indicator. Cf Access surfaces the protected
+  // application's URL here; we MUST forward it on the auth request
+  // (Cf rejects with `invalid_target` otherwise). Fall back to the
+  // base URL we already have when the metadata omits the field OR
+  // emits something useless (whitespace-only).
+  const rawResource =
+    typeof resourceMeta.resource === "string"
+      ? resourceMeta.resource.trim()
+      : "";
+  const resource = rawResource.length > 0 ? rawResource : resourceUrl;
+  // Defence-in-depth: refuse to walk to step 2 over HTTP. Without
+  // this check a malicious step-1 response could redirect us to a
+  // plaintext metadata endpoint and harvest the auth flow.
+  const rawServer = resourceMeta.authorization_servers[0];
+  let parsed: URL;
+  try {
+    parsed = new URL(rawServer);
+  } catch {
+    throw new DiscoveryError(
+      `${wellKnownUrl}: authorization_servers[0] is not a valid URL: ${rawServer}`,
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new DiscoveryError(
+      `${wellKnownUrl}: authorization_servers[0] is not https: ${rawServer}`,
+    );
+  }
+  const server = rawServer.replace(/\/+$/, "");
+
+  // Step 2: OAuth server metadata.
+  const serverUrl = `${server}/.well-known/oauth-authorization-server`;
+  const serverMeta = (await fetchJson(fetcher, serverUrl)) as Record<
+    string,
+    unknown
+  >;
+  const authorizationEndpoint = requireHttpsString(
+    serverMeta,
+    "authorization_endpoint",
+    serverUrl,
+  );
+  const tokenEndpoint = requireHttpsString(
+    serverMeta,
+    "token_endpoint",
+    serverUrl,
+  );
+  const registrationEndpoint = requireHttpsString(
+    serverMeta,
+    "registration_endpoint",
+    serverUrl,
+  );
+  return {
+    authorizationEndpoint,
+    tokenEndpoint,
+    registrationEndpoint,
+    resource,
+  };
+}
+
+async function fetchJson(
+  fetcher: typeof fetch,
+  url: string,
+): Promise<unknown> {
+  let res: Response;
+  try {
+    res = await fetcher(url, { method: "GET" });
+  } catch (e) {
+    throw new DiscoveryError(
+      `discovery: network error fetching ${url}: ${describe(e)}`,
+    );
+  }
+  if (!res.ok) {
+    throw new DiscoveryError(`discovery: ${url} returned HTTP ${res.status}`);
+  }
+  try {
+    return await res.json();
+  } catch (e) {
+    throw new DiscoveryError(
+      `discovery: ${url} returned non-JSON body: ${describe(e)}`,
+    );
+  }
+}
+
+function requireHttpsString(
+  obj: Record<string, unknown>,
+  key: string,
+  source: string,
+): string {
+  const v = obj[key];
+  if (typeof v !== "string") {
+    throw new DiscoveryError(`${source} missing string ${key}`);
+  }
+  if (!v.startsWith("https://")) {
+    throw new DiscoveryError(`${source} ${key} is not https: ${v}`);
+  }
+  return v;
+}
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}