changelog and npm publish

annotations.md

@@ -3,48 +3,58 @@
 ## BufferRows
 
 ```console
-bufferrows number
-buffer_rows number
-buffer-rows number
-buffer number
+                                                           
+bufferrows number                                          
+buffer_rows number                                         
+buffer-rows number                                         
+buffer number                                              
+                                                           
 ```
 
 Sets the buffered amount of rows before they are written to the response for this endpoint.
 
 ## Tags
 
 ```console
-for tag1, tag2, tag3 [, ...]
-tag tag1, tag2, tag3 [, ...]
-tags tag1, tag2, tag3 [, ...]
+                                                           
+for tag1, tag2, tag3 [, ...]                               
+tag tag1, tag2, tag3 [, ...]                               
+tags tag1, tag2, tag3 [, ...]                              
+                                                           
 ```
 
 All annotations in lines below this line apply only to tags in the argument list.
 
 ## Disabled
 
 ```console
-disabled
-disabled [ tag1, tag2, tag3 [, ...] ]
+                                                           
+disabled                                                   
+disabled [ tag1, tag2, tag3 [, ...] ]                      
+                                                           
 ```
 
 The endpoint is disabled. Optional tag list disabled only for tags in the argument list.
 
 ## Enabled
 
 ```console
-enabled
-enabled [ tag1, tag2, tag3 [, ...] ]
+                                                           
+enabled                                                    
+enabled [ tag1, tag2, tag3 [, ...] ]                       
+                                                           
 ```
 
 The endpoint is enabled. Optional tag list enabled only for tags in the argument list.
 
 ## HTTP
 
 ```console
-HTTP 
-HTTP [ GET | POST | PUT | DELETE ]
-HTTP [ GET | POST | PUT | DELETE ] path
+                                                           
+HTTP                                                       
+HTTP [ GET | POST | PUT | DELETE ]                         
+HTTP [ GET | POST | PUT | DELETE ] path                    
+                                                           
 ```
 
 HTTP settings:
@@ -68,14 +78,16 @@ Set how request parameters are sent - query string or JSON body.
 ## RequiresAuthorization
 
 ```console
-requiresauthorization
-authorize
-requires_authorization
-requires-authorization
-requiresauthorization [ role1, role2, role2 [, ...] ]
-authorize [ role1, role2, role2 [, ...] ]
-requires_authorization [ role1, role2, role2 [, ...] ]
-requires-authorization [ role1, role2, role2 [, ...] ]
+                                                           
+requiresauthorization                                      
+authorize                                                  
+requires_authorization                                     
+requires-authorization                                     
+requiresauthorization [ role1, role2, role2 [, ...] ]      
+authorize [ role1, role2, role2 [, ...] ]                  
+requires_authorization [ role1, role2, role2 [, ...] ]     
+requires-authorization [ role1, role2, role2 [, ...] ]     
+                                                           
 ```
 
 Require authorization for this endpoint.
@@ -86,35 +98,41 @@ Require authorization for this endpoint.
 ## AllowAnonymous
 
 ```console
-allowanonymous
-allow_anonymous
-allow-anonymous
-anonymous
-anon
+                                                             
+allowanonymous                                               
+allow_anonymous                                              
+allow-anonymous                                              
+anonymous                                                    
+anon                                                         
+                                                             
 ```
 
 Allow anonymous access with no authorization to this endpoint. 
 
 ## CommandTimeout
 
 ```console
-commandtimeout seconds
-command_timeout seconds
-command-timeout seconds
-timeout seconds
+                                                             
+commandtimeout seconds                                       
+command_timeout seconds                                      
+command-timeout seconds                                      
+timeout seconds                                              
+                                                             
 ```
 
 Set the command execution timeout in seconds.
 
 ## RequestHeadersMode
 
 ```console
-requestheadersmode [ ignore | context | parameter ]
-request_headers_mode [ ignore | context | parameter ]
-request-headers-mode [ ignore | context | parameter ]
-requestheaders [ ignore | context | parameter ]
-request_headers [ ignore | context | parameter ]
-request-headers [ ignore | context | parameter ]
+                                                             
+requestheadersmode [ ignore | context | parameter ]          
+request_headers_mode [ ignore | context | parameter ]        
+request-headers-mode [ ignore | context | parameter ]        
+requestheaders [ ignore | context | parameter ]              
+request_headers [ ignore | context | parameter ]             
+request-headers [ ignore | context | parameter ]             
+                                                             
 ```
 
 Set how request parameters are handled:
@@ -125,35 +143,41 @@ Set how request parameters are handled:
 ## RequestHeadersParameterName
 
 ```console
-requestheadersparametername name
-requestheadersparamname name
-request_headers_parameter_name name
-request_headers_param_name name
-request-headers-parameter-name name
-request-headers-param-name name
+                                                
+requestheadersparametername name                
+requestheadersparamname name                    
+request_headers_parameter_name name             
+request_headers_param_name name                 
+request-headers-parameter-name name             
+request-headers-param-name name                 
+                                                
 ```
 
 When `RequestHeadersMode` is set to send request headers as a parameter, set the existing parameter name. The default is `headers`.
 
 ## BodyParameterName
 
 ```console
-bodyparametername name
-body-parameter-name name
-body_parameter_name name
-bodyparamname name
-body-param-name name
-body_param_name name
+                                                
+bodyparametername name                          
+body-parameter-name name                        
+body_parameter_name name                        
+bodyparamname name                              
+body-param-name name                            
+body_param_name name                            
+                                                
 ```
 
 Set the name of the existing parameter which is sent as body content. When the `BodyParameterName` is set, all other parameters are sent by the query string.
 
 ## ResponseNullHandling
 
 ```console
-responsenullhandling [ emptystring | nullliteral | nocontent ]
-response_null_handling [ emptystring | nullliteral | nocontent ]
-response-null-handling [ emptystring | nullliteral | nocontent ]
+                                                
+responsenullhandling [ emptystring | nullliteral | nocontent ]         
+response_null_handling [ emptystring | nullliteral | nocontent ]       
+response-null-handling [ emptystring | nullliteral | nocontent ]       
+                                                
 ```
 
 Sets the response NULL handling option for a single function results other than JSON (text, number, etc...):
@@ -165,9 +189,11 @@ Sets the response NULL handling option for a single function results other than
 ## QueryStringNullHandling
 
 ```console
-querystringnullhandling [ emptystring | nullliteral | ignore ]
-query_string_null_handling [ emptystring | nullliteral | ignore ]
-query-string-null-handling [ emptystring | nullliteral | ignore ]
+                                                
+querystringnullhandling [ emptystring | nullliteral | ignore ]        
+query_string_null_handling [ emptystring | nullliteral | ignore ]     
+query-string-null-handling [ emptystring | nullliteral | ignore ]     
+                                                
 ```
 
 Sets the response NULL handling option for the query string parameters:
@@ -179,25 +205,31 @@ Sets the response NULL handling option for the query string parameters:
 ## Headers
 
 ```console
-key: value
+                                                
+key: value                                      
+                                                
 ```
 
 Any line containing a`:` character is interpreted as the request header key and value where the key is the left side and the value is the right side string. For example: `Content-Type: text/html`
 
 ## Login
 
 ```console
-login
-signin
+                                                
+login                                           
+signin                                          
+                                                
 ```
 
 This annotation will transform the routine into the authentication endpoint that performs the sign-in operation.
 
 Note: to be able to use this feature authentication needs to be enabled and configured in your application, for example:
 
