@volter/twin-googleoauth 0.1.0

package/client/googleoauth-consent.tsx

@@ -0,0 +1,286 @@
+// Google's CONSENT SCREEN, as React — the vendor's own product UI, not a dashboard mirror.
+//
+// These components are the ONE renderer for the screen: the twin server-renders them with
+// `renderToStaticMarkup` to answer `GET /o/oauth2/v2/auth`, the capability verifies render the SAME
+// exported components over the SAME projection, and the Playwright journey drives the HTML they
+// emit. There is no second implementation to drift from.
+//
+// PROGRESSIVE ENHANCEMENT, DELIBERATELY. The whole flow is plain `<form>` submits — choosing an
+// account is a GET submit, Continue/Cancel are POST submits with a `decision` value. No JavaScript
+// is required to complete an OAuth round trip against this twin, which matters because the twin is
+// driven by headless browsers, by `curl`, and by library redirect-followers that execute nothing.
+// The bundled client (`hydrateConsentControls` below) only ADDS the granular-consent "select all"
+// affordance into an element that is EMPTY server-side, so there is no hydration mismatch to
+// stumble over.
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+
+export type ConsentAccount = {
+  sub: string;
+  email: string;
+  name: string;
+  givenName: string;
+  picture: string;
+  hd?: string;
+};
+
+export type ConsentScopeRow = {
+  scope: string;
+  label: string;
+  group: 'openid' | 'product';
+  sensitivity?: 'sensitive' | 'restricted';
+  known: boolean;
+  declinable: boolean;
+};
+
+export type ConsentApp = {
+  clientId: string;
+  name: string;
+  supportEmail: string;
+  verified: boolean;
+};
+
+/**
+ * Google's GRANULAR-CONSENT RULE, from its own documentation: the per-scope checkbox screen appears
+ * only when the request mixes a sign-in scope with a non-sign-in one, OR asks for two or more
+ * non-sign-in scopes. A single scope, or sign-in scopes alone, is all-or-nothing with no checkboxes
+ * at all. Modelling this matters: an integration that asks for exactly one product scope can never
+ * receive a partial grant, and a twin that offered a checkbox there would invent a code path the
+ * app will never see in production.
+ */
+export function granularConsentApplies(scopes: Array<{ declinable: boolean }>): boolean {
+  const nonSignIn = scopes.filter((s) => s.declinable).length;
+  const signIn = scopes.length - nonSignIn;
+  return nonSignIn >= 2 || (nonSignIn >= 1 && signIn >= 1);
+}
+
+export type ConsentView = {
+  step: 'choose' | 'consent';
+  requestId: string;
+  /** Where the twin is reachable — the form actions post back here. */
+  origin: string;
+  app: ConsentApp;
+  accounts: ConsentAccount[];
+  scopes: ConsentScopeRow[];
+  /** The chosen account; present on the `consent` step. */
+  account?: ConsentAccount;
+};
+
+/** The Google wordmark, drawn rather than fetched — a twin never reaches out to a vendor CDN. */
+function GoogleMark() {
+  return (
+    <div className="g-header">
+      <span className="g-mark" aria-hidden="true">
+        <span className="g-b">G</span>
+        <span className="g-r">o</span>
+        <span className="g-y">o</span>
+        <span className="g-b">g</span>
+        <span className="g-g">l</span>
+        <span className="g-r">e</span>
+      </span>
+      <span className="g-signin">Sign in with Google</span>
+    </div>
+  );
+}
+
+function Avatar({ account }: { account: ConsentAccount }) {
+  // The picture URL is a lh3.googleusercontent.com link the twin does NOT fetch (offline, always);
+  // the initial is the honest local stand-in for it, and the URL travels in the id_token where a
+  // real integration reads it.
+  return (
+    <span className="avatar" aria-hidden="true">
+      {(account.givenName || account.name || account.email).slice(0, 1).toUpperCase()}
+    </span>
+  );
+}
+
+/** STEP 1 — "Choose an account". Each account is a real submit button, so a click IS the choice. */
+export function AccountChooser({ view }: { view: ConsentView }) {
+  return (
+    <div className="card">
+      <GoogleMark />
+      <h1 className="title">Choose an account</h1>
+      <p className="subtitle">
+        to continue to <strong className="app-name">{view.app.name}</strong>
+      </p>
+      <form method="GET" action={`${view.origin}/_twin/consent`} className="account-list">
+        <input type="hidden" name="auth_request" value={view.requestId} />
+        {view.accounts.map((account) => (
+          <button key={account.sub} className="account-row" type="submit" name="sub" value={account.sub}>
+            <Avatar account={account} />
+            <span className="account-text">
+              <span className="account-name">{account.name}</span>
+              <span className="account-email">{account.email}</span>
+            </span>
+          </button>
+        ))}
+      </form>
+      <p className="legal">
+        To continue, Google will share your name, email address, language preference, and profile
+        picture with {view.app.name}.
+      </p>
+    </div>
+  );
+}
+
+/**
+ * The per-scope rows. Checkboxes appear only when `granularConsentApplies` says Google would show
+ * them; otherwise every scope is a fixed hidden input and the grant is all-or-nothing.
+ */
+export function ScopeList({ scopes, granular }: { scopes: ConsentScopeRow[]; granular?: boolean }) {
+  const checkboxes = granular ?? granularConsentApplies(scopes);
+  return (
+    <ul className="scope-list">
+      {scopes.map((row) => (
+        <li key={row.scope} className="scope-row">
+          {checkboxes && row.declinable ? (
+            <input type="checkbox" name="scope" value={row.scope} defaultChecked id={`scope-${row.scope}`} className="scope-check" />
+          ) : (
+            <input type="hidden" name="scope" value={row.scope} />
+          )}
+          <label htmlFor={checkboxes && row.declinable ? `scope-${row.scope}` : undefined} className="scope-label">
+            <span className="scope-text">{row.label}</span>
+            {row.sensitivity ? <span className="scope-tag">{row.sensitivity}</span> : null}
+            {row.known ? null : <span className="scope-tag scope-tag-unknown">not in the twin&apos;s scope catalog</span>}
+          </label>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** STEP 2 — the consent screen proper. */
+export function ConsentScreen({ view }: { view: ConsentView }) {
+  const account = view.account;
+  const granular = granularConsentApplies(view.scopes);
+  return (
+    <div className="card">
+      <GoogleMark />
+      <h1 className="title">
+        <strong className="app-name">{view.app.name}</strong> wants access to your Google Account
+      </h1>
+      {account ? (
+        <div className="chosen-account">
+          <Avatar account={account} />
+          <span className="account-email">{account.email}</span>
+        </div>
+      ) : null}
+      {view.app.verified ? null : (
+        <p className="unverified">Google hasn&apos;t verified this app</p>
+      )}
+      <p className="subtitle">
+        {granular ? `Select what ${view.app.name} can access` : `This will allow ${view.app.name} to:`}
+      </p>
+      <form method="POST" action={`${view.origin}/_twin/consent`} className="consent-form">
+        <input type="hidden" name="auth_request" value={view.requestId} />
+        <input type="hidden" name="sub" value={account?.sub ?? ''} />
+        {/* Empty server-side on purpose — the bundled client mounts the "Select all" affordance
+            here, so there is no server/client markup to disagree about. */}
+        {granular ? <div id="granular-consent-controls" /> : null}
+        <ScopeList scopes={view.scopes} granular={granular} />
+        <p className="legal">
+          Make sure you trust {view.app.name}. You may be sharing sensitive info with this site or
+          app. You can always see or remove access in your Google Account.
+        </p>
+        <div className="actions">
+          <button className="btn btn-text" type="submit" name="decision" value="deny">
+            Cancel
+          </button>
+          <button className="btn btn-primary" type="submit" name="decision" value="allow">
+            Continue
+          </button>
+        </div>
+      </form>
+      {/* Google hides the developer's details behind the app-name link, in a dialog headed
+          "Developer Information" with "App name:" and "Support email:" rows. A <details> is the
+          no-JavaScript equivalent of that disclosure. */}
+      <details className="support">
+        <summary>Developer Information</summary>
+        <p>App name: {view.app.name}</p>
+        <p>Support email: {view.app.supportEmail}</p>
+      </details>
+    </div>
+  );
+}
+
+/** The whole page body for either step — the single entry the server renders. */
+export function ConsentPage({ view }: { view: ConsentView }) {
+  return view.step === 'choose' ? <AccountChooser view={view} /> : <ConsentScreen view={view} />;
+}
+
+export type ErrorPageProps = {
+  status: number;
+  code: string;
+  summary: string;
+  detail: string;
+  /** The offending parameter Google echoes into its "Request details:" dialog. */
+  requestPath?: string;
+  /** The documentation URL Google links from the error page. */
+  docUrl?: string;
+  /** The app's registered name, when the failing request named a known client. */
+  appName?: string;
+};
+
+/**
+ * Google's OAuth error PAGE — what a browser sees when the twin cannot trust the redirect_uri and
+ * therefore must not bounce the error back to it. The heading reproduces Google's own
+ * "Error <status>: <code>" line, which is the string every integrator searches for.
+ */
+export function ErrorPage({ status, code, summary, detail, requestPath, docUrl, appName }: ErrorPageProps) {
+  return (
+    <div className="card card-error">
+      <GoogleMark />
+      <h1 className="title">{summary}</h1>
+      {detail.split('\n\n').map((paragraph, i) => (
+        <p className="error-detail" key={i}>
+          {paragraph}
+        </p>
+      ))}
+      <p className="error-code">
+        Error {status}: {code}
+      </p>
+      <details className="error-details">
+        <summary>
+          If you are a developer of {appName ?? 'this app'}, see error details.
+        </summary>
+        {requestPath ? <p className="error-request">Request details: {requestPath}</p> : null}
+        <p className="error-request">flowName=GeneralOAuthFlow</p>
+        {docUrl ? <p className="error-request">Related developer documentation: {docUrl}</p> : null}
+      </details>
+    </div>
+  );
+}
+
+/**
+ * The bundled browser entry. Mounts the granular-consent "select all" control into the
+ * server-rendered EMPTY `#granular-consent-controls` slot — an addition, never a re-render of
+ * server markup, so the no-JavaScript path and the enhanced path agree by construction.
+ */
+export function hydrateConsentControls(): void {
+  const slot = document.getElementById('granular-consent-controls');
+  if (!slot) return;
+  const boxes = () => Array.from(document.querySelectorAll<HTMLInputElement>('input.scope-check'));
+  if (boxes().length === 0) return;
+  // ONLY the pill. The "Select what <App> can access" heading is SERVER-RENDERED by
+  // `ConsentScreen`, so repeating it here would show it twice — which it did, until the journey's
+  // filmstrip made the duplication obvious. Google shows the heading once, with the pill beside it.
+  createRoot(slot).render(
+    <StrictMode>
+      <div className="granular-controls">
+        <button
+          className="btn btn-text"
+          type="button"
+          onClick={() => {
+            const all = boxes();
+            const target = all.some((b) => !b.checked);
+            for (const b of all) b.checked = target;
+          }}
+        >
+          Select all
+        </button>
+      </div>
+    </StrictMode>,
+  );
+}
+
+if (typeof document !== 'undefined') hydrateConsentControls();