@graph8/sdk 0.370.0 → 0.374.0

package/README.md

@@ -499,10 +499,10 @@ npx @graph8/sdk create mailchimp my-app   # then: cd my-app && cp .env.local.exa
 | `mailchimp` | Newsletter, nurture, forms, contacts, companies, tasks, lists, suppressions |
 | `clay` | Prospect search, workbench, enrichment, lists, contacts, companies, tasks, suppressions |
 | `6sense` | Intent, visitors, competitors, companies, contacts, tasks |
-| `intercom` | Inbox, web chat conversations, contacts, companies, tasks, AI agents, mailboxes |
+| `intercom` | Inbox, web chat conversations, contacts, companies, tasks, AI agents, mailboxes, email signatures |
 | `calendly` | Meetings and scheduling (event types, availability, booking pages) over contacts, companies and tasks |
-| `pipedrive` | Analytics, deals, quotes, contacts, companies, inbox, meetings, scheduling, tasks and mailboxes; deals and quotes open each other, replies can start a deal |
-| `outreach` | Analytics, contacts, companies, lists, sequences, campaigns, inbox, dialer, call log, meetings, scheduling, tasks, mailboxes, suppressions |
+| `pipedrive` | Analytics, deals, quotes, contacts, companies, inbox, meetings, scheduling, tasks, mailboxes and email signatures; deals and quotes open each other, replies can start a deal |
+| `outreach` | Analytics, contacts, companies, lists, sequences, campaigns, inbox, dialer, call log, meetings, scheduling, tasks, mailboxes, email signatures, suppressions |
 | `apollo` | Outreach's screens plus prospect search, enrichment, intent, visitors, deals and integrations; contacts get Enrich, Add to sequence and a Deals tab |
 | `gong` | Analytics, call log, coaching, dialer, meetings, scheduling, contacts, companies, tasks, lists, suppressions |
 | `salesforce` | Analytics, contacts, companies, lists, deals, quotes, lifecycle, tasks, workflows, copilot, custom objects, suppressions, integrations |
@@ -512,6 +512,25 @@ npx @graph8/sdk create mailchimp my-app   # then: cd my-app && cp .env.local.exa
 
 Every available stack is proven by `npm run build && npm run e2e:create -- <stack>`, which packs the SDK, scaffolds the app with the built CLI, installs it and requires `next build` to pass. More stacks appear here as their blocks land; `create` refuses a stack that is not available yet.
 
