docs: add optional manual Front Door onboarding and failover findings

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Hou Chi Chan

README.md

@@ -6,6 +6,13 @@ by SMS or voice. Start here to onboard **one deployment in one Azure region**.
 For implementation details, configuration, packaging, and security behavior, see the
 [technical reference](TECHNICAL.md).
 
+## Deployment options
+
+| Option | Onboarding |
+|---|---|
+| Single region | Follow the guided steps below; `Setup-Epp.ps1` deploys one endpoint. |
+| Multiple regions behind Azure Front Door | Follow the [optional manual guide](docs/FRONTDOOR.md). No Front Door setup script is provided; a separately implemented readiness endpoint and coordinated regional configuration are required. |
+
 ## What you will set up
 
 You will connect a provider account to a dedicated Azure Function endpoint, validate SMS or voice
@@ -37,8 +44,9 @@ return **401 or 403**; neither is a successful evaluation.
 Choose a region with available Linux Premium EP1 capacity and sufficient quota in your subscription.
 
 Application Insights provides operational telemetry. Provider API keys stay in Key Vault; supported
-OAuth integrations use managed identity. This guide covers only the single-region topology shown
-above. Multi-region deployment, failover, and resiliency guidance are deferred.
+OAuth integrations use managed identity. The guided steps below cover the single-region topology
+shown above. For one public URL backed by multiple regional origins, see the
+[manual Front Door option](docs/FRONTDOOR.md), including its observed transition failures.
 
 ## Before you start
 
@@ -222,6 +230,7 @@ application behavior or configuration details, use the technical documentation b
 
 ## More documentation
 
+- [Optional manual Azure Front Door onboarding](docs/FRONTDOOR.md) - regional origins, readiness, security, validation, and failover limitations; no automation supplied.
 - [Setup guide](setup/docs/README.md) - permissions, deployment prompts, validation, and manual rollback.
 - [Technical reference](TECHNICAL.md) - configuration, packages, provider behavior, and security.
 - [Detailed configuration and validation](docs/ONBOARDING.md) - local development and deployment checks.

TECHNICAL.md

@@ -3,6 +3,10 @@
 For the single-region customer deployment flow, start with the
 [main onboarding guide](README.md).
 
+Azure Front Door is an [optional manual multi-region design](docs/FRONTDOOR.md), not a feature
+enabled by the single-region setup script. Its additional readiness endpoint is not shipped in
+the release packages, and regional failover does not change the SendOtp contract.
+
 A provider-agnostic **OTP-delivery Azure Function** sample, implemented across multiple languages.
 Each language folder is a self-contained implementation of the **same design and the same
 [contract](docs/CONTRACT.md)**: one engine, drop-in provider adapters, env-provisioned config, and
