@pithy-sh/ui-react 0.1.0

package/templates/src/session.tsx

@@ -0,0 +1,78 @@
+import type { AuthSession, AuthUser } from "@pithy-sh/auth/src/client/api";
+import { signOut as endSession, getSession as readSession } from "@pithy-sh/auth/src/client/api";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { authConfig } from "./pithy-config";
+import { navigate, routeTable, screenPath } from "./router";
+
+/**
+ * Session state, read from the server.
+ *
+ * COOKIE/SESSION, NOT BEARER. The SPA is same-origin with its worker, so the session rides an
+ * httpOnly cookie: no access token, no refresh token, nothing in localStorage or sessionStorage, and
+ * no rotation logic here. JavaScript cannot read the cookie, so XSS has nothing to steal.
+ *
+ * **The requests themselves are not in this file, and that is deliberate.** Pithy wrote this file once
+ * and may never rewrite it — it is yours now — so a `fetch` written here would freeze the base-path
+ * join, the cookie mode and the failure handling into your repository on the day you scaffolded. They
+ * live in `@pithy-sh/auth/src/client/api`, which is the one place that knows how a browser program
+ * asks this worker an auth question, and which upgrades with a minor release. Same-origin and CSRF are
+ * its problem, not this screen's.
+ */
+
+/** The signed-in user, as the session route returns them. */
+export type SessionUser = AuthUser;
+
+/** A live session, or `null` when nobody is signed in. */
+export type Session = AuthSession;
+
+/** Where the auth routes are, for every call this file makes. */
+const client = { basePath: authConfig.basePath };
+
+/**
+ * The current session, or `null`.
+ *
+ * Never throws. A worker that could not be reached, or answered with something unreadable, reads as
+ * signed out here — which is a decision this file makes rather than one the package makes for it. If
+ * you would rather show "we couldn't check" than a sign-in form, read `result.failure` instead.
+ */
+export async function getSession(): Promise<Session> {
+  if (!authConfig.enabled) return null;
+  const result = await readSession(client);
+  return result.ok ? result.value : null;
+}
+
+/** End the session server-side and return to the sign-in screen. */
+export async function signOut(): Promise<void> {
+  await endSession(client);
+  // Where "the sign-in screen" is comes from the screen itself, never a literal here. Renaming its
+  // path is one edit and this follows it (#393).
+  navigate(screenPath(await routeTable(), "sign-in"));
+}
+
+/** The session as component state, plus a `refresh` for after a sign-in completes. */
+export function useSession(): { session: Session; loading: boolean; refresh: () => void } {
+  const [current, setCurrent] = useState<Session>(null);
+  const [loading, setLoading] = useState(true);
+  // Guards against setting state after unmount. A ref rather than a local, because `refresh` is
+  // callable from an event handler long after the effect that created it has been cleaned up.
+  const live = useRef(true);
+
+  const refresh = useCallback(() => {
+    setLoading(true);
+    void getSession().then((value) => {
+      if (!live.current) return;
+      setCurrent(value);
+      setLoading(false);
+    });
+  }, []);
+
+  useEffect(() => {
+    live.current = true;
+    refresh();
+    return () => {
+      live.current = false;
+    };
+  }, [refresh]);
+
+  return { session: current, loading, refresh };
+}

package/templates/src/styles.css

@@ -0,0 +1,53 @@
+/*
+ * Your stylesheet. Pithy writes it once, when there is none, and never touches it again.
+ *
+ * The classes Pithy's own screens render are NOT here — they live in `pithy-screens.css`, which those
+ * screens import themselves. So you can replace everything below without unstyling the sign-in screen,
+ * and a project that adds the auth screens years later gets them styled without this file being
+ * touched.
+ *
+ * The custom properties are the seam between the two. `pithy-screens.css` reads each of them with a
+ * fallback, so editing a value here restyles Pithy's screens along with your own, and deleting one
+ * leaves them standing.
+ *
+ * Declare them as a set, or declare none. Half a set is the one arrangement no fallback can catch —
+ * your background under Pithy's text — and `pithy-screens.test.tsx` beside this file is what notices.
+ */
+
+:root {
+  --bg: #fafaf6;
+  --surface: #ffffff;
+  --fg: #111111;
+  --fg-muted: #5f5d57;
+  --border: #e5e3db;
+  --accent: #d4a017;
+  --danger: #b3261e;
+  color-scheme: light dark;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #111111;
+    --surface: #1a1a19;
+    --fg: #fafaf6;
+    --fg-muted: #9a988f;
+    --border: #2e2e2b;
+    --danger: #f2b8b5;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--fg);
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+  line-height: 1.5;
+}
+
+a {
+  color: var(--accent);
+}

