Overhaul first installation and admin editors

.github/workflows/cd-publish-nuget-prerelease.yml

@@ -1,6 +1,6 @@
 name: CD - Publish NuGet Prerelease
 
-# Builds and publishes a prerelease of Modgud.Client.AspNetCore to
+# Builds and publishes a prerelease of Modgud.AspNetCore.ResourceServer to
 # nuget.org. Mirrors the cocoar.configuration workflow pattern so the
 # release plumbing is consistent across the org.
 #
@@ -23,7 +23,7 @@ name: CD - Publish NuGet Prerelease
 # Trigger this when:
 #   - You need a specific prerelease build to test in a downstream
 #     consumer app
-#   - An external user asked for "the latest" of the client library
+#   - An external user asked for "the latest" resource-server package
 #   - Pre-stable release-candidate testing
 #
 # Otherwise leave it alone. The version still ships via the
@@ -50,7 +50,7 @@ concurrency:
 
 jobs:
   test:
-    name: Test client lib
+    name: Test resource-server package
     runs-on: ubuntu-latest
     timeout-minutes: 20
     permissions:
@@ -67,24 +67,24 @@ jobs:
       - name: Setup .NET
         uses: ./.github/actions/setup-dotnet
 
-      - name: Restore client lib + unit tests
+      - name: Restore resource-server package + unit tests
         run: |
-          dotnet restore Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj
+          dotnet restore Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj
           dotnet restore Modgud.Tests.Unit/Modgud.Tests.Unit.csproj
         working-directory: ./src/dotnet
 
-      - name: Build client lib + unit tests
+      - name: Build resource-server package + unit tests
         run: |
-          dotnet build Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj -c Release --no-restore
+          dotnet build Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj -c Release --no-restore
           dotnet build Modgud.Tests.Unit/Modgud.Tests.Unit.csproj -c Release --no-restore
         working-directory: ./src/dotnet
 
-      # Filter to the Client.AspNetCore tests so we don't pull in
+      # Filter to the ResourceServer tests so we don't pull in
       # integration tests that need Docker/Postgres (those live in
-      # Modgud.Api.Tests and aren't relevant for a client-lib
+      # Modgud.Api.Tests and aren't relevant for this package
       # publish gate).
-      - name: Test client lib
-        run: dotnet test Modgud.Tests.Unit/Modgud.Tests.Unit.csproj -c Release --no-build --verbosity normal --filter "FullyQualifiedName~Client"
+      - name: Test resource-server package
+        run: dotnet test Modgud.Tests.Unit/Modgud.Tests.Unit.csproj -c Release --no-build --verbosity normal --filter "FullyQualifiedName~ResourceServer"
         working-directory: ./src/dotnet
 
   publish-prerelease:
@@ -134,12 +134,12 @@ jobs:
           echo "Calculated prerelease version: $VERSION"
 
       - name: Restore
-        run: dotnet restore Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj
+        run: dotnet restore Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj
         working-directory: ./src/dotnet
 
       - name: Build
         run: |
-          dotnet build Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj \
+          dotnet build Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj \
             -c Release --no-restore \
             -p:Version=$PACKAGE_VERSION \
             -p:AssemblyVersion=${{ steps.dotnet.outputs.assembly-semver }} \
@@ -149,7 +149,7 @@ jobs:
 
       - name: Pack (incl. symbols)
         run: |
-          dotnet pack Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj \
+          dotnet pack Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj \
             -c Release --no-build \
             -p:Version=$PACKAGE_VERSION \
             -p:ContinuousIntegrationBuild=true \
