.NET quickstart

using Microsoft.EntityFrameworkCore;   // UseNpgsql — production lines only (Npgsql arrives with the *.Migrations.PostgreSql packages)
using Veriqa.Core.AuthServer.DependencyInjection;
using Veriqa.Core.AuthServer.Infrastructure;   // UseSecurityHeaders (step 3)
using Veriqa.Core.ChannelAdapter.DependencyInjection;   // AddTelegram, AddWhatsApp, AddMax, AddEmail
using Veriqa.Core.TransactionEngine.DependencyInjection;   // UseEfCoreStore — production lines only

var builder = WebApplication.CreateBuilder(args);

// The production lines below take the connection string from the host's configuration:
// var connectionString = builder.Configuration.GetConnectionString("Veriqa");

builder.Services.AddVeriqaAuthServer(builder.Configuration, builder.Environment, authServer =>
{
    // OpenIddict store (clients, authorizations, tokens). There is no default — choose it
    // explicitly. For development — the volatile in-memory one:
    authServer.UseInMemoryOpenIddictStore();

    // For production — a relational provider instead of the line above (provider and connection
    // string are owned by the host; the migrations ship in the
    // Veriqa.Core.AuthServer.Migrations.PostgreSql package):
    // authServer.UseOpenIddictDatabase(ef => ef.UseNpgsql(connectionString,
    //     npgsql => npgsql.MigrationsAssembly("Veriqa.Core.AuthServer.Migrations.PostgreSql")));

    // Transaction store
    authServer.ConfigureTransactionEngine(te =>
    {
        // For development — InMemory:
        te.UseInMemoryStore();

        // For production — EF Core (the method itself ships in the
        // Veriqa.Core.TransactionEngine.EntityFrameworkCore package; provider and connection
        // string are owned by the host; the migrations ship in the
        // Veriqa.Core.TransactionEngine.Migrations.PostgreSql package):
        // te.UseEfCoreStore(ef => ef.UseNpgsql(connectionString,
        //     npgsql => npgsql.MigrationsAssembly("Veriqa.Core.TransactionEngine.Migrations.PostgreSql")));
    });

    // Confirmation channels
    authServer.AddChannelAdapters(adapters =>
    {
        adapters.AddTelegram();
        adapters.AddWhatsApp();
        adapters.AddMax();
        adapters.AddEmail();
    });
});

var app = builder.Build();

app.UseSecurityHeaders();   // CSP, X-Frame-Options
app.UseStaticFiles();       // SignalR client for live status updates
app.UseAuthentication();
app.UseAuthorization();
app.UseRateLimiter();

// Veriqa endpoints: OIDC + channel webhooks + transaction status + SignalR hub
app.MapVeriqaAuthServer();

app.Run();

{
  "Veriqa": {
    "Channels": {
      "Telegram": {
        "Enabled": true,
        "InboundVerification": "shared_secret",
        "BotToken": "YOUR_BOT_TOKEN",
        "UpdateMode": "Webhook",
        "WebhookBaseUrl": "https://your-domain.com",
        "WebhookSecretToken": "YOUR_SECRET"
      },
      "WhatsApp": {
        "Enabled": false,
        "InboundVerification": "signature",
        "Provider": "MetaCloudApi",
        "BusinessPhoneNumber": "+15551234567",
        "MetaCloudApi": {
          "PhoneNumberId": "YOUR_PHONE_NUMBER_ID",
          "AccessToken": "YOUR_ACCESS_TOKEN",
          "AppSecret": "YOUR_APP_SECRET",
          "WebhookVerifyToken": "YOUR_VERIFY_TOKEN"
        }
      },
      "Max": {
        "Enabled": false,
        "InboundVerification": "shared_secret",
        "BotToken": "YOUR_BOT_TOKEN",
        "UpdateMode": "Webhook",
        "WebhookBaseUrl": "https://your-domain.com",
        "WebhookSecretToken": "YOUR_SECRET"
      },
      "OutcomeNotice": {
        "DisplayIntent": "ReplacePrompt"
      }
    },
    "MessageTemplates": {
      "outcome-receipt-confirmed": {
        "Contract": {
          "Slots": [ { "Name": "app", "Type": "string", "Source": "ServerInitiatorContext" } ]
        },
        "ByType": {
          "login": {
            "BySurface": {
              "in-channel-messenger": {
                "Templates": [ "Signed in to {app} ✅", "Signed in ✅" ]
              }
            }
          }
        }
      },
      "outcome-receipt-declined": {
        "Contract": {
          "Slots": [ { "Name": "app", "Type": "string", "Source": "ServerInitiatorContext" } ]
        },
        "ByType": {
          "login": {
            "BySurface": {
              "in-channel-messenger": {
                "Templates": [ "Sign-in to {app} declined ❌", "Sign-in declined ❌" ]
              }
            }
          }
        }
      }
    },
    "TransactionEngine": {
      "TransactionTtlSeconds": 300
    },
    "OpenIddict": {
      "Clients": [
        {
          "ClientId": "my-app",
          "DisplayName": "My Application",
          "AllowedRedirectUris": [ "https://localhost:7020/signin-oidc" ],
          "AllowedScopes": [ "openid", "profile", "email", "offline_access" ],
          "AllowRefreshTokens": true
        }
      ]
    }
  }
}

