@m-kopa/launchpad-cli 0.23.0

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

@@ -0,0 +1,262 @@
+// Orchestration: putting discovery + registration + PKCE +
+// callback server + browser open + token exchange together into
+// a single "log the user in" function.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/flow.ts — see
+// PROVENANCE.md. Marquee adaptations:
+//   * `botUrl` → `resourceUrl` (the option that names the protected
+//     app — for Marquee, `https://marquee.launchpad.m-kopa.us`).
+//   * `CliSession` → `MarqueeSession`.
+//   * User-facing error strings say `marquee login`.
+//   * The callback wait is bounded by `CALLBACK_TIMEOUT_MS` so a
+//     never-arriving callback can't hang the command forever.
+// The state-machine logic itself is otherwise unchanged.
+//
+// Also: `getValidAccessToken` — the symmetric read path the upload
+// task (a later task) will go through. Returns the current
+// `accessToken` if it's still valid, otherwise silently refreshes
+// using the `refreshToken`. If the refresh fails (grant session
+// expired, token revoked, etc.) the caller gets a typed
+// `LoginRequiredError`.
+//
+// The login flow is a state machine in narrative form:
+//
+//   1. discoverOauthEndpoints(resourceUrl) — two GETs of well-known
+//      metadata.
+//   2. bindCallbackServer(state) — pick a free localhost port.
+//   3. registerClient(registrationEndpoint, redirectUri) — get a
+//      `client_id` for this loopback URI (public client, no secret).
+//   4. generatePkcePair() — verifier + challenge with the
+//      Cloudflare-quirk regen.
+//   5. openBrowser(authUrl) — kick the user into Cf Access.
+//   6. server.result — wait for /callback?code=...
+//   7. exchangeCodeForTokens(...) — code → access + refresh.
+//   8. writeSession(...) — persist with mode 0600.
+//   9. server.close().
+//
+// The whole thing is wrapped in a try/finally that always closes
+// the server, even on cancellation or thrown errors.
+
+import { randomBytes } from "node:crypto";
+import { bindCallbackServer } from "./callback-server.js";
+import { discoverOauthEndpoints } from "./discovery.js";
+import { generatePkcePair } from "./pkce.js";
+import { registerClient } from "./registration.js";
+import { exchangeCodeForTokens, refreshTokens, TokenError } from "./token.js";
+import {
+  readSession,
+  writeSession,
+  type MarqueeSession,
+  SESSION_VERSION,
+} from "./session.js";
+import { openBrowser } from "./browser.js";
+
+export class LoginRequiredError extends Error {
+  readonly code = "login_required" as const;
+}
+
+/** Refresh-window buffer: refresh `REFRESH_SKEW_MS` before expiry
+ *  so a request fired right at the edge doesn't hit a 401. */
+export const REFRESH_SKEW_MS = 30_000;
+
+/** Upper bound on how long `login` waits for the browser to round-trip
+ *  back to the localhost callback. Without it a closed tab, a blocked
+ *  loopback, or a bad redirect hangs `marquee login` indefinitely. */
+export const CALLBACK_TIMEOUT_MS = 5 * 60_000;
+
+export interface LoginOptions {
+  /** Base URL of the protected app — for Marquee,
+   *  `https://marquee.launchpad.m-kopa.us`. Discovery walks the
+   *  well-known docs under this host. */
+  readonly resourceUrl: string;
+  readonly sessionPath: string;
+  /** Receives the auth URL once the localhost server is bound +
+   *  the browser opener is about to fire. The caller prints it to
+   *  stdout so a headless dev can copy-paste. */
+  readonly onAuthUrl?: (url: string) => void;
+  /** Injection points for tests. */
+  readonly fetcher?: typeof fetch;
+  readonly browserOpener?: (url: string) => Promise<void>;
+}
+
+/**
+ * Run the full PKCE flow and persist the session. Returns the
+ * resulting session for the caller (so it can print confirmation
+ * diagnostics — never the token itself).
+ */
+export async function login(opts: LoginOptions): Promise<MarqueeSession> {
+  const fetcher = opts.fetcher ?? fetch;
+  const opener = opts.browserOpener ?? ((url: string) => openBrowser(url));
+
+  const endpoints = await discoverOauthEndpoints(opts.resourceUrl, fetcher);
+  const state = randomBytes(16).toString("hex");
+  const server = await bindCallbackServer(state);
+  try {
+    const redirectUri = `http://127.0.0.1:${server.port}/callback`;
+    const reg = await registerClient(
+      endpoints.registrationEndpoint,
+      redirectUri,
+      fetcher,
+    );
+    const pkce = generatePkcePair();
+    const authUrl = buildAuthorizationUrl({
+      authorizationEndpoint: endpoints.authorizationEndpoint,
+      clientId: reg.clientId,
+      redirectUri,
+      challenge: pkce.challenge,
+      state,
+      resource: endpoints.resource,
+    });
+    opts.onAuthUrl?.(authUrl);
+    // Opener failure (no `xdg-open` on a headless box, etc.) must NOT
+    // tear down the flow — `onAuthUrl` already printed the URL for
+    // the user to copy-paste. Log the error to the onAuthUrl sink so
+    // the caller sees something, then keep waiting on the callback.
+    try {
+      await opener(authUrl);
+    } catch (e) {
+      opts.onAuthUrl?.(
+        `(could not auto-open browser: ${describe(e)} — copy the URL above into a browser instead)`,
+      );
+    }
+    // Bound the callback wait — the `finally` below still closes the
+    // server when the timeout fires, so no listener / port leaks.
+    let callbackTimer: ReturnType<typeof setTimeout> | undefined;
+    const callback = await Promise.race([
+      server.result,
+      new Promise<never>((_, reject) => {
+        callbackTimer = setTimeout(
+          () =>
+            reject(
+              new LoginRequiredError(
+                "timed out waiting for the browser callback — run `marquee login` again",
+              ),
+            ),
+          CALLBACK_TIMEOUT_MS,
+        );
+      }),
+    ]).finally(() => {
+      if (callbackTimer !== undefined) clearTimeout(callbackTimer);
+    });
+    const tokens = await exchangeCodeForTokens(
+      {
+        tokenEndpoint: endpoints.tokenEndpoint,
+        clientId: reg.clientId,
+        code: callback.code,
+        codeVerifier: pkce.verifier,
+        redirectUri,
+        resource: endpoints.resource,
+      },
+      fetcher,
+    );
+    const session: MarqueeSession = {
+      version: SESSION_VERSION,
+      accessToken: tokens.accessToken,
+      refreshToken: tokens.refreshToken,
+      accessTokenExpiresAt: Date.now() + tokens.expiresInSec * 1000,
+      clientId: reg.clientId,
+      tokenEndpoint: endpoints.tokenEndpoint,
+      resource: endpoints.resource,
+      issuedAt: new Date().toISOString(),
+    };
+    await writeSession(opts.sessionPath, session);
+    return session;
+  } finally {
+    await server.close();
+  }
+}
+
+/**
+ * Read the session and return a still-valid access token. If the
+ * persisted access token is past (or near) expiry, silently
+ * refresh and persist the new pair before returning. If the
+ * refresh fails because the grant has expired, throws
+ * `LoginRequiredError`.
+ *
+ * `now` is injected for tests so we can simulate expiry without
+ * mocking the system clock.
+ */
+export async function getValidAccessToken(
+  sessionPath: string,
+  fetcher: typeof fetch = fetch,
+  now: () => number = Date.now,
+): Promise<{ accessToken: string; session: MarqueeSession }> {
+  const session = await readSession(sessionPath);
+  if (session === null) {
+    throw new LoginRequiredError("no session — run `marquee login`");
+  }
+  if (session.accessTokenExpiresAt - REFRESH_SKEW_MS > now()) {
+    return { accessToken: session.accessToken, session };
+  }
+  // Expired (or close to it). Try silent refresh.
+  //
+  // A session written without `resource` cannot be refreshed (Cf
+  // Access would fail the `invalid_target` check). Force the user
+  // back through `marquee login` rather than send a doomed request.
+  if (session.resource === undefined) {
+    throw new LoginRequiredError(
+      "session is missing the resource indicator — run `marquee login`",
+    );
+  }
+  let next;
+  try {
+    next = await refreshTokens(
+      {
+        tokenEndpoint: session.tokenEndpoint,
+        clientId: session.clientId,
+        refreshToken: session.refreshToken,
+        resource: session.resource,
+      },
+      fetcher,
+    );
+  } catch (e) {
+    if (
+      e instanceof TokenError &&
+      e.httpStatus !== undefined &&
+      e.httpStatus >= 400 &&
+      e.httpStatus < 500
+    ) {
+      // 4xx on refresh = grant rejected by the server. The user
+      // must re-auth via browser; nothing the skill can do silently.
+      throw new LoginRequiredError(
+        `session expired — run \`marquee login\` (token endpoint said: ${e.message})`,
+      );
+    }
+    throw e;
+  }
+  const refreshed: MarqueeSession = {
+    ...session,
+    accessToken: next.accessToken,
+    refreshToken: next.refreshToken,
+    accessTokenExpiresAt: now() + next.expiresInSec * 1000,
+    issuedAt: new Date(now()).toISOString(),
+  };
+  await writeSession(sessionPath, refreshed);
+  return { accessToken: refreshed.accessToken, session: refreshed };
+}
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}
+
+function buildAuthorizationUrl(params: {
+  readonly authorizationEndpoint: string;
+  readonly clientId: string;
+  readonly redirectUri: string;
+  readonly challenge: string;
+  readonly state: string;
+  readonly resource: string;
+}): string {
+  const u = new URL(params.authorizationEndpoint);
+  u.searchParams.set("client_id", params.clientId);
+  u.searchParams.set("redirect_uri", params.redirectUri);
+  u.searchParams.set("response_type", "code");
+  u.searchParams.set("code_challenge", params.challenge);
+  u.searchParams.set("code_challenge_method", "S256");
+  u.searchParams.set("state", params.state);
+  // RFC 8707 — Cf Access requires this on the auth request
+  // (`invalid_target` otherwise). The resulting access_token's `aud`
+  // is bound to this value; Marquee's JWT validation expects a match.
+  u.searchParams.set("resource", params.resource);
+  return u.toString();
+}

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

