Tugi.Integration.Swagger 1.2.0

Tugi.Integration.Swagger

Provides one function that enhances the generated swagger documentation with everything from XML comments in Tugi.Integration and its niches:

using Tugi.Integration.Swagger;
services.AddTugiSwagger();

Example

services.AddEndpointsApiExplorer();
services.AddSwaggerGen(options =>
{
	options.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, System.Reflection.Assembly.GetExecutingAssembly().GetName().Name + ".xml"));
	options.SwaggerDoc("v1", new()
	{
		Version = "1.0",
		Title = "Tugi client endpoints",
		Contact = new()
		{
			Email = "alex.cole@tugitark.com",
			Name = "Alex Cole"
		},
		Description = "The endpoints to be exposed by clients to allow Tugi to request data directly from their systems",
		License = new()
		{
			Name = "Copyright (c) 2026, TugiTark O�",
		}
	});
});
services.AddTugiSwagger();

Protected Endpoints

In addition to documenting the endpoints this library also adds an authorisation method to enable calling the protected /.tugi/users and /.tugi/documents endpoints. These endpoints are protected as they contain PII and other secure information. Hence in order to call them you must have a JWT signed by the tugi private key to identify you as the tugi backend. This would obviously be impossible in testing as the tugi private key is private, but there is public/private key pair included with the Tugi.Integration.Example demo program. This key pair is entirely insecure (it's visible to anyone on the internet), so don't use it in your live system. Since we give you our real public key for checking that our JWT is signed correctly using this incorrect insecure key would mean to literally anyone in the world except us could request your users's data.

Again: Do not copy the example tugi.key file in to your live system.

To generate a new key pair use:

ssh-keygen -t rsa -b 4096 -m PEM -f "tugi.private.pem"
openssl rsa -in "tugi.private.pem" -pubout -outform PEM -out "tugi.pem"

The /.tugi/documents endpoint is considered less secure than /.tugi/users, it literally only exists to provide your documentation to us. Indeed, while Tugi.Integration secures it with a signed JWT there's no reason for a custom implementation to do the same - we'll always send the header but you do not need to check it. However, providing open access to all information about all users is a massive security issue (even if "open" is only "open to tugi"). Thus there is a second, more granular, level of authorisation on those endpoints embedded within the JWT from us. This is an embedded JWT signed by you using any key you please as it is both created and verified only on your system, never by anyone else - the default library implementation just generates a random UUID as a key on first run. The JWT specifies exactly which endpoints we are allowed to access for a single user, for how long, and the range of data we may obtain. A custom implementation could include more claims to restrict this information gathering even further. These claims look something like:

{
	"sub": "bob-the-user",
	"/": {
		"exp": 1778820206
	},
	"/unavailable-bonuses": {
		"exp": 1778820206
	},
	"/bonus-history": {
		"exp": 1778820206
	}
}

This JWT grants access to /.tugi/users/bob-the-user, /.tugi/users/bob-the-user/unavailable-bonuses, /.tugi/users/bob-the-user/bonus-history, and no other endpoints; each with an access expiration some time is 2029 (don't use an expiry this long in reality). Most standard JWT claims such as iss, aud, etc are simply not required here due to the JWT being both issued and and consumed in the same place, with the signature confirming this is done correctly.

The full tugi JWT making an authenticated request using the insecure example private key to a protected /.tugi endpoint will thus look something like (see jwt.io to inspect this JWT):

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InR1Z2kifQ.eyJzdWIiOiIvLnR1Z2kiLCJpc3MiOiJodHRwczovL3R1Z2kuYWkiLCJhdWQiOiJodHRwczovL2xvY2FsaG9zdDo3MDU3IiwiZXhwIjoxODc4ODMwMDAwLCJpYXQiOjE3Nzg4MjAwMDAsIm5iZiI6MTc3ODgyMDAwMCwiL3VzZXJzIjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnpkV0lpT2lKaWIySXRkR2hsTFhWelpYSWlMQ0l2SWpwN0ltVjRjQ0k2TVRrM09EZ3lNREl3Tm4wc0lpOTFibUYyWVdsc1lXSnNaUzFpYjI1MWMyVnpJanA3SW1WNGNDSTZNVGszT0RneU1ESXdObjBzSWk5aWIyNTFjeTFvYVhOMGIzSjVJanA3SW1WNGNDSTZNVGszT0RneU1ESXdObjE5LjRWTkQ2UjBpVEdoWktDZEQ0OTdNdTBOVEs5T19icnFDQjlWNHJCZmN6c3MifQ.Gb6Fw2KnhfXlNGYsgQzhLHQyXDFYjdxH6sqc0gemnCVfcomvm1qrg3KcvUxjnfd0v4PiMRm30mslYlKnVymaUQDxDVa8S4PGJ9JJfKUuO7YGhAEed7y6QVi_gEcqZq8uYAinpgWYIcbGkdRh9PopG58aw1Xn9RXvfgINuIq55Pvq433Vlyqd4fFb0qXk7f-bMA-4-x721wRXuswkidCJ4RLBn_zD57tKrIVl3JraeUTGQSk8ijSA5tnnr3m5rfpwTS3fE80gr5H-_LZ2-YPhAbDpm9Swm_aqusA0yHMJgaQoauQZKN_S6uOsBbRW3aBul0DJzWhe4h40ajRLwn4qIbPb6rJCEuYKH741pIWMxQjPAaPQclyUuc9c5GyPLqUQqWzkrj_lll8gjhuEttQpbzYtoSRMyOkxSB5welMPkxb1xCoaVlcyFPEo07yWy5LAhdTZchXzMIW2tBX8SEedgW6o6Y0be3MuCgW5f9r4p6IT3NPkLWUNWYw76W01llAwjxs5BI7FtmITDMOfvyqbuC_EiGCmw-PS066SRzTRrzI7CDGxVa24l3LBemVeHW4XxY77dweNP8CRqccx9DZbDgtuvhyVxyTJV1TogOCqAD91YannD6b3PVpGMF3FStSh4qpoHUlpcS6RvIprHEe5Fnl097myOifwDYL_-M35oHk

Upon inspection you should notice the /.tugi/users combined subject and key. This is designed to be extensible but as of yet no other endpoints use this scheme.