Progmasoft Git

progmaweb

The site and account service of Progmasoft: a Next.js frontend and an ASP.NET Core API.

Clonegit clone https://git.progmasoft.com/progmaweb

Describe the hosts, routes and limits Progmaweb has

The documentation described three hosts and the account endpoints only.
It now matches the code and the Nginx file:

- README and Architecture list every host the build serves: the apex
  with its policies, account, credentials, authorize, console, product
  and license, and the three Nginx answers alone (viget 410, catch3 to
  catch3.uk, the Maven repository). The diagram shows the OAuth paths
  Nginx sends straight to the API, the routing rules list the sites of
  their own and their internal trees, and the pages table has every page.
- Account API: acceptPolicies at registration and the policies-required
  outcome of Google sign-in, the OAuth endpoints of the same service, the
  60-a-minute limit of OAuth and the console, AllowedHosts as it is, and
  the database and key settings.
- Known limitations: the database is backed up every night and a restore
  was tried; an account is deleted by support with the procedure in
  Operations.
- Operations: the logs keep no IP address, without a reference to ViGet.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Commit
92c03645c5d41eaadf03c09b876f8b69e3c5d9d7
Author
Leitwolf11 ·
Parents
eed176f71dce

Files · Download .tar.gz

Changes

 README.md            | 25 +++++++++++------
 docs/ACCOUNT-API.md  | 22 +++++++++++----
 docs/ARCHITECTURE.md | 77 ++++++++++++++++++++++++++++++++++++++--------------
 docs/LIMITATIONS.md  | 15 +++++-----
 ops/README.md        |  2 +-
 5 files changed, 97 insertions(+), 44 deletions(-)

diff --git a/README.md b/README.md
index bbb34bc..d825e62 100644
--- a/README.md
+++ b/README.md
@@ -9,11 +9,17 @@ the ASP.NET Core API.
 
 ## Public hosts
 
-- `progmasoft.com` serves the canonical organization homepage; `www.progmasoft.com` redirects to it.
-- `account.progmasoft.com` serves account discovery and authentication.
-- `account.progmasoft.com/login` signs an existing account in.
-- `account.progmasoft.com/register` creates a new account after server-side validation.
-- `account.progmasoft.com/<Account>/dashboard` serves the authenticated account dashboard.
+- `progmasoft.com` serves the organization homepage, the Privacy Policy and the Security Policy;
+  `www.progmasoft.com` redirects to it.
+- `account.progmasoft.com` serves the account: sign-in (`/login`), registration (`/register`), recovery (`/recover`)
+  and the dashboard (`/<Account>/dashboard`).
+- `credentials.progmasoft.com`, `authorize.progmasoft.com` and `console.progmasoft.com` serve Progmasoft OAuth: the
+  issuer, the pages people sign in and consent on, and the Progmasoft Console. See [Progmasoft OAuth](docs/OAUTH.md).
+- `product.progmasoft.com` serves the product catalog, and `license.progmasoft.com` the Progmasoft Source License.
+
+The same Nginx file also answers `viget.progmasoft.com` with 410 Gone, sends `catch3.progmasoft.com` to `catch3.uk`,
+and serves the Maven repository on `maven.progmasoft.com`; [Operations](ops/README.md) describes those and the other
+sites of the server.
 
 Account names preserve their original display case but reserve names case-insensitively, preventing visually confusing
 duplicates. Email uniqueness is also evaluated case-insensitively by the API.