+### Branding: your Brand Kit, automatically
+
+If your graph8 organization already has a Brand Kit (Studio), `create` uses it. With a key in `G8_API_KEY` (environment or `.env.local`), the new app gets your organization's name, primary colour and logo without any flags; the logo is downloaded into `public/brand/` (never hot-linked), and the colour becomes `--brand` / `--primary` with button text checked for WCAG AA.
+
+```bash
+G8_API_KEY=... npx @graph8/sdk create apollo my-app           # picks up the Brand Kit
+npx @graph8/sdk create apollo my-app --no-org-brand            # skip it
+npx @graph8/sdk create apollo my-app --brand-color "#0f62fe"   # your colour wins; the kit still fills the name and logo
+npx @graph8/sdk brand --from-org                               # brand an existing app from the kit
+```
+
+| Brand Kit field (Developer API) | App brand input |
+|---|---|
+| `GET /me` `org_name` | `--name` (`g8.config.ts` `name`) |
+| `GET /brand-kit` `design_tokens.colors.primary` (else `brand`, `accent`, button background) | `--brand-color` |
+| `GET /brand-kit` `logo_url` (one logo; no light, dark or icon variant) | `--logo` (`public/brand/logo.*`) |
+
+Explicit flags always win, field by field. With no key, a missing or empty kit, no `campaigns:read` scope or no network, the app keeps the default look and the CLI prints one info line; it never fails. The key is never printed or written. Fonts, tagline and voice traits are in the kit but have no brand input, so they are not applied. Icons stay Lucide.
+
 ## UI kit (`@graph8/sdk/ui`)
 
 The React component kit and design tokens behind the graph8 app (primitives, light and dark

package/blocks/_foundation/README.md

@@ -10,6 +10,8 @@ Shared base every other block depends on. Install it first (the CLI does it for
 | `server/proxy.ts` | `createG8Proxy(config)`: the logic of the proxy (forwarding, allowlist, `authorize` hook). |
 | `server/route.ts` | Installs as `app/api/g8/[...path]/route.ts` and mounts the proxy. `allowedPrefixes` is generated from the installed blocks' operations; local preview is on. |
 | `server/local-key.ts`, `server/connect.ts`, `server/connect-route.ts` | Local preview key store: `app/api/g8-connect/route.ts` checks a pasted key (GET /me) and keeps it in `.g8/local-key` on the server. 404 in production. |
+| `server/auth.ts` | Optional `authorize` presets (sign-in) for the proxy: `sharedPassword`, `basicAuth`, `jwtAuth`, `sessionAuth`, `allowAnonymous`, and `createG8AuthRoute`. See "Sign-in presets" below. |
+| `components/auth-gate.tsx` | `G8AuthGate`, `SignInPanel`, `G8SignOutButton`: the branded sign-in screen for apps that use a preset. |
 | `components/connect-graph8.tsx` | `ConnectGraph8Panel` + `G8ConnectGate`: the first-run Connect graph8 panel in `next dev`; a no-op in production. |
 | `hooks/use-g8-query.ts` | `useG8Query(fetcher, deps)` -> `{ data, error, loading, refetch }`. Latest request wins. |
 | `hooks/use-g8-mutation.ts` | `useG8Mutation(fn)` -> `{ mutate, mutateAsync, data, error, loading, reset }`. |
@@ -122,6 +124,51 @@ Connect graph8 panel, which the server checks against `GET /me` and stores in `.
 `npx @graph8/sdk doctor --production` fails until the route is safe to deploy;
 `npx @graph8/sdk doctor --fix-prefixes` regenerates `allowedPrefixes` after you add or remove blocks.
 
+### Sign-in presets (optional): going live with `authorize`
+
+`authorize` is any function `(request) => Response | void`; your own session check is always fine. For the
+common cases `server/auth.ts` ships presets, and `npx @graph8/sdk create <stack> <dir> --auth <preset>` wires one
+up (g8.auth.ts, the route's `authorize`, the sign-in screen, README and `.env.local.example`). Nothing changes for
+apps that do not use one: without `authorize` the proxy behaves exactly as described above.
+
+| Preset | What it checks | Server environment |
+|---|---|---|
+| `sharedPassword()` | one team password; signs an HttpOnly, SameSite=Lax session cookie (HMAC-SHA-256, 7 days); sign-in screen | `G8_APP_PASSWORD` (12+), `G8_SESSION_SECRET` (32+) |
+| `basicAuth()` | HTTP Basic auth; pair with a `middleware.ts` so every page asks; refuses cross-site writes; 20 wrong tries per client per 15 min | `G8_BASIC_AUTH` (`user:pass,user2:pass2`; passwords 12+ characters, no commas) |
+| `jwtAuth()` | a JWT from your OIDC provider (JWKS: RS/PS/ES256 family, discovered from the issuer) or an HS256 secret; exp, nbf, iss, aud; optional `claims` check | `G8_JWT_ISSUER`, `G8_JWT_JWKS_URL`, `G8_JWT_AUDIENCE`, `G8_JWT_COOKIE` or a Bearer header, `G8_JWT_SECRET` |
+| `sessionAuth(fn)` | your session library: return the user to allow (Clerk `auth()`, NextAuth `auth()`, Supabase `getUser()`) | `G8_SIGN_IN_URL`, `G8_SIGN_OUT_URL` (for the screen) |
+| `allowAnonymous()` | nothing: anyone who can reach the app uses the key. Logs a warning; `doctor` flags it | |
+
+Wire one by hand in an existing app:
+
+```ts
+// g8.auth.ts
+import { sharedPassword } from "@/components/g8/_foundation/server/auth";
+export const appAuth = sharedPassword();
+
+// app/api/g8/[...path]/route.ts: inside createG8Proxy({ ... })
+authorize: appAuth.authorize,
+
+// app/api/g8-auth/route.ts (the sign-in screen's server side; password, jwt and session presets)
+import { createG8AuthRoute } from "@/components/g8/_foundation/server/auth";
+import { appAuth } from "@/g8.auth";
+export const { GET, POST, DELETE } = createG8AuthRoute(appAuth);
+
+// app/layout.tsx: wrap the shell (BrandProvider keeps the screen on brand)
+<BrandProvider brand={brand}><G8AuthGate><AppShell headerSlot={<G8SignOutButton />}>...</AppShell></G8AuthGate></BrandProvider>
+```
+
+Security: passwords and secrets are compared in constant time; cookie and Basic presets refuse cross-site writes (CSRF:
+`Sec-Fetch-Site`/`Origin`); JWTs with alg `none`, an algorithm outside the allow-list, a key of the wrong type
+(no HS/RS confusion), `crit` headers or no `exp` are refused; sign-in attempts are rate limited per client (in
+memory: best effort on serverless, so pick a long password). `sharedPassword` also caps WRONG passwords from all
+clients together (`maxFailuresGlobal`, default 100 per 15 min): anyone who can reach the sign-in route can keep
+NEW sign-ins paused that way (existing sessions keep working); with a long random password raise it or pass
+`Infinity`. `jwtAuth` with a JWKS and no audience accepts any token the issuer minted for other apps on the same
+tenant: set `G8_JWT_AUDIENCE` or a `claims` check (it warns at startup, and `doctor` warns). `sharedPassword` and
+`basicAuth` read the environment on every request; `jwtAuth` and `sessionAuth` once at startup. A missing setting is a 500 that names the variable,
+never its value. The sign-in screen is UX only: the proxy's `authorize` is the gate.
+
 What the proxy does on its own: rejects `..`, encoded slashes and empty segments (400); forwards only
 `content-type`, `accept`, `accept-language` and `idempotency-key` (never the browser's cookies or
 `Authorization`); strips hop-by-hop headers, `set-cookie` and `location` from the response; does not follow
@@ -238,6 +285,20 @@ Rules the kit encodes, so screens stay consistent:
 - Loading is visible and distinct from empty: `StatStrip loading`, `Skeleton` rows.
 - Dates show short text; the full timestamp is the `title` of a `<time dateTime>`.
 
+## Long lists: paging, notices and filters (no silent truncation)
+
+A list read that sends a `limit` must page or say it stopped. The foundation ships the pieces:
+
+| Need | Use |
+|---|---|
+| Show rows with a "Load more" button (the API pages by `page` or `offset`) | `useLoadMoreList(byPage(size, read))` or `byOffset(size, read)` (`lib/paging.ts`), then `<LoadMore>` under the rows |
+| The API has only a `limit` (no paging) | `<FirstNotice shown={rows.length} limit={LIMIT} noun="mailboxes" />`: "Showing the first N ..." appears only when the read came back full |
+| A screen needs EVERY row (a lookup by id, a full dropdown) | `useAllPages(read, deps)`: reads page after page, reports `truncated` if the page cap cut it short |
+| Choose one audience list | crm's `ListSelect`: a native select with server search and "Load more lists" |
+| Filters for a list screen | `useUrlFilters(keys, { prefix })` keeps them in the URL (`c_email=...`); `TextFilter`, `SelectFilter`, `RangeFilter` and `MoreFilters` (a "More filters" disclosure) go in the Toolbar `filters` slot |
+
+`tests/blocks/list-paging-guard.test.ts` in the SDK repo fails on a new `g8Get(..., { limit })` read that does none of these.
+
 ## Prerequisites
 
 - `G8_API_KEY` in the server env; verify with `recipes/verify-proxy-key.ts`.

package/blocks/_foundation/block.json

@@ -9,6 +9,7 @@
     "spend/send/delete confirmation dialog",
     "screen kit: layout, stats, split view, detail panel, toolbar, status pills, avatars, cards, form sheet, charts",
     "local preview: a Connect graph8 screen stores the server's key for `next dev`; generated allowedPrefixes",
+    "go live: optional sign-in presets for the proxy's authorize (team password, Basic, OIDC/JWT, Clerk/NextAuth/Supabase sessions) and a branded sign-in screen",
     "white-label: BrandProvider + useBrand give every block's copy and link-outs your platform name and app URL (default graph8)"
   ],
   "dependsOn": [],
@@ -149,12 +150,40 @@
       "operations": [],
       "tiers": []
     },
+    {
+      "name": "G8AuthGate",
+      "file": "components/auth-gate.tsx",
+      "purpose": "Sign-in for apps with an auth preset (create --auth): G8AuthGate shows SignInPanel (team password form, provider redirect, or the missing server setting) until the visitor is signed in, G8SignOutButton for the header. Talks only to the app's /api/g8-auth route; renders the app unchanged when that route does not exist.",
+      "operations": [],
+      "tiers": []
+    },
     {
       "name": "BrandProvider",
       "file": "components/brand-provider.tsx",
       "purpose": "White-label context: the app's name, logo, and what the platform is called and where it lives, for every block's copy and link-outs. Fields left out stay graph8's.",
       "operations": [],
       "tiers": []
+    },
+    {
+      "name": "ListSelect",
+      "file": "components/list-select.tsx",
+      "purpose": "Audience-list dropdown, searchable and paged (native select + server search + Load more). It owns no API call: the block that uses it passes a `read` (crm ships ListSelect with the /lists read wired in).",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "FirstNotice",
+      "file": "components/paging-notices.tsx",
+      "purpose": "FirstNotice (\"Showing the first N ...\" when a read without paging came back full) and LoadMore (\"Showing N\" + Load more): the two honest endings of a capped list.",
+      "operations": [],
+      "tiers": []
+    },
+    {
+      "name": "TextFilter",
+      "file": "components/screen/filter-controls.tsx",
+      "purpose": "Toolbar filter controls: TextFilter, SelectFilter, RangeFilter (from/to) and MoreFilters (a disclosure that opens by itself when a hidden filter is set).",
+      "operations": [],
+      "tiers": []
     }
   ],
   "hooks": [
@@ -192,6 +221,21 @@
       "name": "useBrand",
       "file": "hooks/use-brand.ts",
       "purpose": "The current brand ({ name, appUrl, linkLabel, logo }) from the nearest BrandProvider, else graph8's defaults; brandUrl(brand, path) builds a link-out."
+    },
+    {
+      "name": "useAllPages",
+      "file": "hooks/use-all-pages.ts",
+      "purpose": "Read every page of a list a screen needs in full (lookups, full dropdowns), up to a page cap, and report when the cap cut it short."
+    },
+    {
+      "name": "useLoadMoreList",
+      "file": "hooks/use-load-more-list.ts",
+      "purpose": "A list read with Load more: the shape of a useG8Query list (data, loading, error, refetch) plus hasMore / loadMore. Pair with byPage / byOffset and the LoadMore notice."
+    },
+    {
+      "name": "useUrlFilters",
+      "file": "hooks/use-url-filters.ts",
+      "purpose": "List-screen filters kept in the URL (debounced, prefixed, SSR-safe): draft for the inputs, query for the read, clear()."
     }
   ],
   "lib": [
@@ -218,6 +262,14 @@
     {
       "file": "lib/plural.ts",
       "purpose": "plural(n, 'contact') -> '1 contact' / '2 contacts' (and pluralWord): one correct plural helper for titles, counts and bulk dialogs."
+    },
+    {
+      "file": "lib/paging.ts",
+      "purpose": "byPage / byOffset adapt page-number and offset lists to usePaginated's cursor shape; hasNextOf reads the API's has_next / next_cursor."
+    },
+    {
+      "file": "lib/use-debounced-value.ts",
+      "purpose": "useDebounced: a value after it stopped changing (foundation-local copy)."
     }
   ],
   "server": [
@@ -226,6 +278,11 @@
       "purpose": "createG8Proxy(): forwards browser calls to the graph8 API with the server-side key, a required path allowlist and authorize hook (it refuses to run without them) and a server-side org hook.",
       "target": "g8/server/proxy.ts"
     },
+    {
+      "file": "server/auth.ts",
+      "purpose": "Optional authorize presets for the proxy: sharedPassword (signed session cookie + sign-in route), basicAuth, jwtAuth (OIDC JWKS or HS256), sessionAuth (Clerk/NextAuth/Supabase adapter), allowAnonymous; createG8AuthRoute() backs the sign-in screen. Web APIs only (Node and Edge).",
+      "target": "g8/server/auth.ts"
+    },
     {
       "file": "server/local-key.ts",
       "purpose": "Node only: the local-preview key file (.g8/local-key, 0600, self-gitignored) and resolveApiKey() (environment first, then the file outside production).",

package/blocks/_foundation/components/auth-gate.tsx

@@ -0,0 +1,363 @@
+"use client";
+
+/**
+ * Sign-in for a created app that uses an auth preset (`create --auth <preset>`, g8/server/auth.ts). The proxy
+ * enforces sign-in on the server; this is the screen people see instead of empty, refused data.
+ *
+ * Calls this app's own `/api/g8-auth` route (createG8AuthRoute), never graph8:
+ *   GET    the session status: signed in or not, which preset, the sign-in URL, or what the server is missing
+ *   POST   { password } (shared-password preset): sets an HttpOnly session cookie
+ *   DELETE sign out (shared-password preset)
+ * No billable, external or destructive graph8 operation. The password goes from the input to the server once
+ * and is never kept in browser state after submit, storage or the URL.
+ *
+ * Exports:
+ *   - G8AuthGate: wraps the app. Shows a loading screen while it checks, SignInPanel when signed out, the app when
+ *     signed in. Re-checks when the tab becomes visible again. If /api/g8-auth does not exist it renders the
+ *     app unchanged (apps without a preset).
+ *   - SignInPanel: the sign-in screen (password form, provider redirect, or the setup problem). No required props.
+ *   - G8SignOutButton: a header button (AppShell `headerSlot`); renders nothing outside a signed-in gate.
+ *   - useG8Auth: { status, signOut, refresh } inside the gate, else null.
+ * The app's name and logo come from the nearest BrandProvider (g8.config.ts), the colours from the theme tokens
+ * (the Brand Kit region in globals.css), so the screen is on brand without edits.
+ */
+
+import { createContext, useCallback, useContext, useEffect, useId, useRef, useState, type FormEvent, type ReactNode } from "react";
+import { AlertTriangle, ArrowRight, Eye, EyeOff, Loader2, LockKeyhole, LogIn, LogOut, RefreshCw } from "lucide-react";
+import { Button, Input, cn } from "@graph8/sdk/ui";
+import { useBrand } from "../hooks/use-brand";
+
+export const AUTH_PATH = "/api/g8-auth";
+
+export type AuthKind = "password" | "basic" | "jwt" | "session" | "anonymous";
+
+export interface AuthStatus {
+  kind: AuthKind;
+  signedIn: boolean;
+  signInUrl?: string;
+  signOutUrl?: string;
+  problem?: string;
+}
+
+/** The status, null when the route does not exist (no preset), or "error" when the server could not be reached. */
+export async function fetchAuthStatus(): Promise<AuthStatus | null | "error"> {
+  try {
+    const res = await fetch(AUTH_PATH, { headers: { accept: "application/json" }, cache: "no-store", credentials: "same-origin" });
+    if (res.status === 404) return null;
+    if (!res.ok) return "error";
+    const body = (await res.json().catch(() => null)) as AuthStatus | null;
+    return body && typeof body.signedIn === "boolean" ? body : "error";
+  } catch {
+    return "error";
+  }
+}
+
+interface AuthContextValue {
+  status: AuthStatus;
+  signOut: () => Promise<void>;
+  refresh: () => Promise<void>;
+}
+
+const AuthContext = createContext<AuthContextValue | null>(null);
+
+/** Inside G8AuthGate: the session and its actions. Null elsewhere. */
+export function useG8Auth(): AuthContextValue | null {
+  return useContext(AuthContext);
+}
+
+/** Only same-app paths or http(s) URLs are followed; anything else (javascript:, data:) is dropped. */
+function safeUrl(url: string | undefined): string | undefined {
+  if (!url) return undefined;
+  if (url.startsWith("/") && !url.startsWith("//")) return url;
+  return /^https?:\/\//i.test(url) ? url : undefined;
+}
+
+function Frame({ children, labelledBy }: { children: ReactNode; labelledBy?: string }) {
+  return (
+    <main aria-labelledby={labelledBy} className="flex min-h-dvh items-center justify-center bg-background px-4 py-12">
+      <div className="w-full max-w-sm">{children}</div>
+    </main>
+  );
+}
+
+function BrandMark() {
+  const brand = useBrand();
+  return (
+    <div className="flex items-center gap-2.5">
+      {brand.logo ? (
+        // eslint-disable-next-line @next/next/no-img-element
+        <img src={brand.logo} alt="" className="size-8 rounded-md object-contain" />
+      ) : (
+        <span aria-hidden className="flex size-8 items-center justify-center rounded-md bg-primary text-sm font-medium text-primary-foreground">
+          {brand.name.trim().charAt(0).toUpperCase() || "A"}
+        </span>
+      )}
+      <span className="truncate text-sm font-medium text-foreground">{brand.name}</span>
+    </div>
+  );
+}
+
+function ErrorLine({ id, children }: { id?: string; children: ReactNode }) {
+  return (
+    <p id={id} role="alert" className="flex items-start gap-1.5 text-xs leading-5 text-error-foreground">
+      <AlertTriangle aria-hidden className="mt-0.5 size-3.5 shrink-0" strokeWidth={1.5} />
+      <span>{children}</span>
+    </p>
+  );
+}
+
+function PasswordForm({ onSignedIn }: { onSignedIn: (s: AuthStatus) => void }) {
+  const [password, setPassword] = useState("");
+  const [show, setShow] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const id = useId();
+
+  const submit = async (e: FormEvent) => {
+    e.preventDefault();
+    if (!password || busy) return;
+    setBusy(true);
+    setError(null);
+    try {
+      const res = await fetch(AUTH_PATH, { method: "POST", credentials: "same-origin", headers: { "content-type": "application/json" }, body: JSON.stringify({ password }) });
+      const body = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+      setPassword("");
+      if (res.ok && body.signedIn === true) onSignedIn(body as unknown as AuthStatus);
+      else setError(typeof body.message === "string" ? body.message : `Could not sign in (HTTP ${res.status}).`);
+    } catch {
+      setError("Could not reach this app's server. Check your connection and try again.");
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <form onSubmit={submit} className="flex flex-col gap-3" noValidate>
+      <div className="flex flex-col gap-1.5">
+        <label htmlFor={`${id}-pw`} className="text-sm font-medium text-foreground">
+          Password
+        </label>
+        <div className="relative">
+          <Input
+            id={`${id}-pw`}
+            type={show ? "text" : "password"}
+            autoComplete="current-password"
+            autoFocus
+            value={password}
+            onChange={(e) => setPassword(e.target.value)}
+            className="pr-10"
+            aria-invalid={error ? true : undefined}
+            aria-describedby={error ? `${id}-err` : undefined}
+          />
+          <button
+            type="button"
+            onClick={() => setShow((v) => !v)}
+            aria-label={show ? "Hide password" : "Show password"}
+            aria-pressed={show}
+            className="absolute inset-y-0 right-0 flex w-10 items-center justify-center rounded-r-md text-text-color-muted hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            {show ? <EyeOff aria-hidden className="size-4" strokeWidth={1.5} /> : <Eye aria-hidden className="size-4" strokeWidth={1.5} />}
+          </button>
+        </div>
+      </div>
+      {error ? <ErrorLine id={`${id}-err`}>{error}</ErrorLine> : null}
+      <Button type="submit" className="w-full" disabled={!password || busy}>
+        {busy ? <Loader2 aria-hidden className="size-4 animate-spin" /> : <ArrowRight aria-hidden className="size-4" strokeWidth={1.5} />}
+        {busy ? "Signing in" : "Sign in"}
+      </Button>
+    </form>
+  );
+}
+
+export interface SignInPanelProps {
+  /** Status from a previous GET (the gate passes it); fetched on mount when absent. */
+  status?: AuthStatus | null;
+  /** Called after a successful sign-in. */
+  onSignedIn?: (status: AuthStatus) => void;
+  className?: string;
+}
+
+/** The sign-in screen: a password form, a "Continue to sign in" link to your provider, or what the server lacks. */
+export function SignInPanel({ status: initial, onSignedIn, className }: SignInPanelProps) {
+  const [status, setStatus] = useState<AuthStatus | null | undefined>(initial);
+  const brand = useBrand();
+  const titleId = useId();
+
+  useEffect(() => {
+    if (initial === undefined) void fetchAuthStatus().then((s) => setStatus(s === "error" ? null : s));
+  }, [initial]);
+
+  const signInUrl = safeUrl(status?.signInUrl);
+  const problem = status?.problem;
+
+  return (
+    <section aria-labelledby={titleId} className={cn("flex flex-col gap-6", className)}>
+      <BrandMark />
+      <div className="flex flex-col gap-1.5">
+        <div aria-hidden className="mb-1 flex size-10 items-center justify-center rounded-lg border border-border bg-muted text-foreground">
+          {problem ? <AlertTriangle className="size-5" strokeWidth={1.5} /> : <LockKeyhole className="size-5" strokeWidth={1.5} />}
+        </div>
+        <h1 id={titleId} className="text-lg font-medium text-foreground">
+          {problem ? "Sign-in is not set up yet" : `Sign in to ${brand.name}`}
+        </h1>
+        <p className="text-sm leading-5 text-text-color-muted">
+          {problem
+            ? "This app asks people to sign in before it shows any data, but its server is missing a setting."
+            : status?.kind === "password"
+              ? "Enter the team password to continue."
+              : "Use your account to continue."}
+        </p>
+      </div>
+
+      {status === undefined ? (
+        <div className="flex h-10 items-center gap-2 text-sm text-text-color-muted" role="status">
+          <Loader2 aria-hidden className="size-4 animate-spin" />
+          Checking your session
+        </div>
+      ) : problem ? (
+        <div className="rounded-lg border border-border bg-muted/40 p-3 text-xs leading-5 text-foreground">
+          <p>{problem}</p>
+          <p className="mt-2 text-text-color-muted">The settings go in the server environment (.env.local while developing), never in NEXT_PUBLIC_ variables.</p>
+        </div>
+      ) : status?.kind === "password" ? (
+        <PasswordForm
+          onSignedIn={(s) => {
+            setStatus(s);
+            onSignedIn?.(s);
+          }}
+        />
+      ) : signInUrl ? (
+        <Button asChild className="w-full">
+          <a href={signInUrl}>
+            <LogIn aria-hidden className="size-4" strokeWidth={1.5} />
+            Continue to sign in
+          </a>
+        </Button>
+      ) : (
+        <p className="rounded-lg border border-border p-3 text-xs leading-5 text-text-color-muted">
+          Sign in through your identity provider, then reload this page. To show a sign-in button here, set G8_SIGN_IN_URL in the server environment.
+        </p>
+      )}
+    </section>
+  );
+}
+
+export interface G8AuthGateProps {
+  children: ReactNode;
+}
+
+/**
+ * Shows SignInPanel instead of the app until the visitor is signed in. Renders the app unchanged when the app has
+ * no /api/g8-auth route. The server (the proxy's `authorize`) is the real gate; this only decides what to show.
+ */
+export function G8AuthGate({ children }: G8AuthGateProps) {
+  const [status, setStatus] = useState<AuthStatus | null | "error" | undefined>(undefined);
+  const [retrying, setRetrying] = useState(false);
+  const titleId = useId();
+  const latest = useRef(0);
+
+  const refresh = useCallback(async () => {
+    const n = ++latest.current;
+    const next = await fetchAuthStatus();
+    if (n === latest.current) setStatus(next);
+  }, []);
+
+  useEffect(() => {
+    void refresh();
+    const onVisible = () => {
+      if (document.visibilityState === "visible") void refresh();
+    };
+    document.addEventListener("visibilitychange", onVisible);
+    return () => document.removeEventListener("visibilitychange", onVisible);
+  }, [refresh]);
+
+  const signOut = useCallback(async () => {
+    const current = typeof status === "object" ? status : null;
+    const out = safeUrl(current?.signOutUrl);
+    if (current?.kind !== "password") {
+      if (out) window.location.assign(out);
+      return;
+    }
+    await fetch(AUTH_PATH, { method: "DELETE", credentials: "same-origin" }).catch(() => undefined);
+    latest.current++;
+    setStatus({ ...current, signedIn: false });
+  }, [status]);
+
+  if (status === null) return <>{children}</>;
+  if (status === undefined) {
+    return (
+      <Frame>
+        <div role="status" className="flex flex-col items-center gap-3 text-sm text-text-color-muted">
+          <Loader2 aria-hidden className="size-5 animate-spin" />
+          Checking your session
+        </div>
+      </Frame>
+    );
+  }
+  if (status === "error") {
+    return (
+      <Frame labelledBy={titleId}>
+        <div className="flex flex-col gap-4">
+          <BrandMark />
+          <h1 id={titleId} className="text-lg font-medium text-foreground">
+            Could not check your session
+          </h1>
+          <p className="text-sm leading-5 text-text-color-muted">This app&apos;s server did not answer. Check your connection and try again.</p>
+          <Button
+            type="button"
+            variant="outline"
+            className="w-fit"
+            disabled={retrying}
+            onClick={async () => {
+              setRetrying(true);
+              await refresh();
+              setRetrying(false);
+            }}
+          >
+            {retrying ? <Loader2 aria-hidden className="size-4 animate-spin" /> : <RefreshCw aria-hidden className="size-4" strokeWidth={1.5} />}
+            Try again
+          </Button>
+        </div>
+      </Frame>
+    );
+  }
+  if (!status.signedIn) {
+    return (
+      <Frame>
+        <SignInPanel
+          status={status}
+          onSignedIn={(s) => {
+            latest.current++;
+            setStatus(s);
+          }}
+        />
+      </Frame>
+    );
+  }
+  return <AuthContext.Provider value={{ status, signOut, refresh }}>{children}</AuthContext.Provider>;
+}
+
+/** Sign out, for the AppShell header. Nothing outside a signed-in G8AuthGate, or when sign-out lives at your provider without a G8_SIGN_OUT_URL. */
+export function G8SignOutButton({ className }: { className?: string }) {
+  const auth = useG8Auth();
+  const [busy, setBusy] = useState(false);
+  if (!auth || !auth.status.signedIn) return null;
+  if (auth.status.kind !== "password" && !safeUrl(auth.status.signOutUrl)) return null;
+  return (
+    <Button
+      type="button"
+      variant="ghost"
+      size="sm"
+      className={className}
+      disabled={busy}
+      onClick={async () => {
+        setBusy(true);
+        await auth.signOut();
+        setBusy(false);
+      }}
+    >
+      {busy ? <Loader2 aria-hidden className="size-4 animate-spin" /> : <LogOut aria-hidden className="size-4" strokeWidth={1.5} />}
+      Sign out
+    </Button>
+  );
+}

package/blocks/_foundation/components/confirm-spend-dialog.tsx

@@ -39,6 +39,13 @@ const TIER_COPY: Record<ConfirmTier, { badge: string; confirm: string; note: str
 };
 
 /** True for the tiers an app should confirm before calling. read/write never need it. */
+/** The tier badge: ember for what cannot be undone, ochre for spend and outreach. Token classes only. */
+const TIER_BADGE: Record<ConfirmTier, string> = {
+  billable: "bg-warning text-warning-foreground",
+  external: "bg-warning text-warning-foreground",
+  destructive: "bg-error text-error-foreground",
+};
+
 export function tierRequiresConfirmation(tier: string): tier is ConfirmTier {
   return tier === "billable" || tier === "external" || tier === "destructive";
 }
@@ -83,7 +90,7 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
         showCloseButton={false}
         data-tier={tier}
         style={interactive}
-        className={`max-w-md sm:max-w-md bg-white p-5 shadow-xl ${props.className ?? ""}`}
+        className={`max-w-md gap-4 border-border bg-background p-5 shadow-xl sm:max-w-md ${props.className ?? ""}`}
         onOpenAutoFocus={(event) => {
           event.preventDefault();
           openerRef.current = document.activeElement instanceof HTMLElement ? document.activeElement : null;
@@ -98,15 +105,15 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
         onInteractOutside={(event) => event.preventDefault()}
         onEscapeKeyDown={(event) => confirming && event.preventDefault()}
       >
-        <span className="inline-block w-fit rounded bg-gray-100 px-2 py-0.5 text-xs font-medium text-gray-700">
+        <span className={`inline-flex h-5 w-fit items-center rounded-full px-2 text-[11px] font-medium leading-none ${TIER_BADGE[tier]}`}>
           {copy.badge}
         </span>
-        <DialogTitle className="text-base font-semibold text-gray-900">{title}</DialogTitle>
+        <DialogTitle className="text-base font-medium leading-6 text-foreground">{title}</DialogTitle>
         <DialogDescription asChild>
-          <div className="space-y-2 text-sm text-gray-600">
+          <div className="space-y-2 text-sm leading-5 text-muted-foreground">
             {description ? <div>{description}</div> : null}
             {summary.length > 0 ? (
-              <ul className="list-disc pl-5 text-gray-900">
+              <ul className="list-disc space-y-0.5 pl-5 tabular-nums text-foreground">
                 {summary.map((line) => (
                   <li key={line}>{line}</li>
                 ))}
@@ -115,14 +122,14 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
             <p>{copy.note}</p>
           </div>
         </DialogDescription>
-        <div className="flex justify-end gap-2">
+        <div className="flex justify-end gap-2 pt-1">
           <button
             ref={cancelRef}
             type="button"
             disabled={confirming}
             onClick={onCancel}
             style={interactive}
-            className="rounded border border-gray-300 px-3 py-1.5 text-sm text-gray-700 disabled:opacity-50"
+            className="inline-flex h-8 items-center rounded-md border border-border bg-background px-3 text-sm font-medium text-foreground transition-colors hover:bg-surface-hover focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring disabled:opacity-50"
           >
             {props.cancelLabel ?? "Cancel"}
           </button>
@@ -131,7 +138,7 @@ export function ConfirmSpendDialog(props: ConfirmSpendDialogProps) {
             disabled={confirming}
             onClick={onConfirm}
             style={interactive}
-            className="rounded bg-gray-900 px-3 py-1.5 text-sm font-medium text-white disabled:opacity-50"
+            className={`inline-flex h-8 items-center rounded-md px-3 text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:opacity-50 ${tier === "destructive" ? "bg-destructive text-destructive-foreground hover:bg-destructive/90" : "bg-primary text-primary-foreground hover:bg-primary/90"}`}
           >
             {confirming ? "Working..." : (props.confirmLabel ?? copy.confirm)}
           </button>