package/templates/src/turnstile.test.tsx

@@ -0,0 +1,119 @@
+// @vitest-environment happy-dom
+
+import { act } from "react";
+import { createRoot } from "react-dom/client";
+import { afterEach, beforeEach, expect, test, vi } from "vitest";
+
+/**
+ * **The widget is solved for the action the projection names, and states none of its own.**
+ *
+ * Turnstile bakes an action label into the token when the widget renders, and siteverify echoes it
+ * back; the sign-in route asserts it. One contract, two ends. `src/turnstile.tsx` is yours to edit,
+ * and the one edit it must never take is retyping that label as a literal.
+ *
+ * ## Why nothing you run before production can catch the two drifting apart
+ *
+ * `pithy turnstile provision` wires Cloudflare's documented **always-pass test secret** into dev and
+ * staging, and that secret's siteverify answer carries **no `action` field at all**. The gate accepts
+ * exactly that answer in exactly those environments. So in every environment you develop or test in,
+ * there is no action coming back to compare, and two strings that disagree behave precisely like two
+ * that agree.
+ *
+ * The first environment that can tell is production. There a real widget echoes what it was solved
+ * for, and a mismatch refuses **every** sign-in with a 403 that truthfully says the challenge failed
+ * — which sends whoever is paged to the user, the sitekey and the secret, in that order, and to the
+ * mismatch last. That is the whole reason this file exists rather than a comment asking nicely.
+ *
+ * ## What this proves, and how it goes red
+ *
+ * The projection is mocked with an action that is **deliberately not** the real one. A widget that
+ * read a literal of its own would render that literal, and this goes red; only a widget that renders
+ * what it was handed can pass. The expected value is invented here and reachable from nowhere else,
+ * which is what a canary is for — asserting the real action would pass against the very bug this
+ * catches.
+ *
+ * This is the widget half. That the *route* asserts the action the projection carries is the kit's
+ * own gate, in `@pithy-sh/auth`. Neither is sufficient alone: this one says the widget carries what
+ * it is told, that one says the server expects what is told.
+ */
+
+/**
+ * The action the mocked projection carries. Not the real one, on purpose: it is the difference
+ * between proving the widget *reads* the projection and proving only that two literals happen to
+ * match.
+ */
+const CANARY_ACTION = "pithy-gate-canary-not-a-real-action";
+
+/** A sitekey to match, so a mock that never took effect fails as loudly as a widget that ignored it. */
+const CANARY_SITEKEY = "0xCANARY";
+
+/**
+ * The projection, stubbed at the module the widget reads it through.
+ *
+ * `src/pithy-config.tsx` is mocked rather than `virtual:pithy/turnstile` because the virtual modules
+ * are served by `@pithy-sh/vite` during a build and resolve nowhere else — mocking the config module
+ * keeps this gate running under the plain `vitest run` a scaffolded project already has.
+ */
+vi.mock("./pithy-config", () => ({
+  turnstileConfig: {
+    enabled: true,
+    sitekey: CANARY_SITEKEY,
+    mode: "visible",
+    action: CANARY_ACTION,
+    token: { field: "cf-turnstile-response", header: null },
+  },
+}));
+
+// React refuses to run `act` unless the environment says it is a test one.
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+/** The options the component handed `turnstile.render`, or null if it never rendered a widget. */
+let rendered: { sitekey: string; action: string } | null = null;
+
+beforeEach(() => {
+  rendered = null;
+  // The component loads Cloudflare's script by appending it to `<head>` and awaiting `onload`. Nothing
+  // in a test environment can serve it, so the append is intercepted: no element is added, no request
+  // is made, and the handler the component just assigned is called as if the script had arrived.
+  vi.spyOn(document.head, "appendChild").mockImplementation(<T extends Node>(node: T): T => {
+    queueMicrotask(() => {
+      (node as unknown as HTMLScriptElement).onload?.(new Event("load"));
+    });
+    return node;
+  });
+  window.turnstile = {
+    render: (_element, options) => {
+      rendered = { sitekey: options.sitekey, action: options.action };
+      return "widget-id";
+    },
+  };
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  window.turnstile = undefined;
+});
+
+test("the widget is solved for the action the projection carries, not one of its own", async () => {
+  // The one place the kit's default action may appear: as the value the expectation must NOT be. A
+  // canary that drifted onto a real action would pass against the drift it exists to catch.
+  expect(CANARY_ACTION).not.toBe("login");
+
+  // Imported inside the case so the mocked config module is in place before the widget's module scope
+  // reads it.
+  const { Turnstile } = await import("./turnstile");
+  const host = document.createElement("div");
+  document.body.appendChild(host);
+
+  await act(async () => {
+    createRoot(host).render(<Turnstile onToken={() => {}} />);
+  });
+  // One more turn for the script promise's continuation, which is where `render` is called.
+  await act(async () => {
+    await Promise.resolve();
+  });
+
+  expect(rendered, "the widget never rendered — the config mock or the script stub did not take").not.toBeNull();
+  expect(rendered?.sitekey).toBe(CANARY_SITEKEY);
+  expect(rendered?.action).toBe(CANARY_ACTION);
+});

