feat: fluent API shorthand — client builders, resource setup, constants & response helpers#26
Merged
Merged
Conversation
…ants, and response helpers Phases 5-10 of the Client Builder Fluent Shorthand initiative: - Phase 5: SelfIssuing(key).As(iss, sub) fluent sub-builder replacing positional SelfIssued(key, iss, sub, kid) [marked Obsolete] - Phase 6: Enrolled(key).RefreshingFrom(...) for AP-enrolled clients - Phase 7: MapAAuthResource() unified middleware setup from DI options - Phase 8: All samples and docs updated to use new fluent APIs - Phase 9: AAuthConstants, AAuthTokenType enum, HttpContext extensions (GetAAuthVerification, GetAAuthParsedKey, GetAAuthTokenType) - Phase 10: Resource-side response helpers (ChallengeAAuth, SetAAuthError) All 648 tests pass (308 unit + 340 conformance). All AgentConsole workflows verified E2E (JWT, HWK, JWKS-URI, JKT-JWT, call-chain).
There was a problem hiding this comment.
Pull request overview
Phases 5–10 of the AAuth SDK fluent API initiative. Adds verb-form sub-builders for self-issued and AP-enrolled clients, a unified resource-side MapAAuthResource() pipeline, central protocol constants, an AAuthTokenType enum, and HttpContext extension helpers — replacing scattered string literals, manual Items[] casts, and multi-call middleware setup.
Changes:
- New fluent client builders:
AAuthClientBuilder.SelfIssuing(key).As(...)andAAuthClientBuilder.Enrolled(key).RefreshingFrom(...); legacySelfIssued(...)marked[Obsolete]. - New server-side surface:
AAuthConstants,AAuthTokenTypeenum (breaking change toAAuthVerificationResult.TokenType),AAuthHttpContextExtensions(GetAAuthVerification/GetAAuthParsedKey/GetAAuthTokenType/ChallengeAAuth/SetAAuthError), andapp.MapAAuthResource()unified pipeline. - SDK internals, samples, and docs broadly refactored to use the new constants, enum, and extension helpers; six new test files (~30+ tests added).
Show a summary per file
| File | Description |
|---|---|
| src/AAuth/AAuthConstants.cs | New centralized protocol constants. |
| src/AAuth/AAuthTokenType.cs | New token type enum + parse/format helpers. |
| src/AAuth/HttpSig/SelfIssuingBuilder.cs | New fluent sub-builder for self-issued identity. |
| src/AAuth/HttpSig/EnrolledBuilder.cs | New fluent sub-builder for AP-enrolled clients. |
| src/AAuth/HttpSig/AAuthClientBuilder.cs | Adds SelfIssuing/Enrolled factories, WithSelfIssuedToken, WithPersonServer; obsoletes SelfIssued. |
| src/AAuth/HttpSig/AAuthSigningHandler.cs | Header literals replaced with constants. |
| src/AAuth/HttpSig/SignatureKeyParser.cs | Scheme literals replaced with constants. |
| src/AAuth/HttpSig/DefaultSignatureKeyResolver.cs | Scheme literals replaced with constants. |
| src/AAuth/Server/AAuthHttpContextExtensions.cs | New typed accessors and response helpers. |
| src/AAuth/Server/AAuthVerificationMiddleware.cs | Uses new constants; stores AAuthTokenType enum. |
| src/AAuth/Server/AAuthVerificationResult.cs | TokenType changed to AAuthTokenType enum (breaking). |
| src/AAuth/Server/AAuthChallengeMiddleware.cs | Uses constants and enum for scheme/token-type comparisons. |
| src/AAuth/Agent/ChallengeHandler.cs | Header literals replaced with constants. |
| src/AAuth/Agent/NamingJwtBuilder.cs | Uses AAuthConstants.TokenTypes.NamingJwt. |
| src/AAuth/Discovery/ServerMetadata.cs | Uses AAuthConstants.DwkFiles. |
| src/AAuth/DependencyInjection/AAuthApplicationBuilderExtensions.cs | New MapAAuthResource() unified pipeline. |
| src/AAuth/DependencyInjection/AAuthResourcePipelineOptions.cs | New options class for the unified pipeline. |
| samples/Orchestrator/Program.cs | Uses SelfIssuing(...).As(...) and GetAAuthVerification(). |
| samples/WhoAmI/Program.cs | Uses extension helpers and ChallengeAAuth. |
| samples/MockPersonServer/Program.cs | Uses extension helpers and AAuthTokenType. |
| samples/GuidedTour/CodeSnippets.cs | Snippets migrated to new fluent API. |
| samples/SampleApp/Components/Pages/{Jwt,Hwk,JwksUri,Deferred,CallChain}.razor | Display and runtime snippets updated. |
| docs/**, README.md | Migrated examples to fluent shorthand and extension helpers. |
| tests/AAuth.Tests/AAuthConstantsTests.cs | Verifies new constants match existing builder fields. |
| tests/AAuth.Tests/AAuthTokenTypeTests.cs | Enum parse/format round-trip tests. |
| tests/AAuth.Tests/Server/AAuthHttpContextExtensionsTests.cs | Tests for the new HttpContext extensions. |
| tests/AAuth.Tests/HttpSig/SelfIssuingBuilderTests.cs | Tests for SelfIssuingBuilder. |
| tests/AAuth.Tests/HttpSig/EnrolledBuilderTests.cs | Tests for EnrolledBuilder. |
| tests/AAuth.Tests/HttpSig/AAuthClientBuilderSelfIssuedTests.cs | Tests for legacy + new self-issued paths. |
| .agent/plans/2026-05-28-self-issued-client-builder-shorthand/* | Research, implementation plan, before/after summary, plan log. |
Copilot's findings
- Files reviewed: 48/48 changed files
- Comments generated: 1
Alpha SDK — no need to keep deprecated API surface. - Remove SelfIssued(key, iss, sub, kid) static method entirely - Make WithSelfIssuedToken() internal (only used by SelfIssuingBuilder) - Delete duplicate test file (AAuthClientBuilderSelfIssuedTests) - Merge 4 unique tests into SelfIssuingBuilderTests - Remove WithSelfIssuedToken from public API docs 635 tests pass (295 unit + 340 conformance).
Addresses PR review comment — the test claimed to verify both header and status but only checked the header. Now asserts IStatusCodeHttpResult returns 401.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Fluent API improvements across the AAuth SDK (Phases 5–10), reducing verbosity for the three main developer surfaces: agent client construction, resource server setup, and endpoint request handling.
Key Changes
Agent-Side (Client Builder)
SelfIssued(key, iss, sub, kid)SelfIssuing(key).As(iss, sub)Enrolled(key).RefreshingFrom(...).WithCallChaining(ctx)Resource-Side (Server Setup)
app.MapAAuthResource()(reads from DI)ctx.ChallengeAAuth(rt)(string?)parsed.Header?["typ"]ctx.GetAAuthTokenType()ctx.Features.Get<AAuthVerificationResult>()ctx.GetAAuthVerification()ctx.Response.Headers[...] = msgctx.SetAAuthError(msg)Infrastructure
AAuthConstants— centralized protocol constants (headers, schemes, token types, DWK files)AAuthTokenTypeenum — type-safe token type withParseTokenType/ToHeaderValuehelpersAAuthHttpContextExtensions— typed access to verification results and protocol response helpersFiles Changed
Breaking Changes
AAuthVerificationResult.TokenTypechanged fromstring?toAAuthTokenTypeenumAAuthClientBuilder.SelfIssued(key, iss, sub, kid)removed (useSelfIssuing(key).As(iss, sub))AAuthClientBuilder.WithSelfIssuedToken()made internal (useSelfIssuing(key).As(iss, sub))Testing
All AgentConsole workflows pass E2E against live sample servers.