@graph8/sdk 0.373.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 |

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

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,6 +150,13 @@
       "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",
@@ -270,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>
+  );
+}