package/templates/src/turnstile.tsx

@@ -0,0 +1,105 @@
+import { type ReactNode, useEffect, useRef } from "react";
+import { turnstileConfig } from "./pithy-config";
+
+const SCRIPT_SRC = "https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit";
+
+interface TurnstileApi {
+  render: (
+    element: HTMLElement,
+    options: {
+      sitekey: string;
+      action: string;
+      appearance: "always" | "execute";
+      /** The widget is a cross-origin iframe we cannot style, so its palette is an argument, not CSS. */
+      theme: "light" | "dark" | "auto";
+      /**
+       * Its width is an argument too, and this is the half that is easy to miss. `normal` is a fixed
+       * 300px box — which is why a widget styled `width: 100%` still sat narrower than the email field
+       * beside it. `flexible` fills its container instead, with a 300px floor `pithy-screens.css`
+       * keeps the form's column above.
+       */
+      size: "normal" | "flexible" | "compact";
+      callback: (value: string) => void;
+      "expired-callback": () => void;
+    },
+  ) => string;
+}
+
+declare global {
+  interface Window {
+    turnstile?: TurnstileApi;
+  }
+}
+
+let script: Promise<void> | undefined;
+
+function loadScript(): Promise<void> {
+  script ??= new Promise<void>((resolve, reject) => {
+    const element = document.createElement("script");
+    element.src = SCRIPT_SRC;
+    element.async = true;
+    element.onload = () => resolve();
+    element.onerror = () => reject(new Error("Turnstile failed to load."));
+    document.head.appendChild(element);
+  });
+  return script;
+}
+
+/**
+ * Where the response token goes on a gated request. The server reads `token.header` when one is
+ * configured and `token.field` in the body otherwise — this returns both halves already decided.
+ */
+export function turnstileRequest(
+  body: Record<string, unknown>,
+  value: string | null,
+): { body: Record<string, unknown>; headers: Record<string, string> } {
+  if (!turnstileConfig.enabled || !value) return { body, headers: {} };
+  if (turnstileConfig.token.header) return { body, headers: { [turnstileConfig.token.header]: value } };
+  return { body: { ...body, [turnstileConfig.token.field]: value }, headers: {} };
+}
+
+/** True when a gated form still needs a token before it can submit. */
+export function turnstilePending(value: string | null): boolean {
+  return turnstileConfig.enabled && !value;
+}
+
+/** The widget. Renders nothing at all when the capability is not composed. */
+export function Turnstile(props: { onToken: (value: string | null) => void }): ReactNode {
+  const host = useRef<HTMLDivElement>(null);
+  const onToken = props.onToken;
+
+  useEffect(() => {
+    if (!turnstileConfig.enabled) return;
+    let live = true;
+    void loadScript()
+      .then(() => {
+        if (!live || !host.current || !window.turnstile) return;
+        window.turnstile.render(host.current, {
+          sitekey: turnstileConfig.sitekey,
+          // The action comes from the projection, and writing it out here again would be a bug nothing
+          // short of production could see: the server asserts this exact string against the token, and
+          // dev and staging run Cloudflare test keys, whose answer carries no action to compare. A
+          // drifted copy is silent everywhere until it refuses every sign-in in prod. #377.
+          action: turnstileConfig.action,
+          appearance: turnstileConfig.mode === "invisible" ? "execute" : "always",
+          // `auto` is Turnstile's own name for `prefers-color-scheme`, which is what `pithy-screens.css`
+          // answers too. The widget is a cross-origin iframe, so this argument is the only lever — and
+          // it resolves the same question from the same source, with nothing to keep in step.
+          theme: "auto",
+          // Fill the column, so the check matches the field and the button above and below it. The host
+          // element supplies the width; see `.auth__check` in pithy-screens.css. Both halves are
+          // required — either one alone leaves a ragged edge beside a full-width input.
+          size: "flexible",
+          callback: (value) => onToken(value),
+          "expired-callback": () => onToken(null),
+        });
+      })
+      .catch(() => onToken(null));
+    return () => {
+      live = false;
+    };
+  }, [onToken]);
+
+  if (!turnstileConfig.enabled) return null;
+  return <div ref={host} />;
+}

