Changelog v4.0.1
Version 4.0.1 (2026-11-20)
Patch release. It fixes one regression of 4.0.0 (password login failed on endpoints that use user parameters), one problem that 4.0.0 made visible (role checks failed for JWT sign-ins), and five older bugs. All of them were found by upgrading the examples to 4.0.0 and running every one of them. No configuration key was added, removed or renamed.
Who should upgrade: everyone on 4.0.0 who uses UseUserParameters (or user_params) together with a login endpoint, or who signs users in with JWT and uses roles.
Fixes
Login failed (404) when the login parameter had a claim-mapped name
A regression in 4.0.0. Applies to login endpoints on which user parameters are enabled (UseUserParameters: true, or the user_params annotation) and whose routine has a parameter with a name from ParameterNameClaimsMapping: by default _user_id, _user_name and _user_roles, and very often a mapped _username.
What was wrong. 4.0.0 stopped anonymous callers from sending values for claim-mapped parameters (4.0.0: anonymous callers can no longer fill user parameters). A login request is anonymous by definition, and its parameters are the credentials. So with this configuration, which is the one the authentication guide shows:
jsonc
"AuthenticationOptions": {
"UseUserParameters": true,
"ParameterNameClaimsMapping": { "_user_id": "user_id", "_username": "username" }
}sql
create function login(_username text, _password text) returns table (...) ...;
comment on function login(text, text) is 'HTTP POST
login';the submitted username was removed from the request, the routine no longer matched, and every login answered 404 with nothing in the log. No one could sign in.
What changed. Request values for claim-mapped parameters are kept on login endpoints. Everywhere else the 4.0.0 rule stands: an anonymous caller cannot fill them.
Workaround on 4.0.0. Turn UseUserParameters off and put the user_params annotation on the endpoints that need the claims, or rename the login parameter.
JWT: authorize role answered 403, and roles and email were NULL
Applies to JWT sign-ins (Auth:JwtAuth, or an Auth:Schemes entry of type Jwt) where the role claim is named roles or role, or where a claim is named email, sub or another name the JWT handler knows.
What was wrong. The JWT bearer handler renames well-known claim types when it reads a token: roles and role become http://schemas.microsoft.com/ws/2008/06/identity/claims/role, email becomes .../claims/emailaddress, and so on. After a JWT sign-in the claims therefore no longer had the names the login routine returned. With DefaultRoleClaimType: "roles":
authorize admindid not find the role claim. Before 4.0.0 a plainauthorizevalue also matched the user name and the user id, so a user named like the role was let in by accident and the others got403. Since 4.0.0 a plain value is a role only, so every JWT user got403on an endpoint withauthorize <role>.- the role and email claims were NULL in user parameters and in the user context (
request.roles,request.email). - a refreshed token carried the renamed claims, so the claim names changed again after the first refresh.
Cookie and bearer-token sign-ins were never affected.
What changed. The client registers JWT schemes with MapInboundClaims = false, and validates refresh tokens the same way. Claims of a JWT sign-in keep the names the login routine gave them, as they do for cookies. Tokens issued by 4.0.0 stay valid. One case needs a new sign-in: a token that an earlier version issued from a refresh token already contains the renamed claims, and they are now read as they are written, so such a user has no roles claim until they sign in again.
What to check. If your code works around this by reading the long claim names (for example DefaultRoleClaimType set to the http://schemas.microsoft.com/... URI), change it back to the short name used in the login routine.
Logout with a JWT answered 500
What was wrong. A logout endpoint called with a JWT, or a logout routine that returns the name of a JWT scheme, failed with "The authentication handler registered for scheme 'jwt' is 'JwtBearerHandler' which cannot be used for SignOutAsync" and answered 500.
What changed. A scheme whose handler cannot sign out is skipped. A JWT scheme keeps no session on the server: the client discards its tokens. Cookie and bearer-token schemes named in the same logout are signed out as before, and an unknown scheme name is still reported.
SQL files: a typed parameter with a default failed (500) when the request left it out
What was wrong. For a parameter with a type and a default:
sql
-- @param $1 productId int
-- @param $2 quantity int default 1a request without quantity failed with 500 ("Writing values of 'System.String' is not supported for parameters having NpgsqlDbType 'Integer'"). The default is written as text in the annotation, and it was bound as text. Defaults of parameters without a declared type, and default null, worked.
What changed. The default is converted to the parameter's type, exactly as a value from the query string is. This applies to query string and JSON body parameters, and to the = value form.
TypeScript client: DefaultJsonType was string when it was not set
What was wrong. ClientCodeGen:DefaultJsonType is documented with the default any, and that is the default of the plugin option. The npgsqlrest client used string when the key was missing from the configuration. JSON values typed from this setting (results of multi-command SQL files, fields of composite types) were then declared as string although the response contains JSON.
What changed. The default is any, as documented. To keep the earlier output, set "DefaultJsonType": "string".
TypeScript client: void on a multi-command SQL file
What was wrong. A multi-command SQL file with the void annotation answers 204 with no body. Its client function was still declared as returning the command results and read them with response.json(), which throws "Unexpected end of JSON input" in the browser.
What changed. The function returns void (or the status object when status codes are included), and no response interface is generated for it.
TypeScript client: return type of a pass-through proxy function
What was wrong. For a pass-through proxy (a proxy endpoint on a routine that returns void) and for proxy_out, the client function returns the fetch response itself. With status codes included, which is the default of the npgsqlrest client, it was declared as Promise<ApiResult<Response>>, so result.response and result.error type-checked and were undefined at run time, and the generated file did not compile in strict mode.
What changed. The function is declared as Promise<Response>. Code that read .status from the result is unaffected; code that read .response or .error now gets a compile error where it used to get undefined.
Timeout messages depended on the regional settings of the server
The error message of a timed-out HTTP Custom Type call, proxy call or proxy_out call contained the timeout formatted with the server's culture: Request timed out after 0,3 seconds on a system with a decimal comma. The message is data handed to the routine, so it is now always 0.3 seconds.
Known issue, not fixed in this release
When a statement of a multi-command SQL file fails after an earlier statement has written output, the error body is not valid JSON (the problem details follow the partial output). The status code is correct. This is not new in 4.0.0; earlier versions appended the partial output after the problem details.
Tests
UserParamsTests.Test_login_keeps_claim_mapped_credential_parameters: aloginroutine with a claim-mapped_user_nameparameter anduser_paramssigns in, and rejects a wrong secret.JwtClaimNamesTests: the claims of an access token, and of a token issued from a refresh token, keep the namesroles,email,usernameanduser_id.AuthSchemeLoginTests.Logout_naming_a_jwt_scheme_succeeds_and_still_signs_out_the_cookie_scheme.ParamDefaultValueTests: typed defaults (int,numeric,boolean,date) left out and supplied, in the query string and in the JSON body.TsClientDefaultJsonTypeTests: the client fallback, the plugin option default and the documented default agree.SqlFileTsClientTests.TsClient_MultiCommand_VoidAnnotation_ReturnsVoidandProxyPassthroughResponseTests.Test_ProxyPassthroughResponse_WithStatusCode_StillReturnsResponse.- The timeout message is covered by the existing
HttpClientTypeFixesTests.Call_to_an_own_endpoint_honors_the_timeout, which failed on a system with a decimal comma.
Full suite green on .NET 11 (3298) and .NET 10 (3279).
NuGet Package Upgrades
| Package | Version |
|---|---|
NpgsqlRest | 4.0.0 → 4.0.1 |
NpgsqlRest.TsClient | 1.38.0 → 1.38.1 |
The other plugins are unchanged.