@@ -189,10 +189,10 @@ jobs:
       - name: Summary
         run: |
           {
-            echo "### Modgud.Client.AspNetCore — $PACKAGE_VERSION (prerelease)"
+            echo "### Modgud.AspNetCore.ResourceServer — $PACKAGE_VERSION (prerelease)"
             echo ""
             if [ "${{ github.ref }}" = "refs/heads/develop" ]; then
-              echo "**Pushed to:** https://www.nuget.org/packages/Modgud.Client.AspNetCore/$PACKAGE_VERSION"
+              echo "**Pushed to:** https://www.nuget.org/packages/Modgud.AspNetCore.ResourceServer/$PACKAGE_VERSION"
             else
               echo "**Artifact only** (feature branch — not pushed to nuget.org)."
               echo "Download the \`prerelease-packages-$PACKAGE_VERSION\` artifact and add it as a local source to test."

.github/workflows/cd-release.yml

@@ -40,7 +40,7 @@ name: CD - Release
 # Sibling workflows for staging / prerelease / editorial doc paths:
 #   - cd-publish-staging-image.yml    — pushes `:beta` / `:<slug>` moving
 #                                       Docker tags (auto on develop push + manual)
-#   - cd-publish-nuget-prerelease.yml — prerelease NuGet for client-lib
+#   - cd-publish-nuget-prerelease.yml — prerelease resource-server NuGet
 #                                       (manual workflow_dispatch)
 #   - cd-deploy-docs.yml              — editorial doc deploy to Shelf
 #                                       between releases (manual)
@@ -146,7 +146,7 @@ jobs:
         working-directory: ./src/dotnet
 
   pack-nuget:
-    name: Pack NuGet (Client.AspNetCore)
+    name: Pack NuGet (ResourceServer)
     needs: validate-version
     runs-on: ubuntu-latest
     permissions:
@@ -165,20 +165,20 @@ jobs:
         uses: ./.github/actions/setup-dotnet
 
       - name: Restore
-        run: dotnet restore Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj
+        run: dotnet restore Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj
         working-directory: ./src/dotnet
 
       - name: Build (stable)
         run: |
-          dotnet build Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj \
+          dotnet build Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj \
             -c Release --no-restore \
             -p:Version=${{ needs.validate-version.outputs.version }} \
             -p:ContinuousIntegrationBuild=true
         working-directory: ./src/dotnet
 
       - name: Pack (incl. symbols)
         run: |
-          dotnet pack Modgud.Client.AspNetCore/Modgud.Client.AspNetCore.csproj \
+          dotnet pack Modgud.AspNetCore.ResourceServer/Modgud.AspNetCore.ResourceServer.csproj \
             -c Release --no-build \
             -p:Version=${{ needs.validate-version.outputs.version }} \
             -p:ContinuousIntegrationBuild=true \
@@ -442,9 +442,9 @@ jobs:
       - name: Summary
         run: |
           {
-            echo "### NuGet — Modgud.Client.AspNetCore ${{ needs.validate-version.outputs.version }}"
+            echo "### NuGet — Modgud.AspNetCore.ResourceServer ${{ needs.validate-version.outputs.version }}"
             echo ""
-            echo "**URL:** https://www.nuget.org/packages/Modgud.Client.AspNetCore/${{ needs.validate-version.outputs.version }}"
+            echo "**URL:** https://www.nuget.org/packages/Modgud.AspNetCore.ResourceServer/${{ needs.validate-version.outputs.version }}"
           } >> "$GITHUB_STEP_SUMMARY"
 
   publish-docker:

.gitignore

@@ -288,6 +288,7 @@ FakesAssemblies/
 # Node.js Tools for Visual Studio
 .ntvs_analysis.dat
 node_modules/
+.astro/
 
 # Visual Studio 6 build log
 *.plg

README.md

@@ -19,18 +19,22 @@ emission, full 2FA spectrum, GDPR self-service.
   database separation prevents query-level tenant mixing.
 - **Multi-app permission model** — Apps are first-class. Permissions
   are 2-segment (`<resource>:<action>`) inside an app's catalog. Two
-  bypass tiers, no more. Roles bind to one App, groups carry a
-  `BoundTo` activation list.
-- **Keycloak-style `resource_access` on UserInfo** — per-audience
-  blocks with bypass pre-expansion and per-RS subset narrowing. A
-  drop-in `IClaimsTransformation` library flattens the right block
-  into `ClaimTypes.Role` so `[Authorize(Roles = "...")]` works
-  without per-endpoint plumbing.
+  bypass tiers, no more. Application roles bind to one App; a pure
+  `realm:admin` role is the explicit realm-local exception. Groups
+  carry a `BoundTo` activation list.
+- **Keycloak-shaped `resource_access` authorization claims** — when a
+  token targets a registered OAuth API and requests `roles` and/or
+  `permissions`, Modgud emits a block keyed by that API's exact
+  audience, with bypass pre-expansion and per-RS subset narrowing.
+  `Modgud.AspNetCore.ResourceServer` projects only its configured
+  audience block into native role and permission claims.
 - **Full 2FA spectrum + WebAuthn** — TOTP, Email-OTP, FIDO2/Passkey,
   Magic Link, recovery codes. 2FA enforcement middleware with grace
   period and per-user override.
-- **OIDC federation** — Microsoft Entra ID, Google, any OIDC IdP.
-  JIT user provisioning + JavaScript claim-mapping (`UserUpdateScript`).
+- **OIDC and SAML 2.0 federation** — Microsoft Entra ID and
+  standards-compatible OIDC or SAML identity providers. Modgud consumes SAML
+  as an SP; it does not issue SAML assertions. JIT user provisioning +
+  JavaScript claim-mapping (`UserUpdateScript`).
 - **Dynamic Client Registration (RFC 7591)** with triple opt-in
   (realm master / per-API / per-scope), audience-target containment,
   full audit-event trail.
@@ -51,6 +55,7 @@ emission, full 2FA spectrum, GDPR self-service.
 |---|---|
 | [📘 Get Started](./docs/getting-started/) | What this is, requirements, first-time setup |
 | [⚡ Quickstart (Docker)](./docs/getting-started/quickstart.md) | From `docker compose up` to first login in 10 minutes |
+| [🧑‍💻 Developing locally](./docs/contribute/developing-locally.md) | Running from source: dev loop, `*.localhost` realms, recovery CLI, tests |
 | [🧠 Concepts](./docs/concepts/) | Realms, apps, permissions, OAuth, tokens — the mental model |
 | [🛠️ Operate](./docs/operate/) | Deployment, observability, recovery CLI, feature flags |
 | [👤 Administer](./docs/admin/) | Users, groups, roles, OAuth clients, login providers |
@@ -86,9 +91,16 @@ pnpm install
 pnpm dev
 ```
 
-First-time admin bootstrap via the recovery CLI — see
-[First-time setup](./docs/getting-started/first-time-setup.md) for
-the walkthrough.
+That is the short version. [Developing locally](./docs/contribute/developing-locally.md)
+is the full one and the page that is kept in sync with the code: the
+Postgres container, what the first boot actually does, reaching tenant
+realms at `*.localhost`, the recovery CLI, demo seed data, tests and
+Playwright.
+
+For the first admin you need the recovery CLI — that guide covers it, and
+[First-time setup](./docs/getting-started/first-time-setup.md) has the
+decision tree for the other bootstrap routes (invite mode, provisioning
+further realms).
 
 ## Contributing
 

SECURITY.md

@@ -12,7 +12,7 @@ thing.
 - The Modgud IdP itself — backend (`src/dotnet/Modgud.Api`,
   `Modgud.Authentication`, `Modgud.Authorization`, `Modgud.Domain`,
   `Modgud.Infrastructure`) and admin SPA (`src/frontend-vue/`).
-- The `Modgud.Client.AspNetCore` NuGet package that downstream apps
+- The `Modgud.AspNetCore.ResourceServer` NuGet package that downstream apps
   use to validate Modgud-issued tokens.
 - The official Docker image (`ghcr.io/cocoar-dev/modgud:*`).
 - The default configuration shipped in

docs/admin/applications.md

@@ -96,7 +96,7 @@ effectively **rename** one — is to clone it. In the list, right-click a row 
 - **Display name, description and the whole permission catalog** are copied. The
   catalog entries are copied as *new* entries (fresh ids), so the source app's
   role grants and resource-server subsets are left untouched.
-- **Settings** are copied too — branding, registration, native-grant / DCR / CIMD
+- **Settings** are copied too — branding, registration, client-session, native-grant / DCR / CIMD
   overrides — **except the Origin subdomain**, which is globally unique and would
   collide. Set a new subdomain on the copy if it needs one.
 
@@ -110,7 +110,8 @@ the app's slug and link it to the app. Its `PermissionIds` declare
 which subset of the catalog this resource server gates on (full
 catalog is the typical default; tighten for microservices that only
 need a slice). This is the identity Modgud uses to compute the
-per-Audience `resource_access` block in UserInfo.
+audience-keyed `resource_access` block at the token boundary. The key
+is the OAuth API Audience, not this App's slug.
 
 ## Extending or changing the catalog
 
@@ -140,6 +141,7 @@ re-inherits the realm.
 | **Email branding** | The product name used in this App's outbound emails (OTP, magic link, ...) instead of the realm default. |
 | **Self-registration** | Per-app override of the realm self-registration policy (allowed email domains, admin approval, default groups, ToS/privacy URLs) plus the **posture** (see below). Captcha stays realm-level. |
 | **Registration fields** | Per-app override of which identity fields (username / first / last name) are required when an account is created — each one inheriting the realm by default. See [Registration fields](#registration-fields) below. |
+| **Client sessions** | Idle and absolute lifetime defaults for refresh-token-backed native/OAuth sessions belonging to this App. Each field inherits the realm unless overridden; an individual OAuth client can override the App again. |
 | **Native grants** | Per-app toggle + token lifetimes for the cookieless [native passwordless grants](../integrate/native-apps). |
 | **DCR** | Per-app override of [Dynamic Client Registration](./dynamic-client-registration) (enable, token lifetimes, rate limits, reserved-name blocklist). |
 | **CIMD** | Per-app override of [Client-ID Metadata Documents](./client-id-metadata-documents) (enable, token lifetimes). |