package/templates/tsconfig.client.json

@@ -0,0 +1,28 @@
+{
+  // The CLIENT program. Deliberately separate from tsconfig.json (the Worker's): the client needs JSX
+  // and the DOM, the Worker needs the Workers globals, and nothing may import across the two.
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "jsx": "react-jsx",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "noImplicitOverride": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "types": ["vite/client"],
+    // Referenced from the project's root tsconfig.json, which requires `composite` — and `composite`
+    // makes tsc write build state. It goes under the PROJECT's `dist/`, already gitignored, never under
+    // this Worker's: Vite owns `apps/<worker>/dist` and empties it on every build, which would throw the
+    // incremental state away each time.
+    "composite": true,
+    "tsBuildInfoFile": "../../dist/__PITHY_WORKER__.client.tsbuildinfo",
+    "noEmit": true
+  },
+  "include": ["src/**/*.tsx", "client-env.d.ts"]
+}

package/templates/tsconfig.node.json

@@ -0,0 +1,22 @@
+{
+  // The BUILD program: vite.config.ts runs on Node.
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "moduleDetection": "force",
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "strict": true,
+    "skipLibCheck": true,
+    "types": ["node"],
+    // Referenced from the project's root tsconfig.json — see tsconfig.client.json for why the build
+    // state lands in the project's `dist/` and not this Worker's.
+    "composite": true,
+    "tsBuildInfoFile": "../../dist/__PITHY_WORKER__.node.tsbuildinfo",
+    "noEmit": true
+  },
+  "include": ["vite.config.ts"]
+}

package/templates/vite.config.ts

@@ -0,0 +1,45 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { devWorkerConfig } from "@pithy-sh/vite/src/devOrigin";
+import { pithy } from "@pithy-sh/vite/src/plugin";
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  /**
+   * One React, however many checkouts the packages live in.
+   *
+   * Vite resolves a symlinked package from its realpath, so a package linked in from somewhere else —
+   * the Pithy kit, a design system, any workspace you point at by path — imports `react` out of *its*
+   * tree rather than out of this Worker's. Two copies of React is `invalid hook call` on the first
+   * component that package renders, and the stack blames the component rather than the resolution.
+   *
+   * `dedupe` resolves both names from Vite's root no matter who asked, and the root here is this
+   * Worker's own directory, where `react` is a dependency and there is therefore something to resolve.
+   * That is not true one level up: the project's `vitest.config.ts` is rooted at the repository, which
+   * has no React, so it states the same rule as an explicit alias instead. Read the note there before
+   * moving either.
+   *
+   * It is not a workaround for a symlink. It is what every linked-package setup needs, it costs nothing
+   * when nothing is linked, and it goes on costing nothing the day `@pithy-sh/*` is published.
+   */
+  resolve: { dedupe: ["react", "react-dom"] },
+  plugins: [
+    react(),
+    cloudflare({
+      // `BASE_URL` from the port block `pithy dev` allocated *this checkout*, overriding the one in
+      // wrangler.jsonc while dev is running. A dev port is allocated rather than configured, so a
+      // literal there is right in the first checkout on a machine and wrong in every other one — and
+      // `BASE_URL` is the `iss` on every control-plane token this Worker signs and the origin its
+      // callback links are built against. Outside `pithy dev` it does nothing and the declared value
+      // stands, which is what a deployed environment wants. See `devWorkerConfig`.
+      config: devWorkerConfig(),
+      // Local state lives at the PROJECT root, not here — the same store pithy dev, migrate, and seed
+      // use. Per-worker state would silently give two workers separate copies of a shared database.
+      persistState: { path: "../../.wrangler/state" },
+      // Pinned off. The inspector defaults to 9229 and silently advances on a collision, so two
+      // UI-bearing workers under one pithy dev would drift onto ports nobody assigned them.
+      inspectorPort: false,
+    }),
+    pithy(),
+  ],
+});