@@ -273,6 +277,7 @@ authentication; [separate deployed security checks](docs/ONBOARDING.md#4-package
 
 - **[README.md](README.md)**: single-region customer onboarding.
 - **[docs/ONBOARDING.md](docs/ONBOARDING.md)**: detailed configuration, security, deployment, and validation.
+- **[docs/FRONTDOOR.md](docs/FRONTDOOR.md)**: optional manual multi-region onboarding and observed failover limitations.
 - **[docs/CONTRACT.md](docs/CONTRACT.md)**: the language-agnostic contract every implementation follows.
 - **[Application logs](docs/CONTRACT.md#application-logs)**: separate service events, per-request summaries,
   and the meaning of Microsoft, Function and provider identifier fields.

docs/CONTRACT.md

@@ -11,6 +11,11 @@ The design selects one provider per deployment. The HTTP Function owns the reque
 API-specific credentials, paths, headers, payloads, response rules, outcomes and safe failure
 classifications remain inside each provider implementation.
 
+An [optional manual Front Door topology](FRONTDOOR.md) can route this same API to regional origins.
+It does not change caller authentication, JWE validation, nonce semantics, or provider selection,
+and it does not add automatic provider failover or delivery deduplication. Any readiness endpoint
+is separate from this contract and must not deliver OTPs.
+
 ---
 
 ## 1. HTTP API

docs/FRONTDOOR.md

@@ -6,6 +6,11 @@ Provider (EPP) Function. Choose one language:
 [JavaScript](../javascript/README.md), [Python](../python/README.md), or [.NET](../dotnet/README.md).
 Use [CONTRACT.md](CONTRACT.md) for the full request contract and production limitations.
 
+For a single public URL backed by multiple regions, see the
+[optional manual Front Door guide](FRONTDOOR.md). That option requires customer-managed readiness,
+shared-key coordination, origin restrictions, and separate validation; this onboarding flow does
+not automate it.
+
 1. **Purchase a provider offer from Security Store.**
 
 	 Open **Security Store > Provider offers**, purchase an offer, and activate the provider account.

docs/ONBOARDING.md

@@ -5,6 +5,10 @@ selected provider per deployment. Target: .NET 8 isolated worker, Azure Function
 
 ## Setup and deployment
 
+For multiple regional origins behind one URL, see [manual Front Door onboarding](../docs/FRONTDOOR.md).
+No Front Door deployment script or readiness handler is supplied. The reported multi-region trials
+used JavaScript; validate an equivalent .NET readiness implementation and deployment separately.
+
 1. Follow [customer onboarding](../docs/ONBOARDING.md). Set `EPP_PROVIDER_NAME` to the selected
 	adapter's `Name` (`<adapter-id>` is only a placeholder).
 2. Consult the selected adapter in [Src/Providers/](Src/Providers/) for required credentials and

docs/images/multi-region-architecture.png

@@ -7,6 +7,10 @@ each provider owns its credentials, wire request, response interpretation, outco
 
 ## Setup
 
+For multiple regional origins behind one URL, see [manual Front Door onboarding](../docs/FRONTDOOR.md).
+The JavaScript evaluation trials used a separate readiness handler; it is not included in this
+sample's release package. No Front Door deployment script is supplied.
+
 1. Follow [customer onboarding](../docs/ONBOARDING.md). Choose a bundled provider and set
    `EPP_PROVIDER_NAME` to its fixed id; `<provider-id>` is a placeholder, not a default.
 2. Consult the selected implementation in [src/functions/providers/](src/functions/providers/)

dotnet/README.md

@@ -5,6 +5,10 @@ provider per deployment. Target: Python 3.11, Azure Functions v4, Python v2 prog
 
 ## Setup and deployment
 
+For multiple regional origins behind one URL, see [manual Front Door onboarding](../docs/FRONTDOOR.md).
+No Front Door deployment script or readiness handler is supplied. The reported multi-region trials
+used JavaScript; validate an equivalent Python readiness implementation and deployment separately.
+
 1. Follow [customer onboarding](../docs/ONBOARDING.md). Set `EPP_PROVIDER_NAME` to the selected
 	adapter's registered manifest id (`<adapter-id>` is only a placeholder).
 2. Consult the selected adapter and its manifest in [src/providers/](src/providers/) for required

javascript/README.md

@@ -7,9 +7,10 @@ The customer does not clone this repository or download Bicep/support scripts se
 `Setup-Epp.ps1` retrieves those files and the selected provider's JSON from GitHub.
 
 This guide deploys **one Function endpoint in one Azure region**. It does not provision Azure
-Front Door or a second region. A successful single-region deployment or encrypted evaluation
-does not establish cross-region failover or recovery; Front Door onboarding is deferred until
-that validation is complete.
+Front Door or a second region. For the optional multi-region design, use the
+[manual Front Door onboarding guide](../../docs/FRONTDOOR.md). No Front Door setup script is
+provided. Do not rerun this single-region flow as a substitute for shared-key and multi-origin
+coordination. A successful deployment or evaluation does not prove live delivery or seamless failover.
 
 ## Availability