using System.Security.Claims;
using Microsoft.AspNetCore.Authentication.Cookies;
using Microsoft.AspNetCore.Authentication.OpenIdConnect;

builder.Services
    .AddAuthentication(options =>
    {
        options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddOpenIdConnect(options =>
    {
        // The address of the host running Veriqa. Endpoints and keys are picked up through
        // discovery ({Authority}/.well-known/openid-configuration) — none are spelled out here.
        options.Authority = "https://localhost:7300";
        options.ClientId = "my-app";
        options.ResponseType = "code";
        options.UsePkce = true;

        // Must equal an AllowedRedirectUris entry from step 4 — the comparison is exact.
        options.CallbackPath = "/signin-oidc";

        // A user who presses "Cancel sign-in" on the Veriqa page
        // comes back with error=access_denied. That is an answer, not a fault: with the path set
        // the handler redirects to the route mapped below. With no path set the refusal
        // would go to OnRemoteFailure below, like any other failed return.
        options.AccessDeniedPath = "/signin-cancelled";

        // Every other failed return — Veriqa answering error=server_error, say, because the channel
        // did not deliver the confirmation — raises OnRemoteFailure; with no handler for it the
        // return ends in an HTTP 500. The user is taken to a page that offers to start over. The
        // error text is deliberately not shown to the user: it is written to the log instead.
        options.Events.OnRemoteFailure = context =>
        {
            context.HttpContext.RequestServices.GetRequiredService<ILogger<Program>>()
                .LogWarning(context.Failure, "The sign-in return carried an error.");
            context.HandleResponse();
            context.Response.Redirect("/signin-failed");
            return Task.CompletedTask;
        };

        // The handler requests openid and profile itself — only extra scopes go here.
        // Each one must be listed in the client's AllowedScopes on the issuer.
        options.Scope.Add("email");
        options.GetClaimsFromUserInfoEndpoint = true;
        options.SaveTokens = true;

        // Veriqa issues the user's name as the short OIDC `name` claim, while User.Identity.Name
        // looks up ClaimTypes.Name (the long WS-Federation URI) by default — without this line the
        // page below greets an empty name after a successful sign-in.
        options.TokenValidationParameters.NameClaimType = "name";
    });

builder.Services.AddAuthorization();

app.UseAuthentication();
app.UseAuthorization();

app.MapGet("/", (ClaimsPrincipal user) =>
    user.Identity?.IsAuthenticated is true
        ? Results.Text($"Hello, {user.Identity.Name}!")
        : Results.Challenge());

// Where the handler sends a user who did not go through with the sign-in (AccessDeniedPath above).
// It is a route of its own because "/" challenges an anonymous visitor: sent there, the user would
// be put straight back on the sign-in page they have just left.
app.MapGet("/signin-cancelled", () => Results.Text("Sign-in was canceled. Open / to sign in again."));

// Where OnRemoteFailure above sends a user whose sign-in ended in an error. Like the route before
// it, it is anonymous and starts nothing by itself: redirected to "/", a failure that repeats
// would loop.
app.MapGet("/signin-failed", () => Results.Text("Sign-in could not be completed. Open / to sign in again."));

builder.Services
    .AddAuthentication(/* the two schemes of step 5 */)
    .AddCookie()
    .AddOpenIdConnect(options =>
    {
        // The only value that differs between cloud, self-hosted and embedded. Everything else —
        // endpoints, keys, supported scopes — the client reads from discovery at startup.
        options.Authority = builder.Configuration["Veriqa:Authority"];
        options.ClientId = builder.Configuration["Veriqa:ClientId"];
        options.ResponseType = "code";
        options.UsePkce = true;
        options.CallbackPath = "/signin-oidc";
        options.AccessDeniedPath = "/signin-cancelled";
        options.Events.OnRemoteFailure = context =>
        {
            context.HttpContext.RequestServices.GetRequiredService<ILogger<Program>>()
                .LogWarning(context.Failure, "The sign-in return carried an error.");
            context.HandleResponse();
            context.Response.Redirect("/signin-failed");
            return Task.CompletedTask;
        };
        options.TokenValidationParameters.NameClaimType = "name";
    });

{
  "Veriqa": {
    "Authority": "https://auth.your-domain.com",
    "ClientId": "my-app"
  }
}