Expose invitation email binding through the Aspire API

[woksin]

Problem

AuthProxy configuration exposes Invite.EmailClaim, but both public WithInvite Aspire overloads omit it. Enabling recipient-bound invitations therefore requires bypassing the typed builder and spelling a raw environment variable.

Expected behavior

Expose the setting through the Aspire API with XML documentation and specs for URL-based and resource-based invite configuration.

Acceptance criteria

• Both invite configuration shapes can declare the email claim.
• Generated environment configuration binds to Cratis:AuthProxy:Invite:EmailClaim.
• Null or empty retains the released default.
• Documentation explains the opt-in recipient-binding meaning.
• Existing compiled consumers remain binary compatible.

Do not replace an existing CLR signature by only adding an optional parameter, which is binary-incompatible. Keep existing overloads and add a delegating overload or separate fluent extension. This is a small additive change suitable for the current minor release train.

[woksin]

Picking this up — recording intent before writing code, per convention.

Confirmed on main: Invite.EmailClaim exists in configuration (Source/AuthProxy/Configuration/Invite.cs:93), but no Aspire builder emits it. The recent invitation work (#97–#101) did not touch Source/Aspire at all.

Worth flagging that this is more than ergonomics. Source/AuthProxy/Invites/InvitationAttestationConfigurationValidator.cs:71-74 makes Invite.EmailClaim unconditionally required when signed invitation attestations are enabled — right next to an identical check for Invite.TenantClaim, which is exposed through Aspire. So an AppHost configured purely through the typed API, WithInvite(...).WithSignedInvitationAttestations(...), fails startup options validation. The Aspire path to the signed two-stage protocol is currently unreachable without a hand-spelled environment variable.

Shape: a new WithInviteEmailBinding(string emailClaim) fluent extension modelled on WithSignedInvitationAttestations (Source/Aspire/AuthProxyExtensions.cs:990), emitting Cratis__AuthProxy__Invite__EmailClaim. Because it composes after either WithInvite overload, one method covers both configuration shapes.

Deliberately not a parameter on the existing overloads: adding a trailing optional argument is binary breaking (C# bakes defaults into the call site), and a same-name overload differing only by that argument would make every existing call ambiguous (CS0121).

Specs in Source/Aspire.Specs/for_AuthProxyExtensions/when_binding_invitations_to_the_invited_email/, covering claim-set and claim-absent. Docs in Documentation/aspire/index.md. Label: minor.

[woksin]

Fixed in #102, released in v2.19.0.

WithInviteEmailBinding(string emailClaim) composes after either WithInvite overload and emits Cratis__AuthProxy__Invite__EmailClaim, so recipient binding is reachable from a typed AppHost. Not calling it, or passing an empty claim, writes nothing and retains the released default of no binding.

This also closes a hole in a shipped feature that the issue did not mention: InvitationAttestationConfigurationValidator requires Invite.EmailClaim unconditionally when signed invitation attestations are enabled, and that guard is genuinely reached — the validator returns early only when Invite.Attestation is null, WithSignedInvitationAttestations binds it non-null, and the options are registered with ValidateOnStart(). So WithInvite(...).WithSignedInvitationAttestations(...) previously failed startup validation with no typed way to satisfy it.

Deliberately a separate extension rather than a parameter on WithInvite: a trailing optional parameter is binary breaking, and a same-name overload differing only by it would make existing calls ambiguous (CS0121).

Gate: Debug and Release --no-incremental -warnaserror, 0 errors / 0 warnings; Aspire.Specs 68 passed. Mutation-verified — changing the emitted key reddens and_a_claim_is_named at its own assertion while and_no_claim_is_named stays green, and removing the empty-guard reddens exactly the other one.

Not verified: no AppHost was booted, so the startup-validation failure is established from the code paths rather than observed.