@@ -0,0 +1,171 @@
+// Public auth surface for the Marquee share skill.
+//
+// This is the ONLY module later tasks (HTML render, upload) should
+// import from. It wraps the vendored OAuth/PKCE machinery (see
+// PROVENANCE.md) with Marquee config loading and exposes three
+// operations:
+//
+//   * `login`         — one-time browser PKCE login; persists a
+//                       session at `~/.marquee/session.json` (0600).
+//   * `logout`        — clears the cached session.
+//   * `getValidToken` — returns a still-valid access token, silently
+//                       reusing a cached session while valid and
+//                       refreshing on expiry. If the refresh grant
+//                       has also expired it runs a fresh browser
+//                       login (when `interactive` is allowed) so the
+//                       upload task gets a token without the caller
+//                       orchestrating the re-auth.
+//
+// SECURITY POSTURE
+//   * The access + refresh tokens are NEVER returned to stdout, never
+//     logged, and never passed to a logging sink. `getValidToken`
+//     returns the token string to its in-process caller only; the
+//     caller (the upload task) puts it in an `Authorization` header.
+//   * PKCE public client — no client secret is generated, received,
+//     or stored anywhere in this skill.
+//   * JWT signatures are NOT verified here. The skill is an OAuth
+//     client; Marquee's Pages Functions verify. `whoami`-style
+//     identity readout uses the payload-only decoder in `jwt.ts`.
+
+import { loadConfig, type SkillConfig } from "../config.js";
+import { login as runLoginFlow, getValidAccessToken } from "./flow.js";
+import { LoginRequiredError } from "./flow.js";
+import { clearSession, type MarqueeSession } from "./session.js";
+
+export { LoginRequiredError } from "./flow.js";
+export type { MarqueeSession } from "./session.js";
+export type { SkillConfig } from "../config.js";
+
+/** A logging sink restricted to non-secret diagnostics. The auth
+ *  layer only ever passes auth URLs and human-readable status here —
+ *  never a token. Defaults to `console.error` (stderr). */
+export type DiagnosticSink = (line: string) => void;
+
+export interface AuthOptions {
+  /** Override the resolved config (resourceUrl + sessionPath).
+   *  Defaults to `loadConfig()` which reads `MARQUEE_*` env vars. */
+  readonly config?: SkillConfig;
+  /** Non-secret diagnostic sink. Defaults to stderr. NEVER receives
+   *  a token. */
+  readonly onDiagnostic?: DiagnosticSink;
+  /** Injected for tests. */
+  readonly fetcher?: typeof fetch;
+  readonly browserOpener?: (url: string) => Promise<void>;
+  /** Injected for tests — the clock `getValidToken` uses to decide
+   *  whether the cached token is still fresh. */
+  readonly now?: () => number;
+}
+
+function resolveConfig(opts: AuthOptions): SkillConfig {
+  return opts.config ?? loadConfig();
+}
+
+function diag(opts: AuthOptions, line: string): void {
+  (opts.onDiagnostic ?? ((l: string) => console.error(l)))(line);
+}
+
+/**
+ * One-time interactive login. Opens the browser to Cloudflare Access,
+ * completes the PKCE exchange, and persists the session.
+ *
+ * Returns the session for diagnostics. The caller MUST NOT print
+ * `session.accessToken` / `session.refreshToken`.
+ */
+export async function login(
+  opts: AuthOptions = {},
+): Promise<MarqueeSession> {
+  const cfg = resolveConfig(opts);
+  diag(opts, "Opening browser to authenticate with Cloudflare Access…");
+  diag(opts, "(if it doesn't open automatically, copy the URL below)");
+  const session = await runLoginFlow({
+    resourceUrl: cfg.resourceUrl,
+    sessionPath: cfg.sessionPath,
+    onAuthUrl: (url) => diag(opts, url),
+    ...(opts.fetcher !== undefined ? { fetcher: opts.fetcher } : {}),
+    ...(opts.browserOpener !== undefined
+      ? { browserOpener: opts.browserOpener }
+      : {}),
+  });
+  diag(opts, `Logged in. Session stored at ${cfg.sessionPath}`);
+  return session;
+}
+
+/**
+ * Clear the persisted session. Idempotent — returns `true` if a
+ * session existed and was removed, `false` if there was nothing to
+ * clear.
+ */
+export async function logout(opts: AuthOptions = {}): Promise<boolean> {
+  const cfg = resolveConfig(opts);
+  const had = await clearSession(cfg.sessionPath);
+  diag(
+    opts,
+    had
+      ? `Logged out. Session cleared at ${cfg.sessionPath}`
+      : "Already logged out.",
+  );
+  return had;
+}
+
+export interface GetTokenOptions extends AuthOptions {
+  /**
+   * Whether `getValidToken` may fall back to an interactive browser
+   * login when there is no session, or when the refresh grant has
+   * expired. Defaults to `true` — the skill runs on a developer's
+   * machine and the whole point is a frictionless token. Set to
+   * `false` in non-interactive contexts (CI, tests) to get a thrown
+   * `LoginRequiredError` instead of a hung browser open.
+   */
+  readonly interactive?: boolean;
+}
+
+/**
+ * Return a still-valid Marquee access token.
+ *
+ * Resolution order:
+ *   1. Cached session present and the access token is comfortably
+ *      within its lifetime → return it directly (no network).
+ *   2. Cached session present but the access token is expired (or
+ *      within the refresh-skew window) → silently refresh via the
+ *      refresh token, persist the new pair, return the fresh token.
+ *   3. No session, or the refresh grant itself has expired → if
+ *      `interactive` (default), run a fresh browser PKCE login and
+ *      return the resulting token; otherwise throw
+ *      `LoginRequiredError`.
+ *
+ * The returned string is a bearer token. The caller is responsible
+ * for transmitting it ONLY in an `Authorization` header to Marquee
+ * over HTTPS, and for never logging it.
+ */
+export async function getValidToken(
+  opts: GetTokenOptions = {},
+): Promise<string> {
+  const cfg = resolveConfig(opts);
+  const interactive = opts.interactive ?? true;
+  const fetcher = opts.fetcher ?? fetch;
+  const now = opts.now ?? Date.now;
+  try {
+    const { accessToken } = await getValidAccessToken(
+      cfg.sessionPath,
+      fetcher,
+      now,
+    );
+    return accessToken;
+  } catch (e) {
+    if (e instanceof LoginRequiredError) {
+      if (!interactive) {
+        // Re-throw so a non-interactive caller (CI, tests) gets a
+        // typed signal instead of an unexpected browser launch.
+        throw e;
+      }
+      // No usable session — fall back to a fresh interactive login.
+      diag(
+        opts,
+        "No valid Marquee session — starting a browser login…",
+      );
+      const session = await login(opts);
+      return session.accessToken;
+    }
+    throw e;
+  }
+}

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

