feat(auth): allowed_email_domains client surface + <SignIn> SSR sign-in errors (#418)

* feat(auth): add allowed_email_domains to auth settings (SDK + MCP + CLI)

Public client surface for the hosted-auth Workspace-domain allowlist.
Gateway enforcement lives in run402-private (feat/hosted-auth-domain-allowlist,
issue #440); this lets operators restrict hosted Google sign-in to specific
email domains, enforced server-side at token issuance.

- SDK: allowed_email_domains on AuthSettings/AuthSettingsResult, added to
  AUTH_SETTINGS_FIELDS + validateAuthSettings (shape check only; the gateway
  owns normalization + domain-syntax validation)
- MCP: allowed_email_domains on the auth_settings tool schema + rendered output
- CLI: run402 auth settings --allowed-email-domains <csv|none> ('none' clears,
  mirroring the existing --preferred null sentinel since parseFlag drops "")
- docs: llms-cli.txt command + R402_AUTH_DOMAIN_NOT_ALLOWED (403) catalog entry
- tests: 3 SDK + 1 MCP cases; full suite green

Refs #415

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* feat(astro): <SignIn> renders hosted sign-in errors server-side (no JS)

Companion to the gateway hosted-auth-signin-error-ssr change
(run402-private#442): a failed hosted OAuth sign-in returns to the sign-in
page with a server-readable ?r402_auth_error=<code>, and <SignIn> renders the
message with zero client JS and zero consumer code.

- sign-in-methods.ts: googleOauthHtml emits errorReturnTo on the start link;
  AUTH_ERROR_PARAM + messageForAuthError (specific copy for user-actionable
  codes, generic fallback otherwise) + .r402-auth-error styling.
- SignIn.astro: reads ?r402_auth_error from Astro.url, renders a role="alert"
  block in the multi-method branch; emits its own URL as errorReturnTo. The
  password-only default branch is untouched, so the byte-identical default
  render contract (6.1/6.3) is preserved.
- tests: alert render + absent + generic-fallback + builder/unit cases.
  Full astro suite 285/285; tsc build clean.
- README: "Hosted sign-in errors render themselves" DX section.

Refs #415

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: MajorTal

astro/README.md

@@ -312,6 +312,19 @@ Every auth error carries a structured envelope with a `next_actions[].fix` paylo
 
 Two pre-existing codes were enriched with `fix` payloads in this release (names unchanged): `R402_AUTH_CSRF_ORIGIN_MISMATCH` (submit from a Run402 component / same-origin form) and `R402_AUTH_PRERENDERED` (`export const prerender = false;`). At deploy time, `run402 doctor` statically detects a `createResponseFromTenantAssertion` call whose function lacks the `auth.sessionMint` capability and emits `R402_DOCTOR_AUTH_SESSION_MINT_CAPABILITY_MISSING` with the exact spec edit — catching the footgun before it becomes a runtime 403.
 
+### Hosted sign-in errors render themselves (`<SignIn>`)
+
+A failed hosted OAuth sign-in — e.g. a Google account whose domain is not in the project's `allowed_email_domains` (set via `run402 auth settings --allowed-email-domains …`) — is returned to your sign-in page with a **server-readable** `?r402_auth_error=<code>` query param, and `<SignIn>` renders the message for you. Server-side, **no client JS, zero extra code**:
+
+```astro
+---
+import { SignIn } from "@run402/astro/components";
+---
+<SignIn returnTo="/admin" methods={["google"]} />
+```
+
+A `@gmail.com` user rejected from a Workspace-restricted admin tool lands back on this page with "This site is restricted to approved email domains. Sign in with your work account." rendered above the form. `<SignIn>` emits its own URL as the error-return target on the OAuth start link, so the round-trip is automatic — you never touch a query param or the URL hash. Known codes (`domain_not_allowed`, `account_exists_requires_link`, `identity_already_linked`) get specific copy; anything else (transient/infra) falls back to a generic "Sign-in could not be completed. Please try again." The block carries `role="alert"` and the `.r402-auth-error` class — restyle via your own CSS or the `--r402-error-fg` / `--r402-error-bg` / `--r402-error-border` custom properties. With no error param the render is byte-identical to before — nothing extra ships.
+
 ## `<Run402Picture>` — runtime CMS images
 
 For images coming from a DB row at SSR time (the common CMS pattern), use `<Run402Picture asset={page.hero_asset}>`. The `asset` prop is the `AssetRef` JSONB that `r.assets.put()` returned at upload time — store the whole object, not just the URL, then render directly.

astro/src/components/SignIn.astro

@@ -58,6 +58,8 @@ import {
   buildExtraMethodsHtml,
   EXTRA_METHOD_CSS,
   PASSKEY_SCRIPT,
+  messageForAuthError,
+  AUTH_ERROR_PARAM,
 } from "./sign-in-methods.js";
 
 interface Props {
@@ -82,10 +84,22 @@ const defaultOnly = isDefaultOnly(methods);
 const resolved = normalizeMethods(methods);
 const hasPassword = includesPassword(resolved);
 const hasPasskey = resolved.includes("passkey");
+// hosted-auth-signin-error-ssr: a FAILED hosted OAuth sign-in returns the
+// visitor here with `?r402_auth_error=<code>` (a server-readable query param —
+// see the @run402/astro README). Render it server-side; no client JS. When the
+// param is absent nothing renders, and the default (password-only) branch never
+// touches it, so the byte-identical default contract (§6.1/§6.3) holds.
+const authErrorMessage = messageForAuthError(Astro.url.searchParams.get(AUTH_ERROR_PARAM));
+// Where the gateway returns a FAILED OAuth sign-in: this same sign-in page
+// (path only, so the error code can't accumulate across attempts). The gateway
+// validates it same-origin and delivers `?r402_auth_error=` there. Rides the
+// google start link below.
+const errorReturnTo = Astro.url.pathname;
+
 // Extra (non-password) method markup, divider-interleaved. A leading divider
 // is added when the password form was rendered just above (so "or" sits
 // between password and the next method).
-const extraMethodsHtml = buildExtraMethodsHtml(resolved, returnTo, hasPassword);
+const extraMethodsHtml = buildExtraMethodsHtml(resolved, returnTo, hasPassword, errorReturnTo);
 
 // §6.1/§6.3 byte-identical default: when `methods` is omitted or exactly
 // ["password"], the `defaultOnly` branch below renders the verbatim
@@ -132,6 +146,9 @@ const extraMethodsHtml = buildExtraMethodsHtml(resolved, returnTo, hasPassword);
 </form>
 ) : (
   <div class={`r402-sign-in-methods ${className}`.trim()} data-r402-sign-in-methods>
+    {authErrorMessage && (
+      <div class="r402-auth-error" role="alert">{authErrorMessage}</div>
+    )}
     {hasPassword && (
       <form
         method="POST"

astro/src/components/SignIn.test.ts

@@ -38,6 +38,7 @@ import {
   dividerHtml,
   PASSKEY_SCRIPT,
   DEFAULT_METHODS,
+  messageForAuthError,
 } from "./sign-in-methods.js";
 
 // ---------------------------------------------------------------------------
@@ -78,10 +79,15 @@ async function loadAstroComponent(astroFileUrl: URL): Promise<unknown> {
 async function render(
   astroFileUrl: URL,
   props: Record<string, unknown> = {},
+  requestUrl?: string,
 ): Promise<string> {
   const Component = await loadAstroComponent(astroFileUrl);
   const container = await AstroContainer.create();
-  return container.renderToString(Component as never, { props });
+  const opts: Record<string, unknown> = { props };
+  // Drives `Astro.url` so errorReturnTo emission + the ?r402_auth_error read are
+  // deterministic in tests (hosted-auth-signin-error-ssr).
+  if (requestUrl) opts.request = new Request(requestUrl);
+  return container.renderToString(Component as never, opts as never);
 }
 
 /** Astro derives the `astro-xxxxxxxx` scope hash from component source and
@@ -193,12 +199,18 @@ describe("SignIn.astro — methods rendering", () => {
     assert.doesNotMatch(dom, /<script/);
   });
 
-  it("(c) methods=['google'] renders an anchor href containing /auth/sign-in/oauth/google/start", async () => {
-    const html = await render(SIGNIN_URL, { returnTo: "/portal", methods: ["google"] });
+  it("(c) methods=['google'] renders an anchor href containing /auth/sign-in/oauth/google/start (+ errorReturnTo)", async () => {
+    const html = await render(
+      SIGNIN_URL,
+      { returnTo: "/portal", methods: ["google"] },
+      "https://app.example/auth/sign-in",
+    );
     const dom = markup(html);
+    // The start link carries returnTo AND errorReturnTo (this sign-in page), so
+    // a domain-rejected sign-in is delivered back here server-readably.
     assert.match(
       dom,
-      /<a class="r402-oauth r402-oauth-google" href="\/auth\/sign-in\/oauth\/google\/start\?returnTo=%2Fportal">Continue with Google<\/a>/,
+      /<a class="r402-oauth r402-oauth-google" href="\/auth\/sign-in\/oauth\/google\/start\?returnTo=%2Fportal&amp;errorReturnTo=%2Fauth%2Fsign-in">Continue with Google<\/a>/,
     );
     assert.doesNotMatch(dom, /action="\/auth\/sign-in"/);
     assert.doesNotMatch(dom, /<script/);
@@ -262,14 +274,56 @@ describe("SignIn.astro — methods rendering", () => {
   });
 
   it("returnTo is HTML-attribute-escaped where interpolated", async () => {
-    const html = await render(SIGNIN_URL, {
-      returnTo: '/a&b"c',
-      methods: ["magic_link", "google"],
-    });
+    const html = await render(
+      SIGNIN_URL,
+      { returnTo: '/a&b"c', methods: ["magic_link", "google"] },
+      "https://app.example/login",
+    );
     // magic-link hidden input value escaped
     assert.match(html, /name="returnTo" value="\/a&amp;b&quot;c"/);
-    // google href: encodeURIComponent then attribute-escape (& → &amp;)
-    assert.match(html, /href="\/auth\/sign-in\/oauth\/google\/start\?returnTo=%2Fa%26b%22c"/);
+    // google href: encodeURIComponent then attribute-escape (& → &amp;), plus the
+    // errorReturnTo (this page) appended as a second query param.
+    assert.match(html, /href="\/auth\/sign-in\/oauth\/google\/start\?returnTo=%2Fa%26b%22c&amp;errorReturnTo=%2Flogin"/);
+  });
+
+  // hosted-auth-signin-error-ssr: a failed hosted OAuth sign-in returns here with
+  // ?r402_auth_error=<code>; <SignIn> renders it server-side, no client JS.
+  it("renders an auth-error alert from ?r402_auth_error (server-side, no JS)", async () => {
+    const html = await render(
+      SIGNIN_URL,
+      { returnTo: "/admin", methods: ["google"] },
+      "https://app.example/auth/sign-in?r402_auth_error=domain_not_allowed",
+    );
+    const dom = stripScope(markup(html));
+    assert.match(
+      dom,
+      /<div class="r402-auth-error" role="alert">This site is restricted to approved email domains[^<]*<\/div>/,
+    );
+    // The message is in the SSR HTML — no script required to display it.
+    assert.doesNotMatch(dom, /<script/);
+  });
+
+  it("renders NO auth-error alert when ?r402_auth_error is absent", async () => {
+    const html = await render(
+      SIGNIN_URL,
+      { returnTo: "/admin", methods: ["google"] },
+      "https://app.example/auth/sign-in",
+    );
+    // The alert DIV is absent from the markup (the .r402-auth-error CSS rule
+    // still ships in the stylesheet, hence checking markup() not the full html).
+    assert.doesNotMatch(markup(html), /r402-auth-error/);
+  });
+
+  it("an unknown auth-error code falls back to the generic message", async () => {
+    const html = await render(
+      SIGNIN_URL,
+      { returnTo: "/admin", methods: ["google"] },
+      "https://app.example/auth/sign-in?r402_auth_error=token_exchange_failed",
+    );
+    assert.match(
+      stripScope(markup(html)),
+      /<div class="r402-auth-error" role="alert">Sign-in could not be completed[^<]*<\/div>/,
+    );
   });
 });
 
@@ -338,6 +392,13 @@ describe("sign-in-methods — markup builders", () => {
     );
   });
 
+  it("googleOauthHtml appends errorReturnTo when provided (hosted-auth-signin-error-ssr)", () => {
+    assert.equal(
+      googleOauthHtml("/portal", "/auth/sign-in"),
+      '<a class="r402-oauth r402-oauth-google" href="/auth/sign-in/oauth/google/start?returnTo=%2Fportal&amp;errorReturnTo=%2Fauth%2Fsign-in">Continue with Google</a>',
+    );
+  });
+
   it("passkeyButtonHtml emits the data hooks + escaped returnTo", () => {
     assert.equal(
       passkeyButtonHtml('/x"y'),
@@ -391,3 +452,24 @@ describe("sign-in-methods — markup builders", () => {
     assert.match(PASSKEY_SCRIPT, /catch \(_err\)/);
   });
 });
+
+describe("sign-in-methods — messageForAuthError (hosted-auth-signin-error-ssr)", () => {
+  it("returns null for no/empty code", () => {
+    assert.equal(messageForAuthError(null), null);
+    assert.equal(messageForAuthError(undefined), null);
+    assert.equal(messageForAuthError(""), null);
+  });
+
+  it("returns specific copy for user-actionable codes", () => {
+    assert.match(messageForAuthError("domain_not_allowed")!, /approved email domains/);
+    assert.match(messageForAuthError("account_exists_requires_link")!, /already exists/);
+    assert.match(messageForAuthError("identity_already_linked")!, /already linked/);
+  });
+
+  it("falls back to a generic message for infra/unknown codes", () => {
+    const generic = /could not be completed/;
+    assert.match(messageForAuthError("token_exchange_failed")!, generic);
+    assert.match(messageForAuthError("id_token_invalid")!, generic);
+    assert.match(messageForAuthError("totally_unknown_code")!, generic);
+  });
+});

astro/src/components/sign-in-methods.ts

@@ -101,11 +101,17 @@ export function magicLinkFormHtml(returnTo: string): string {
   );
 }
 
-/** `google` — a no-JS link/button to the hosted OAuth start route (GET). */
-export function googleOauthHtml(returnTo: string): string {
+/** `google` — a no-JS link/button to the hosted OAuth start route (GET).
+ *  `errorReturnTo` (hosted-auth-signin-error-ssr): the same-origin sign-in-page
+ *  URL the gateway returns to on a FAILED sign-in, with `?r402_auth_error=<code>`.
+ *  When provided it rides the start link so the error round-trip is zero-config. */
+export function googleOauthHtml(returnTo: string, errorReturnTo?: string): string {
   // The href is built with encodeURIComponent at render time; the resulting
   // string is then attribute-escaped so `&` becomes `&amp;` in the markup.
-  const href = escapeAttr(`/auth/sign-in/oauth/google/start?returnTo=${encodeURIComponent(returnTo)}`);
+  const qs =
+    `returnTo=${encodeURIComponent(returnTo)}` +
+    (errorReturnTo ? `&errorReturnTo=${encodeURIComponent(errorReturnTo)}` : "");
+  const href = escapeAttr(`/auth/sign-in/oauth/google/start?${qs}`);
   return `<a class="r402-oauth r402-oauth-google" href="${href}">Continue with Google</a>`;
 }
 
@@ -127,15 +133,15 @@ export function passkeyButtonHtml(returnTo: string): string {
  * between every adjacent pair across the full ordered method list (including
  * the password form, which the component owns).
  */
-export function buildMethodBlocks(methods: SignInMethod[], returnTo: string): string[] {
+export function buildMethodBlocks(methods: SignInMethod[], returnTo: string, errorReturnTo?: string): string[] {
   const out: string[] = [];
   for (const m of methods) {
     switch (m) {
       case "magic_link":
         out.push(magicLinkFormHtml(returnTo));
         break;
       case "google":
-        out.push(googleOauthHtml(returnTo));
+        out.push(googleOauthHtml(returnTo, errorReturnTo));
         break;
       case "passkey":
         out.push(passkeyButtonHtml(returnTo));
@@ -161,8 +167,9 @@ export function buildExtraMethodsHtml(
   methods: SignInMethod[],
   returnTo: string,
   passwordIsFirst: boolean,
+  errorReturnTo?: string,
 ): string {
-  const blocks = buildMethodBlocks(methods, returnTo);
+  const blocks = buildMethodBlocks(methods, returnTo, errorReturnTo);
   if (blocks.length === 0) return "";
   const divider = dividerHtml();
   const joined = blocks.join(divider);
@@ -303,4 +310,47 @@ export const EXTRA_METHOD_CSS = `
   .r402-passkey[hidden] {
     display: none;
   }
+  .r402-auth-error {
+    padding: 0.625rem 0.75rem;
+    font-size: 0.875rem;
+    color: var(--r402-error-fg, #8a1c1c);
+    background: var(--r402-error-bg, #fdecea);
+    border: 1px solid var(--r402-error-border, #f5c2c0);
+    border-radius: var(--r402-radius, 0.375rem);
+  }
 `;
+
+/**
+ * hosted-auth-signin-error-ssr: surfacing hosted sign-in errors in <SignIn>.
+ *
+ * On a FAILED hosted OAuth sign-in the gateway returns the visitor to the
+ * sign-in page with `?<AUTH_ERROR_PARAM>=<code>` — a SERVER-READABLE query param
+ * (not the legacy URL hash), so the no-JS SSR component renders a message with
+ * zero consumer code. The codes mirror the gateway callback's recoverable
+ * reasons (see the gateway's `redirectError`).
+ */
+export const AUTH_ERROR_PARAM = "r402_auth_error";
+
+/** Specific, user-actionable copy for codes a visitor can act on. Infra /
+ *  transient codes intentionally fall through to the generic message. */
+export const AUTH_ERROR_MESSAGES: Record<string, string> = {
+  domain_not_allowed:
+    "This site is restricted to approved email domains. Sign in with your work account.",
+  account_exists_requires_link:
+    "An account with this email already exists. Sign in with your original method, then link Google from your account settings.",
+  identity_already_linked:
+    "This Google account is already linked to a different account.",
+};
+
+const GENERIC_AUTH_ERROR = "Sign-in could not be completed. Please try again.";
+
+/**
+ * Map a delivered `r402_auth_error` code to user-facing copy. Returns null for
+ * no/empty code (nothing to show). Known user-actionable codes get specific
+ * copy; anything else (incl. infra codes like `token_exchange_failed`) gets a
+ * safe generic message rather than leaking a raw code or rendering blank.
+ */
+export function messageForAuthError(code: string | null | undefined): string | null {
+  if (!code) return null;
+  return AUTH_ERROR_MESSAGES[code] ?? GENERIC_AUTH_ERROR;
+}

cli/lib/auth.mjs

@@ -24,7 +24,7 @@ Subcommands:
   set-password --token <bearer> --new <password> [--current <password>] [--project <id>]
     Change, reset, or set a user's password. Requires the user's access_token.
 
-  settings [--allow-password-set <true|false>] [--preferred <method|null>] [--public-signup <policy>] [--require-admin-passkey <true|false>] [--project <id>]
+  settings [--allow-password-set <true|false>] [--preferred <method|null>] [--public-signup <policy>] [--require-admin-passkey <true|false>] [--allowed-email-domains <csv|none>] [--project <id>]
     Update project auth settings (requires service_key).
 
   passkey-register-options --token <bearer> --app-origin <origin> [--project <id>]
@@ -147,14 +147,19 @@ Options:
   --preferred <method|null>             password, magic_link, oauth_google, passkey, or null
   --public-signup <policy>              open, known_email, or invite_only
   --require-admin-passkey <true|false>  Require passkey auth for project_admin sessions
+  --allowed-email-domains <csv|none>    Restrict hosted Google sign-in to these domains; 'none' clears (unrestricted)
   --project <id>                        Project ID (defaults to active project)
 
 Notes:
   Requires the project's service_key (admin-level).
+  --allowed-email-domains is comma-separated (e.g. kychee.com,example.com); pass 'none' to clear.
+  Domains are normalized + validated server-side; hosted Google sign-in from any
+  other domain is rejected at token issuance (R402_AUTH_DOMAIN_NOT_ALLOWED).
 
 Examples:
   run402 auth settings --allow-password-set true
   run402 auth settings --preferred passkey --require-admin-passkey true
+  run402 auth settings --allowed-email-domains kychee.com,example.com
 `,
   "passkey-register-options": `run402 auth passkey-register-options — Create passkey registration options
 
@@ -253,8 +258,8 @@ const AUTH_FLAGS = {
     values: ["--token", "--new", "--current", "--project"],
   },
   settings: {
-    known: ["--allow-password-set", "--preferred", "--public-signup", "--require-admin-passkey", "--project", "--help", "-h"],
-    values: ["--allow-password-set", "--preferred", "--public-signup", "--require-admin-passkey", "--project"],
+    known: ["--allow-password-set", "--preferred", "--public-signup", "--require-admin-passkey", "--allowed-email-domains", "--project", "--help", "-h"],
+    values: ["--allow-password-set", "--preferred", "--public-signup", "--require-admin-passkey", "--allowed-email-domains", "--project"],
   },
   "passkey-register-options": {
     known: ["--token", "--app-origin", "--project", "--help", "-h"],
@@ -460,12 +465,14 @@ async function settings(args) {
   const requireAdminPasskey = parseOptionalBool(args, "--require-admin-passkey");
   const preferredRaw = parseFlag(args, "--preferred");
   const publicSignup = parseFlag(args, "--public-signup");
+  const domainsRaw = parseFlag(args, "--allowed-email-domains");
 
   if (
     allow === undefined &&
     requireAdminPasskey === undefined &&
     preferredRaw === null &&
-    publicSignup === null
+    publicSignup === null &&
+    domainsRaw === null
   ) {
     fail({
       code: "BAD_USAGE",
@@ -488,12 +495,23 @@ async function settings(args) {
     });
   }
 
+  // --allowed-email-domains: comma-separated list; the literal `none` clears the
+  // restriction (→ []); omitted preserves. Server normalizes + validates each entry.
+  let allowedEmailDomains;
+  if (domainsRaw !== null) {
+    allowedEmailDomains =
+      domainsRaw.trim().toLowerCase() === "none"
+        ? []
+        : domainsRaw.split(",").map((d) => d.trim()).filter((d) => d.length > 0);
+  }
+
   try {
     const patch = {
       allow_password_set: allow,
       preferred_sign_in_method: preferredRaw === "null" ? null : preferredRaw ?? undefined,
       public_signup: publicSignup ?? undefined,
       require_passkey_for_project_admin: requireAdminPasskey,
+      allowed_email_domains: allowedEmailDomains,
     };
     const data = await getSdk().auth.settings(projectId, patch);
     console.log(JSON.stringify({ ...patch, ...data }));