| | | 1 | | using ArturRios.Heimdall.Command.Services; |
| | | 2 | | using ArturRios.Heimdall.Shared.Security; |
| | | 3 | | using ArturRios.Jwt; |
| | | 4 | | using ArturRios.Util.WebApi.Security.Authentication; |
| | | 5 | | using ArturRios.Util.WebApi.Security.Interfaces; |
| | | 6 | | |
| | | 7 | | namespace ArturRios.Heimdall.WebApi.Security; |
| | | 8 | | |
| | | 9 | | /// <summary> |
| | | 10 | | /// Issues and validates UC-38's short-lived challenge token as the application's own ES256-signed |
| | | 11 | | /// JWT (FR-2F-07…FR-2F-10, NFR-17), signed with the same key as |
| | | 12 | | /// <see cref="JwtAuthTokenIssuer" />'s full tokens but built and read independently of it, since |
| | | 13 | | /// the two carry deliberately different claims. |
| | | 14 | | /// </summary> |
| | | 15 | | /// <remarks> |
| | | 16 | | /// <para> |
| | | 17 | | /// <b>Signature.</b> ES256 under any configured key, the current or the previous one, so a |
| | | 18 | | /// rotation does not void the challenges in flight. The configured keys are EC keys alone, so |
| | | 19 | | /// an HS256 challenge is refused (Threat Model TH-43). |
| | | 20 | | /// </para> |
| | | 21 | | /// <para> |
| | | 22 | | /// <b>Expiry.</b> Taken from <see cref="TwoFactorLifetimes.ChallengeToken" /> (10 minutes, |
| | | 23 | | /// NFR-17) rather than added to <see cref="JwtConfiguration" /> as a second environment |
| | | 24 | | /// variable: a full login token's lifetime is meant to be tuned per deployment, but a |
| | | 25 | | /// challenge token's is a security property of the use case itself, so there is no |
| | | 26 | | /// legitimate reason an operator would want it longer, and every reason to keep it fixed. |
| | | 27 | | /// </para> |
| | | 28 | | /// <para> |
| | | 29 | | /// It is read from that shared type rather than written here because the number is not this |
| | | 30 | | /// class's to choose. The App method would be served by a much shorter window — an |
| | | 31 | | /// authenticator generates a code on demand, so its holder really can finish UC-38 within |
| | | 32 | | /// moments of UC-11 returning the token. The Email method cannot: "within moments" is a |
| | | 33 | | /// claim about someone else's mail infrastructure, and FR-2F-03 already committed to |
| | | 34 | | /// tolerating ten minutes of it. Both methods share one challenge token, so its lifetime has |
| | | 35 | | /// to be the longer of the two, and it has to be the <em>same</em> ten minutes the code it |
| | | 36 | | /// was issued with gets — a shorter one silently retracted that tolerance and left a |
| | | 37 | | /// correct, unexpired code with nowhere to be presented, since FR-2F-10 makes second-factor |
| | | 38 | | /// verification the only endpoint that will take a challenge token. |
| | | 39 | | /// </para> |
| | | 40 | | /// <para> |
| | | 41 | | /// <b>Claims.</b> Built directly rather than through <see cref="IdentityUserMapper" />'s |
| | | 42 | | /// normal login path: the token carries the person's <c>PublicId</c>, their role (required by |
| | | 43 | | /// <see cref="IAuthenticatedUserMapper.FromClaims" />, which cannot resolve an |
| | | 44 | | /// <see cref="IdentityUser" /> without one), and <see cref="IdentityUser.MfaPending" /> set — |
| | | 45 | | /// but never a <c>ScopeId</c>, <c>OwnedScopeIds</c>, or scope-permission claim, since |
| | | 46 | | /// <see cref="IdentityUser" /> is constructed here with none of those populated. Carrying a |
| | | 47 | | /// role at all is what lets <see cref="MfaPendingGuardFilter" /> actually authenticate and |
| | | 48 | | /// then reject the token if it is misused as a bearer credential elsewhere (FR-2F-10) — a |
| | | 49 | | /// token the claims mapper could not parse at all would already be rejected by |
| | | 50 | | /// <c>AuthenticationMiddleware</c> before the filter ever ran, which would leave the filter |
| | | 51 | | /// untested by construction rather than genuinely enforcing anything. |
| | | 52 | | /// </para> |
| | | 53 | | /// <para> |
| | | 54 | | /// <b>Audience.</b> <see cref="PersonTokenAudiences.TwoFactorChallenge" />, not the full |
| | | 55 | | /// token's. The claims above mean nothing to a consumer, which validates signature, issuer, |
| | | 56 | | /// audience and lifetime; under the full token's audience it would take a challenge — what a |
| | | 57 | | /// password alone obtains — for a sign-in (Threat Model TH-06). |
| | | 58 | | /// </para> |
| | | 59 | | /// </remarks> |
| | 294 | 60 | | public class JwtTwoFactorChallengeTokenIssuer( |
| | 294 | 61 | | JwtConfiguration configuration, |
| | 294 | 62 | | PersonTokenAudiences audiences, |
| | 294 | 63 | | JwtHandler jwtHandler, |
| | 294 | 64 | | IAuthenticatedUserMapper mapper) : ITwoFactorChallengeTokenIssuer, ITwoFactorChallengeTokenValidator |
| | | 65 | | { |
| | | 66 | | public Task<AuthToken> IssueAsync(Guid personId, int roleId, Guid challengeId, Guid securityStamp) |
| | | 67 | | { |
| | 33 | 68 | | var identity = new IdentityUser(personId, roleId) |
| | 33 | 69 | | { |
| | 33 | 70 | | MfaPending = true, ChallengeId = challengeId, SecurityStamp = securityStamp |
| | 33 | 71 | | }; |
| | | 72 | | |
| | | 73 | | // TH-06: under its own audience, so a consumer pinning the person audience refuses it. |
| | 33 | 74 | | var challengeConfiguration = configuration with |
| | 33 | 75 | | { |
| | 33 | 76 | | Audience = audiences.TwoFactorChallenge, |
| | 33 | 77 | | Claims = mapper.ToClaims(identity), |
| | 33 | 78 | | ExpirationInSeconds = TwoFactorLifetimes.ChallengeToken.TotalSeconds |
| | 33 | 79 | | }; |
| | | 80 | | |
| | 33 | 81 | | var token = jwtHandler.CreateToken(challengeConfiguration); |
| | | 82 | | |
| | 33 | 83 | | return Task.FromResult(new AuthToken(token, DateTime.UtcNow.Add(TwoFactorLifetimes.ChallengeToken))); |
| | | 84 | | } |
| | | 85 | | |
| | | 86 | | public async Task<TwoFactorChallengePrincipal?> ValidateAsync(string? token) |
| | | 87 | | { |
| | | 88 | | // Signature and lifetime (JwtHandler.IsTokenValidAsync validates both) — AF-38a's "expired |
| | | 89 | | // or invalid". ES256 under the configured keys, which are EC keys alone. |
| | 111 | 90 | | if (string.IsNullOrWhiteSpace(token) || !await jwtHandler.IsTokenValidAsync(token, configuration.Keys)) |
| | | 91 | | { |
| | 18 | 92 | | return null; |
| | | 93 | | } |
| | | 94 | | |
| | | 95 | | // TB-5: issued by Heimdall, for the challenge audience alone. The signature proves only that |
| | | 96 | | // Heimdall's key signed it, and that key signs every kind of token. |
| | 93 | 97 | | if (!TokenOrigin.IsIssuedFor(token, configuration.Issuer, audiences.TwoFactorChallenge)) |
| | | 98 | | { |
| | 9 | 99 | | return null; |
| | | 100 | | } |
| | | 101 | | |
| | 84 | 102 | | var claims = TokenClaimsReader.Read(token); |
| | | 103 | | |
| | 84 | 104 | | if (claims is null) |
| | | 105 | | { |
| | 0 | 106 | | return null; |
| | | 107 | | } |
| | | 108 | | |
| | | 109 | | // FR-2F-10: only a token carrying the MFA-pending claim is a challenge token at all — a full |
| | | 110 | | // login token that happens to still be signature-valid is not accepted here either. The mapper |
| | | 111 | | // reads that claim only under the challenge audience, so one carried by any other token is |
| | | 112 | | // not accepted either (TH-06). |
| | | 113 | | // FR-2F-10 again: a challenge token names which challenge it is, so UC-38 can refuse one that |
| | | 114 | | // was already redeemed or has been superseded by a newer login. One without that claim |
| | | 115 | | // cannot be checked, and so is not accepted either. |
| | 84 | 116 | | return mapper.FromClaims(claims) is IdentityUser { MfaPending: true, ChallengeId: { } challengeId } identity |
| | 84 | 117 | | ? new TwoFactorChallengePrincipal(identity.Id, challengeId, identity.SecurityStamp) |
| | 84 | 118 | | : null; |
| | 111 | 119 | | } |
| | | 120 | | } |