Validate ID tokens against discovered issuer and refreshed tokens

OIDCClient.validate_id_token compared the iss claim against
OIDCConfig.issuer (the discovery URL) instead of the issuer advertised by
the provider metadata. This broke Microsoft Entra ID, whose v2 metadata
advertises the templated issuer
https://login.microsoftonline.com/{tenantid}/v2.0 while tokens carry the
concrete tenant GUID, and it also affected tenant-domain issuers.

- Validate iss against the discovered metadata issuer and substitute
  {tenantid} with the token's tid claim.
- Catch jwt.PyJWTError in the OIDC callback so invalid tokens return 400
  instead of 500 (InvalidIssuerError is not a ValueError).
- Re-enable aud/exp/iat/nbf checks for unsigned (alg: none) ID tokens.
- Validate ID tokens returned by the refresh grant before storing them,
  including nonce continuity when present and sub continuity with the
  session user.
- Document Entra ID support and update tests.

packages/kaya-oidc/README.md

@@ -164,6 +164,9 @@ authentication methods (`private_key_jwt`, mTLS) is not supported.
 - Generic OIDC discovery
 - Authorization Code Flow with PKCE (S256)
 - ID token signature validation with JWKS
+- Issuer validation against discovery metadata, including support for
+  Microsoft Entra ID `{tenantid}` issuer templates
+- Refreshed ID token validation on token refresh
 - `state` and `nonce` protection
 - Session fixation defense via `regenerate_id()` after login
 - Optional userinfo endpoint fetch
@@ -174,8 +177,37 @@ authentication methods (`private_key_jwt`, mTLS) is not supported.
 - `single-identity` (default) or `multi-identity` session strategy
 - Composable with any other `KayaMixin` (RSGI, MCP, etc.)
 
+## Microsoft Entra ID
+
+Entra ID v2 ID tokens carry an `iss` claim of the form
+`https://login.microsoftonline.com/<tenant-id>/v2.0`, while the discovery
+metadata for the multi-tenant endpoints advertises the templated issuer
+`https://login.microsoftonline.com/{tenantid}/v2.0`. `kaya-oidc` validates the
+`iss` claim against the discovered metadata and substitutes the token's `tid`
+claim into `{tenantid}`, so both tenant-specific and multi-tenant issuers work:
+
+```python
+OIDCConfig(
+    issuer='https://login.microsoftonline.com/<tenant-id-or-domain>/v2.0',
+    client_id=os.environ['OIDC_CLIENT_ID'],
+    client_secret=os.environ['OIDC_CLIENT_SECRET'],
+    redirect_uri='https://example.com/auth/callback',
+)
+```
+
+Use a tenant-specific issuer (the tenant GUID or a verified domain name) to
+restrict logins to that tenant. The `common` and `organizations` aliases are
+multi-tenant: any tenant in that cloud can obtain an ID token that passes
+validation. If you build a multi-tenant application, check the `tid` claim
+against the tenants you trust.
+
 ## Security notes
 
+- The `iss` claim is validated against the `issuer` value of the provider's
+  discovery document, not against `OIDCConfig.issuer` (they can differ, for
+  example for Entra ID multi-tenant endpoints).
+- Refreshed ID tokens are validated before being stored; the `nonce` is also
+  checked when the refreshed token carries one.
 - The `none` signing algorithm is rejected by default.
 - Only algorithms listed in `OIDCConfig.allowed_id_token_algorithms` are accepted.
 - Always use HTTPS for `redirect_uri` in production.