@@ -28,6 +34,7 @@ menu is remembered across the three hosts. See [Localization](docs/LOCALIZATION.
 
 - [Architecture](docs/ARCHITECTURE.md): processes, hosts, routing and trust boundaries.
 - [Account API](docs/ACCOUNT-API.md): endpoints, errors, cookies and limits.
+- [Progmasoft OAuth](docs/OAUTH.md): the authorization server, the console and how an application uses them.
 - [Localization](docs/LOCALIZATION.md): language selection, text direction and adding a language.
 - [Development](docs/DEVELOPMENT.md): local setup, checks and what CI enforces.
 - [Known limitations](docs/LIMITATIONS.md): what is missing or temporary. Read this before operating the service;
@@ -36,10 +43,10 @@ menu is remembered across the three hosts. See [Localization](docs/LOCALIZATION.
 
 ## Architecture
 
-- `apps/web` is a Next.js App Router application. Host-aware routing keeps the public organization, account, product and license
-  surfaces in one build without coupling their page hierarchies.
-- `apps/api` is an ASP.NET Core minimal API. It owns account-name policy, password hashing, session issuance, secure
-  cookies, rate limiting, and authorization.
+- `apps/web` is a Next.js App Router application. Host-aware routing keeps the organization, account, OAuth, console,
+  product and license sites in one build without coupling their page hierarchies.
+- `apps/api` is an ASP.NET Core minimal API. It owns account-name policy, password hashing, sessions, secure cookies,
+  rate limiting, and Progmasoft OAuth (OpenIddict) with the applications of the console.
 - The browser never receives password hashes, session digests, deployment secrets, or database credentials.
 - Production account maintenance is an explicit operations workflow. The public API does not contain bulk-delete,
   reset-all, seed-password, or environment-password endpoints.
diff --git a/docs/ACCOUNT-API.md b/docs/ACCOUNT-API.md
index 024dea5..eb6b529 100644
--- a/docs/ACCOUNT-API.md
+++ b/docs/ACCOUNT-API.md
@@ -22,6 +22,10 @@ Every response carries `Cache-Control: no-store`.
 | `GET /api/v1/status` | report that the service is online | no |
 | `GET /health` | liveness probe for the service manager | no |
 
+The same service also serves Progmasoft OAuth: `/connect/*` and `/.well-known/*`, and the JSON endpoints of its pages
+under `/api/v1/oauth` (`session`, `signin`, `signout`, `consent`, `allowed`, `applications`). They answer only on the
+OAuth hosts and are described in [Progmasoft OAuth](OAUTH.md).
+
 ## Field rules
 
 | Field | Rule |
@@ -37,9 +41,12 @@ Surrounding white space of an account name or email address is ignored.
 `POST /api/v1/accounts/register`
 
 ```json
-{ "accountName": "ExampleUser1", "email": "user@example.com", "password": "a long passphrase" }
+{ "accountName": "ExampleUser1", "email": "user@example.com", "password": "a long passphrase", "acceptPolicies": true }
 ```
 
+`acceptPolicies` says that the person accepted the Privacy Policy and the Security Policy; anything but `true` is
+refused on that field. The account records the version of the policies it accepted.
+
 **201 Created.** The session cookie is set, `Location` names the account, and the body is the account:
 
 ```json
@@ -83,8 +90,9 @@ revoked when it is seen.
 The flow is a server-side authorization-code flow. The browser is redirected; it never receives Google tokens.
 
 1. `GET /api/v1/accounts/oauth/google/start` sends the browser to Google. When a new account should be created, the
-   request carries `?accountName=<name>`. An invalid name redirects back to
-   `/register?google=invalid-account-name` without contacting Google.
+   request carries `?accountName=<name>` and the acceptance of the policies. An invalid name redirects back to
+   `/register?google=invalid-account-name`, and a missing acceptance to `/register?google=policies-required`, without
+   contacting Google.
 2. Google returns to `/api/v1/accounts/oauth/google/callback`, which the authentication middleware handles. The
    identity is kept for at most ten minutes in a separate cookie, `__Host-ProgmasoftExternal`.
 3. `GET /api/v1/accounts/oauth/google/complete` decides the outcome and removes that cookie.
@@ -94,6 +102,7 @@ The flow is a server-side authorization-code flow. The browser is redirected; it
 | the Google identity is already linked to an account | signed in; redirect to `/<Account>/dashboard` |
 | the identity is new and a valid, free account name was supplied | account created and signed in |
 | the identity is new and no account name was supplied | redirect to `/register?google=account-name-required` |
+| the identity is new and the policies were not accepted | redirect to `/register?google=policies-required` |
 | the supplied account name is invalid | redirect to `/register?google=invalid-account-name` |
 | the supplied account name is taken | redirect to `/register?google=account-name-unavailable` |
 | the email address of the identity belongs to another account | redirect to `/login?google=failed` |
@@ -137,7 +146,8 @@ Passwords are hashed with the ASP.NET Core Identity password hasher and are neve
 ## Limits
 
 - **Rate limit.** The endpoints marked above share one limit per client address: 12 requests in a sliding window of
-  three minutes. A request over the limit gets **429 Too Many Requests**.
+  three minutes; the sign-in of the authorize host shares it too. The OAuth endpoints and the console have their own,
+  60 requests a minute. A request over a limit gets **429 Too Many Requests**.
 - **Body size.** A request body larger than 16 KiB gets **413 Content Too Large**.
 - **Hosts.** The service answers only the host names listed in `AllowedHosts`; any other host gets **400**.
 
@@ -152,7 +162,9 @@ The client address comes from `X-Forwarded-For`, which the service accepts from
 | `AccountSessions:CookieDomain` | domain the session cookie is shared with | none; production `progmasoft.com` |
 | `Authentication:Google:ClientId` | Google OAuth client identifier | empty; Google sign-in is off |
 | `Authentication:Google:ClientSecret` | Google OAuth client secret | empty; Google sign-in is off |
-| `AllowedHosts` | host names the service answers | see `appsettings.json` |
+| `AllowedHosts` | host names the service answers | the apex, `www`, `account`, `credentials`, `authorize` and `console` hosts, and loopback (`appsettings.json`) |
+| `ConnectionStrings:Accounts` | the PostgreSQL database of accounts, sessions and OAuth | none; without it the store is in memory (development) |
+| `OAuth:SigningKeyPath`, `OAuth:EncryptionKeyPath` | the keys that sign identity tokens and encrypt access tokens | see [Progmasoft OAuth](OAUTH.md) |
 | `ASPNETCORE_URLS` | listener address | `http://127.0.0.1:5085` in production |
 
 Environment variables use a double underscore for the colon, for example `Authentication__Google__ClientId`. Secrets
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index fe19db6..2f176b6 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -5,9 +5,10 @@
 
 Progmaweb is two processes behind one reverse proxy:
 
-- **`apps/web`**, a Next.js App Router application. It renders every page of three public hosts and forwards API
+- **`apps/web`**, a Next.js App Router application. It renders every page of the public hosts and forwards API
   calls.
-- **`apps/api`**, an ASP.NET Core minimal API. It owns accounts, passwords and sessions.
+- **`apps/api`**, an ASP.NET Core minimal API. It owns accounts, passwords and sessions, and Progmasoft OAuth: the
+  authorization server and the applications of the Progmasoft Console.
 
 Both listen on loopback only. Nginx is the only public listener and terminates TLS.
 
@@ -15,26 +16,41 @@ Both listen on loopback only. Nginx is the only public listener and terminates T
 browser
    |  HTTPS
    v
-Nginx  (progmasoft.com, www, account.progmasoft.com, ...)
-   |  http://127.0.0.1:3010
-   v
-Next.js server (apps/web)
-   |  /api/*  ->  http://127.0.0.1:5085   (rewrite, server side)
-   v
-ASP.NET Core account API (apps/api)
+Nginx  (progmasoft.com, account., credentials., authorize., console., product., license.)
+   |                                    |
+   |  pages: http://127.0.0.1:3010      |  OAuth hosts only: /connect/*, /.well-known/* (issuer)
+   v                                    |  and /api/* go straight to http://127.0.0.1:5085
+Next.js server (apps/web)               |
+   |  /api/*  ->  http://127.0.0.1:5085 |  (rewrite, server side)
+   v                                    v
+ASP.NET Core API (apps/api)
 ```
 
-## Hosts
+On `credentials.progmasoft.com` Nginx sends `/connect/`, `/.well-known/` and `/api/` to the API; on
+`authorize.progmasoft.com` `/connect/` and `/api/`; on `console.progmasoft.com` `/api/`. Every other path of those
+hosts, and every path of the other hosts, goes to Next.js, which forwards `/api/*` itself.
 
-One build serves three hosts. The host of a request, not a separate deployment, decides which pages it sees.
+## Hosts
 
-| Host | Serves |
-| --- | --- |
-| `progmasoft.com` | the organization homepage; the only host that is meant to be indexed as the organization |
-| `www.progmasoft.com` | a permanent redirect to the apex host, issued by Nginx |
-| `account.progmasoft.com` | the account landing page, sign-in, registration, recovery and the dashboard |
+One build serves every host. The host of a request, not a separate deployment, decides which pages it sees.
 
-`*.localhost` names (`account.localhost`, `product.localhost`) behave like the production hosts during development.
+| Host | Serves | Internal tree |
+| --- | --- | --- |
+| `progmasoft.com` | the organization homepage, the Privacy Policy (`/privacy`), the Security Policy (`/security`), `llms.txt`; the only host meant to be indexed as the organization | `/` |
+| `www.progmasoft.com` | a permanent redirect to the apex host, issued by Nginx | — |
+| `account.progmasoft.com` | the account landing page, sign-in, registration, recovery and the dashboard | `/account` and the account pages |
+| `credentials.progmasoft.com` | the OAuth issuer: its page, and through the API the discovery documents, key set and token endpoints | `/issuer` |
+| `authorize.progmasoft.com` | the authorization endpoint, sign-in (`/signin`), consent (`/consent`) and the allowed applications (`/account/applications`) | `/authorize` |
+| `console.progmasoft.com` | the Progmasoft Console: OAuth 2.1 tokens of the account's applications (`/credentials`, `/credentials/new`, `/credentials/<clientId>`) | `/console` |
+| `product.progmasoft.com` | the product catalog: `/`, `/<product>`, `/categories`, `/languages`, `/releases` | `/products` |
+| `license.progmasoft.com` | the Progmasoft Source License 1.0 and its pages | `/license` |
+
+Nginx alone answers three more names from the same file: `viget.progmasoft.com` with 410 Gone (ViGet was closed),
+`catch3.progmasoft.com` with a permanent redirect to `catch3.uk`, and `maven.progmasoft.com` with the static Maven
+repository of `/srv/maven`.
+
+`*.localhost` names (`account.localhost`, `authorize.localhost`, `product.localhost`, ...) behave like the production
+hosts during development.
 
 ## Host-aware routing
 
@@ -42,9 +58,17 @@ One build serves three hosts. The host of a request, not a separate deployment,
 
 1. **Language parameter.** `?lang=<locale>` with a published locale stores the language cookie and redirects to the
    same URL without the parameter. See [Localization](LOCALIZATION.md).
-2. **Account root.** `/` on the account host is rewritten to the internal `/account` page, so the account landing page
+2. **Sites of their own.** On the credentials, authorize, console, product and license hosts, a public path is
+   rewritten into the host's internal tree (the table above); a path the host does not have shows its not-found page.
+   `/api/*` passes through on the credentials, authorize and console hosts only.
+3. **Internal trees stay internal.** `/issuer`, `/authorize`, `/console`, `/products` and `/license` on any other host
+   show the not-found page.
+4. **Account root.** `/` on the account host is rewritten to the internal `/account` page, so the account landing page
    has the short URL.
-3. **Internal trees stay internal.** `/account` on any other host redirects to the account host.
+5. **The account tree stays on its host.** `/account` on any other host redirects to the account host.
+
+The proxy also gives every page a nonce for its content security policy and expires host-only cookies that would
+shadow the shared language and theme cookies of `.progmasoft.com`.
 
 Internal rewrites use `http:` on purpose. TLS ends at Nginx, and Next.js would otherwise try TLS against its own
 plain-HTTP loopback listener.
@@ -56,15 +80,22 @@ The host is read from `X-Forwarded-Host` first and `Host` second, without the po
 | Route | Page | Indexed |
 | --- | --- | --- |
 | `/` (apex) | organization homepage | yes |
+| `/privacy`, `/security` (apex) | the Privacy Policy and the Security Policy | yes |
 | `/account` (shown as `/` on the account host) | account landing page | no |
 | `/login`, `/register`, `/recover` | authentication and recovery | no |
 | `/<Account>/dashboard` | dashboard of the signed-in account | no |
+| `/` (credentials host) | the issuer page | no |
+| `/`, `/signin`, `/consent`, `/account/applications` (authorize host) | authorization, sign-in, consent, allowed applications | no |
+| `/`, `/credentials`, `/credentials/new[/<kind>]`, `/credentials/<clientId>` (console host) | the Progmasoft Console | no |
+| `/`, `/<product>`, `/categories`, `/languages`, `/releases` (product host) | the product catalog | yes |
+| `/`, `/pm-spl/1.0/<page>` (license host) | the Progmasoft Source License | yes |
 
 `robots.txt` and `sitemap.xml` are generated per host: the product and license hosts list their own pages, every
 other host lists the apex homepage only. Nginx additionally sends `X-Robots-Tag: noindex` for the whole account host.
 
-Pages are rendered on the server for every request, because the language depends on the request. Two components run
-in the browser: the authentication form and the dashboard.
+Pages are rendered on the server for every request, because the language depends on the request. The interactive
+parts run in the browser: the authentication form, the dashboard, and the sign-in, consent, allowed-applications and
+console forms of the OAuth hosts.
 
 ## Account flow
 
@@ -78,6 +109,10 @@ Sign-in with Google is a server-side authorization-code flow that starts at `/ap
 returns through the API; the browser never handles Google tokens. The [Account API](ACCOUNT-API.md) describes each
 step.
 
+Sign-in on the authorize host has its own cookie and opens no session of the account site; the console uses the
+account session, whose cookie production shares with `progmasoft.com`. [Progmasoft OAuth](OAUTH.md) describes both.
+The API answers each OAuth and console path on its own host only and 404 elsewhere (`OAuthHostFilter`).
+
 ## Trust boundaries
 
 - **Browser to Nginx.** Everything from the browser is untrusted, including the language cookie, the `lang`
diff --git a/docs/LIMITATIONS.md b/docs/LIMITATIONS.md
index 774714e..6d82b97 100644
--- a/docs/LIMITATIONS.md
+++ b/docs/LIMITATIONS.md
@@ -6,20 +6,19 @@
 This page lists what Progmaweb does not do yet, so that nobody has to discover it in production. Each entry says what
 is missing, what follows from it, and what would close it.
 
-## The account database has no backup yet
+## The backup is at most a day old
 
-Accounts and sessions are kept in PostgreSQL; see [Operations](../ops/README.md). Restarting or redeploying the API no
-longer loses them. Nothing copies the database anywhere else yet.
+Accounts, sessions and OAuth data are kept in PostgreSQL. Every night the database is dumped with `pg_dump` and copied
+with restic to the second Progmasoft server, with the OAuth keys of `/etc/progmaweb`; a restore has been tried.
 
-- **Consequence.** Losing the disk of the host, or dropping the database by mistake, loses every account.
-- **What closes it.** A scheduled `pg_dump` of the account database to storage outside the host, and a restore that
-  has been tried once.
+- **Consequence.** Losing the host loses what changed since the last night's backup.
 
-## Accounts cannot be deleted
+## Accounts cannot be deleted by their owners
 
 The store has no operation that removes an account, and the API has no endpoint for it.
 
-- **Consequence.** A request to erase an account has to be carried out by hand in the database, by its operator.
+- **Consequence.** A request to erase an account is carried out by support in the database, with the procedure in
+  [Operations](../ops/README.md) ("Deleting an account").
 - **What closes it.** A deletion operation in the store with an endpoint or an operator command, and a decision about
   what happens to the account name afterwards.
 
diff --git a/ops/README.md b/ops/README.md
index daf8516..b238d19 100644
--- a/ops/README.md
+++ b/ops/README.md
@@ -101,7 +101,7 @@ Delete the dump once the deletion is confirmed.
 
 ### Logs without client addresses
 
-The Privacy Policy says that IP addresses are kept only with ViGet uploads. On both servers the `main` log format of
+The logs keep no IP address. On both servers the `main` log format of
 `/etc/nginx/nginx.conf` therefore has no `$remote_addr` and no `$http_x_forwarded_for`, and `error_log` keeps only
 `crit` entries, because a lower level names the client of a failed request. The change was applied by hand on the
 first server on 2026-11-06, with a copy of the previous file in `/root/policy-20261106`. A new site in `conf.d` uses the `main` format or one of its own without an address.