@@ -0,0 +1,77 @@
+// Tiny payload-only JWT decoder used for identity display.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/jwt.ts — see
+// PROVENANCE.md. Unchanged from upstream.
+//
+// We are NOT validating the signature. The token came back from
+// Cloudflare's OAuth token endpoint over HTTPS; we trust its content
+// for *display* purposes only (e.g. showing "logged in as <email>").
+//
+// Marquee's Pages Functions are the authority for actual authz — the
+// skill is a client. The marquee repo's ANTI-PATTERNS.md is explicit:
+// "Do not implement custom JWT verification." This decoder NEVER
+// verifies a signature; it only base64-decodes the payload segment.
+// If real client-side validation were ever needed (it should not be),
+// the answer is `jose`, not crypto rolled here.
+
+export interface JwtPayload {
+  /** Cf Access user-scoped JWT subject — the stable Entra UUID.
+   *  Marquee keys ownership off this `sub`, never off `email`. */
+  readonly sub?: string;
+  /** Email / UPN claim. Cloudflare populates this from the IdP. */
+  readonly email?: string;
+  /** Cf Access aud (the App's UUID). */
+  readonly aud?: string | readonly string[];
+  /** Issued-at + expiry, seconds since epoch (RFC 7519). */
+  readonly iat?: number;
+  readonly exp?: number;
+  /** Token type — "app" for Cf Access app tokens. */
+  readonly type?: string;
+  /** Anything else the IdP / Cf added; we don't validate it. */
+  readonly [k: string]: unknown;
+}
+
+export class JwtParseError extends Error {
+  readonly code = "jwt_parse_error" as const;
+}
+
+/**
+ * Decode the payload of a JWT. Returns `null` for inputs that
+ * don't look like a JWT at all (e.g. an opaque token). Throws
+ * `JwtParseError` only for shapes that look JWT-like but have an
+ * undecodable payload — callers should treat both null and throw
+ * as "show empty identity".
+ */
+export function decodeJwtPayload(token: string): JwtPayload | null {
+  const parts = token.split(".");
+  if (parts.length !== 3) return null;
+  const payload = parts[1] ?? "";
+  let json: string;
+  try {
+    json = Buffer.from(b64UrlToB64(payload), "base64").toString("utf8");
+  } catch (e) {
+    throw new JwtParseError(
+      `could not base64-decode JWT payload: ${describe(e)}`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(json);
+  } catch (e) {
+    throw new JwtParseError(`JWT payload is not JSON: ${describe(e)}`);
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new JwtParseError(`JWT payload is not an object`);
+  }
+  return parsed as JwtPayload;
+}
+
+function b64UrlToB64(s: string): string {
+  // Pad to length-multiple-of-4 + swap URL-safe alphabet back.
+  const padded = s.padEnd(s.length + ((4 - (s.length % 4)) % 4), "=");
+  return padded.replace(/-/g, "+").replace(/_/g, "/");
+}
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}

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