-```cs
-var builder = WebApplication.CreateBuilder(args);
-builder.Services.AddAuthentication().AddCookie();
+```csharp
+
+var builder = WebApplication.CreateBuilder(args);              
+builder.Services.AddAuthentication().AddCookie();              
+
 ```
 
 The login-enabled endpoints must return a named record.

changelog.md

@@ -4,8 +4,15 @@
 
 [Full Changelog](https://github.com/vb-consulting/NpgsqlRest/compare/2.7.0...2.7.1)
 
+### NpgsqlRest 2.7.1
 
+- Small fix on the Login endpoint that fixed the problem with the custom message not being written to the response in some rare circumstances.
+- Redesigned the auth module and changed the access modifiers to the public of the ClaimTypes Dictionary to be used with the client application.
 
+### NpgsqlRest Client 1.1.0
+
+- [Client application](https://vb-consulting.github.io/npgsqlrest/client/) new release with massive improvements.
+- External auth logins implementation (Google, LinkedIn, GitHub)
 
 ## Version [2.7.0](https://github.com/vb-consulting/NpgsqlRest/tree/2.7.0) (2024-04-17)
 

login-endpoints.md

@@ -0,0 +1,95 @@
+# Login Endpoints
+
+Endpoints can be labeled as Login endpoints to act as authentication endpoints and perform user sign-in operations.
+
+## How To Label Login Endpoint
+
+1) By using `EndpointCreated` callback:
+
+```csharp
+app.UseNpgsqlRest(new NpgsqlRestOptions
+{
+    EndpointCreated = (routine, endpoint) =>
+    {
+        if (routine.Name == "login")
+        {
+            endpoint.Login = true;
+        }
+        return endpoint;
+    }
+});
+```
+
+2) By using the [`login` endpoint annotation](https://vb-consulting.github.io/npgsqlrest/annotations/#login):
+
+```sql
+create function auth.login(_username text, _password text) 
+returns table (status int, name_identifier text, name text, role text[])
+language sql as 
+$$
+-- select query that returns status, name_identifier, name and role array
+$$;
+
+comment on function auth.login(text, text) is '
+HTTP POST
+Login
+';
+```
+
+## Login Endpoint Conventions
+
+- The login-enabled endpoints must return a **named record (table)**.
+
+- If the return type is not named record and it is one of these instead (`void` type, a simple value like `int` or `text`, or unnamed record) the endpoint will return an **unauthorized status (code 401)**.
+
+- If the endpoint has a return type **named record** - but it returns an empty record the endpoint will return an **unauthorized status (code 401)**.
+
+- If the endpoint has a return type **named record** - and it reruns some records, only the first records will be read and parsed, the rest is discarded.
+
+- Returned columns are parsed by the column name. Column name can be the original column name from PostgreSQL or, parsed by the [default name converter](https://vb-consulting.github.io/npgsqlrest/options/#nameconverter). This camel case name converter, by default (unless changed in options).
+
+- Three special column names are interpreted differently: the **status** column, the **scheme** column and the **message** column. See below for more details.
+
+- If the column is neither of those three, the column name is interpreted as the [security claim type](https://learn.microsoft.com/en-us/dotnet/api/system.security.claims.claim?view=net-8.0) and and column value is the security claim value (for the given type). These are values such as user name, user id, etc...
+
+
+### Claim Types
+
+- By default, if the column name interpreted as the security claim type, matches one of the Active Directory Federation Services Claim Types names, it will use that AD Federation Services Claim Type URI. The table can be seen here: [ClaimTypes Class](https://learn.microsoft.com/en-us/dotnet/api/system.security.claims.claimtypes?view=net-8.0#fields).
+
+- That means that if the column name is either of these `NameIdentifier` - or the `nameidentifier` (case is ignored), or the `name_identifier` (for the camel case converted names, which is the default), the actual security claim type is `http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier` according to this table. 
+
+- If the name is not found in this table, security is the column name as-is but parsed by the default name converter. 
+
+- In this example column name `name_identifier` will be the security claim type the `nameIdentifier`. 
+
+- This behavior that uses AD Federation Services Claim Type can be turned off with the [AuthenticationOptions.UseActiveDirectoryFederationServicesClaimTypes
+ option](https://vb-consulting.github.io/npgsqlrest/options/#authenticationoptionsuseactivedirectoryfederationservicesclaimtypes).
+
+### Status Columns
+
+- The status column name is set by the option [AuthenticationOptions.StatusColumnName](https://vb-consulting.github.io/npgsqlrest/options/#authenticationoptionsstatuscolumnname). The default is `status`.
+
+- This column can only be a boolean or numeric type. If it is neither boolean nor numeric, the endpoint will return status `500 InternalServerError` and you'll have to check logs.
+
+- When this field is boolean, and it is true, the login process will continue with security claims set by other fields (which usually ends up in `200 OK` if authentication is configured). If it is false, the endpoint will return `404 NotFound` and the login attempt will not continue.
+
+- When this field is numeric, and it is 200, the login process will continue with security claims set by other fields (which usually ends up in `200 OK` if authentication is configured). If it is not 200, the endpoint will return the status code the same as the value of this field, and the login attempt will not continue.
+
+### Scheme Columns
+
+- The scheme column name is set by the option [AuthenticationOptions.SchemeColumnName](https://vb-consulting.github.io/npgsqlrest/options/#authenticationoptionsschemecolumnname). The default is `scheme`.
+
+- The textual value of this field will set the authentication scheme name for the sign-in operation.
+
+- This is useful when using multiple authentication schemes. Returning any value from the logout routine will cause a logout from only that scheme. So for example, if you have the Cookie scheme and the Bearer Token scheme configured, you can handle them separately for login and logout.
+
+### Message Columns
+
+- The status column name is set by the option [AuthenticationOptions.MessageColumnName](https://vb-consulting.github.io/npgsqlrest/options/#authenticationoptionsmessagecolumnname). The default is `message`.
+
+- This is the textual message that is returned in the response body.
+
+- Note: this message is only returned in a case when the configured authentication scheme doesn't write anything into the response body on a sign-in operation.
+
+- For example, the Cookie authentication scheme doesn't write anything into the body and this message is safely written to the response body. On other hand, the Bearer Token schemes will always write the response body and this message will not be written to the response body.

npm/config-copy.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+// Get the destination directory from the command line arguments, or use the current directory
+const destDir = process.argv[2] || process.cwd();
+
+// Path to the source file
+const srcFile = path.join(__dirname, "appsettings.json");
+
+// Path to the destination file
+const destFile = path.join(destDir, "appsettings.json");
+
+// Copy the file
+fs.copyFileSync(srcFile, destFile);
+
+console.log(`Copied appsettings.json to ${destFile}`);