feat: Pro requires a tenant contact address - gated at plan entry, never as a runtime lockout

Backend: POST config/{id}/trial now denies with 409 ContactEmailRequired
when no contact address is stored (extracted EvaluateTrialStart verdict,
order test-pinned: consumed/already-Pro win over the contact prompt). The
gate is live at the API even while the trial CTA stays behind its
"coming soon" flag; GA plan assignment stays unblocked by design. The
feature-flags payload gains contactEmailSet (bool only, never the
address - contract test updated).

Web: trial CTA shows a "set a contact address first" note instead of the
start button when the flag flips on; dashboard gets an amber non-blocking
banner for Pro tenants without a contact (admins only, fail-safe: only an
explicit contactEmailSet:false nags, so loading/error/older-backend states
stay quiet); GA tenant editor warns when assigning Pro to a tenant
without a contact address.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

src/Backend/AutopilotMonitor.Functions.Tests/GetTenantFeatureFlagsPayloadTests.cs

@@ -38,6 +38,9 @@ public class GetTenantFeatureFlagsPayloadTests
             // self-service migration banner).
             "appHomingFunnelActive",
             "bootstrapTokenEnabled",
+            // Non-sensitive by review: bool only ("is a contact address set"), never the
+            // address itself (admin-gated full config only).
+            "contactEmailSet",
             "diagnosticsUploadConfigured",
             "edition",
             "enableIntegrityBypassAnalyzer",
@@ -249,4 +252,27 @@ public class GetTenantFeatureFlagsPayloadTests
         Assert.False(element.GetProperty("isTrial").GetBoolean());
         Assert.False(element.GetProperty("trialAvailable").GetBoolean(), "consumed trial must not be offered again");
     }
+
+    // ── contactEmailSet (drives the Pro-requires-contact trial gate + banner) ──
+
+    [Theory]
+    [InlineData(null, false)]
+    [InlineData("", false)]
+    [InlineData("   ", false)]
+    [InlineData("it-ops@contoso.com", true)]
+    public void Payload_ContactEmailSet_ReflectsWhetherAnAddressIsStored(string? stored, bool expected)
+    {
+        var element = Serialize(new TenantConfiguration { ContactEmail = stored });
+
+        Assert.Equal(expected, element.GetProperty("contactEmailSet").GetBoolean());
+    }
+
+    [Fact]
+    public void Payload_ContactEmailSet_NeverLeaksTheAddress()
+    {
+        var json = JsonSerializer.Serialize(GetTenantFeatureFlagsFunction.BuildPayload(
+            new TenantConfiguration { ContactEmail = "secret-contact@contoso.com" }, Now));
+
+        Assert.DoesNotContain("secret-contact", json);
+    }
 }

src/Backend/AutopilotMonitor.Functions.Tests/PlanManagementTrialGateTests.cs