@@ -0,0 +1,79 @@
+// PKCE (RFC 7636) primitives, with one Cloudflare-specific deviation.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/pkce.ts — see
+// PROVENANCE.md. Unchanged from upstream: the protocol logic is
+// generic and not Marquee-specific.
+//
+// **The quirk.** The RFC says the `code_challenge` is base64url
+// (i.e. `[A-Za-z0-9_-]*`). Cloudflare's Access OAuth server rejects
+// challenges that don't START with `[a-zA-Z0-9]` — so a leading `-`
+// or `_` in the base64url output silently fails. Strategy: generate;
+// if the challenge starts with `-` or `_`, throw away both the
+// verifier AND the challenge and regenerate. We do NOT reuse the
+// verifier with a salt — that would not produce a fresh challenge.
+//
+// Verifier length: 32 bytes of entropy → 43 base64url chars (no
+// padding). Within the RFC's 43–128-char window.
+
+import { randomBytes, createHash } from "node:crypto";
+
+export interface PkcePair {
+  /** Plain-text random secret, kept on the client. */
+  readonly verifier: string;
+  /** S256 hash of the verifier, sent in the authorization URL. */
+  readonly challenge: string;
+}
+
+/** Hard cap on regeneration attempts — defends against an
+ *  algorithmic mistake silently spinning forever. The probability
+ *  of a `-` or `_` first byte is ~2/64 per attempt, so even 5 tries
+ *  is enough for ~6-nines reliability; we pick a higher bound so a
+ *  pathological RNG (or a future encoding change) surfaces as a
+ *  clear error rather than a hang. */
+export const MAX_PKCE_REGEN_ATTEMPTS = 32;
+
+export class PkceGenerationError extends Error {
+  readonly code = "pkce_generation_failed" as const;
+}
+
+/**
+ * Generate a fresh PKCE pair satisfying both RFC 7636 and the
+ * Cloudflare Access "challenge must start with [a-zA-Z0-9]" rule.
+ * Pure (modulo `randomBytes`) — caller can re-test by injecting
+ * a deterministic RNG via the optional `rng` parameter.
+ */
+export function generatePkcePair(
+  rng: (size: number) => Uint8Array = (s) => new Uint8Array(randomBytes(s)),
+): PkcePair {
+  for (let attempt = 0; attempt < MAX_PKCE_REGEN_ATTEMPTS; attempt++) {
+    const verifierBytes = rng(32);
+    const verifier = base64Url(verifierBytes);
+    const challenge = sha256Base64Url(verifier);
+    if (/^[a-zA-Z0-9]/.test(challenge)) {
+      return { verifier, challenge };
+    }
+    // Else: leading `-` or `_` — re-roll. Discarding the verifier
+    // entirely is intentional: re-hashing the same verifier with a
+    // salt would mean the server-side `verifier` derivation no
+    // longer matches the challenge.
+  }
+  throw new PkceGenerationError(
+    `could not produce a Cloudflare-acceptable PKCE challenge after ${MAX_PKCE_REGEN_ATTEMPTS} attempts; check the RNG`,
+  );
+}
+
+/** S256 challenge for an arbitrary verifier. Exposed for tests. */
+export function sha256Base64Url(verifier: string): string {
+  const hash = createHash("sha256").update(verifier).digest();
+  return base64Url(hash);
+}
+
+/** RFC 4648 §5 unpadded base64url. */
+function base64Url(bytes: Uint8Array | Buffer): string {
+  const buf = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}

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

@@ -0,0 +1,87 @@
+// Dynamic client registration (RFC 7591) for Cloudflare Access
+// Managed OAuth.
+//
+// Vendored from @m-kopa/launchpad-cli src/auth/registration.ts — see
+// PROVENANCE.md. Marquee adaptation: `client_name` is
+// "marquee-share-skill" (was "launchpad-cli") so the registered
+// public client is identifiable in Cloudflare Access logs.
+//
+// The first time a skill installation runs `login`, it POSTs a tiny
+// JSON body to the OAuth server's `registration_endpoint` announcing
+// itself as a PUBLIC client (`token_endpoint_auth_method: "none"`)
+// with the loopback redirect URI it just bound. The server returns a
+// `client_id` we use for this session and persist alongside the
+// tokens.
+//
+// We do NOT persist — or even receive and keep — a `client_secret`.
+// Public clients don't have one; PKCE replaces it. This is the
+// "PKCE public client — no client secret anywhere in the shipped
+// skill" requirement, enforced structurally: `RegistrationResult`
+// carries only `clientId`.
+
+export interface RegistrationResult {
+  readonly clientId: string;
+}
+
+export class RegistrationError extends Error {
+  readonly code = "registration_error" as const;
+}
+
+export async function registerClient(
+  registrationEndpoint: string,
+  redirectUri: string,
+  fetcher: typeof fetch = fetch,
+): Promise<RegistrationResult> {
+  const body = {
+    client_name: "marquee-share-skill",
+    redirect_uris: [redirectUri],
+    // Public client: no secret. PKCE is the proof-of-possession.
+    token_endpoint_auth_method: "none",
+    grant_types: ["authorization_code", "refresh_token"],
+    response_types: ["code"],
+  };
+  let res: Response;
+  try {
+    res = await fetcher(registrationEndpoint, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "application/json",
+      },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    throw new RegistrationError(`registration: network error: ${describe(e)}`);
+  }
+  if (!res.ok) {
+    const detail = await res.text().catch(() => "");
+    throw new RegistrationError(
+      `registration: ${registrationEndpoint} returned HTTP ${res.status}: ${detail.slice(0, 200)}`,
+    );
+  }
+  let parsed: unknown;
+  try {
+    parsed = await res.json();
+  } catch (e) {
+    throw new RegistrationError(
+      `registration: non-JSON response: ${describe(e)}`,
+    );
+  }
+  if (
+    parsed === null ||
+    typeof parsed !== "object" ||
+    typeof (parsed as { client_id?: unknown }).client_id !== "string"
+  ) {
+    throw new RegistrationError(
+      `registration: response missing string client_id`,
+    );
+  }
+  // Deliberately read ONLY client_id. Even if the server echoes a
+  // `client_secret`, we never capture it — a public client has no
+  // use for one and it must not reach disk.
+  return { clientId: (parsed as { client_id: string }).client_id };
+}
+
+function describe(e: unknown): string {
+  return e instanceof Error ? e.message : String(e);
+}