@@ -0,0 +1,76 @@
+using AutopilotMonitor.Functions.Functions.Config;
+using AutopilotMonitor.Shared.Models;
+
+namespace AutopilotMonitor.Functions.Tests;
+
+/// <summary>
+/// Tests for <see cref="PlanManagementFunction.EvaluateTrialStart"/> — the self-service
+/// trial verdict, including the Pro-requires-contact gate. The check ORDER is semantic
+/// and pinned here: terminal conditions (consumed / already Pro) must win over the
+/// contact-address prompt, and the contact gate exists only at this entry point (never
+/// as a runtime lockout for existing Pro tenants).
+/// </summary>
+public class PlanManagementTrialGateTests
+{
+    private static readonly DateTime Now = new(2026, 8, 2, 12, 0, 0, DateTimeKind.Utc);
+    private const string Contact = "it-ops@contoso.com";
+
+    [Fact]
+    public void Allowed_WhenCommunityWithContactAndUnconsumedTrial()
+    {
+        var config = new TenantConfiguration { ContactEmail = Contact };
+
+        Assert.Null(PlanManagementFunction.EvaluateTrialStart(config, Now));
+    }
+
+    [Theory]
+    [InlineData(null)]
+    [InlineData("")]
+    [InlineData("   ")]
+    public void Denied_ContactEmailRequired_WhenNoAddressStored(string? contact)
+    {
+        var config = new TenantConfiguration { ContactEmail = contact };
+
+        var deny = PlanManagementFunction.EvaluateTrialStart(config, Now);
+
+        Assert.Equal("ContactEmailRequired", deny?.Error);
+    }
+
+    [Fact]
+    public void Denied_TrialAlreadyConsumed_WinsOverMissingContact()
+    {
+        // A consumed trial is terminal — prompting for a contact address would be pointless.
+        var config = new TenantConfiguration { TrialConsumed = true, ContactEmail = null };
+
+        var deny = PlanManagementFunction.EvaluateTrialStart(config, Now);
+
+        Assert.Equal("TrialAlreadyConsumed", deny?.Error);
+    }
+
+    [Fact]
+    public void Denied_AlreadyPro_WinsOverMissingContact()
+    {
+        // Existing Pro tenants without a contact address are nagged via the dashboard
+        // banner, never blocked — the verdict must name the Pro state, not the address.
+        var config = new TenantConfiguration { PlanTier = "pro", ContactEmail = null };
+
+        var deny = PlanManagementFunction.EvaluateTrialStart(config, Now);
+
+        Assert.Equal("AlreadyPro", deny?.Error);
+    }
+
+    [Fact]
+    public void Denied_AlreadyPro_ForActiveTrialEdition()
+    {
+        var config = new TenantConfiguration
+        {
+            TrialExpiresUtc = Now.AddDays(5),
+            TrialConsumed = false, // hypothetical shape — edition resolution alone must deny
+            ContactEmail = Contact,
+        };
+
+        var deny = PlanManagementFunction.EvaluateTrialStart(config, Now);
+
+        Assert.Equal("AlreadyPro", deny?.Error);
+    }
+}

src/Backend/AutopilotMonitor.Functions/Functions/Config/GetTenantFeatureFlagsFunction.cs

@@ -113,6 +113,10 @@ namespace AutopilotMonitor.Functions.Functions.Config
                 isTrial,
                 trialExpiresUtc = isTrial ? config.TrialExpiresUtc : null,
                 trialAvailable = !config.TrialConsumed && edition == TenantEdition.Community,
+                // Pro-requires-contact surface: drives the trial CTA gate and the dashboard
+                // "set a contact address" banner for Pro tenants. Boolean only — the address
+                // itself stays in the admin-gated full config response.
+                contactEmailSet = !string.IsNullOrWhiteSpace(config.ContactEmail),
                 entitlements = new
                 {
                     retentionCapDays = entitlements.RetentionCapDays,

src/Backend/AutopilotMonitor.Functions/Functions/Config/PlanManagementFunction.cs

@@ -4,6 +4,7 @@ using AutopilotMonitor.Functions.Helpers;
 using AutopilotMonitor.Functions.Security;
 using AutopilotMonitor.Functions.Services;
 using AutopilotMonitor.Shared.DataAccess;
+using AutopilotMonitor.Shared.Models;
 using AutopilotMonitor.Shared.Models.Config;
 using Microsoft.Azure.Functions.Worker;
 using Microsoft.Azure.Functions.Worker.Http;
@@ -199,6 +200,36 @@ namespace AutopilotMonitor.Functions.Functions.Config
         /// 30-day Pro trial, exactly once per tenant. 409 when the trial was already
         /// consumed or the tenant is already effectively Pro.
         /// </summary>
+        /// <summary>
+        /// Pure verdict for the self-service trial start; null = allowed. Order matters and is
+        /// test-pinned: the terminal conditions (trial consumed, already Pro) win over the
+        /// contact-address prompt — asking for an address would be pointless there. The contact
+        /// requirement is enforced ONLY at this plan entry point, never as a runtime gate on Pro
+        /// features (existing Pro tenants get the dashboard banner instead of a lockout); GA
+        /// plan assignment (PATCH plan) deliberately has no such block — the admin UI warns.
+        /// </summary>
+        internal static (string Error, string Message)? EvaluateTrialStart(TenantConfiguration config, DateTime nowUtc)
+        {
+            if (config.TrialConsumed)
+            {
+                return ("TrialAlreadyConsumed",
+                    "This tenant has already used its one self-service Pro trial. Contact support to extend.");
+            }
+
+            if (FeatureEntitlementCatalog.ResolveEdition(config.PlanTier, config.TrialExpiresUtc, nowUtc) == TenantEdition.Pro)
+            {
+                return ("AlreadyPro", "This tenant is already on the Pro plan.");
+            }
+
+            if (string.IsNullOrWhiteSpace(config.ContactEmail))
+            {
+                return ("ContactEmailRequired",
+                    "Pro requires a tenant contact address so we can reach you about service or security matters. Set it under Settings → Tenant → Contact, then start the trial.");
+            }
+
+            return null;
+        }
+
         [Function("StartTenantTrial")]
         public async Task<HttpResponseData> StartTrial(
             [HttpTrigger(AuthorizationLevel.Anonymous, "post", Route = "config/{tenantId}/trial")] HttpRequestData req,
@@ -220,25 +251,10 @@ namespace AutopilotMonitor.Functions.Functions.Config
 
                 var nowUtc = _time.GetUtcNow().UtcDateTime;
 
-                if (config.TrialConsumed)
+                if (EvaluateTrialStart(config, nowUtc) is { } deny)
                 {
                     var conflict = req.CreateResponse(HttpStatusCode.Conflict);
-                    await conflict.WriteAsJsonAsync(new
-                    {
-                        error = "TrialAlreadyConsumed",
-                        message = "This tenant has already used its one self-service Pro trial. Contact support to extend."
-                    });
-                    return conflict;
-                }
-
-                if (FeatureEntitlementCatalog.ResolveEdition(config.PlanTier, config.TrialExpiresUtc, nowUtc) == TenantEdition.Pro)
-                {
-                    var conflict = req.CreateResponse(HttpStatusCode.Conflict);
-                    await conflict.WriteAsJsonAsync(new
-                    {
-                        error = "AlreadyPro",
-                        message = "This tenant is already on the Pro plan."
-                    });
+                    await conflict.WriteAsJsonAsync(new { error = deny.Error, message = deny.Message });
                     return conflict;
                 }
 

src/Web/autopilot-monitor-web/app/admin/components/TenantManagementSection.tsx

@@ -774,6 +774,14 @@ function TenantManagementSectionInner({
                         Stored legacy tier "{editingTenant.planTier}" resolves to Community. Saving normalizes it.
                       </p>
                     )}
+                    {(editingTenant.planTier === "pro" || editingTenant.planTier === "enterprise") && !editingTenant.contactEmail && (
+                      <p className="text-xs text-amber-600 mt-1">
+                        ⚠ No contact address set — Pro tenants should be reachable for service and
+                        security matters. Self-service trials are blocked without one; GA assignment
+                        is not, and the tenant sees a dashboard reminder until an admin sets it
+                        (Settings → Tenant → Contact).
+                      </p>
+                    )}
                   </div>
                   <div>
                     <label className="block text-sm font-medium text-gray-700 mb-1">Trial Ends (UTC)</label>

src/Web/autopilot-monitor-web/app/dashboard/hooks/useTenantSecurityConfig.ts

@@ -16,6 +16,8 @@ type AddNotification = (
 
 interface TenantConfigurationSummary {
   validateAutopilotDevice: boolean;
+  edition?: string;
+  contactEmailSet?: boolean;
 }
 
 interface User {
@@ -24,11 +26,22 @@ interface User {
   role?: string | null;
 }
 
+export interface TenantSecuritySummary {
+  /** null while loading or on error; the red banner keys on `=== false`. */
+  serialValidationEnabled: boolean | null;
+  /**
+   * Pro tenant (incl. trial) with no stored contact address — drives the amber
+   * "set a contact address" banner. Requires an EXPLICIT contactEmailSet:false from
+   * the backend, so loading/error/older-backend states never nag.
+   */
+  proContactMissing: boolean;
+}
+
 /**
- * Fetches the tenant's security config (validateAutopilotDevice flag) to drive the
- * "Autopilot Device Validation is disabled" banner on the dashboard.
+ * Fetches the tenant's feature-flags summary to drive the dashboard banners:
+ * the red "Autopilot Device Validation is disabled" banner and the amber
+ * Pro-without-contact-address banner.
  *
- * Returns null while loading, true/false once resolved, or null on error.
  * Skips the fetch for regular users (they never see the dashboard).
  */
 export function useTenantSecurityConfig(
@@ -36,8 +49,11 @@ export function useTenantSecurityConfig(
   user: User | null | undefined,
   getAccessToken: (forceRefresh?: boolean) => Promise<string | null>,
   addNotification: AddNotification,
-): boolean | null {
-  const [serialValidationEnabled, setSerialValidationEnabled] = useState<boolean | null>(null);
+): TenantSecuritySummary {
+  const [summary, setSummary] = useState<TenantSecuritySummary>({
+    serialValidationEnabled: null,
+    proContactMissing: false,
+  });
 
   useEffect(() => {
     // Wait until both tenant and user are resolved. Without the !user guard
@@ -54,17 +70,22 @@ export function useTenantSecurityConfig(
         const response = await dedupedAuthFetch(api.config.featureFlags(tenantId), getAccessToken);
 
         if (!response.ok) {
-          setSerialValidationEnabled(null);
+          setSummary({ serialValidationEnabled: null, proContactMissing: false });
           return;
         }
 
         const data: TenantConfigurationSummary = await response.json();
-        setSerialValidationEnabled(!!data.validateAutopilotDevice);
+        setSummary({
+          serialValidationEnabled: !!data.validateAutopilotDevice,
+          proContactMissing:
+            (data.edition === "pro" || data.edition === "enterprise") &&
+            data.contactEmailSet === false,
+        });
       } catch (error) {
         if (error instanceof TokenExpiredError) {
           addNotification('error', 'Session Expired', error.message, 'session-expired-error');
         }
-        setSerialValidationEnabled(null);
+        setSummary({ serialValidationEnabled: null, proContactMissing: false });
       }
     };
 
@@ -77,5 +98,5 @@ export function useTenantSecurityConfig(
     // eslint-disable-next-line react-hooks/exhaustive-deps
   }, [tenantId, user?.isTenantAdmin, user?.isGlobalAdmin, user?.role]);
 
-  return serialValidationEnabled;
+  return summary;
 }

src/Web/autopilot-monitor-web/app/dashboard/page.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { sessionUrl } from "@/lib/routes";
+import Link from "next/link";
 import { Suspense, useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { useRouter, useSearchParams } from "next/navigation";
 import { ProtectedRoute } from "../../components/ProtectedRoute";
@@ -188,7 +189,7 @@ function HomeContent() {
     }
   }, [user, router]);
 
-  const serialValidationEnabled = useTenantSecurityConfig(tenantId, user, getAccessToken, addNotification);
+  const { serialValidationEnabled, proContactMissing } = useTenantSecurityConfig(tenantId, user, getAccessToken, addNotification);
   const rawTenantList = useTenantList(crossTenant, getAccessToken);
   // Delegated: bound the tenant filter's autocomplete to the managed subset (defense in depth on top of the
   // backend-bounded config/all), plus the caller's own HOME tenant when they hold a member role there —
@@ -363,6 +364,30 @@ function HomeContent() {
             </div>
           )}
 
+          {/* Pro-requires-contact nag (amber, non-blocking): Pro tenants keep every feature,
+              but should be reachable. Admins only — they own the Contact section; delegated
+              admins are excluded (the link would target their own tenant, not the viewed one). */}
+          {proContactMissing && !isDelegated && (user?.isTenantAdmin || user?.isGlobalAdmin) && (
+            <div className="mb-6 bg-amber-50 border border-amber-300 rounded-lg px-4 py-3 flex flex-col sm:flex-row sm:items-center sm:justify-between gap-3 dark:bg-amber-950/30 dark:border-amber-700/50">
+              <div className="flex items-start gap-3">
+                <svg className="w-4 h-4 text-amber-500 mt-0.5 shrink-0" fill="none" stroke="currentColor" viewBox="0 0 24 24">
+                  <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={2} d="M12 9v2m0 4h.01M10.29 3.86L1.82 18a2 2 0 001.71 3h16.94a2 2 0 001.71-3L13.71 3.86a2 2 0 00-3.42 0z" />
+                </svg>
+                <p className="text-sm text-amber-800 dark:text-amber-300">
+                  <span className="font-semibold">Your Pro tenant has no contact address.</span>{" "}
+                  Set one so we can reach you about service or security matters — it is used for
+                  nothing else and never shared.
+                </p>
+              </div>
+              <Link
+                href="/settings/tenant/contact"
+                className="shrink-0 inline-flex items-center gap-2 bg-amber-600 text-white font-medium text-sm px-3 py-1.5 rounded-lg hover:bg-amber-700 transition-colors"
+              >
+                Set contact address
+              </Link>
+            </div>
+          )}
+
           {/* Stats cards — server-aggregated (see useDashboardStats).
               `dashboardStats === null` covers both initial load and post-scope-change
               reset; show a non-zero placeholder so a fetch error doesn't masquerade

src/Web/autopilot-monitor-web/app/settings/tenant/sections/SectionPlan.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import { useState } from "react";
+import Link from "next/link";
 import { useTenantConfig } from "../../TenantConfigContext";
 import { trialDaysLeft } from "@/lib/edition";
 
@@ -221,6 +222,17 @@ export function SectionPlan() {
                   >
                     Start 30-day Pro trial — coming soon
                   </button>
+                ) : canStartTrial && !editionInfo.contactEmailSet ? (
+                  // Pro-requires-contact gate (backend enforces the same via 409
+                  // ContactEmailRequired — this branch just makes the path obvious).
+                  <div className="text-sm bg-amber-50 border border-amber-200 rounded-lg p-3 text-amber-900 dark:bg-amber-950/30 dark:border-amber-700/50 dark:text-amber-200">
+                    <span className="font-medium">Pro requires a contact address.</span>{" "}
+                    Set one under{" "}
+                    <Link href="/settings/tenant/contact" className="font-medium text-purple-700 hover:underline dark:text-purple-300">
+                      Contact
+                    </Link>{" "}
+                    so we can reach you about service or security matters — then start your trial here.
+                  </div>
                 ) : canStartTrial && !confirming ? (
                   <button
                     type="button"

src/Web/autopilot-monitor-web/lib/__tests__/edition.test.ts

@@ -54,6 +54,14 @@ describe("parseEditionInfo", () => {
     expect(info.entitlements.retentionCapDays).toBe(90);
     expect(info.entitlements.userRateLimitPerMinute).toBeNull();
   });
+
+  it("contactEmailSet: only an explicit false means missing (fail-safe against older backends)", () => {
+    // Missing field (backend predates it) or malformed → true: never nag on unknown state.
+    expect(parseEditionInfo({ edition: "pro" }).contactEmailSet).toBe(true);
+    expect(parseEditionInfo({ edition: "pro", contactEmailSet: "no" }).contactEmailSet).toBe(true);
+    expect(parseEditionInfo({ edition: "pro", contactEmailSet: true }).contactEmailSet).toBe(true);
+    expect(parseEditionInfo({ edition: "pro", contactEmailSet: false }).contactEmailSet).toBe(false);
+  });
 });
 
 describe("trialDaysLeft", () => {

src/Web/autopilot-monitor-web/lib/edition.ts

@@ -13,6 +13,11 @@ export interface EditionInfo {
   isTrial: boolean;
   trialExpiresUtc: string | null;
   trialAvailable: boolean;
+  /**
+   * Whether a tenant contact address is stored (boolean only — the address itself is
+   * admin-gated). Drives the Pro-requires-contact trial gate and dashboard banner.
+   */
+  contactEmailSet: boolean;
   entitlements: {
     retentionCapDays: number;
     userRateLimitPerMinute: number | null;
@@ -27,6 +32,9 @@ export const COMMUNITY_DEFAULT: EditionInfo = {
   isTrial: false,
   trialExpiresUtc: null,
   trialAvailable: false,
+  // Fail-SAFE true (unlike the fail-closed entitlements): while flags are loading, on
+  // error, or against an older backend without the field, no nag banner may appear.
+  contactEmailSet: true,
   entitlements: {
     retentionCapDays: 90,
     userRateLimitPerMinute: null,
@@ -53,6 +61,8 @@ export function parseEditionInfo(flags: unknown): EditionInfo {
     isTrial: f.isTrial === true,
     trialExpiresUtc: typeof f.trialExpiresUtc === "string" ? f.trialExpiresUtc : null,
     trialAvailable: f.trialAvailable === true,
+    // Only an explicit false means "missing" — absent field (older backend) must not nag.
+    contactEmailSet: f.contactEmailSet !== false,
     entitlements: {
       retentionCapDays:
         typeof ent.retentionCapDays === "number" ? ent.retentionCapDays : COMMUNITY_DEFAULT.entitlements.retentionCapDays,